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

1"""Size, complexity and layering limits over the Python files of a change. 

2 

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.""" 

7 

8from __future__ import annotations 

9 

10import ast 

11from collections.abc import Callable, Iterator, Mapping 

12from dataclasses import dataclass 

13 

14from governed_harness.checks.model import Issue, is_test_path 

15from governed_harness.domain.enums import FindingSeverity 

16 

17_CATEGORY = "architecture" 

18 

19 

20@dataclass(frozen=True) 

21class ArchitectureLimits: 

22 """The limits a task or project sets; ``None`` (or an empty tuple) disables a rule.""" 

23 

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``.""" 

30 

31 

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__") 

41 

42 

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 + ".") 

47 

48 

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) 

58 

59 

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) 

76 

77 

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 

97 

98 

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) 

112 

113 

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 

134 

135 

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) 

141 

142 

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 

195 

196 

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 

239 

240 

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