@kodus/kodus-graph 0.1.0

package/src/graph/types.ts

@@ -0,0 +1,218 @@
+// ── Node kinds (aligned with Postgres ast_nodes.kind) ──
+export type NodeKind = 'Function' | 'Method' | 'Constructor' | 'Class' | 'Interface' | 'Enum' | 'Test';
+
+// ── Edge kinds (aligned with Postgres ast_edges.kind) ──
+export type EdgeKind = 'CALLS' | 'IMPORTS' | 'INHERITS' | 'IMPLEMENTS' | 'TESTED_BY' | 'CONTAINS';
+
+// ── Graph node (matches ast_nodes table) ──
+export interface GraphNode {
+  kind: NodeKind;
+  name: string;
+  qualified_name: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  language: string;
+  parent_name?: string;
+  params?: string;
+  return_type?: string;
+  modifiers?: string;
+  is_test: boolean;
+  file_hash: string;
+}
+
+// ── Graph edge (matches ast_edges table) ──
+export interface GraphEdge {
+  kind: EdgeKind;
+  source_qualified: string;
+  target_qualified: string;
+  file_path: string;
+  line: number;
+  confidence?: number; // 0.0-1.0, only for CALLS
+}
+
+// ── Full graph data ──
+export interface GraphData {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+// ── Parse command output ──
+export interface ParseMetadata {
+  repo_dir: string;
+  files_parsed: number;
+  total_nodes: number;
+  total_edges: number;
+  duration_ms: number;
+  parse_errors: number;
+  extract_errors: number;
+  files_unchanged?: number;
+  incremental?: boolean;
+}
+
+export interface ParseOutput {
+  metadata: ParseMetadata;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+// ── Analyze command output ──
+export interface BlastRadiusResult {
+  total_functions: number;
+  total_files: number;
+  by_depth: Record<string, string[]>;
+}
+
+export interface RiskFactor {
+  weight: number;
+  value: number;
+  detail: string;
+}
+
+export interface RiskScoreResult {
+  level: 'LOW' | 'MEDIUM' | 'HIGH';
+  score: number;
+  factors: {
+    blast_radius: RiskFactor;
+    test_gaps: RiskFactor;
+    complexity: RiskFactor;
+    inheritance: RiskFactor;
+  };
+}
+
+export interface TestGap {
+  function: string;
+  file_path: string;
+  line_start: number;
+}
+
+export interface AnalysisOutput {
+  blast_radius: BlastRadiusResult;
+  risk_score: RiskScoreResult;
+  test_gaps: TestGap[];
+}
+
+// ── Context command output ──
+export interface ContextMetadata {
+  changed_functions: number;
+  caller_count: number;
+  callee_count: number;
+  untested_count: number;
+  blast_radius: { functions: number; files: number };
+  risk_level: 'LOW' | 'MEDIUM' | 'HIGH';
+  risk_score: number;
+}
+
+export interface ContextOutput {
+  text: string;
+  metadata: ContextMetadata;
+}
+
+// ── Main graph JSON (input --graph, from Postgres) ──
+export interface MainGraphInput {
+  repo_id: string;
+  sha: string;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+// ── Internal types used during parsing pipeline ──
+export interface RawFunction {
+  name: string;
+  file: string;
+  line_start: number;
+  line_end: number;
+  params: string;
+  returnType: string;
+  kind: 'Function' | 'Method' | 'Constructor';
+  className: string;
+  qualified: string;
+}
+
+export interface RawClass {
+  name: string;
+  file: string;
+  line_start: number;
+  line_end: number;
+  extends: string;
+  implements: string;
+  qualified: string;
+}
+
+export interface RawInterface {
+  name: string;
+  file: string;
+  line_start: number;
+  line_end: number;
+  methods: string[];
+  qualified: string;
+}
+
+export interface RawEnum {
+  name: string;
+  file: string;
+  line_start: number;
+  line_end: number;
+  qualified: string;
+}
+
+export interface RawTest {
+  name: string;
+  file: string;
+  line_start: number;
+  line_end: number;
+  qualified: string;
+}
+
+export interface RawImport {
+  module: string;
+  file: string;
+  line: number;
+  names: string[];
+  lang: string;
+}
+
+export interface RawReExport {
+  module: string;
+  file: string;
+  line: number;
+}
+
+export interface RawCallSite {
+  source: string; // relative file path
+  callName: string; // function or method name being called
+  line: number; // line number of the call
+  diField?: string; // if DI pattern (this.field.method), the field name
+}
+
+export interface RawCallEdge {
+  source: string; // file path of the caller
+  target: string; // qualified name of the callee
+  callName: string;
+  line: number;
+  confidence: number;
+}
+
+export interface ImportEdge {
+  source: string; // source file
+  target: string; // resolved target file or unresolved module
+  resolved: boolean;
+  line: number;
+}
+
+export interface RawGraph {
+  functions: RawFunction[];
+  classes: RawClass[];
+  interfaces: RawInterface[];
+  enums: RawEnum[];
+  tests: RawTest[];
+  imports: RawImport[];
+  reExports: RawReExport[];
+  rawCalls: RawCallSite[];
+  diMaps: Map<string, Map<string, string>>; // file -> Map<fieldName, typeName>
+}
+
+export interface ParseBatchResult extends RawGraph {
+  parseErrors: number;
+  extractErrors: number;
+}

package/src/parser/batch.ts

@@ -0,0 +1,74 @@
+import type { SgRoot } from '@ast-grep/napi';
+import { parseAsync } from '@ast-grep/napi';
+import { readFileSync } from 'fs';
+import { extname, relative } from 'path';
+import type { ParseBatchResult, RawGraph } from '../graph/types';
+import { log } from '../shared/logger';
+import { extractCallsFromFile, extractFromFile } from './extractor';
+import { getLanguage } from './languages';
+
+const BATCH_SIZE = 50;
+
+export async function parseBatch(files: string[], repoRoot: string): Promise<ParseBatchResult> {
+  const graph: RawGraph = {
+    functions: [],
+    classes: [],
+    interfaces: [],
+    enums: [],
+    tests: [],
+    imports: [],
+    reExports: [],
+    rawCalls: [],
+    diMaps: new Map(),
+  };
+  const seen = new Set<string>();
+  let parseErrors = 0;
+  let extractErrors = 0;
+
+  for (let i = 0; i < files.length; i += BATCH_SIZE) {
+    const batch = files.slice(i, i + BATCH_SIZE);
+
+    const promises = batch.map(async (filePath) => {
+      const lang = getLanguage(extname(filePath));
+      if (!lang) return;
+
+      let source: string;
+      try {
+        source = readFileSync(filePath, 'utf-8');
+      } catch (err) {
+        log.warn('Failed to read file', { file: filePath, error: String(err) });
+        parseErrors++;
+        return;
+      }
+
+      let root: SgRoot;
+      try {
+        root = await parseAsync(lang, source);
+      } catch (err) {
+        log.warn('Failed to parse file', { file: filePath, error: String(err) });
+        parseErrors++;
+        return;
+      }
+
+      const fp = relative(repoRoot, filePath);
+
+      try {
+        extractFromFile(root, fp, lang, seen, graph);
+      } catch (err) {
+        log.error('Extraction crashed', { file: fp, error: String(err) });
+        extractErrors++;
+      }
+
+      try {
+        extractCallsFromFile(root, fp, lang, graph.rawCalls);
+      } catch (err) {
+        log.error('Call extraction crashed', { file: fp, error: String(err) });
+        extractErrors++;
+      }
+    });
+
+    await Promise.all(promises);
+  }
+
+  return { ...graph, parseErrors, extractErrors };
+}

package/src/parser/discovery.ts

@@ -0,0 +1,42 @@
+import { readdirSync } from 'fs';
+import { extname, join, resolve } from 'path';
+import { isSkippableFile, SKIP_DIRS } from '../shared/filters';
+import { log } from '../shared/logger';
+import { ensureWithinRoot } from '../shared/safe-path';
+import { getLanguage } from './languages';
+
+/**
+ * Walk the filesystem and find all supported source files.
+ * If `filterFiles` is provided, only return those specific files (resolved to absolute paths).
+ */
+export function discoverFiles(repoDir: string, filterFiles?: string[]): string[] {
+  const absRepoDir = resolve(repoDir);
+
+  if (filterFiles) {
+    return filterFiles
+      .map((f) => (f.startsWith('/') ? f : join(absRepoDir, f)))
+      .filter((f) => {
+        try {
+          ensureWithinRoot(f, absRepoDir);
+          return getLanguage(extname(f)) !== null;
+        } catch (err) {
+          log.warn('Skipping file outside repository root', { file: f, error: String(err) });
+          return false;
+        }
+      });
+  }
+
+  const files: string[] = [];
+  walkFiles(absRepoDir, files);
+  return files;
+}
+
+function walkFiles(dir: string, files: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      walkFiles(join(dir, entry.name), files);
+    } else if (entry.isFile() && getLanguage(extname(entry.name)) !== null && !isSkippableFile(entry.name)) {
+      files.push(join(dir, entry.name));
+    }
+  }
+}

package/src/parser/extractor.ts

@@ -0,0 +1,37 @@
+import type { Lang, SgRoot } from '@ast-grep/napi';
+import type { RawCallSite, RawGraph } from '../graph/types';
+import { extractCallsFromGeneric, extractGeneric } from './extractors/generic';
+import { extractCallsFromPython, extractPython } from './extractors/python';
+import { extractCallsFromRuby, extractRuby } from './extractors/ruby';
+import { extractCallsFromTypeScript, extractTypeScript } from './extractors/typescript';
+import { isTypeScriptLike } from './languages';
+
+export function extractFromFile(
+  root: SgRoot,
+  filePath: string,
+  lang: Lang | string,
+  seen: Set<string>,
+  graph: RawGraph,
+): void {
+  if (isTypeScriptLike(lang)) {
+    extractTypeScript(root, filePath, seen, graph, lang);
+  } else if (lang === 'python') {
+    extractPython(root, filePath, seen, graph);
+  } else if (lang === 'ruby') {
+    extractRuby(root, filePath, seen, graph);
+  } else {
+    extractGeneric(root, filePath, lang as string, seen, graph);
+  }
+}
+
+export function extractCallsFromFile(root: SgRoot, filePath: string, lang: Lang | string, calls: RawCallSite[]): void {
+  if (isTypeScriptLike(lang)) {
+    extractCallsFromTypeScript(root, filePath, calls);
+  } else if (lang === 'python') {
+    extractCallsFromPython(root, filePath, calls);
+  } else if (lang === 'ruby') {
+    extractCallsFromRuby(root, filePath, calls);
+  } else {
+    extractCallsFromGeneric(root, filePath, calls);
+  }
+}

package/src/parser/extractors/generic.ts

@@ -0,0 +1,87 @@
+import type { SgNode, SgRoot } from '@ast-grep/napi';
+import type { RawCallSite, RawGraph } from '../../graph/types';
+import { NOISE } from '../../shared/filters';
+import { log } from '../../shared/logger';
+import { LANG_KINDS } from '../languages';
+
+export function extractGeneric(root: SgRoot, fp: string, lang: string, seen: Set<string>, graph: RawGraph): void {
+  const kinds = LANG_KINDS[lang];
+  if (!kinds) return;
+  const rootNode = root.root();
+
+  // Try to extract classes
+  for (const classKind of [kinds.class, kinds.struct, kinds.interface].filter(Boolean)) {
+    try {
+      for (const node of rootNode.findAll({ rule: { kind: classKind } })) {
+        const name = node.field('name')?.text();
+        if (!name || seen.has(`c:${fp}:${name}`)) continue;
+        seen.add(`c:${fp}:${name}`);
+        graph.classes.push({
+          name,
+          file: fp,
+          line_start: node.range().start.line,
+          line_end: node.range().end.line,
+          extends: '',
+          implements: '',
+          qualified: `${fp}::${name}`,
+        });
+      }
+    } catch (err) {
+      log.debug('Generic extraction failed', { file: fp, error: String(err) });
+    }
+  }
+
+  // Try to extract functions/methods
+  // biome-ignore lint/complexity/useLiteralKeys: 'constructor' must use bracket notation to avoid Object.prototype.constructor
+  for (const funcKind of [kinds.function, kinds.method, kinds['constructor'] as string | undefined].filter(Boolean)) {
+    try {
+      for (const node of rootNode.findAll({ rule: { kind: funcKind } })) {
+        const name = node.field('name')?.text();
+        if (!name) continue;
+        const line = node.range().start.line;
+        if (seen.has(`f:${fp}:${name}:${line}`)) continue;
+        seen.add(`f:${fp}:${name}:${line}`);
+
+        const classAncestor = node.ancestors().find((a: SgNode) => {
+          const k = String(a.kind());
+          return k.includes('class') || k.includes('struct') || k.includes('impl');
+        });
+        const className = classAncestor?.field('name')?.text() || '';
+
+        graph.functions.push({
+          name,
+          file: fp,
+          line_start: line,
+          line_end: node.range().end.line,
+          params: node.field('parameters')?.text() || '()',
+          returnType: node.field('return_type')?.text() || '',
+          kind: className ? 'Method' : 'Function',
+          className,
+          qualified: className ? `${fp}::${className}.${name}` : `${fp}::${name}`,
+        });
+      }
+    } catch (err) {
+      log.debug('Generic extraction failed', { file: fp, error: String(err) });
+    }
+  }
+}
+
+/**
+ * Extract raw call sites from a generic language AST.
+ * Direct calls only.
+ */
+export function extractCallsFromGeneric(root: SgRoot, fp: string, calls: RawCallSite[]): void {
+  const rootNode = root.root();
+
+  for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
+    const callee = m.getMatch('CALLEE')?.text();
+    if (!callee) continue;
+    const callName = callee.includes('.') ? callee.split('.').pop()! : callee;
+    if (NOISE.has(callName)) continue;
+    calls.push({
+      source: fp,
+      callName,
+      line: m.range().start.line,
+    });
+  }
+}

