gitnexus 1.6.10-rc.99 → 1.6.10

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.d.ts

@@ -15,7 +15,7 @@
  *        - propagatesReturnTypesAcrossImports (default true)
  *        - fieldFallbackOnMethodLookup (default true — turn OFF for
  *          statically-typed languages; the heuristic over-connects)
- *        - unwrapCollectionAccessor — property-style collection views
+ *        - elementTypeOf — container element type, by subscript or accessor
  *        - collapseMemberCallsByCallerTarget — one edge per caller/target
  *        - populateNamespaceSiblings — cross-file implicit visibility
  *        - hoistTypeBindingsToModule — enable ONLY when method return
@@ -113,13 +113,24 @@
  *       3. Case 0.5 implicit-`this` chain walk — GATED: fires only for
  *          languages that set `resolveThisViaEnclosingClass === true`;
  *          it intercepts every bare-`this` call/read/write site ahead of
- *          Case 4 and does NOT emit Case 4's interface-dispatch fan-out,
- *          so enabling the toggle for a language changes that language's
- *          `this` dispatch semantics (see the toggle's doc below)
+ *          Case 4 and does NOT emit the interface-dispatch fan-out that
+ *          Cases 0, 3b and 4 all perform (Case 0 gained it in #2829 and
+ *          Case 3b in #2832, leaving 0.5 the only INSTANCE-receiver case
+ *          that folds or walks to a receiver type without fanning out.
+ *          Read that narrowly: Case 2 also walks an MRO and its binding
+ *          admits `Interface`, but its receiver IS the type name, so the
+ *          site is static dispatch and a fan-out would be wrong; Cases 3
+ *          and 5 resolve by direct lookup rather than a fold or MRO walk,
+ *          and no language is known to reach Case 3 with an Interface —
+ *          every one that could strips the namespace qualifier first,
+ *          sending it to Case 4), so enabling the toggle
+ *          for a language changes that language's `this` dispatch
+ *          semantics (see the toggle's doc below)
  *       4. Case 1 namespace-receiver
  *       5. Case 2 class-name receiver
  *       6. Case 3 dotted typeBinding for namespace prefix
- *       7. Case 3b chain-typebinding (compound resolver)
+ *       7. Case 3b chain-typebinding (compound resolver + interface-dispatch
+ *          fan-out on an Interface fold, #2832)
  *       8. Case 4 simple typeBinding (MRO walk + findOwnedMember)
  *     Reordering or merging cases changes resolution semantics. The
  *     numbering is part of the contract — keep the comments.
@@ -267,6 +278,7 @@
  * Plan that introduced most of these invariants:
  * `docs/plans/2026-04-20-001-refactor-emit-pipeline-generalization-plan.md`.
  */
+import type { DecorationStripper } from '../scope/walkers.js';
 import type { BindingRef, Callsite, ConstraintContext, ParsedFile, ParsedImport, ReferenceSite, ScopeId, SupportedLanguages, SymbolDefinition } from '../../../../_shared/index.js';
 import type { KnowledgeGraph } from '../../../graph/types.js';
 import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
@@ -274,6 +286,8 @@ import { LanguageProvider } from '../../language-provider.js';
 import { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import type { SemanticModel } from '../../model/semantic-model.js';
 import type { ConversionRankFn } from '../passes/overload-narrowing.js';
+import type { HeritageTypeArgumentSink } from '../utils/generic-instantiation.js';
+import type { WorkspaceResolutionIndex } from '../workspace-index.js';
 /** A LinearizeStrategy receives the full ancestor map so C3-style
  *  algorithms (which need to merge each parent's MRO) can implement
  *  themselves. Python's depth-first first-seen only consumes
@@ -295,6 +309,52 @@ export interface ImportResolutionContext {
 /** Re-exported for ScopeResolver consumers — same shape as
  *  `RegistryProviders.constraintCompatibility`'s third parameter. */
 export type { ConstraintContext } from '../../../../_shared/index.js';
+/** How a container's element was reached in the source. */
+export type ElementAccessRoute = {
+    readonly kind: 'index';
+} | {
+    readonly kind: 'accessor';
+    readonly name: string;
+};
+/** One structurally-detected implementor plus the receiver form in which it
+ *  satisfies the interface (see `detectInterfaceImplementations`). */
+export interface StructuralImplementor {
+    readonly structDefId: string;
+    readonly receiverForm: 'value' | 'pointer';
+}
+/**
+ * One interface whose satisfaction check could not be COMPLETED for at least
+ * one candidate type — not one that was checked and came out negative.
+ *
+ * The distinction is the whole point (#2873): a detector that reports only
+ * positives makes "nobody implements this" and "we could not tell whether
+ * anybody implements this" byte-identical, and the second one silently becomes
+ * a confident zero in `impact`. Consumers must not turn these into edges; they
+ * exist so a query can say it is answering with a lower bound.
+ */
+export interface UndecidedSatisfaction {
+    readonly interfaceDefId: string;
+    readonly interfaceName: string;
+    readonly filePath: string;
+    /** How many candidate types went unjudged for this interface. */
+    readonly undecidedCandidates: number;
+    /**
+     * The candidate types themselves, by name.
+     *
+     * Both sides are recorded because a query arrives from either one. Asking
+     * `impact` about the IMPLEMENTATION — the case #2873 reports — never touches
+     * the interface node at all: the walk starts at a method whose owner has no
+     * heritage edge precisely because the check was undecided, so an
+     * interface-keyed record alone would leave that query unhedged.
+     */
+    readonly candidateNames: readonly string[];
+}
+/** What `detectInterfaceImplementations` answers: the positives, plus the
+ *  questions it could not answer. */
+export interface StructuralImplementationResult {
+    readonly implementations: Map<string, readonly StructuralImplementor[]>;
+    readonly undecided: readonly UndecidedSatisfaction[];
+}
 export interface ScopeResolver {
     /** Identity for telemetry + per-language flag check. */
     readonly language: SupportedLanguages;
@@ -331,6 +391,12 @@ export interface ScopeResolver {
      * when a PSR-4 import names a function instead of a file.
      */
     resolveImportTarget(targetRaw: string, fromFile: string, allFilePaths: ReadonlySet<string>, resolutionConfig?: unknown, context?: ImportResolutionContext): string | readonly string[] | null;
+    /**
+     * Optionally reclassify an import as a namespace handle after target
+     * resolution proves the imported name is itself a module. Returning false
+     * retains ordinary named-binding behavior.
+     */
+    readonly isNamespaceImport?: (parsedImport: ParsedImport, targetFile: string, fromFile: string) => boolean;
     /**
      * Enumerate names visible through a wildcard import after the target
      * module scope has been linked. Languages that do not support
@@ -456,9 +522,19 @@ export interface ScopeResolver {
      * shape. Must be idempotent (the orchestrator may call it more than once
      * during re-resolution).
      *
+     * `recordTypeArguments` is the same sink `preEmitInheritanceEdges` writes to:
+     * the generic INSTANTIATION a heritage clause was written with, so
+     * interface-dispatch fan-out can refuse an implementor of an incompatible one
+     * (#2912). An implementation that emits an edge for a generic base
+     * (`impl Validator<String> for V`, `class V implements Validator<String>`)
+     * should call it with the same (source, target) graph ids it just used;
+     * anything not recorded reads as "unknown" and keeps the pre-#2912 fan-out.
+     * Ignoring it entirely is correct for a language whose heritage carries no
+     * type arguments (Ruby `include`).
+     *
      * Default: undefined (no extra heritage edges needed).
      */
-    readonly emitHeritageEdges?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, scopes?: ScopeResolutionIndexes) => void;
+    readonly emitHeritageEdges?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, scopes?: ScopeResolutionIndexes, recordTypeArguments?: HeritageTypeArgumentSink) => void;
     /**
      * Optional hook to emit IMPORTS edges that no syntactic import
      * statement produces. Some languages grant files implicit visibility
@@ -610,19 +686,56 @@ export interface ScopeResolver {
      */
     readonly fieldFallbackOnMethodLookup?: boolean;
     /**
-     * Unwrap a property-style collection accessor on a typed receiver
-     * to its element type. Called by `resolveCompoundReceiverClass`
-     * when walking dotted member-access chains of the form
-     * `receiver.Accessor`. The provider returns the element type's
-     * simple name, or `undefined` when the accessor doesn't unwrap —
-     * in which case the regular field-walk resumes.
-     *
-     * Use this only for languages that expose collection views as
-     * properties rather than method calls; languages whose collection
-     * views are `.values()` / `.keys()` method calls leave this
-     * undefined and let the normal call-expression branch handle them.
+     * Element type of a container, reached either by a subscript (`repos[0]`) or
+     * by a property-style collection view (`dict.Values`). Returns the element
+     * type's simple name, or `undefined` when the container does not unwrap by
+     * that route — in which case the caller resumes its normal walk.
+     *
+     * ONE hook for both routes, deliberately. They were previously two
+     * (`unwrapCollectionAccessor` for the property route, `unwrapCollectionElement`
+     * for the subscript route), which meant a language implementing one silently
+     * got nothing for the other: C# parsed `Dictionary<K,V>` for `.Values` but
+     * returned nothing for `list[0]`, and TypeScript did the reverse. Two entries
+     * answering one question, each accreting an implementation per language.
+     *
+     * `via` carries the route so a provider can distinguish them where it matters
+     * (a `Dictionary` yields its VALUE type by subscript but either type by
+     * accessor name); a provider that does not care can ignore it.
+     *
+     * Consulted ONLY where the source actually performed the access. It is NOT a
+     * general type-name normalizer: unwrapping a container at a bare class lookup
+     * would let `repos.find(x)` fold to `Repo.find`, because a container's member
+     * set is not its element's. For the same reason it is deliberately separate
+     * from `stripTypePreservingDecoration`: a pointer or a nullable leaves the
+     * member set unchanged and is safe to strip at the lookup; a container is not.
+     *
+     * ## The `index` route is REQUIRED, and `undefined` means "not a container"
+     *
+     * A language that leaves the `index` route unanswered gets NO index folding —
+     * the structural fold declines the step rather than passing the position
+     * through. That is not a default worth softening. `undefined` used to mean
+     * "fall back to identity", on the theory that a capture layer which already
+     * reduced the container (Go's `normalizeGoTypeName`, C#/TypeScript's
+     * `stripGeneric`) leaves nothing to unwrap. The theory holds for a container;
+     * it is false for an ordinary class the source happened to subscript, and
+     * `rawName` cannot tell those apart — `repos: User[]` and `grid: Grid` both
+     * arrive as a bare resolvable class name. Identity there typed `grid[0].run()`
+     * as `Grid.run` and `t[0].Render()` as `Table.Render`: a wrong owner, which
+     * this pipeline ranks strictly below a missing edge.
+     *
+     * The hook is therefore handed `TypeRef.declaredSpelling` — the annotation AS
+     * WRITTEN, retained by the scope extractor precisely because capture-time
+     * normalization destroys it — falling back to `rawName` only when nothing was
+     * normalized away. So a provider sees `User[]`, `List[User]`, `[]*User` or
+     * `Dictionary<string, User>`, never the post-reduction `User`, and answering
+     * `undefined` for a spelling it does not recognize as a container is an
+     * ANSWER, not an absence.
+     *
+     * Implementations may return a still-DECORATED element name (Go's `[]*User`
+     * yields `*User`): the index step looks the element up through
+     * `stripTypePreservingDecoration`, so the pointer resolves.
      */
-    readonly unwrapCollectionAccessor?: (receiverType: string, accessor: string) => string | undefined;
+    readonly elementTypeOf?: (containerType: string, via: ElementAccessRoute) => string | undefined;
     /**
      * Collapse member-call CALLS edges by `(caller, target)` rather
      * than per-site. Default `false` — scope-resolution's contract
@@ -667,6 +780,57 @@ export interface ScopeResolver {
      * Swift — opt in.
      */
     readonly constructorCallTargetsClass?: boolean;
+    /**
+     * How this language spells a construction expression, so the compound
+     * receiver resolver can type an INLINE constructor receiver — the
+     * `Service(db).do_work()` shape, where the receiver is the constructed
+     * value itself rather than a binding that holds it (#2708).
+     *
+     * The rule is the same in every language ("constructing a class yields
+     * an instance of that class"); only the surface syntax differs, so the
+     * syntax is declared here and the rule lives once in
+     * `resolveCompoundReceiverClass`:
+     *
+     *   - `bare: true`      — `Service(db).m()`     (Python)
+     *   - `keyword: 'new'`  — `new Service(db).m()` (JS/TS, C#)
+     *   - `selector: 'new'` — `Service.new.m()`     (Ruby)
+     *
+     * Java is deliberately NOT wired even though it spells construction with
+     * `new`: its capture layer already rewrites an `object_creation_expression`
+     * receiver to the constructed type's simple name (#2564), so the raw
+     * `new Svc()` text never reaches this resolver and the declaration would be
+     * unreachable. Measured both ways — Java resolves the shape identically with
+     * and without it.
+     *
+     * Opting in is per-language ON PURPOSE rather than universal, for two
+     * reasons. Correctness: `bare` would mistype `stat(&st).field` in C,
+     * where a struct and a function may share a name and the free call is
+     * NOT a construction. Evidence: PHP, Swift, Dart and Kotlin already
+     * resolve this shape through their own capture-side paths (verified
+     * per language — the receiver typing here changed nothing for them),
+     * so they stay unwired rather than carrying a redundant declaration.
+     *
+     * Only affects receiver TYPING. Which node a construction call links
+     * to is a separate question, owned by `constructorCallTargetsClass`.
+     * Path-syntax constructors (Rust `Foo::new(x)`) are not covered — they
+     * are not member calls and never reach this resolver.
+     */
+    readonly constructionSyntax?: {
+        /** A free call naming a class constructs it: `Service(db)`. */
+        readonly bare?: boolean;
+        /** Prefix keyword form: `new Service(db)`. */
+        readonly keyword?: string;
+        /** Member-selector form on the class itself: `Service.new(db)`.
+         *  Applies only when the receiver names the CLASS — `factory.new` is an
+         *  ordinary call to a member named `new` on an instance and keeps normal
+         *  member resolution. KNOWN LIMITATION: a class that OVERRIDES the
+         *  selector at class level (Ruby `def self.new` returning some other
+         *  type) is still read as construction, because the scope model records
+         *  no staticness for a member, so `def new` and `def self.new` are
+         *  indistinguishable here. Modelling that needs per-member staticness
+         *  from the language provider first. */
+        readonly selector?: string;
+    };
     /**
      * Optional per-slot conversion-rank function for overload resolution.
      * When provided, `narrowOverloadCandidates` uses ranked scoring as a
@@ -750,6 +914,24 @@ export interface ScopeResolver {
      * receiver class is a dispatch candidate).
      */
     readonly isStaticOnly?: (def: SymbolDefinition) => boolean;
+    /**
+     * Optional canonicalizer for a written GENERIC TYPE ARGUMENT, so two
+     * spellings of one type compare equal during interface-dispatch
+     * instantiation matching (#2912).
+     *
+     * The case it exists for is a language with predefined ALIASES: C# `string`
+     * and `String` are the same type, so `IValidator<string>` must still fan out
+     * to `class V : IValidator<String>`. Without the hook the two spellings look
+     * like two instantiations and the implementor is pruned — a missing edge,
+     * which is the failure direction #2912 is most concerned to avoid.
+     *
+     * Called ONLY on the two sides of one argument comparison, never on a name
+     * used for lookup, so it may map to whatever canonical form the language
+     * prefers (`string` → `String`, or the reverse) as long as it is consistent.
+     * Languages whose types have one spelling each leave it undefined and the
+     * comparison stays exact.
+     */
+    readonly normalizeTypeArgument?: (name: string) => string;
     /**
      * Optional predicate to gate free-call fallback emission by caller-side
      * visibility. When provided, `pickUniqueGlobalCallable` rejects candidates
@@ -803,6 +985,39 @@ export interface ScopeResolver {
             readonly startCol: number;
         };
     }, callerParsed: ParsedFile, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[]) => readonly SymbolDefinition[] | undefined;
+    /**
+     * Optional resolver for a module-qualified FREE call — a call written with
+     * an explicit path but no value receiver (Rust `tools::dispatch(...)`, where
+     * `tools` names a module, not a variable or a type).
+     *
+     * These sites are captured as free calls (`callForm === 'free'`) with the
+     * written path preserved in `site.rawQualifiedName`. Without this hook the
+     * qualifier is inert and the scope-chain walk resolves the bare tail name —
+     * which silently binds to a same-named definition in the CALLER's own file
+     * when one exists, producing a self-loop and dropping the real cross-module
+     * edge (#2730: `fn dispatch` in `sched.rs` calling `tools::dispatch`
+     * resolved to itself, so `impact` reported the central dispatcher as
+     * risk LOW with 0 affected processes).
+     *
+     * `emitFreeCallFallback` invokes this BEFORE the implicit-`this` and
+     * scope-chain lookups, so an explicit path outranks a lexical shadow.
+     * Returning `undefined` (unqualified call, unknown module, or no such
+     * member in the named module) falls through to the unchanged chain — the
+     * hook is strictly additive and never removes an edge the prior tiers
+     * would have produced.
+     *
+     * Languages whose qualified calls carry a value/type receiver (`x.foo()`,
+     * `Type::foo()`) are served by the receiver-bound-calls pass and leave
+     * this undefined.
+     */
+    readonly resolveQualifiedFreeCall?: (site: {
+        readonly name: string;
+        readonly rawQualifiedName?: string;
+        /** Needed to locate the calling MODULE, not just the calling file — a
+         *  relative anchor (`super::`) is resolved against the module the call
+         *  sits in, which may be an inline `mod` block inside that file. */
+        readonly inScope: ScopeId;
+    }, callerParsed: ParsedFile, scopes: ScopeResolutionIndexes, workspaceIndex: WorkspaceResolutionIndex, allFilePaths: ReadonlySet<string>) => SymbolDefinition | undefined;
     /**
      * Optional resolver for qualified-receiver member calls where the
      * receiver is a namespace (not a class) and ordinary scope-chain /
@@ -821,6 +1036,40 @@ export interface ScopeResolver {
      * `undefined` to fall through to the remaining cases.
      */
     readonly resolveQualifiedReceiverMember?: (receiverName: string, memberName: string, callerScope: ScopeId, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[], callsite?: Callsite) => SymbolDefinition | 'ambiguous' | undefined;
+    /**
+     * Every receiver spelling under which a namespace import's target is
+     * reachable, and the file each spelling names (#2826). Returning
+     * `undefined` keeps the shared default: the local binding name alone,
+     * mapped to the edge's own target file.
+     *
+     * Python needs this because one `import a.b.c` statement binds THREE
+     * spellings at once — `a`, `a.b` and `a.b.c` — each naming a DIFFERENT
+     * file (`a/__init__.py`, `a/b/__init__.py`, `a/b/c.py`), while
+     * `ImportEdge` carries only the leaf. The default keyed `a` (its
+     * `localName`) to the LEAF, so `a.helper()` resolved into `a/b/c.py`
+     * whenever that module happened to export `helper` — a wrong edge — and
+     * `a.b.mid()` resolved to nothing at all.
+     *
+     * Shared code cannot derive this. Swift's `import Foo.Bar` produces an
+     * edge shape identical to Python's (`localName: 'Foo'`,
+     * `targetExportedName: 'Foo.Bar'`), yet there the FIRST segment is the
+     * resolved target and `Foo.Bar` names a nested TYPE; keying it would hand
+     * `resolveConstructionExpressionClass` an authoritative namespace — that
+     * branch deliberately does not fall through on a miss — and break
+     * `Foo.Bar(x)` construction that resolves correctly today. And the
+     * `__init__.py` convention that turns a dotted prefix into a file is
+     * Python's alone.
+     *
+     * `moduleFileExists` reports whether a path is a module the workspace
+     * actually parsed, so a provider can propose a prefix file and have it
+     * dropped when absent (a PEP-420 namespace package has no `__init__.py`)
+     * rather than minting a key to a file that is not there.
+     */
+    readonly namespaceReceiverPaths?: (edge: {
+        readonly localName: string;
+        readonly importPath: string;
+        readonly targetFile: string;
+    }, moduleFileExists: (filePath: string) => boolean) => readonly (readonly [spelling: string, targetFile: string])[] | undefined;
     /**
      * Optional language-specific member-lattice lookup. Runs for a resolved
      * simple receiver type before the generic flattened-MRO walk. Languages
@@ -887,6 +1136,38 @@ export interface ScopeResolver {
      * level bindings.
      */
     readonly hoistTypeBindingsToModule?: boolean;
+    /**
+     * Strip ONE layer of type-preserving decoration off a declared type name,
+     * or return `undefined` when there is nothing left to strip.
+     *
+     * Exists because a declared type is stored as written. Go's
+     * `synthesizeGoReceiverBinding` keeps `typeNode.text`, so a pointer-receiver
+     * method binds its receiver to the literal `*Host` — which matches no class
+     * binding, so receiver-chain resolution declines at the base and every
+     * `h.field.method()` in the dominant Go idiom loses its `CALLS` edge (#2766).
+     * The stored binding is deliberately left decorated (`method-owners.ts`
+     * consumes `*T` vs `T` to model Go's value and pointer method sets), so the
+     * normalization belongs at LOOKUP, never as a rewrite of the binding.
+     *
+     * TYPE-PRESERVING ONLY. Pointer, reference, `const`, nullable, borrow,
+     * deref-transparent smart pointer and sigil all leave the member set
+     * unchanged. A CONTAINER — array, slice, map, `Option` — does not: stripping
+     * one here would type `repos: Repo[]` as `Repo` and let `repos.find(x)` fold
+     * to `Repo.find`, a confident wrong edge the ambiguity gate cannot catch
+     * because `Repo` binds uniquely. Containers are unwrapped only by an index
+     * step that consumed a subscript.
+     *
+     * Consulted ONLY after every undecorated lookup has failed, and only by
+     * receiver-chain base and step resolution — the shared class lookup keeps
+     * exact-name behaviour for its other ~two dozen callers, several of which are
+     * shaped `findClassBindingInScope(...) ?? otherResolver(...)` and would have
+     * their fallback suppressed by a global widening.
+     *
+     * Leave undefined for languages whose declared types carry no type-preserving
+     * decoration. Measured: only Go needs it for a receiver base; Rust, C#, Swift,
+     * TypeScript and C++ need it for field types.
+     */
+    readonly stripTypePreservingDecoration?: DecorationStripper;
     /**
      * Whether the compound-receiver resolver should strip C-style cast
      * expressions from receiver-position text before resolving it —
@@ -913,7 +1194,7 @@ export interface ScopeResolver {
      *
      * A second opting language must extend the classifier grammar or
      * convert this toggle into a per-language classifier hook (the
-     * `unwrapCollectionAccessor` pattern) — do not flip this flag for
+     * `elementTypeOf` pattern) — do not flip this flag for
      * another language as-is.
      *
      * Known non-goal: the compound-receiver options built from this
@@ -929,10 +1210,19 @@ export interface ScopeResolver {
      * Languages like Go use structural typing — a struct satisfies an
      * interface if its method set is a superset, without an explicit
      * `implements` keyword. Runs after finalize, before resolution passes.
-     * Returns: Map<interface_DefId, implementing_struct_DefId[]>.
+     * Returns: Map<interface_DefId, StructuralImplementor[]>, where each entry
+     * names the implementing type AND the form in which it implements.
+     *
+     * `receiverForm` is not a confidence signal — it is the language's own
+     * distinction. In Go the method set of `T` and of `*T` differ (a
+     * pointer-receiver method belongs only to `*T`), so `receiverForm: 'pointer'`
+     * means the VALUE type does not implement the interface and only `*T` does.
+     * `'value'` means both do. Consumers that only want blast radius can ignore
+     * it; consumers reasoning about assignability must not.
+     *
      * Default: undefined (no structural interface detection).
      */
-    readonly detectInterfaceImplementations?: (parsedFiles: readonly ParsedFile[], indexes: ScopeResolutionIndexes, model: SemanticModel) => Map<string, string[]>;
+    readonly detectInterfaceImplementations?: (parsedFiles: readonly ParsedFile[], indexes: ScopeResolutionIndexes, model: SemanticModel) => StructuralImplementationResult;
     /**
      * Optional: mirror typeBindings from namespace-import target modules
      * into the importer's module scope. Languages like Go use namespace

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.js

@@ -15,7 +15,7 @@
  *        - propagatesReturnTypesAcrossImports (default true)
  *        - fieldFallbackOnMethodLookup (default true — turn OFF for
  *          statically-typed languages; the heuristic over-connects)
- *        - unwrapCollectionAccessor — property-style collection views
+ *        - elementTypeOf — container element type, by subscript or accessor
  *        - collapseMemberCallsByCallerTarget — one edge per caller/target
  *        - populateNamespaceSiblings — cross-file implicit visibility
  *        - hoistTypeBindingsToModule — enable ONLY when method return
@@ -113,13 +113,24 @@
  *       3. Case 0.5 implicit-`this` chain walk — GATED: fires only for
  *          languages that set `resolveThisViaEnclosingClass === true`;
  *          it intercepts every bare-`this` call/read/write site ahead of
- *          Case 4 and does NOT emit Case 4's interface-dispatch fan-out,
- *          so enabling the toggle for a language changes that language's
- *          `this` dispatch semantics (see the toggle's doc below)
+ *          Case 4 and does NOT emit the interface-dispatch fan-out that
+ *          Cases 0, 3b and 4 all perform (Case 0 gained it in #2829 and
+ *          Case 3b in #2832, leaving 0.5 the only INSTANCE-receiver case
+ *          that folds or walks to a receiver type without fanning out.
+ *          Read that narrowly: Case 2 also walks an MRO and its binding
+ *          admits `Interface`, but its receiver IS the type name, so the
+ *          site is static dispatch and a fan-out would be wrong; Cases 3
+ *          and 5 resolve by direct lookup rather than a fold or MRO walk,
+ *          and no language is known to reach Case 3 with an Interface —
+ *          every one that could strips the namespace qualifier first,
+ *          sending it to Case 4), so enabling the toggle
+ *          for a language changes that language's `this` dispatch
+ *          semantics (see the toggle's doc below)
  *       4. Case 1 namespace-receiver
  *       5. Case 2 class-name receiver
  *       6. Case 3 dotted typeBinding for namespace prefix
- *       7. Case 3b chain-typebinding (compound resolver)
+ *       7. Case 3b chain-typebinding (compound resolver + interface-dispatch
+ *          fan-out on an Interface fold, #2832)
  *       8. Case 4 simple typeBinding (MRO walk + findOwnedMember)
  *     Reordering or merging cases changes resolution semantics. The
  *     numbering is part of the contract — keep the comments.

package/dist/core/ingestion/scope-resolution/graph-bridge/edges.d.ts

@@ -52,6 +52,9 @@ export declare function tryEmitEdge(graph: KnowledgeGraph, scopes: ScopeResoluti
         startCol: number;
     };
     readonly kind: string;
+    /** See {@link isPhantomCalleeRead}. Set by the extractor from the
+     *  language's `@reference.callee-position` marker; absent otherwise. */
+    readonly inCalleePosition?: boolean;
 }, targetDef: SymbolDefinition, reason: string, seen: Set<string>, confidence?: number, collapseByCallerTarget?: boolean, calleeCapture?: CalleeIdCaptureCtx): boolean;
 /**
  * Variant of `tryEmitEdge` that takes a pre-resolved target graph id
@@ -65,6 +68,15 @@ export declare function tryEmitEdge(graph: KnowledgeGraph, scopes: ScopeResoluti
  *
  * All other invariants of `tryEmitEdge` apply: dedup key shape, collapse
  * flag honoring, edge-type mapping, caller-id resolution.
+ *
+ * ONE deliberate exception: the {@link isPhantomCalleeRead} suppression is not
+ * applied here, because it keys on the target's node label and this entry point
+ * is handed an id rather than a def. Reachable only for a `read` site marked
+ * `inCalleePosition` whose receiver typed as an object-literal VALUE — a
+ * JS/TS-shaped registration. No language that sets the marker resolves through
+ * this bridge today (verified for Go, whose func-valued struct-literal fields
+ * resolve through the owned-member path instead). A language adding the marker
+ * must re-check this path.
  */
 export declare function tryEmitEdgeWithExplicitTargetId(graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, nodeLookup: GraphNodeLookup, site: {
     readonly inScope: ScopeId;

package/dist/core/ingestion/scope-resolution/graph-bridge/edges.js

@@ -14,6 +14,7 @@
  * (or TypeScript-specific, etc.) logic. The dedup key is
  * language-agnostic — no language needs to change it.
  */
+import { CALL_TARGET_TYPES } from '../../model/symbol-table.js';
 import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
 /**
  * Map a `Reference.kind` to a graph edge type. `import-use` is dropped
@@ -48,6 +49,38 @@ export function mapReferenceKindToEdgeType(kind) {
             return undefined;
     }
 }
+/**
+ * Is this read site a PHANTOM — a duplicate of the call happening beside it?
+ *
+ * Some languages' member-read capture also matches the callee of a member call,
+ * so `obj.f()` produces a `call` site on `f` AND a `read` site on `obj.f` at the
+ * same position (Go's `@reference.read` matches every `selector_expression`).
+ * The capture layer marks that second site `inCalleePosition` rather than
+ * dropping it, because the two cases it covers are indistinguishable there:
+ *
+ *   - tail resolves to a METHOD → phantom. The ACCESSES edge duplicates the
+ *     CALLS edge emitted for the same source position; suppress it.
+ *   - tail resolves to a FIELD  → genuine. `h.dep.Work()` where
+ *     `Work func() error` reads a func-typed struct field and calls the value
+ *     it holds. That read is the field's only ACCESSES evidence — keep it.
+ *
+ * Only the resolved target's kind separates them, which is why this decision
+ * lives at emission and not in any language's capture code. Sites without the
+ * marker are untouched, so a genuine method VALUE (`f := obj.method`) — never in
+ * callee position — keeps its read.
+ *
+ * "Invoked rather than read" is `CALL_TARGET_TYPES` — the canonical callable
+ * target set (`FREE_CALLABLE_TYPES` ∪ Method/Constructor), not a local copy. A
+ * hand-rolled `{Function, Method, Constructor}` silently omits `Macro` (C/C++)
+ * and `Delegate` (C#), the two labels that set exists to add, and drops the
+ * `satisfies` guard in `symbol-table.ts` that compile-enforces every free
+ * callable label against `LABEL_BEHAVIOR`.
+ */
+function isPhantomCalleeRead(site, targetDef) {
+    if (site.kind !== 'read' || site.inCalleePosition !== true)
+        return false;
+    return CALL_TARGET_TYPES.has(targetDef.type);
+}
 /**
  * Resolve caller + target to graph ids and emit the edge. Returns true
  * if the edge was emitted (not deduped, not skipped).
@@ -58,6 +91,11 @@ export function mapReferenceKindToEdgeType(kind) {
  * double-emit a resolution one of them already produced.
  */
 export function tryEmitEdge(graph, scopes, nodeLookup, site, targetDef, reason, seen, confidence = 0.85, collapseByCallerTarget = false, calleeCapture) {
+    // A read that only exists because it is the callee of the call beside it, and
+    // whose tail resolved to a callable, is that call restated as an access —
+    // checked first because it needs no id resolution.
+    if (isPhantomCalleeRead(site, targetDef))
+        return false;
     // Inheritance edges are emitted directly by `preEmitInheritanceEdges` (which
     // owns the enclosing-class caller and the EXTENDS-vs-IMPLEMENTS type), so this
     // generic bridge derives caller + edge type purely from the site.
@@ -110,6 +148,15 @@ export function tryEmitEdge(graph, scopes, nodeLookup, site, targetDef, reason,
  *
  * All other invariants of `tryEmitEdge` apply: dedup key shape, collapse
  * flag honoring, edge-type mapping, caller-id resolution.
+ *
+ * ONE deliberate exception: the {@link isPhantomCalleeRead} suppression is not
+ * applied here, because it keys on the target's node label and this entry point
+ * is handed an id rather than a def. Reachable only for a `read` site marked
+ * `inCalleePosition` whose receiver typed as an object-literal VALUE — a
+ * JS/TS-shaped registration. No language that sets the marker resolves through
+ * this bridge today (verified for Go, whose func-valued struct-literal fields
+ * resolve through the owned-member path instead). A language adding the marker
+ * must re-check this path.
  */
 export function tryEmitEdgeWithExplicitTargetId(graph, scopes, nodeLookup, site, targetGraphId, reason, seen, confidence = 0.85, collapseByCallerTarget = false, calleeCapture) {
     const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup, site.atRange);

package/dist/core/ingestion/scope-resolution/graph-bridge/ids.d.ts

@@ -20,23 +20,28 @@ import type { NodeLabel, ParameterTypeClass, ScopeId, SymbolDefinition } from '.
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import { type GraphNodeLookup } from '../graph-bridge/node-lookup.js';
 /**
- * Look up a `SymbolDefinition` in the graph node lookup.
+ * Labels that may legitimately ANCHOR a CALLS/ACCESSES edge as the
+ * source ("caller"). A Variable / Property can be the TARGET of an
+ * edge (e.g., a write-access to `user.name`), but it cannot be a
+ * caller — variables don't execute code, so attributing a call to a
+ * sibling Variable in the same scope produces nonsense edges like
+ * `Variable:create → Function:create` (which the simpleKey fallback
+ * in `resolveDefGraphId` then silently rewrites to
+ * `Function:create → Function:create`, a self-loop that doesn't exist
+ * in the source).
  *
- * Tries the type-prefixed fully-qualified key FIRST. That's the only
- * correct key when:
- *   - Two classes in the same file define a method with the same
- *     simple name (`class User: def save` + `class Document: def save`).
- *   - A top-level function and a class method share a simple name
- *     (`def save` + `class User: def save` — the Function's qualifier
- *     is just `save`, which would alias the Method's simple-key slot
- *     without the type prefix).
- *
- * Falls back to the simple name for definitions whose qualifier the
- * lookup didn't capture (rare, but keeps cross-file simple-name
- * resolution working for languages that don't yet synthesize
- * qualifiers).
+ * Module-level call expressions inside a `const X = expr(args)`
+ * declaration are the canonical case where this used to fail: the
+ * walk-up over module scope's ownedDefs (only Variables) would land
+ * on the FIRST Variable, get name-aliased to its sibling Function
+ * with the same simple name, and emit a self-CALLS. With this label
+ * restricted to function/class-likes, those calls correctly fall
+ * through to the File-node fallback at the bottom of the walk.
  */
+export declare const CALLER_ANCHOR_LABELS: ReadonlySet<NodeLabel>;
 export declare function resolveDefGraphId(filePath: string, def: {
+    /** Scope-resolution def id — carries the declaration position (#2699). */
+    nodeId?: string;
     qualifiedName?: string;
     type?: NodeLabel;
     parameterTypes?: readonly string[];
@@ -51,7 +56,7 @@ export declare function resolveDefGraphId(filePath: string, def: {
 export declare function simpleQualifiedName(def: SymbolDefinition): string | undefined;
 /**
  * Walk the scope chain from `startScope` upward looking for the first
- * scope whose `ownedDefs` contains a Function/Method/Class — that's
+ * scope whose `ownedDefs` contains a callable or class-like anchor — that's
  * our caller anchor. Translate via `nodeLookup` to the graph-node ID.
  *
  * Module-level references (e.g. Python `u = models.User()` at top