arceus-s 1.6.4

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

@@ -0,0 +1,241 @@
+/**
+ * Capture-match → semantic-shape interpreters for PHP.
+ *
+ *   - `interpretPhpImport`       → `ParsedImport`
+ *   - `interpretPhpTypeBinding`  → `ParsedTypeBinding`
+ *
+ * Import matches arrive pre-decomposed by `emitPhpScopeCaptures` (one
+ * CaptureMatch per logical import, with synthesized `@import.kind /
+ * source / name / alias` markers). Type-binding matches arrive from
+ * the raw query captures — each `@type-binding.*` anchor carries
+ * `@type-binding.name` + `@type-binding.type`.
+ */
+// ─── interpretImport ──────────────────────────────────────────────────────
+export function interpretPhpImport(captures) {
+    const kindCap = captures['@import.kind'];
+    const sourceCap = captures['@import.source'];
+    const nameCap = captures['@import.name'];
+    const aliasCap = captures['@import.alias'];
+    const kind = kindCap?.text;
+    if (kind === undefined || sourceCap === undefined)
+        return null;
+    const source = sourceCap.text.trim();
+    if (source === '')
+        return null;
+    switch (kind) {
+        case 'namespace': {
+            // `use Foo\Bar;` — PHP `use` is a NAMED import (binds the class
+            // `Bar`, not the namespace `Foo`). This differs from C# `using`,
+            // which is a true namespace import. Producing 'named' here makes
+            // `new Bar()` resolve to the imported class def.
+            const localName = nameCap?.text.trim() ?? lastSegment(source);
+            return {
+                kind: 'named',
+                localName,
+                importedName: localName,
+                targetRaw: source,
+            };
+        }
+        case 'alias': {
+            // `use Foo\Bar as Baz;`
+            if (aliasCap === undefined)
+                return null;
+            const alias = aliasCap.text.trim();
+            if (alias === '')
+                return null;
+            const importedName = lastSegment(source);
+            return {
+                kind: 'alias',
+                localName: alias,
+                importedName,
+                alias,
+                targetRaw: source,
+            };
+        }
+        case 'function': {
+            // `use function Foo\bar;` — treat as named import; importedName is
+            // the function name (last segment). targetRaw is the full path.
+            const localName = nameCap?.text.trim() ?? lastSegment(source);
+            return {
+                kind: 'named',
+                localName,
+                importedName: localName,
+                targetRaw: source,
+            };
+        }
+        case 'const': {
+            // `use const Foo\BAR;` — same shape as function.
+            const localName = nameCap?.text.trim() ?? lastSegment(source);
+            return {
+                kind: 'named',
+                localName,
+                importedName: localName,
+                targetRaw: source,
+            };
+        }
+        default:
+            return null;
+    }
+}
+// ─── interpretTypeBinding ─────────────────────────────────────────────────
+export function interpretPhpTypeBinding(captures) {
+    const nameCap = captures['@type-binding.name'];
+    const typeCap = captures['@type-binding.type'];
+    if (nameCap === undefined || typeCap === undefined)
+        return null;
+    // Determine source from anchor captures. Order: most-specific first.
+    let source = 'parameter-annotation';
+    if (captures['@type-binding.self'] !== undefined)
+        source = 'self';
+    else if (captures['@type-binding.constructor'] !== undefined)
+        source = 'constructor-inferred';
+    else if (captures['@type-binding.annotation'] !== undefined)
+        source = 'annotation';
+    else if (captures['@type-binding.alias'] !== undefined)
+        source = 'assignment-inferred';
+    else if (captures['@type-binding.return'] !== undefined)
+        source = 'return-annotation';
+    let rawType;
+    if (source === 'assignment-inferred') {
+        // `@type-binding.alias` captures cover several assignment RHS shapes:
+        //   - `$alias = $u`               → rawType = '$u'   (variable alias)
+        //   - `$u = getUser()`            → rawType = 'getUser' (callable alias)
+        //   - `$u = new User()`           → rawType = 'User' (constructor — via @type-binding.constructor; handled below)
+        //   - `$role = UserRole::Viewer`  → rawType = 'UserRole' (enum/class constant)
+        //
+        // For variable aliases (`$u`), `normalizePhpType` returns null because
+        // `$` is not a word character. We must preserve the raw `$`-prefixed name
+        // so `followChainedRef` can walk the chain `$alias → $u → User`.
+        // For callable/class names, `normalizePhpType` strips qualifiers correctly.
+        const rawText = typeCap.text.trim();
+        if (rawText.startsWith('$')) {
+            // Variable alias: keep as-is for chain-following.
+            rawType = rawText;
+        }
+        else {
+            rawType = normalizePhpType(rawText);
+        }
+    }
+    else {
+        // All other sources: strip PHP type decoration to get the simple class name:
+        //   ?User → User (nullable prefix)
+        //   User|null → User (union with null/false/void)
+        //   User&Loggable → User (intersection — take first meaningful)
+        //   Collection<User> → User (PHPDoc generic wrapper)
+        //   User[] → User (array suffix)
+        //   \App\Models\User → User (backslash qualifier)
+        rawType = normalizePhpType(typeCap.text.trim());
+    }
+    if (rawType === null)
+        return null;
+    // PHP variable names include the `$` sigil (e.g. `$user`). Most
+    // bindings keep it because they are looked up via the variable
+    // (`$user->method()` finds binding `$user`). Property field bindings
+    // are different: `$user->address` looks up `address` (no sigil) on
+    // the User class. Property declarations carry source `'annotation'`,
+    // so we strip the leading `$` for that source only.
+    let boundName = nameCap.text.trim();
+    if (source === 'annotation' && boundName.startsWith('$')) {
+        boundName = boundName.slice(1);
+    }
+    return { boundName, rawTypeName: rawType, source };
+}
+// ─── Type normalization ───────────────────────────────────────────────────
+/**
+ * Normalize a PHP type string to a simple class identifier, or `null`
+ * when the type is uninformative (primitive, void, mixed, self, etc.).
+ *
+ * Rules applied in order:
+ *   1. Strip nullable prefix `?`
+ *   2. Split on `|` (union) — keep only if exactly one non-null part
+ *   3. Take first part of `&` intersection
+ *   4. Strip array suffix `[]`
+ *   5. Strip generic wrapper `Collection<User>` → `User`
+ *   6. Canonicalize leading backslash off: `\App\Models\User` → `App\Models\User`
+ *   7. Reject PHP primitive / pseudo types
+ *
+ * The qualified form is preserved on `TypeRef.rawName` so downstream PHP
+ * receiver resolution can distinguish `\App\Other\User` from a same-simple-name
+ * `User` reachable via `use`. Without this, fully-qualified type hints collapse
+ * to ambiguous simple names and resolve against the caller's scope chain
+ * instead of the explicit target the source named (Codex PR #1497 review,
+ * finding 1).
+ */
+export function normalizePhpType(raw) {
+    // 1. Strip nullable prefix
+    let type = raw.startsWith('?') ? raw.slice(1).trim() : raw;
+    // 2. Union type — keep only if one non-null/false/void part remains
+    if (type.includes('|')) {
+        const parts = type
+            .split('|')
+            .map((p) => p.trim())
+            .filter((p) => p !== 'null' && p !== 'false' && p !== 'void' && p !== 'mixed' && p !== '');
+        if (parts.length !== 1)
+            return null;
+        type = parts[0];
+    }
+    // 3. Intersection type — take the first part
+    if (type.includes('&')) {
+        const first = type.split('&')[0].trim();
+        if (first === '')
+            return null;
+        type = first;
+    }
+    // 4. Strip array suffix
+    if (type.endsWith('[]'))
+        type = type.slice(0, -2).trim();
+    // 5. Strip single-arg generic wrapper: Collection<User> → User
+    //    Qualified inner types (Collection<\App\Models\User>) survive — the
+    //    capture group preserves whatever the writer named.
+    const genericMatch = type.match(/^\w[\w\\]*\s*<([^,<>]+)>$/);
+    if (genericMatch) {
+        type = genericMatch[1].trim();
+    }
+    // 6. Canonicalize leading backslash off — keep the qualified path intact.
+    //    `\App\Models\User` → `App\Models\User`. `App\Models\User` → unchanged.
+    //    Unqualified `User` stays as `User`. The qualified form is the lookup
+    //    key into the workspace QualifiedNameIndex (PHP defs are indexed by
+    //    namespace-joined qualifiedName); the leading-backslash distinction in
+    //    source is only an "absolute path" anchor, not part of the canonical key.
+    if (type.startsWith('\\'))
+        type = type.replace(/^\\+/, '');
+    // 7. Reject primitives / pseudo-types
+    if (isPrimitiveOrPseudo(type))
+        return null;
+    // Must be a (possibly qualified) PHP identifier — segments of word chars
+    // separated by single backslashes. Empty segments (consecutive backslashes,
+    // trailing backslash) are rejected.
+    if (!/^\w+(?:\\\w+)*$/.test(type))
+        return null;
+    return type;
+}
+const PHP_PRIMITIVE_TYPES = new Set([
+    'int',
+    'integer',
+    'float',
+    'double',
+    'string',
+    'bool',
+    'boolean',
+    'array',
+    'object',
+    'callable',
+    'iterable',
+    'null',
+    'void',
+    'never',
+    'mixed',
+    'false',
+    'true',
+    'self',
+    'static',
+    'parent',
+]);
+function isPrimitiveOrPseudo(type) {
+    return PHP_PRIMITIVE_TYPES.has(type.toLowerCase());
+}
+/** Last backslash-separated segment: `Foo\Bar\Baz` → `Baz`. */
+function lastSegment(path) {
+    const parts = path.split('\\').filter(Boolean);
+    return parts[parts.length - 1] ?? path;
+}