package/src/parser/extractors/python.ts

@@ -0,0 +1,127 @@
+import type { SgNode, SgRoot } from '@ast-grep/napi';
+import type { RawCallSite, RawGraph } from '../../graph/types';
+import { NOISE } from '../../shared/filters';
+import { LANG_KINDS } from '../languages';
+
+export function extractPython(root: SgRoot, fp: string, seen: Set<string>, graph: RawGraph): void {
+  const kinds = LANG_KINDS.python;
+  const rootNode = root.root();
+
+  // ── Classes ──
+  for (const node of rootNode.findAll({ rule: { kind: kinds.class } })) {
+    const name = node.field('name')?.text();
+    if (!name || seen.has(`c:${fp}:${name}`)) continue;
+    seen.add(`c:${fp}:${name}`);
+
+    const argList = node.field('superclasses') || node.children().find((c: SgNode) => c.kind() === 'argument_list');
+    const extendsName =
+      argList
+        ?.children()
+        .find((c: SgNode) => c.kind() === 'identifier')
+        ?.text() || '';
+
+    graph.classes.push({
+      name,
+      file: fp,
+      line_start: node.range().start.line,
+      line_end: node.range().end.line,
+      extends: extendsName,
+      implements: '',
+      qualified: `${fp}::${name}`,
+    });
+  }
+
+  // ── Functions / Methods ──
+  for (const node of rootNode.findAll({ rule: { kind: kinds.function } })) {
+    const name = node.field('name')?.text();
+    if (!name) continue;
+    const line = node.range().start.line;
+    if (seen.has(`m:${fp}:${name}:${line}`)) continue;
+    seen.add(`m:${fp}:${name}:${line}`);
+
+    const classAncestor = node.ancestors().find((a: SgNode) => a.kind() === kinds.class);
+    const className = classAncestor?.field('name')?.text() || '';
+    const retType =
+      node
+        .field('return_type')
+        ?.text()
+        ?.replace(/^->\s*/, '') || '';
+
+    const isTest = name.startsWith('test_');
+    if (isTest) {
+      graph.tests.push({
+        name,
+        file: fp,
+        line_start: line,
+        line_end: node.range().end.line,
+        qualified: `${fp}::test:${name}`,
+      });
+    }
+
+    graph.functions.push({
+      name,
+      file: fp,
+      line_start: line,
+      line_end: node.range().end.line,
+      params: node.field('parameters')?.text() || '()',
+      returnType: retType,
+      kind: name === '__init__' ? 'Constructor' : className ? 'Method' : 'Function',
+      className,
+      qualified: className ? `${fp}::${className}.${name}` : `${fp}::${name}`,
+    });
+  }
+
+  // ── Imports (from X import Y) ──
+  for (const node of rootNode.findAll({ rule: { kind: kinds.import } })) {
+    const modNode = node.children().find((c: SgNode) => c.kind() === 'dotted_name' || c.kind() === 'relative_import');
+    const modulePath = modNode?.text() || '';
+    if (!modulePath) continue;
+
+    const names: string[] = [];
+    for (const child of node.children()) {
+      if (child.kind() === 'dotted_name' && child !== modNode) names.push(child.text());
+      if (child.kind() === 'identifier' && child !== modNode) names.push(child.text());
+    }
+    graph.imports.push({
+      module: modulePath,
+      file: fp,
+      line: node.range().start.line,
+      names,
+      lang: 'python',
+    });
+  }
+
+  // ── Regular imports (import X) ──
+  for (const node of rootNode.findAll({ rule: { kind: kinds.importRegular } })) {
+    const modNode = node.children().find((c: SgNode) => c.kind() === 'dotted_name');
+    if (modNode) {
+      graph.imports.push({
+        module: modNode.text(),
+        file: fp,
+        line: node.range().start.line,
+        names: [modNode.text()],
+        lang: 'python',
+      });
+    }
+  }
+}
+
+/**
+ * Extract raw call sites from a Python AST.
+ * Direct calls only — Python has no DI pattern.
+ */
+export function extractCallsFromPython(root: SgRoot, fp: string, calls: RawCallSite[]): void {
+  const rootNode = root.root();
+
+  for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
+    const callee = m.getMatch('CALLEE')?.text();
+    if (!callee) continue;
+    const callName = callee.includes('.') ? callee.split('.').pop()! : callee;
+    if (NOISE.has(callName)) continue;
+    calls.push({
+      source: fp,
+      callName,
+      line: m.range().start.line,
+    });
+  }
+}