feat: implement repoctl L1 core (models, schemas, validate, discover, context, init, adopt)

Adds the repository-stewardship Python package (src/stewardship) with:
- JSON Schemas (Draft 2020-12) for RepositoryContract, KnowledgeBase, CatalogIndex,
  ContextBundle, BootstrapPlan, AdoptionAssessment/Plan/Report, user config and the
  repoctl-result envelope.
- Safe YAML I/O, path confinement, deterministic clock and canonical-JSON hashing.
- validate: schema, ID uniqueness, path safety, KDB references, freshness, secret-shaped
  fields, shell-string detection, and Markdown frontmatter/fence/link checks.
- discover/CatalogIndex with deterministic sorting and duplicate-name detection.
- describe (contract-only) and context (intent-scoped ContextBundle with budgeted
  materialization and --strict truncation).
- init: plan-then-apply bootstrap with SHA-256 plan-hash approval, no fake domain
  artifacts, bundled Claude skills.
- adopt: assess/plan/apply/verify overlay workflow per docs/adoption-runbook.md,
  preserving legacy content roots and KDB, with baseline-hash re-check and rollback.
- argparse-based `repoctl` CLI with human/yaml/json output and spec exit codes.
- pytest suite (39 tests) covering positive/negative fixtures, discovery, context,
  bootstrap and adoption (including LXD- and Antivirus-shaped legacy layouts).

