arceus-s 1.6.4

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

@@ -0,0 +1,290 @@
+/**
+ * PHP language provider.
+ *
+ * PHP uses named imports (use statements for classes/functions/constants),
+ * and standard export/import resolution. PHP files can use a variety of
+ * extensions from legacy versions through modern PHP 8.
+ */
+import { emitPhpScopeCaptures, interpretPhpImport, interpretPhpTypeBinding, phpArityCompatibility, phpMergeBindings, resolvePhpImportTarget, phpBindingScopeFor, phpImportOwningScope, phpReceiverBinding, } from './php/index.js';
+import { SupportedLanguages } from '../../../_shared/index.js';
+import { createClassExtractor } from '../class-extractors/generic.js';
+import { phpClassConfig } from '../class-extractors/configs/php.js';
+import { defineLanguage } from '../language-provider.js';
+import { typeConfig as phpConfig } from '../type-extractors/php.js';
+import { phpExportChecker } from '../export-detection.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { phpImportConfig } from '../import-resolvers/configs/php.js';
+import { extractPhpNamedBindings } from '../named-bindings/php.js';
+import { PHP_QUERIES } from '../tree-sitter-queries.js';
+import { findDescendant, extractStringContent } from '../utils/ast-helpers.js';
+import { createFieldExtractor } from '../field-extractors/generic.js';
+import { phpConfig as phpFieldConfig } from '../field-extractors/configs/php.js';
+import { createMethodExtractor } from '../method-extractors/generic.js';
+import { phpMethodConfig } from '../method-extractors/configs/php.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { phpVariableConfig } from '../variable-extractors/configs/php.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { phpCallConfig } from '../call-extractors/configs/php.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+const BUILT_INS = new Set([
+    'echo',
+    'isset',
+    'empty',
+    'unset',
+    'list',
+    'array',
+    'compact',
+    'extract',
+    'count',
+    'strlen',
+    'strpos',
+    'strrpos',
+    'substr',
+    'strtolower',
+    'strtoupper',
+    'trim',
+    'ltrim',
+    'rtrim',
+    'str_replace',
+    'str_contains',
+    'str_starts_with',
+    'str_ends_with',
+    'sprintf',
+    'vsprintf',
+    'printf',
+    'number_format',
+    'array_map',
+    'array_filter',
+    'array_reduce',
+    'array_push',
+    'array_pop',
+    'array_shift',
+    'array_unshift',
+    'array_slice',
+    'array_splice',
+    'array_merge',
+    'array_keys',
+    'array_values',
+    'array_key_exists',
+    'in_array',
+    'array_search',
+    'array_unique',
+    'usort',
+    'rsort',
+    'json_encode',
+    'json_decode',
+    'serialize',
+    'unserialize',
+    'intval',
+    'floatval',
+    'strval',
+    'boolval',
+    'is_null',
+    'is_string',
+    'is_int',
+    'is_array',
+    'is_object',
+    'is_numeric',
+    'is_bool',
+    'is_float',
+    'var_dump',
+    'print_r',
+    'var_export',
+    'date',
+    'time',
+    'strtotime',
+    'mktime',
+    'microtime',
+    'file_exists',
+    'file_get_contents',
+    'file_put_contents',
+    'is_file',
+    'is_dir',
+    'preg_match',
+    'preg_match_all',
+    'preg_replace',
+    'preg_split',
+    'header',
+    'session_start',
+    'session_destroy',
+    'ob_start',
+    'ob_end_clean',
+    'ob_get_clean',
+    'dd',
+    'dump',
+]);
+/** Eloquent model properties whose array values are worth indexing. */
+const ELOQUENT_ARRAY_PROPS = new Set(['fillable', 'casts', 'hidden', 'guarded', 'with', 'appends']);
+/** Eloquent relationship method names. */
+const ELOQUENT_RELATIONS = new Set([
+    'hasMany',
+    'hasOne',
+    'belongsTo',
+    'belongsToMany',
+    'morphTo',
+    'morphMany',
+    'morphOne',
+    'morphToMany',
+    'morphedByMany',
+    'hasManyThrough',
+    'hasOneThrough',
+]);
+/**
+ * For a PHP property_declaration node, extract array values as a description string.
+ * Returns null if not an Eloquent model property or no array values found.
+ */
+function extractPhpPropertyDescription(propName, propDeclNode) {
+    if (!ELOQUENT_ARRAY_PROPS.has(propName))
+        return null;
+    const arrayNode = findDescendant(propDeclNode, 'array_creation_expression');
+    if (!arrayNode)
+        return null;
+    const items = [];
+    for (const child of arrayNode.children ?? []) {
+        if (child.type !== 'array_element_initializer')
+            continue;
+        const children = child.children ?? [];
+        const arrowIdx = children.findIndex((c) => c.type === '=>');
+        if (arrowIdx !== -1) {
+            const key = extractStringContent(children[arrowIdx - 1]);
+            const val = extractStringContent(children[arrowIdx + 1]);
+            if (key && val)
+                items.push(`${key}:${val}`);
+        }
+        else {
+            const val = extractStringContent(children[0]);
+            if (val)
+                items.push(val);
+        }
+    }
+    return items.length > 0 ? items.join(', ') : null;
+}
+/**
+ * For a PHP method_declaration node, detect if it defines an Eloquent relationship.
+ * Returns description like "hasMany(Post)" or null.
+ */
+function extractEloquentRelationDescription(methodNode) {
+    function findRelationCall(root) {
+        const stack = [root];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (node.type === 'member_call_expression') {
+                const children = node.children ?? [];
+                const objectNode = children.find((c) => c.type === 'variable_name' && c.text === '$this');
+                const nameNode = children.find((c) => c.type === 'name');
+                if (objectNode && nameNode && ELOQUENT_RELATIONS.has(nameNode.text))
+                    return node;
+            }
+            const children = node.children ?? [];
+            for (let i = children.length - 1; i >= 0; i--) {
+                stack.push(children[i]);
+            }
+        }
+        return null;
+    }
+    const callNode = findRelationCall(methodNode);
+    if (!callNode)
+        return null;
+    const relType = callNode.children?.find((c) => c.type === 'name')?.text;
+    const argsNode = callNode.children?.find((c) => c.type === 'arguments');
+    let targetModel = null;
+    if (argsNode) {
+        const firstArg = argsNode.children?.find((c) => c.type === 'argument');
+        if (firstArg) {
+            const classConstant = firstArg.children?.find((c) => c.type === 'class_constant_access_expression');
+            if (classConstant) {
+                targetModel =
+                    classConstant.children?.find((c) => c.type === 'name')?.text ?? null;
+            }
+        }
+    }
+    if (relType && targetModel)
+        return `${relType}(${targetModel})`;
+    if (relType)
+        return relType;
+    return null;
+}
+/**
+ * LanguageProvider.descriptionExtractor implementation for PHP.
+ * Extracts Eloquent model property metadata and relationship descriptions.
+ */
+function phpDescriptionExtractor(nodeLabel, nodeName, captureMap) {
+    if (nodeLabel === 'Property' && captureMap['definition.property']) {
+        return extractPhpPropertyDescription(nodeName, captureMap['definition.property']) ?? undefined;
+    }
+    if (nodeLabel === 'Method' && captureMap['definition.method']) {
+        return extractEloquentRelationDescription(captureMap['definition.method']) ?? undefined;
+    }
+    return undefined;
+}
+/** Detect Laravel route files by path convention. */
+function isPhpRouteFile(filePath) {
+    return (filePath.endsWith('.php') && (filePath.includes('/routes/') || filePath.startsWith('routes/')));
+}
+export const phpProvider = defineLanguage({
+    id: SupportedLanguages.PHP,
+    extensions: ['.php', '.phtml', '.php3', '.php4', '.php5', '.php8'],
+    entryPointPatterns: [
+        /Controller$/,
+        /^handle$/,
+        /^execute$/,
+        /^boot$/,
+        /^register$/,
+        /^__invoke$/,
+        /^(index|show|store|update|destroy|create|edit)$/,
+        /^(get|post|put|delete|patch)[A-Z]/,
+        /^run$/,
+        /^fire$/,
+        /^dispatch$/,
+        /Service$/,
+        /Repository$/,
+        /^find$/,
+        /^findAll$/,
+        /^save$/,
+        /^delete$/,
+    ],
+    astFrameworkPatterns: [
+        {
+            framework: 'laravel',
+            entryPointMultiplier: 3.0,
+            reason: 'php-route-attribute',
+            patterns: [
+                'Route::get',
+                'Route::post',
+                'Route::put',
+                'Route::delete',
+                'Route::resource',
+                'Route::apiResource',
+                '#[Route(',
+            ],
+        },
+    ],
+    treeSitterQueries: PHP_QUERIES,
+    typeConfig: phpConfig,
+    exportChecker: phpExportChecker,
+    importResolver: createImportResolver(phpImportConfig),
+    namedBindingExtractor: extractPhpNamedBindings,
+    callExtractor: createCallExtractor(phpCallConfig),
+    fieldExtractor: createFieldExtractor(phpFieldConfig),
+    methodExtractor: createMethodExtractor(phpMethodConfig),
+    variableExtractor: createVariableExtractor(phpVariableConfig),
+    classExtractor: createClassExtractor(phpClassConfig),
+    heritageExtractor: createHeritageExtractor(SupportedLanguages.PHP),
+    descriptionExtractor: phpDescriptionExtractor,
+    isRouteFile: isPhpRouteFile,
+    builtInNames: BUILT_INS,
+    // ── RFC #909 Ring 3: scope-based resolution hooks ──────────────────────
+    emitScopeCaptures: emitPhpScopeCaptures,
+    interpretImport: interpretPhpImport,
+    interpretTypeBinding: interpretPhpTypeBinding,
+    // LanguageProvider uses (def, callsite); phpArityCompatibility uses (def, callsite) — same.
+    arityCompatibility: phpArityCompatibility,
+    // LanguageProvider adapter: (parsedImport, workspaceIndex) → string | null
+    resolveImportTarget: resolvePhpImportTarget,
+    // mergeBindings on LanguageProvider: (scope, bindings) — ignore scope id,
+    // delegate to phpMergeBindings which uses binding origin tiers.
+    mergeBindings: (_scope, bindings) => [...phpMergeBindings(bindings)],
+    bindingScopeFor: phpBindingScopeFor,
+    importOwningScope: phpImportOwningScope,
+    receiverBinding: phpReceiverBinding,
+});

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

