@getmikk/core 1.8.2 → 1.9.0

package/src/graph/graph-builder.ts

@@ -1,355 +1,415 @@
-import * as path from 'node:path'
+import * as nodePath from 'node:path'
 import type { DependencyGraph, GraphNode, GraphEdge } from './types.js'
-import type { ParsedFile, ParsedFunction, ParsedClass } from '../parser/types.js'
+import type { MikkLock } from '../contract/schema.js'
+import type { ParsedFile, ParsedFunction, ParsedClass, ParsedVariable, ParsedGeneric } from '../parser/types.js'
+
+export const EDGE_WEIGHTS = {
+    imports: 1.0,
+    extends: 0.9,
+    implements: 0.8,
+    calls: { exact: 1.0, fuzzy: 0.6, method: 0.8, dynamic: 0.4 },
+    accesses: 0.5,
+    contains: 1.0,
+};
 
 /**
- * GraphBuilder — takes parsed files and builds the dependency graph.
+ * GraphBuilder — three-pass dependency graph construction.
  *
- * Three-pass approach:
- *   Pass 1: Register all nodes (files, functions, classes, generics)
- *   Pass 2: Add all edges (imports, calls, containment)
- *   Pass 3: Build adjacency maps for O(1) traversal
+ * ID contract (must match oxc-parser.ts exactly):
+ *   function:  fn:<absolute-posix-path>:<FunctionName>
+ *   class:     class:<absolute-posix-path>:<ClassName>
+ *   type/enum: type:<absolute-posix-path>:<Name> | enum:<absolute-posix-path>:<Name>
+ *   variable:  var:<absolute-posix-path>:<Name>
+ *   file:      <absolute-posix-path>  (no prefix)
  *
- * Key correctness guarantees:
- *   - No duplicate edges (tracked via edgeKey Set)
- *   - Method nodes are resolved correctly via ClassName.method lookup
- *   - Default imports are handled separately from named imports
- *   - moduleId is propagated from ParsedFunction/ParsedClass to graph nodes
- *   - Unresolved calls are tracked and emitted as low-confidence edges where possible
+ * No case normalisation — paths and names keep their original case.
+ * Lookups use exact string matching after posix-normalising separators.
  */
 export class GraphBuilder {
-    /** Main entry point — takes all parsed files and returns the complete graph */
     build(files: ParsedFile[]): DependencyGraph {
-        const graph: DependencyGraph = {
-            nodes: new Map(),
-            edges: [],
-            outEdges: new Map(),
-            inEdges: new Map(),
-        }
-
-        // Used to deduplicate edges: "source->target:type"
+        const graph = this.createEmptyGraph()
         const edgeKeys = new Set<string>()
 
-        // Pass 1: add all nodes
+        // Pass 1: Register all nodes
         for (const file of files) {
             this.addFileNode(graph, file)
-            for (const fn of file.functions) {
-                this.addFunctionNode(graph, fn)
-            }
-            for (const cls of file.classes ?? []) {
-                this.addClassNode(graph, cls, file.path)
-            }
-            for (const gen of file.generics ?? []) {
-                this.addGenericNode(graph, gen)
-            }
+            for (const fn of file.functions) this.addFunctionNode(graph, fn)
+            for (const cls of file.classes ?? []) this.addClassNode(graph, cls)
+            for (const gen of file.generics ?? []) this.addGenericNode(graph, gen)
+            for (const v of file.variables ?? []) this.addVariableNode(graph, v)
         }
 
-        // Pass 2: add all edges
+        // Pass 2: Structural edges (imports, containment, inheritance)
         for (const file of files) {
             this.addImportEdges(graph, file, edgeKeys)
-            this.addCallEdges(graph, file, edgeKeys)
             this.addContainmentEdges(graph, file, edgeKeys)
+            this.addInheritanceEdges(graph, file, edgeKeys)
+        }
+
+        // Pass 3: Behavioural edges (calls, accesses)
+        for (const file of files) {
+            this.addCallEdges(graph, file, edgeKeys)
         }
 
-        // Pass 3: build adjacency maps for fast lookup
         this.buildAdjacencyMaps(graph)
+        return graph
+    }
+
+    /**
+     * Rebuild a lightweight DependencyGraph from a serialised lock file.
+     * Used for preflight checks without re-parsing the codebase.
+     */
+    buildFromLock(lock: MikkLock): DependencyGraph {
+        const graph = this.createEmptyGraph()
+        const edgeKeys = new Set<string>()
+
+        // File nodes
+        for (const file of Object.values(lock.files)) {
+            const p = this.normPath(file.path)
+            graph.nodes.set(p, {
+                id: p, type: 'file', name: nodePath.basename(p),
+                file: p, moduleId: file.moduleId,
+                metadata: { hash: file.hash },
+            })
+        }
+
+        // Function nodes
+        for (const fn of Object.values(lock.functions)) {
+            graph.nodes.set(fn.id, {
+                id: fn.id, type: 'function', name: fn.name,
+                file: this.normPath(fn.file), moduleId: fn.moduleId,
+                metadata: { ...fn },
+            })
+        }
+
+        // Class nodes
+        for (const cls of Object.values(lock.classes ?? {})) {
+            graph.nodes.set(cls.id, {
+                id: cls.id, type: 'class', name: cls.name,
+                file: this.normPath(cls.file), moduleId: cls.moduleId,
+                metadata: { ...cls },
+            })
+        }
+
+        // Edges from lock data
+        for (const file of Object.values(lock.files)) {
+            const fp = this.normPath(file.path)
+            // Import edges
+            for (const imp of file.imports ?? []) {
+                if (!imp.resolvedPath) continue
+                const rp = this.normPath(imp.resolvedPath)
+                if (graph.nodes.has(rp)) {
+                    this.pushEdge(graph, edgeKeys, { from: fp, to: rp, type: 'imports', confidence: 1.0, weight: EDGE_WEIGHTS.imports })
+                }
+            }
+            // Containment: file → functions in this file
+            for (const fn of Object.values(lock.functions)) {
+                if (this.normPath(fn.file) === fp) {
+                    this.pushEdge(graph, edgeKeys, { from: fp, to: fn.id, type: 'contains', confidence: 1.0, weight: EDGE_WEIGHTS.contains })
+                }
+            }
+        }
+
+        // Call edges
+        for (const fn of Object.values(lock.functions)) {
+            for (const calleeId of fn.calls) {
+                if (graph.nodes.has(calleeId)) {
+                    this.pushEdge(graph, edgeKeys, { from: fn.id, to: calleeId, type: 'calls', confidence: 0.8, weight: EDGE_WEIGHTS.calls.exact })
+                }
+            }
+        }
 
+        this.buildAdjacencyMaps(graph)
         return graph
     }
 
     // -------------------------------------------------------------------------
-    // Node registration
+    // Helpers
+    // -------------------------------------------------------------------------
+
+    private normPath(p: string): string {
+        return p.replace(/\\/g, '/').toLowerCase()
+    }
+
+    private createEmptyGraph(): DependencyGraph {
+        return { nodes: new Map(), edges: [], outEdges: new Map(), inEdges: new Map() }
+    }
+
+    // -------------------------------------------------------------------------
+    // Pass 1: Node Registration
     // -------------------------------------------------------------------------
 
     private addFileNode(graph: DependencyGraph, file: ParsedFile): void {
-        graph.nodes.set(file.path, {
-            id: file.path,
-            type: 'file',
-            label: path.basename(file.path),
-            file: file.path,
-            // moduleId on file nodes is not set here — it comes from the lock compiler
-            // which maps files to declared modules after graph construction.
-            metadata: { hash: file.hash },
+        const p = this.normPath(file.path)
+        graph.nodes.set(p, {
+            id: p, type: 'file', name: nodePath.basename(p),
+            file: p, metadata: { hash: file.hash },
         })
     }
 
     private addFunctionNode(graph: DependencyGraph, fn: ParsedFunction): void {
-        // Use fn.moduleId if the parser/compiler populated it; otherwise leave undefined.
-        // The lock compiler sets moduleId on MikkLockFunction; the graph node mirrors it
-        // when graph is rebuilt from lock. For fresh parse output moduleId may be absent.
-        const node: GraphNode = {
-            id: fn.id,
-            type: 'function',
-            label: fn.name,
-            file: fn.file,
+        graph.nodes.set(fn.id, {
+            id: fn.id, type: 'function', name: fn.name,
+            file: this.normPath(fn.file), moduleId: fn.moduleId,
             metadata: {
-                startLine: fn.startLine,
-                endLine: fn.endLine,
-                isExported: fn.isExported,
-                isAsync: fn.isAsync,
-                hash: fn.hash,
-                purpose: fn.purpose,
-                params: fn.params?.map(p => ({
-                    name: p.name,
-                    type: p.type,
-                    ...(p.optional ? { optional: true } : {}),
-                })),
-                returnType: fn.returnType !== 'void' ? fn.returnType : undefined,
+                startLine: fn.startLine, endLine: fn.endLine,
+                isExported: fn.isExported, isAsync: fn.isAsync,
+                hash: fn.hash, purpose: fn.purpose,
+                params: fn.params, returnType: fn.returnType !== 'void' ? fn.returnType : undefined,
                 edgeCasesHandled: fn.edgeCasesHandled,
                 errorHandling: fn.errorHandling,
                 detailedLines: fn.detailedLines,
             },
-        }
-        // Propagate moduleId if available on the parsed function
-        if (fn.moduleId) {
-            node.moduleId = fn.moduleId
-        }
-        graph.nodes.set(fn.id, node)
+        })
     }
 
-    private addClassNode(graph: DependencyGraph, cls: ParsedClass, filePath: string): void {
-        const node: GraphNode = {
-            id: cls.id,
-            type: 'class',
-            label: cls.name,
-            file: filePath,
+    private addClassNode(graph: DependencyGraph, cls: ParsedClass): void {
+        const p = this.normPath(cls.file)
+        graph.nodes.set(cls.id, {
+            id: cls.id, type: 'class', name: cls.name, file: p, moduleId: cls.moduleId,
             metadata: {
-                startLine: cls.startLine,
-                endLine: cls.endLine,
-                isExported: cls.isExported,
-                purpose: cls.purpose,
-                edgeCasesHandled: cls.edgeCasesHandled,
-                errorHandling: cls.errorHandling,
+                startLine: cls.startLine, endLine: cls.endLine,
+                isExported: cls.isExported, purpose: cls.purpose,
+                inheritsFrom: cls.extends ? [cls.extends] : [],
+                implements: cls.implements,
             },
-        }
-        if (cls.moduleId) {
-            node.moduleId = cls.moduleId
-        }
-        graph.nodes.set(cls.id, node)
-        // Add nodes for each method
-        for (const method of cls.methods) {
-            this.addFunctionNode(graph, method)
-        }
+        })
+        for (const method of cls.methods) this.addFunctionNode(graph, method)
+        for (const prop of cls.properties ?? []) this.addVariableNode(graph, prop)
     }
 
-    private addGenericNode(graph: DependencyGraph, gen: any): void {
+    private addGenericNode(graph: DependencyGraph, gen: ParsedGeneric): void {
         graph.nodes.set(gen.id, {
-            id: gen.id,
-            type: 'generic',
-            label: gen.name,
-            file: gen.file,
+            id: gen.id, type: 'generic', name: gen.name,
+            file: this.normPath(gen.file),
             metadata: {
-                startLine: gen.startLine,
-                endLine: gen.endLine,
-                isExported: gen.isExported,
-                purpose: gen.purpose,
-                hash: gen.type,
+                startLine: gen.startLine, endLine: gen.endLine,
+                isExported: gen.isExported, purpose: gen.purpose,
+                // Store the kind (interface/type/enum) in genericKind, NOT hash
+                genericKind: gen.type,
             },
         })
     }
 
+    private addVariableNode(graph: DependencyGraph, v: ParsedVariable): void {
+        graph.nodes.set(v.id, {
+            id: v.id, type: 'variable', name: v.name,
+            file: this.normPath(v.file),
+            metadata: { startLine: v.line, isExported: v.isExported, purpose: v.purpose },
+        })
+    }
+
     // -------------------------------------------------------------------------
-    // Edge construction
+    // Pass 2: Structural Edges
     // -------------------------------------------------------------------------
 
-    /**
-     * Import edges: fileA → fileB via 'imports'.
-     * Only created when resolvedPath is non-empty AND the target file node exists.
-     * When resolvedPath is empty the import was unresolved — no edge is created,
-     * avoiding false positive graph connections to non-existent paths.
-     */
-    private addImportEdges(
-        graph: DependencyGraph,
-        file: ParsedFile,
-        edgeKeys: Set<string>,
-    ): void {
+    private addImportEdges(graph: DependencyGraph, file: ParsedFile, edgeKeys: Set<string>): void {
+        const src = this.normPath(file.path)
         for (const imp of file.imports) {
-            if (!imp.resolvedPath || !graph.nodes.has(imp.resolvedPath)) continue
-            this.pushEdge(graph, edgeKeys, {
-                source: file.path,
-                target: imp.resolvedPath,
-                type: 'imports',
-                confidence: 1.0,
-            })
+            if (!imp.resolvedPath) continue
+            const tgt = this.normPath(imp.resolvedPath)
+            if (!graph.nodes.has(tgt)) continue
+            this.pushEdge(graph, edgeKeys, { from: src, to: tgt, type: 'imports', confidence: 1.0, weight: EDGE_WEIGHTS.imports })
         }
     }
 
-    /**
-     * Call edges: fnA → fnB via 'calls'.
-     *
-     * Resolution strategy (in priority order):
-     *   1. Named imports: `import { foo } from './x'` → maps foo → fn:./x:foo
-     *   2. Default import aliased calls: `import jwt from 'x'; jwt.verify()` →
-     *      the receiver (jwt) is matched against default import bindings.
-     *      The method name (verify) is looked up in the resolved module.
-     *   3. Local function in the same file (exact name match)
-     *   4. Local class method (ClassName.method format)
-     *
-     * Confidence levels:
-     *   1.0 — exact name, same file
-     *   0.8 — resolved through named import
-     *   0.6 — resolved through default import + method name lookup
-     *   0.5 — dotted-access name stripped to simple name (uncertain receiver)
-     */
-    private addCallEdges(
-        graph: DependencyGraph,
-        file: ParsedFile,
-        edgeKeys: Set<string>,
-    ): void {
-        // Build named-import map: importedName → canonicalFunctionId
-        const importedNames = new Map<string, string>()
-        // Build default-import map: localAlias → resolvedFilePath
-        const defaultImports = new Map<string, string>()
+    private addContainmentEdges(graph: DependencyGraph, file: ParsedFile, edgeKeys: Set<string>): void {
+        const src = this.normPath(file.path)
+        for (const fn of file.functions) {
+            this.pushEdge(graph, edgeKeys, { from: src, to: fn.id, type: 'contains', confidence: 1.0, weight: EDGE_WEIGHTS.contains })
+        }
+        for (const cls of file.classes ?? []) {
+            this.pushEdge(graph, edgeKeys, { from: src, to: cls.id, type: 'contains', confidence: 1.0, weight: EDGE_WEIGHTS.contains })
+            for (const method of cls.methods) {
+                this.pushEdge(graph, edgeKeys, { from: cls.id, to: method.id, type: 'contains', confidence: 1.0, weight: EDGE_WEIGHTS.contains })
+            }
+            for (const prop of cls.properties ?? []) {
+                this.pushEdge(graph, edgeKeys, { from: cls.id, to: prop.id, type: 'contains', confidence: 1.0, weight: EDGE_WEIGHTS.contains })
+            }
+        }
+        for (const gen of file.generics ?? []) {
+            this.pushEdge(graph, edgeKeys, { from: src, to: gen.id, type: 'contains', confidence: 1.0, weight: EDGE_WEIGHTS.contains })
+        }
+        for (const v of file.variables ?? []) {
+            this.pushEdge(graph, edgeKeys, { from: src, to: v.id, type: 'contains', confidence: 1.0, weight: EDGE_WEIGHTS.contains })
+        }
+    }
+
+    private addInheritanceEdges(graph: DependencyGraph, file: ParsedFile, edgeKeys: Set<string>): void {
+        // Build class name → id map from graph (already populated in Pass 1)
+        const classNameToId = new Map<string, string>()
+        for (const [, node] of graph.nodes) {
+            if (node.type === 'class') classNameToId.set(node.name, node.id)
+        }
+
+        for (const cls of file.classes ?? []) {
+            if (cls.extends && classNameToId.has(cls.extends)) {
+                this.pushEdge(graph, edgeKeys, {
+                    from: cls.id, to: classNameToId.get(cls.extends)!,
+                    type: 'extends', confidence: 1.0, weight: EDGE_WEIGHTS.extends,
+                })
+            }
+            for (const iface of cls.implements ?? []) {
+                if (classNameToId.has(iface)) {
+                    this.pushEdge(graph, edgeKeys, {
+                        from: cls.id, to: classNameToId.get(iface)!,
+                        type: 'implements', confidence: 1.0, weight: EDGE_WEIGHTS.implements,
+                    })
+                }
+            }
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Pass 3: Behavioural Edges (calls, accesses)
+    //
+    // Call resolution order (priority-first):
+    //   1. Named import: `import { foo } from './x'` → fn:<resolvedPath>:foo
+    //   2. Default import alias: `import jwt from './x'; jwt.verify()` → fn:<resolvedPath>:verify
+    //   3. Local function exact: same file, same name
+    //   4. Local class method: SomeClass.method in same file
+    //
+    // Confidence levels:
+    //   1.0  — local exact match (AST confirmed)
+    //   0.8  — named import match
+    //   0.6  — default-import method match
+    //   0.5  — dotted name stripped to simple name (receiver uncertain)
+    // -------------------------------------------------------------------------
+
+    private addCallEdges(graph: DependencyGraph, file: ParsedFile, edgeKeys: Set<string>): void {
+        const filePath = this.normPath(file.path)
+
+        // Build import lookup tables for this file
+        // key: the local name used in code (e.g. "verifyToken")
+        // value: the canonical graph node ID (e.g. "fn:/abs/path/jwt.ts:verifyToken")
+        const namedImportIds = new Map<string, string>()
+        // key: local alias (e.g. "jwt"), value: resolved absolute file path
+        const defaultImportPaths = new Map<string, string>()
 
         for (const imp of file.imports) {
             if (!imp.resolvedPath) continue
+            const resolvedPath = this.normPath(imp.resolvedPath)
+
             for (const name of imp.names) {
+                const localName = name.toLowerCase()
                 if (imp.isDefault) {
-                    // `import jwt from 'x'` → defaultImports.set('jwt', 'src/x.ts')
-                    defaultImports.set(name, imp.resolvedPath)
+                    // `import jwt from './jwt'` → defaultImportPaths['jwt'] = '/abs/.../jwt.ts'
+                    defaultImportPaths.set(localName, resolvedPath)
                 } else {
-                    // `import { foo } from 'x'` → importedNames.set('foo', 'fn:src/x.ts:foo')
-                    importedNames.set(name, `fn:${imp.resolvedPath}:${name}`)
+                    // `import { verifyToken } from './jwt'` → namedImportIds['verifyToken'] = 'fn:.../jwt.ts:verifytoken'
+                    const candidateId = `fn:${resolvedPath}:${localName}`
+                    if (graph.nodes.has(candidateId)) {
+                        namedImportIds.set(localName, candidateId)
+                    }
                 }
             }
         }
 
-        // Build class name → class id map for this file (for method resolution)
+        // Class name → class node ID for local method resolution
         const localClassIds = new Map<string, string>()
         for (const cls of file.classes ?? []) {
             localClassIds.set(cls.name, cls.id)
         }
 
-        const allFunctions = [
-            ...file.functions,
-            ...(file.classes ?? []).flatMap(c => c.methods),
+        // Collect all (sourceId, callName) pairs from every function and method
+        const behaviors: Array<{ sourceId: string; calls: Array<{ name: string; type: string }> }> = [
+            // Module-level calls
+            { sourceId: filePath, calls: file.calls ?? [] },
+            // Function-level calls
+            ...file.functions.map(fn => ({ sourceId: fn.id, calls: fn.calls })),
+            // Class method calls
+            ...(file.classes ?? []).flatMap(cls =>
+                cls.methods.map(m => ({ sourceId: m.id, calls: m.calls }))
+            ),
         ]
 
-        for (const fn of allFunctions) {
-            for (const call of fn.calls) {
-                const hasDot = call.includes('.')
-                const simpleName = hasDot ? call.split('.').pop()! : call
-                const receiver = hasDot ? call.split('.')[0] : null
+        for (const { sourceId, calls } of behaviors) {
+            for (const call of calls) {
+                const callName = call.name
+                if (!callName || callName === 'super') continue
+
+                const normalizedCallName = callName.toLowerCase()
+                const hasDot = normalizedCallName.includes('.')
+                const simpleName = hasDot ? normalizedCallName.split('.').pop()! : normalizedCallName
+                const receiver = hasDot ? normalizedCallName.split('.')[0] : null
+                const isPropertyAccess = call.type === 'property'
 
-                // --- 1. Named import exact match ---
-                const namedId = importedNames.get(call) ?? importedNames.get(simpleName)
-                if (namedId && graph.nodes.has(namedId)) {
+                // ── 1. Named import exact match ──────────────────────────
+                // Try full name first (e.g. "jwt.verify" mapped via named import of "verify")
+                const namedId = namedImportIds.get(normalizedCallName) ?? (receiver === null ? namedImportIds.get(simpleName) : undefined)
+                if (namedId) {
                     this.pushEdge(graph, edgeKeys, {
-                        source: fn.id,
-                        target: namedId,
-                        type: 'calls',
-                        confidence: 0.8,
+                        from: sourceId, to: namedId,
+                        type: isPropertyAccess ? 'accesses' : 'calls',
+                        confidence: 0.8, weight: EDGE_WEIGHTS.calls.exact,
                     })
                     continue
                 }
 
-                // --- 2. Default import: receiver is the alias, method is simpleName ---
-                if (receiver && defaultImports.has(receiver)) {
-                    const resolvedFile = defaultImports.get(receiver)!
-                    // Try to find "fn:resolvedFile:simpleName" in graph
+                // ── 2. Default import: receiver is the alias ─────────────
+                if (receiver && defaultImportPaths.has(receiver)) {
+                    const resolvedFile = defaultImportPaths.get(receiver)!
                     const methodId = `fn:${resolvedFile}:${simpleName}`
                     if (graph.nodes.has(methodId)) {
                         this.pushEdge(graph, edgeKeys, {
-                            source: fn.id,
-                            target: methodId,
-                            type: 'calls',
-                            confidence: 0.6,
+                            from: sourceId, to: methodId,
+                            type: isPropertyAccess ? 'accesses' : 'calls',
+                            confidence: 0.6, weight: EDGE_WEIGHTS.calls.method,
                         })
                         continue
                     }
                 }
 
-                // --- 3. Local function exact match ---
-                const localExactId = `fn:${file.path}:${simpleName}`
-                if (graph.nodes.has(localExactId) && localExactId !== fn.id) {
+                // ── 3. Local function exact match ────────────────────────
+                const localId = `fn:${filePath}:${simpleName}`
+                if (graph.nodes.has(localId) && localId !== sourceId) {
                     this.pushEdge(graph, edgeKeys, {
-                        source: fn.id,
-                        target: localExactId,
-                        type: 'calls',
-                        confidence: simpleName === call ? 1.0 : 0.5,
+                        from: sourceId, to: localId,
+                        type: isPropertyAccess ? 'accesses' : 'calls',
+                        confidence: simpleName === callName ? 1.0 : 0.5,
+                        weight: simpleName === callName ? EDGE_WEIGHTS.calls.exact : EDGE_WEIGHTS.calls.fuzzy,
                     })
                     continue
                 }
 
-                // --- 4. Local class method: ClassName.method format ---
+                // ── 4. Local class method: SomeClass.method ──────────────
                 if (receiver && localClassIds.has(receiver)) {
-                    const clsId = localClassIds.get(receiver)!
-                    // Method IDs are stored as "fn:file:ClassName.methodName"
-                    const classMethodId = `fn:${file.path}:${receiver}.${simpleName}`
-                    if (graph.nodes.has(classMethodId) && classMethodId !== fn.id) {
+                    // Method IDs are stored as fn:<file>:<ClassName>.<methodName>
+                    const classMethodId = `fn:${filePath}:${receiver}.${simpleName}`
+                    if (graph.nodes.has(classMethodId) && classMethodId !== sourceId) {
                         this.pushEdge(graph, edgeKeys, {
-                            source: fn.id,
-                            target: classMethodId,
-                            type: 'calls',
-                            confidence: 0.8,
+                            from: sourceId, to: classMethodId,
+                            type: isPropertyAccess ? 'accesses' : 'calls',
+                            confidence: 0.8, weight: EDGE_WEIGHTS.calls.method,
                         })
                         continue
                     }
                 }
 
-                // Unresolved call — not added to graph.
+                // Unresolved call — intentionally not added to graph.
                 // Callers can detect incomplete coverage by comparing
-                // fn.calls.length to the number of outgoing 'calls' edges from fn.id.
-            }
-        }
-    }
-
-    /** Containment edges: file → function, file → class, class → method */
-    private addContainmentEdges(
-        graph: DependencyGraph,
-        file: ParsedFile,
-        edgeKeys: Set<string>,
-    ): void {
-        for (const fn of file.functions) {
-            this.pushEdge(graph, edgeKeys, {
-                source: file.path,
-                target: fn.id,
-                type: 'contains',
-            })
-        }
-        for (const cls of file.classes ?? []) {
-            this.pushEdge(graph, edgeKeys, {
-                source: file.path,
-                target: cls.id,
-                type: 'contains',
-            })
-            for (const method of cls.methods) {
-                this.pushEdge(graph, edgeKeys, {
-                    source: cls.id,
-                    target: method.id,
-                    type: 'contains',
-                })
+                // fn.calls.length vs outgoing 'calls' edge count on fn.id.
             }
         }
     }
 
     // -------------------------------------------------------------------------
-    // Helpers
+    // Edge helpers
     // -------------------------------------------------------------------------
 
-    /**
-     * Push an edge only if it hasn't been added before.
-     * Edge key format: "source->target:type"
-     */
-    private pushEdge(
-        graph: DependencyGraph,
-        edgeKeys: Set<string>,
-        edge: GraphEdge,
-    ): void {
-        const key = `${edge.source}->${edge.target}:${edge.type}`
+    private pushEdge(graph: DependencyGraph, edgeKeys: Set<string>, edge: GraphEdge): void {
+        const key = `${edge.from}->${edge.to}:${edge.type}`
         if (edgeKeys.has(key)) return
         edgeKeys.add(key)
         graph.edges.push(edge)
     }
 
-    /** Build adjacency maps from edge list for O(1) lookups */
     private buildAdjacencyMaps(graph: DependencyGraph): void {
         for (const edge of graph.edges) {
-            if (!graph.outEdges.has(edge.source)) graph.outEdges.set(edge.source, [])
-            graph.outEdges.get(edge.source)!.push(edge)
-
-            if (!graph.inEdges.has(edge.target)) graph.inEdges.set(edge.target, [])
-            graph.inEdges.get(edge.target)!.push(edge)
+            if (!graph.outEdges.has(edge.from)) graph.outEdges.set(edge.from, [])
+            graph.outEdges.get(edge.from)!.push(edge)
+            if (!graph.inEdges.has(edge.to)) graph.inEdges.set(edge.to, [])
+            graph.inEdges.get(edge.to)!.push(edge)
         }
     }
 }