@zuvia-software-solutions/code-mapper 1.4.0

package/dist/core/ingestion/resolvers/go.d.ts

@@ -0,0 +1,8 @@
+/** @file Go package import resolution using go.mod module paths */
+export interface GoModuleConfig {
+    modulePath: string;
+}
+/** Extract the package directory suffix from a Go import path (e.g., "/internal/auth/") */
+export declare function resolveGoPackageDir(importPath: string, goModule: GoModuleConfig): string | null;
+/** Resolve a Go package import to all .go files in the package directory */
+export declare function resolveGoPackage(importPath: string, goModule: GoModuleConfig, normalizedFileList: string[], allFileList: string[]): string[];

package/dist/core/ingestion/resolvers/go.js

@@ -0,0 +1,33 @@
+// code-mapper/src/core/ingestion/resolvers/go.ts
+/** @file Go package import resolution using go.mod module paths */
+/** Extract the package directory suffix from a Go import path (e.g., "/internal/auth/") */
+export function resolveGoPackageDir(importPath, goModule) {
+    if (!importPath.startsWith(goModule.modulePath))
+        return null;
+    const relativePkg = importPath.slice(goModule.modulePath.length + 1);
+    if (!relativePkg)
+        return null;
+    return '/' + relativePkg + '/';
+}
+/** Resolve a Go package import to all .go files in the package directory */
+export function resolveGoPackage(importPath, goModule, normalizedFileList, allFileList) {
+    if (!importPath.startsWith(goModule.modulePath))
+        return [];
+    const relativePkg = importPath.slice(goModule.modulePath.length + 1); // e.g., "internal/auth"
+    if (!relativePkg)
+        return [];
+    const pkgSuffix = '/' + relativePkg + '/';
+    const matches = [];
+    for (let i = 0; i < normalizedFileList.length; i++) {
+        // Prepend '/' so "internal/auth/service.go" matches suffix "/internal/auth/"
+        const normalized = '/' + normalizedFileList[i];
+        // Must be directly in the package directory (not a subdirectory)
+        if (normalized.includes(pkgSuffix) && normalized.endsWith('.go') && !normalized.endsWith('_test.go')) {
+            const afterPkg = normalized.substring(normalized.indexOf(pkgSuffix) + pkgSuffix.length);
+            if (!afterPkg.includes('/')) {
+                matches.push(allFileList[i]);
+            }
+        }
+    }
+    return matches;
+}

package/dist/core/ingestion/resolvers/index.d.ts

@@ -0,0 +1,14 @@
+/** @file Barrel export for language-specific import resolvers */
+export { EXTENSIONS, tryResolveWithExtensions, buildSuffixIndex, suffixResolve } from './utils.js';
+export type { SuffixIndex } from './utils.js';
+export { KOTLIN_EXTENSIONS, appendKotlinWildcard, resolveJvmWildcard, resolveJvmMemberImport } from './jvm.js';
+export { resolveGoPackageDir, resolveGoPackage } from './go.js';
+export type { GoModuleConfig } from './go.js';
+export { resolveCSharpImport, resolveCSharpNamespaceDir } from './csharp.js';
+export type { CSharpProjectConfig } from './csharp.js';
+export { resolvePhpImport } from './php.js';
+export type { ComposerConfig } from './php.js';
+export { resolveRustImport, tryRustModulePath } from './rust.js';
+export { resolveRubyImport } from './ruby.js';
+export { resolveImportPath, RESOLVE_CACHE_CAP } from './standard.js';
+export type { TsconfigPaths } from './standard.js';

package/dist/core/ingestion/resolvers/index.js