@@ -0,0 +1,24 @@
+/**
+ * Extract Python arity metadata from a `function_definition` tree-sitter
+ * node — parameter count, required count, and (where present) a type
+ * list that the existing `pythonArityCompatibility` hook reads.
+ *
+ * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
+ * defs carry the same arity semantics as the parse-worker path:
+ *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - Defaulted params contribute to `optionalCount`, flipping
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
+ *     `undefined`, which `pythonArityCompatibility` then treats as
+ *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - `parameterTypes` is populated only with real type text, matching
+ *     legacy behavior.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+interface PythonArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computePythonArityMetadata(fnNode: SyntaxNode): PythonArityMetadata;
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * Extract Python arity metadata from a `function_definition` tree-sitter
+ * node — parameter count, required count, and (where present) a type
+ * list that the existing `pythonArityCompatibility` hook reads.
+ *
+ * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
+ * defs carry the same arity semantics as the parse-worker path:
+ *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - Defaulted params contribute to `optionalCount`, flipping
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
+ *     `undefined`, which `pythonArityCompatibility` then treats as
+ *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - `parameterTypes` is populated only with real type text, matching
+ *     legacy behavior.
+ */
+import { pythonMethodConfig } from '../../method-extractors/configs/python.js';
+export function computePythonArityMetadata(fnNode) {
+    const params = pythonMethodConfig.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);
+    }
+    const total = params.length;
+    const parameterCount = hasVariadic ? undefined : total;
+    // Unlike legacy `buildMethodProps`, we populate `requiredParameterCount`
+    // whenever the function isn't variadic — even when it equals
+    // `parameterCount`. The scope-resolution registry needs a concrete min
+    // to rule out under-application (e.g. picking `write_audit(x, y)` for
+    // a 1-arg call). Legacy could get away with leaving it undefined
+    // because its call-graph builder had a separate arity pre-filter.
+    const requiredParameterCount = hasVariadic ? undefined : total - optionalCount;
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes: types.length > 0 ? types : undefined,
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Python arity check, accommodating `*args`, `**kwargs`, and defaults.
+ *
+ * The `def` metadata we care about (set by the existing Python method/
+ * function extractor):
+ *   - `parameterCount`         — total positional + keyword params
+ *   - `requiredParameterCount` — min required (excludes defaults / `*args` / `**kwargs`)
+ *   - `parameterTypes`         — present when types are known; we also use it
+ *                                as a "we have varargs" hint (`'*args'`,
+ *                                `'**kwargs'` literals appear in the array).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `*args` (then any `argCount >= required` ok).
+ *   - `'incompatible'` — argCount is below required, OR above max with no `*args`.
+ *   - `'unknown'`      — def metadata is absent / incomplete.
+ *
+ * `'incompatible'` is a soft signal in `Registry.lookup` (penalized but
+ * still considered when no compatible candidate exists), per RFC §4.
+ */
+import type { Callsite, SymbolDefinition } from '../../../../_shared/index.js';
+export declare function pythonArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

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

