dsh-plugin-codegraph-tree-sitter 0.1.0 → 0.1.4

package/lib/index.d.ts

@@ -44,7 +44,11 @@ export declare const inject: string[];
 export declare const DATABASE_RELATIVE_PATH = ".codegraph/codegraph.db";
 /** Default branded identity this indexer reserves on the seam. */
 export declare const DEFAULT_INDEXER_ID = "codegraph-tree-sitter";
-/** Directory segments never descended into by default. */
+/**
+ * Directory segments never descended into by default. Includes this package's own `.codegraph`
+ * output — without it, a watcher would treat its own `writeGraph()` as an in-scope change and
+ * rebuild forever.
+ */
 export declare const DEFAULT_EXCLUDE: string[];
 /** Default ceiling on a single file's size before it is skipped. */
 export declare const DEFAULT_MAX_FILE_BYTES = 2000000;
@@ -84,8 +88,8 @@ export interface Config {
     concurrency?: number;
     /**
      * Watch the workspace for file changes and refresh the index automatically after a successful
-     * `index()` call establishes a baseline (default false). A caller that never sets this sees no
-     * change from before this option existed — indexing stays purely explicit.
+     * `index()` call establishes a baseline (default true). Set `watch: false` to keep indexing purely
+     * explicit instead.
      *
      * Overridden off by default on a WSL2 kernel watching a path mounted in from the Windows host
      * (`/mnt/<drive>/...`), since inotify does not reliably deliver events over that 9P mount — see

package/lib/index.js

@@ -43,8 +43,12 @@ export const inject = ['codegraph'];
 export const DATABASE_RELATIVE_PATH = '.codegraph/codegraph.db';
 /** Default branded identity this indexer reserves on the seam. */
 export const DEFAULT_INDEXER_ID = 'codegraph-tree-sitter';
-/** Directory segments never descended into by default. */
-export const DEFAULT_EXCLUDE = ['node_modules', 'dist', 'build', 'coverage', '.git'];
+/**
+ * Directory segments never descended into by default. Includes this package's own `.codegraph`
+ * output — without it, a watcher would treat its own `writeGraph()` as an in-scope change and
+ * rebuild forever.
+ */
+export const DEFAULT_EXCLUDE = ['node_modules', 'dist', 'build', 'coverage', '.git', '.codegraph'];
 /** Default ceiling on a single file's size before it is skipped. */
 export const DEFAULT_MAX_FILE_BYTES = 2_000_000;
 /** Default ceiling on how many files one run indexes. */
@@ -63,7 +67,7 @@ export const Config = z.object({
     maxFileBytes: z.number().default(DEFAULT_MAX_FILE_BYTES),
     maxFiles: z.number().default(DEFAULT_MAX_FILES),
     concurrency: z.number().default(DEFAULT_CONCURRENCY),
-    watch: z.boolean().default(false),
+    watch: z.boolean().default(true),
     watchDebounceMs: z.number().default(DEFAULT_WATCH_DEBOUNCE_MS),
     maxWatchedDirectories: z.number().default(DEFAULT_MAX_WATCHED_DIRECTORIES),
 });

package/lib/languages.d.ts

@@ -28,7 +28,80 @@ export interface DefinitionRule {
         /** Node types the field must resolve to for this rule to match. */
         readonly types: readonly string[];
     };
+    /**
+     * Present only when this rule must reject a name shape it cannot represent as a single declared
+     * name — a destructuring `variable_declarator` (`const {a, b} = x`) or a Python tuple/attribute
+     * assignment (`a, b = 1, 2`, `self.x = 1`) binds through {@link nameField} too, but to a pattern
+     * node this package does not attempt to name. Absent, any node type in {@link nameField} matches.
+     */
+    readonly nameNodeTypes?: readonly string[];
+    /**
+     * Present only when this rule must not match the same node type wherever it appears — a bare
+     * `property_identifier` names an enum member only directly inside an `enum_body`; the same node
+     * type also names a method, a class field, and a member-expression property everywhere else. Absent,
+     * any parent matches.
+     */
+    readonly parentType?: string;
+    /**
+     * True only for a rule this package extracts solely directly inside a module's top level or a class
+     * body — never inside a function or method body. Unlike a function or class declaration (captured at
+     * any depth, however deeply nested), a function-local variable is not a workspace "symbol" anyone
+     * would search for by name, and capturing it would flood the cross-file name index `resolve.ts` uses
+     * to settle calls — more names means more collisions, which means more calls silently dropped to
+     * `unresolved`. See `resolve.ts`'s "an ambiguous edge is worse than a missing one" rule.
+     *
+     * This is a property of the *rule*, not of {@link kind} in general: JS/TS's `field_definition` rule
+     * (kind `field`) sets this because a class field could in principle sit at any depth a class does —
+     * but Go's struct-field rule, also kind `field`, must not, because its enclosing `type_spec` is itself
+     * never scope-restricted (a Go type declaration is captured at any depth, like a function), so a
+     * scope-restricted struct-field rule could never fire at all. Absent (the common case), always
+     * extracted regardless of depth.
+     */
+    readonly scopeRestricted?: boolean;
+    /**
+     * Present only when a rule must distinguish two node types that share both their own type and their
+     * immediate parent's type — C#'s field vs. local variable both parse as a `variable_declarator`
+     * directly inside a `variable_declaration`, and only the *grandparent* differs
+     * (`field_declaration` vs. `local_declaration_statement`). Absent, any grandparent matches, the same
+     * as an absent {@link parentType}.
+     */
+    readonly grandparentType?: string;
 }
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose matched node has no separate
+ * name-bearing child — a bare enum member (`enum_body`'s `Red` in `enum Color { Red }`) parses as a
+ * lone `property_identifier` token with no fields of its own; the node itself, unlike every other
+ * `nameField` target, *is* the name.
+ */
+export declare const SELF_NAME_FIELD = "@self";
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose name sits behind an arbitrarily deep
+ * chain of C/C++ `declarator` wrappers — `int *make(int a)`'s name is three `declarator` fields down
+ * (`pointer_declarator` → `function_declarator` → `identifier`), and a plain `int g` binds its
+ * `identifier` directly with no wrapper at all. See `declaratorName` in `extract.ts`, which this
+ * sentinel dispatches to instead of a flat `childForFieldName` lookup.
+ */
+export declare const DECLARATOR_NAME_FIELD = "@declarator";
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose name is its matched node's first
+ * named child with no field name of its own — C#'s `variable_declarator` binds neither its name nor its
+ * optional initializer to a field at all (`int Field = 5;`'s `variable_declarator` has two purely
+ * positional named children, `identifier` then `equals_value_clause`), unlike every other grammar this
+ * package extracts a name from. Distinct from {@link SELF_NAME_FIELD}: the matched node's own text
+ * would include that initializer (`"Field = 5"`), not just the name. See `firstChildName` in
+ * `extract.ts`.
+ */
+export declare const FIRST_CHILD_NAME_FIELD = "@first-child";
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose name is PHP-specific: a bare `name`
+ * node directly (`const_element`'s `VERSION` in `const VERSION = "1"`), or one nested a level deeper
+ * inside a `variable_name` child (`property_element`'s `$name` in `public string $name;`, and an
+ * `assignment_expression`'s `$fn` in `$fn = function () {}` — both bind their bare `name` behind the
+ * same `$`-prefixed wrapper). See `phpElementName` in `extract.ts`, which this sentinel dispatches to
+ * instead of a flat `childForFieldName` lookup — none of these three shapes bind their name to a field
+ * of its own.
+ */
+export declare const PHP_ELEMENT_NAME_FIELD = "@php-element";
 /** One tree-sitter node type recording a relative-import binding, per language family. */
 export interface ImportRule {
     /** The tree-sitter node type anchoring one import statement, e.g. `import_statement`. */
@@ -46,10 +119,29 @@ export interface LanguageSpec {
     readonly definitions: readonly DefinitionRule[];
     /** Node types whose {@link callFunctionField} names the callee. */
     readonly callTypes: readonly string[];
-    /** Field on a call node holding the callee expression. */
+    /** Field on a call node holding the callee expression, used for any {@link callTypes} member absent
+     * from {@link callFunctionFieldByType}. */
     readonly callFunctionField: string;
+    /**
+     * Present only when different {@link callTypes} members name their callee through different fields —
+     * PHP's `member_call_expression` ($obj->method()) and `scoped_call_expression` (Class::method()) both
+     * use `name`, while `function_call_expression` uses `function`; every other language's call types
+     * (today, always exactly one) share a single field, so this is absent for all of them. Overrides
+     * {@link callFunctionField} for the node types it lists.
+     */
+    readonly callFunctionFieldByType?: Readonly<Record<string, string>>;
     /** Node types anchoring one import statement. */
     readonly importTypes: readonly string[];
+    /**
+     * Node types that bound a new function scope even when the walk never captures them as a named
+     * definition — a callback (`arr.forEach(function(item) { ... })`) or an IIFE's `function_expression`
+     * never matches a {@link DefinitionRule} (only a *named* declaration, or one assigned through a
+     * captured `variable_declarator`, does), but a `const`/`var` inside its body is exactly the
+     * function-local binding a `scopeRestricted` {@link DefinitionRule} exists to exclude. Empty for a language with
+     * no anonymous-function shape that can contain a statement (Python's `lambda` body is a single
+     * expression, never a block).
+     */
+    readonly bareFunctionScopeTypes: readonly string[];
 }
 /** Every grammar this package loads, keyed by the seam language label it produces. */
 export declare const LANGUAGE_TABLE: readonly LanguageSpec[];

package/lib/languages.js

@@ -8,6 +8,41 @@
  * defers until the core proves itself against real workspaces.
  * @module dsh-plugin-codegraph-tree-sitter/languages
  */
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose matched node has no separate
+ * name-bearing child — a bare enum member (`enum_body`'s `Red` in `enum Color { Red }`) parses as a
+ * lone `property_identifier` token with no fields of its own; the node itself, unlike every other
+ * `nameField` target, *is* the name.
+ */
+export const SELF_NAME_FIELD = '@self';
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose name sits behind an arbitrarily deep
+ * chain of C/C++ `declarator` wrappers — `int *make(int a)`'s name is three `declarator` fields down
+ * (`pointer_declarator` → `function_declarator` → `identifier`), and a plain `int g` binds its
+ * `identifier` directly with no wrapper at all. See `declaratorName` in `extract.ts`, which this
+ * sentinel dispatches to instead of a flat `childForFieldName` lookup.
+ */
+export const DECLARATOR_NAME_FIELD = '@declarator';
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose name is its matched node's first
+ * named child with no field name of its own — C#'s `variable_declarator` binds neither its name nor its
+ * optional initializer to a field at all (`int Field = 5;`'s `variable_declarator` has two purely
+ * positional named children, `identifier` then `equals_value_clause`), unlike every other grammar this
+ * package extracts a name from. Distinct from {@link SELF_NAME_FIELD}: the matched node's own text
+ * would include that initializer (`"Field = 5"`), not just the name. See `firstChildName` in
+ * `extract.ts`.
+ */
+export const FIRST_CHILD_NAME_FIELD = '@first-child';
+/**
+ * Sentinel {@link DefinitionRule.nameField} value for a rule whose name is PHP-specific: a bare `name`
+ * node directly (`const_element`'s `VERSION` in `const VERSION = "1"`), or one nested a level deeper
+ * inside a `variable_name` child (`property_element`'s `$name` in `public string $name;`, and an
+ * `assignment_expression`'s `$fn` in `$fn = function () {}` — both bind their bare `name` behind the
+ * same `$`-prefixed wrapper). See `phpElementName` in `extract.ts`, which this sentinel dispatches to
+ * instead of a flat `childForFieldName` lookup — none of these three shapes bind their name to a field
+ * of its own.
+ */
+export const PHP_ELEMENT_NAME_FIELD = '@php-element';
 /** Definitions common to every ECMAScript-family grammar (JavaScript, JSX, TypeScript, TSX). */
 const ECMASCRIPT_DEFINITIONS = [
     { nodeType: 'function_declaration', kind: 'function', nameField: 'name' },
@@ -20,6 +55,12 @@ const ECMASCRIPT_DEFINITIONS = [
         nameField: 'name',
         value: { field: 'value', types: ['arrow_function', 'function_expression', 'generator_function'] },
     },
+    // Falls through from the function-valued rule above: any other simply-named `const`/`let`/`var`
+    // binding (`lexical_declaration` and `variable_declaration` both wrap this same node type).
+    // `nameNodeTypes` rejects a destructuring pattern (`const {a, b} = x`) rather than name it after its
+    // pattern text — the same "don't guess a name" precedent `pythonBinding`/`ecmascriptImports` already
+    // follow for shapes this package does not resolve.
+    { nodeType: 'variable_declarator', kind: 'variable', nameField: 'name', nameNodeTypes: ['identifier'], scopeRestricted: true },
 ];
 /** Definitions TypeScript and TSX add on top of {@link ECMASCRIPT_DEFINITIONS}. */
 const TYPESCRIPT_DEFINITIONS = [
@@ -27,9 +68,29 @@ const TYPESCRIPT_DEFINITIONS = [
     { nodeType: 'interface_declaration', kind: 'interface', nameField: 'name' },
     { nodeType: 'type_alias_declaration', kind: 'type_alias', nameField: 'name' },
     { nodeType: 'enum_declaration', kind: 'enum', nameField: 'name' },
+    // `enum Color { Red, Green = 5 }` — a bare member (`Red`) parses as a lone `property_identifier`
+    // naming itself, tagged with `enum_body`'s own repeated `name` field; a valued member (`Green = 5`)
+    // wraps its own `property_identifier` in a distinct `enum_assignment` node instead. Both verified
+    // against a real parse, not guessed.
+    { nodeType: 'property_identifier', kind: 'enum_member', nameField: SELF_NAME_FIELD, parentType: 'enum_body' },
+    { nodeType: 'enum_assignment', kind: 'enum_member', nameField: 'name' },
+    // The TypeScript/TSX grammars name a class field node differently from plain JavaScript's
+    // `field_definition` (see JAVASCRIPT_DEFINITIONS) — verified against a real parse, not guessed.
+    { nodeType: 'public_field_definition', kind: 'field', nameField: 'name', scopeRestricted: true },
+];
+/** Definitions JavaScript and JSX add on top of {@link ECMASCRIPT_DEFINITIONS}. */
+const JAVASCRIPT_DEFINITIONS = [
+    ...ECMASCRIPT_DEFINITIONS,
+    // The plain JavaScript grammar's class field node names its field-name field `property`, not `name`
+    // as TypeScript's `public_field_definition` does (see TYPESCRIPT_DEFINITIONS) — verified against a
+    // real parse, not guessed.
+    { nodeType: 'field_definition', kind: 'field', nameField: 'property', scopeRestricted: true },
 ];
 const ECMASCRIPT_CALL_TYPES = ['call_expression'];
 const ECMASCRIPT_IMPORT_TYPES = ['import_statement'];
+/** The ECMAScript function-value node types, matched against a real parse — see
+ * {@link LanguageSpec.bareFunctionScopeTypes}. */
+const ECMASCRIPT_BARE_FUNCTION_SCOPE_TYPES = ['function_expression', 'arrow_function', 'generator_function'];
 /** Every grammar this package loads, keyed by the seam language label it produces. */
 export const LANGUAGE_TABLE = [
     {
@@ -40,6 +101,7 @@ export const LANGUAGE_TABLE = [
         callTypes: ECMASCRIPT_CALL_TYPES,
         callFunctionField: 'function',
         importTypes: ECMASCRIPT_IMPORT_TYPES,
+        bareFunctionScopeTypes: ECMASCRIPT_BARE_FUNCTION_SCOPE_TYPES,
     },
     {
         language: 'tsx',
@@ -49,15 +111,17 @@ export const LANGUAGE_TABLE = [
         callTypes: ECMASCRIPT_CALL_TYPES,
         callFunctionField: 'function',
         importTypes: ECMASCRIPT_IMPORT_TYPES,
+        bareFunctionScopeTypes: ECMASCRIPT_BARE_FUNCTION_SCOPE_TYPES,
     },
     {
         language: 'javascript',
         extensions: ['.js', '.mjs', '.cjs'],
         wasmFile: 'tree-sitter-javascript.wasm',
-        definitions: ECMASCRIPT_DEFINITIONS,
+        definitions: JAVASCRIPT_DEFINITIONS,
         callTypes: ECMASCRIPT_CALL_TYPES,
         callFunctionField: 'function',
         importTypes: ECMASCRIPT_IMPORT_TYPES,
+        bareFunctionScopeTypes: ECMASCRIPT_BARE_FUNCTION_SCOPE_TYPES,
     },
     {
         language: 'jsx',
@@ -65,10 +129,11 @@ export const LANGUAGE_TABLE = [
         // The plain JavaScript grammar already parses JSX syntax; tree-sitter-wasms ships no separate
         // "jsx" binary, only distinct typescript/tsx binaries.
         wasmFile: 'tree-sitter-javascript.wasm',
-        definitions: ECMASCRIPT_DEFINITIONS,
+        definitions: JAVASCRIPT_DEFINITIONS,
         callTypes: ECMASCRIPT_CALL_TYPES,
         callFunctionField: 'function',
         importTypes: ECMASCRIPT_IMPORT_TYPES,
+        bareFunctionScopeTypes: ECMASCRIPT_BARE_FUNCTION_SCOPE_TYPES,
     },
     {
         language: 'python',
@@ -77,10 +142,15 @@ export const LANGUAGE_TABLE = [
         definitions: [
             { nodeType: 'function_definition', kind: 'function', nameField: 'name' },
             { nodeType: 'class_definition', kind: 'class', nameField: 'name' },
+            // Module- and class-level `x = ...`; `nameNodeTypes` rejects a tuple assignment (`a, b = 1, 2`,
+            // `left` is a `pattern_list`) and an attribute target (`self.x = 1`, `left` is an `attribute`) —
+            // verified against a real parse, not guessed.
+            { nodeType: 'assignment', kind: 'variable', nameField: 'left', nameNodeTypes: ['identifier'], scopeRestricted: true },
         ],
         callTypes: ['call'],
         callFunctionField: 'function',
         importTypes: ['import_statement', 'import_from_statement'],
+        bareFunctionScopeTypes: [],
     },
     {
         language: 'go',
@@ -90,10 +160,269 @@ export const LANGUAGE_TABLE = [
             { nodeType: 'function_declaration', kind: 'function', nameField: 'name' },
             { nodeType: 'method_declaration', kind: 'method', nameField: 'name' },
             { nodeType: 'type_spec', kind: 'type_alias', nameField: 'name' },
+            // Go allows `const a, b = 1, 2` — multiple names sharing one `const_spec`/`var_spec` node, each
+            // tagged with the same `name` field. `matchDefinition`'s single-name-field requirement rejects
+            // the multi-name form entirely rather than capture only the first — a partial, silently
+            // misleading result would be worse than none, per this file's existing "don't guess" precedent.
+            { nodeType: 'const_spec', kind: 'constant', nameField: 'name', scopeRestricted: true },
+            { nodeType: 'var_spec', kind: 'variable', nameField: 'name', scopeRestricted: true },
+            // A struct field (`field_declaration`) and an interface method signature (`method_spec`) both sit
+            // inside a `type_spec`'s `struct_type`/`interface_type` body — `type_spec` itself (kind
+            // `type_alias`) is not scope-restricted (a Go type can be declared inside a function, like `type
+            // Local struct {...}` in `func f() {...}`), so these must not be either: a scope-restricted rule
+            // here could never fire, since the enclosing `type_spec` always pushes `'other'` for its children
+            // regardless of where it itself sits. An embedded (anonymous) field — `Nested` with no separate
+            // name — has no child bound to the `name` field at all, so `matchDefinition`'s name-arity check
+            // already excludes it without a dedicated rule; verified against a real parse, not guessed.
+            { nodeType: 'field_declaration', kind: 'field', nameField: 'name' },
+            { nodeType: 'method_spec', kind: 'method', nameField: 'name' },
         ],
         callTypes: ['call_expression'],
         callFunctionField: 'function',
         importTypes: ['import_declaration'],
+        // A closure literal (`f := func() { ... }`) is never itself named, so it never matches a
+        // `DefinitionRule` — but a `var`/`const` inside its body is still function-local.
+        bareFunctionScopeTypes: ['func_literal'],
+    },
+    {
+        language: 'java',
+        extensions: ['.java'],
+        wasmFile: 'tree-sitter-java.wasm',
+        definitions: [
+            { nodeType: 'class_declaration', kind: 'class', nameField: 'name' },
+            // A record has no dedicated seam kind — `class` is the closest existing fit for a concrete type
+            // declaration with a body, and (like a class) it can `implements` an interface; see
+            // `javaHeritage` in extract.ts.
+            { nodeType: 'record_declaration', kind: 'class', nameField: 'name' },
+            { nodeType: 'interface_declaration', kind: 'interface', nameField: 'name' },
+            { nodeType: 'enum_declaration', kind: 'enum', nameField: 'name' },
+            // Unlike TypeScript's bare `property_identifier` enum member (see TYPESCRIPT_DEFINITIONS),
+            // Java's `enum_constant` already carries its own `name` field — verified against a real parse.
+            { nodeType: 'enum_constant', kind: 'enum_member', nameField: 'name' },
+            { nodeType: 'method_declaration', kind: 'method', nameField: 'name' },
+            // No dedicated `constructor` seam kind exists; a constructor is a method in every way this
+            // package's graph cares about.
+            { nodeType: 'constructor_declaration', kind: 'method', nameField: 'name' },
+            // A field (`field_declaration`) and a local variable (`local_variable_declaration`) both wrap one
+            // or more `variable_declarator` children directly, each carrying its own `name` field — unlike
+            // Go's `const_spec`/`var_spec`, a multi-name Java declaration (`int x = 1, y = 2;`) is not one
+            // ambiguous shared name field but several independent `variable_declarator` nodes, each visited
+            // (and named) on its own, so no `nameNodeTypes`-style rejection is needed here.
+            { nodeType: 'variable_declarator', kind: 'field', nameField: 'name', parentType: 'field_declaration', scopeRestricted: true },
+            { nodeType: 'variable_declarator', kind: 'variable', nameField: 'name', parentType: 'local_variable_declaration', scopeRestricted: true },
+        ],
+        callTypes: ['method_invocation'],
+        // Unlike the ECMAScript/Go/Python call node's `function` field (an expression this package's
+        // `calleeName` unwraps down to a simple name), Java's `method_invocation` already exposes the
+        // callee's simple name directly through its own `name` field — the receiver, if any, is a sibling
+        // `object` field extract.ts checks separately to tell a member call from a bare one. Verified
+        // against a real parse, not guessed.
+        callFunctionField: 'name',
+        importTypes: ['import_declaration'],
+        // A lambda body (`() -> { int x = 1; }`) is never itself named, so it never matches a
+        // `DefinitionRule` — but a local variable inside its block body is still function-local, the same
+        // reasoning `ECMASCRIPT_BARE_FUNCTION_SCOPE_TYPES` applies to an arrow function.
+        bareFunctionScopeTypes: ['lambda_expression'],
+    },
+    {
+        language: 'c',
+        extensions: ['.c', '.h'],
+        wasmFile: 'tree-sitter-c.wasm',
+        definitions: [
+            // No dedicated `union` seam kind exists; `struct` is the closest existing fit for a
+            // concrete-layout aggregate type, matching Java's record→`class` precedent.
+            { nodeType: 'struct_specifier', kind: 'struct', nameField: 'name' },
+            { nodeType: 'union_specifier', kind: 'struct', nameField: 'name' },
+            { nodeType: 'enum_specifier', kind: 'enum', nameField: 'name' },
+            // `enumerator` carries its own `name` field directly, unlike TypeScript's bare enum member —
+            // verified against a real parse, not guessed.
+            { nodeType: 'enumerator', kind: 'enum_member', nameField: 'name' },
+            // A typedef's `declarator` names the alias directly (`typedef struct Point PointT;`'s
+            // `declarator` is the plain `type_identifier` "PointT", no wrapper) — unlike a function or
+            // variable declarator, verified against a real parse, not guessed.
+            { nodeType: 'type_definition', kind: 'type_alias', nameField: 'declarator' },
+            // `function_definition`'s name sits behind a `pointer_declarator`/`function_declarator` chain of
+            // arbitrary depth — see `DECLARATOR_NAME_FIELD`.
+            { nodeType: 'function_definition', kind: 'function', nameField: DECLARATOR_NAME_FIELD },
+            // A struct/union member (`field_declaration`) — same declarator-nesting rule as a top-level
+            // variable, minus the multi-declarator ambiguity Go's `field_declaration` has none of either.
+            { nodeType: 'field_declaration', kind: 'field', nameField: DECLARATOR_NAME_FIELD },
+            // A top-level or function-local `int g = 1;`/`int x;` — both parse as `declaration`, distinguished
+            // only by where the walk currently sits, the same convention JS/Python/Go's local-variable rules
+            // already follow.
+            { nodeType: 'declaration', kind: 'variable', nameField: DECLARATOR_NAME_FIELD, scopeRestricted: true },
+        ],
+        callTypes: ['call_expression'],
+        callFunctionField: 'function',
+        importTypes: ['preproc_include'],
+        bareFunctionScopeTypes: [],
+    },
+    {
+        language: 'cpp',
+        extensions: ['.cpp', '.cc', '.cxx', '.hpp', '.hh', '.hxx'],
+        wasmFile: 'tree-sitter-cpp.wasm',
+        definitions: [
+            { nodeType: 'class_specifier', kind: 'class', nameField: 'name' },
+            { nodeType: 'struct_specifier', kind: 'struct', nameField: 'name' },
+            { nodeType: 'union_specifier', kind: 'struct', nameField: 'name' },
+            { nodeType: 'enum_specifier', kind: 'enum', nameField: 'name' },
+            { nodeType: 'enumerator', kind: 'enum_member', nameField: 'name' },
+            { nodeType: 'type_definition', kind: 'type_alias', nameField: 'declarator' },
+            // A method (including a constructor/destructor) is a `function_definition` directly inside a
+            // class/struct's `field_declaration_list` — the same node type a free function uses, so this rule
+            // (tried first) must claim that shape before the unrestricted `function` rule below falls through
+            // to everything else. Verified against a real parse, not guessed.
+            { nodeType: 'function_definition', kind: 'method', nameField: DECLARATOR_NAME_FIELD, parentType: 'field_declaration_list' },
+            { nodeType: 'function_definition', kind: 'function', nameField: DECLARATOR_NAME_FIELD },
+            // `field_declaration` doubles as a pure-virtual method signature (`virtual void v() = 0;` is still
+            // a `field_declaration`, just with a `function_declarator` for its `declarator`) — the same
+            // function-valued guard `ECMASCRIPT_DEFINITIONS`'s `variable_declarator` rule uses, tried first.
+            { nodeType: 'field_declaration', kind: 'method', nameField: DECLARATOR_NAME_FIELD, value: { field: 'declarator', types: ['function_declarator'] } },
+            { nodeType: 'field_declaration', kind: 'field', nameField: DECLARATOR_NAME_FIELD },
+            { nodeType: 'declaration', kind: 'variable', nameField: DECLARATOR_NAME_FIELD, scopeRestricted: true },
+        ],
+        callTypes: ['call_expression'],
+        callFunctionField: 'function',
+        importTypes: ['preproc_include'],
+        // A lambda body (`[](){ int x = 1; }`) is never itself named, so it never matches a `DefinitionRule`
+        // — but a local variable inside its block body is still function-local.
+        bareFunctionScopeTypes: ['lambda_expression'],
+    },
+    {
+        language: 'csharp',
+        extensions: ['.cs'],
+        wasmFile: 'tree-sitter-c_sharp.wasm',
+        definitions: [
+            { nodeType: 'class_declaration', kind: 'class', nameField: 'name' },
+            { nodeType: 'struct_declaration', kind: 'struct', nameField: 'name' },
+            // No dedicated seam kind exists for a record; `class` is the closest existing fit, matching Java's
+            // record→`class` precedent.
+            { nodeType: 'record_declaration', kind: 'class', nameField: 'name' },
+            { nodeType: 'interface_declaration', kind: 'interface', nameField: 'name' },
+            { nodeType: 'enum_declaration', kind: 'enum', nameField: 'name' },
+            { nodeType: 'enum_member_declaration', kind: 'enum_member', nameField: 'name' },
+            { nodeType: 'method_declaration', kind: 'method', nameField: 'name' },
+            // No dedicated `constructor` seam kind exists; both are a method in every way this package's graph
+            // cares about, matching Java's constructor_declaration→`method` precedent.
+            { nodeType: 'constructor_declaration', kind: 'method', nameField: 'name' },
+            { nodeType: 'destructor_declaration', kind: 'method', nameField: 'name' },
+            { nodeType: 'property_declaration', kind: 'property', nameField: 'name' },
+            // A field (`variable_declarator` two levels under a `field_declaration`) and a local variable
+            // (`variable_declarator` two levels under a `local_declaration_statement`) parse identically one
+            // level up (`variable_declaration`) — only the grandparent tells them apart. See
+            // `DefinitionRule.grandparentType`. Verified against a real parse, not guessed.
+            { nodeType: 'variable_declarator', kind: 'field', nameField: FIRST_CHILD_NAME_FIELD, grandparentType: 'field_declaration', scopeRestricted: true },
+            { nodeType: 'variable_declarator', kind: 'variable', nameField: FIRST_CHILD_NAME_FIELD, grandparentType: 'local_declaration_statement', scopeRestricted: true },
+        ],
+        callTypes: ['invocation_expression'],
+        callFunctionField: 'function',
+        importTypes: ['using_directive'],
+        // A lambda body (`() => { int x = 1; }`) is never itself named, so it never matches a
+        // `DefinitionRule` — but a local variable inside its block body is still function-local.
+        bareFunctionScopeTypes: ['lambda_expression', 'anonymous_method_expression'],
+    },
+    {
+        language: 'php',
+        extensions: ['.php'],
+        wasmFile: 'tree-sitter-php.wasm',
+        definitions: [
+            { nodeType: 'function_definition', kind: 'function', nameField: 'name' },
+            { nodeType: 'method_declaration', kind: 'method', nameField: 'name' },
+            { nodeType: 'class_declaration', kind: 'class', nameField: 'name' },
+            { nodeType: 'interface_declaration', kind: 'interface', nameField: 'name' },
+            { nodeType: 'trait_declaration', kind: 'trait', nameField: 'name' },
+            { nodeType: 'enum_declaration', kind: 'enum', nameField: 'name' },
+            // `enum_case` carries its own `name` field directly, unlike TypeScript's bare enum member —
+            // verified against a real parse, not guessed.
+            { nodeType: 'enum_case', kind: 'enum_member', nameField: 'name' },
+            // `const_element` (`const VERSION = "1"`) and `property_element` (`public string $name;`) neither
+            // bind their name to a field of their own — see `PHP_ELEMENT_NAME_FIELD`. Unlike a JS/Go/Python
+            // local binding, neither is `scopeRestricted`: a PHP `const`/property only legitimately appears at
+            // namespace scope or directly inside a class/interface/trait/enum body, and every non-class body
+            // here (`interface`/`trait`/`enum`) pushes `'other'` scope, not `'class'` — the same "must not be
+            // scopeRestricted" reasoning Go's struct-field rule documents, since a restricted rule could never
+            // fire inside one. The one shape this misses is already invalid PHP the grammar merely tolerates
+            // (a `const`/property statement directly inside a function body), so capturing it there costs
+            // nothing in practice.
+            { nodeType: 'const_element', kind: 'constant', nameField: PHP_ELEMENT_NAME_FIELD },
+            { nodeType: 'property_element', kind: 'field', nameField: PHP_ELEMENT_NAME_FIELD },
+            // `$fn = function () {}` / `$fn = fn($a) => $a` — the same function-valued-binding rule
+            // ECMASCRIPT_DEFINITIONS's `variable_declarator` follows, captured at any depth like a named
+            // function declaration (not `scopeRestricted`) since a named closure is as much a workspace symbol
+            // as one. Unlike ECMASCRIPT_DEFINITIONS, no bare-variable fallback rule follows it: PHP draws no
+            // `const`/`let`-style distinction for `$x = 5;` — it is an unremarkable, ubiquitous assignment, and
+            // capturing every one would flood `resolve.ts`'s cross-file name index with noise no caller wants.
+            {
+                nodeType: 'assignment_expression',
+                kind: 'function',
+                nameField: PHP_ELEMENT_NAME_FIELD,
+                value: { field: 'right', types: ['anonymous_function_creation_expression', 'arrow_function'] },
+            },
+        ],
+        callTypes: ['function_call_expression', 'member_call_expression', 'scoped_call_expression'],
+        callFunctionField: 'function',
+        // `member_call_expression` ($obj->method()) and `scoped_call_expression` (Class::method()) both name
+        // their callee through a `name` field, not `function` — verified against a real parse, not guessed.
+        callFunctionFieldByType: { member_call_expression: 'name', scoped_call_expression: 'name' },
+        importTypes: ['namespace_use_declaration'],
+        // A closure's block body (`function () { ... }`) can contain a statement, so it must flip scope like
+        // JS's `function_expression`; an arrow function's body is always a single expression (like Python's
+        // `lambda`, never a block), so it is omitted, matching that same precedent.
+        bareFunctionScopeTypes: ['anonymous_function_creation_expression'],
+    },
+    {
+        language: 'rust',
+        extensions: ['.rs'],
+        wasmFile: 'tree-sitter-rust.wasm',
+        definitions: [
+            { nodeType: 'struct_item', kind: 'struct', nameField: 'name' },
+            // No dedicated `union` seam kind exists; `struct` is the closest existing fit, matching C/C++'s
+            // same union→`struct` precedent — a Rust `union_item` shares `struct_item`'s exact body shape
+            // (`field_declaration_list`), verified against a real parse.
+            { nodeType: 'union_item', kind: 'struct', nameField: 'name' },
+            { nodeType: 'enum_item', kind: 'enum', nameField: 'name' },
+            // `enum_variant` carries its own `name` field directly, unlike TypeScript's bare enum member —
+            // verified against a real parse, not guessed.
+            { nodeType: 'enum_variant', kind: 'enum_member', nameField: 'name' },
+            { nodeType: 'trait_item', kind: 'trait', nameField: 'name' },
+            { nodeType: 'mod_item', kind: 'namespace', nameField: 'name' },
+            { nodeType: 'type_item', kind: 'type_alias', nameField: 'name' },
+            // A method — including a trait's default-body method — is a `function_item` directly inside an
+            // `impl_item`'s or `trait_item`'s `declaration_list`, the same node type a free function uses;
+            // mod's `declaration_list` shares that exact node type too, so only the grandparent (not the
+            // immediate parent) tells a method apart from a module-level function. Tried first, before the
+            // unrestricted `function` rule below falls through to everything else — the same precedent C++'s
+            // method rule follows for its own shared `function_definition` node type. Verified against a real
+            // parse, not guessed.
+            { nodeType: 'function_item', kind: 'method', nameField: 'name', grandparentType: 'impl_item' },
+            { nodeType: 'function_item', kind: 'method', nameField: 'name', grandparentType: 'trait_item' },
+            { nodeType: 'function_item', kind: 'function', nameField: 'name' },
+            // A trait method declared with no body (`fn area(&self) -> f64;`) parses as a distinct node type
+            // from one with a body, and only ever appears directly inside a trait's `declaration_list` — an
+            // `impl_item` must supply a body for every method it defines. Verified against a real parse.
+            { nodeType: 'function_signature_item', kind: 'method', nameField: 'name', grandparentType: 'trait_item' },
+            // A struct/union member — verified against a real parse, not guessed; unlike Go's/C++'s field
+            // rule this needs no declarator-unwrapping helper, since `field_declaration` binds its name
+            // directly to a `name` field.
+            { nodeType: 'field_declaration', kind: 'field', nameField: 'name' },
+            // A top-level, associated (inside `impl`/`trait`), or function-local `const`/`static` all parse
+            // identically — `scopeRestricted` excludes only the function-local case, the same convention
+            // Go's `const_spec`/`var_spec` already follow. No dedicated seam kind distinguishes a `static`
+            // from a `const`; `static` maps to `variable` (it names a single mutable-or-shared storage
+            // location, unlike a `const`'s compile-time-inlined value).
+            { nodeType: 'const_item', kind: 'constant', nameField: 'name', scopeRestricted: true },
+            { nodeType: 'static_item', kind: 'variable', nameField: 'name', scopeRestricted: true },
+        ],
+        callTypes: ['call_expression'],
+        callFunctionField: 'function',
+        importTypes: ['use_declaration'],
+        // A closure's body can be a block containing a statement (`|x| { let y = x; y }`) — unlike an
+        // ECMAScript arrow function, a bare-expression closure body (`|x| x`) is indistinguishable by node
+        // type alone (both are plain `closure_expression`), so this is not split into two cases; a
+        // function-local binding inside a bare-expression body is impossible syntactically anyway (no
+        // statement can appear there), so flipping scope unconditionally costs nothing. Verified against a
+        // real parse, not guessed.
+        bareFunctionScopeTypes: ['closure_expression'],
     },
 ];
 /**

package/lib/resolve.d.ts

@@ -45,6 +45,9 @@ export interface GraphNode {
     readonly isExported: boolean;
     readonly isAsync: boolean;
     readonly isStatic: boolean;
+    /** Decorator names applied to this declaration — see `RawDefinition.decorators`. Empty for a file
+     * node and for every declaration this package does not currently extract decorators from. */
+    readonly decorators: readonly string[];
     readonly updatedAt: number;
 }
 /** One resolved graph edge. */