Managed with uv (.venv), ruff clean, mypy --strict clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-24 14:57:34 +03:00
co-authored by Claude Sonnet 5
parent 9a39b8a941
commit 96d4d08230
75 changed files with 4259 additions and 0 deletions
+3
View File
@@ -0,0 +1,3 @@
"""Repository Stewardship protocol implementation."""
__version__ = "0.1.0"
+396
View File
@@ -0,0 +1,396 @@
"""`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 .validate import validate_repository
_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 _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]] = []
if (root / "kdb" / "kdb.yaml").exists():
knowledge.append({"path": "kdb/kdb.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"})
elif (root / "kdb.yaml").exists():
knowledge.append({"path": "kdb.yaml", "format": "legacy-yaml", "action": "wrap"})
findings.append(_finding("info", "ADOPT_KDB_LEGACY", "kdb.yaml"))
if (root / "ops" / "knowledge.yaml").exists():
knowledge.append({"path": "ops/knowledge.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"})
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 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",
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"]
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']}/**")
if not contract_exists:
contract = {
"apiVersion": API_VERSION,
"kind": "RepositoryContract",
"metadata": {
"name": confirmed_name,
"title": confirmed_title or confirmed_name,
"owners": confirmed_owners or [],
},
"spec": {
"summary": f"Adopted repository {confirmed_name}",
"repository": {
"type": assessment["classification"]["proposedType"],
"lifecycle": confirmed_lifecycle,
},
"template": {
"id": "repository." + assessment["classification"]["proposedType"].split("-")[0],
"version": "0.1.0",
"source": "repo:repository-stewardship",
"mode": "adopted-overlay",
"managedPaths": ["ops/contract.yaml"],
},
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
"knowledge": {"entrypoint": _knowledge_entrypoint(assessment)},
"contentRoots": content_roots,
},
}
changes.append({"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": io.yaml_text(contract)})
else:
changes.append({"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"})
kdb_entries = assessment.get("knowledge", [])
kdb_paths = {entry["path"] for entry in kdb_entries}
if "kdb/kdb.yaml" not in kdb_paths:
legacy = next((e for e in kdb_entries if e["action"] == "wrap"), None)
kdb: dict[str, Any] = {
"apiVersion": API_VERSION,
"kind": "KnowledgeBase",
"metadata": {"name": f"{confirmed_name}-knowledge-index"},
"spec": {
"repository": f"repo:{confirmed_name}",
"defaultLanguage": "en",
"topics": [],
"documents": [],
},
}
target_kdb_path = "kdb/kdb.yaml"
if legacy:
kdb["spec"]["documents"].append(
{
"id": "legacy-knowledge-base",
"title": "Existing knowledge base",
"role": "reference",
"path": legacy["path"],
"mediaType": "application/yaml",
"authority": "local-canonical",
"status": "verified",
}
)
forbidden.append(legacy["path"])
changes.append({"action": "create", "path": target_kdb_path, "ownership": "stewardship", "reason": "Compatibility index for legacy knowledge base" if legacy else "Minimal KDB", "content": io.yaml_text(kdb)})
else:
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
if not (root / "AGENTS.md").exists():
answers = BootstrapAnswers(
name=confirmed_name, title=confirmed_title or confirmed_name, owners=confirmed_owners or [],
repository_type=assessment["classification"]["proposedType"], 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"})
if not (root / "CLAUDE.md").exists():
changes.append({"action": "create", "path": "CLAUDE.md", "ownership": "shared", "content": render_claude_md()})
else:
changes.append({"action": "preserve", "path": "CLAUDE.md", "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 _knowledge_entrypoint(assessment: dict[str, Any]) -> str:
for entry in assessment.get("knowledge", []):
if entry["path"] == "kdb/kdb.yaml":
return "kdb/kdb.yaml"
return "kdb/kdb.yaml"
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 ValueError("Plan hash does not match plan content; re-plan before apply")
if approve_hash != plan["planHash"]:
raise ValueError("Approval hash does not match plan hash")
current_head = gitutil.head_revision(root)
if current_head != plan["baselineRevision"]:
raise ValueError("ADOPT_BASELINE_CHANGED: baseline revision changed since plan was built; re-plan")
to_write = [c for c in plan["changes"] if c["action"] in ("create", "patch-managed-block")]
for change in to_write:
target = root / change["path"]
if change["action"] == "create" and target.exists():
raise FileExistsError(f"ADOPT_PATH_COLLISION: refusing to overwrite existing path: {change['path']}")
written: list[str] = []
backups: dict[str, bytes | None] = {}
try:
for change in to_write:
target = root / change["path"]
backups[change["path"]] = target.read_bytes() if target.exists() else None
io.write_text_atomic(target, change["content"])
written.append(change["path"])
except Exception:
for rel, original in backups.items():
target = root / rel
if original is None:
if target.exists() and rel in written:
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,
}
+235
View File
@@ -0,0 +1,235 @@
"""`repoctl init`: plan-then-apply bootstrap of a new repository.
Content roots are declared in the contract but their directories are not created —
this repository's self-hosting rule forbids placeholder directories and fictional
domain artifacts. `init` never commits, pushes or creates a remote.
"""
from __future__ import annotations
import subprocess
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from . import io
from .clock import DEFAULT_CLOCK
from .constants import API_VERSION
from .skills_content import (
REPO_HANDOFF_SKILL,
REPOSITORY_ADOPTION_SKILL,
REPOSITORY_BOOTSTRAP_SKILL,
)
TEMPLATE_IDS = {
"infrastructure-config": "repository.infrastructure",
"service-config": "repository.service",
"software": "repository.software",
"project": "repository.project",
}
TEMPLATE_VERSION = "0.1.0"
_DEFAULT_CONTENT_ROOTS: dict[str, list[dict[str, str]]] = {
"infrastructure-config": [
{"id": "desired-state", "role": "desired", "path": "desired", "kind": "directory", "authority": "source", "writePolicy": "managed"},
{"id": "inventory", "role": "inventory", "path": "inventory", "kind": "directory", "authority": "source", "writePolicy": "managed"},
],
"service-config": [
{"id": "policies", "role": "policies", "path": "policies", "kind": "directory", "authority": "source", "writePolicy": "managed"},
{"id": "acceptance", "role": "acceptance", "path": "acceptance", "kind": "directory", "authority": "source", "writePolicy": "managed"},
],
"software": [
{"id": "source", "role": "source", "path": "src", "kind": "directory", "authority": "source", "writePolicy": "managed"},
{"id": "tests", "role": "tests", "path": "tests", "kind": "directory", "authority": "source", "writePolicy": "managed"},
],
"project": [
{"id": "deliverables", "role": "deliverables", "path": "deliverables", "kind": "directory", "authority": "source", "writePolicy": "managed"},
{"id": "decisions", "role": "decisions", "path": "decisions", "kind": "directory", "authority": "source", "writePolicy": "managed"},
],
}
SSH_RECOMMENDATION = (
"Consider a repository-scoped SSH deploy key: read-only by default, private key kept "
"outside Git, and scoped to only this repository. repoctl does not generate or store "
"the key; use the gen-ssh-eddsa workflow or your Git host's deploy key feature."
)
@dataclass
class BootstrapAnswers:
name: str
title: str
owners: list[str]
repository_type: str
lifecycle: str = "active"
namespace: str | None = None
access: str | None = None
summary: str | None = None
content_roots: list[dict[str, str]] | None = None
git_init: bool = False
@staticmethod
def from_mapping(data: dict[str, Any]) -> BootstrapAnswers:
return BootstrapAnswers(
name=data["name"],
title=data.get("title", data["name"]),
owners=list(data.get("owners", [])),
repository_type=data["repositoryType"],
lifecycle=data.get("lifecycle", "active"),
namespace=data.get("namespace"),
access=data.get("access"),
summary=data.get("summary"),
content_roots=data.get("contentRoots"),
git_init=bool(data.get("gitInit", False)),
)
def _render_contract(answers: BootstrapAnswers) -> str:
content_roots = answers.content_roots if answers.content_roots is not None else _DEFAULT_CONTENT_ROOTS.get(answers.repository_type, [])
contract: dict[str, Any] = {
"apiVersion": API_VERSION,
"kind": "RepositoryContract",
"metadata": {
"name": answers.name,
"title": answers.title,
"owners": answers.owners,
},
"spec": {
"summary": answers.summary or f"{answers.title} repository",
"repository": {
"type": answers.repository_type,
"lifecycle": answers.lifecycle,
**({"namespace": answers.namespace} if answers.namespace else {}),
**({"access": answers.access} if answers.access else {}),
},
"template": {
"id": TEMPLATE_IDS[answers.repository_type],
"version": TEMPLATE_VERSION,
"source": "repo:repository-stewardship",
"answersRef": "ops/template-answers.yaml",
"mode": "generated",
},
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
"knowledge": {"entrypoint": "kdb/kdb.yaml"},
"contentRoots": content_roots,
},
}
return io.yaml_text(contract)
def _render_kdb(answers: BootstrapAnswers) -> str:
kdb = {
"apiVersion": API_VERSION,
"kind": "KnowledgeBase",
"metadata": {"name": f"{answers.name}-kdb", "title": f"{answers.title} knowledge base"},
"spec": {
"repository": f"repo:{answers.name}",
"defaultLanguage": "en",
"topics": [],
"documents": [],
},
}
return io.yaml_text(kdb)
def render_agents_md(answers: BootstrapAnswers) -> str:
return f"""# Repository instructions
## Purpose
{answers.summary or answers.title}
## Start here
1. Read `ops/contract.yaml` to identify the repository and authoritative content roots.
2. Read the small index in `kdb/kdb.yaml`.
3. Match the task to an exact topic intent.
4. Open only the documents and headings named by that topic's `data.readHints`.
## Safety
- Do not run destructive operations without an approved plan.
- Do not place secrets, tokens or private keys in this repository.
- Use `repoctl validate --repo .` before proposing changes to contract or KDB.
"""
def render_claude_md() -> str:
return """# CLAUDE.md
@AGENTS.md
## Claude-specific guidance
Use `repoctl context` before loading detailed knowledge or running repository operations.
"""
def _render_template_answers(answers: BootstrapAnswers) -> str:
return io.yaml_text(
{
"schema": "stewardship/template-answers@0.1",
"templateId": TEMPLATE_IDS[answers.repository_type],
"templateVersion": TEMPLATE_VERSION,
"name": answers.name,
"title": answers.title,
"owners": answers.owners,
"repositoryType": answers.repository_type,
"lifecycle": answers.lifecycle,
}
)
def _render_gitignore() -> str:
return "ops/runs/\n.venv/\n__pycache__/\n"
def build_bootstrap_plan(answers: BootstrapAnswers) -> dict[str, Any]:
contract_text = _render_contract(answers)
files = [
{"path": "ops/contract.yaml", "content": contract_text},
{"path": "kdb/kdb.yaml", "content": _render_kdb(answers)},
{"path": "AGENTS.md", "content": render_agents_md(answers)},
{"path": "CLAUDE.md", "content": render_claude_md()},
{"path": "ops/template-answers.yaml", "content": _render_template_answers(answers)},
{"path": ".gitignore", "content": _render_gitignore()},
{"path": ".claude/skills/repository-bootstrap/SKILL.md", "content": REPOSITORY_BOOTSTRAP_SKILL},
{"path": ".claude/skills/repository-adoption/SKILL.md", "content": REPOSITORY_ADOPTION_SKILL},
{"path": ".claude/skills/repo-handoff/SKILL.md", "content": REPO_HANDOFF_SKILL},
]
plan: dict[str, Any] = {
"schema": "stewardship/bootstrap-plan@0.1",
"repository": answers.name,
"repositoryType": answers.repository_type,
"createdAt": DEFAULT_CLOCK.now_iso(),
"gitInit": answers.git_init,
"files": files,
"recommendations": [SSH_RECOMMENDATION],
}
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
plan["planHash"] = plan_hash
return plan
def apply_bootstrap_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 ValueError("Plan hash does not match plan content; re-plan before apply")
if approve_hash != plan["planHash"]:
raise ValueError("Approval hash does not match plan hash")
written: list[str] = []
for file_entry in plan["files"]:
target = root / file_entry["path"]
if target.exists():
raise FileExistsError(f"Refusing to overwrite existing file: {file_entry['path']}")
for file_entry in plan["files"]:
target = root / file_entry["path"]
io.write_text_atomic(target, file_entry["content"])
written.append(file_entry["path"])
if plan.get("gitInit") and not (root / ".git").exists():
subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
return written
+334
View File
@@ -0,0 +1,334 @@
"""`repoctl`: thin argparse CLI adapter over the stewardship library.
Exit codes (specification.md 19.2): 0 success, 1 validation/operation failure,
2 invalid invocation/input, 3 repository not found, 4 stale/incomplete strict
context, 5 approval required or denied.
"""
from __future__ import annotations
import argparse
import sys
from pathlib import Path
from typing import Any
from . import adoption, bootstrap, config, discovery, io
from .constants import CONTRACT_PATH
from .context import build_context
from .paths import find_repository_root
from .render import build_envelope, emit
from .schema_loader import validate_against_kind
from .types import Finding
from .validate import validate_repository
EXIT_SUCCESS = 0
EXIT_VALIDATION_FAILURE = 1
EXIT_INVALID_INPUT = 2
EXIT_NOT_FOUND = 3
EXIT_STRICT_INCOMPLETE = 4
EXIT_APPROVAL = 5
class CliError(Exception):
def __init__(self, message: str, exit_code: int = EXIT_INVALID_INPUT):
super().__init__(message)
self.exit_code = exit_code
def _resolve_repo(repo_arg: str | None, roots: list[str] | None) -> Path:
if repo_arg:
candidate = Path(repo_arg).expanduser()
if candidate.exists():
root = find_repository_root(candidate)
if root is None:
raise CliError(f"No .git ancestor found for {candidate}", EXIT_NOT_FOUND)
return root
found, _ = discovery.discover_repositories(config.resolve_roots(roots))
for repo in found:
name = (repo.contract.get("metadata") or {}).get("name")
if name == repo_arg:
return repo.path
raise CliError(f"Repository not found: {repo_arg}", EXIT_NOT_FOUND)
root = find_repository_root(Path.cwd())
if root is None:
raise CliError("No .git ancestor found from current directory", EXIT_NOT_FOUND)
return root
def _write(envelope: dict[str, Any], output: str) -> None:
emit(envelope, output)
def cmd_config(args: argparse.Namespace) -> int:
if args.config_action == "show":
data = config.load_config()
_write(build_envelope("config show", "success", data, []), args.output)
return EXIT_SUCCESS
if args.config_action == "add-root":
data = config.add_root(args.path)
_write(build_envelope("config add-root", "success", data, []), args.output)
return EXIT_SUCCESS
if args.config_action == "remove-root":
data = config.remove_root(args.path)
_write(build_envelope("config remove-root", "success", data, []), args.output)
return EXIT_SUCCESS
raise CliError("Unknown config action")
def cmd_validate(args: argparse.Namespace) -> int:
root = _resolve_repo(args.repo, args.root)
result = validate_repository(root)
outcome = "success" if result.ok else "failure"
data = {"repository": str(root), "valid": result.ok}
_write(build_envelope("validate", outcome, data, result.findings), args.output)
return EXIT_SUCCESS if result.ok else EXIT_VALIDATION_FAILURE
def cmd_discover(args: argparse.Namespace) -> int:
roots = config.resolve_roots(args.root)
catalog, findings = discovery.build_catalog_index(roots)
has_error = any(f.severity == "error" for f in findings)
_write(build_envelope("discover", "failure" if has_error else "success", catalog, findings), args.output)
return EXIT_VALIDATION_FAILURE if has_error else EXIT_SUCCESS
def cmd_describe(args: argparse.Namespace) -> int:
root = _resolve_repo(args.repo, args.root)
contract_path = root / CONTRACT_PATH
if not contract_path.exists():
raise CliError(f"{CONTRACT_PATH} not found under {root}", EXIT_NOT_FOUND)
contract = io.load_yaml(contract_path)
errors = validate_against_kind("RepositoryContract", contract) if isinstance(contract, dict) else ["not a mapping"]
findings = [Finding("error", "CONTRACT_SCHEMA_INVALID", e) for e in errors]
outcome = "failure" if findings else "success"
_write(build_envelope("describe", outcome, contract, findings), args.output)
return EXIT_VALIDATION_FAILURE if findings else EXIT_SUCCESS
def cmd_context(args: argparse.Namespace) -> int:
root = _resolve_repo(args.repo, args.root)
result = build_context(
root,
args.intent,
include_related=args.include_related,
materialize=args.materialize,
budget_bytes=args.budget_bytes,
strict=args.strict,
)
data = dict(result.bundle)
if result.materialized:
data["spec"] = dict(data["spec"])
data["spec"]["materializedContent"] = [
{"document": m.document_id, "path": m.path, "bytes": m.bytes_used, "content": m.content}
for m in result.materialized
]
findings = [
Finding(w.split(":", 2)[0], w.split(":", 2)[1], w.split(":", 2)[2])
for w in result.bundle["spec"]["warnings"]
]
outcome = "success"
exit_code = EXIT_SUCCESS
if result.truncated and args.strict:
outcome = "failure"
exit_code = EXIT_STRICT_INCOMPLETE
_write(build_envelope("context", outcome, data, findings), args.output)
return exit_code
def cmd_init(args: argparse.Namespace) -> int:
repo_path = Path(args.repo).expanduser()
if args.apply:
if not args.plan or not args.approve:
raise CliError("--apply requires --plan and --approve", EXIT_INVALID_INPUT)
plan = io.load_yaml(Path(args.plan))
repo_path.mkdir(parents=True, exist_ok=True)
try:
written = bootstrap.apply_bootstrap_plan(repo_path, plan, args.approve)
except ValueError as exc:
_write(build_envelope("init apply", "failure", None, [Finding("error", "APPROVAL_FAILED", str(exc))]), args.output)
return EXIT_APPROVAL
except FileExistsError as exc:
_write(build_envelope("init apply", "failure", None, [Finding("error", "ADOPT_PATH_COLLISION", str(exc))]), args.output)
return EXIT_VALIDATION_FAILURE
_write(build_envelope("init apply", "success", {"written": written}, []), args.output)
return EXIT_SUCCESS
if args.answers:
answers_data = io.load_yaml(Path(args.answers))
else:
answers_data = {}
if args.name:
answers_data["name"] = args.name
if args.type:
answers_data["repositoryType"] = args.type
if args.title:
answers_data["title"] = args.title
if args.owner:
answers_data["owners"] = list(args.owner)
if args.lifecycle:
answers_data["lifecycle"] = args.lifecycle
if args.git_init:
answers_data["gitInit"] = True
missing = [f for f in ("name", "repositoryType") if f not in answers_data]
if missing:
raise CliError(f"Missing required answers: {', '.join(missing)}", EXIT_INVALID_INPUT)
answers = bootstrap.BootstrapAnswers.from_mapping(answers_data)
plan = bootstrap.build_bootstrap_plan(answers)
_write(build_envelope("init plan", "success", plan, []), args.output)
return EXIT_SUCCESS
def cmd_adopt(args: argparse.Namespace) -> int:
repo_path = Path(args.repo).expanduser()
if not repo_path.exists():
raise CliError(f"Path does not exist: {repo_path}", EXIT_NOT_FOUND)
if args.mode == "assess":
result = adoption.assess(repo_path)
findings = [
Finding(f["severity"], f["code"], f.get("message", f["code"]), path=f.get("path"))
for f in result["findings"]
]
blocker = any(f.severity == "error" for f in findings)
_write(build_envelope("adopt assess", "failure" if blocker else "success", result, findings), args.output)
return EXIT_VALIDATION_FAILURE if blocker else EXIT_SUCCESS
if args.mode == "plan":
assessment = adoption.assess(repo_path)
if args.answers:
answers = io.load_yaml(Path(args.answers))
else:
answers = {}
name = answers.get("name") or repo_path.name.lower()
plan = adoption.build_plan(
repo_path,
assessment,
confirmed_name=name,
confirmed_title=answers.get("title"),
confirmed_owners=answers.get("owners"),
confirmed_lifecycle=answers.get("lifecycle", "active"),
strategy=args.strategy,
)
_write(build_envelope("adopt plan", "success", plan, []), args.output)
return EXIT_SUCCESS
if args.mode == "apply":
if not args.plan or not args.approve:
raise CliError("--mode apply requires --plan and --approve", EXIT_INVALID_INPUT)
plan = io.load_yaml(Path(args.plan))
try:
written = adoption.apply_plan(repo_path, plan, args.approve)
except ValueError as exc:
code = "APPROVAL_FAILED" if "Approval" in str(exc) or "hash" in str(exc) else "ADOPT_BASELINE_CHANGED"
_write(build_envelope("adopt apply", "failure", None, [Finding("error", code, str(exc))]), args.output)
return EXIT_APPROVAL
except FileExistsError as exc:
_write(build_envelope("adopt apply", "failure", None, [Finding("error", "ADOPT_PATH_COLLISION", str(exc))]), args.output)
return EXIT_VALIDATION_FAILURE
_write(build_envelope("adopt apply", "success", {"written": written}, []), args.output)
return EXIT_SUCCESS
if args.mode == "verify":
verify_plan = io.load_yaml(Path(args.plan)) if args.plan else None
report = adoption.verify(repo_path, verify_plan)
outcome = "failure" if report["outcome"] == "fail" else "success"
_write(build_envelope("adopt verify", outcome, report, []), args.output)
return EXIT_VALIDATION_FAILURE if report["outcome"] == "fail" else EXIT_SUCCESS
raise CliError(f"Unknown adopt mode: {args.mode}", EXIT_INVALID_INPUT)
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="repoctl", description="Repository Stewardship CLI")
sub = parser.add_subparsers(dest="command", required=True)
def add_common(p: argparse.ArgumentParser) -> None:
p.add_argument("--output", choices=["human", "yaml", "json"], default="human")
p_config = sub.add_parser("config")
add_common(p_config)
config_sub = p_config.add_subparsers(dest="config_action", required=True)
config_sub.add_parser("show")
p_add_root = config_sub.add_parser("add-root")
p_add_root.add_argument("path")
p_remove_root = config_sub.add_parser("remove-root")
p_remove_root.add_argument("path")
p_config.set_defaults(func=cmd_config)
p_validate = sub.add_parser("validate")
add_common(p_validate)
p_validate.add_argument("--repo")
p_validate.add_argument("--root", action="append")
p_validate.set_defaults(func=cmd_validate)
p_discover = sub.add_parser("discover")
add_common(p_discover)
p_discover.add_argument("--root", action="append")
p_discover.set_defaults(func=cmd_discover)
p_describe = sub.add_parser("describe")
add_common(p_describe)
p_describe.add_argument("--repo")
p_describe.add_argument("--root", action="append")
p_describe.set_defaults(func=cmd_describe)
p_context = sub.add_parser("context")
add_common(p_context)
p_context.add_argument("--repo")
p_context.add_argument("--root", action="append")
p_context.add_argument("--intent", required=True)
p_context.add_argument("--include-related", action="store_true")
p_context.add_argument("--materialize", action="store_true")
p_context.add_argument("--budget-bytes", type=int, default=None)
p_context.add_argument("--strict", action="store_true")
p_context.set_defaults(func=cmd_context)
p_init = sub.add_parser("init")
add_common(p_init)
p_init.add_argument("--repo", required=True)
p_init.add_argument("--answers")
p_init.add_argument("--name")
p_init.add_argument("--type", dest="type", choices=["infrastructure-config", "service-config", "software", "project"])
p_init.add_argument("--title")
p_init.add_argument("--owner", action="append")
p_init.add_argument("--lifecycle")
p_init.add_argument("--git-init", action="store_true")
p_init.add_argument("--no-git-init", dest="git_init", action="store_false")
p_init.set_defaults(git_init=None)
p_init.add_argument("--apply", action="store_true")
p_init.add_argument("--plan")
p_init.add_argument("--approve")
p_init.set_defaults(func=cmd_init)
p_adopt = sub.add_parser("adopt")
add_common(p_adopt)
p_adopt.add_argument("--repo", required=True)
p_adopt.add_argument("--mode", required=True, choices=["assess", "plan", "apply", "verify"])
p_adopt.add_argument("--answers")
p_adopt.add_argument("--strategy", default="overlay", choices=["overlay", "normalize"])
p_adopt.add_argument("--recipe")
p_adopt.add_argument("--plan")
p_adopt.add_argument("--approve")
p_adopt.set_defaults(func=cmd_adopt)
return parser
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
try:
result: int = args.func(args)
return result
except CliError as exc:
print(f"ERROR: {exc}", file=sys.stderr)
return exc.exit_code
except Exception as exc: # noqa: BLE001 - top-level CLI safety net
print(f"ERROR: {exc}", file=sys.stderr)
return EXIT_VALIDATION_FAILURE
if __name__ == "__main__":
raise SystemExit(main())
+20
View File
@@ -0,0 +1,20 @@
"""Deterministic time source so machine output is reproducible in tests."""
from __future__ import annotations
import os
from datetime import UTC, datetime
class Clock:
def now(self) -> datetime:
override = os.environ.get("REPOCTL_CLOCK_UTC")
if override:
return datetime.fromisoformat(override).replace(tzinfo=UTC)
return datetime.now(UTC)
def now_iso(self) -> str:
return self.now().replace(microsecond=0).isoformat().replace("+00:00", "Z")
DEFAULT_CLOCK = Clock()
+75
View File
@@ -0,0 +1,75 @@
"""User configuration: repository root list used to resolve `--repo NAME`.
Resolution order (per docs/PLAN.md): explicit --root flags -> REPOCTL_ROOTS env ->
user config -> current repository as a last-resort fallback. Config is only ever
changed by explicit `config add-root` / `config remove-root`; no hidden cache.
"""
from __future__ import annotations
import os
import platform
from pathlib import Path
from typing import Any
from . import io
from .constants import CONFIG_SCHEMA
def config_path() -> Path:
override = os.environ.get("REPOCTL_CONFIG_PATH")
if override:
return Path(override)
if platform.system() == "Windows":
base = os.environ.get("APPDATA")
root = Path(base) if base else Path.home() / "AppData" / "Roaming"
return root / "RepositoryStewardship" / "config.yaml"
xdg = os.environ.get("XDG_CONFIG_HOME")
root = Path(xdg) if xdg else Path.home() / ".config"
return root / "repository-stewardship" / "config.yaml"
def load_config() -> dict[str, Any]:
path = config_path()
if not path.exists():
return {"schema": CONFIG_SCHEMA, "roots": []}
data = io.load_yaml(path)
if not isinstance(data, dict):
raise TypeError(f"Config at {path} is not a mapping")
data.setdefault("schema", CONFIG_SCHEMA)
data.setdefault("roots", [])
return data
def save_config(data: dict[str, Any]) -> None:
path = config_path()
io.write_text_atomic(path, io.yaml_text(data))
def add_root(root: str) -> dict[str, Any]:
data = load_config()
normalized = str(Path(root).expanduser())
roots = list(dict.fromkeys([*data.get("roots", []), normalized]))
data["roots"] = roots
save_config(data)
return data
def remove_root(root: str) -> dict[str, Any]:
data = load_config()
normalized = str(Path(root).expanduser())
data["roots"] = [item for item in data.get("roots", []) if item != normalized]
save_config(data)
return data
def resolve_roots(cli_roots: list[str] | None) -> list[Path]:
if cli_roots:
return [Path(item).expanduser() for item in cli_roots]
env_roots = os.environ.get("REPOCTL_ROOTS")
if env_roots:
return [Path(item).expanduser() for item in env_roots.split(os.pathsep) if item]
configured = load_config().get("roots", [])
if configured:
return [Path(item).expanduser() for item in configured]
return [Path.cwd()]
+19
View File
@@ -0,0 +1,19 @@
from __future__ import annotations
API_VERSION = "stewardship.corsus.ru/v1alpha1"
CONTRACT_PATH = "ops/contract.yaml"
DEFAULT_KDB_PATH = "kdb/kdb.yaml"
CONFIG_SCHEMA = "stewardship/repoctl-config@0.1"
RESULT_SCHEMA = "stewardship/repoctl-result@0.1"
ID_PATTERN = r"^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$"
REPOSITORY_TYPES = {"infrastructure-config", "service-config", "software", "project"}
LIFECYCLES = {"production", "active", "experimental", "stub", "archive", "external"}
ACCESS_VALUES = {"public", "internal", "restricted"}
CONTENT_KINDS = {"directory", "file", "file-set", "manifest"}
AUTHORITIES = {"source", "generated", "observed", "mirror", "evidence"}
WRITE_POLICIES = {"managed", "read-only", "generated"}
DOCUMENT_AUTHORITIES = {"vendor", "local-canonical", "observed", "derived", "manual"}
DOCUMENT_STATUSES = {"verified", "manual", "draft", "stale"}
DOCUMENT_ROLES = {"tutorial", "how-to", "reference", "explanation", "runbook", "vendor-source", "evidence"}
SECRET_KEYS = {"password", "token", "privatekey", "secretvalue"}
+149
View File
@@ -0,0 +1,149 @@
"""`repoctl context`: deterministic, budgeted, intent-scoped ContextBundle selection."""
from __future__ import annotations
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from .clock import DEFAULT_CLOCK
from .io import file_sha256
from .validate import validate_repository
@dataclass
class MaterializedItem:
document_id: str
path: str
bytes_used: int
content: str
@dataclass
class ContextResult:
bundle: dict[str, Any]
materialized: list[MaterializedItem] = field(default_factory=list)
truncated: bool = False
def build_context(
root: Path,
intent: str,
*,
include_related: bool = False,
materialize: bool = False,
budget_bytes: int | None = None,
strict: bool = False,
) -> ContextResult:
validation = validate_repository(root)
warnings: list[str] = [f"{f.severity}:{f.code}:{f.message}" for f in validation.findings if f.severity != "info"]
contract = validation.contract or {}
metadata = contract.get("metadata", {}) or {}
spec = contract.get("spec", {}) or {}
repo_name = metadata.get("name", "unknown")
contract_revision = file_sha256(root / "ops/contract.yaml") if (root / "ops/contract.yaml").exists() else None
operations = [
f"operation:{repo_name}/{op.get('id')}"
for op in spec.get("operations") or []
if isinstance(op, dict) and intent in (op.get("intents") or [])
]
content_roots = [
cr["id"] for cr in spec.get("contentRoots") or [] if isinstance(cr, dict) and cr.get("id")
]
topics_selected: list[dict[str, Any]] = []
document_ids: list[str] = []
kdb = validation.kdb or {}
kdb_spec = kdb.get("spec", {}) if isinstance(kdb.get("spec"), dict) else {}
all_topics = kdb_spec.get("topics") or []
all_documents = {d.get("id"): d for d in (kdb_spec.get("documents") or []) if isinstance(d, dict)}
matched = [t for t in all_topics if isinstance(t, dict) and intent in (t.get("intents") or [])]
matched.sort(key=lambda t: (-(t.get("priority") or 50), t.get("id") or ""))
topics_selected.extend(matched)
if include_related:
related_ids: set[str] = set()
for topic in matched:
related_ids.update(topic.get("relatedTopics") or [])
for topic in all_topics:
if isinstance(topic, dict) and topic.get("id") in related_ids:
topics_selected.append(topic)
seen_docs: set[str] = set()
for topic in topics_selected:
for doc_id in topic.get("documents") or []:
if doc_id in seen_docs:
continue
seen_docs.add(doc_id)
document_ids.append(doc_id)
doc = all_documents.get(doc_id)
if doc is None:
warnings.append(f"warning:CONTEXT_DOCUMENT_MISSING:Referenced document not found: {doc_id}")
elif doc.get("status") == "stale":
warnings.append(f"warning:CONTEXT_DOCUMENT_STALE:Document authored status is stale: {doc_id}")
topics_ref = sorted(f"topic:{repo_name}/{t.get('id')}" for t in topics_selected if t.get("id"))
operations = sorted(set(operations))
content_roots = sorted(set(content_roots))
document_ids = sorted(set(document_ids))
bundle_name = f"{repo_name}-{intent.replace('.', '-')}"
bundle: dict[str, Any] = {
"apiVersion": "stewardship.corsus.ru/v1alpha1",
"kind": "ContextBundle",
"metadata": {"name": bundle_name},
"spec": {
"generatedAt": DEFAULT_CLOCK.now_iso(),
"intent": intent,
"repository": f"repo:{repo_name}",
"summary": spec.get("summary", ""),
"contentRoots": content_roots,
"operations": operations,
"topics": topics_ref,
"documents": document_ids,
"warnings": warnings,
},
}
if contract_revision:
bundle["spec"]["contractRevision"] = contract_revision
result = ContextResult(bundle=bundle)
if materialize:
remaining = budget_bytes if budget_bytes is not None else None
materialized_items = []
truncated = False
for doc_id in document_ids:
doc = all_documents.get(doc_id)
if not doc or not doc.get("path"):
continue
doc_path = root / doc["path"]
if not doc_path.exists():
continue
content = doc_path.read_text(encoding="utf-8")
content_bytes = content.encode("utf-8")
if remaining is not None:
if len(content_bytes) > remaining:
truncated = True
if remaining <= 0:
continue
content_bytes = content_bytes[:remaining]
content = content_bytes.decode("utf-8", errors="ignore")
remaining -= len(content_bytes)
materialized_items.append(
MaterializedItem(document_id=doc_id, path=doc["path"], bytes_used=len(content_bytes), content=content)
)
result.materialized = materialized_items
result.truncated = truncated
bundle["spec"]["materialized"] = [
{"document": item.document_id, "path": item.path, "bytes": item.bytes_used} for item in materialized_items
]
if truncated:
bundle["spec"]["warnings"].append("warning:CONTEXT_BUDGET_TRUNCATED:Materialized content truncated to fit budget")
return result
+151
View File
@@ -0,0 +1,151 @@
"""`repoctl discover`: find `ops/contract.yaml` under roots and build a CatalogIndex."""
from __future__ import annotations
from collections.abc import Iterator
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from .clock import DEFAULT_CLOCK
from .constants import CONTRACT_PATH
from .io import file_sha256
from .types import Finding, sort_findings
from .validate import validate_repository
_SKIP_DIR_NAMES = {
".git",
".venv",
"venv",
"node_modules",
"__pycache__",
".mypy_cache",
".pytest_cache",
".ruff_cache",
".tox",
"dist",
"build",
".eggs",
"site-packages",
}
@dataclass
class DiscoveredRepository:
path: Path
contract: dict[str, Any]
contract_hash: str
def _iter_contract_dirs(root: Path) -> Iterator[Path]:
root = root.resolve()
if not root.exists():
return
stack = [root]
while stack:
current = stack.pop()
try:
entries = sorted(current.iterdir(), key=lambda p: p.name)
except OSError:
continue
if (current / CONTRACT_PATH.split("/")[0] / CONTRACT_PATH.split("/")[1]).exists():
yield current
for entry in entries:
if not entry.is_dir():
continue
if entry.is_symlink():
continue
if entry.name in _SKIP_DIR_NAMES:
continue
stack.append(entry)
def discover_repositories(roots: list[Path]) -> tuple[list[DiscoveredRepository], list[Finding]]:
findings: list[Finding] = []
found: list[DiscoveredRepository] = []
seen_paths: set[Path] = set()
for root in roots:
for repo_dir in _iter_contract_dirs(root):
resolved = repo_dir.resolve()
if resolved in seen_paths:
continue
seen_paths.add(resolved)
validation = validate_repository(repo_dir)
if validation.contract is None:
findings.extend(validation.findings)
continue
findings.extend(validation.findings)
contract_hash = file_sha256(repo_dir / CONTRACT_PATH)
found.append(DiscoveredRepository(repo_dir, validation.contract, contract_hash))
found.sort(key=lambda item: item.path.as_posix())
return found, findings
def build_catalog_index(roots: list[Path]) -> tuple[dict[str, Any], list[Finding]]:
repositories, findings = discover_repositories(roots)
seen_names: dict[str, Path] = {}
entries = []
relations: list[dict[str, str]] = []
by_name: dict[str, dict[str, Any]] = {}
for repo in repositories:
metadata = repo.contract.get("metadata", {}) or {}
name = metadata.get("name")
spec = repo.contract.get("spec", {}) or {}
repository_info = spec.get("repository", {}) or {}
if not name:
findings.append(Finding("error", "CATALOG_REPOSITORY_NAME_MISSING", "Contract has no metadata.name", path=str(repo.path)))
continue
if name in seen_names:
findings.append(
Finding(
"error",
"CATALOG_DUPLICATE_REPOSITORY_NAME",
f"Repository name {name!r} is used by both {seen_names[name]} and {repo.path}",
resource=f"repo:{name}",
)
)
continue
seen_names[name] = repo.path
entry = {
"ref": f"repo:{name}",
"path": repo.path.as_posix(),
"type": repository_info.get("type", "unknown"),
"lifecycle": repository_info.get("lifecycle", "unknown"),
"contractHash": repo.contract_hash,
}
entries.append(entry)
by_name[name] = repo.contract
for name, contract in by_name.items():
spec = contract.get("spec", {}) or {}
for cap in spec.get("provides") or []:
relations.append({"from": f"repo:{name}", "type": "provides", "to": f"capability:{name}/{cap.get('id')}"})
for req in spec.get("requires") or []:
req_ref = f"requirement:{name}/{req.get('id')}"
relations.append({"from": f"repo:{name}", "type": "requires", "to": req_ref})
for other_name, other_contract in by_name.items():
for cap in (other_contract.get("spec", {}) or {}).get("provides") or []:
if cap.get("capability") == req.get("capability"):
relations.append({"from": req_ref, "type": "matches", "to": f"capability:{other_name}/{cap.get('id')}"})
for binding in spec.get("bindings") or []:
binding_ref = f"binding:{name}/{binding.get('id')}"
requirement_ref = binding.get("requirement", "")
relations.append({"from": binding_ref, "type": "fulfills", "to": requirement_ref})
entries.sort(key=lambda e: e["ref"])
relations.sort(key=lambda r: (r["from"], r["type"], r["to"]))
catalog = {
"apiVersion": "stewardship.corsus.ru/v1alpha1",
"kind": "CatalogIndex",
"metadata": {"name": "local-git-catalog"},
"spec": {
"generatedAt": DEFAULT_CLOCK.now_iso(),
"roots": [str(r) for r in roots],
"repositories": entries,
"relations": relations,
},
}
return catalog, sort_findings(findings)
+35
View File
@@ -0,0 +1,35 @@
"""Minimal read-only Git helpers used by adoption assess/plan/apply/verify.
Adoption never commits, pushes, clones or touches remotes; these helpers only ever
call read-only `git` subcommands, plus `git init` for `repoctl init --git-init`.
"""
from __future__ import annotations
import subprocess
from pathlib import Path
def _run(args: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
return subprocess.run(
["git", *args], cwd=cwd, capture_output=True, text=True, check=False
)
def head_revision(root: Path) -> str:
result = _run(["rev-parse", "HEAD"], root)
if result.returncode != 0:
return "unborn"
return result.stdout.strip()
def is_dirty(root: Path) -> bool:
result = _run(["status", "--porcelain"], root)
return bool(result.stdout.strip())
def tracked_files(root: Path) -> set[str]:
result = _run(["ls-files"], root)
if result.returncode != 0:
return set()
return {line.strip() for line in result.stdout.splitlines() if line.strip()}
+86
View File
@@ -0,0 +1,86 @@
from __future__ import annotations
import hashlib
import json
from pathlib import Path
from typing import Any
from ruamel.yaml import YAML
from ruamel.yaml.error import YAMLError
class ResourceError(ValueError):
"""Input cannot be safely parsed as an expected resource."""
def _safe_yaml() -> YAML:
yaml = YAML(typ="safe", pure=True)
yaml.allow_duplicate_keys = False
return yaml
def _output_yaml() -> YAML:
yaml = YAML()
yaml.default_flow_style = False
yaml.allow_unicode = True
yaml.indent(mapping=2, sequence=4, offset=2)
return yaml
def load_yaml(path: Path) -> Any:
try:
with path.open("r", encoding="utf-8") as handle:
return _safe_yaml().load(handle)
except (OSError, YAMLError) as exc:
raise ResourceError(f"Cannot parse YAML: {exc}") from exc
def yaml_text(data: Any) -> str:
from io import StringIO
stream = StringIO()
_output_yaml().dump(data, stream)
return stream.getvalue()
def primitive(value: Any) -> Any:
if isinstance(value, dict):
return {str(key): primitive(item) for key, item in value.items()}
if isinstance(value, (list, tuple)):
return [primitive(item) for item in value]
if hasattr(value, "isoformat") and not isinstance(value, str):
return value.isoformat()
return value
def canonical_json(value: Any) -> str:
return json.dumps(primitive(value), ensure_ascii=False, sort_keys=True, separators=(",", ":"))
def sha256(value: Any) -> str:
return "sha256:" + hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
def file_sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(chunk)
return "sha256:" + digest.hexdigest()
def write_text_atomic(path: Path, content: str) -> None:
"""Write ``content`` to ``path`` via a temp file in the same directory, then replace.
Uses ``\\n`` line endings unconditionally so hashes and diffs are platform independent.
"""
path.parent.mkdir(parents=True, exist_ok=True)
normalized = content.replace("\r\n", "\n")
tmp = path.parent / f".{path.name}.repoctl-tmp"
with tmp.open("w", encoding="utf-8", newline="\n") as handle:
handle.write(normalized)
tmp.replace(path)
def dump_json(value: Any) -> str:
return json.dumps(primitive(value), ensure_ascii=False, indent=2, sort_keys=False) + "\n"
+176
View File
@@ -0,0 +1,176 @@
"""Lightweight Markdown structural checks: frontmatter, fenced YAML/Mermaid, local links.
This module never executes Markdown or fetches remote resources; it is purely static.
"""
from __future__ import annotations
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from .io import ResourceError
from .types import Finding
_FENCE_RE = re.compile(r"^(```+|~~~+)(\S*)\s*$")
_LINK_RE = re.compile(r"(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
_MERMAID_HEADERS = {
"flowchart",
"graph",
"sequenceDiagram",
"stateDiagram-v2",
"stateDiagram",
"classDiagram",
"erDiagram",
"gantt",
"pie",
"journey",
"mindmap",
"timeline",
}
@dataclass
class MarkdownCheckResult:
findings: list[Finding]
def check_markdown_file(repo_root: Path, rel_path: str) -> list[Finding]:
findings: list[Finding] = []
full_path = repo_root / rel_path
try:
text = full_path.read_text(encoding="utf-8")
except OSError as exc:
return [Finding("error", "MARKDOWN_UNREADABLE", str(exc), path=rel_path)]
findings.extend(_check_frontmatter(text, rel_path))
findings.extend(_check_fences(text, rel_path))
findings.extend(_check_local_links(repo_root, rel_path, text))
return findings
def _check_frontmatter(text: str, rel_path: str) -> list[Finding]:
findings: list[Finding] = []
if text.startswith("---\n"):
end = text.find("\n---", 4)
if end == -1:
return [
Finding(
"error",
"MARKDOWN_FRONTMATTER_UNTERMINATED",
"Frontmatter block is not closed with '---'",
path=rel_path,
)
]
block = text[4:end]
try:
load_yaml_text(block)
except ResourceError as exc:
findings.append(
Finding("error", "MARKDOWN_FRONTMATTER_INVALID_YAML", str(exc), path=rel_path)
)
return findings
def load_yaml_text(text: str) -> Any:
from io import StringIO
from ruamel.yaml import YAML
from ruamel.yaml.error import YAMLError
yaml = YAML(typ="safe", pure=True)
try:
return yaml.load(StringIO(text))
except YAMLError as exc:
raise ResourceError(str(exc)) from exc
def _check_fences(text: str, rel_path: str) -> list[Finding]:
findings: list[Finding] = []
stack: list[tuple[str, int]] = []
lines = text.splitlines()
fence_blocks: list[tuple[int, int, str]] = []
for lineno, line in enumerate(lines, start=1):
match = _FENCE_RE.match(line)
if not match:
continue
marker, info = match.groups()
if stack and stack[-1][0][0] == marker[0]:
_open_marker, open_line = stack.pop()
fence_blocks.append((open_line, lineno, info))
else:
stack.append((marker, lineno))
for marker, lineno in stack:
findings.append(
Finding(
"error",
"MARKDOWN_FENCE_UNBALANCED",
f"Unclosed code fence opened at line {lineno}",
path=rel_path,
)
)
for start, end, info in fence_blocks:
lang = info.strip().lower()
body = "\n".join(lines[start:end - 1])
if lang == "yaml":
try:
load_yaml_text(body)
except ResourceError as exc:
findings.append(
Finding(
"error",
"MARKDOWN_YAML_FENCE_INVALID",
f"Fenced YAML block at line {start} is invalid: {exc}",
path=rel_path,
)
)
elif lang == "mermaid":
head = body.strip().splitlines()[0].strip() if body.strip() else ""
head_token = head.split()[0] if head else ""
if head_token not in _MERMAID_HEADERS:
findings.append(
Finding(
"warning",
"MARKDOWN_MERMAID_HEADER_UNKNOWN",
f"Mermaid block at line {start} has an unrecognized diagram header: {head_token!r}",
path=rel_path,
)
)
return findings
def _check_local_links(repo_root: Path, rel_path: str, text: str) -> list[Finding]:
findings: list[Finding] = []
base_dir = (repo_root / rel_path).parent
for match in _LINK_RE.finditer(text):
target = match.group(1)
if target.startswith(("http://", "https://", "mailto:", "#")):
continue
target_path_part = target.split("#", 1)[0]
if not target_path_part:
continue
candidate = (base_dir / target_path_part).resolve()
try:
candidate.relative_to(repo_root.resolve())
except ValueError:
findings.append(
Finding(
"warning",
"MARKDOWN_LINK_OUTSIDE_REPOSITORY",
f"Link target resolves outside repository root: {target}",
path=rel_path,
)
)
continue
if not candidate.exists():
findings.append(
Finding(
"error",
"MARKDOWN_LINK_TARGET_MISSING",
f"Local link target does not exist: {target}",
path=rel_path,
)
)
return findings
+51
View File
@@ -0,0 +1,51 @@
from __future__ import annotations
import os
from pathlib import Path
class PathViolation(ValueError):
"""A resource path escapes the repository boundary."""
def normalize_resource_path(value: str) -> str:
if not value or not isinstance(value, str):
raise PathViolation("Path must be a non-empty string")
if "\\" in value or value.startswith(("/", "\\")) or ":" in value.split("/")[0]:
raise PathViolation("Path must be repository-relative and use '/' separators")
parts = value.split("/")
if any(part in {"", ".", ".."} for part in parts):
raise PathViolation("Path contains an unsafe segment")
return "/".join(parts)
def confined_path(root: Path, value: str, *, must_exist: bool = False) -> Path:
normalized = normalize_resource_path(value)
root_resolved = root.resolve(strict=True)
candidate = root_resolved.joinpath(*normalized.split("/"))
probe = candidate if candidate.exists() else candidate.parent
try:
probe.resolve(strict=True).relative_to(root_resolved)
except ValueError as exc:
raise PathViolation("Path resolves outside repository root") from exc
if must_exist and not candidate.exists():
raise PathViolation("Path does not exist")
return candidate
def find_repository_root(path: Path) -> Path | None:
current = path.resolve()
if current.is_file():
current = current.parent
for candidate in (current, *current.parents):
if (candidate / ".git").exists():
return candidate
return None
def display_path(path: Path) -> str:
return path.as_posix()
def split_roots(value: str) -> list[Path]:
return [Path(item).expanduser() for item in value.split(os.pathsep) if item]
+48
View File
@@ -0,0 +1,48 @@
"""Render the `stewardship/repoctl-result@0.1` envelope as human, YAML or JSON output."""
from __future__ import annotations
import sys
from collections.abc import Callable
from typing import Any
from .constants import RESULT_SCHEMA
from .io import dump_json, yaml_text
from .types import Finding
def build_envelope(command: str, outcome: str, data: Any, findings: list[Finding]) -> dict[str, Any]:
return {
"schema": RESULT_SCHEMA,
"command": command,
"outcome": outcome,
"data": data,
"findings": [f.to_dict() for f in findings],
}
def print_findings_human(findings: list[Finding]) -> None:
for finding in findings:
location = f" [{finding.resource}]" if finding.resource else ""
path = f" ({finding.path})" if finding.path else ""
print(f"{finding.severity.upper()} {finding.code}{location}{path}: {finding.message}", file=sys.stderr)
def emit(
envelope: dict[str, Any],
output: str,
human_renderer: Callable[[dict[str, Any]], None] | None = None,
) -> None:
if output == "json":
sys.stdout.write(dump_json(envelope))
elif output == "yaml":
sys.stdout.write(yaml_text(envelope))
else:
for finding in envelope["findings"]:
location = f" [{finding['resource']}]" if finding.get("resource") else ""
path = f" ({finding['path']})" if finding.get("path") else ""
print(f"{finding['severity'].upper()} {finding['code']}{location}{path}: {finding['message']}", file=sys.stderr)
if human_renderer is not None:
human_renderer(envelope)
else:
print(f"{envelope['command']}: {envelope['outcome']}")
+83
View File
@@ -0,0 +1,83 @@
"""Load bundled JSON Schemas (Draft 2020-12) as package resources and validate resources.
Unknown-field rejection follows specification.md 22.2: fields prefixed with ``x-`` are an
open extension point and MUST be preserved by consumers, so they are stripped from a
working copy before schema validation and are never treated as "unknown normative fields".
``metadata.annotations`` is already an open object in the schemas and needs no stripping.
"""
from __future__ import annotations
import json
from copy import deepcopy
from functools import cache
from importlib import resources
from typing import Any
import jsonschema
_SCHEMA_FILES = {
"RepositoryContract": "repository-contract.schema.json",
"KnowledgeBase": "knowledge-base.schema.json",
"CatalogIndex": "catalog-index.schema.json",
"ContextBundle": "context-bundle.schema.json",
"RepoctlResult": "result-envelope.schema.json",
"RepoctlUserConfig": "user-config.schema.json",
"BootstrapPlan": "bootstrap-plan.schema.json",
"AdoptionAssessment": "adoption-assessment.schema.json",
"AdoptionPlan": "adoption-plan.schema.json",
"AdoptionReport": "adoption-report.schema.json",
}
class SchemaValidationError(ValueError):
def __init__(self, errors: list[str]):
super().__init__("; ".join(errors))
self.errors = errors
@cache
def _load_schema(filename: str) -> dict[str, Any]:
package = resources.files("stewardship")
with resources.as_file(package.joinpath("schemas").joinpath(filename)) as path:
loaded: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
return loaded
def _strip_extensions(value: Any) -> Any:
if isinstance(value, dict):
return {
key: _strip_extensions(item)
for key, item in value.items()
if not (isinstance(key, str) and key.startswith("x-"))
}
if isinstance(value, list):
return [_strip_extensions(item) for item in value]
return value
def schema_for_kind(kind: str) -> dict[str, Any]:
filename = _SCHEMA_FILES.get(kind)
if filename is None:
raise KeyError(f"No bundled schema for kind {kind!r}")
return _load_schema(filename)
def validate_against_kind(kind: str, data: dict[str, Any]) -> list[str]:
"""Return a list of human-readable schema validation error messages (empty if valid)."""
schema = schema_for_kind(kind)
working = _strip_extensions(deepcopy(data))
validator_cls = jsonschema.validators.validator_for(schema)
validator_cls.check_schema(schema)
validator = validator_cls(schema)
errors = []
for error in sorted(validator.iter_errors(working), key=lambda e: list(e.absolute_path)):
location = "/".join(str(part) for part in error.absolute_path) or "<root>"
errors.append(f"{location}: {error.message}")
return errors
def validate_against_kind_strict(kind: str, data: dict[str, Any]) -> None:
errors = validate_against_kind(kind, data)
if errors:
raise SchemaValidationError(errors)
@@ -0,0 +1,84 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/adoption-assessment.schema.json",
"title": "AdoptionAssessment",
"type": "object",
"required": ["schema", "repository", "classification", "entrypoints", "knowledge", "proposedContentRoots", "collisions", "findings", "questions"],
"additionalProperties": false,
"properties": {
"schema": { "const": "stewardship/adoption-assessment@0.1" },
"repository": {
"type": "object",
"required": ["path", "baselineRevision", "dirty"],
"additionalProperties": false,
"properties": {
"path": { "type": "string" },
"baselineRevision": { "type": "string" },
"dirty": { "type": "boolean" }
}
},
"classification": {
"type": "object",
"required": ["proposedType", "confidence", "evidence", "confirmationRequired"],
"additionalProperties": false,
"properties": {
"proposedType": { "type": "string" },
"confidence": { "enum": ["low", "medium", "high"] },
"evidence": { "type": "array", "items": { "type": "string" } },
"confirmationRequired": { "type": "boolean" }
}
},
"entrypoints": {
"type": "object",
"additionalProperties": false,
"properties": {
"claude": { "type": ["string", "null"] },
"portable": { "type": ["string", "null"] },
"canonicalDirection": { "type": "string" }
}
},
"knowledge": {
"type": "array",
"items": {
"type": "object",
"required": ["path", "format", "action"],
"additionalProperties": false,
"properties": {
"path": { "type": "string" },
"format": { "type": "string" },
"action": { "type": "string" }
}
}
},
"proposedContentRoots": {
"type": "array",
"items": {
"type": "object",
"required": ["id", "path", "role", "authority"],
"additionalProperties": false,
"properties": {
"id": { "type": "string" },
"path": { "type": "string" },
"role": { "type": "string" },
"authority": { "type": "string" }
}
}
},
"collisions": { "type": "array", "items": { "type": "string" } },
"findings": {
"type": "array",
"items": {
"type": "object",
"required": ["severity", "code"],
"additionalProperties": false,
"properties": {
"severity": { "enum": ["info", "warning", "error"] },
"code": { "type": "string" },
"path": { "type": "string" },
"message": { "type": "string" }
}
}
},
"questions": { "type": "array", "items": { "type": "string" } }
}
}
@@ -0,0 +1,44 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/adoption-plan.schema.json",
"title": "AdoptionPlan",
"type": "object",
"required": ["schema", "repository", "baselineRevision", "strategy", "changes", "forbiddenChanges", "approval", "planHash"],
"additionalProperties": false,
"properties": {
"schema": { "const": "stewardship/adoption-plan@0.1" },
"repository": { "type": "string" },
"baselineRevision": { "type": "string" },
"strategy": { "enum": ["overlay", "normalize"] },
"recipe": { "type": "string" },
"changes": {
"type": "array",
"items": {
"type": "object",
"required": ["action", "path"],
"additionalProperties": false,
"properties": {
"action": { "enum": ["create", "patch-managed-block", "preserve", "move"] },
"path": { "type": "string" },
"toPath": { "type": "string" },
"ownership": { "type": "string" },
"reason": { "type": "string" },
"content": { "type": "string" },
"optional": { "type": "boolean" }
}
}
},
"forbiddenChanges": { "type": "array", "items": { "type": "string" } },
"validations": { "type": "array", "items": { "type": "string" } },
"approval": {
"type": "object",
"required": ["required"],
"additionalProperties": false,
"properties": {
"required": { "type": "boolean" },
"planHash": { "type": "string" }
}
},
"planHash": { "type": "string" }
}
}
@@ -0,0 +1,18 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/adoption-report.schema.json",
"title": "AdoptionReport",
"type": "object",
"required": ["schema", "repository", "baselineRevision", "compatibilityLevel", "outcome", "changedPaths", "preservedPaths", "unresolvedFindings"],
"additionalProperties": false,
"properties": {
"schema": { "const": "stewardship/adoption-report@0.1" },
"repository": { "type": "string" },
"baselineRevision": { "type": "string" },
"compatibilityLevel": { "type": "string" },
"outcome": { "enum": ["pass", "pass-with-warnings", "fail"] },
"changedPaths": { "type": "array", "items": { "type": "string" } },
"preservedPaths": { "type": "array", "items": { "type": "string" } },
"unresolvedFindings": { "type": "array", "items": { "type": "string" } }
}
}
@@ -0,0 +1,29 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/bootstrap-plan.schema.json",
"title": "BootstrapPlan",
"type": "object",
"required": ["schema", "repository", "files", "planHash"],
"additionalProperties": false,
"properties": {
"schema": { "const": "stewardship/bootstrap-plan@0.1" },
"repository": { "type": "string" },
"repositoryType": { "type": "string" },
"createdAt": { "type": "string" },
"gitInit": { "type": "boolean" },
"files": {
"type": "array",
"items": {
"type": "object",
"required": ["path", "content"],
"additionalProperties": false,
"properties": {
"path": { "type": "string" },
"content": { "type": "string" }
}
}
},
"recommendations": { "type": "array", "items": { "type": "string" } },
"planHash": { "type": "string" }
}
}
@@ -0,0 +1,55 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/catalog-index.schema.json",
"title": "CatalogIndex",
"type": "object",
"required": ["apiVersion", "kind", "metadata", "spec"],
"additionalProperties": false,
"properties": {
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
"kind": { "const": "CatalogIndex" },
"metadata": {
"type": "object",
"required": ["name"],
"additionalProperties": false,
"properties": { "name": { "type": "string" } }
},
"spec": {
"type": "object",
"required": ["generatedAt", "roots", "repositories", "relations"],
"additionalProperties": false,
"properties": {
"generatedAt": { "type": "string" },
"roots": { "type": "array", "items": { "type": "string" } },
"repositories": {
"type": "array",
"items": {
"type": "object",
"required": ["ref", "path", "type", "lifecycle", "contractHash"],
"additionalProperties": false,
"properties": {
"ref": { "type": "string" },
"path": { "type": "string" },
"type": { "type": "string" },
"lifecycle": { "type": "string" },
"contractHash": { "type": "string" }
}
}
},
"relations": {
"type": "array",
"items": {
"type": "object",
"required": ["from", "type", "to"],
"additionalProperties": false,
"properties": {
"from": { "type": "string" },
"type": { "type": "string" },
"to": { "type": "string" }
}
}
}
}
}
}
}
@@ -0,0 +1,36 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/context-bundle.schema.json",
"title": "ContextBundle",
"type": "object",
"required": ["apiVersion", "kind", "metadata", "spec"],
"additionalProperties": false,
"properties": {
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
"kind": { "const": "ContextBundle" },
"metadata": {
"type": "object",
"required": ["name"],
"additionalProperties": false,
"properties": { "name": { "type": "string" } }
},
"spec": {
"type": "object",
"required": ["generatedAt", "intent", "repository", "summary", "warnings"],
"additionalProperties": false,
"properties": {
"generatedAt": { "type": "string" },
"intent": { "type": "string" },
"repository": { "type": "string" },
"contractRevision": { "type": "string" },
"summary": { "type": "string" },
"contentRoots": { "type": "array", "items": { "type": "string" } },
"operations": { "type": "array", "items": { "type": "string" } },
"topics": { "type": "array", "items": { "type": "string" } },
"documents": { "type": "array", "items": { "type": "string" } },
"materialized": { "type": "array", "items": { "type": "object" } },
"warnings": { "type": "array", "items": { "type": "string" } }
}
}
}
}
@@ -0,0 +1,91 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/knowledge-base.schema.json",
"title": "KnowledgeBase",
"type": "object",
"required": ["apiVersion", "kind", "metadata", "spec"],
"additionalProperties": false,
"properties": {
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
"kind": { "const": "KnowledgeBase" },
"metadata": {
"type": "object",
"required": ["name"],
"additionalProperties": false,
"properties": {
"name": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"title": { "type": "string" },
"owners": { "type": "array", "items": { "type": "string" } },
"labels": { "type": "object", "additionalProperties": { "type": "string" } },
"annotations": { "type": "object" }
}
},
"spec": {
"type": "object",
"required": ["repository", "topics", "documents"],
"additionalProperties": false,
"properties": {
"repository": { "type": "string" },
"defaultLanguage": { "type": "string" },
"topics": { "type": "array", "items": { "$ref": "#/$defs/topic" } },
"documents": { "type": "array", "items": { "$ref": "#/$defs/document" } }
}
}
},
"$defs": {
"topic": {
"type": "object",
"required": ["id", "summary", "intents"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"title": { "type": "string" },
"summary": { "type": "string" },
"intents": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
"keywords": { "type": "array", "items": { "type": "string" } },
"priority": { "type": "integer", "minimum": 0, "maximum": 100 },
"documents": { "type": "array", "items": { "type": "string" } },
"relatedTopics": { "type": "array", "items": { "type": "string" } },
"data": { "type": "object" }
}
},
"document": {
"type": "object",
"required": ["id", "role", "authority", "status"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"title": { "type": "string" },
"role": {
"enum": ["tutorial", "how-to", "reference", "explanation", "runbook", "vendor-source", "evidence"]
},
"path": { "type": "string" },
"uri": { "type": "string", "format": "uri" },
"mediaType": { "type": "string" },
"authority": { "enum": ["vendor", "local-canonical", "observed", "derived", "manual"] },
"status": { "enum": ["verified", "manual", "draft", "stale"] },
"provenance": {
"type": "object",
"additionalProperties": false,
"properties": {
"uri": { "type": "string" },
"vendor": { "type": "string" },
"version": { "type": "string" },
"retrievedAt": { "type": "string" },
"sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
"license": { "type": "string" }
}
},
"freshness": {
"type": "object",
"additionalProperties": false,
"properties": {
"verifiedAt": { "type": "string" },
"expiresAt": { "type": "string" },
"verificationOperation": { "type": "string" }
}
}
}
}
}
}
@@ -0,0 +1,176 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/repository-contract.schema.json",
"title": "RepositoryContract",
"type": "object",
"required": ["apiVersion", "kind", "metadata", "spec"],
"additionalProperties": false,
"properties": {
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
"kind": { "const": "RepositoryContract" },
"metadata": { "$ref": "#/$defs/metadata" },
"spec": {
"type": "object",
"required": ["summary", "repository"],
"additionalProperties": false,
"properties": {
"summary": { "type": "string", "minLength": 1 },
"repository": {
"type": "object",
"required": ["type", "lifecycle"],
"additionalProperties": false,
"properties": {
"type": { "enum": ["infrastructure-config", "service-config", "software", "project"] },
"lifecycle": { "enum": ["production", "active", "experimental", "stub", "archive", "external"] },
"namespace": { "type": "string" },
"access": { "enum": ["public", "internal", "restricted"] }
}
},
"template": {
"type": "object",
"required": ["id", "version"],
"additionalProperties": false,
"properties": {
"id": { "type": "string" },
"version": { "type": "string" },
"source": { "type": "string" },
"revision": { "type": "string" },
"answersRef": { "type": "string" },
"mode": { "enum": ["generated", "adopted-overlay"] },
"managedPaths": { "type": "array", "items": { "type": "string" } }
}
},
"agent": {
"type": "object",
"additionalProperties": false,
"properties": {
"primary": { "type": "string" },
"portable": { "type": "string" }
}
},
"knowledge": {
"type": "object",
"additionalProperties": false,
"properties": {
"entrypoint": { "type": "string" }
}
},
"contentRoots": {
"type": "array",
"items": { "$ref": "#/$defs/contentRoot" }
},
"provides": {
"type": "array",
"items": { "$ref": "#/$defs/capability" }
},
"requires": {
"type": "array",
"items": { "$ref": "#/$defs/requirement" }
},
"bindings": {
"type": "array",
"items": { "$ref": "#/$defs/binding" }
},
"operations": {
"type": "array",
"items": { "$ref": "#/$defs/operation" }
}
}
}
},
"$defs": {
"metadata": {
"type": "object",
"required": ["name"],
"additionalProperties": false,
"properties": {
"name": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"title": { "type": "string" },
"owners": { "type": "array", "items": { "type": "string" } },
"labels": { "type": "object", "additionalProperties": { "type": "string" } },
"annotations": { "type": "object" }
}
},
"contentRoot": {
"type": "object",
"required": ["id", "role", "path", "kind", "authority"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"role": { "type": "string" },
"path": { "type": "string" },
"kind": { "enum": ["directory", "file", "file-set", "manifest"] },
"authority": { "enum": ["source", "generated", "observed", "mirror", "evidence"] },
"writePolicy": { "enum": ["managed", "read-only", "generated"] },
"selector": { "type": "string" },
"format": { "type": "string" },
"environments": { "type": "array", "items": { "type": "string" } },
"generatedFrom": { "type": "array", "items": { "type": "string" } }
}
},
"capability": {
"type": "object",
"required": ["id", "capability"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"capability": { "type": "string" },
"summary": { "type": "string" },
"parametersSchema": { "type": "string" }
}
},
"requirement": {
"type": "object",
"required": ["id", "capability"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"capability": { "type": "string" },
"summary": { "type": "string" },
"constraints": { "type": "object" },
"preferredProviders": { "type": "array", "items": { "type": "string" } },
"acceptance": { "type": "array", "items": { "type": "string" } }
}
},
"binding": {
"type": "object",
"required": ["id", "requirement", "target", "status"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"requirement": { "type": "string" },
"target": { "type": "string" },
"status": { "enum": ["proposed", "active", "failed", "retired"] },
"evidenceRef": { "type": "string" }
}
},
"operation": {
"type": "object",
"required": ["id", "phase", "effect", "risk"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
"title": { "type": "string" },
"intents": { "type": "array", "items": { "type": "string" } },
"phase": {
"enum": ["describe", "inspect", "snapshot", "validate", "diff", "plan", "apply", "verify", "reconcile", "rollback"]
},
"effect": { "enum": ["read-only", "local-write", "external-write", "disruptive", "destructive"] },
"risk": { "enum": ["low", "medium", "high", "critical"] },
"execution": {
"type": "object",
"required": ["handler"],
"additionalProperties": false,
"properties": {
"handler": { "type": "string" },
"argv": { "type": "array", "items": { "type": "string" } }
}
},
"inputSchema": { "type": "string" },
"outputSchema": { "type": "string" },
"preconditions": { "type": "array", "items": { "type": "string" } },
"approval": { "enum": ["never", "on-write", "always"] }
}
}
}
}
@@ -0,0 +1,29 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/repoctl-result.schema.json",
"title": "RepoctlResult",
"type": "object",
"required": ["schema", "command", "outcome", "data", "findings"],
"additionalProperties": false,
"properties": {
"schema": { "const": "stewardship/repoctl-result@0.1" },
"command": { "type": "string" },
"outcome": { "enum": ["success", "failure"] },
"data": {},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": ["severity", "code", "message"],
"additionalProperties": false,
"properties": {
"severity": { "enum": ["info", "warning", "error"] },
"code": { "type": "string" },
"message": { "type": "string" },
"resource": { "type": "string" },
"path": { "type": "string" }
}
}
}
}
}
@@ -0,0 +1,12 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/repoctl-config.schema.json",
"title": "RepoctlUserConfig",
"type": "object",
"required": ["schema"],
"additionalProperties": false,
"properties": {
"schema": { "const": "stewardship/repoctl-config@0.1" },
"roots": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
}
}
+82
View File
@@ -0,0 +1,82 @@
"""Shared text for the three Claude project skills that ship with every bootstrap.
Skills are thin wrappers: they call `repoctl` with machine output and explain findings.
They must never duplicate repoctl's classification, generation or validation logic.
"""
from __future__ import annotations
REPOSITORY_BOOTSTRAP_SKILL = """---
name: repository-bootstrap
description: Bootstrap a new repository into Repository Stewardship using repoctl init. Use when creating a new repository or scaffolding ops/contract.yaml, kdb/kdb.yaml and agent entrypoints from scratch.
---
# repository-bootstrap
Thin wrapper around `repoctl init`. Do not reimplement classification, template
rendering or validation here — call the CLI and explain its output.
## Procedure
1. Collect the missing decisions from the user: repository type
(`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`,
`title`, `owners`, `lifecycle`.
2. Run `repoctl init --repo <path> --answers <answers-file> --output json` to obtain a
`BootstrapPlan` (this performs no writes).
3. Show the user the planned files and the `planHash`.
4. Only after explicit approval, run
`repoctl init --repo <path> --apply --plan <plan-file> --approve <planHash>`.
5. Report the resulting `repoctl validate --repo <path>` findings.
Never invent files outside the plan and never skip the approval step.
"""
REPOSITORY_ADOPTION_SKILL = """---
name: repository-adoption
description: Assess and adopt an existing repository into Repository Stewardship using repoctl adopt. Use when connecting an existing, non-templated repository without moving its domain content.
---
# repository-adoption
Thin wrapper around `repoctl adopt`. The canonical procedure is
`docs/adoption-runbook.md`; this skill only collects missing decisions, calls the CLI
with machine output, and explains findings. It must not duplicate the runbook logic.
## Procedure
1. Run `repoctl adopt --repo <path> --mode assess --output json` (read-only).
2. Present the classification, detected content roots, and any `questions` that need
owner confirmation.
3. Run `repoctl adopt --repo <path> --mode plan --output json` once open questions are
resolved. This is still read-only and returns an `AdoptionPlan` with a `planHash`.
4. Show the full plan (files created, patched managed blocks, preserved paths,
forbidden changes) before asking for approval.
5. Only after explicit approval, run
`repoctl adopt --repo <path> --mode apply --plan <plan-file> --approve <planHash>`.
6. Run `repoctl adopt --repo <path> --mode verify --output json` and report the
`AdoptionReport`, including any `unresolvedFindings`.
Default strategy is `overlay`. Only use `--strategy normalize --recipe
documents-to-content-root` when the owner explicitly asks to reorganize root documents.
"""
REPO_HANDOFF_SKILL = """---
name: repo-handoff
description: Produce a minimal, intent-scoped context handoff for a repository using repoctl context. Use when another agent, session or teammate needs just enough context to work on one task in a repository.
---
# repo-handoff
Thin wrapper around `repoctl context`. Do not read the full repository or the full KDB
by hand when this skill applies — let `repoctl` perform the selection.
## Procedure
1. Turn the user's request into an `intent` id (e.g. `container.deploy`,
`repository.adopt`), not a literal command.
2. Run `repoctl context --repo <name-or-path> --intent <intent> --output json`.
3. If the bundle looks incomplete, retry with `--include-related` or `--materialize`
and an explicit `--budget-bytes`.
4. Hand the resulting `ContextBundle` (and any `warnings`) to the requester instead of
pasting raw repository files.
"""
+24
View File
@@ -0,0 +1,24 @@
from __future__ import annotations
from dataclasses import asdict, dataclass
from typing import Any
@dataclass(frozen=True)
class Finding:
severity: str
code: str
message: str
resource: str | None = None
path: str | None = None
def to_dict(self) -> dict[str, Any]:
return {key: value for key, value in asdict(self).items() if value is not None}
def sort_findings(findings: list[Finding]) -> list[Finding]:
rank = {"error": 0, "warning": 1, "info": 2}
return sorted(
findings,
key=lambda item: (rank.get(item.severity, 9), item.resource or "", item.path or "", item.code),
)
+416
View File
@@ -0,0 +1,416 @@
"""`repoctl validate`: schema, path-safety, reference and Markdown checks for one repository."""
from __future__ import annotations
import fnmatch
import re
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from . import markdown
from .clock import DEFAULT_CLOCK
from .constants import CONTRACT_PATH, ID_PATTERN, SECRET_KEYS
from .io import ResourceError, load_yaml
from .paths import PathViolation, confined_path, normalize_resource_path
from .schema_loader import validate_against_kind
from .types import Finding, sort_findings
_ID_RE = re.compile(ID_PATTERN)
_SHELL_CHARS = set("|&;<>$`\n\r")
@dataclass
class RepositoryValidation:
root: Path
contract: dict[str, Any] | None
kdb: dict[str, Any] | None
findings: list[Finding]
@property
def ok(self) -> bool:
return not any(item.severity == "error" for item in self.findings)
def validate_repository(root: Path) -> RepositoryValidation:
findings: list[Finding] = []
contract_path = root / CONTRACT_PATH
contract: dict[str, Any] | None = None
kdb: dict[str, Any] | None = None
if not contract_path.exists():
findings.append(
Finding("error", "CONTRACT_MISSING", f"{CONTRACT_PATH} does not exist")
)
return RepositoryValidation(root, None, None, sort_findings(findings))
try:
contract = load_yaml(contract_path)
except ResourceError as exc:
findings.append(Finding("error", "CONTRACT_PARSE_ERROR", str(exc), path=CONTRACT_PATH))
return RepositoryValidation(root, None, None, sort_findings(findings))
if not isinstance(contract, dict):
findings.append(
Finding("error", "CONTRACT_NOT_MAPPING", "Contract root must be a mapping", path=CONTRACT_PATH)
)
return RepositoryValidation(root, None, None, sort_findings(findings))
resource_name = f"repo:{contract.get('metadata', {}).get('name', '?')}"
if contract.get("apiVersion") != "stewardship.corsus.ru/v1alpha1":
findings.append(
Finding(
"error",
"CONTRACT_API_VERSION_UNKNOWN",
f"Unknown or missing apiVersion: {contract.get('apiVersion')!r}",
resource=resource_name,
path="apiVersion",
)
)
if contract.get("kind") != "RepositoryContract":
findings.append(
Finding(
"error",
"CONTRACT_KIND_UNEXPECTED",
f"Expected kind RepositoryContract, found {contract.get('kind')!r}",
resource=resource_name,
path="kind",
)
)
for message in validate_against_kind("RepositoryContract", contract):
findings.append(
Finding("error", "CONTRACT_SCHEMA_INVALID", message, resource=resource_name, path=message.split(":", 1)[0])
)
spec = contract.get("spec", {}) if isinstance(contract.get("spec"), dict) else {}
findings.extend(_check_ids(spec, resource_name))
findings.extend(_check_content_root_paths(root, spec, resource_name))
findings.extend(_check_operations(root, spec, resource_name))
findings.extend(_check_secrets(contract, resource_name, "contract"))
kdb_rel = None
knowledge = spec.get("knowledge") if isinstance(spec.get("knowledge"), dict) else None
if knowledge and knowledge.get("entrypoint"):
kdb_rel = knowledge["entrypoint"]
lifecycle = (spec.get("repository") or {}).get("lifecycle")
try:
kdb_path = confined_path(root, kdb_rel)
except PathViolation as exc:
findings.append(
Finding("error", "CONTRACT_PATH_OUTSIDE_REPOSITORY", str(exc), resource=resource_name, path="spec.knowledge.entrypoint")
)
kdb_path = None
if kdb_path is not None:
if not kdb_path.exists():
if lifecycle != "stub":
findings.append(
Finding(
"error",
"KNOWLEDGE_ENTRYPOINT_MISSING",
f"KDB entrypoint does not exist: {kdb_rel}",
resource=resource_name,
path="spec.knowledge.entrypoint",
)
)
else:
kdb, kdb_findings = _validate_kdb(root, kdb_path, kdb_rel, resource_name)
findings.extend(kdb_findings)
for entry_field, entry_path in (("primary", "agent.primary"), ("portable", "agent.portable")):
agent_raw = spec.get("agent")
agent: dict[str, Any] = agent_raw if isinstance(agent_raw, dict) else {}
rel = agent.get(entry_field)
if rel:
full = root / rel
if not full.exists():
findings.append(
Finding("warning", "AGENT_ENTRYPOINT_MISSING", f"{rel} does not exist", resource=resource_name, path=f"spec.{entry_path}")
)
elif full.suffix.lower() == ".md":
findings.extend(markdown.check_markdown_file(root, rel))
for extra in ("README.md",):
if (root / extra).exists():
findings.extend(markdown.check_markdown_file(root, extra))
return RepositoryValidation(root, contract, kdb, sort_findings(findings))
def _check_ids(spec: dict[str, Any], resource_name: str) -> list[Finding]:
findings: list[Finding] = []
for collection_name in ("contentRoots", "provides", "requires", "bindings", "operations"):
items = spec.get(collection_name)
if not isinstance(items, list):
continue
seen: set[str] = set()
for item in items:
if not isinstance(item, dict):
continue
item_id = item.get("id")
if not isinstance(item_id, str) or not _ID_RE.match(item_id):
findings.append(
Finding(
"error",
"ID_FORMAT_INVALID",
f"Invalid id in {collection_name}: {item_id!r}",
resource=resource_name,
path=f"spec.{collection_name}",
)
)
continue
if item_id in seen:
findings.append(
Finding(
"error",
"ID_DUPLICATE",
f"Duplicate id {item_id!r} in {collection_name}",
resource=resource_name,
path=f"spec.{collection_name}",
)
)
seen.add(item_id)
return findings
def _check_content_root_paths(root: Path, spec: dict[str, Any], resource_name: str) -> list[Finding]:
findings: list[Finding] = []
lifecycle = (spec.get("repository") or {}).get("lifecycle")
for index, item in enumerate(spec.get("contentRoots") or []):
if not isinstance(item, dict):
continue
raw_path = item.get("path")
try:
confined = confined_path(root, raw_path) if isinstance(raw_path, str) else None
except PathViolation as exc:
findings.append(
Finding(
"error",
"CONTRACT_PATH_OUTSIDE_REPOSITORY",
str(exc),
resource=resource_name,
path=f"spec.contentRoots[{index}].path",
)
)
continue
if confined is not None and not confined.exists() and lifecycle != "stub":
findings.append(
Finding(
"warning",
"CONTENT_ROOT_PATH_MISSING",
f"contentRoots[{index}] path does not exist: {raw_path}",
resource=resource_name,
path=f"spec.contentRoots[{index}].path",
)
)
return findings
def _check_operations(root: Path, spec: dict[str, Any], resource_name: str) -> list[Finding]:
findings: list[Finding] = []
for index, op in enumerate(spec.get("operations") or []):
if not isinstance(op, dict):
continue
execution = op.get("execution")
if not isinstance(execution, dict):
continue
handler = execution.get("handler")
if isinstance(handler, str):
try:
normalize_resource_path(handler)
except PathViolation as exc:
findings.append(
Finding(
"error",
"OPERATION_HANDLER_PATH_UNSAFE",
str(exc),
resource=resource_name,
path=f"spec.operations[{index}].execution.handler",
)
)
if any(ch in _SHELL_CHARS for ch in handler):
findings.append(
Finding(
"error",
"OPERATION_HANDLER_SHELL_STRING",
"Handler path must not contain shell metacharacters",
resource=resource_name,
path=f"spec.operations[{index}].execution.handler",
)
)
for token in execution.get("argv") or []:
if isinstance(token, str) and any(ch in _SHELL_CHARS for ch in token):
findings.append(
Finding(
"error",
"OPERATION_ARGV_SHELL_STRING",
f"argv token looks like a shell string: {token!r}",
resource=resource_name,
path=f"spec.operations[{index}].execution.argv",
)
)
return findings
def _check_secrets(data: Any, resource_name: str, top_path: str) -> list[Finding]:
findings: list[Finding] = []
def walk(value: Any, path: str) -> None:
if isinstance(value, dict):
for key, item in value.items():
key_norm = str(key).lower().replace("_", "").replace("-", "")
if key_norm in SECRET_KEYS and isinstance(item, str) and item.strip():
findings.append(
Finding(
"error",
"SECRET_SHAPED_FIELD",
f"Field looks like a secret value: {key}",
resource=resource_name,
path=f"{path}.{key}" if path else str(key),
)
)
continue
walk(item, f"{path}.{key}" if path else str(key))
elif isinstance(value, list):
for i, item in enumerate(value):
walk(item, f"{path}[{i}]")
walk(data, top_path)
return findings
def _validate_kdb(
root: Path, kdb_path: Path, kdb_rel: str, contract_resource: str
) -> tuple[dict[str, Any] | None, list[Finding]]:
findings: list[Finding] = []
try:
kdb = load_yaml(kdb_path)
except ResourceError as exc:
return None, [Finding("error", "KNOWLEDGE_PARSE_ERROR", str(exc), path=kdb_rel)]
if not isinstance(kdb, dict):
return None, [Finding("error", "KNOWLEDGE_NOT_MAPPING", "KDB root must be a mapping", path=kdb_rel)]
kdb_resource = f"repo:{kdb.get('spec', {}).get('repository', '?')}"
if kdb.get("kind") != "KnowledgeBase":
findings.append(Finding("error", "KNOWLEDGE_KIND_UNEXPECTED", f"Expected kind KnowledgeBase, found {kdb.get('kind')!r}", resource=kdb_resource, path=kdb_rel))
for message in validate_against_kind("KnowledgeBase", kdb):
findings.append(Finding("error", "KNOWLEDGE_SCHEMA_INVALID", message, resource=kdb_resource, path=kdb_rel))
kdb_spec = kdb.get("spec", {}) if isinstance(kdb.get("spec"), dict) else {}
topics = kdb_spec.get("topics") or []
documents = kdb_spec.get("documents") or []
topic_ids: set[Any] = {t.get("id") for t in topics if isinstance(t, dict)}
doc_ids: dict[Any, dict[str, Any]] = {d.get("id"): d for d in documents if isinstance(d, dict)}
seen_topic_ids: set[Any] = set()
for topic in topics:
if not isinstance(topic, dict):
continue
tid = topic.get("id")
if tid in seen_topic_ids:
findings.append(Finding("error", "ID_DUPLICATE", f"Duplicate topic id {tid!r}", resource=kdb_resource, path=kdb_rel))
seen_topic_ids.add(tid)
for doc_id in topic.get("documents") or []:
if doc_id not in doc_ids:
findings.append(
Finding(
"error",
"KNOWLEDGE_TOPIC_DOCUMENT_MISSING",
f"Topic {tid!r} references unknown document {doc_id!r}",
resource=kdb_resource,
path=kdb_rel,
)
)
for related in topic.get("relatedTopics") or []:
if related not in topic_ids:
findings.append(
Finding(
"warning",
"KNOWLEDGE_RELATED_TOPIC_MISSING",
f"Topic {tid!r} references unknown relatedTopic {related!r}",
resource=kdb_resource,
path=kdb_rel,
)
)
seen_doc_ids: set[Any] = set()
for doc in documents:
if not isinstance(doc, dict):
continue
did = doc.get("id")
if did in seen_doc_ids:
findings.append(Finding("error", "ID_DUPLICATE", f"Duplicate document id {did!r}", resource=kdb_resource, path=kdb_rel))
seen_doc_ids.add(did)
has_path = bool(doc.get("path"))
has_uri = bool(doc.get("uri"))
if has_path == has_uri:
findings.append(
Finding(
"error",
"KNOWLEDGE_DOCUMENT_PATH_XOR_URI",
f"Document {did!r} must set exactly one of path/uri",
resource=kdb_resource,
path=kdb_rel,
)
)
if has_path:
doc_path = doc["path"]
try:
confined = confined_path(root, doc_path)
except PathViolation as exc:
findings.append(Finding("error", "CONTRACT_PATH_OUTSIDE_REPOSITORY", str(exc), resource=kdb_resource, path=kdb_rel))
confined = None
if confined is not None:
if not confined.exists():
findings.append(
Finding("error", "KNOWLEDGE_DOCUMENT_PATH_MISSING", f"Document {did!r} path does not exist: {doc_path}", resource=kdb_resource, path=kdb_rel)
)
elif confined.suffix.lower() == ".md":
findings.extend(markdown.check_markdown_file(root, doc_path))
freshness = doc.get("freshness") if isinstance(doc.get("freshness"), dict) else None
if freshness and freshness.get("expiresAt"):
try:
expires = _parse_dt(freshness["expiresAt"])
if expires <= DEFAULT_CLOCK.now():
findings.append(
Finding(
"warning",
"KNOWLEDGE_DOCUMENT_STALE",
f"Document {did!r} freshness expired at {freshness['expiresAt']}",
resource=kdb_resource,
path=kdb_rel,
)
)
except ValueError:
findings.append(
Finding("warning", "KNOWLEDGE_FRESHNESS_UNPARSEABLE", f"Cannot parse expiresAt for document {did!r}", resource=kdb_resource, path=kdb_rel)
)
provenance = doc.get("provenance") if isinstance(doc.get("provenance"), dict) else None
if provenance and provenance.get("sha256") and not re.fullmatch(r"[0-9a-f]{64}", provenance["sha256"]):
findings.append(
Finding("error", "KNOWLEDGE_PROVENANCE_HASH_INVALID", f"Document {did!r} sha256 must be 64 lowercase hex chars", resource=kdb_resource, path=kdb_rel)
)
findings.extend(_check_secrets(kdb, kdb_resource, kdb_rel))
return kdb, findings
def _parse_dt(value: str) -> datetime:
text = value.replace("Z", "+00:00")
dt = datetime.fromisoformat(text)
if dt.tzinfo is None:
dt = dt.replace(tzinfo=UTC)
return dt
def content_root_files(root: Path, selector_root: Path, selector: str | None) -> list[Path]:
if selector is None:
return [selector_root] if selector_root.is_file() else list(selector_root.rglob("*"))
return [p for p in selector_root.rglob("*") if p.is_file() and fnmatch.fnmatch(p.relative_to(selector_root).as_posix(), selector)]