@@ -0,0 +1,10 @@
+// code-mapper/src/core/ingestion/resolvers/index.ts
+/** @file Barrel export for language-specific import resolvers */
+export { EXTENSIONS, tryResolveWithExtensions, buildSuffixIndex, suffixResolve } from './utils.js';
+export { KOTLIN_EXTENSIONS, appendKotlinWildcard, resolveJvmWildcard, resolveJvmMemberImport } from './jvm.js';
+export { resolveGoPackageDir, resolveGoPackage } from './go.js';
+export { resolveCSharpImport, resolveCSharpNamespaceDir } from './csharp.js';
+export { resolvePhpImport } from './php.js';
+export { resolveRustImport, tryRustModulePath } from './rust.js';
+export { resolveRubyImport } from './ruby.js';
+export { resolveImportPath, RESOLVE_CACHE_CAP } from './standard.js';

package/dist/core/ingestion/resolvers/jvm.d.ts

@@ -0,0 +1,9 @@
+/** @file JVM import resolution for Java and Kotlin (wildcards, member/static imports) */
+import type { SuffixIndex } from './utils.js';
+export declare const KOTLIN_EXTENSIONS: readonly string[];
+/** Append .* to a Kotlin import path if a wildcard_import sibling node exists */
+export declare const appendKotlinWildcard: (importPath: string, importNode: any) => string;
+/** Resolve a JVM wildcard import (com.example.*) to all matching files */
+export declare function resolveJvmWildcard(importPath: string, normalizedFileList: string[], allFileList: string[], extensions: readonly string[], index?: SuffixIndex): string[];
+/** Resolve a JVM member/static import by stripping the member name */
+export declare function resolveJvmMemberImport(importPath: string, normalizedFileList: string[], allFileList: string[], extensions: readonly string[], index?: SuffixIndex): string | null;

package/dist/core/ingestion/resolvers/jvm.js

