@kodus/kodus-graph 0.2.8 → 0.2.10

package/dist/parser/languages.d.ts

@@ -0,0 +1,32 @@
+import type { SgNode } from '@ast-grep/napi';
+import { Lang } from '@ast-grep/napi';
+export type HeritageFinder = (node: SgNode) => string | string[] | undefined;
+export interface TestConfig {
+    filePatterns?: RegExp[];
+    funcPatterns?: RegExp[];
+    /** When both filePatterns and funcPatterns are set: 'and' requires both, 'or' (default) requires either */
+    matchMode?: 'and' | 'or';
+    annotationKind?: string;
+    annotationNames?: string[];
+}
+export interface LangConfig {
+    class?: string[];
+    function?: string[];
+    method?: string[];
+    constructorKinds?: string[];
+    interface?: string[];
+    enum?: string[];
+    import?: string[];
+    heritage?: {
+        extends?: HeritageFinder;
+        implements?: HeritageFinder;
+    };
+    tests?: TestConfig;
+}
+export declare function getLanguage(ext: string): Lang | string | null;
+export declare function getSupportedExtensions(): string[];
+export declare function getLanguageName(lang: Lang | string): string;
+export declare function isTypeScriptLike(lang: Lang | string): boolean;
+export declare const LANG_CONFIGS: Record<string, LangConfig>;
+export declare const LANG_KINDS: Record<string, Record<string, string>>;
+export { Lang };

package/dist/parser/languages.js

