xrefkit 0.3.0__py3-none-any.whl

xrefkit/structure_catalog.py

@@ -0,0 +1,199 @@
+"""List-first source target/finding catalog and safe candidate promotion."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+SCHEMA = "xrefkit.source_structure_catalog/v1"
+RECEIPT_SCHEMA = "xrefkit.source_structure_candidate/v1"
+XID_RE = re.compile(r"^[A-F0-9]{12}$")
+
+
+def load_catalog(path: str | Path) -> dict[str, Any]:
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or data.get("schema") != SCHEMA:
+        raise ValueError("unsupported source structure catalog")
+    return data
+
+
+def save_catalog(path: str | Path, catalog: dict[str, Any]) -> None:
+    Path(path).write_text(yaml.safe_dump(catalog, sort_keys=False, allow_unicode=True), encoding="utf-8")
+
+
+def _safe_value(value: Any) -> Any:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    if isinstance(value, list):
+        return [_safe_value(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _safe_value(item) for key, item in value.items()}
+    return value
+
+
+def list_targets(catalog: dict[str, Any]) -> list[dict[str, Any]]:
+    return [_safe_value(dict(item)) for item in catalog.get("targets", [])]
+
+
+def list_findings(catalog: dict[str, Any], target_xid: str) -> list[dict[str, Any]]:
+    key = target_xid.upper()
+    return [_safe_value(dict(item)) for item in catalog.get("findings", []) if str(item.get("target_xid", "")).upper() == key]
+
+
+def get_entry(catalog: dict[str, Any], xid: str) -> dict[str, Any]:
+    key = xid.upper()
+    for collection, field in (("targets", "target_xid"), ("findings", "finding_xid")):
+        for item in catalog.get(collection, []):
+            if str(item.get(field, "")).upper() == key:
+                return _safe_value({"kind": collection[:-1], **dict(item)})
+    raise KeyError(f"unknown catalog XID: {xid}")
+
+
+def _target_identity(item: dict[str, Any]) -> tuple[str, str, str]:
+    return (
+        str(item.get("repository_identity", "")).strip(),
+        str(item.get("source_scope", "")).strip(),
+        str(item.get("target_kind", "")).strip(),
+    )
+
+
+def _derived_xid(*parts: str) -> str:
+    return hashlib.sha256("\x1f".join(parts).encode("utf-8")).hexdigest()[:12].upper()
+
+
+def _validate_receipt(receipt: dict[str, Any], root: Path) -> list[str]:
+    errors: list[str] = []
+    if receipt.get("schema") != RECEIPT_SCHEMA:
+        errors.append("unsupported receipt schema")
+    required = (
+        "candidate_xid", "artifact_path", "repository_identity", "source_scope",
+        "target_kind", "source_revision", "producer_skill", "analyzed_at",
+    )
+    for field in required:
+        if not str(receipt.get(field, "")).strip():
+            errors.append(f"missing {field}")
+    xid = str(receipt.get("candidate_xid", "")).upper()
+    if xid and not XID_RE.fullmatch(xid):
+        errors.append("candidate_xid must be 12 hexadecimal characters")
+    artifact = root / str(receipt.get("artifact_path", ""))
+    if not artifact.is_file():
+        errors.append(f"artifact not found: {artifact}")
+    return errors
+
+
+def maintain_catalog(
+    root: str | Path,
+    catalog_path: str | Path,
+    inbox: str | Path,
+    *,
+    apply_safe: bool,
+) -> dict[str, Any]:
+    root_path = Path(root).resolve()
+    catalog_file = root_path / catalog_path
+    catalog = load_catalog(catalog_file)
+    results: list[dict[str, Any]] = []
+    changed = False
+    for receipt_path in sorted((root_path / inbox).glob("*.yaml")):
+        receipt = yaml.safe_load(receipt_path.read_text(encoding="utf-8"))
+        if not isinstance(receipt, dict):
+            results.append({"receipt": str(receipt_path), "status": "invalid", "errors": ["receipt is not a mapping"]})
+            continue
+        errors = _validate_receipt(receipt, root_path)
+        identity = _target_identity(receipt)
+        matches = [item for item in catalog.get("targets", []) if _target_identity(item) == identity]
+        if len(matches) > 1:
+            errors.append("multiple targets match receipt identity")
+        finding_xid = str(receipt.get("candidate_xid", "")).upper()
+        if any(str(item.get("finding_xid", "")).upper() == finding_xid for item in catalog.get("findings", [])):
+            results.append({"receipt": str(receipt_path), "status": "already_registered", "finding_xid": finding_xid})
+            continue
+        if errors or not apply_safe:
+            results.append({
+                "receipt": str(receipt_path),
+                "status": "pending_review" if not errors else "invalid",
+                "errors": errors,
+            })
+            continue
+        if matches:
+            target = matches[0]
+        else:
+            target_xid = str(receipt.get("target_xid", "")).upper() or _derived_xid(*identity)
+            target = {
+                "target_xid": target_xid,
+                "name": str(receipt.get("target_name") or receipt.get("target_hint") or identity[1]),
+                "repository_identity": identity[0],
+                "source_scope": identity[1],
+                "target_kind": identity[2],
+                "aliases": list(receipt.get("aliases") or []),
+            }
+            catalog.setdefault("targets", []).append(target)
+        artifact = root_path / str(receipt["artifact_path"])
+        slug = re.sub(r"[^a-z0-9]+", "_", str(target["name"]).lower()).strip("_") or "target"
+        detail_relative = Path("knowledge/source_analysis") / f"{finding_xid.lower()}_{slug}_structure_findings.md"
+        detail = root_path / detail_relative
+        body = artifact.read_text(encoding="utf-8")
+        if f"xid: {finding_xid}" not in body:
+            body = f'<!-- xid: {finding_xid} -->\n<a id="xid-{finding_xid}"></a>\n\n' + body
+        detail.parent.mkdir(parents=True, exist_ok=True)
+        detail.write_text(body, encoding="utf-8")
+        finding = {
+            "finding_xid": finding_xid,
+            "target_xid": target["target_xid"],
+            "title": str(receipt.get("title") or f"{target['name']} structure findings"),
+            "analysis_kinds": list(receipt.get("analysis_kinds") or ["source_structure"]),
+            "status": "current",
+            "source_revision": str(receipt["source_revision"]),
+            "last_verified": str(receipt["analyzed_at"]),
+            "coverage": str(receipt.get("coverage") or "See canonical finding detail."),
+            "unresolved_verification": str(receipt.get("unresolved_verification") or "None recorded."),
+            "detail_path": detail_relative.as_posix(),
+        }
+        catalog.setdefault("findings", []).append(finding)
+        receipt["status"] = "registered"
+        receipt["target_xid"] = target["target_xid"]
+        receipt["canonical_detail_path"] = detail_relative.as_posix()
+        receipt_path.write_text(yaml.safe_dump(receipt, sort_keys=False, allow_unicode=True), encoding="utf-8")
+        results.append({"receipt": str(receipt_path), **finding, "processing_status": "registered"})
+        changed = True
+    if changed:
+        save_catalog(catalog_file, catalog)
+    return {
+        "ok": all(item["status"] not in {"invalid"} for item in results),
+        "changed": changed,
+        "results": results,
+        "registered": sum(item.get("processing_status") == "registered" for item in results),
+        "pending_review": sum(item["status"] == "pending_review" for item in results),
+    }
+
+
+def reconcile_receipts(root: str | Path, reports: str | Path, inbox: str | Path) -> dict[str, Any]:
+    root_path = Path(root).resolve()
+    inbox_path = root_path / inbox
+    inbox_path.mkdir(parents=True, exist_ok=True)
+    existing = {
+        str(data.get("artifact_path"))
+        for path in inbox_path.glob("*.yaml")
+        if isinstance((data := yaml.safe_load(path.read_text(encoding="utf-8"))), dict)
+    }
+    created: list[str] = []
+    pattern = re.compile(r"^candidate_xid:\s*([A-Fa-f0-9]{12})\s*$", re.MULTILINE)
+    for report in sorted((root_path / reports).glob("*.md")):
+        relative = report.relative_to(root_path).as_posix()
+        if relative in existing:
+            continue
+        text = report.read_text(encoding="utf-8")
+        match = pattern.search(text[:2000])
+        if not match:
+            continue
+        xid = match.group(1).upper()
+        receipt = {"schema": RECEIPT_SCHEMA, "candidate_xid": xid, "artifact_path": relative, "status": "incomplete"}
+        target = inbox_path / f"{date.today().isoformat()}_{xid}.yaml"
+        target.write_text(yaml.safe_dump(receipt, sort_keys=False), encoding="utf-8")
+        created.append(str(target))
+    return {"ok": True, "created": created, "count": len(created)}

xrefkit/tools/__init__.py

@@ -0,0 +1,119 @@
+"""Stable tool-ID registry and client-side execution."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class ToolContract:
+    tool_id: str
+    xid: str
+    path: str
+    execution_location: str
+    side_effects: str
+    content_hash: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "tool_id": self.tool_id,
+            "xid": self.xid,
+            "path": self.path,
+            "execution_location": self.execution_location,
+            "side_effects": self.side_effects,
+            "content_hash": self.content_hash,
+        }
+
+
+def load_tool_contracts(root: str | Path = ".", manifest: str = "tools/contracts.yaml") -> list[ToolContract]:
+    root_path = Path(root).resolve()
+    data = yaml.safe_load((root_path / manifest).read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or data.get("schema") != "xrefkit.tool_contracts/v1":
+        raise ValueError("unsupported tool contract manifest")
+    contracts: list[ToolContract] = []
+    ids: set[str] = set()
+    xids: set[str] = set()
+    for item in data.get("tools", []):
+        tool_id = str(item["tool_id"])
+        xid = str(item["xid"]).upper()
+        if tool_id in ids:
+            raise ValueError(f"duplicate tool_id: {tool_id}")
+        if xid in xids:
+            raise ValueError(f"duplicate tool XID: {xid}")
+        path = root_path / str(item["path"])
+        if not path.is_file():
+            raise ValueError(f"tool path not found: {path}")
+        ids.add(tool_id)
+        xids.add(xid)
+        contracts.append(
+            ToolContract(
+                tool_id=tool_id,
+                xid=xid,
+                path=str(item["path"]),
+                execution_location=str(item["execution_location"]),
+                side_effects=str(item["side_effects"]),
+                content_hash=hashlib.sha256(path.read_bytes()).hexdigest(),
+            )
+        )
+    return contracts
+
+
+def _find(contracts: list[ToolContract], identity: str) -> ToolContract:
+    key = identity.upper()
+    for contract in contracts:
+        if contract.tool_id == identity or contract.xid == key:
+            return contract
+    raise KeyError(f"unknown tool: {identity}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="xrefkit tools")
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--manifest", default="tools/contracts.yaml")
+    sub = parser.add_subparsers(dest="command", required=True)
+    list_parser = sub.add_parser("list")
+    list_parser.add_argument("--json", action="store_true")
+    show = sub.add_parser("show")
+    show.add_argument("tool")
+    show.add_argument("--json", action="store_true")
+    run = sub.add_parser("run")
+    run.add_argument("tool")
+    run.add_argument("tool_args", nargs=argparse.REMAINDER)
+    args = parser.parse_args(argv)
+    try:
+        contracts = load_tool_contracts(args.root, args.manifest)
+        if args.command == "list":
+            payload: Any = [contract.to_dict() for contract in contracts]
+        else:
+            contract = _find(contracts, args.tool)
+            if args.command == "show":
+                payload = contract.to_dict()
+            else:
+                if contract.execution_location != "client":
+                    raise ValueError(f"tool is not client executable: {contract.tool_id}")
+                command = [sys.executable, str(Path(args.root) / contract.path), *args.tool_args]
+                return subprocess.run(command, check=False).returncode
+    except (OSError, KeyError, ValueError, yaml.YAMLError) as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        return 1
+    as_json = bool(getattr(args, "json", False))
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    elif isinstance(payload, list):
+        for item in payload:
+            print(f"{item['tool_id']}\t{item['xid']}\t{item['execution_location']}")
+    else:
+        print(f"{payload['tool_id']}\t{payload['xid']}\t{payload['path']}")
+    return 0
+
+
+__all__ = ["ToolContract", "load_tool_contracts", "main"]

xrefkit/tools/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+
+raise SystemExit(main())

xrefkit/v2_cli.py

@@ -0,0 +1,130 @@
+"""Minimal CLI for XRefKit v2 MVP."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Sequence
+
+from .discovery import discover_skill_packages, package_list_rows
+from .loaders import load_server_config
+from .resolver import EffectiveSkillResolver
+from .workspace import build_registry
+
+
+def _add_workspace_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--package-manifest", action="append", default=[], help="Path to package_manifest.yaml")
+    parser.add_argument("--local-manifest", help="Path to xrefkit.local/local_manifest.yaml")
+    parser.add_argument("--enable-entry-point-discovery", action="store_true", help="Load enabled packages from Python entry points")
+    parser.add_argument("--enabled-package", action="append", default=[], help="Package id enabled for resolver use")
+
+
+def _enabled_packages_from_args(args: argparse.Namespace) -> set[str]:
+    enabled = set(args.enabled_package or [])
+    server_config = getattr(args, "server_config", None)
+    if server_config:
+        config = load_server_config(server_config)
+        enabled.update(config.packages.enabled)
+    return enabled
+
+
+def _bundle_tree(bundle: object) -> str:
+    # Deliberately use model_dump so this function stays stable if the model
+    # gains computed properties later.
+    data = bundle.model_dump(mode="json")  # type: ignore[attr-defined]
+    lines = [f"effective_skill: {data['effective_skill_id']}", f"mode: {data['resolution_mode']}"]
+    lines.append("loaded:")
+    for group, entries in data["loaded_texts"].items():
+        if not entries:
+            continue
+        lines.append(f"  {group}:")
+        for entry in entries:
+            lines.append(f"    - {entry['xid']} ({entry['load_reason']})")
+    lines.append("references:")
+    for group, entries in data["references"].items():
+        if entries:
+            lines.append(f"  {group}: {', '.join(entries)}")
+    lines.append("required_outputs:")
+    for output in data["required_outputs"]:
+        lines.append(f"  - {output}")
+    return "\n".join(lines)
+
+
+def cmd_show_effective_skill(args: argparse.Namespace) -> int:
+    registry = build_registry(
+        package_manifests=args.package_manifest,
+        local_manifest_path=args.local_manifest,
+        discover_entry_points=args.enable_entry_point_discovery,
+        enabled_package_ids=_enabled_packages_from_args(args),
+    )
+    bundle = EffectiveSkillResolver(registry).resolve_entry(args.skill_id)
+    if args.mode == "tree":
+        print(_bundle_tree(bundle))
+    elif args.mode == "resolved-json":
+        print(json.dumps(bundle.model_dump(mode="json"), ensure_ascii=False, indent=2))
+    else:
+        raise NotImplementedError("true full materialize is not implemented in the MVP CLI")
+    return 0
+
+
+def cmd_package_discover(args: argparse.Namespace) -> int:
+    rows = [
+        {
+            "entry_point": package.entry_point_name,
+            "package_id": package.package_id,
+            "version": package.version,
+            "manifest_path": str(package.manifest_path),
+        }
+        for package in discover_skill_packages()
+    ]
+    if args.json:
+        print(json.dumps(rows, ensure_ascii=False, indent=2))
+    else:
+        for row in rows:
+            print(f"{row['package_id']}\t{row['version']}\t{row['manifest_path']}")
+    return 0
+
+
+def cmd_package_list(args: argparse.Namespace) -> int:
+    rows = package_list_rows(enabled_package_ids=_enabled_packages_from_args(args))
+    if args.json:
+        print(json.dumps(rows, ensure_ascii=False, indent=2))
+    else:
+        for row in rows:
+            status = "enabled" if row["enabled"] else "disabled"
+            print(f"{row['package_id']}\t{row['version']}\t{status}\t{row['manifest_path']}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="xrefkit")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    package = subparsers.add_parser("package")
+    package_sub = package.add_subparsers(dest="package_command", required=True)
+    discover = package_sub.add_parser("discover")
+    discover.add_argument("--json", action="store_true")
+    discover.set_defaults(func=cmd_package_discover)
+
+    package_list = package_sub.add_parser("list")
+    package_list.add_argument("--json", action="store_true")
+    package_list.add_argument("--server-config", help="Path to xrefkit.server.toml with enabled packages")
+    package_list.add_argument("--enabled-package", action="append", default=[], help="Package id enabled for resolver use")
+    package_list.set_defaults(func=cmd_package_list)
+
+    show = subparsers.add_parser("show")
+    show_sub = show.add_subparsers(dest="show_command", required=True)
+    effective = show_sub.add_parser("effective-skill")
+    effective.add_argument("skill_id")
+    effective.add_argument("--mode", choices=["tree", "resolved-json"], default="tree")
+    effective.add_argument("--server-config", help="Path to xrefkit.server.toml with enabled packages")
+    _add_workspace_args(effective)
+    effective.set_defaults(func=cmd_show_effective_skill)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)

xrefkit/workspace.py

@@ -0,0 +1,117 @@
+"""Workspace assembly helpers for XRefKit v2 MVP."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .discovery import enabled_discovered_packages
+from .loaders import load_local_manifest
+from .loaders import load_local_domain_skill, load_package_manifest, load_skill_definition
+from .registry import XRefKitRegistry
+from .models.common import version_satisfies
+
+
+CORE_PROTOCOL_VERSION = "2.0.0"
+
+
+def _contained_path(root: Path, relative_path: str, *, label: str) -> Path:
+    root = root.resolve()
+    candidate = (root / relative_path).resolve()
+    try:
+        candidate.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(f"{label} escapes root: {relative_path}") from exc
+    return candidate
+
+
+def _validate_skill_paths(root: Path, skill) -> None:
+    _contained_path(root, skill.entry.path, label="skill entry")
+    for fragment in skill.required_fragments:
+        _contained_path(root, fragment.path, label=f"skill fragment {fragment.id}")
+    for branch in skill.branches:
+        _contained_path(root, branch.path, label=f"skill branch {branch.id}")
+
+
+def build_registry(
+    *,
+    package_manifests: list[str | Path],
+    local_manifest_path: str | Path | None = None,
+    discover_entry_points: bool = False,
+    enabled_package_ids: set[str] | None = None,
+) -> XRefKitRegistry:
+    registry = XRefKitRegistry()
+    manifest_paths = [Path(path) for path in package_manifests]
+    if discover_entry_points:
+        enabled = enabled_package_ids or set()
+        manifest_paths.extend(candidate.manifest_path for candidate in enabled_discovered_packages(enabled_package_ids=enabled))
+
+    for manifest_path in manifest_paths:
+        manifest_path = Path(manifest_path).resolve()
+        manifest = load_package_manifest(manifest_path)
+        package_root = manifest_path.parent.resolve()
+        if not version_satisfies(CORE_PROTOCOL_VERSION, manifest.requires.xrefkit_core):
+            raise ValueError(
+                f"package {manifest.package_id} requires XRefKit core {manifest.requires.xrefkit_core}, "
+                f"current core is {CORE_PROTOCOL_VERSION}"
+            )
+        for asset_group in (
+            manifest.provides.skills,
+            manifest.provides.fragments,
+            manifest.provides.knowledge,
+            manifest.provides.review_axes,
+            manifest.provides.schemas,
+            manifest.provides.templates,
+        ):
+            for asset in asset_group:
+                _contained_path(package_root, asset.path, label=f"package asset {asset.id}")
+        registry.add_package(manifest, package_root)
+        for provided in manifest.provides.skills:
+            skill_path = _contained_path(package_root, provided.path, label=f"package skill {provided.id}")
+            skill = load_skill_definition(skill_path)
+            _validate_skill_paths(package_root, skill)
+            registry.add_package_skill(
+                package_id=manifest.package_id,
+                skill=skill,
+                path=skill_path,
+                root=package_root,
+            )
+        registry.add_package_knowledge_from_manifest(manifest, package_root)
+    if local_manifest_path is not None:
+        local_manifest_path = Path(local_manifest_path).resolve()
+        local_manifest = load_local_manifest(local_manifest_path)
+        local_root = local_manifest_path.parent.resolve()
+        if not version_satisfies(CORE_PROTOCOL_VERSION, local_manifest.requires.xrefkit_core):
+            raise ValueError(
+                f"local manifest requires XRefKit core {local_manifest.requires.xrefkit_core}, "
+                f"current core is {CORE_PROTOCOL_VERSION}"
+            )
+        for asset_group in (
+            local_manifest.mounts.knowledge,
+            local_manifest.mounts.templates,
+            local_manifest.mounts.schemas,
+            local_manifest.mounts.review_axes,
+        ):
+            for asset in asset_group:
+                _contained_path(local_root, asset.path, label=f"local asset {asset.id}")
+        for mount in local_manifest.mounts.skills:
+            _contained_path(local_root, mount.path, label="local skill")
+        for requirement in local_manifest.requires.skill_packages:
+            package = registry.packages.get(requirement.package_id)
+            if package is None:
+                raise ValueError(f"required package is not loaded: {requirement.package_id}")
+            if not version_satisfies(package.manifest.version, requirement.version):
+                raise ValueError(
+                    f"package {requirement.package_id} version {package.manifest.version} "
+                    f"does not satisfy local requirement {requirement.version}"
+                )
+        registry.add_local_manifest_assets(local_root, local_manifest)
+        for mount in local_manifest.mounts.skills:
+            skill_path = _contained_path(local_root, mount.path, label="local skill")
+            skill = load_local_domain_skill(skill_path)
+            registry.add_local_skill(
+                skill=skill,
+                path=skill_path,
+                root=local_root,
+                local_id=local_manifest.local_id,
+            )
+    return registry