Coverage for src/governed_harness/checks/constraints.py: 92%

273 statements  

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

1"""Checks for the constraints a task states in prose. 

2 

3A task says "use only the standard library" or "never read the clock"; an agent may agree and 

4still import ``requests`` or call ``datetime.now()``. ``constraints_from_task`` maps the 

5constraint sentences to a closed set of machine checks (plus any the task declares by name), and 

6``check_constraints`` applies them to the changed, non-test Python files with ``ast``. The 

7mapping is keyword based on purpose: it is deterministic and auditable, and a sentence it does not 

8recognise simply adds no check (the task can still declare the check explicitly).""" 

9 

10from __future__ import annotations 

11 

12import ast 

13import re 

14import sys 

15from collections.abc import Iterator, Mapping, Sequence 

16 

17from governed_harness.checks.interface import is_stub_body 

18from governed_harness.checks.model import Issue, is_test_path 

19from governed_harness.domain.enums import FindingSeverity 

20 

21CONSTRAINT_CHECKS: tuple[str, ...] = ( 

22 "stdlib-only", 

23 "no-clock-random", 

24 "annotated-public-api", 

25 "no-float-money", 

26 "no-stubs", 

27) 

28 

29_CATEGORY = "constraints" 

30 

31_NEGATION = re.compile(r"\b(?:never|no|not|without|deterministic\w*)\b|n't\b") 

32_MONEY_SENTENCE = re.compile( 

33 r"\b(?:money|(?:price|amount|fare|cost|balance|fee|total)s?|currency|currencies)\b" 

34) 

35_STUB_SENTENCE = re.compile(r"notimplementederror|\bstub|placeholder") 

36_MONEY_TOKEN = re.compile( 

37 r"^(?:price|amount|total|fare|cost|balance|fee|subtotal|money|charge|payment|salary|" 

38 r"salaries|tax)(?:e?s)?$" 

39) 

40 

41_CLOCK_CALLS = frozenset( 

42 { 

43 "time.time", 

44 "time.time_ns", 

45 "datetime.now", 

46 "datetime.utcnow", 

47 "datetime.today", 

48 "date.today", 

49 "datetime.datetime.now", 

50 "datetime.datetime.utcnow", 

51 "datetime.datetime.today", 

52 "datetime.date.today", 

53 "uuid.uuid1", 

54 "uuid.uuid4", 

55 "os.urandom", 

56 } 

57) 

58 

59 

60def constraints_from_task( 

61 constraints: Sequence[str], declared: Sequence[str] = () 

62) -> tuple[str, ...]: 

63 """The constraint checks that apply to a task: the ones it declares by name (unknown names 

64 are ignored) and the ones its constraint sentences ask for, in ``CONSTRAINT_CHECKS`` order.""" 

65 selected = {name for name in declared if name in CONSTRAINT_CHECKS} 

66 for sentence in constraints: 

67 selected.update(_sentence_checks(sentence.lower())) 

68 return tuple(name for name in CONSTRAINT_CHECKS if name in selected) 

69 

70 

71def _sentence_checks(text: str) -> list[str]: 

72 """The constraint checks one lower-cased constraint sentence asks for.""" 

73 found: list[str] = [] 

74 if "standard library" in text or "stdlib" in text: 

75 found.append("stdlib-only") 

76 if ("clock" in text or "random" in text) and _NEGATION.search(text): 

77 found.append("no-clock-random") 

78 if ("type hint" in text or "annotat" in text or "typed" in text) and "public" in text: 

79 found.append("annotated-public-api") 

80 if "float" in text and _MONEY_SENTENCE.search(text): 

81 found.append("no-float-money") 

82 if _STUB_SENTENCE.search(text): 

83 found.append("no-stubs") 

84 return found 

85 

86 

87def first_party_modules(paths: Sequence[str]) -> frozenset[str]: 

88 """The top-level import names the change itself provides: ``src/<name>/...`` gives 

89 ``<name>``, ``<dir>/...`` gives ``<dir>`` and a top-level ``<stem>.py`` gives ``<stem>``. 

90 ``__future__`` is a compiler directive, not a dependency.""" 

91 names = {"__future__"} 

92 for raw in paths: 

93 parts = [part for part in raw.replace("\\", "/").split("/") if part and part != "."] 

94 if parts and parts[0] == "src" and len(parts) > 1: 

95 parts = parts[1:] 

