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

package/dist/core/ingestion/languages/php/import-decomposer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Decompose a PHP `namespace_use_declaration` into one or more
+ * `CaptureMatch` objects carrying the synthesized markers
+ * `@import.kind` / `@import.source` / `@import.name` / `@import.alias`
+ * that `interpretPhpImport` consumes.
+ *
+ * PHP import forms handled:
+ *
+ *   use Foo\Bar;                      → namespace, localName=Bar
+ *   use Foo\Bar as Baz;               → alias, localName=Baz
+ *   use function Foo\bar;             → function, localName=bar
+ *   use const Foo\BAR;                → const, localName=BAR
+ *   use Foo\{A, B as C};              → grouped: one match per clause
+ *   use function Foo\{f, g as h};     → grouped function variants
+ *   use const Foo\{X, Y as Z};        → grouped const variants
+ *
+ * Unlike C#'s decomposer this is 1:N — each grouped use_declaration
+ * fans out to one CaptureMatch per inner clause.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+export type PhpImportKind = 'namespace' | 'alias' | 'function' | 'const';
+/**
+ * Decompose a `namespace_use_declaration` node into one `CaptureMatch`
+ * per logical import. Returns `[]` when the node is unrecognized or
+ * carries no resolvable clauses.
+ */
+export declare function splitNamespaceUseDeclaration(stmtNode: SyntaxNode): CaptureMatch[];

package/dist/core/ingestion/languages/php/import-decomposer.js

