arceus-s 1.6.4

package/dist/core/ingestion/utils/env.js

@@ -0,0 +1,24 @@
+/**
+ * Environment constants shared across the ingestion module.
+ *
+ * Centralizes `isDev` so every file in `ingestion/` imports from
+ * one canonical location rather than re-declaring the check.
+ *
+ * @module
+ */
+/** Whether we're running in development mode (enables verbose console logging). */
+export const isDev = process.env.NODE_ENV === 'development';
+/**
+ * Whether scope-resolution dev validators (e.g. `validateBindingsImmutability`)
+ * should run AND emit warnings. Off by default in CLI runs to avoid silent
+ * O(n) scans on large repos; on in `NODE_ENV=development` or when explicitly
+ * opted-in via `VALIDATE_SEMANTIC_MODEL=1`. `VALIDATE_SEMANTIC_MODEL=0` is the
+ * explicit off switch and wins over both.
+ *
+ * Read every call (not memoized) so test setups using `vi.stubEnv` work.
+ */
+export const isSemanticModelValidatorEnabled = () => {
+    if (process.env.VALIDATE_SEMANTIC_MODEL === '0')
+        return false;
+    return process.env.NODE_ENV === 'development' || process.env.VALIDATE_SEMANTIC_MODEL === '1';
+};

package/dist/core/ingestion/utils/event-loop.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Yield control to the event loop so spinners/progress can render.
+ * Call periodically in hot loops to prevent UI freezes.
+ */
+export declare const yieldToEventLoop: () => Promise<void>;

package/dist/core/ingestion/utils/event-loop.js

@@ -0,0 +1,5 @@
+/**
+ * Yield control to the event loop so spinners/progress can render.
+ * Call periodically in hot loops to prevent UI freezes.
+ */
+export const yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));

package/dist/core/ingestion/utils/graph-sort.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Topological level sort for file-level import graphs.
+ *
+ * Groups files into topological levels where files within the same level
+ * have no mutual import dependencies and can be processed in parallel.
+ * Files involved in import cycles are appended as a final group and
+ * processed last in an undefined order (best-effort propagation).
+ *
+ * Used by cross-file binding propagation to process files in the correct
+ * order — upstream exports must be resolved before downstream importers.
+ *
+ * @module
+ */
+/** A group of files with no mutual dependencies, safe to process in parallel. */
+export type IndependentFileGroup = readonly string[];
+/**
+ * Groups files by topological level using Kahn's algorithm on the **reverse**
+ * import graph.
+ *
+ * Files in the same level have no mutual dependencies — safe to process in parallel.
+ * Files involved in import cycles are appended as a final level and processed
+ * last in an undefined order (best-effort propagation, no ordering guarantees).
+ *
+ * ## Why the counter is named `pendingImportsPerFile` (not `inDegree`)
+ *
+ * Cross-file binding propagation must process **leaves first** — a file's
+ * imports must be resolved before the file itself is re-resolved. To get
+ * leaves first from Kahn's algorithm, we run Kahn's on the **reverse** of
+ * the import graph:
+ *
+ * - `importMap` is `importer → {imports}` (forward edges point at deps).
+ * - The reverse graph has edges `dep → {importers}`, materialized in
+ *   `reverseDeps`.
+ * - On the reverse graph, "in-degree of node X" equals "number of imports X
+ *   has in the forward graph" — i.e. X's forward **out-degree**.
+ *
+ * So `pendingImportsPerFile.get(file)` counts how many of `file`'s imports
+ * are still un-emitted. A file is ready (level 0 / appended to `currentLevel`)
+ * once all its imports have been emitted in earlier levels — that is, once
+ * its pending-imports count drops to 0. Pairing this counter with
+ * `reverseDeps` (dep → importers) is the standard Kahn's-on-the-reverse-graph
+ * formulation; it is **not** a bug to be "fixed" by counting forward
+ * in-degree (importers per file).
+ *
+ * **Do not rename this back to `inDegree` and do not invert the counting
+ * direction.** Doing either flips the emission order from leaves-first to
+ * roots-first, which silently breaks cross-file binding propagation
+ * (downstream files would be re-resolved before their upstream exports
+ * are available).
+ *
+ * @param importMap  Map of file → set of files it imports (forward graph)
+ * @returns          Levels (topologically ordered groups, leaves first)
+ *                   and count of files in cycles
+ */
+export declare function topologicalLevelSort(importMap: ReadonlyMap<string, ReadonlySet<string>>): {
+    levels: readonly IndependentFileGroup[];
+    cycleCount: number;
+};

