@kodus/kodus-graph 0.1.0

package/src/commands/search.ts

@@ -0,0 +1,41 @@
+import { writeFileSync } from 'fs';
+import { findCallees, findCallers, searchNodes } from '../analysis/search';
+import { loadGraph } from '../graph/loader';
+import type { GraphNode } from '../graph/types';
+
+interface SearchCommandOptions {
+  graph: string;
+  query?: string;
+  kind?: string;
+  file?: string;
+  callersOf?: string;
+  calleesOf?: string;
+  limit: number;
+  out?: string;
+}
+
+export function executeSearch(opts: SearchCommandOptions): void {
+  const graph = loadGraph(opts.graph);
+
+  let results: GraphNode[];
+  let queryInfo: Record<string, string | null>;
+
+  if (opts.callersOf) {
+    results = findCallers(graph, opts.callersOf);
+    queryInfo = { callers_of: opts.callersOf, kind: null, file: null };
+  } else if (opts.calleesOf) {
+    results = findCallees(graph, opts.calleesOf);
+    queryInfo = { callees_of: opts.calleesOf, kind: null, file: null };
+  } else {
+    results = searchNodes(graph, { query: opts.query, kind: opts.kind, file: opts.file, limit: opts.limit });
+    queryInfo = { pattern: opts.query || null, kind: opts.kind || null, file: opts.file || null };
+  }
+
+  const output = JSON.stringify({ results, total: results.length, query: queryInfo }, null, 2);
+
+  if (opts.out) {
+    writeFileSync(opts.out, output);
+  } else {
+    process.stdout.write(`${output}\n`);
+  }
+}

