gitnexus 1.6.5-rc.2 → 1.6.5-rc.21

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

@@ -0,0 +1,326 @@
+/**
+ * Tree-sitter query for PHP scope captures (RFC #909 Ring 3 LANG-php).
+ *
+ * Captures the structural skeleton the generic scope-resolution pipeline
+ * consumes: scopes (program/namespace/class/function), declarations
+ * (class-likes, method-likes, properties, variables), imports
+ * (namespace_use_declaration), type bindings (parameter annotations,
+ * property types, constructor-inferred locals, return types), and
+ * references (call sites, member writes).
+ *
+ * PHP specifics that shape this query:
+ *
+ *   - `namespace_use_declaration` is an import only at top level / inside
+ *     namespace blocks. Class-body `use_declaration` (trait-use) is a
+ *     different node type and is NOT captured here.
+ *
+ *   - `object_creation_expression` has `name` and `qualified_name` as
+ *     direct children (no wrapping node).
+ *
+ *   - `method_declaration` exposes a `return_type:` named field containing
+ *     a `type` node, which may be `named_type`, `optional_type`, etc.
+ *
+ *   - `property_element` has a `name:` field of type `variable_name`.
+ *
+ *   - `variable_name` nodes always include the `$` sigil in their text.
+ *
+ * Exposes lazy `Parser` and `Query` singletons so callers don't pay
+ * tree-sitter init cost per file.
+ */
+import Parser from 'tree-sitter';
+import Php from 'tree-sitter-php';
+// tree-sitter-php exports `{ php, php_only, html }` in recent versions, or the
+// language directly in older versions.
+//
+// IMPORTANT: must match the grammar used by the central parse phase
+// (`src/core/tree-sitter/parser-loader.ts` line: `[SupportedLanguages.PHP]: PHP.php_only`).
+// Using a different grammar variant causes tree-sitter to throw when running
+// a query built against grammar A on a tree parsed by grammar B — this error
+// is swallowed by `scope-extractor-bridge.ts`, producing silent empty results.
+const Php_typed = Php;
+const PHP_LANG = Php_typed.php_only ?? Php_typed.php ?? Php;
+const PHP_SCOPE_QUERY = `
+;; ── Scopes ────────────────────────────────────────────────────────────────
+
+(program) @scope.module
+
+;; Both block-scoped and statement-scoped namespace declarations.
+(namespace_definition) @scope.namespace
+
+(class_declaration)     @scope.class
+(interface_declaration) @scope.class
+(trait_declaration)     @scope.class
+(enum_declaration)      @scope.class
+
+(method_declaration)                        @scope.function
+(function_definition)                       @scope.function
+(anonymous_function)                        @scope.function
+(arrow_function)                            @scope.function
+
+;; ── Declarations — types ──────────────────────────────────────────────────
+
+(class_declaration
+  name: (name) @declaration.name) @declaration.class
+
+(interface_declaration
+  name: (name) @declaration.name) @declaration.interface
+
+(trait_declaration
+  name: (name) @declaration.name) @declaration.trait
+
+(enum_declaration
+  name: (name) @declaration.name) @declaration.enum
+
+;; ── Declarations — methods / functions / constructors ─────────────────────
+
+(method_declaration
+  name: (name) @declaration.name) @declaration.method
+
+(function_definition
+  name: (name) @declaration.name) @declaration.function
+
+;; ── Declarations — properties ─────────────────────────────────────────────
+
+;; PHP 7.4+ typed property: private UserRepo $repo;
+;; property_element has name: (variable_name) field.
+;; Emits BOTH a declaration (so SemanticModel registers the property) AND a type-binding.
+(property_declaration
+  type: (_) @type-binding.type
+  (property_element
+    name: (variable_name) @type-binding.name)) @type-binding.annotation
+
+(property_declaration
+  type: (_)
+  (property_element
+    name: (variable_name) @declaration.name)) @declaration.property
+
+;; Untyped property: public $id; — capture as plain declaration.
+(property_declaration
+  (property_element
+    name: (variable_name) @declaration.name)) @declaration.variable
+
+;; ── Imports — namespace_use_declaration ───────────────────────────────────
+;;
+;; Captures ALL forms: plain, alias, function/const qualifiers, and grouped.
+;; The import-decomposer in captures.ts fans out grouped uses.
+;;
+;; NOTE: class-body use_declaration = trait-use, NOT an import.
+;; Only namespace_use_declaration (top-level / namespace scope) is an import.
+
+(namespace_use_declaration) @import.statement
+
+;; ── Type bindings — parameters ────────────────────────────────────────────
+
+;; simple_parameter with a type hint: function f(User $u)
+;; type field is a 'type' supertype (named_type, optional_type, union_type, etc.)
+(simple_parameter
+  type: (_) @type-binding.type
+  name: (variable_name) @type-binding.name) @type-binding.parameter
+
+;; property_promotion_parameter: function __construct(private User $u)
+;; Emits type-binding so the constructor body can resolve $u as the typed param.
+(property_promotion_parameter
+  type: (_) @type-binding.type
+  name: (variable_name) @type-binding.name) @type-binding.parameter
+
+;; Also emit a @type-binding.annotation for the promoted parameter so that
+;; phpBindingScopeFor can hoist it to the Class scope (stripping the $ sigil).
+;; This enables compound-receiver resolution: $user->address->save() resolves
+;; address → Address via the Class scope's typeBindings.
+;; The @type-binding.parameter above stays for constructor-body resolution ($address).
+(property_promotion_parameter
+  type: (_) @type-binding.type
+  name: (variable_name) @type-binding.name) @type-binding.annotation
+
+;; Also emit a @declaration.property so SemanticModel registers the promoted
+;; parameter as a class-owned property (enabling $obj->propName lookups).
+(property_promotion_parameter
+  name: (variable_name) @declaration.name) @declaration.property
+
+;; ── Type bindings — local assignment: $u = new User() ─────────────────────
+
+;; new ClassName() — name is a direct child of object_creation_expression
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (object_creation_expression
+    (name) @type-binding.type)) @type-binding.constructor
+
+;; new Foo\Bar\ClassName() — qualified_name wraps name
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (object_creation_expression
+    (qualified_name
+      (name) @type-binding.type))) @type-binding.constructor
+
+;; ── Type bindings — $alias = $u (identifier alias) ───────────────────────
+
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (variable_name) @type-binding.type) @type-binding.alias
+
+;; ── Type bindings — $u = factory() (free call return alias) ──────────────
+
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (function_call_expression
+    function: (name) @type-binding.type)) @type-binding.alias
+
+;; ── Type bindings — $u = $svc->getUser() (method call return alias) ───────
+
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (member_call_expression
+    name: (name) @type-binding.type)) @type-binding.alias
+
+;; ── Type bindings — method return type ───────────────────────────────────
+
+;; method_declaration exposes return_type: field (type node supertype).
+;; named_type wraps the class name: function getUser(): User
+(method_declaration
+  name: (name) @type-binding.name
+  return_type: (named_type
+    (name) @type-binding.type)) @type-binding.return
+
+;; nullable return type via optional_type: function getUser(): ?User
+(method_declaration
+  name: (name) @type-binding.name
+  return_type: (optional_type
+    (named_type
+      (name) @type-binding.type))) @type-binding.return
+
+;; function_definition (top-level or namespace-level) return type: User
+;; Enables cross-file return-type propagation for free functions.
+(function_definition
+  name: (name) @type-binding.name
+  return_type: (named_type
+    (name) @type-binding.type)) @type-binding.return
+
+;; nullable return type for function_definition: ?User
+(function_definition
+  name: (name) @type-binding.name
+  return_type: (optional_type
+    (named_type
+      (name) @type-binding.type))) @type-binding.return
+
+;; ── References — free calls: foo() ───────────────────────────────────────
+
+(function_call_expression
+  function: (name) @reference.name) @reference.call.free
+
+;; ── References — member calls: $obj->method() ────────────────────────────
+;;
+;; SAFETY-INVARIANT (Finding 1 of PR #1497 adversarial review): the name:
+;; field is constrained to (name), NOT (_) — tree-sitter-php emits
+;; variable_name nodes for dynamic method names ($obj->$method(),
+;; $obj->{$method}()). Keeping the pattern at (name) is what suppresses
+;; capture of those dynamic shapes. The resolver is structural-only and
+;; cannot infer the bound method name from runtime values; relaxing this
+;; pattern to (_) would silently emit zero-confidence false-positive
+;; edges. Regression: test/fixtures/lang-resolution/php-dynamic-calls/.
+
+(member_call_expression
+  object: (_) @reference.receiver
+  name: (name) @reference.name) @reference.call.member
+
+;; ── References — null-safe member calls: $obj?->method() (PHP 8+) ─────────
+
+(nullsafe_member_call_expression
+  object: (_) @reference.receiver
+  name: (name) @reference.name) @reference.call.member
+
+;; ── References — static calls: X::method() ───────────────────────────────
+;;
+;; Same SAFETY-INVARIANT as member_call_expression above: name: (name)
+;; deliberately excludes variable_name so Class::$method() and
+;; $className::$method() shapes do not capture. The receiver field uses
+;; (_) because static dispatch on a variable receiver
+;; ($className::method()) IS captured — but resolution falls through
+;; harmlessly when $className has no class type binding. See
+;; php-dynamic-calls/ regression suite.
+
+(scoped_call_expression
+  scope: (_) @reference.receiver
+  name: (name) @reference.name) @reference.call.member
+
+;; ── Type bindings — $x = X::Constant or $x = X::CASE (enum case) ─────────
+;; Binds the variable to the class name X so member calls on $x dispatch
+;; to X's methods (e.g. UserRole::Viewer → label()).
+;;
+;; tree-sitter-php emits class_constant_access_expression with two name
+;; children: [0]=class/enum name, [1]=constant/case name. The dot-anchor
+;; before (name) matches only the FIRST name child (the class).
+
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (class_constant_access_expression
+    . (name) @type-binding.type)) @type-binding.alias
+
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (class_constant_access_expression
+    (qualified_name
+      (name) @type-binding.type))) @type-binding.alias
+
+;; ── Type bindings — $x = SomeClass::staticFactory() ──────────────────────
+;; Binds $x to the type returned by the static factory method, anchored on
+;; the method name (chain-follow resolves the actual return type later).
+
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (scoped_call_expression
+    name: (name) @type-binding.type)) @type-binding.alias
+
+;; ── Type bindings — null-safe member-call result: $x = $a?->getY() ───────
+
+(assignment_expression
+  left: (variable_name) @type-binding.name
+  right: (nullsafe_member_call_expression
+    name: (name) @type-binding.type)) @type-binding.alias
+
+;; ── References — constructor calls: new User() ───────────────────────────
+
+(object_creation_expression
+  (name) @reference.name) @reference.call.constructor
+
+(object_creation_expression
+  (qualified_name
+    (name) @reference.name)) @reference.call.constructor
+
+;; ── References — member writes: $obj->prop = $x ──────────────────────────
+
+(assignment_expression
+  left: (member_access_expression
+    object: (_) @reference.receiver
+    name: (name) @reference.name)) @reference.write.member
+
+;; ── References — static property writes: User::$count = $x ──────────────
+;; Uses @reference.write.static anchor so captures.ts can strip the leading
+;; $ from the variable_name capture (static props are stored without $ in graph).
+;;
+;; SAFETY-INVARIANT (Finding 2 of PR #1497 adversarial review): no
+;; read-access property capture exists in this query — dynamic property
+;; reads ($obj->$prop, $obj->{$prop}) produce no captures, which is the
+;; desired behavior for a structural-only resolver. Adding a read pattern
+;; in the future MUST keep name: (name) (not (_)) to preserve the
+;; suppression. Regression: php-dynamic-calls/ fixture dynamicPropertyRead.
+
+(assignment_expression
+  left: (scoped_property_access_expression
+    scope: (_) @reference.receiver
+    name: (variable_name) @reference.name)) @reference.write.static
+`;
+let _parser = null;
+let _query = null;
+export function getPhpParser() {
+    if (_parser === null) {
+        _parser = new Parser();
+        _parser.setLanguage(PHP_LANG);
+    }
+    return _parser;
+}
+export function getPhpScopeQuery() {
+    if (_query === null) {
+        _query = new Parser.Query(PHP_LANG, PHP_SCOPE_QUERY);
+    }
+    return _query;
+}

