Coverage for src/governed_harness/checks/principles.py: 92%
248 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"""Engineering principles as deterministic proxies (#56).
3A principle such as DRY or YAGNI is a judgement, but some of its violations leave a trace a tool
4can measure without a model. This module measures those traces on the ChangeSet; the rest of
5each principle is a checklist item of the existing review call (no extra agent call).
7===================================== ============================================ ==========
8Proxy (rule id) Measured Principle
9===================================== ============================================ ==========
10``principles.dry.duplication`` a window of N normalized lines the change DRY
11 adds that already exists elsewhere
12``principles.kiss.nesting`` an added line nested deeper than 5 levels KISS
13 (indentation, any language)
14``principles.kiss.module-size`` a non-Python source file the change grows KISS, Clean
15 past the module limit Code
16``principles.composition.inheritance`` a class the change adds or edits whose composition
17 inheritance chain in the workspace is deeper over
18 than the limit inheritance
19``principles.yagni.unused-public`` a public function or class the change adds YAGNI
20 that nothing else in the workspace names
21``principles.boy-scout.reformat-only`` a file whose every change is whitespace or Boy Scout
22 layout (an unrelated cleanup) (bounded)
23===================================== ============================================ ==========
25Size and complexity of Python functions, and dependency direction between layers, are the #40
26checks (``architecture.*``); naming and signatures are verified by the linters of the standards
27packs. Everything here is a pure function of text: nothing runs, nothing is written."""
29from __future__ import annotations
31import ast
32import hashlib
33import re
34from collections import Counter
35from collections.abc import Iterable, Iterator, Mapping, Sequence
36from dataclasses import dataclass
37from pathlib import Path
39from governed_harness.checks.model import DiffFile, Issue, is_test_path
40from governed_harness.domain.enums import FindingSeverity
41from governed_harness.runtime.workspace import DEFAULT_EXCLUDES
43SOURCE_SUFFIXES: tuple[str, ...] = (
44 ".py",
45 ".js",
46 ".mjs",
47 ".cjs",
48 ".jsx",
49 ".ts",
50 ".tsx",
51 ".vue",
52 ".java",
53 ".kt",
54 ".kts",
55 ".go",
56 ".rs",
57 ".swift",
58 ".cs",
59 ".php",
60 ".rb",
61)
62_FAMILY = {
63 ".mjs": ".js",
64 ".cjs": ".js",
65 ".jsx": ".js",
66 ".ts": ".js",
67 ".tsx": ".js",
68 ".vue": ".js",
69 ".kts": ".kt",
70}
71_CATEGORY = "principles"
72MAX_NESTING = 5
73_MAX_CORPUS_FILES = 3000
74_MAX_CORPUS_BYTES = 8_000_000
75_TRIVIAL = re.compile(r"^[\s{}()\[\];,]*$|^(?:import|from|using|package|#include|require)\b")
76_COMMENT = re.compile(r"^\s*(?:#|//|/\*|\*|--)")
78PRINCIPLES_CHECKLIST: tuple[tuple[str, str], ...] = (
79 ("principles.srp", "One reason to change per class or module."),
80 ("principles.ocp", "Extend with new types, not by growing switches over types."),
81 ("principles.lsp", "Subtypes keep their base's contract."),
82 ("principles.isp", "Small, client-specific interfaces."),
83 ("principles.dip", "Policy depends on abstractions; infrastructure is injected."),
84 ("principles.dry", "Each rule, constant or format lives in one place."),
85 ("principles.kiss", "Simplest design that meets the criteria."),
86 ("principles.yagni", "Nothing the task does not ask for."),
87 ("principles.least-astonishment", "Names, signatures and side effects as a reader expects."),
88 ("principles.composition", "Composition over deep inheritance."),
89 ("principles.boy-scout", "Cleanup only in touched code; no unrelated refactors."),
90)
91"""The principles checklist appended to the review call, with rule ids for its findings."""
94@dataclass(frozen=True)
95class PrincipleLimits:
96 window: int = 6
97 inheritance_depth: int = 3
98 max_module_lines: int | None = 800
99 unused_public: bool = True
100 boy_scout: bool = True
103def is_source(path: str) -> bool:
104 return path.endswith(SOURCE_SUFFIXES) and not path.endswith(".d.ts")
107def _family(path: str) -> str:
108 suffix = Path(path).suffix.lower()
109 return _FAMILY.get(suffix, suffix)
112def _normalized(line: str) -> str | None:
113 text = " ".join(line.split())
114 if not text or _TRIVIAL.match(text) or _COMMENT.match(text) or len(text) < 4:
115 return None
116 return text
119# ----- corpus ---------------------------------------------------------------------------------
120def source_corpus(workspace: Path, families: set[str]) -> dict[str, str]:
121 """The source files of the workspace in the given language families (bounded)."""
122 found: dict[str, str] = {}
123 total = 0
124 root = workspace.resolve()
125 stack = [root]
126 while stack and len(found) < _MAX_CORPUS_FILES and total < _MAX_CORPUS_BYTES:
127 for entry in _entries(stack.pop()):
128 if entry.is_dir():
129 stack.append(entry)
130 continue
131 relative = entry.relative_to(root).as_posix()
132 data = _source_bytes(entry, relative, families)
133 if data is not None:
134 total += len(data)
135 found[relative] = data.decode("utf-8", "replace")
136 return found
139def _entries(directory: Path) -> list[Path]:
140 """The entries of a directory by name, without the default excludes and symbolic links
141 (none when the directory cannot be read)."""
142 try:
143 entries = sorted(directory.iterdir(), key=lambda item: item.name)
144 except OSError:
145 return []
146 return [
147 entry for entry in entries if entry.name not in DEFAULT_EXCLUDES and not entry.is_symlink()
148 ]
151def _source_bytes(entry: Path, relative: str, families: set[str]) -> bytes | None:
152 """The first 400 kB of a source file of one of ``families``, else ``None``."""
153 if not is_source(relative) or _family(relative) not in families:
154 return None
155 try:
156 return entry.read_bytes()[:400_000]
157 except OSError:
158 return None
161# ----- DRY ------------------------------------------------------------------------------------
162def _windows(lines: Sequence[str], window: int) -> Iterable[tuple[int, str]]:
163 """``(first line number, digest)`` of every window of ``window`` normalized lines."""
164 kept = [
165 (number, text) for number, raw in enumerate(lines, start=1) if (text := _normalized(raw))
166 ]
167 for index in range(len(kept) - window + 1):
168 chunk = kept[index : index + window]
169 digest = hashlib.sha256("\n".join(text for _, text in chunk).encode()).hexdigest()
170 yield chunk[0][0], digest
173def duplication(
174 diff: Sequence[DiffFile],
175 files: Mapping[str, str],
176 corpus: Mapping[str, str],
177 *,
178 window: int,
179 severity: FindingSeverity,
180) -> list[Issue]:
181 """Windows of added code that already exist elsewhere (another file, or earlier in the
182 same file). Test files are ignored: repeated arrangement in tests is expected."""
183 index: dict[str, list[tuple[str, int]]] = {}
184 for path, text in corpus.items():
185 if is_test_path(path):
186 continue
187 for line, digest in _windows(text.splitlines(), window):
188 index.setdefault(digest, []).append((path, line))
189 issues: list[Issue] = []
190 for item in diff:
191 path = item.path
192 if item.is_deleted or not is_source(path) or is_test_path(path) or path not in files:
193 continue
194 added = {line.number for line in item.added}
195 issues.extend(
196 _duplicates(
197 path, files[path].splitlines(), added, index, window=window, severity=severity
198 )
199 )
200 return issues
203def _duplicates(
204 path: str,
205 lines: Sequence[str],
206 added: set[int],
207 index: Mapping[str, list[tuple[str, int]]],
208 *,
209 window: int,
210 severity: FindingSeverity,
211) -> list[Issue]:
212 """The windows of one file with an added line that exist elsewhere in ``index``."""
213 issues: list[Issue] = []
214 reported_until = 0
215 for first, digest in _windows(lines, window):
216 if first <= reported_until:
217 continue
218 if not any(number in added for number in range(first, first + window)): 218 ↛ 219line 218 didn't jump to line 219 because the condition on line 218 was never true
219 continue
220 others = [
221 (other, line)
222 for other, line in index.get(digest, [])
223 if other != path or abs(line - first) >= window
224 ]
225 if others:
226 other, line = others[0]
227 issues.append(
228 Issue(
229 rule_id="principles.dry.duplication",
230 severity=severity,
231 message=(
232 f"{path}:{first} adds {window} or more lines that already exist in "
233 f"{other}:{line}"
234 ),
235 path=path,
236 line=first,
237 category=_CATEGORY,
238 recommendation="Extract the shared code into one function or module and "
239 "call it from both places.",
240 )
241 )
242 reported_until = first + window * 2
243 return issues
246# ----- KISS -----------------------------------------------------------------------------------
247def _indent_unit(lines: Sequence[str]) -> int:
248 widths = sorted(
249 {len(line) - len(line.lstrip(" ")) for line in lines if line.strip() and line[0] == " "}
250 )
251 steps = [b - a for a, b in zip([0, *widths], widths, strict=False) if b - a > 0]
252 return min(steps) if steps else 4
255def nesting(
256 diff: Sequence[DiffFile], files: Mapping[str, str], *, severity: FindingSeverity
257) -> list[Issue]:
258 issues: list[Issue] = []
259 for item in diff:
260 path = item.path
261 if item.is_deleted or not is_source(path) or is_test_path(path) or path not in files:
262 continue
263 lines = files[path].splitlines()
264 unit = _indent_unit(lines)
265 for line in item.added:
266 text = line.text.replace("\t", " " * unit)
267 if not text.strip() or _COMMENT.match(text): 267 ↛ 268line 267 didn't jump to line 268 because the condition on line 267 was never true
268 continue
269 depth = (len(text) - len(text.lstrip(" "))) // max(unit, 1)
270 # One level is the class or module body in most languages.
271 if depth > MAX_NESTING + 1:
272 issues.append(
273 Issue(
274 rule_id="principles.kiss.nesting",
275 severity=severity,
276 message=f"{path}:{line.number} is nested {depth} levels deep",
277 path=path,
278 line=line.number,
279 category=_CATEGORY,
280 recommendation="Use early returns or extract the inner block into a "
281 "named function.",
282 )
283 )
284 break
285 return issues
288def module_size(
289 diff: Sequence[DiffFile],
290 files: Mapping[str, str],
291 limit: int | None,
292 baseline: Mapping[str, int],
293 *,
294 severity: FindingSeverity,
295) -> list[Issue]:
296 """Non-Python source files grown past the limit (Python has ``architecture.module-lines``).
297 A file already past it on the baseline is reported as LOW."""
298 if limit is None: 298 ↛ 299line 298 didn't jump to line 299 because the condition on line 298 was never true
299 return []
300 issues: list[Issue] = []
301 for item in diff:
302 path = item.path
303 if (
304 item.is_deleted
305 or path.endswith(".py")
306 or not is_source(path)
307 or is_test_path(path)
308 or path not in files
309 ):
310 continue
311 count = len(files[path].splitlines())
312 if count <= limit: 312 ↛ 314line 312 didn't jump to line 314 because the condition on line 312 was always true
313 continue
314 before = baseline.get(path, 0)
315 issues.append(
316 Issue(
317 rule_id="principles.kiss.module-size",
318 severity=FindingSeverity.LOW if before > limit else severity,
319 message=f"{'Pre-existing: ' if before > limit else ''}{path} has {count} lines; "
320 f"the limit is {limit}.",
321 path=path,
322 line=1,
323 category=_CATEGORY,
324 recommendation="Split the file along its responsibilities.",
325 )
326 )
327 return issues
330# ----- composition over inheritance -------------------------------------------------------------
331_EXTENDS = re.compile(
332 r"\b(?:class|interface)\s+(?P<name>[A-Z]\w*)(?:<[^>{]*>)?\s*"
333 r"(?:extends\s+(?P<base>[A-Z]\w*)|:\s*(?P<colon>[A-Z]\w*))"
334)
335_RUBY_CLASS = re.compile(r"^\s*class\s+(?P<name>[A-Z]\w*)\s*<\s*(?P<base>[A-Z][\w:]*)")
338_NOT_A_BASE = frozenset({"object", "Protocol", "Generic", "ABC", "Enum"})
341def _base_name(base: ast.expr) -> str | None:
342 if isinstance(base, ast.Name): 342 ↛ 344line 342 didn't jump to line 344 because the condition on line 342 was always true
343 return base.id
344 if isinstance(base, ast.Attribute):
345 return base.attr
346 return None
349def _python_bases(text: str) -> dict[str, str]:
350 found: dict[str, str] = {}
351 try:
352 tree = ast.parse(text)
353 except SyntaxError:
354 return found
355 for node in ast.walk(tree):
356 if isinstance(node, ast.ClassDef) and node.bases:
357 name = _base_name(node.bases[0])
358 if name and name not in _NOT_A_BASE: 358 ↛ 355line 358 didn't jump to line 355 because the condition on line 358 was always true
359 found[node.name] = name
360 return found
363def _bases(path: str, text: str) -> dict[str, str]:
364 """``class -> first base`` declared in one file."""
365 if path.endswith(".py"):
366 return _python_bases(text)
367 found: dict[str, str] = {}
368 for line in text.splitlines():
369 match = _RUBY_CLASS.match(line) if path.endswith(".rb") else _EXTENDS.search(line)
370 if match:
371 parent = match.groupdict().get("base") or match.groupdict().get("colon")
372 if parent: 372 ↛ 368line 372 didn't jump to line 368 because the condition on line 372 was always true
373 found[match["name"]] = str(parent).split("::")[-1]
374 return found
377def _chain(name: str, hierarchy: Mapping[str, str], limit: int) -> list[str]:
378 """``name`` and its ancestors, stopping at a cycle or a few levels past ``limit``."""
379 chain = [name]
380 while chain[-1] in hierarchy and len(chain) <= limit + 5:
381 parent = hierarchy[chain[-1]]
382 if parent in chain: 382 ↛ 383line 382 didn't jump to line 383 because the condition on line 382 was never true
383 break
384 chain.append(parent)
385 return chain
388def _class_line(text: str, name: str) -> int | None:
389 declaration = re.compile(rf"\bclass\s+{re.escape(name)}\b")
390 return next(
391 (
392 number
393 for number, line in enumerate(text.splitlines(), start=1)
394 if declaration.search(line)
395 ),
396 None,
397 )
400def inheritance_depth(
401 diff: Sequence[DiffFile],
402 files: Mapping[str, str],
403 corpus: Mapping[str, str],
404 *,
405 limit: int,
406 severity: FindingSeverity,
407) -> list[Issue]:
408 hierarchy: dict[str, str] = {}
409 for path, text in corpus.items():
410 hierarchy.update(_bases(path, text))
411 for path, text in files.items():
412 if is_source(path): 412 ↛ 411line 412 didn't jump to line 411 because the condition on line 412 was always true
413 hierarchy.update(_bases(path, text))
414 issues: list[Issue] = []
415 for item in diff:
416 path = item.path
417 if item.is_deleted or not is_source(path) or is_test_path(path) or path not in files:
418 continue
419 added_text = "\n".join(line.text for line in item.added)
420 issues.extend(
421 _inheritance_issue(path, files[path], chain, limit, severity)
422 for chain in _deep_chains(path, files[path], added_text, hierarchy, limit)
423 )
424 return issues
427def _deep_chains(
428 path: str, text: str, added_text: str, hierarchy: Mapping[str, str], limit: int
429) -> Iterator[list[str]]:
430 """The inheritance chains past ``limit`` of the classes of a file the added lines name."""
431 for name in _bases(path, text):
432 if re.search(rf"\b{re.escape(name)}\b", added_text): 432 ↛ 431line 432 didn't jump to line 431 because the condition on line 432 was always true
433 chain = _chain(name, hierarchy, limit)
434 if len(chain) - 1 > limit:
435 yield chain
438def _inheritance_issue(
439 path: str, text: str, chain: list[str], limit: int, severity: FindingSeverity
440) -> Issue:
441 name = chain[0]
442 return Issue(
443 rule_id="principles.composition.inheritance",
444 severity=severity,
445 message=(
446 f"{name} inherits through {len(chain) - 1} levels ({' -> '.join(chain)}); "
447 f"the limit is {limit}"
448 ),
449 path=path,
450 line=_class_line(text, name),
451 category=_CATEGORY,
452 recommendation="Prefer composition: hold the behaviour as a collaborator "
453 "instead of inheriting it.",
454 )
457# ----- YAGNI ----------------------------------------------------------------------------------
458_PUBLIC_DEFINITION = {
459 ".py": re.compile(r"^(?:def|class|async\s+def)\s+(?P<name>[A-Za-z]\w*)"),
460 ".js": re.compile(
461 r"^export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|interface|type)"
462 r"\s+(?P<name>[A-Za-z_$][\w$]*)"
463 ),
464}
467def unused_public(
468 diff: Sequence[DiffFile],
469 files: Mapping[str, str],
470 corpus: Mapping[str, str],
471 *,
472 severity: FindingSeverity,
473) -> list[Issue]:
474 """Public top-level functions and classes (Python) and exports (JavaScript, TypeScript)
475 the change adds and that no other file, test included, names."""
476 issues: list[Issue] = []
477 for item in diff:
478 path = item.path
479 family = _family(path)
480 pattern = _PUBLIC_DEFINITION.get(family)
481 if pattern is None or item.is_deleted or is_test_path(path) or path not in files:
482 continue
483 for line in item.added:
484 match = pattern.match(line.text)
485 if not match or match["name"].startswith("_") or match["name"] in {"main"}:
486 continue
487 name = match["name"]
488 word = re.compile(rf"(?<![\w$]){re.escape(name)}(?![\w$])")
489 used_elsewhere = any(
490 word.search(text) for other, text in corpus.items() if other != path
491 ) or any(word.search(text) for other, text in files.items() if other != path)
492 used_here = len(word.findall(files[path])) > 1
493 if used_elsewhere or used_here:
494 continue
495 issues.append(
496 Issue(
497 rule_id="principles.yagni.unused-public",
498 severity=severity,
499 message=f"{name} ({path}:{line.number}) is added as public API but nothing "
500 "in the workspace uses it, not even a test",
501 path=path,
502 line=line.number,
503 category=_CATEGORY,
504 recommendation="Remove it until the task needs it, or test the behaviour "
505 "it provides.",
506 )
507 )
508 return issues
511# ----- Boy Scout ------------------------------------------------------------------------------
512def reformat_only(diff: Sequence[DiffFile], *, severity: FindingSeverity) -> list[Issue]:
513 """Files whose every change is whitespace or line layout: the change touched them only to
514 clean them up. Cleanup inside a file the change edits for the task is allowed."""
515 issues: list[Issue] = []
516 for item in diff:
517 if item.is_added or item.is_deleted or not (item.added or item.removed): 517 ↛ 518line 517 didn't jump to line 518 because the condition on line 517 was never true
518 continue
519 added = Counter("".join(line.text.split()) for line in item.added)
520 removed = Counter("".join(line.text.split()) for line in item.removed)
521 if "".join(sorted(added.elements())) == "".join(sorted(removed.elements())) or (
522 "".join(line.text for line in item.added).replace(" ", "").replace("\t", "")
523 == "".join(line.text for line in item.removed).replace(" ", "").replace("\t", "")
524 ):
525 issues.append(
526 Issue(
527 rule_id="principles.boy-scout.reformat-only",
528 severity=severity,
529 message=f"{item.path} changes only whitespace or layout; the task does not "
530 "need it",
531 path=item.path,
532 line=item.added[0].number if item.added else None,
533 category=_CATEGORY,
534 recommendation="Leave unrelated files as they are; clean up only the code "
535 "the change touches.",
536 )
537 )
538 return issues
541def check_principles(
542 diff: Sequence[DiffFile],
543 files: Mapping[str, str],
544 corpus: Mapping[str, str],
545 limits: PrincipleLimits,
546 *,
547 severity: FindingSeverity,
548 baseline_lines: Mapping[str, int] | None = None,
549) -> list[Issue]:
550 issues: list[Issue] = []
551 issues.extend(duplication(diff, files, corpus, window=limits.window, severity=severity))
552 issues.extend(nesting(diff, files, severity=severity))
553 issues.extend(
554 module_size(diff, files, limits.max_module_lines, baseline_lines or {}, severity=severity)
555 )
556 issues.extend(
557 inheritance_depth(diff, files, corpus, limit=limits.inheritance_depth, severity=severity)
558 )
559 if limits.unused_public:
560 low = FindingSeverity.LOW if severity is not FindingSeverity.INFO else severity
561 issues.extend(unused_public(diff, files, corpus, severity=low))
562 if limits.boy_scout: 562 ↛ 564line 562 didn't jump to line 564 because the condition on line 562 was always true
563 issues.extend(reformat_only(diff, severity=severity))
564 return issues
567__all__ = [
568 "PRINCIPLES_CHECKLIST",
569 "SOURCE_SUFFIXES",
570 "PrincipleLimits",
571 "check_principles",
572 "duplication",
573 "inheritance_depth",
574 "is_source",
575 "module_size",
576 "nesting",
577 "reformat_only",
578 "source_corpus",
579 "unused_public",
580]