package/dist/core/ingestion/utils/graph-sort.js

@@ -0,0 +1,100 @@
+/**
+ * Topological level sort for file-level import graphs.
+ *
+ * Groups files into topological levels where files within the same level
+ * have no mutual import dependencies and can be processed in parallel.
+ * Files involved in import cycles are appended as a final group and
+ * processed last in an undefined order (best-effort propagation).
+ *
+ * Used by cross-file binding propagation to process files in the correct
+ * order — upstream exports must be resolved before downstream importers.
+ *
+ * @module
+ */
+/**
+ * Groups files by topological level using Kahn's algorithm on the **reverse**
+ * import graph.
+ *
+ * Files in the same level have no mutual dependencies — safe to process in parallel.
+ * Files involved in import cycles are appended as a final level and processed
+ * last in an undefined order (best-effort propagation, no ordering guarantees).
+ *
+ * ## Why the counter is named `pendingImportsPerFile` (not `inDegree`)
+ *
+ * Cross-file binding propagation must process **leaves first** — a file's
+ * imports must be resolved before the file itself is re-resolved. To get
+ * leaves first from Kahn's algorithm, we run Kahn's on the **reverse** of
+ * the import graph:
+ *
+ * - `importMap` is `importer → {imports}` (forward edges point at deps).
+ * - The reverse graph has edges `dep → {importers}`, materialized in
+ *   `reverseDeps`.
+ * - On the reverse graph, "in-degree of node X" equals "number of imports X
+ *   has in the forward graph" — i.e. X's forward **out-degree**.
+ *
+ * So `pendingImportsPerFile.get(file)` counts how many of `file`'s imports
+ * are still un-emitted. A file is ready (level 0 / appended to `currentLevel`)
+ * once all its imports have been emitted in earlier levels — that is, once
+ * its pending-imports count drops to 0. Pairing this counter with
+ * `reverseDeps` (dep → importers) is the standard Kahn's-on-the-reverse-graph
+ * formulation; it is **not** a bug to be "fixed" by counting forward
+ * in-degree (importers per file).
+ *
+ * **Do not rename this back to `inDegree` and do not invert the counting
+ * direction.** Doing either flips the emission order from leaves-first to
+ * roots-first, which silently breaks cross-file binding propagation
+ * (downstream files would be re-resolved before their upstream exports
+ * are available).
+ *
+ * @param importMap  Map of file → set of files it imports (forward graph)
+ * @returns          Levels (topologically ordered groups, leaves first)
+ *                   and count of files in cycles
+ */
+export function topologicalLevelSort(importMap) {
+    // Per-file count of imports that have not yet been emitted in an earlier
+    // level. See JSDoc above for why this is **not** standard `inDegree`.
+    const pendingImportsPerFile = new Map();
+    const reverseDeps = new Map();
+    for (const [file, deps] of importMap) {
+        if (!pendingImportsPerFile.has(file))
+            pendingImportsPerFile.set(file, 0);
+        for (const dep of deps) {
+            if (!pendingImportsPerFile.has(dep))
+                pendingImportsPerFile.set(dep, 0);
+            pendingImportsPerFile.set(file, (pendingImportsPerFile.get(file) ?? 0) + 1);
+            let rev = reverseDeps.get(dep);
+            if (!rev) {
+                rev = [];
+                reverseDeps.set(dep, rev);
+            }
+            rev.push(file);
+        }
+    }
+    const levels = [];
+    // Level 0: files with no un-emitted imports (true leaves of the import graph).
+    let currentLevel = [...pendingImportsPerFile.entries()]
+        .filter(([, d]) => d === 0)
+        .map(([f]) => f);
+    while (currentLevel.length > 0) {
+        levels.push(currentLevel);
+        const nextLevel = [];
+        for (const file of currentLevel) {
+            // For each importer of `file`, one of its pending imports just got
+            // emitted — decrement the importer's pending count. If it hits 0,
+            // the importer is ready for the next level.
+            for (const dependent of reverseDeps.get(file) ?? []) {
+                const newPending = (pendingImportsPerFile.get(dependent) ?? 1) - 1;
+                pendingImportsPerFile.set(dependent, newPending);
+                if (newPending === 0)
+                    nextLevel.push(dependent);
+            }
+        }
+        currentLevel = nextLevel;
+    }
+    // Anything still > 0 participates in a cycle — append in undefined order.
+    const cycleFiles = [...pendingImportsPerFile.entries()].filter(([, d]) => d > 0).map(([f]) => f);
+    if (cycleFiles.length > 0) {
+        levels.push(cycleFiles);
+    }
+    return { levels, cycleCount: cycleFiles.length };
+}

