gitnexus 1.6.12-rc.2 → 1.6.12-rc.21

package/dist/core/ingestion/languages/objective-c.js

@@ -0,0 +1,300 @@
+import path from 'path';
+import { SupportedLanguages, } from '../../../_shared/index.js';
+import Parser from 'tree-sitter';
+import { defineLanguage } from '../language-provider.js';
+import { getLanguageGrammar } from '../../tree-sitter/parser-loader.js';
+import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
+import { assertCloneable } from '../workers/clone-safety.js';
+import { preprocessObjectiveCMacroMarkers } from './objective-c/macro-marker-preprocess.js';
+import { buildObjectiveCSemanticGraph, buildObjectiveCScopeCaptures, collectObjectiveCCaptureSideChannel, collectObjectiveCFacts, parseObjCType, setObjectiveCFileFacts, } from './objective-c/facts.js';
+const OBJECTIVE_C_SCOPE_QUERY = `((translation_unit) @objc.root)`;
+const EMPTY_TYPE_CONFIG = {
+    declarationNodeTypes: new Set(),
+    extractDeclaration: () => null,
+    extractParameter: () => null,
+};
+const noImportResolution = () => null;
+function normalizedExt(filePath) {
+    return path.extname(filePath).toLowerCase();
+}
+function isObjectiveCSourcePath(filePath) {
+    const ext = normalizedExt(filePath);
+    return ext === '.m' || ext === '.mm';
+}
+function isHeaderPath(filePath) {
+    return normalizedExt(filePath) === '.h';
+}
+const OBJECTIVE_C_HEADER_NODE_TYPES = new Set([
+    'class_declaration',
+    'class_interface',
+    'class_implementation',
+    'compatibility_alias_declaration',
+    'module_import',
+    'protocol_declaration',
+    // Embedding chunks a Method node's snippet, not the enclosing @interface.
+    // tree-sitter-objc only emits these for +/- declarators, not C++ functions.
+    'method_declaration',
+    'method_definition',
+]);
+const OBJECTIVE_C_HEADER_DIRECTIVES = [
+    '@class',
+    '@compatibility_alias',
+    '@import',
+    '@implementation',
+    '@interface',
+    '@protocol',
+];
+function hasObjectiveCHeaderSyntax(sourceText) {
+    try {
+        const tree = parseObjectiveCSource(sourceText);
+        const stack = [tree.rootNode];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (node === undefined)
+                continue;
+            if (OBJECTIVE_C_HEADER_NODE_TYPES.has(node.type))
+                return true;
+            for (let i = node.namedChildCount - 1; i >= 0; i--) {
+                const child = node.namedChild(i);
+                if (child !== null)
+                    stack.push(child);
+            }
+        }
+    }
+    catch {
+        // Keep unambiguous Objective-C headers on the normal unavailable-parser path.
+        return hasObjectiveCHeaderDirective(sourceText) || hasObjectiveCMethodDeclarator(sourceText);
+    }
+    // Bare method snippets (`- (void)run;`) are not `method_declaration` at
+    // translation-unit scope; the grammar only emits that under @interface.
+    return hasObjectiveCMethodDeclarator(sourceText);
+}
+/**
+ * Line-leading `+/- (Type)selector` used when the tree has no @interface and
+ * when the grammar cannot load. `-(x);` does not match: `)` is not followed
+ * by a selector identifier.
+ */
+function hasObjectiveCMethodDeclarator(sourceText) {
+    return /(?:^|[\r\n])[ \t]*[+-][ \t]*\([^;\n]+\)[ \t]*[A-Za-z_]/.test(sourceTextWithoutComments(sourceText));
+}
+/** Replace comments with spaces so line-leading method probes see only code. */
+function sourceTextWithoutComments(sourceText) {
+    const chars = sourceText.split('');
+    let index = 0;
+    let state = 'code';
+    while (index < chars.length) {
+        const current = chars[index];
+        const next = chars[index + 1];
+        if (state === 'line-comment') {
+            if (current === '\n' || current === '\r')
+                state = 'code';
+            else
+                chars[index] = ' ';
+            index++;
+            continue;
+        }
+        if (state === 'block-comment') {
+            if (current === '*' && next === '/') {
+                chars[index] = ' ';
+                chars[index + 1] = ' ';
+                state = 'code';
+                index += 2;
+            }
+            else {
+                if (current !== '\n' && current !== '\r')
+                    chars[index] = ' ';
+                index++;
+            }
+            continue;
+        }
+        if (state === 'single-quote' || state === 'double-quote') {
+            if (current === '\\') {
+                index += 2;
+            }
+            else if ((state === 'single-quote' && current === "'") ||
+                (state === 'double-quote' && current === '"')) {
+                state = 'code';
+                index++;
+            }
+            else {
+                index++;
+            }
+            continue;
+        }
+        if (current === '/' && next === '/') {
+            chars[index] = ' ';
+            chars[index + 1] = ' ';
+            state = 'line-comment';
+            index += 2;
+            continue;
+        }
+        if (current === '/' && next === '*') {
+            chars[index] = ' ';
+            chars[index + 1] = ' ';
+            state = 'block-comment';
+            index += 2;
+            continue;
+        }
+        if (current === "'") {
+            state = 'single-quote';
+            index++;
+            continue;
+        }
+        if (current === '"') {
+            state = 'double-quote';
+            index++;
+            continue;
+        }
+        index++;
+    }
+    return chars.join('');
+}
+function hasObjectiveCHeaderDirective(sourceText) {
+    let index = 0;
+    let state = 'code';
+    while (index < sourceText.length) {
+        const current = sourceText[index];
+        const next = sourceText[index + 1];
+        if (state === 'line-comment') {
+            if (current === '\n' || current === '\r')
+                state = 'code';
+            index++;
+            continue;
+        }
+        if (state === 'block-comment') {
+            if (current === '*' && next === '/') {
+                state = 'code';
+                index += 2;
+            }
+            else {
+                index++;
+            }
+            continue;
+        }
+        if (state === 'single-quote' || state === 'double-quote') {
+            if (current === '\\') {
+                index += 2;
+            }
+            else if ((state === 'single-quote' && current === "'") ||
+                (state === 'double-quote' && current === '"')) {
+                state = 'code';
+                index++;
+            }
+            else {
+                index++;
+            }
+            continue;
+        }
+        if (current === '/' && next === '/') {
+            state = 'line-comment';
+            index += 2;
+            continue;
+        }
+        if (current === '/' && next === '*') {
+            state = 'block-comment';
+            index += 2;
+            continue;
+        }
+        if (current === "'") {
+            state = 'single-quote';
+            index++;
+            continue;
+        }
+        if (current === '"') {
+            state = 'double-quote';
+            index++;
+            continue;
+        }
+        if (current === '@') {
+            const directive = OBJECTIVE_C_HEADER_DIRECTIVES.find((candidate) => sourceText.startsWith(candidate, index));
+            if (directive !== undefined && !isIdentifierCharacter(sourceText[index + directive.length])) {
+                return true;
+            }
+        }
+        index++;
+    }
+    return false;
+}
+function isIdentifierCharacter(character) {
+    return character !== undefined && /[A-Za-z0-9_]/.test(character);
+}
+export function classifyObjectiveCFileContent(filePath, sourceText) {
+    if (isObjectiveCSourcePath(filePath))
+        return true;
+    if (!isHeaderPath(filePath))
+        return false;
+    return hasObjectiveCHeaderSyntax(sourceText);
+}
+function parseObjectiveCSource(sourceText) {
+    const parser = new Parser();
+    parser.setLanguage(getLanguageGrammar(SupportedLanguages.ObjectiveC));
+    return parseSourceSafe(parser, preprocessObjectiveCMacroMarkers(sourceText), undefined, undefined, 'Objective-C source');
+}
+function treeFromCachedOrSource(cachedTree, sourceText) {
+    if (cachedTree !== undefined && looksLikeTree(cachedTree))
+        return cachedTree;
+    return parseObjectiveCSource(sourceText);
+}
+function looksLikeTree(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        'rootNode' in value &&
+        value.rootNode !== undefined);
+}
+function interpretObjectiveCImport(captures) {
+    const source = captures['@import.source'];
+    if (source === undefined || source.text.trim().length === 0)
+        return null;
+    const targetRaw = source.text.trim();
+    const kind = captures['@import.kind']?.text.trim();
+    const isSystemHeader = targetRaw.startsWith('<') && targetRaw.endsWith('>');
+    return {
+        kind: 'side-effect',
+        // Scope resolution needs to distinguish a quoted header path from a bare
+        // @import module name and an angle-bracket system header. The latter stays
+        // wrapped so the Objective-C resolver can fail closed instead of resolving
+        // a framework header to a same-named local file.
+        targetRaw: isSystemHeader || kind === 'module' || targetRaw.startsWith('./')
+            ? targetRaw
+            : `./${targetRaw}`,
+    };
+}
+function interpretObjectiveCTypeBinding(captures) {
+    const name = captures['@type-binding.name'];
+    const type = captures['@type-binding.type'];
+    if (name === undefined || type === undefined)
+        return null;
+    const parsed = parseObjCType(type.text);
+    return {
+        boundName: name.text,
+        rawTypeName: parsed?.name ?? parsed?.raw ?? type.text,
+        declaredSpelling: type.text,
+        source: 'annotation',
+    };
+}
+export const objectiveCProvider = defineLanguage({
+    id: SupportedLanguages.ObjectiveC,
+    extensions: ['.m', '.mm'],
+    treeSitterQueries: OBJECTIVE_C_SCOPE_QUERY,
+    typeConfig: EMPTY_TYPE_CONFIG,
+    exportChecker: () => true,
+    importResolver: noImportResolution,
+    classifyFileContent: classifyObjectiveCFileContent,
+    shouldClassifyFileContent: isHeaderPath,
+    preprocessSource: preprocessObjectiveCMacroMarkers,
+    importsExecuteWhereWritten: false,
+    emitScopeCaptures: (sourceText, filePath, cachedTree) => {
+        const tree = treeFromCachedOrSource(cachedTree, sourceText);
+        const facts = collectObjectiveCFacts(tree, filePath);
+        setObjectiveCFileFacts(facts);
+        return buildObjectiveCScopeCaptures(facts, tree.rootNode);
+    },
+    collectCaptureSideChannel: (filePath) => assertCloneable(collectObjectiveCCaptureSideChannel(filePath)),
+    interpretImport: interpretObjectiveCImport,
+    interpretTypeBinding: interpretObjectiveCTypeBinding,
+    extractSemanticGraph: (tree, filePath) => {
+        const facts = collectObjectiveCFacts(tree, filePath);
+        setObjectiveCFileFacts(facts);
+        return buildObjectiveCSemanticGraph(facts);
+    },
+});

