yigraf 0.1.0__py3-none-any.whl

yigraf/__init__.py

@@ -0,0 +1,3 @@
+"""yigraf — one connected graph over code, intent, plan, and memory."""
+
+__version__ = "0.0.0"

yigraf/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m yigraf`` entry point — used by the git hook, which bakes in an absolute interpreter
+path so it works regardless of ``PATH`` (see :mod:`yigraf.hooks`)."""
+from yigraf.cli import main
+
+if __name__ == "__main__":
+    main()

yigraf/artifacts.py

@@ -0,0 +1,312 @@
+"""Intent & plan artifacts: the authored ``.md`` truth for the intent/plan node families (M2).
+
+Intents and plans live as one-file-per-node markdown under ``yigraf/intents/`` and
+``yigraf/plans/`` (``docs/graph-design.md`` §4, ``docs/m2-notes.md``). Bodies are human-authored;
+the plan's ``edges`` frontmatter is machine-written by ``yigraf link``. This module reads them into
+dataclasses, projects those into the graph (intent/plan/task nodes + ``contains``/``tracks``/
+``requires``/``implements`` edges), and writes new artifacts for the authoring verbs.
+
+A target id that doesn't resolve to a node is **not** added as a phantom edge — it's stashed on the
+task node (``dangling_implements`` / ``dangling_tracks``) for M3 to surface as hard drift.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import networkx as nx
+import yaml
+
+from yigraf.astnorm import ANCHOR_ALGO
+
+INTENT_FAMILY = "intent"
+PLAN_FAMILY = "plan"
+CONF = "EXTRACTED"  # authored artifacts are asserted truth, not inferred
+
+INTENT_TYPES = ("requirement", "goal", "capability")
+INTENT_STATUSES = ("proposed", "active", "satisfied", "archived")
+
+_FRONTMATTER = re.compile(r"\A---\n(.*?)\n---\n?(.*)\Z", re.DOTALL)
+_TASK_LINE = re.compile(r"^- \[([ xX])\]\s*\{#(\d+)\}\s*(.*)$")
+_HEADING = re.compile(r"^##\s+(.*?)\s*$")
+
+
+# --------------------------------------------------------------------------------------------------
+# Frontmatter + section parsing
+# --------------------------------------------------------------------------------------------------
+
+
+def _split_frontmatter(text: str) -> tuple[dict, str]:
+    """Return ``(metadata, body)`` for a ``---``-fenced markdown file (empty meta if none)."""
+    match = _FRONTMATTER.match(text)
+    if match is None:
+        return {}, text
+    meta = yaml.safe_load(match.group(1)) or {}
+    if not isinstance(meta, dict):
+        raise ValueError("artifact frontmatter must be a YAML mapping")
+    return meta, match.group(2)
+
+
+def _compose(meta: dict, body: str) -> str:
+    """Inverse of :func:`_split_frontmatter`: deterministic frontmatter + body."""
+    front = yaml.safe_dump(meta, sort_keys=True, allow_unicode=True, default_flow_style=False)
+    body = body if body.endswith("\n") or not body else body + "\n"
+    return f"---\n{front}---\n{body}"
+
+
+def _sections(body: str) -> dict[str, str]:
+    """Split a markdown body into ``{heading_lower: text}`` keyed by ``## Heading``.
+
+    The heading key is lowercased and trimmed of a trailing parenthetical (``Design (how)`` →
+    ``design``), so authored variants still map to a stable field.
+    """
+    out: dict[str, list[str]] = {}
+    current: str | None = None
+    for line in body.splitlines():
+        heading = _HEADING.match(line)
+        if heading is not None:
+            key = heading.group(1).split("(")[0].strip().casefold()
+            current = key
+            out.setdefault(current, [])
+        elif current is not None:
+            out[current].append(line)
+    return {k: "\n".join(v).strip() for k, v in out.items()}
+
+
+def _bullets(text: str) -> list[str]:
+    """The ``- `` bullet items in a section, in order (used for scenarios)."""
+    return [ln[2:].strip() for ln in text.splitlines() if ln.lstrip().startswith("- ")]
+
+
+# --------------------------------------------------------------------------------------------------
+# Intent
+# --------------------------------------------------------------------------------------------------
+
+
+@dataclass
+class Intent:
+    id: str
+    slug: str
+    type: str
+    status: str
+    statement: str
+    scenarios: list[str] = field(default_factory=list)
+    design: str | None = None
+
+
+def read_intent(path: Path) -> Intent:
+    """Parse an ``intents/<slug>.md`` file into an :class:`Intent`."""
+    path = Path(path)
+    meta, body = _split_frontmatter(path.read_text(encoding="utf-8"))
+    slug = path.stem
+    sections = _sections(body)
+    design = sections.get("design") or None
+    return Intent(
+        id=meta.get("id", f"int:{slug.casefold()}"),
+        slug=slug,
+        type=meta.get("type", "requirement"),
+        status=meta.get("status", "proposed"),
+        statement=sections.get("requirement", "").strip(),
+        scenarios=_bullets(sections.get("scenarios", "")),
+        design=design,
+    )
+
+
+def render_intent(slug: str, statement: str, scenarios: list[str], design: str | None,
+                  type: str = "requirement", status: str = "proposed") -> str:
+    """Render the markdown for a new intent artifact."""
+    meta = {"id": f"int:{slug.casefold()}", "family": INTENT_FAMILY, "type": type, "status": status}
+    lines = ["## Requirement", statement, "", "## Scenarios"]
+    lines += [f"- {s}" for s in scenarios] or ["- "]
+    if design:
+        lines += ["", "## Design (how)", design]
+    return _compose(meta, "\n".join(lines) + "\n")
+
+
+# --------------------------------------------------------------------------------------------------
+# Plan + tasks
+# --------------------------------------------------------------------------------------------------
+
+
+@dataclass
+class Implements:
+    sym: str
+    anchor: str | None = None
+    anchor_algo: str | None = None
+
+
+@dataclass
+class Task:
+    id: str
+    num: int
+    description: str
+    state: str  # todo | done
+    tracks: str | None = None
+    requires: list[str] = field(default_factory=list)
+    implements: list[Implements] = field(default_factory=list)
+
+
+@dataclass
+class Plan:
+    id: str
+    slug: str
+    title: str
+    tasks: list[Task] = field(default_factory=list)
+    phase: str = "active"  # active | completed (from the plans/<phase>/ subdir)
+
+
+def read_plan(path: Path) -> Plan:
+    """Parse a plan file (frontmatter ``edges`` + ``## Tasks`` checkboxes) into a :class:`Plan`."""
+    path = Path(path)
+    meta, body = _split_frontmatter(path.read_text(encoding="utf-8"))
+    slug = path.stem
+    edges = meta.get("edges") or {}
+
+    title = slug
+    for line in body.splitlines():
+        if line.startswith("# "):
+            title = line[2:].strip()
+            break
+
+    tasks: list[Task] = []
+    for line in body.splitlines():
+        m = _TASK_LINE.match(line.strip())
+        if m is None:
+            continue
+        num = int(m.group(2))
+        task_id = f"task:{slug.casefold()}/{num}"
+        spec = edges.get(task_id) or {}
+        tasks.append(
+            Task(
+                id=task_id,
+                num=num,
+                description=m.group(3).strip(),
+                state="done" if m.group(1).lower() == "x" else "todo",
+                tracks=spec.get("tracks"),
+                requires=list(spec.get("requires") or []),
+                implements=[_read_impl(e) for e in (spec.get("implements") or [])],
+            )
+        )
+    tasks.sort(key=lambda t: t.num)
+    return Plan(id=meta.get("id", f"plan:{slug.casefold()}"), slug=slug, title=title, tasks=tasks)
+
+
+def _read_impl(entry: Any) -> Implements:
+    if isinstance(entry, str):
+        return Implements(sym=entry)
+    return Implements(sym=entry["sym"], anchor=entry.get("anchor"), anchor_algo=entry.get("anchor_algo"))
+
+
+def render_plan(slug: str, title: str, tasks: list[str]) -> str:
+    """Render the markdown for a new plan with todo tasks (no edges yet)."""
+    meta = {"id": f"plan:{slug.casefold()}", "family": PLAN_FAMILY, "edges": {}}
+    lines = [f"# {title}", "", "## Tasks"]
+    lines += [f"- [ ] {{#{i}}} {desc}" for i, desc in enumerate(tasks, start=1)]
+    return _compose(meta, "\n".join(lines) + "\n")
+
+
+def add_edge_to_plan(path: Path, task_id: str, relation: str, target: str,
+                     anchor: str | None = None) -> None:
+    """Write a ``tracks`` or ``implements`` edge for ``task_id`` into the plan's frontmatter.
+
+    ``tracks`` is a single intent id; ``implements`` appends a (deduplicated) symbol entry carrying
+    its stamped ``anchor`` + ``anchor_algo``. Re-linking the same symbol re-stamps its anchor.
+    """
+    path = Path(path)
+    meta, body = _split_frontmatter(path.read_text(encoding="utf-8"))
+    edges = meta.setdefault("edges", {}) or {}
+    meta["edges"] = edges
+    spec = edges.setdefault(task_id, {})
+
+    if relation == "tracks":
+        spec["tracks"] = target
+    elif relation == "implements":
+        impls = spec.setdefault("implements", [])
+        entry = {"sym": target, "anchor": anchor, "anchor_algo": ANCHOR_ALGO if anchor else None}
+        for existing in impls:
+            if existing.get("sym") == target:
+                existing.update(entry)
+                break
+        else:
+            impls.append(entry)
+    else:
+        raise ValueError(f"unsupported relation for a plan edge: {relation}")
+
+    path.write_text(_compose(meta, body), encoding="utf-8")
+
+
+# --------------------------------------------------------------------------------------------------
+# Projection into the graph
+# --------------------------------------------------------------------------------------------------
+
+
+def iter_intents(root: Path) -> list[Intent]:
+    intents_dir = Path(root) / "yigraf" / "intents"
+    return [read_intent(p) for p in sorted(intents_dir.glob("*.md"))] if intents_dir.is_dir() else []
+
+
+def iter_plans(root: Path) -> list[Plan]:
+    plans_dir = Path(root) / "yigraf" / "plans"
+    out = []
+    for sub in ("active", "completed"):
+        d = plans_dir / sub
+        if d.is_dir():
+            for p in sorted(d.glob("*.md")):
+                plan = read_plan(p)
+                plan.phase = sub
+                out.append(plan)
+    return out
+
+
+def project_into(graph: nx.DiGraph, root: Path) -> None:
+    """Add intent/plan/task nodes and their cross-family edges to ``graph`` from the artifacts."""
+    for intent in iter_intents(root):
+        graph.add_node(
+            intent.id, family=INTENT_FAMILY, kind=intent.type, label=intent.statement or intent.slug,
+            confidence=CONF, status=intent.status, statement=intent.statement,
+            scenarios=intent.scenarios, design=intent.design, source_file=f"intents/{intent.slug}.md",
+        )
+
+    for plan in iter_plans(root):
+        graph.add_node(plan.id, family=PLAN_FAMILY, kind="plan", label=plan.title,
+                       confidence=CONF, phase=plan.phase)
+        for task in plan.tasks:
+            graph.add_node(
+                task.id, family=PLAN_FAMILY, kind="task", label=task.description,
+                confidence=CONF, state=task.state, order=task.num,
+            )
+            graph.add_edge(plan.id, task.id, relation="contains", confidence=CONF)
+            _project_task_edges(graph, task)
+
+
+def _project_task_edges(graph: nx.DiGraph, task: Task) -> None:
+    """Add a task's tracks/requires/implements edges, stashing unresolved targets for M3."""
+    if task.tracks is not None:
+        if task.tracks in graph:
+            graph.add_edge(task.id, task.tracks, relation="tracks", confidence=CONF)
+        else:
+            _stash(graph, task.id, "dangling_tracks", task.tracks)
+
+    for req in task.requires:
+        if req in graph:
+            graph.add_edge(task.id, req, relation="requires", confidence=CONF)
+        else:
+            _stash(graph, task.id, "dangling_requires", req)
+
+    for impl in task.implements:
+        if impl.sym in graph:
+            attrs = {"relation": "implements", "confidence": CONF}
+            if impl.anchor is not None:
+                attrs["anchor"] = impl.anchor
+                attrs["anchor_algo"] = impl.anchor_algo or ANCHOR_ALGO
+            graph.add_edge(task.id, impl.sym, **attrs)
+        else:
+            # Keep the anchor so M3 can re-anchor a rename by content match (docs/m3-notes.md §3).
+            _stash(graph, task.id, "dangling_implements",
+                   {"sym": impl.sym, "anchor": impl.anchor, "anchor_algo": impl.anchor_algo})
+
+
+def _stash(graph: nx.DiGraph, node_id: str, attr: str, value: str) -> None:
+    graph.nodes[node_id].setdefault(attr, []).append(value)

