arceus-s 1.6.4

package/dist/core/ingestion/languages/kotlin.js

@@ -0,0 +1,164 @@
+/**
+ * Kotlin language provider.
+ *
+ * Kotlin uses named imports with JVM wildcard/member resolution and
+ * Java-interop fallback. Default visibility is public (no modifier needed).
+ * Heritage uses EXTENDS by default with implements-split MRO for
+ * multiple interface implementation.
+ */
+import { SupportedLanguages } from '../../../_shared/index.js';
+import { createClassExtractor } from '../class-extractors/generic.js';
+import { kotlinClassConfig } from '../class-extractors/configs/jvm.js';
+import { defineLanguage } from '../language-provider.js';
+import { kotlinTypeConfig } from '../type-extractors/jvm.js';
+import { kotlinExportChecker } from '../export-detection.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { kotlinImportConfig } from '../import-resolvers/configs/jvm.js';
+import { extractKotlinNamedBindings } from '../named-bindings/kotlin.js';
+import { appendKotlinWildcard } from '../import-resolvers/jvm.js';
+import { KOTLIN_QUERIES } from '../tree-sitter-queries.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { kotlinCallConfig } from '../call-extractors/configs/jvm.js';
+import { createFieldExtractor } from '../field-extractors/generic.js';
+import { kotlinConfig } from '../field-extractors/configs/jvm.js';
+import { createMethodExtractor } from '../method-extractors/generic.js';
+import { kotlinMethodConfig } from '../method-extractors/configs/jvm.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { kotlinVariableConfig } from '../variable-extractors/configs/jvm.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+/** Check if a Kotlin function_declaration capture is inside a class_body (i.e., a method).
+ *  Kotlin grammar uses function_declaration for both top-level functions and class methods.
+ *  Returns true when the captured definition node has a class_body ancestor. */
+function isKotlinClassMethod(captureNode) {
+    let ancestor = captureNode?.parent;
+    while (ancestor) {
+        if (ancestor.type === 'class_body')
+            return true;
+        ancestor = ancestor.parent;
+    }
+    return false;
+}
+const BUILT_INS = new Set([
+    'println',
+    'print',
+    'readLine',
+    'require',
+    'requireNotNull',
+    'check',
+    'assert',
+    'lazy',
+    'error',
+    'listOf',
+    'mapOf',
+    'setOf',
+    'mutableListOf',
+    'mutableMapOf',
+    'mutableSetOf',
+    'arrayOf',
+    'sequenceOf',
+    'also',
+    'apply',
+    'run',
+    'with',
+    'takeIf',
+    'takeUnless',
+    'TODO',
+    'buildString',
+    'buildList',
+    'buildMap',
+    'buildSet',
+    'repeat',
+    'synchronized',
+    'launch',
+    'async',
+    'runBlocking',
+    'withContext',
+    'coroutineScope',
+    'supervisorScope',
+    'delay',
+    'flow',
+    'flowOf',
+    'collect',
+    'emit',
+    'onEach',
+    'catch',
+    'buffer',
+    'conflate',
+    'distinctUntilChanged',
+    'flatMapLatest',
+    'flatMapMerge',
+    'combine',
+    'stateIn',
+    'shareIn',
+    'launchIn',
+    'to',
+    'until',
+    'downTo',
+    'step',
+]);
+export const kotlinProvider = defineLanguage({
+    id: SupportedLanguages.Kotlin,
+    extensions: ['.kt', '.kts'],
+    entryPointPatterns: [
+        /^on(Create|Start|Resume|Pause|Stop|Destroy)$/,
+        /^do[A-Z]/,
+        /^create[A-Z]/,
+        /^build[A-Z]/,
+        /ViewModel$/,
+        /^module$/,
+        /Service$/,
+    ],
+    astFrameworkPatterns: [
+        {
+            framework: 'spring-kotlin',
+            entryPointMultiplier: 3.2,
+            reason: 'spring-kotlin-annotation',
+            patterns: [
+                '@RestController',
+                '@Controller',
+                '@GetMapping',
+                '@PostMapping',
+                '@RequestMapping',
+            ],
+        },
+        {
+            framework: 'jaxrs',
+            entryPointMultiplier: 3.0,
+            reason: 'jaxrs-annotation',
+            patterns: ['@Path', '@GET', '@POST', '@PUT', '@DELETE'],
+        },
+        {
+            framework: 'ktor',
+            entryPointMultiplier: 2.8,
+            reason: 'ktor-routing',
+            patterns: ['routing', 'embeddedServer', 'Application.module'],
+        },
+        {
+            framework: 'android-kotlin',
+            entryPointMultiplier: 2.5,
+            reason: 'android-annotation',
+            patterns: ['@AndroidEntryPoint', 'AppCompatActivity', 'Fragment('],
+        },
+    ],
+    treeSitterQueries: KOTLIN_QUERIES,
+    typeConfig: kotlinTypeConfig,
+    exportChecker: kotlinExportChecker,
+    importResolver: createImportResolver(kotlinImportConfig),
+    namedBindingExtractor: extractKotlinNamedBindings,
+    importPathPreprocessor: appendKotlinWildcard,
+    mroStrategy: 'implements-split',
+    callExtractor: createCallExtractor(kotlinCallConfig),
+    fieldExtractor: createFieldExtractor(kotlinConfig),
+    methodExtractor: createMethodExtractor(kotlinMethodConfig),
+    variableExtractor: createVariableExtractor(kotlinVariableConfig),
+    classExtractor: createClassExtractor(kotlinClassConfig),
+    heritageExtractor: createHeritageExtractor(SupportedLanguages.Kotlin),
+    builtInNames: BUILT_INS,
+    labelOverride: (functionNode, defaultLabel) => {
+        if (defaultLabel !== 'Function')
+            return defaultLabel;
+        if (isKotlinClassMethod(functionNode))
+            return 'Method';
+        return defaultLabel;
+    },
+});

