xrefkit 0.3.0__py3-none-any.whl

xrefkit/ownership.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+class OwnershipError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Zone:
+    id: str
+    owner: str
+    paths: tuple[str, ...]
+    catalog: bool
+    distribution: bool
+    base_sync: bool
+    shadowing: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "owner": self.owner,
+            "paths": list(self.paths),
+            "catalog": self.catalog,
+            "distribution": self.distribution,
+            "base_sync": self.base_sync,
+            "shadowing": self.shadowing,
+        }
+
+
+@dataclass(frozen=True)
+class Ownership:
+    zones: tuple[Zone, ...]
+
+    def zone_for(self, rel_path: str) -> Zone | None:
+        normalized = _normalize_rel_path(rel_path)
+        for zone in self.zones:
+            if any(_matches(pattern, normalized) for pattern in zone.paths):
+                return zone
+        return None
+
+    def base_sync_enabled(self, rel_path: str) -> bool:
+        zone = self.zone_for(rel_path)
+        return True if zone is None else zone.base_sync
+
+    def catalog_enabled(self, rel_path: str) -> bool:
+        zone = self.zone_for(rel_path)
+        return True if zone is None else zone.catalog
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"zones": [zone.to_dict() for zone in self.zones]}
+
+
+def load_ownership(root: str | Path, filename: str = "ownership.yaml") -> Ownership | None:
+    path = Path(root) / filename
+    if not path.exists():
+        return None
+    parsed = _parse_simple_yaml(path.read_text(encoding="utf-8"))
+    zones = parsed.get("zones")
+    if not isinstance(zones, list):
+        raise OwnershipError("ownership.yaml must contain a zones list")
+    result = []
+    seen: set[str] = set()
+    for index, raw in enumerate(zones):
+        if not isinstance(raw, dict):
+            raise OwnershipError(f"zone {index} must be a mapping")
+        zone = _zone_from_mapping(raw, index)
+        if zone.id in seen:
+            raise OwnershipError(f"duplicate zone id: {zone.id}")
+        seen.add(zone.id)
+        result.append(zone)
+    return Ownership(tuple(result))
+
+
+def validate_ownership(root: str | Path, ownership: Ownership) -> list[str]:
+    errors: list[str] = []
+    repo = Path(root).resolve()
+    for zone in ownership.zones:
+        for pattern in zone.paths:
+            if not pattern or pattern.startswith("/") or "\\" in pattern:
+                errors.append(f"{zone.id}: invalid path pattern `{pattern}`")
+                continue
+            literal_prefix = pattern.split("*", 1)[0]
+            target = (repo / literal_prefix).resolve()
+            try:
+                target.relative_to(repo)
+            except ValueError:
+                errors.append(f"{zone.id}: path escapes repository `{pattern}`")
+    return errors
+
+
+def load_optional_ownership(root: str | Path) -> Ownership | None:
+    ownership = load_ownership(root)
+    if ownership is None:
+        return None
+    errors = validate_ownership(root, ownership)
+    if errors:
+        raise OwnershipError("; ".join(errors))
+    return ownership
+
+
+def content_files(
+    root: str | Path,
+    family: str,
+    pattern: str,
+    *,
+    ownership: Ownership | None = None,
+) -> list[Path]:
+    repo = Path(root).resolve()
+    paths: list[Path] = []
+    base = repo / family
+    if base.exists():
+        paths.extend(
+            path
+            for path in sorted(base.glob(f"**/{pattern}"))
+            if _catalog_enabled(repo, ownership, path)
+        )
+    packs_root = repo / "packs"
+    if ownership is not None and packs_root.exists():
+        paths.extend(
+            path
+            for path in sorted(packs_root.glob(f"*/{family}/**/{pattern}"))
+            if _catalog_enabled(repo, ownership, path)
+        )
+        paths.extend(
+            path
+            for path in sorted(packs_root.glob(f"local/*/{family}/**/{pattern}"))
+            if _catalog_enabled(repo, ownership, path)
+        )
+    return sorted(set(paths))
+
+
+def _zone_from_mapping(raw: dict[str, Any], index: int) -> Zone:
+    required = ("id", "owner", "paths", "catalog", "distribution", "base_sync", "shadowing")
+    missing = [key for key in required if key not in raw]
+    if missing:
+        raise OwnershipError(f"zone {index} missing fields: {', '.join(missing)}")
+    paths = raw["paths"]
+    if not isinstance(paths, list) or not all(isinstance(item, str) for item in paths):
+        raise OwnershipError(f"zone {raw.get('id', index)} paths must be a list of strings")
+    return Zone(
+        id=_as_str(raw["id"], "id"),
+        owner=_as_str(raw["owner"], "owner"),
+        paths=tuple(_normalize_pattern(path) for path in paths),
+        catalog=_as_bool(raw["catalog"], "catalog"),
+        distribution=_as_bool(raw["distribution"], "distribution"),
+        base_sync=_as_bool(raw["base_sync"], "base_sync"),
+        shadowing=_as_bool(raw["shadowing"], "shadowing"),
+    )
+
+
+def _parse_simple_yaml(text: str) -> dict[str, Any]:
+    root: dict[str, Any] = {}
+    current_list_name: str | None = None
+    current_item: dict[str, Any] | None = None
+    current_item_list_name: str | None = None
+
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.split("#", 1)[0].rstrip()
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        stripped = line.strip()
+
+        if indent == 0:
+            if not stripped.endswith(":"):
+                raise OwnershipError(f"line {line_number}: top-level value must be a mapping key")
+            current_list_name = stripped[:-1]
+            root[current_list_name] = []
+            current_item = None
+            current_item_list_name = None
+            continue
+
+        if current_list_name is None:
+            raise OwnershipError(f"line {line_number}: nested value before top-level key")
+
+        if indent == 2 and stripped.startswith("- "):
+            value = stripped[2:]
+            if ":" not in value:
+                raise OwnershipError(f"line {line_number}: list item must start a mapping")
+            key, raw_value = _split_key_value(value, line_number)
+            current_item = {key: _parse_scalar(raw_value)}
+            root[current_list_name].append(current_item)
+            current_item_list_name = None
+            continue
+
+        if indent == 4:
+            if current_item is None:
+                raise OwnershipError(f"line {line_number}: mapping value before list item")
+            key, raw_value = _split_key_value(stripped, line_number)
+            if raw_value == "":
+                current_item[key] = []
+                current_item_list_name = key
+            else:
+                current_item[key] = _parse_scalar(raw_value)
+                current_item_list_name = None
+            continue
+
+        if indent == 6 and stripped.startswith("- "):
+            if current_item is None or current_item_list_name is None:
+                raise OwnershipError(f"line {line_number}: list value without parent key")
+            value = _parse_scalar(stripped[2:])
+            if not isinstance(current_item[current_item_list_name], list):
+                raise OwnershipError(f"line {line_number}: parent is not a list")
+            current_item[current_item_list_name].append(value)
+            continue
+
+        raise OwnershipError(f"line {line_number}: unsupported indentation or syntax")
+
+    return root
+
+
+def _split_key_value(value: str, line_number: int) -> tuple[str, str]:
+    if ":" not in value:
+        raise OwnershipError(f"line {line_number}: expected key: value")
+    key, raw = value.split(":", 1)
+    key = key.strip()
+    if not key:
+        raise OwnershipError(f"line {line_number}: empty key")
+    return key, raw.strip()
+
+
+def _parse_scalar(value: str) -> str | bool:
+    if value == "true":
+        return True
+    if value == "false":
+        return False
+    return value.strip("'\"")
+
+
+def _as_str(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise OwnershipError(f"{field} must be a non-empty string")
+    return value
+
+
+def _as_bool(value: Any, field: str) -> bool:
+    if not isinstance(value, bool):
+        raise OwnershipError(f"{field} must be true or false")
+    return value
+
+
+def _normalize_pattern(pattern: str) -> str:
+    normalized = pattern.replace("\\", "/")
+    if normalized.startswith("./"):
+        normalized = normalized[2:]
+    if normalized and not normalized.endswith("/"):
+        normalized += "/"
+    return normalized
+
+
+def _normalize_rel_path(path: str) -> str:
+    normalized = path.replace("\\", "/")
+    if normalized.startswith("./"):
+        normalized = normalized[2:]
+    parts = PurePosixPath(normalized).parts
+    if any(part == ".." for part in parts):
+        return normalized
+    return normalized
+
+
+def _matches(pattern: str, rel_path: str) -> bool:
+    if "*" not in pattern:
+        return rel_path == pattern.rstrip("/") or rel_path.startswith(pattern)
+    return fnmatch.fnmatch(rel_path, pattern + "*")
+
+
+def _catalog_enabled(root: Path, ownership: Ownership | None, path: Path) -> bool:
+    if ownership is None:
+        return True
+    rel = path.relative_to(root).as_posix()
+    return ownership.catalog_enabled(rel)

xrefkit/packmeta.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from xrefkit.ownership import load_optional_ownership
+from xrefkit.skillmeta import (
+    REQUIRED_OS_CONTRACT,
+    VALID_MATURITY_LEVELS,
+    _parse_key_value_list,
+    _parse_meta_lines,
+)
+
+# A Business Pack is a manifest-driven composition, not a folder of co-located
+# files. `pack.md` declares which assets the pack OWNS (exclusive) and which it
+# USES (shared references that may live anywhere, including the OS core). This
+# lets one Skill/Knowledge be reused by several packs while keeping ownership
+# and the OS-core contract boundary machine-checkable.
+PACK_MANIFEST_NAME = "pack.md"
+PACKS_DIR = "skills/packs"
+TOP_LEVEL_PACKS_DIR = "packs"
+
+# Owned assets must not live inside an OS-core scope: that would mean a business
+# pack is redefining the operating layer rather than depending on it.
+OS_CORE_SKILL_PREFIX = "skills/os/"
+
+# Flat owns_* / uses_* keys keep the manifest readable AND parseable by the same
+# bullet-list reader as meta.md (which flattens nested lists), so no bespoke
+# manifest parser is needed.
+# Skill-centric consolidation (083): flows/ and capabilities/ are removed, so
+# owns_flows / uses_capabilities are no longer manifest keys.
+OWNS_KEYS = ("owns_skills", "owns_knowledge")
+USES_KEYS = ("uses_skills", "uses_knowledge")
+REQUIRED_TEXT_FIELDS = ("pack_id", "summary", "entry")
+
+
+def current_os_contract_version() -> str:
+    return str(REQUIRED_OS_CONTRACT["version"])
+
+
+@dataclass
+class PackManifestResult:
+    manifest_path: str
+    pack_id: str | None
+    maturity: str | None
+    os_contract_version: str | None
+    owns: dict[str, list[str]]
+    uses: dict[str, list[str]]
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "manifest_path": self.manifest_path,
+            "pack_id": self.pack_id,
+            "maturity": self.maturity,
+            "os_contract_version": self.os_contract_version,
+            "owns": self.owns,
+            "uses": self.uses,
+            "ok": self.ok,
+            "errors": self.errors,
+            "warnings": self.warnings,
+        }
+
+
+def _as_list(value: object) -> list[str]:
+    if isinstance(value, list):
+        return [str(item) for item in value if isinstance(item, str) and item.strip()]
+    if isinstance(value, str) and value.strip():
+        return [value.strip()]
+    return []
+
+
+def _strip_fragment(ref: str) -> str:
+    return ref.split("#", 1)[0]
+
+
+def validate_pack_manifest(manifest_path: Path, *, root: Path) -> PackManifestResult:
+    text = manifest_path.read_text(encoding="utf-8")
+    parsed = _parse_meta_lines(text)
+
+    pack_id = parsed.get("pack_id")
+    maturity = parsed.get("maturity") or parsed.get("status")
+    depends_on = _parse_key_value_list(parsed.get("depends_on"))
+    os_contract_version = depends_on.get("os_contract_version")
+
+    owns = {key: _as_list(parsed.get(key)) for key in OWNS_KEYS}
+    uses = {key: _as_list(parsed.get(key)) for key in USES_KEYS}
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    for key in REQUIRED_TEXT_FIELDS:
+        value = parsed.get(key)
+        if not isinstance(value, str) or not value.strip():
+            errors.append(f"missing {key}")
+
+    if not isinstance(maturity, str) or not maturity.strip():
+        errors.append("missing maturity")
+    elif maturity not in VALID_MATURITY_LEVELS:
+        errors.append(f"invalid maturity: {maturity}")
+
+    if "<!-- xid:" not in text:
+        warnings.append("manifest has no XID block; run `xrefkit xref fix` so it is xref-addressable")
+
+    # OS-core contract gate: if the pack pins a contract version that no longer
+    # matches the live OS-core contract, the pack must be revalidated. This makes
+    # the prose rule in 065 (revalidate when controls change) enforceable.
+    if not os_contract_version:
+        errors.append("missing depends_on.os_contract_version")
+    elif os_contract_version != current_os_contract_version():
+        errors.append(
+            f"depends_on.os_contract_version is {os_contract_version} but OS core is "
+            f"{current_os_contract_version()}; pack revalidation required"
+        )
+
+    if not any(owns.values()):
+        errors.append("pack owns no assets (declare at least one owns_skills/owns_knowledge)")
+
+    # Owned-asset existence + boundary checks.
+    for skill_ref in owns["owns_skills"]:
+        norm = skill_ref.replace("\\", "/")
+        skill_dir = (root / norm).resolve()
+        if not (skill_dir / "meta.md").exists():
+            errors.append(f"owned skill has no meta.md: {skill_ref}")
+        if norm.startswith(OS_CORE_SKILL_PREFIX):
+            errors.append(f"owned skill lives in OS core (boundary violation): {skill_ref}")
+
+    for asset_ref in owns["owns_knowledge"]:
+        target = (root / _strip_fragment(asset_ref).replace("\\", "/")).resolve()
+        if not target.exists():
+            errors.append(f"owned asset path does not resolve: {asset_ref}")
+
+    # Used references only need to resolve; they may live anywhere (incl. OS core).
+    for use_ref in uses["uses_skills"] + uses["uses_knowledge"]:
+        target = (root / _strip_fragment(use_ref).replace("\\", "/")).resolve()
+        if not target.exists():
+            warnings.append(f"used reference does not resolve: {use_ref}")
+
+    return PackManifestResult(
+        manifest_path=str(manifest_path),
+        pack_id=str(pack_id) if pack_id else None,
+        maturity=str(maturity) if isinstance(maturity, str) and maturity.strip() else None,
+        os_contract_version=os_contract_version,
+        owns=owns,
+        uses=uses,
+        ok=not errors,
+        errors=errors,
+        warnings=warnings,
+    )
+
+
+def list_packs(root: Path) -> list[dict[str, object]]:
+    """Pack-level catalog derived from manifests, for job-first routing.
+
+    The manifest is the single source of truth: ownership is read from
+    `owns_skills`, and each owned Skill's id/summary is resolved from its meta.
+    Nothing here is hand-maintained, so the catalog cannot drift from the packs.
+    """
+    packs: list[dict[str, object]] = []
+    for manifest in _discover_manifests(root):
+        parsed = _parse_meta_lines(manifest.read_text(encoding="utf-8"))
+        skills: list[dict[str, str]] = []
+        for skill_ref in _as_list(parsed.get("owns_skills")):
+            meta = (root / skill_ref.replace("\\", "/") / "meta.md")
+            skill_id = skill_ref.rsplit("/", 1)[-1]
+            summary = ""
+            if meta.exists():
+                smeta = _parse_meta_lines(meta.read_text(encoding="utf-8"))
+                skill_id = str(smeta.get("skill_id") or skill_id)
+                summary = str(smeta.get("summary") or "")
+            skills.append({"skill_id": skill_id, "path": skill_ref, "summary": summary})
+        packs.append(
+            {
+                "pack_id": str(parsed.get("pack_id") or manifest.parent.name),
+                "summary": str(parsed.get("summary") or ""),
+                "maturity": str(parsed.get("maturity") or parsed.get("status") or ""),
+                "entry": str(parsed.get("entry") or ""),
+                "skills": skills,
+            }
+        )
+    return packs
+
+
+def cmd_pack_list(args) -> int:
+    root = Path(args.root).resolve()
+    packs = list_packs(root)
+
+    if args.json:
+        print(json.dumps(packs, ensure_ascii=False, indent=2))
+    else:
+        for pack in packs:
+            print(f"{pack['pack_id']}  ({pack['maturity']})")
+            print(f"  {pack['summary']}")
+            for skill in pack["skills"]:
+                print(f"    - {skill['skill_id']}: {skill['summary']}")
+        print(f"packs: {len(packs)}")
+
+    return 0
+
+
+def _discover_manifests(root: Path) -> list[Path]:
+    manifests: list[Path] = []
+    legacy_base = root / PACKS_DIR
+    if legacy_base.exists():
+        manifests.extend(sorted(legacy_base.glob(f"*/{PACK_MANIFEST_NAME}")))
+    ownership = load_optional_ownership(root)
+    top_base = root / TOP_LEVEL_PACKS_DIR
+    if ownership is not None and top_base.exists():
+        manifests.extend(
+            path
+            for path in sorted(top_base.glob(f"*/{PACK_MANIFEST_NAME}"))
+            if ownership.catalog_enabled(path.relative_to(root).as_posix())
+        )
+    return sorted(set(manifests))
+
+
+def _physical_skill_dirs(root: Path, pack_dir: Path) -> list[str]:
+    dirs: list[str] = []
+    for meta_path in sorted(pack_dir.rglob("meta.md")):
+        rel = meta_path.parent.relative_to(root).as_posix()
+        dirs.append(rel)
+    return dirs
+
+
+def cmd_pack_lint(args) -> int:
+    root = Path(args.root).resolve()
+
+    if args.manifest:
+        manifests = [(root / args.manifest).resolve()]
+    else:
+        manifests = _discover_manifests(root)
+
+    results = [validate_pack_manifest(path, root=root) for path in manifests]
+
+    # Cross-pack ownership exclusivity: an owned asset must belong to exactly one
+    # pack. (Shared assets belong in uses_*, not owns_*.)
+    owner_of: dict[str, list[str]] = {}
+    for result in results:
+        pack_label = result.pack_id or result.manifest_path
+        for key in OWNS_KEYS:
+            for ref in result.owns[key]:
+                norm = _strip_fragment(ref).replace("\\", "/").rstrip("/")
+                owner_of.setdefault(norm, []).append(pack_label)
+
+    for asset, owners in owner_of.items():
+        if len(owners) > 1:
+            for result in results:
+                pack_label = result.pack_id or result.manifest_path
+                if pack_label in owners:
+                    result.errors.append(
+                        f"asset owned by multiple packs (move to uses_*): {asset} -> {sorted(set(owners))}"
+                    )
+                    result.ok = False
+
+    # Orphan warning: a Skill physically under skills/packs/<pack>/ that no
+    # manifest claims. Useful during the co-located -> manifest transition.
+    owned_skill_dirs = {
+        _strip_fragment(ref).replace("\\", "/").rstrip("/")
+        for result in results
+        for ref in result.owns["owns_skills"]
+    }
+    for path in manifests:
+        result = next(r for r in results if r.manifest_path == str(path))
+        for skill_dir in _physical_skill_dirs(root, path.parent):
+            if skill_dir not in owned_skill_dirs:
+                result.warnings.append(f"skill physically in pack but not owned by any manifest: {skill_dir}")
+
+    failed = [r for r in results if not r.ok]
+
+    if args.json:
+        print(json.dumps([r.to_dict() for r in results], ensure_ascii=False, indent=2))
+    else:
+        for result in results:
+            status = "ok" if result.ok else "fail"
+            print(f"{status}: {result.manifest_path}")
+            if result.pack_id:
+                print(f"  pack_id: {result.pack_id}")
+            if result.maturity:
+                print(f"  maturity: {result.maturity}")
+            for warning in result.warnings:
+                print(f"  warning: {warning}")
+            for error in result.errors:
+                print(f"  error: {error}")
+        print(f"packs: {len(results)}  failed: {len(failed)}")
+
+    return 1 if failed else 0