@@ -0,0 +1,74 @@
+// code-mapper/src/core/ingestion/resolvers/jvm.ts
+/** @file JVM import resolution for Java and Kotlin (wildcards, member/static imports) */
+// Kotlin file extensions for JVM resolver reuse
+export const KOTLIN_EXTENSIONS = ['.kt', '.kts'];
+/** Append .* to a Kotlin import path if a wildcard_import sibling node exists */
+export const appendKotlinWildcard = (importPath, importNode) => {
+    for (let i = 0; i < importNode.childCount; i++) {
+        if (importNode.child(i)?.type === 'wildcard_import') {
+            return importPath.endsWith('.*') ? importPath : `${importPath}.*`;
+        }
+    }
+    return importPath;
+};
+/** Resolve a JVM wildcard import (com.example.*) to all matching files */
+export function resolveJvmWildcard(importPath, normalizedFileList, allFileList, extensions, index) {
+    // "com.example.util.*" -> "com/example/util"
+    const packagePath = importPath.slice(0, -2).replace(/\./g, '/');
+    if (index) {
+        const candidates = extensions.flatMap(ext => index.getFilesInDir(packagePath, ext));
+        // Filter to only direct children (no subdirectories)
+        const packageSuffix = '/' + packagePath + '/';
+        return candidates.filter(f => {
+            const normalized = f.replace(/\\/g, '/');
+            const idx = normalized.indexOf(packageSuffix);
+            if (idx < 0)
+                return false;
+            const afterPkg = normalized.substring(idx + packageSuffix.length);
+            return !afterPkg.includes('/');
+        });
+    }
+    // Fallback: linear scan
+    const packageSuffix = '/' + packagePath + '/';
+    const matches = [];
+    for (let i = 0; i < normalizedFileList.length; i++) {
+        const normalized = normalizedFileList[i];
+        if (normalized.includes(packageSuffix) &&
+            extensions.some(ext => normalized.endsWith(ext))) {
+            const afterPackage = normalized.substring(normalized.indexOf(packageSuffix) + packageSuffix.length);
+            if (!afterPackage.includes('/')) {
+                matches.push(allFileList[i]);
+            }
+        }
+    }
+    return matches;
+}
+/** Resolve a JVM member/static import by stripping the member name */
+export function resolveJvmMemberImport(importPath, normalizedFileList, allFileList, extensions, index) {
+    // Last segment is a member if it starts with lowercase, is ALL_CAPS, or is a wildcard
+    const segments = importPath.split('.');
+    if (segments.length < 3)
+        return null;
+    const lastSeg = segments[segments.length - 1];
+    if (lastSeg === '*' || /^[a-z]/.test(lastSeg) || /^[A-Z_]+$/.test(lastSeg)) {
+        const classPath = segments.slice(0, -1).join('/');
+        for (const ext of extensions) {
+            const classSuffix = classPath + ext;
+            if (index) {
+                const result = index.get(classSuffix) || index.getInsensitive(classSuffix);
+                if (result)
+                    return result;
+            }
+            else {
+                const fullSuffix = '/' + classSuffix;
+                for (let i = 0; i < normalizedFileList.length; i++) {
+                    if (normalizedFileList[i].endsWith(fullSuffix) ||
+                        normalizedFileList[i].toLowerCase().endsWith(fullSuffix.toLowerCase())) {
+                        return allFileList[i];
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/core/ingestion/resolvers/php.d.ts

@@ -0,0 +1,7 @@
+/** @file PHP PSR-4 import resolution via composer.json autoload mappings */
+import type { SuffixIndex } from './utils.js';
+export interface ComposerConfig {
+    psr4: Map<string, string>;
+}
+/** Resolve a PHP use-statement via PSR-4 mappings, falling back to suffix matching */
+export declare function resolvePhpImport(importPath: string, composerConfig: ComposerConfig | null, allFiles: Set<string>, normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string | null;

package/dist/core/ingestion/resolvers/php.js

@@ -0,0 +1,30 @@
+// code-mapper/src/core/ingestion/resolvers/php.ts
+/** @file PHP PSR-4 import resolution via composer.json autoload mappings */
+import { suffixResolve } from './utils.js';
+/** Resolve a PHP use-statement via PSR-4 mappings, falling back to suffix matching */
+export function resolvePhpImport(importPath, composerConfig, allFiles, normalizedFileList, allFileList, index) {
+    // Normalize backslashes to forward slashes
+    const normalized = importPath.replace(/\\/g, '/');
+    // Try PSR-4 resolution if composer.json is available
+    if (composerConfig) {
+        // Longest match wins
+        const sorted = [...composerConfig.psr4.entries()].sort((a, b) => b[0].length - a[0].length);
+        for (const [nsPrefix, dirPrefix] of sorted) {
+            const nsPrefixSlash = nsPrefix.replace(/\\/g, '/');
+            if (normalized.startsWith(nsPrefixSlash + '/') || normalized === nsPrefixSlash) {
+                const remainder = normalized.slice(nsPrefixSlash.length).replace(/^\//, '');
+                const filePath = dirPrefix + (remainder ? '/' + remainder : '') + '.php';
+                if (allFiles.has(filePath))
+                    return filePath;
+                if (index) {
+                    const result = index.getInsensitive(filePath);
+                    if (result)
+                        return result;
+                }
+            }
+        }
+    }
+    // Fallback: suffix matching (works without composer.json)
+    const pathParts = normalized.split('/').filter(Boolean);
+    return suffixResolve(pathParts, normalizedFileList, allFileList, index);
+}

package/dist/core/ingestion/resolvers/ruby.d.ts

@@ -0,0 +1,9 @@
+/** @file Ruby require/require_relative import resolution via suffix matching */
+import type { SuffixIndex } from './utils.js';
+/**
+ * Resolve a Ruby require/require_relative path to a matching .rb file
+ *
+ * require_relative paths are pre-normalized to './' prefix by the caller;
+ * require paths use suffix matching (gem-style paths like 'json', 'net/http')
+ */
+export declare function resolveRubyImport(importPath: string, normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string | null;

package/dist/core/ingestion/resolvers/ruby.js

@@ -0,0 +1,13 @@
+// code-mapper/src/core/ingestion/resolvers/ruby.ts
+/** @file Ruby require/require_relative import resolution via suffix matching */
+import { suffixResolve } from './utils.js';
+/**
+ * Resolve a Ruby require/require_relative path to a matching .rb file
+ *
+ * require_relative paths are pre-normalized to './' prefix by the caller;
+ * require paths use suffix matching (gem-style paths like 'json', 'net/http')
+ */
+export function resolveRubyImport(importPath, normalizedFileList, allFileList, index) {
+    const pathParts = importPath.replace(/^\.\//, '').split('/').filter(Boolean);
+    return suffixResolve(pathParts, normalizedFileList, allFileList, index);
+}

package/dist/core/ingestion/resolvers/rust.d.ts

@@ -0,0 +1,5 @@
+/** @file Rust module import resolution for crate::, super::, self:: paths */
+/** Resolve a Rust use-path to a file, handling crate::, super::, self:: prefixes */
+export declare function resolveRustImport(currentFile: string, importPath: string, allFiles: Set<string>): string | null;
+/** Try to resolve a Rust module path to a file (path.rs, path/mod.rs, or symbol-stripped) */
+export declare function tryRustModulePath(modulePath: string, allFiles: Set<string>): string | null;

package/dist/core/ingestion/resolvers/rust.js

@@ -0,0 +1,62 @@
+// code-mapper/src/core/ingestion/resolvers/rust.ts
+/** @file Rust module import resolution for crate::, super::, self:: paths */
+/** Resolve a Rust use-path to a file, handling crate::, super::, self:: prefixes */
+export function resolveRustImport(currentFile, importPath, allFiles) {
+    let rustPath;
+    if (importPath.startsWith('crate::')) {
+        // crate:: resolves from src/ (standard Rust layout)
+        rustPath = importPath.slice(7).replace(/::/g, '/');
+        // Try from src/ (standard layout)
+        const fromSrc = tryRustModulePath('src/' + rustPath, allFiles);
+        if (fromSrc)
+            return fromSrc;
+        // Try from repo root (non-standard)
+        const fromRoot = tryRustModulePath(rustPath, allFiles);
+        if (fromRoot)
+            return fromRoot;
+        return null;
+    }
+    if (importPath.startsWith('super::')) {
+        // super:: = parent directory of current file's module
+        const currentDir = currentFile.split('/').slice(0, -1);
+        currentDir.pop(); // Go up one level for super::
+        rustPath = importPath.slice(7).replace(/::/g, '/');
+        const fullPath = [...currentDir, rustPath].join('/');
+        return tryRustModulePath(fullPath, allFiles);
+    }
+    if (importPath.startsWith('self::')) {
+        // self:: = current module's directory
+        const currentDir = currentFile.split('/').slice(0, -1);
+        rustPath = importPath.slice(6).replace(/::/g, '/');
+        const fullPath = [...currentDir, rustPath].join('/');
+        return tryRustModulePath(fullPath, allFiles);
+    }
+    // Bare path without prefix — convert :: to / and try suffix matching
+    if (importPath.includes('::')) {
+        rustPath = importPath.replace(/::/g, '/');
+        return tryRustModulePath(rustPath, allFiles);
+    }
+    return null;
+}
+/** Try to resolve a Rust module path to a file (path.rs, path/mod.rs, or symbol-stripped) */
+export function tryRustModulePath(modulePath, allFiles) {
+    // Try direct: path.rs
+    if (allFiles.has(modulePath + '.rs'))
+        return modulePath + '.rs';
+    // Try directory: path/mod.rs
+    if (allFiles.has(modulePath + '/mod.rs'))
+        return modulePath + '/mod.rs';
+    // Try path/lib.rs (for crate root)
+    if (allFiles.has(modulePath + '/lib.rs'))
+        return modulePath + '/lib.rs';
+    // Last segment might be a symbol name, not a module — strip and retry
+    const lastSlash = modulePath.lastIndexOf('/');
+    if (lastSlash > 0) {
+        const parentPath = modulePath.substring(0, lastSlash);
+        if (allFiles.has(parentPath + '.rs'))
+            return parentPath + '.rs';
+        if (allFiles.has(parentPath + '/mod.rs'))
+            return parentPath + '/mod.rs';
+    }
+    return null;
+}

package/dist/core/ingestion/resolvers/standard.d.ts

@@ -0,0 +1,16 @@
+/** @file Standard import path resolution with relative imports, path alias rewriting, and suffix matching */
+import type { SuffixIndex } from './utils.js';
+import { SupportedLanguages } from '../../../config/supported-languages.js';
+export interface TsconfigPaths {
+    aliases: Map<string, string>;
+    baseUrl: string;
+}
+export declare const RESOLVE_CACHE_CAP = 100000;
+/**
+ * Resolve an import path to a file path in the repository
+ *
+ * Applies language-specific preprocessing (TS/JS path aliases, Rust module paths)
+ * before generic resolution. Java wildcards and Go packages are handled separately
+ * in processImports because they resolve to multiple files.
+ */
+export declare const resolveImportPath: (currentFile: string, importPath: string, allFiles: Set<string>, allFileList: string[], normalizedFileList: string[], resolveCache: Map<string, string | null>, language: SupportedLanguages, tsconfigPaths: TsconfigPaths | null, index?: SuffixIndex) => string | null;

package/dist/core/ingestion/resolvers/standard.js

@@ -0,0 +1,144 @@
+// code-mapper/src/core/ingestion/resolvers/standard.ts
+/** @file Standard import path resolution with relative imports, path alias rewriting, and suffix matching */
+import { tryResolveWithExtensions, suffixResolve } from './utils.js';
+import { resolveRustImport } from './rust.js';
+import { SupportedLanguages } from '../../../config/supported-languages.js';
+// Max entries in the resolve cache (100K entries ≈ 15MB)
+export const RESOLVE_CACHE_CAP = 100_000;
+/**
+ * Resolve an import path to a file path in the repository
+ *
+ * Applies language-specific preprocessing (TS/JS path aliases, Rust module paths)
+ * before generic resolution. Java wildcards and Go packages are handled separately
+ * in processImports because they resolve to multiple files.
+ */
+export const resolveImportPath = (currentFile, importPath, allFiles, allFileList, normalizedFileList, resolveCache, language, tsconfigPaths, index) => {
+    const cacheKey = `${currentFile}::${importPath}`;
+    if (resolveCache.has(cacheKey))
+        return resolveCache.get(cacheKey) ?? null;
+    const cache = (result) => {
+        // Evict oldest 20% when cap is reached
+        if (resolveCache.size >= RESOLVE_CACHE_CAP) {
+            const evictCount = Math.floor(RESOLVE_CACHE_CAP * 0.2);
+            const iter = resolveCache.keys();
+            for (let i = 0; i < evictCount; i++) {
+                const key = iter.next().value;
+                if (key !== undefined)
+                    resolveCache.delete(key);
+            }
+        }
+        resolveCache.set(cacheKey, result);
+        return result;
+    };
+    // TypeScript/JavaScript: rewrite path aliases
+    if ((language === SupportedLanguages.TypeScript || language === SupportedLanguages.JavaScript) &&
+        tsconfigPaths &&
+        !importPath.startsWith('.')) {
+        for (const [aliasPrefix, targetPrefix] of tsconfigPaths.aliases) {
+            if (importPath.startsWith(aliasPrefix)) {
+                const remainder = importPath.slice(aliasPrefix.length);
+                // Rewrite path relative to baseUrl
+                const rewritten = tsconfigPaths.baseUrl === '.'
+                    ? targetPrefix + remainder
+                    : tsconfigPaths.baseUrl + '/' + targetPrefix + remainder;
+                // Try direct resolution from repo root first
+                const resolved = tryResolveWithExtensions(rewritten, allFiles);
+                if (resolved)
+                    return cache(resolved);
+                // Try suffix matching as fallback
+                const parts = rewritten.split('/').filter(Boolean);
+                const suffixResult = suffixResolve(parts, normalizedFileList, allFileList, index);
+                if (suffixResult)
+                    return cache(suffixResult);
+            }
+        }
+    }
+    // Rust: convert module path syntax to file paths
+    if (language === SupportedLanguages.Rust) {
+        // Grouped imports: extract prefix path before ::{...} and resolve the module
+        let rustImportPath = importPath;
+        const braceIdx = importPath.indexOf('::{');
+        if (braceIdx !== -1) {
+            rustImportPath = importPath.substring(0, braceIdx);
+        }
+        else if (importPath.startsWith('{') && importPath.endsWith('}')) {
+            // Top-level grouped imports: use {crate::a, crate::b}
+            // Returns first resolving part; callers needing ALL edges intercept earlier
+            const inner = importPath.slice(1, -1);
+            const parts = inner.split(',').map(p => p.trim()).filter(Boolean);
+            for (const part of parts) {
+                const partResult = resolveRustImport(currentFile, part, allFiles);
+                if (partResult)
+                    return cache(partResult);
+            }
+            return cache(null);
+        }
+        const rustResult = resolveRustImport(currentFile, rustImportPath, allFiles);
+        if (rustResult)
+            return cache(rustResult);
+        // Fall through to generic resolution if Rust-specific resolver missed
+    }
+    // Python relative imports (PEP 328): .module, ..module, ...
+    if (language === SupportedLanguages.Python && importPath.startsWith('.')) {
+        const dotMatch = importPath.match(/^(\.+)(.*)/);
+        if (dotMatch) {
+            const dotCount = dotMatch[1].length;
+            const modulePart = dotMatch[2]; // e.g., "models" from ".models"
+            const dirParts = currentFile.split('/').slice(0, -1);
+            // 1 dot = same package, each additional dot goes up one level
+            for (let i = 1; i < dotCount; i++) {
+                dirParts.pop();
+            }
+            if (modulePart) {
+                // from .models import User → resolve "models" relative to current package
+                const modulePath = modulePart.replace(/\./g, '/');
+                dirParts.push(...modulePath.split('/'));
+            }
+            const basePath = dirParts.join('/');
+            const resolved = tryResolveWithExtensions(basePath, allFiles);
+            return cache(resolved);
+        }
+    }
+    // Generic relative import resolution (./ and ../)
+    const currentDir = currentFile.split('/').slice(0, -1);
+    const parts = importPath.split('/');
+    for (const part of parts) {
+        if (part === '.')
+            continue;
+        if (part === '..') {
+            currentDir.pop();
+        }
+        else {
+            currentDir.push(part);
+        }
+    }
+    const basePath = currentDir.join('/');
+    if (importPath.startsWith('.')) {
+        const resolved = tryResolveWithExtensions(basePath, allFiles);
+        if (resolved)
+            return cache(resolved);
+        // ESM TypeScript: import from './foo.js' refers to './foo.ts'
+        // Strip .js/.jsx/.mjs/.cjs extension and retry with TS/native extensions
+        const jsExtMatch = basePath.match(/\.(js|jsx|mjs|cjs)$/);
+        if (jsExtMatch) {
+            const stripped = basePath.slice(0, -jsExtMatch[0].length);
+            const retried = tryResolveWithExtensions(stripped, allFiles);
+            if (retried)
+                return cache(retried);
+        }
+        return cache(null);
+    }
+    // Generic package/absolute import resolution (suffix matching)
+    // Java wildcards are handled in processImports, not here
+    if (importPath.endsWith('.*')) {
+        return cache(null);
+    }
+    // C/C++ includes use actual file paths (e.g. "animal.h") — don't convert dots to slashes
+    const isCpp = language === SupportedLanguages.C || language === SupportedLanguages.CPlusPlus;
+    const pathLike = importPath.includes('/') || isCpp
+        ? importPath
+        : importPath.replace(/\./g, '/');
+    const pathParts = pathLike.split('/').filter(Boolean);
+    const resolved = suffixResolve(pathParts, normalizedFileList, allFileList, index);
+    return cache(resolved);
+};

package/dist/core/ingestion/resolvers/utils.d.ts

@@ -0,0 +1,18 @@
+/** @file Shared utilities for import path resolution including extension matching and suffix indexing */
+export declare const EXTENSIONS: string[];
+/** Try to match a path (with extensions) against the known file set */
+export declare function tryResolveWithExtensions(basePath: string, allFiles: Set<string>): string | null;
+/**
+ * O(1) suffix index mapping every possible path suffix to its original file path
+ *
+ * For "src/com/example/Foo.java", indexes: "Foo.java", "example/Foo.java", etc
+ */
+export interface SuffixIndex {
+    get(suffix: string): string | undefined;
+    getInsensitive(suffix: string): string | undefined;
+    getFilesInDir(dirSuffix: string, extension: string): string[];
+}
+/** Build a suffix index from normalized and original file lists */
+export declare function buildSuffixIndex(normalizedFileList: string[], allFileList: string[]): SuffixIndex;
+/** Suffix-based resolution using index (O(1) per lookup, falls back to linear scan) */
+export declare function suffixResolve(pathParts: string[], normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string | null;

package/dist/core/ingestion/resolvers/utils.js

@@ -0,0 +1,113 @@
+// code-mapper/src/core/ingestion/resolvers/utils.ts
+/** @file Shared utilities for import path resolution including extension matching and suffix indexing */
+// All file extensions to try during resolution
+export const EXTENSIONS = [
+    '',
+    // TypeScript/JavaScript
+    '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js',
+    // Python
+    '.py', '/__init__.py',
+    // Java
+    '.java',
+    // Kotlin
+    '.kt', '.kts',
+    // C/C++
+    '.c', '.h', '.cpp', '.hpp', '.cc', '.cxx', '.hxx', '.hh',
+    // C#
+    '.cs',
+    // Go
+    '.go',
+    // Rust
+    '.rs', '/mod.rs',
+    // PHP
+    '.php', '.phtml',
+    // Swift
+    '.swift',
+    // Ruby
+    '.rb',
+];
+/** Try to match a path (with extensions) against the known file set */
+export function tryResolveWithExtensions(basePath, allFiles) {
+    for (const ext of EXTENSIONS) {
+        const candidate = basePath + ext;
+        if (allFiles.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** Build a suffix index from normalized and original file lists */
+export function buildSuffixIndex(normalizedFileList, allFileList) {
+    const exactMap = new Map(); // normalized suffix -> original path
+    const lowerMap = new Map(); // lowercase suffix -> original path
+    const dirMap = new Map(); // dir suffix -> file paths in that dir
+    for (let i = 0; i < normalizedFileList.length; i++) {
+        const normalized = normalizedFileList[i];
+        const original = allFileList[i];
+        const parts = normalized.split('/');
+        // Index all suffixes: "a/b/c.java" -> "c.java", "b/c.java", "a/b/c.java"
+        for (let j = parts.length - 1; j >= 0; j--) {
+            const suffix = parts.slice(j).join('/');
+            // First match wins for ambiguous suffixes
+            if (!exactMap.has(suffix)) {
+                exactMap.set(suffix, original);
+            }
+            const lower = suffix.toLowerCase();
+            if (!lowerMap.has(lower)) {
+                lowerMap.set(lower, original);
+            }
+        }
+        // Index directory membership for getFilesInDir lookups
+        const lastSlash = normalized.lastIndexOf('/');
+        if (lastSlash >= 0) {
+            // Build all directory suffix variants
+            const dirParts = parts.slice(0, -1);
+            const fileName = parts[parts.length - 1];
+            const ext = fileName.substring(fileName.lastIndexOf('.'));
+            for (let j = dirParts.length - 1; j >= 0; j--) {
+                const dirSuffix = dirParts.slice(j).join('/');
+                const key = `${dirSuffix}:${ext}`;
+                let list = dirMap.get(key);
+                if (!list) {
+                    list = [];
+                    dirMap.set(key, list);
+                }
+                list.push(original);
+            }
+        }
+    }
+    return {
+        get: (suffix) => exactMap.get(suffix),
+        getInsensitive: (suffix) => lowerMap.get(suffix.toLowerCase()),
+        getFilesInDir: (dirSuffix, extension) => {
+            return dirMap.get(`${dirSuffix}:${extension}`) || [];
+        },
+    };
+}
+/** Suffix-based resolution using index (O(1) per lookup, falls back to linear scan) */
+export function suffixResolve(pathParts, normalizedFileList, allFileList, index) {
+    if (index) {
+        for (let i = 0; i < pathParts.length; i++) {
+            const suffix = pathParts.slice(i).join('/');
+            for (const ext of EXTENSIONS) {
+                const suffixWithExt = suffix + ext;
+                const result = index.get(suffixWithExt) || index.getInsensitive(suffixWithExt);
+                if (result)
+                    return result;
+            }
+        }
+        return null;
+    }
+    // Fallback: linear scan (for backward compatibility)
+    for (let i = 0; i < pathParts.length; i++) {
+        const suffix = pathParts.slice(i).join('/');
+        for (const ext of EXTENSIONS) {
+            const suffixWithExt = suffix + ext;
+            const suffixPattern = '/' + suffixWithExt;
+            const matchIdx = normalizedFileList.findIndex(filePath => filePath.endsWith(suffixPattern) || filePath.toLowerCase().endsWith(suffixPattern.toLowerCase()));
+            if (matchIdx !== -1) {
+                return allFileList[matchIdx];
+            }
+        }
+    }
+    return null;
+}

package/dist/core/ingestion/structure-processor.d.ts

@@ -0,0 +1,4 @@
+/** @file structure-processor.ts @description Builds the file/folder tree structure in the knowledge graph by creating File and Folder nodes with CONTAINS relationships */
+import { KnowledgeGraph } from "../graph/types.js";
+/** Build File/Folder nodes and CONTAINS edges from a list of file paths */
+export declare const processStructure: (graph: KnowledgeGraph, paths: string[]) => void;

package/dist/core/ingestion/structure-processor.js

@@ -0,0 +1,39 @@
+// code-mapper/src/core/ingestion/structure-processor.ts
+/** @file structure-processor.ts @description Builds the file/folder tree structure in the knowledge graph by creating File and Folder nodes with CONTAINS relationships */
+import { generateId } from "../../lib/utils.js";
+/** Build File/Folder nodes and CONTAINS edges from a list of file paths */
+export const processStructure = (graph, paths) => {
+    paths.forEach(path => {
+        const parts = path.split('/');
+        let currentPath = '';
+        let parentId = '';
+        parts.forEach((part, index) => {
+            const isFile = index === parts.length - 1;
+            const label = isFile ? 'File' : 'Folder';
+            currentPath = currentPath ? `${currentPath}/${part}` : part;
+            const nodeId = generateId(label, currentPath);
+            const node = {
+                id: nodeId,
+                label: label,
+                properties: {
+                    name: part,
+                    filePath: currentPath
+                }
+            };
+            graph.addNode(node);
+            if (parentId) {
+                const relId = generateId('CONTAINS', `${parentId}->${nodeId}`);
+                const relationship = {
+                    id: relId,
+                    type: 'CONTAINS',
+                    sourceId: parentId,
+                    targetId: nodeId,
+                    confidence: 1.0,
+                    reason: '',
+                };
+                graph.addRelationship(relationship);
+            }
+            parentId = nodeId;
+        });
+    });
+};