@getmikk/core 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/core",
-    "version": "1.6.0",
+    "version": "1.7.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",

package/src/contract/lock-compiler.ts

@@ -1,4 +1,4 @@
-import * as path from 'node:path'
+import * as path from 'node:path'
 import { createHash } from 'node:crypto'
 import type { MikkContract, MikkLock } from './schema.js'
 import type { DependencyGraph } from '../graph/types.js'
@@ -131,7 +131,7 @@ export class LockCompiler {
         }
 
         const lockData: MikkLock = {
-            version: '1.0.0',
+            version: '1.7.0',
             generatedAt: new Date().toISOString(),
             generatorVersion: VERSION,
             projectRoot: contract.project.name,
@@ -146,7 +146,9 @@ export class LockCompiler {
             classes: Object.keys(classes).length > 0 ? classes : undefined,
             generics: Object.keys(generics).length > 0 ? generics : undefined,
             files,
-            contextFiles: contextFiles && contextFiles.length > 0 ? contextFiles : undefined,
+            contextFiles: contextFiles && contextFiles.length > 0
+                ? contextFiles.map(({ path, type, size }) => ({ path, type, size }))
+                : undefined,
             routes: routes.length > 0 ? routes : undefined,
             graph: {
                 nodes: graph.nodes.size,
@@ -205,7 +207,6 @@ export class LockCompiler {
                 ),
                 edgeCasesHandled: node.metadata.edgeCasesHandled,
                 errorHandling: node.metadata.errorHandling,
-                detailedLines: node.metadata.detailedLines,
             }
         }
 
@@ -333,7 +334,7 @@ export class LockCompiler {
                 path: file.path,
                 hash: file.hash,
                 moduleId: moduleId || 'unknown',
-                lastModified: new Date().toISOString(),
+                lastModified: new Date(file.parsedAt).toISOString(),
                 ...(importedFiles.length > 0 ? { imports: importedFiles } : {}),
             }
         }

package/src/contract/lock-reader.ts

@@ -32,7 +32,7 @@ export class LockReader {
     /** Write lock file to disk in compact format */
     async write(lock: MikkLock, lockPath: string): Promise<void> {
         const compact = compactifyLock(lock)
-        const json = JSON.stringify(compact, null, 2)
+        const json = JSON.stringify(compact)
         await fs.writeFile(lockPath, json, 'utf-8')
     }
 }
@@ -59,17 +59,23 @@ function compactifyLock(lock: MikkLock): any {
         graph: lock.graph,
     }
 
+    // P7: Build fnIndex for integer edge references
+    const fnKeys = Object.keys(lock.functions)
+    const fnIndexMap = new Map<string, number>()
+    fnKeys.forEach((k, i) => fnIndexMap.set(k, i))
+    out.fnIndex = fnKeys
+
     // Functions — biggest savings
     out.functions = {}