package/dist/core/ingestion/languages/php/merge-bindings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PHP shadowing precedence for the `mergeBindings` hook.
+ *
+ * Tier ranking (lower wins in shadowing):
+ *
+ *   - 0: `local` — a class member, method, local variable, or parameter
+ *        declared in this scope.
+ *   - 1: `import` / `namespace` / `reexport` — `use Foo\Bar;`,
+ *        `use Foo\Bar as Baz;`, `use function`, `use const`.
+ *        All use-statement flavors that introduce a name sit at this tier.
+ *   - 2: `wildcard` — grouped uses / wildcard imports (deferred; mapped
+ *        here for completeness).
+ *
+ * Within a surviving tier we de-dup by `DefId`, last-write-wins so a
+ * `use` re-declared further down the file cleanly replaces the earlier
+ * binding.
+ */
+import type { BindingRef } from '../../../../_shared/index.js';
+export declare function phpMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[];

package/dist/core/ingestion/languages/php/merge-bindings.js

@@ -0,0 +1,47 @@
+/**
+ * PHP shadowing precedence for the `mergeBindings` hook.
+ *
+ * Tier ranking (lower wins in shadowing):
+ *
+ *   - 0: `local` — a class member, method, local variable, or parameter
+ *        declared in this scope.
+ *   - 1: `import` / `namespace` / `reexport` — `use Foo\Bar;`,
+ *        `use Foo\Bar as Baz;`, `use function`, `use const`.
+ *        All use-statement flavors that introduce a name sit at this tier.
+ *   - 2: `wildcard` — grouped uses / wildcard imports (deferred; mapped
+ *        here for completeness).
+ *
+ * Within a surviving tier we de-dup by `DefId`, last-write-wins so a
+ * `use` re-declared further down the file cleanly replaces the earlier
+ * binding.
+ */
+const TIER_LOCAL = 0;
+const TIER_IMPORT = 1;
+const TIER_WILDCARD = 2;
+const TIER_UNKNOWN = 3;
+function tierOf(b) {
+    switch (b.origin) {
+        case 'local':
+            return TIER_LOCAL;
+        case 'reexport':
+        case 'import':
+        case 'namespace':
+            return TIER_IMPORT;
+        case 'wildcard':
+            return TIER_WILDCARD;
+        default:
+            return TIER_UNKNOWN;
+    }
+}
+export function phpMergeBindings(bindings) {
+    if (bindings.length === 0)
+        return bindings;
+    let bestTier = Number.POSITIVE_INFINITY;
+    for (const b of bindings)
+        bestTier = Math.min(bestTier, tierOf(b));
+    const survivors = bindings.filter((b) => tierOf(b) === bestTier);
+    const seen = new Map();
+    for (const b of survivors)
+        seen.set(b.def.nodeId, b);
+    return [...seen.values()];
+}

