Coverage for src/governed_harness/checks/layers.py: 87%

233 statements  

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

1"""Layer rules: the forbidden dependencies of an architecture, in any language (#56, #40). 

2 

3``verification.architecture.forbiddenImports`` (#40) forbids imports between Python module 

4prefixes. An architecture (``architecture.layers`` and ``allow``, or the rules a person approved 

5from a survey or an ADR) generalizes it: each layer is a set of path globs and/or module prefixes, 

6``allow`` lists the layers each layer may depend on (a layer may always use itself; a layer 

7without an entry may use no other layer), and every import of a changed file is resolved to the 

8layer it reaches. The imports are read per language: 

9 

10* Python: the AST (``import``, ``from ... import``, relative imports), as #40 does; 

11* JavaScript and TypeScript: ``import ... from``, ``export ... from``, ``import()`` and 

12 ``require()``; a relative specifier is resolved to a workspace path; 

13* Java, Kotlin, Scala: ``import a.b.C``; C#: ``using A.B``; PHP: ``use A\\B``; Go: the import 

14 paths; Rust: ``use crate::a::b``; Swift: ``import X``; Ruby: ``require`` and 

15 ``require_relative``. 

16 

17A target that resolves to no layer (a library, the standard library) is not a dependency 

18between layers and is ignored.""" 

19 

20from __future__ import annotations 

21 

22import ast 

23import posixpath 

24import re 

25from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence 

26from dataclasses import dataclass, field 

27from pathlib import Path 

28 

29from governed_harness.checks.architecture import module_name 

30from governed_harness.checks.model import Issue, is_test_path 

31from governed_harness.domain.enums import FindingSeverity 

32 

33RULE_ID = "architecture.layer-violation" 

34_CATEGORY = "architecture" 

35_SEPARATORS = re.compile(r"::|[./\\]") 

36 

37 

38@dataclass(frozen=True) 

39class Layer: 

40 name: str 

41 paths: tuple[str, ...] = () 

42 modules: tuple[str, ...] = () 

43 

44 

45@dataclass(frozen=True) 

46class LayerRules: 

47 layers: tuple[Layer, ...] 

48 allow: Mapping[str, tuple[str, ...]] = field(default_factory=dict) 

49 

50 @classmethod 

51 def from_mapping( 

52 cls, layers: Sequence[Mapping[str, object]], allow: Mapping[str, object] 

53 ) -> LayerRules: 

54 def strings(value: object) -> tuple[str, ...]: 

55 return tuple(str(item) for item in value) if isinstance(value, list | tuple) else () 

56 

57 return cls( 

58 layers=tuple( 

59 Layer( 

60 name=str(item.get("name")), 

61 paths=strings(item.get("paths")), 

62 modules=strings(item.get("modules")), 

63 ) 

64 for item in layers 

65 if item.get("name") 

66 ), 

67 allow={str(key): strings(value) for key, value in allow.items()}, 

68 ) 

69 

70 def as_dict(self) -> dict[str, object]: 

71 return { 

72 "layers": [ 

73 {"name": item.name, "paths": list(item.paths), "modules": list(item.modules)} 

74 for item in self.layers 

75 ], 

76 "allow": {key: list(value) for key, value in self.allow.items()}, 

77 } 

78 

79 def layer_of_path(self, path: str) -> str | None: 

80 for layer in self.layers: 

81 if any(_glob(path, pattern) for pattern in layer.paths): 

82 return layer.name 

83 return None 

84 

85 def layer_of_module(self, module: str) -> str | None: 

86 parts = [item for item in _SEPARATORS.split(module) if item] 

87 best: tuple[int, str] | None = None 

88 for layer in self.layers: 

89 for prefix in layer.modules: 

90 wanted = [item for item in _SEPARATORS.split(prefix) if item] 

91 if ( 

92 wanted 

93 and parts[: len(wanted)] == wanted 

94 and (best is None or len(wanted) > best[0]) 

95 ): 

96 best = (len(wanted), layer.name) 

97 if best is not None: 

98 return best[1] 

99 # A dotted module lives under a path with its segments (``shop.infra.db`` in 