@@ -0,0 +1,38 @@
+/**
+ * Python arity check, accommodating `*args`, `**kwargs`, and defaults.
+ *
+ * The `def` metadata we care about (set by the existing Python method/
+ * function extractor):
+ *   - `parameterCount`         — total positional + keyword params
+ *   - `requiredParameterCount` — min required (excludes defaults / `*args` / `**kwargs`)
+ *   - `parameterTypes`         — present when types are known; we also use it
+ *                                as a "we have varargs" hint (`'*args'`,
+ *                                `'**kwargs'` literals appear in the array).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `*args` (then any `argCount >= required` ok).
+ *   - `'incompatible'` — argCount is below required, OR above max with no `*args`.
+ *   - `'unknown'`      — def metadata is absent / incomplete.
+ *
+ * `'incompatible'` is a soft signal in `Registry.lookup` (penalized but
+ * still considered when no compatible candidate exists), per RFC §4.
+ */
+export function pythonArityCompatibility(def, callsite) {
+    const max = def.parameterCount;
+    const min = def.requiredParameterCount;
+    if (max === undefined && min === undefined)
+        return 'unknown';
+    const argCount = callsite.arity;
+    if (!Number.isFinite(argCount) || argCount < 0)
+        return 'unknown';
+    // Detect varargs/kwargs from parameterTypes if present (the Python
+    // method extractor stores `'*args'`/`'**kwargs'` in this list).
+    const hasVarArgs = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === '*args' || t === '**kwargs' || t.startsWith('*'));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVarArgs)
+        return 'incompatible';
+    return 'compatible';
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache.
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. In production the module-level
+ * `PROF` constant is `false` and V8 folds every increment site into
+ * dead code, so the hot path in `captures.ts` stays branch-free.
+ *
+ * Extracted from `captures.ts` so the production hot-path module
+ * doesn't carry a module-global counter and its reset/export surface.
+ */
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function getPythonCaptureCacheStats(): {
+    hits: number;
+    misses: number;
+};
+export declare function resetPythonCaptureCacheStats(): void;

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