package/dist/core/ingestion/languages/php/receiver-binding.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Synthesize `@type-binding.self` captures for PHP instance methods —
+ * one for `$this` (always on non-static methods inside a type
+ * declaration) and optionally one for `parent` (only on class methods
+ * when the enclosing class has an explicit `base_clause`).
+ *
+ * Mirrors `languages/csharp/receiver-binding.ts` in structure. PHP's
+ * grammar doesn't give us a clean `.scm` pattern for "implicit receiver
+ * on every instance method inside an enclosing type" because `$this` is
+ * not a parameter — it's an implicit receiver. Synthesis in code is the
+ * same approach C# uses for `this` / `base`.
+ *
+ * ## Known limitations
+ *
+ *   - **Trait `$this`**: for methods defined in a trait, `$this` is
+ *     synthesized as a binding to the trait itself. The actual using-class
+ *     type is not known at single-file parse time. V1 limitation —
+ *     documented in `index.ts`.
+ *   - **Anonymous classes**: skipped (no stable enclosing class name).
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+/**
+ * Build zero, one, or two `@type-binding.self` matches for `fnNode`:
+ *
+ *  - Returns `[]` if the function is free (no enclosing type), static,
+ *    or the enclosing type has no resolvable name.
+ *  - Returns one match (`$this`) for non-static methods inside a
+ *    class / trait / interface / enum body.
+ *  - Returns two matches (`$this` + `parent`) only when the function
+ *    lives in a `class_declaration` that has an explicit `base_clause`.
+ *
+ * The caller is responsible for guaranteeing
+ * `FUNCTION_NODE_TYPES.has(fnNode.type)`.
+ */
+export declare function synthesizePhpReceiverBinding(fnNode: SyntaxNode): CaptureMatch[];

