feat: harden multi-repo registry and add structural analysis

[carlos-alm]

Summary

• Registry pruning: New pruneRegistry() removes stale entries where the repo directory no longer exists on disk, exposed via codegraph registry prune
• MCP repo allowlist: --repos <names> option on codegraph mcp restricts which registered repos the MCP server can access (tool calls and list_repos are filtered)
• Name collision auto-suffix: registerRepo now auto-suffixes when a basename collides with a different path (api → api-2), preventing silent overwrites during auto-registration
• Structural analysis: New src/structure.js module makes directories first-class graph nodes with containment edges and per-file/per-directory metrics (symbol density, avg fan-out, cohesion). Adds codegraph structure and codegraph hotspots CLI commands, MCP tools, and DOT/Mermaid directory clusters

Changed files

File	Changes
src/registry.js	pruneRegistry(), registerRepo() auto-suffix
src/mcp.js	options.allowedRepos param + filtering
src/cli.js	registry prune, --repos on mcp, structure, hotspots commands
src/index.js	New exports
src/structure.js	New module — build-time + query-time structure analysis
src/builder.js	Directory collection, line counts, buildStructure call
src/db.js	node_metrics table in schema
src/export.js	Directory cluster support in DOT/Mermaid
tests/unit/registry.test.js	Prune + collision tests
tests/unit/mcp.test.js	Allowlist filtering tests
tests/unit/structure.test.js	Structure metrics unit tests
tests/integration/cli.test.js	CLI integration tests
tests/integration/structure.test.js	Full build + query integration tests

Test plan

• npm run lint — 0 errors
• npm test — 362 passed, 0 failed
• Manual: codegraph registry prune on a system with stale entries
• Manual: codegraph mcp --repos repo1,repo2 restricts tool access
• Manual: codegraph structure and codegraph hotspots on a real project

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

Adds directories as first-class graph nodes with computed metrics (cohesion, fan-in/out, symbol density) and two new commands (structure, hotspots) plus MCP tools for AI integration.

Key changes:

• New src/structure.js module with buildStructure() for metrics computation and query functions
• node_metrics table added to v1 schema (no migration needed since there are no existing users)
• collectFiles() now tracks directories during traversal
• DOT exporter uses DB directory nodes with cohesion labels (fallback to path.dirname() for old DBs)
• Registry enhancements: auto-suffixing for basename collisions, prune command for stale entries
• MCP server gains --repos allowlist for access control
• 20 new tests (7 unit, 13 integration) with comprehensive coverage

Security concern:

• hotspotsData() in src/structure.js:329 uses string interpolation for SQL ORDER BY clause. While metricToColumn() validates inputs via switch statement, this pattern is vulnerable if future changes allow untrusted input to bypass validation.

Confidence Score: 4/5

• Safe to merge with one SQL injection risk requiring attention
• The implementation is well-architected with comprehensive tests (20 new tests, all passing), proper error handling, and backward compatibility. However, the SQL injection vulnerability in hotspotsData() with dynamic ORDER BY construction prevents a perfect score. The risk is currently mitigated by input validation in metricToColumn(), but the pattern is fragile.
• src/structure.js requires fixing the SQL injection risk at line 329

Important Files Changed

Filename	Overview
src/structure.js	New module introducing directory-level graph nodes, metrics computation (cohesion, fan-in/out), and query functions. SQL injection risk in hotspotsData line 329 with dynamic ORDER BY.
src/builder.js	Updated collectFiles to track directories and added structure analysis integration after edge building. Clean implementation with proper error handling.
src/db.js	Added node_metrics table to v1 schema with proper foreign keys and indexes. Schema design is sound.
src/export.js	DOT exporter now uses directory nodes from DB with cohesion labels, falls back gracefully to path.dirname() for old DBs.
src/cli.js	Added structure and hotspots commands with proper option parsing, plus registry prune command and MCP --repos filter option.
src/mcp.js	Added structure and hotspots MCP tools with proper schema validation, plus allowedRepos access control for multi-repo scenarios.

Entity Relationship Diagram

%%{init: {'theme': 'neutral'}}%%
erDiagram
    nodes ||--o{ node_metrics : "has metrics"
    nodes ||--o{ edges : "source"
    nodes ||--o{ edges : "target"
    
    nodes {
        int id PK
        string name
        string kind "file, directory, function, class, etc"
        string file
        int line
        int end_line
    }
    
    node_metrics {
        int node_id PK,FK
        int line_count "files only"
        int symbol_count "deduplicated definitions"
        int import_count "files only"
        int export_count "files only"
        int fan_in "cross-boundary imports"
        int fan_out "cross-boundary imports"
        real cohesion "intra_edges divided by total_edges"
        int file_count "directories only"
    }
    
    edges {
        int id PK
        int source_id FK
        int target_id FK
        string kind "imports, contains, calls, etc"
        real confidence
        int dynamic
    }

Loading

_{Last reviewed commit: 691fefe}

[greptile-apps]

_{13 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

SQL injection risk: ${orderCol} is directly interpolated into the SQL query. While metricToColumn() validates the input with a switch statement, this pattern is fragile. If future code changes allow untrusted input to reach this function, it creates a vulnerability.

Suggested change

	ORDER BY ${orderCol} DESC
	ORDER BY ${orderCol} DESC NULLS LAST

Also consider using parameterized queries or a whitelist of allowed column names directly in the query builder for defense in depth.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[carlos-alm]

Good catch on NULLS LAST — added in a41668f.

On the SQL injection concern: metricToColumn() is a closed switch/case that only returns hardcoded column expressions (nm.fan_in, nm.fan_out, etc.) with a safe default fallback. No external input reaches the SQL string. That said, the NULLS LAST addition is a genuine correctness fix — without it NULL metrics would sort to the top.