Coverage for src/governed_harness/checks/architecture.py: 97%
125 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"""Size, complexity and layering limits over the Python files of a change.
3These are the structural properties a reviewer would otherwise judge by eye: a module or function
4that grew past what the task allows, a function whose branching makes it hard to test, a layer that
5reaches into one it must not depend on. Measuring them from the AST keeps the verdict reproducible
6and independent of formatting."""
8from __future__ import annotations
10import ast
11from collections.abc import Callable, Iterator, Mapping
12from dataclasses import dataclass
14from governed_harness.checks.model import Issue, is_test_path
15from governed_harness.domain.enums import FindingSeverity
17_CATEGORY = "architecture"
20@dataclass(frozen=True)
21class ArchitectureLimits:
22 """The limits a task or project sets; ``None`` (or an empty tuple) disables a rule."""
24 max_module_lines: int | None = None
25 max_function_lines: int | None = None
26 max_complexity: int | None = None
27 forbidden_imports: tuple[tuple[str, str], ...] = ()
28 """``(source, target)`` pairs of dotted module prefixes: modules under ``source`` must not
29 import modules under ``target``."""
32def module_name(path: str) -> str:
33 """The dotted module name of a workspace path: ``src/shop/orders.py`` -> ``shop.orders``,
34 ``shop/__init__.py`` -> ``shop``. The ``src/`` layout prefix is not part of the import
35 name, so it is dropped."""
36 normalized = path.replace("\\", "/")
37 normalized = normalized.removeprefix("./").removeprefix("src/")
38 normalized = normalized.removesuffix(".py")
39 name = normalized.replace("/", ".")
40 return name.removesuffix(".__init__")
43def is_under(module: str, prefix: str) -> bool:
44 """Whether a dotted module equals a prefix or lives inside it (``a.b`` is under ``a`` but
45 ``ab`` is not)."""
46 return module == prefix or module.startswith(prefix + ".")
49def _resolve_relative(module: str, is_package: bool, level: int, target: str | None) -> str:
50 parts = module.split(".") if module else []
51 if not is_package:
52 parts = parts[:-1]
53 if level > 1:
54 parts = parts[: max(len(parts) - (level - 1), 0)]
55 if target:
56 parts.append(target)
57 return ".".join(parts)
60def _imported_modules(
61 tree: ast.Module,
62 module: str,
63 is_package: bool,
64 module_exists: Callable[[str], bool] | None = None,
65) -> Iterator[tuple[int, str]]:
66 """Every module an import statement may bind, with its line. ``from pkg import name`` may
67 import the submodule ``pkg.name``, so both ``pkg`` and ``pkg.name`` are candidates; with
68 ``module_exists``, ``pkg.name`` is one only when it is a module or package of the workspace
69 (otherwise ``name`` is a function, class or variable of ``pkg``)."""
70 for node in ast.walk(tree):
71 if isinstance(node, ast.Import):
72 for alias in node.names:
73 yield node.lineno, alias.name
74 elif isinstance(node, ast.ImportFrom):
75 yield from _from_imported_modules(node, module, is_package, module_exists)
78def _from_imported_modules(
79 node: ast.ImportFrom,
80 module: str,
81 is_package: bool,
82 module_exists: Callable[[str], bool] | None = None,
83) -> Iterator[tuple[int, str]]:
84 """The candidates of one ``from ... import`` statement: the base and each named module."""
85 if node.level:
86 base = _resolve_relative(module, is_package, node.level, node.module)
87 else:
88 base = node.module or ""
89 if base: 89 ↛ 91line 89 didn't jump to line 91 because the condition on line 89 was always true
90 yield node.lineno, base
91 for alias in node.names:
92 if alias.name == "*": 92 ↛ 93line 92 didn't jump to line 93 because the condition on line 92 was never true
93 continue
94 named = f"{base}.{alias.name}" if base else alias.name
95 if module_exists is None or module_exists(named):
96 yield node.lineno, named
99def _functions(
100 tree: ast.AST, prefix: str = ""
101) -> Iterator[tuple[str, ast.FunctionDef | ast.AsyncFunctionDef]]:
102 """Every function and method with a qualified name (``Class.method``, ``outer.inner``)."""
103 for node in ast.iter_child_nodes(tree):
104 if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
105 qualified = f"{prefix}{node.name}"
106 yield qualified, node
107 yield from _functions(node, qualified + ".")
108 elif isinstance(node, ast.ClassDef):
109 yield from _functions(node, f"{prefix}{node.name}.")
110 else:
111 yield from _functions(node, prefix)
114def _decision_points(node: ast.AST) -> int:
115 """The decision points of one function, not counting nested functions and classes, which
116 are measured on their own (as McCabe does)."""
117 count = 0
118 for child in ast.iter_child_nodes(node):
119 if isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
120 continue
121 if isinstance(
122 child,
123 ast.If | ast.For | ast.AsyncFor | ast.While | ast.IfExp | ast.ExceptHandler,
124 ):
125 count += 1
126 elif isinstance(child, ast.BoolOp):
127 count += len(child.values) - 1
128 elif isinstance(child, ast.comprehension):
129 count += 1 + len(child.ifs)
130 elif isinstance(child, ast.match_case):
131 count += 1
132 count += _decision_points(child)
133 return count
136def cyclomatic_complexity(function: ast.FunctionDef | ast.AsyncFunctionDef) -> int:
137 """McCabe complexity: one plus each ``if``/``elif``, loop, ``except`` handler, extra
138 ``and``/``or`` operand, comprehension ``for`` and ``if``, conditional expression and
139 ``match`` case."""
140 return 1 + _decision_points(function)
143def check_architecture(
144 files: Mapping[str, str],
145 limits: ArchitectureLimits,
146 *,
147 severity: FindingSeverity,
148) -> list[Issue]:
149 """Measure the non-test Python files of a change against the limits."""
150 issues: list[Issue] = []
151 needs_ast = (
152 limits.max_function_lines is not None
153 or limits.max_complexity is not None
154 or bool(limits.forbidden_imports)
155 )
156 for path in sorted(files):
157 if not path.endswith(".py") or is_test_path(path):
158 continue
159 text = files[path]
160 line_count = len(text.splitlines())
161 if limits.max_module_lines is not None and line_count > limits.max_module_lines:
162 issues.append(
163 Issue(
164 rule_id="architecture.module-lines",
165 severity=severity,
166 message=(
167 f"{path} has {line_count} lines; the limit is {limits.max_module_lines}."
168 ),
169 path=path,
170 line=1,
171 category=_CATEGORY,
172 recommendation="Split the module along its responsibilities.",
173 )
174 )
175 if not needs_ast: 175 ↛ 176line 175 didn't jump to line 176 because the condition on line 175 was never true
176 continue
177 try:
178 tree = ast.parse(text, filename=path)
179 except SyntaxError as error:
180 issues.append(
181 Issue(
182 rule_id="architecture.unparsable",
183 severity=FindingSeverity.INFO,
184 message=f"{path} could not be parsed ({error.msg}); "
185 "its functions and imports were not measured.",
186 path=path,
187 line=error.lineno,
188 category=_CATEGORY,
189 )
190 )
191 continue
192 issues.extend(_function_issues(path, tree, limits, severity))
193 issues.extend(_import_issues(path, tree, limits, severity))
194 return issues
197def _function_issues(
198 path: str, tree: ast.Module, limits: ArchitectureLimits, severity: FindingSeverity
199) -> list[Issue]:
200 issues: list[Issue] = []
201 for qualified, function in _functions(tree):
202 length = (function.end_lineno or function.lineno) - function.lineno + 1
203 if limits.max_function_lines is not None and length > limits.max_function_lines:
204 issues.append(
205 Issue(
206 rule_id="architecture.function-lines",
207 severity=severity,
208 message=(
209 f"{qualified} spans {length} lines; the limit is "
210 f"{limits.max_function_lines}."
211 ),
212 path=path,
213 line=function.lineno,
214 category=_CATEGORY,
215 recommendation="Extract cohesive steps into smaller functions.",
216 )
217 )
218 if limits.max_complexity is not None:
219 complexity = cyclomatic_complexity(function)
220 if complexity > limits.max_complexity:
221 issues.append(
222 Issue(
223 rule_id="architecture.complexity",
224 severity=severity,
225 message=(
226 f"{qualified} has cyclomatic complexity {complexity}; the limit is "
227 f"{limits.max_complexity}."
228 ),
229 path=path,
230 line=function.lineno,
231 category=_CATEGORY,
232 recommendation=(
233 "Reduce branching: extract decisions into helpers, use lookup "
234 "tables or early returns."
235 ),
236 )
237 )
238 return issues
241def _import_issues(
242 path: str, tree: ast.Module, limits: ArchitectureLimits, severity: FindingSeverity
243) -> list[Issue]:
244 if not limits.forbidden_imports:
245 return []
246 module = module_name(path)
247 is_package = path.replace("\\", "/").endswith("/__init__.py") or path == "__init__.py"
248 rules = [
249 (source, target) for source, target in limits.forbidden_imports if is_under(module, source)
250 ]
251 if not rules:
252 return []
253 issues: list[Issue] = []
254 reported: set[tuple[int, str, str]] = set()
255 for line, imported in _imported_modules(tree, module, is_package):
256 for source, target in rules:
257 key = (line, source, target)
258 if key in reported or not is_under(imported, target):
259 continue
260 reported.add(key)
261 issues.append(
262 Issue(
263 rule_id="architecture.forbidden-import",
264 severity=severity,
265 message=(
266 f"{module} imports {imported}, but modules under {source} must not "
267 f"import modules under {target}."
268 ),
269 path=path,
270 line=line,
271 category=_CATEGORY,
272 recommendation=(
273 f"Invert the dependency (define an interface in {source} that {target} "
274 "implements) or move the code to the layer it belongs to."
275 ),
276 )
277 )
278 return issues