@@ -0,0 +1,265 @@
+/**
+ * Decompose a PHP `namespace_use_declaration` into one or more
+ * `CaptureMatch` objects carrying the synthesized markers
+ * `@import.kind` / `@import.source` / `@import.name` / `@import.alias`
+ * that `interpretPhpImport` consumes.
+ *
+ * PHP import forms handled:
+ *
+ *   use Foo\Bar;                      → namespace, localName=Bar
+ *   use Foo\Bar as Baz;               → alias, localName=Baz
+ *   use function Foo\bar;             → function, localName=bar
+ *   use const Foo\BAR;                → const, localName=BAR
+ *   use Foo\{A, B as C};              → grouped: one match per clause
+ *   use function Foo\{f, g as h};     → grouped function variants
+ *   use const Foo\{X, Y as Z};        → grouped const variants
+ *
+ * Unlike C#'s decomposer this is 1:N — each grouped use_declaration
+ * fans out to one CaptureMatch per inner clause.
+ */
+import { nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+/**
+ * Decompose a `namespace_use_declaration` node into one `CaptureMatch`
+ * per logical import. Returns `[]` when the node is unrecognized or
+ * carries no resolvable clauses.
+ */
+export function splitNamespaceUseDeclaration(stmtNode) {
+    if (stmtNode.type !== 'namespace_use_declaration')
+        return [];
+    // Detect qualifier keyword: `use function` / `use const`
+    // tree-sitter-php uses a `use_type` or `function`/`const` keyword
+    // child to distinguish them. We scan the raw text before the first
+    // backslash-path child.
+    const qualifier = detectQualifier(stmtNode);
+    // Grouped use: `use Foo\{A, B as C}` — find namespace_use_group child.
+    const groupNode = findNamedChild(stmtNode, 'namespace_use_group');
+    if (groupNode !== null) {
+        return decomposeGrouped(stmtNode, groupNode, qualifier);
+    }
+    // Single use clause (possibly aliased).
+    const spec = parseSingleUseClause(stmtNode, qualifier);
+    if (spec === null)
+        return [];
+    return [buildImportMatch(stmtNode, spec)];
+}
+// ── Qualifier detection ────────────────────────────────────────────────────
+/**
+ * Return the qualifier keyword appearing after `use`:
+ * `'function'`, `'const'`, or `null` for plain namespace use.
+ *
+ * tree-sitter-php emits the qualifier as a `name` node with text
+ * "function" or "const" (not a keyword token in recent grammars),
+ * or as a dedicated `use_type` node. We inspect the node's raw text
+ * to be grammar-version-agnostic.
+ */
+function detectQualifier(node) {
+    const raw = node.text;
+    // Match `use function` or `use const` at the start (after optional whitespace)
+    if (/^\s*use\s+function\s/i.test(raw))
+        return 'function';
+    if (/^\s*use\s+const\s/i.test(raw))
+        return 'const';
+    return 'namespace';
+}
+// ── Single clause parsing ──────────────────────────────────────────────────
+function parseSingleUseClause(node, qualifier) {
+    // A plain `namespace_use_declaration` has one or more
+    // `namespace_use_clause` named children (each clause is one import,
+    // comma-separated for multiple).  For the single case there is one.
+    const clause = findNamedChild(node, 'namespace_use_clause');
+    if (clause !== null)
+        return parseUseClause(clause, qualifier);
+    // Older grammar versions may put the qualified_name directly under
+    // the declaration node. Check for a qualified_name or name child.
+    const qualName = findNamedChild(node, 'qualified_name') ?? findNamedChild(node, 'name');
+    if (qualName === null)
+        return null;
+    const source = qualName.text.trim();
+    if (source === '')
+        return null;
+    return {
+        kind: qualifier,
+        source,
+        name: lastSegment(source),
+        atNode: node,
+    };
+}
+function parseUseClause(clause, qualifier) {
+    // namespace_use_clause:
+    //   qualified_name (or name)
+    //   optional: alias_clause → "as" name   (some grammar versions)
+    //   optional: bare name node             (tree-sitter-php ≥ 0.22 emits the
+    //                                         alias as a sibling `name` node
+    //                                         directly, not inside alias_clause)
+    const qualName = findNamedChild(clause, 'qualified_name') ?? findNamedChild(clause, 'name');
+    if (qualName === null)
+        return null;
+    const source = qualName.text.trim();
+    if (source === '')
+        return null;
+    // Strategy 1: explicit alias_clause wrapper (older grammar versions).
+    const aliasClause = findNamedChild(clause, 'alias_clause');
+    if (aliasClause !== null) {
+        // alias_clause: "as" name
+        const aliasName = findNamedChild(aliasClause, 'name') ?? aliasClause.firstNamedChild;
+        const alias = aliasName?.text.trim() ?? '';
+        if (alias === '')
+            return null;
+        return {
+            kind: 'alias',
+            source,
+            name: alias,
+            alias,
+            atNode: clause,
+        };
+    }
+    // Strategy 2: bare sibling `name` node after the qualified_name.
+    // tree-sitter-php (≥ 0.22) emits `use Foo\Bar as Baz` as:
+    //   namespace_use_clause
+    //     qualified_name "Foo\Bar"
+    //     name "Baz"          ← alias, no alias_clause wrapper
+    // Detect by: clause has ≥2 named children AND the last named child is
+    // a `name` node that differs from the qualName node.
+    if (clause.namedChildCount >= 2) {
+        const lastChild = clause.namedChild(clause.namedChildCount - 1);
+        if (lastChild !== null && lastChild !== qualName && lastChild.type === 'name') {
+            const alias = lastChild.text.trim();
+            if (alias !== '') {
+                return {
+                    kind: 'alias',
+                    source,
+                    name: alias,
+                    alias,
+                    atNode: clause,
+                };
+            }
+        }
+    }
+    return {
+        kind: qualifier,
+        source,
+        name: lastSegment(source),
+        atNode: clause,
+    };
+}
+// ── Grouped use decomposition ──────────────────────────────────────────────
+/**
+ * Decompose `use Foo\Bar\{A, B as C, function f, const X}` into one
+ * `CaptureMatch` per inner clause.
+ *
+ * The leading prefix (`Foo\Bar`) is prepended to each inner path.
+ * Inner clauses can override the qualifier with their own `function` /
+ * `const` keyword inside the group.
+ */
+function decomposeGrouped(stmtNode, groupNode, outerQualifier) {
+    // The prefix is the qualified_name that precedes the `{...}` group.
+    const prefixNode = findNamedChild(stmtNode, 'qualified_name') ?? findNamedChild(stmtNode, 'name');
+    const prefix = prefixNode?.text.trim() ?? '';
+    const out = [];
+    for (let i = 0; i < groupNode.namedChildCount; i++) {
+        const child = groupNode.namedChild(i);
+        if (child === null)
+            continue;
+        // Each child in a group may be:
+        //   namespace_use_clause  — plain or aliased
+        //   namespace_use_type    — `function` or `const` qualifier inside group
+        // We detect an inline qualifier by checking the raw text of the clause.
+        if (child.type !== 'namespace_use_clause')
+            continue;
+        const innerQualifier = detectInnerQualifier(child) ?? outerQualifier;
+        const spec = parseInnerClause(child, prefix, innerQualifier);
+        if (spec !== null) {
+            out.push(buildImportMatch(stmtNode, spec));
+        }
+    }
+    return out;
+}
+/**
+ * Detect an inline qualifier keyword inside a grouped clause.
+ * e.g. `use Foo\{function bar, const BAZ}` — each clause may start with
+ * `function` or `const`.
+ */
+function detectInnerQualifier(clause) {
+    const raw = clause.text.trim();
+    if (/^function\s/i.test(raw))
+        return 'function';
+    if (/^const\s/i.test(raw))
+        return 'const';
+    return null;
+}
+function parseInnerClause(clause, prefix, qualifier) {
+    const qualName = findNamedChild(clause, 'qualified_name') ?? findNamedChild(clause, 'name');
+    if (qualName === null)
+        return null;
+    // Strip inline `function` / `const` text prefix if present in the text.
+    let innerPath = qualName.text.trim();
+    innerPath = innerPath.replace(/^(?:function|const)\s+/i, '').trim();
+    if (innerPath === '')
+        return null;
+    const source = prefix !== '' ? `${prefix}\\${innerPath}` : innerPath;
+    // Strategy 1: explicit alias_clause wrapper (older grammar versions).
+    const aliasClause = findNamedChild(clause, 'alias_clause');
+    if (aliasClause !== null) {
+        const aliasName = findNamedChild(aliasClause, 'name') ?? aliasClause.firstNamedChild;
+        const alias = aliasName?.text.trim() ?? '';
+        if (alias === '')
+            return null;
+        return {
+            kind: 'alias',
+            source,
+            name: alias,
+            alias,
+            atNode: clause,
+        };
+    }
+    // Strategy 2: bare sibling `name` node after the qualified_name (tree-sitter-php ≥ 0.22).
+    if (clause.namedChildCount >= 2) {
+        const lastChild = clause.namedChild(clause.namedChildCount - 1);
+        if (lastChild !== null && lastChild !== qualName && lastChild.type === 'name') {
+            const alias = lastChild.text.trim();
+            if (alias !== '') {
+                return {
+                    kind: 'alias',
+                    source,
+                    name: alias,
+                    alias,
+                    atNode: clause,
+                };
+            }
+        }
+    }
+    return {
+        kind: qualifier,
+        source,
+        name: lastSegment(innerPath),
+        atNode: clause,
+    };
+}
+// ── CaptureMatch builder ───────────────────────────────────────────────────
+function buildImportMatch(stmtNode, spec) {
+    const m = {
+        '@import.statement': nodeToCapture('@import.statement', stmtNode),
+        '@import.kind': syntheticCapture('@import.kind', spec.atNode, spec.kind),
+        '@import.source': syntheticCapture('@import.source', spec.atNode, spec.source),
+        '@import.name': syntheticCapture('@import.name', spec.atNode, spec.name),
+    };
+    if (spec.alias !== undefined) {
+        m['@import.alias'] = syntheticCapture('@import.alias', spec.atNode, spec.alias);
+    }
+    return m;
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+/** Last backslash-separated segment: `Foo\Bar\Baz` → `Baz`. */
+function lastSegment(path) {
+    const parts = path.split('\\').filter(Boolean);
+    return parts[parts.length - 1] ?? path;
+}
+/** Find the first named child with a given node type. */
+function findNamedChild(node, type) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child !== null && child.type === type)
+            return child;
+    }
+    return null;
+}

