gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/ingestion/languages/zig/range-binding.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Zig payload captures (F6): `for (items) |it|`, `if (opt) |v|`,
+ * `while (it.next()) |x|`. The captured name has no annotation anywhere — its
+ * type is the SUBJECT's type minus one layer (slice/array element, optional
+ * payload) — so the tree-sitter query cannot bind it; this post-finalize hook
+ * reads the subject's binding from the finished scope model and injects the
+ * payload's. Rust/Go do the same (`rust/range-binding.ts`,
+ * `go/range-binding.ts`).
+ *
+ * Deliberately narrow and honest: a payload binds only when the subject's
+ * WRITTEN type visibly has the layer the construct removes — `[]T` / `[N]T` /
+ * `[*]T` / `*[N]T` for `for`, `?T` (after any `E!`) for `if` / `while`. A
+ * subject typed `std.ArrayList(T)`, `anytype`, or anything unresolved binds
+ * nothing rather than guessing. `catch |err|` (an error, never a container
+ * receiver) and `switch` prongs are skipped. The same one-layer projection
+ * types `const t = items[i];` / `opt.?` / `ptr.*` (`bindProjectedLocal`).
+ *
+ * Runs after `propagateImportedReturnTypes`, so return bindings hoisted from
+ * other files are visible when a subject is a call.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+export declare function populateZigRangeBindings(parsedFiles: readonly ParsedFile[], indexes: ScopeResolutionIndexes, ctx: {
+    readonly fileContents: ReadonlyMap<string, string>;
+    readonly treeCache?: {
+        get(filePath: string): unknown;
+    };
+}): void;
+/** `*T` / `*const T` / `E!*T` → `T`; undefined when not visibly a pointer. */
+export declare function zigPointeeSpelling(spelling: string): string | undefined;
+/** `[]T` / `[]const T` / `[N]T` / `[*]T` / `[*:0]T` / `*[N]T` / `*const []T`
+ *  → `T` (with `T`'s own sigils kept: `[]*Thing` → `*Thing`). Undefined when
+ *  the written type has no slice/array layer to remove. */
+export declare function zigElementSpelling(spelling: string): string | undefined;
+/** `?T` / `?*T` / `E!?T` → `T` (sigils of `T` kept). Undefined when the
+ *  written type is not visibly optional. */
+export declare function zigOptionalPayloadSpelling(spelling: string): string | undefined;

package/dist/core/ingestion/languages/zig/range-binding.js