package/dist/core/ingestion/utils/max-file-size.d.ts

@@ -0,0 +1,20 @@
+/** Default threshold (512 KB). Files larger than this are skipped by the walker. */
+export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
+/** Hard upper bound — tree-sitter refuses buffers above this regardless. */
+export declare const MAX_FILE_SIZE_UPPER_BOUND_BYTES: number;
+/**
+ * Resolve the effective file-size skip threshold (bytes) for the walker.
+ * Reads `ARC_MAX_FILE_SIZE` (KB). Invalid values fall back to the default
+ * and emit a one-time warning. Values above the tree-sitter ceiling are clamped.
+ */
+export declare const getMaxFileSizeBytes: () => number;
+/**
+ * Build the CLI banner message announcing an active file-size override.
+ * Returns `null` when the effective threshold equals the default — the caller
+ * should print nothing in that case. The returned message reflects the
+ * *effective* post-clamp threshold, not the raw env value, so operators reading
+ * startup output see the actual configuration the walker will use.
+ */
+export declare const getMaxFileSizeBannerMessage: () => string | null;
+/** Test-only: reset the warn-once cache so repeated test runs can re-observe warnings. */
+export declare const _resetMaxFileSizeWarnings: () => void;

package/dist/core/ingestion/utils/max-file-size.js

@@ -0,0 +1,53 @@
+import { TREE_SITTER_MAX_BUFFER } from '../constants.js';
+import { logger } from '../../logger.js';
+/** Default threshold (512 KB). Files larger than this are skipped by the walker. */
+export const DEFAULT_MAX_FILE_SIZE_BYTES = 512 * 1024;
+/** Hard upper bound — tree-sitter refuses buffers above this regardless. */
+export const MAX_FILE_SIZE_UPPER_BOUND_BYTES = TREE_SITTER_MAX_BUFFER;
+const warned = new Set();
+const warnOnce = (key, message) => {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    logger.warn(message);
+};
+/**
+ * Resolve the effective file-size skip threshold (bytes) for the walker.
+ * Reads `ARC_MAX_FILE_SIZE` (KB). Invalid values fall back to the default
+ * and emit a one-time warning. Values above the tree-sitter ceiling are clamped.
+ */
+export const getMaxFileSizeBytes = () => {
+    const raw = process.env.ARC_MAX_FILE_SIZE;
+    if (!raw)
+        return DEFAULT_MAX_FILE_SIZE_BYTES;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+        warnOnce(`invalid:${raw}`, `  ARC_MAX_FILE_SIZE must be a positive integer (KB), got "${raw}" — using default ${DEFAULT_MAX_FILE_SIZE_BYTES / 1024}KB`);
+        return DEFAULT_MAX_FILE_SIZE_BYTES;
+    }
+    const bytes = parsed * 1024;
+    if (bytes > MAX_FILE_SIZE_UPPER_BOUND_BYTES) {
+        warnOnce(`clamp:${raw}`, `  ARC_MAX_FILE_SIZE=${parsed}KB exceeds tree-sitter ceiling (${MAX_FILE_SIZE_UPPER_BOUND_BYTES / 1024}KB) — clamping`);
+        return MAX_FILE_SIZE_UPPER_BOUND_BYTES;
+    }
+    return bytes;
+};
+/**
+ * Build the CLI banner message announcing an active file-size override.
+ * Returns `null` when the effective threshold equals the default — the caller
+ * should print nothing in that case. The returned message reflects the
+ * *effective* post-clamp threshold, not the raw env value, so operators reading
+ * startup output see the actual configuration the walker will use.
+ */
+export const getMaxFileSizeBannerMessage = () => {
+    const effectiveBytes = getMaxFileSizeBytes();
+    if (effectiveBytes === DEFAULT_MAX_FILE_SIZE_BYTES)
+        return null;
+    const effectiveKb = effectiveBytes / 1024;
+    const defaultKb = DEFAULT_MAX_FILE_SIZE_BYTES / 1024;
+    return `  ARC_MAX_FILE_SIZE: effective threshold ${effectiveKb}KB (default ${defaultKb}KB)`;
+};
+/** Test-only: reset the warn-once cache so repeated test runs can re-observe warnings. */
+export const _resetMaxFileSizeWarnings = () => {
+    warned.clear();
+};

