arceus-s 1.6.4

package/dist/core/ingestion/scope-resolution/pipeline/phase.js

@@ -0,0 +1,152 @@
+/**
+ * Phase: scopeResolution
+ *
+ * Generic registry-primary resolution phase (RFC #909 Ring 3).
+ *
+ * For every language in `MIGRATED_LANGUAGES` (per-language flag set)
+ * whose provider is registered in `SCOPE_RESOLVERS`:
+ *   1. Filter scanned files by language extension.
+ *   2. Read file contents.
+ *   3. Drive the scope-based pipeline end-to-end via the generic
+ *      `runScopeResolution(input, provider)` orchestrator.
+ *   4. Emit IMPORTS / CALLS / ACCESSES / INHERITS / USES edges.
+ *
+ * Pairs with the per-language gates in `import-processor.ts` and
+ * `call-processor.ts` that skip files when their language is registry-
+ * primary, so we don't double-emit edges from both code paths.
+ *
+ * Adding a language is two changes:
+ *   - Implement `ScopeResolver` in `languages/<lang>/scope-resolver.ts`
+ *     and register it in `scope-resolution/pipeline/registry.ts`.
+ *   - Add the language to `MIGRATED_LANGUAGES` in
+ *     `registry-primary-flag.ts`.
+ *
+ * @deps    parse  (needs Symbol nodes already in the graph so emit-references
+ *                  can attach edges to existing Function/Method/Class nodes)
+ * @reads   scannedFiles
+ * @writes  graph (IMPORTS, CALLS, ACCESSES, INHERITS, USES)
+ */
+import { getPhaseOutput } from '../../pipeline-phases/types.js';
+import { isRegistryPrimary } from '../../registry-primary-flag.js';
+import { getLanguageFromFilename } from '../../../../_shared/index.js';
+import { readFileContents } from '../../filesystem-walker.js';
+import { runScopeResolution } from './run.js';
+import { SCOPE_RESOLVERS } from './registry.js';
+import { isDev, isSemanticModelValidatorEnabled } from '../../utils/env.js';
+import { logger } from '../../../logger.js';
+const NOOP_OUTPUT = Object.freeze({
+    ran: false,
+    filesProcessed: 0,
+    importsEmitted: 0,
+    referenceEdgesEmitted: 0,
+    perLanguage: new Map(),
+});
+export const scopeResolutionPhase = {
+    name: 'scopeResolution',
+    // Depends on `parse` because emit-references attaches edges to
+    // already-existing Symbol nodes (Function/Method/Class). The legacy
+    // `parse` phase still creates those nodes; we only replace the
+    // import + call resolution layer.
+    //
+    // Also depends on `crossFile` — we don't read crossFile's output
+    // directly (we have our own cross-file resolution), but crossFile
+    // writes EXTENDS edges that `buildMro` consumes via
+    // `iterRelationshipsByType('EXTENDS')`. Declaring the dep pins the
+    // ordering explicitly: without it, Kahn's runner could schedule
+    // scopeResolution before crossFile (both unblock after parse), and
+    // the MRO walk would miss heritage edges crossFile later adds.
+    deps: ['parse', 'crossFile', 'structure'],
+    async execute(ctx, deps) {
+        const { scannedFiles } = getPhaseOutput(deps, 'structure');
+        // Reach into the parse phase's AST cache so per-file extract can
+        // skip a second tree-sitter parse. Cache miss is safe (re-parses).
+        // Worker-mode parses leave the cache empty for those files; they
+        // also fall back to a fresh parse — no correctness impact.
+        const parseOutput = getPhaseOutput(deps, 'parse');
+        const { scopeTreeCache, resolutionContext, parsedFiles: workerParsedFiles } = parseOutput;
+        // SemanticModel populated during `parse`: scope-resolution consumes
+        // TypeRegistry / MethodRegistry / SymbolTable lookups instead of
+        // rebuilding parallel indexes. See ARCHITECTURE.md § "Semantic-model
+        // source of truth".
+        const model = resolutionContext.model;
+        // Build a per-file lookup of ParsedFile artifacts the workers (or
+        // sequential extracts) already produced. Threading this into
+        // `runScopeResolution` lets the per-language extract loop short-
+        // circuit `extractParsedFile` — the dominant cost on the warm-cache
+        // path, since workers can't return tree-sitter Trees across the
+        // MessageChannel and scope-resolution would otherwise re-parse
+        // every file from scratch on the main thread.
+        const preExtractedByPath = new Map();
+        for (const pf of workerParsedFiles) {
+            preExtractedByPath.set(pf.filePath, pf);
+        }
+        let totalFiles = 0;
+        let totalImports = 0;
+        let totalRefs = 0;
+        let anyRan = false;
+        const perLanguage = new Map();
+        for (const [lang, provider] of SCOPE_RESOLVERS) {
+            if (!isRegistryPrimary(lang))
+                continue;
+            const langFiles = scannedFiles.filter((f) => getLanguageFromFilename(f.path) === lang);
+            if (langFiles.length === 0)
+                continue;
+            const filePaths = langFiles.map((f) => f.path);
+            const contents = await readFileContents(ctx.repoPath, filePaths);
+            const files = [];
+            for (const fp of filePaths) {
+                const content = contents.get(fp);
+                if (content !== undefined)
+                    files.push({ path: fp, content });
+            }
+            // Load per-language import-resolution config (tsconfig paths,
+            // composer.json autoload, go.mod, ...). One I/O round trip per
+            // workspace pass — cached implicitly by the result handed to
+            // every `resolveImportTarget` call below.
+            const resolutionConfig = provider.loadResolutionConfig !== undefined
+                ? await provider.loadResolutionConfig(ctx.repoPath)
+                : undefined;
+            const stats = runScopeResolution({
+                graph: ctx.graph,
+                model,
+                files,
+                treeCache: scopeTreeCache,
+                resolutionConfig,
+                preExtractedParsedFiles: preExtractedByPath,
+                onWarn: (msg) => {
+                    if (isSemanticModelValidatorEnabled()) {
+                        logger.warn(`[scope-resolution:${lang}] ${msg}`);
+                    }
+                },
+            }, provider);
+            anyRan = true;
+            totalFiles += stats.filesProcessed;
+            totalImports += stats.importsEmitted;
+            totalRefs += stats.referenceEdgesEmitted;
+            perLanguage.set(lang, {
+                filesProcessed: stats.filesProcessed,
+                importsEmitted: stats.importsEmitted,
+                referenceEdgesEmitted: stats.referenceEdgesEmitted,
+            });
+            if (isDev) {
+                logger.info(`[scope-resolution:${lang}] ${stats.filesProcessed} files → ${stats.importsEmitted} IMPORTS + ${stats.referenceEdgesEmitted} reference edges (${stats.resolve.unresolved} unresolved sites, ${stats.referenceSkipped} skipped)`);
+            }
+        }
+        // Dispose the cross-phase Tree cache — scope-resolution is the
+        // only consumer. Holding Trees past this point is pure memory
+        // pressure: downstream phases (mro, community, csv-generator)
+        // never read them, and tree-sitter Trees hold native-heap memory
+        // under WASM runtimes. ASTCache.clear() fires the LRU dispose
+        // handler which calls tree.delete?.() on each retained Tree.
+        scopeTreeCache.clear();
+        if (!anyRan)
+            return NOOP_OUTPUT;
+        return {
+            ran: true,
+            filesProcessed: totalFiles,
+            importsEmitted: totalImports,
+            referenceEdgesEmitted: totalRefs,
+            perLanguage,
+        };
+    },
+};

