gitnexus 1.6.11-rc.8 → 1.6.11

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

@@ -0,0 +1,260 @@
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+/** Zig container node types: `struct`, `enum`, `union` and the fieldless
+ *  `opaque` all bind through `const T = <container> {…}` and may own methods.
+ *  Single source for the class/field/method extractor configs. */
+export declare const ZIG_CONTAINER_TYPES: ReadonlySet<string>;
+/** The `@import(…)` call at the ROOT of a value expression: the value itself
+ *  (`@import("x.zig")`) or the leftmost object of a member chain
+ *  (`@import("x.zig").Foo`, `@import("std").mem.Allocator`). Null otherwise. */
+export declare function zigImportRootOf(value: SyntaxNode | null): SyntaxNode | null;
+/** Is this `@import(…)` builtin the receiver of a member call —
+ *  `@import("dump.zig").root(...)` — or of a qualified construction —
+ *  `@import("a.zig").Thing{…}` — i.e. the `object` of a `field_expression`
+ *  that is the `function` of a `call_expression` or the type of a
+ *  `struct_initializer`? A deeper chain (`@import("x.zig").Foo.init()`) is
+ *  not: its receiver is `….Foo`, and the builtin is only the module the chain
+ *  starts from (the namespace chain walk resolves it from there). */
+export declare function isZigInlineImportReceiver(importNode: SyntaxNode): boolean;
+/** Is this variable_declaration a container binding (`const T = struct {…}`)
+ *  or an import binding (`const x = @import("…")`, `const X = @import("…").X`)?
+ *  Those groups are emitted by their dedicated query rules; the plain
+ *  @declaration.variable / @definition.const match for the same node must be
+ *  dropped so the name binds exactly once (and no Const node shadows the
+ *  Struct / import). Shared by the scope walker, the variable extractor and
+ *  the provider's `shouldSkipDefinitionCapture` so the structure-phase records
+ *  and the scope-side bindings agree on what counts as a plain variable. */
+/** A binding whose name the type system already owns: a container / import
+ *  binding, or the top-level `@This()` self-alias of a file-struct. None of
+ *  these may mint a Const beside the Struct / import they stand for. */
+export declare function isZigTypeShadowingBinding(declNode: SyntaxNode): boolean;
+export declare function isZigContainerOrImportBinding(declNode: SyntaxNode): boolean;
+/** Does the `@import(…)` a binding rule matched sit in the TYPE annotation of
+ *  its declaration (`var x: @import("foo.zig").T = undefined;`) rather than
+ *  in its value? `variable_declaration` is fieldless except for `type:`, so
+ *  the query cannot tell the two positions apart; such a match must not bind
+ *  `x` as an import — `x` is a variable, and the `@import` is only a file
+ *  dependency (the `@import.inline` rule records it as a side-effect import
+ *  once this match releases the source node). */
+export declare function isZigTypePositionImport(stmt: SyntaxNode, source: SyntaxNode): boolean;
+/** Does this `variable_declaration` carry a `const` / `var` keyword child?
+ *  tree-sitter-zig 1.1.2 parses statement-position ASSIGNMENTS (`x = 5;`,
+ *  `x += 1;`, `_ = expr;`) as `variable_declaration` too — the only thing
+ *  that separates a real binding from a re-assignment is the keyword. Query
+ *  rules match the keyword literally; this is the JS-side twin for the
+ *  extractors and the phantom-local guard in `emitZigScopeCaptures`. */
+export declare function isZigKeywordDeclaration(declNode: SyntaxNode): boolean;
+/** Is `root` a FILE-STRUCT — a `.zig` file that IS a type? In Zig every file
+ *  is a struct; the ones that matter as types are named after the file stem
+ *  (`Page.zig` declares `Page`, `@typeName(Page)` is `"Page"`) and their
+ *  top-level `fn`s taking a receiver are its methods. Two signals, either one
+ *  suffices:
+ *    - the top level declares at least one container field (an instantiable
+ *      type with state); the MISSING-identifier placeholder tree-sitter-zig
+ *      recovers for an empty body is not a field (see
+ *      `zigFieldConfig.extractName`);
+ *    - a top-level `fn` takes the file's OWN type as its first parameter —
+ *      `self: *@This()`, or `self: *Self` with `const Self = @This();` at
+ *      file level. A zero-sized file type (`Empty.zig`: no field, a `Self`
+ *      alias and `pub fn ping(self: *Self)`) is still constructed (`Empty{}`)
+ *      and dispatched on by importers; keyed on fields alone it lost its
+ *      `Struct`, its `HAS_METHOD`s and every `e.ping()` edge (PR #1432
+ *      review, 8.12).
+ *  A file with neither is a namespace and stays a Module: its fns keep their
+ *  `Function` ids, and a `const js = @This();` there stays a Const. Only the
+ *  receiver TYPE decides, never the parameter name: `fn f(self: Foo)` in a
+ *  utility file is a free function that happens to call its argument `self`. */
+export declare function isZigFileStruct(root: SyntaxNode | null | undefined): boolean;
+/** The type name a file-struct declares: the file stem (`src/browser/Page.zig`
+ *  → `Page`). This is what importers write (`const Page = @import("Page.zig")`)
+ *  and what `@typeName` reports; the in-file `const Page = @This();` alias is
+ *  a second spelling of the same type (see `zigThisAliasTargets`). */
+export declare function zigFileStructName(filePath: string): string;
+/** Is `declNode` a top-level `const X = @This();` — the idiomatic self-alias of
+ *  a file-struct? Such a binding names the FILE's own type, so a file-struct
+ *  must not mint a `Const` (graph node or scope binding) beside the `Struct`
+ *  it aliases — the Const would shadow the type for every `x: *Page`. */
+export declare function isZigFileThisAlias(declNode: SyntaxNode): boolean;
+/** Does this module-level import binding REPUBLISH the name? `pub const Arena
+ *  = @import("Arena.zig");` at file scope makes `Arena` part of this file's
+ *  public surface: a third file reaches it as `lp.Arena` (Lightpanda's
+ *  `lightpanda.zig` is one long list of these). Same fact as a Python
+ *  `__init__.py` `from .impl import X` — the shared contract's
+ *  `reexportsName` flag. Only `pub` at container level publishes; a `const`
+ *  inside a fn body binds locally. */
+export declare function isZigPublishingImport(declNode: SyntaxNode): boolean;
+/** The BINDING name of a Zig container node — the spelling code uses to
+ *  refer to it — or undefined for a truly anonymous one. Three shapes carry
+ *  one:
+ *    - a file-struct: the file stem (`Page.zig` → `Page`);
+ *    - `const Point = struct {…}` — the first identifier of the wrapping
+ *      `variable_declaration`;
+ *    - `pub fn List(comptime T: type) type { return struct {…}; }` — the
+ *      generic type constructor. Zig has no other spelling for a generic
+ *      type, and every reader calls the returned container `List`, so the
+ *      enclosing function's name IS the type name (`ArrayList(u8)`).
+ *  This is what scope-side NAME BINDINGS use (`R.get()`, `self: *R`, a
+ *  `const Self = @This();` rewrite). The graph IDENTITY of a container is
+ *  `zigContainerName`, which equals the binding name except for the
+ *  function-local and anonymous shapes (F8). */
+export declare function zigContainerBindingName(containerNode: SyntaxNode, filePath?: string): string | undefined;
+/** The RECEIVER parameter of a container method, or null for a static fn.
+ *
+ *  Zig has no receiver keyword: `self` is a convention, not a rule, and real
+ *  code names the receiver after its type as often as not — tigerbeetle
+ *  (`replica: *Replica`, 777 of 1127 methods), mach (`pool: *@This()`, 764 of
+ *  833). Treating only `self` as the receiver labelled those methods static,
+ *  counted the receiver in their arity (`Counter.incr#1`) and left the
+ *  scope-side binding sourced as a plain parameter. The rule, applied to the
+ *  FIRST parameter only:
+ *    - named `self`, whatever its type; or
+ *    - typed as the enclosing container: `@This()`, the container's binding
+ *      name (`Counter`, the generic constructor `Pool` for `Pool(Node)`, the
+ *      file stem for a file-struct when `filePath` is known), or a
+ *      `const X = @This();` alias declared in that container (`Self`, `PRNG`
+ *      in `prng.zig`) — pointers, `const` and optionals stripped.
+ *  `fn` must be a direct child of a container (or the file root); a fn nested
+ *  in a body is never a method. Single source for the method extractor
+ *  (parameters / receiver type / `isStatic`) and `emitZigScopeCaptures`
+ *  (`@type-binding.receiver`), so the structure and scope phases agree. */
+export declare function zigReceiverParameter(fn: SyntaxNode, filePath?: string): SyntaxNode | null;
+/** The graph IDENTITY of a Zig container node — the name its class-like
+ *  node, its members' owner segment (`Method:<file>:<name>.<fn>`) and the
+ *  scope-side def all carry. Single source for the class/field/method
+ *  extractor configs, the provider's `resolveContainerTypeOwner` hook (the
+ *  structure phase's owner walk) and `emitZigScopeCaptures`, so the two
+ *  phases agree by construction.
+ *
+ *    - file-struct / `const T = struct {…}` at file level / generic type
+ *      constructor: the binding name (`zigContainerBindingName`).
+ *    - CONTAINER-HOSTED named container — `pub const Item = struct {…}`
+ *      inside `const A = struct {…}`: owner-qualified, `A.Item` (recursively:
+ *      `A.B.Item`). By binding name alone `A.Item` and `B.Item` — two
+ *      distinct types, each with its own `run` — shared ONE `Struct:<file>:
+ *      Item` node and one `Item.run` (PR #1432 review, 8.5). The scope side
+ *      still binds the lexical spelling `Item` inside `A` (the
+ *      `@declaration.binding-name` split in `emitZigScopeCaptures`), and the
+ *      shared `populateClassOwnedMembers` leaves a dotted qualified name
+ *      alone, so the def and the graph node agree on `A.Item` and its members
+ *      qualify as `A.Item.run` — the same shape Java's `Outer.Inner` takes.
+ *    - FUNCTION-LOCAL named container (F8) — `const R = struct {…}` inside a
+ *      `fn` or `test` body: `<enclosing callable>$<name>`, e.g. `string$R`,
+ *      `Reflect.string$R`. Zig code declares such helper containers per
+ *      builder function (Lightpanda's `reflection.zig` has ~20 `const R =
+ *      struct { fn get… fn set… }`), and by binding name alone they all
+ *      collapsed onto ONE `Struct:<file>:R` with one `R.get`. Java's local
+ *      classes are keyed the same way (`Outer$1Local`); the `$` is what tells
+ *      the shared `populateClassOwnedMembers` the name is already complete.
+ *      Two same-named locals in sibling blocks of ONE callable still share
+ *      an identity (Zig code does not do that; javac's ordinal would).
+ *    - ANONYMOUS container (F8) — `struct { fn lessThan(…) … }.lessThan`
+ *      passed to `std.sort.pdq`, `const cmp = struct {…}.lt;`, a field or
+ *      parameter typed `struct { min: u32 }`: `<host>$<ordinal>` where the
+ *      host is the enclosing callable (`build$1`), else the enclosing
+ *      container (`Outer$1`), else the file stem (`util$1`), and the ordinal
+ *      counts the anonymous containers of that host in source order —
+ *      javac's `Outer$1` rule (`synthesizeJavaTypeIdentity`). Without an
+ *      identity their fns were OWNERLESS Methods (`Method:<file>:lessThan`),
+ *      and same-named ones in one file collided on a single node.
+ *  Deterministic in the tree alone, so any two walks over one source agree. */
+export declare function zigContainerName(containerNode: SyntaxNode, filePath?: string): string | undefined;
+/** The label the graph gives a container node (`opaque {}` is a fieldless
+ *  container that may own methods — Struct, see ZIG_QUERIES). */
+export declare function zigContainerLabel(containerNode: SyntaxNode): 'Struct' | 'Enum' | 'Union' | undefined;
+/** Which ZIG_QUERIES rule mints a container's graph node (F8):
+ *    - 'wrapper': `const T = struct {…}` at FILE level — the
+ *      `variable_declaration … @definition.struct` rule (name from `@name`);
+ *    - 'constructor': the container a generic type constructor returns —
+ *      the `fn … type { return struct {…}; }` rule;
+ *    - 'container': everything the bare `(struct_declaration)
+ *      @definition.struct` rule owns — FUNCTION-LOCAL and CONTAINER-HOSTED
+ *      named containers (their identities `string$R` / `A.Item` are not
+ *      captures, so the class extractor names them via `zigContainerName`)
+ *      and ANONYMOUS containers.
+ *  The provider's `shouldSkipClassCapture` drops the other rules' matches for
+ *  the same node so each container is minted exactly once. */
+export declare function zigContainerAnchor(containerNode: SyntaxNode): 'wrapper' | 'constructor' | 'container' | 'file';
+/** Is this `@definition.<container>` match of ZIG_QUERIES REDUNDANT — i.e.
+ *  minted by another rule for the same container (F8)? `definitionNode` is
+ *  the match anchor (the wrapper `variable_declaration`, or the container
+ *  node for the type-constructor and bare-container rules), `nameNode` its
+ *  `@name` capture (the type-constructor rule captures the fn's name, the
+ *  bare rule captures none). Wired through the provider's
+ *  `shouldSkipDefinitionCapture`, which the definition phase consults for
+ *  EVERY label — `shouldSkipClassCapture` would not see `Union`. */
+export declare function isZigRedundantContainerCapture(definitionNode: SyntaxNode, nameNode: SyntaxNode | undefined): boolean;
+/** A callable's qualified name as the structure phase spells it: its owner
+ *  container's identity, a dot, its own name (`Reflect.string`, `Page.init`,
+ *  `helper` in a namespace file). A `test` block is keyed by its LINE
+ *  (`test@L<line>`, 1-based; a test is a top-level declaration, so the line
+ *  identifies it), not by its string: the class extractor's
+ *  `buildQualifiedName` normalizes a graph node's `qualifiedName`
+ *  (whitespace stripped, `::` → `.`), so an identity carrying `"Function:
+ *  requested termination …"` would key the node under one spelling and the
+ *  scope def under another, and `State{}` in that test would resolve to
+ *  nothing. No `:` either (`row:col` would do), so an id keeps a single
+ *  `label:file:name` colon structure for anything that splits on it. */
+export declare function zigCallableQualifiedName(fnNode: SyntaxNode, filePath?: string): string;
+/** For a container that is the direct `return` value of a function whose
+ *  return type is `type` — `fn List(comptime T: type) type { return struct
+ *  {…}; }` — the function_declaration; null for any other placement. Only the
+ *  literal `return_expression → expression_statement → block → fn` chain
+ *  counts: a container nested deeper (`return struct {…}.field`, a container
+ *  inside an `if`) is not the type the function constructs. */
+export declare function zigTypeConstructorOf(containerNode: SyntaxNode): SyntaxNode | null;
+/** F7 — is `call` an instantiation of a generic type constructor —
+ *  `List(u8)`, `util.List(u8)`, `js.Bridge(T)`, `std.AutoHashMapUnmanaged(K, V)`?
+ *  Zig spells a generic type as a CALL, and the grammar cannot separate it
+ *  from a value call; the one signal is the naming convention (types and
+ *  type constructors are TitleCase, functions camelCase), so the callee's
+ *  last identifier decides. Heuristic by nature — say so wherever it is used. */
+export declare function isZigTypeConstructorCall(call: SyntaxNode): boolean;
+/** A `fn` nested in a struct/enum/union/opaque container is a method. Single
+ *  predicate shared between the provider's `labelOverride` (worker
+ *  structure phase) and the scope-capture relabel below, so the graph
+ *  node label and the scope-side def label cannot drift apart. The loose
+ *  parameter shape matches what `labelOverride` receives.
+ *
+ *  Only a `function_declaration` can be a method: a named `test "…" {}`
+ *  inside a container is also a Function definition, but the method
+ *  extractor does not know test blocks (no parameters, no `self`), so
+ *  relabelling it would mint a Method id the definition phase never
+ *  builds. Tests stay Functions wherever they sit. */
+export declare function isZigContainerMethod(captureNode: {
+    readonly type?: string;
+    readonly parent?: SyntaxNode | null;
+} | null | undefined): boolean;
+/** Strip the value wrappers Zig puts around a call — `try f()`, `f() catch
+ *  …`, `f() orelse …`, `(f())` — down to the wrapped expression. Rust's
+ *  `.await` unwrapping, one level richer. */
+export declare function zigUnwrapValue(value: SyntaxNode): SyntaxNode;
+/** For `const t = <value>;`, the type source the value names, or undefined
+ *  when the value types nothing on its own:
+ *    - `Counter.init()` / `mod.Counter.init()` / `List(u8).init()` (receiver
+ *      is a module-level name) → `{ type: 'Counter' }` — the receiver names
+ *      the type (Rust `Foo::new()`); a value receiver simply finds no
+ *      container later and declines.
+ *    - `node.asElement()` / `self.parser.next()` (receiver head is a fn-local
+ *      param / local / payload) → `{ type: 'node.asElement()', memberCall:
+ *      true }` — the compound shape the shared resolver walks through the
+ *      receiver's class scope to the method's `@type-binding.return`.
+ *    - `makeThing()` (free call) → `{ type: 'makeThing' }` — chains to the
+ *      fn's return binding.
+ *    - a `struct_initializer` under a wrapper (`try Thing{…}`) → its type,
+ *      `structLiteral: true` (the direct shape has its own query rules).
+ *    - `.init()` decl literals, TitleCase callees (type constructors —
+ *      aliases, F7), identifiers, field chains, literals → undefined.
+ *  Wrappers (`try`, `catch`, `orelse`, parens) are unwrapped first. */
+export declare function zigCallReturnTypeOf(value: SyntaxNode, localNamesCache: Map<number, Set<string>>, hostValueNames?: Map<number, Set<string>>): {
+    readonly type: string;
+    readonly memberCall?: true;
+    readonly structLiteral?: true;
+} | undefined;
+/** Should `fn name() <type>` bind `name ↦ <type>`? Only when the return
+ *  type is nominal: a container name, a qualified name, a generic
+ *  instantiation, or `@This()`. Builtins (`void`, `u8`, `bool`, `anyerror`),
+ *  `type` (a generic type constructor — its container binding is the type),
+ *  and `@TypeOf(…)` bind nothing: `List ↦ type` would hijack the
+ *  `List(u8){}` constructor chain, and `f ↦ void` is noise. */
+export declare function zigReturnTypeIsNominal(typeNode: SyntaxNode): boolean;
+export declare function emitZigScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];