arceus-s 1.6.4

package/dist/core/ingestion/community-processor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Community Detection Processor
+ *
+ * Uses the Leiden algorithm (via graphology-communities-leiden) to detect
+ * communities/clusters in the code graph based on CALLS relationships.
+ *
+ * Communities represent groups of code that work together frequently,
+ * helping agents navigate the codebase by functional area rather than file structure.
+ */
+import { KnowledgeGraph } from '../graph/types.js';
+export interface CommunityNode {
+    id: string;
+    label: string;
+    heuristicLabel: string;
+    cohesion: number;
+    symbolCount: number;
+}
+export interface CommunityMembership {
+    nodeId: string;
+    communityId: string;
+}
+export interface CommunityDetectionResult {
+    communities: CommunityNode[];
+    memberships: CommunityMembership[];
+    stats: {
+        totalCommunities: number;
+        modularity: number;
+        nodesProcessed: number;
+    };
+}
+export declare const COMMUNITY_COLORS: string[];
+export declare const getCommunityColor: (communityIndex: number) => string;
+/**
+ * Detect communities in the knowledge graph using Leiden algorithm
+ *
+ * This runs AFTER all relationships (CALLS, IMPORTS, etc.) have been built.
+ * It uses primarily CALLS edges to cluster code that works together.
+ */
+export declare const processCommunities: (knowledgeGraph: KnowledgeGraph, onProgress?: (message: string, progress: number) => void) => Promise<CommunityDetectionResult>;

package/dist/core/ingestion/community-processor.js