yigraf/astnorm.py

@@ -0,0 +1,151 @@
+"""AST-normalized ``content_hash`` — the drift anchor (``astnorm-v1``).
+
+A symbol's ``content_hash`` is a SHA-256 over its *significant token stream*: the tokens that remain
+after dropping comments and docstrings, normalizing string quote style, and replacing each nested
+*extracted* symbol with a stable ``<def:NAME>`` marker. The rule is pinned in ``docs/m1-notes.md`` §4
+and is **load-bearing**: once anchors are stamped (M2), changing the rule silently mismatches every
+stored anchor — so the algorithm carries a version tag (:data:`ANCHOR_ALGO`). A future rule change
+bumps the tag and re-anchors on next commit instead of false-drifting.
+
+What is deliberately ignored (no drift): comments, docstrings, string quote style (``'x'`` ≡ ``"x"``),
+and all whitespace/reformatting that doesn't change the parsed token stream — so a ``black``/``isort``
+reflow is safe. What trips drift (intended): any change to identifiers, operators, literal *values*,
+keywords, control flow, signatures, or decorators within a symbol's own body.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import TYPE_CHECKING, Mapping
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+#: Version tag stored alongside every anchor. Bumping it (``astnorm-v2``) re-anchors instead of
+#: silently false-drifting against hashes produced by an older rule (docs/m1-notes.md §4).
+ANCHOR_ALGO = "astnorm-v1"
+
+#: Field separators for the token stream. ``\x1f`` (unit) joins a token's type to its text; ``\x1e``
+#: (record) joins tokens. Both are control chars that cannot occur in Python source, so they can't be
+#: forged by a literal's contents.
+_FIELD = "\x1f"
+_TOKEN = "\x1e"
+
+#: Python defaults for the per-language astnorm knobs. They are the function defaults below, so a
+#: caller that passes nothing reproduces the original Python rule byte-for-byte (no ``astnorm-v2``
+#: bump, existing anchors stay valid). Other languages pass their own sets (e.g. Go: all empty — no
+#: docstrings, no quote-style ambiguity), keeping the *algorithm* astnorm-v1 while varying the
+#: language-specific token vocabulary it normalizes.
+
+#: Token types whose text is a quote delimiter (prefix + quotes) we canonicalize.
+_PY_QUOTE_TOKENS = frozenset({"string_start", "string_end"})
+
+#: Block-like containers whose *leading* string statement is a docstring to drop.
+_PY_BODY_CONTAINERS = frozenset({"block", "module"})
+
+#: Node types that count as a lone string statement (a docstring) inside a body container.
+_PY_DOCSTRING_TYPES = frozenset({"string", "concatenated_string"})
+
+#: Node types dropped as comments. Default fits Python/Go/JS/C; languages whose grammar names them
+#: differently (Rust/Java: ``line_comment``/``block_comment``) pass their own set.
+_PY_COMMENT_TYPES = frozenset({"comment"})
+
+
+def content_hash(node: Node, source: bytes, boundaries: Mapping[int, str],
+                 exclude: frozenset[int] = frozenset(), *,
+                 quote_tokens: frozenset[str] = _PY_QUOTE_TOKENS,
+                 body_containers: frozenset[str] = _PY_BODY_CONTAINERS,
+                 docstring_types: frozenset[str] = _PY_DOCSTRING_TYPES,
+                 comment_types: frozenset[str] = _PY_COMMENT_TYPES) -> str:
+    """Hash ``node``'s significant token stream (``astnorm-v1``); see module docstring.
+
+    ``boundaries`` maps the tree-sitter node id of each *directly nested extracted symbol* (a
+    top-level def for a module; a method for a class) to its local name. Those subtrees are replaced
+    by a ``<def:NAME>`` marker and not descended into — so a class hash captures its member *names*
+    but not method bodies, and editing a method body flips only that method's hash.
+
+    ``exclude`` is a set of node ids dropped outright — used for the symbol's **own declared name**,
+    so a pure rename leaves the body-hash unchanged and M3 can re-anchor by exact match
+    (docs/m3-notes.md §2). A *container's* member names (the ``<def:NAME>`` markers) are unaffected.
+
+    ``quote_tokens`` / ``body_containers`` / ``docstring_types`` are the per-language knobs (default:
+    Python). Empty sets disable quote canonicalization / docstring dropping for languages that have
+    neither (e.g. Go), while the rest of the algorithm — and ``ANCHOR_ALGO`` — is unchanged.
+    """
+    tokens: list[str] = []
+    _emit(node, source, boundaries, exclude, tokens, quote_tokens, body_containers, docstring_types,
+          comment_types)
+    blob = _TOKEN.join(tokens).encode("utf-8", "surrogatepass")
+    return hashlib.sha256(blob).hexdigest()
+
+
+def _emit(node: Node, source: bytes, boundaries: Mapping[int, str], exclude: frozenset[int],
+          out: list[str], quote_tokens: frozenset[str], body_containers: frozenset[str],
+          docstring_types: frozenset[str], comment_types: frozenset[str]) -> None:
+    """Append ``node``'s significant tokens to ``out`` in pre-order."""
+    if node.id in exclude:
+        return  # the symbol's own name — dropped so a rename doesn't change the body-hash
+
+    name = boundaries.get(node.id)
+    if name is not None:
+        out.append(f"<def:{name}>")  # nested extracted symbol — its body is its own concern
+        return
+
+    kind = node.type
+    if kind in comment_types:
+        return
+
+    if node.child_count == 0:
+        text = source[node.start_byte : node.end_byte].decode("utf-8", "surrogatepass")
+        if kind in quote_tokens:
+            # Canonicalize the *kind* too: in some grammars (JS/TS) the delimiter's node type IS the
+            # quote char (``"`` vs ``'``), so normalizing only the text would still differ by type.
+            # On Python's ``string_start``/``string_end`` this is a no-op (no quote char in the name),
+            # so existing anchors stay byte-identical.
+            kind = _canon_quote(kind)
+            text = _canon_quote(text)
+        out.append(f"{kind}{_FIELD}{text}")
+        return
+
+    children = node.children
+    if kind in body_containers:
+        children = _without_leading_docstring(children, docstring_types)
+    for child in children:
+        _emit(child, source, boundaries, exclude, out, quote_tokens, body_containers, docstring_types,
+              comment_types)
+
+
+def _without_leading_docstring(children: list[Node], docstring_types: frozenset[str]) -> list[Node]:
+    """Return ``children`` with a leading docstring statement removed, if present.
+
+    A docstring is the first *statement* (comments don't count) of a body that is a bare string
+    expression. Doc-only edits are maintenance; a real contract change also edits code, which trips
+    drift anyway (docs/m1-notes.md §4).
+    """
+    for i, child in enumerate(children):
+        if child.type == "comment":
+            continue  # comments precede the docstring but aren't the first statement
+        if child.type == "expression_statement" and _is_string_only(child, docstring_types):
+            return children[:i] + children[i + 1 :]
+        return children  # first real statement isn't a docstring
+    return children
+
+
+def _is_string_only(stmt: Node, docstring_types: frozenset[str]) -> bool:
+    """True when an ``expression_statement`` is a lone string literal (a docstring)."""
+    kids = stmt.children
+    return len(kids) == 1 and kids[0].type in docstring_types
+
+
+def _canon_quote(token: str) -> str:
+    """Canonicalize a string delimiter: lowercase the prefix, force double quotes, keep quote count.
+
+    ``r'''`` → ``r\"\"\"``, ``F"`` → ``f"``. Preserves the prefix letters (``r``/``b``/``f``) and the
+    quote *count* (never collapses ``'''`` ↔ ``'``, which would change semantics). Kills the dominant
+    ``black`` quote-flip false-drift source; ``string_content`` is emitted verbatim, so escape-level
+    rewrites (``'it\\'s'`` → ``"it's"``) still trip drift and are deferred to a possible v2.
+    """
+    i = 0
+    while i < len(token) and token[i] not in ("'", '"'):
+        i += 1
+    prefix, quotes = token[:i], token[i:]
+    return prefix.lower() + quotes.replace("'", '"')