package/dist/core/ingestion/languages/php/arity-metadata.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Extract PHP arity metadata from a method-like tree-sitter node —
+ * `method_declaration` or `function_definition`.
+ *
+ * Reuses `phpMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - `variadic_parameter` (`...$args`) collapses `parameterCount` to
+ *     `undefined`, which `phpArityCompatibility` then treats as
+ *     "max unknown" — the candidate stays eligible at `argCount >= required`.
+ *   - Defaulted parameters (`= expr`) contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount − (variadic ? 1 : 0)`.
+ *     The variadic slot itself accepts zero args so it is subtracted from
+ *     the required count — `f(int $a, ...$rest)` requires exactly 1 arg,
+ *     not 2, and `f(...$rest)` requires 0.
+ *   - `property_promotion_parameter` (constructor-promoted) is counted
+ *     the same as `simple_parameter` since both consume an argument slot.
+ *   - `parameterTypes` collects declared type names; a literal `'...'`
+ *     marker is appended for variadic methods so `phpArityCompatibility`
+ *     can detect them without re-reading the AST.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+interface PhpArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computePhpArityMetadata(fnNode: SyntaxNode): PhpArityMetadata;
+export {};

package/dist/core/ingestion/languages/php/arity-metadata.js

@@ -0,0 +1,63 @@
+/**
+ * Extract PHP arity metadata from a method-like tree-sitter node —
+ * `method_declaration` or `function_definition`.
+ *
+ * Reuses `phpMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - `variadic_parameter` (`...$args`) collapses `parameterCount` to
+ *     `undefined`, which `phpArityCompatibility` then treats as
+ *     "max unknown" — the candidate stays eligible at `argCount >= required`.
+ *   - Defaulted parameters (`= expr`) contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount − (variadic ? 1 : 0)`.
+ *     The variadic slot itself accepts zero args so it is subtracted from
+ *     the required count — `f(int $a, ...$rest)` requires exactly 1 arg,
+ *     not 2, and `f(...$rest)` requires 0.
+ *   - `property_promotion_parameter` (constructor-promoted) is counted
+ *     the same as `simple_parameter` since both consume an argument slot.
+ *   - `parameterTypes` collects declared type names; a literal `'...'`
+ *     marker is appended for variadic methods so `phpArityCompatibility`
+ *     can detect them without re-reading the AST.
+ */
+import { phpMethodConfig } from '../../method-extractors/configs/php.js';
+export function computePhpArityMetadata(fnNode) {
+    const params = phpMethodConfig.extractParameters?.(fnNode) ?? [];
+    let hasVariadic = false;
+    let optionalCount = 0;
+    const types = [];
+    for (const p of params) {
+        if (p.isVariadic) {
+            hasVariadic = true;
+        }
+        else if (p.isOptional) {
+            optionalCount++;
+        }
+        if (p.type !== null)
+            types.push(p.type);
+    }
+    // PHP variadic marker convention: append the literal '...' string to
+    // `parameterTypes`. This is intentionally DIFFERENT from C#, which uses
+    // the literal 'params' (its source-language keyword). The shared
+    // `narrowOverloadCandidates` pass in `scope-resolution/passes/overload-
+    // narrowing.ts` checks for the C# 'params' marker — that branch is
+    // dead code for PHP because PHP variadic methods set `parameterCount
+    // = undefined` (see line below), which skips the `max !== undefined`
+    // gate that hosts the 'params' check. PHP's actual variadic-aware
+    // arity logic lives in `phpArityCompatibility` (arity.ts) and now
+    // also in `phpEmitUnresolvedReceiverEdges` (scope-resolver.ts), both
+    // of which check `'...'`. Finding 9 of PR #1497 adversarial review.
+    if (hasVariadic)
+        types.push('...');
+    const total = params.length;
+    // Variadic methods accept any arg count ≥ required — leave `parameterCount`
+    // undefined so the registry treats max as unknown.
+    const parameterCount = hasVariadic ? undefined : total;
+    // The variadic slot itself accepts zero args; subtract it from the required
+    // count so PHP's ArgumentCountError-equivalent calls (too few args before
+    // the variadic) are correctly rejected by arity compatibility.
+    const requiredParameterCount = total - optionalCount - (hasVariadic ? 1 : 0);
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes: types.length > 0 ? types : undefined,
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * PHP arity check, accommodating variadic (`...$args`) and default parameters.
+ *
+ * The `def` metadata synthesized by `arity-metadata.ts`:
+ *   - `parameterCount`         — total formal parameters; `undefined` when
+ *                                the method has a variadic `...$param`.
+ *   - `requiredParameterCount` — min required (excludes defaulted params
+ *                                and the variadic itself).
+ *   - `parameterTypes`         — declared type strings; contains the
+ *                                literal `'...'` when the method is variadic.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `required <= argCount <= max`, OR the def has
+ *                        variadic (any `argCount >= required`).
+ *   - `'incompatible'` — argCount below required, or above max with no variadic.
+ *   - `'unknown'`      — metadata absent / incomplete; named-args can satisfy
+ *                        any arity so we return unknown when we detect them.
+ *
+ * PHP supports named arguments (PHP 8.0+): `save(force: true)`. Named-arg
+ * call sites cannot be arity-checked statically without parsing arg names,
+ * so we return `'unknown'` when the callsite carries named args (signalled
+ * by a negative `arity` value per the shared Callsite contract).
+ */
+import type { Callsite, SymbolDefinition } from '../../../../_shared/index.js';
+export declare function phpArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

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

@@ -0,0 +1,40 @@
+/**
+ * PHP arity check, accommodating variadic (`...$args`) and default parameters.
+ *
+ * The `def` metadata synthesized by `arity-metadata.ts`:
+ *   - `parameterCount`         — total formal parameters; `undefined` when
+ *                                the method has a variadic `...$param`.
+ *   - `requiredParameterCount` — min required (excludes defaulted params
+ *                                and the variadic itself).
+ *   - `parameterTypes`         — declared type strings; contains the
+ *                                literal `'...'` when the method is variadic.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `required <= argCount <= max`, OR the def has
+ *                        variadic (any `argCount >= required`).
+ *   - `'incompatible'` — argCount below required, or above max with no variadic.
+ *   - `'unknown'`      — metadata absent / incomplete; named-args can satisfy
+ *                        any arity so we return unknown when we detect them.
+ *
+ * PHP supports named arguments (PHP 8.0+): `save(force: true)`. Named-arg
+ * call sites cannot be arity-checked statically without parsing arg names,
+ * so we return `'unknown'` when the callsite carries named args (signalled
+ * by a negative `arity` value per the shared Callsite contract).
+ */
+export function phpArityCompatibility(def, callsite) {
+    const max = def.parameterCount;
+    const min = def.requiredParameterCount;
+    if (max === undefined && min === undefined)
+        return 'unknown';
+    const argCount = callsite.arity;
+    // Negative arity signals named-argument call sites — can't narrow statically.
+    if (!Number.isFinite(argCount) || argCount < 0)
+        return 'unknown';
+    const hasVarArgs = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === '...' || t.startsWith('...'));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVarArgs)
+        return 'incompatible';
+    return 'compatible';
+}