@@ -0,0 +1,28 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache.
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. In production the module-level
+ * `PROF` constant is `false` and V8 folds every increment site into
+ * dead code, so the hot path in `captures.ts` stays branch-free.
+ *
+ * Extracted from `captures.ts` so the production hot-path module
+ * doesn't carry a module-global counter and its reset/export surface.
+ */
+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 getPythonCaptureCacheStats() {
+    return { hits: CACHE_HITS, misses: CACHE_MISSES };
+}
+export function resetPythonCaptureCacheStats() {
+    CACHE_HITS = 0;
+    CACHE_MISSES = 0;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * `emitScopeCaptures` for Python.
+ *
+ * Drives the scope query against `tree-sitter-python` and groups raw
+ * matches into `CaptureMatch[]` for the central extractor, then layers
+ * two synthesized streams on top:
+ *
+ *   1. **Per-name import statements** — `import a, b` and
+ *      `from m import x, y` decompose to one match per imported name
+ *      (see `import-decomposer.ts`).
+ *   2. **Receiver type bindings** — each `function_definition` inside a
+ *      class body emits a `@type-binding.self` (or `@type-binding.cls`
+ *      for `@classmethod`) capture so Pass-4 attaches the implicit
+ *      receiver (see `receiver-binding.ts`).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitPythonScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];

