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

1"""Whether an implementation honours a declared Python interface. 

2 

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

9 

10from __future__ import annotations 

11 

12import ast 

13from dataclasses import dataclass 

14 

15from governed_harness.checks.model import Issue 

16from governed_harness.domain.enums import FindingSeverity 

17 

18_CATEGORY = "interface" 

19 

20FunctionNode = ast.FunctionDef | ast.AsyncFunctionDef 

21 

22 

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

30 

31 

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

40 

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

65 

66 

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("_") 

71 

72 

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 ) 

79 

80 

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 ) 

88 

89 

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) 

111 

112 

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 

122 

123 

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 ) 

148 

149 

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 

164 

165 

166def _classes(body: list[ast.stmt]) -> dict[str, ast.ClassDef]: 

167 return {node.name: node for node in body if isinstance(node, ast.ClassDef)} 

168 

169 

170def _is_dataclass(node: ast.ClassDef) -> bool: 

171 return "dataclass" in _decorator_names(node) 

172 

173 

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 

185 

186 

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 

195 

196 

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 ) 

202 

203 

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 ) 

208 

209 

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 

231 

232 

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 

242 

243 

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 

264 

265 

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 

285 

286 

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) 

289 

290 

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 

304 

305 

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 

366 

367 

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 ) 

385 

386 

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 ) 

397 

398 

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)] 

418 

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 

452 

453 

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 

488 

489 

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 

527 

528 

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 

546 

547 

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)