96 if not parts: 96 ↛ 97line 96 didn't jump to line 97 because the condition on line 96 was never true

97 continue 

98 head = parts[0] 

99 if len(parts) == 1: 

100 head = head.rsplit(".", 1)[0] if "." in head else head 

101 names.add(head) 

102 return frozenset(names) 

103 

104 

105def _issue( 

106 rule_id: str, 

107 message: str, 

108 path: str, 

109 line: int | None, 

110 severity: FindingSeverity, 

111 recommendation: str, 

112) -> Issue: 

113 return Issue( 

114 rule_id=rule_id, 

115 severity=severity, 

116 message=message, 

117 path=path, 

118 line=line, 

119 category=_CATEGORY, 

120 recommendation=recommendation, 

121 ) 

122 

123 

124def check_constraints( 

125 checks: Sequence[str], files: Mapping[str, str], *, severity: FindingSeverity 

126) -> list[Issue]: 

127 """Apply the selected constraint checks (unknown names are ignored) to the non-test Python 

128 files of a change.""" 

129 selected = {name for name in checks if name in CONSTRAINT_CHECKS} 

130 if not selected: 

131 return [] 

132 first_party = first_party_modules(list(files)) 

133 issues: list[Issue] = [] 

134 for path in sorted(files): 

135 if not path.endswith(".py") or is_test_path(path): 

136 continue 

137 source = files[path] 

138 try: 

139 tree = ast.parse(source, filename=path) 

140 except SyntaxError as error: 

141 issues.append(_unparsable(path, error)) 

142 continue 

143 issues.extend(_file_issues(selected, path, tree, source, first_party, severity)) 

144 return issues 

145 

146 

147def _unparsable(path: str, error: SyntaxError) -> Issue: 

148 return Issue( 

149 rule_id="constraints.unparsable", 

150 severity=FindingSeverity.INFO, 

151 message=f"{path} could not be parsed ({error.msg}); its constraints were not checked.", 

152 path=path, 

153 line=error.lineno, 

154 category=_CATEGORY, 

155 ) 

156 

157 

158def _file_issues( 

159 selected: set[str], 

160 path: str, 

161 tree: ast.Module, 

162 source: str, 

163 first_party: frozenset[str], 

164 severity: FindingSeverity, 

165) -> list[Issue]: 

166 """The issues of the selected checks on one parsed file, in check order.""" 

167 issues: list[Issue] = [] 

168 if "stdlib-only" in selected: 

169 issues.extend(_non_stdlib_imports(path, tree, first_party, severity)) 

170 if "no-clock-random" in selected: 

171 issues.extend(_clock_or_random(path, tree, source.splitlines(), severity)) 

172 if "annotated-public-api" in selected: 

173 issues.extend(_unannotated_public_api(path, tree, severity)) 

174 if "no-float-money" in selected: 

175 issues.extend(_float_money(path, tree, severity)) 

176 if "no-stubs" in selected: 

177 issues.extend(_stubs(path, tree, severity)) 

178 return issues 

179 

180 

181# stdlib-only ---------------------------------------------------------------------------------- 

182 

183 

184def _non_stdlib_imports( 

185 path: str, tree: ast.Module, first_party: frozenset[str], severity: FindingSeverity 

186) -> list[Issue]: 

187 seen: set[str] = set() 

188 issues: list[Issue] = [] 

189 for node in ast.walk(tree): 

190 if isinstance(node, ast.Import): 

191 modules = [alias.name for alias in node.names] 

192 elif isinstance(node, ast.ImportFrom) and not node.level and node.module: 

193 modules = [node.module] 

194 else: 

195 continue 

196 for module in modules: 

197 top = module.split(".", 1)[0] 

198 if top in sys.stdlib_module_names or top in first_party or top in seen: 

199 continue 

200 seen.add(top) 

201 issues.append( 

202 _issue( 

203 "constraints.non-stdlib-import", 

204 f"{path} imports {module}, which is neither in the standard library nor " 

205 "part of the change; the task allows only the standard library.", 

206 path, 

207 node.lineno, 

208 severity, 

209 f"Replace {top} with a standard library module.", 

210 ) 

211 ) 

212 return sorted(issues, key=lambda issue: issue.line or 0) 

213 

214 

215# no-clock-random ------------------------------------------------------------------------------ 

216 

217 

218def _import_aliases(tree: ast.Module) -> dict[str, str]: 