-    for (const [key, fn] of Object.entries(lock.functions)) {
+    for (let idx = 0; idx < fnKeys.length; idx++) {
+        const fn = lock.functions[fnKeys[idx]]
         const c: any = {
             lines: [fn.startLine, fn.endLine],
-            hash: fn.hash,
+            // P4: no hash, P6: no moduleId
         }
-        // Only write non-default fields
-        if (fn.moduleId && fn.moduleId !== 'unknown') c.moduleId = fn.moduleId
-        if (fn.calls.length > 0) c.calls = fn.calls
-        if (fn.calledBy.length > 0) c.calledBy = fn.calledBy
+        // P7: integer calls/calledBy referencing fnIndex positions
+        if (fn.calls.length > 0) c.calls = fn.calls.map(id => fnIndexMap.get(id) ?? -1).filter((n: number) => n >= 0)
+        if (fn.calledBy.length > 0) c.calledBy = fn.calledBy.map(id => fnIndexMap.get(id) ?? -1).filter((n: number) => n >= 0)
         if (fn.params && fn.params.length > 0) c.params = fn.params
         if (fn.returnType) c.returnType = fn.returnType
         if (fn.isAsync) c.isAsync = true
@@ -79,10 +85,8 @@ function compactifyLock(lock: MikkLock): any {
         if (fn.errorHandling && fn.errorHandling.length > 0) {
             c.errors = fn.errorHandling.map(e => [e.line, e.type, e.detail])
         }
-        if (fn.detailedLines && fn.detailedLines.length > 0) {
-            c.details = fn.detailedLines.map(d => [d.startLine, d.endLine, d.blockType])
-        }
-        out.functions[key] = c
+        // P2: no c.details (detailedLines removed)
+        out.functions[String(idx)] = c
     }
 
     // Classes
@@ -134,9 +138,9 @@ function compactifyLock(lock: MikkLock): any {
         out.files[key] = c
     }
 
-    // Context files — keep as-is (content is the bulk, no savings)
+    // Context files — paths/type only, no content
     if (lock.contextFiles && lock.contextFiles.length > 0) {
-        out.contextFiles = lock.contextFiles
+        out.contextFiles = lock.contextFiles.map(({ path, type, size }) => ({ path, type, size }))
     }
 
     // Routes — keep as-is (already compact)
@@ -166,23 +170,37 @@ function hydrateLock(raw: any): any {
         graph: raw.graph,
     }
 
+    // P7: function index for integer edge resolution
+    const fnIndex: string[] = raw.fnIndex || []
+    const hasFnIndex = fnIndex.length > 0
+
+    // P6: build file→moduleId map before function loop
+    const fileModuleMap: Record<string, string> = {}
+    for (const [key, c] of Object.entries(raw.files || {}) as [string, any][]) {
+        fileModuleMap[key] = c.moduleId || 'unknown'
+    }
+
     // Hydrate functions
     out.functions = {}
     for (const [key, c] of Object.entries(raw.functions || {}) as [string, any][]) {
-        // Parse key: "fn:filepath:functionName"
-        const { name, file } = parseEntityKey(key, 'fn:')
+        // P7: key is integer index → look up full ID via fnIndex
+        const fullId = hasFnIndex ? (fnIndex[parseInt(key)] || key) : key
+        const { name, file } = parseEntityKey(fullId, 'fn:')
         const lines = c.lines || [c.startLine || 0, c.endLine || 0]
+        // P7: integer calls/calledBy → resolve to full string IDs (backward compat: strings pass through)
+        const calls = (c.calls || []).map((v: any) => typeof v === 'number' ? (fnIndex[v] ?? null) : v).filter(Boolean)
+        const calledBy = (c.calledBy || []).map((v: any) => typeof v === 'number' ? (fnIndex[v] ?? null) : v).filter(Boolean)
 
-        out.functions[key] = {
-            id: key,
+        out.functions[fullId] = {
+            id: fullId,
             name,
             file,
             startLine: lines[0],
             endLine: lines[1],
-            hash: c.hash || '',
-            calls: c.calls || [],
-            calledBy: c.calledBy || [],
-            moduleId: c.moduleId || 'unknown',
+            hash: c.hash || '',  // P4: empty string when not stored
+            calls,
+            calledBy,
+            moduleId: fileModuleMap[file] || c.moduleId || 'unknown',  // P6: derive from file
             ...(c.params ? { params: c.params } : {}),
             ...(c.returnType ? { returnType: c.returnType } : {}),
             ...(c.isAsync ? { isAsync: true } : {}),
@@ -194,11 +212,7 @@ function hydrateLock(raw: any): any {
                     line: e[0], type: e[1], detail: e[2]
                 }))
             } : {}),
-            ...(c.details && c.details.length > 0 ? {
-                detailedLines: c.details.map((d: any) => ({
-                    startLine: d[0], endLine: d[1], blockType: d[2]
-                }))
-            } : {}),
+            // P2: no detailedLines restoration
         }
     }
 

