GitNexus/type-resolution-system.md

Type Resolution System

GitNexus's type resolution system maps variables to likely declared types across the supported languages so the ingestion pipeline can perform receiver-constrained call resolution.

When the code contains a call such as user.save(), the resolver tries to determine that user is a User, allowing call resolution to prefer User#save over unrelated methods such as Repo#save.

This system is designed to be:

• Conservative — it prefers missing a binding over introducing a misleading one
• Single-pass — bindings are collected during a single AST walk, with a limited post-pass for assignment propagation
• Scope-aware — function-local bindings are isolated from file-level bindings
• Per-file — the environment is built for one file at a time, though it may consult the global SymbolTable for validation in specific cases

It is not a full compiler type checker. Its job is to recover enough type information to improve call-edge accuracy during ingestion.

---

Purpose in the Pipeline

Type resolution sits between parsing and call resolution.

parse-worker.ts
     │
     ▼
buildTypeEnv(tree, language, symbolTable?)
     │
     ├──► TypeEnvironment.lookup(varName, callNode)
     │         │
     │         ▼
     │    call-processor.ts
     │    - resolves receiver type for method calls
     │    - filters candidates by receiver match
     │    - verifies deferred constructor / initializer bindings
     │
     └──► discarded after file processing

The TypeEnvironment is built once per file. call-processor.ts then uses lookup() to determine receiver types and narrow candidate symbols from the SymbolTable.

---

Architecture

                                 ┌──────────────────────┐
                                 │     type-env.ts      │
                                 │                      │
                                 │  buildTypeEnv()      │
                                 │  - Single AST walk   │
                                 │  - Scope tracking    │
                                 │  - Tier orchestration│
                                 └──────────┬───────────┘
                                            │ dispatches to
                    ┌───────────────────────┬┴┬────────────────────────┐
                    │                       │ │                        │
          ┌─────────▼──────────┐  ┌─────────▼─▼─────────┐  ┌──────────▼─────────┐
          │   shared.ts        │  │  <language>.ts      │  │    types.ts        │
          │                    │  │                      │  │                    │
          │  Container table   │  │  Per-language        │  │  Extractor         │
          │  Type helpers      │  │  extractors          │  │  interface defs    │
          │  Generic helpers   │  │  (shared + per-lang) │  │                    │
          └────────────────────┘  └──────────────────────┘  └────────────────────┘

Main files

File	Purpose
type-env.ts	Core engine. Walks the AST once, tracks scopes, collects bindings, and exposes buildTypeEnv() plus the TypeEnvironment interface.
types.ts	TypeScript interfaces for extractor hooks such as TypeBindingExtractor, ForLoopExtractor, and PatternBindingExtractor.
shared.ts	Language-agnostic helpers such as extractSimpleTypeName, extractElementTypeFromString, resolveIterableElementType, CONTAINER_DESCRIPTORS, and TYPED_PARAMETER_TYPES.
index.ts	Dispatch map from SupportedLanguages to LanguageTypeConfig.
typescript.ts	TypeScript and JavaScript extractors, including JSDoc support.
jvm.ts	Java and Kotlin extractors.
csharp.ts	C# extractors.
go.ts	Go extractors, including range semantics.
rust.ts	Rust extractors, including if let, match-related handling, and Self resolution.
python.ts	Python extractors, including match / case handling.
php.ts	PHP extractors, including PHPDoc support.
ruby.ts	Ruby extractors, including YARD support.
swift.ts	Swift extractors. Currently the most minimal configuration.
c-cpp.ts	Shared C / C++ extractors.

---

Supported Languages

The current type-resolution layer supports 13 languages:

• TypeScript
• JavaScript
• Python
• Java
• Kotlin
• C#
• Go
• Rust
• PHP
• Ruby
• Swift
• C
• C++

Not all languages have the same level of coverage. Swift remains the most minimal. C and some C++ cases naturally benefit less from receiver typing than object-oriented languages.

---

Design Constraints

The type resolution layer is intentionally narrower than a compiler-grade type system.

