GitNexus/docs/languages/local-import-scoping.md

Local import scoping

GitNexus resolves statically known local imports through their lexical owner and actual declaration identity. A nearer name that is unresolved, unavailable, or noncallable blocks an unrelated outer or workspace fallback. An absent name can continue through the existing lookup rules. This is static analysis: it does not execute loaders or infer arbitrary runtime initialization order.

Shared contract

Language rules stay in providers. The shared name-claim lookup distinguishes absent, blocked, and resolved before filtering by target kind. Its regressions cover noncallable barriers, unresolved imports, type/value lookup, declaration positions, and inferred aliases that retain their initializer's lookup position. Calls, constructors, receiver/type inference, inheritance, namespace lookup, and fallback consumers use these ownership facts rather than independently choosing a same-named symbol.

Ownership and inferred type facts are separate. For providers that mark their name claims complete, an assignment-inferred or constructor-inferred fact does not declare a name. Lookup continues to the actual declaration, import, or shadowing barrier. Providers without complete claims retain their existing ownership rules.

The shared records carry ownership, activation positions, directive destinations, and lookup purpose as serializable data. They retain declaration identity and ambiguity; they contain no AST nodes or callbacks. For imports, declaredAtScope records lexical location independently of runsOnlyWhenCalled, which describes deferred execution. On a TypeRef, declaredAtScope anchors type-name lookup where the annotation or inference was written; it can differ from the binding's owner. A function-local Rust use or C #include is not deferred merely because of its position; Python and Ruby loading can be. The function-local import chain tests pin that distinction.

Providers with expanded lexical support

These seven entries are part of the 18-provider registry. The evidence links cover exact targets and negative cases, not just edge counts.

Provider	Supported behavior	Source and regression evidence
Python	Function-local named, aliased, and namespace imports; compiler-local ownership; ordered class lookup; global/nonlocal destinations.	Lexical facts, local imports, namespace semantics
TypeScript	Literal genuine require, immediately awaited import, and import-equals; namespace, named, and renamed bindings; type/value separation.	Loader collector, loader tests, type ownership
JavaScript	The same supported runtime loaders and lexical barriers, using JavaScript captures for JS/JSX.	Captures, JS/JSX loader cases
Vue	Local loader facts in extracted scripts, with original declaration graph positions preserved. Explicit JS/JSX uses its own semantic grammar inside the worker; TS reuses the cached tree.	Script delegation, direct/pre-extracted parity, real workers
Rust	Lexical use, producer identity for imported factories/types, and Cargo-aware crate/module identity. Unresolved explicit imports block unrelated fallback.	Lexical facts, import targets, local scope, Cargo boundaries
C++	Position-sensitive local using declarations/directives, separate from includes; propagated header claims retain unresolved named using barriers.	Captures, local using, header using
Zig	Literal @import namespace/member bindings, block activation, container hoisting, stable deep aliases, and inline @import receivers.	Captures, local imports, static gating

Python boundaries

Compiler-local binders include parameters, assignment patterns, loop/with/except targets, match captures, augmented assignment, deletion, and comprehension/walrus bindings. Comprehension targets do not leak, and the first iterable is evaluated outside the comprehension environment. Class bodies use ordered locals; methods skip class locals for bare-name lookup while explicit instance receivers remain available. Annotation-only declarations distinguish compiler ownership from a runtime store. These cases are characterized in the Python local-import tests.

Mixed import/value rebinding and conflicting import identities conservatively abstain throughout the environment, including simple sequential rebinding; this is not a control-flow evaluator. A definite def/class declaration can still supply its own target after activation. The provider policy and rebinding regressions define this boundary. There is no full annotation evaluator, exec evaluation, or general closure scheduling model. A deferred global/nonlocal installer is not assumed to have executed for unrelated callers.

Conditional imports with one compatible identity remain available for structural reference resolution, including TYPE_CHECKING annotations and try imports. Their runtime execution is not guaranteed by a resolved graph edge.

Default expressions look up names in the enclosing environment. FastAPI's synthetic dependency graph caller is recorded separately as callerScope; it does not move lexical lookup into the handler body. Both direct extraction and worker transport check this distinction.

JavaScript-family boundaries

Loader recognition checks AST shape and binding identity, including parameters, catch/destructuring bindings, temporal-dead-zone ownership, and writes to the loader or imported handle. CommonJS forwarding uses that same identity check. Reassigning one destructured import leaves unchanged sibling re-exports intact. Writes to ordinary locals retain their declared type and callable-value facts. Unawaited dynamic imports remain Promise/file-dependency facts rather than module namespace aliases. Computed specifiers, indirect loader/Promise chains, and unsupported destructuring remain unresolved; see the loader regressions.

Receiver type precedence

