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
« 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).
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:
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``.
17A target that resolves to no layer (a library, the standard library) is not a dependency
18between layers and is ignored."""
20from __future__ import annotations
22import ast
23import posixpath
24import re
25from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
26from dataclasses import dataclass, field
27from pathlib import Path
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
33RULE_ID = "architecture.layer-violation"
34_CATEGORY = "architecture"
35_SEPARATORS = re.compile(r"::|[./\\]")
38@dataclass(frozen=True)
39class Layer:
40 name: str
41 paths: tuple[str, ...] = ()
42 modules: tuple[str, ...] = ()
45@dataclass(frozen=True)
46class LayerRules:
47 layers: tuple[Layer, ...]
48 allow: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
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 ()
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 )
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 }
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
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
117 def allowed(self, source: str, target: str) -> bool:
118 return source == target or target in self.allow.get(source, ())
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
132def _glob(path: str, pattern: str) -> bool:
133 from fnmatch import fnmatchcase
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}/**"
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)
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."""
172_JS_SUFFIXES = frozenset({"js", "mjs", "cjs", "jsx", "ts", "tsx", "vue"})
174_Import = tuple[int, str, str]
177ModuleExists = Callable[[str], bool]
178"""Whether a dotted Python module is a module or package of the workspace."""
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 }
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
206 return exists
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])
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
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"]
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"]
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
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
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
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)
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)
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
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 )
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.
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.
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
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 )
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)
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."""
390 path: str
391 line: int
392 source: str
393 target: str
394 layer: str
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
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)
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 )
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]