package/dist/core/ingestion/languages/php/namespace-siblings.d.ts

@@ -0,0 +1,51 @@
+/**
+ * PHP same-namespace cross-file visibility.
+ *
+ * In PHP, every class declared in `namespace Foo\Bar` is visible to all
+ * other files in the same namespace WITHOUT an explicit `use` statement.
+ * Without this pass, `Service.php` (namespace `App\Services`) can't see
+ * `User` declared in `Models.php` (namespace `App\Models`) unless
+ * `UserService.php` has an explicit `use App\Models\User` statement.
+ *
+ * More importantly, A.php (namespace `App\Models`) can return `Greeting`
+ * (same namespace `App\Models`) without importing it, and the compound-
+ * receiver resolver needs to find `Greeting` as a class binding in the
+ * scope chain.
+ *
+ * Implementation mirrors C#'s `namespace-siblings.ts`:
+ *   1. Extract the declared namespace from each PHP file's source.
+ *   2. Group class-like defs by namespace.
+ *   3. Inject sibling class defs into each file's Module scope's
+ *      `bindingAugmentations` with `origin: 'namespace'`.
+ *   4. Also mirror return-type bindings from same-namespace siblings
+ *      so cross-file chain-follow finds return types without explicit imports.
+ *
+ * Uses the PHP tree-sitter parser (via the lazy singleton in `query.ts`)
+ * to extract namespace declarations — same AST that `extractParsedFile`
+ * already parsed, reused via `treeCache` to avoid double-parsing.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+export interface PhpSiblingInputs {
+    readonly fileContents: ReadonlyMap<string, string>;
+    readonly treeCache?: {
+        get(filePath: string): unknown;
+    };
+}
+/**
+ * Read the cached PHP namespace for a given filePath. Returns `''` (global)
+ * when the file has no namespace_definition or hasn't been processed yet.
+ * Callers should only consult this AFTER either `populatePhpClassQualifiedNames`
+ * or `populatePhpNamespaceSiblings` has run for the current resolution.
+ */
+export declare function getPhpNamespaceForFile(filePath: string): string;
+/**
+ * Inject same-namespace class defs and return-type bindings into each
+ * PHP file's Module scope's `bindingAugmentations`. This makes classes
+ * in the same PHP namespace visible to each other without explicit `use`
+ * statements, mirroring PHP's actual runtime behavior.
+ *
+ * Uses `origin: 'namespace'` so `phpMergeBindings` tiers it below
+ * explicit `use` imports (`origin: 'import'`) and local declarations.
+ */
+export declare function populatePhpNamespaceSiblings(parsedFiles: readonly ParsedFile[], indexes: ScopeResolutionIndexes, inputs: PhpSiblingInputs): void;

