gitnexus 1.6.6-rc.99 → 1.6.6

package/dist/core/ingestion/pipeline-phases/parse.d.ts

@@ -2,8 +2,8 @@
  * Phase: parse
  *
  * Chunked parse + resolve loop: reads source in byte-budget chunks,
- * parses via worker pool (or sequential fallback), resolves imports,
- * heritage, and calls, synthesizes wildcard bindings.
+ * parses via the worker pool (the sole parse path — no sequential fallback),
+ * resolves imports, heritage, and calls, synthesizes wildcard bindings.
  *
  * This phase encapsulates the entire `runChunkedParseAndResolve` function
  * from the original pipeline. The chunk loop is a memory optimization
@@ -19,14 +19,14 @@ import type { PipelinePhase } from './types.js';
 import type { BindingAccumulator } from '../binding-accumulator.js';
 import type { ParsedFile } from '../../../_shared/index.js';
 import type { ExtractedFetchCall, ExtractedRoute, ExtractedDecoratorRoute, ExtractedToolDef, ExtractedORMQuery, FetchWrapperDef } from '../workers/parse-worker.js';
-import type { createResolutionContext } from '../model/resolution-context.js';
-import type { ASTCache } from '../ast-cache.js';
+import type { MutableSemanticModel } from '../model/index.js';
 export interface ParseOutput {
     /**
      * Read-only snapshot of exported type bindings keyed by file path.
      *
-     * Fully populated by `parse` (sequential path via `enrichExportedTypeMap`
-     * and worker path via `buildExportedTypeMapFromGraph` in the main thread).
+     * Fully populated by `parse` on the main thread after the worker parse:
+     * `enrichExportedTypeMap` propagates fixpoint-inferred TypeEnv bindings and
+     * `buildExportedTypeMapFromGraph` reconstructs from graph nodes.
      * Downstream phases — including `crossFile` — receive it as a true
      * `ReadonlyMap`; `crossFile` builds its own mutable working copy locally
      * for per-file re-resolution writes, so this snapshot is never mutated
@@ -40,8 +40,9 @@ export interface ParseOutput {
     readonly allToolDefs: readonly ExtractedToolDef[];
     readonly allORMQueries: readonly ExtractedORMQuery[];
     bindingAccumulator: BindingAccumulator;
-    /** Resolution context from the parse phase — carries importMap, namedImportMap, etc. */
-    resolutionContext: ReturnType<typeof createResolutionContext>;
+    /** SemanticModel populated during parse — scope-resolution reads its
+     *  TypeRegistry / MethodRegistry / SymbolTable indexes. */
+    model: MutableSemanticModel;
     /** Pass-through: all file paths for downstream phases. */
     readonly allPaths: readonly string[];
     /** Pass-through: shared `allPathSet` from structure (built once, not per-phase). */
@@ -49,29 +50,12 @@ export interface ParseOutput {
     /** Pass-through: total file count for progress reporting. */
     totalFiles: number;
     /**
-     * True if the parse phase spawned a live worker pool for this run.
-     * False means every chunk ran through the sequential fallback (skipWorkers,
-     * thresholds not met, or pool-creation failure). Primarily a test affordance:
-     * see `PipelineOptions.workerThresholdsForTest`.
+     * True if the parse phase constructed a worker pool for this run. False
+     * means no pool was needed — a warm all-cache-hit run replays cached worker
+     * output without spawning workers, or there were no parseable files. There
+     * is no sequential parser; the pool is the sole parse path on a cache miss.
      */
     readonly usedWorkerPool: boolean;
-    /**
-     * Cross-phase tree-sitter Tree cache populated by the sequential
-     * parse path. Separate from the chunk-local `astCache` used *inside*
-     * the parse phase (which is cleared between chunks) — this one
-     * survives the whole phase and hands Trees to scope-resolution so
-     * it can skip a second parse.
-     *
-     * Empty entries for files that ran through the worker pool
-     * (workers can't return native tree-sitter Trees across the
-     * MessageChannel). Cache miss is safe — consumers fall back to a
-     * fresh parse. See plan
-     * docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 4).
-     *
-     * Disposed by `scopeResolutionPhase` (the sole consumer) via
-     * `scopeTreeCache.clear()` after its extract loop finishes.
-     */
-    readonly scopeTreeCache: ASTCache;
     /**
      * Per-file `ParsedFile` artifacts produced by workers' calls to
      * `extractParsedFile`. Threaded through to `scopeResolutionPhase`
@@ -79,10 +63,6 @@ export interface ParseOutput {
      * scope-resolution can skip its own `extractParsedFile` (which would
      * otherwise re-parse the file with tree-sitter on the main thread,
      * costing ~58s on a 1000-file repo).
-     *
-     * Empty for files that went through the sequential parse fallback —
-     * sequential doesn't emit ParsedFile artifacts; scope-resolution
-     * falls back to a fresh extract for those.
      */
     readonly parsedFiles: readonly ParsedFile[];
 }

package/dist/core/ingestion/pipeline-phases/parse.js

@@ -2,8 +2,8 @@
  * Phase: parse
  *
  * Chunked parse + resolve loop: reads source in byte-budget chunks,
- * parses via worker pool (or sequential fallback), resolves imports,
- * heritage, and calls, synthesizes wildcard bindings.
+ * parses via the worker pool (the sole parse path — no sequential fallback),
+ * resolves imports, heritage, and calls, synthesizes wildcard bindings.
  *
  * This phase encapsulates the entire `runChunkedParseAndResolve` function
  * from the original pipeline. The chunk loop is a memory optimization

package/dist/core/ingestion/pipeline-phases/processes.d.ts

@@ -4,7 +4,7 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools
+ * @deps    communities, routes, tools, pruneLocalSymbols
  * @reads   graph (all nodes and relationships), communityResult, routeRegistry, toolDefs
  * @writes  graph (Process nodes, STEP_IN_PROCESS edges, ENTRY_POINT_OF edges)
  */

package/dist/core/ingestion/pipeline-phases/processes.js

@@ -4,7 +4,7 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools
+ * @deps    communities, routes, tools, pruneLocalSymbols
  * @reads   graph (all nodes and relationships), communityResult, routeRegistry, toolDefs
  * @writes  graph (Process nodes, STEP_IN_PROCESS edges, ENTRY_POINT_OF edges)
  */
@@ -16,8 +16,10 @@ import { logger } from '../../logger.js';
 export const processesPhase = {
     name: 'processes',
     // `structure` supplies `totalFiles` (progress counter) without the spurious
-    // structural data dependency on `parse`.
-    deps: ['communities', 'routes', 'tools', 'structure'],
+    // structural data dependency on `parse`. `pruneLocalSymbols` is declared
+    // explicitly so process extraction always reads the trimmed graph even if a
+    // future option drops the intervening `mro`/`communities` phases.
+    deps: ['communities', 'routes', 'tools', 'pruneLocalSymbols', 'structure'],
     async execute(ctx, deps) {
         const { totalFiles } = getPhaseOutput(deps, 'structure');
         const { communityResult } = getPhaseOutput(deps, 'communities');

package/dist/core/ingestion/pipeline-phases/prune-local-symbols.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Phase: pruneLocalSymbols
+ *
+ * Drops inert function/block-local value symbols after scope resolution has
+ * already used them for binding and call resolution.
+ *
+ * @deps    scopeResolution
+ * @reads   graph (nodes and relationships)
+ * @writes  graph (removes unreferenced local Const/Variable/Static nodes)
+ */
+import type { PipelinePhase } from './types.js';
+import { type LocalSymbolPruneStats } from '../local-symbol-pruner.js';
+export type PruneLocalSymbolsOutput = LocalSymbolPruneStats;
+export declare const pruneLocalSymbolsPhase: PipelinePhase<PruneLocalSymbolsOutput>;

package/dist/core/ingestion/pipeline-phases/prune-local-symbols.js

@@ -0,0 +1,26 @@
+/**
+ * Phase: pruneLocalSymbols
+ *
+ * Drops inert function/block-local value symbols after scope resolution has
+ * already used them for binding and call resolution.
+ *
+ * @deps    scopeResolution
+ * @reads   graph (nodes and relationships)
+ * @writes  graph (removes unreferenced local Const/Variable/Static nodes)
+ */
+import { pruneLocalValueSymbols } from '../local-symbol-pruner.js';
+import { isDev } from '../utils/env.js';
+import { logger } from '../../logger.js';
+export const pruneLocalSymbolsPhase = {
+    name: 'pruneLocalSymbols',
+    deps: ['scopeResolution'],
+    async execute(ctx) {
+        const stats = pruneLocalValueSymbols(ctx.graph, {
+            keepLocalValueSymbols: ctx.options?.keepLocalValueSymbols,
+        });
+        if (isDev && !stats.skippedByEnv && stats.prunedNodes > 0) {
+            logger.info(`Pruned ${stats.prunedNodes}/${stats.candidateNodes} inert local value symbols`);
+        }
+        return stats;
+    },
+};

package/dist/core/ingestion/pipeline.d.ts

@@ -17,29 +17,29 @@
 import { type PipelineProgress } from '../../_shared/index.js';
 import { PipelineResult } from '../../types/pipeline.js';
 export interface PipelineOptions {
-    /** Skip MRO, community detection, and process extraction for faster test runs. */
+    /**
+     * Skip MRO, community detection, and process extraction for faster test runs.
+     * The `pruneLocalSymbols` phase still runs — it is graph construction (it cleans
+     * up inert local symbols), not graph analysis — so set `keepLocalValueSymbols`
+     * to retain those nodes under `skipGraphPhases`.
+     */
     skipGraphPhases?: boolean;
-    /** Force sequential parsing (no worker pool). Useful for testing the sequential path. */
-    skipWorkers?: boolean;
     /**
-     * @internal Test-only override for worker-pool gating thresholds.
-     * When unset, production defaults apply (15 files OR 512 KB total bytes).
-     * Setting either field lowers the corresponding threshold so small test
-     * fixtures can still exercise the worker-pool path. Do not use from
-     * production call sites.
+     * Request parsing with the worker pool disabled. The sequential parser was
+     * removed — the worker pool is the sole parse path — so setting this now
+     * makes the parse phase throw a `WorkerPoolDisabledError` (equivalent to
+     * `--workers 0`). Retained so callers get an actionable error rather than a
+     * silently-different result.
      */
-    workerThresholdsForTest?: {
-        minFiles?: number;
-        minBytes?: number;
-    };
+    skipWorkers?: boolean;
     /**
      * @internal Test-only override for the worker script URL the pool
      * spawns. When unset, parse-impl resolves `parse-worker.js` from the
      * adjacent `workers/` directory (or the compiled `dist/` fallback
      * under vitest). Integration tests use this to inject a custom
      * worker script that deterministically triggers worker-pool
-     * resilience paths (e.g., crash-on-poison-file) — same precedent as
-     * `workerThresholdsForTest`. Do not use from production call sites.
+     * resilience paths (e.g., crash-on-poison-file). Do not use from production
+     * call sites.
      */
     workerUrlForTest?: URL;
     /**
@@ -61,11 +61,11 @@ export interface PipelineOptions {
      * `createWorkerPool` so the pool sizing bypasses the env-var fallback
      * in `resolveAutoPoolSize`. The env-var channel
      * (`GITNEXUS_WORKER_POOL_SIZE`) remains as a back-compat fallback when
-     * this field is undefined. Setting `workerPoolSize: 0` disables the
-     * pool entirely (sequential fallback) — equivalent to `skipWorkers`
-     * but expressed in the same units as `--workers <N>` so long-running
-     * hosts (eval-server, MCP daemon) can size per-call without leaking
-     * `process.env` state across analyze invocations.
+     * this field is undefined. Must be a positive integer — `0` hard-errors
+     * (sequential parsing was removed; equivalent to `skipWorkers`), expressed
+     * in the same units as `--workers <N>` so long-running hosts (eval-server,
+     * MCP daemon) can size per-call without leaking `process.env` state across
+     * analyze invocations.
      */
     workerPoolSize?: number;
     /**
@@ -95,5 +95,13 @@ export interface PipelineOptions {
      * without leaking `process.env` state across invocations.
      */
     chunkByteBudget?: number;
+    /**
+     * Keep inert block-local value symbols (Const/Variable/Static) that the
+     * `pruneLocalSymbols` phase would otherwise drop. Mirrors the
+     * `GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS` env var, but threaded per-call so
+     * long-running hosts (eval-server, MCP daemon) can opt out without leaking
+     * `process.env` state across invocations. When undefined, the env var decides.
+     */
+    keepLocalValueSymbols?: boolean;
 }
 export declare const runPipelineFromRepo: (repoPath: string, onProgress: (progress: PipelineProgress) => void, options?: PipelineOptions) => Promise<PipelineResult>;

package/dist/core/ingestion/pipeline.js

@@ -15,7 +15,7 @@
  * See ARCHITECTURE.md for the full phase dependency diagram.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
+import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, pruneLocalSymbolsPhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
 // ── Phase registry ─────────────────────────────────────────────────────────
 /**
  * All pipeline phases with their dependency relationships.
@@ -23,7 +23,8 @@ import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase,
  * Phase dependency graph:
  *
  *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
- *     → crossFile → mro → communities → processes
+ *     → crossFile → scopeResolution → pruneLocalSymbols
+ *     → mro → communities → processes
  *
  * To add a new phase: create a file in pipeline-phases/, export the phase
  * object, and add it to the appropriate position in this array.
@@ -40,6 +41,7 @@ function buildPhaseList(options) {
         ormPhase,
         crossFilePhase,
         scopeResolutionPhase,
+        pruneLocalSymbolsPhase,
     ];
     if (!options?.skipGraphPhases) {
         phases.push(mroPhase, communitiesPhase, processesPhase);

package/dist/core/ingestion/resolve-references.js

@@ -37,7 +37,7 @@
  *     resolution but not emitted as multiple edges; callers that want
  *     branch-on-ambiguity behavior should consume the registries directly.
  */
-import { buildClassRegistry, buildFieldRegistry, buildMethodRegistry, CLASS_KINDS, FIELD_KINDS, METHOD_KINDS, } from '../../_shared/index.js';
+import { buildClassRegistry, buildFieldRegistry, buildMacroRegistry, buildMethodRegistry, CLASS_KINDS, FIELD_KINDS, METHOD_KINDS, } from '../../_shared/index.js';
 /**
  * Resolve every `ReferenceSite` in `scopes.referenceSites` against the
  * matching registry and produce a `ReferenceIndex` keyed by source scope
@@ -58,6 +58,7 @@ export function resolveReferenceSites(input) {
     const classRegistry = buildClassRegistry(ctx);
     const methodRegistry = buildMethodRegistry(ctx);
     const fieldRegistry = buildFieldRegistry(ctx);
+    const macroRegistry = buildMacroRegistry(ctx);
     // bySourceScope is the canonical index; byTargetDef is derived from it.
     const bySourceScope = new Map();
     const byTargetDef = new Map();
@@ -66,7 +67,7 @@ export function resolveReferenceSites(input) {
     let unresolved = 0;
     for (const site of scopes.referenceSites) {
         sitesProcessed++;
-        const resolutions = lookupForSite(site, classRegistry, methodRegistry, fieldRegistry);
+        const resolutions = lookupForSite(site, classRegistry, methodRegistry, fieldRegistry, macroRegistry);
         if (resolutions.length === 0) {
             unresolved++;
             continue;
@@ -112,6 +113,12 @@ export function resolveReferenceSites(input) {
  *   | `type-reference` | ClassRegistry     | CLASS_KINDS                  |
  *   | `read`/`write`   | FieldRegistry     | FIELD_KINDS                  |
  *   | `import-use`     | tiered fallback   | METHOD ∪ CLASS ∪ FIELD       |
+ *   | `macro`          | MacroRegistry     | MACRO_KINDS (`Macro` only)   |
+ *
+ * `macro` has its own single-kind registry so a macro invocation
+ * (`log!(…)`) resolves ONLY to a `macro_rules! log` definition and never
+ * to a same-named free function — macros and functions are disjoint
+ * namespaces (the false-`CALLS`-edge class flagged in the #1934 review).
  *
  * `import-use` doesn't have a single registry — the imported name might
  * be a class, a function, or a constant. Try each in priority order and
@@ -119,7 +126,7 @@ export function resolveReferenceSites(input) {
  * scope's `bindings` (Step 1 lexical hit), so the lookup is correct
  * regardless of which registry surfaces the def.
  */
-function lookupForSite(site, classRegistry, methodRegistry, fieldRegistry) {
+function lookupForSite(site, classRegistry, methodRegistry, fieldRegistry, macroRegistry) {
     switch (site.kind) {
         case 'call': {
             const opts = {
@@ -159,6 +166,11 @@ function lookupForSite(site, classRegistry, methodRegistry, fieldRegistry) {
                 return methodHits;
             return fieldRegistry.lookup(site.name, site.inScope);
         }
+        case 'macro': {
+            // Macro-only namespace: resolves against `Macro`-labeled defs, never
+            // functions. No receiver, no arity — see `MacroRegistry`.
+            return macroRegistry.lookup(site.name, site.inScope);
+        }
     }
 }
 /** Compose a `Reference` record from a site + its top resolution. */

package/dist/core/ingestion/route-extractors/laravel.d.ts

@@ -5,6 +5,16 @@ export interface ExtractedRoute {
     routePath: string | null;
     routeName: string | null;
     controllerName: string | null;
+    /**
+     * The controller class's normalized (dot-joined) fully-qualified name when
+     * the routes file disambiguates it — via a `use` import (`use App\…\X;` or
+     * `use App\…\X as Y;`) or an inline qualified `::class` reference. Resolved
+     * to the same key shape the type registry stores (`normalizeQualifiedName`),
+     * so the emitter can `lookupClassByQualifiedName` to disambiguate
+     * same-short-name controllers. `null`/undefined when only a bare short name
+     * is available — the emitter then falls back to short-name resolution.
+     */
+    controllerQualifiedName?: string | null;
     methodName: string | null;
     middleware: string[];
     prefix: string | null;

package/dist/core/ingestion/route-extractors/laravel.js

@@ -1,4 +1,6 @@
 import { extractStringContent, findDescendant } from '../utils/ast-helpers.js';
+import { splitNamespaceUseDeclaration } from '../languages/php/import-decomposer.js';
+import { normalizeQualifiedName } from '../utils/qualified-name.js';
 const ROUTE_HTTP_METHODS = new Set([
     'get',
     'post',
@@ -120,10 +122,26 @@ function appendResourceActionName(base, action) {
         return null;
     return base.endsWith('.') ? `${base}${action}` : `${base}.${action}`;
 }
+/**
+ * Read the controller class reference out of a `class_constant_access_expression`
+ * (the `X::class` node). Returns the simple short name (for short-name fallback)
+ * and, when the reference is itself namespace-qualified (`\App\Admin\X::class`),
+ * its normalized dot-joined fully-qualified name (for direct disambiguation).
+ */
+function readControllerClassRef(classAccess) {
+    const nameChild = classAccess.children?.find((c) => c.type === 'name');
+    const qualifiedChild = classAccess.children?.find((c) => c.type === 'qualified_name');
+    const qualified = qualifiedChild ? normalizeQualifiedName(qualifiedChild.text) : null;
+    // When only a qualified_name is present, derive the simple short name from
+    // its last segment so short-name fallback still works.
+    const simple = nameChild?.text ?? (qualified ? (qualified.split('.').pop() ?? null) : null);
+    return { simple, qualified };
+}
 /** Extract controller class name from common Laravel handler argument shapes. */
 function extractControllerTarget(argsNode) {
+    const none = { controller: null, controllerQualified: null, method: null, bareMethod: null };
     if (!argsNode)
-        return { controller: null, method: null, bareMethod: null };
+        return none;
     const args = [];
     for (const child of argsNode.children ?? []) {
         if (child.type === 'argument')
@@ -134,10 +152,11 @@ function extractControllerTarget(argsNode) {
     // Second arg is the handler
     const handlerNode = args[1];
     if (!handlerNode)
-        return { controller: null, method: null, bareMethod: null };
+        return none;
     // Array syntax: [UserController::class, 'index']
     if (handlerNode.type === 'array_creation_expression') {
         let controller = null;
+        let controllerQualified = null;
         let method = null;
         const elements = [];
         for (const el of handlerNode.children ?? []) {
@@ -147,14 +166,16 @@ function extractControllerTarget(argsNode) {
         if (elements[0]) {
             const classAccess = findDescendant(elements[0], 'class_constant_access_expression');
             if (classAccess) {
-                controller = classAccess.children?.find((c) => c.type === 'name')?.text ?? null;
+                const ref = readControllerClassRef(classAccess);
+                controller = ref.simple;
+                controllerQualified = ref.qualified;
             }
         }
         if (elements[1]) {
             const str = findDescendant(elements[1], 'string');
             method = str ? extractStringContent(str) : null;
         }
-        return { controller, method, bareMethod: null };
+        return { controller, controllerQualified, method, bareMethod: null };
     }
     // String syntax: 'UserController@index'. A bare string such as 'index'
     // becomes a method only when a surrounding Route::controller(...) group
@@ -163,17 +184,22 @@ function extractControllerTarget(argsNode) {
         const text = extractStringContent(handlerNode);
         if (text?.includes('@')) {
             const [controller, method] = text.split('@');
-            return { controller, method, bareMethod: null };
+            return { controller, controllerQualified: null, method, bareMethod: null };
         }
         if (text)
-            return { controller: null, method: null, bareMethod: text };
+            return { controller: null, controllerQualified: null, method: null, bareMethod: text };
     }
     // Class reference: UserController::class (invokable controller)
     if (handlerNode.type === 'class_constant_access_expression') {
-        const controller = handlerNode.children?.find((c) => c.type === 'name')?.text ?? null;
-        return { controller, method: '__invoke', bareMethod: null };
+        const ref = readControllerClassRef(handlerNode);
+        return {
+            controller: ref.simple,
+            controllerQualified: ref.qualified,
+            method: '__invoke',
+            bareMethod: null,
+        };
     }
-    return { controller: null, method: null, bareMethod: null };
+    return { controller: null, controllerQualified: null, method: null, bareMethod: null };
 }
 /**
  * Unwrap a chained call like Route::middleware('auth')->prefix('api')->group(fn)
@@ -266,8 +292,59 @@ function parseArrayGroupArgs(argsNode) {
     }
     return ctx;
 }
+/**
+ * Build the routes file's `use`-import alias map: local name (alias, else the
+ * imported short name) → the class's normalized dot-joined fully-qualified name.
+ * Reuses the PHP `use`-declaration decomposer so grouped (`use Foo\{A, B}`) and
+ * aliased (`use Foo\Bar as Baz;`) forms are handled across grammar versions.
+ * `use` statements are file-/namespace-scoped, so a shallow walk over the
+ * routes file's structural nodes finds them all.
+ */
+function buildUseAliasMap(root) {
+    const aliasMap = new Map();
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node.type === 'namespace_use_declaration') {
+            for (const match of splitNamespaceUseDeclaration(node)) {
+                const source = match['@import.source']?.text;
+                if (source === undefined)
+                    continue;
+                const local = match['@import.alias']?.text ?? match['@import.name']?.text;
+                if (local === undefined || local === '')
+                    continue;
+                aliasMap.set(local, normalizeQualifiedName(source));
+            }
+            continue;
+        }
+        // Only descend through file/namespace structure where `use` can appear —
+        // not into function bodies or expressions.
+        if (node.type === 'program' ||
+            node.type === 'namespace_definition' ||
+            node.type === 'declaration_list' ||
+            node.type === 'compound_statement') {
+            for (const child of node.namedChildren ?? [])
+                stack.push(child);
+        }
+    }
+    return aliasMap;
+}
+/**
+ * Resolve a route's controller to its normalized fully-qualified name when the
+ * routes file disambiguates it: an inline qualified `::class` wins, else the
+ * `use`-import alias map for the short/local name, else `null` (the emitter
+ * falls back to short-name resolution).
+ */
+function resolveControllerQualifiedName(inlineQualified, controllerName, aliasMap) {
+    if (inlineQualified)
+        return inlineQualified;
+    if (controllerName)
+        return aliasMap.get(controllerName) ?? null;
+    return null;
+}
 export function extractLaravelRoutes(tree, filePath) {
     const routes = [];
+    const useAliasMap = buildUseAliasMap(tree.rootNode);
     function resolveStack(stack) {
         const middleware = [];
         let prefix = null;
@@ -316,6 +393,7 @@ export function extractLaravelRoutes(tree, filePath) {
                     routePath,
                     routeName: appendResourceActionName(routeNameBase, action),
                     controllerName: target.controller ?? effective.controller,
+                    controllerQualifiedName: resolveControllerQualifiedName(target.controllerQualified, target.controller ?? effective.controller, useAliasMap),
                     methodName: action,
                     middleware: [...effective.middleware],
                     prefix: effective.prefix,
@@ -331,6 +409,7 @@ export function extractLaravelRoutes(tree, filePath) {
                 routePath,
                 routeName,
                 controllerName: target.controller ?? effective.controller,
+                controllerQualifiedName: resolveControllerQualifiedName(target.controllerQualified, target.controller ?? effective.controller, useAliasMap),
                 methodName: target.method ?? (effective.controller ? target.bareMethod : null),
                 middleware: [...effective.middleware],
                 prefix: effective.prefix,

package/dist/core/ingestion/scope-extractor-bridge.d.ts

@@ -27,9 +27,10 @@ import type { ParsedFile } from '../../_shared/index.js';
 import type { LanguageProvider } from './language-provider.js';
 /** Callback used to report scope-extraction warnings to the host (worker or direct). */
 export type ScopeBridgeWarn = (message: string) => void;
+export type ScopeCaptureSourceKind = 'full-file' | 'pre-extracted-script';
 /**
  * Produce a `ParsedFile` for the given file, or `undefined` when the
  * provider hasn't migrated / the extractor throws. Never propagates
  * exceptions.
  */
-export declare function extractParsedFile(provider: LanguageProvider, sourceText: string, filePath: string, onWarn?: ScopeBridgeWarn, cachedTree?: unknown): ParsedFile | undefined;
+export declare function extractParsedFile(provider: LanguageProvider, sourceText: string, filePath: string, onWarn?: ScopeBridgeWarn, cachedTree?: unknown, sourceKind?: ScopeCaptureSourceKind): ParsedFile | undefined;

package/dist/core/ingestion/scope-extractor-bridge.js

@@ -30,13 +30,13 @@ import { logger } from '../logger.js';
  * provider hasn't migrated / the extractor throws. Never propagates
  * exceptions.
  */
-export function extractParsedFile(provider, sourceText, filePath, onWarn, cachedTree) {
+export function extractParsedFile(provider, sourceText, filePath, onWarn, cachedTree, sourceKind = 'full-file') {
     if (provider.emitScopeCaptures === undefined)
         return undefined;
     if (sourceText.trim().length === 0)
         return undefined;
     try {
-        const captures = provider.emitScopeCaptures(sourceText, filePath, cachedTree);
+        const captures = provider.emitScopeCaptures(sourceText, filePath, cachedTree, { sourceKind });
         return extractScope(captures, filePath, provider);
     }
     catch (err) {

package/dist/core/ingestion/scope-extractor.js

@@ -565,6 +565,8 @@ function normalizeNodeLabel(kindStr) {
             return 'Annotation';
         case 'namespace':
             return 'Namespace';
+        case 'macro':
+            return 'Macro';
         default:
             return undefined;
     }
@@ -775,6 +777,11 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
         if (kind === undefined)
             continue;
         const nameCap = match['@reference.name'] ?? anchor;
+        // Optional qualified form of the reference (e.g. a C++ base `Other::Inner`),
+        // threaded to resolution so a same-tail nested base resolves to the correct
+        // sibling via the full-path QualifiedNameIndex before the simple-tail walk
+        // (#1982). Absent for unqualified references — resolution stays unchanged.
+        const qualifiedCap = match['@reference.qualified-name'];
         const inScopeId = positionIndex.atPosition(filePath, anchor.range.startLine, anchor.range.startCol);
         if (inScopeId === undefined)
             continue;
@@ -790,6 +797,9 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
             atRange: anchor.range,
             inScope: inScopeId,
             kind,
+            ...(qualifiedCap?.text !== undefined && qualifiedCap.text.length > 0
+                ? { rawQualifiedName: qualifiedCap.text }
+                : {}),
             ...(callForm !== undefined ? { callForm } : {}),
             ...(explicitReceiver !== undefined ? { explicitReceiver } : {}),
             ...(arity !== undefined ? { arity } : {}),
@@ -819,6 +829,8 @@ function referenceKindFromAnchor(name) {
         case 'import_use':
         case 'import-use':
             return 'import-use';
+        case 'macro':
+            return 'macro';
         default:
             return undefined;
     }
@@ -897,6 +909,7 @@ const KNOWN_SUB_TAGS = new Set([
     '@type-binding.name',
     '@type-binding.type',
     '@reference.name',
+    '@reference.qualified-name',
     '@reference.receiver',
     '@reference.operator',
     '@reference.arity',