219 """Local names bound by imports, mapped to the dotted name they stand for.""" 

220 aliases: dict[str, str] = {} 

221 for node in ast.walk(tree): 

222 if isinstance(node, ast.Import): 

223 _add_import_aliases(node, aliases) 

224 elif isinstance(node, ast.ImportFrom) and not node.level and node.module: 

225 for alias in node.names: 

226 aliases[alias.asname or alias.name] = f"{node.module}.{alias.name}" 

227 return aliases 

228 

229 

230def _add_import_aliases(node: ast.Import, aliases: dict[str, str]) -> None: 

231 """The names an ``import`` statement binds: its alias, or the top-level package.""" 

232 for alias in node.names: 

233 if alias.asname: 233 ↛ 234line 233 didn't jump to line 234 because the condition on line 233 was never true

234 aliases[alias.asname] = alias.name 

235 else: 

236 top = alias.name.split(".", 1)[0] 

237 aliases[top] = top 

238 

239 

240def _dotted(node: ast.expr) -> str | None: 

241 parts: list[str] = [] 

242 while isinstance(node, ast.Attribute): 

243 parts.append(node.attr) 

244 node = node.value 

245 if not isinstance(node, ast.Name): 245 ↛ 246line 245 didn't jump to line 246 because the condition on line 245 was never true

246 return None 

247 parts.append(node.id) 

248 return ".".join(reversed(parts)) 

249 

250 

251def _resolve(call: ast.Call, aliases: dict[str, str]) -> str | None: 

252 dotted = _dotted(call.func) 

253 if dotted is None: 253 ↛ 254line 253 didn't jump to line 254 because the condition on line 253 was never true

254 return None 

255 head, _, rest = dotted.partition(".") 

256 resolved = aliases.get(head, head) 

257 return f"{resolved}.{rest}" if rest else resolved 

258 

259 

260def _is_nondeterministic(name: str, call: ast.Call) -> bool: 

261 if name in _CLOCK_CALLS: 

262 return True 

263 module, _, function = name.partition(".") 

264 if module == "random" and function: 

265 # ``random.Random(seed)`` is a seeded generator: deterministic by construction. 

266 return not (function == "Random" and (call.args or call.keywords)) 

267 return module == "secrets" and bool(function) 

268 

269 

270def _clock_or_random( 

271 path: str, tree: ast.Module, lines: list[str], severity: FindingSeverity 

272) -> list[Issue]: 

273 aliases = _import_aliases(tree) 

274 issues: list[Issue] = [] 

275 

276 def visit(node: ast.AST, function: str) -> None: 

277 for child in ast.iter_child_nodes(node): 

278 scope = function 

279 if isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef): 

280 scope = child.name 

281 if isinstance(child, ast.Call): 

282 name = _resolve(child, aliases) 

283 if name is not None and _is_nondeterministic(name, child): 

284 issues.extend(_clock_issue(path, child, name, scope, lines, severity)) 

285 visit(child, scope) 

286 

287 visit(tree, "") 

288 return issues 

289 

290 

291def _clock_issue( 

292 path: str, 

293 call: ast.Call, 

294 name: str, 

295 function: str, 

296 lines: list[str], 

297 severity: FindingSeverity, 

298) -> list[Issue]: 

299 if name.startswith("secrets.") or name == "os.urandom": 

300 line_text = lines[call.lineno - 1] if 0 < call.lineno <= len(lines) else "" 

301 if "salt" in function.lower() or "salt" in line_text.lower(): 

302 return [] 

303 return [ 

304 _issue( 

305 "constraints.clock-or-random", 

306 f"{name}() reads the clock or a random source; the task requires deterministic " 

307 "behaviour.", 

308 path, 

309 call.lineno, 

310 severity, 

311 "Inject the clock or the random generator (a parameter or a seeded " 

312 "random.Random) so callers and tests control it.", 

313 ) 

314 ] 

315 

316 

317# annotated-public-api ------------------------------------------------------------------------- 

318 

319 

320def _is_public(name: str) -> bool: 

321 return name == "__init__" or not name.startswith("_") 

322 

323 

324def _missing_annotations(function: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]: 

325 args = function.args 

326 missing = [ 

327 arg.arg 

328 for arg in [*args.posonlyargs, *args.args, *args.kwonlyargs] 

329 if arg.annotation is None and arg.arg not in {"self", "cls"} 

330 ] 