package/dist/core/ingestion/languages/python/captures.js

@@ -0,0 +1,130 @@
+/**
+ * `emitScopeCaptures` for Python.
+ *
+ * Drives the scope query against `tree-sitter-python` and groups raw
+ * matches into `CaptureMatch[]` for the central extractor, then layers
+ * two synthesized streams on top:
+ *
+ *   1. **Per-name import statements** — `import a, b` and
+ *      `from m import x, y` decompose to one match per imported name
+ *      (see `import-decomposer.ts`).
+ *   2. **Receiver type bindings** — each `function_definition` inside a
+ *      class body emits a `@type-binding.self` (or `@type-binding.cls`
+ *      for `@classmethod`) capture so Pass-4 attaches the implicit
+ *      receiver (see `receiver-binding.ts`).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import { findNodeAtRange, nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+import { splitImportStatement } from './import-decomposer.js';
+import { getPythonParser, getPythonScopeQuery } from './query.js';
+import { synthesizeReceiverTypeBinding } from './receiver-binding.js';
+import { computePythonArityMetadata } from './arity-metadata.js';
+import { recordCacheHit, recordCacheMiss } from './cache-stats.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
+import { pythonFunctionDefinitionLabel } from './simple-hooks.js';
+export function emitPythonScopeCaptures(sourceText, _filePath, cachedTree) {
+    // Skip the parse when the caller (parse phase's ASTCache) already
+    // produced a Tree for this source. Cache miss = re-parse, same as
+    // before. The cachedTree parameter is typed as `unknown` at the
+    // contract layer (see `LanguageProvider.emitScopeCaptures`); cast
+    // here at the use site.
+    let tree = cachedTree;
+    if (tree === undefined) {
+        try {
+            tree = parseSourceSafe(getPythonParser(), sourceText, undefined, {
+                bufferSize: getTreeSitterBufferSize(sourceText),
+            });
+        }
+        catch (err) {
+            throw scopeExtractionError('parse', _filePath, err);
+        }
+        recordCacheMiss();
+    }
+    else {
+        recordCacheHit();
+    }
+    let rawMatches;
+    try {
+        rawMatches = getPythonScopeQuery().matches(tree.rootNode);
+    }
+    catch (err) {
+        throw scopeExtractionError('scope query', _filePath, err);
+    }
+    const out = [];
+    for (const m of rawMatches) {
+        // Group captures by their tag name. Tree-sitter strips the leading
+        // `@`; we put it back so the central extractor's prefix lookups
+        // (`@scope.`, `@declaration.`, …) work.
+        const grouped = {};
+        for (const c of m.captures) {
+            const tag = '@' + c.name;
+            grouped[tag] = nodeToCapture(tag, c.node);
+        }
+        if (Object.keys(grouped).length === 0)
+            continue;
+        if (grouped['@import.statement'] !== undefined) {
+            // Decompose multi-name imports. Both `import_statement` and
+            // `import_from_statement` share the matched range, so we try the
+            // `from` form first and fall back to plain.
+            const stmtCapture = grouped['@import.statement'];
+            const stmtNode = findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_from_statement') ??
+                findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_statement');
+            if (stmtNode !== null) {
+                for (const piece of splitImportStatement(stmtNode))
+                    out.push(piece);
+            }
+            else {
+                // Defensive fallback: emit the raw match.
+                out.push(grouped);
+            }
+            continue;
+        }
+        if (grouped['@scope.function'] !== undefined) {
+            out.push(grouped);
+            const fnNode = findNodeAtRange(tree.rootNode, grouped['@scope.function'].range, 'function_definition');
+            if (fnNode !== null) {
+                const synth = synthesizeReceiverTypeBinding(fnNode);
+                if (synth !== null)
+                    out.push(synth);
+            }
+            continue;
+        }
+        if (grouped['@declaration.function'] !== undefined) {
+            // Synthesize arity captures on the declaration match so the
+            // central scope-extractor picks them up alongside @declaration.name.
+            // The anchor range is the function_definition itself — we resolve
+            // the node and pipe it through the arity helper.
+            const anchorCap = grouped['@declaration.function'];
+            const fnNode = findNodeAtRange(tree.rootNode, anchorCap.range, 'function_definition');
+            if (fnNode !== null) {
+                if (pythonFunctionDefinitionLabel(fnNode, 'Function') === 'Method') {
+                    delete grouped['@declaration.function'];
+                    grouped['@declaration.method'] = { ...anchorCap, name: '@declaration.method' };
+                }
+                const arity = computePythonArityMetadata(fnNode);
+                if (arity.parameterCount !== undefined) {
+                    grouped['@declaration.parameter-count'] = syntheticCapture('@declaration.parameter-count', fnNode, String(arity.parameterCount));
+                }
+                if (arity.requiredParameterCount !== undefined) {
+                    grouped['@declaration.required-parameter-count'] = syntheticCapture('@declaration.required-parameter-count', fnNode, String(arity.requiredParameterCount));
+                }
+                if (arity.parameterTypes !== undefined) {
+                    // Serialize as JSON so the consumer can round-trip without
+                    // inventing a quoting convention for type names that may
+                    // contain commas (`Dict[str, int]`).
+                    grouped['@declaration.parameter-types'] = syntheticCapture('@declaration.parameter-types', fnNode, JSON.stringify(arity.parameterTypes));
+                }
+            }
+            out.push(grouped);
+            continue;
+        }
+        out.push(grouped);
+    }
+    return out;
+}
+function scopeExtractionError(stage, filePath, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return new Error(`[python] tree-sitter ${stage} failed for ${filePath}: ${reason}; skipping scope extraction for this file`);
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Decompose a Python `import_statement` / `import_from_statement` into
+ * one `CaptureMatch` per imported name.
+ *
+ * Why split here? The `LanguageProvider.interpretImport` contract is
+ * one `ParsedImport` per call. Tree-sitter delivers `import a, b as c`
+ * and `from m import x, y, z` as a single match each, so without
+ * decomposition we'd lose names. The synthesized markers
+ * (`@import.kind` / `@import.name` / `@import.alias` / `@import.source`)
+ * carry everything `interpretPythonImport` needs to recover the original
+ * `ParsedImport` shape — see `interpret.ts`.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+export declare function splitImportStatement(stmtNode: SyntaxNode): CaptureMatch[];