package/dist/core/ingestion/scope-resolution/pipeline/reconcile-ownership.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Reconcile scope-resolution's ownership view into the SemanticModel.
+ *
+ * For migrated languages (Python in particular) the legacy `parse` phase
+ * emits class-body callables without `ownerId` because
+ * `parsing-processor`'s `resolveEnclosingOwner` is language-dependent and
+ * not every extractor carries the enclosing-class info at parse time.
+ * Scope-resolution later calls `provider.populateOwners(parsed)`, which
+ * stamps the correct `ownerId` onto `parsed.localDefs[i]`. This pass
+ * mirrors those corrections into `model.methods` and `model.fields` so
+ * downstream passes can consult `SemanticModel` as the single
+ * authoritative owner-keyed index — no parallel scope-resolution
+ * registry is needed.
+ *
+ * ## Single-source-of-truth invariant (I9)
+ *
+ * After this pass runs, every `def in parsed.localDefs` with a non-
+ * undefined `ownerId` is reachable via either:
+ *   - `model.methods.lookupAllByOwner(ownerId, simpleName)` — if the
+ *     def is a Method / Function / Constructor, OR
+ *   - `model.fields.lookupFieldByOwner(ownerId, simpleName)` — if the
+ *     def is a Property / Variable.
+ *
+ * This invariant is the foundation of Contract Invariant I9
+ * (`contract/scope-resolver.ts`): scope-resolution passes MUST read
+ * symbol-keyed lookups exclusively from `SemanticModel`.
+ *
+ * ## Idempotency
+ *
+ * The pass skips registration when `(ownerId, simpleName)` already
+ * contains a def with matching `nodeId`. Safe to call multiple times
+ * or after a language whose legacy extractor does populate `ownerId`
+ * (C#) — no duplicates are introduced.
+ *
+ * ## Transitional shim
+ *
+ * This reconciliation pass is an explicit shim. The architectural end
+ * state is for the legacy extractor to emit the correct `ownerId` for
+ * every language at parse time, removing the need for a second pass.
+ * See ARCHITECTURE.md § "Semantic-model source of truth" for the
+ * follow-up plan.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { MutableSemanticModel, SemanticModel } from '../../model/semantic-model.js';
+export interface ReconcileStats {
+    /** Method/Function/Constructor defs registered into MethodRegistry. */
+    readonly methodsRegistered: number;
+    /** Property/Variable defs registered into FieldRegistry. */
+    readonly fieldsRegistered: number;
+    /** Defs already present (idempotent skip). */
+    readonly skippedAlreadyPresent: number;
+}
+export declare function reconcileOwnership(parsedFiles: readonly ParsedFile[], model: MutableSemanticModel): ReconcileStats;
+/**
+ * Debug-mode parity validator. Runs only when
+ * `VALIDATE_SEMANTIC_MODEL !== '0'` AND `NODE_ENV !== 'production'`.
+ *
+ * Iterates every def in `parsedFiles[i].localDefs` with an `ownerId`
+ * and asserts it is reachable via `model.methods.lookupAllByOwner` or
+ * `model.fields.lookupFieldByOwner`. On mismatch: emits a warning via
+ * `onWarn` — never throws, mirroring the pipeline's soft-fail posture.
+ *
+ * This is the enforcement of Contract Invariant I9 at runtime. In
+ * production it is a no-op; in development it surfaces drift between
+ * `parsed.localDefs` and `SemanticModel` that would otherwise silently
+ * produce wrong edges.
+ */
+export declare function validateOwnershipParity(parsedFiles: readonly ParsedFile[], model: SemanticModel, onWarn: (message: string) => void): number;

package/dist/core/ingestion/scope-resolution/pipeline/reconcile-ownership.js

@@ -0,0 +1,125 @@
+/**
+ * Reconcile scope-resolution's ownership view into the SemanticModel.
+ *
+ * For migrated languages (Python in particular) the legacy `parse` phase
+ * emits class-body callables without `ownerId` because
+ * `parsing-processor`'s `resolveEnclosingOwner` is language-dependent and
+ * not every extractor carries the enclosing-class info at parse time.
+ * Scope-resolution later calls `provider.populateOwners(parsed)`, which
+ * stamps the correct `ownerId` onto `parsed.localDefs[i]`. This pass
+ * mirrors those corrections into `model.methods` and `model.fields` so
+ * downstream passes can consult `SemanticModel` as the single
+ * authoritative owner-keyed index — no parallel scope-resolution
+ * registry is needed.
+ *
+ * ## Single-source-of-truth invariant (I9)
+ *
+ * After this pass runs, every `def in parsed.localDefs` with a non-
+ * undefined `ownerId` is reachable via either:
+ *   - `model.methods.lookupAllByOwner(ownerId, simpleName)` — if the
+ *     def is a Method / Function / Constructor, OR
+ *   - `model.fields.lookupFieldByOwner(ownerId, simpleName)` — if the
+ *     def is a Property / Variable.
+ *
+ * This invariant is the foundation of Contract Invariant I9
+ * (`contract/scope-resolver.ts`): scope-resolution passes MUST read
+ * symbol-keyed lookups exclusively from `SemanticModel`.
+ *
+ * ## Idempotency
+ *
+ * The pass skips registration when `(ownerId, simpleName)` already
+ * contains a def with matching `nodeId`. Safe to call multiple times
+ * or after a language whose legacy extractor does populate `ownerId`
+ * (C#) — no duplicates are introduced.
+ *
+ * ## Transitional shim
+ *
+ * This reconciliation pass is an explicit shim. The architectural end
+ * state is for the legacy extractor to emit the correct `ownerId` for
+ * every language at parse time, removing the need for a second pass.
+ * See ARCHITECTURE.md § "Semantic-model source of truth" for the
+ * follow-up plan.
+ */
+import { simpleQualifiedName } from '../graph-bridge/ids.js';
+export function reconcileOwnership(parsedFiles, model) {
+    let methodsRegistered = 0;
+    let fieldsRegistered = 0;
+    let skippedAlreadyPresent = 0;
+    for (const parsed of parsedFiles) {
+        for (const def of parsed.localDefs) {
+            const ownerId = def.ownerId;
+            if (ownerId === undefined)
+                continue;
+            const simple = simpleQualifiedName(def);
+            if (simple === undefined)
+                continue;
+            if (def.type === 'Method' || def.type === 'Function' || def.type === 'Constructor') {
+                const existing = model.methods.lookupAllByOwner(ownerId, simple);
+                if (existing.some((e) => e.nodeId === def.nodeId)) {
+                    skippedAlreadyPresent++;
+                    continue;
+                }
+                model.methods.register(ownerId, simple, def);
+                methodsRegistered++;
+            }
+            else if (def.type === 'Property' || def.type === 'Variable') {
+                const existing = model.fields.lookupFieldByOwner(ownerId, simple);
+                if (existing !== undefined && existing.nodeId === def.nodeId) {
+                    skippedAlreadyPresent++;
+                    continue;
+                }
+                model.fields.register(ownerId, simple, def);
+                fieldsRegistered++;
+            }
+        }
+    }
+    return { methodsRegistered, fieldsRegistered, skippedAlreadyPresent };
+}
+/**
+ * Debug-mode parity validator. Runs only when
+ * `VALIDATE_SEMANTIC_MODEL !== '0'` AND `NODE_ENV !== 'production'`.
+ *
+ * Iterates every def in `parsedFiles[i].localDefs` with an `ownerId`
+ * and asserts it is reachable via `model.methods.lookupAllByOwner` or
+ * `model.fields.lookupFieldByOwner`. On mismatch: emits a warning via
+ * `onWarn` — never throws, mirroring the pipeline's soft-fail posture.
+ *
+ * This is the enforcement of Contract Invariant I9 at runtime. In
+ * production it is a no-op; in development it surfaces drift between
+ * `parsed.localDefs` and `SemanticModel` that would otherwise silently
+ * produce wrong edges.
+ */
+export function validateOwnershipParity(parsedFiles, model, onWarn) {
+    if (process.env.NODE_ENV === 'production')
+        return 0;
+    if (process.env.VALIDATE_SEMANTIC_MODEL === '0')
+        return 0;
+    let mismatches = 0;
+    for (const parsed of parsedFiles) {
+        for (const def of parsed.localDefs) {
+            const ownerId = def.ownerId;
+            if (ownerId === undefined)
+                continue;
+            const simple = simpleQualifiedName(def);
+            if (simple === undefined)
+                continue;
+            if (def.type === 'Method' || def.type === 'Function' || def.type === 'Constructor') {
+                const found = model.methods.lookupAllByOwner(ownerId, simple);
+                if (!found.some((d) => d.nodeId === def.nodeId)) {
+                    onWarn(`semantic-model parity: ${def.type} ${def.nodeId} (${parsed.filePath}) ` +
+                        `owned by ${ownerId} as "${simple}" not in MethodRegistry`);
+                    mismatches++;
+                }
+            }
+            else if (def.type === 'Property' || def.type === 'Variable') {
+                const found = model.fields.lookupFieldByOwner(ownerId, simple);
+                if (found === undefined || found.nodeId !== def.nodeId) {
+                    onWarn(`semantic-model parity: ${def.type} ${def.nodeId} (${parsed.filePath}) ` +
+                        `owned by ${ownerId} as "${simple}" not in FieldRegistry`);
+                    mismatches++;
+                }
+            }
+        }
+    }
+    return mismatches;
+}

package/dist/core/ingestion/scope-resolution/pipeline/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-language `ScopeResolver` registry — the lookup the generic
+ * `scopeResolutionPhase` uses to pick the right resolver for each
+ * migrated language.
+ *
+ * Adding a language is two lines: implement a `ScopeResolver` in
+ * `languages/<lang>/scope-resolver.ts` and register it here. The
+ * phase picks it up automatically — no workflow changes, no
+ * per-language pipeline phase file.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import type { ScopeResolver } from '../contract/scope-resolver.js';
+/** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates
+ *  this map intersected with `MIGRATED_LANGUAGES` (the per-language
+ *  flag set) so adding a resolver here without flipping the flag is
+ *  safe — the resolver sits idle until the language is migrated. */
+export declare const SCOPE_RESOLVERS: ReadonlyMap<SupportedLanguages, ScopeResolver>;

package/dist/core/ingestion/scope-resolution/pipeline/registry.js

@@ -0,0 +1,31 @@
+/**
+ * Per-language `ScopeResolver` registry — the lookup the generic
+ * `scopeResolutionPhase` uses to pick the right resolver for each
+ * migrated language.
+ *
+ * Adding a language is two lines: implement a `ScopeResolver` in
+ * `languages/<lang>/scope-resolver.ts` and register it here. The
+ * phase picks it up automatically — no workflow changes, no
+ * per-language pipeline phase file.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { pythonScopeResolver } from '../../languages/python/scope-resolver.js';
+import { csharpScopeResolver } from '../../languages/csharp/scope-resolver.js';
+import { typescriptScopeResolver } from '../../languages/typescript/scope-resolver.js';
+import { goScopeResolver } from '../../languages/go/scope-resolver.js';
+import { javaScopeResolver } from '../../languages/java/scope-resolver.js';
+import { cScopeResolver } from '../../languages/c/scope-resolver.js';
+import { phpScopeResolver } from '../../languages/php/scope-resolver.js';
+/** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates
+ *  this map intersected with `MIGRATED_LANGUAGES` (the per-language
+ *  flag set) so adding a resolver here without flipping the flag is
+ *  safe — the resolver sits idle until the language is migrated. */
+export const SCOPE_RESOLVERS = new Map([
+    [SupportedLanguages.Python, pythonScopeResolver],
+    [SupportedLanguages.CSharp, csharpScopeResolver],
+    [SupportedLanguages.TypeScript, typescriptScopeResolver],
+    [SupportedLanguages.Go, goScopeResolver],
+    [SupportedLanguages.Java, javaScopeResolver],
+    [SupportedLanguages.C, cScopeResolver],
+    [SupportedLanguages.PHP, phpScopeResolver],
+]);

package/dist/core/ingestion/scope-resolution/pipeline/run.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `runScopeResolution` — generic registry-primary resolution
+ * orchestrator.
+ *
+ *     ParsedFile[]  (one per file via `extractParsedFile`)
+ *        │  finalizeScopeModel(  + provider hooks adapted to FinalizeHooks)
+ *        ▼
+ *     ScopeResolutionIndexes
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReceiverBoundCalls (FIRST — see Contract Invariant I1)
+ *        │  emitFreeCallFallback   (THEN)
+ *        │  emitReferencesViaLookup (LAST — uses handledSites)
+ *        │  emitImportEdges
+ *        ▼
+ *     KnowledgeGraph
+ *
+ * Per-language entry points (e.g. `runPythonScopeResolution` in
+ * `languages/python/scope-resolver.ts`) construct an `ScopeResolver` and
+ * delegate here.
+ *
+ * Plan: `docs/plans/2026-04-20-001-refactor-emit-pipeline-generalization-plan.md`.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { MutableSemanticModel } from '../../model/semantic-model.js';
+import { type ResolveStats } from '../../resolve-references.js';
+import type { ScopeResolver } from '../contract/scope-resolver.js';
+interface RunScopeResolutionInput {
+    readonly graph: KnowledgeGraph;
+    /**
+     * Semantic model populated by the legacy `parse` phase. Scope-
+     * resolution consumes its `TypeRegistry` / `MethodRegistry` /
+     * `SymbolTable` lookups instead of rebuilding parallel indexes from
+     * `ParsedFile[]`. See ARCHITECTURE.md § "Semantic-model source of
+     * truth". Tests that invoke `runScopeResolution` in isolation pass a
+     * freshly-created `MutableSemanticModel` populated from the same
+     * `ParsedFile[]` to mirror the pipeline shape.
+     */
+    readonly model: MutableSemanticModel;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly onWarn?: (message: string) => void;
+    /**
+     * Optional pre-parsed-Tree lookup keyed by file path. When the
+     * pipeline's parse phase ran sequentially, it populated an
+     * `ASTCache`; passing that here lets the per-file extract step
+     * skip a second `tree-sitter parser.parse(...)` call. Cache miss
+     * is safe — falls back to a fresh parse inside the provider.
+     */
+    readonly treeCache?: {
+        get(filePath: string): unknown;
+    };
+    /**
+     * Opaque per-language import-resolution config (e.g. tsconfig path
+     * aliases for TypeScript). Loaded once by the caller via
+     * `provider.loadResolutionConfig(repoPath)` and threaded into every
+     * `provider.resolveImportTarget` call. `undefined` when the
+     * provider doesn't supply a config loader.
+     */
+    readonly resolutionConfig?: unknown;
+    /**
+     * Pre-extracted ParsedFile artifacts keyed by file path. When a
+     * file is present here, the extract loop reuses it directly and
+     * skips `extractParsedFile` (which would re-parse the file with
+     * tree-sitter on the main thread). Only files matching the
+     * provider's language are honored — the loop verifies this
+     * implicitly by language filter at the call-site (scopeResolution
+     * phase).
+     *
+     * Worker-mode parses produce these ParsedFile artifacts as a side
+     * effect of `extractParsedFile` running inside the worker; threading
+     * them here is what lets the warm-cache analyze run skip the ~58s
+     * scope-resolution re-parse loop on a multi-thousand-file repo.
+     * Cache miss is safe — falls back to fresh extract.
+     */
+    readonly preExtractedParsedFiles?: ReadonlyMap<string, ParsedFile>;
+}
+interface RunScopeResolutionStats {
+    readonly filesProcessed: number;
+    readonly filesSkipped: number;
+    readonly importsEmitted: number;
+    readonly resolve: ResolveStats;
+    readonly referenceEdgesEmitted: number;
+    readonly referenceSkipped: number;
+}
+export declare function runScopeResolution(input: RunScopeResolutionInput, provider: ScopeResolver): RunScopeResolutionStats;
+export {};