331 for star, arg in (("*", args.vararg), ("**", args.kwarg)): 

332 if arg is not None and arg.annotation is None: 332 ↛ 333line 332 didn't jump to line 333 because the condition on line 332 was never true

333 missing.append(f"{star}{arg.arg}") 

334 if function.returns is None and function.name != "__init__": 

335 missing.append("return") 

336 return missing 

337 

338 

339def _public_functions(tree: ast.Module) -> list[tuple[str, ast.FunctionDef | ast.AsyncFunctionDef]]: 

340 """The public module functions and the public methods of public classes, qualified.""" 

341 candidates: list[tuple[str, ast.FunctionDef | ast.AsyncFunctionDef]] = [] 

342 for node in tree.body: 

343 if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) and _is_public(node.name): 

344 candidates.append((node.name, node)) 

345 elif isinstance(node, ast.ClassDef) and not node.name.startswith("_"): 

346 candidates.extend( 

347 (f"{node.name}.{member.name}", member) 

348 for member in node.body 

349 if isinstance(member, ast.FunctionDef | ast.AsyncFunctionDef) 

350 and _is_public(member.name) 

351 ) 

352 return candidates 

353 

354 

355def _unannotated_public_api(path: str, tree: ast.Module, severity: FindingSeverity) -> list[Issue]: 

356 candidates = _public_functions(tree) 

357 issues: list[Issue] = [] 

358 for qualified, function in candidates: 

359 missing = _missing_annotations(function) 

360 if missing: 

361 issues.append( 

362 _issue( 

363 "constraints.unannotated-public-api", 

364 f"{qualified} is public but lacks type annotations for: {', '.join(missing)}.", 

365 path, 

366 function.lineno, 

367 severity, 

368 "Annotate every parameter and the return type of the public API.", 

369 ) 

370 ) 

371 return issues 

372 

373 

374# no-float-money ------------------------------------------------------------------------------- 

375 

376 

377def _is_money_name(name: str) -> bool: 

378 snake = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name).lower() 

379 return any(_MONEY_TOKEN.match(token) for token in snake.split("_") if token) 

380 

381 

382def _mentions_float(annotation: ast.expr | None) -> bool: 

383 if annotation is None: 

384 return False 

385 if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str): 385 ↛ 386line 385 didn't jump to line 386 because the condition on line 385 was never true

386 try: 

387 annotation = ast.parse(annotation.value, mode="eval").body 

388 except SyntaxError: 

389 return False 

390 return any(isinstance(node, ast.Name) and node.id == "float" for node in ast.walk(annotation)) 

391 

392 

393def _is_float_value(value: ast.expr | None) -> bool: 

394 if isinstance(value, ast.UnaryOp) and isinstance(value.op, ast.USub | ast.UAdd): 394 ↛ 395line 394 didn't jump to line 395 because the condition on line 394 was never true

395 value = value.operand 

396 if isinstance(value, ast.Constant): 

397 return isinstance(value.value, float) 

398 return ( 

399 isinstance(value, ast.Call) 

400 and isinstance(value.func, ast.Name) 

401 and value.func.id == "float" 

402 ) 

403 

404 

405def _target_name(target: ast.expr) -> str | None: 

406 if isinstance(target, ast.Name): 406 ↛ 408line 406 didn't jump to line 408 because the condition on line 406 was always true

407 return target.id 

408 if isinstance(target, ast.Attribute): 

409 return target.attr 

410 return None 

411 

412 

413def _float_money_sites(tree: ast.Module) -> Iterator[tuple[str, int]]: 

414 for node in ast.walk(tree): 

415 if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda): 

416 yield from _function_money_sites(node) 

417 elif isinstance(node, ast.AnnAssign): 

418 name = _target_name(node.target) 

419 if ( 

420 name is not None 

421 and _is_money_name(name) 

422 and (_mentions_float(node.annotation) or _is_float_value(node.value)) 

423 ): 

424 yield name, node.lineno 

425 elif isinstance(node, ast.Assign) and _is_float_value(node.value): 

426 yield from _assign_money_sites(node) 

427 

428 