It does:

• resolve variable types from declarations, parameters, initializers, loops, and selected pattern constructs
• normalize common wrappers such as nullable types and generic containers
• improve receiver matching during call resolution
• verify some ambiguous initializer bindings against the SymbolTable

It does not:

• perform full semantic type checking
• run fixpoint inference
• propagate inferred bindings across files as ordinary environment entries
• model deep field/property chains such as user.address.city
• guarantee resolution for every ambiguous construct

---

TypeEnvironment Model

buildTypeEnv() returns a TypeEnvironment that contains:

• scoped bindings collected from the current file
• deferred constructor / initializer binding candidates
• lookup helpers used by call resolution
• pattern override data for branch-local narrowing where supported

Scope model

The environment is scope-aware so identical variable names in different functions do not collide.

File scope ('')
├── config → Config
├── users → Map
│
├── processUsers@100
│   ├── user → User
│   └── alias → User
│
└── processRepos@200
    └── repo → Repo

Scope keys

• '' for file scope
• functionName@startIndex for function-local scope

These scope keys are also used later when verifying deferred bindings in call processing, so any future change to scope-key format must stay consistent across both layers.

---

Lookup Semantics

TypeEnvironment.lookup() resolves types in this effective order:

1. special receivers
   • this, self, $this → enclosing class
   • super, base, parent → parent class
2. position-indexed pattern overrides
3. function-local scope
4. file-level scope

Special receivers are handled as a dedicated fast path rather than ordinary lexical bindings.

---

Resolution Tiers

Bindings are collected during the same AST walk. Higher-confidence sources win over weaker inference.

Tier 0: Explicit Type Annotations

Direct extraction from AST type nodes.

// TypeScript
const user: User = getUser()

// Java
User user = getUser()

// Go
var user User

// Rust
let user: User = get_user()

// Python
user: User = get_user()

extractDeclaration() reads the declaration type node and normalizes it through extractSimpleTypeName().

Parameters are handled separately by extractParameter() using the same normalization logic. The shared TYPED_PARAMETER_TYPES set controls which AST node types are treated as typed parameters.

Tier 0b: For-Loop Element Type Resolution

Also referred to as Tier 1c in Phase 6 PR and test naming.

For-each style loops often introduce a variable with no explicit type. In those cases, the resolver derives the loop variable type from the iterable's container type.

foreach (var user in users) { user.Save(); }

// TypeScript
for (const user of users) { user.save(); }

// Rust
for user in users { user.save(); }

This is handled by resolveIterableElementType() through a three-step cascade:

1. Declaration type nodes
   Uses raw type annotation nodes when available, including cases such as User[] or List[User].

2. Scope environment string
   Uses extractElementTypeFromString() to parse a stored type string.

3. AST walk fallback
   Walks upward to enclosing declarations or parameters when needed.

Tier 0c: Pattern Binding

Pattern-matching constructs may introduce a new variable or temporarily narrow an existing one.

if (obj is User user) { user.Save(); }

// Java
if (obj instanceof User user) { user.save(); }

// Rust
if let Some(user) = opt { user.save(); }

// Python
match obj:
    case User() as user:
        user.save()

Binding behavior depends on the language:

• first-writer-wins is used by default
• position-indexed branch overrides are used where branch-local narrowing must not leak between branches, most notably Kotlin

Tier 1: Initializer / Constructor Inference

When there is no explicit annotation, the resolver can infer a type from the initializer.

const user = new User()

// C#
var user = new User()

// Kotlin
val user = User()

// Go
user := User{}
ptr := &User{}
user2 := new(User)

// Ruby
user = User.new

Some languages can identify constructor-like syntax directly. Others need validation through the SymbolTable, because syntax alone cannot always distinguish User() from getUser().

In those cases the system records an unverified binding candidate and later validates it against known class / struct symbols.

Tier 2: Assignment Chain Propagation

Bindings can propagate through simple identifier assignments.

const user: User = getUser()
const alias = user
const other = alias

