@kodus/kodus-graph 0.1.0

package/src/resolver/call-resolver.ts

@@ -0,0 +1,179 @@
+/**
+ * Call resolution with 5-tier confidence cascade.
+ *
+ * Cascade: DI (0.90-0.95) → same-file (0.85) → import-resolved (0.70-0.90)
+ *        → unique-name (0.50) → ambiguous (0.30)
+ *
+ * Pure resolution logic — no file I/O, no parsing.
+ * Raw call sites are provided by the batch parser.
+ */
+
+import type { RawCallEdge, RawCallSite } from '../graph/types';
+import { NOISE } from '../shared/filters';
+import type { ImportMap } from './import-map';
+import type { SymbolTable } from './symbol-table';
+
+// ── Types ──
+
+interface ResolveResult {
+  target: string;
+  confidence: number;
+  strategy: 'di' | 'same' | 'import' | 'unique' | 'ambiguous';
+}
+
+interface CallResolverStats {
+  di: number;
+  same: number;
+  import: number;
+  unique: number;
+  ambiguous: number;
+  noise: number;
+}
+
+interface ResolveAllResult {
+  callEdges: RawCallEdge[];
+  stats: CallResolverStats;
+}
+
+// ── Batch resolution (pure, no I/O) ──
+
+/**
+ * Resolve all raw call sites via the 5-tier cascade.
+ *
+ * Accepts pre-extracted RawCallSite[] from the batch parser.
+ * No file reads, no parseAsync — pure iteration + lookup.
+ */
+export function resolveAllCalls(
+  rawCalls: RawCallSite[],
+  diMaps: Map<string, Map<string, string>>,
+  symbolTable: SymbolTable,
+  importMap: ImportMap,
+): ResolveAllResult {
+  const callEdges: RawCallEdge[] = [];
+  const stats: CallResolverStats = { di: 0, same: 0, import: 0, unique: 0, ambiguous: 0, noise: 0 };
+
+  for (const call of rawCalls) {
+    if (NOISE.has(call.callName)) {
+      stats.noise++;
+      continue;
+    }
+
+    const fp = call.source;
+    const diMap = diMaps.get(fp);
+
+    // Try DI resolution first if diField is present
+    if (call.diField) {
+      const resolved = resolveDICall(call.diField, call.callName, fp, diMap, symbolTable);
+      if (resolved) {
+        callEdges.push({
+          source: fp,
+          target: resolved.target,
+          callName: call.callName,
+          line: call.line,
+          confidence: resolved.confidence,
+        });
+        stats.di++;
+        continue;
+      }
+    }
+
+    // Name-based cascade fallback
+    const resolved = resolveByName(call.callName, fp, symbolTable, importMap);
+    if (resolved) {
+      callEdges.push({
+        source: fp,
+        target: resolved.target,
+        callName: call.callName,
+        line: call.line,
+        confidence: resolved.confidence,
+      });
+      stats[resolved.strategy]++;
+    }
+  }
+
+  return { callEdges, stats };
+}
+
+// ── DI resolution ──
+
+function resolveDICall(
+  fieldName: string,
+  methodName: string,
+  _currentFile: string,
+  diMap: Map<string, string> | undefined,
+  symbolTable: SymbolTable,
+): ResolveResult | null {
+  if (!diMap?.has(fieldName)) return null;
+
+  const typeName = diMap.get(fieldName)!;
+
+  // Direct class match
+  const candidates = symbolTable.lookupGlobal(typeName);
+  if (candidates.length >= 1) {
+    const typeFile = candidates[0].split('::')[0];
+    return { target: `${typeFile}::${typeName}.${methodName}`, confidence: 0.95, strategy: 'di' };
+  }
+
+  // ISomething → Something heuristic for interface → implementation
+  if (typeName.startsWith('I') && typeName[1] === typeName[1]?.toUpperCase()) {
+    const implName = typeName.substring(1);
+    const implCandidates = symbolTable.lookupGlobal(implName);
+    if (implCandidates.length >= 1) {
+      const implFile = implCandidates[0].split('::')[0];
+      return { target: `${implFile}::${implName}.${methodName}`, confidence: 0.9, strategy: 'di' };
+    }
+  }
+
+  return null;
+}
+
+// ── Name-based resolution (4-tier cascade) ──
+
+function resolveByName(
+  callName: string,
+  currentFile: string,
+  symbolTable: SymbolTable,
+  importMap: ImportMap,
+): ResolveResult | null {
+  // Strategy 1: Same file (0.85)
+  const sameFile = symbolTable.lookupExact(currentFile, callName);
+  if (sameFile) return { target: sameFile, confidence: 0.85, strategy: 'same' };
+
+  // Strategy 2: Import-resolved (0.70-0.90)
+  const importedFrom = importMap.lookup(currentFile, callName);
+  if (importedFrom) {
+    const targetSym = symbolTable.lookupExact(importedFrom, callName);
+    if (targetSym) return { target: targetSym, confidence: 0.9, strategy: 'import' };
+    return { target: `${importedFrom}::${callName}`, confidence: 0.7, strategy: 'import' };
+  }
+
+  // Strategy 3: Unique global name (0.50)
+  if (symbolTable.isUnique(callName)) {
+    const candidates = symbolTable.lookupGlobal(callName);
+    return { target: candidates[0], confidence: 0.5, strategy: 'unique' };
+  }
+
+  // Strategy 4: Ambiguous (0.30)
+  const candidates = symbolTable.lookupGlobal(callName);
+  if (candidates.length > 1) {
+    return { target: callName, confidence: 0.3, strategy: 'ambiguous' };
+  }
+
+  return null;
+}
+
+// ── Public wrapper for unit testing ──
+
+export function resolveCall(
+  callName: string,
+  currentFile: string,
+  symbolTable: SymbolTable,
+  importMap: ImportMap,
+): { target: string; confidence: number } | null {
+  if (NOISE.has(callName)) return null;
+
+  const result = resolveByName(callName, currentFile, symbolTable, importMap);
+  if (!result) return null;
+
+  return { target: result.target, confidence: result.confidence };
+}

