@layrx/dependency-graph

Dependency Graph Builder for LayrX – analyses import/export relationships after repository indexing.

Purpose

Reads indexed file metadata from SQLite, parses TypeScript and JavaScript sources with Tree-sitter, extracts imports and exports, builds direct relationship edges, and persists the graph for querying.

Flow

indexRepository(path)          ← Feature #1 (prerequisite)
        ↓
buildDependencyGraph(path)
        ↓
Read files from SQLite
        ↓
Tree-sitter parse (.ts/.tsx/.js/.jsx)
        ↓
ImportResolver + ExportResolver
        ↓
RelationshipBuilder
        ↓
GraphStorage → graph_nodes / graph_edges
        ↓
GraphBuildStatistics

Architecture

| Module | Responsibility | |--------|----------------| | ImportResolver | Tree-sitter import extraction | | ExportResolver | Export and re-export extraction | | RelationshipBuilder | Node/edge construction and path resolution | | GraphStorage | SQLite persistence and queries | | DependencyGraphBuilder | Orchestrates the full pipeline |

Database tables

graph_nodes

| Column | Description | |--------|-------------| | id | UUID primary key | | repository_id | FK to repositories | | node_type | File, Function, Component, Hook, Class, Interface, Enum | | name | Symbol or file name | | file_path | Repository-relative path | | metadata | Optional JSON |

graph_edges

| Column | Description | |--------|-------------| | id | UUID primary key | | repository_id | FK to repositories | | source_node_id | FK to graph_nodes | | target_node_id | FK to graph_nodes | | edge_type | IMPORTS, EXPORTS, DEPENDS_ON, USES | | metadata | Optional JSON |

Public API

import { indexRepository } from '@layrx/repository';
import {
  buildDependencyGraph,
  getNode,
  getEdges,
  getDependencies,
  getDependents,
} from '@layrx/dependency-graph';

await indexRepository('./my-repo', { databasePath: './data/layrx.db' });

const result = await buildDependencyGraph('./my-repo', {
  databasePath: './data/layrx.db',
});

console.log(result.statistics);

const deps = getDependencies('src/app.ts');
const dependents = getDependents('src/utils.ts');

Edge semantics

| Edge | Meaning | Example | |------|---------|---------| | IMPORTS | File imports another local file | app.ts → utils.ts | | EXPORTS | File exports a symbol | utils.ts → helper function | | DEPENDS_ON | Service/utility dependency | service.ts → utils.ts | | USES | Component uses a hook | Counter.tsx → useCounter |

Dependencies

• tree-sitter, tree-sitter-typescript, tree-sitter-javascript
• @layrx/repository, @layrx/database, @layrx/logger

Tests

npm run test --workspace=@layrx/dependency-graph

Future improvements

• Vue SFC parsing (.vue files)
• Python, Go, Rust grammars
• Transitive dependency closure (optional analysis mode)
• Symbol-level call graph (intra-file usage)
• Integration with file watcher for incremental graph updates
• .gitignore-aware external package nodes

Future extension points

• React: Component/hook heuristics already use PascalCase + use* naming; extend with JSX body analysis
• Vue: Add ExportResolver branch for <script setup> and composable imports
• Node: Class/service DEPENDS_ON edges already cover server-side modules; add CommonJS require() support

Performance considerations

• Parses only supported extensions already indexed in SQLite
• Skips failed files and continues (error tolerant)
• Uses in-memory node deduplication before bulk SQLite insert
• Direct relationships only (no transitive expansion)
• Tree-sitter incremental parse can be added later for watcher-driven updates