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 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
005419a0ba
commit
e5a42fa446
@@ -54,6 +54,18 @@ def splice_managed_block(text: str, block: str) -> str:
|
|||||||
agent reads it first. Malformed or duplicated markers raise rather than
|
agent reads it first. Malformed or duplicated markers raise rather than
|
||||||
guess at the author's intent.
|
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)
|
start_count = text.count(MANAGED_BLOCK_START)
|
||||||
end_count = text.count(MANAGED_BLOCK_END)
|
end_count = text.count(MANAGED_BLOCK_END)
|
||||||
if start_count > 1 or end_count > 1:
|
if start_count > 1 or end_count > 1:
|
||||||
|
|||||||
@@ -60,7 +60,9 @@
|
|||||||
"id": { "type": "string" },
|
"id": { "type": "string" },
|
||||||
"path": { "type": "string" },
|
"path": { "type": "string" },
|
||||||
"role": { "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" } }
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
|||||||
@@ -34,6 +34,30 @@ def make_repo(tmp_path):
|
|||||||
return _make
|
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
|
@pytest.fixture
|
||||||
def negative_repo(tmp_path):
|
def negative_repo(tmp_path):
|
||||||
"""Materialize a negative/<name>/contract.yaml fixture as ops/contract.yaml under a fresh repo."""
|
"""Materialize a negative/<name>/contract.yaml fixture as ops/contract.yaml under a fresh repo."""
|
||||||
|
|||||||
@@ -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)) == []
|
||||||
Reference in New Issue
Block a user