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
« 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.
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)."""
10from __future__ import annotations
12import ast
13import re
14import sys
15from collections.abc import Iterator, Mapping, Sequence
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
21CONSTRAINT_CHECKS: tuple[str, ...] = (
22 "stdlib-only",
23 "no-clock-random",
24 "annotated-public-api",
25 "no-float-money",
26 "no-stubs",
27)
29_CATEGORY = "constraints"
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)
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)
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)
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
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)
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 )
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
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 )
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
181# stdlib-only ----------------------------------------------------------------------------------
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)
215# no-clock-random ------------------------------------------------------------------------------
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
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
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))
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
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)
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] = []
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)
287 visit(tree, "")
288 return issues
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 ]
317# annotated-public-api -------------------------------------------------------------------------
320def _is_public(name: str) -> bool:
321 return name == "__init__" or not name.startswith("_")
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
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
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
374# no-float-money -------------------------------------------------------------------------------
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)
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))
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 )
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
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)
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
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
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
483# no-stubs -------------------------------------------------------------------------------------
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
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 )
512def _stubs(path: str, tree: ast.Module, severity: FindingSeverity) -> list[Issue]:
513 issues: list[Issue] = []
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)
539 visit(tree, "", False)
540 return issues