package/dist/core/ingestion/utils/method-props.d.ts

@@ -0,0 +1,32 @@
+import type { MethodInfo } from '../method-types.js';
+import { SupportedLanguages } from '../../../_shared/index.js';
+/**
+ * Compute arity for ID-generation purposes.
+ * Returns `undefined` when any parameter is variadic (arity is indeterminate).
+ */
+export declare function arityForIdFromInfo(info: MethodInfo): number | undefined;
+/**
+ * Compute a type-based discriminator suffix for same-arity overloads.
+ * Returns `~type1,type2` when the current method collides with another method
+ * in the same class that has the same name and arity but different parameter types.
+ * Returns `''` when there is no collision or types are unavailable.
+ */
+/**
+ * Build collision groups from a method map — groups methods by `name#arity`.
+ * Call once per class, then pass to typeTagForId/constTagForId to avoid O(N²) scans.
+ */
+export declare function buildCollisionGroups(methodMap: Map<string, MethodInfo>): Map<string, MethodInfo[]>;
+export declare function typeTagForId(methodMap: Map<string, MethodInfo>, methodName: string, arity: number | undefined, currentInfo: MethodInfo, language?: SupportedLanguages, 
+/** Pre-built collision groups from buildCollisionGroups(). Avoids O(N) scan per call. */
+collisionGroups?: Map<string, MethodInfo[]>): string;
+/**
+ * Compute a const-qualifier suffix for C++ const/non-const method collisions.
+ * Returns `$const` when the current method is const-qualified and a non-const
+ * method with the same name and arity exists in the same class.
+ * Returns `''` when there is no collision or the method is not const-qualified.
+ */
+export declare function constTagForId(methodMap: Map<string, MethodInfo>, methodName: string, arity: number | undefined, currentInfo: MethodInfo, 
+/** Pre-built collision groups from buildCollisionGroups(). Avoids O(N) scan per call. */
+collisionGroups?: Map<string, MethodInfo[]>): string;
+/** Convert MethodInfo from methodExtractor into flat properties for a graph node. */
+export declare function buildMethodProps(info: MethodInfo): Record<string, unknown>;

package/dist/core/ingestion/utils/method-props.js