429def _function_money_sites( 

430 node: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda, 

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

432 """Money parameters typed or defaulted as a float, then a money function returning one.""" 

433 args = node.args 

434 positional = [*args.posonlyargs, *args.args] 

435 defaults: list[ast.expr | None] = [None] * (len(positional) - len(args.defaults)) 

436 defaults.extend(args.defaults) 

437 pairs = [ 

438 *zip(positional, defaults, strict=True), 

439 *zip(args.kwonlyargs, args.kw_defaults, strict=True), 

440 ] 

441 for arg, default in pairs: 

442 if _is_money_name(arg.arg) and ( 

443 _mentions_float(arg.annotation) or _is_float_value(default) 

444 ): 

445 yield arg.arg, arg.lineno 

446 if ( 446 ↛ 451line 446 didn't jump to line 451 because the condition on line 446 was never true

447 isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) 

448 and _is_money_name(node.name) 

449 and _mentions_float(node.returns) 

450 ): 

451 yield node.name, node.lineno 

452 

453 

454def _assign_money_sites(node: ast.Assign) -> Iterator[tuple[str, int]]: 

455 """The money targets of an assignment whose value is a float.""" 

456 for target in node.targets: 

457 name = _target_name(target) 

458 if name is not None and _is_money_name(name): 

459 yield name, node.lineno 

460 

461 

462def _float_money(path: str, tree: ast.Module, severity: FindingSeverity) -> list[Issue]: 

463 seen: set[tuple[str, int]] = set() 

464 issues: list[Issue] = [] 

465 for name, line in sorted(_float_money_sites(tree), key=lambda site: (site[1], site[0])): 

466 if (name, line) in seen: 466 ↛ 467line 466 didn't jump to line 467 because the condition on line 466 was never true

467 continue 

468 seen.add((name, line)) 

469 issues.append( 

470 _issue( 

471 "constraints.float-money", 

472 f"{name} holds money as a float, which cannot represent most decimal amounts " 

473 "exactly.", 

474 path, 

475 line, 

476 severity, 

477 "Use integer minor units (cents) or decimal.Decimal for money.", 

478 ) 

479 ) 

480 return issues 

481 

482 

483# no-stubs ------------------------------------------------------------------------------------- 

484 

485 

486def _decorator_names(function: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]: 

487 names: set[str] = set() 

488 for decorator in function.decorator_list: 

489 target = decorator.func if isinstance(decorator, ast.Call) else decorator 

490 if isinstance(target, ast.Name): 490 ↛ 492line 490 didn't jump to line 492 because the condition on line 490 was always true

491 names.add(target.id) 

492 elif isinstance(target, ast.Attribute): 

493 names.add(target.attr) 

494 return names 

495 

496 

497def _is_interface_class(node: ast.ClassDef) -> bool: 

498 """Protocols and abstract base classes declare methods without implementing them.""" 

499 for base in node.bases: 

500 target = base.value if isinstance(base, ast.Subscript) else base 

501 name = target.id if isinstance(target, ast.Name) else None 

502 if isinstance(target, ast.Attribute): 502 ↛ 503line 502 didn't jump to line 503 because the condition on line 502 was never true

503 name = target.attr 

504 if name in {"Protocol", "ABC"}: 504 ↛ 499line 504 didn't jump to line 499 because the condition on line 504 was always true

505 return True 

506 return any( 

507 keyword.arg == "metaclass" and _dotted(keyword.value) in {"ABCMeta", "abc.ABCMeta"} 

508 for keyword in node.keywords 

509 ) 

510 

511 

512def _stubs(path: str, tree: ast.Module, severity: FindingSeverity) -> list[Issue]: 

513 issues: list[Issue] = [] 

514 

515 def visit(node: ast.AST, prefix: str, in_interface: bool) -> None: 

516 for child in ast.iter_child_nodes(node): 

517 if isinstance(child, ast.ClassDef): 

518 visit(child, f"{prefix}{child.name}.", _is_interface_class(child)) 

519 elif isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef): 

520 exempt = in_interface or bool( 

521 _decorator_names(child) & {"abstractmethod", "overload"} 

522 ) 

523 if not exempt and is_stub_body(child.body): 

524 issues.append( 

525 _issue( 

526 "constraints.stub", 

527 f"{prefix}{child.name} is a stub (pass, ..., a docstring or raise " 

528 "NotImplementedError); the task forbids placeholders.", 

529 path, 

530 child.lineno, 

531 severity, 

532 "Implement the function or remove it.", 

533 ) 

534 ) 

535 visit(child, f"{prefix}{child.name}.", False) 

536 else: 

537 visit(child, prefix, in_interface) 

538 

539 visit(tree, "", False) 

540 return issues