Files
repoctl/src/stewardship/discovery.py
T
Alexander BaranovandClaude Sonnet 5 96d4d08230 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>
2026-08-24 14:57:34 +03:00

152 lines
5.3 KiB
Python

"""`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)