package/dist/core/ingestion/languages/typescript/query.d.ts

@@ -51,6 +51,37 @@
  */
 import Parser from 'tree-sitter';
 export declare const TYPESCRIPT_SCOPE_QUERY: string;
+/**
+ * JSX-only query suffix. Appended to the base query when compiling
+ * against the TSX grammar; NOT compiled against the plain TS grammar
+ * (which has no \`jsx_*\` node types and would reject these patterns).
+ *
+ * Why JSX as a CALLS edge: \`<Foo />\` is syntactic sugar for \`Foo(props)\`
+ * and the React component is invoked by the renderer, so for blast-radius
+ * (\`gitnexus_impact("Badge", direction: "upstream")\`) and call-graph
+ * (\`gitnexus_context("Foo")\`) purposes JSX usage IS a call. Routing
+ * through \`@reference.call.free\` / \`@reference.call.member\` makes the
+ * downstream caller-walk + edge-emission paths handle JSX uniformly with
+ * ordinary call expressions — no new edge type, no schema changes.
+ *
+ * Identifier-only JSX is filtered to PascalCase via \`(#match? ... "^[A-Z]")\`
+ * so \`<div>\`, \`<span>\`, \`<button>\` and other native HTML elements (which
+ * by JSX convention start lowercase) don't emit edges to nonexistent
+ * "div" / "span" symbols. Member-form JSX (\`<Foo.Bar />\`) is always a
+ * component (HTML element names can't contain dots), so no predicate
+ * filter is applied there.
+ *
+ * Both \`jsx_self_closing_element\` (\`<Foo />\`) and \`jsx_opening_element\`
+ * (\`<Foo>...</Foo>\`) emit; the closing tag is intentionally NOT captured —
+ * each JSX element should emit exactly one CALLS edge per use site.
+ */
+/**
+ * Exported alongside `TYPESCRIPT_SCOPE_QUERY` so
+ * `value-ref-dispatchability.test.ts` checks the whole query a `.tsx` file is
+ * analyzed with. Checking the base alone would miss a `value-ref` rule added
+ * here. Not part of the provider surface — use `getTsScopeQuery`.
+ */
+export declare const TSX_JSX_QUERY_SUFFIX = "\n;; <Foo />\n((jsx_self_closing_element\n  name: (identifier) @reference.name) @reference.call.free\n  (#match? @reference.name \"^[A-Z]\"))\n\n;; <Foo> ... </Foo>  (paired form \u2014 match the opening tag only)\n((jsx_opening_element\n  name: (identifier) @reference.name) @reference.call.free\n  (#match? @reference.name \"^[A-Z]\"))\n\n;; <Foo.Bar />  /  <Container.Section.Title />  \u2014 namespaced JSX\n(jsx_self_closing_element\n  name: (member_expression\n    object: (_) @reference.receiver\n    property: (property_identifier) @reference.name)) @reference.call.member\n\n(jsx_opening_element\n  name: (member_expression\n    object: (_) @reference.receiver\n    property: (property_identifier) @reference.name)) @reference.call.member\n";
 /**
  * Return the right tree-sitter parser for `filePath` (or the TS parser
  * when no path is given — the legacy callsite shape).

package/dist/core/ingestion/languages/typescript/query.js

@@ -1338,7 +1338,13 @@ export const TYPESCRIPT_SCOPE_QUERY = `
  * (\`<Foo>...</Foo>\`) emit; the closing tag is intentionally NOT captured —
  * each JSX element should emit exactly one CALLS edge per use site.
  */