A constructor assignment inside a closure does not make that closure the owner of the assigned name. Lookup may retain the nearest constructor fact on its path to the owner when the owner has no type fact or only an inferred or propagated fact. It keeps the complete selected TypeRef, including the scope, position, and namespace in which its type name must resolve.

The owner's annotation, parameter annotation, return annotation, self, or decorator fact takes precedence. For example, assigning new Foo() to a parameter annotated Base inside a closure leaves receiver lookup anchored to Base, including its inherited methods. Same-scope precedence and METHOD_OVERRIDES relationships retain their existing rules. A nested write is not promoted into an unconditional type fact for reads outside that closure. These are static inference rules, not control-flow narrowing or a prediction of the receiver's runtime class. The type ownership regressions and shared lookup regressions cover declaration ownership, fact precedence, and retained lookup anchors.

HTTP provenance

Express route receivers and fetch-wrapper analysis share per-file lexical bindings. They track declaration identity across closures and check identity at each use; an unrelated same-named declaration in a sibling scope does not invalidate a binding. Writes to the tracked binding do invalidate its provenance. For a forwarded Express parameter, an initialized var redeclaration or a body function declaration is a write, while an uninitialized var declaration alone preserves the parameter value. See the route provenance regressions.

Automatic fetch-wrapper detection requires evidence of platform fetch. Bare fetch must be unshadowed; globalThis.fetch, window.fetch, and self.fetch require an unshadowed global root. Unresolved or blocked local names are not globals. An injected fetch parameter alone is not evidence. A default such as fetch = globalThis.fetch supplies potential platform evidence, not a guarantee that callers use that default. A self-referential fetch = fetch default or a locally shadowed globalThis does not supply it. Stable aliases retain this provenance by binding identity.

Nested callable bodies contribute only when reachable from the function's evaluated code through resolved binding references. Unused self-recursive or mutually recursive helpers do not prove a wrapper. IIFEs, inline callbacks, and directly escaping anonymous functions participate; a named stored helper needs a reachable reference. Class heritage, computed keys, static fields, and static blocks participate during class evaluation. Methods and instance fields remain deferred until the class binding is referenced from reachable code. This is a conservative approximation of potential execution: reading or returning a function does not execute its body, and referencing a class does not establish that every method runs. The wrapper provenance cases cover these boundaries.

Bare wrapper calls and forwarded calls resolve declaration or import identity before using name fallback. Relative imports, renamed imports, tsconfig aliases, and workspace imports use the project module resolver. A known local non-wrapper, a different resolved target, or an ambiguous target blocks fallback. An unresolved name can fall back only when exactly one distinct definition can be the target, including non-wrappers, and that definition is a proven wrapper. For an import the resolver cannot follow, the candidates are module-level functions exported under the imported name; for an undeclared global, they are top-level functions of that name. Nested and unexported helpers are never candidates. This fallback is an analyzer recovery heuristic; it does not prove lexical identity. A function whose binding is reassigned in its file, including through export { request as send }; request = other; or a later var request = … initializer, proves no wrapper in importing files either. Explicit fetchWrappers configuration takes precedence over automatic inference, including for names shadowed by local parameters; member calls retain their existing matching rules. See the wrapper consumer integration tests and configured wrapper tests.

The scope model does not represent separate parameter and body environments. When formals contain expressions, including nested defaults or computed pattern keys, HTTP inference therefore declines an affected binding if a body var or function declaration shares a parameter's name or a binding referenced by a parameter expression. Declarations inside nested functions do not count as outer body declarations; a rest parameter alone is not a parameter expression. The lexical binding tests pin this conservative boundary. If scope extraction fails, scope-dependent HTTP facts are omitted and the existing scope-extraction failure remains visible; unrelated structural extraction continues. A failing HTTP hook drops only that file's HTTP facts. Either way the file's function names are still recorded, so name fallback elsewhere declines instead of treating another definition as unique.

Barrels follow ECMAScript ResolveExport. A local or named export shadows export *, star exports never carry default, and a name that two star-exported modules export as different bindings is ambiguous, whether or not either is a wrapper. Two export names of one declaration are one binding.

Some recall is given up deliberately. A helper that conditionally rebinds its parameter, as in if (!app) { var app = express(); }, loses that parameter's provenance: the initialized var is a write. A dynamic-import shim such as (...args) => import('node-fetch').then(...) is not platform fetch evidence. A write to the URL parameter clears URL forwarding. Calls inside recovered syntax are still resolved, but nothing else inside an ERROR node is trusted.

Vue's explicit JS/JSX script requires an additional bounded semantic parse because the worker's structural tree uses TypeScript. That parse runs inside the real worker. The parity test witnesses returned worker facts; a main-thread fallback does not satisfy it.

Rust, C++, and Zig boundaries

