@codragraph/cli 1.6.2

package/dist/core/ingestion/field-extractors/typescript.js

@@ -0,0 +1,291 @@
+// codragraph/src/core/ingestion/field-extractors/typescript.ts
+import { SupportedLanguages } from '../../../_shared/index.js';
+import { BaseFieldExtractor } from '../field-extractor.js';
+/**
+ * Hand-written TypeScript field extractor.
+ *
+ * This exists alongside the config-based extractor in configs/typescript-javascript.ts
+ * (used for JavaScript) because TypeScript has unique requirements:
+ * 1. type_alias_declaration with object type literals (e.g., type Config = { key: string })
+ * 2. Optional property detection appending '| undefined' to types
+ * 3. Nested type discovery within class/interface bodies
+ *
+ * The config-based extractor cannot express these TS-specific capabilities.
+ * JavaScript uses the config-based version since it lacks type syntax.
+ */
+export class TypeScriptFieldExtractor extends BaseFieldExtractor {
+    language = SupportedLanguages.TypeScript;
+    /**
+     * Node types that represent type declarations with fields in TypeScript
+     */
+    static TYPE_DECLARATION_NODES = new Set([
+        'class_declaration',
+        'interface_declaration',
+        'abstract_class_declaration',
+        'type_alias_declaration', // for object type literals
+    ]);
+    /**
+     * Node types that contain field definitions within class bodies
+     */
+    static FIELD_NODE_TYPES = new Set([
+        'public_field_definition', // class field: private users: User[]
+        'property_signature', // interface property: name: string
+        'field_definition', // fallback field type
+    ]);
+    /**
+     * Visibility modifiers in TypeScript
+     */
+    static VISIBILITY_MODIFIERS = new Set([
+        'public',
+        'private',
+        'protected',
+    ]);
+    /**
+     * Check if this node represents a type declaration with fields
+     */
+    isTypeDeclaration(node) {
+        return TypeScriptFieldExtractor.TYPE_DECLARATION_NODES.has(node.type);
+    }
+    /**
+     * Extract visibility modifier from a field node
+     */
+    extractVisibility(node) {
+        // Check for accessibility_modifier named child (tree-sitter typescript)
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const child = node.namedChild(i);
+            if (child && child.type === 'accessibility_modifier') {
+                const text = child.text.trim();
+                if (TypeScriptFieldExtractor.VISIBILITY_MODIFIERS.has(text)) {
+                    return text;
+                }
+            }
+        }
+        // Check for modifiers in the field's unnamed children (fallback)
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child && !child.isNamed) {
+                const text = child.text.trim();
+                if (TypeScriptFieldExtractor.VISIBILITY_MODIFIERS.has(text)) {
+                    return text;
+                }
+            }
+        }
+        // Check for modifier node (tree-sitter typescript may group these)
+        const modifiers = node.childForFieldName('modifiers');
+        if (modifiers) {
+            for (let i = 0; i < modifiers.childCount; i++) {
+                const modifier = modifiers.child(i);
+                const modText = modifier?.text.trim();
+                if (modText && TypeScriptFieldExtractor.VISIBILITY_MODIFIERS.has(modText)) {
+                    return modText;
+                }
+            }
+        }
+        // TypeScript class members are public by default
+        return 'public';
+    }
+    /**
+     * Check if a field has the static modifier
+     */
+    isStatic(node) {
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child && !child.isNamed && child.text.trim() === 'static') {
+                return true;
+            }
+        }
+        const modifiers = node.childForFieldName('modifiers');
+        if (modifiers) {
+            for (let i = 0; i < modifiers.childCount; i++) {
+                const modifier = modifiers.child(i);
+                if (modifier && modifier.text === 'static') {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Check if a field has the readonly modifier
+     */
+    isReadonly(node) {
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child && !child.isNamed && child.text.trim() === 'readonly') {
+                return true;
+            }
+        }
+        const modifiers = node.childForFieldName('modifiers');
+        if (modifiers) {
+            for (let i = 0; i < modifiers.childCount; i++) {
+                const modifier = modifiers.child(i);
+                if (modifier && modifier.text === 'readonly') {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Check if a property is optional (has ?: syntax)
+     */
+    isOptional(node) {
+        // Look for the optional marker '?' in unnamed children
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child && !child.isNamed && child.text === '?') {
+                return true;
+            }
+        }
+        // Also check for optional_property_signature or marker in type
+        const kind = node.childForFieldName('kind');
+        if (kind && kind.text === '?') {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Extract the full type text, handling complex generic types.
+     *
+     * type_annotation nodes wrap the literal ': SomeType' — only that branch
+     * needs special handling to unwrap the inner child and skip the colon.
+     * All other node kinds are already the type text itself, so normalizeType
+     * is applied directly.
+     */
+    extractFullType(typeNode) {
+        if (!typeNode)
+            return null;
+        if (typeNode.type === 'type_annotation') {
+            const innerType = typeNode.firstNamedChild;
+            return innerType ? this.normalizeType(innerType.text) : null;
+        }
+        return this.normalizeType(typeNode.text);
+    }
+    /**
+     * Extract a single field from a field definition node
+     */
+    extractField(node, context) {
+        // Get the field name
+        const nameNode = node.childForFieldName('name') ?? node.childForFieldName('property');
+        if (!nameNode)
+            return null;
+        const name = nameNode.text;
+        if (!name)
+            return null;
+        // Get the type annotation
+        const typeNode = node.childForFieldName('type');
+        let type = this.extractFullType(typeNode);
+        // Try to resolve the type using the context
+        if (type) {
+            const resolvedType = this.resolveType(type, context);
+            type = resolvedType ?? type;
+        }
+        return {
+            name,
+            type,
+            visibility: this.extractVisibility(node),
+            isStatic: this.isStatic(node),
+            isReadonly: this.isReadonly(node),
+            sourceFile: context.filePath,
+            line: node.startPosition.row + 1,
+        };
+    }
+    /**
+     * Extract fields from a class body or interface body
+     */
+    extractFieldsFromBody(bodyNode, context) {
+        const fields = [];
+        // Find all field definition nodes within the body
+        for (let i = 0; i < bodyNode.namedChildCount; i++) {
+            const child = bodyNode.namedChild(i);
+            if (!child)
+                continue;
+            if (TypeScriptFieldExtractor.FIELD_NODE_TYPES.has(child.type)) {
+                const field = this.extractField(child, context);
+                if (field) {
+                    fields.push(field);
+                }
+            }
+        }
+        return fields;
+    }
+    /**
+     * Extract fields from an object type (used in type aliases)
+     */
+    extractFieldsFromObjectType(objectTypeNode, context) {
+        const fields = [];
+        // Find all property_signature nodes within the object type
+        const propertySignatures = objectTypeNode.descendantsOfType('property_signature');
+        for (const propNode of propertySignatures) {
+            const field = this.extractField(propNode, context);
+            if (field) {
+                // Mark optional properties
+                if (this.isOptional(propNode) && field.type) {
+                    field.type = field.type + ' | undefined';
+                }
+                fields.push(field);
+            }
+        }
+        return fields;
+    }
+    /**
+     * Extract fields from a class or interface declaration
+     */
+    extract(node, context) {
+        if (!this.isTypeDeclaration(node))
+            return null;
+        // Get the type name
+        const nameNode = node.childForFieldName('name');
+        if (!nameNode)
+            return null;
+        const typeName = nameNode.text;
+        const ownerFqn = typeName;
+        const fields = [];
+        const nestedTypes = [];
+        // Handle different declaration types
+        if (node.type === 'class_declaration' || node.type === 'abstract_class_declaration') {
+            // Find the class body
+            const bodyNode = node.childForFieldName('body');
+            if (bodyNode) {
+                const extractedFields = this.extractFieldsFromBody(bodyNode, context);
+                fields.push(...extractedFields);
+            }
+        }
+        else if (node.type === 'interface_declaration') {
+            // Find the interface body
+            const bodyNode = node.childForFieldName('body');
+            if (bodyNode) {
+                const extractedFields = this.extractFieldsFromBody(bodyNode, context);
+                fields.push(...extractedFields);
+            }
+        }
+        else if (node.type === 'type_alias_declaration') {
+            // Handle type aliases with object types
+            const valueNode = node.childForFieldName('value');
+            if (valueNode && valueNode.type === 'object_type') {
+                const extractedFields = this.extractFieldsFromObjectType(valueNode, context);
+                fields.push(...extractedFields);
+            }
+        }
+        // Find nested type declarations
+        const nestedClasses = node.descendantsOfType('class_declaration');
+        const nestedInterfaces = node.descendantsOfType('interface_declaration');
+        const nestedDeclarations = [...nestedClasses, ...nestedInterfaces];
+        for (const nested of nestedDeclarations) {
+            // Skip the current node itself
+            if (nested === node)
+                continue;
+            const nestedName = nested.childForFieldName('name');
+            if (nestedName) {
+                nestedTypes.push(nestedName.text);
+            }
+        }
+        return {
+            ownerFqn,
+            fields,
+            nestedTypes,
+        };
+    }
+}
+// Export a singleton instance for registration
+export const typescriptFieldExtractor = new TypeScriptFieldExtractor();

package/dist/core/ingestion/field-types.d.ts

@@ -0,0 +1,61 @@
+import type { TypeEnvironment } from './type-env.js';
+import type { SymbolTableReader } from './model/index.js';
+import { SupportedLanguages } from '../../_shared/index.js';
+/**
+ * Visibility levels used across all supported languages.
+ * - public / private / protected: universal modifiers
+ * - internal: C#, Kotlin (assembly/module scope)
+ * - protected internal: C# (accessible by same assembly OR derived classes)
+ * - private protected: C# (accessible by derived classes within same assembly)
+ * - package: Java (package-private, no keyword)
+ * - fileprivate: Swift (file scope)
+ * - open: Swift (subclassable across modules)
+ */
+export type FieldVisibility = 'public' | 'private' | 'protected' | 'internal' | 'protected internal' | 'private protected' | 'package' | 'fileprivate' | 'open';
+/**
+ * Represents a field or property within a class/struct/interface
+ */
+export interface FieldInfo {
+    /** Field name */
+    name: string;
+    /** Resolved type (may be primitive, FQN, or generic) */
+    type: string | null;
+    /** Visibility modifier */
+    visibility: FieldVisibility;
+    /** Is this a static member? */
+    isStatic: boolean;
+    /** Is this readonly/const? */
+    isReadonly: boolean;
+    /** Source file path */
+    sourceFile: string;
+    /** Line number */
+    line: number;
+}
+/**
+ * Maps owner type FQN to its fields
+ */
+export type FieldTypeMap = Map<string, FieldInfo[]>;
+/**
+ * Context for field extraction
+ */
+export interface FieldExtractorContext {
+    /** Type environment for resolution */
+    typeEnv: TypeEnvironment;
+    /** Symbol table for FQN lookups */
+    symbolTable: SymbolTableReader;
+    /** Current file path */
+    filePath: string;
+    /** Language ID */
+    language: SupportedLanguages;
+}
+/**
+ * Result of field extraction from a type declaration
+ */
+export interface ExtractedFields {
+    /** Owner type FQN */
+    ownerFqn: string;
+    /** Extracted fields */
+    fields: FieldInfo[];
+    /** Nested types found during extraction */
+    nestedTypes: string[];
+}

package/dist/core/ingestion/field-types.js

@@ -0,0 +1,2 @@
+// codragraph/src/core/ingestion/field-types.ts
+export {};

package/dist/core/ingestion/filesystem-walker.d.ts

@@ -0,0 +1,28 @@
+export interface FileEntry {
+    path: string;
+    content: string;
+}
+/** Lightweight entry — path + size from stat, no content in memory */
+export interface ScannedFile {
+    path: string;
+    size: number;
+}
+/** Path-only reference (for type signatures) */
+export interface FilePath {
+    path: string;
+}
+/**
+ * Phase 1: Scan repository — stat files to get paths + sizes, no content loaded.
+ * Memory: ~10MB for 100K files vs ~1GB+ with content.
+ */
+export declare const walkRepositoryPaths: (repoPath: string, onProgress?: (current: number, total: number, filePath: string) => void) => Promise<ScannedFile[]>;
+/**
+ * Phase 2: Read file contents for a specific set of relative paths.
+ * Returns a Map for O(1) lookup. Silently skips files that fail to read.
+ */
+export declare const readFileContents: (repoPath: string, relativePaths: string[]) => Promise<Map<string, string>>;
+/**
+ * Legacy API — scans and reads everything into memory.
+ * Used by sequential fallback path only.
+ */
+export declare const walkRepository: (repoPath: string, onProgress?: (current: number, total: number, filePath: string) => void) => Promise<FileEntry[]>;

package/dist/core/ingestion/filesystem-walker.js

@@ -0,0 +1,91 @@
+import { isVerboseIngestionEnabled } from './utils/verbose.js';
+import { DEFAULT_MAX_FILE_SIZE_BYTES, getMaxFileSizeBytes } from './utils/max-file-size.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+import { createIgnoreFilter } from '../../config/ignore-service.js';
+const READ_CONCURRENCY = 32;
+/**
+ * Phase 1: Scan repository — stat files to get paths + sizes, no content loaded.
+ * Memory: ~10MB for 100K files vs ~1GB+ with content.
+ */
+export const walkRepositoryPaths = async (repoPath, onProgress) => {
+    const ignoreFilter = await createIgnoreFilter(repoPath);
+    const maxFileSizeBytes = getMaxFileSizeBytes();
+    const filtered = await glob('**/*', {
+        cwd: repoPath,
+        nodir: true,
+        dot: false,
+        ignore: ignoreFilter,
+    });
+    const entries = [];
+    let processed = 0;
+    let skippedLarge = 0;
+    const skippedLargePaths = [];
+    for (let start = 0; start < filtered.length; start += READ_CONCURRENCY) {
+        const batch = filtered.slice(start, start + READ_CONCURRENCY);
+        const results = await Promise.allSettled(batch.map(async (relativePath) => {
+            const fullPath = path.join(repoPath, relativePath);
+            const stat = await fs.stat(fullPath);
+            if (stat.size > maxFileSizeBytes) {
+                skippedLarge++;
+                skippedLargePaths.push(relativePath.replace(/\\/g, '/'));
+                return null;
+            }
+            return { path: relativePath.replace(/\\/g, '/'), size: stat.size };
+        }));
+        for (const result of results) {
+            processed++;
+            if (result.status === 'fulfilled' && result.value !== null) {
+                entries.push(result.value);
+                onProgress?.(processed, filtered.length, result.value.path);
+            }
+            else {
+                onProgress?.(processed, filtered.length, batch[results.indexOf(result)]);
+            }
+        }
+    }
+    if (skippedLarge > 0) {
+        const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
+        const suffix = isDefault ? ', likely generated/vendored' : '';
+        console.warn(`  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
+        if (isVerboseIngestionEnabled()) {
+            for (const p of skippedLargePaths) {
+                console.warn(`  - ${p}`);
+            }
+        }
+    }
+    return entries;
+};
+/**
+ * Phase 2: Read file contents for a specific set of relative paths.
+ * Returns a Map for O(1) lookup. Silently skips files that fail to read.
+ */
+export const readFileContents = async (repoPath, relativePaths) => {
+    const contents = new Map();
+    for (let start = 0; start < relativePaths.length; start += READ_CONCURRENCY) {
+        const batch = relativePaths.slice(start, start + READ_CONCURRENCY);
+        const results = await Promise.allSettled(batch.map(async (relativePath) => {
+            const fullPath = path.join(repoPath, relativePath);
+            const content = await fs.readFile(fullPath, 'utf-8');
+            return { path: relativePath, content };
+        }));
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                contents.set(result.value.path, result.value.content);
+            }
+        }
+    }
+    return contents;
+};
+/**
+ * Legacy API — scans and reads everything into memory.
+ * Used by sequential fallback path only.
+ */
+export const walkRepository = async (repoPath, onProgress) => {
+    const scanned = await walkRepositoryPaths(repoPath, onProgress);
+    const contents = await readFileContents(repoPath, scanned.map((f) => f.path));
+    return scanned
+        .filter((f) => contents.has(f.path))
+        .map((f) => ({ path: f.path, content: contents.get(f.path) }));
+};

package/dist/core/ingestion/finalize-orchestrator.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `finalizeScopeModel` — turn a workspace's `ParsedFile[]` into a
+ * materialized `ScopeResolutionIndexes` (RFC §3.2 Phase 2; Ring 2 PKG #921).
+ *
+ * Thin integration glue, per issue #884's boundary: all algorithmic logic
+ * lives in `@codragraph/shared` (finalize algorithm #915, the four per-file
+ * indexes #913, the method-dispatch materialization #914, the scope tree
+ * #912). This file does three things only:
+ *
+ *   1. Map `ParsedFile[]` → `FinalizeInput` and call shared `finalize()`.
+ *   2. Build the four workspace-wide indexes from the union of per-file
+ *      defs/scopes/modules/qualified-names.
+ *   3. Bundle the results into `ScopeResolutionIndexes` for
+ *      `MutableSemanticModel.attachScopeIndexes(...)`.
+ *
+ * ## What this module is NOT responsible for
+ *
+ *   - Invoking tree-sitter or running AST walks. That's the extractor (#919).
+ *   - Per-language import-target resolution. Hooks are plumbed through
+ *     but default to "unresolved" when no provider supplies them — the
+ *     real adapters land with #922.
+ *   - Populating `ReferenceIndex`. That's the resolution phase (#925).
+ *   - Deciding which language uses registry-primary lookup. That's the
+ *     flag reader (#924).
+ *
+ * ## Empty-input behavior
+ *
+ * When `parsedFiles` is empty (the common case today — no language has
+ * migrated yet), the orchestrator produces a valid but empty bundle: all
+ * indexes are zero-sized, the scope tree is empty, and
+ * `finalize.stats.totalFiles === 0`. This lets downstream consumers
+ * safely consult `model.scopes` without branching on presence.
+ */
+import type { FinalizeHooks, ParsedFile, WorkspaceIndex } from '../../_shared/index.js';
+import type { ScopeResolutionIndexes } from './model/scope-resolution-indexes.js';
+/**
+ * Options forwarded to the orchestrator. All fields optional so callers
+ * that don't yet have per-language hooks (today) get sensible defaults;
+ * #922 will populate `hooks.resolveImportTarget` + friends per language.
+ */
+export interface FinalizeOrchestratorOptions {
+    /**
+     * Hooks forwarded to shared `finalize()`. Any omitted field gets a
+     * no-op default: unresolved targets, empty wildcard expansion, append
+     * merge for bindings.
+     */
+    readonly hooks?: Partial<FinalizeHooks>;
+    /**
+     * Opaque workspace context forwarded to hooks. `undefined` today; Ring
+     * 2 PKG #922 populates this with a real cross-file index for the
+     * per-language resolvers.
+     */
+    readonly workspaceIndex?: WorkspaceIndex;
+}
+/**
+ * Produce a fully materialized `ScopeResolutionIndexes` from the
+ * workspace's per-file artifacts.
+ *
+ * Pure function (given pure hooks). No I/O, no globals consulted. The
+ * pipeline calls this once per ingestion run and hands the result to
+ * `MutableSemanticModel.attachScopeIndexes`.
+ */
+export declare function finalizeScopeModel(parsedFiles: readonly ParsedFile[], options?: FinalizeOrchestratorOptions): ScopeResolutionIndexes;

package/dist/core/ingestion/finalize-orchestrator.js

@@ -0,0 +1,139 @@
+/**
+ * `finalizeScopeModel` — turn a workspace's `ParsedFile[]` into a
+ * materialized `ScopeResolutionIndexes` (RFC §3.2 Phase 2; Ring 2 PKG #921).
+ *
+ * Thin integration glue, per issue #884's boundary: all algorithmic logic
+ * lives in `@codragraph/shared` (finalize algorithm #915, the four per-file
+ * indexes #913, the method-dispatch materialization #914, the scope tree
+ * #912). This file does three things only:
+ *
+ *   1. Map `ParsedFile[]` → `FinalizeInput` and call shared `finalize()`.
+ *   2. Build the four workspace-wide indexes from the union of per-file
+ *      defs/scopes/modules/qualified-names.
+ *   3. Bundle the results into `ScopeResolutionIndexes` for
+ *      `MutableSemanticModel.attachScopeIndexes(...)`.
+ *
+ * ## What this module is NOT responsible for
+ *
+ *   - Invoking tree-sitter or running AST walks. That's the extractor (#919).
+ *   - Per-language import-target resolution. Hooks are plumbed through
+ *     but default to "unresolved" when no provider supplies them — the
+ *     real adapters land with #922.
+ *   - Populating `ReferenceIndex`. That's the resolution phase (#925).
+ *   - Deciding which language uses registry-primary lookup. That's the
+ *     flag reader (#924).
+ *
+ * ## Empty-input behavior
+ *
+ * When `parsedFiles` is empty (the common case today — no language has
+ * migrated yet), the orchestrator produces a valid but empty bundle: all
+ * indexes are zero-sized, the scope tree is empty, and
+ * `finalize.stats.totalFiles === 0`. This lets downstream consumers
+ * safely consult `model.scopes` without branching on presence.
+ */
+import { buildDefIndex, buildMethodDispatchIndex, buildModuleScopeIndex, buildQualifiedNameIndex, buildScopeTree, finalize, } from '../../_shared/index.js';
+/**
+ * Produce a fully materialized `ScopeResolutionIndexes` from the
+ * workspace's per-file artifacts.
+ *
+ * Pure function (given pure hooks). No I/O, no globals consulted. The
+ * pipeline calls this once per ingestion run and hands the result to
+ * `MutableSemanticModel.attachScopeIndexes`.
+ */
+export function finalizeScopeModel(parsedFiles, options = {}) {
+    const hooks = withDefaultHooks(options.hooks ?? {});
+    const workspaceIndex = options.workspaceIndex ?? undefined;
+    // ── Step 1: Shared finalize — runs SCC-aware cross-file link + binding
+    // materialization. Returns linked imports + merged bindings per module
+    // scope + SCC condensation + stats.
+    const finalizeInput = {
+        files: parsedFiles.map(toFinalizeFile),
+        workspaceIndex,
+    };
+    const finalizeOut = finalize(finalizeInput, hooks);
+    // ── Step 2: Workspace-wide indexes built from the per-file unions.
+    // These are pure aggregations — no algorithm beyond what the builders
+    // in codragraph-shared already encapsulate (first-write-wins, qname
+    // collision buckets, etc.).
+    const allScopes = [];
+    const allDefs = [];
+    const moduleEntries = [];
+    const allReferenceSites = [];
+    for (const file of parsedFiles) {
+        for (const s of file.scopes)
+            allScopes.push(s);
+        for (const d of file.localDefs)
+            allDefs.push(d);
+        moduleEntries.push({ filePath: file.filePath, moduleScopeId: file.moduleScope });
+    }
+    // References kept out of the loop above to centralize list-init.
+    allReferenceSites.push(...collectReferenceSites(parsedFiles));
+    const scopeTree = buildScopeTree(allScopes);
+    const defs = buildDefIndex(allDefs);
+    const qualifiedNames = buildQualifiedNameIndex(allDefs);
+    const moduleScopes = buildModuleScopeIndex(moduleEntries);
+    // ── Step 3: MethodDispatchIndex. Today we lack per-language MRO
+    // strategies wired into this orchestrator (that belongs with the
+    // HeritageMap bridge, a separate piece of work). Ship an EMPTY index
+    // so the bundle shape is consistent; the callbacks return `[]` for
+    // every owner and `implementsOf` returns `[]`. Populating this
+    // properly is tracked alongside the per-language provider hooks.
+    const methodDispatch = buildMethodDispatchIndex({
+        owners: [], // empty → no MRO entries; `mroFor(x)` returns the frozen empty array
+        computeMro: () => [],
+        implementsOf: () => [],
+    });
+    return {
+        scopeTree,
+        defs,
+        qualifiedNames,
+        moduleScopes,
+        methodDispatch,
+        imports: finalizeOut.imports,
+        bindings: finalizeOut.bindings,
+        referenceSites: Object.freeze([...allReferenceSites]),
+        sccs: finalizeOut.sccs,
+        stats: finalizeOut.stats,
+    };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/** Shape-reduce a `ParsedFile` to the narrower `FinalizeFile` the shared
+ *  algorithm reads. The subset is stable — `FinalizeFile` is a proper
+ *  subset of `ParsedFile`. */
+function toFinalizeFile(file) {
+    return {
+        filePath: file.filePath,
+        moduleScope: file.moduleScope,
+        parsedImports: file.parsedImports,
+        localDefs: file.localDefs,
+    };
+}
+/** Flatten every file's reference sites into one list. Order reflects
+ *  input-file order, then capture order inside each file. Deterministic. */
+function collectReferenceSites(parsedFiles) {
+    const out = [];
+    for (const file of parsedFiles) {
+        for (const site of file.referenceSites)
+            out.push(site);
+    }
+    return out;
+}
+/**
+ * Fill in no-op defaults for any omitted hook. Keeps `finalize()`
+ * behavior well-defined for the zero-provider case today:
+ *
+ *   - `resolveImportTarget: () => null` — every import edge ends up
+ *     `linkStatus: 'unresolved'` (or dynamic-unresolved pass-through).
+ *   - `expandsWildcardTo: () => []` — wildcards don't materialize.
+ *   - `mergeBindings: (existing, incoming) => [...existing, ...incoming]`
+ *     — append without precedence; providers override to implement local-
+ *     shadows-import and similar rules.
+ */
+function withDefaultHooks(partial) {
+    return {
+        resolveImportTarget: partial.resolveImportTarget ?? (() => null),
+        expandsWildcardTo: partial.expandsWildcardTo ?? (() => []),
+        mergeBindings: partial.mergeBindings ??
+            ((existing, incoming) => [...existing, ...incoming]),
+    };
+}