@@ -0,0 +1,147 @@
+import { SupportedLanguages } from '../../../_shared/index.js';
+/** Languages where class overload signatures are declaration-only contracts
+ *  that should collapse to the implementation body's node ID. */
+const SKIP_TYPE_HASH_LANGUAGES = new Set([
+    SupportedLanguages.TypeScript,
+    SupportedLanguages.JavaScript,
+]);
+/**
+ * Compute arity for ID-generation purposes.
+ * Returns `undefined` when any parameter is variadic (arity is indeterminate).
+ */
+export function arityForIdFromInfo(info) {
+    return info.parameters.some((p) => p.isVariadic) ? undefined : info.parameters.length;
+}
+/**
+ * Compute a type-based discriminator suffix for same-arity overloads.
+ * Returns `~type1,type2` when the current method collides with another method
+ * in the same class that has the same name and arity but different parameter types.
+ * Returns `''` when there is no collision or types are unavailable.
+ */
+/**
+ * Build collision groups from a method map — groups methods by `name#arity`.
+ * Call once per class, then pass to typeTagForId/constTagForId to avoid O(N²) scans.
+ */
+export function buildCollisionGroups(methodMap) {
+    const groups = new Map();
+    for (const info of methodMap.values()) {
+        if (info.parameters.some((p) => p.isVariadic))
+            continue;
+        const key = `${info.name}#${info.parameters.length}`;
+        let group = groups.get(key);
+        if (!group) {
+            group = [];
+            groups.set(key, group);
+        }
+        group.push(info);
+    }
+    return groups;
+}
+export function typeTagForId(methodMap, methodName, arity, currentInfo, language, 
+/** Pre-built collision groups from buildCollisionGroups(). Avoids O(N) scan per call. */
+collisionGroups) {
+    if (arity === undefined)
+        return '';
+    // Zero-arity methods have no parameter types to disambiguate.
+    if (arity === 0)
+        return '';
+    // TS/JS class overload signatures are declaration-only contracts that should
+    // collapse to the implementation body's node ID, not be disambiguated.
+    if (language && SKIP_TYPE_HASH_LANGUAGES.has(language))
+        return '';
+    // Check if all parameters of this method have types (rawType or type)
+    if (currentInfo.parameters.length > 0 &&
+        currentInfo.parameters.some((p) => (p.rawType ?? p.type) === null)) {
+        return '';
+    }
+    // Use pre-built collision group if available, otherwise scan (backward compat)
+    const groupKey = `${methodName}#${arity}`;
+    const sameArityGroup = collisionGroups?.get(groupKey) ?? _buildGroup(methodMap, methodName, arity);
+    // No collision — single method with this name+arity
+    if (sameArityGroup.length < 2)
+        return '';
+    // Check that ALL methods in the collision group have full type info
+    for (const info of sameArityGroup) {
+        if (info.parameters.length > 0 && info.parameters.some((p) => (p.rawType ?? p.type) === null)) {
+            return '';
+        }
+    }
+    // Build type tag from current method's parameter types.
+    // Prefer rawType (preserves generic/template args like vector<int>) over
+    // type (simplified by extractSimpleTypeName which strips generics).
+    const types = currentInfo.parameters.map((p) => (p.rawType ?? p.type));
+    return `~${types.join(',')}`;
+}
+/** Fallback: build a same-arity group by scanning the full map (O(N)). */
+function _buildGroup(methodMap, methodName, arity) {
+    const group = [];
+    for (const info of methodMap.values()) {
+        if (info.name !== methodName)
+            continue;
+        if (info.parameters.some((p) => p.isVariadic))
+            continue;
+        if (info.parameters.length !== arity)
+            continue;
+        group.push(info);
+    }
+    return group;
+}
+/**
+ * Compute a const-qualifier suffix for C++ const/non-const method collisions.
+ * Returns `$const` when the current method is const-qualified and a non-const
+ * method with the same name and arity exists in the same class.
+ * Returns `''` when there is no collision or the method is not const-qualified.
+ */
+export function constTagForId(methodMap, methodName, arity, currentInfo, 
+/** Pre-built collision groups from buildCollisionGroups(). Avoids O(N) scan per call. */
+collisionGroups) {
+    if (!currentInfo.isConst)
+        return '';
+    if (arity === undefined)
+        return '';
+    // Use pre-built group if available
+    const groupKey = `${methodName}#${arity}`;
+    const group = collisionGroups?.get(groupKey);
+    const candidates = group ?? _buildGroup(methodMap, methodName, arity);
+    // Check if a non-const method exists in the collision group
+    for (const info of candidates) {
+        if (info === currentInfo)
+            continue;
+        if (info.isConst)
+            continue;
+        return '$const';
+    }
+    return '';
+}
+/** Convert MethodInfo from methodExtractor into flat properties for a graph node. */
+export function buildMethodProps(info) {
+    const types = [];
+    let optionalCount = 0;
+    let hasVariadic = false;
+    for (const p of info.parameters) {
+        if (p.type !== null)
+            types.push(p.type);
+        if (p.isOptional)
+            optionalCount++;
+        if (p.isVariadic)
+            hasVariadic = true;
+    }
+    return {
+        parameterCount: hasVariadic ? undefined : info.parameters.length,
+        ...(!hasVariadic && optionalCount > 0
+            ? { requiredParameterCount: info.parameters.length - optionalCount }
+            : {}),
+        ...(types.length > 0 ? { parameterTypes: types } : {}),
+        returnType: info.returnType ?? undefined,
+        visibility: info.visibility,
+        isStatic: info.isStatic,
+        isAbstract: info.isAbstract,
+        isFinal: info.isFinal,
+        ...(info.isVirtual ? { isVirtual: info.isVirtual } : {}),
+        ...(info.isOverride ? { isOverride: info.isOverride } : {}),
+        ...(info.isAsync ? { isAsync: info.isAsync } : {}),
+        ...(info.isPartial ? { isPartial: info.isPartial } : {}),
+        ...(info.isConst ? { isConst: info.isConst } : {}),
+        ...(info.annotations.length > 0 ? { annotations: info.annotations } : {}),
+    };
+}