@@ -0,0 +1,304 @@
+import csharp from '@ast-grep/lang-csharp';
+import go from '@ast-grep/lang-go';
+import java from '@ast-grep/lang-java';
+import php from '@ast-grep/lang-php';
+import python from '@ast-grep/lang-python';
+import ruby from '@ast-grep/lang-ruby';
+import rust from '@ast-grep/lang-rust';
+import { Lang, registerDynamicLanguage } from '@ast-grep/napi';
+// Register dynamic languages at import time (side effect).
+// This must happen before parseAsync can parse these languages.
+registerDynamicLanguage({ python, ruby, go, java, rust, php, csharp });
+// ---------------------------------------------------------------------------
+// Extension -> language identifier
+// Built-in langs use Lang enum, dynamic langs use lowercase string
+// ---------------------------------------------------------------------------
+const EXT_TO_LANG = {
+    '.ts': Lang.TypeScript,
+    '.tsx': Lang.Tsx,
+    '.js': Lang.JavaScript,
+    '.jsx': Lang.JavaScript,
+    '.mjs': Lang.JavaScript,
+    '.cjs': Lang.JavaScript,
+    '.py': 'python',
+    '.rb': 'ruby',
+    '.go': 'go',
+    '.java': 'java',
+    '.rs': 'rust',
+    '.cs': 'csharp',
+    '.php': 'php',
+};
+export function getLanguage(ext) {
+    return EXT_TO_LANG[ext] ?? null;
+}
+export function getSupportedExtensions() {
+    return Object.keys(EXT_TO_LANG);
+}
+export function getLanguageName(lang) {
+    if (typeof lang === 'string') {
+        return lang;
+    }
+    if (lang === Lang.TypeScript || lang === Lang.Tsx) {
+        return 'typescript';
+    }
+    if (lang === Lang.JavaScript) {
+        return 'javascript';
+    }
+    return 'unknown';
+}
+export function isTypeScriptLike(lang) {
+    return lang === Lang.TypeScript || lang === Lang.Tsx || lang === Lang.JavaScript;
+}
+// ---------------------------------------------------------------------------
+// Per-language LangConfig definitions
+// ---------------------------------------------------------------------------
+const typescriptConfig = {
+    class: ['class_declaration', 'abstract_class_declaration'],
+    method: ['method_definition'],
+    function: ['function_declaration'],
+    interface: ['interface_declaration'],
+    enum: ['enum_declaration'],
+    import: ['import_statement'],
+};
+const pythonConfig = {
+    class: ['class_definition'],
+    method: ['function_definition'],
+    function: ['function_definition'],
+    import: ['import_from_statement', 'import_statement'],
+    tests: {
+        funcPatterns: [/^test_/],
+        filePatterns: [/test_.*\.py$/, /_test\.py$/],
+    },
+};
+const rubyConfig = {
+    class: ['class'],
+    method: ['method', 'singleton_method'],
+    import: [],
+    tests: {
+        filePatterns: [/_spec\.rb$/, /spec_.*\.rb$/],
+    },
+};
+const goConfig = {
+    function: ['function_declaration'],
+    method: ['method_declaration'],
+    class: ['type_declaration'],
+    interface: ['type_declaration'],
+    import: ['import_declaration'],
+    tests: {
+        filePatterns: [/_test\.go$/],
+        funcPatterns: [/^Test/, /^Benchmark/],
+        matchMode: 'and',
+    },
+};
+const javaConfig = {
+    class: ['class_declaration'],
+    interface: ['interface_declaration'],
+    method: ['method_declaration'],
+    constructorKinds: ['constructor_declaration'],
+    import: ['import_declaration'],
+    enum: ['enum_declaration'],
+    heritage: {
+        extends: (node) => {
+            const superclass = node.children().find((c) => c.kind() === 'superclass');
+            if (!superclass) {
+                return undefined;
+            }
+            const typeId = superclass.children().find((c) => c.kind() === 'type_identifier');
+            return typeId?.text();
+        },
+        implements: (node) => {
+            const superInterfaces = node.children().find((c) => c.kind() === 'super_interfaces');
+            if (!superInterfaces) {
+                return [];
+            }
+            // type_identifiers may be direct children or nested in a type_list
+            const typeList = superInterfaces.children().find((c) => c.kind() === 'type_list');
+            const container = typeList || superInterfaces;
+            return container
+                .children()
+                .filter((c) => c.kind() === 'type_identifier')
+                .map((c) => c.text());
+        },
+    },
+    tests: {
+        annotationKind: 'marker_annotation',
+        annotationNames: ['Test', 'ParameterizedTest'],
+    },
+};
+const rustConfig = {
+    function: ['function_item'],
+    class: ['struct_item', 'impl_item'],
+    interface: ['trait_item'],
+    enum: ['enum_item'],
+    import: ['use_declaration'],
+    tests: {
+        annotationKind: 'attribute_item',
+        annotationNames: ['test'],
+    },
+};
+const csharpConfig = {
+    class: ['class_declaration'],
+    interface: ['interface_declaration'],
+    method: ['method_declaration'],
+    constructorKinds: ['constructor_declaration'],
+    import: ['using_directive'],
+    enum: ['enum_declaration'],
+    heritage: {
+        // C# base_list doesn't distinguish extends vs implements syntactically.
+        // Heuristic: names starting with 'I' + uppercase are interfaces (C# convention).
+        // First non-interface type is treated as the base class.
+        extends: (node) => {
+            const baseList = node.children().find((c) => c.kind() === 'base_list');
+            if (!baseList) {
+                return undefined;
+            }
+            const types = baseList
+                .children()
+                .filter((c) => c.kind() === 'type_identifier' || c.kind() === 'identifier')
+                .map((c) => c.text());
+            // First non-interface name is the base class
+            return types.find((t) => !(t.length >= 2 && t[0] === 'I' && t[1] === t[1].toUpperCase()));
+        },
+        implements: (node) => {
+            const baseList = node.children().find((c) => c.kind() === 'base_list');
+            if (!baseList) {
+                return undefined;
+            }
+            const types = baseList
+                .children()
+                .filter((c) => c.kind() === 'type_identifier' || c.kind() === 'identifier')
+                .map((c) => c.text());
+            // Names matching I+uppercase convention are interfaces
+            return types.filter((t) => t.length >= 2 && t[0] === 'I' && t[1] === t[1].toUpperCase());
+        },
+    },
+    tests: {
+        annotationKind: 'attribute',
+        annotationNames: ['TestMethod', 'Fact', 'Test', 'Theory'],
+    },
+};
+const phpConfig = {
+    class: ['class_declaration'],
+    interface: ['interface_declaration'],
+    method: ['method_declaration'],
+    function: ['function_definition'],
+    import: ['namespace_use_declaration'],
+    heritage: {
+        extends: (node) => {
+            const baseClause = node.children().find((c) => c.kind() === 'base_clause');
+            if (!baseClause) {
+                return undefined;
+            }
+            const name = baseClause.children().find((c) => c.kind() === 'name');
+            return name?.text();
+        },
+        implements: (node) => {
+            const ifaceClause = node.children().find((c) => c.kind() === 'class_interface_clause');
+            if (!ifaceClause) {
+                return undefined;
+            }
+            return ifaceClause
+                .children()
+                .filter((c) => c.kind() === 'name')
+                .map((c) => c.text());
+        },
+    },
+    tests: {
+        funcPatterns: [/^test/],
+        filePatterns: [/Test\.php$/],
+    },
+};
+// ---------------------------------------------------------------------------
+// LANG_CONFIGS export
+// ---------------------------------------------------------------------------
+export const LANG_CONFIGS = {
+    typescript: typescriptConfig,
+    python: pythonConfig,
+    ruby: rubyConfig,
+    go: goConfig,
+    java: javaConfig,
+    rust: rustConfig,
+    csharp: csharpConfig,
+    php: phpConfig,
+};
+// ---------------------------------------------------------------------------
+// Backward-compat LANG_KINDS derived from LANG_CONFIGS
+// (used by the dedicated typescript.ts, python.ts, ruby.ts extractors)
+// Takes the first element of each array to match the old single-string format,
+// then merges in language-specific extras.
+// ---------------------------------------------------------------------------
+function firstOf(arr) {
+    return arr?.[0];
+}
+function derivedKinds(config) {
+    const result = {};
+    if (firstOf(config.class)) {
+        result.class = firstOf(config.class);
+    }
+    if (firstOf(config.function)) {
+        result.function = firstOf(config.function);
+    }
+    if (firstOf(config.method)) {
+        result.method = firstOf(config.method);
+    }
+    if (firstOf(config.constructorKinds)) {
+        // biome-ignore lint/complexity/useLiteralKeys: bracket notation required — dot notation resolves to Function.prototype.constructor (TS2322)
+        result['constructor'] = firstOf(config.constructorKinds);
+    }
+    if (firstOf(config.interface)) {
+        result.interface = firstOf(config.interface);
+    }
+    if (firstOf(config.enum)) {
+        result.enum = firstOf(config.enum);
+    }
+    if (firstOf(config.import)) {
+        result.import = firstOf(config.import);
+    }
+    return result;
+}
+export const LANG_KINDS = {
+    typescript: {
+        ...derivedKinds(typescriptConfig),
+        abstractClass: 'abstract_class_declaration',
+        arrowContainer: 'variable_declarator',
+        arrowFunction: 'arrow_function',
+        export: 'export_statement',
+        methodSignature: 'method_signature',
+    },
+    python: {
+        ...derivedKinds(pythonConfig),
+        importRegular: 'import_statement',
+        decorator: 'decorator',
+    },
+    ruby: {
+        ...derivedKinds(rubyConfig),
+        module: 'module',
+        singletonMethod: 'singleton_method',
+        call: 'call',
+    },
+    go: {
+        ...derivedKinds(goConfig),
+        struct: 'type_declaration',
+    },
+    java: {
+        ...derivedKinds(javaConfig),
+        annotation: 'marker_annotation',
+    },
+    rust: {
+        ...derivedKinds(rustConfig),
+        impl: 'impl_item',
+        struct: 'struct_item',
+        trait: 'trait_item',
+        use: 'use_declaration',
+    },
+    csharp: {
+        ...derivedKinds(csharpConfig),
+        using: 'using_directive',
+        attribute: 'attribute',
+    },
+    php: {
+        ...derivedKinds(phpConfig),
+        namespace: 'namespace_use_declaration',
+    },
+};
+export { Lang };

