Coverage for src/governed_harness/checks/interface.py: 87%
271 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"""Whether an implementation honours a declared Python interface.
3A task can declare the interface it expects (a ``.pyi`` stub, or a ``.py`` file whose bodies are
4``...``). An agent that renames a parameter, turns a keyword-only argument into a positional one or
5leaves ``raise NotImplementedError`` behind still passes a test suite that does not exercise that
6path, so the comparison is structural: it reads both sources with ``ast`` and never imports them.
7Annotations are deliberately not compared: they do not change how a caller invokes the symbol, and
8stub annotations routinely differ in spelling (``Optional[int]`` vs ``int | None``)."""
10from __future__ import annotations
12import ast
13from dataclasses import dataclass
15from governed_harness.checks.model import Issue
16from governed_harness.domain.enums import FindingSeverity
18_CATEGORY = "interface"
20FunctionNode = ast.FunctionDef | ast.AsyncFunctionDef
23@dataclass(frozen=True)
24class _Param:
25 name: str
26 kind: str
27 """One of ``posonly``, ``regular``, ``vararg``, ``kwonly``, ``kwarg``."""
28 default: str | None
29 """``ast.unparse`` of the default, or ``None`` when the parameter has no default."""
32@dataclass(frozen=True)
33class _Signature:
34 name: str
35 params: tuple[_Param, ...]
36 is_async: bool
37 line: int | None
38 node: FunctionNode | None
39 """The implementing ``def``; ``None`` for a signature synthesised from a dataclass."""
41 def render(self) -> str:
42 parts: list[str] = []
43 previous = ""
44 star_written = False
45 for param in self.params:
46 if previous == "posonly" and param.kind != "posonly": 46 ↛ 47line 46 didn't jump to line 47 because the condition on line 46 was never true
47 parts.append("/")
48 if param.kind == "kwonly" and not star_written:
49 parts.append("*")
50 star_written = True
51 if param.kind == "vararg": 51 ↛ 52line 51 didn't jump to line 52 because the condition on line 51 was never true
52 parts.append(f"*{param.name}")
53 star_written = True
54 elif param.kind == "kwarg":
55 parts.append(f"**{param.name}")
56 elif param.default is not None:
57 parts.append(f"{param.name}={param.default}")
58 else:
59 parts.append(param.name)
60 previous = param.kind
61 if previous == "posonly": 61 ↛ 62line 61 didn't jump to line 62 because the condition on line 61 was never true
62 parts.append("/")
63 prefix = "async " if self.is_async else ""
64 return f"{prefix}{self.name}({', '.join(parts)})"
67def is_public(name: str) -> bool:
68 """Public names are those a caller is meant to use: no leading underscore, plus
69 ``__init__``, whose signature is how a class is constructed."""
70 return name == "__init__" or not name.startswith("_")
73def _is_docstring(statement: ast.stmt) -> bool:
74 return (
75 isinstance(statement, ast.Expr)
76 and isinstance(statement.value, ast.Constant)
77 and isinstance(statement.value.value, str)
78 )
81def _is_not_implemented(statement: ast.stmt) -> bool:
82 if not isinstance(statement, ast.Raise) or statement.exc is None:
83 return False
84 target = statement.exc.func if isinstance(statement.exc, ast.Call) else statement.exc
85 return (isinstance(target, ast.Name) and target.id == "NotImplementedError") or (
86 isinstance(target, ast.Attribute) and target.attr == "NotImplementedError"
87 )
90def is_stub_body(body: list[ast.stmt]) -> bool:
91 """Whether a function body does nothing: only ``pass``, ``...``, a docstring, or
92 ``raise NotImplementedError`` (optionally after a docstring). Such a body satisfies the
93 interface on paper while delivering no behaviour."""
94 statements = list(body)
95 if statements and _is_docstring(statements[0]):
96 statements = statements[1:]
97 if not statements:
98 return True
99 if len(statements) != 1: 99 ↛ 100line 99 didn't jump to line 100 because the condition on line 99 was never true
100 return False
101 only = statements[0]
102 if isinstance(only, ast.Pass):
103 return True
104 if (
105 isinstance(only, ast.Expr)
106 and isinstance(only.value, ast.Constant)
107 and only.value.value is Ellipsis
108 ):
109 return True
110 return _is_not_implemented(only)
113def _decorator_names(node: FunctionNode | ast.ClassDef) -> set[str]:
114 names: set[str] = set()
115 for decorator in node.decorator_list:
116 target = decorator.func if isinstance(decorator, ast.Call) else decorator
117 if isinstance(target, ast.Name): 117 ↛ 119line 117 didn't jump to line 119 because the condition on line 117 was always true
118 names.add(target.id)
119 elif isinstance(target, ast.Attribute):
120 names.add(target.attr)
121 return names
124def _signature(node: FunctionNode) -> _Signature:
125 args = node.args
126 positional = [*args.posonlyargs, *args.args]
127 defaults: list[ast.expr | None] = [None] * (len(positional) - len(args.defaults))
128 defaults.extend(args.defaults)
129 params: list[_Param] = []
130 for index, arg in enumerate(positional):
131 kind = "posonly" if index < len(args.posonlyargs) else "regular"
132 default = defaults[index]
133 params.append(_Param(arg.arg, kind, None if default is None else ast.unparse(default)))
134 if args.vararg is not None: 134 ↛ 135line 134 didn't jump to line 135 because the condition on line 134 was never true
135 params.append(_Param(args.vararg.arg, "vararg", None))
136 for arg, kw_default in zip(args.kwonlyargs, args.kw_defaults, strict=True):
137 rendered = None if kw_default is None else ast.unparse(kw_default)
138 params.append(_Param(arg.arg, "kwonly", rendered))
139 if args.kwarg is not None:
140 params.append(_Param(args.kwarg.arg, "kwarg", None))
141 return _Signature(
142 name=node.name,
143 params=tuple(params),
144 is_async=isinstance(node, ast.AsyncFunctionDef),
145 line=node.lineno,
146 node=node,
147 )
150def _functions(body: list[ast.stmt]) -> dict[str, FunctionNode]:
151 """The functions defined directly in a body, by name. ``@overload`` variants only stand in
152 for a name when nothing else defines it; a later definition replaces an earlier one, as at
153 run time."""
154 found: dict[str, FunctionNode] = {}
155 for statement in body:
156 if not isinstance(statement, ast.FunctionDef | ast.AsyncFunctionDef):
157 continue
158 is_overload = "overload" in _decorator_names(statement)
159 current = found.get(statement.name)
160 if is_overload and current is not None and "overload" not in _decorator_names(current): 160 ↛ 161line 160 didn't jump to line 161 because the condition on line 160 was never true
161 continue
162 found[statement.name] = statement
163 return found
166def _classes(body: list[ast.stmt]) -> dict[str, ast.ClassDef]:
167 return {node.name: node for node in body if isinstance(node, ast.ClassDef)}
170def _is_dataclass(node: ast.ClassDef) -> bool:
171 return "dataclass" in _decorator_names(node)
174def _dataclass_kw_only(node: ast.ClassDef) -> bool:
175 for decorator in node.decorator_list:
176 if isinstance(decorator, ast.Call): 176 ↛ 177line 176 didn't jump to line 177 because the condition on line 176 was never true
177 for keyword in decorator.keywords:
178 if (
179 keyword.arg == "kw_only"
180 and isinstance(keyword.value, ast.Constant)
181 and keyword.value.value is True
182 ):
183 return True
184 return False
187def _field_call(value: ast.expr | None) -> ast.Call | None:
188 if not isinstance(value, ast.Call):
189 return None
190 func = value.func
191 is_field = (isinstance(func, ast.Name) and func.id == "field") or (
192 isinstance(func, ast.Attribute) and func.attr == "field"
193 )
194 return value if is_field else None
197def _is_classvar(annotation: ast.expr) -> bool:
198 target = annotation.value if isinstance(annotation, ast.Subscript) else annotation
199 return (isinstance(target, ast.Name) and target.id == "ClassVar") or (
200 isinstance(target, ast.Attribute) and target.attr == "ClassVar"
201 )
204def _is_kw_only_marker(annotation: ast.expr) -> bool:
205 return (isinstance(annotation, ast.Name) and annotation.id == "KW_ONLY") or (
206 isinstance(annotation, ast.Attribute) and annotation.attr == "KW_ONLY"
207 )
210def _dataclass_params(node: ast.ClassDef, classes: dict[str, ast.ClassDef]) -> list[_Param]:
211 """The ``__init__`` parameters ``@dataclass`` generates, base dataclasses of the same
212 module first. Without this a declared ``__init__`` would be reported missing for every
213 dataclass, which is how most value objects are written."""
214 params = _base_dataclass_params(node, classes)
215 kw_only = _dataclass_kw_only(node)
216 for statement in node.body:
217 if not isinstance(statement, ast.AnnAssign) or not isinstance(statement.target, ast.Name): 217 ↛ 218line 217 didn't jump to line 218 because the condition on line 217 was never true
218 continue
219 if _is_classvar(statement.annotation): 219 ↛ 220line 219 didn't jump to line 220 because the condition on line 219 was never true
220 continue
221 if _is_kw_only_marker(statement.annotation): 221 ↛ 222line 221 didn't jump to line 222 because the condition on line 221 was never true
222 kw_only = True
223 continue
224 default, include = _field_default(statement)
225 if not include: 225 ↛ 226line 225 didn't jump to line 226 because the condition on line 225 was never true
226 continue
227 name = statement.target.id
228 params = [param for param in params if param.name != name]
229 params.append(_Param(name, "kwonly" if kw_only else "regular", default))
230 return params
233def _base_dataclass_params(node: ast.ClassDef, classes: dict[str, ast.ClassDef]) -> list[_Param]:
234 """The generated parameters of the base dataclasses of the same module, in base order."""
235 params: list[_Param] = []
236 for base in node.bases:
237 if isinstance(base, ast.Name) and base.id in classes and base.id != node.name: 237 ↛ 236line 237 didn't jump to line 236 because the condition on line 237 was always true
238 base_node = classes[base.id]
239 if _is_dataclass(base_node): 239 ↛ 240line 239 didn't jump to line 240 because the condition on line 239 was never true
240 params.extend(_dataclass_params(base_node, classes))
241 return params
244def _field_default(statement: ast.AnnAssign) -> tuple[str | None, bool]:
245 """The default a dataclass field gives its parameter and whether ``__init__`` takes it."""
246 default: str | None = None
247 include = True
248 call = _field_call(statement.value)
249 if call is not None:
250 for keyword in call.keywords:
251 if keyword.arg == "default": 251 ↛ 252line 251 didn't jump to line 252 because the condition on line 251 was never true
252 default = ast.unparse(keyword.value)
253 elif keyword.arg == "default_factory": 253 ↛ 255line 253 didn't jump to line 255 because the condition on line 253 was always true
254 default = f"field(default_factory={ast.unparse(keyword.value)})"
255 elif (
256 keyword.arg == "init"
257 and isinstance(keyword.value, ast.Constant)
258 and keyword.value.value is False
259 ):
260 include = False
261 elif statement.value is not None: 261 ↛ 262line 261 didn't jump to line 262 because the condition on line 261 was never true
262 default = ast.unparse(statement.value)
263 return default, include
266def _find_method(
267 cls: ast.ClassDef, name: str, classes: dict[str, ast.ClassDef], seen: set[str]
268) -> _Signature | None:
269 """A method of a class, looked up in the class, then in its bases defined in the same
270 module (an inherited method satisfies the interface), then, for ``__init__`` of a
271 dataclass, the generated constructor."""
272 seen.add(cls.name)
273 method = _functions(cls.body).get(name)
274 if method is not None:
275 return _signature(method)
276 if name == "__init__" and _is_dataclass(cls):
277 params = (_Param("self", "regular", None), *_dataclass_params(cls, classes))
278 return _Signature("__init__", tuple(params), False, cls.lineno, None)
279 for base in cls.bases:
280 if isinstance(base, ast.Name) and base.id in classes and base.id not in seen: 280 ↛ 279line 280 didn't jump to line 279 because the condition on line 280 was always true
281 found = _find_method(classes[base.id], name, classes, seen)
282 if found is not None: 282 ↛ 279line 282 didn't jump to line 279 because the condition on line 282 was always true
283 return found
284 return None
287def _shape(signature: _Signature) -> tuple[bool, tuple[tuple[str, str], ...]]:
288 return signature.is_async, tuple((param.name, param.kind) for param in signature.params)
291def _default_differences(declared: _Signature, actual: _Signature) -> list[str]:
292 differences: list[str] = []
293 for want, have in zip(declared.params, actual.params, strict=True):
294 if want.default is None and have.default is None:
295 continue
296 if want.default == "..." and have.default is not None:
297 continue
298 if want.default != have.default:
299 differences.append(
300 f"{want.name}: declared {want.default or 'no default'}, "
301 f"actual {have.default or 'no default'}"
302 )
303 return differences
306def _compare(
307 qualified: str,
308 declared: _Signature,
309 actual: _Signature,
310 *,
311 implementation_path: str,
312 severity: FindingSeverity,
313) -> list[Issue]:
314 issues: list[Issue] = []
315 if _shape(declared) != _shape(actual):
316 issues.append(
317 Issue(
318 rule_id="interface.signature",
319 severity=severity,
320 message=(
321 f"{qualified} does not match the declared signature: declared "
322 f"`{declared.render()}`, actual `{actual.render()}`."
323 ),
324 path=implementation_path,
325 line=actual.line,
326 category=_CATEGORY,
327 recommendation=(
328 "Keep the declared parameter names, order and kinds (positional-only, "
329 "keyword-only, *args, **kwargs) and the declared async/sync form."
330 ),
331 )
332 )
333 else:
334 differences = _default_differences(declared, actual)
335 if differences:
336 issues.append(
337 Issue(
338 rule_id="interface.default",
339 severity=severity,
340 message=(
341 f"{qualified} changes declared defaults ({'; '.join(differences)}): "
342 f"declared `{declared.render()}`, actual `{actual.render()}`."
343 ),
344 path=implementation_path,
345 line=actual.line,
346 category=_CATEGORY,
347 recommendation="Use the default values the interface declares.",
348 )
349 )
350 if actual.node is not None and is_stub_body(actual.node.body):
351 issues.append(
352 Issue(
353 rule_id="interface.stub",
354 severity=severity,
355 message=(
356 f"{qualified} is declared by the interface but its implementation is a "
357 "stub (pass, ..., a docstring or raise NotImplementedError)."
358 ),
359 path=implementation_path,
360 line=actual.line,
361 category=_CATEGORY,
362 recommendation="Implement the behaviour the interface declares.",
363 )
364 )
365 return issues
368def _missing(
369 qualified: str,
370 kind: str,
371 *,
372 implementation_path: str,
373 line: int | None,
374 severity: FindingSeverity,
375) -> Issue:
376 return Issue(
377 rule_id="interface.missing",
378 severity=severity,
379 message=f"The declared {kind} {qualified} is not defined in {implementation_path}.",
380 path=implementation_path,
381 line=line,
382 category=_CATEGORY,
383 recommendation=f"Define {qualified} with the declared signature.",
384 )
387def _unparsable(which: str, path: str, error: SyntaxError) -> Issue:
388 return Issue(
389 rule_id="interface.unparsable",
390 severity=FindingSeverity.INFO,
391 message=f"The {which} source {path} could not be parsed ({error.msg}); "
392 "the interface was not compared.",
393 path=path,
394 line=error.lineno,
395 category=_CATEGORY,
396 )
399def check_interface(
400 declared_source: str,
401 implementation_source: str,
402 *,
403 declared_path: str,
404 implementation_path: str,
405 severity: FindingSeverity,
406) -> list[Issue]:
407 """Compare the public top-level functions and classes (and their public methods) of a
408 declared interface with an implementation, and report missing symbols, signature and default
409 mismatches and stub bodies."""
410 try:
411 declared_tree = ast.parse(declared_source, filename=declared_path)
412 except SyntaxError as error:
413 return [_unparsable("declared", declared_path, error)]
414 try:
415 implementation_tree = ast.parse(implementation_source, filename=implementation_path)
416 except SyntaxError as error:
417 return [_unparsable("implementation", implementation_path, error)]
419 issues = _compare_functions(
420 declared_tree,
421 _functions(implementation_tree.body),
422 implementation_path=implementation_path,
423 severity=severity,
424 )
425 actual_classes = _classes(implementation_tree.body)
426 for class_name, class_node in _classes(declared_tree.body).items():
427 if not is_public(class_name): 427 ↛ 428line 427 didn't jump to line 428 because the condition on line 427 was never true
428 continue
429 actual_class = actual_classes.get(class_name)
430 if actual_class is None:
431 issues.append(
432 _missing(
433 class_name,
434 "class",
435 implementation_path=implementation_path,
436 line=None,
437 severity=severity,
438 )
439 )
440 continue
441 issues.extend(
442 _compare_methods(
443 class_name,
444 class_node,
445 actual_class,
446 actual_classes,
447 implementation_path=implementation_path,
448 severity=severity,
449 )
450 )
451 return issues
454def _compare_functions(
455 declared_tree: ast.Module,
456 actual_functions: dict[str, FunctionNode],
457 *,
458 implementation_path: str,
459 severity: FindingSeverity,
460) -> list[Issue]:
461 """The issues of the declared public top-level functions, in declaration order."""
462 issues: list[Issue] = []
463 for name, node in _functions(declared_tree.body).items():
464 if not is_public(name):
465 continue
466 actual = actual_functions.get(name)
467 if actual is None:
468 issues.append(
469 _missing(
470 name,
471 "function",
472 implementation_path=implementation_path,
473 line=None,
474 severity=severity,
475 )
476 )
477 continue
478 issues.extend(
479 _compare(
480 name,
481 _signature(node),
482 _signature(actual),
483 implementation_path=implementation_path,
484 severity=severity,
485 )
486 )
487 return issues
490def _compare_methods(
491 class_name: str,
492 class_node: ast.ClassDef,
493 actual_class: ast.ClassDef,
494 actual_classes: dict[str, ast.ClassDef],
495 *,
496 implementation_path: str,
497 severity: FindingSeverity,
498) -> list[Issue]:
499 """The issues of the public methods one declared class has, in declaration order."""
500 issues: list[Issue] = []
501 for method_name, method in _functions(class_node.body).items():
502 if not is_public(method_name):
503 continue
504 qualified = f"{class_name}.{method_name}"
505 found = _find_method(actual_class, method_name, actual_classes, set())
506 if found is None:
507 issues.append(
508 _missing(
509 qualified,
510 "method",
511 implementation_path=implementation_path,
512 line=actual_class.lineno,
513 severity=severity,
514 )
515 )
516 continue
517 issues.extend(
518 _compare(
519 qualified,
520 _signature(method),
521 found,
522 implementation_path=implementation_path,
523 severity=severity,
524 )
525 )
526 return issues
529def declared_names(declared_source: str) -> list[str]:
530 """The public functions and methods an interface declares (``create_order``,
531 ``Dispatcher.advance``), in source order, so other checks can look for them (in tests, in
532 traceability). Constructors are left out: callers name the class, not ``__init__``. An
533 unparsable source declares nothing."""
534 try:
535 tree = ast.parse(declared_source)
536 except SyntaxError:
537 return []
538 names: list[str] = []
539 for node in tree.body:
540 if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
541 if not node.name.startswith("_") and node.name not in names:
542 names.append(node.name)
543 elif isinstance(node, ast.ClassDef) and not node.name.startswith("_"): 543 ↛ 539line 543 didn't jump to line 539 because the condition on line 543 was always true
544 _add_method_names(node, names)
545 return names
548def _add_method_names(node: ast.ClassDef, names: list[str]) -> None:
549 """Append the public methods of a class (``Class.method``) that ``names`` lacks."""
550 for member in node.body:
551 if isinstance(
552 member, ast.FunctionDef | ast.AsyncFunctionDef
553 ) and not member.name.startswith("_"):
554 qualified = f"{node.name}.{member.name}"
555 if qualified not in names: 555 ↛ 550line 555 didn't jump to line 550 because the condition on line 555 was always true
556 names.append(qualified)