Rust uses Cargo editions, target roots, and module identities, including files with multiple valid identities. Reusable per-analysis indexes bound repeated lookup work; this is not a claim of a global indexing speedup. See Cargo metadata and its tests. Exact same-name inline pub use forwarding is supported. A forwarding alias that changes symbol spelling through a file-only target conservatively remains unresolved; ambiguous same-file homonyms and re-export cycles cannot select an unrelated declaration. These limits are explicit in the Cargo fallback regressions. Inferred receiver types retain their receiving declaration range. When same-block shadowing replaces a retained type fact, earlier uses cannot consume the later declaration's type and may remain unresolved; this is not full SSA inference. See the factory ownership regressions.

C++ includes keep their compilation-unit behavior alongside lexical using. The header tests cover literal includes, declaration positions, unresolved named using claims, and overload identity. They do not establish a full preprocessor, namespace-alias evaluator, or arbitrary transitive using namespace chain support. Zig nonliteral imports remain unresolved; its block-local names do not escape or activate before their declarations.

Retained provider behavior

The other eleven providers retain their existing import/loading models. This work does not reinterpret every dependency construct as a local value import.

Provider	Retained model and boundary	Evidence
Ruby	Wildcard loading; method-local loading is deferred. The extractor recognizes string arguments to require, require_relative, and load. The linked behavioral tests establish require/require_relative and deferral, not arbitrary load execution.	Extractor, loading, deferral
PHP	Namespace use imports are distinct from closure capture and trait use. The scope provider does not propagate names through include/require.	Query, ownership, resolver coverage
C	Header includes remain preprocessor/compilation-unit dependencies, including includes written inside functions; no full preprocessing is added.	Include interpretation, include tests, deferral boundary
Objective-C	Headers, modules, and compilation-unit siblings retain the dedicated provider rules.	Provider guide, resolver, workspace tests
COBOL	COPY stays on the dedicated copybook path with module ownership.	Interpretation, COPY target parity
Go	File imports and package sibling visibility retain separate provider rules.	Import ownership, imports, package siblings
Java	Imports belong to the compilation unit.	Ownership, named/wildcard import resolution
Kotlin	File import headers retain their existing alias/package resolution.	Header decomposition, resolver tests
C#	Namespace/file using directives remain imports; resource using statements are not import directives.	Directive query, import tests
Swift	Imports and target/module visibility retain provider ownership.	Ownership, import decomposition, target siblings
Dart	Library imports retain existing package identity and visibility rules.	Ownership, library/package regressions

Taint provenance

Taint source, sink, and sanitizer matching uses the same lexical provenance. A genuine external import may match its raw module name even when that package has no indexed source. A sibling import, local shadow, or type-only import cannot authorize that match. General copied-handle tracking is outside this support. The taint regressions cover extraction, emission, and function summaries, including abstention when exact call-site positions are missing.

Cache migration and verification evidence

Parser compatibility uses automatic artifact-derived identities, not manually assigned semantic counters. The worker-result cache and durable ParsedFile store validate the same base identity and include it in their chunk keys. PDG-enabled chunks also include the PDG identity and resolved function-line cap. Legacy numeric, missing, malformed, or foreign identities cause a cache miss and rebuild; compatible records remain eligible for reuse. If identity verification fails, analysis uses a transient store without persistent cache reads or writes.

Parser contributors update no counter or generated digest. The identity tests, input-coverage tests, and lifecycle tests cover the compatibility gates. Source changes invalidate identity immediately, but compiled workers still need npm run build in gitnexus/ before verification.

Cached wrapper import facts retain raw specifiers and imported names. Each analysis resolves them against the current project configuration, including on warm runs, so a changed tsconfig alias does not retain a stale wrapper target. The wrapper persistence tests cover raw cache transport, warm reuse, and alias changes.

The real-worker parity suite witnesses worker boot, dispatch, and returned ParsedFiles, then compares complete provider facts with direct extraction, including callerScope and C++ side-channel data. Optional grammar availability is explicit in the test gate.

The persistence suite loads both stores afresh from disk. Its parse-cache chunks contain no embedded ParsedFiles, so warm equality requires durable-store reuse. It checks identical CALLS/IMPORTS identities with zero extraction and zero worker dispatch on an unchanged warm run. Editing a local import target or shadowing require removes the stale target, and a second warm run preserves the edited graph.

Both suites are in the cross-platform manifest; the shard regression ensures each is selected exactly once across the four Windows/macOS shards. CI owns native execution on those systems; Ubuntu's full suite discovers the tests normally. These are focused evidence boundaries, not a statement that the final full suite or every platform has passed.

Related Python ownership behavior

The nested declaration ownership fix in #3502 for the original #3499 case and the aliased package re-export fix in #3504 remain part of Python's provider rules. Their Python integration coverage and module namespace coverage remain relevant. Lexical ownership does not model all dynamic Python behavior.