gitnexus 1.6.10-rc.99 → 1.6.10

package/dist/core/ingestion/language-config.d.ts

@@ -1,4 +1,3 @@
-import type { ImportConfigs } from './import-resolvers/types.js';
 /** TypeScript path alias config parsed from tsconfig.json */
 export interface TsconfigPaths {
     /** Map of alias prefix -> target prefix (e.g., "@/" -> "src/") */
@@ -15,10 +14,19 @@ export interface GoModuleConfig {
 export interface ComposerConfig {
     /** Map of namespace prefix -> directory (e.g., "App\\" -> "app/") */
     psr4: Map<string, string>;
+    /** Production `autoload.psr-4` prefixes that may gate external namespaces.
+     *  Absent on legacy/manual configs, where every mapping remains authoritative. */
+    authoritativePsr4?: ReadonlySet<string>;
+    /** True when Composer also declares an autoload mechanism this resolver does not model. */
+    hasUnmodeledAutoload?: boolean;
     /** PSR-4 entries sorted by namespace length descending (longest match wins).
      *  Cached once at config load time to avoid re-sorting on every import. */
     psr4Sorted?: readonly [string, string][];
 }
+/** Parse one Composer manifest without performing I/O. */
+export declare function parseComposerConfig(value: unknown, baseDir?: string): ComposerConfig | null;
+/** Merge package-local Composer manifests into one repository-relative config. */
+export declare function mergeComposerConfigs(configs: readonly ComposerConfig[]): ComposerConfig | null;
 /** C# project config parsed from .csproj files */
 export interface CSharpProjectConfig {
     /** Root namespace from <RootNamespace> or assembly name (default: project directory name) */
@@ -85,5 +93,25 @@ export declare function loadComposerConfig(repoRoot: string): Promise<ComposerCo
  */
 export declare function scanCSharpProject(repoRoot: string): Promise<CSharpProjectScan>;
 export declare function loadSwiftPackageConfig(repoRoot: string): Promise<SwiftPackageConfig | null>;
+/**
+ * Bundled language-specific configs loaded once per ingestion run — the
+ * result of {@link loadImportConfigs}, and every field's type is declared
+ * above in this module.
+ *
+ * It lives here rather than in `import-resolvers/types.ts` (its consumer, via
+ * `ResolveCtx`) so the dependency runs one way: the import-resolver types
+ * import this bundle, and this module imports nothing from them. Homing the
+ * producer's result type with the producer also keeps `import-resolvers/
+ * types.ts` free of per-language names.
+ */
+export interface ImportConfigs {
+    tsconfigPaths: TsconfigPaths | null;
+    goModule: GoModuleConfig | null;
+    composerConfig: ComposerConfig | null;
+    swiftPackageConfig: SwiftPackageConfig | null;
+    csharpConfigs: CSharpProjectConfig[];
+    /** In-repo namespace evidence gating C# suffix-fallback resolution (#1881). */
+    csharpNamespaces?: CSharpNamespaceEvidence;
+}
 /** Load all language-specific configs once for an ingestion run. */
 export declare function loadImportConfigs(repoRoot: string): Promise<ImportConfigs>;

package/dist/core/ingestion/language-config.js

@@ -3,7 +3,95 @@ import { createReadStream } from 'fs';
 import { createInterface } from 'readline';
 import path from 'path';
 import { isDev } from './utils/env.js';
+import { mapConcurrent } from '../../lib/utils.js';
 import { logger } from '../logger.js';
+function normalizeComposerDirectory(baseDir, directory) {
+    const normalizedBase = baseDir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+    const normalizedDirectory = directory
+        .replace(/\\/g, '/')
+        .replace(/^(?:\.\/)+/, '')
+        .replace(/\/+$/, '');
+    if (normalizedBase === '')
+        return normalizedDirectory;
+    if (normalizedDirectory === '')
+        return normalizedBase;
+    return path.posix.normalize(`${normalizedBase}/${normalizedDirectory}`);
+}
+/** Parse one Composer manifest without performing I/O. */
+export function parseComposerConfig(value, baseDir = '') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const composer = value;
+    const autoload = composer.autoload;
+    const autoloadDev = composer['autoload-dev'];
+    if (autoload === undefined && autoloadDev === undefined)
+        return null;
+    const psr4 = new Map();
+    const authoritativePsr4 = new Set();
+    let hasUnmodeledAutoload = false;
+    const addSection = (sectionValue, authoritative) => {
+        if (typeof sectionValue !== 'object' || sectionValue === null || Array.isArray(sectionValue)) {
+            return;
+        }
+        const section = sectionValue;
+        if ('psr-0' in section || 'classmap' in section)
+            hasUnmodeledAutoload = true;
+        const rawPsr4 = section['psr-4'];
+        if (typeof rawPsr4 !== 'object' || rawPsr4 === null || Array.isArray(rawPsr4))
+            return;
+        for (const [namespace, directories] of Object.entries(rawPsr4)) {
+            const stringDirectories = Array.isArray(directories)
+                ? directories.filter((entry) => typeof entry === 'string')
+                : typeof directories === 'string'
+                    ? [directories]
+                    : [];
+            if (stringDirectories.length === 0)
+                continue;
+            if (stringDirectories.length > 1)
+                hasUnmodeledAutoload = true;
+            const normalizedNamespace = namespace.replace(/\\+$/, '');
+            const normalizedDirectory = normalizeComposerDirectory(baseDir, stringDirectories[0]);
+            const existing = psr4.get(normalizedNamespace);
+            if (existing !== undefined && existing !== normalizedDirectory) {
+                hasUnmodeledAutoload = true;
+                continue;
+            }
+            if (existing === undefined)
+                psr4.set(normalizedNamespace, normalizedDirectory);
+            if (authoritative)
+                authoritativePsr4.add(normalizedNamespace);
+        }
+    };
+    // Production mappings win duplicate prefixes. Development mappings remain
+    // usable for test code but do not establish authority for the external gate.
+    addSection(autoload, true);
+    addSection(autoloadDev, false);
+    return { psr4, authoritativePsr4, hasUnmodeledAutoload };
+}
+/** Merge package-local Composer manifests into one repository-relative config. */
+export function mergeComposerConfigs(configs) {
+    if (configs.length === 0)
+        return null;
+    const psr4 = new Map();
+    const authoritativePsr4 = new Set();
+    let hasUnmodeledAutoload = false;
+    for (const config of configs) {
+        hasUnmodeledAutoload ||= config.hasUnmodeledAutoload === true;
+        for (const [namespace, directory] of config.psr4) {
+            const existing = psr4.get(namespace);
+            if (existing !== undefined && existing !== directory) {
+                hasUnmodeledAutoload = true;
+                continue;
+            }
+            if (existing === undefined)
+                psr4.set(namespace, directory);
+        }
+        for (const namespace of config.authoritativePsr4 ?? config.psr4.keys()) {
+            authoritativePsr4.add(namespace);
+        }
+    }
+    return { psr4, authoritativePsr4, hasUnmodeledAutoload };
+}
 /** Project the one-pass {@link CSharpProjectScan} into the
  *  {@link CSharpNamespaceEvidence} both import-resolution legs thread to the
  *  #1881 gate — one shape, two carriers (`ImportConfigs.csharpNamespaces` for
@@ -84,20 +172,13 @@ export async function loadComposerConfig(repoRoot) {
     try {
         const composerPath = path.join(repoRoot, 'composer.json');
         const raw = await fs.readFile(composerPath, 'utf-8');
-        const composer = JSON.parse(raw);
-        const psr4Raw = composer.autoload?.['psr-4'] ?? {};
-        const psr4Dev = composer['autoload-dev']?.['psr-4'] ?? {};
-        const merged = { ...psr4Raw, ...psr4Dev };
-        const psr4 = new Map();
-        for (const [ns, dir] of Object.entries(merged)) {
-            const nsNorm = ns.replace(/\\+$/, '');
-            const dirNorm = dir.replace(/\\/g, '/').replace(/\/+$/, '');
-            psr4.set(nsNorm, dirNorm);
-        }
+        const config = parseComposerConfig(JSON.parse(raw));
+        if (config === null)
+            return null;
         if (isDev) {
-            logger.info(`📦 Loaded ${psr4.size} PSR-4 mappings from composer.json`);
+            logger.info(`📦 Loaded ${config.psr4.size} PSR-4 mappings from composer.json`);
         }
-        return { psr4 };
+        return config;
     }
     catch {
         return null;
@@ -197,28 +278,25 @@ export async function scanCSharpProject(repoRoot) {
                 csNames.push(entry.name);
             }
         }
-        for (let i = 0; i < csprojNames.length; i += CSHARP_SCAN_READ_CONCURRENCY) {
-            const batch = csprojNames.slice(i, i + CSHARP_SCAN_READ_CONCURRENCY);
-            const settled = await Promise.allSettled(batch.map((name) => readCsprojConfig(path.join(dir, name), name, repoRoot, dir)));
-            for (const r of settled) {
-                const config = r.status === 'fulfilled' ? r.value : null;
-                if (config) {
-                    configs.push(config);
-                    rootNamespaces.add(config.rootNamespace);
-                }
+        // `mapConcurrent` runs the same bounded waves and degrades per item
+        // (a rejection becomes `undefined`), so entry order is still preserved.
+        const csprojResults = await mapConcurrent(csprojNames, (name) => readCsprojConfig(path.join(dir, name), name, repoRoot, dir), { concurrency: CSHARP_SCAN_READ_CONCURRENCY });
+        for (const config of csprojResults) {
+            if (config) {
+                configs.push(config);
+                rootNamespaces.add(config.rootNamespace);
             }
         }
-        for (let i = 0; i < csNames.length; i += CSHARP_SCAN_READ_CONCURRENCY) {
-            const batch = csNames.slice(i, i + CSHARP_SCAN_READ_CONCURRENCY);
-            const settled = await Promise.allSettled(batch.map((name) => collectDeclaredNamespaces(path.join(dir, name), declaredNamespaces, rootNamespaces)));
-            // A `.cs` that was unreadable (or whose read/scan unexpectedly rejected)
-            // leaves its namespaces uncollected → mark truncated to fail the #1881
-            // gate OPEN rather than wrongly suppress an import. The scan streams each
-            // file, so file size no longer trips truncation.
-            for (const r of settled) {
-                if (r.status !== 'fulfilled' || r.value === 'truncated')
-                    truncated = true;
-            }
+        const csResults = await mapConcurrent(csNames, (name) => collectDeclaredNamespaces(path.join(dir, name), declaredNamespaces, rootNamespaces), { concurrency: CSHARP_SCAN_READ_CONCURRENCY });
+        // A `.cs` that was unreadable (or whose read/scan unexpectedly rejected)
+        // leaves its namespaces uncollected → mark truncated to fail the #1881
+        // gate OPEN rather than wrongly suppress an import. The scan streams each
+        // file, so file size no longer trips truncation. A rejected read arrives
+        // here as `undefined`, which is `!== 'ok'` just like the old
+        // `r.status !== 'fulfilled'` arm.
+        for (const r of csResults) {
+            if (r !== 'ok')
+                truncated = true;
         }
     }
     if (truncated) {
@@ -362,9 +440,6 @@ export async function loadSwiftPackageConfig(repoRoot) {
     }
     return null;
 }
-// ============================================================================
-// BUNDLED CONFIG LOADER
-// ============================================================================
 /** Load all language-specific configs once for an ingestion run. */
 export async function loadImportConfigs(repoRoot) {
     const csharpScan = await scanCSharpProject(repoRoot);

package/dist/core/ingestion/language-provider.d.ts

@@ -23,10 +23,25 @@ import type { CfgVisitor } from './cfg/types.js';
 import type { NodeLabel } from '../../_shared/index.js';
 import type { ExtractedRoute } from './route-extractors/laravel.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
+import type { ModuleConstants, Operand, RepoConstants } from './route-extractors/constant-resolver.js';
 import type Parser from 'tree-sitter';
 import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
 /** Tree-sitter query captures: capture name → AST node (or undefined if not captured). */
 export type CaptureMap = Record<string, SyntaxNode | undefined>;
+export interface DefinitionPropertiesContext {
+    readonly nodeLabel: NodeLabel;
+    readonly nodeName: string;
+    readonly definitionNode: SyntaxNode;
+    readonly parsedImports: readonly ParsedImport[];
+    readonly isExported: boolean;
+}
+export type DefinitionPropertiesExtractor = (context: DefinitionPropertiesContext) => Readonly<Record<string, unknown>> | undefined;
+/** Run optional provider enrichment without allowing one hook failure to drop
+ * the rest of the worker's language batch. */
+export declare function runDefinitionPropertiesExtractor(extractor: DefinitionPropertiesExtractor, context: DefinitionPropertiesContext, onError: (error: unknown) => void): Readonly<Record<string, unknown>> | undefined;
+/** Provider metadata is additive; graph identity and source-location fields
+ * supplied by the worker remain authoritative. */
+export declare function mergeCanonicalDefinitionProperties<TCanonical extends Readonly<Record<string, unknown>>>(providerProperties: Readonly<Record<string, unknown>>, canonicalProperties: TCanonical): Record<string, unknown> & TCanonical;
 /** Configuration for AST-based framework detection patterns. */
 export interface AstFrameworkPatternConfig {
     framework: string;
@@ -39,6 +54,18 @@ export interface AstFrameworkPatternConfig {
  * Required fields must be explicitly set; optional fields have defaults
  * applied by defineLanguage().
  */
+/**
+ * Should the parse worker run {@link LanguageProviderConfig.extractModuleConstants}
+ * on this file?
+ *
+ * Exported so the DECISION is testable without booting a worker. It encodes the
+ * one rule that is easy to get backwards: a provider that declares no
+ * `moduleConstantHeuristic` harvests unconditionally. Writing the gate as
+ * `provider.moduleConstantHeuristic?.(content)` reads `undefined` as "skip" and
+ * silently disables the hook for every provider without a heuristic — which is
+ * exactly how Python's already-shipped harvest was turned off (#2391/#2980).
+ */
+export declare function shouldHarvestModuleConstants(provider: Pick<LanguageProvider, 'extractModuleConstants' | 'moduleConstantHeuristic'>, content: string): boolean;
 interface LanguageProviderConfig {
     readonly id: SupportedLanguages;
     /** File extensions that map to this language (e.g., ['.ts', '.tsx']) */
@@ -83,9 +110,17 @@ interface LanguageProviderConfig {
      * The current C++ UE-macro preprocessor relies on the practical fact that
      * UE reflection macros and module-export tokens are ASCII-only.
      *
-     * Must be a pure function — same input always yields the same output. Called
-     * once per file, on every code path that re-parses (parsing-processor, import
-     * processor, heritage processor, call processor, parse worker).
+     * Must be a pure function — same input always yields the same output, and
+     * re-applying it to its own output changes nothing.
+     *
+     * Applied by the parse worker (`parse-worker.ts`), by `extractParsedFile`
+     * (`scope-extractor-bridge.ts`) on the parse-cache-miss path, and by the
+     * embedding parse (`embeddings/ast-utils.ts`, which does not go through the
+     * bridge). Any *new* path that re-parses a file must apply it too, or the two
+     * halves of the pipeline analyze different programs — and note the set is not
+     * closed today: language-owned re-parse helpers reached through other
+     * provider hooks (e.g. `populateRangeBindings`) still see raw text.
+     * `test/unit/preprocess-source-parity.test.ts` pins the bridge equivalence.
      *
      * Default: undefined (no preprocessing — `file.content` is parsed verbatim).
      */
@@ -163,6 +198,16 @@ interface LanguageProviderConfig {
      *  (e.g., 'Method' for Kotlin), or defaultLabel to keep as-is.
      *  Default: undefined (standard label assignment). */
     readonly labelOverride?: (functionNode: SyntaxNode, defaultLabel: NodeLabel) => NodeLabel | null;
+    /**
+     * Suppress a definition query match after its default label is known.
+     * Languages use this for syntax that represents an implicit declaration
+     * unless an explicit declaration with the same semantics is present.
+     *
+     * `defaultLabel` is supplied so an implementation can scope itself to one
+     * kind of definition; implementations whose capture map alone decides the
+     * question may ignore it.
+     */
+    readonly shouldSkipDefinitionCapture?: (captureMap: CaptureMap, defaultLabel: NodeLabel) => boolean;
     /** MRO strategy for multiple inheritance resolution.
      *  Default: 'first-wins'. */
     readonly mroStrategy?: MroStrategy;
@@ -184,6 +229,10 @@ interface LanguageProviderConfig {
      *  constant, and static declarations. Produces VariableInfo with type, visibility,
      *  isConst, isStatic, isMutable metadata. Default: undefined (no variable extraction). */
     readonly variableExtractor?: VariableExtractor;
+    /** Add language-owned, structured properties to a definition node. Values
+     *  cross the worker boundary and must therefore be structured-clone-safe.
+     *  Shared ingestion code treats these properties as opaque. */
+    readonly definitionPropertiesExtractor?: DefinitionPropertiesExtractor;
     /** Class/type extractor for deriving canonical qualified names for class-like symbols.
      *  Uses the same provider-driven strategy pattern as method/field extraction so
      *  namespace/package/module rules stay language-specific. */
@@ -217,14 +266,22 @@ interface LanguageProviderConfig {
      *  Default: undefined (no route extraction). */
     readonly extractRoutes?: (tree: Parser.Tree, filePath: string, reader: (relativePath: string) => string | null, parser?: Parser | null) => ExtractedRoute[];
     /**
-     * Extract decorator-style route annotations from a parsed file.
+     * Extract routes that a parsed file declares in its own AST.
      *
      * When defined, the parse worker calls this after per-file capture processing
-     * to extract framework route definitions that require AST-level analysis beyond
+     * to extract route definitions that require AST-level analysis beyond
      * generic `@decorator` captures (e.g., Java Spring class-level prefix joining,
      * multi-class handling). The returned routes are appended to `decoratorRoutes`.
      *
-     * Default: undefined (no language-specific decorator route extraction).
+     * Decorators are the common case and the reason for the name, but not the only
+     * shape: JS/TS uses this hook for hand-rolled dispatch guards
+     * (`route-extractors/dispatch-guard.ts`), where a raw `node:http` server
+     * declares a route by comparing the request path to a literal. Anything that
+     * yields a `(path, verb, handler)` triple from one file's AST belongs here —
+     * set `ExtractedDecoratorRoute.source` when the provenance is not a decorator,
+     * so the `HANDLES_ROUTE` edge does not claim one.
+     *
+     * Default: undefined (no language-specific route extraction).
      */
     readonly extractDecoratorRoutes?: (tree: Parser.Tree, filePath: string, lineOffset: number) => ExtractedDecoratorRoute[];
     /**
@@ -240,6 +297,51 @@ interface LanguageProviderConfig {
      * Default: undefined (no interface-inheritance route resolution).
      */
     readonly extractRouteInheritanceTypes?: (tree: Parser.Tree, filePath: string) => SharedSpringType[];
+    /**
+     * Harvest this file's module-level string constants (#2391 core, #2980 Java
+     * parity) into the language-agnostic {@link ModuleConstants} shape, so the
+     * parse phase can resolve non-literal decorator route paths cross-file.
+     *
+     * The worker calls this when BOTH hold:
+     *  - the provider declares no `moduleConstantHeuristic`, or the one it
+     *    declares matched — syntax-driven, e.g. a `static final String` field or
+     *    a constants-bearing import; NEVER a class-name pattern like
+     *    `*Constants`, which silently drops route constants living in classes
+     *    named e.g. `ApiPaths`/`Routes`, and
+     *  - the extraction yields something resolvable (a literal, an expression, or
+     *    an import binding), keeping the aggregate bounded on large repos.
+     *
+     * Default: undefined (no constant harvest; non-literal route paths of this
+     * language floor to skip).
+     */
+    readonly extractModuleConstants?: (tree: Parser.Tree) => ModuleConstants;
+    /**
+     * Cheap content heuristic deciding whether the worker should run
+     * {@link extractModuleConstants} on a file. Guards the harvest cost on huge
+     * repos: files that cannot contribute (no constant-bearing syntax) are not
+     * walked. Must be syntax-driven (field/import shape), not identifier
+     * pattern-matching on class names.
+     *
+     * Default: undefined — harvest EVERY file of this language. A gate is opt-in
+     * because getting it wrong silently drops routes that already resolve, and a
+     * missed gate only costs time. Declare one only where the cost bites (Java's
+     * Maven monorepos) and only after checking it against every shape
+     * {@link extractModuleConstants} accepts.
+     */
+    readonly moduleConstantHeuristic?: (content: string) => boolean;
+    /**
+     * Fold one file's non-literal route-path operand list
+     * (`routePathExpr`/`routePathOperands` of an `ExtractedDecoratorRoute`)
+     * against the repo-wide, file-path-keyed constant map, or null when it cannot
+     * be fully folded (skip floor — never a phantom path). Languages whose
+     * qualified refs resolve through class imports (`Outer.CONST`,
+     * `com.example.ApiPaths.USERS`) need this hook because the shared fold has no
+     * notion of qualified names; Python's bare-name refs use the shared default.
+     *
+     * Default: undefined (the parse phase falls back to the shared
+     * language-agnostic operand fold).
+     */
+    readonly foldRoutePathOperands?: (filePath: string, operands: readonly Operand[], repo: RepoConstants) => string | null;
     /** Built-in/stdlib names that should be filtered from the call graph for this language.
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;
@@ -339,6 +441,93 @@ interface LanguageProviderConfig {
      * Required when `emitScopeCaptures` is implemented.
      */
     readonly interpretImport?: (captures: CaptureMatch) => ParsedImport | null;
+    /**
+     * Do this language's imports EXECUTE at the point in the program where they
+     * are written?
+     *
+     * The scope extractor marks an import `runsOnlyWhenCalled` when the statement
+     * sits inside a `Function` scope (Pass 3): where imports are executed
+     * statements, one written in a function body runs only when that function is
+     * called — Python's `def f(): from x import Y`, Ruby's
+     * `def f; require 'x'; end`, a CommonJS `require()` in a body (which
+     * `javascript/captures.ts` does capture, via its own AST walk). That rule is
+     * about EXECUTION. It says nothing true about a language whose "import" is
+     * not an executed statement at all, and in such a language moving one into a
+     * function body defers exactly nothing.
+     *
+     * "Where written" is about execution time, not textual placement: a
+     * `#include` is spliced precisely where it is written and still answers
+     * `false`, because splicing is not running.
+     *
+     * **The failure directions are not symmetric, which is why the default is
+     * what it is.** Answering `false` for a language that really does execute
+     * its imports un-defers a deliberately lazy one, and `check --cycles`
+     * reports a cycle its author broke on purpose — wrong, but visible on screen
+     * and arguable by whoever reads it. Answering `true` for a language that
+     * does not SUPPRESSES a cycle that is entirely real: nobody sees it, so
+     * nobody can argue with it. Getting this wrong in the `true` direction hides
+     * a true cycle, and that is the failure that matters.
+     *
+     * Absent — the default — reads as `true`, so every provider that does not
+     * name this keeps today's behaviour exactly. The flag never ADDS deferral;
+     * declaring `false` only WITHHOLDS it.
+     *
+     * Declared `false` by, and only by:
+     *
+     *   - **C and C++** — `#include` is a preprocessor directive. The header's
+     *     text is spliced in before a line of the program runs, wherever the
+     *     directive sits, and C permits one inside a function body. C++'s only
+     *     other Pass-3 import form, `using ns::name` / `using namespace ns`, is
+     *     compile-time name lookup, is legal in a function body too, and defers
+     *     no more than an `#include` does.
+     *   - **Rust** — `use` is a compile-time path alias, not a statement that
+     *     runs. `fn f() { use crate::m::X; }` is legal, and putting the `use`
+     *     there changes only where the name is VISIBLE, never when anything
+     *     happens; Rust has no module-initialization order in the JS/Python
+     *     sense and permits intra-crate module cycles outright. It is the
+     *     structural twin of C++'s `using ns::name`. `rust/query.ts` captures
+     *     `(use_declaration)` and nothing else, so this covers the whole
+     *     surface. (The claim here is the narrow one: POSITION does not defer a
+     *     Rust import. Whether a Rust `use` can create an initialization
+     *     dependency *at all* is a larger and separate question, and this flag
+     *     deliberately does not answer it.)
+     *   - **COBOL** — `COPY` is a pure textual splice performed by the copybook
+     *     preprocessor, the `#include` case exactly. Latent today: the COBOL
+     *     `@scope.function` capture covers a single line (`cobol/captures.ts`
+     *     ranges sections and paragraphs `line → line`), so a `COPY` on any
+     *     later line never resolves inside one and Pass 3 has nothing to mark.
+     *     Declared anyway, so that giving those anchors their true multi-line
+     *     ranges cannot silently start suppressing real copybook cycles.
+     *
+     * Per-provider rather than per-import, and that is sufficient — the question
+     * this answers is narrower than "do this language's imports execute". It is
+     * only ever asked of an import that resolved INSIDE A FUNCTION SCOPE, so the
+     * real domain is: *can a function-local import in this language be
+     * non-executing?* No supported language has two forms that are both
+     * function-local and disagree. C++ has two forms, `#include` and
+     * `using ns::name`; both can appear in a body and both are compile-time.
+     *
+     * PHP is the case that looks like a counterexample and is not. It does mix —
+     * `use Foo\Bar;` aliases at compile time while `require` executes — but
+     * `use` cannot appear in a function body at all (`php/query.ts` records this
+     * twice: "`namespace_use_declaration` is an import only at top level / inside
+     * namespace scope"), so it never reaches this flag. Absent is therefore
+     * PERMANENTLY correct for PHP, including the day `require` is captured: a
+     * `require` in a body will correctly defer, and a `use` still cannot get
+     * here. Do not read PHP as a reason to build a per-`ParsedImport`
+     * classification hook — it would cost a provider call per import on the
+     * extractor's hot path, and `ParsedImport.kind` does not discriminate the
+     * thing being asked anyway.
+     *
+     * A capability on the provider rather than a language check in
+     * `scope-extractor.ts`: shared `core/ingestion/` pipeline code must not name
+     * languages (AGENTS.md), and "imports here are not executed statements" is a
+     * property of the language, not of the walk.
+     *
+     * Default: undefined, read as `true` (imports execute where they are
+     * written; position defers them).
+     */
+    readonly importsExecuteWhereWritten?: boolean;
     /**
      * What is the implicit receiver on a Function scope? For instance methods
      * this is `self`/`this`; for standalone functions it is `null`. Consulted
@@ -367,6 +556,19 @@ interface LanguageProviderConfig {
      * suffix — `@scope.function` → `'Function'`, etc.).
      */
     readonly resolveScopeKind?: (captures: CaptureMatch) => ScopeKind | null;
+    /**
+     * Report the receiver names this scope BINDS rather than inherits — see
+     * `Scope.ownsReceivers` (#2701).
+     *
+     * Called once per `@scope.*` capture during scope-tree construction.
+     * Return the shared frozen set for a scope that starts a fresh receiver
+     * (a JS/TS ordinary `function`, whose `this` is bound at call time), and
+     * `undefined` for one that inherits it (an arrow function, and every
+     * closure form in languages that capture the receiver lexically).
+     *
+     * Default: undefined everywhere — the receiver walk is unchanged.
+     */
+    readonly scopeOwnsReceivers?: (captures: CaptureMatch) => ReadonlySet<string> | undefined;
     /**
      * Override where a declaration's name becomes visible. By default the name
      * is bound in the innermost enclosing scope; return a different `ScopeId`
@@ -396,7 +598,7 @@ interface LanguageProviderConfig {
      * Required when `emitScopeCaptures` is implemented. Ring 2 PKG #922
      * provides the adapter that bridges today's resolver shape to this hook.
      */
-    readonly resolveImportTarget?: (parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex) => string | null;
+    readonly resolveImportTarget?: (parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex) => string | readonly string[] | null;
     /**
      * Enumerate the exported names of a file — used by the finalize algorithm
      * to expand `import * from M` into individual `BindingRef`s with

package/dist/core/ingestion/language-provider.js

@@ -8,6 +8,43 @@
  * The providers table in `languages/index.ts` uses `satisfies Record<SupportedLanguages, LanguageProvider>`
  * so adding a language to the enum without creating a provider is a compiler error.
  */
+/** Run optional provider enrichment without allowing one hook failure to drop
+ * the rest of the worker's language batch. */
+export function runDefinitionPropertiesExtractor(extractor, context, onError) {
+    try {
+        return extractor(context);
+    }
+    catch (error) {
+        onError(error);
+        return undefined;
+    }
+}
+/** Provider metadata is additive; graph identity and source-location fields
+ * supplied by the worker remain authoritative. */
+export function mergeCanonicalDefinitionProperties(providerProperties, canonicalProperties) {
+    return { ...providerProperties, ...canonicalProperties };
+}
+/**
+ * Everything a language needs to provide.
+ * Required fields must be explicitly set; optional fields have defaults
+ * applied by defineLanguage().
+ */
+/**
+ * Should the parse worker run {@link LanguageProviderConfig.extractModuleConstants}
+ * on this file?
+ *
+ * Exported so the DECISION is testable without booting a worker. It encodes the
+ * one rule that is easy to get backwards: a provider that declares no
+ * `moduleConstantHeuristic` harvests unconditionally. Writing the gate as
+ * `provider.moduleConstantHeuristic?.(content)` reads `undefined` as "skip" and
+ * silently disables the hook for every provider without a heuristic — which is
+ * exactly how Python's already-shipped harvest was turned off (#2391/#2980).
+ */
+export function shouldHarvestModuleConstants(provider, content) {
+    if (!provider.extractModuleConstants)
+        return false;
+    return !provider.moduleConstantHeuristic || provider.moduleConstantHeuristic(content);
+}
 const DEFAULTS = {
     mroStrategy: 'first-wins',
 };

package/dist/core/ingestion/languages/c/captures.js

@@ -5,6 +5,7 @@ import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 import { splitCInclude } from './import-decomposer.js';
 import { computeCDeclarationArity, computeCCallArity } from './arity-metadata.js';
 import { markStaticName } from './static-linkage.js';
+import { synthesizeReceiverChainCapture } from '../../utils/receiver-chain-captures.js';
 import { synthesizeCallableFlowCaptures, } from '../../utils/callable-flow-captures.js';
 const C_CALLABLE_CAPTURE_OPTIONS = {
     functionNodeTypes: new Set(['function_definition']),
@@ -118,6 +119,12 @@ export function emitCScopeCaptures(sourceText, filePath, cachedTree) {
                 grouped['@reference.arity'] = syntheticCapture('@reference.arity', callNode, String(computeCCallArity(callNode)));
             }
         }
+        // Structural receiver chain for a call whose receiver is itself an
+        // expression, so resolution can type it by folding over structure
+        // instead of re-parsing the receiver's source text. Self-gating: a
+        // non-call match, an absent receiver, or a chain with no nameable base
+        // all leave `grouped` untouched.
+        synthesizeReceiverChainCapture(grouped, nodeMap['@reference.receiver']);
         out.push(grouped);
     }
     out.push(...synthesizeCallableFlowCaptures(tree.rootNode, C_CALLABLE_CAPTURE_OPTIONS));

package/dist/core/ingestion/languages/c/import-target.js

@@ -1,4 +1,5 @@
 import { dirname, join } from 'path';
+import { perFileSet } from '../../import-resolvers/per-file-set.js';
 /**
  * Per-pass memo: workspace paths bucketed by basename (last path segment),
  * keyed on the `allFilePaths` set identity.
@@ -15,25 +16,20 @@ import { dirname, join } from 'path';
  * `WeakMap`-keyed so it is reclaimed with the pass (no cross-pass staleness).
  * Shared by C and C++ (`resolveCppImportTarget` delegates here).
  */
-const suffixIndexByPaths = new WeakMap();
-function suffixIndex(allFilePaths) {
-    let index = suffixIndexByPaths.get(allFilePaths);
-    if (index === undefined) {
-        index = new Map();
-        for (const original of allFilePaths) {
-            const normalized = original.replace(/\\/g, '/');
-            const basename = normalized.slice(normalized.lastIndexOf('/') + 1);
-            let bucket = index.get(basename);
-            if (bucket === undefined) {
-                bucket = [];
-                index.set(basename, bucket);
-            }
-            bucket.push({ original, normalized, depth: normalized.split('/').length });
+const suffixIndex = perFileSet((allFilePaths) => {
+    const index = new Map();
+    for (const original of allFilePaths) {
+        const normalized = original.replace(/\\/g, '/');
+        const basename = normalized.slice(normalized.lastIndexOf('/') + 1);
+        let bucket = index.get(basename);
+        if (bucket === undefined) {
+            bucket = [];
+            index.set(basename, bucket);
         }
-        suffixIndexByPaths.set(allFilePaths, index);
+        bucket.push({ original, normalized, depth: normalized.split('/').length });
     }
     return index;
-}
+});
 /**
  * Resolve a C #include path to a file in the workspace.
  *