@@ -0,0 +1,336 @@
+/**
+ * Community Detection Processor
+ *
+ * Uses the Leiden algorithm (via graphology-communities-leiden) to detect
+ * communities/clusters in the code graph based on CALLS relationships.
+ *
+ * Communities represent groups of code that work together frequently,
+ * helping agents navigate the codebase by functional area rather than file structure.
+ */
+// NOTE: The Leiden algorithm source is vendored from graphology's repo
+// (src/communities-leiden) because it was never published to npm.
+// We use createRequire to load the CommonJS vendored files in ESM context.
+import Graph from 'graphology';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Navigate to package root (works from both src/ and dist/)
+const leidenPath = resolve(__dirname, '..', '..', '..', 'vendor', 'leiden', 'index.cjs');
+const _require = createRequire(import.meta.url);
+const leiden = _require(leidenPath);
+/**
+ * Deterministic PRNG (mulberry32) seed for the vendored Leiden algorithm.
+ * Vendored Leiden defaults `rng: Math.random`, which makes community
+ * assignment non-deterministic across runs. Passing a seeded RNG gives us
+ * reproducible community/modularity output, which is required for the
+ * incremental-indexing equivalence test (incremental ≡ full rebuild).
+ */
+const LEIDEN_SEED = 0xc0de;
+function createSeededRng(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(s ^ (s >>> 15), 1 | s);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+// ============================================================================
+// COMMUNITY COLORS (for visualization)
+// ============================================================================
+export const COMMUNITY_COLORS = [
+    '#ef4444', // red
+    '#f97316', // orange
+    '#eab308', // yellow
+    '#22c55e', // green
+    '#06b6d4', // cyan
+    '#3b82f6', // blue
+    '#f59e0b', // violet
+    '#d946ef', // fuchsia
+    '#ec4899', // pink
+    '#f43f5e', // rose
+    '#14b8a6', // teal
+    '#84cc16', // lime
+];
+export const getCommunityColor = (communityIndex) => {
+    return COMMUNITY_COLORS[communityIndex % COMMUNITY_COLORS.length];
+};
+// ============================================================================
+// MAIN PROCESSOR
+// ============================================================================
+/**
+ * Detect communities in the knowledge graph using Leiden algorithm
+ *
+ * This runs AFTER all relationships (CALLS, IMPORTS, etc.) have been built.
+ * It uses primarily CALLS edges to cluster code that works together.
+ */
+export const processCommunities = async (knowledgeGraph, onProgress) => {
+    onProgress?.('Building graph for community detection...', 0);
+    // Pre-check total symbol count to determine large-graph mode before building
+    let symbolCount = 0;
+    knowledgeGraph.forEachNode((node) => {
+        if (node.label === 'Function' ||
+            node.label === 'Class' ||
+            node.label === 'Method' ||
+            node.label === 'Interface') {
+            symbolCount++;
+        }
+    });
+    const isLarge = symbolCount > 10_000;
+    const graph = buildGraphologyGraph(knowledgeGraph, isLarge);
+    if (graph.order === 0) {
+        return {
+            communities: [],
+            memberships: [],
+            stats: { totalCommunities: 0, modularity: 0, nodesProcessed: 0 },
+        };
+    }
+    const nodeCount = graph.order;
+    const edgeCount = graph.size;
+    onProgress?.(`Running Leiden on ${nodeCount} nodes, ${edgeCount} edges${isLarge ? ` (filtered from ${symbolCount} symbols)` : ''}...`, 30);
+    // Large graphs: higher resolution + capped iterations (matching Python leidenalg default of 2).
+    // The first 2 iterations capture ~95%+ of modularity; additional iterations have diminishing returns.
+    // Timeout: abort after 60s for pathological graph structures.
+    const LEIDEN_TIMEOUT_MS = 60_000;
+    let details;
+    try {
+        details = await Promise.race([
+            Promise.resolve(leiden.detailed(graph, {
+                resolution: isLarge ? 2.0 : 1.0,
+                maxIterations: isLarge ? 3 : 0,
+                rng: createSeededRng(LEIDEN_SEED),
+            })),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Leiden timeout')), LEIDEN_TIMEOUT_MS)),
+        ]);
+    }
+    catch (e) {
+        if (e.message === 'Leiden timeout') {
+            onProgress?.('Community detection timed out, using fallback...', 60);
+            // Fallback: assign all nodes to community 0
+            const communities = {};
+            graph.forEachNode((node) => {
+                communities[node] = 0;
+            });
+            details = { communities, count: 1, modularity: 0 };
+        }
+        else {
+            throw e;
+        }
+    }
+    onProgress?.(`Found ${details.count} communities...`, 60);
+    // Step 3: Create community nodes with heuristic labels
+    const communityNodes = createCommunityNodes(details.communities, details.count, graph, knowledgeGraph);
+    onProgress?.('Creating membership edges...', 80);
+    // Step 4: Create membership mappings
+    const memberships = [];
+    Object.entries(details.communities).forEach(([nodeId, communityNum]) => {
+        memberships.push({
+            nodeId,
+            communityId: `comm_${communityNum}`,
+        });
+    });
+    onProgress?.('Community detection complete!', 100);
+    return {
+        communities: communityNodes,
+        memberships,
+        stats: {
+            totalCommunities: details.count,
+            modularity: details.modularity,
+            nodesProcessed: graph.order,
+        },
+    };
+};
+// ============================================================================
+// HELPER: Build graphology graph from knowledge graph
+// ============================================================================
+/**
+ * Build a graphology graph containing only symbol nodes and clustering edges.
+ * For large graphs (>10K symbols), filter out low-confidence fuzzy-global edges
+ * and degree-1 nodes that add noise and massively increase Leiden runtime.
+ */
+const MIN_CONFIDENCE_LARGE = 0.5;
+const buildGraphologyGraph = (knowledgeGraph, isLarge) => {
+    const GraphCtor = Graph;
+    const graph = new GraphCtor({ type: 'undirected', allowSelfLoops: false });
+    const symbolTypes = new Set(['Function', 'Class', 'Method', 'Interface']);
+    const clusteringRelTypes = new Set(['CALLS', 'EXTENDS', 'IMPLEMENTS']);
+    const connectedNodes = new Set();
+    const nodeDegree = new Map();
+    knowledgeGraph.forEachRelationship((rel) => {
+        if (!clusteringRelTypes.has(rel.type) || rel.sourceId === rel.targetId)
+            return;
+        if (isLarge && rel.confidence < MIN_CONFIDENCE_LARGE)
+            return;
+        connectedNodes.add(rel.sourceId);
+        connectedNodes.add(rel.targetId);
+        nodeDegree.set(rel.sourceId, (nodeDegree.get(rel.sourceId) || 0) + 1);
+        nodeDegree.set(rel.targetId, (nodeDegree.get(rel.targetId) || 0) + 1);
+    });
+    knowledgeGraph.forEachNode((node) => {
+        if (!symbolTypes.has(node.label) || !connectedNodes.has(node.id))
+            return;
+        // For large graphs, skip degree-1 nodes — they just become singletons or
+        // get absorbed into their single neighbor's community, but cost iteration time.
+        if (isLarge && (nodeDegree.get(node.id) || 0) < 2)
+            return;
+        graph.addNode(node.id, {
+            name: node.properties.name,
+            filePath: node.properties.filePath,
+            type: node.label,
+        });
+    });
+    knowledgeGraph.forEachRelationship((rel) => {
+        if (!clusteringRelTypes.has(rel.type))
+            return;
+        if (isLarge && rel.confidence < MIN_CONFIDENCE_LARGE)
+            return;
+        if (graph.hasNode(rel.sourceId) &&
+            graph.hasNode(rel.targetId) &&
+            rel.sourceId !== rel.targetId) {
+            if (!graph.hasEdge(rel.sourceId, rel.targetId)) {
+                graph.addEdge(rel.sourceId, rel.targetId);
+            }
+        }
+    });
+    return graph;
+};
+// ============================================================================
+// HELPER: Create community nodes with heuristic labels
+// ============================================================================
+/**
+ * Create Community nodes with auto-generated labels based on member file paths
+ */
+const createCommunityNodes = (communities, communityCount, graph, knowledgeGraph) => {
+    // Group node IDs by community
+    const communityMembers = new Map();
+    Object.entries(communities).forEach(([nodeId, commNum]) => {
+        if (!communityMembers.has(commNum)) {
+            communityMembers.set(commNum, []);
+        }
+        communityMembers.get(commNum).push(nodeId);
+    });
+    // Build node lookup for file paths
+    const nodePathMap = new Map();
+    for (const node of knowledgeGraph.iterNodes()) {
+        if (node.properties.filePath) {
+            nodePathMap.set(node.id, node.properties.filePath);
+        }
+    }
+    // Create community nodes - SKIP SINGLETONS (isolated nodes)
+    const communityNodes = [];
+    communityMembers.forEach((memberIds, commNum) => {
+        // Skip singleton communities - they're just isolated nodes
+        if (memberIds.length < 2)
+            return;
+        const heuristicLabel = generateHeuristicLabel(memberIds, nodePathMap, graph, commNum);
+        communityNodes.push({
+            id: `comm_${commNum}`,
+            label: heuristicLabel,
+            heuristicLabel,
+            cohesion: calculateCohesion(memberIds, graph),
+            symbolCount: memberIds.length,
+        });
+    });
+    // Sort by size descending
+    communityNodes.sort((a, b) => b.symbolCount - a.symbolCount);
+    return communityNodes;
+};
+// ============================================================================
+// HELPER: Generate heuristic label from folder patterns
+// ============================================================================
+/**
+ * Generate a human-readable label from the most common folder name in the community
+ */
+const generateHeuristicLabel = (memberIds, nodePathMap, graph, commNum) => {
+    // Collect folder names from file paths
+    const folderCounts = new Map();
+    memberIds.forEach((nodeId) => {
+        const filePath = nodePathMap.get(nodeId) || '';
+        const parts = filePath.split('/').filter(Boolean);
+        // Get the most specific folder (parent directory)
+        if (parts.length >= 2) {
+            const folder = parts[parts.length - 2];
+            // Skip generic folder names
+            if (!['src', 'lib', 'core', 'utils', 'common', 'shared', 'helpers'].includes(folder.toLowerCase())) {
+                folderCounts.set(folder, (folderCounts.get(folder) || 0) + 1);
+            }
+        }
+    });
+    // Find most common folder
+    let maxCount = 0;
+    let bestFolder = '';
+    folderCounts.forEach((count, folder) => {
+        if (count > maxCount) {
+            maxCount = count;
+            bestFolder = folder;
+        }
+    });
+    if (bestFolder) {
+        // Capitalize first letter
+        return bestFolder.charAt(0).toUpperCase() + bestFolder.slice(1);
+    }
+    // Fallback: use function names to detect patterns
+    const names = [];
+    memberIds.forEach((nodeId) => {
+        const name = graph.getNodeAttribute(nodeId, 'name');
+        if (name)
+            names.push(name);
+    });
+    // Look for common prefixes
+    if (names.length > 2) {
+        const commonPrefix = findCommonPrefix(names);
+        if (commonPrefix.length > 2) {
+            return commonPrefix.charAt(0).toUpperCase() + commonPrefix.slice(1);
+        }
+    }
+    // Last resort: generic name with community ID for uniqueness
+    return `Cluster_${commNum}`;
+};
+/**
+ * Find common prefix among strings
+ */
+const findCommonPrefix = (strings) => {
+    if (strings.length === 0)
+        return '';
+    const sorted = strings.slice().sort();
+    const first = sorted[0];
+    const last = sorted[sorted.length - 1];
+    let i = 0;
+    while (i < first.length && first[i] === last[i]) {
+        i++;
+    }
+    return first.substring(0, i);
+};
+// ============================================================================
+// HELPER: Calculate community cohesion
+// ============================================================================
+/**
+ * Estimate cohesion score (0-1) based on internal edge density.
+ * Uses sampling for large communities to avoid O(N^2) cost.
+ */
+const calculateCohesion = (memberIds, graph) => {
+    if (memberIds.length <= 1)
+        return 1.0;
+    const memberSet = new Set(memberIds);
+    // Sample up to 50 members for large communities
+    const SAMPLE_SIZE = 50;
+    const sample = memberIds.length <= SAMPLE_SIZE ? memberIds : memberIds.slice(0, SAMPLE_SIZE);
+    let internalEdges = 0;
+    let totalEdges = 0;
+    for (const nodeId of sample) {
+        if (!graph.hasNode(nodeId))
+            continue;
+        graph.forEachNeighbor(nodeId, (neighbor) => {
+            totalEdges++;
+            if (memberSet.has(neighbor)) {
+                internalEdges++;
+            }
+        });
+    }
+    // Cohesion = fraction of edges that stay internal
+    if (totalEdges === 0)
+        return 1.0;
+    return Math.min(1.0, internalEdges / totalEdges);
+};

package/dist/core/ingestion/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default minimum buffer size for tree-sitter parsing (512 KB).
+ * tree-sitter requires bufferSize >= file size in bytes.
+ */
+export declare const TREE_SITTER_BUFFER_SIZE: number;
+/**
+ * Maximum buffer size cap (32 MB) to prevent OOM on huge files.
+ * Also used as the file-size skip threshold — files larger than this are not parsed.
+ */
+export declare const TREE_SITTER_MAX_BUFFER: number;
+/**
+ * Compute adaptive buffer size for tree-sitter parsing.
+ * Uses 2x UTF-8 byte size, clamped between 512 KB and 32 MB.
+ * Keeps tree-sitter's byte-sized buffer above large ASCII and multibyte sources.
+ */
+export declare const getTreeSitterContentByteLength: (sourceText: string) => number;
+export declare const getTreeSitterBufferSize: (sourceText: string) => number;

package/dist/core/ingestion/constants.js

@@ -0,0 +1,21 @@
+import { Buffer } from 'node:buffer';
+/**
+ * Default minimum buffer size for tree-sitter parsing (512 KB).
+ * tree-sitter requires bufferSize >= file size in bytes.
+ */
+export const TREE_SITTER_BUFFER_SIZE = 512 * 1024;
+/**
+ * Maximum buffer size cap (32 MB) to prevent OOM on huge files.
+ * Also used as the file-size skip threshold — files larger than this are not parsed.
+ */
+export const TREE_SITTER_MAX_BUFFER = 32 * 1024 * 1024;
+/**
+ * Compute adaptive buffer size for tree-sitter parsing.
+ * Uses 2x UTF-8 byte size, clamped between 512 KB and 32 MB.
+ * Keeps tree-sitter's byte-sized buffer above large ASCII and multibyte sources.
+ */
+export const getTreeSitterContentByteLength = (sourceText) => Buffer.byteLength(sourceText, 'utf8');
+export const getTreeSitterBufferSize = (sourceText) => {
+    const byteLength = getTreeSitterContentByteLength(sourceText);
+    return Math.min(Math.max(byteLength * 2, TREE_SITTER_BUFFER_SIZE), TREE_SITTER_MAX_BUFFER);
+};

package/dist/core/ingestion/cpp-ue-preprocessor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Strip Unreal Engine reflection macros from C++ source, length-preserving.
+ *
+ * Returns the original string unchanged if no strong UE marker is detected,
+ * so non-UE C++ files (including ones that contain `*_API`-suffixed
+ * identifiers like `REST_API` or `HTTP_API`) incur only a single regex test.
+ *
+ * The `_filePath` parameter is part of the `LanguageProvider.preprocessSource`
+ * contract but is unused — UE detection is purely content-based. Accepted and
+ * ignored here so the function matches the hook signature exactly.
+ */
+export declare function stripUeMacros(source: string, _filePath?: string): string;

package/dist/core/ingestion/cpp-ue-preprocessor.js

@@ -0,0 +1,260 @@
+/**
+ * Unreal Engine reflection-macro preprocessor for C++ source.
+ *
+ * Tree-sitter does not expand C preprocessor macros, so Unreal's reflection
+ * markers (`UCLASS(...)`, `UFUNCTION(...)`, `MODULENAME_API`, ...) are parsed
+ * verbatim. The result is mis-parsed declarations: in `class BRAWLUI_API
+ * UMyClass : public UObject`, tree-sitter-cpp captures `BRAWLUI_API` as the
+ * class name and the rest of the declaration becomes structurally wrong.
+ *
+ * This module elides those macros from the source text BEFORE tree-sitter
+ * parses it. Replacement is **length-preserving** (each elided byte becomes
+ * a space, newlines preserved) so byte offsets and line/column positions
+ * tree-sitter reports remain identical to the original file. Symbol
+ * locations in the graph stay accurate.
+ *
+ * A cheap detection guard short-circuits files that don't look like UE
+ * sources, so non-UE C++ codebases pay no cost.
+ *
+ * Pure function — no tree-sitter dependency, safe for worker threads.
+ */
+/**
+ * Strong UE markers — reflection macros that only Unreal Engine projects use.
+ * Presence of one of these is sufficient evidence that the file is a UE source
+ * and that `MODULENAME_API` tokens in it are intended as export macros.
+ *
+ * Importantly, `_API` tokens are NOT in this guard — `REST_API`, `HTTP_API`,
+ * `MY_LIB_API` and similar identifiers appear in plenty of non-UE C++ codebases
+ * as constants/enums/parameter names. We must not erase them just because the
+ * file mentions an `_API` token.
+ */
+const HAS_UE_HINT = /\b(?:UCLASS|UFUNCTION|UPROPERTY|USTRUCT|UENUM|UINTERFACE|GENERATED_BODY|GENERATED_[A-Z_]+_BODY|UE_DEPRECATED|DECLARE_(?:DYNAMIC_)?(?:MULTICAST_)?DELEGATE)/;
+const SIMPLE_MACROS_NO_ARGS = [
+    'GENERATED_BODY',
+    'GENERATED_UCLASS_BODY',
+    'GENERATED_USTRUCT_BODY',
+    'GENERATED_UINTERFACE_BODY',
+    'GENERATED_IINTERFACE_BODY',
+    'DECLARE_CLASS',
+    'GENERATED_BODY_LEGACY',
+];
+const PARENTHESIZED_MACROS = [
+    'UCLASS',
+    'UFUNCTION',
+    'UPROPERTY',
+    'USTRUCT',
+    'UENUM',
+    'UINTERFACE',
+    'UMETA',
+    'UE_DEPRECATED',
+];
+const DELEGATE_MACRO_RE = /\bDECLARE_(?:DYNAMIC_)?(?:MULTICAST_)?DELEGATE(?:_(?:RetVal_OneParam|RetVal_TwoParams|RetVal_ThreeParams|RetVal_FourParams|RetVal_FiveParams|RetVal_SixParams|RetVal_SevenParams|RetVal_EightParams|RetVal_NineParams|RetVal|OneParam|TwoParams|ThreeParams|FourParams|FiveParams|SixParams|SevenParams|EightParams|NineParams|TenParams))?(?=\s*\()/g;
+/**
+ * Module export tokens like `BRAWLUI_API`, `ENGINE_API`, `COREUOBJECT_API`.
+ * Pattern: ALL_CAPS identifier ending in `_API`. The leading word boundary
+ * (`\b`) prevents matching mid-identifier.
+ */
+const API_MACRO_RE = /\b[A-Z][A-Z0-9_]*_API\b/g;
+/** Replace `[start, end)` of `chars` with spaces, preserving newlines. */
+function eraseRange(chars, start, end) {
+    for (let i = start; i < end; i++) {
+        if (chars[i] !== '\n' && chars[i] !== '\r') {
+            chars[i] = ' ';
+        }
+    }
+}
+/**
+ * Find the matching close paren for an opening paren at index `openIdx`.
+ * Returns the index of `)` (inclusive end), or -1 if unbalanced.
+ *
+ * Handles nested parens and string/char literals so commas/parens inside
+ * strings don't throw off the match. Does not attempt to handle raw string
+ * literals (`R"(...)"`); UE reflection-macro arguments do not use them in
+ * practice.
+ */
+function findMatchingParen(source, openIdx) {
+    if (source.charCodeAt(openIdx) !== 0x28)
+        return -1;
+    let depth = 1;
+    let i = openIdx + 1;
+    const len = source.length;
+    while (i < len && depth > 0) {
+        const ch = source.charCodeAt(i);
+        // String literal
+        if (ch === 0x22) {
+            i++;
+            while (i < len) {
+                const c = source.charCodeAt(i);
+                if (c === 0x5c) {
+                    i += 2;
+                    continue;
+                }
+                if (c === 0x22) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        // Char literal
+        if (ch === 0x27) {
+            i++;
+            while (i < len) {
+                const c = source.charCodeAt(i);
+                if (c === 0x5c) {
+                    i += 2;
+                    continue;
+                }
+                if (c === 0x27) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        // Line comment
+        if (ch === 0x2f && source.charCodeAt(i + 1) === 0x2f) {
+            while (i < len && source.charCodeAt(i) !== 0x0a)
+                i++;
+            continue;
+        }
+        // Block comment
+        if (ch === 0x2f && source.charCodeAt(i + 1) === 0x2a) {
+            i += 2;
+            while (i < len) {
+                if (source.charCodeAt(i) === 0x2a && source.charCodeAt(i + 1) === 0x2f) {
+                    i += 2;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (ch === 0x28)
+            depth++;
+        else if (ch === 0x29) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+        i++;
+    }
+    return -1;
+}
+/** Match a whole-word identifier at `idx`. Returns the byte after the identifier, or -1 on miss. */
+function matchIdentifierAt(source, idx, name) {
+    if (idx > 0) {
+        const prev = source.charCodeAt(idx - 1);
+        if ((prev >= 0x30 && prev <= 0x39) ||
+            (prev >= 0x41 && prev <= 0x5a) ||
+            (prev >= 0x61 && prev <= 0x7a) ||
+            prev === 0x5f) {
+            return -1;
+        }
+    }
+    for (let k = 0; k < name.length; k++) {
+        if (source.charCodeAt(idx + k) !== name.charCodeAt(k))
+            return -1;
+    }
+    const after = idx + name.length;
+    if (after < source.length) {
+        const next = source.charCodeAt(after);
+        if ((next >= 0x30 && next <= 0x39) ||
+            (next >= 0x41 && next <= 0x5a) ||
+            (next >= 0x61 && next <= 0x7a) ||
+            next === 0x5f) {
+            return -1;
+        }
+    }
+    return after;
+}
+/** Skip ASCII whitespace forward from `idx`. Returns the next non-whitespace byte index. */
+function skipWhitespace(source, idx) {
+    const len = source.length;
+    while (idx < len) {
+        const ch = source.charCodeAt(idx);
+        if (ch === 0x20 || ch === 0x09 || ch === 0x0a || ch === 0x0d) {
+            idx++;
+            continue;
+        }
+        break;
+    }
+    return idx;
+}
+/**
+ * Strip Unreal Engine reflection macros from C++ source, length-preserving.
+ *
+ * Returns the original string unchanged if no strong UE marker is detected,
+ * so non-UE C++ files (including ones that contain `*_API`-suffixed
+ * identifiers like `REST_API` or `HTTP_API`) incur only a single regex test.
+ *
+ * The `_filePath` parameter is part of the `LanguageProvider.preprocessSource`
+ * contract but is unused — UE detection is purely content-based. Accepted and
+ * ignored here so the function matches the hook signature exactly.
+ */
+export function stripUeMacros(source, _filePath) {
+    if (!HAS_UE_HINT.test(source))
+        return source;
+    const chars = source.split('');
+    for (const macro of PARENTHESIZED_MACROS) {
+        let searchFrom = 0;
+        while (true) {
+            const hit = source.indexOf(macro, searchFrom);
+            if (hit < 0)
+                break;
+            searchFrom = hit + 1;
+            const after = matchIdentifierAt(source, hit, macro);
+            if (after < 0)
+                continue;
+            const parenIdx = skipWhitespace(source, after);
+            if (source.charCodeAt(parenIdx) !== 0x28)
+                continue;
+            const close = findMatchingParen(source, parenIdx);
+            if (close < 0)
+                continue;
+            eraseRange(chars, hit, close + 1);
+        }
+    }
+    for (const macro of SIMPLE_MACROS_NO_ARGS) {
+        let searchFrom = 0;
+        while (true) {
+            const hit = source.indexOf(macro, searchFrom);
+            if (hit < 0)
+                break;
+            searchFrom = hit + 1;
+            const after = matchIdentifierAt(source, hit, macro);
+            if (after < 0)
+                continue;
+            const parenIdx = skipWhitespace(source, after);
+            if (source.charCodeAt(parenIdx) === 0x28) {
+                const close = findMatchingParen(source, parenIdx);
+                if (close < 0)
+                    continue;
+                eraseRange(chars, hit, close + 1);
+            }
+            else {
+                eraseRange(chars, hit, after);
+            }
+        }
+    }
+    for (const re of [DELEGATE_MACRO_RE, API_MACRO_RE]) {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(source)) !== null) {
+            const start = match.index;
+            let end = start + match[0].length;
+            if (re === DELEGATE_MACRO_RE) {
+                const parenIdx = skipWhitespace(source, end);
+                if (source.charCodeAt(parenIdx) === 0x28) {
+                    const close = findMatchingParen(source, parenIdx);
+                    if (close >= 0)
+                        end = close + 1;
+                }
+            }
+            eraseRange(chars, start, end);
+        }
+    }
+    return chars.join('');
+}