package/dist/core/ingestion/languages/php/namespace-siblings.js

@@ -0,0 +1,288 @@
+/**
+ * PHP same-namespace cross-file visibility.
+ *
+ * In PHP, every class declared in `namespace Foo\Bar` is visible to all
+ * other files in the same namespace WITHOUT an explicit `use` statement.
+ * Without this pass, `Service.php` (namespace `App\Services`) can't see
+ * `User` declared in `Models.php` (namespace `App\Models`) unless
+ * `UserService.php` has an explicit `use App\Models\User` statement.
+ *
+ * More importantly, A.php (namespace `App\Models`) can return `Greeting`
+ * (same namespace `App\Models`) without importing it, and the compound-
+ * receiver resolver needs to find `Greeting` as a class binding in the
+ * scope chain.
+ *
+ * Implementation mirrors C#'s `namespace-siblings.ts`:
+ *   1. Extract the declared namespace from each PHP file's source.
+ *   2. Group class-like defs by namespace.
+ *   3. Inject sibling class defs into each file's Module scope's
+ *      `bindingAugmentations` with `origin: 'namespace'`.
+ *   4. Also mirror return-type bindings from same-namespace siblings
+ *      so cross-file chain-follow finds return types without explicit imports.
+ *
+ * Uses the PHP tree-sitter parser (via the lazy singleton in `query.ts`)
+ * to extract namespace declarations — same AST that `extractParsedFile`
+ * already parsed, reused via `treeCache` to avoid double-parsing.
+ */
+import { getPhpParser } from './query.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
+/**
+ * Extract the declared namespace from a PHP file's source.
+ * Uses the cached AST tree when available to avoid re-parsing.
+ */
+function extractPhpFileStructure(content, cachedTree) {
+    const tree = cachedTree ??
+        parseSourceSafe(getPhpParser(), content, undefined, {
+            bufferSize: getTreeSitterBufferSize(content),
+        });
+    // Walk top-level nodes looking for namespace_definition.
+    // PHP files have at most one namespace declaration (PSR-4 convention).
+    // `namespace_definition` has a `name:` field of type `namespace_name`.
+    const root = tree.rootNode;
+    for (let i = 0; i < root.namedChildCount; i++) {
+        const child = root.namedChild(i);
+        if (child === null)
+            continue;
+        if (child.type === 'namespace_definition') {
+            const nameNode = child.childForFieldName('name');
+            if (nameNode !== null) {
+                return { namespace: nameNode.text };
+            }
+        }
+    }
+    return { namespace: '' };
+}
+// ─── Augmentation bucket helper ─────────────────────────────────────────────
+function getAugmentationBucket(augmentations, scopeId, name) {
+    let scopeBindings = augmentations.get(scopeId);
+    if (scopeBindings === undefined) {
+        scopeBindings = new Map();
+        augmentations.set(scopeId, scopeBindings);
+    }
+    let bucket = scopeBindings.get(name);
+    if (bucket === undefined) {
+        bucket = [];
+        scopeBindings.set(name, bucket);
+    }
+    return bucket;
+}
+function isClassLikeDef(def) {
+    return (def.type === 'Class' ||
+        def.type === 'Interface' ||
+        def.type === 'Struct' ||
+        def.type === 'Enum' ||
+        def.type === 'Trait');
+}
+/**
+ * Side-channel cache populated by `populatePhpNamespaceSiblings` so that
+ * later visibility-check hooks (e.g., `isCallableVisibleFromCaller`) can
+ * look up a file's PHP namespace without re-parsing. Cleared at the start
+ * of every populate run so stale entries don't leak across resolutions.
+ */
+const namespaceByFilePath = new Map();
+/**
+ * Read the cached PHP namespace for a given filePath. Returns `''` (global)
+ * when the file has no namespace_definition or hasn't been processed yet.
+ * Callers should only consult this AFTER either `populatePhpClassQualifiedNames`
+ * or `populatePhpNamespaceSiblings` has run for the current resolution.
+ */
+export function getPhpNamespaceForFile(filePath) {
+    return namespaceByFilePath.get(filePath) ?? '';
+}
+/**
+ * Inject same-namespace class defs and return-type bindings into each
+ * PHP file's Module scope's `bindingAugmentations`. This makes classes
+ * in the same PHP namespace visible to each other without explicit `use`
+ * statements, mirroring PHP's actual runtime behavior.
+ *
+ * Uses `origin: 'namespace'` so `phpMergeBindings` tiers it below
+ * explicit `use` imports (`origin: 'import'`) and local declarations.
+ */
+export function populatePhpNamespaceSiblings(parsedFiles, indexes, inputs) {
+    // Step 1: extract namespace structure for each file. Also seed the
+    // side-channel cache used by visibility-check hooks downstream.
+    namespaceByFilePath.clear();
+    const structureByFile = new Map();
+    for (const parsed of parsedFiles) {
+        const content = inputs.fileContents.get(parsed.filePath);
+        if (content === undefined)
+            continue;
+        const cachedTree = inputs.treeCache?.get(parsed.filePath);
+        const struct = extractPhpFileStructure(content, cachedTree);
+        structureByFile.set(parsed.filePath, struct);
+        namespaceByFilePath.set(parsed.filePath, struct.namespace);
+    }
+    const buckets = new Map();
+    const getBucket = (ns) => {
+        let b = buckets.get(ns);
+        if (b === undefined) {
+            b = { scopes: [], classDefs: [] };
+            buckets.set(ns, b);
+        }
+        return b;
+    };
+    for (const parsed of parsedFiles) {
+        const struct = structureByFile.get(parsed.filePath);
+        if (struct === undefined)
+            continue;
+        const ns = struct.namespace;
+        const bucket = getBucket(ns);
+        // Register the file's module scope in the bucket.
+        const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
+        if (moduleScope !== undefined) {
+            bucket.scopes.push({
+                filePath: parsed.filePath,
+                scopeId: moduleScope.id,
+                scope: moduleScope,
+            });
+        }
+        // Collect class-like defs declared at the top-level of this file
+        // (defs in Class or Module scopes, excluding nested inner classes).
+        for (const scope of parsed.scopes) {
+            if (scope.kind !== 'Class')
+                continue;
+            // Only top-level class scopes (parent is Module or Namespace scope).
+            if (scope.parent === null)
+                continue;
+            const parentScope = parsed.scopes.find((s) => s.id === scope.parent);
+            if (parentScope === undefined ||
+                (parentScope.kind !== 'Module' && parentScope.kind !== 'Namespace')) {
+                continue;
+            }
+            for (const def of scope.ownedDefs) {
+                if (isClassLikeDef(def)) {
+                    bucket.classDefs.push(def);
+                    break; // one class-like per scope
+                }
+            }
+        }
+    }
+    const augmentations = indexes.bindingAugmentations;
+    // Step 3: For each namespace bucket, inject sibling class bindings
+    // into every file's Module scope (that is NOT the declaring file).
+    for (const [, bucket] of buckets) {
+        // Build name → def map (simple name of qualifiedName).
+        const defsByName = new Map();
+        for (const def of bucket.classDefs) {
+            const q = def.qualifiedName ?? '';
+            const simpleName = q.includes('.')
+                ? q.slice(q.lastIndexOf('.') + 1)
+                : q.includes('\\')
+                    ? q.slice(q.lastIndexOf('\\') + 1)
+                    : q;
+            if (simpleName === '')
+                continue;
+            const arr = defsByName.get(simpleName) ?? [];
+            arr.push(def);
+            defsByName.set(simpleName, arr);
+        }
+        for (const { filePath, scopeId, scope } of bucket.scopes) {
+            for (const [name, defs] of defsByName) {
+                // Skip if already locally declared (origin: 'local' wins).
+                const local = scope.bindings.get(name);
+                if (local !== undefined && local.some((b) => b.origin === 'local'))
+                    continue;
+                for (const def of defs) {
+                    if (def.filePath === filePath)
+                        continue; // don't self-inject
+                    const arr = getAugmentationBucket(augmentations, scopeId, name);
+                    if (arr.some((b) => b.def.nodeId === def.nodeId))
+                        continue;
+                    arr.push({ def, origin: 'namespace' });
+                }
+            }
+        }
+    }
+    // Step 3b: Inject fully-qualified-name bindings into every PHP file's
+    // Module scope. PHP `\App\Models\User` (leading-backslash FQN) and
+    // `App\Models\User` (already-qualified relative) on a parameter or
+    // typed receiver must resolve to the exact namespace-qualified class
+    // regardless of which simple-name `User` the caller's `use` imports
+    // shadowed. The shared `findClassBindingInScope` scope-chain walk
+    // consumes these augmentations via `lookupBindingsAt`, so adding the
+    // qualified key on every file's module scope routes FQN-receivers to
+    // the right def. Codex PR #1497 review, finding 1.
+    //
+    // Cost: O(PHP files × class-like defs in the workspace) augmentation
+    // entries. Bounded and acceptable in practice — typical PHP projects
+    // have hundreds of files and classes, not tens of thousands.
+    for (const parsed of parsedFiles) {
+        const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
+        if (moduleScope === undefined)
+            continue;
+        const moduleScopeId = moduleScope.id;
+        for (const [ns, bucket] of buckets) {
+            if (ns === '')
+                continue; // global-namespace classes have no qualified form to register
+            for (const def of bucket.classDefs) {
+                const q = def.qualifiedName ?? '';
+                const simpleName = q.includes('\\') ? q.slice(q.lastIndexOf('\\') + 1) : q;
+                if (simpleName === '')
+                    continue;
+                const fqn = `${ns}\\${simpleName}`;
+                const arr = getAugmentationBucket(augmentations, moduleScopeId, fqn);
+                if (arr.some((b) => b.def.nodeId === def.nodeId))
+                    continue;
+                arr.push({ def, origin: 'namespace' });
+            }
+        }
+    }
+    // Step 4: Mirror return-type bindings from same-namespace sibling files.
+    // This enables chain-follow like `$c->greet()->save()` where `greet()`
+    // returns `Greeting` (declared in A.php, same namespace) and `Greeting`
+    // isn't imported in the calling file. Without this, the compound-receiver
+    // resolver can't resolve `Greeting` as a class binding in the importer's
+    // scope chain.
+    //
+    // Additionally, mirror from files that are imported via `use` (different
+    // namespace) so return types from dependencies are chain-followable too.
+    for (const parsed of parsedFiles) {
+        const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
+        if (moduleScope === undefined)
+            continue;
+        const moduleTypeBindings = moduleScope.typeBindings;
+        const struct = structureByFile.get(parsed.filePath);
+        const ownNs = struct?.namespace ?? '';
+        // Collect namespaces accessible from this file:
+        // 1. Own namespace (same-ns siblings)
+        // 2. Namespaces of directly imported files (via parsedImports → targetRaw → PSR-4 namespace)
+        const accessibleFiles = new Set();
+        // Same-namespace siblings.
+        const sameBucket = buckets.get(ownNs);
+        if (sameBucket !== undefined) {
+            for (const { filePath } of sameBucket.scopes) {
+                if (filePath !== parsed.filePath)
+                    accessibleFiles.add(filePath);
+            }
+        }
+        // Files directly imported by this file (finalized import edges).
+        const ownModuleScopeBindings = indexes.bindings.get(moduleScope.id);
+        if (ownModuleScopeBindings !== undefined) {
+            for (const [, refs] of ownModuleScopeBindings) {
+                for (const ref of refs) {
+                    if (ref.origin === 'import' || ref.origin === 'namespace') {
+                        const importFilePath = ref.def.filePath;
+                        if (importFilePath !== parsed.filePath) {
+                            accessibleFiles.add(importFilePath);
+                        }
+                    }
+                }
+            }
+        }
+        // Mirror return-type bindings from accessible files.
+        for (const srcFilePath of accessibleFiles) {
+            const srcParsed = parsedFiles.find((p) => p.filePath === srcFilePath);
+            if (srcParsed === undefined)
+                continue;
+            const srcModuleScope = srcParsed.scopes.find((s) => s.kind === 'Module');
+            if (srcModuleScope === undefined)
+                continue;
+            for (const [boundName, typeRef] of srcModuleScope.typeBindings) {
+                if (moduleTypeBindings.has(boundName))
+                    continue;
+                moduleTypeBindings.set(boundName, typeRef);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * 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';
+export declare function getPhpParser(): Parser;
+export declare function getPhpScopeQuery(): Parser.Query;