@@ -0,0 +1,373 @@
+/**
+ * Zig payload captures (F6): `for (items) |it|`, `if (opt) |v|`,
+ * `while (it.next()) |x|`. The captured name has no annotation anywhere — its
+ * type is the SUBJECT's type minus one layer (slice/array element, optional
+ * payload) — so the tree-sitter query cannot bind it; this post-finalize hook
+ * reads the subject's binding from the finished scope model and injects the
+ * payload's. Rust/Go do the same (`rust/range-binding.ts`,
+ * `go/range-binding.ts`).
+ *
+ * Deliberately narrow and honest: a payload binds only when the subject's
+ * WRITTEN type visibly has the layer the construct removes — `[]T` / `[N]T` /
+ * `[*]T` / `*[N]T` for `for`, `?T` (after any `E!`) for `if` / `while`. A
+ * subject typed `std.ArrayList(T)`, `anytype`, or anything unresolved binds
+ * nothing rather than guessing. `catch |err|` (an error, never a container
+ * receiver) and `switch` prongs are skipped. The same one-layer projection
+ * types `const t = items[i];` / `opt.?` / `ptr.*` (`bindProjectedLocal`).
+ *
+ * Runs after `propagateImportedReturnTypes`, so return bindings hoisted from
+ * other files are visible when a subject is a call.
+ */
+import { getZigParser } from './query.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe, ParseTimeoutError } from '../../../tree-sitter/safe-parse.js';
+import { logger } from '../../../logger.js';
+import { findClassBindingInScope, findReceiverTypeBinding, isClassLike, } from '../../scope-resolution/scope/walkers.js';
+import { isZigKeywordDeclaration, zigUnwrapValue } from './captures.js';
+import { normalizeZigTypeName } from './interpret.js';
+const PAYLOAD_HOSTS = new Set([
+    'for_statement',
+    'for_expression',
+    'if_statement',
+    'if_expression',
+    'while_statement',
+    'while_expression',
+]);
+export function populateZigRangeBindings(parsedFiles, indexes, ctx) {
+    const parser = getZigParser();
+    // Class def nodeId → its Class scope (whose typeBindings hold the members'
+    // field types and the methods' return types). Same derivation as
+    // `buildWorkspaceResolutionIndex`, which this hook does not receive.
+    const classScopeByDefId = new Map();
+    for (const parsed of parsedFiles) {
+        for (const scope of parsed.scopes) {
+            if (scope.kind !== 'Class')
+                continue;
+            const cd = scope.ownedDefs.find((d) => isClassLike(d.type));
+            if (cd !== undefined)
+                classScopeByDefId.set(cd.nodeId, scope);
+        }
+    }
+    for (const parsed of parsedFiles) {
+        const sourceText = ctx.fileContents.get(parsed.filePath);
+        if (sourceText === undefined)
+            continue;
+        let tree = ctx.treeCache?.get(parsed.filePath);
+        if (tree === undefined) {
+            try {
+                tree = parseSourceSafe(parser, sourceText, undefined, {
+                    bufferSize: getTreeSitterBufferSize(sourceText),
+                });
+            }
+            catch (err) {
+                if (err instanceof ParseTimeoutError) {
+                    logger.warn({ file: parsed.filePath }, 'zig range-binding: parse timed out, skipping file');
+                    continue;
+                }
+                throw err;
+            }
+        }
+        const scopes = parsed.scopes;
+        if (scopes.length === 0)
+            continue;
+        const resolver = new ZigSubjectTypeResolver(scopes, indexes, classScopeByDefId);
+        // Pre-order: an outer payload is bound before an inner construct reads it
+        // (`for (pages) |p| { if (p.frame) |f| … }`).
+        const visit = (node) => {
+            if (PAYLOAD_HOSTS.has(node.type))
+                bindPayloads(node, resolver);
+            else if (node.type === 'variable_declaration')
+                bindProjectedLocal(node, resolver);
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const c = node.namedChild(i);
+                if (c !== null)
+                    visit(c);
+            }
+        };
+        visit(tree.rootNode);
+    }
+}
+/** Bind the payload identifiers of one `for` / `if` / `while` node. */
+function bindPayloads(node, resolver) {
+    const named = node.namedChildren.filter((c) => c !== null && c.type !== 'comment');
+    // The payload right after the subject(s); a trailing `else |err|` payload
+    // belongs to the else_clause and is not a child here.
+    const payload = named.find((c) => c.type === 'payload');
+    if (payload === undefined)
+        return;
+    const isFor = node.type === 'for_statement' || node.type === 'for_expression';
+    // A `for` lists its subjects BEFORE the payload; the body follows it.
+    const subjects = isFor
+        ? named.slice(0, named.indexOf(payload)).filter((c) => c.type !== 'block_label')
+        : [node.childForFieldName('condition')].filter((c) => c !== null);
+    if (subjects.length === 0)
+        return;
+    // For a `for` the payload names pair positionally with the subjects
+    // (`for (items, 0..) |it, i|`); `if` / `while` capture one value.
+    const captured = payload.namedChildren.filter((c) => c !== null && c.type === 'identifier');
+    const host = payloadHostScope(node, resolver);
+    if (host === undefined)
+        return;
+    for (let i = 0; i < captured.length && i < subjects.length; i++) {
+        const name = captured[i].text;
+        if (name === '_')
+            continue;
+        const subject = subjects[i];
+        if (subject.type === 'range_expression')
+            continue; // `0..` — an index
+        const spelling = resolver.spellingOf(subject);
+        if (spelling === undefined)
+            continue;
+        const projected = isFor ? zigElementSpelling(spelling) : zigOptionalPayloadSpelling(spelling);
+        if (projected === undefined)
+            continue;
+        // `|*p|` captures a POINTER to the element/payload (the `*` is an
+        // anonymous payload child right before the identifier). Keep the written
+        // `*` so a later deref projection (`const q = p.*;`) still sees the
+        // layer; `rawName` strips it again, so method dispatch is unchanged.
+        const element = captured[i].previousSibling?.type === '*' ? `*${projected}` : projected;
+        const rawName = normalizeZigTypeName(element);
+        if (rawName.length === 0 || rawName.startsWith('@'))
+            continue;
+        const existing = host.typeBindings.get(name);
+        // Zig forbids shadowing, so an existing binding of this name in the host
+        // can only be a sibling construct's payload (bare-expression bodies share
+        // the enclosing scope). Two different types for one name: decline both
+        // rather than let the last one type the first one's body.
+        if (existing !== undefined) {
+            if (existing.rawName !== rawName) {
+                host.typeBindings.delete(name);
+            }
+            continue;
+        }
+        const ref = element === rawName
+            ? { rawName, declaredAtScope: host.id, source: 'annotation' }
+            : { rawName, declaredSpelling: element, declaredAtScope: host.id, source: 'annotation' };
+        host.typeBindings.set(name, ref);
+    }
+}
+/** `const t = items[i];` / `const t = opt.?;` / `const t = ptr.*;` — a local
+ *  bound to ONE LAYER under a typed subject: the element of a slice/array
+ *  (not a `[a..b]` re-slice), the payload of an optional, the pointee of a
+ *  pointer. Same honesty rule as the payloads: the subject's WRITTEN type
+ *  must show the layer. Skipped when the name is already typed (an
+ *  annotation, or a capture-time inference). */
+function bindProjectedLocal(decl, resolver) {
+    if (!isZigKeywordDeclaration(decl))
+        return;
+    const named = decl.namedChildren.filter((c) => c !== null && c.type !== 'comment');
+    if (named.length < 2 || named[0].type !== 'identifier')
+        return;
+    const value = named[named.length - 1];
+    if (value.id === decl.childForFieldName('type')?.id)
+        return; // `const x: T;`
+    const inner = zigUnwrapValue(value);
+    let subject;
+    let project;
+    switch (inner.type) {
+        case 'index_expression':
+            if (inner.childForFieldName('index')?.type === 'range_expression')
+                return; // `a[0..n]`
+            subject = inner.childForFieldName('object');
+            project = zigElementSpelling;
+            break;
+        case 'null_coercion_expression':
+            subject = inner.namedChild(0);
+            project = zigOptionalPayloadSpelling;
+            break;
+        case 'dereference_expression':
+            subject = inner.namedChild(0);
+            project = zigPointeeSpelling;
+            break;
+        default:
+            return;
+    }
+    if (subject === null)
+        return;
+    const name = named[0].text;
+    const host = resolver.scopeAt(decl.startPosition.row + 1, decl.startPosition.column, false);
+    if (host === undefined || host.typeBindings.has(name))
+        return;
+    const spelling = resolver.spellingOf(subject);
+    if (spelling === undefined)
+        return;
+    const projected = project(spelling);
+    if (projected === undefined)
+        return;
+    const rawName = normalizeZigTypeName(projected);
+    if (rawName.length === 0 || rawName.startsWith('@'))
+        return;
+    const ref = projected === rawName
+        ? { rawName, declaredAtScope: host.id, source: 'assignment-inferred' }
+        : {
+            rawName,
+            declaredSpelling: projected,
+            declaredAtScope: host.id,
+            source: 'assignment-inferred',
+        };
+    host.typeBindings.set(name, ref);
+}
+/** `*T` / `*const T` / `E!*T` → `T`; undefined when not visibly a pointer. */
+export function zigPointeeSpelling(spelling) {
+    let t = spelling.trim();
+    const bang = t.lastIndexOf('!');
+    if (bang !== -1)
+        t = t.slice(bang + 1).trim();
+    const m = /^\*(const\s+)?/.exec(t);
+    if (m === null)
+        return undefined;
+    const rest = t.slice(m[0].length).trim();
+    return rest.length > 0 ? rest : undefined;
+}
+function body(node) {
+    return node.childForFieldName('body');
+}
+/** The scope the payload name lives in: the body block's own scope when the
+ *  body is a block (`|t| { … }`), otherwise the innermost scope enclosing the
+ *  construct (a bare-expression body: `for (items) |t| t.run();`). */
+function payloadHostScope(node, resolver) {
+    // for/if/while_statement carry `body:`; in the *_expression forms the
+    // body is the named child right after the payload.
+    let bodyNode = body(node);
+    if (bodyNode === null) {
+        const named = node.namedChildren.filter((c) => c !== null);
+        const at = named.findIndex((c) => c.type === 'payload');
+        bodyNode = at === -1 ? null : (named[at + 1] ?? null);
+    }
+    let block = bodyNode;
+    if (block?.type === 'block_expression')
+        block = block.namedChildren.find((c) => c?.type === 'block') ?? null;
+    if (block?.type === 'labeled_statement')
+        block = block.namedChildren.find((c) => c?.type === 'block') ?? null;
+    if (block?.type === 'block') {
+        const exact = resolver.scopeAt(block.startPosition.row + 1, block.startPosition.column, true);
+        if (exact !== undefined)
+            return exact;
+    }
+    return resolver.scopeAt(node.startPosition.row + 1, node.startPosition.column, false);
+}
+/** `[]T` / `[]const T` / `[N]T` / `[*]T` / `[*:0]T` / `*[N]T` / `*const []T`
+ *  → `T` (with `T`'s own sigils kept: `[]*Thing` → `*Thing`). Undefined when
+ *  the written type has no slice/array layer to remove. */
+export function zigElementSpelling(spelling) {
+    let t = spelling.trim();
+    const bang = t.lastIndexOf('!');
+    if (bang !== -1)
+        t = t.slice(bang + 1).trim();
+    // A pointer TO an array/slice iterates the pointee.
+    t = t.replace(/^\*(const\s+)?(?=\[)/, '');
+    const m = /^\[[^\]]*\]\s*(const\s+)?/.exec(t);
+    if (m === null)
+        return undefined;
+    const rest = t.slice(m[0].length).trim();
+    return rest.length > 0 ? rest : undefined;
+}
+/** `?T` / `?*T` / `E!?T` → `T` (sigils of `T` kept). Undefined when the
+ *  written type is not visibly optional. */
+export function zigOptionalPayloadSpelling(spelling) {
+    let t = spelling.trim();
+    const bang = t.lastIndexOf('!');
+    if (bang !== -1)
+        t = t.slice(bang + 1).trim();
+    if (!t.startsWith('?'))
+        return undefined;
+    const rest = t.slice(1).trim();
+    return rest.length > 0 ? rest : undefined;
+}
+/** Resolves a subject expression to the WRITTEN type spelling of its binding
+ *  (`declaredSpelling` when the capture layer reduced it, else `rawName`),
+ *  through the finished scope model of one file. */
+class ZigSubjectTypeResolver {
+    scopes;
+    indexes;
+    classScopeByDefId;
+    constructor(scopes, indexes, classScopeByDefId) {
+        this.scopes = scopes;
+        this.indexes = indexes;
+        this.classScopeByDefId = classScopeByDefId;
+    }
+    /** Innermost scope containing (line, col); with `exact`, only a scope
+     *  STARTING there (a block's own scope). */
+    scopeAt(line, col, exact) {
+        let best;
+        for (const s of this.scopes) {
+            const r = s.range;
+            if (exact) {
+                if (r.startLine === line && r.startCol === col && s.kind === 'Block')
+                    return s;
+                continue;
+            }
+            const startsBefore = r.startLine < line || (r.startLine === line && r.startCol <= col);
+            const endsAfter = r.endLine > line || (r.endLine === line && r.endCol >= col);
+            if (!startsBefore || !endsAfter)
+                continue;
+            if (best === undefined || contains(best.range, r))
+                best = s;
+        }
+        return best;
+    }
+    spellingOf(subject) {
+        const ref = this.typeRefOf(subject);
+        return ref === undefined ? undefined : (ref.declaredSpelling ?? ref.rawName);
+    }
+    typeRefOf(subjectRaw) {
+        const subject = zigUnwrapValue(subjectRaw);
+        const scope = this.scopeAt(subject.startPosition.row + 1, subject.startPosition.column, false);
+        if (scope === undefined)
+            return undefined;
+        switch (subject.type) {
+            case 'identifier':
+                return findReceiverTypeBinding(scope.id, subject.text, this.indexes);
+            case 'field_expression': {
+                // `self.items` / `page.session` — the member's binding on the
+                // object's class scope (field type, or a method's return type).
+                const object = subject.childForFieldName('object');
+                const member = subject.childForFieldName('member');
+                if (object === null || member === null)
+                    return undefined;
+                return this.memberRefOf(object, member.text, scope.id);
+            }
+            case 'call_expression': {
+                const callee = subject.childForFieldName('function');
+                if (callee === null)
+                    return undefined;
+                if (callee.type === 'identifier') {
+                    // A free call: the fn's return binding, in the scope chain.
+                    return findReceiverTypeBinding(scope.id, callee.text, this.indexes);
+                }
+                if (callee.type !== 'field_expression')
+                    return undefined;
+                const object = callee.childForFieldName('object');
+                const member = callee.childForFieldName('member');
+                if (object === null || member === null)
+                    return undefined;
+                return this.memberRefOf(object, member.text, scope.id);
+            }
+            default:
+                return undefined;
+        }
+    }
+    /** The binding of `member` on the class the `object` expression is typed
+     *  by — recursively through field chains (`self.a.b`). */
+    memberRefOf(object, member, scopeId) {
+        const objectRef = this.typeRefOf(object);
+        if (objectRef === undefined)
+            return undefined;
+        // A compound rawName (`node.asElement()`, F6's member-call shape) needs
+        // the shared compound resolver; not walked here.
+        if (objectRef.rawName.includes('('))
+            return undefined;
+        const classDef = findClassBindingInScope(scopeId, objectRef.rawName, this.indexes);
+        if (classDef === undefined)
+            return undefined;
+        const classScope = this.classScopeByDefId.get(classDef.nodeId);
+        return classScope?.typeBindings.get(member);
+    }
+}
+function contains(outer, inner) {
+    const startsBefore = outer.startLine < inner.startLine ||
+        (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
+    const endsAfter = outer.endLine > inner.endLine ||
+        (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
+    return startsBefore && endsAfter;
+}

package/dist/core/ingestion/languages/zig/scope-resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Zig `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by the
+ * generic `runScopeResolution` orchestrator.
+ *
+ * Thin wiring: Zig has no inheritance (default MRO linearization over an
+ * empty heritage set), no `super`, and is statically typed (field-fallback
+ * heuristic off per the contract guidance). Import resolution reuses the
+ * same `resolveZigImportInternal` the legacy import-resolver config wraps,
+ * with `build.zig.zon` `.path` deps threaded through `loadResolutionConfig`.
+ */
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+export declare const zigScopeResolver: ScopeResolver;

package/dist/core/ingestion/languages/zig/scope-resolver.js

@@ -0,0 +1,58 @@
+/**
+ * Zig `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by the
+ * generic `runScopeResolution` orchestrator.
+ *
+ * Thin wiring: Zig has no inheritance (default MRO linearization over an
+ * empty heritage set), no `super`, and is statically typed (field-fallback
+ * heuristic off per the contract guidance). Import resolution reuses the
+ * same `resolveZigImportInternal` the legacy import-resolver config wraps,
+ * with `build.zig.zon` `.path` deps threaded through `loadResolutionConfig`.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
+import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+import { loadZigBuildConfig } from '../../language-config.js';
+import { resolveZigImportInternal } from '../../import-resolvers/zig.js';
+import { zigProvider } from '../zig.js';
+import { expandZigWildcardNames, zigArityCompatibility, zigMergeBindings } from './index.js';
+import { populateZigRangeBindings } from './range-binding.js';
+export const zigScopeResolver = {
+    language: SupportedLanguages.Zig,
+    languageProvider: zigProvider,
+    importEdgeReason: 'zig-scope: import',
+    // A struct literal `T{ .f = x }` is a CALLS edge to the Struct node (the
+    // Rust `T { .. }` / Go `T{}` shape). Zig has no Constructor nodes, so
+    // nothing but this marker tells that edge from an invocation on the edge
+    // itself — `main → SpawnRequest` looked like a call to a function
+    // (PR #1432 review). Emits `local-call (constructor)` and friends.
+    markConstructionSites: true,
+    // Hub modules are how Zig projects publish their types: `pub const Terminal
+    // = @import("Terminal.zig");` / `pub const PRNG = @import("prng.zig");` in a
+    // file that declares nothing itself. Consumers then write
+    // `terminal.Terminal.init()`, `stdx.PRNG.from_seed()`, `t: stdx.Thing`.
+    // Measured on real projects before → after this flag: CALLS into ghostty's
+    // `src/terminal/` from outside it 46 → 253; into tigerbeetle's `stdx` hub
+    // from outside it 837 → 1500 (136 `stdx.Type.fn(` sites, 289 annotations).
+    namespaceExportsIncludeImportedNames: true,
+    // A qualified receiver is a chain of `const` handles — hub modules
+    // republishing modules (`hub.sub.Thing{}`), types nested in types
+    // (`mod.Outer.Inner{}`), enum variants through the module
+    // (`opmod.Op.lookup.event_max()`) — walked hop by hop from the verified
+    // import; a one-hop split at the last dot resolved none of them.
+    resolveNamespaceChains: true,
+    loadResolutionConfig: (repoPath) => loadZigBuildConfig(repoPath),
+    resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => resolveZigImportInternal(fromFile, targetRaw, allFilePaths, resolutionConfig ?? null),
+    // `pub usingnamespace @import("x.zig");` — target decls become local decls.
+    expandsWildcardTo: (targetModuleScope, parsedFiles) => expandZigWildcardNames(targetModuleScope, parsedFiles),
+    mergeBindings: zigMergeBindings,
+    arityCompatibility: zigArityCompatibility,
+    buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
+    populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    // Payload captures — `for (items) |it|`, `if (opt) |v|`, `while (it.next())
+    // |x|` — typed from the subject's binding after finalize (F6).
+    populateRangeBindings: populateZigRangeBindings,
+    // Zig has no `super`.
+    isSuperReceiver: () => false,
+    // Statically typed — the field-fallback heuristic over-connects.
+    fieldFallbackOnMethodLookup: false,
+};

package/dist/core/ingestion/languages/zig/simple-hooks.d.ts

@@ -0,0 +1,25 @@
+import type { BindingRef, Callsite, CaptureMatch, ParsedFile, Scope, ScopeId, ScopeTree, SymbolDefinition, TypeRef } from '../../../../_shared/index.js';
+/** Keep parameter (incl. `self`) typeBindings in the function scope —
+ *  hoisting them to Module would pollute other functions' receiver
+ *  resolution (same rationale as `goBindingScopeFor`). */
+export declare function zigBindingScopeFor(decl: CaptureMatch, innermost: Scope, tree: ScopeTree): ScopeId | null;
+/** `pub usingnamespace @import("x.zig");` — every declaration of the target
+ *  module becomes a declaration of the importer. Enumerates the target's
+ *  module-level names for the finalize wildcard expansion (Dart pattern).
+ *  Zig visibility (`pub`) is not recorded on scope-side defs, so this
+ *  over-approximates to every top-level name; the structure phase's
+ *  `isExported` is the authoritative visibility. */
+export declare function expandZigWildcardNames(targetModuleScope: ScopeId, parsedFiles: readonly ParsedFile[]): readonly string[];
+/** Zig's receiver convention is a FIRST parameter named `self`; the
+ *  `self`-sourced typeBinding on the function scope carries its type.
+ *  Position is enforced upstream, not here: `interpretZigTypeBinding` only
+ *  sources a binding as `self` when `emitZigScopeCaptures` tagged it
+ *  `@type-binding.first-parameter`, so a later parameter named `self`
+ *  arrives as `parameter-annotation` and is never returned by this hook. */
+export declare function zigReceiverBinding(functionScope: Scope): TypeRef | null;
+/** Local declarations shadow imports; deterministic order within a tier. */
+export declare function zigMergeBindings(existing: readonly BindingRef[], incoming: readonly BindingRef[], _scopeId: string): BindingRef[];
+/** Zig has no overloading; without synthesized arity metadata on
+ *  declarations the comparison is always 'unknown' — kept as a real
+ *  bounds check so it turns on if arity captures are added later. */
+export declare function zigArityCompatibility(callsite: Callsite, def: SymbolDefinition): 'compatible' | 'unknown' | 'incompatible';

package/dist/core/ingestion/languages/zig/simple-hooks.js

@@ -0,0 +1,143 @@
+/** Keep parameter (incl. `self`) typeBindings in the function scope —
+ *  hoisting them to Module would pollute other functions' receiver
+ *  resolution (same rationale as `goBindingScopeFor`). */
+export function zigBindingScopeFor(decl, innermost, tree) {
+    if (decl['@type-binding.parameter'] !== undefined) {
+        return innermost.id;
+    }
+    // A container returned by a generic type constructor (`fn List(comptime T:
+    // type) type { return struct {…}; }`) is anchored on the container node,
+    // whose innermost enclosing scope is the FUNCTION BODY. Its name is only
+    // useful to callers (`List(u8){}`, `List(u8).init()`), so bind it in the
+    // module scope beside the Function def of the same name — `List` really is
+    // both a callable and a type. `zigTypeConstructorOf` in the walker decides
+    // WHICH containers get this rule; the marker capture carries the verdict.
+    if (decl['@declaration.type-constructor'] !== undefined) {
+        let scope = innermost;
+        while (scope !== undefined && scope.kind !== 'Module')
+            scope = tree.getParent(scope.id);
+        return scope?.id ?? null;
+    }
+    // File-struct members: the file's Class scope spans the whole file (same
+    // range as the Module scope, nested under it). Their DEFS stay owned by the
+    // Class scope (that is what makes them methods/fields of the file's Struct),
+    // but their NAMES must stay visible at module level — `Page.init()` from
+    // another file is a namespace-member lookup over the module scope's
+    // bindings, and `usingnamespace` expansion reads the same. Hoist every
+    // declaration binding hosted by an equal-range Class scope to its Module
+    // parent. Type bindings (`@type-binding.*`, incl. field types) are NOT
+    // hoisted: the compound resolver reads member types from the class scope.
+    const anchor = ZIG_DECLARATION_ANCHORS.map((k) => decl[k]).find((c) => c !== undefined);
+    if (anchor !== undefined) {
+        // Reproduce the extractor's auto-hoist (a scope-creating declaration is
+        // bound in the scope OUTSIDE its own body), then step past the file's
+        // Class scope when that is where the name would land.
+        let host = innermost;
+        if (host.parent !== null && sameRange(anchor.range, host.range)) {
+            host = tree.getParent(host.id);
+        }
+        if (host !== undefined && host.kind === 'Class' && host.parent !== null) {
+            const parent = tree.getParent(host.id);
+            if (parent !== undefined && parent.kind === 'Module' && sameRange(parent.range, host.range)) {
+                return parent.id;
+            }
+        }
+    }
+    return null; // default auto-hoist for other bindings
+}
+const ZIG_DECLARATION_ANCHORS = [
+    '@declaration.function',
+    '@declaration.method',
+    '@declaration.struct',
+    '@declaration.enum',
+    '@declaration.union',
+    '@declaration.field',
+    '@declaration.variable',
+];
+function sameRange(a, b) {
+    return (a.startLine === b.startLine &&
+        a.startCol === b.startCol &&
+        a.endLine === b.endLine &&
+        a.endCol === b.endCol);
+}
+/** `pub usingnamespace @import("x.zig");` — every declaration of the target
+ *  module becomes a declaration of the importer. Enumerates the target's
+ *  module-level names for the finalize wildcard expansion (Dart pattern).
+ *  Zig visibility (`pub`) is not recorded on scope-side defs, so this
+ *  over-approximates to every top-level name; the structure phase's
+ *  `isExported` is the authoritative visibility. */
+export function expandZigWildcardNames(targetModuleScope, parsedFiles) {
+    const target = parsedFiles.find((p) => p.moduleScope === targetModuleScope);
+    if (target === undefined)
+        return [];
+    const seen = new Set();
+    const names = [];
+    for (const def of target.localDefs) {
+        const qn = def.qualifiedName;
+        if (qn === undefined || qn.length === 0 || qn.includes('.'))
+            continue; // top-level only
+        if (seen.has(qn))
+            continue;
+        seen.add(qn);
+        names.push(qn);
+    }
+    return names;
+}
+/** Zig's receiver convention is a FIRST parameter named `self`; the
+ *  `self`-sourced typeBinding on the function scope carries its type.
+ *  Position is enforced upstream, not here: `interpretZigTypeBinding` only
+ *  sources a binding as `self` when `emitZigScopeCaptures` tagged it
+ *  `@type-binding.first-parameter`, so a later parameter named `self`
+ *  arrives as `parameter-annotation` and is never returned by this hook. */
+export function zigReceiverBinding(functionScope) {
+    if (functionScope.kind !== 'Function')
+        return null;
+    for (const binding of functionScope.typeBindings.values()) {
+        if (binding.source === 'self')
+            return binding;
+    }
+    return null;
+}
+const TIER = {
+    local: 0,
+    namespace: 1,
+    import: 2,
+    reexport: 3,
+    wildcard: 4,
+};
+/** Local declarations shadow imports; deterministic order within a tier. */
+export function zigMergeBindings(existing, incoming, _scopeId) {
+    const all = [...existing, ...incoming];
+    if (all.length === 0)
+        return [];
+    let bestTier = 99;
+    for (const b of all) {
+        const t = TIER[b.origin] ?? 99;
+        if (t < bestTier)
+            bestTier = t;
+    }
+    const byNode = new Map();
+    for (const b of all) {
+        if ((TIER[b.origin] ?? 99) !== bestTier)
+            continue;
+        if (!byNode.has(b.def.nodeId))
+            byNode.set(b.def.nodeId, b);
+    }
+    return [...byNode.values()].sort((a, b) => a.def.nodeId.localeCompare(b.def.nodeId));
+}
+/** Zig has no overloading; without synthesized arity metadata on
+ *  declarations the comparison is always 'unknown' — kept as a real
+ *  bounds check so it turns on if arity captures are added later. */
+export function zigArityCompatibility(callsite, def) {
+    const max = def.parameterCount;
+    const min = def.requiredParameterCount;
+    if (max === undefined && min === undefined)
+        return 'unknown';
+    if (!Number.isFinite(callsite.arity) || callsite.arity < 0)
+        return 'unknown';
+    if (min !== undefined && callsite.arity < min)
+        return 'incompatible';
+    if (max !== undefined && callsite.arity > max)
+        return 'incompatible';
+    return 'compatible';
+}