yigraf/cache.py

@@ -0,0 +1,102 @@
+"""Per-file SHA content cache for structure extraction (``yigraf/cache/structure.json``).
+
+Keyed by the raw file bytes' SHA-256: a hit means the file is byte-for-byte unchanged since it was
+last extracted, so its cached node/edge projection is reused verbatim and tree-sitter is skipped.
+This is the *file cache SHA* of ``docs/m1-notes.md`` §3 — distinct from a symbol's astnorm
+``content_hash``. The cache is gitignored and rebuildable; it never affects the output graph (which
+is deterministic), only whether a file is re-parsed. It is invalidated wholesale when the astnorm
+algorithm version changes, so a stale anchor can never survive a rule change.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from yigraf.astnorm import ANCHOR_ALGO
+
+if TYPE_CHECKING:
+    from yigraf.extract import FileProjection
+
+#: Bumped when the on-disk cache layout changes incompatibly (separate from the astnorm algo).
+#: 2: structure nodes gained a ``signature`` field (M4).
+#: 3: file nodes gained an ``inherits`` field (import-aware inheritance edges) — a stale cache would
+#:    otherwise serve pre-inheritance projections for files that haven't changed since the upgrade.
+#: 4: the tags-tier extractors began populating ``inherits`` too (inheritance across the breadth
+#:    languages), so a format-3 cache of e.g. a Java file lacks its inheritance — invalidate it.
+#: 5: Kotlin/Scala began recording ``imports`` on the file node (import edges) — a format-4 cache of
+#:    those files has an empty imports list.
+CACHE_FORMAT = 5
+
+
+def file_sha(data: bytes) -> str:
+    """SHA-256 hex of raw file bytes — the cache key (a file changed at all)."""
+    return hashlib.sha256(data).hexdigest()
+
+
+@dataclass
+class StructureCache:
+    """Reusable per-file extraction projections, keyed by relative path then content SHA.
+
+    Also carries a small HEAD-keyed ``maturity`` slot (R2 survival counts): recomputing maturity
+    walks git history, but an edit never moves ``HEAD``, so this lets the hot ``PostToolUse`` rebuild
+    skip the walk until a commit actually lands. Like the rest of the cache it's gitignored,
+    rebuildable, and never alters the (deterministic) output graph — only how survival is obtained.
+    """
+
+    algo: str
+    entries: dict[str, dict]
+    maturity: dict = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: Path) -> "StructureCache":
+        """Load the cache, or start empty if absent, unreadable, or built by a different algo."""
+        p = Path(path)
+        if p.exists():
+            try:
+                data = json.loads(p.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                data = {}
+            if data.get("format") == CACHE_FORMAT and data.get("algo") == ANCHOR_ALGO:
+                return cls(algo=ANCHOR_ALGO, entries=dict(data.get("files", {})),
+                           maturity=dict(data.get("maturity", {})))
+        return cls(algo=ANCHOR_ALGO, entries={})
+
+    def maturity_survival(self, head: str) -> dict | None:
+        """Cached ``{path: survival}`` if it was computed at this ``HEAD``, else ``None`` (a miss)."""
+        if self.maturity.get("head") == head:
+            return dict(self.maturity.get("survival", {}))
+        return None
+
+    def set_maturity_survival(self, head: str, survival: dict) -> None:
+        """Record the survival map computed at ``head`` (replaces any map from an earlier HEAD)."""
+        self.maturity = {"head": head, "survival": dict(survival)}
+
+    def get(self, relpath: str, sha: str) -> "FileProjection | None":
+        """Return the cached projection for ``relpath`` iff its content SHA still matches."""
+        from yigraf.extract import FileProjection
+
+        entry = self.entries.get(relpath)
+        if entry is not None and entry.get("sha") == sha:
+            return FileProjection.from_cache(entry)
+        return None
+
+    def put(self, relpath: str, sha: str, projection: "FileProjection") -> None:
+        """Record ``projection`` for ``relpath`` under its content SHA."""
+        self.entries[relpath] = {"sha": sha, **projection.to_cache()}
+
+    def prune(self, keep: set[str]) -> None:
+        """Drop cached entries for files no longer present in the repo."""
+        for relpath in list(self.entries):
+            if relpath not in keep:
+                del self.entries[relpath]
+
+    def save(self, path: Path) -> None:
+        """Write the cache as deterministic JSON (sorted keys)."""
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        out = {"format": CACHE_FORMAT, "algo": self.algo, "files": self.entries,
+               "maturity": self.maturity}
+        p.write_text(json.dumps(out, indent=2, sort_keys=True) + "\n", encoding="utf-8")