100 # ``src/shop/infra/db.py``, a Java package in its directory). 

101 as_path = "/".join(parts) 

102 if not as_path: 102 ↛ 103line 102 didn't jump to line 103 because the condition on line 102 was never true

103 return None 

104 for candidate in ( 

105 as_path, 

106 f"{as_path}.py", 

107 f"{as_path}/__init__.py", 

108 f"src/{as_path}", 

109 f"src/{as_path}.py", 

110 f"src/{as_path}/__init__.py", 

111 ): 

112 found = self.layer_of_path(candidate) 

113 if found is not None: 

114 return found 

115 return None 

116 

117 def allowed(self, source: str, target: str) -> bool: 

118 return source == target or target in self.allow.get(source, ()) 

119 

120 def forbidden_pairs(self) -> list[tuple[str, str]]: 

121 """``(from, to)`` module prefixes of the #40 form, for the layers that declare 

122 modules.""" 

123 pairs: list[tuple[str, str]] = [] 

124 for source in self.layers: 

125 for target in self.layers: 

126 if self.allowed(source.name, target.name): 

127 continue 

128 pairs.extend((left, right) for left in source.modules for right in target.modules) 

129 return pairs 

130 

131 

132def _glob(path: str, pattern: str) -> bool: 

133 from fnmatch import fnmatchcase 

134 

135 path = path.replace("\\", "/") 

136 if fnmatchcase(path, pattern): 

137 return True 

138 if pattern.startswith("**/") and fnmatchcase(path, pattern[3:]): 138 ↛ 139line 138 didn't jump to line 139 because the condition on line 138 was never true

139 return True 

140 # "src/domain/**" also matches the directory itself and an extension-less import target. 

141 return pattern == f"{path}/**" 

142 

143 

144# ----- imports per language ---------------------------------------------------------------------- 

145_JS_IMPORT = re.compile( 

146 r"""(?:\bfrom\s+|\b(?:import|require)\s*\(\s*|^\s*import\s+)(['"])(?P<target>[^'"]+)\1""" 

147) 

148_JVM_IMPORT = re.compile(r"^\s*import\s+(?:static\s+)?(?P<target>[\w.]+)") 

149_CS_USING = re.compile(r"^\s*(?:global\s+)?using\s+(?:static\s+)?(?P<target>[A-Z][\w.]*)\s*;") 

150_PHP_USE = re.compile(r"^\s*use\s+(?:function\s+|const\s+)?(?P<target>[\w\\]+)") 

151_GO_IMPORT = re.compile(r'^\s*(?:import\s+)?(?:[\w.]+\s+)?"(?P<target>[^"]+)"') 

152_RUST_USE = re.compile(r"^\s*(?:pub\s+)?use\s+(?P<target>(?:crate|super|self)(?:::\w+)+)") 

153_SWIFT_IMPORT = re.compile(r"^\s*(?:@testable\s+)?import\s+(?P<target>\w+)") 

154_RUBY_REQUIRE = re.compile( 

155 r"""^\s*require(?P<relative>_relative)?\s*(?:\(\s*)?(['"])(?P<target>[^'"]+)\2""" 

156) 

157 

158 

159_SINGLE_LINE: dict[str, tuple[re.Pattern[str], str]] = { 

160 "java": (_JVM_IMPORT, ""), 

161 "kt": (_JVM_IMPORT, ""), 

162 "kts": (_JVM_IMPORT, ""), 

163 "scala": (_JVM_IMPORT, ""), 

164 "cs": (_CS_USING, ""), 

165 "php": (_PHP_USE, "\\"), 

166 "rs": (_RUST_USE, "::"), 

167 "swift": (_SWIFT_IMPORT, ""), 

168} 

169"""Languages with one import per line: the pattern and the separator to turn into dots.""" 

170 

171 

172_JS_SUFFIXES = frozenset({"js", "mjs", "cjs", "jsx", "ts", "tsx", "vue"}) 

173 

174_Import = tuple[int, str, str] 

175 

176 

177ModuleExists = Callable[[str], bool] 

178"""Whether a dotted Python module is a module or package of the workspace.""" 

179 

180 

181def known_modules(files: Iterable[str], workspace: Path | None = None) -> ModuleExists: 

