Coverage for src/governed_harness/review/signals.py: 89%

95 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""Diff slices and the signals that activate a reviewer (#57). 

2 

3A reviewer reads only its slice of the diff (``sources``, ``tests``, ``pipeline``, ``all`` or 

4path globs) and runs only when the slice has its signal: no changed test, no tests reviewer; no 

5concurrency primitive on a changed line, no concurrency reviewer; no script, hook or CI file, no 

6pipeline reviewer. The signals of a language (its concurrency primitives, its calls that leave 

7the process) come from the standards packs (``review.yaml``); the machinery here knows no 

8language.""" 

9 

10from __future__ import annotations 

11 

12import re 

13from collections.abc import Iterable, Sequence 

14from dataclasses import dataclass 

15from functools import lru_cache 

16from pathlib import PurePosixPath 

17from typing import Any 

18 

19from governed_harness.checks.model import is_test_path 

20from governed_harness.review.diff import FileChange, glob_match 

21from governed_harness.review.reviewers import Reviewer 

22from governed_harness.review.rules import pack_review 

23from governed_harness.standards.packs import BUILTIN_PACKS, builtin_pack 

24 

25PIPELINE_GLOBS: tuple[str, ...] = ( 

26 ".github/workflows/*", 

27 ".github/actions/**", 

28 ".gitlab-ci.yml", 

29 ".gitlab/**", 

30 "bitbucket-pipelines.yml", 

31 "azure-pipelines.yml", 

32 ".azure-pipelines/**", 

33 ".circleci/**", 

34 "Jenkinsfile", 

35 ".gitea/workflows/*", 

36 ".forgejo/workflows/*", 

37 ".buildkite/**", 

38 ".travis.yml", 

39 "Makefile", 

40 "*.mk", 

41 "Dockerfile", 

42 "*.Dockerfile", 

43 "docker-compose*.yml", 

44 "*.sh", 

45 "*.bash", 

46 "scripts/**", 

47 "hooks/**", 

48 ".githooks/**", 

49 ".husky/**", 

50 "lefthook.yml", 

51) 

52"""Language-neutral files of the pipeline slice; packs add their own (``review.yaml``).""" 

53 

54_DOC_SUFFIXES = (".md", ".rst", ".adoc", ".txt") 

55 

56 

57@lru_cache(maxsize=1) 

58def _pack_tables() -> tuple[ 

59 tuple[tuple[str, tuple[str, ...]], ...], tuple[str, ...], dict[str, dict[str, tuple[str, ...]]] 

60]: 

61 extensions: list[tuple[str, tuple[str, ...]]] = [] 

62 pipeline: list[str] = [] 

63 signals: dict[str, dict[str, tuple[str, ...]]] = {} 

64 for pack in BUILTIN_PACKS: 

65 meta = pack_review(pack) 

66 extensions.append((pack, tuple(builtin_pack(pack).detect.extensions))) 

67 pipeline.extend(str(item) for item in meta.get("pipeline") or []) 

68 signals[pack] = { 

69 str(name): tuple(str(item) for item in patterns or []) 

70 for name, patterns in (meta.get("signals") or {}).items() 

71 } 

72 return tuple(extensions), tuple(dict.fromkeys(pipeline)), signals 

73 

74 

75def pipeline_globs() -> tuple[str, ...]: 

76 return (*PIPELINE_GLOBS, *_pack_tables()[1]) 

77 

78 

79def is_pipeline_path(path: str) -> bool: 

80 return any(glob_match(path, pattern) for pattern in pipeline_globs()) 

81 

82 

83def is_doc_path(path: str) -> bool: 

84 return path.lower().endswith(_DOC_SUFFIXES) 

85 

86 

87def packs_of(path: str) -> list[str]: 

88 suffix = PurePosixPath(path).suffix.lower() 

89 return [pack for pack, extensions in _pack_tables()[0] if suffix and suffix in extensions] 

90 

91 

92def signal_patterns(name: str, path: str, packs: Sequence[str] | None = None) -> tuple[str, ...]: 

93 """The patterns of signal ``name`` for a file, from the packs of its extension (limited to 

94 the project's packs when given).""" 

95 table = _pack_tables()[2] 

96 found: list[str] = [] 

97 for pack in packs_of(path): 

98 if packs is not None and pack not in packs: 98 ↛ 99line 98 didn't jump to line 99 because the condition on line 98 was never true

99 continue 

100 found.extend(table.get(pack, {}).get(name, ())) 

101 return tuple(dict.fromkeys(found)) 

102 

103 

104def in_slice(path: str, diff_slice: str | tuple[str, ...]) -> bool: 

105 if isinstance(diff_slice, tuple): 105 ↛ 106line 105 didn't jump to line 106 because the condition on line 105 was never true

106 return any(glob_match(path, pattern) for pattern in diff_slice) 

107 if diff_slice == "all": 107 ↛ 108line 107 didn't jump to line 108 because the condition on line 107 was never true

108 return True 

109 if diff_slice == "tests": 

110 return is_test_path(path) 

111 if diff_slice == "pipeline": 

112 return is_pipeline_path(path) 

113 return not is_test_path(path) and not is_pipeline_path(path) and not is_doc_path(path) 

114 

115 

116def slice_files(files: Iterable[FileChange], diff_slice: str | tuple[str, ...]) -> list[FileChange]: 

117 return [item for item in files if not item.binary and in_slice(item.path, diff_slice)] 

118 

119 

120@dataclass(frozen=True) 

121class Activation: 

122 active: bool 

123 reason: str 

124 signals: tuple[str, ...] = () 

125 

126 def as_dict(self) -> dict[str, Any]: 

127 value: dict[str, Any] = {"active": self.active, "reason": self.reason} 

128 if self.signals: 

129 value["signals"] = list(self.signals) 

130 return value 

131 

132 

133def _changed_text(item: FileChange) -> Iterable[str]: 

134 for line in item.added: 

135 yield line.text 

136 for line in item.removed: 

137 yield line.text 

138 

139 

140def _changed(pattern: str, item: FileChange) -> bool: 

141 """Whether ``pattern`` matches a changed line of ``item``.""" 

142 compiled = re.compile(pattern) 

143 return any(compiled.search(text) for text in _changed_text(item)) 

144 

145 

146def _pattern_hits(patterns: Sequence[str], files: list[FileChange]) -> list[str]: 

147 """``pattern:P@PATH`` for each pattern of the reviewer, at the first file it matches.""" 

148 hits: list[str] = [] 

149 for pattern in patterns: 149 ↛ 150line 149 didn't jump to line 150 because the loop on line 149 never started

150 first = next((item for item in files if _changed(pattern, item)), None) 

151 if first is not None: 

152 hits.append(f"pattern:{pattern}@{first.path}") 

153 return hits 

154 

155 

156def activation( 

157 reviewer: Reviewer, files: list[FileChange], packs: Sequence[str] | None = None 

158) -> Activation: 

159 """Whether a reviewer runs on its slice, and why (recorded in the report).""" 

160 spec = reviewer.spec 

161 if not files: 

162 return Activation(False, "no file of its slice changed") 

163 hits = _pattern_hits(spec.patterns, files) 

164 if spec.activation == "always": 164 ↛ 165line 164 didn't jump to line 165 because the condition on line 164 was never true

165 return Activation(True, "always", tuple(hits)) 

166 if spec.activation == "changed": 

167 return Activation(True, f"{len(files)} file(s) of its slice changed", tuple(hits)) 

168 name = spec.activation.split(":", 1)[1] 

169 hits.extend( 

170 f"{name}@{item.path}" 

171 for item in files 

172 if any(_changed(pattern, item) for pattern in signal_patterns(name, item.path, packs)) 

173 ) 

174 if hits: 

175 return Activation(True, f"signal {name} on a changed line", tuple(hits)) 

176 return Activation(False, f"no {name} signal on a changed line of its slice") 

177 

178 

179__all__ = [ 

180 "PIPELINE_GLOBS", 

181 "Activation", 

182 "activation", 

183 "in_slice", 

184 "is_doc_path", 

185 "is_pipeline_path", 

186 "packs_of", 

187 "pipeline_globs", 

188 "signal_patterns", 

189 "slice_files", 

190]