package/dist/resolver/call-resolver.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { ImportMap } from './import-map';
+import type { SymbolTable } from './symbol-table';
+interface CallResolverStats {
+    di: number;
+    same: number;
+    import: number;
+    unique: number;
+    ambiguous: number;
+    noise: number;
+}
+interface ResolveAllResult {
+    callEdges: RawCallEdge[];
+    stats: CallResolverStats;
+}
+/**
+ * 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 declare function resolveAllCalls(rawCalls: RawCallSite[], diMaps: Map<string, Map<string, string>>, symbolTable: SymbolTable, importMap: ImportMap): ResolveAllResult;
+export declare function resolveCall(callName: string, currentFile: string, symbolTable: SymbolTable, importMap: ImportMap): {
+    target: string;
+    confidence: number;
+} | null;
+export {};

package/dist/resolver/call-resolver.js

@@ -0,0 +1,178 @@
+/**
+ * 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 { NOISE } from '../shared/filters';
+// ── 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, diMaps, symbolTable, importMap) {
+    const callEdges = [];
+    const stats = { 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;
+            }
+        }
+        // Class-aware resolution for self.X() and super().X()
+        if (call.resolveInClass) {
+            const classResolved = resolveInClass(call.callName, fp, call.resolveInClass, symbolTable);
+            if (classResolved) {
+                callEdges.push({
+                    source: fp,
+                    target: classResolved.target,
+                    callName: call.callName,
+                    line: call.line,
+                    confidence: classResolved.confidence,
+                });
+                stats[classResolved.strategy]++;
+                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 };
+}
+// ── Class-aware resolution (self./super.) ──
+function resolveInClass(callName, currentFile, className, symbolTable) {
+    // Try same-file class method first (self.method() or super().method())
+    const inFile = symbolTable.lookupInFile(currentFile, callName, className);
+    if (inFile) {
+        return { target: inFile, confidence: 0.9, strategy: 'same' };
+    }
+    // Class might be in another file (imported parent class for super())
+    const candidates = symbolTable.lookupGlobal(callName);
+    const match = candidates.find((q) => q.includes(`::${className}.${callName}`));
+    if (match) {
+        return { target: match, confidence: 0.85, strategy: 'import' };
+    }
+    return null;
+}
+// ── DI resolution ──
+function resolveDICall(fieldName, methodName, _currentFile, diMap, symbolTable) {
+    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, currentFile, symbolTable, importMap) {
+    // 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) — pick closest candidate by directory proximity
+    const candidates = symbolTable.lookupGlobal(callName);
+    if (candidates.length > 1) {
+        const best = pickClosestCandidate(candidates, currentFile);
+        return { target: best, confidence: 0.3, strategy: 'ambiguous' };
+    }
+    return null;
+}
+// ── Proximity-based candidate selection ──
+/**
+ * Pick the candidate whose file path is closest to the caller's file.
+ * Counts shared leading path segments — more shared = closer.
+ */
+function pickClosestCandidate(candidates, callerFile) {
+    const callerParts = callerFile.split('/');
+    let best = candidates[0];
+    let bestScore = -1;
+    for (const candidate of candidates) {
+        const candidateFile = candidate.includes('::') ? candidate.split('::')[0] : candidate;
+        const parts = candidateFile.split('/');
+        let shared = 0;
+        for (let i = 0; i < Math.min(callerParts.length, parts.length); i++) {
+            if (callerParts[i] === parts[i]) {
+                shared++;
+            }
+            else {
+                break;
+            }
+        }
+        if (shared > bestScore) {
+            bestScore = shared;
+            best = candidate;
+        }
+    }
+    return best;
+}
+// ── Public wrapper for unit testing ──
+export function resolveCall(callName, currentFile, symbolTable, importMap) {
+    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/dist/resolver/external-detector.d.ts

@@ -0,0 +1,11 @@
+/**
+ * External package detector.
+ * Reads dependency manifests (package.json, requirements.txt, go.mod, etc.)
+ * to determine if an import target is an external (third-party) package.
+ */
+export declare function clearExternalCache(): void;
+/**
+ * Check if an import is an external (third-party) package.
+ * Returns the package name if external, null if not detected as external.
+ */
+export declare function detectExternal(modulePath: string, lang: string, repoRoot: string): string | null;