182 """Whether a dotted module is one of ``files`` (``a/b.py``) or a directory that holds one 

183 (``a/b/``), at the workspace root or under ``src/``; with ``workspace``, also a file or a 

184 directory on disk. It decides what ``from a import b`` reaches (#166).""" 

185 paths = {item.replace("\\", "/") for item in files} 

186 directories = { 

187 "/".join(parts[:depth]) 

188 for parts in (item.split("/") for item in paths) 

189 for depth in range(1, len(parts)) 

190 } 

191 

192 def exists(module: str) -> bool: 

193 parts = module.split(".") 

194 if not all(part.isidentifier() for part in parts): 194 ↛ 195line 194 didn't jump to line 195 because the condition on line 194 was never true

195 return False 

196 base = "/".join(parts) 

197 for candidate in (base, f"src/{base}"): 

198 if f"{candidate}.py" in paths or candidate in directories: 

199 return True 

200 if workspace is not None and ( 

201 (workspace / f"{candidate}.py").is_file() or (workspace / candidate).is_dir() 

202 ): 

203 return True 

204 return False 

205 

206 return exists 

207 

208 

209def imports(path: str, text: str, module_exists: ModuleExists | None = None) -> Iterator[_Import]: 

210 """``(line, kind, target)`` of every import of a file; ``kind`` is ``path`` (a workspace 

211 path) or ``module`` (a dotted or package name). For ``from pkg import name`` in Python, 

212 ``pkg.name`` is a target only when ``module_exists`` says it is a module (always without 

213 it).""" 

214 suffix = path.rsplit(".", 1)[-1].lower() if "." in path else "" 

215 if suffix == "py": 

216 yield from _python_imports(path, text, module_exists) 

217 return 

218 directory = posixpath.dirname(path) 

219 lines = text.splitlines() 

220 if suffix in _JS_SUFFIXES: 

221 yield from _js_imports(lines, directory) 

222 elif suffix == "go": 

223 yield from _go_imports(lines) 

224 elif suffix == "rb": 224 ↛ 225line 224 didn't jump to line 225 because the condition on line 224 was never true

225 yield from _ruby_imports(lines, directory) 

226 elif suffix in _SINGLE_LINE: 226 ↛ exitline 226 didn't return from function 'imports' because the condition on line 226 was always true

227 yield from _single_line_imports(lines, *_SINGLE_LINE[suffix]) 

228 

229 

230def _js_imports(lines: list[str], directory: str) -> Iterator[_Import]: 

231 for number, line in enumerate(lines, start=1): 

232 for found in _JS_IMPORT.finditer(line): 

233 target = found["target"] 

234 if target.startswith("."): 234 ↛ 237line 234 didn't jump to line 237 because the condition on line 234 was always true

235 yield number, "path", posixpath.normpath(posixpath.join(directory, target)) 

236 else: 

237 yield number, "module", target 

238 

239 

240def _go_imports(lines: list[str]) -> Iterator[_Import]: 

241 in_block = False 

242 for number, line in enumerate(lines, start=1): 

243 stripped = line.strip() 

244 if stripped.startswith("import ("): 

245 in_block = True 

246 continue 

247 if in_block and stripped == ")": 

248 in_block = False 

249 continue 

250 found = _GO_IMPORT.match(line) 

251 if found is not None and (in_block or stripped.startswith("import ")): 251 ↛ 242line 251 didn't jump to line 242 because the condition on line 251 was always true

252 yield number, "module", found["target"] 

253 

254 

255def _ruby_imports(lines: list[str], directory: str) -> Iterator[_Import]: 

256 for number, line in enumerate(lines, start=1): 

257 ruby = _RUBY_REQUIRE.match(line) 

258 if ruby is None: 

259 continue 

260 if ruby["relative"]: 

261 yield number, "path", posixpath.normpath(posixpath.join(directory, ruby["target"])) 

262 else: 

263 yield number, "module", ruby["target"] 

264 

265 

266def _single_line_imports( 

267 lines: list[str], pattern: re.Pattern[str], separator: str 

268) -> Iterator[_Import]: 

