@kodus/kodus-graph 0.2.8 → 0.2.10

package/dist/resolver/fs-cache.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared filesystem cache for resolvers.
+ * Caches existsSync and readdirSync results to avoid repeated disk I/O.
+ * Call clearFsCache() between analysis runs.
+ */
+export declare function cachedExists(path: string): boolean;
+export declare function cachedReaddir(path: string): string[];
+export declare function clearFsCache(): void;

package/dist/resolver/fs-cache.js

@@ -0,0 +1,36 @@
+/**
+ * Shared filesystem cache for resolvers.
+ * Caches existsSync and readdirSync results to avoid repeated disk I/O.
+ * Call clearFsCache() between analysis runs.
+ */
+import { existsSync, readdirSync } from 'fs';
+const existsCache = new Map();
+const readdirCache = new Map();
+export function cachedExists(path) {
+    const cached = existsCache.get(path);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const result = existsSync(path);
+    existsCache.set(path, result);
+    return result;
+}
+export function cachedReaddir(path) {
+    const cached = readdirCache.get(path);
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        const result = readdirSync(path).sort();
+        readdirCache.set(path, result);
+        return result;
+    }
+    catch {
+        readdirCache.set(path, []);
+        return [];
+    }
+}
+export function clearFsCache() {
+    existsCache.clear();
+    readdirCache.clear();
+}

package/dist/resolver/import-map.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function createImportMap(): ImportMap;

package/dist/resolver/import-map.js

