From e5a42fa446dc7e5e25e2b7c3b07bb99084ab867c Mon Sep 17 00:00:00 2001 From: Alexander Baranov Date: Mon, 24 Aug 2026 18:48:54 +0300 Subject: [PATCH] test(adopt): bind the compatibility tables to code, and check apply's safety Runbook 11.1 and 11.2 are decision tables, and nothing tied them to branches: the two existing antivirus-legacy tests asserted only that kdb/kdb.yaml was preserved, which stayed true while the surrounding behaviour was wrong. These cases are parametrized over the table rows so prose and code cannot drift apart again without a failure. Writing them found two defects that no existing test could see. splice_managed_block validated the file it patched but never the block being inserted, so a hand-edited plan carrying unbalanced markers would have been written in and only failed on a later run. And the adoption output schemas were validated nowhere, which had let the richer content roots from the previous commit silently stop conforming to AdoptionAssessment. - table-driven coverage of the knowledge and agent-entrypoint rows - path escape, forbidden path, dirty gate, rollback and preserve-tampering cases - schema conformance for assessment, plan, report and the generated contract - widen proposedContentRoots for writePolicy/generatedFrom, and constrain authority to the enum it always should have used - add a synthetic_repo fixture instead of a fourth copy of git init Co-Authored-By: Claude Opus 5 --- src/stewardship/adoption.py | 12 + .../schemas/adoption-assessment.schema.json | 4 +- tests/conftest.py | 24 ++ tests/test_adoption_rules.py | 286 ++++++++++++++++++ 4 files changed, 325 insertions(+), 1 deletion(-) create mode 100644 tests/test_adoption_rules.py diff --git a/src/stewardship/adoption.py b/src/stewardship/adoption.py index 2d54dce..0d551c7 100644 --- a/src/stewardship/adoption.py +++ b/src/stewardship/adoption.py @@ -54,6 +54,18 @@ def splice_managed_block(text: str, block: str) -> str: agent reads it first. Malformed or duplicated markers raise rather than guess at the author's intent. """ + # The block arrives from a plan file, which can be hand-edited: inserting one + # with unbalanced markers would corrupt the boundary this function relies on + # and only fail on some later run. + if block.count(MANAGED_BLOCK_START) != 1 or block.count(MANAGED_BLOCK_END) != 1: + raise AdoptionError( + "ADOPT_MANAGED_BLOCK_MALFORMED", "Replacement block must carry exactly one marker pair" + ) + if block.index(MANAGED_BLOCK_END) < block.index(MANAGED_BLOCK_START): + raise AdoptionError( + "ADOPT_MANAGED_BLOCK_MALFORMED", "Replacement block ends before it starts" + ) + start_count = text.count(MANAGED_BLOCK_START) end_count = text.count(MANAGED_BLOCK_END) if start_count > 1 or end_count > 1: diff --git a/src/stewardship/schemas/adoption-assessment.schema.json b/src/stewardship/schemas/adoption-assessment.schema.json index 1e735eb..c50c45a 100644 --- a/src/stewardship/schemas/adoption-assessment.schema.json +++ b/src/stewardship/schemas/adoption-assessment.schema.json @@ -60,7 +60,9 @@ "id": { "type": "string" }, "path": { "type": "string" }, "role": { "type": "string" }, - "authority": { "type": "string" } + "authority": { "enum": ["source", "generated", "observed", "mirror", "evidence"] }, + "writePolicy": { "enum": ["managed", "read-only", "generated"] }, + "generatedFrom": { "type": "array", "items": { "type": "string" } } } } }, diff --git a/tests/conftest.py b/tests/conftest.py index b30182d..48c6ab3 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -34,6 +34,30 @@ def make_repo(tmp_path): return _make +@pytest.fixture +def synthetic_repo(tmp_path): + """Build a repository from an explicit path -> content mapping. + + The checked-in fixtures cover two concrete legacy layouts; the adoption + compatibility tables need many small permutations of knowledge files and + agent entrypoints, which are clearer written inline than as dozens of + near-identical fixture trees. + """ + + def _make(files: dict[str, str], *, name: str = "repo", git: bool = True) -> Path: + dest = tmp_path / name + dest.mkdir(parents=True, exist_ok=True) + for relative, content in files.items(): + target = dest / relative + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(content, encoding="utf-8") + if git: + _git_init(dest) + return dest + + return _make + + @pytest.fixture def negative_repo(tmp_path): """Materialize a negative//contract.yaml fixture as ops/contract.yaml under a fresh repo.""" diff --git a/tests/test_adoption_rules.py b/tests/test_adoption_rules.py new file mode 100644 index 0000000..8e7b985 --- /dev/null +++ b/tests/test_adoption_rules.py @@ -0,0 +1,286 @@ +"""The adoption compatibility tables, and the safety rules `apply` must enforce. + +Runbook sections 11.1 and 11.2 are written as tables, and for a long time they +were only tables: the code implemented some rows, contradicted others and had no +test that noticed. These cases exist so a row cannot be changed in prose without +a corresponding branch here failing. +""" + +from __future__ import annotations + +import pytest + +from stewardship import adoption +from stewardship.markdown import load_yaml_text +from stewardship.schema_loader import validate_against_kind + +CONFORMANT_KDB = """apiVersion: stewardship.corsus.ru/v1alpha1 +kind: KnowledgeBase +metadata: + name: sample-kdb +spec: + repository: repo:sample + topics: [] + documents: [] +""" + +LEGACY_KDB = "custom_format: true\nsections:\n - quick_facts\n" + +BASE = {"README.md": "# Sample\n", "policies/.gitkeep": ""} + + +def _plan_for(repo): + assessment = adoption.assess(repo) + return assessment, adoption.build_plan(repo, assessment, confirmed_name="sample") + + +def _actions(plan): + return {change["path"]: change["action"] for change in plan["changes"]} + + +def _contract(plan): + entry = next(c for c in plan["changes"] if c["path"] == "ops/contract.yaml") + return load_yaml_text(entry["content"]) + + +# --- runbook 11.1: knowledge base compatibility ----------------------------- + +@pytest.mark.parametrize( + ("files", "expected_entrypoint", "expected_actions"), + [ + pytest.param({}, "kdb/kdb.yaml", {"kdb/kdb.yaml": "create"}, id="no-kdb-creates-one"), + pytest.param( + {"kdb/kdb.yaml": CONFORMANT_KDB}, + "kdb/kdb.yaml", + {"kdb/kdb.yaml": "preserve"}, + id="conformant-kdb-is-kept", + ), + pytest.param( + {"kdb.yaml": LEGACY_KDB}, + "kdb/kdb.yaml", + {"kdb/kdb.yaml": "create", "kdb.yaml": "preserve"}, + id="legacy-elsewhere-gets-an-index", + ), + pytest.param( + {"kdb/kdb.yaml": LEGACY_KDB}, + "ops/knowledge.yaml", + {"ops/knowledge.yaml": "create", "kdb/kdb.yaml": "preserve"}, + id="legacy-occupying-canonical-path-gets-an-adapter", + ), + ], +) +def test_knowledge_compatibility_table(synthetic_repo, files, expected_entrypoint, expected_actions): + repo = synthetic_repo({**BASE, **files}) + _, plan = _plan_for(repo) + actions = _actions(plan) + + assert _contract(plan)["spec"]["knowledge"]["entrypoint"] == expected_entrypoint + for path, action in expected_actions.items(): + assert actions[path] == action + + +def test_legacy_kdb_is_not_declared_conformant(synthetic_repo): + """The specific misreading that produced an invalid pilot contract.""" + repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB}) + assessment, _ = _plan_for(repo) + entry = next(e for e in assessment["knowledge"] if e["path"] == "kdb/kdb.yaml") + assert entry["format"] == "legacy-yaml" + assert entry["action"] == "wrap" + + +def test_generated_adapter_registers_the_legacy_file_and_validates(synthetic_repo): + repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB}) + _, plan = _plan_for(repo) + adapter = next(c for c in plan["changes"] if c["path"] == "ops/knowledge.yaml") + document = load_yaml_text(adapter["content"]) + + assert validate_against_kind("KnowledgeBase", document) == [] + assert document["spec"]["documents"][0]["path"] == "kdb/kdb.yaml" + assert "kdb/kdb.yaml" in plan["forbiddenChanges"] + + +# --- runbook 11.2: agent entrypoints ---------------------------------------- + +@pytest.mark.parametrize( + ("files", "expected_actions"), + [ + pytest.param({}, {"AGENTS.md": "create", "CLAUDE.md": "create"}, id="neither-exists"), + pytest.param( + {"AGENTS.md": "# Portable\n"}, + {"AGENTS.md": "preserve", "CLAUDE.md": "create"}, + id="portable-only", + ), + pytest.param( + {"CLAUDE.md": "# CLAUDE.md\n\nDomain rules.\n"}, + {"AGENTS.md": "create", "CLAUDE.md": "patch-managed-block"}, + id="claude-only-is-patched-not-replaced", + ), + pytest.param( + {"AGENTS.md": "# Portable\n", "CLAUDE.md": "# CLAUDE.md\n\nDomain rules.\n"}, + {"AGENTS.md": "preserve", "CLAUDE.md": "patch-managed-block"}, + id="both-exist", + ), + ], +) +def test_agent_entrypoint_table(synthetic_repo, files, expected_actions): + repo = synthetic_repo({**BASE, **files}) + _, plan = _plan_for(repo) + actions = _actions(plan) + for path, action in expected_actions.items(): + assert actions[path] == action + + +def test_patching_claude_keeps_every_existing_line(synthetic_repo): + original = "# CLAUDE.md\n\nIntro.\n\n## Domain\n\nRules that must survive.\n" + repo = synthetic_repo({**BASE, "CLAUDE.md": original}) + _, plan = _plan_for(repo) + adoption.apply_plan(repo, plan, plan["planHash"]) + + patched = (repo / "CLAUDE.md").read_text(encoding="utf-8") + for line in original.splitlines(): + if line.strip(): + assert line in patched + assert adoption.MANAGED_BLOCK_START in patched + + +def test_replanning_after_apply_is_idempotent(synthetic_repo): + repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n", "kdb/kdb.yaml": LEGACY_KDB}) + _, plan = _plan_for(repo) + adoption.apply_plan(repo, plan, plan["planHash"]) + + _, second = _plan_for(repo) + assert set(_actions(second).values()) == {"preserve"} + + +def test_managed_paths_cover_everything_the_plan_authors(synthetic_repo): + repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n", "kdb/kdb.yaml": LEGACY_KDB}) + _, plan = _plan_for(repo) + authored = { + c["path"] for c in plan["changes"] if c["action"] in ("create", "patch-managed-block") + } + assert set(_contract(plan)["spec"]["template"]["managedPaths"]) == authored + + +# --- apply safety ----------------------------------------------------------- + +def _replanned(plan, **changes): + """Re-hash a mutated plan so apply rejects it on its merits, not on the hash.""" + mutated = {**plan, **changes} + mutated.pop("planHash", None) + from stewardship import io + + mutated["planHash"] = io.sha256(mutated) + return mutated + + +@pytest.mark.parametrize( + "escape", + ["../escaped.md", "/etc/escaped.md", "C:/Windows/escaped.md"], + ids=["parent", "posix-absolute", "windows-absolute"], +) +def test_apply_refuses_paths_outside_the_repository(synthetic_repo, escape): + repo = synthetic_repo(BASE) + _, plan = _plan_for(repo) + hostile = _replanned( + plan, + changes=[{"action": "create", "path": escape, "ownership": "stewardship", "content": "x"}], + ) + with pytest.raises(adoption.AdoptionError) as caught: + adoption.apply_plan(repo, hostile, hostile["planHash"]) + assert caught.value.code == "ADOPT_PATH_OUTSIDE_REPOSITORY" + + +def test_apply_refuses_to_write_into_a_forbidden_path(synthetic_repo): + repo = synthetic_repo(BASE) + _, plan = _plan_for(repo) + hostile = _replanned( + plan, + changes=[ + {"action": "create", "path": "policies/new.yaml", "ownership": "stewardship", "content": "x"} + ], + forbiddenChanges=["policies/**"], + ) + with pytest.raises(adoption.AdoptionError) as caught: + adoption.apply_plan(repo, hostile, hostile["planHash"]) + assert caught.value.code == "ADOPT_FORBIDDEN_PATH" + + +def test_apply_refuses_when_a_path_it_writes_has_uncommitted_edits(synthetic_repo): + repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n"}) + _, plan = _plan_for(repo) + (repo / "CLAUDE.md").write_text("# CLAUDE.md\n\nEditing right now.\n", encoding="utf-8") + + with pytest.raises(adoption.AdoptionError) as caught: + adoption.apply_plan(repo, plan, plan["planHash"]) + assert caught.value.code == "ADOPT_WORKTREE_DIRTY" + + +def test_apply_tolerates_dirt_it_does_not_touch(synthetic_repo): + repo = synthetic_repo(BASE) + _, plan = _plan_for(repo) + (repo / "UNRELATED.md").write_text("still drafting\n", encoding="utf-8") + + assert "ops/contract.yaml" in adoption.apply_plan(repo, plan, plan["planHash"]) + + +def test_failed_apply_leaves_no_partial_file(synthetic_repo): + repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n"}) + _, plan = _plan_for(repo) + broken = _replanned( + plan, + changes=[ + {"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": "ok"}, + { + "action": "patch-managed-block", + "path": "CLAUDE.md", + "ownership": "shared", + "content": adoption.MANAGED_BLOCK_START + "\nunterminated", + }, + ], + ) + with pytest.raises(adoption.AdoptionError): + adoption.apply_plan(repo, broken, broken["planHash"]) + + assert not (repo / "ops" / "contract.yaml").exists() + assert (repo / "CLAUDE.md").read_text(encoding="utf-8") == "# CLAUDE.md\n\nRules.\n" + + +# --- verify ----------------------------------------------------------------- + +def test_verify_fails_when_a_preserved_file_was_modified(synthetic_repo): + repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB}) + _, plan = _plan_for(repo) + adoption.apply_plan(repo, plan, plan["planHash"]) + assert adoption.verify(repo, plan)["outcome"] == "pass" + + (repo / "kdb" / "kdb.yaml").write_text("tampered: true\n", encoding="utf-8") + report = adoption.verify(repo, plan) + assert report["outcome"] == "fail" + assert "ADOPT_PRESERVED_MODIFIED" in report["unresolvedFindings"] + + +def test_verify_without_a_plan_says_it_verified_nothing(synthetic_repo): + repo = synthetic_repo(BASE) + _, plan = _plan_for(repo) + adoption.apply_plan(repo, plan, plan["planHash"]) + + report = adoption.verify(repo) + assert "ADOPT_REPORT_UNSCOPED" in report["unresolvedFindings"] + + +# --- schemas ---------------------------------------------------------------- + +def test_adoption_outputs_match_their_schemas(synthetic_repo): + repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n"}) + assessment, plan = _plan_for(repo) + assert validate_against_kind("AdoptionAssessment", assessment) == [] + assert validate_against_kind("AdoptionPlan", plan) == [] + + adoption.apply_plan(repo, plan, plan["planHash"]) + assert validate_against_kind("AdoptionReport", adoption.verify(repo, plan)) == [] + + +def test_generated_contract_matches_its_schema(synthetic_repo): + repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB}) + _, plan = _plan_for(repo) + assert validate_against_kind("RepositoryContract", _contract(plan)) == []