@kodus/kodus-graph 0.2.8 → 0.2.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kodus AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# @kodus/kodus-graph
+
+[![npm version](https://img.shields.io/npm/v/@kodus/kodus-graph)](https://www.npmjs.com/package/@kodus/kodus-graph)
+[![license](https://img.shields.io/npm/l/@kodus/kodus-graph)](LICENSE)
+[![Bun](https://img.shields.io/badge/runtime-Bun-%23f9f1e1)](https://bun.sh)
+
+Code graph builder for Kodus code review. Parses source code into structural graphs with nodes, edges, and analysis — enabling blast radius detection, risk scoring, test gap analysis, and enriched review context for AI agents.
+
+## Features
+
+- **Multi-language** — TypeScript, Python, Go, Java, Ruby, Rust, C#, PHP
+- **Structural graph** — Functions, classes, interfaces, enums as nodes; CALLS, IMPORTS, INHERITS, IMPLEMENTS, TESTED_BY, CONTAINS as edges
+- **Call resolution** — 5-tier confidence cascade with DI pattern detection
+- **Incremental parsing** — Content hashing skips unchanged files
+- **Streaming JSON** — Memory-efficient output for large codebases
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.3.0
+
+## Installation
+
+```bash
+# Global (recommended for CLI usage)
+bun install -g @kodus/kodus-graph
+
+# Or via npm/yarn (requires Bun as runtime)
+npm install -g @kodus/kodus-graph
+yarn global add @kodus/kodus-graph
+```
+
+## Quick Start
+
+```bash
+# 1. Parse a repository
+kodus-graph parse --all --repo-dir ./my-project --out graph.json
+
+# 2. Analyze changed files
+kodus-graph analyze --files src/auth.ts src/db.ts --graph graph.json --out analysis.json
+
+# 3. Generate review context for AI agents
+kodus-graph context --files src/auth.ts --graph graph.json --out context.json --format json
+```
+
+## Commands
+
+### `parse`
+
+Builds the structural graph of your codebase — extracts every function, class, interface, enum, and their relationships (calls, imports, inheritance).
+
+**When to use:** First step in any workflow. Run once on the full repo to create the baseline graph, then use `update` for incremental changes.
+
+```bash
+# Parse all files
+kodus-graph parse --all --repo-dir . --out graph.json
+
+# Parse specific files
+kodus-graph parse --files src/auth.ts src/db.ts --repo-dir . --out graph.json
+
+# With glob filters
+kodus-graph parse --all --repo-dir . --out graph.json \
+  --include "src/**/*.ts" \
+  --exclude "**/*.test.ts" "**/*.spec.ts"
+```
+
+**Output:** JSON with `metadata`, `nodes`, and `edges`. See [example output](examples/parse-output.json).
+
+### `analyze`
+
+Computes the impact of code changes — how far the blast radius reaches, how risky the change is (4-factor score), and which changed functions lack tests.
+
+**When to use:** During code review or CI, to assess the risk of a PR before merging.
+
+```bash
+kodus-graph analyze \
+  --files src/auth.ts src/user.service.ts \
+  --graph graph.json \
+  --out analysis.json
+```
+
+**Output:** `blast_radius`, `risk_score` (level + factors), `test_gaps`. See [example output](examples/analyze-output.json).
+
+### `context`
+
+Generates enriched review context for AI agents — caller/callee chains, affected execution flows, inheritance, risk assessment, and test coverage per changed function.
+
+**When to use:** Feed this to an LLM-based code reviewer so it understands the full impact of a change, not just the diff.
+
+```bash
+# JSON format (for programmatic use)
+kodus-graph context \
+  --files src/auth.ts \
+  --graph graph.json \
+  --out context.json \
+  --format json
+
+# Prompt format (for LLM agents)
+kodus-graph context \
+  --files src/auth.ts \
+  --graph graph.json \
+  --out context.txt \
+  --format prompt \
+  --min-confidence 0.5 \
+  --max-depth 3
+```
+
+**Output:** Enriched functions with callers, callees, affected flows, risk level. See [example output](examples/context-output.json).
+
+### `diff`
+
+Detects structural changes between the current code and a previous graph — which nodes/edges were added, removed, or modified (signature, body, line range).
+
+**When to use:** To understand what actually changed structurally in a PR, beyond the raw text diff.
+
+```bash
+# Diff against a git ref
+kodus-graph diff --base main --graph graph.json --out diff.json
+
+# Diff specific files
+kodus-graph diff --files src/auth.ts --graph graph.json --out diff.json
+```
+
+**Output:** Added/removed/modified nodes and edges with detail on what changed.
+
+### `update`
+
+Incrementally updates an existing graph — only re-parses files whose content hash changed. Much faster than a full parse on large repos.
+
+**When to use:** After each commit or PR merge to keep the baseline graph up to date without re-parsing the entire codebase.
+
+```bash
+kodus-graph update --repo-dir . --graph graph.json
+```
+
+### `communities`
+
+Groups code into module clusters based on directory structure and detects coupling between them (how many cross-cluster calls exist).
+
+**When to use:** To understand the modular architecture of a codebase and identify tightly coupled areas that may need refactoring.
+
+```bash
+kodus-graph communities --graph graph.json --out communities.json --min-size 2 --depth 2
+```
+
+### `flows`
+
+Detects entry points (HTTP handlers, test functions) and traces their execution paths through the call graph.
+
+**When to use:** To understand which user-facing flows are affected by a code change — e.g., "this change breaks the login flow".
+
+```bash
+kodus-graph flows --graph graph.json --out flows.json --max-depth 10 --type all
+```
+
+### `search`
+
+Queries the graph by name, kind, file path, or call relationships. Supports glob patterns and regex.
+
+**When to use:** To explore the graph interactively — find all callers of a function, list all methods in a service, etc.
+
+```bash
+# Search by name (glob or regex)
+kodus-graph search --graph graph.json --query "auth*"
+kodus-graph search --graph graph.json --query "/^handle.*Request$/"
+
+# Filter by kind
+kodus-graph search --graph graph.json --query "*" --kind Method --file "src/services/*"
+
+# Find callers/callees
+kodus-graph search --graph graph.json --callers-of "src/db.ts::query"
+kodus-graph search --graph graph.json --callees-of "src/auth.ts::authenticate"
+```
+
+## Graph Schema
+
+### Nodes
+
+| Field | Type | Description |
+|---|---|---|
+| `kind` | `NodeKind` | Function, Method, Constructor, Class, Interface, Enum, Test |
+| `name` | `string` | Symbol name |
+| `qualified_name` | `string` | Unique ID: `file::Class.method` |
+| `file_path` | `string` | Relative file path |
+| `line_start` / `line_end` | `number` | Source location |
+| `language` | `string` | Source language |
+| `is_test` | `boolean` | Whether it's a test function |
+
+### Edges
+
+| Field | Type | Description |
+|---|---|---|
+| `kind` | `EdgeKind` | CALLS, IMPORTS, INHERITS, IMPLEMENTS, TESTED_BY, CONTAINS |
+| `source_qualified` | `string` | Caller/parent node |
+| `target_qualified` | `string` | Callee/child node |
+| `confidence` | `number` | 0.0–1.0 (for CALLS edges) |
+
+### Confidence Levels
+
+| Source | Confidence | Description |
+|---|---|---|
+| DI injection | 0.90–0.95 | Constructor/property injection patterns |
+| Same file | 0.85 | Call within the same file |
+| Import resolved | 0.70–0.90 | Cross-file call via import |
+| Unique match | 0.50 | Only one candidate across codebase |
+| Ambiguous | 0.30 | Multiple candidates found |
+
+## Examples
+
+The `examples/` directory contains real output from running kodus-graph on a sample TypeScript project:
+
+| File | Command | Description |
+|---|---|---|
+| [`parse-output.json`](examples/parse-output.json) | `parse --all` | Full graph with 17 nodes, 21 edges |
+| [`analyze-output.json`](examples/analyze-output.json) | `analyze --files src/auth.ts` | Blast radius, risk score, test gaps |
+| [`context-output.json`](examples/context-output.json) | `context --files src/auth.ts` | Enriched review context for AI agents |
+
+## Architecture
+
+```
+Source Code → Parser → Resolver → Graph → Analysis
+```
+
+| Layer | Path | Responsibility |
+|---|---|---|
+| **Parser** | `src/parser/` | AST extraction via ast-grep (functions, classes, imports, tests) |
+| **Resolver** | `src/resolver/` | Import resolution, call resolution, symbol table |
+| **Graph** | `src/graph/` | Node/edge building, incremental merging, JSON output |
+| **Analysis** | `src/analysis/` | Blast radius, risk score, test gaps, flows, context |
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in dev mode
+bun run dev parse --all --repo-dir ./my-project --out graph.json
+
+# Run tests
+bun test
+
+# Full check (typecheck + lint + tests)
+bun run check
+
+# Lint & format
+bun run lint:fix
+bun run format
+```
+
+## License
+
+MIT

package/dist/analysis/blast-radius.d.ts

@@ -0,0 +1,2 @@
+import type { BlastRadiusResult, GraphData } from '../graph/types';
+export declare function computeBlastRadius(graph: GraphData, changedFiles: string[], maxDepth?: number): BlastRadiusResult;

package/dist/analysis/blast-radius.js

@@ -0,0 +1,57 @@
+export function computeBlastRadius(graph, changedFiles, maxDepth = 2) {
+    // Build adjacency list from CALLS edges (callers of changed nodes)
+    const adj = new Map();
+    for (const edge of graph.edges) {
+        if (edge.kind !== 'CALLS' && edge.kind !== 'IMPORTS') {
+            continue;
+        }
+        // Reverse direction: target -> source (who calls/imports this?)
+        if (!adj.has(edge.target_qualified)) {
+            adj.set(edge.target_qualified, new Set());
+        }
+        adj.get(edge.target_qualified).add(edge.source_qualified);
+        // Forward direction too for IMPORTS
+        if (edge.kind === 'IMPORTS') {
+            if (!adj.has(edge.source_qualified)) {
+                adj.set(edge.source_qualified, new Set());
+            }
+            adj.get(edge.source_qualified).add(edge.target_qualified);
+        }
+    }
+    // Seed: all nodes in changed files
+    const changedSet = new Set(changedFiles);
+    const seeds = graph.nodes.filter((n) => changedSet.has(n.file_path)).map((n) => n.qualified_name);
+    // BFS
+    const visited = new Set(seeds);
+    const byDepth = {};
+    let frontier = seeds;
+    for (let depth = 1; depth <= maxDepth; depth++) {
+        const next = [];
+        for (const node of frontier) {
+            for (const neighbor of adj.get(node) || []) {
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    next.push(neighbor);
+                }
+            }
+        }
+        if (next.length > 0) {
+            byDepth[String(depth)] = next;
+        }
+        frontier = next;
+    }
+    // Count unique files
+    const nodeIndex = new Map(graph.nodes.map((n) => [n.qualified_name, n]));
+    const impactedFiles = new Set();
+    for (const q of visited) {
+        const node = nodeIndex.get(q);
+        if (node) {
+            impactedFiles.add(node.file_path);
+        }
+    }
+    return {
+        total_functions: visited.size,
+        total_files: impactedFiles.size,
+        by_depth: byDepth,
+    };
+}

package/dist/analysis/communities.d.ts

@@ -0,0 +1,28 @@
+import type { IndexedGraph } from '../graph/loader';
+export interface CommunityOptions {
+    depth: number;
+    minSize: number;
+}
+export interface Community {
+    name: string;
+    files: string[];
+    node_count: number;
+    cohesion: number;
+    language: string;
+}
+export interface CouplingPair {
+    source: string;
+    target: string;
+    edges: number;
+    strength: 'HIGH' | 'MEDIUM' | 'LOW';
+}
+export interface CommunitiesResult {
+    communities: Community[];
+    coupling: CouplingPair[];
+    summary: {
+        total_communities: number;
+        avg_cohesion: number;
+        high_coupling_pairs: number;
+    };
+}
+export declare function detectCommunities(graph: IndexedGraph, opts: CommunityOptions): CommunitiesResult;

package/dist/analysis/communities.js

@@ -0,0 +1,100 @@
+function getCommunityKey(filePath, depth) {
+    const parts = filePath.split('/');
+    return parts.slice(0, depth).join('/');
+}
+export function detectCommunities(graph, opts) {
+    const { depth, minSize } = opts;
+    // Group nodes by directory
+    const groups = new Map(); // community -> files
+    const nodeComm = new Map(); // qualified_name -> community
+    for (const node of graph.nodes) {
+        const key = getCommunityKey(node.file_path, depth);
+        if (!groups.has(key)) {
+            groups.set(key, new Set());
+        }
+        groups.get(key).add(node.file_path);
+        nodeComm.set(node.qualified_name, key);
+    }
+    // Count internal and cross edges per community pair
+    const internalEdges = new Map();
+    const crossEdges = new Map(); // "a|b" -> count
+    for (const edge of graph.edges) {
+        if (edge.kind !== 'CALLS' && edge.kind !== 'IMPORTS') {
+            continue;
+        }
+        const srcComm = nodeComm.get(edge.source_qualified);
+        const tgtComm = nodeComm.get(edge.target_qualified);
+        if (!srcComm || !tgtComm) {
+            continue;
+        }
+        if (srcComm === tgtComm) {
+            internalEdges.set(srcComm, (internalEdges.get(srcComm) || 0) + 1);
+        }
+        else {
+            const pairKey = [srcComm, tgtComm].sort().join('|');
+            crossEdges.set(pairKey, (crossEdges.get(pairKey) || 0) + 1);
+        }
+    }
+    // Build communities
+    const communities = [];
+    for (const [name, files] of groups) {
+        const nodeCount = graph.nodes.filter((n) => getCommunityKey(n.file_path, depth) === name).length;
+        if (nodeCount < minSize) {
+            continue;
+        }
+        const internal = internalEdges.get(name) || 0;
+        const maxPossible = nodeCount * (nodeCount - 1);
+        const cohesion = maxPossible > 0 ? Math.round((internal / maxPossible) * 100) / 100 : 0;
+        const langs = new Map();
+        for (const n of graph.nodes) {
+            if (getCommunityKey(n.file_path, depth) === name) {
+                langs.set(n.language, (langs.get(n.language) || 0) + 1);
+            }
+        }
+        let dominant = 'unknown';
+        let maxCount = 0;
+        for (const [lang, count] of langs) {
+            if (count > maxCount) {
+                dominant = lang;
+                maxCount = count;
+            }
+        }
+        communities.push({
+            name,
+            files: [...files].sort(),
+            node_count: nodeCount,
+            cohesion,
+            language: dominant,
+        });
+    }
+    communities.sort((a, b) => b.node_count - a.node_count);
+    // Build coupling pairs
+    const communityNames = new Set(communities.map((c) => c.name));
+    const coupling = [];
+    for (const [pairKey, count] of crossEdges) {
+        const [src, tgt] = pairKey.split('|');
+        if (!communityNames.has(src) || !communityNames.has(tgt)) {
+            continue;
+        }
+        const srcTotal = graph.edges.filter((e) => {
+            const c = nodeComm.get(e.source_qualified);
+            return c === src || c === tgt;
+        }).length;
+        const ratio = srcTotal > 0 ? count / srcTotal : 0;
+        const strength = ratio > 0.3 ? 'HIGH' : ratio > 0.1 ? 'MEDIUM' : 'LOW';
+        coupling.push({ source: src, target: tgt, edges: count, strength });
+    }
+    coupling.sort((a, b) => b.edges - a.edges);
+    const avgCohesion = communities.length > 0
+        ? Math.round((communities.reduce((s, c) => s + c.cohesion, 0) / communities.length) * 100) / 100
+        : 0;
+    return {
+        communities,
+        coupling,
+        summary: {
+            total_communities: communities.length,
+            avg_cohesion: avgCohesion,
+            high_coupling_pairs: coupling.filter((c) => c.strength === 'HIGH').length,
+        },
+    };
+}

package/dist/analysis/context-builder.d.ts

@@ -0,0 +1,34 @@
+import type { AffectedFlow, ContextAnalysisMetadata, GraphData, GraphEdge, GraphNode, ParseMetadata } from '../graph/types';
+import { computeBlastRadius } from './blast-radius';
+import { type DiffResult } from './diff';
+import { enrichChangedFunctions } from './enrich';
+import { extractInheritance } from './inheritance';
+import { computeRiskScore } from './risk-score';
+import { findTestGaps } from './test-gaps';
+export interface ContextV2Output {
+    graph: {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+        metadata: ParseMetadata;
+    };
+    analysis: {
+        changed_functions: ReturnType<typeof enrichChangedFunctions>;
+        structural_diff: DiffResult;
+        blast_radius: ReturnType<typeof computeBlastRadius>;
+        affected_flows: AffectedFlow[];
+        inheritance: ReturnType<typeof extractInheritance>;
+        test_gaps: ReturnType<typeof findTestGaps>;
+        risk: ReturnType<typeof computeRiskScore>;
+        metadata: ContextAnalysisMetadata;
+    };
+}
+interface BuildContextV2Options {
+    mergedGraph: GraphData;
+    oldGraph: GraphData | null;
+    changedFiles: string[];
+    minConfidence: number;
+    maxDepth: number;
+    skipTests?: boolean;
+}
+export declare function buildContextV2(opts: BuildContextV2Options): ContextV2Output;
+export {};

package/dist/analysis/context-builder.js

@@ -0,0 +1,83 @@
+import { performance } from 'perf_hooks';
+import { indexGraph } from '../graph/loader';
+import { computeBlastRadius } from './blast-radius';
+import { computeStructuralDiff } from './diff';
+import { enrichChangedFunctions } from './enrich';
+import { detectFlows } from './flows';
+import { extractInheritance } from './inheritance';
+import { computeRiskScore } from './risk-score';
+import { findTestGaps } from './test-gaps';
+export function buildContextV2(opts) {
+    const t0 = performance.now();
+    const { mergedGraph, oldGraph, changedFiles, minConfidence, maxDepth } = opts;
+    // Phase 1: Index
+    const indexed = indexGraph(mergedGraph);
+    const oldIndexed = oldGraph ? indexGraph(oldGraph) : indexGraph({ nodes: [], edges: [] });
+    // Phase 2: Independent analyses
+    const changedSet = new Set(changedFiles);
+    const newNodesInChanged = mergedGraph.nodes.filter((n) => changedSet.has(n.file_path));
+    const newEdgesInChanged = mergedGraph.edges.filter((e) => changedSet.has(e.file_path));
+    const structuralDiff = computeStructuralDiff(oldIndexed, newNodesInChanged, newEdgesInChanged, changedFiles);
+    const blastRadius = computeBlastRadius(mergedGraph, changedFiles, maxDepth);
+    const allFlows = detectFlows(indexed, { maxDepth: 10, type: 'all' });
+    const testGaps = opts.skipTests ? [] : findTestGaps(mergedGraph, changedFiles);
+    const risk = computeRiskScore(mergedGraph, changedFiles, blastRadius, { skipTests: opts.skipTests });
+    const inheritance = extractInheritance(indexed, changedFiles);
+    // Phase 3: Filter affected flows
+    const changedFuncSet = new Set(mergedGraph.nodes.filter((n) => changedSet.has(n.file_path) && !n.is_test).map((n) => n.qualified_name));
+    const affectedFlows = [];
+    for (const flow of allFlows.flows) {
+        const touches = flow.path.filter((qn) => changedFuncSet.has(qn));
+        if (touches.length > 0) {
+            affectedFlows.push({
+                entry_point: flow.entry_point,
+                type: flow.type,
+                touches_changed: touches,
+                depth: flow.depth,
+                path: flow.path,
+            });
+        }
+    }
+    // Phase 3: Enrichment
+    const enriched = enrichChangedFunctions(indexed, changedFiles, structuralDiff, allFlows.flows, minConfidence);
+    // Phase 4: Assembly
+    const totalCallers = enriched.reduce((s, f) => s + f.callers.length, 0);
+    const totalCallees = enriched.reduce((s, f) => s + f.callees.length, 0);
+    const metadata = {
+        changed_functions_count: enriched.length,
+        total_callers: totalCallers,
+        total_callees: totalCallees,
+        untested_count: testGaps.length,
+        affected_flows_count: affectedFlows.length,
+        duration_ms: Math.round(performance.now() - t0),
+        min_confidence: minConfidence,
+    };
+    const graphMetadata = indexed.metadata.repo_dir
+        ? indexed.metadata
+        : {
+            repo_dir: '',
+            files_parsed: changedFiles.length,
+            total_nodes: mergedGraph.nodes.length,
+            total_edges: mergedGraph.edges.length,
+            duration_ms: 0,
+            parse_errors: 0,
+            extract_errors: 0,
+        };
+    return {
+        graph: {
+            nodes: mergedGraph.nodes,
+            edges: mergedGraph.edges,
+            metadata: graphMetadata,
+        },
+        analysis: {
+            changed_functions: enriched,
+            structural_diff: structuralDiff,
+            blast_radius: blastRadius,
+            affected_flows: affectedFlows,
+            inheritance,
+            test_gaps: testGaps,
+            risk,
+            metadata,
+        },
+    };
+}

package/dist/analysis/diff.d.ts

@@ -0,0 +1,35 @@
+import type { IndexedGraph } from '../graph/loader';
+import type { GraphEdge, GraphNode } from '../graph/types';
+export interface NodeChange {
+    qualified_name: string;
+    kind: string;
+    file_path: string;
+    line_start: number;
+    line_end: number;
+}
+export interface ModifiedNode {
+    qualified_name: string;
+    changes: string[];
+}
+export interface DiffResult {
+    changed_files: string[];
+    summary: {
+        added: number;
+        removed: number;
+        modified: number;
+    };
+    nodes: {
+        added: NodeChange[];
+        removed: NodeChange[];
+        modified: ModifiedNode[];
+    };
+    edges: {
+        added: Pick<GraphEdge, 'kind' | 'source_qualified' | 'target_qualified'>[];
+        removed: Pick<GraphEdge, 'kind' | 'source_qualified' | 'target_qualified'>[];
+    };
+    risk_by_file: Record<string, {
+        dependents: number;
+        risk: 'HIGH' | 'MEDIUM' | 'LOW';
+    }>;
+}
+export declare function computeStructuralDiff(oldGraph: IndexedGraph, newNodes: GraphNode[], newEdges: GraphEdge[], changedFiles: string[]): DiffResult;