package/dist/core/ingestion/languages/php/import-target.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Delegates to the existing `resolvePhpImportInternal` (PSR-4 via
+ * composer.json + suffix matching fallback). The `WorkspaceIndex` is
+ * opaque at this layer; consumers wire a `PhpResolveContext` shape
+ * carrying `fromFile` + `allFilePaths`.
+ *
+ * `loadPhpComposerConfig` is the `ScopeResolver.loadResolutionConfig`
+ * implementation — it loads `composer.json` once per workspace pass and
+ * threads the parsed config into every subsequent `resolveImportTarget`
+ * call via the opaque `resolutionConfig` parameter.
+ *
+ * Returning `null` lets the finalize algorithm mark the edge as
+ * `linkStatus: 'unresolved'`.
+ */
+import type { ParsedImport, WorkspaceIndex } from '../../../../_shared/index.js';
+import type { ComposerConfig } from '../../language-config.js';
+export interface PhpResolveContext {
+    readonly fromFile: string;
+    readonly allFilePaths: ReadonlySet<string>;
+}
+/**
+ * Load and parse `composer.json` from the repo root. Returns a
+ * `ComposerConfig` object (PSR-4 namespace → directory mappings) or
+ * `null` when no `composer.json` is present or it cannot be parsed.
+ *
+ * The result is threaded into each `resolvePhpImportInternal` call as
+ * the `composerConfig` argument.
+ */
+export declare function loadPhpComposerConfig(repoPath: string): ComposerConfig | null;
+/**
+ * LanguageProvider-shaped adapter: `(ParsedImport, WorkspaceIndex) → string | null`.
+ *
+ * The `WorkspaceIndex` is `unknown` in the shared contract. The scope-resolution
+ * orchestrator hands us a `PhpResolveContext`-shaped object; narrow structurally
+ * rather than via a cast chain so unexpected shapes return `null` cleanly.
+ */
+export declare function resolvePhpImportTarget(parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex): string | null;
+/**
+ * ScopeResolver-shaped adapter: `(targetRaw, fromFile, allFilePaths, resolutionConfig?) → string | null`.
+ *
+ * Used inside `scope-resolver.ts`. Accepts the optional `resolutionConfig`
+ * (a `ComposerConfig | null` loaded once per workspace by
+ * `loadPhpComposerConfig`) and threads it into `resolvePhpImportInternal`.
+ */
+export declare function resolvePhpImportTargetInternal(targetRaw: string, _fromFile: string, allFilePaths: ReadonlySet<string>, resolutionConfig?: unknown): string | null;