-const TSX_JSX_QUERY_SUFFIX = `
+/**
+ * Exported alongside `TYPESCRIPT_SCOPE_QUERY` so
+ * `value-ref-dispatchability.test.ts` checks the whole query a `.tsx` file is
+ * analyzed with. Checking the base alone would miss a `value-ref` rule added
+ * here. Not part of the provider surface — use `getTsScopeQuery`.
+ */
+export const TSX_JSX_QUERY_SUFFIX = `
 ;; <Foo />
 ((jsx_self_closing_element
   name: (identifier) @reference.name) @reference.call.free

package/dist/core/ingestion/languages/typescript/tsconfig.js

@@ -234,9 +234,10 @@ async function firstReadableConfig(base) {
 async function findTsconfigFiles(repoRoot) {
     const found = [];
     const queue = [{ dir: repoRoot, depth: 0 }];
+    let queueHead = 0;
     let dirsScanned = 0;
-    while (queue.length > 0 && dirsScanned < SCAN_MAX_DIRS) {
-        const { dir, depth } = queue.shift();
+    while (queueHead < queue.length && dirsScanned < SCAN_MAX_DIRS) {
+        const { dir, depth } = queue[queueHead++];
         dirsScanned++;
         let entries;
         try {

package/dist/core/ingestion/languages/typescript.js

@@ -314,7 +314,7 @@ const TS_OWNED_RECEIVERS = new Set(['this']);
 const tsScopeOwnsReceivers = (match) => match['@receiver-owner.this'] === undefined ? undefined : TS_OWNED_RECEIVERS;
 export const typescriptProvider = defineLanguage({
     id: SupportedLanguages.TypeScript,
-    extensions: ['.ts', '.tsx'],
+    extensions: ['.ts', '.tsx', '.mts', '.cts'],
     entryPointPatterns: [/^use[A-Z]/],
     astFrameworkPatterns: [
         {

package/dist/core/ingestion/languages/zig/query.d.ts

@@ -1,3 +1,29 @@
 import Parser from 'tree-sitter';
+/**
+ * Zig scope-resolution query (RFC #909 Ring 3).
+ *
+ * The grammar is vendored (`vendor/tree-sitter-zig`) and may be absent on a
+ * platform without a prebuild, so the language module is required lazily and
+ * `getZigParser` / `getZigScopeQuery` throw only when actually invoked without
+ * the grammar installed. That is safe: the parse pipeline filters `.zig` files
+ * through `parser-loader.isLanguageAvailable` before any scope extraction runs.
+ *
+ * Zig specifics encoded here:
+ *   - Containers (struct/enum/union/opaque) are anonymous nodes bound by the
+ *     enclosing `variable_declaration`; declarations capture the binding
+ *     identifier from the wrapper.
+ *   - `@import` is a builtin call, not import-statement syntax; the
+ *     `#eq?` predicate keeps other builtins (@sizeOf, @as, …) out.
+ *   - A plain `(variable_declaration (identifier))` rule would also match
+ *     container and import bindings — `emitZigScopeCaptures` filters those
+ *     groups out so a name binds exactly once.
+ */
+/**
+ * Exported for `value-ref-dispatchability.test.ts`, which reads every language's
+ * scope query to enforce the keyed/unkeyed partition that
+ * `callableValueReferenceBoundaries`' dispatch exclusion depends on. Not part of
+ * the provider surface — nothing else should import it.
+ */
+export declare const ZIG_SCOPE_QUERY = "\n;; Scopes\n(source_file) @scope.module\n(struct_declaration) @scope.class\n(enum_declaration) @scope.class\n(union_declaration) @scope.class\n(opaque_declaration) @scope.class\n(function_declaration) @scope.function\n(test_declaration) @scope.function\n(block) @scope.block\n\n;; Declarations \u2014 functions (relabeled @declaration.method inside containers\n;; by emitZigScopeCaptures, mirroring the provider's labelOverride)\n(function_declaration\n  name: (identifier) @declaration.name) @declaration.function\n\n;; Declarations \u2014 named tests. Same naming rule as ZIG_QUERIES: the string\n;; node WITH quotes, so the def joins the graph node and never collides with\n;; a same-named fn. Anonymous / decl-form tests are scopes without a def.\n(test_declaration\n  (string) @declaration.name) @declaration.function\n\n;; Declarations \u2014 containers. The binding name lives on the wrapper\n;; variable_declaration, but the ANCHOR is the container node itself so its\n;; range equals the @scope.class range: the extractor then attaches the def\n;; to the class scope (walkers.populateClassOwnedMembers expects the\n;; class-like def among the class scope's ownedDefs) and auto-hoists the\n;; name binding to the parent scope. Keyword-gated like the ordinary\n;; binding rules: a keyword-less `x = struct {\u2026};` is an assignment\n;; (tree-sitter-zig 1.1.2 reuses variable_declaration), not a container def.\n(variable_declaration\n  \"const\" . (identifier) @declaration.name\n  (struct_declaration) @declaration.struct)\n(variable_declaration\n  \"var\" . (identifier) @declaration.name\n  (struct_declaration) @declaration.struct)\n(variable_declaration\n  \"const\" . (identifier) @declaration.name\n  (enum_declaration) @declaration.enum)\n(variable_declaration\n  \"var\" . (identifier) @declaration.name\n  (enum_declaration) @declaration.enum)\n(variable_declaration\n  \"const\" . (identifier) @declaration.name\n  (union_declaration) @declaration.union)\n(variable_declaration\n  \"var\" . (identifier) @declaration.name\n  (union_declaration) @declaration.union)\n;; opaque {} is a fieldless container that may own methods \u2014 Struct, as in\n;; ZIG_QUERIES (see the rationale there).\n(variable_declaration\n  \"const\" . (identifier) @declaration.name\n  (opaque_declaration) @declaration.struct)\n(variable_declaration\n  \"var\" . (identifier) @declaration.name\n  (opaque_declaration) @declaration.struct)\n\n;; Declarations \u2014 generic type constructors. `fn List(comptime T: type) type\n;; { return struct {\u2026}; }` is Zig's only spelling of a generic type; the\n;; returned container is anonymous in the grammar but every reader (and every\n;; caller: `List(u8)`) names it after the function. Anchor on the container\n;; so the def sits in its own class scope; the name binding is hoisted to the\n;; MODULE scope by `zigBindingScopeFor` (not the fn body, where the name\n;; would be invisible to callers) and coexists with the Function def of the\n;; same name \u2014 `List` really is both a callable and a type.\n((function_declaration\n  name: (identifier) @declaration.name\n  type: (builtin_type) @_ret\n  body: (block (expression_statement (return_expression\n    (struct_declaration) @declaration.struct))))\n  (#eq? @_ret \"type\"))\n((function_declaration\n  name: (identifier) @declaration.name\n  type: (builtin_type) @_ret\n  body: (block (expression_statement (return_expression\n    (union_declaration) @declaration.union))))\n  (#eq? @_ret \"type\"))\n((function_declaration\n  name: (identifier) @declaration.name\n  type: (builtin_type) @_ret\n  body: (block (expression_statement (return_expression\n    (enum_declaration) @declaration.enum))))\n  (#eq? @_ret \"type\"))\n\n;; Declarations \u2014 container fields (struct fields, enum/union variants).\n;; The #not-eq? guard drops the MISSING placeholder identifier tree-sitter-zig\n;; recovers for an empty container body (see ZIG_QUERIES). The optional\n;; `type:` (absent on enum variants) is captured as @declaration.field-type:\n;; `emitZigScopeCaptures` turns it into a @type-binding.field on the\n;; container's Class scope so `self.session.name()` can walk the field's\n;; type (Rust/Go parity \u2014 see the F5 block in captures.ts).\n((container_field\n  name: (identifier) @declaration.name\n  type: (_)? @declaration.field-type) @declaration.field\n  (#not-eq? @declaration.name \"\"))\n\n;; Declarations \u2014 const/var bindings (import/container groups filtered in TS).\n;; The `.` anchor pins the FIRST named child: without it the pattern also\n;; matched the initializer of `const first = target;`, minting a phantom\n;; local named `target` that shadowed the real callee for every later\n;; reference in the block. The literal keyword is load-bearing too:\n;; tree-sitter-zig 1.1.2 parses statement assignments (`x = 5;`, `x += 1;`,\n;; `_ = expr;`) as `variable_declaration` WITHOUT a keyword child, and\n;; without the keyword every assignment and every discard minted a phantom\n;; local (one `_` per statement).\n(variable_declaration\n  \"const\" . (identifier) @declaration.name) @declaration.variable\n(variable_declaration\n  \"var\" . (identifier) @declaration.name) @declaration.variable\n\n;; Imports \u2014 const x = @import(\"...\") / var x = @import(\"...\"). Keyword-gated\n;; like every binding rule: a keyword-less `x = @import(\"...\")` is a\n;; statement (see the side-effect rule below), not a binding.\n(variable_declaration\n  \"const\" . (identifier) @import.name\n  (builtin_function\n    (builtin_identifier) @_builtin\n    (arguments (string) @import.source))\n  (#eq? @_builtin \"@import\")) @import.statement\n(variable_declaration\n  \"var\" . (identifier) @import.name\n  (builtin_function\n    (builtin_identifier) @_builtin\n    (arguments (string) @import.source))\n  (#eq? @_builtin \"@import\")) @import.statement\n\n;; Imports \u2014 const X = @import(\"...\").X : a NAMED import of one member. The\n;; local name is whatever the user chose (`const Alloc = @import(\"std\").mem;`\n;; is a rename), the imported name is the member. A deeper chain\n;; (`@import(\"std\").mem.Allocator`, `@import(\"lib.zig\").B.work`) is matched\n;; by the second rule below but is NOT bound as a named import of the\n;; innermost member: that discarded the written owner (`B`) and let a\n;; same-named `A.work` answer first. `emitZigScopeCaptures` binds the module\n;; under the builtin's text instead and rewrites the alias's use sites to the\n;; full path (`collectZigDeepAliases`, PR #1432 review 8.4).\n(variable_declaration\n  \"const\" . (identifier) @import.name\n  (field_expression\n    object: (builtin_function\n      (builtin_identifier) @_builtin\n      (arguments (string) @import.source))\n    member: (identifier) @import.imported)\n  (#eq? @_builtin \"@import\")) @import.statement\n(variable_declaration\n  \"const\" . (identifier) @import.name\n  (field_expression\n    object: (field_expression\n      object: (builtin_function\n        (builtin_identifier) @_builtin\n        (arguments (string) @import.source)))\n    member: (identifier) @import.imported)\n  (#eq? @_builtin \"@import\")) @import.statement\n\n;; Imports \u2014 a keyword-less `<ident> = @import(\"...\");` statement\n;; (`_ = @import(\"all_tests.zig\");` in a test block, the refAllDecls\n;; idiom): tree-sitter-zig reuses `variable_declaration` for assignments, so\n;; the shape is a declaration minus the keyword. It references the file\n;; without binding a name \u2014 a side-effect import. Tree-sitter queries cannot\n;; say \"no keyword child\", so this rule matches the keyword-bearing shapes\n;; too; `emitZigScopeCaptures` keeps it only when `isZigKeywordDeclaration`\n;; is false (the keyword shapes are the binding rules above).\n(variable_declaration\n  . (identifier)\n  (builtin_function\n    (builtin_identifier) @_builtin\n    (arguments (string) @import.source))\n  (#eq? @_builtin \"@import\")) @import.side-effect\n\n;; Aliases of a namespace member \u2014 const Counter = counter.Counter; where\n;; `counter` is an @import binding of THIS file. The query cannot know which\n;; identifiers are import bindings, so it captures every one-level member\n;; alias and `emitZigScopeCaptures` promotes the ones whose object is a\n;; known @import to a named import (same fact as `const Counter =\n;; @import(\"counter.zig\").Counter;`); the rest stay ordinary variables.\n;; Only the ONE-level shape is promoted; a deeper chain (`lib.B.work`,\n;; `std.mem.Allocator`) is a deep alias \u2014 a Const whose use sites are\n;; rewritten to the written owner path (see the import rule above, 8.4).\n(variable_declaration\n  \"const\" . (identifier) @alias.name\n  (field_expression\n    object: (identifier) @alias.namespace\n    member: (identifier) @alias.member) .) @alias.statement\n(variable_declaration\n  \"const\" . (identifier) @alias.name\n  (field_expression\n    object: (field_expression\n      object: (identifier) @alias.namespace)\n    member: (identifier) @alias.member) .) @alias.statement\n\n;; Imports \u2014 pub usingnamespace @import(\"...\"); : every pub decl of the target\n;; becomes a decl of this container (removed from the language in 0.15, still\n;; everywhere in 0.11\u20130.14 code). Modelled as a wildcard import.\n(using_namespace_declaration\n  (builtin_function\n    (builtin_identifier) @_builtin\n    (arguments (string) @import.source))\n  (#eq? @_builtin \"@import\")) @import.wildcard\n\n;; Imports \u2014 `@import(\"...\")` in ANY other position: a tuple element\n;; (`pub const Interfaces = .{ @import(\"a.zig\"), @import(\"b.zig\") }`, the\n;; JS-API registration table), a call argument (`event.is(@import(\"x.zig\"))`),\n;; a comparison operand (`T == @import(\"x.zig\").T`), the receiver of a\n;; member call (`try @import(\"dump.zig\").root(...)`), a 3-deep member chain\u2026\n;; Every one of them is a file dependency; only the const/var/usingnamespace\n;; shapes above bind a name. This rule matches EVERY `@import` builtin, the\n;; bound shapes included \u2014 `emitZigScopeCaptures` drops the matches whose\n;; string node a binding rule (or the keyword-less side-effect rule) already\n;; claimed, so a bound import is never doubled, and emits the rest as\n;; side-effect imports (file edge, no binding) \u2014 except the member-call\n;; receiver, which becomes a namespace import keyed by its own source text so\n;; the call resolves into the imported module (see the emitter).\n((builtin_function\n  (builtin_identifier) @_builtin\n  (arguments (string) @import.source))\n  (#eq? @_builtin \"@import\")) @import.inline\n\n;; Type bindings \u2014 parameter annotations (incl. self: *T receivers)\n(parameter\n  name: (identifier) @type-binding.name\n  type: (_) @type-binding.type) @type-binding.parameter\n\n;; Type bindings \u2014 constructor inference: const p = T{ ... }. Keyword-gated\n;; like every binding rule: a keyword-less `p = T{ ... };` is a\n;; re-assignment (same node type in tree-sitter-zig 1.1.2), and Zig's static\n;; typing means `p` already carries its type from its declaration\n;; (annotation, constructor or inferred value) \u2014 the assignment declares\n;; nothing, and `_ = T{ ... };` must not bind `_`.\n(variable_declaration\n  \"const\" . (identifier) @type-binding.name\n  (struct_initializer\n    (identifier) @type-binding.type)) @type-binding.constructor\n(variable_declaration\n  \"var\" . (identifier) @type-binding.name\n  (struct_initializer\n    (identifier) @type-binding.type)) @type-binding.constructor\n\n;; Type bindings \u2014 qualified constructor: const p = mod.T{ ... }. The whole\n;; field_expression is captured so the dotted text \"mod.T\" survives \u2014\n;; receiver dispatch resolves the namespace prefix through the import\n;; binding (emitReceiverBoundCalls Case 3).\n(variable_declaration\n  \"const\" . (identifier) @type-binding.name\n  (struct_initializer\n    (field_expression) @type-binding.type)) @type-binding.constructor\n(variable_declaration\n  \"var\" . (identifier) @type-binding.name\n  (struct_initializer\n    (field_expression) @type-binding.type)) @type-binding.constructor\n\n;; Type bindings \u2014 generic instantiation literal: const l = List(u8){ ... }.\n;; The callee is the type constructor; `normalizeZigTypeName` drops the\n;; comptime argument list so `List(u8)` looks up `List`.\n(variable_declaration\n  \"const\" . (identifier) @type-binding.name\n  (struct_initializer\n    (call_expression) @type-binding.type)) @type-binding.constructor\n(variable_declaration\n  \"var\" . (identifier) @type-binding.name\n  (struct_initializer\n    (call_expression) @type-binding.type)) @type-binding.constructor\n\n;; Type bindings \u2014 declared type: var x: T = \u2026; const x: T = .init(\u2026);\n;; The annotation is the ONLY type source for `= undefined` and for 0.14+\n;; decl literals (`.init`, `.empty`), which are the idiomatic\n;; constructors in current std. Ranked below constructor inference by the\n;; shared resolver (source 'annotation'), so a literal on the right still\n;; wins when both are present.\n(variable_declaration\n  . (identifier) @type-binding.name\n  type: (_) @type-binding.type) @type-binding.annotation\n\n;; Type bindings \u2014 value inference (F6): const t = <value>; where <value> is a\n;; call (`Counter.init()`, `makeThing()`, `node.asElement()`), possibly\n;; wrapped in `try` / `catch \u2026` / `\u2026 orelse \u2026` / parentheses \u2014 the shape of\n;; nearly every Zig constructor call (`const p = try Page.init(\u2026)`). The\n;; query only pins the declaration; `emitZigScopeCaptures` unwraps the\n;; wrappers and rewrites `@type-binding.type` to the type source (see\n;; `zigCallReturnTypeOf`). Keyword-gated: `_ = e.top();` is an assignment\n;; (same node type), not a binding of `_`. Rust's twin is\n;; `let x = Foo::new()` / `let x = foo().await`.\n(variable_declaration\n  \"const\" . (identifier) @type-binding.name\n  (_) @type-binding.value .) @type-binding.call-return\n(variable_declaration\n  \"var\" . (identifier) @type-binding.name\n  (_) @type-binding.value .) @type-binding.call-return\n\n;; Type bindings \u2014 return-type annotation (F6): `fn make() !*Thing` binds\n;; `make \u21A6 Thing` in the enclosing scope (Module for free fns, the container's\n;; Class scope for methods \u2014 that is where the compound resolver reads a\n;; method's return type for `node.asElement()`), so `const t = makeThing()`\n;; chains to `Thing`. Rust: `(function_item \u2026 return_type:) @type-binding.return`.\n;; `emitZigScopeCaptures` drops builtin / `type` returns (a `List \u21A6 type`\n;; binding would hijack the `List(u8){}` constructor chain).\n(function_declaration\n  name: (identifier) @type-binding.name\n  type: (_) @type-binding.type) @type-binding.return\n\n;; Type bindings \u2014 aliases (F5 field-access aliases + F7 type aliases):\n;; `const page = self.page;` (F5: the RHS path is kept verbatim as the\n;; \"type\", the compound resolver's member-alias branch re-resolves it as a\n;; receiver chain \u2014 head `self` \u2192 class \u2192 field type), `const LocalAlias = Local;`,\n;; `const Proto = HtmlElement;`, `const T2 = Thing;` (alias of an alias /\n;; import), `const B = util.List(u8);` (an INSTANTIATED generic type\n;; constructor). Zig has no `type X = Y` syntax \u2014 a type alias is a const\n;; whose value is a type expression, and it stays a Const in the graph. What\n;; must change is the scope side: bind the alias NAME to the value's type\n;; text (Rust's `let x = y` / JS's `const B = Foo` `@type-binding.alias`,\n;; source 'assignment-inferred'), so `LocalAlias.mk()` types through Case 4,\n;; `B.init()` / `x: B` / `B{}` through Case 3 once `normalizeZigTypeName`\n;; drops the comptime arguments (`util.List(u8)` \u2192 `util.List`), and every\n;; binding that names the alias (`var l = LocalAlias.mk()`, `var x: B`) is\n;; chained to the target by the shared `followChainedRef` /\n;; `followChainPostFinalize`. The identifier / member shapes take `var` too:\n;; `var node = orig_node;` is the same value alias as Rust's `let x = y`\n;; and chains to the type of `orig_node` (a Zig type is comptime and never\n;; `var`, so the type-alias reading only ever applies to `const`). The\n;; call shape is `const`-only and kept only when the callee's last\n;; identifier is TitleCase \u2014 see `emitZigScopeCaptures` (a value call\n;; `const t = util.makeThing()` belongs to the call-return rules above and\n;; must not receive a competing binding). A promoted namespace-member alias\n;; (`const Counter = counter.Counter;` \u2192 named import) is skipped there too:\n;; the import binding already carries the type.\n(variable_declaration\n  \"const\" . (identifier) @type-binding.name\n  (identifier) @type-binding.type .) @type-binding.alias\n(variable_declaration\n  \"var\" . (identifier) @type-binding.name\n  (identifier) @type-binding.type .) @type-binding.alias\n(variable_declaration\n  \"const\" . (identifier) @type-binding.name\n  (field_expression) @type-binding.type .) @type-binding.alias\n(variable_declaration\n  \"var\" . (identifier) @type-binding.name\n  (field_expression) @type-binding.type .) @type-binding.alias\n(variable_declaration\n  \"const\" . (identifier) @type-binding.name\n  (call_expression) @type-binding.type .) @type-binding.alias\n\n;; References \u2014 VALUE positions (#3399): a callable named where a value is\n;; expected rather than where a callee is. Zig's JS bridge is built entirely\n;; out of this shape \u2014\n;;\n;;     pub const namespaceURI = bridge.accessor(Element.getNamespaceUri, null, .{});\n;;\n;; \u2014 2,047 such declarations across 257 files in lightpanda-io/browser, the\n;; project's whole JS\u2194Zig surface, and NONE of them reached the graph: Zig\n;; emitted no `value-ref` capture at all, so a public DOM accessor's only\n;; recorded callers were the two internal ones and `impact` called that `exact`.\n;;\n;; These become reference-class USES edges through the existing\n;; `mapReferenceKindToEdgeType` mapping \u2014 a registration is not an invocation\n;; (Kythe `ref` vs `ref/call`; Joern `METHOD_REF`) \u2014 resolved by the\n;; property-dispatch pass, which keeps ONLY callable targets. That callable gate\n;; is what makes these deliberately broad rules safe: `js.Bridge(Element)` and\n;; `register(count)` match too, and emit nothing, exactly as TypeScript's\n;; `{ port: DEFAULT_PORT }` does.\n;;\n;; No `@reference.property-key` is attached: Zig has no object-literal key to\n;; dispatch through, so these register a reference and never synthesize CALLS.\n;; The terminal invoke \u2014 `Accessor.init` \u2192 a struct field \u2192 `Factory.zig`'s\n;; `inline for`/`@typeInfo` \u2192 `@call(.auto, func, args)` \u2014 needs comptime\n;; evaluation and is deliberately NOT modelled; `impact` reports the shortfall\n;; as `epistemic: \"lower-bound\"` instead of pretending to certainty.\n\n;; Call ARGUMENTS. In tree-sitter-zig arguments are direct children of\n;; `call_expression`, NOT wrapped in an `arguments` node (only builtins have\n;; one), so the callee has to be consumed explicitly by `function:` \u2014 without\n;; that binding the same rule also matches the callee of `foo(bar)` and mints a\n;; USES edge duplicating the call.\n(call_expression\n  function: (_)\n  (identifier) @reference.name @reference.value-ref)\n\n;; Qualified argument \u2014 `bridge.accessor(Element.getNamespaceUri, \u2026)`. The\n;; RECEIVER is captured alongside the member so the site carries the owner it\n;; was written with; `@reference.name` stays the member, which is the name the\n;; scope walk resolves.\n(call_expression\n  function: (_)\n  (field_expression\n    object: (_) @reference.receiver\n    member: (identifier) @reference.name) @reference.value-ref)\n\n;; Const binding initialiser \u2014 `pub const defaultHandler = onReset;`. Both\n;; anchors are load-bearing: the leading `.` pins the bound name to the first\n;; named child (see the declaration rules above), and the trailing `.` keeps the\n;; initializer as the LAST child, so a `const x: T = y` annotation shape cannot\n;; put the TYPE in value position.\n(variable_declaration\n  \"const\" . (identifier)\n  (identifier) @reference.name @reference.value-ref .)\n\n;; References \u2014 free calls: foo(...)\n(call_expression\n  function: (identifier) @reference.name) @reference.call.free\n\n;; References \u2014 member calls: obj.method(...) / mod.fn(...)\n(call_expression\n  function: (field_expression\n    object: (_) @reference.receiver\n    member: (identifier) @reference.name)) @reference.call.member\n\n;; References \u2014 constructor uses: T{ ... }\n(struct_initializer\n  (identifier) @reference.name) @reference.call.constructor\n\n;; References \u2014 qualified constructor uses: mod.T{ ... } / hub.sub.T{ ... }\n;; Captured with the RECEIVER, not as a free constructor with a raw qualified\n;; name, on purpose: the free-call fallback resolves a qualified constructor by\n;; its simple tail, and a workspace-unique `Thing` then answers for\n;; `other.Thing{}` whichever module the source named (measured: `c.Thing{}`\n;; with no `Thing` in c.zig bound to a.zig's). With the receiver the site goes\n;; through the receiver-bound namespace case, which resolves the member inside\n;; the module the receiver is bound to \u2014 the same path `mod.fn()` takes \u2014 so\n;; `a.Thing{}` and `b.Thing{}` each bind their own file and `std.Thread.Mutex{}`\n;; binds nothing even when a local `Mutex` exists.\n(struct_initializer\n  (field_expression\n    object: (_) @reference.receiver\n    member: (identifier) @reference.name)) @reference.call.constructor\n\n;; References \u2014 generic instantiation literals: List(u8){ ... } /\n;; lists.List(u8){ ... }. The type head is a call_expression \u2014 the\n;; instantiation of the type constructor \u2014 which neither constructor rule\n;; above matches, so the OUTER aggregate event had no site: only the inner\n;; `List(u8)` call (a free / member call reference on the call node) reached\n;; the graph (PR #1432 review, 8.11). Two sites on two anchors: the call\n;; (an invocation of `List`) and this initializer (a construction of the\n;; container `List` returns, marked `(constructor)`). The receiver form goes\n;; through the same namespace path as `mod.T{}`.\n(struct_initializer\n  (call_expression\n    function: (identifier) @reference.name)) @reference.call.constructor\n(struct_initializer\n  (call_expression\n    function: (field_expression\n      object: (_) @reference.receiver\n      member: (identifier) @reference.name))) @reference.call.constructor\n";
 export declare function getZigParser(): Parser;
 export declare function getZigScopeQuery(): Parser.Query;

package/dist/core/ingestion/languages/zig/query.js

@@ -19,7 +19,13 @@ import { requireVendoredGrammar } from '../../../tree-sitter/vendored-grammars.j
  *     container and import bindings — `emitZigScopeCaptures` filters those
  *     groups out so a name binds exactly once.
  */
-const ZIG_SCOPE_QUERY = `
+/**
+ * Exported for `value-ref-dispatchability.test.ts`, which reads every language's
+ * scope query to enforce the keyed/unkeyed partition that
+ * `callableValueReferenceBoundaries`' dispatch exclusion depends on. Not part of
+ * the provider surface — nothing else should import it.
+ */
+export const ZIG_SCOPE_QUERY = `
 ;; Scopes
 (source_file) @scope.module
 (struct_declaration) @scope.class
@@ -358,6 +364,60 @@ const ZIG_SCOPE_QUERY = `
   "const" . (identifier) @type-binding.name
   (call_expression) @type-binding.type .) @type-binding.alias
 
+;; References — VALUE positions (#3399): a callable named where a value is
+;; expected rather than where a callee is. Zig's JS bridge is built entirely
+;; out of this shape —
+;;
+;;     pub const namespaceURI = bridge.accessor(Element.getNamespaceUri, null, .{});
+;;
+;; — 2,047 such declarations across 257 files in lightpanda-io/browser, the
+;; project's whole JS↔Zig surface, and NONE of them reached the graph: Zig
+;; emitted no \`value-ref\` capture at all, so a public DOM accessor's only
+;; recorded callers were the two internal ones and \`impact\` called that \`exact\`.
+;;
+;; These become reference-class USES edges through the existing
+;; \`mapReferenceKindToEdgeType\` mapping — a registration is not an invocation
+;; (Kythe \`ref\` vs \`ref/call\`; Joern \`METHOD_REF\`) — resolved by the
+;; property-dispatch pass, which keeps ONLY callable targets. That callable gate
+;; is what makes these deliberately broad rules safe: \`js.Bridge(Element)\` and
+;; \`register(count)\` match too, and emit nothing, exactly as TypeScript's
+;; \`{ port: DEFAULT_PORT }\` does.
+;;
+;; No \`@reference.property-key\` is attached: Zig has no object-literal key to
+;; dispatch through, so these register a reference and never synthesize CALLS.
+;; The terminal invoke — \`Accessor.init\` → a struct field → \`Factory.zig\`'s
+;; \`inline for\`/\`@typeInfo\` → \`@call(.auto, func, args)\` — needs comptime
+;; evaluation and is deliberately NOT modelled; \`impact\` reports the shortfall
+;; as \`epistemic: "lower-bound"\` instead of pretending to certainty.
+
+;; Call ARGUMENTS. In tree-sitter-zig arguments are direct children of
+;; \`call_expression\`, NOT wrapped in an \`arguments\` node (only builtins have
+;; one), so the callee has to be consumed explicitly by \`function:\` — without
+;; that binding the same rule also matches the callee of \`foo(bar)\` and mints a
+;; USES edge duplicating the call.
+(call_expression
+  function: (_)
+  (identifier) @reference.name @reference.value-ref)
+
+;; Qualified argument — \`bridge.accessor(Element.getNamespaceUri, …)\`. The
+;; RECEIVER is captured alongside the member so the site carries the owner it
+;; was written with; \`@reference.name\` stays the member, which is the name the
+;; scope walk resolves.
+(call_expression
+  function: (_)
+  (field_expression
+    object: (_) @reference.receiver
+    member: (identifier) @reference.name) @reference.value-ref)
+
+;; Const binding initialiser — \`pub const defaultHandler = onReset;\`. Both
+;; anchors are load-bearing: the leading \`.\` pins the bound name to the first
+;; named child (see the declaration rules above), and the trailing \`.\` keeps the
+;; initializer as the LAST child, so a \`const x: T = y\` annotation shape cannot
+;; put the TYPE in value position.
+(variable_declaration
+  "const" . (identifier)
+  (identifier) @reference.name @reference.value-ref .)
+
 ;; References — free calls: foo(...)
 (call_expression
   function: (identifier) @reference.name) @reference.call.free

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

@@ -17,6 +17,14 @@
  *
  * Runs after `propagateImportedReturnTypes`, so return bindings hoisted from
  * other files are visible when a subject is a call.
+ *
+ * This hook also carries `bindZigThisAliases` (`this-alias-bindings.ts`), which
+ * is a different job — binding `const Self = @This();` to its container — but
+ * needs the same thing this pass is already paying for: the file's parsed tree,
+ * post-finalize. Giving it a pass of its own would re-parse every Zig file in
+ * the repo whenever the tree cache is cold. That is the whole reason it is
+ * here; the two do not otherwise interact, for the reason recorded at the call
+ * site.
  */
 import type { ParsedFile } from '../../../../_shared/index.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';

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

@@ -17,6 +17,14 @@
  *
  * Runs after `propagateImportedReturnTypes`, so return bindings hoisted from
  * other files are visible when a subject is a call.
+ *
+ * This hook also carries `bindZigThisAliases` (`this-alias-bindings.ts`), which
+ * is a different job — binding `const Self = @This();` to its container — but
+ * needs the same thing this pass is already paying for: the file's parsed tree,
+ * post-finalize. Giving it a pass of its own would re-parse every Zig file in
+ * the repo whenever the tree cache is cold. That is the whole reason it is
+ * here; the two do not otherwise interact, for the reason recorded at the call
+ * site.
  */
 import { getZigParser } from './query.js';
 import { getTreeSitterBufferSize } from '../../constants.js';
@@ -24,6 +32,7 @@ import { parseSourceSafe, ParseTimeoutError } from '../../../tree-sitter/safe-pa
 import { logger } from '../../../logger.js';
 import { findClassBindingInScope, findReceiverTypeBinding, isClassLike, } from '../../scope-resolution/scope/walkers.js';
 import { isZigKeywordDeclaration, zigUnwrapValue } from './captures.js';
+import { bindZigThisAliases } from './this-alias-bindings.js';
 import { normalizeZigTypeName } from './interpret.js';
 const PAYLOAD_HOSTS = new Set([
     'for_statement',
@@ -70,6 +79,21 @@ export function populateZigRangeBindings(parsedFiles, indexes, ctx) {
         const scopes = parsed.scopes;
         if (scopes.length === 0)
             continue;
+        // `const Self = @This();` — bind the alias to its container. It sits in this
+        // loop for ONE reason: the tree. A pass of its own would re-parse every Zig
+        // file in the repo whenever the tree cache is cold.
+        //
+        // Its position relative to the payload walk below is NOT load-bearing, and
+        // saying otherwise would be wrong in a checkable way: the payload walk types
+        // a subject through `findReceiverTypeBinding`, which reads `typeBindings`
+        // and the namespace/workspace type channels — never `bindingAugmentations`,
+        // where this writes. Measured on `for (Self.items) |it|`: `it` is bound
+        // neither before nor after. Nor is that a gap this should close by also
+        // writing a typeBinding — NO container name has one, the file stem included,
+        // so a payload subject written `Type.member` resolves for no spelling at
+        // all, and giving the alias an entry would make it behave unlike the very
+        // container it names.
+        bindZigThisAliases(parsed, tree.rootNode, indexes);
         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| … }`).

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

@@ -5,8 +5,9 @@
  * 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`.
+ * same `resolveZigImportInternal` the legacy import-resolver config wraps, with
+ * the repo's Zig build packages threaded through `loadResolutionConfig` and the
+ * one governing each file selected per-file by `zigPackageFor`.
  */
 import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
 export declare const zigScopeResolver: ScopeResolver;