assess sets confirmationRequired and asks "Confirm repository type" whenever confidence is below high, but there was no way to answer it: --answers read only name, title, owners and lifecycle, and build_plan took the type solely from the classifier's guess. The confirmation boundary in runbook section 9 could not be closed through the tool, and nothing in the resulting contract distinguished a deliberate decision from an unreviewed low-confidence default. - accept the type via --type or a repositoryType answer, validated against the known set rather than written through unchecked - record classification, confidence and evidence in metadata.annotations, which the schema already allows as a free-form object - omit any timestamp so re-planning stays deterministic and planHash stable Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
650 lines
26 KiB
Python
650 lines
26 KiB
Python
"""`repoctl adopt`: assess -> plan -> apply -> verify for an existing repository.
|
|
|
|
Follows docs/adoption-runbook.md. Default strategy is `overlay`: it only adds
|
|
stewardship metadata and never moves, deletes or renames existing files. The
|
|
`documents-to-content-root` normalization recipe is a separate, explicitly opted-in
|
|
path (not implemented as an automatic heuristic) and is intentionally out of scope
|
|
for this first cut beyond structural support in the AdoptionPlan schema.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import fnmatch
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
from . import gitutil, io
|
|
from .bootstrap import BootstrapAnswers, render_agents_md, render_claude_md
|
|
from .constants import API_VERSION
|
|
from .io import ResourceError
|
|
from .paths import PathViolation, confined_path
|
|
from .schema_loader import validate_against_kind
|
|
from .validate import validate_repository
|
|
|
|
MANAGED_BLOCK_START = "<!-- stewardship:managed:start -->"
|
|
MANAGED_BLOCK_END = "<!-- stewardship:managed:end -->"
|
|
|
|
|
|
class AdoptionError(ValueError):
|
|
"""An adoption step refused to proceed, carrying a stable finding code.
|
|
|
|
Subclasses ``ValueError`` so existing callers that catch ``ValueError`` keep
|
|
working, while ``code`` lets the CLI report the precise reason instead of
|
|
guessing one from the message text.
|
|
"""
|
|
|
|
def __init__(self, code: str, message: str) -> None:
|
|
super().__init__(f"{code}: {message}")
|
|
self.code = code
|
|
|
|
|
|
def render_managed_block(body: str) -> str:
|
|
"""Wrap ``body`` in the stewardship managed-block markers."""
|
|
return f"{MANAGED_BLOCK_START}\n{body.strip()}\n{MANAGED_BLOCK_END}\n"
|
|
|
|
|
|
def splice_managed_block(text: str, block: str) -> str:
|
|
"""Insert or replace the managed block inside ``text``, leaving the rest intact.
|
|
|
|
Adoption must never rewrite a shared agent entrypoint wholesale (runbook
|
|
section 3 and 11.2), so this only ever touches the marked region. When no
|
|
markers are present the block is inserted just below the first level-1
|
|
heading, keeping the stewardship pointer above the document body where an
|
|
agent reads it first. Malformed or duplicated markers raise rather than
|
|
guess at the author's intent.
|
|
"""
|
|
start_count = text.count(MANAGED_BLOCK_START)
|
|
end_count = text.count(MANAGED_BLOCK_END)
|
|
if start_count > 1 or end_count > 1:
|
|
raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "Duplicate managed-block markers")
|
|
if bool(start_count) != bool(end_count):
|
|
raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "Unpaired managed-block marker")
|
|
|
|
normalized = block if block.endswith("\n") else block + "\n"
|
|
if start_count == 1:
|
|
start = text.index(MANAGED_BLOCK_START)
|
|
end = text.index(MANAGED_BLOCK_END) + len(MANAGED_BLOCK_END)
|
|
if end < start:
|
|
raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "End marker precedes start marker")
|
|
tail = text[end:].lstrip("\n")
|
|
return text[:start] + normalized + ("\n" + tail if tail else "")
|
|
|
|
lines = text.splitlines(keepends=True)
|
|
for position, line in enumerate(lines):
|
|
if line.startswith("# "):
|
|
insert_at = position + 1
|
|
if insert_at < len(lines) and not lines[insert_at].strip():
|
|
insert_at += 1
|
|
head = "".join(lines[:insert_at])
|
|
if not head.endswith("\n"):
|
|
head += "\n"
|
|
if not head.endswith("\n\n"):
|
|
head += "\n"
|
|
tail = "".join(lines[insert_at:]).lstrip("\n")
|
|
return head + normalized + ("\n" + tail if tail else "")
|
|
tail = text.lstrip("\n")
|
|
return normalized + ("\n" + tail if tail else "")
|
|
|
|
|
|
_COLLISION_PATHS = [
|
|
"ops/contract.yaml",
|
|
"kdb/kdb.yaml",
|
|
"kdb.yaml",
|
|
"CLAUDE.md",
|
|
"AGENTS.md",
|
|
".claude/skills",
|
|
".agents/skills",
|
|
"ops/handlers",
|
|
"ops/template-answers.yaml",
|
|
]
|
|
|
|
_SECRET_SHAPED_GLOBS = [
|
|
"*.pem", "*.key", "id_rsa", "id_ed25519", "id_ecdsa", "id_dsa",
|
|
".env", ".env.*", "*.env", "*password*", "*secret*", "*.pfx", "*.p12",
|
|
]
|
|
_SECRET_EXCLUDE_SUFFIXES = (".pub", ".schema.json", ".example")
|
|
|
|
_TYPE_EVIDENCE: list[tuple[str, list[str]]] = [
|
|
("infrastructure-config", ["profiles-source", "profiles", "inventory", "stacks", "terraform", "ansible"]),
|
|
("service-config", ["policies", "acceptance", "runbooks", "deployments"]),
|
|
("software", ["src", "pyproject.toml", "package.json", "go.mod", "Cargo.toml"]),
|
|
("project", ["deliverables", "docs", "decisions"]),
|
|
]
|
|
|
|
|
|
def _finding(severity: str, code: str, path: str | None = None, message: str | None = None) -> dict[str, Any]:
|
|
item: dict[str, Any] = {"severity": severity, "code": code}
|
|
if path:
|
|
item["path"] = path
|
|
if message:
|
|
item["message"] = message
|
|
return item
|
|
|
|
|
|
def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, bool]]:
|
|
"""Return (relative_path, is_tracked) for files matching secret-shaped name patterns."""
|
|
tracked = gitutil.tracked_files(root)
|
|
found: list[tuple[str, bool]] = []
|
|
for path in root.rglob("*"):
|
|
if not path.is_file():
|
|
continue
|
|
if ".git" in path.parts or ".venv" in path.parts or "node_modules" in path.parts:
|
|
continue
|
|
name = path.name
|
|
if name.lower().endswith(_SECRET_EXCLUDE_SUFFIXES):
|
|
continue
|
|
if any(fnmatch.fnmatch(name.lower(), pattern) for pattern in _SECRET_SHAPED_GLOBS):
|
|
rel = path.relative_to(root).as_posix()
|
|
found.append((rel, rel in tracked))
|
|
return found
|
|
|
|
|
|
def _knowledge_format(path: Path) -> str:
|
|
"""Return ``stewardship-yaml`` only when the file really is a KnowledgeBase.
|
|
|
|
Location is not evidence of format: a repository may keep a large custom
|
|
knowledge file at the canonical path (runbook 11.1). Deciding by path alone
|
|
is what made adoption declare a legacy file conformant and then point the
|
|
contract at it, so validate the content against the schema instead.
|
|
"""
|
|
try:
|
|
data = io.load_yaml(path)
|
|
except ResourceError:
|
|
return "unparseable"
|
|
if not isinstance(data, dict):
|
|
return "legacy-yaml"
|
|
return "legacy-yaml" if validate_against_kind("KnowledgeBase", data) else "stewardship-yaml"
|
|
|
|
|
|
def _knowledge_entry(root: Path, rel: str) -> dict[str, str]:
|
|
fmt = _knowledge_format(root / rel)
|
|
action = "keep-or-validate" if fmt == "stewardship-yaml" else "wrap"
|
|
return {"path": rel, "format": fmt, "action": action}
|
|
|
|
|
|
def _classify_type(root: Path) -> tuple[str, str, list[str]]:
|
|
scores: dict[str, list[str]] = {t: [] for t, _ in _TYPE_EVIDENCE}
|
|
for repo_type, markers in _TYPE_EVIDENCE:
|
|
for marker in markers:
|
|
if (root / marker).exists():
|
|
scores[repo_type].append(marker)
|
|
ranked = sorted(scores.items(), key=lambda kv: -len(kv[1]))
|
|
best_type, best_evidence = ranked[0]
|
|
second_count = len(ranked[1][1]) if len(ranked) > 1 else 0
|
|
if not best_evidence:
|
|
return "project", "low", []
|
|
if len(best_evidence) >= 2 and len(best_evidence) > second_count:
|
|
confidence = "high"
|
|
elif len(best_evidence) > second_count:
|
|
confidence = "medium"
|
|
else:
|
|
confidence = "low"
|
|
return best_type, confidence, best_evidence
|
|
|
|
|
|
def assess(root: Path) -> dict[str, Any]:
|
|
head = gitutil.head_revision(root)
|
|
dirty = gitutil.is_dirty(root)
|
|
|
|
proposed_type, confidence, evidence = _classify_type(root)
|
|
|
|
claude_exists = (root / "CLAUDE.md").exists()
|
|
agents_exists = (root / "AGENTS.md").exists()
|
|
canonical_direction = "none"
|
|
findings: list[dict[str, Any]] = []
|
|
if claude_exists and agents_exists:
|
|
claude_text = (root / "CLAUDE.md").read_text(encoding="utf-8", errors="ignore")
|
|
if "AGENTS.md" in claude_text:
|
|
canonical_direction = "claude-imports-agents"
|
|
else:
|
|
agents_text = (root / "AGENTS.md").read_text(encoding="utf-8", errors="ignore")
|
|
if "CLAUDE.md" in agents_text:
|
|
canonical_direction = "legacy-agents-to-claude"
|
|
findings.append(_finding("warning", "ADOPT_ENTRYPOINT_DIRECTION_LEGACY", "AGENTS.md"))
|
|
else:
|
|
canonical_direction = "independent"
|
|
elif claude_exists:
|
|
canonical_direction = "claude-only"
|
|
elif agents_exists:
|
|
canonical_direction = "agents-only"
|
|
|
|
knowledge: list[dict[str, Any]] = []
|
|
for rel in ("kdb/kdb.yaml", "kdb.yaml", "ops/knowledge.yaml"):
|
|
if not (root / rel).exists():
|
|
continue
|
|
entry = _knowledge_entry(root, rel)
|
|
knowledge.append(entry)
|
|
if entry["action"] == "wrap":
|
|
findings.append(_finding("info", "ADOPT_KDB_LEGACY", rel))
|
|
|
|
proposed_content_roots: list[dict[str, Any]] = []
|
|
for repo_type, markers in _TYPE_EVIDENCE:
|
|
if repo_type != proposed_type:
|
|
continue
|
|
for marker in markers:
|
|
candidate = root / marker
|
|
if candidate.is_dir():
|
|
proposed_content_roots.append(
|
|
{"id": marker.replace("/", "-").lower(), "path": marker, "role": marker, "authority": "source"}
|
|
)
|
|
|
|
collisions: list[str] = []
|
|
for rel in _COLLISION_PATHS:
|
|
if (root / rel).exists():
|
|
collisions.append(rel)
|
|
if (root / "kdb" / "kdb.yaml").exists() and (root / "kdb.yaml").exists():
|
|
findings.append(_finding("warning", "ADOPT_KDB_CANONICAL_PATH_OCCUPIED", "kdb/kdb.yaml"))
|
|
|
|
for rel, tracked in _detect_secret_shaped_paths(root):
|
|
if tracked:
|
|
findings.append(_finding("error", "ADOPT_SECRET_TRACKED", rel, "Tracked path matches a secret-shaped filename pattern"))
|
|
else:
|
|
findings.append(_finding("info", "ADOPT_SECRET_TRACKED", rel, "Untracked secret-shaped path (path only, content not read)"))
|
|
|
|
if dirty:
|
|
findings.append(_finding("warning", "ADOPT_WORKTREE_DIRTY"))
|
|
|
|
questions: list[str] = []
|
|
confirmation_required = confidence != "high"
|
|
if confirmation_required:
|
|
questions.append("Confirm repository type and confidence evidence")
|
|
questions.append("Confirm owner(s) and lifecycle")
|
|
|
|
return {
|
|
"schema": "stewardship/adoption-assessment@0.1",
|
|
"repository": {"path": str(root), "baselineRevision": head, "dirty": dirty},
|
|
"classification": {
|
|
"proposedType": proposed_type,
|
|
"confidence": confidence,
|
|
"evidence": evidence,
|
|
"confirmationRequired": confirmation_required,
|
|
},
|
|
"entrypoints": {
|
|
"claude": "CLAUDE.md" if claude_exists else None,
|
|
"portable": "AGENTS.md" if agents_exists else None,
|
|
"canonicalDirection": canonical_direction,
|
|
},
|
|
"knowledge": knowledge,
|
|
"proposedContentRoots": proposed_content_roots,
|
|
"collisions": collisions,
|
|
"findings": findings,
|
|
"questions": questions,
|
|
}
|
|
|
|
|
|
def _entrypoint_pointer_block(knowledge_entrypoint: str) -> str:
|
|
"""The managed block adoption adds to an existing primary agent entrypoint."""
|
|
return render_managed_block(
|
|
f"""## Repository Stewardship
|
|
|
|
This repository is adopted at L1. Before reading anything else:
|
|
|
|
- `ops/contract.yaml` names the repository, its owner and its content roots.
|
|
- `{knowledge_entrypoint}` is the knowledge index; match the task to a topic
|
|
intent and open only what that topic names.
|
|
- `repoctl context --repo . --intent <intent>` returns just the context an
|
|
intent needs, instead of the whole knowledge base."""
|
|
)
|
|
|
|
|
|
def _knowledge_base(name: str, legacy_path: str | None) -> dict[str, Any]:
|
|
"""A minimal KnowledgeBase, indexing ``legacy_path`` when one was found.
|
|
|
|
Topics stay empty on purpose: which sections of a legacy file matter is a
|
|
judgement call the tool cannot make, so adoption registers the document and
|
|
leaves routing to be authored deliberately afterwards.
|
|
"""
|
|
documents: list[dict[str, Any]] = []
|
|
if legacy_path:
|
|
documents.append(
|
|
{
|
|
"id": "legacy-knowledge-base",
|
|
"title": "Existing knowledge base",
|
|
"role": "reference",
|
|
"path": legacy_path,
|
|
"mediaType": "application/yaml",
|
|
"authority": "local-canonical",
|
|
"status": "verified",
|
|
}
|
|
)
|
|
return {
|
|
"apiVersion": API_VERSION,
|
|
"kind": "KnowledgeBase",
|
|
"metadata": {"name": f"{name}-knowledge-index"},
|
|
"spec": {
|
|
"repository": f"repo:{name}",
|
|
"defaultLanguage": "en",
|
|
"topics": [],
|
|
"documents": documents,
|
|
},
|
|
}
|
|
|
|
|
|
def _plan_knowledge(
|
|
assessment: dict[str, Any], confirmed_name: str
|
|
) -> tuple[str, list[dict[str, Any]], list[str]]:
|
|
"""Choose the knowledge entrypoint and the changes that establish it.
|
|
|
|
This is the compatibility table in runbook 11.1 expressed as code. The row
|
|
that matters most here is the last one: when a legacy or custom knowledge
|
|
base already occupies ``kdb/kdb.yaml`` it is indexed from a new
|
|
``ops/knowledge.yaml`` and left untouched, never rewritten and never
|
|
declared conformant.
|
|
"""
|
|
entries = {entry["path"]: entry for entry in assessment.get("knowledge", [])}
|
|
changes: list[dict[str, Any]] = []
|
|
forbidden: list[str] = []
|
|
|
|
canonical = entries.get("kdb/kdb.yaml")
|
|
adapter = entries.get("ops/knowledge.yaml")
|
|
root_legacy = entries.get("kdb.yaml")
|
|
|
|
if adapter is not None:
|
|
changes.append({"action": "preserve", "path": "ops/knowledge.yaml", "ownership": "repository"})
|
|
if canonical is not None:
|
|
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
|
|
forbidden.append("kdb/kdb.yaml")
|
|
return "ops/knowledge.yaml", changes, forbidden
|
|
|
|
if canonical is not None and canonical["action"] == "keep-or-validate":
|
|
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
|
|
return "kdb/kdb.yaml", changes, forbidden
|
|
|
|
if canonical is not None:
|
|
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
|
|
forbidden.append("kdb/kdb.yaml")
|
|
changes.append(
|
|
{
|
|
"action": "create",
|
|
"path": "ops/knowledge.yaml",
|
|
"ownership": "stewardship",
|
|
"reason": "Compatibility index; kdb/kdb.yaml holds a non-conformant knowledge base",
|
|
"content": io.yaml_text(_knowledge_base(confirmed_name, "kdb/kdb.yaml")),
|
|
}
|
|
)
|
|
return "ops/knowledge.yaml", changes, forbidden
|
|
|
|
legacy_path = root_legacy["path"] if root_legacy is not None else None
|
|
if legacy_path:
|
|
forbidden.append(legacy_path)
|
|
changes.append(
|
|
{
|
|
"action": "create",
|
|
"path": "kdb/kdb.yaml",
|
|
"ownership": "stewardship",
|
|
"reason": "Compatibility index for legacy knowledge base" if legacy_path else "Minimal KDB",
|
|
"content": io.yaml_text(_knowledge_base(confirmed_name, legacy_path)),
|
|
}
|
|
)
|
|
return "kdb/kdb.yaml", changes, forbidden
|
|
|
|
|
|
def build_plan(
|
|
root: Path,
|
|
assessment: dict[str, Any],
|
|
*,
|
|
confirmed_name: str,
|
|
confirmed_title: str | None = None,
|
|
confirmed_owners: list[str] | None = None,
|
|
confirmed_lifecycle: str = "active",
|
|
confirmed_type: str | None = None,
|
|
strategy: str = "overlay",
|
|
) -> dict[str, Any]:
|
|
if strategy != "overlay":
|
|
raise ValueError("Only the overlay strategy is implemented; normalize requires an explicit recipe run")
|
|
|
|
baseline = assessment["repository"]["baselineRevision"]
|
|
classification = assessment["classification"]
|
|
repository_type = confirmed_type or classification["proposedType"]
|
|
# assess asks the owner to confirm the type whenever confidence is below
|
|
# high, so record which of the two answers the contract is built on. Without
|
|
# this a low-confidence guess and a deliberate decision look identical later.
|
|
annotations: dict[str, str] = {
|
|
"stewardship.corsus.ru/classification": "confirmed" if confirmed_type else "inferred",
|
|
"stewardship.corsus.ru/classification-confidence": classification["confidence"],
|
|
}
|
|
if classification.get("evidence"):
|
|
annotations["stewardship.corsus.ru/classification-evidence"] = ", ".join(
|
|
classification["evidence"]
|
|
)
|
|
changes: list[dict[str, Any]] = []
|
|
forbidden: list[str] = []
|
|
|
|
contract_exists = (root / "ops/contract.yaml").exists()
|
|
content_roots = [
|
|
{
|
|
"id": cr["id"],
|
|
"role": cr["role"],
|
|
"path": cr["path"],
|
|
"kind": "directory",
|
|
"authority": cr.get("authority", "source"),
|
|
"writePolicy": "managed",
|
|
}
|
|
for cr in assessment.get("proposedContentRoots", [])
|
|
]
|
|
for cr in content_roots:
|
|
forbidden.append(f"{cr['path']}/**")
|
|
|
|
knowledge_entrypoint, knowledge_changes, knowledge_forbidden = _plan_knowledge(
|
|
assessment, confirmed_name
|
|
)
|
|
forbidden.extend(knowledge_forbidden)
|
|
|
|
changes.extend(knowledge_changes)
|
|
|
|
if not (root / "AGENTS.md").exists():
|
|
answers = BootstrapAnswers(
|
|
name=confirmed_name, title=confirmed_title or confirmed_name, owners=confirmed_owners or [],
|
|
repository_type=repository_type, lifecycle=confirmed_lifecycle,
|
|
)
|
|
changes.append({"action": "create", "path": "AGENTS.md", "ownership": "shared", "content": render_agents_md(answers)})
|
|
else:
|
|
changes.append({"action": "preserve", "path": "AGENTS.md", "ownership": "repository"})
|
|
|
|
claude_path = root / "CLAUDE.md"
|
|
if not claude_path.exists():
|
|
changes.append({"action": "create", "path": "CLAUDE.md", "ownership": "shared", "content": render_claude_md()})
|
|
else:
|
|
# An existing Claude entrypoint keeps its content; adoption only adds a
|
|
# short pointer so an agent finds the contract before it starts reading
|
|
# whatever large document the repository routes through.
|
|
block = _entrypoint_pointer_block(knowledge_entrypoint)
|
|
current = claude_path.read_text(encoding="utf-8", errors="ignore")
|
|
if splice_managed_block(current, block) == current:
|
|
changes.append({"action": "preserve", "path": "CLAUDE.md", "ownership": "repository"})
|
|
else:
|
|
changes.append(
|
|
{
|
|
"action": "patch-managed-block",
|
|
"path": "CLAUDE.md",
|
|
"ownership": "shared",
|
|
"reason": "Point the primary agent entrypoint at the contract and knowledge index",
|
|
"content": block,
|
|
}
|
|
)
|
|
|
|
# The contract is assembled last because managedPaths is a statement about
|
|
# the rest of the plan: anything this adoption authors, it owns.
|
|
managed_paths = ["ops/contract.yaml"] + [
|
|
change["path"]
|
|
for change in changes
|
|
if change["action"] in ("create", "patch-managed-block")
|
|
]
|
|
if not contract_exists:
|
|
contract = {
|
|
"apiVersion": API_VERSION,
|
|
"kind": "RepositoryContract",
|
|
"metadata": {
|
|
"name": confirmed_name,
|
|
"title": confirmed_title or confirmed_name,
|
|
"owners": confirmed_owners or [],
|
|
"annotations": annotations,
|
|
},
|
|
"spec": {
|
|
"summary": f"Adopted repository {confirmed_name}",
|
|
"repository": {
|
|
"type": repository_type,
|
|
"lifecycle": confirmed_lifecycle,
|
|
},
|
|
"template": {
|
|
"id": "repository." + repository_type.split("-")[0],
|
|
"version": "0.1.0",
|
|
"source": "repo:repository-stewardship",
|
|
"mode": "adopted-overlay",
|
|
"managedPaths": sorted(dict.fromkeys(managed_paths)),
|
|
},
|
|
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
|
|
"knowledge": {"entrypoint": knowledge_entrypoint},
|
|
"contentRoots": content_roots,
|
|
},
|
|
}
|
|
changes.insert(0, {"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": io.yaml_text(contract)})
|
|
else:
|
|
changes.insert(0, {"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"})
|
|
|
|
preserved_already = {c["path"] for c in changes if c["action"] == "preserve"}
|
|
for rel in ("kdb.yaml", "profiles-source", "profiles"):
|
|
if (root / rel).exists() and rel not in preserved_already:
|
|
changes.append({"action": "preserve", "path": rel, "ownership": "repository"})
|
|
preserved_already.add(rel)
|
|
|
|
forbidden.append(".ssh/**")
|
|
|
|
plan: dict[str, Any] = {
|
|
"schema": "stewardship/adoption-plan@0.1",
|
|
"repository": f"repo:{confirmed_name}",
|
|
"baselineRevision": baseline,
|
|
"strategy": strategy,
|
|
"changes": changes,
|
|
"forbiddenChanges": sorted(set(forbidden)),
|
|
"validations": [
|
|
"stewardship-schema",
|
|
"path-confinement",
|
|
"knowledge-references",
|
|
"agent-entrypoint-cycle",
|
|
],
|
|
"approval": {"required": True},
|
|
}
|
|
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
|
plan["planHash"] = plan_hash
|
|
return plan
|
|
|
|
|
|
def is_forbidden(rel_path: str, forbidden: list[str]) -> bool:
|
|
"""True when ``rel_path`` is covered by any ``forbiddenChanges`` pattern."""
|
|
return any(fnmatch.fnmatch(rel_path, pattern) for pattern in forbidden)
|
|
|
|
|
|
def _resolve_change_target(root: Path, rel_path: str) -> Path:
|
|
"""Confine a plan-supplied path to the repository before it is ever written.
|
|
|
|
A plan is an ordinary file that can be edited or moved between machines, and
|
|
``root / rel_path`` silently discards ``root`` when ``rel_path`` is absolute,
|
|
so this is the boundary that keeps `apply` from writing outside the repo.
|
|
"""
|
|
try:
|
|
return confined_path(root, rel_path)
|
|
except PathViolation as exc:
|
|
raise AdoptionError("ADOPT_PATH_OUTSIDE_REPOSITORY", f"{rel_path}: {exc}") from exc
|
|
|
|
|
|
def apply_plan(root: Path, plan: dict[str, Any], approve_hash: str) -> list[str]:
|
|
expected_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
|
if expected_hash != plan.get("planHash"):
|
|
raise AdoptionError("APPROVAL_FAILED", "Plan hash does not match plan content; re-plan before apply")
|
|
if approve_hash != plan["planHash"]:
|
|
raise AdoptionError("APPROVAL_FAILED", "Approval hash does not match plan hash")
|
|
|
|
current_head = gitutil.head_revision(root)
|
|
if current_head != plan["baselineRevision"]:
|
|
raise AdoptionError(
|
|
"ADOPT_BASELINE_CHANGED", "Baseline revision changed since plan was built; re-plan"
|
|
)
|
|
|
|
forbidden = list(plan.get("forbiddenChanges", []))
|
|
to_write = [c for c in plan["changes"] if c["action"] in ("create", "patch-managed-block")]
|
|
|
|
targets: dict[str, Path] = {}
|
|
for change in to_write:
|
|
rel = change["path"]
|
|
target = _resolve_change_target(root, rel)
|
|
if is_forbidden(rel, forbidden):
|
|
raise AdoptionError("ADOPT_FORBIDDEN_PATH", f"Plan writes into a forbidden path: {rel}")
|
|
if change["action"] == "create" and target.exists():
|
|
raise AdoptionError("ADOPT_PATH_COLLISION", f"Refusing to overwrite existing path: {rel}")
|
|
if change["action"] == "patch-managed-block" and not target.exists():
|
|
raise AdoptionError(
|
|
"ADOPT_PATH_COLLISION", f"Cannot patch a managed block into a missing file: {rel}"
|
|
)
|
|
targets[rel] = target
|
|
|
|
# Re-check the worktree immediately before writing rather than trusting the
|
|
# `assess` that preceded it: a dirty path unrelated to the plan is the user's
|
|
# business, but overwriting a file they have uncommitted edits in is not.
|
|
contested = gitutil.dirty_paths(root) & set(targets)
|
|
if contested:
|
|
raise AdoptionError(
|
|
"ADOPT_WORKTREE_DIRTY",
|
|
"Uncommitted changes in paths this plan writes: " + ", ".join(sorted(contested)),
|
|
)
|
|
|
|
backups: dict[str, bytes | None] = {}
|
|
written: list[str] = []
|
|
try:
|
|
for change in to_write:
|
|
rel = change["path"]
|
|
target = targets[rel]
|
|
backups[rel] = target.read_bytes() if target.exists() else None
|
|
if change["action"] == "patch-managed-block":
|
|
current = target.read_text(encoding="utf-8")
|
|
content = splice_managed_block(current, change["content"])
|
|
else:
|
|
content = change["content"]
|
|
io.write_text_atomic(target, content)
|
|
written.append(rel)
|
|
except Exception:
|
|
# Restore by what was on disk before, not by what we believe we finished:
|
|
# a write that failed part-way still leaves a file that never existed.
|
|
for rel, original in backups.items():
|
|
target = targets[rel]
|
|
if original is None:
|
|
if target.exists():
|
|
target.unlink()
|
|
else:
|
|
target.write_bytes(original)
|
|
raise
|
|
return written
|
|
|
|
|
|
def verify(root: Path, plan: dict[str, Any] | None = None) -> dict[str, Any]:
|
|
validation = validate_repository(root)
|
|
baseline = gitutil.head_revision(root)
|
|
|
|
changed_paths: list[str] = []
|
|
preserved_paths: list[str] = []
|
|
if plan is not None:
|
|
for change in plan["changes"]:
|
|
if change["action"] in ("create", "patch-managed-block"):
|
|
changed_paths.append(change["path"])
|
|
elif change["action"] == "preserve":
|
|
preserved_paths.append(change["path"])
|
|
|
|
unresolved = sorted({f.code for f in validation.findings if f.severity in ("warning", "error")})
|
|
if any(f.severity == "error" for f in validation.findings):
|
|
outcome = "fail"
|
|
elif unresolved:
|
|
outcome = "pass-with-warnings"
|
|
else:
|
|
outcome = "pass"
|
|
|
|
return {
|
|
"schema": "stewardship/adoption-report@0.1",
|
|
"repository": f"repo:{(validation.contract or {}).get('metadata', {}).get('name', 'unknown')}",
|
|
"baselineRevision": baseline,
|
|
"compatibilityLevel": "L1",
|
|
"outcome": outcome,
|
|
"changedPaths": sorted(set(changed_paths)),
|
|
"preservedPaths": sorted(set(preserved_paths)),
|
|
"unresolvedFindings": unresolved,
|
|
}
|