feat(AST indexing): Implement relationship index

[PatrickSys]

What / Why

Implements relationship indexing so we have an indexed import graph for files and symbols (AST-aware) and unlocks future tooling capabilities.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[greptile-apps]

Greptile Summary

Implements AST-aware relationship indexing via a new relationships.json artifact that stores the file import graph, reverse imports (importedBy), and symbol export index (exportedBy). This unlocks future tooling capabilities like fast symbol lookup and dependency analysis without parsing intelligence.json.

Key changes:

• New relationships.json artifact generated during both full and incremental indexing, properly versioned with buildId and formatVersion
• Integrated into atomic staging/swap logic with proper rollback support
• Version validation ensures relationships artifact matches index-meta.json
• Tools (detect_circular_dependencies, search_codebase) updated to prefer relationships sidecar over intelligence.json with graceful fallback
• Comprehensive test coverage for creation, validation, incremental updates, and rebuilds
• Documentation updated in CHANGELOG, README, and capabilities docs

The implementation follows the project's zero-infra, crash-safe, and incremental indexing principles. All artifacts are properly versioned and validated to prevent mixed-version corruption.

Confidence Score: 5/5

• Safe to merge with no issues found
• The implementation is thorough and well-tested with proper error handling, version validation, atomic swap semantics, rollback support, and graceful fallbacks. Code follows existing patterns and respects all project constraints from AGENTS.md. Documentation accurately reflects the implementation.
• No files require special attention

Important Files Changed

Filename	Overview
src/core/indexer.ts	Added relationships.json generation with reverse import map and symbol export index; properly integrated into staging/active swap and rollback logic
src/core/index-meta.ts	Added relationships artifact validation with proper schema checking and version/buildId matching
src/tools/detect-circular-dependencies.ts	Updated to prefer relationships sidecar over intelligence.json for graph data with graceful fallback
src/tools/search-codebase.ts	Updated to use relationships sidecar for import graph lookups with intelligence.json fallback; improved separation of concerns
tests/relationship-sidecar.test.ts	Comprehensive test coverage for relationships.json creation, validation, incremental updates, and rebuild scenarios

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Index Build] --> B{Full Rebuild?}
    B -->|Yes| C[Write to .staging/buildId/]
    B -->|No| D[Write to .codebase-context/]
    
    C --> E[Generate intelligence.json]
    D --> E
    
    E --> F[Extract internalFileGraph]
    F --> G[Build relationships.json]
    
    G --> H[Create imports map]
    G --> I[Build importedBy reverse map]
    G --> J[Build exportedBy symbol index]
    
    H --> K[Write relationships.json with header]
    I --> K
    J --> K
    
    K --> L{Full Rebuild?}
    L -->|Yes| M[Atomic Swap: .staging → active]
    L -->|No| N[Direct write to active]
    
    M --> O[Move active → .previous]
    O --> P[Move staging → active]
    P -->|Success| Q[Cleanup .previous & .staging]
    P -->|Failure| R[Rollback: .previous → active]
    
    N --> S[Index Ready]
    Q --> S
    
    S --> T[Tools read relationships.json]
    T --> U[detect_circular_dependencies]
    T --> V[search_codebase]
    
    U --> W{relationships.json exists?}
    V --> W
    W -->|Yes| X[Use relationships sidecar]
    W -->|No| Y[Fallback to intelligence.json]

Loading

_{Last reviewed commit: 5b4dbe4}

[greptile-apps]

_{9 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}