package/dist/core/ingestion/languages/php/cache-stats.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (PHP mirror of `languages/csharp/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function getPhpCaptureCacheStats(): {
+    hits: number;
+    misses: number;
+};
+export declare function resetPhpCaptureCacheStats(): void;

package/dist/core/ingestion/languages/php/cache-stats.js

@@ -0,0 +1,26 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (PHP mirror of `languages/csharp/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+const PROF = process.env.PROF_SCOPE_RESOLUTION === '1';
+let CACHE_HITS = 0;
+let CACHE_MISSES = 0;
+export function recordCacheHit() {
+    if (PROF)
+        CACHE_HITS++;
+}
+export function recordCacheMiss() {
+    if (PROF)
+        CACHE_MISSES++;
+}
+export function getPhpCaptureCacheStats() {
+    return { hits: CACHE_HITS, misses: CACHE_MISSES };
+}
+export function resetPhpCaptureCacheStats() {
+    CACHE_HITS = 0;
+    CACHE_MISSES = 0;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * `emitScopeCaptures` for PHP (RFC #909 Ring 3 LANG-php).
+ *
+ * Drives the PHP scope query against tree-sitter-php and groups raw
+ * matches into `CaptureMatch[]` for the central extractor. Layers two
+ * synthesized streams on top:
+ *
+ *   1. **Decomposed use declarations** — each `namespace_use_declaration`
+ *      is re-emitted with `@import.kind/source/name/alias` markers so
+ *      `interpretPhpImport` can recover the ParsedImport shape without
+ *      re-parsing raw text. Grouped uses fan out to one match per clause.
+ *
+ *   2. **Receiver-binding synthesis** — `$this` and `parent` type-bindings
+ *      are synthesized on every non-static method entry. PHP's grammar
+ *      does not express "implicit receiver of a non-static class method"
+ *      via a clean `.scm` pattern, so we walk up the AST in code.
+ *
+ *   3. **Arity metadata synthesis** — `@declaration.parameter-count` /
+ *      `@declaration.required-parameter-count` / `@declaration.parameter-types`
+ *      are synthesized on function-like declarations so the registry can
+ *      narrow overloads.
+ *
+ *   4. **PHPDoc synthesis** — @param and @return annotations in comment
+ *      nodes preceding method/function declarations are extracted and emitted
+ *      as `@type-binding.parameter` and `@type-binding.return` matches.
+ *
+ *   5. **Foreach loop synthesis** — `foreach ($users as $user)` emits
+ *      a `@type-binding.alias` match binding the loop variable to the
+ *      element type of the iterable (resolved from PHPDoc or scopeEnv).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitPhpScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];