This is handled after the main walk through a single pass over pending assignments.

This supports simple forward propagation, but there is no iterative fixpoint step. For example:

const b = a
const a: User = getUser()

will not resolve b.

---

Container Type Descriptors

CONTAINER_DESCRIPTORS defines the type-parameter semantics for common containers.

That allows the resolver to distinguish key-yielding methods from value-yielding methods instead of always assuming the last generic argument.

for (const key of map.keys()) { ... }    // key → string
for (const val of map.values()) { ... }  // val → User

Unknown containers fall back to heuristics, keeping the system conservative rather than fully semantic.

Examples of descriptor-driven behavior

• Map<K, V> / Dictionary<K, V> / similar key-value containers
• List<T> / Array<T> / Vec<T> / Set<T> / similar single-element containers
• method-aware yield selection such as .keys(), .values(), .keySet(), .Values

---

Comment-Based Types

For less strictly typed ecosystems, the resolver can fall back to documentation-based type information.

Supported comment systems:

• JSDoc for JavaScript / TypeScript
• PHPDoc for PHP
• YARD for Ruby

These are used conservatively and only when AST-level type information is missing or insufficient.

---

SymbolTable Interaction

Although the environment is built per file, it may consult the global SymbolTable in specific validation paths.

This is important for languages where constructor-like syntax is ambiguous. A binding candidate such as val user = User() may need confirmation that User is a class-like symbol rather than an ordinary function.

This means the system is still per-file in binding construction, but not completely isolated from project-wide symbol knowledge.

---

Deferred Binding Verification in Call Processing

A key detail is that some initializer bindings are not fully resolved inside TypeEnv itself.

call-processor.ts later verifies deferred bindings and may infer receiver types from:

• validated class / struct constructor candidates
• uniquely resolved function or method calls that expose a usable return type

So return-type-aware receiver inference already exists in a constrained downstream form today. What does not yet exist is feeding that information back into TypeEnv broadly enough to power loop inference, general assignment propagation, and wider expression typing.

---

Language Feature Matrix

Feature	TS/JS	Java	Kotlin	C#	Go	Rust	Python	PHP	Ruby	Swift	C/C++
Declarations	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Parameters	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Initializer / constructor inference	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Constructor binding scan	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
For-loop element types	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No	Yes
Pattern binding	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	No	No
Assignment chains	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No	Yes
Comment-based types	JSDoc	No	No	No	No	No	No	PHPDoc	YARD	No	No
Return type extraction	JSDoc	No	No	No	No	No	No	PHPDoc	YARD	No	No

---

Current Strengths

The current system already provides strong value for call resolution because it combines:

• explicit annotation extraction
• generic-aware loop element typing
• initializer-based inference
• selected pattern-based narrowing
• scope-aware lookups
• comment-based fallbacks for dynamic ecosystems
• constrained return-type-aware receiver inference in call processing

This is enough to materially improve call-edge precision even without implementing a full static type system.

---

Current Limitations

Important gaps still remain:

• no field / property type map for deep chains such as user.address.city
• no general cross-file propagation of inferred bindings
• no fixpoint inference
• limited branch-sensitive narrowing outside selected pattern constructs
• limited Swift support compared with other languages
• no complete destructuring-based field typing
• no broad expression-level return-type propagation inside TypeEnv

---

Contributor Notes

When modifying this system, treat the following as load-bearing invariants:

1. Conservatism matters more than recall
   A missed binding is usually safer than a misleading receiver type.

2. Scope-key format is shared behavior
   If scope keys change, constructor-binding verification and any downstream lookup using those keys must change in sync.

3. Tier naming may differ across code and PR discussions
   For-loop element inference may appear as "Tier 0b" in documentation and "Tier 1c" in Phase 6 PR / test naming.

4. Comment-based types are fallback signals, not primary truth
   They should remain lower-trust than explicit AST-derived types.

5. Return-type-aware inference already exists in constrained form
   Future roadmap work should extend and generalize it rather than reintroduce it from scratch.