ultimate-unreal-engine-mcp 0.1.0

package/dist/parsers/cpp-class-index.js

@@ -0,0 +1,230 @@
+// src/parsers/cpp-class-index.ts
+// Project-wide class scanner and query engine for UE C++ headers.
+//
+// Scans Source/**/*.h files, parses each with cpp-parser.ts, and provides:
+//   - buildIndex(projectRoot): scans disk with mtime caching
+//   - buildIndexFromMap(files): in-memory variant for testing (no fs I/O)
+//   - CppClassIndex: query methods (getClassHierarchy, getIncludes, findClassFile)
+//   - clearIndexCache(): reset mtime cache between test runs
+//
+// Design rules (Phase 4 / CONTEXT.md):
+//   - No console.log — all log output via console.error only
+//   - T-04-04 mitigated: cycle detection via visited Set in getClassHierarchy
+//   - T-04-05: mtime caching keeps repeated calls O(1) per unchanged file
+//   - buildIndex() returns IndexBuildResult discriminated union — never throws
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseCppFile } from './cpp-parser.js';
+const mtimeCache = new Map();
+/**
+ * Clears the mtime cache. Used in tests to ensure isolation between runs.
+ */
+export function clearIndexCache() {
+    mtimeCache.clear();
+}
+// ---------------------------------------------------------------------------
+// Internal: build CppClassIndex from a Map<className, ClassIndexEntry>
+// ---------------------------------------------------------------------------
+function makeCppClassIndex(entries) {
+    return {
+        entries,
+        /**
+         * Returns the inheritance chain starting from className.
+         * Stops when parent is not in index or a cycle is detected.
+         * T-04-04: visited Set prevents infinite loop on circular inheritance.
+         *
+         * Rule: always add the starting class. For subsequent parents, only add
+         * them if they exist in the index (stop without adding unknown parents).
+         * Exception for cycle detection: if a class appears in visited, stop
+         * without adding it again.
+         */
+        getClassHierarchy(className) {
+            const chain = [];
+            const visited = new Set();
+            // Always add the starting class regardless of whether it's in the index
+            chain.push(className);
+            visited.add(className);
+            // Look up the entry for the starting class
+            let entry = entries.get(className);
+            if (!entry || !entry.parentClass) {
+                return chain;
+            }
+            let current = entry.parentClass;
+            while (true) {
+                if (visited.has(current)) {
+                    // Cycle detected — stop WITHOUT adding the duplicate
+                    break;
+                }
+                const currentEntry = entries.get(current);
+                if (!currentEntry) {
+                    // Parent not in index — stop WITHOUT adding it to chain
+                    break;
+                }
+                // Parent is in index — add it and continue traversal
+                chain.push(current);
+                visited.add(current);
+                if (!currentEntry.parentClass) {
+                    // No further parent — chain ends here
+                    break;
+                }
+                current = currentEntry.parentClass;
+            }
+            return chain;
+        },
+        /**
+         * Returns the #include list for the entry's header.
+         * Returns [] if className is not in the index.
+         */
+        getIncludes(className) {
+            const entry = entries.get(className);
+            return entry ? entry.includes : [];
+        },
+        /**
+         * Returns header and source paths for a class.
+         * Returns null if className is not in the index.
+         */
+        findClassFile(className) {
+            const entry = entries.get(className);
+            if (!entry)
+                return null;
+            return { header: entry.headerPath, source: entry.sourcePath };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: parse a single header content and produce ClassIndexEntry[]
+// ---------------------------------------------------------------------------
+function buildEntriesFromContent(headerPath, content, sourcePath) {
+    const parseResult = parseCppFile(content);
+    if (!parseResult.success) {
+        return { entries: [], errorCount: 1 };
+    }
+    const { classes, includes } = parseResult.data;
+    const entries = classes.map((cls) => ({
+        className: cls.name,
+        headerPath,
+        sourcePath: sourcePath(cls.name),
+        parentClass: cls.parentClass,
+        includes,
+        specifiers: cls.specifiers,
+    }));
+    return { entries, errorCount: 0 };
+}
+// ---------------------------------------------------------------------------
+// buildIndexFromMap — in-memory test variant (no fs I/O)
+// ---------------------------------------------------------------------------
+/**
+ * Builds a CppClassIndex from an in-memory map of { absoluteFilePath: fileContent }.
+ * Does NOT touch the filesystem — intended for testing.
+ * No mtime caching in this variant (always parses fresh).
+ */
+export async function buildIndexFromMap(files) {
+    const allEntries = new Map();
+    let fileCount = 0;
+    let errorCount = 0;
+    for (const [filePath, content] of Object.entries(files)) {
+        fileCount++;
+        // Derive the directory for potential .cpp companion lookup
+        const dir = path.dirname(filePath);
+        const { entries, errorCount: fileErrors } = buildEntriesFromContent(filePath, content, (className) => {
+            // In-memory: check if a .cpp file exists in the provided map
+            const candidateCpp = path.join(dir, `${className}.cpp`);
+            return files[candidateCpp] !== undefined ? candidateCpp : null;
+        });
+        errorCount += fileErrors;
+        for (const entry of entries) {
+            allEntries.set(entry.className, entry);
+        }
+    }
+    return {
+        success: true,
+        index: makeCppClassIndex(allEntries),
+        fileCount,
+        errorCount,
+    };
+}
+// ---------------------------------------------------------------------------
+// buildIndex — real filesystem variant with mtime caching
+// ---------------------------------------------------------------------------
+/**
+ * Scans {projectRoot}/Source/**\/*.h, parses each header, and builds an index.
+ *
+ * Returns IndexBuildResult — never throws.
+ * - success=true even if individual headers fail (errorCount tracks failures)
+ * - success=false only if the Source/ directory itself cannot be read
+ *
+ * Mtime caching: parsed results are cached per absolute path. Re-scanning an
+ * unchanged file (same mtime) reuses cached entries without re-parsing.
+ */
+export async function buildIndex(projectRoot) {
+    const sourceDir = path.join(projectRoot, 'Source');
+    let files;
+    try {
+        const allEntries = await fs.promises.readdir(sourceDir, { recursive: true });
+        files = allEntries
+            .filter((f) => typeof f === 'string' && f.endsWith('.h'))
+            .map((f) => path.join(sourceDir, f));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `Cannot read Source/ directory: ${msg}` };
+    }
+    const allEntries = new Map();
+    let fileCount = 0;
+    let errorCount = 0;
+    for (const headerPath of files) {
+        fileCount++;
+        // Stat for mtime caching
+        let mtime;
+        try {
+            const stat = await fs.promises.stat(headerPath);
+            mtime = stat.mtimeMs;
+        }
+        catch {
+            // Cannot stat — skip with error
+            errorCount++;
+            continue;
+        }
+        const cached = mtimeCache.get(headerPath);
+        let entries;
+        if (cached && cached.mtime === mtime) {
+            // Cache hit — reuse without re-parsing
+            entries = cached.entries;
+        }
+        else {
+            // Cache miss — read and parse
+            let content;
+            try {
+                content = await fs.promises.readFile(headerPath, 'utf-8');
+            }
+            catch {
+                errorCount++;
+                continue;
+            }
+            const dir = path.dirname(headerPath);
+            const result = buildEntriesFromContent(headerPath, content, (className) => {
+                const candidateCpp = path.join(dir, `${className}.cpp`);
+                try {
+                    fs.accessSync(candidateCpp);
+                    return candidateCpp;
+                }
+                catch {
+                    return null;
+                }
+            });
+            errorCount += result.errorCount;
+            entries = result.entries;
+            // Update cache
+            mtimeCache.set(headerPath, { mtime, entries });
+        }
+        for (const entry of entries) {
+            allEntries.set(entry.className, entry);
+        }
+    }
+    return {
+        success: true,
+        index: makeCppClassIndex(allEntries),
+        fileCount,
+        errorCount,
+    };
+}

package/dist/parsers/cpp-parser.js

@@ -0,0 +1,369 @@
+// src/parsers/cpp-parser.ts
+// Purpose-built TypeScript regex parser for UE C++ macro grammar.
+//
+// Parses a small, well-defined subset of C++ that UHT (Unreal Header Tool) emits:
+//   - UCLASS / UPROPERTY / UFUNCTION macros with specifiers and meta=(...)
+//   - Inheritance declarations: class AMyActor : public AActor
+//   - #include directives (both quoted and angled)
+//
+// This is NOT a general C++ parser — it targets UE macro patterns only.
+// Design rules (Phase 4 context):
+//   - Pure string processing — no fs imports, no eval, never throws
+//   - Returns discriminated union ParseResult<T>
+//   - All output goes to console.error (never console.log)
+//   - T-04-02 mitigation: balanced-paren collector capped at 500 lines
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const INCLUDE_RE = /^\s*#include\s+["<]([^">]+)[">]/;
+const MACRO_START_RE = /^\s*(UCLASS|UPROPERTY|UFUNCTION)\s*\(/;
+/**
+ * Collects a balanced-parenthesis macro argument string starting from the
+ * opening paren found at `startLine`. The `lines` array must have the opening
+ * paren on lines[startLine]. Returns the inner content (excluding outer parens)
+ * and the index of the line containing the matching closing paren.
+ *
+ * T-04-02: Capped at 500 lines to prevent runaway loops on pathological input.
+ */
+function collectMacroArgs(lines, startLine) {
+    let depth = 0;
+    let collecting = false;
+    const parts = [];
+    const MAX_LINES = 500;
+    for (let i = startLine; i < lines.length && i - startLine <= MAX_LINES; i++) {
+        const line = lines[i];
+        for (let j = 0; j < line.length; j++) {
+            const ch = line[j];
+            if (ch === '(') {
+                depth++;
+                collecting = true;
+            }
+            else if (ch === ')') {
+                depth--;
+                if (depth === 0 && collecting) {
+                    // Capture everything collected so far as the full arg string
+                    parts.push(line.slice(0, j));
+                    // Remove the opening paren from the first segment
+                    const joined = parts.join('\n');
+                    // Strip everything up to and including the first '('
+                    const openIdx = joined.indexOf('(');
+                    const inner = openIdx >= 0 ? joined.slice(openIdx + 1) : joined;
+                    return { args: inner.trim(), endLine: i };
+                }
+            }
+        }
+        if (collecting) {
+            parts.push(line);
+        }
+    }
+    // Unclosed paren or exceeded 500 lines — return what we have
+    const joined = parts.join('\n');
+    const openIdx = joined.indexOf('(');
+    const inner = openIdx >= 0 ? joined.slice(openIdx + 1) : joined;
+    return { args: inner.trim(), endLine: Math.min(startLine + MAX_LINES, lines.length - 1) };
+}
+/**
+ * Parses a meta=(...) block from specifier text.
+ * Example: 'meta=(ClampMin="0", ClampMax="100")' → { ClampMin: "0", ClampMax: "100" }
+ */
+function parseMeta(metaBlock) {
+    const result = {};
+    // metaBlock is the content inside the outer parens, e.g. 'ClampMin="0", ClampMax="100"'
+    const inner = metaBlock.replace(/^\s*meta\s*=\s*\(/, '').replace(/\)\s*$/, '').trim();
+    if (!inner)
+        return result;
+    // Split on commas that are not inside nested parens or quotes
+    const pairs = splitTopLevel(inner, ',');
+    for (const pair of pairs) {
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx < 0)
+            continue;
+        const key = pair.slice(0, eqIdx).trim();
+        const val = pair.slice(eqIdx + 1).trim().replace(/^"(.*)"$/, '$1');
+        if (key)
+            result[key] = val;
+    }
+    return result;
+}
+/**
+ * Splits a string on a delimiter, but only at the top level
+ * (not inside nested parentheses or double-quoted strings).
+ */
+function splitTopLevel(text, delimiter) {
+    const parts = [];
+    let depth = 0;
+    let inString = false;
+    let current = '';
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '"' && text[i - 1] !== '\\') {
+            inString = !inString;
+            current += ch;
+        }
+        else if (!inString && ch === '(') {
+            depth++;
+            current += ch;
+        }
+        else if (!inString && ch === ')') {
+            depth--;
+            current += ch;
+        }
+        else if (!inString && depth === 0 && text.slice(i, i + delimiter.length) === delimiter) {
+            parts.push(current.trim());
+            current = '';
+            i += delimiter.length - 1;
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+/**
+ * Parses the args string from inside a UCLASS/UPROPERTY/UFUNCTION macro.
+ * Returns { specifiers, meta }.
+ * meta=(...) is extracted and NOT included in specifiers.
+ */
+function parseSpecifiersAndMeta(args) {
+    if (!args.trim())
+        return { specifiers: [], meta: {} };
+    const topLevel = splitTopLevel(args, ',');
+    const specifiers = [];
+    let meta = {};
+    for (const item of topLevel) {
+        const trimmed = item.trim();
+        if (!trimmed)
+            continue;
+        if (/^meta\s*=\s*\(/.test(trimmed)) {
+            meta = parseMeta(trimmed);
+        }
+        else {
+            specifiers.push(trimmed);
+        }
+    }
+    return { specifiers, meta };
+}
+/**
+ * Finds the next non-blank line index after `fromLine`.
+ * Returns -1 if none found.
+ */
+function nextNonBlankLine(lines, fromLine) {
+    for (let i = fromLine + 1; i < lines.length; i++) {
+        if (lines[i].trim().length > 0)
+            return i;
+    }
+    return -1;
+}
+/**
+ * Parses a property declaration line like:
+ *   "float Health;"
+ *   "AActor* TargetActor;"
+ *   "TArray<FHitResult> HitResults;"
+ * Returns { type, name } or null if unparseable.
+ */
+function parsePropertyDecl(declLine) {
+    const trimmed = declLine.trim();
+    // Remove trailing semicolons, UPROPERTY that might bleed in, etc.
+    const cleaned = trimmed.replace(/;.*$/, '').trim();
+    if (!cleaned)
+        return null;
+    // Handle template types: TArray<FHitResult> HitResults
+    // Strategy: find the last space-separated token as name, everything before as type
+    // But we must handle TArray<A, B> with inner commas
+    // Walk backwards through space-separated tokens respecting angle brackets
+    // Find last word boundary at depth 0 (not inside <> or ())
+    let depth = 0;
+    let nameStart = -1;
+    for (let i = cleaned.length - 1; i >= 0; i--) {
+        const ch = cleaned[i];
+        if (ch === '>' || ch === ')')
+            depth++;
+        else if (ch === '<' || ch === '(')
+            depth--;
+        else if (depth === 0 && ch === ' ') {
+            nameStart = i + 1;
+            break;
+        }
+    }
+    if (nameStart < 0)
+        return null;
+    const name = cleaned.slice(nameStart).trim();
+    const type = cleaned.slice(0, nameStart).trim();
+    if (!name || !type)
+        return null;
+    // Validate name is an identifier (word chars only)
+    if (!/^\w+$/.test(name))
+        return null;
+    return { type, name };
+}
+/**
+ * Parses a function declaration line like:
+ *   "void Attack();"
+ *   "void ServerFire(float Damage);"
+ *   "FMyStruct GetStuff();"
+ * Returns { returnType, name } or null if unparseable.
+ */
+function parseFunctionDecl(declLine) {
+    const trimmed = declLine.trim();
+    // Match: returnType functionName(...)
+    // The function name is the last word before '('
+    const funcMatch = trimmed.match(/^(.*?)\s+(\w+)\s*\(/);
+    if (!funcMatch)
+        return null;
+    const returnType = funcMatch[1].trim();
+    const name = funcMatch[2].trim();
+    if (!returnType || !name)
+        return null;
+    return { returnType, name };
+}
+// ---------------------------------------------------------------------------
+// Main parse function
+// ---------------------------------------------------------------------------
+/**
+ * Parses the content of a UE C++ header file.
+ *
+ * Returns ParseResult<ParsedCppFile> — never throws.
+ * T-04-01: Pure string processing, no eval/exec.
+ */
+export function parseCppFile(content) {
+    try {
+        // Guard against null/undefined input
+        if (content === null || content === undefined) {
+            return { success: true, data: { classes: [], includes: [], rawContent: '' } };
+        }
+        const rawContent = String(content);
+        if (!rawContent.trim()) {
+            return { success: true, data: { classes: [], includes: [], rawContent } };
+        }
+        const lines = rawContent.split('\n');
+        const includes = [];
+        let classes = [];
+        let activeClass = null;
+        let pendingMacro = null;
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            const lineNum = i + 1; // 1-based
+            // ---- #include extraction ----
+            const includeMatch = line.match(INCLUDE_RE);
+            if (includeMatch) {
+                let path = includeMatch[1];
+                // For angle-bracket includes, the regex captures inside the brackets.
+                // Re-check if it was angled: look at the original line
+                if (line.trim().startsWith('#include <')) {
+                    path = '<' + path + '>';
+                }
+                includes.push(path);
+                i++;
+                continue;
+            }
+            // ---- UCLASS / UPROPERTY / UFUNCTION detection ----
+            const macroMatch = line.match(MACRO_START_RE);
+            if (macroMatch) {
+                const macroKind = macroMatch[1];
+                const { args, endLine } = collectMacroArgs(lines, i);
+                const { specifiers, meta } = parseSpecifiersAndMeta(args);
+                pendingMacro = { kind: macroKind, specifiers, meta, line: lineNum };
+                i = endLine + 1;
+                continue;
+            }
+            // ---- Resolve pending UCLASS: look for class declaration ----
+            if (pendingMacro?.kind === 'UCLASS') {
+                // Look for: class NAME : public PARENT or class NAME
+                const classMatch = line.match(/\bclass\s+(?:\w+\s+)?(\w+)\s*(?::\s*public\s+(\w+))?/);
+                if (classMatch && !line.trim().startsWith('//')) {
+                    const className = classMatch[1];
+                    const parentClass = classMatch[2] ?? '';
+                    const newClass = {
+                        name: className,
+                        parentClass,
+                        specifiers: pendingMacro.specifiers,
+                        meta: pendingMacro.meta,
+                        properties: [],
+                        functions: [],
+                        line: lineNum,
+                    };
+                    // Push previous class if still open
+                    if (activeClass) {
+                        classes.push(activeClass.decl);
+                    }
+                    activeClass = { decl: newClass, braceDepth: 0, started: false };
+                    pendingMacro = null;
+                    i++;
+                    continue;
+                }
+            }
+            // ---- Track brace depth to know when we're inside a class body ----
+            if (activeClass) {
+                for (const ch of line) {
+                    if (ch === '{') {
+                        activeClass.braceDepth++;
+                        activeClass.started = true;
+                    }
+                    else if (ch === '}') {
+                        activeClass.braceDepth--;
+                        if (activeClass.started && activeClass.braceDepth <= 0) {
+                            // Class body closed
+                            classes.push(activeClass.decl);
+                            activeClass = null;
+                            break;
+                        }
+                    }
+                }
+            }
+            // ---- Resolve pending UPROPERTY / UFUNCTION ----
+            if (pendingMacro?.kind === 'UPROPERTY' || pendingMacro?.kind === 'UFUNCTION') {
+                const trimmed = line.trim();
+                // Skip blank lines, GENERATED_BODY(), braces
+                if (trimmed.length === 0 ||
+                    trimmed.startsWith('GENERATED_BODY') ||
+                    trimmed === '{' ||
+                    trimmed === '}') {
+                    i++;
+                    continue;
+                }
+                if (pendingMacro.kind === 'UPROPERTY') {
+                    const parsed = parsePropertyDecl(line);
+                    if (parsed && activeClass) {
+                        activeClass.decl.properties.push({
+                            name: parsed.name,
+                            type: parsed.type,
+                            specifiers: pendingMacro.specifiers,
+                            meta: pendingMacro.meta,
+                            line: pendingMacro.line,
+                        });
+                    }
+                    pendingMacro = null;
+                }
+                else if (pendingMacro.kind === 'UFUNCTION') {
+                    const parsed = parseFunctionDecl(line);
+                    if (parsed && activeClass) {
+                        activeClass.decl.functions.push({
+                            name: parsed.name,
+                            returnType: parsed.returnType,
+                            specifiers: pendingMacro.specifiers,
+                            meta: pendingMacro.meta,
+                            line: pendingMacro.line,
+                        });
+                    }
+                    pendingMacro = null;
+                }
+            }
+            i++;
+        }
+        // Flush any still-open class
+        if (activeClass) {
+            classes.push(activeClass.decl);
+        }
+        return {
+            success: true,
+            data: { classes, includes, rawContent },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `Parser internal error: ${msg}` };
+    }
+}