package/src/contract/schema.ts

@@ -74,11 +74,6 @@ export const MikkLockFunctionSchema = z.object({
         type: z.enum(['try-catch', 'throw']),
         detail: z.string(),
     })).optional(),
-    detailedLines: z.array(z.object({
-        startLine: z.number(),
-        endLine: z.number(),
-        blockType: z.string(),
-    })).optional()
 })
 
 export const MikkLockModuleSchema = z.object({
@@ -129,9 +124,9 @@ export const MikkLockGenericSchema = z.object({
 
 export const MikkLockContextFileSchema = z.object({
     path: z.string(),
-    content: z.string(),
+    content: z.string().optional(),
     type: z.enum(['schema', 'model', 'types', 'routes', 'config', 'api-spec', 'migration', 'docker']),
-    size: z.number(),
+    size: z.number().optional(),
 })
 
 export const MikkLockRouteSchema = z.object({

package/src/index.ts

@@ -10,4 +10,4 @@ export * from './utils/logger.js'
 export { discoverFiles, discoverContextFiles, readFileContent, writeFileContent, fileExists, setupMikkDirectory, readMikkIgnore, parseMikkIgnore, detectProjectLanguage, getDiscoveryPatterns, generateMikkIgnore } from './utils/fs.js'
 export type { ContextFile, ContextFileType, ProjectLanguage } from './utils/fs.js'
 export { minimatch } from './utils/minimatch.js'
-export { scoreFunctions, findFuzzyMatches, levenshtein, splitCamelCase, extractKeywords } from './utils/fuzzy-match.js'
+export { scoreFunctions, findFuzzyMatches, levenshtein, splitCamelCase, extractKeywords } from './utils/fuzzy-match.js'

package/src/parser/index.ts

@@ -2,6 +2,7 @@ import * as path from 'node:path'
 import { BaseParser } from './base-parser.js'
 import { TypeScriptParser } from './typescript/ts-parser.js'
 import { GoParser } from './go/go-parser.js'
+import { JavaScriptParser } from './javascript/js-parser.js'
 import { UnsupportedLanguageError } from '../utils/errors.js'
 import type { ParsedFile } from './types.js'
 
@@ -13,6 +14,9 @@ export { TypeScriptResolver } from './typescript/ts-resolver.js'
 export { GoParser } from './go/go-parser.js'
 export { GoExtractor } from './go/go-extractor.js'
 export { GoResolver } from './go/go-resolver.js'
+export { JavaScriptParser } from './javascript/js-parser.js'
+export { JavaScriptExtractor } from './javascript/js-extractor.js'
+export { JavaScriptResolver } from './javascript/js-resolver.js'
 export { BoundaryChecker } from './boundary-checker.js'
 
 /** Get the appropriate parser for a file based on its extension */
@@ -22,6 +26,11 @@ export function getParser(filePath: string): BaseParser {
         case '.ts':
         case '.tsx':
             return new TypeScriptParser()
+        case '.js':
+        case '.mjs':
+        case '.cjs':
+        case '.jsx':
+            return new JavaScriptParser()
         case '.go':
             return new GoParser()
         default:
@@ -36,8 +45,10 @@ export async function parseFiles(
     readFile: (fp: string) => Promise<string>
 ): Promise<ParsedFile[]> {
     const tsParser = new TypeScriptParser()
+    const jsParser = new JavaScriptParser()
     const goParser = new GoParser()
     const tsFiles: ParsedFile[] = []
+    const jsFiles: ParsedFile[] = []
     const goFiles: ParsedFile[] = []
 
     for (const fp of filePaths) {
@@ -49,6 +60,13 @@ export async function parseFiles(
             } catch {
                 // Skip unreadable files (permissions, binary, etc.) — don't abort the whole parse
             }
+        } else if (ext === '.js' || ext === '.mjs' || ext === '.cjs' || ext === '.jsx') {
+            try {
+                const content = await readFile(path.join(projectRoot, fp))
+                jsFiles.push(jsParser.parse(fp, content))
+            } catch {
+                // Skip unreadable files
+            }
         } else if (ext === '.go') {
             try {
                 const content = await readFile(path.join(projectRoot, fp))
@@ -61,7 +79,8 @@ export async function parseFiles(
 
     // Resolve imports per language after all files of that language are parsed
     const resolvedTs = tsParser.resolveImports(tsFiles, projectRoot)
+    const resolvedJs = jsParser.resolveImports(jsFiles, projectRoot)
     const resolvedGo = goParser.resolveImports(goFiles, projectRoot)
 
-    return [...resolvedTs, ...resolvedGo]
+    return [...resolvedTs, ...resolvedJs, ...resolvedGo]
 }

package/src/parser/javascript/js-extractor.ts

@@ -0,0 +1,262 @@
+import ts from 'typescript'
+import { TypeScriptExtractor } from '../typescript/ts-extractor.js'
+import { hashContent } from '../../hash/file-hasher.js'
+import type { ParsedFunction, ParsedImport, ParsedExport } from '../types.js'
+
+/**
+ * JavaScriptExtractor — extends TypeScriptExtractor to add CommonJS support on top of
+ * the TypeScript Compiler API's native JS/JSX parsing.
+ *
+ * Extra patterns handled:
+ *   - require() imports: const x = require('./m') / const { a } = require('./m')
+ *   - module.exports = { foo, bar }  / module.exports = function() {}
+ *   - exports.foo = function() {}
+ *
+ * All ESM patterns (import/export, arrow functions, classes) are inherited from the
+ * TypeScriptExtractor which already handles ScriptKind.JS and ScriptKind.JSX.
+ */
+export class JavaScriptExtractor extends TypeScriptExtractor {
+
+    // ── Public overrides ───────────────────────────────────────────────────────
+
+    /** ESM functions + module.exports-assigned functions */
+    override extractFunctions(): ParsedFunction[] {
+        const fns = super.extractFunctions()
+        const seen = new Set(fns.map(f => f.name))
+        for (const fn of this.extractCommonJsFunctions()) {
+            if (!seen.has(fn.name)) { fns.push(fn); seen.add(fn.name) }
+        }
+        return fns
+    }
+
+    /** ESM imports + CommonJS require() calls */
+    override extractImports(): ParsedImport[] {
+        const esm = super.extractImports()
+        const seen = new Set(esm.map(i => i.source))
+        for (const imp of this.extractRequireImports()) {
+            if (!seen.has(imp.source)) { esm.push(imp); seen.add(imp.source) }
+        }
+        return esm
+    }
+
+    /** ESM exports + CommonJS module.exports / exports.x */
+    override extractExports(): ParsedExport[] {
+        const esm = super.extractExports()
+        const seen = new Set(esm.map(e => e.name))
+        for (const exp of this.extractCommonJsExports()) {
+            if (!seen.has(exp.name)) { esm.push(exp); seen.add(exp.name) }
+        }
+        return esm
+    }
+
+    // ── CommonJS: require() ────────────────────────────────────────────────────
+
+    private extractRequireImports(): ParsedImport[] {
+        const imports: ParsedImport[] = []
+        const walk = (node: ts.Node) => {
+            if (
+                ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                node.expression.text === 'require' &&
+                node.arguments.length === 1 &&
+                ts.isStringLiteral(node.arguments[0])
+            ) {
+                // Ignore require.resolve(), require.cache etc. — those are property accesses
+                // on the result, not on `require` itself:  require.resolve() has a
+                // PropertyAccessExpression as node.expression, not an Identifier.
+                const source = (node.arguments[0] as ts.StringLiteral).text
+                const names = this.getRequireBindingNames(node)
+                // isDefault = true when binding is a plain identifier (const x = require(...))
+                // or when there's no binding at all (require(...) used for side effects).
+                // Only destructured object bindings (const { a } = require(...)) are named imports.
+                const parent = node.parent
+                const isDestructured = parent &&
+                    ts.isVariableDeclaration(parent) &&
+                    ts.isObjectBindingPattern(parent.name)
+                imports.push({
+                    source,
+                    resolvedPath: '',
+                    names,
+                    isDefault: !isDestructured,
+                    isDynamic: false,
+                })
+            }
+            ts.forEachChild(node, walk)
+        }
+        ts.forEachChild(this.sourceFile, walk)
+        return imports
+    }
+
+    /** Names extracted from the variable declaration that receives the require() call. */
+    private getRequireBindingNames(call: ts.CallExpression): string[] {
+        const parent = call.parent
+        if (!parent || !ts.isVariableDeclaration(parent)) return []
+        // const { a, b } = require('...') → ['a', 'b']
+        if (ts.isObjectBindingPattern(parent.name)) {
+            return parent.name.elements
+                .filter(e => ts.isIdentifier(e.name))
+                .map(e => (e.name as ts.Identifier).text)
+        }
+        // const x = require('...') → ['x']
+        if (ts.isIdentifier(parent.name)) return [parent.name.text]
+        return []
+    }
+
+    // ── CommonJS: module.exports / exports.x exports ─────────────────────────
+
+    private extractCommonJsExports(): ParsedExport[] {
+        const result: ParsedExport[] = []
+        const fp = this.filePath
+
+        const walk = (node: ts.Node) => {
+            if (
+                ts.isExpressionStatement(node) &&
+                ts.isBinaryExpression(node.expression) &&
+                node.expression.operatorToken.kind === ts.SyntaxKind.EqualsToken
+            ) {
+                const lhs = node.expression.left
+                const rhs = node.expression.right
+
+                // ── module.exports = ... ────────────────────────────────────
+                if (isModuleExports(lhs)) {
+                    if (ts.isObjectLiteralExpression(rhs)) {
+                        // module.exports = { foo, bar }
+                        for (const prop of rhs.properties) {
+                            if (ts.isShorthandPropertyAssignment(prop)) {
+                                result.push({ name: prop.name.text, type: 'const', file: fp })
+                            } else if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                                const isFunc = ts.isFunctionExpression(prop.initializer) || ts.isArrowFunction(prop.initializer)
+                                result.push({ name: prop.name.text, type: isFunc ? 'function' : 'const', file: fp })
+                            }
+                        }
+                    } else if (ts.isFunctionExpression(rhs) || ts.isArrowFunction(rhs)) {
+                        // module.exports = function name() {} → use function name or 'default'
+                        const name = ts.isFunctionExpression(rhs) && rhs.name ? rhs.name.text : 'default'
+                        result.push({ name, type: 'default', file: fp })
+                    } else if (ts.isClassExpression(rhs) && rhs.name) {
+                        result.push({ name: rhs.name.text, type: 'class', file: fp })
+                    } else if (ts.isIdentifier(rhs)) {
+                        result.push({ name: rhs.text, type: 'default', file: fp })
+                    } else {
+                        result.push({ name: 'default', type: 'default', file: fp })
+                    }
+                }
+
+                // ── exports.foo = ... ───────────────────────────────────────
+                if (isExportsDotProp(lhs)) {
+                    const prop = lhs as ts.PropertyAccessExpression
+                    const isFunc = ts.isFunctionExpression(rhs) || ts.isArrowFunction(rhs)
+                    result.push({ name: prop.name.text, type: isFunc ? 'function' : 'const', file: fp })
+                }
+
+                // ── module.exports.foo = ... ────────────────────────────────
+                if (isModuleExportsDotProp(lhs)) {
+                    const prop = lhs as ts.PropertyAccessExpression
+                    const isFunc = ts.isFunctionExpression(rhs) || ts.isArrowFunction(rhs)
+                    result.push({ name: prop.name.text, type: isFunc ? 'function' : 'const', file: fp })
+                }
+            }
+            ts.forEachChild(node, walk)
+        }
+
+        ts.forEachChild(this.sourceFile, walk)
+        return result
+    }
+
+    // ── CommonJS: module.exports / exports.x function bodies ──────────────────
+
+    /**
+     * Detect functions directly assigned via module.exports or exports.x:
+     *   module.exports = function handleLogin(req, res) { ... }
+     *   module.exports = function() { ... }            ← name = 'default'
+     *   exports.createUser = function(data) { ... }
+     *   exports.createUser = (data) => { ... }
+     */
+    private extractCommonJsFunctions(): ParsedFunction[] {
+        const result: ParsedFunction[] = []
+
+        const walk = (node: ts.Node) => {
+            if (
+                ts.isExpressionStatement(node) &&
+                ts.isBinaryExpression(node.expression) &&
+                node.expression.operatorToken.kind === ts.SyntaxKind.EqualsToken
+            ) {
+                const lhs = node.expression.left
+                const rhs = node.expression.right
+
+                if (!ts.isFunctionExpression(rhs) && !ts.isArrowFunction(rhs)) {
+                    ts.forEachChild(node, walk)
+                    return
+                }
+
+                let fnName: string | null = null
+                if (isModuleExports(lhs)) {
+                    // module.exports = function name() {} / function() {}
+                    fnName = ts.isFunctionExpression(rhs) && rhs.name ? rhs.name.text : 'default'
+                } else if (isExportsDotProp(lhs)) {
+                    // exports.foo = function() {}
+                    fnName = (lhs as ts.PropertyAccessExpression).name.text
+                } else if (isModuleExportsDotProp(lhs)) {
+                    // module.exports.foo = function() {}
+                    fnName = (lhs as ts.PropertyAccessExpression).name.text
+                }
+
+                if (fnName !== null) {
+                    const startLine = this.getLineNumber(node.getStart())
+                    const endLine = this.getLineNumber(node.getEnd())
+                    const isAsync = !!(rhs.modifiers?.some((m: ts.Modifier) => m.kind === ts.SyntaxKind.AsyncKeyword))
+                    result.push({
+                        id: `fn:${this.filePath}:${fnName}`,
+                        name: fnName,
+                        file: this.filePath,
+                        startLine,
+                        endLine,
+                        params: this.extractParams(rhs.parameters),
+                        returnType: rhs.type ? rhs.type.getText(this.sourceFile) : 'void',
+                        isExported: true,
+                        isAsync,
+                        calls: this.extractCalls(rhs),
+                        hash: hashContent(rhs.getText(this.sourceFile)),
+                        purpose: this.extractPurpose(node),
+                        edgeCasesHandled: this.extractEdgeCases(rhs),
+                        errorHandling: this.extractErrorHandling(rhs),
+                        detailedLines: this.extractDetailedLines(rhs),
+                    })
+                }
+            }
+            ts.forEachChild(node, walk)
+        }
+
+        ts.forEachChild(this.sourceFile, walk)
+        return result
+    }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** node is `module.exports` */
+function isModuleExports(node: ts.Node): boolean {
+    return (
+        ts.isPropertyAccessExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'module' &&
+        node.name.text === 'exports'
+    )
+}
+
+/** node is `exports.something` */
+function isExportsDotProp(node: ts.Node): boolean {
+    return (
+        ts.isPropertyAccessExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'exports'
+    )
+}
+
+/** node is `module.exports.something` */
+function isModuleExportsDotProp(node: ts.Node): boolean {
+    return (
+        ts.isPropertyAccessExpression(node) &&
+        isModuleExports(node.expression)
+    )
+}

package/src/parser/javascript/js-parser.ts

@@ -0,0 +1,92 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import { BaseParser } from '../base-parser.js'
+import { JavaScriptExtractor } from './js-extractor.js'
+import { JavaScriptResolver } from './js-resolver.js'
+import { hashContent } from '../../hash/file-hasher.js'
+import type { ParsedFile } from '../types.js'
+
+/**
+ * JavaScriptParser — implements BaseParser for .js / .mjs / .cjs / .jsx files.
+ *
+ * Uses the TypeScript Compiler API (ScriptKind.JS / ScriptKind.JSX) which correctly
+ * parses JavaScript without type annotations.  JavaScriptExtractor extends
+ * TypeScriptExtractor and adds CommonJS require() / module.exports support.
+ */
+export class JavaScriptParser extends BaseParser {
+    parse(filePath: string, content: string): ParsedFile {
+        const extractor = new JavaScriptExtractor(filePath, content)
+
+        const functions = extractor.extractFunctions()
+        const classes   = extractor.extractClasses()
+        const generics  = extractor.extractGenerics()
+        const imports   = extractor.extractImports()
+        const exports   = extractor.extractExports()
+        const routes    = extractor.extractRoutes()
+
+        // Cross-reference: CJS exports may mark a name exported even when the
+        // declaration itself had no `export` keyword.
+        const exportedNames = new Set(exports.map(e => e.name))
+        for (const fn  of functions) { if (!fn.isExported  && exportedNames.has(fn.name))  fn.isExported  = true }
+        for (const cls of classes)   { if (!cls.isExported && exportedNames.has(cls.name)) cls.isExported = true }
+        for (const gen of generics)  { if (!gen.isExported && exportedNames.has(gen.name)) gen.isExported = true }
+
+        return {
+            path: filePath,
+            language: 'javascript',
+            functions,
+            classes,
+            generics,
+            imports,
+            exports,
+            routes,
+            hash: hashContent(content),
+            parsedAt: Date.now(),
+        }
+    }
+
+    resolveImports(files: ParsedFile[], projectRoot: string): ParsedFile[] {
+        const aliases = loadAliases(projectRoot)
+        const allFilePaths = files.map(f => f.path)
+        const resolver = new JavaScriptResolver(projectRoot, aliases)
+        return files.map(file => ({
+            ...file,
+            imports: resolver.resolveAll(file.imports, file.path, allFilePaths),
+        }))
+    }
+
+    getSupportedExtensions(): string[] {
+        return ['.js', '.mjs', '.cjs', '.jsx']
+    }
+}
+
+/**
+ * Load path aliases from jsconfig.json → tsconfig.json → tsconfig.base.json.
+ * Strips JS/block comments before parsing (both formats allow them).
+ * Falls back to raw content if comment-stripping breaks a URL.
+ * Returns {} when no config is found.
+ */
+function loadAliases(projectRoot: string): Record<string, string[]> {
+    for (const name of ['jsconfig.json', 'tsconfig.json', 'tsconfig.base.json']) {
+        const configPath = path.join(projectRoot, name)
+        try {
+            const raw = fs.readFileSync(configPath, 'utf-8')
+            const stripped = raw.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '')
+            let config: any
+            try   { config = JSON.parse(stripped) }
+            catch { config = JSON.parse(raw) }          // URL stripping may have broken JSON
+
+            const options  = config.compilerOptions ?? {}
+            const rawPaths: Record<string, string[]> = options.paths ?? {}
+            if (Object.keys(rawPaths).length === 0) continue
+
+            const baseUrl = options.baseUrl ?? '.'
+            const resolved: Record<string, string[]> = {}
+            for (const [alias, targets] of Object.entries(rawPaths)) {
+                resolved[alias] = (targets as string[]).map((t: string) => path.posix.join(baseUrl, t))
+            }
+            return resolved
+        } catch { /* config absent or unreadable — try next */ }
+    }
+    return {}
+}