codegraph structure: directory fileCount/cohesion metrics go stale on incremental rebuild after adding a new file

[carlos-alm]

Summary

codegraph structure --depth 2 --json reports stale fileCount/symbolCount/fanIn/cohesion/density for a directory after an incremental rebuild adds a brand-new file to that directory. The stale values persist until a full rebuild (codegraph build --no-incremental) recomputes them.

Root cause (likely)

computeDirectoryMetrics in src/features/structure.ts:348 computes and upserts per-directory metrics (fileCount = files.length at line 365, etc.) as part of buildStructure. This appears to only be invoked/refreshed for directories affected by the incremental build's scoped file set, not unconditionally recomputed for every directory that gained a file. When a new file is added to an existing directory and the repo's post-edit hook triggers an incremental/scoped rebuild (not a full rebuild), the directory's cached metrics row in the DB is not refreshed to include the new file.

Repro

1. In a repo with an existing directory, e.g. src/shared/ (10 files at HEAD), add a new file src/shared/sleep.ts exporting one function.
2. Let the incremental build/rebuild run (e.g. via the repo's post-edit hook, or codegraph build without --no-incremental after the file hash cache is warm).
3. Run:

   codegraph structure --depth 2 --json
   

   The src/shared entry still reports fileCount: 10 — the new file is not counted, even though:
   • ls src/shared/*.ts shows 11 files.
   • A direct query of the DB (SELECT DISTINCT file FROM nodes WHERE file LIKE 'src/shared/%') returns all 11 files, including the new one.
   • codegraph fn-impact <symbolInNewFile> correctly resolves the symbol to the new file.
4. Run codegraph build --no-incremental, then re-run codegraph structure --depth 2 --json — src/shared.fileCount now correctly shows 11.

This shows the underlying graph (nodes/edges tables) is correctly updated by the incremental build, but the separately-cached directory-metrics table used by codegraph structure is not.

Impact

Any tooling that diffs codegraph structure output before/after a change to detect "cohesion drift" (e.g. an architectural-snapshot gate) will silently miss real changes to a directory's file count/cohesion whenever the change added a new file and only an incremental rebuild ran in between — the comparison will show zero delta for a directory that actually changed, masking genuine cohesion regressions until someone happens to run a full rebuild.

Fix direction

Ensure computeDirectoryMetrics recomputes metrics for every ancestor directory of any file touched by the incremental build (added, removed, or modified), not just directories in some pre-filtered "changed" set — or make buildStructure's directory-metrics pass always operate over the full current directory→file mapping (which is cheap relative to the rest of an incremental build) rather than a scoped subset.

Context

Found while running the Titan Paradigm forge pipeline (/titan-forge --phase 5) on worktree-titan-run, during Step 5.5 (architectural snapshot comparison) of /titan-gate, while diffing codegraph structure --depth 2 --json output against a pre-forge baseline to check for cohesion drift after adding src/shared/sleep.ts. Not blocking that change (a full rebuild confirmed the real cohesion delta is negligible, ~0.00008), filed here per project scope-discipline convention.