269 """One import per line (Java, Kotlin, Scala, C#, PHP, Rust, Swift).""" 

270 for number, line in enumerate(lines, start=1): 

271 found = pattern.match(line) 

272 if found is not None: 

273 target = found["target"] 

274 yield number, "module", target.replace(separator, ".") if separator else target 

275 

276 

277def _python_imports( 

278 path: str, text: str, module_exists: ModuleExists | None 

279) -> Iterator[tuple[int, str, str]]: 

280 from governed_harness.checks.architecture import _imported_modules 

281 

282 try: 

283 tree = ast.parse(text, filename=path) 

284 except SyntaxError: 

285 return 

286 module = module_name(path) 

287 is_package = path.replace("\\", "/").endswith("__init__.py") 

288 for line, imported in _imported_modules(tree, module, is_package, module_exists): 

289 yield line, "module", imported 

290 

291 

292# ----- the check ----------------------------------------------------------------------------------- 

293# Blanks within the line only (``[^\S\n]``) and one optional terminator: linear on any text. 

294_DECLARATION = re.compile( 

295 r"^[^\S\n]*(?:package|namespace)\s+(?P<name>[A-Za-z_][\w.\\]*)[^\S\n]*(?:[;{][^\S\n]*)?$", 

296 re.MULTILINE, 

297) 

298 

299 

300def source_layer(rules: LayerRules, path: str, text: str = "") -> str | None: 

301 """The layer of a file: by its path, else by its module (Python), its declared package or 

302 namespace (Java, Kotlin, C#, PHP, Go), else by a module prefix that appears in its path 

303 (``src/main/java/com/shop/domain/Order.java`` is in ``com.shop.domain``).""" 

304 layer = rules.layer_of_path(path) 

305 if layer is not None: 

306 return layer 

307 if path.endswith(".py"): 

308 return rules.layer_of_module(module_name(path)) 

309 declared = _DECLARATION.search(text) 

310 if declared is not None: 310 ↛ 314line 310 didn't jump to line 314 because the condition on line 310 was always true

311 layer = rules.layer_of_module(declared["name"].replace("\\", ".")) 

312 if layer is not None: 312 ↛ 314line 312 didn't jump to line 314 because the condition on line 312 was always true

313 return layer 

314 return _layer_of_directories(rules, path) 

315 

316 

317def _layer_of_directories(rules: LayerRules, path: str) -> str | None: 

318 """The first layer with a module prefix whose segments appear in the file's directories.""" 

319 parts = [item for item in path.replace("\\", "/").split("/")[:-1] if item] 

320 for layer_item in rules.layers: 

321 for prefix in layer_item.modules: 

322 wanted = [item for item in _SEPARATORS.split(prefix) if item] 

323 if wanted and _contains(parts, wanted): 

324 return layer_item.name 

325 return None 

326 

327 

328def _contains(parts: list[str], wanted: list[str]) -> bool: 

329 return any( 

330 parts[start : start + len(wanted)] == wanted 

331 for start in range(len(parts) - len(wanted) + 1) 

332 ) 

333 

334 

335def check_layers( 

336 files: Mapping[str, str], 

337 rules: LayerRules, 

338 *, 

339 severity: FindingSeverity, 

340 baseline: Callable[[str], str | None] | None = None, 

341 module_exists: ModuleExists | None = None, 

342) -> list[Issue]: 

343 """Every import of a changed (non-test) file that crosses into a layer its layer may not 

344 depend on. 

345 

346 With ``baseline`` (the text of a path before the change, ``None`` for a new file) the 

347 check is differential (``architecture.layerCheck: differential``, #93): a layer the file 

348 already imported on the baseline is a dependency the change did not add, and is not 

349 judged; only an import that reaches a layer the file did not depend on before is. 

350 

351 ``from pkg import name`` reaches the module ``pkg.name`` only when ``module_exists`` (by 

352 default ``known_modules(files)``) says it is one: a function or class ``name`` is not a 

353 path that the pattern of another layer may match (#166).""" 

354 issues: list[Issue] = [] 

355 if not rules.layers: 355 ↛ 356line 355 didn't jump to line 356 because the condition on line 355 was never true

356 return issues 