package/dist/core/ingestion/utils/ruby-self-call.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Ruby bare-call self-inference helper.
+ *
+ * Ruby makes `self` implicit for method calls inside instance and class bodies:
+ * `serialize` inside `Account#call_serialize` means `self.serialize`. Other
+ * supported languages make the receiver explicit in source (`this.x`, `self.x`),
+ * so tree-sitter produces a member call directly. Ruby's bare identifier
+ * produces either `callForm === 'free'` or `callForm === undefined` (body_statement
+ * identifier captures where the @call node IS the @call.name node), and
+ * `resolveFreeCall` does a global tiered name lookup — no MRO walk.
+ *
+ * This helper is a pure decision function consumed by the Ruby language
+ * provider's `inferImplicitReceiver` hook. Shared pipeline code never imports
+ * it directly — only `languages/ruby.ts` does.
+ */
+import type { SyntaxNode } from './ast-helpers.js';
+import type { LanguageProvider } from '../language-provider.js';
+/**
+ * Rewrite suggestion returned by `maybeRewriteRubyBareCallToSelf`.
+ *
+ * `callForm` is always `'member'`; `receiverName` is always `'self'`.
+ * `dispatchKind` controls the stage-4 ancestry view:
+ * - `'instance'` → prepend → direct → include (normal MRO)
+ * - `'singleton'` → extend providers only, no file-scoped fallback
+ *
+ * Consumed by `languages/ruby.ts § inferImplicitReceiver` (wraps into
+ * `ImplicitReceiverOverride`; `dispatchKind` becomes the `hint` field).
+ */
+export interface SelfCallRewrite {
+    readonly callForm: 'member';
+    readonly receiverName: 'self';
+    readonly receiverTypeName: string;
+    /** `'singleton'` when the enclosing method is `def self.foo` / inside a
+     *  `singleton_class` body; `'instance'` otherwise. Controls MRO ancestry
+     *  view selection in stage-4 dispatch. */
+    readonly dispatchKind: 'instance' | 'singleton';
+}
+/**
+ * Pure decision function: should a bare Ruby call be rewritten as `self.method`?
+ *
+ * Returns a `SelfCallRewrite` when all gates pass; null otherwise.
+ * Gates (all required): `callForm` is `'free'` or `undefined`, strategy is
+ * `'ruby-mixin'`, `enclosingClassName` is non-null, name is not `'super'`,
+ * name is not a built-in.
+ *
+ * Note: Ruby body-statement identifiers produce `callForm === undefined` because
+ * the @call node IS the @call.name node in tree-sitter-ruby.
+ *
+ * Example: `calledName='serialize'` in `Account` instance method →
+ * `{callForm:'member', receiverName:'self', receiverTypeName:'Account', dispatchKind:'instance'}`
+ */
+export declare function maybeRewriteRubyBareCallToSelf(calledName: string, callForm: 'free' | 'member' | 'constructor' | undefined, callNode: SyntaxNode, enclosingClassName: string | null, provider: Pick<LanguageProvider, 'isBuiltInName' | 'mroStrategy'>): SelfCallRewrite | null;

package/dist/core/ingestion/utils/ruby-self-call.js