package/src/resolver/import-map.ts

@@ -0,0 +1,27 @@
+/**
+ * Import map: tracks which symbols are imported from where per file.
+ *
+ * For each importing file, maps symbol names to the resolved file path
+ * they were imported from. Used by the call resolver to connect
+ * function calls to their definitions across files.
+ */
+
+export interface ImportMap {
+  add(file: string, name: string, targetFile: string): void;
+  lookup(file: string, name: string): string | null;
+}
+
+export function createImportMap(): ImportMap {
+  const map = new Map<string, Map<string, string>>();
+
+  return {
+    add(file, name, targetFile) {
+      if (!map.has(file)) map.set(file, new Map());
+      map.get(file)!.set(name, targetFile);
+    },
+
+    lookup(file, name) {
+      return map.get(file)?.get(name) ?? null;
+    },
+  };
+}

package/src/resolver/import-resolver.ts

@@ -0,0 +1,72 @@
+/**
+ * Import resolver dispatcher.
+ *
+ * Routes import resolution to language-specific resolvers and
+ * falls back to tsconfig aliases for TypeScript/JavaScript.
+ */
+
+import { log } from '../shared/logger';
+import { ensureWithinRoot } from '../shared/safe-path';
+import { resolve as resolveCsImport } from './languages/csharp';
+import { resolve as resolveGoImport } from './languages/go';
+import { resolve as resolveJavaImport } from './languages/java';
+import { resolve as resolvePhpImport } from './languages/php';
+import { resolve as resolvePyImport } from './languages/python';
+import { resolve as resolveRbImport } from './languages/ruby';
+import { resolve as resolveRustImport } from './languages/rust';
+import { loadTsconfigAliases, resolve as resolveTsImport, resolveWithAliases } from './languages/typescript';
+
+const RESOLVERS: Record<string, (from: string, mod: string, root: string) => string | null> = {
+  ts: resolveTsImport,
+  javascript: resolveTsImport,
+  typescript: resolveTsImport,
+  python: resolvePyImport,
+  ruby: resolveRbImport,
+  go: resolveGoImport,
+  java: resolveJavaImport,
+  rust: resolveRustImport,
+  csharp: resolveCsImport,
+  php: resolvePhpImport,
+};
+
+/**
+ * Resolve an import from one file to another.
+ *
+ * @param fromAbsFile - Absolute path of the importing file
+ * @param modulePath - The import specifier (e.g., './auth', 'express', '@/lib/db')
+ * @param lang - Language key (ts, javascript, typescript, python, ruby, etc.)
+ * @param repoRoot - Absolute path to the repository root
+ * @param tsconfigAliases - Optional pre-loaded tsconfig aliases for TS/JS
+ * @returns Absolute path to the resolved file, or null if unresolvable
+ */
+export function resolveImport(
+  fromAbsFile: string,
+  modulePath: string,
+  lang: string,
+  repoRoot: string,
+  tsconfigAliases?: Map<string, string[]>,
+): string | null {
+  const resolver = RESOLVERS[lang];
+  if (!resolver) return null;
+
+  let result = resolver(fromAbsFile, modulePath, repoRoot);
+
+  // Fallback: tsconfig aliases for TS/JS
+  if (!result && (lang === 'ts' || lang === 'javascript' || lang === 'typescript') && tsconfigAliases?.size) {
+    result = resolveWithAliases(modulePath, tsconfigAliases, repoRoot);
+  }
+
+  // Validate resolved path is within repo root
+  if (result) {
+    try {
+      ensureWithinRoot(result, repoRoot);
+    } catch {
+      log.warn('Import resolves outside repository root', { from: fromAbsFile, module: modulePath, resolved: result });
+      return null;
+    }
+  }
+
+  return result;
+}
+
+export { loadTsconfigAliases };