package/dist/core/ingestion/languages/php/import-target.js

@@ -0,0 +1,100 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Delegates to the existing `resolvePhpImportInternal` (PSR-4 via
+ * composer.json + suffix matching fallback). The `WorkspaceIndex` is
+ * opaque at this layer; consumers wire a `PhpResolveContext` shape
+ * carrying `fromFile` + `allFilePaths`.
+ *
+ * `loadPhpComposerConfig` is the `ScopeResolver.loadResolutionConfig`
+ * implementation — it loads `composer.json` once per workspace pass and
+ * threads the parsed config into every subsequent `resolveImportTarget`
+ * call via the opaque `resolutionConfig` parameter.
+ *
+ * Returning `null` lets the finalize algorithm mark the edge as
+ * `linkStatus: 'unresolved'`.
+ */
+import { resolvePhpImportInternal } from '../../import-resolvers/php.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// ─── loadResolutionConfig ──────────────────────────────────────────────────
+/**
+ * Load and parse `composer.json` from the repo root. Returns a
+ * `ComposerConfig` object (PSR-4 namespace → directory mappings) or
+ * `null` when no `composer.json` is present or it cannot be parsed.
+ *
+ * The result is threaded into each `resolvePhpImportInternal` call as
+ * the `composerConfig` argument.
+ */
+export function loadPhpComposerConfig(repoPath) {
+    try {
+        const composerPath = join(repoPath, 'composer.json');
+        const raw = readFileSync(composerPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const composer = parsed;
+        const autoload = composer['autoload'];
+        if (autoload === undefined)
+            return null;
+        const psr4Raw = (autoload['psr-4'] ?? {});
+        const psr4 = new Map();
+        for (const [ns, dirs] of Object.entries(psr4Raw)) {
+            // namespace prefix ends with `\` — keep as-is; resolver strips it
+            const normalizedNs = ns.replace(/\\$/, '');
+            const dir = Array.isArray(dirs) ? dirs[0] : dirs;
+            if (typeof dir === 'string') {
+                // Normalize directory path (strip trailing slash)
+                const normalizedDir = dir.replace(/\/+$/, '');
+                psr4.set(normalizedNs, normalizedDir);
+            }
+        }
+        return { psr4 };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── resolvePhpImportTarget ────────────────────────────────────────────────
+/**
+ * LanguageProvider-shaped adapter: `(ParsedImport, WorkspaceIndex) → string | null`.
+ *
+ * The `WorkspaceIndex` is `unknown` in the shared contract. The scope-resolution
+ * orchestrator hands us a `PhpResolveContext`-shaped object; narrow structurally
+ * rather than via a cast chain so unexpected shapes return `null` cleanly.
+ */
+export function resolvePhpImportTarget(parsedImport, workspaceIndex) {
+    const ctx = workspaceIndex;
+    if (ctx === undefined ||
+        typeof ctx.fromFile !== 'string' ||
+        !(ctx.allFilePaths instanceof Set)) {
+        return null;
+    }
+    if (parsedImport.kind === 'dynamic-unresolved')
+        return null;
+    if (parsedImport.targetRaw === null || parsedImport.targetRaw === '')
+        return null;
+    const allFiles = ctx.allFilePaths;
+    const normalizedFileList = [...allFiles].map((f) => f.replace(/\\/g, '/'));
+    const allFileList = [...allFiles];
+    return resolvePhpImportInternal(parsedImport.targetRaw, null, // composerConfig not available through LanguageProvider path
+    allFiles, normalizedFileList, allFileList, undefined);
+}
+/**
+ * ScopeResolver-shaped adapter: `(targetRaw, fromFile, allFilePaths, resolutionConfig?) → string | null`.
+ *
+ * Used inside `scope-resolver.ts`. Accepts the optional `resolutionConfig`
+ * (a `ComposerConfig | null` loaded once per workspace by
+ * `loadPhpComposerConfig`) and threads it into `resolvePhpImportInternal`.
+ */
+export function resolvePhpImportTargetInternal(targetRaw, _fromFile, allFilePaths, resolutionConfig) {
+    if (targetRaw === '')
+        return null;
+    const composerConfig = resolutionConfig !== undefined && resolutionConfig !== null
+        ? resolutionConfig
+        : null;
+    const allFiles = allFilePaths;
+    const normalizedFileList = [...allFiles].map((f) => f.replace(/\\/g, '/'));
+    const allFileList = [...allFiles];
+    return resolvePhpImportInternal(targetRaw, composerConfig, allFiles, normalizedFileList, allFileList, undefined);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * PHP scope-resolution hooks (RFC #909 Ring 3 LANG-php, #938).
+ *
+ * Public API barrel. Consumers should import from this file rather than
+ * the individual modules.
+ *
+ * Module layout (each file is a single concern):
+ *
+ *   - `query.ts`               — tree-sitter query + lazy parser/query singletons
+ *   - `captures.ts`            — `emitPhpScopeCaptures` orchestrator
+ *   - `import-decomposer.ts`   — each `namespace_use_declaration` → ParsedImport captures
+ *   - `interpret.ts`           — capture-match → `ParsedImport` / `ParsedTypeBinding`
+ *   - `simple-hooks.ts`        — small/no-op hooks made explicit
+ *   - `receiver-binding.ts`    — synthesize `$this` / `parent` type-bindings on
+ *                                instance-method entry
+ *   - `merge-bindings.ts`      — PHP `use` precedence (local > import > wildcard)
+ *   - `arity.ts`               — PHP arity compatibility (variadic, defaults)
+ *   - `arity-metadata.ts`      — synthesize arity metadata from declarations
+ *   - `import-target.ts`       — `(ParsedImport, WorkspaceIndex) → file path` adapter
+ *                                wrapping `resolvePhpImportInternal` (PSR-4 + composer.json)
+ *   - `scope-resolver.ts`      — `ScopeResolver` registered in `SCOPE_RESOLVERS`
+ *   - `cache-stats.ts`         — PROF_SCOPE_RESOLUTION cache hit/miss counters
+ *
+ * ## Known limitations
+ *
+ * The PHP registry-primary path intentionally does NOT resolve the following.
+ * Each is a conscious trade-off at migration time.
+ *
+ *   1. **Trait `$this` → using-class binding** — for methods defined in a
+ *      trait, `$this` is synthesized as a binding to the trait itself.
+ *      Resolving `$this` to the actual using-class type requires cross-file
+ *      analysis of all `use TraitName;` declarations in class bodies.
+ *      Deferred to a follow-up; trait method resolution falls back to the
+ *      trait scope.
+ *
+ *   2. **Anonymous classes** — `new class extends Foo { }` have no stable
+ *      class name and are skipped by receiver-binding synthesis. The class
+ *      body is still scoped; member lookups inside it will fall back to
+ *      free-call resolution.
+ *
+ *   3. **Dynamic property/method access** — `$obj->{$name}()` and
+ *      `$$varName` are not followed. The dynamic receiver is ignored and
+ *      the call falls through to the shared free-call resolver.
+ *
+ *   4. **Magic methods** — `__get`, `__set`, `__call`, `__callStatic` are
+ *      not modeled as virtual dispatch; they appear as regular method
+ *      declarations in the graph but calls that would route through them
+ *      at runtime are not distinguished.
+ *
+ *   5. **Laravel facade magic** — `App::make(...)`, `Cache::get(...)` etc.
+ *      resolve statically to the Facade class rather than the underlying
+ *      bound implementation. Deferred to a Laravel-specific plugin.
+ *
+ *   6. **Intersection types in parameters** — `T&U $param` takes the first
+ *      named part (`T`). This matches the legacy type-extractor's behavior.
+ *
+ * Shadow-harness corpus parity is the authoritative signal for which of
+ * these matter in practice. The CI parity gate blocks any PR that regresses
+ * either the legacy or registry-primary run of
+ * `test/integration/resolvers/php.test.ts`.
+ */
+export { emitPhpScopeCaptures } from './captures.js';
+export { getPhpCaptureCacheStats, resetPhpCaptureCacheStats } from './cache-stats.js';
+export { interpretPhpImport, interpretPhpTypeBinding } from './interpret.js';
+export { phpMergeBindings } from './merge-bindings.js';
+export { phpArityCompatibility } from './arity.js';
+export { resolvePhpImportTarget, type PhpResolveContext } from './import-target.js';
+export { phpBindingScopeFor, phpImportOwningScope, phpReceiverBinding } from './simple-hooks.js';

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

@@ -0,0 +1,72 @@
+/**
+ * PHP scope-resolution hooks (RFC #909 Ring 3 LANG-php, #938).
+ *
+ * Public API barrel. Consumers should import from this file rather than
+ * the individual modules.
+ *
+ * Module layout (each file is a single concern):
+ *
+ *   - `query.ts`               — tree-sitter query + lazy parser/query singletons
+ *   - `captures.ts`            — `emitPhpScopeCaptures` orchestrator
+ *   - `import-decomposer.ts`   — each `namespace_use_declaration` → ParsedImport captures
+ *   - `interpret.ts`           — capture-match → `ParsedImport` / `ParsedTypeBinding`
+ *   - `simple-hooks.ts`        — small/no-op hooks made explicit
+ *   - `receiver-binding.ts`    — synthesize `$this` / `parent` type-bindings on
+ *                                instance-method entry
+ *   - `merge-bindings.ts`      — PHP `use` precedence (local > import > wildcard)
+ *   - `arity.ts`               — PHP arity compatibility (variadic, defaults)
+ *   - `arity-metadata.ts`      — synthesize arity metadata from declarations
+ *   - `import-target.ts`       — `(ParsedImport, WorkspaceIndex) → file path` adapter
+ *                                wrapping `resolvePhpImportInternal` (PSR-4 + composer.json)
+ *   - `scope-resolver.ts`      — `ScopeResolver` registered in `SCOPE_RESOLVERS`
+ *   - `cache-stats.ts`         — PROF_SCOPE_RESOLUTION cache hit/miss counters
+ *
+ * ## Known limitations
+ *
+ * The PHP registry-primary path intentionally does NOT resolve the following.
+ * Each is a conscious trade-off at migration time.
+ *
+ *   1. **Trait `$this` → using-class binding** — for methods defined in a
+ *      trait, `$this` is synthesized as a binding to the trait itself.
+ *      Resolving `$this` to the actual using-class type requires cross-file
+ *      analysis of all `use TraitName;` declarations in class bodies.
+ *      Deferred to a follow-up; trait method resolution falls back to the
+ *      trait scope.
+ *
+ *   2. **Anonymous classes** — `new class extends Foo { }` have no stable
+ *      class name and are skipped by receiver-binding synthesis. The class
+ *      body is still scoped; member lookups inside it will fall back to
+ *      free-call resolution.
+ *
+ *   3. **Dynamic property/method access** — `$obj->{$name}()` and
+ *      `$$varName` are not followed. The dynamic receiver is ignored and
+ *      the call falls through to the shared free-call resolver.
+ *
+ *   4. **Magic methods** — `__get`, `__set`, `__call`, `__callStatic` are
+ *      not modeled as virtual dispatch; they appear as regular method
+ *      declarations in the graph but calls that would route through them
+ *      at runtime are not distinguished.
+ *
+ *   5. **Laravel facade magic** — `App::make(...)`, `Cache::get(...)` etc.
+ *      resolve statically to the Facade class rather than the underlying
+ *      bound implementation. Deferred to a Laravel-specific plugin.
+ *
+ *   6. **Intersection types in parameters** — `T&U $param` takes the first
+ *      named part (`T`). This matches the legacy type-extractor's behavior.
+ *
+ * Shadow-harness corpus parity is the authoritative signal for which of
+ * these matter in practice. The CI parity gate blocks any PR that regresses
+ * either the legacy or registry-primary run of
+ * `test/integration/resolvers/php.test.ts`.
+ */
+export { emitPhpScopeCaptures } from './captures.js';
+export { getPhpCaptureCacheStats, resetPhpCaptureCacheStats } from './cache-stats.js';
+export { interpretPhpImport, interpretPhpTypeBinding } from './interpret.js';
+export { phpMergeBindings } from './merge-bindings.js';
+export { phpArityCompatibility } from './arity.js';
+export { resolvePhpImportTarget } from './import-target.js';
+export { phpBindingScopeFor, phpImportOwningScope, phpReceiverBinding } from './simple-hooks.js';
+// NOTE: phpScopeResolver is intentionally NOT re-exported from this barrel.
+// Importing it here would create a circular dependency:
+//   php.ts → php/index.js → php/scope-resolver.js → ../php.js
+// Registry and other consumers must import directly from './php/scope-resolver.js'.

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

@@ -0,0 +1,36 @@
+/**
+ * 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`.
+ */
+import type { CaptureMatch, ParsedImport, ParsedTypeBinding } from '../../../../_shared/index.js';
+export declare function interpretPhpImport(captures: CaptureMatch): ParsedImport | null;
+export declare function interpretPhpTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null;
+/**
+ * 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 declare function normalizePhpType(raw: string): string | null;