Skip to content

Commit 46eb2ad

Browse files
committed
fix(ingest): tie each code graph to its root and prune graphs of deleted roots (#711, slice 1)
ingest_codebase now writes cortex-root.json (the resolved project root) next to the graph it builds, and prunes every graph under ~/.cache/cortex/code-graphs whose recorded root no longer exists. A directory without the marker is logged as unattributed and kept, never deleted on a guess. This replaces the name-prefix prune, which removed any sibling sharing the project name's first segment (cortex-viz-* when cortex ran) and never removed the graph of a deleted worktree, whose name differs. Refs #711 Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_018kyZYt8uiGG3xcmvaug2eG
1 parent df21c59 commit 46eb2ad

5 files changed

Lines changed: 219 additions & 29 deletions

File tree

‎docs/module-inventory.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,7 @@ Run the measurement command in the header to get a current file listing.
260260
- `managed_pg.py` — The managed PostgreSQL server's cluster root (`~/.claude/methodology/managed-pg`), its three `flock` files and `attach`/`detach` for every surface (ADR-1114)
261261
- `managed_pg_supervisor.py` — The detached process that owns one managed server: starts it, waits for its last client, stops it (ADR-1114)
262262
- `managed_pg_server.py` — Starts and stops the managed postmaster; a postmaster is ours only when its PID and kernel start time are the ones recorded at spawn (ADR-1114)
263+
- `code_graph_cache.py` — Code-graph cache ownership: writes `cortex-root.json` (the project root a graph under `~/.cache/cortex/code-graphs/` was built from) and prunes graphs whose root no longer exists; a directory without the marker is reported and kept (issue #711)
263264
- `managed_pg_process.py` — Kernel facts and waits: process start time, liveness, exit and directory events (kqueue, inotify + pidfd), no timer (ADR-1114)
264265
- `managed_pg_pidfile.py` — `postmaster.pid` of one managed cluster: the recorded postmaster's kernel proof, and whether the file's named process is its writer (kernel start time vs line 3) (ADR-1114)
265266
- `managed_pg_liveness.py` — A client never takes a `running` status whose recorded postmaster is dead: it waits for the supervisor's restart on directory events (ADR-1114)

‎mcp_server/handlers/ingest_codebase.py‎

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
build_entity_sink,
5252
)
5353
from mcp_server.shared.progress import NullProgress, ProgressReporter
54-
import shutil
54+
from mcp_server.infrastructure import code_graph_cache as graph_cache
5555

5656
logger = logging.getLogger(__name__)
5757

@@ -104,37 +104,24 @@ def _get_store() -> MemoryStore:
104104
def _default_output_dir(project_path: str) -> str:
105105
"""Default graph location under ~/.cache/cortex/code-graphs/."""
106106

107-
return str(
108-
Path.home() / ".cache" / "cortex" / "code-graphs" / project_key(project_path)
109-
)
107+
return str(graph_cache.default_cache_dir() / project_key(project_path))
110108

111109

112-
def _prune_precedent_graphs(output_dir: str) -> list[str]:
113-
"""Remove stale graphs for the SAME project once a fresh one is built.
110+
def _record_and_prune_graphs(project_path: str, output_dir: str) -> None:
111+
"""Tie ``output_dir`` to its project root, then prune orphaned graphs.
114112
115-
Remove stale sibling graph directories sharing the current project name prefix,
116-
preserving the graph just written. Returns removed directory names.
113+
Replaces the former name-prefix prune, which deleted any sibling sharing
114+
the project name's first segment (``cortex-viz-*`` for ``cortex``) and
115+
never removed a deleted worktree's graph (issue #711).
117116
118-
source: ADR-0399"""
117+
source: issue #711"""
119118

120-
cur = Path(output_dir)
121-
parent = cur.parent
122-
if not parent.is_dir():
123-
return []
124-
# Project name = key minus the trailing ``-<hash>`` segment.
125-
prefix = cur.name.rsplit("-", 1)[0] + "-"
126-
removed: list[str] = []
127-
for sib in parent.iterdir():
128-
if sib == cur or not sib.is_dir() or not sib.name.startswith(prefix):
129-
continue
119+
if Path(output_dir).expanduser().is_dir():
130120
try:
131-
shutil.rmtree(sib)
132-
removed.append(sib.name)
121+
graph_cache.write_root_marker(output_dir, project_path)
133122
except OSError as exc:
134-
logger.warning("could not prune precedent graph %s: %s", sib, exc)
135-
if removed:
136-
logger.info("pruned %d precedent graph(s): %s", len(removed), removed)
137-
return removed
123+
logger.warning("could not write root marker in %s: %s", output_dir, exc)
124+
graph_cache.prune_orphan_graphs(graph_cache.default_cache_dir())
138125

139126

140127
def _parse_int_or_none(raw: Any) -> int | None:
@@ -501,8 +488,7 @@ async def handler(
501488
"error": f"{type(exc).__name__}: {exc}",
502489
}
503490

504-
# source: ADR-0399
505-
_prune_precedent_graphs(output_dir)
491+
_record_and_prune_graphs(project_path, output_dir)
506492

507493
diagnostics: list[Any] = []
508494
do_symbols = top_symbols is None or top_symbols > 0
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
"""Code-graph cache ownership: root markers and orphan pruning (issue #711).
2+
3+
Every project or worktree where a session opens gets its own graph under
4+
``~/.cache/cortex/code-graphs/<project key>/`` (0.6 to 1.1 GB each, measured
5+
2026-10-10 on a development machine, issue #711). Nothing tied a directory to
6+
the project it was built from, so a deleted worktree left its graph behind.
7+
8+
Cortex now writes its own marker, ``cortex-root.json``, next to the graph it
9+
asks the upstream analyzer to build. The upstream ``meta.json`` belongs to the
10+
automatised-pipeline (ADR-0052: it writes it "for cortex-viz") and its schema
11+
is not defined in this repository, so it is never read or rewritten here.
12+
13+
Pruning rule: a graph directory whose marker names a root that no longer exists
14+
is removed; no session can be using a graph whose project directory is gone. A
15+
directory without a readable marker cannot be tied to a root, so it is reported
16+
and kept, never deleted on a guess.
17+
"""
18+
19+
from __future__ import annotations
20+
21+
import dataclasses
22+
import json
23+
import logging
24+
import shutil
25+
from pathlib import Path
26+
27+
logger = logging.getLogger(__name__)
28+
29+
ROOT_MARKER = "cortex-root.json"
30+
31+
32+
@dataclasses.dataclass(frozen=True)
33+
class PruneReport:
34+
"""Outcome of one pruning pass over a code-graph cache directory."""
35+
36+
removed: tuple[str, ...]
37+
unattributed: tuple[str, ...]
38+
failed: tuple[str, ...]
39+
40+
41+
def default_cache_dir() -> Path:
42+
"""The cache directory ``ingest_codebase`` writes graphs into by default."""
43+
return Path.home() / ".cache" / "cortex" / "code-graphs"
44+
45+
46+
def write_root_marker(graph_dir: str | Path, project_root: str | Path) -> None:
47+
"""Record ``project_root`` (resolved) as the root ``graph_dir`` was built from."""
48+
target = Path(graph_dir).expanduser()
49+
target.mkdir(parents=True, exist_ok=True)
50+
root = str(Path(project_root).expanduser().resolve())
51+
payload = json.dumps({"project_root": root}, indent=2) + "\n"
52+
tmp = target / (ROOT_MARKER + ".tmp")
53+
tmp.write_text(payload, encoding="utf-8")
54+
tmp.replace(target / ROOT_MARKER)
55+
56+
57+
def read_root_marker(graph_dir: Path) -> str | None:
58+
"""The recorded project root, or None when the marker is absent or unreadable."""
59+
try:
60+
data = json.loads((graph_dir / ROOT_MARKER).read_text(encoding="utf-8"))
61+
except (OSError, ValueError):
62+
return None
63+
root = data.get("project_root") if isinstance(data, dict) else None
64+
return root if isinstance(root, str) and root else None
65+
66+
67+
def prune_orphan_graphs(cache_dir: str | Path) -> PruneReport:
68+
"""Remove graphs whose recorded root is gone; report the unattributed ones."""
69+
base = Path(cache_dir).expanduser()
70+
removed: list[str] = []
71+
unattributed: list[str] = []
72+
failed: list[str] = []
73+
if not base.is_dir():
74+
return PruneReport((), (), ())
75+
for entry in sorted(base.iterdir()):
76+
if not entry.is_dir():
77+
continue
78+
root = read_root_marker(entry)
79+
if root is None:
80+
unattributed.append(entry.name)
81+
elif not Path(root).exists():
82+
try:
83+
shutil.rmtree(entry)
84+
removed.append(entry.name)
85+
except OSError as exc:
86+
logger.warning("could not prune orphan graph %s: %s", entry, exc)
87+
failed.append(entry.name)
88+
_log_report(base, removed, unattributed)
89+
return PruneReport(tuple(removed), tuple(unattributed), tuple(failed))
90+
91+
92+
def _log_report(base: Path, removed: list[str], unattributed: list[str]) -> None:
93+
if removed:
94+
logger.info("pruned %d orphan code graph(s): %s", len(removed), removed)
95+
if unattributed:
96+
logger.warning(
97+
"%d code graph(s) under %s carry no %s and cannot be tied to a "
98+
"project root; kept, remove by hand if unused: %s",
99+
len(unattributed),
100+
base,
101+
ROOT_MARKER,
102+
unattributed,
103+
)
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
"""Code-graph cache root markers and orphan pruning (issue #711)."""
2+
3+
from __future__ import annotations
4+
5+
import json
6+
import logging
7+
from pathlib import Path
8+
9+
from mcp_server.infrastructure import code_graph_cache as cache
10+
11+
12+
def _graph(cache_dir: Path, name: str, root: Path | None) -> Path:
13+
graph_dir = cache_dir / name
14+
(graph_dir / "graph").mkdir(parents=True)
15+
(graph_dir / "graph" / "data").write_bytes(b"x")
16+
if root is not None:
17+
cache.write_root_marker(graph_dir, root)
18+
return graph_dir
19+
20+
21+
def test_marker_records_the_resolved_root(tmp_path: Path) -> None:
22+
root = tmp_path / "proj"
23+
root.mkdir()
24+
graph_dir = tmp_path / "cache" / "proj-1234abcd"
25+
cache.write_root_marker(graph_dir, root / ".." / "proj")
26+
data = json.loads((graph_dir / cache.ROOT_MARKER).read_text(encoding="utf-8"))
27+
assert data == {"project_root": str(root.resolve())}
28+
assert cache.read_root_marker(graph_dir) == str(root.resolve())
29+
30+
31+
def test_graph_of_a_deleted_root_is_pruned(tmp_path: Path) -> None:
32+
worktree = tmp_path / "wt"
33+
worktree.mkdir()
34+
cache_dir = tmp_path / "cache"
35+
graph_dir = _graph(cache_dir, "wt-0000aaaa", worktree)
36+
worktree.rmdir()
37+
38+
report = cache.prune_orphan_graphs(cache_dir)
39+
40+
assert report.removed == ("wt-0000aaaa",)
41+
assert not graph_dir.exists()
42+
43+
44+
def test_graph_of_a_live_root_is_kept(tmp_path: Path) -> None:
45+
root = tmp_path / "live"
46+
root.mkdir()
47+
cache_dir = tmp_path / "cache"
48+
graph_dir = _graph(cache_dir, "live-1111bbbb", root)
49+
50+
report = cache.prune_orphan_graphs(cache_dir)
51+
52+
assert report.removed == ()
53+
assert graph_dir.is_dir()
54+
55+
56+
def test_directory_without_marker_is_reported_not_deleted(
57+
tmp_path: Path, caplog
58+
) -> None:
59+
cache_dir = tmp_path / "cache"
60+
legacy = _graph(cache_dir, "legacy-2222cccc", None)
61+
62+
with caplog.at_level(logging.WARNING, logger=cache.__name__):
63+
report = cache.prune_orphan_graphs(cache_dir)
64+
65+
assert report.unattributed == ("legacy-2222cccc",)
66+
assert report.removed == ()
67+
assert legacy.is_dir()
68+
assert "legacy-2222cccc" in caplog.text
69+
70+
71+
def test_unreadable_marker_counts_as_unattributed(tmp_path: Path) -> None:
72+
cache_dir = tmp_path / "cache"
73+
graph_dir = _graph(cache_dir, "bad-3333dddd", None)
74+
(graph_dir / cache.ROOT_MARKER).write_text("{not json", encoding="utf-8")
75+
76+
report = cache.prune_orphan_graphs(cache_dir)
77+
78+
assert report.unattributed == ("bad-3333dddd",)
79+
assert graph_dir.is_dir()
80+
81+
82+
def test_prefix_sharing_project_is_not_touched(tmp_path: Path) -> None:
83+
"""The former name-prefix prune removed ``cortex-viz-*`` when ``cortex`` ran."""
84+
cortex = tmp_path / "cortex"
85+
viz = tmp_path / "cortex-viz"
86+
cortex.mkdir()
87+
viz.mkdir()
88+
cache_dir = tmp_path / "cache"
89+
_graph(cache_dir, "cortex-4444eeee", cortex)
90+
viz_graph = _graph(cache_dir, "cortex-viz-5555ffff", viz)
91+
92+
report = cache.prune_orphan_graphs(cache_dir)
93+
94+
assert report.removed == ()
95+
assert viz_graph.is_dir()
96+
97+
98+
def test_missing_cache_dir_is_empty_report(tmp_path: Path) -> None:
99+
report = cache.prune_orphan_graphs(tmp_path / "absent")
100+
assert report == cache.PruneReport((), (), ())

‎tests_py/test_ingest_progress.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -283,7 +283,7 @@ async def _fake_enrich(*args: Any, **kwargs: Any):
283283
monkeypatch.setattr(icb, "_pull_processes", _fake_pull_processes)
284284
monkeypatch.setattr(icb, "_enrich_process_symbols", _fake_enrich)
285285
monkeypatch.setattr(icb_pages, "write_process_pages", lambda _procs: [])
286-
monkeypatch.setattr(icb, "_prune_precedent_graphs", lambda _: [])
286+
monkeypatch.setattr(icb, "_record_and_prune_graphs", lambda *_: None)
287287

288288
reporter = FakeReporter()
289289
result = await icb.handler(
@@ -338,7 +338,7 @@ async def _fake_enrich(*args: Any, **kwargs: Any):
338338
monkeypatch.setattr(icb, "_pull_processes", _fake_pull_processes)
339339
monkeypatch.setattr(icb, "_enrich_process_symbols", _fake_enrich)
340340
monkeypatch.setattr(icb_pages, "write_process_pages", lambda _procs: [])
341-
monkeypatch.setattr(icb, "_prune_precedent_graphs", lambda _: [])
341+
monkeypatch.setattr(icb, "_record_and_prune_graphs", lambda *_: None)
342342

343343
np = NullProgress()
344344
result = await icb.handler(

0 commit comments

Comments
 (0)