@codragraph/cli 1.6.2

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

@@ -0,0 +1,44 @@
+/**
+ * Java language provider.
+ *
+ * Java uses named imports, JVM wildcard/member import resolution,
+ * and a 'public' modifier-based export checker. 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 { javaClassConfig } from '../class-extractors/configs/jvm.js';
+import { defineLanguage } from '../language-provider.js';
+import { javaTypeConfig } from '../type-extractors/jvm.js';
+import { javaExportChecker } from '../export-detection.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { javaImportConfig } from '../import-resolvers/configs/jvm.js';
+import { extractJavaNamedBindings } from '../named-bindings/java.js';
+import { JAVA_QUERIES } from '../tree-sitter-queries.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { javaCallConfig } from '../call-extractors/configs/jvm.js';
+import { createFieldExtractor } from '../field-extractors/generic.js';
+import { javaConfig } from '../field-extractors/configs/jvm.js';
+import { createMethodExtractor } from '../method-extractors/generic.js';
+import { javaMethodConfig } from '../method-extractors/configs/jvm.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { javaVariableConfig } from '../variable-extractors/configs/jvm.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+export const javaProvider = defineLanguage({
+    id: SupportedLanguages.Java,
+    extensions: ['.java'],
+    treeSitterQueries: JAVA_QUERIES,
+    typeConfig: javaTypeConfig,
+    exportChecker: javaExportChecker,
+    importResolver: createImportResolver(javaImportConfig),
+    namedBindingExtractor: extractJavaNamedBindings,
+    interfaceNamePattern: /^I[A-Z]/,
+    mroStrategy: 'implements-split',
+    callExtractor: createCallExtractor(javaCallConfig),
+    fieldExtractor: createFieldExtractor(javaConfig),
+    methodExtractor: createMethodExtractor(javaMethodConfig),
+    variableExtractor: createVariableExtractor(javaVariableConfig),
+    classExtractor: createClassExtractor(javaClassConfig),
+    heritageExtractor: createHeritageExtractor(SupportedLanguages.Java),
+});

package/dist/core/ingestion/languages/kotlin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export declare const kotlinProvider: import("../language-provider.js").LanguageProvider;

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

@@ -0,0 +1,123 @@
+/**
+ * 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'],
+    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.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare const phpProvider: import("../language-provider.js").LanguageProvider;

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

@@ -0,0 +1,240 @@
+/**
+ * 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 { 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'],
+    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,
+});

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[];