package/src/resolver/languages/csharp.ts

@@ -0,0 +1,7 @@
+/**
+ * C# import resolver (stub).
+ */
+
+export function resolve(_fromAbsFile: string, _modulePath: string, _repoRoot: string): string | null {
+  return null;
+}

package/src/resolver/languages/go.ts

@@ -0,0 +1,7 @@
+/**
+ * Go import resolver (stub).
+ */
+
+export function resolve(_fromAbsFile: string, _modulePath: string, _repoRoot: string): string | null {
+  return null;
+}

package/src/resolver/languages/java.ts

@@ -0,0 +1,7 @@
+/**
+ * Java import resolver (stub).
+ */
+
+export function resolve(_fromAbsFile: string, _modulePath: string, _repoRoot: string): string | null {
+  return null;
+}

package/src/resolver/languages/php.ts

@@ -0,0 +1,7 @@
+/**
+ * PHP import resolver (stub).
+ */
+
+export function resolve(_fromAbsFile: string, _modulePath: string, _repoRoot: string): string | null {
+  return null;
+}

package/src/resolver/languages/python.ts

@@ -0,0 +1,35 @@
+/**
+ * Python import resolver.
+ *
+ * Handles dotted module paths (e.g., "from x.y import z").
+ * Walks up directories to find packages.
+ */
+
+import { existsSync } from 'fs';
+import { dirname, join, resolve as resolvePath } from 'path';
+
+/**
+ * Resolve a Python dotted import to a file path.
+ * Walks up from the importing file's directory to find the module.
+ */
+export function resolve(fromAbsFile: string, modulePath: string, _repoRoot: string): string | null {
+  if (!modulePath || modulePath.startsWith('.')) {
+    // Relative import -- not handled yet
+    return null;
+  }
+
+  const parts = modulePath.replace(/\./g, '/');
+  let current = dirname(fromAbsFile);
+
+  for (let i = 0; i < 10; i++) {
+    for (const candidate of [`${parts}.py`, `${parts}/__init__.py`]) {
+      const full = join(current, candidate);
+      if (existsSync(full)) return resolvePath(full);
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return null;
+}

package/src/resolver/languages/ruby.ts

@@ -0,0 +1,21 @@
+/**
+ * Ruby import resolver.
+ *
+ * Handles require_relative paths.
+ */
+
+import { existsSync } from 'fs';
+import { dirname, join, resolve as resolvePath } from 'path';
+
+/**
+ * Resolve a Ruby require/require_relative to a file path.
+ */
+export function resolve(fromAbsFile: string, modulePath: string, _repoRoot: string): string | null {
+  if (!modulePath) return null;
+
+  const base = join(dirname(fromAbsFile), modulePath);
+  if (existsSync(`${base}.rb`)) return resolvePath(`${base}.rb`);
+  if (existsSync(base)) return resolvePath(base);
+
+  return null;
+}

package/src/resolver/languages/rust.ts

@@ -0,0 +1,7 @@
+/**
+ * Rust import resolver (stub).
+ */
+
+export function resolve(_fromAbsFile: string, _modulePath: string, _repoRoot: string): string | null {
+  return null;
+}

package/src/resolver/languages/typescript.ts

@@ -0,0 +1,168 @@
+/**
+ * TypeScript/JavaScript import resolver.
+ *
+ * Handles:
+ * - Relative imports with extension probing (.ts, .tsx, .js, .jsx)
+ * - ESM .js → .ts remapping
+ * - Directory index files
+ * - tsconfig path aliases
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve as resolvePath } from 'path';
+import { log } from '../../shared/logger';
+
+const TS_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * Resolve a TypeScript/JavaScript relative import to an absolute file path.
+ * Returns null for non-relative (external package) imports.
+ */
+export function resolve(fromAbsFile: string, modulePath: string, _repoRoot: string): string | null {
+  if (!modulePath.startsWith('.')) return null;
+
+  let base = join(dirname(fromAbsFile), modulePath);
+
+  // ESM convention: .js in import -> .ts on disk
+  if (modulePath.endsWith('.js')) base = base.slice(0, -3);
+
+  // Try direct with extension
+  for (const ext of TS_EXTENSIONS) {
+    const candidate = base + ext;
+    if (existsSync(candidate)) return resolvePath(candidate);
+  }
+
+  // Try index file in directory
+  for (const ext of TS_EXTENSIONS) {
+    const candidate = join(base, `index${ext}`);
+    if (existsSync(candidate)) return resolvePath(candidate);
+  }
+
+  return null;
+}
+
+/**
+ * Strip comments and trailing commas from JSON (tsconfig-compatible).
+ * Handles strings correctly -- won't strip // inside "url://..." etc.
+ */
+function stripJsonComments(str: string): string {
+  let result = '';
+  let i = 0;
+  const len = str.length;
+
+  while (i < len) {
+    // String literal -- copy as-is
+    if (str[i] === '"') {
+      let j = i + 1;
+      while (j < len && str[j] !== '"') {
+        if (str[j] === '\\') j++; // skip escaped char
+        j++;
+      }
+      result += str.substring(i, j + 1);
+      i = j + 1;
+      continue;
+    }
+
+    // Single-line comment
+    if (str[i] === '/' && str[i + 1] === '/') {
+      while (i < len && str[i] !== '\n') i++;
+      continue;
+    }
+
+    // Block comment
+    if (str[i] === '/' && str[i + 1] === '*') {
+      i += 2;
+      while (i < len && !(str[i] === '*' && str[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+
+    // Trailing comma: comma followed by optional whitespace + closing bracket
+    if (str[i] === ',') {
+      let j = i + 1;
+      while (j < len && (str[j] === ' ' || str[j] === '\t' || str[j] === '\n' || str[j] === '\r')) j++;
+      if (str[j] === '}' || str[j] === ']') {
+        i++;
+        continue;
+      }
+    }
+
+    result += str[i];
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Load and parse tsconfig.json path aliases.
+ *
+ * Tries tsconfig.json first, then tsconfig.base.json.
+ * Converts alias patterns like "@libs/*" into prefix → resolved dirs.
+ */
+export function loadTsconfigAliases(repoRoot: string): Map<string, string[]> {
+  const aliases = new Map<string, string[]>();
+
+  for (const filename of ['tsconfig.json', 'tsconfig.base.json']) {
+    const tsconfigPath = join(repoRoot, filename);
+    if (!existsSync(tsconfigPath)) continue;
+
+    try {
+      const content = readFileSync(tsconfigPath, 'utf-8');
+      const cleaned = stripJsonComments(content);
+      const config = JSON.parse(cleaned);
+      const paths = config?.compilerOptions?.paths;
+      const baseUrl = config?.compilerOptions?.baseUrl || '.';
+      const baseDir = join(repoRoot, baseUrl);
+
+      if (paths) {
+        for (const [alias, targets] of Object.entries(paths)) {
+          // Convert alias pattern: "@libs/*" -> prefix "@libs/"
+          const prefix = alias.replace('/*', '/').replace('*', '');
+          const resolvedTargets = (targets as string[]).map((t) => {
+            const targetPath = t.replace('/*', '').replace('*', '');
+            return join(baseDir, targetPath);
+          });
+          aliases.set(prefix, resolvedTargets);
+        }
+      }
+    } catch (err) {
+      log.warn('Failed to parse tsconfig', { file: tsconfigPath, error: String(err) });
+    }
+  }
+
+  return aliases;
+}
+
+/**
+ * Resolve an import path using tsconfig aliases.
+ *
+ * Tries each alias prefix, and for matches, probes extensions and index files.
+ */
+export function resolveWithAliases(
+  modulePath: string,
+  aliases: Map<string, string[]>,
+  _repoRoot: string,
+): string | null {
+  for (const [prefix, targets] of aliases) {
+    if (modulePath.startsWith(prefix)) {
+      const rest = modulePath.slice(prefix.length);
+
+      for (const targetBase of targets) {
+        const base = join(targetBase, rest);
+
+        for (const ext of TS_EXTENSIONS) {
+          if (existsSync(base + ext)) return resolvePath(base + ext);
+        }
+        for (const ext of TS_EXTENSIONS) {
+          const idx = join(base, `index${ext}`);
+          if (existsSync(idx)) return resolvePath(idx);
+        }
+        // Try exact match (for directories with index)
+        if (existsSync(base)) return resolvePath(base);
+      }
+    }
+  }
+
+  return null;
+}

package/src/resolver/symbol-table.ts

@@ -0,0 +1,53 @@
+/**
+ * Symbol table with dual-index lookup (GitNexus pattern).
+ *
+ * Provides both exact (file + name) and global (name-only) lookups.
+ * The exact lookup is high-confidence; global lookup is lower-confidence
+ * but useful when import resolution fails.
+ */
+
+export interface SymbolTable {
+  add(file: string, name: string, qualified: string): void;
+  lookupExact(file: string, name: string): string | null;
+  isUnique(name: string): boolean;
+  lookupGlobal(name: string): string[];
+  readonly size: number;
+  readonly fileCount: number;
+}
+
+export function createSymbolTable(): SymbolTable {
+  const byFile = new Map<string, Map<string, string>>();
+  const byName = new Map<string, string[]>();
+
+  return {
+    add(file, name, qualified) {
+      if (!byFile.has(file)) byFile.set(file, new Map());
+      byFile.get(file)!.set(name, qualified);
+
+      if (!byName.has(name)) byName.set(name, []);
+      byName.get(name)!.push(qualified);
+    },
+
+    lookupExact(file, name) {
+      return byFile.get(file)?.get(name) ?? null;
+    },
+
+    isUnique(name) {
+      return (byName.get(name)?.length ?? 0) === 1;
+    },
+
+    lookupGlobal(name) {
+      return byName.get(name) ?? [];
+    },
+
+    get size() {
+      let count = 0;
+      for (const m of byFile.values()) count += m.size;
+      return count;
+    },
+
+    get fileCount() {
+      return byFile.size;
+    },
+  };
+}

package/src/shared/file-hash.ts

@@ -0,0 +1,7 @@
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+
+export function computeFileHash(filePath: string): string {
+  const content = readFileSync(filePath);
+  return createHash('sha256').update(content).digest('hex');
+}