Skip to content

progress.md

Latest commit

 

History

History
116 lines (97 loc) · 8.45 KB

progress.md

File metadata and controls

116 lines (97 loc) · 8.45 KB
Raw

Codebase Intelligence Graph — Project Progress & Roadmap

This document tracks the current implementation progress against the proposal in Codebase Intelligence Graph — Initial POC Proposal.md, listing completed features, upcoming versions, and current tasks.

1. Current Progress (Initial POC — Completed)

The foundational pipeline (Repository $\rightarrow$ AST $\rightarrow$ Module Resolution $\rightarrow$ Graph Model $\rightarrow$ Layout $\rightarrow$ Interactive UI) is complete and fully functional.

✅ Completed Capabilities:

  • Scanner & AST Engine (server/analyzer.ts):
    • Auto-discovery of .ts and .tsx source files using fast-glob, ignoring node_modules and build directories.
    • AST parsing via ts-morph.
    • tsconfig.json detection to respect compiler options and path aliases (@/*).
    • Import (ImportDeclaration) and Re-export (ExportDeclaration) resolution to internal source files.
    • Filtering external packages and standard libraries to focus purely on internal codebase structure.
    • In-memory graph model generation with portable, relative-path node IDs.
    • Calculation of fan-in (incoming callers) and fan-out (outgoing imports) metrics.
  • Backend API (server/index.ts):
    • Express server on port 3001 with POST /api/analyze and GET /api/graph?path=....
    • Codebase presets endpoint GET /api/presets.
    • Resilient fallback mock dataset (server/mockData.ts).
  • Dagre Layout Engine (src/utils/layout.ts):
    • Automated hierarchical arrangement with toggleable Top-to-Bottom (TB) and Left-to-Right (LR) directions.
    • Dynamic edge generation with animated flowing arrows and bezier curves.
  • Interactive UI (src/components/):
    • React Flow (@xyflow/react) canvas with minimap, zoom/fit controls, and background grid.
    • Custom file nodes with category badges (Component, Hook, Service, Util, Type).
    • Neighborhood focus: active node glows indigo, incoming callers in cyan, outgoing dependencies in purple with animated dashes, unrelated files dimmed to 15%.
    • Inspector sidebar showing relative path, callers, and dependencies with clickable jump-to-node links.
    • Search bar with autocomplete and preset switcher.
  • Test Repository (example-repo/):
    • 10 interdependent React + TypeScript files covering components, hooks, services, utils, types, and barrel re-exports.

2. Completed Feature: Straightforward Symbol Extraction (Version 2 Fast-Track)

Objective: Extract what functions, components, hooks, and types exist inside each file and surface them in the application inspector.

✅ Completed & Verified (commit 1973f75):

  • AST Symbol Extractor (server/analyzer.ts):
    • Parses FunctionDeclaration, VariableDeclaration (arrow functions/components), InterfaceDeclaration, TypeAliasDeclaration, and ClassDeclaration.
    • Discovers 7 symbol kinds (component, hook, function, interface, type, class, variable).
    • Detects export visibility (isExported: true/false).
  • Interactive Inspector UI (src/components/Sidebar.tsx):
    • Displays "Symbols & Declarations (N)" section with colored badges for each symbol type (sky for components, amber for hooks, indigo for functions, fuchsia for types).
    • Shows export status badges (export in emerald vs internal in slate).
  • File Node Badges (src/components/FileNode.tsx):
    • Shows live symbol count pill (e.g. 2 syms, 3 syms) in each file node header on the canvas.
  • Unit Testing & Browser Verification:
    • Validated with npm run test:analyzer (10 files, 15 symbols extracted).
    • Verified in interactive browser session (e.g. inspecting Chat.tsx, types/chat.ts, services/api.ts).
  • Visual Folder Browser & Native OS Dialog (src/components/FolderBrowserModal.tsx & server/index.ts):
    • In-app visual directory navigator with breadcrumb navigation and shortcuts (Desktop, Home, ProjectX, example-repo).
    • Automatic Codebase badge detection for folders containing package.json or tsconfig.json.
    • Native Windows Explorer Folder Dialog integration via /api/browse-folder.
    • 0 file uploads required: passes directory path directly to the AST engine.
  • Topological Sort Engine & Developer Onboarding Guide (src/utils/topoSort.ts & src/components/TopoOrderDrawer.tsx):
    • Kahn's algorithm computing linear order across both Execution Flow (Entrypoint $\rightarrow$ Leaves, default) and Build Order (Leaves $\rightarrow$ Entrypoint).
    • Interactive direction toggle with contextual developer tips explaining runtime boot sequence vs compilation prerequisites.
    • Automatic Architectural Layering (Entrypoints $\rightarrow$ Containers $\rightarrow$ Layouts $\rightarrow$ Hooks $\rightarrow$ APIs $\rightarrow$ Utilities $\rightarrow$ Types).
    • Slide-out "Topological Flow Order" drawer with step-by-step reading guide and jump-to-node links.
  • Interactive Canvas Stepper / Flow Player (src/components/CanvasFlowPlayer.tsx):
    • Bottom docked player with Play, Pause, Next, Prev, First, Last, and speed toggles (0.5x, 1.0x, 2.0x).
    • Real-time visual synchronization on React Flow: lights up current step node with glowing amber ring, dims unreached modules, and animates progress bar.
  • Instant Circular Dependency Cycle Detection & Fault-Tolerant Sort (src/utils/topoSort.ts & src/components/CycleAlertModal.tsx):
    • Cycle-Breaking Heuristic: When circular dependencies ($A \rightarrow B \rightarrow C \rightarrow A$) exist, the engine identifies the loop, bypasses the deadlock, and completes topological sort for 100% of the codebase.
    • Diagnostic Highlighting: Flags cyclic nodes in crimson red with clear warnings in the drawer, stepper, and canvas, while ensuring the healthy 95% of the repository's flow is never hidden.
    • Flashing header alert pill and one-click canvas cycle isolation with glowing crimson red nodes and animated edges.

3. Current Active / Next Recommended Milestone: Multi-Hop BFS Impact Analysis ("Blast Radius")

Objective: Move beyond direct 1-hop dependencies to compute full architectural propagation:

  • Implement BFS graph traversal from any selected node across upstream dependents.
  • Calculate direct impact (Level 1) vs indirect impact (Level 2+).
  • Display total "Blast Radius" counter badge in the Inspector Sidebar.
  • Visual multi-tiered highlighting on the canvas (e.g. level 1 callers in cyan, level 2+ in deep blue).

4. Future Versions Roadmap

🚀 Version 2 (Full): Symbol-Level Graph Hierarchy

  • File-to-Symbol containment edges: Representing FILE ──CONTAINS──▶ SYMBOL in the graph model.
  • Expandable Node Clusters: Ability to expand a file node on the canvas to see internal function pills inside the node box.

🚀 Version 3: Symbol-Level Relationships

  • Cross-file call graphs:
    • Component ──RENDERS──▶ Component (e.g. Chat renders MessageList).
    • Function/Hook ──CALLS──▶ Function (e.g. Message calls formatTimestamp).
    • Component ──USES──▶ Hook (e.g. Chat uses useChat).
  • Semantic AST resolution tracing identifiers back to import declarations.

🚀 Version 4: Multi-Hop Impact Analysis ("Blast Radius")

  • BFS Traversal Engine:
    • Level 1: Direct dependents.
    • Level 2: Indirect dependents.
    • Level $N$: Deep architectural ripple effects.
  • Impact Counter: "Changing formatDate.ts directly impacts 1 file and indirectly affects 4 files (Total reachable blast radius: 5 files)."
  • Color-coded depth tiers on the canvas during inspection.

🚀 Version 5: Architecture Intelligence & Linting

  • Circular Dependency Detection: Automated cycle detection algorithm (Tarjan's or Johnson's algorithm) highlighting illegal dependency loops in red.
  • Hotspot & Coupling Metrics:
    • Identifying God-objects / architectural bottlenecks (files with excessive fan-in).
    • High instability / volatile files (excessive fan-out).
  • Architecture Clustering: Grouping nodes into logical modules or layers (Presentation, Domain, Infrastructure).

🚀 Version 6: Integrations & Tooling

  • CLI Export: Run npx codebase-graph export --path ./src --output graph.json in CI/CD.
  • Markdown Architecture Report Generator: Automatic architectural health report.
  • VS Code Extension: View the dependency neighborhood directly inside the editor sidebar.