Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Accept existing covering proofs in the completion guard

rcourtmancfd1477852ac
diff --git a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md
index 45ee2cf79b..1833795b7e 100644
--- a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md
+++ b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md
@@ -606,7 +606,8 @@ must include:
1. the matching subsystem contract update
2. any dependent subsystem contract whose `Canonical Files`, `Shared Boundaries`, or `Extension Points` explicitly reference a touched runtime path
-3. at least one matching verification artifact update
+3. a matching verification artifact: a registered proof that already exercises
+ each touched runtime file, or a staged update to one
A staged contract file only counts when its diff changes a substantive contract
section. Update the owning statement of current behavior, responsibility, shared
@@ -643,6 +644,18 @@ test elsewhere in the same subsystem is never proof on its own: the registry
audit keeps `allow_same_subsystem_tests` false, because it would accept any
test the subsystem owns rather than the ones a path policy names.
+A registered proof counts without being edited when it already exercises the
+touched runtime file in the tree being judged (the index before a commit, the
+commit itself in CI): a Go test compiled with or importing the file's package,
+a TypeScript or JavaScript test importing the module, a Python test importing
+it, or, for docs, workflows, scripts and data files, a test naming the file's
+path. Reading a code file's source as text (`readFileSync`, Vite `?raw`) is
+not coverage, and a type-only import does not run the module. CI's test jobs
+run the proof, so an existing covering test is the verification. Only a change
+no registered proof exercises needs a staged proof, so do not add a source-text
+assertion to a proof file to satisfy the guard; make a proof import and test
+the file instead. `subsystem_lookup.py --pretty` names the covering proofs.
+
For changes to a declared contract, cross-subsystem dependencies are not
advisory. If a touched runtime path is named in another subsystem contract's
`Canonical Files`, `Shared Boundaries`, or `Extension Points`, include the
diff --git a/scripts/release_control/canonical_completion_guard.py b/scripts/release_control/canonical_completion_guard.py
index 71b6eaeade..7b4d207e77 100644
--- a/scripts/release_control/canonical_completion_guard.py
+++ b/scripts/release_control/canonical_completion_guard.py
@@ -2,8 +2,9 @@
"""Canonical subsystem completion guard.
Blocks commits when staged runtime changes touch a canonical subsystem but the
-matching subsystem contract file and required verification artifact are not
-staged in the same commit.
+matching subsystem contract file is not staged in the same commit, or when no
+registered proof verifies the change: a proof counts when it is staged or when
+it already exercises each touched runtime file (see proof_coverage.py).
"""
from __future__ import annotations
@@ -20,6 +21,7 @@ from typing import Dict, List, Sequence, Set
import browser_verification_guard
from control_plane import DEFAULT_CONTROL_PLANE
+import proof_coverage
from repo_file_io import git_env, load_repo_json, merged_in_paths
from subsystem_contracts import load_contract_index, referenced_contracts_for_path
@@ -484,6 +486,81 @@ def staged_verification_files_for_requirement(rule: dict, requirement: dict, sta
return sorted(set(matches))
+def candidate_proof_files(requirement: dict, *, revision: str | None) -> List[str]:
+ """Registered proofs for a requirement as they exist in the evaluated tree."""
+ candidates = set(requirement.get("exact_files", []))
+ test_prefixes = list(requirement.get("test_prefixes", []))
+ if test_prefixes:
+ candidates.update(
+ path
+ for path in proof_coverage.git_tracked_paths(revision, test_prefixes, repo_root=REPO_ROOT)
+ if is_test_or_fixture(path)
+ )
+ return sorted(candidates)
+
+
+def uncovered_runtime_files_for_requirement(
+ requirement: dict,
+ read: proof_coverage.TextReader,
+ *,
+ revision: str | None,
+) -> List[str]:
+ """Touched runtime files that no existing registered proof exercises.
+
+ A registered proof that already imports (or compiles with) the touched file
+ and runs in CI verifies the change without being edited, so the guard no
+ longer asks for a staged diff to it. Requiring that diff is what turned
+ proof files into piles of source-text pins.
+ """
+ if requirement.get("path_policy_gap"):
+ return list(requirement.get("touched_runtime_files", []))
+ candidates = candidate_proof_files(requirement, revision=revision)
+ return [
+ path
+ for path in requirement.get("touched_runtime_files", [])
+ if not proof_coverage.covering_proof_files(path, candidates, read)
+ ]
+
+
+def missing_verification_requirements(
+ impacted: Dict[str, dict],
+ staged_files: Sequence[str],
+ *,
+ revision: str | None = None,
+ read: proof_coverage.TextReader | None = None,
+) -> Dict[str, dict]:
+ """Requirements met neither by a staged proof nor by an existing covering proof.
+
+ `revision` selects the tree the proofs are read from: the index when None
+ (a commit being made), the evaluated commit otherwise (CI and pre-push).
+ """
+ owned_reader = proof_coverage.GitTextReader(revision, repo_root=REPO_ROOT) if read is None else None
+ reader = read or owned_reader
+ missing_verification: Dict[str, dict] = {}
+ try:
+ for subsystem_id, data in impacted.items():
+ missing_requirements: List[dict] = []
+ for requirement in data.get("verification_requirements", []):
+ if staged_verification_files_for_requirement(data, requirement, staged_files):
+ continue
+ uncovered = uncovered_runtime_files_for_requirement(
+ requirement, reader, revision=revision
+ )
+ if uncovered:
+ missing_requirements.append(
+ {**requirement, "uncovered_runtime_files": uncovered}
+ )
+ if missing_requirements:
+ missing_verification[subsystem_id] = {
+ **data,
+ "missing_requirements": missing_requirements,
+ }
+ finally:
+ if owned_reader is not None:
+ owned_reader.close()
+ return missing_verification
+
+
def git_blob_text(spec: str) -> str:
result = subprocess.run(
["git", "show", spec],
@@ -657,6 +734,14 @@ def format_missing_requirements(
exact_files = sorted(requirement.get("exact_files", []))
test_prefixes = sorted(requirement.get("test_prefixes", []))
allow_same_subsystem_tests = bool(requirement.get("allow_same_subsystem_tests", False))
+ uncovered = sorted(requirement.get("uncovered_runtime_files", []))
+ if uncovered:
+ lines.append(" no acceptable proof below already exercises:")
+ for path in uncovered:
+ lines.append(f" {path}")
+ lines.append(
+ " make one of them import and test each file (Go: compile with or import its package), or stage a change to one"
+ )
if exact_files:
lines.append(" acceptable exact proof files include:")
for path in exact_files:
@@ -679,7 +764,8 @@ def format_missing_requirements(
"A staged contract file only counts if its staged diff changes a substantive contract section,",
"not just `Contract Metadata` or cosmetic noise.",
"Each touched runtime path must also satisfy the first matching",
- "verification policy from that subsystem's registry entry.",
+ "verification policy from that subsystem's registry entry: an acceptable",
+ "proof that already exercises the path counts unchanged; otherwise stage one.",
]
)
return "\n".join(lines)
@@ -721,18 +807,11 @@ def check_staged_contracts(
if contract_path in staged_set
if not staged_contract_has_substantive_change(contract_path, diff_base, revision)
}
- missing_verification: Dict[str, dict] = {}
- for subsystem_id, data in impacted.items():
- missing_requirements = [
- requirement
- for requirement in data.get("verification_requirements", [])
- if not staged_verification_files_for_requirement(data, requirement, staged_files)
- ]
- if missing_requirements:
- missing_verification[subsystem_id] = {
- **data,
- "missing_requirements": missing_requirements,
- }
+ missing_verification = missing_verification_requirements(
+ impacted,
+ staged_files,
+ revision=governance_revision,
+ )
if not missing_contracts and not insufficient_contract_updates and not missing_verification:
return 0
diff --git a/scripts/release_control/canonical_completion_guard_test.py b/scripts/release_control/canonical_completion_guard_test.py
index 2c90961cea..5070688688 100644
--- a/scripts/release_control/canonical_completion_guard_test.py
+++ b/scripts/release_control/canonical_completion_guard_test.py
@@ -3,6 +3,7 @@ import canonical_completion_guard
import json
import os
import subprocess
+import sys
import tempfile
import unittest
from contextlib import redirect_stderr
@@ -31,6 +32,7 @@ from canonical_completion_guard import (
stdin_files,
subsystem_matches_path,
)
+from proof_coverage import GitTextReader, proof_covers_runtime_file
from repo_file_io import canonical_workspace_repos_root, strip_local_git_env
WORKSPACE_REPOS_ROOT = canonical_workspace_repos_root(REPO_ROOT)
@@ -3136,10 +3138,29 @@ None yet.
patch("canonical_completion_guard.load_subsystem_rules", return_value=rules),
# Isolate verification routing from contract-edit checks.
patch("canonical_completion_guard.required_contract_updates", return_value={}),
+ # Route by staged proofs alone: the real proofs already
+ # import their runtime files, which would satisfy both
+ # policies unchanged (see ExistingProofCoverageTest).
+ patch("proof_coverage.covering_proof_files", return_value=[]),
redirect_stderr(io.StringIO()),
):
self.assertEqual(check_staged_contracts(paths), expected)
+ def test_recovery_and_transfer_edits_pass_on_existing_covering_proofs(self):
+ rules = load_subsystem_rules()
+ paths = [
+ "frontend-modern/src/components/Settings/RecoverySettingsPanel.tsx",
+ "frontend-modern/src/components/Settings/BackupTransferDialogs.tsx",
+ "frontend-modern/src/components/Settings/useBackupTransferFlow.ts",
+ ]
+ with (
+ patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}, clear=False),
+ patch("canonical_completion_guard.load_subsystem_rules", return_value=rules),
+ patch("canonical_completion_guard.required_contract_updates", return_value={}),
+ redirect_stderr(io.StringIO()) as stderr,
+ ):
+ self.assertEqual(check_staged_contracts(paths), 0, stderr.getvalue())
+
def test_frontend_primitive_remaining_settings_shells_use_specific_guardrails(self):
rule = next(rule for rule in load_subsystem_rules() if rule["id"] == "frontend-primitives")
runtime_files = [
@@ -4575,5 +4596,378 @@ with open(os.environ["PULSE_TEST_GUARD_LOG"], "a", encoding="utf-8") as log:
)
+class ProofCoverageRelationTest(unittest.TestCase):
+ """A registered proof covers a runtime file when it exercises it, not when
+ it reads the file's source as text."""
+
+ @staticmethod
+ def covers(proof: str, proof_text: str, runtime: str, runtime_text: str = "x\n") -> bool:
+ files = {proof: proof_text, runtime: runtime_text}
+ return proof_covers_runtime_file(proof, runtime, files.get)
+
+ def test_go_proof_in_the_package_directory_covers(self) -> None:
+ self.assertTrue(self.covers("internal/a/b_test.go", "package a_test\n", "internal/a/c.go"))
+
+ def test_go_proof_importing_the_package_covers(self) -> None:
+ proof = 'package api\n\nimport (\n\t"github.com/rcourtman/pulse-go-rewrite/internal/a"\n)\n'
+ self.assertTrue(self.covers("internal/api/x_test.go", proof, "internal/a/c.go"))
+
+ def test_go_proof_elsewhere_without_the_import_does_not_cover(self) -> None:
+ proof = 'package api\n\nimport "github.com/rcourtman/pulse-go-rewrite/internal/ab"\n'
+ self.assertFalse(self.covers("internal/api/x_test.go", proof, "internal/a/c.go"))
+
+ def test_go_non_test_file_does_not_cover(self) -> None:
+ self.assertFalse(self.covers("internal/a/b.go", "package a\n", "internal/a/c.go"))
+
+ def test_ts_relative_and_alias_imports_cover(self) -> None:
+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"
+ relative = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"
+ self.assertTrue(self.covers(relative, "import { Widget } from '../Widget';\n", runtime))
+ alias = "frontend-modern/src/pages/__tests__/Page.test.tsx"
+ self.assertTrue(
+ self.covers(alias, "import {\n Widget,\n other,\n} from '@/components/Foo/Widget';\n", runtime)
+ )
+ self.assertTrue(
+ self.covers(alias, "const mod = await import('@/components/Foo/Widget');\n", runtime)
+ )
+
+ def test_ts_directory_import_resolves_to_index(self) -> None:
+ runtime = "frontend-modern/src/features/foo/index.ts"
+ proof = "frontend-modern/src/features/__tests__/foo.test.ts"
+ self.assertTrue(self.covers(proof, "import { foo } from '../foo';\n", runtime))
+
+ def test_ts_type_only_import_does_not_cover(self) -> None:
+ runtime = "frontend-modern/src/types/widget.ts"
+ proof = "frontend-modern/src/components/__tests__/Widget.test.tsx"
+ self.assertFalse(
+ self.covers(proof, "import type { Widget } from '@/types/widget';\n", runtime)
+ )
+
+ def test_ts_source_text_pin_does_not_cover(self) -> None:
+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"
+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.guardrails.test.ts"
+ pin = (
+ "import { readFileSync } from 'node:fs';\n"
+ "const source = readFileSync('src/components/Foo/Widget.tsx', 'utf8');\n"
+ "expect(source).toContain('Widget');\n"
+ )
+ self.assertFalse(self.covers(proof, pin, runtime))
+ raw = "import widgetSource from '@/components/Foo/Widget.tsx?raw';\n"
+ self.assertFalse(self.covers(proof, raw, runtime))
+
+ def test_ts_mocked_module_does_not_cover(self) -> None:
+ runtime = "frontend-modern/src/api/charts.ts"
+ proof = "frontend-modern/src/components/__tests__/Chart.test.tsx"
+ text = "vi.mock('@/api/charts', () => ({ ChartsAPI: {} }));\nimport { ChartsAPI } from '@/api/charts';\n"
+ self.assertFalse(self.covers(proof, text, runtime))
+
+ def test_ts_mock_with_import_argument_does_not_cover(self) -> None:
+ runtime = "frontend-modern/src/api/charts.ts"
+ proof = "frontend-modern/src/components/__tests__/Chart.test.tsx"
+ self.assertFalse(self.covers(proof, "vi.mock(import('@/api/charts'), () => ({}));\n", runtime))
+
+ def test_ts_comments_and_type_queries_do_not_cover(self) -> None:
+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"
+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"
+ for text in (
+ "// const mod = await import('../Widget');\n",
+ "/*\nimport { Widget } from '../Widget';\n*/\n",
+ "type WidgetModule = typeof import('../Widget');\n",
+ ):
+ with self.subTest(text=text):
+ self.assertFalse(self.covers(proof, text, runtime))
+
+ def test_ts_imports_in_trailing_comments_strings_or_member_calls_do_not_cover(self) -> None:
+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"
+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"
+ for text in (
+ "const n = 1; // await import('../Widget');\n",
+ "const s = \"import('../Widget')\";\n",
+ "loader.require('../Widget');\n",
+ ):
+ with self.subTest(text=text):
+ self.assertFalse(self.covers(proof, text, runtime))
+
+ def test_ts_specifier_resolves_to_one_file(self) -> None:
+ proof = "frontend-modern/src/features/__tests__/foo.test.ts"
+ files = {
+ proof: "import { foo } from '../foo';\n",
+ "frontend-modern/src/features/foo.ts": "x",
+ "frontend-modern/src/features/foo/index.ts": "x",
+ }
+ self.assertTrue(proof_covers_runtime_file(proof, "frontend-modern/src/features/foo.ts", files.get))
+ self.assertFalse(
+ proof_covers_runtime_file(proof, "frontend-modern/src/features/foo/index.ts", files.get)
+ )
+
+ def test_go_package_path_outside_import_declarations_does_not_cover(self) -> None:
+ proof = (
+ "package api\n\n// see github.com/rcourtman/pulse-go-rewrite/internal/a\n"
+ 'const sample = "github.com/rcourtman/pulse-go-rewrite/internal/a"\n'
+ )
+ self.assertFalse(self.covers("internal/api/x_test.go", proof, "internal/a/c.go"))
+ aliased = 'package api\n\nimport alpha "github.com/rcourtman/pulse-go-rewrite/internal/a"\n'
+ self.assertTrue(self.covers("internal/api/x_test.go", aliased, "internal/a/c.go"))
+
+ def test_go_proof_behind_a_non_platform_build_tag_does_not_cover(self) -> None:
+ for constraint, expected in (
+ ("//go:build ignore", False),
+ ("//go:build integration", False),
+ ("//go:build linux && !arm64", True),
+ ("//go:build go1.21", True),
+ ):
+ with self.subTest(constraint=constraint):
+ proof = f"{constraint}\n\npackage a\n"
+ self.assertEqual(self.covers("internal/a/b_test.go", proof, "internal/a/c.go"), expected)
+
+ def test_python_docstring_and_type_checking_imports_do_not_cover(self) -> None:
+ runtime = "scripts/release_control/widget_policy.py"
+ proof = "scripts/release_control/widget_policy_test.py"
+ docstring = '"""Usage:\nimport widget_policy\n"""\n'
+ type_only = "from typing import TYPE_CHECKING\nif TYPE_CHECKING:\n import widget_policy\n"
+ self.assertFalse(self.covers(proof, docstring, runtime))
+ self.assertFalse(self.covers(proof, type_only, runtime))
+ dynamic = "import importlib\nmod = importlib.import_module('widget_policy')\n"
+ self.assertTrue(self.covers(proof, dynamic, runtime))
+
+ def test_python_stdlib_name_does_not_cover_a_same_named_file(self) -> None:
+ proof = "scripts/tests/test_tool.py"
+ if "json" in getattr(sys, "stdlib_module_names", ()):
+ self.assertFalse(self.covers(proof, "import json\n", "scripts/json.py"))
+ self.assertTrue(self.covers(proof, "import scripts.json\n", "scripts/json.py"))
+
+ def test_python_multiline_and_package_imports(self) -> None:
+ runtime = "scripts/release_control/widget_policy.py"
+ proof = "scripts/release_control/widget_policy_test.py"
+ self.assertTrue(self.covers(proof, "import os\nimport widget_policy\n\nclass T: pass\n", runtime))
+ self.assertTrue(self.covers(proof, "from release_control import (\n other,\n widget_policy,\n)\n", runtime))
+ self.assertFalse(self.covers(proof, "import os\n# import widget_policy\n", runtime))
+
+ def test_python_proof_importing_the_module_covers(self) -> None:
+ runtime = "scripts/release_control/widget_policy.py"
+ self.assertTrue(
+ self.covers("scripts/tests/test_widget.py", "from widget_policy import check\n", runtime)
+ )
+ self.assertTrue(
+ self.covers("scripts/tests/test_widget.py", "import os, widget_policy\n", runtime)
+ )
+ self.assertFalse(
+ self.covers("scripts/tests/test_widget.py", "import widget_policy_extra\n", runtime)
+ )
+
+ def test_non_code_file_is_covered_by_a_proof_that_names_its_path(self) -> None:
+ proof = "scripts/release_control/ai_docs_policy_test.py"
+ self.assertTrue(self.covers(proof, 'DOC = REPO / "docs/AI.md"\n', "docs/AI.md"))
+ self.assertFalse(self.covers(proof, 'DOC = REPO / "docs/API.md"\n', "docs/AI.md"))
+ mirror = 'DOC = REPO / "frontend-modern/public/docs/AI.md"\n'
+ self.assertFalse(self.covers(proof, mirror, "docs/AI.md"))
+ self.assertFalse(self.covers(proof, 'DOC = "docs/AI.md.bak"\n', "docs/AI.md"))
+
+ def test_missing_files_do_not_cover(self) -> None:
+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"
+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"
+ files = {proof: "import { Widget } from '../Widget';\n"}
+ self.assertFalse(proof_covers_runtime_file(proof, runtime, files.get))
+ self.assertFalse(proof_covers_runtime_file(proof, proof, {proof: "x"}.get))
+
+
+class ExistingProofCoverageTest(unittest.TestCase):
+ """A commit that changes an owned runtime file passes verification when a
+ registered proof already exercises that file, without editing the proof.
+ Requiring a staged proof diff is what filled proof files with source-text
+ pins. A change no registered proof exercises still needs a staged proof."""
+
+ SUBSYSTEMS = "docs/release-control/v6/internal/subsystems"
+ REGISTRY = f"{SUBSYSTEMS}/registry.json"
+ CONTRACT = f"{SUBSYSTEMS}/alpha.md"
+ GO_RUNTIME = "app/alpha/widget.go"
+ GO_PROOF = "app/alpha/widget_test.go"
+ GO_UNCOVERED = "app/alpha/sub/gadget.go"
+ TS_RUNTIME = "frontend-modern/src/alpha/widget.ts"
+ TS_PROOF = "frontend-modern/src/alpha/__tests__/widget.test.ts"
+ TS_PINNED = "frontend-modern/src/alpha/pinned.ts"
+ TS_PIN_PROOF = "frontend-modern/src/alpha/__tests__/alpha.guardrails.test.ts"
+
+ def setUp(self) -> None:
+ temp_dir = tempfile.TemporaryDirectory()
+ self.addCleanup(temp_dir.cleanup)
+ self.repo = Path(temp_dir.name)
+ for target in (
+ patch.dict(os.environ, strip_local_git_env(os.environ.copy()), clear=True),
+ patch("canonical_completion_guard.REPO_ROOT", self.repo),
+ patch("canonical_completion_guard.SUBSYSTEM_REGISTRY", self.repo / self.REGISTRY),
+ patch("repo_file_io.REPO_ROOT", self.repo),
+ patch("subsystem_contracts.REPO_ROOT", self.repo),
+ patch("subsystem_contracts.CONTRACTS_DIR", self.repo / self.SUBSYSTEMS),
+ ):
+ target.start()
+ self.addCleanup(target.stop)
+ self.git("init", "-q", "-b", "main")
+ self.git("config", "user.name", "Pulse Test")
+ self.git("config", "user.email", "[email protected]")
+ self.revision = 0
+ self.commit(
+ "base",
+ {
+ self.REGISTRY: self.registry(),
+ self.CONTRACT: self.contract(),
+ self.GO_RUNTIME: "package alpha\n",
+ self.GO_PROOF: "package alpha\n",
+ self.GO_UNCOVERED: "package sub\n",
+ self.TS_RUNTIME: "export const widget = 1;\n",
+ self.TS_PROOF: "import { widget } from '../widget';\n",
+ self.TS_PINNED: "export const pinned = 1;\n",
+ self.TS_PIN_PROOF: (
+ "import { readFileSync } from 'node:fs';\n"
+ "const source = readFileSync('src/alpha/pinned.ts', 'utf8');\n"
+ "expect(source).toContain('pinned');\n"
+ ),
+ },
+ )
+
+ def registry(self) -> str:
+ rule = {
+ "id": "alpha",
+ "contract": self.CONTRACT,
+ "owned_prefixes": ["app/alpha/", "frontend-modern/src/alpha/"],
+ "owned_files": [],
+ "verification": {
+ "allow_same_subsystem_tests": False,
+ "test_prefixes": [],
+ "exact_files": [],
+ "require_explicit_path_policy_coverage": True,
+ "path_policies": [
+ {
+ "id": "alpha-runtime",
+ "label": "alpha runtime proof",
+ "match_prefixes": ["app/alpha/", "frontend-modern/src/alpha/"],
+ "match_files": [],
+ "allow_same_subsystem_tests": False,
+ "test_prefixes": [],
+ "exact_files": [self.GO_PROOF, self.TS_PIN_PROOF, self.TS_PROOF],
+ }
+ ],
+ },
+ }
+ return json.dumps({"subsystems": [rule]}, indent=2) + "\n"
+
+ def contract(self) -> str:
+ self.revision = getattr(self, "revision", 0) + 1
+ return (
+ "# alpha contract\n\n"
+ "## Contract Metadata\n\n"
+ "```json\n"
+ '{"subsystem_id": "alpha"}\n'
+ "```\n\n"
+ "## Current State\n\n"
+ f"Alpha owns the widget (revision {self.revision}).\n"
+ )
+
+ def git(self, *args: str) -> str:
+ return subprocess.run(
+ ["git", *args],
+ cwd=self.repo,
+ check=True,
+ capture_output=True,
+ text=True,
+ ).stdout.strip()
+
+ def write(self, files: dict[str, str]) -> None:
+ for rel, text in files.items():
+ path = self.repo / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+ self.git("add", *files)
+
+ def commit(self, message: str, files: dict[str, str]) -> str:
+ self.write(files)
+ self.git("commit", "-q", "-m", message)
+ return self.git("rev-parse", "HEAD")
+
+ def change(self, runtime: str, text: str) -> str:
+ return self.commit(f"change {runtime}", {runtime: text, self.CONTRACT: self.contract()})
+
+ def run_guard(self, commit: str) -> tuple[int, str]:
+ files = self.git("diff-tree", "--no-commit-id", "--name-only", "-r", commit)
+ stderr = io.StringIO()
+ with (
+ patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}),
+ patch("sys.stdin", io.StringIO(files + "\n")),
+ redirect_stderr(stderr),
+ ):
+ status = main(["--files-from-stdin", "--diff-base", f"{commit}^", "--commit", commit])
+ return status, stderr.getvalue()
+
+ def test_untouched_covering_go_proof_satisfies_verification(self) -> None:
+ commit = self.change(self.GO_RUNTIME, "package alpha\n\nconst Size = 2\n")
+ status, stderr = self.run_guard(commit)
+ self.assertEqual(status, 0, stderr)
+
+ def test_untouched_covering_ts_proof_satisfies_verification(self) -> None:
+ commit = self.change(self.TS_RUNTIME, "export const widget = 2;\n")
+ status, stderr = self.run_guard(commit)
+ self.assertEqual(status, 0, stderr)
+
+ def test_runtime_file_no_proof_exercises_still_blocks(self) -> None:
+ commit = self.change(self.GO_UNCOVERED, "package sub\n\nconst Size = 2\n")
+ status, stderr = self.run_guard(commit)
+ self.assertEqual(status, 1)
+ self.assertIn("- subsystem alpha: missing verification artifact for alpha runtime proof", stderr)
+ self.assertIn(f" no acceptable proof below already exercises:\n {self.GO_UNCOVERED}", stderr)
+
+ def test_source_text_pin_is_not_coverage(self) -> None:
+ commit = self.change(self.TS_PINNED, "export const pinned = 2;\n")
+ status, stderr = self.run_guard(commit)
+ self.assertEqual(status, 1)
+ self.assertIn(f" {self.TS_PINNED}", stderr)
+
+ def test_partially_covered_change_blocks_on_the_uncovered_file(self) -> None:
+ self.write({self.GO_UNCOVERED: "package sub\n\nconst Size = 3\n"})
+ commit = self.change(self.GO_RUNTIME, "package alpha\n\nconst Size = 3\n")
+ status, stderr = self.run_guard(commit)
+ self.assertEqual(status, 1)
+ uncovered = stderr.split("already exercises:\n", 1)[1].split("\n make one", 1)[0]
+ self.assertEqual(uncovered, f" {self.GO_UNCOVERED}")
+
+ def test_staged_proof_still_satisfies_an_uncovered_change(self) -> None:
+ self.write({self.GO_PROOF: "package alpha\n\nfunc TestSize() {}\n"})
+ commit = self.change(self.GO_UNCOVERED, "package sub\n\nconst Size = 4\n")
+ status, stderr = self.run_guard(commit)
+ self.assertEqual(status, 0, stderr)
+
+ def test_coverage_is_read_from_the_evaluated_commit(self) -> None:
+ covered = self.change(self.TS_RUNTIME, "export const widget = 5;\n")
+ self.commit("proof stops importing the widget", {self.TS_PROOF: "export {};\n"})
+ uncovered = self.change(self.TS_RUNTIME, "export const widget = 6;\n")
+
+ status, stderr = self.run_guard(covered)
+ self.assertEqual(status, 0, stderr)
+ status, stderr = self.run_guard(uncovered)
+ self.assertEqual(status, 1)
+ self.assertIn(f" {self.TS_RUNTIME}", stderr)
+
+ def test_reader_skips_directories_without_losing_its_place(self) -> None:
+ commit = self.git("rev-parse", "HEAD")
+ with GitTextReader(commit, repo_root=self.repo) as read:
+ self.assertIsNone(read("frontend-modern/src/alpha"))
+ self.assertIsNone(read("frontend-modern/src/alpha/missing.ts"))
+ self.assertEqual(read(self.TS_RUNTIME), "export const widget = 1;\n")
+ with GitTextReader(None, repo_root=self.repo) as read:
+ self.assertIsNone(read("app/alpha"))
+ self.assertEqual(read(self.GO_PROOF), "package alpha\n")
+
+ def test_pre_commit_mode_reads_coverage_from_the_index(self) -> None:
+ self.write({self.GO_RUNTIME: "package alpha\n\nconst Size = 7\n", self.CONTRACT: self.contract()})
+ stderr = io.StringIO()
+ with patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}), redirect_stderr(stderr):
+ self.assertEqual(main([]), 0, stderr.getvalue())
+
+ self.write({self.GO_UNCOVERED: "package sub\n\nconst Size = 7\n"})
+ stderr = io.StringIO()
+ with patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}), redirect_stderr(stderr):
+ self.assertEqual(main([]), 1)
+ self.assertIn(f" {self.GO_UNCOVERED}", stderr.getvalue())
+
+
if __name__ == "__main__":
unittest.main()
diff --git a/scripts/release_control/proof_coverage.py b/scripts/release_control/proof_coverage.py
new file mode 100644
index 0000000000..4a6e2d7fab
--- /dev/null
+++ b/scripts/release_control/proof_coverage.py
@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""Decide whether an existing proof test covers a touched runtime file.
+
+The canonical completion guard used to accept a runtime change only when one
+of the registered proof files was staged with a diff. The cheapest diff was
+one more `expect(source).toContain(...)` pin, so registered proof files grew
+thousands of source-text pins that proved nothing about behaviour. A proof
+that already exercises the touched file and runs in CI is real verification
+whether or not this commit edits it.
+
+Coverage is a static relation between the proof file and the runtime file,
+read from the tree under evaluation (the index before a commit exists, the
+commit itself in CI):
+
+- Go: the proof is a `_test.go` file compiled with the runtime file's package
+ (same directory) or importing that package in its import declarations, and
+ no build tag beyond a platform keeps it out of the default test run.
+- TypeScript/JavaScript: the proof imports the runtime module (relative or
+ `@/` specifier). Reading the module's source as text does not count, neither
+ through `readFileSync` nor through a Vite `?raw` import; a type-only import
+ does not run the module, and a mocked module runs the mock.
+- Python: the proof imports the runtime module by name at runtime (parsed,
+ so docstrings and `if TYPE_CHECKING:` imports do not count).
+- Anything else (docs, workflows, shell scripts, JSON): the proof names the
+ runtime file's repository path, because reading or executing that file is
+ how such files are tested.
+
+CI's required test jobs run every proof file, so "exists and covers" plus a
+green CI run is the verification the guard asks for.
+"""
+
+from __future__ import annotations
+
+import ast
+import posixpath
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Dict, Iterable, List, Optional, Sequence
+
+from repo_file_io import git_env
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+GO_MODULE = "github.com/rcourtman/pulse-go-rewrite"
+FRONTEND_SRC = "frontend-modern/src/"
+
+JS_SUFFIXES: tuple[str, ...] = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs")
+JS_RESOLVE_SUFFIXES: tuple[str, ...] = (
+ "",
+ ".ts",
+ ".tsx",
+ ".js",
+ ".jsx",
+ ".mjs",
+ "/index.ts",
+ "/index.tsx",
+ "/index.js",
+)
+
+# `import x from 'm'`, `import {a,\n b} from "m"`, `export * from 'm'`; the
+# `type` group lets type-only imports be skipped because they never run `m`.
+JS_STATIC_IMPORT_RE = re.compile(
+ r"""(?:^|[;\n])\s*(?:import|export)\s+(type\s+)?[^;'"]*?\bfrom\s*['"]([^'"\n]+)['"]""",
+)
+JS_SIDE_EFFECT_IMPORT_RE = re.compile(r"""(?:^|[;\n])\s*import\s*['"]([^'"\n]+)['"]""")
+# A member call (`obj.require(...)`) or a quoted word is not a module load.
+JS_DYNAMIC_IMPORT_RE = re.compile(
+ r"""(?<![\w$.'"`])(?:import|require)\s*\(\s*['"]([^'"\n]+)['"]\s*\)"""
+)
+JS_MOCK_RE = re.compile(
+ r"""\b(?:vi|jest)\.(?:mock|doMock)\s*\(\s*(?:import\s*\(\s*)?['"]([^'"\n]+)['"]"""
+)
+JS_BLOCK_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL)
+# `//` after code or at line start; `http://` and `'//cdn'` keep their text.
+JS_LINE_COMMENT_RE = re.compile(r"(^|[\s;{},()])//[^\n]*", re.MULTILINE)
+JS_TYPE_QUERY_RE = re.compile(r"\btypeof\s+import\s*\(")
+GO_BLOCK_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL)
+GO_IMPORT_BLOCK_RE = re.compile(r"^import\s*\((.*?)\)", re.MULTILINE | re.DOTALL)
+GO_IMPORT_LINE_RE = re.compile(r'^import\s+(?:[\w.]+\s+)?"([^"]+)"', re.MULTILINE)
+GO_IMPORT_SPEC_RE = re.compile(r'^\s*(?:[\w.]+\s+)?"([^"]+)"', re.MULTILINE)
+GO_BUILD_RE = re.compile(r"^//go:build\s+(.+)$", re.MULTILINE)
+# Constraints CI's Go jobs satisfy or that only pick a platform; any other tag
+# (`ignore`, `integration`, ...) can keep a test out of the required run.
+GO_PLATFORM_TAGS = frozenset(
+ {
+ "386", "amd64", "arm", "arm64", "cgo", "darwin", "freebsd", "linux",
+ "netbsd", "openbsd", "unix", "windows",
+ }
+)
+PATH_CHAR = r"[\w./-]"
+
+
+TextReader = Callable[[str], Optional[str]]
+
+
+class GitTextReader:
+ """Read files from a commit, or from the index when `revision` is None.
+
+ One `git cat-file --batch` process serves every read, so checking a
+ requirement's proofs costs one round trip per file rather than a process.
+ """
+
+ def __init__(self, revision: str | None, *, repo_root: Path = REPO_ROOT) -> None:
+ self.prefix = f"{revision}:" if revision is not None else ":0:"
+ self.repo_root = repo_root
+ self.process: subprocess.Popen | None = None
+ self.cache: Dict[str, Optional[str]] = {}
+
+ def __call__(self, path: str) -> Optional[str]:
+ if path in self.cache:
+ return self.cache[path]
+ if self.process is None:
+ self.process = subprocess.Popen(
+ ["git", "cat-file", "--batch"],
+ cwd=self.repo_root,
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ env=git_env(self.repo_root),
+ )
+ assert self.process.stdin is not None and self.process.stdout is not None
+ self.process.stdin.write(f"{self.prefix}{path}\n".encode())
+ self.process.stdin.flush()
+ header = self.process.stdout.readline().decode("utf-8", errors="replace").split()
+ text: Optional[str] = None
+ if len(header) == 3:
+ # Every found object is followed by its body; a tree (a directory
+ # a specifier names) must be drained too or the stream desyncs.
+ body = self.process.stdout.read(int(header[2]))
+ self.process.stdout.read(1)
+ if header[1] == "blob":
+ text = body.decode("utf-8", errors="replace")
+ self.cache[path] = text
+ return text
+
+ def close(self) -> None:
+ if self.process is None:
+ return
+ assert self.process.stdin is not None and self.process.stdout is not None
+ self.process.stdin.close()
+ self.process.wait()
+ self.process.stdout.close()
+ self.process = None
+
+ def __enter__(self) -> "GitTextReader":
+ return self
+
+ def __exit__(self, *_exc: object) -> None:
+ self.close()
+
+
+def working_tree_reader(repo_root: Path = REPO_ROOT) -> TextReader:
+ """Read files as they are on disk, for lookups made while editing."""
+
+ def read(path: str) -> Optional[str]:
+ try:
+ return (repo_root / path).read_text(encoding="utf-8", errors="replace")
+ except (FileNotFoundError, IsADirectoryError, NotADirectoryError):
+ return None
+
+ return read
+
+
+def git_tracked_paths(revision: str | None, prefixes: Sequence[str], *, repo_root: Path = REPO_ROOT) -> List[str]:
+ """Paths under any of `prefixes` in a commit, or in the index."""
+ if not prefixes:
+ return []
+ if revision is None:
+ command = ["git", "ls-files", "-z", "--", *prefixes]
+ else:
+ command = ["git", "ls-tree", "-r", "-z", "--name-only", revision, "--", *prefixes]
+ result = subprocess.run(
+ command,
+ cwd=repo_root,
+ check=True,
+ capture_output=True,
+ env=git_env(repo_root),
+ )
+ return sorted(path for path in result.stdout.decode().split("\0") if path)
+
+
+def is_js_path(path: str) -> bool:
+ return path.endswith(JS_SUFFIXES) and not path.endswith(".d.ts")
+
+
+def js_code(text: str) -> str:
+ """Drop comments and `typeof import(...)` type queries, which never run a module.
+
+ Stripping is conservative: a `/*` inside a string can only hide imports,
+ never invent one.
+ """
+ text = JS_BLOCK_COMMENT_RE.sub("", text)
+ text = JS_LINE_COMMENT_RE.sub(r"\1", text)
+ return JS_TYPE_QUERY_RE.sub("typeof ", text)
+
+
+def js_import_specifiers(text: str) -> List[str]:
+ specifiers = [spec for type_only, spec in JS_STATIC_IMPORT_RE.findall(text) if not type_only]
+ specifiers.extend(JS_SIDE_EFFECT_IMPORT_RE.findall(text))
+ specifiers.extend(JS_DYNAMIC_IMPORT_RE.findall(text))
+ return specifiers
+
+
+def js_specifier_targets(importer: str, specifier: str) -> List[str]:
+ """Candidate repository paths a module specifier can resolve to, in order.
+
+ A query suffix (`?raw`, `?url`, `?inline`) loads the file as text or an
+ asset without running it, which is a source pin, not coverage.
+ """
+ if "?" in specifier:
+ return []
+ if specifier.startswith("@/"):
+ base = FRONTEND_SRC + specifier[2:]
+ elif specifier.startswith("."):
+ base = posixpath.normpath(posixpath.join(posixpath.dirname(importer), specifier))
+ else:
+ return []
+ return [base + suffix for suffix in JS_RESOLVE_SUFFIXES]
+
+
+def resolve_js_specifier(importer: str, specifier: str, read: TextReader) -> Optional[str]:
+ """The one file a specifier loads: the first candidate that exists."""
+ return next(
+ (path for path in js_specifier_targets(importer, specifier) if read(path) is not None),
+ None,
+ )
+
+
+def go_package_dir(path: str) -> str:
+ return posixpath.dirname(path)
+
+
+def go_imported_packages(text: str) -> set[str]:
+ """Import paths from the file's import declarations, not any quoted string."""
+ code = GO_BLOCK_COMMENT_RE.sub("", text)
+ packages = set(GO_IMPORT_LINE_RE.findall(code))
+ for block in GO_IMPORT_BLOCK_RE.findall(code):
+ packages.update(GO_IMPORT_SPEC_RE.findall(block))
+ return packages
+
+
+def go_test_runs_by_default(text: str) -> bool:
+ """False when a build constraint needs a tag CI's Go test jobs do not set."""
+ header = text.split("\npackage ", 1)[0]
+ for expression in GO_BUILD_RE.findall(header):
+ for tag in re.findall(r"[\w.]+", expression):
+ if tag not in GO_PLATFORM_TAGS and not re.fullmatch(r"go1\.\d+", tag):
+ return False
+ return True
+
+
+def python_module_names(path: str) -> List[str]:
+ """Names a Python test could import the runtime module by.
+
+ A bare name that is also a standard-library module (`json`, `types`)
+ would name the stdlib module, not this file.
+ """
+ stem = posixpath.splitext(path)[0]
+ parts = stem.split("/")
+ if parts[-1] == "__init__":
+ parts = parts[:-1]
+ stdlib = set(getattr(sys, "stdlib_module_names", ()))
+ names = [".".join(parts[index:]) for index in range(len(parts))]
+ return [name for name in names if "." in name or name not in stdlib]
+
+
+def _is_type_checking(test: ast.expr) -> bool:
+ return (isinstance(test, ast.Name) and test.id == "TYPE_CHECKING") or (
+ isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"
+ )
+
+
+def python_imported_modules(text: str) -> set[str]:
+ """Modules a Python file imports at runtime, including `from pkg import module`.
+
+ Docstrings, comments and `if TYPE_CHECKING:` imports do not count.
+ """
+ try:
+ tree = ast.parse(text)
+ except SyntaxError:
+ return set()
+ type_only: set[int] = set()
+ for node in ast.walk(tree):
+ if isinstance(node, ast.If) and _is_type_checking(node.test):
+ for child in node.body:
+ type_only.update(id(inner) for inner in ast.walk(child))
+ modules: set[str] = set()
+ for node in ast.walk(tree):
+ if id(node) in type_only:
+ continue
+ if isinstance(node, ast.Import):
+ modules.update(alias.name for alias in node.names)
+ elif isinstance(node, ast.ImportFrom) and node.module and not node.level:
+ modules.add(node.module)
+ modules.update(f"{node.module}.{alias.name}" for alias in node.names)
+ elif (
+ isinstance(node, ast.Call)
+ and isinstance(node.func, (ast.Attribute, ast.Name))
+ and getattr(node.func, "attr", getattr(node.func, "id", "")) == "import_module"
+ and node.args
+ and isinstance(node.args[0], ast.Constant)
+ and isinstance(node.args[0].value, str)
+ ):
+ modules.add(node.args[0].value)
+ return modules
+
+
+def names_repo_path(text: str, path: str) -> bool:
+ """The text names `path` itself, not a longer path that ends with it."""
+ return re.search(rf"(?<!{PATH_CHAR}){re.escape(path)}(?!{PATH_CHAR})", text) is not None
+
+
+def proof_covers_runtime_file(proof: str, runtime: str, read: TextReader) -> bool:
+ """Return True when the proof file, as it exists, exercises `runtime`."""
+ if proof == runtime:
+ return False
+ text = read(proof)
+ if text is None or read(runtime) is None:
+ return False
+
+ if runtime.endswith(".go"):
+ if not proof.endswith("_test.go") or not go_test_runs_by_default(text):
+ return False
+ if go_package_dir(proof) == go_package_dir(runtime):
+ return True
+ return f"{GO_MODULE}/{go_package_dir(runtime)}" in go_imported_packages(text)
+
+ if is_js_path(runtime):
+ if not is_js_path(proof):
+ return False
+ code = js_code(text)
+ # A mocked module is replaced, so importing it runs the mock instead.
+ if any(resolve_js_specifier(proof, spec, read) == runtime for spec in JS_MOCK_RE.findall(code)):
+ return False
+ return any(
+ resolve_js_specifier(proof, specifier, read) == runtime
+ for specifier in js_import_specifiers(JS_MOCK_RE.sub("", code))
+ )
+
+ if runtime.endswith(".py"):
+ if not proof.endswith(".py"):
+ return False
+ imported = python_imported_modules(text)
+ return any(name in imported for name in python_module_names(runtime))
+
+ return names_repo_path(text, runtime)
+
+
+def covering_proof_files(
+ runtime: str,
+ candidate_proofs: Iterable[str],
+ read: TextReader,
+) -> List[str]:
+ return sorted(
+ {proof for proof in candidate_proofs if proof_covers_runtime_file(proof, runtime, read)}
+ )
diff --git a/scripts/release_control/staged_commit_shape_guard.py b/scripts/release_control/staged_commit_shape_guard.py
index 5035e19e41..549b713659 100644
--- a/scripts/release_control/staged_commit_shape_guard.py
+++ b/scripts/release_control/staged_commit_shape_guard.py
@@ -15,9 +15,9 @@ from canonical_completion_guard import (
git_staged_files as canonical_git_staged_files,
infer_impacted_subsystems,
load_subsystem_rules,
+ missing_verification_requirements,
required_contract_updates,
staged_contract_has_substantive_change,
- staged_verification_files_for_requirement,
)
from repo_file_io import load_repo_json
from release_promotion_policy_support import (
@@ -252,18 +252,7 @@ def canonical_commit_shape_errors(staged_files: Sequence[str]) -> list[str]:
if contract_path in staged_set
if not staged_contract_has_substantive_change(contract_path)
}
- missing_verification: dict[str, dict] = {}
- for subsystem_id, data in impacted.items():
- missing_requirements = [
- requirement
- for requirement in data.get("verification_requirements", [])
- if not staged_verification_files_for_requirement(data, requirement, staged_files)
- ]
- if missing_requirements:
- missing_verification[subsystem_id] = {
- **data,
- "missing_requirements": missing_requirements,
- }
+ missing_verification = missing_verification_requirements(impacted, staged_files)
if not missing_contracts and not insufficient_contract_updates and not missing_verification:
return []
diff --git a/scripts/release_control/subsystem_lookup.py b/scripts/release_control/subsystem_lookup.py
index 272de17a81..28ae4358ae 100644
--- a/scripts/release_control/subsystem_lookup.py
+++ b/scripts/release_control/subsystem_lookup.py
@@ -10,9 +10,11 @@ from pathlib import Path
import sys
from typing import Any
+import proof_coverage
from canonical_completion_guard import (
REPO_ROOT,
build_verification_requirements,
+ candidate_proof_files,
infer_impacted_subsystems,
is_ignored_runtime_file,
is_test_or_fixture,
@@ -284,6 +286,7 @@ def lookup_paths(paths: list[str], *, lean: bool = False) -> dict[str, Any]:
contract_updates = required_contract_updates(normalized, impacted, contract_index=contract_index)
path_entries: list[dict[str, Any]] = []
unowned: list[str] = []
+ read_working_tree = proof_coverage.working_tree_reader(REPO_ROOT)
for path in normalized:
classification = "runtime"
@@ -304,13 +307,25 @@ def lookup_paths(paths: list[str], *, lean: bool = False) -> dict[str, Any]:
if not subsystem_matches_path(rule, path):
continue
requirement = verification_requirement_for_path(rule, path)
+ # The guard accepts an existing proof that already exercises
+ # the file; report it so nobody edits a proof just to pass.
+ covering = (
+ []
+ if requirement.get("path_policy_gap")
+ else proof_coverage.covering_proof_files(
+ path,
+ candidate_proof_files(requirement, revision=None),
+ read_working_tree,
+ )
+ )
matches.append(
{
"subsystem": rule["id"],
"contract": rule["contract"],
"lane_context": lane_context_for_rule(rule, status_report),
"contract_update_required": True,
- "proof_update_required": True,
+ "proof_update_required": not covering,
+ "covering_proof_files": covering,
"ownership_basis": ownership_basis_for_path(rule, path),
"matched_contract_references": reference_matches_by_subsystem.get(
str(rule["id"]),
@@ -349,7 +364,8 @@ def lookup_paths(paths: list[str], *, lean: bool = False) -> dict[str, Any]:
if path in contract["touched_runtime_files"]
],
"contract_update_required": classification == "runtime" and bool(matches),
- "proof_update_required": classification == "runtime" and bool(matches),
+ "proof_update_required": classification == "runtime"
+ and any(match["proof_update_required"] for match in matches),
}
)
@@ -437,6 +453,12 @@ def render_pretty(result: dict[str, Any]) -> str:
f" - {match['subsystem']} -> {match['contract']} "
f"[{requirement['id']}: {requirement['label']}]"
)
+ if match.get("covering_proof_files"):
+ covering = match["covering_proof_files"]
+ more = f" (+{len(covering) - 3} more)" if len(covering) > 3 else ""
+ lines.append(" already proved by: " + ", ".join(covering[:3]) + more)
+ elif match.get("proof_update_required"):
+ lines.append(" proof: no acceptable proof exercises this file yet; stage one")
if lane_context and lane_context.get("lane"):
lane = lane_context["lane"]
gap = lane.get("gap")