Improve common read performance

[lzehrung]

Summary

• Add a derived graph adjacency index to ProjectIndex and route common in-memory reads through it.
• Reuse the indexed graph path for CLI deps, rdeps, path, cycles, and unresolved while preserving injected collector test seams.
• Optimize high-level SQLite canned dependency traversals with indexed stepwise neighbor lookups instead of loading all file edges.
• Document the optimized read paths without changing CLI flags or output contracts.

Accuracy safeguards

• Preserves edge order for traversal results and shortest-path tie behavior.
• Keeps direct graph queries compatible with plain Graph values and avoids stale mutable graph caches.
• Threads discovery, native mode, graph options, progress, and worker options through the indexed CLI graph-query path.
• Adds regression coverage for adjacency traversal shape, CLI index-backed graph reads, discovery-ignore behavior, SQLite cycles, and incremental SQLite edge updates.
• No persistent SQLite schema changes.

Verification

• npm run build
• npm run lint
• npm run test:ci (161 files, 1557 tests)
• node .\dist\cli.js deps src/index.ts --json
• node .\dist\cli.js rdeps src/index.ts --json
• node .\dist\cli.js path src/cli.ts src/index.ts --json
• node .\dist\cli.js search "sqlite graph" --json

[Copilot]

Pull request overview

Adds a derived forward/reverse adjacency index to ProjectIndex and routes common in-memory graph reads (deps, rdeps, path) through it instead of repeatedly scanning graph.edges. CLI graph-query commands now reuse the indexed ProjectIndex graph when no explicit collectGraph is injected, and SQLite canned dependency-chain / affected-functions traversals walk file_edges via indexed stepwise neighbor queries rather than loading every edge into memory.

Changes:

• New src/graphs/adjacency.ts builds forward/reverse Map<FileId, FileId[]> indexes preserving edge order; ProjectIndex now exposes an optional graphAdjacency.
• getDependencies / getReverseDependencies / getShortestPath accept an adjacency option; CLI deps/rdeps/path/cycles/unresolved load via the index-backed path with discovery/native/graph/worker options propagated.
• src/sqlite.ts replaces loadFileEdges + in-memory BFS with stepwise indexed SELECT ... WHERE to_type='file' AND from_path/to_path = ? queries through a shared bfsFileTraversal.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/graphs/adjacency.ts	New helper module building/querying forward+reverse file adjacency.
src/graphs/queries.ts	Routes BFS/shortest-path through adjacency, with optional injected index.
src/indexer/types.ts	Adds optional graphAdjacency field on ProjectIndex.
src/indexer/build-index.ts	Populates graphAdjacency on all ProjectIndex return paths.
src/cli/graphQueries.ts	loadGraph now prefers buildProjectIndex and returns adjacency alongside graph.
src/cli.ts	Threads discovery/native/graph/worker options into indexOptions for graph-query commands.
src/sqlite.ts	Removes loadFileEdges/inline BFS; adds indexed neighbor queries and shared bfsFileTraversal.
tests/graph-queries.test.ts	Performance-shape test asserting adjacency is built once per query.
tests/cli-command-modules.test.ts	Verifies graph-query commands use buildProjectIndex path and indexed adjacency.
tests/cli-regressions.test.ts	Ensures unresolved honors codegraph.config.json discovery ignores.
tests/sqlite.test.ts	Adds regressions for cyclic file traversal and incremental edge updates.
docs/how-it-works.md, docs/cli.md	Document the optimized read paths.
docs/superpowers/plans/2026-05-17-read-performance.md	New implementation plan document.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.