@@ -0,0 +1,59 @@
+// arc/src/core/ingestion/utils/ruby-self-call.ts
+/** Maximum parent-walk depth to prevent runaway traversal. */
+const MAX_PARENT_DEPTH = 50;
+/**
+ * Returns true if `callNode` is inside a `singleton_method` or `singleton_class`.
+ * Stops at `class`/`module` boundary or MAX_PARENT_DEPTH (50) to bound traversal.
+ */
+function isInsideSingletonMethod(callNode) {
+    let current = callNode.parent;
+    let depth = 0;
+    while (current && depth++ < MAX_PARENT_DEPTH) {
+        if (current.type === 'singleton_method')
+            return true;
+        if (current.type === 'singleton_class')
+            return true;
+        if (current.type === 'class' || current.type === 'module')
+            return false;
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Pure decision function: should a bare Ruby call be rewritten as `self.method`?
+ *
+ * Returns a `SelfCallRewrite` when all gates pass; null otherwise.
+ * Gates (all required): `callForm` is `'free'` or `undefined`, strategy is
+ * `'ruby-mixin'`, `enclosingClassName` is non-null, name is not `'super'`,
+ * name is not a built-in.
+ *
+ * Note: Ruby body-statement identifiers produce `callForm === undefined` because
+ * the @call node IS the @call.name node in tree-sitter-ruby.
+ *
+ * Example: `calledName='serialize'` in `Account` instance method →
+ * `{callForm:'member', receiverName:'self', receiverTypeName:'Account', dispatchKind:'instance'}`
+ */
+export function maybeRewriteRubyBareCallToSelf(calledName, callForm, callNode, enclosingClassName, provider) {
+    // Body-statement bare identifiers produce `callForm === undefined` because
+    // the @call node IS the @call.name node in tree-sitter-ruby. Treat both
+    // undefined and 'free' as qualifying.
+    if (callForm !== 'free' && callForm !== undefined)
+        return null;
+    if (provider.mroStrategy !== 'ruby-mixin')
+        return null;
+    if (!enclosingClassName)
+        return null;
+    if (calledName === 'super')
+        return null;
+    if (provider.isBuiltInName(calledName))
+        return null;
+    const dispatchKind = isInsideSingletonMethod(callNode)
+        ? 'singleton'
+        : 'instance';
+    return {
+        callForm: 'member',
+        receiverName: 'self',
+        receiverTypeName: enclosingClassName,
+        dispatchKind,
+    };
+}

package/dist/core/ingestion/utils/verbose.d.ts

@@ -0,0 +1 @@
+export declare const isVerboseIngestionEnabled: () => boolean;

package/dist/core/ingestion/utils/verbose.js

@@ -0,0 +1,7 @@
+export const isVerboseIngestionEnabled = () => {
+    const raw = process.env.ARC_VERBOSE;
+    if (!raw)
+        return false;
+    const value = raw.toLowerCase();
+    return value === '1' || value === 'true' || value === 'yes';
+};

package/dist/core/ingestion/variable-extractors/configs/c-cpp.d.ts

@@ -0,0 +1,3 @@
+import type { VariableExtractionConfig } from '../../variable-types.js';
+export declare const cVariableConfig: VariableExtractionConfig;
+export declare const cppVariableConfig: VariableExtractionConfig;

package/dist/core/ingestion/variable-extractors/configs/c-cpp.js

@@ -0,0 +1,81 @@
+// arc/src/core/ingestion/variable-extractors/configs/c-cpp.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { hasKeyword } from '../../field-extractors/configs/helpers.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+/**
+ * C/C++ variable extraction config.
+ *
+ * Handles global/namespace-scoped variable declarations:
+ * - `int x = 5;`
+ * - `const int MAX = 100;`
+ * - `static int counter = 0;`
+ * - `constexpr int SIZE = 10;` (C++)
+ * - `extern int shared;`
+ *
+ * tree-sitter-c/cpp uses declaration for variable declarations.
+ */
+function extractCVarName(node) {
+    // declaration → declarator (init_declarator or identifier)
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type === 'init_declarator') {
+            const declarator = child.childForFieldName('declarator');
+            if (declarator?.type === 'identifier')
+                return declarator.text;
+            if (declarator?.type === 'pointer_declarator') {
+                const inner = declarator.namedChildren.find((c) => c.type === 'identifier');
+                return inner?.text;
+            }
+        }
+        if (child?.type === 'identifier')
+            return child.text;
+    }
+    return undefined;
+}
+function extractCVarType(node) {
+    const typeNode = node.childForFieldName('type');
+    if (typeNode)
+        return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+    // Fallback: first primitive_type or type_identifier child
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type === 'primitive_type' ||
+            child?.type === 'type_identifier' ||
+            child?.type === 'sized_type_specifier') {
+            return child.text?.trim();
+        }
+    }
+    return undefined;
+}
+const shared = {
+    constNodeTypes: [],
+    staticNodeTypes: [],
+    variableNodeTypes: ['declaration'],
+    extractName: extractCVarName,
+    extractType: extractCVarType,
+    extractVisibility(node) {
+        // C/C++ visibility is file-scoped by default (static = file-private)
+        if (hasKeyword(node, 'static'))
+            return 'private';
+        if (hasKeyword(node, 'extern'))
+            return 'public';
+        return 'public';
+    },
+    isConst(node) {
+        return hasKeyword(node, 'const') || hasKeyword(node, 'constexpr');
+    },
+    isStatic(node) {
+        return hasKeyword(node, 'static');
+    },
+    isMutable(node) {
+        return !hasKeyword(node, 'const') && !hasKeyword(node, 'constexpr');
+    },
+};
+export const cVariableConfig = {
+    ...shared,
+    language: SupportedLanguages.C,
+};
+export const cppVariableConfig = {
+    ...shared,
+    language: SupportedLanguages.CPlusPlus,
+};