package/dist/core/ingestion/languages/php/receiver-binding.js

@@ -0,0 +1,128 @@
+/**
+ * Synthesize `@type-binding.self` captures for PHP instance methods —
+ * one for `$this` (always on non-static methods inside a type
+ * declaration) and optionally one for `parent` (only on class methods
+ * when the enclosing class has an explicit `base_clause`).
+ *
+ * Mirrors `languages/csharp/receiver-binding.ts` in structure. PHP's
+ * grammar doesn't give us a clean `.scm` pattern for "implicit receiver
+ * on every instance method inside an enclosing type" because `$this` is
+ * not a parameter — it's an implicit receiver. Synthesis in code is the
+ * same approach C# uses for `this` / `base`.
+ *
+ * ## Known limitations
+ *
+ *   - **Trait `$this`**: for methods defined in a trait, `$this` is
+ *     synthesized as a binding to the trait itself. The actual using-class
+ *     type is not known at single-file parse time. V1 limitation —
+ *     documented in `index.ts`.
+ *   - **Anonymous classes**: skipped (no stable enclosing class name).
+ */
+import { nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+const TYPE_DECL_NODE_TYPES = new Set([
+    'class_declaration',
+    'interface_declaration',
+    'trait_declaration',
+    'enum_declaration',
+]);
+const FUNCTION_NODE_TYPES = new Set([
+    'method_declaration',
+    'function_definition',
+    'anonymous_function',
+    'arrow_function',
+]);
+/** Walk up to find the enclosing type declaration. */
+function findEnclosingTypeDeclaration(node) {
+    let cur = node.parent;
+    while (cur !== null) {
+        if (TYPE_DECL_NODE_TYPES.has(cur.type))
+            return cur;
+        cur = cur.parent;
+    }
+    return null;
+}
+function typeName(typeNode) {
+    return typeNode.childForFieldName('name')?.text ?? null;
+}
+/**
+ * Return the base class name from a `base_clause` child of the class node.
+ * `base_clause` contains a `qualified_name` or `name` child.
+ */
+function baseClauseText(typeNode) {
+    for (let i = 0; i < typeNode.namedChildCount; i++) {
+        const child = typeNode.namedChild(i);
+        if (child === null || child.type !== 'base_clause')
+            continue;
+        const nameNode = child.firstNamedChild;
+        if (nameNode === null)
+            return null;
+        // Take last segment of qualified name (e.g. \App\Models\BaseModel → BaseModel)
+        const text = nameNode.text.trim();
+        const segments = text.split('\\').filter(Boolean);
+        return segments[segments.length - 1] ?? text;
+    }
+    return null;
+}
+/** Check whether this method has a `static_modifier` child. */
+function isStaticMethod(fnNode) {
+    for (let i = 0; i < fnNode.namedChildCount; i++) {
+        const child = fnNode.namedChild(i);
+        if (child !== null && child.type === 'static_modifier')
+            return true;
+    }
+    return false;
+}
+/**
+ * Build zero, one, or two `@type-binding.self` matches for `fnNode`:
+ *
+ *  - Returns `[]` if the function is free (no enclosing type), static,
+ *    or the enclosing type has no resolvable name.
+ *  - Returns one match (`$this`) for non-static methods inside a
+ *    class / trait / interface / enum body.
+ *  - Returns two matches (`$this` + `parent`) only when the function
+ *    lives in a `class_declaration` that has an explicit `base_clause`.
+ *
+ * The caller is responsible for guaranteeing
+ * `FUNCTION_NODE_TYPES.has(fnNode.type)`.
+ */
+export function synthesizePhpReceiverBinding(fnNode) {
+    if (!FUNCTION_NODE_TYPES.has(fnNode.type))
+        return [];
+    if (isStaticMethod(fnNode))
+        return [];
+    const enclosingType = findEnclosingTypeDeclaration(fnNode);
+    if (enclosingType === null)
+        return [];
+    // Anonymous class — skip (no stable name).
+    if (enclosingType.type === 'anonymous_class_declaration')
+        return [];
+    const enclosingName = typeName(enclosingType);
+    if (enclosingName === null)
+        return [];
+    // Anchor the synthesized captures to the method body (compound_statement)
+    // so they land inside the function scope, not at the class scope.
+    // For interface/abstract methods that have no body, skip.
+    const bodyNode = fnNode.childForFieldName('body') ??
+        // arrow_function: body is the expression after `=>`
+        fnNode.childForFieldName('return_value');
+    if (bodyNode === null)
+        return [];
+    const out = [];
+    out.push(buildReceiverMatch(bodyNode, '$this', enclosingName));
+    // `parent` applies only to class methods with an explicit base_clause.
+    if (enclosingType.type === 'class_declaration') {
+        const baseText = baseClauseText(enclosingType);
+        if (baseText !== null) {
+            out.push(buildReceiverMatch(bodyNode, 'parent', baseText));
+        }
+    }
+    return out;
+}
+function buildReceiverMatch(anchorNode, name, typeText) {
+    const m = {
+        '@type-binding.self': nodeToCapture('@type-binding.self', anchorNode),
+        '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, name),
+        '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, typeText),
+    };
+    return m;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * PHP `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
+ * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3 LANG-php).
+ *
+ * Third migration after Python and C#. See `pythonScopeResolver` for the
+ * canonical shape.
+ *
+ * ## Circular-import avoidance
+ *
+ * The old PR had `php/scope-resolver.ts` importing `phpProvider` from
+ * `../php.js` while `php.ts` imported `phpScopeResolver` from `./php/index.js`
+ * — undefined at module load. The canonical fix (mirroring C#):
+ *
+ *   - `scope-resolver.ts` imports `phpProvider` from `../php.js` ✓
+ *   - `php.ts` imports individual hook FUNCTIONS from `./php/index.js` ✗
+ *
+ * Node's ESM handles the cycle correctly because `phpProvider` is a named
+ * export that is live-binding — by the time `phpScopeResolver` is first
+ * read (lazily, at resolution time), `phpProvider` is fully initialized.
+ */
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+declare const phpScopeResolver: ScopeResolver;
+export { phpScopeResolver };