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
« 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).
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."""
10from __future__ import annotations
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
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
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``)."""
54_DOC_SUFFIXES = (".md", ".rst", ".adoc", ".txt")
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
75def pipeline_globs() -> tuple[str, ...]:
76 return (*PIPELINE_GLOBS, *_pack_tables()[1])
79def is_pipeline_path(path: str) -> bool:
80 return any(glob_match(path, pattern) for pattern in pipeline_globs())
83def is_doc_path(path: str) -> bool:
84 return path.lower().endswith(_DOC_SUFFIXES)
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]
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))
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)
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)]
120@dataclass(frozen=True)
121class Activation:
122 active: bool
123 reason: str
124 signals: tuple[str, ...] = ()
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
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
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))
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
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")
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]