package/src/commands/update.ts

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname, relative, resolve } from 'path';
+import { performance } from 'perf_hooks';
+import { buildGraphData } from '../graph/builder';
+import { loadGraph } from '../graph/loader';
+import type { GraphEdge, GraphNode, ImportEdge, ParseOutput } from '../graph/types';
+import { parseBatch } from '../parser/batch';
+import { discoverFiles } from '../parser/discovery';
+import { resolveAllCalls } from '../resolver/call-resolver';
+import { createImportMap } from '../resolver/import-map';
+import { loadTsconfigAliases, resolveImport } from '../resolver/import-resolver';
+import { createSymbolTable } from '../resolver/symbol-table';
+import { computeFileHash } from '../shared/file-hash';
+
+const DEFAULT_GRAPH_PATH = '.kodus-graph/graph.json';
+
+interface UpdateCommandOptions {
+  repoDir: string;
+  graph?: string;
+  out?: string;
+}
+
+export async function executeUpdate(opts: UpdateCommandOptions): Promise<void> {
+  const t0 = performance.now();
+  const repoDir = resolve(opts.repoDir);
+  const graphPath = resolve(repoDir, opts.graph || DEFAULT_GRAPH_PATH);
+  const outPath = resolve(repoDir, opts.out || opts.graph || DEFAULT_GRAPH_PATH);
+
+  if (!existsSync(graphPath)) {
+    process.stderr.write(`Error: graph file not found: ${graphPath}. Run "kodus-graph parse" first.\n`);
+    process.exit(1);
+  }
+
+  const oldGraph = loadGraph(graphPath);
+  process.stderr.write(`[1/5] Loaded previous graph (${oldGraph.nodes.length} nodes)\n`);
+
+  // Build file hash index from old graph
+  const oldHashes = new Map<string, string>();
+  for (const node of oldGraph.nodes) {
+    if (node.file_hash && !oldHashes.has(node.file_path)) {
+      oldHashes.set(node.file_path, node.file_hash);
+    }
+  }
+
+  // Discover current files
+  const allFiles = discoverFiles(repoDir);
+  const allRel = allFiles.map((f) => relative(repoDir, f));
+  const currentFiles = new Set(allRel);
+  const oldFiles = new Set(oldHashes.keys());
+
+  // Classify files
+  const added: string[] = [];
+  const modified: string[] = [];
+  const deleted: string[] = [];
+  const unchanged: string[] = [];
+
+  for (const file of currentFiles) {
+    const absPath = resolve(repoDir, file);
+    if (!oldHashes.has(file)) {
+      added.push(file);
+    } else {
+      const currentHash = computeFileHash(absPath);
+      if (currentHash !== oldHashes.get(file)) {
+        modified.push(file);
+      } else {
+        unchanged.push(file);
+      }
+    }
+  }
+
+  for (const file of oldFiles) {
+    if (!currentFiles.has(file)) deleted.push(file);
+  }
+
+  const toReparse = [...added, ...modified];
+  process.stderr.write(
+    `[2/5] Files: ${added.length} added, ${modified.length} modified, ${deleted.length} deleted, ${unchanged.length} unchanged\n`,
+  );
+
+  if (toReparse.length === 0 && deleted.length === 0) {
+    process.stderr.write('[3/5] No changes detected, graph is up to date\n');
+    const output: ParseOutput = {
+      metadata: {
+        ...oldGraph.metadata,
+        duration_ms: Math.round(performance.now() - t0),
+        files_unchanged: unchanged.length,
+        incremental: true,
+      },
+      nodes: oldGraph.nodes,
+      edges: oldGraph.edges,
+    };
+    ensureDir(outPath);
+    writeFileSync(outPath, JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // Re-parse changed files
+  const absToReparse = toReparse.map((f) => resolve(repoDir, f));
+  const rawGraph = await parseBatch(absToReparse, repoDir);
+  process.stderr.write(`[3/5] Re-parsed ${toReparse.length} files\n`);
+
+  // Resolve imports and calls for new files
+  const tsconfigAliases = loadTsconfigAliases(repoDir);
+  const symbolTable = createSymbolTable();
+  const importMap = createImportMap();
+  const importEdges: ImportEdge[] = [];
+
+  for (const f of rawGraph.functions) symbolTable.add(f.file, f.name, f.qualified);
+  for (const c of rawGraph.classes) symbolTable.add(c.file, c.name, c.qualified);
+  for (const i of rawGraph.interfaces) symbolTable.add(i.file, i.name, i.qualified);
+
+  for (const imp of rawGraph.imports) {
+    const langKey = imp.lang === 'python' ? 'python' : imp.lang === 'ruby' ? 'ruby' : 'typescript';
+    const resolved = resolveImport(resolve(repoDir, imp.file), imp.module, langKey, repoDir, tsconfigAliases);
+    const resolvedRel = resolved ? relative(repoDir, resolved) : null;
+    importEdges.push({ source: imp.file, target: resolvedRel || imp.module, resolved: !!resolvedRel, line: imp.line });
+    const target = resolvedRel || imp.module;
+    for (const name of imp.names) importMap.add(imp.file, name, target);
+  }
+
+  const { callEdges } = resolveAllCalls(rawGraph.rawCalls, rawGraph.diMaps, symbolTable, importMap);
+
+  const fileHashes = new Map<string, string>();
+  for (const f of absToReparse) {
+    try {
+      fileHashes.set(relative(repoDir, f), computeFileHash(f));
+    } catch {}
+  }
+
+  const newGraphData = buildGraphData(rawGraph, callEdges, importEdges, repoDir, fileHashes);
+  process.stderr.write(`[4/5] Built new graph fragment (${newGraphData.nodes.length} nodes)\n`);
+
+  // Merge: keep old nodes/edges NOT in changed/deleted files, add new ones
+  const changedOrDeleted = new Set([...toReparse, ...deleted]);
+  const mergedNodes: GraphNode[] = oldGraph.nodes.filter((n) => !changedOrDeleted.has(n.file_path));
+  const mergedEdges: GraphEdge[] = oldGraph.edges.filter((e) => !changedOrDeleted.has(e.file_path));
+
+  mergedNodes.push(...newGraphData.nodes);
+  mergedEdges.push(...newGraphData.edges);
+
+  process.stderr.write(`[5/5] Merged: ${mergedNodes.length} nodes, ${mergedEdges.length} edges\n`);
+
+  const output: ParseOutput = {
+    metadata: {
+      repo_dir: repoDir,
+      files_parsed: toReparse.length,
+      files_unchanged: unchanged.length,
+      total_nodes: mergedNodes.length,
+      total_edges: mergedEdges.length,
+      duration_ms: Math.round(performance.now() - t0),
+      parse_errors: rawGraph.parseErrors,
+      extract_errors: rawGraph.extractErrors,
+      incremental: true,
+    },
+    nodes: mergedNodes,
+    edges: mergedEdges,
+  };
+
+  ensureDir(outPath);
+  writeFileSync(outPath, JSON.stringify(output, null, 2));
+}
+
+function ensureDir(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}

package/src/graph/builder.ts

@@ -0,0 +1,170 @@
+import { deriveEdges } from './edges';
+import type { GraphData, GraphEdge, GraphNode, ImportEdge, RawCallEdge, RawGraph } from './types';
+
+export function buildGraphData(
+  raw: RawGraph,
+  callEdges: RawCallEdge[],
+  importEdges: ImportEdge[],
+  _repoDir: string,
+  fileHashes: Map<string, string>,
+): GraphData {
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+
+  // Functions -> nodes
+  for (const f of raw.functions) {
+    nodes.push({
+      kind: f.kind,
+      name: f.name,
+      qualified_name: f.qualified,
+      file_path: f.file,
+      line_start: f.line_start,
+      line_end: f.line_end,
+      language: detectLang(f.file),
+      parent_name: f.className || undefined,
+      params: f.params || undefined,
+      return_type: f.returnType || undefined,
+      is_test: false,
+      file_hash: fileHashes.get(f.file) || '',
+    });
+  }
+
+  // Classes -> nodes
+  for (const c of raw.classes) {
+    nodes.push({
+      kind: 'Class',
+      name: c.name,
+      qualified_name: c.qualified,
+      file_path: c.file,
+      line_start: c.line_start,
+      line_end: c.line_end,
+      language: detectLang(c.file),
+      is_test: false,
+      file_hash: fileHashes.get(c.file) || '',
+    });
+  }
+
+  // Interfaces -> nodes
+  for (const i of raw.interfaces) {
+    nodes.push({
+      kind: 'Interface',
+      name: i.name,
+      qualified_name: i.qualified,
+      file_path: i.file,
+      line_start: i.line_start,
+      line_end: i.line_end,
+      language: detectLang(i.file),
+      is_test: false,
+      file_hash: fileHashes.get(i.file) || '',
+    });
+  }
+
+  // Enums -> nodes
+  for (const e of raw.enums) {
+    nodes.push({
+      kind: 'Enum',
+      name: e.name,
+      qualified_name: e.qualified,
+      file_path: e.file,
+      line_start: e.line_start,
+      line_end: e.line_end,
+      language: detectLang(e.file),
+      is_test: false,
+      file_hash: fileHashes.get(e.file) || '',
+    });
+  }
+
+  // Tests -> nodes
+  for (const t of raw.tests) {
+    nodes.push({
+      kind: 'Test',
+      name: t.name,
+      qualified_name: t.qualified,
+      file_path: t.file,
+      line_start: t.line_start,
+      line_end: t.line_end,
+      language: detectLang(t.file),
+      is_test: true,
+      file_hash: fileHashes.get(t.file) || '',
+    });
+  }
+
+  // CALLS edges
+  for (const ce of callEdges) {
+    edges.push({
+      kind: 'CALLS',
+      source_qualified: ce.source.includes('::') ? ce.source : `${ce.source}::unknown`,
+      target_qualified: ce.target,
+      file_path: ce.source.includes('::') ? ce.source.split('::')[0] : ce.source,
+      line: ce.line,
+      confidence: ce.confidence,
+    });
+  }
+
+  // IMPORTS edges
+  for (const ie of importEdges) {
+    edges.push({
+      kind: 'IMPORTS',
+      source_qualified: ie.source,
+      target_qualified: ie.target,
+      file_path: ie.source,
+      line: ie.line,
+    });
+  }
+
+  // Derived edges
+  const derived = deriveEdges(raw, importEdges);
+
+  for (const e of derived.inherits) {
+    edges.push({
+      kind: 'INHERITS',
+      source_qualified: e.source,
+      target_qualified: e.target,
+      file_path: e.file || '',
+      line: 0,
+    });
+  }
+  for (const e of derived.implements) {
+    edges.push({
+      kind: 'IMPLEMENTS',
+      source_qualified: e.source,
+      target_qualified: e.target,
+      file_path: e.file || '',
+      line: 0,
+    });
+  }
+  for (const e of derived.testedBy) {
+    edges.push({
+      kind: 'TESTED_BY',
+      source_qualified: e.source,
+      target_qualified: e.target,
+      file_path: e.target || '',
+      line: 0,
+    });
+  }
+  for (const e of derived.contains) {
+    edges.push({
+      kind: 'CONTAINS',
+      source_qualified: e.source,
+      target_qualified: e.target,
+      file_path: e.source,
+      line: 0,
+    });
+  }
+
+  return { nodes, edges };
+}
+
+function detectLang(file: string): string {
+  if (file.endsWith('.ts') || file.endsWith('.tsx')) return 'typescript';
+  if (file.endsWith('.js') || file.endsWith('.jsx') || file.endsWith('.mjs') || file.endsWith('.cjs'))
+    return 'javascript';
+  if (file.endsWith('.py')) return 'python';
+  if (file.endsWith('.rb')) return 'ruby';
+  if (file.endsWith('.go')) return 'go';
+  if (file.endsWith('.java')) return 'java';
+  if (file.endsWith('.rs')) return 'rust';
+  if (file.endsWith('.cs')) return 'csharp';
+  if (file.endsWith('.php')) return 'php';
+  return 'unknown';
+}

package/src/graph/edges.ts

@@ -0,0 +1,101 @@
+import { basename, extname } from 'path';
+import type { ImportEdge, RawGraph } from './types';
+
+interface DerivedEdge {
+  source: string;
+  target: string;
+  file?: string;
+}
+
+export interface DerivedEdges {
+  inherits: DerivedEdge[];
+  implements: DerivedEdge[];
+  testedBy: DerivedEdge[];
+  contains: DerivedEdge[];
+}
+
+/**
+ * Extract the "stem" from a test file name by stripping test-related
+ * prefixes/suffixes. Returns null if no test pattern was found.
+ */
+export function extractTestStem(testFile: string): string | null {
+  const base = basename(testFile, extname(testFile));
+  const cleaned = base
+    .replace(/_spec$/, '') // user_spec → user (Ruby/RSpec)
+    .replace(/_test$/, '') // user_test → user (Python/Go)
+    .replace(/^test_/, '') // test_user → user (Python)
+    .replace(/\.test$/, '') // user.test → user (JS/TS)
+    .replace(/\.spec$/, '') // user.spec → user (JS/TS)
+    .replace(/-test$/, '') // user-test → user
+    .replace(/-spec$/, '') // user-spec → user
+    .replace(/^spec_/, '') // spec_user → user
+    .replace(/Test$/, '') // UserTest → User (Java)
+    .replace(/Spec$/, ''); // UserSpec → User (Scala)
+  if (!cleaned || cleaned === base) return null;
+  return cleaned;
+}
+
+export function deriveEdges(graph: RawGraph, importEdges: ImportEdge[]): DerivedEdges {
+  // INHERITS: class extends another class
+  const inherits = graph.classes
+    .filter((c) => c.extends)
+    .map((c) => ({ source: c.qualified, target: c.extends, file: c.file }));
+
+  // IMPLEMENTS: class implements interface
+  const implements_ = graph.classes
+    .filter((c) => c.implements)
+    .map((c) => ({ source: c.qualified, target: c.implements, file: c.file }));
+
+  // TESTED_BY: two heuristics, deduplicated
+  const testFiles = new Set(graph.tests.map((t) => t.file));
+  const testedBySet = new Set<string>();
+  const testedBy: DerivedEdge[] = [];
+
+  const addTestedBy = (source: string, target: string) => {
+    const key = `${source}|${target}`;
+    if (testedBySet.has(key)) return;
+    testedBySet.add(key);
+    testedBy.push({ source, target });
+  };
+
+  // Heuristic 1: Resolved imports from test files (high signal)
+  for (const e of importEdges) {
+    if (testFiles.has(e.source) && e.resolved) {
+      addTestedBy(e.target, e.source);
+    }
+  }
+
+  // Heuristic 2: File-name matching (catches Ruby, Python, and any
+  // language where imports don't resolve)
+  const allSourceFiles = new Set<string>();
+  for (const f of graph.functions) allSourceFiles.add(f.file);
+  for (const c of graph.classes) allSourceFiles.add(c.file);
+  for (const i of graph.interfaces) allSourceFiles.add(i.file);
+  for (const e of graph.enums) allSourceFiles.add(e.file);
+  for (const tf of testFiles) allSourceFiles.delete(tf);
+
+  const sourceByBase = new Map<string, string[]>();
+  for (const file of allSourceFiles) {
+    const base = basename(file, extname(file));
+    const list = sourceByBase.get(base);
+    if (list) list.push(file);
+    else sourceByBase.set(base, [file]);
+  }
+
+  for (const testFile of testFiles) {
+    const stem = extractTestStem(testFile);
+    if (!stem) continue;
+    const matches = sourceByBase.get(stem);
+    if (!matches) continue;
+    for (const sourceFile of matches) {
+      addTestedBy(sourceFile, testFile);
+    }
+  }
+
+  // CONTAINS: file contains function/class
+  const contains: DerivedEdge[] = [];
+  for (const f of graph.functions) contains.push({ source: f.file, target: f.qualified });
+  for (const c of graph.classes) contains.push({ source: c.file, target: c.qualified });
+
+  return { inherits, implements: implements_, testedBy, contains };
+}

package/src/graph/loader.ts

@@ -0,0 +1,100 @@
+// src/graph/loader.ts
+import { readFileSync } from 'fs';
+import { z } from 'zod';
+import type { GraphEdge, GraphNode, ParseMetadata } from './types';
+
+const ParseOutputSchema = z.object({
+  metadata: z.object({
+    repo_dir: z.string(),
+    files_parsed: z.number(),
+    total_nodes: z.number(),
+    total_edges: z.number(),
+    duration_ms: z.number(),
+    parse_errors: z.number(),
+    extract_errors: z.number(),
+    files_unchanged: z.number().optional(),
+    incremental: z.boolean().optional(),
+  }),
+  nodes: z.array(
+    z.object({
+      kind: z.enum(['Function', 'Method', 'Constructor', 'Class', 'Interface', 'Enum', 'Test']),
+      name: z.string(),
+      qualified_name: z.string(),
+      file_path: z.string(),
+      line_start: z.number(),
+      line_end: z.number(),
+      language: z.string(),
+      is_test: z.boolean(),
+      file_hash: z.string(),
+      parent_name: z.string().optional(),
+      params: z.string().optional(),
+      return_type: z.string().optional(),
+      modifiers: z.string().optional(),
+    }),
+  ),
+  edges: z.array(
+    z.object({
+      kind: z.enum(['CALLS', 'IMPORTS', 'INHERITS', 'IMPLEMENTS', 'TESTED_BY', 'CONTAINS']),
+      source_qualified: z.string(),
+      target_qualified: z.string(),
+      file_path: z.string(),
+      line: z.number(),
+      confidence: z.number().optional(),
+    }),
+  ),
+});
+
+export interface IndexedGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  byQualified: Map<string, GraphNode>;
+  byFile: Map<string, GraphNode[]>;
+  adjacency: Map<string, GraphEdge[]>;
+  reverseAdjacency: Map<string, GraphEdge[]>;
+  edgesByKind: Map<string, GraphEdge[]>;
+  metadata: ParseMetadata;
+}
+
+export function loadGraph(path: string): IndexedGraph {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Failed to read graph file: ${path} — ${String(err)}`);
+  }
+
+  const parsed = ParseOutputSchema.parse(raw);
+
+  const nodes = parsed.nodes as GraphNode[];
+  const edges = parsed.edges as GraphEdge[];
+  const metadata = parsed.metadata as ParseMetadata;
+
+  const byQualified = new Map<string, GraphNode>();
+  const byFile = new Map<string, GraphNode[]>();
+  const adjacency = new Map<string, GraphEdge[]>();
+  const reverseAdjacency = new Map<string, GraphEdge[]>();
+  const edgesByKind = new Map<string, GraphEdge[]>();
+
+  for (const node of nodes) {
+    byQualified.set(node.qualified_name, node);
+    const list = byFile.get(node.file_path);
+    if (list) list.push(node);
+    else byFile.set(node.file_path, [node]);
+  }
+
+  for (const edge of edges) {
+    const fwd = adjacency.get(edge.source_qualified);
+    if (fwd) fwd.push(edge);
+    else adjacency.set(edge.source_qualified, [edge]);
+
+    const rev = reverseAdjacency.get(edge.target_qualified);
+    if (rev) rev.push(edge);
+    else reverseAdjacency.set(edge.target_qualified, [edge]);
+
+    const byKind = edgesByKind.get(edge.kind);
+    if (byKind) byKind.push(edge);
+    else edgesByKind.set(edge.kind, [edge]);
+  }
+
+  return { nodes, edges, byQualified, byFile, adjacency, reverseAdjacency, edgesByKind, metadata };
+}

package/src/graph/merger.ts

@@ -0,0 +1,25 @@
+import type { GraphData, MainGraphInput } from './types';
+
+/**
+ * Merge local parse (PR changed files) with the main graph (from Postgres).
+ * Replaces all nodes/edges from changed files with the local parse.
+ * Keeps everything else from the main graph intact.
+ */
+export function mergeGraphs(
+  mainGraph: MainGraphInput | null,
+  localParse: GraphData,
+  changedFiles: string[],
+): GraphData {
+  if (!mainGraph) return localParse;
+
+  const changedSet = new Set(changedFiles);
+
+  // Keep main graph nodes/edges NOT in changed files
+  const mainNodes = mainGraph.nodes.filter((n) => !changedSet.has(n.file_path));
+  const mainEdges = mainGraph.edges.filter((e) => !changedSet.has(e.file_path));
+
+  return {
+    nodes: [...mainNodes, ...localParse.nodes],
+    edges: [...mainEdges, ...localParse.edges],
+  };
+}