@@ -0,0 +1,21 @@
+/**
+ * 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 function createImportMap() {
+    const map = new Map();
+    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/dist/resolver/import-resolver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Import resolver dispatcher.
+ *
+ * Routes import resolution to language-specific resolvers and
+ * falls back to tsconfig aliases for TypeScript/JavaScript.
+ */
+import { loadTsconfigAliases } from './languages/typescript';
+/**
+ * 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 declare function resolveImport(fromAbsFile: string, modulePath: string, lang: string, repoRoot: string, tsconfigAliases?: Map<string, string[]>): string | null;
+export { loadTsconfigAliases };

package/dist/resolver/import-resolver.js

@@ -0,0 +1,310 @@
+/**
+ * Import resolver dispatcher.
+ *
+ * Routes import resolution to language-specific resolvers and
+ * falls back to tsconfig aliases for TypeScript/JavaScript.
+ */
+import { readdirSync, readFileSync } from 'fs';
+import { join, resolve as resolvePath } from 'path';
+import { log } from '../shared/logger';
+import { ensureWithinRoot } from '../shared/safe-path';
+import { detectExternal } from './external-detector';
+import { cachedExists } from './fs-cache';
+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 { loadBundlerAliases, loadTsconfigAliases, resolve as resolveTsImport, resolveWithAliases, } from './languages/typescript';
+/**
+ * Registered import resolvers by language key.
+ *
+ * IMPORTANT: When adding a new language, you MUST:
+ * 1. Create a resolver in src/resolver/languages/<lang>.ts
+ * 2. Add it to this map
+ * 3. Add tests in tests/resolver/<lang>.test.ts
+ * 4. Add external detection in src/resolver/external-detector.ts
+ *
+ * If a language key from the parser is not in this map, resolveImport()
+ * will log a warning and return null. This is intentional — silent
+ * failures that default to another language's resolver cause wrong results.
+ */
+const RESOLVERS = {
+    ts: resolveTsImport,
+    javascript: resolveTsImport,
+    typescript: resolveTsImport,
+    python: resolvePyImport,
+    ruby: resolveRbImport,
+    go: resolveGoImport,
+    java: resolveJavaImport,
+    rust: resolveRustImport,
+    csharp: resolveCsImport,
+    php: resolvePhpImport,
+};
+/**
+ * Resolve package.json #imports (Node.js subpath imports).
+ * Handles both exact matches and wildcard patterns.
+ */
+function resolveHashImport(modulePath, repoRoot) {
+    const pkgPath = join(repoRoot, 'package.json');
+    if (!cachedExists(pkgPath)) {
+        return null;
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const imports = pkg?.imports;
+        if (!imports) {
+            return null;
+        }
+        for (const [pattern, target] of Object.entries(imports)) {
+            if (typeof target !== 'string') {
+                continue;
+            }
+            if (pattern === modulePath) {
+                // Exact match: "#utils" -> "./src/shared/utils.ts"
+                const resolved = resolvePath(repoRoot, target);
+                if (cachedExists(resolved)) {
+                    return resolved;
+                }
+            }
+            // Wildcard match: "#db/*" -> "./src/db/*.ts"
+            if (pattern.includes('*')) {
+                const prefix = pattern.split('*')[0]; // "#db/"
+                if (modulePath.startsWith(prefix)) {
+                    const rest = modulePath.slice(prefix.length); // "connection"
+                    const resolved = resolvePath(repoRoot, target.replace('*', rest));
+                    if (cachedExists(resolved)) {
+                        return resolved;
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // ignore parse errors
+    }
+    return null;
+}
+/**
+ * Resolve a conditional export value to a single string path.
+ * When the value is a plain string, return it directly.
+ * When it's an object with condition keys, prefer: types > import > default > first value.
+ */
+function resolveExportValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        for (const key of ['types', 'import', 'default']) {
+            if (typeof obj[key] === 'string') {
+                return obj[key];
+            }
+        }
+        // Fallback: first value that is a string
+        for (const v of Object.values(obj)) {
+            if (typeof v === 'string') {
+                return v;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolve monorepo workspace package exports.
+ * Scans workspace directories to find packages matching the import specifier.
+ */
+function resolveWorkspaceExport(modulePath, repoRoot) {
+    const rootPkgPath = join(repoRoot, 'package.json');
+    if (!cachedExists(rootPkgPath)) {
+        return null;
+    }
+    try {
+        const rootPkg = JSON.parse(readFileSync(rootPkgPath, 'utf-8'));
+        let workspaceGlobs;
+        if (Array.isArray(rootPkg?.workspaces)) {
+            workspaceGlobs = rootPkg.workspaces;
+        }
+        else if (rootPkg?.workspaces?.packages && Array.isArray(rootPkg.workspaces.packages)) {
+            workspaceGlobs = rootPkg.workspaces.packages;
+        }
+        if (!workspaceGlobs) {
+            return null;
+        }
+        // Collect all workspace package directories
+        const pkgDirs = [];
+        for (const ws of workspaceGlobs) {
+            if (ws.endsWith('/*')) {
+                // Glob pattern like "packages/*"
+                const parentDir = join(repoRoot, ws.slice(0, -2));
+                if (cachedExists(parentDir)) {
+                    const entries = readdirSync(parentDir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        if (entry.isDirectory()) {
+                            pkgDirs.push(join(parentDir, entry.name));
+                        }
+                    }
+                }
+            }
+            else {
+                pkgDirs.push(join(repoRoot, ws));
+            }
+        }
+        // Search each workspace package for a matching name + exports/main/module
+        for (const pkgDir of pkgDirs) {
+            const pkgJsonPath = join(pkgDir, 'package.json');
+            if (!cachedExists(pkgJsonPath)) {
+                continue;
+            }
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const pkgName = pkg?.name;
+            if (!pkgName) {
+                continue;
+            }
+            const exports = pkg?.exports;
+            // Check if modulePath matches this package (exact or subpath)
+            if (modulePath === pkgName) {
+                if (exports && typeof exports === 'object') {
+                    // Root export: "." entry
+                    const target = resolveExportValue(exports['.']);
+                    if (target) {
+                        const resolved = resolvePath(pkgDir, target);
+                        if (cachedExists(resolved)) {
+                            return resolved;
+                        }
+                    }
+                }
+                else if (!exports) {
+                    // Fallback to main or module fields
+                    const fallback = pkg.main ?? pkg.module;
+                    if (typeof fallback === 'string') {
+                        const resolved = resolvePath(pkgDir, fallback);
+                        if (cachedExists(resolved)) {
+                            return resolved;
+                        }
+                    }
+                }
+            }
+            else if (modulePath.startsWith(`${pkgName}/`)) {
+                const subpath = modulePath.slice(pkgName.length + 1);
+                // 1. Try exports field first
+                if (exports && typeof exports === 'object') {
+                    const exportKey = `./${subpath}`;
+                    const target = resolveExportValue(exports[exportKey]);
+                    if (target) {
+                        const resolved = resolvePath(pkgDir, target);
+                        if (cachedExists(resolved)) {
+                            return resolved;
+                        }
+                    }
+                }
+                // 2. No exports or no match? Resolve subpath directly in package directory
+                const directBase = join(pkgDir, subpath);
+                for (const ext of ['.ts', '.tsx', '.js', '.jsx']) {
+                    if (cachedExists(directBase + ext)) {
+                        return resolvePath(directBase + ext);
+                    }
+                }
+                for (const ext of ['.ts', '.tsx', '.js', '.jsx']) {
+                    const idx = join(directBase, `index${ext}`);
+                    if (cachedExists(idx)) {
+                        return resolvePath(idx);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // ignore parse errors
+    }
+    return null;
+}
+/**
+ * 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, modulePath, lang, repoRoot, tsconfigAliases) {
+    const resolver = RESOLVERS[lang];
+    if (!resolver) {
+        log.warn('No import resolver registered for language', { lang, module: modulePath, from: fromAbsFile });
+        return null;
+    }
+    // Strip webpack/rollup loader syntax: !!loader1!loader2!actual/path
+    // The actual import path is always the last segment after the final '!'
+    if (modulePath.includes('!')) {
+        modulePath = modulePath.split('!').pop() || modulePath;
+    }
+    // TS/JS-specific fallbacks: tsconfig aliases, bundler aliases, #imports, workspace exports.
+    // These are Node.js/npm ecosystem features that don't apply to other languages.
+    // Other languages handle their own workspace/monorepo patterns inside their resolvers
+    // (Go: go.work, Rust: Cargo workspace, Java: Maven/Gradle modules).
+    const isTsOrJs = lang === 'ts' || lang === 'javascript' || lang === 'typescript';
+    // Handle package.json #imports (TS/JS only)
+    if (isTsOrJs && modulePath.startsWith('#')) {
+        const result = resolveHashImport(modulePath, repoRoot);
+        if (result) {
+            try {
+                ensureWithinRoot(result, repoRoot);
+                return result;
+            }
+            catch {
+                log.warn('Import resolves outside repository root', {
+                    from: fromAbsFile,
+                    module: modulePath,
+                    resolved: result,
+                });
+                return null;
+            }
+        }
+    }
+    let result = resolver(fromAbsFile, modulePath, repoRoot);
+    // Fallback: tsconfig aliases for TS/JS
+    if (!result && isTsOrJs && tsconfigAliases?.size) {
+        result = resolveWithAliases(modulePath, tsconfigAliases, repoRoot);
+    }
+    // Fallback: bundler aliases (webpack/vite) for TS/JS bare specifiers
+    if (!result && isTsOrJs && !modulePath.startsWith('.')) {
+        const bundlerAliases = loadBundlerAliases(repoRoot);
+        if (bundlerAliases.size > 0) {
+            result = resolveWithAliases(modulePath, bundlerAliases, repoRoot);
+        }
+    }
+    // Fallback: monorepo workspace exports for TS/JS bare specifiers
+    if (!result && isTsOrJs && !modulePath.startsWith('.')) {
+        result = resolveWorkspaceExport(modulePath, 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;
+        }
+    }
+    // If still unresolved, check if it's an external package (for logging/debugging)
+    if (!result) {
+        const externalPkg = detectExternal(modulePath, lang, repoRoot);
+        if (externalPkg) {
+            // External package — expected null, don't log as warning
+            return null;
+        }
+        // Truly unresolved local import
+        log.debug('Unresolved local import', { from: fromAbsFile, module: modulePath });
+    }
+    return result;
+}
+export { loadTsconfigAliases };

package/dist/resolver/languages/csharp.d.ts

@@ -0,0 +1,3 @@
+/** Clear cached .sln data. Call between analysis runs or when switching repos. */
+export declare function clearCache(): void;
+export declare function resolve(_fromAbsFile: string, modulePath: string, repoRoot: string): string | null;

package/dist/resolver/languages/csharp.js

@@ -0,0 +1,94 @@
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { dirname, join, resolve as resolvePath } from 'path';
+import { cachedExists } from '../fs-cache';
+const STDLIB_PREFIXES = ['System.', 'System', 'Microsoft.', 'Newtonsoft.'];
+const slnProjectsCache = new Map();
+/** Clear cached .sln data. Call between analysis runs or when switching repos. */
+export function clearCache() {
+    slnProjectsCache.clear();
+}
+/**
+ * Parse .sln files at repoRoot to discover project directories.
+ * Lines like: Project("{FAE04EC0}") = "Name", "path/to/Project.csproj", "{GUID}"
+ */
+function getSlnProjectDirs(repoRoot) {
+    const cached = slnProjectsCache.get(repoRoot);
+    if (cached) {
+        return cached;
+    }
+    const dirs = [];
+    try {
+        const entries = readdirSync(repoRoot);
+        for (const entry of entries) {
+            if (entry.endsWith('.sln')) {
+                const slnPath = join(repoRoot, entry);
+                try {
+                    const content = readFileSync(slnPath, 'utf-8');
+                    const projectRe = /^Project\("[^"]*"\)\s*=\s*"[^"]*",\s*"([^"]+\.csproj)"/gm;
+                    let m = projectRe.exec(content);
+                    while (m !== null) {
+                        const csprojRelPath = m[1].replace(/\\/g, '/');
+                        const projectDir = dirname(join(repoRoot, csprojRelPath));
+                        if (cachedExists(projectDir)) {
+                            dirs.push(projectDir);
+                        }
+                        m = projectRe.exec(content);
+                    }
+                }
+                catch {
+                    /* ignore unreadable sln */
+                }
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    slnProjectsCache.set(repoRoot, dirs);
+    return dirs;
+}
+export function resolve(_fromAbsFile, modulePath, repoRoot) {
+    if (STDLIB_PREFIXES.some((p) => modulePath.startsWith(p))) {
+        return null;
+    }
+    const segments = modulePath.split('.');
+    // Collect search base directories: standard ones + .sln-discovered project dirs
+    const standardBases = ['', 'src', 'lib', 'Source'];
+    const slnDirs = getSlnProjectDirs(repoRoot);
+    // Try resolving as a .cs file first
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const pathPart = segments.slice(i).join('/');
+        const candidate = `${pathPart}.cs`;
+        for (const base of standardBases) {
+            const full = join(repoRoot, base, candidate);
+            if (cachedExists(full)) {
+                return resolvePath(full);
+            }
+        }
+        // Also search in .sln-discovered project directories
+        for (const projDir of slnDirs) {
+            const full = join(projDir, candidate);
+            if (cachedExists(full)) {
+                return resolvePath(full);
+            }
+        }
+    }
+    // Try resolving as a directory (namespace → folder mapping)
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const pathPart = segments.slice(i).join('/');
+        for (const base of standardBases) {
+            const full = join(repoRoot, base, pathPart);
+            if (cachedExists(full) && statSync(full).isDirectory()) {
+                return resolvePath(full);
+            }
+        }
+        // Also search in .sln-discovered project directories
+        for (const projDir of slnDirs) {
+            const full = join(projDir, pathPart);
+            if (cachedExists(full) && statSync(full).isDirectory()) {
+                return resolvePath(full);
+            }
+        }
+    }
+    return null;
+}

package/dist/resolver/languages/go.d.ts

@@ -0,0 +1,3 @@
+/** Clear cached go.mod data. Call between analysis runs or when switching repos. */
+export declare function clearCache(): void;
+export declare function resolve(_fromAbsFile: string, modulePath: string, repoRoot: string): string | null;