357 exists = module_exists or known_modules(files) 

358 for path in sorted(files): 

359 if is_test_path(path): 

360 continue 

361 source = source_layer(rules, path, files[path]) 

362 if source is None: 

363 continue 

364 before = baseline(path) if baseline is not None else None 

365 known = imported_layers(rules, path, before, exists) if before is not None else frozenset() 

366 issues.extend(_violations(rules, path, files[path], source, severity, known, exists)) 

367 return issues 

368 

369 

370def imported_layers( 

371 rules: LayerRules, path: str, text: str, module_exists: ModuleExists | None = None 

372) -> frozenset[str]: 

373 """The layers the imports of one file reach.""" 

374 return frozenset( 

375 layer 

376 for _line, kind, target in imports(path, text, module_exists) 

377 if (layer := _target_layer(rules, kind, target)) 

378 ) 

379 

380 

381def _target_layer(rules: LayerRules, kind: str, target: str) -> str | None: 

382 return rules.layer_of_path(target) if kind == "path" else rules.layer_of_module(target) 

383 

384 

385@dataclass(frozen=True) 

386class Crossing: 

387 """An import of a file in layer ``source`` that reaches ``layer``, which ``source`` may not 

388 depend on.""" 

389 

390 path: str 

391 line: int 

392 source: str 

393 target: str 

394 layer: str 

395 

396 

397def crossings( 

398 files: Mapping[str, str], rules: LayerRules, *, module_exists: ModuleExists | None = None 

399) -> list[Crossing]: 

400 """Every forbidden dependency between layers in ``files`` (non-test files), one per line 

401 and layer: what a set of rules forbids in the code as it is (#93). ``module_exists`` is 

402 the one of :func:`check_layers`.""" 

403 found: list[Crossing] = [] 

404 exists = module_exists or known_modules(files) 

405 for path in sorted(files): 

406 if is_test_path(path): 

407 continue 

408 source = source_layer(rules, path, files[path]) 

409 if source is not None: 

410 found.extend(_crossings(rules, path, files[path], source, exists)) 

411 return found 

412 

413 

414def _crossings( 

415 rules: LayerRules, path: str, text: str, source: str, module_exists: ModuleExists 

416) -> Iterator[Crossing]: 

417 reported: set[tuple[int, str]] = set() 

418 for line, kind, target in imports(path, text, module_exists): 

419 layer = _target_layer(rules, kind, target) 

420 if layer is None or rules.allowed(source, layer) or (line, layer) in reported: 

421 continue 

422 reported.add((line, layer)) 

423 yield Crossing(path, line, source, target, layer) 

424 

425 

426def _violations( 

427 rules: LayerRules, 

428 path: str, 

429 text: str, 

430 source: str, 

431 severity: FindingSeverity, 

432 known: frozenset[str], 

433 module_exists: ModuleExists, 

434) -> Iterator[Issue]: 

435 """The imports of one file that reach a layer ``source`` may not depend on, one issue per 

436 line and layer; a layer in ``known`` (the file's baseline already reached it) is skipped.""" 

437 allowed = ", ".join(rules.allow.get(source, ())) or "no other layer" 

438 for crossing in _crossings(rules, path, text, source, module_exists): 

439 if crossing.layer in known: 

440 continue 

441 line, target, layer = crossing.line, crossing.target, crossing.layer 

442 yield Issue( 

443 rule_id=RULE_ID, 

444 severity=severity, 

445 message=( 

446 f"{path} is in layer {source} and imports {target} (layer {layer}); " 

447 f"{source} may depend on {allowed}" 

448 ), 

449 path=path, 

450 line=line, 

451 category=_CATEGORY, 

452 recommendation=( 

453 f"Invert the dependency (an interface in {source} that {layer} " 

454 "implements) or move the code to the layer it belongs to." 

455 ), 

456 ) 

457 

458 

459__all__ = [ 

460 "RULE_ID", 

461 "Crossing", 

462 "Layer", 

463 "LayerRules", 

464 "ModuleExists", 

465 "check_layers", 

466 "crossings", 

467 "imported_layers", 

468 "imports", 

469 "known_modules", 

470 "source_layer", 

471]