@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/resource-analysis.js

@@ -0,0 +1,153 @@
+import { findBoardPinByName, formatPinReference, getBoardPins } from './board-pin-utils.js';
+/**
+ * Unified hardware resource conflict analysis.
+ * Detects:
+ * 1. Pin Multiplexing Conflicts: Same pin used for GPIO and a Peripheral (I2C, SPI, UART).
+ * 2. Peripheral Instance Conflicts: Multiple peripherals sharing the same pins.
+ * 3. Board-Specific Hardware Warnings: Logic for specific pins (e.g. "Pin 13 has a built-in LED").
+ */
+export function analyzeResources(program, strategy) {
+    const diagnostics = [];
+    const usage = program.peripheralUsage;
+    const board = program.boardConstants;
+    if (!usage || !board)
+        return diagnostics;
+    // 1. Build Peripheral Pin Map from board definitions
+    const pinMap = buildPeripheralPinMap(board);
+    // 2. Track reported conflicts to avoid noise
+    const reported = new Set();
+    // 3. Check for GPIO vs Peripheral conflicts
+    for (const [pinName, functions] of pinMap) {
+        const boardPin = findBoardPinByName(pinName, board);
+        const pinNumber = boardPin?.number;
+        // Check if pin is used as GPIO
+        const isGpio = isPinUsedAsGpio(pinName, pinNumber, usage);
+        for (const func of functions) {
+            const isActive = isPeripheralActive(func.type, func.instance, usage);
+            if (isActive && isGpio && func.role !== 'cs') {
+                const peripheralName = getPeripheralName(func.type, func.instance);
+                const conflictKey = `gpio:${pinName}:${peripheralName}`;
+                if (!reported.has(conflictKey)) {
+                    reported.add(conflictKey);
+                    const pinRef = formatPinReference(pinName, boardPin);
+                    const suggestion = generateActionableSuggestion(pinName, peripheralName, func.role, board);
+                    diagnostics.push({
+                        severity: 'warning',
+                        message: `${pinRef} is configured as ${peripheralName} ${func.role.toUpperCase()}. Using it as GPIO may interfere with communication.\n   → ${suggestion}`,
+                        code: 'peripheral-pin-conflict',
+                        source: 'resource-analysis',
+                    });
+                }
+            }
+        }
+    }
+    // 4. Check for Peripheral vs Peripheral conflicts (e.g. I2C0 and SPI0 sharing pins - rare but possible on some boards)
+    // This is partially covered by the board-definition logic, but we can detect it here if two active
+    // peripherals use the same canonical pin name.
+    const activePinsToPeripheral = new Map();
+    for (const [pinName, functions] of pinMap) {
+        for (const func of functions) {
+            if (isPeripheralActive(func.type, func.instance, usage)) {
+                const peripheralName = getPeripheralName(func.type, func.instance);
+                if (activePinsToPeripheral.has(pinName) && activePinsToPeripheral.get(pinName) !== peripheralName) {
+                    const other = activePinsToPeripheral.get(pinName);
+                    const conflictKey = `ppp:${pinName}:${peripheralName}:${other}`;
+                    if (!reported.has(conflictKey)) {
+                        reported.add(conflictKey);
+                        diagnostics.push({
+                            severity: 'error',
+                            message: `Hardware Conflict: Pin '${pinName}' is required by both ${peripheralName} and ${other}.`,
+                            hint: `Move one of the peripherals to different pins if your board supports remapping, or avoid using both simultaneously.`,
+                            code: 'peripheral-peripheral-conflict',
+                            source: 'resource-analysis',
+                        });
+                    }
+                }
+                activePinsToPeripheral.set(pinName, peripheralName);
+            }
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Build a peripheral pin map from board constants.
+ */
+function buildPeripheralPinMap(boardConstants) {
+    const map = new Map();
+    const boardPins = getBoardPins(boardConstants);
+    const pinsByCanonicalName = new Map(boardPins.map(pin => [pin.name, pin]));
+    function addPin(pinName, func) {
+        const boardPin = pinsByCanonicalName.get(pinName);
+        const pinNames = boardPin ? [boardPin.name, ...boardPin.aliases] : [pinName];
+        for (const resolvedPinName of pinNames) {
+            const existing = map.get(resolvedPinName) ?? [];
+            existing.push(func);
+            map.set(resolvedPinName, existing);
+        }
+    }
+    // Helper to parse "0:sda=A4,scl=A5;1:sda=...,scl=..."
+    const parseBusData = (data, type) => {
+        if (typeof data !== 'string' || data.length === 0)
+            return;
+        for (const busStr of data.split(';')) {
+            const colonIdx = busStr.indexOf(':');
+            if (colonIdx === -1)
+                continue;
+            const instance = parseInt(busStr.slice(0, colonIdx), 10);
+            const pinsStr = busStr.slice(colonIdx + 1);
+            for (const pair of pinsStr.split(',')) {
+                const eqIdx = pair.indexOf('=');
+                if (eqIdx === -1)
+                    continue;
+                const role = pair.slice(0, eqIdx).trim();
+                const pinName = pair.slice(eqIdx + 1).trim();
+                if (pinName)
+                    addPin(pinName, { type, instance, role });
+            }
+        }
+    };
+    parseBusData(boardConstants.get('pins.i2c'), 'i2c');
+    parseBusData(boardConstants.get('pins.spi'), 'spi');
+    parseBusData(boardConstants.get('pins.uart'), 'uart');
+    return map;
+}
+function isPinUsedAsGpio(pinName, pinNumber, usage) {
+    if (usage.pinsUsed.has(pinName))
+        return true;
+    if (pinNumber !== undefined) {
+        if (usage.outputPins.has(pinNumber) || usage.inputPins.has(pinNumber) ||
+            usage.inputPullupPins.has(pinNumber) || usage.inputPulldownPins.has(pinNumber)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isPeripheralActive(type, instance, usage) {
+    switch (type) {
+        case 'i2c': return usage.i2c || usage.i2cInstancesUsed.has(instance);
+        case 'spi': return usage.spi || usage.spiInstancesUsed.has(instance);
+        case 'uart': return usage.uart || usage.uartInstancesUsed.has(instance);
+        default: return false;
+    }
+}
+function getPeripheralName(type, instance) {
+    switch (type) {
+        case 'i2c': return `I2C${instance}`;
+        case 'spi': return `SPI${instance}`;
+        case 'uart': return instance === 0 ? 'Serial' : `Serial${instance}`;
+        default: return 'Peripheral';
+    }
+}
+function generateActionableSuggestion(pinName, peripheralName, role, board) {
+    const roleUpper = role.toUpperCase();
+    if (peripheralName.startsWith('Serial')) {
+        return `Consider using a different pin for GPIO, or avoid calling ${peripheralName}.begin() if you need ${pinName} as GPIO.`;
+    }
+    if (roleUpper === 'SDA' || roleUpper === 'SCL') {
+        return `I2C requires ${roleUpper} on ${pinName}. Avoid using this pin for GPIO while I2C is active.`;
+    }
+    if (roleUpper === 'MOSI' || roleUpper === 'MISO' || roleUpper === 'SCK') {
+        return `SPI requires ${roleUpper} on ${pinName}. Use a different pin for GPIO, or avoid calling SPI.begin().`;
+    }
+    return `Avoid initializing ${peripheralName} if you need ${pinName} as GPIO.`;
+}

package/dist/ir/statement-to-ir.d.ts

@@ -0,0 +1,23 @@
+import ts from "typescript";
+import { Diagnostic } from "../types.js";
+import { StatementIR } from "../api/index.js";
+import { CppTypeHint } from "./type-resolution.js";
+import { PointerTracker } from "./build-ir-state.js";
+import { forInitializerToIR, incrementorToIR, lowerControlFlowStatement } from "./transformers/control-flow.js";
+export { forInitializerToIR, incrementorToIR, lowerControlFlowStatement };
+import { tryResolveHALMethod, resolveHALCallForVarInit, tryResolveHALExpression } from "./transformers/hal-call-resolver.js";
+export { tryResolveHALMethod, resolveHALCallForVarInit, tryResolveHALExpression };
+import { prescanArrayUsage, buildInlineForLoop } from "./transformers/array-methods.js";
+export { prescanArrayUsage, buildInlineForLoop };
+import { callToStatement } from "./transformers/call-statement.js";
+export { callToStatement };
+import { assignmentOperatorToString, updateLocalTypeFromAssignment, extractForInKeys, variableStatementToIR, collectPointerVars } from "./transformers/variables.js";
+export { assignmentOperatorToString, updateLocalTypeFromAssignment, extractForInKeys, variableStatementToIR, collectPointerVars };
+export declare function expressionStatementToIR(statement: ts.ExpressionStatement, fileName: string, sourceText: string, diagnostics: Diagnostic[], functionReturnTypes: Map<string, CppTypeHint>, localVariableTypes: Map<string, CppTypeHint>, pointerVars?: PointerTracker): StatementIR | undefined;
+export declare function lowerStatement(statement: ts.Statement, fileName: string, sourceText: string, diagnostics: Diagnostic[], functionReturnTypes: Map<string, CppTypeHint>, localVariableTypes: Map<string, CppTypeHint>, functionNameForDiagnostics: string, typeAliases?: Map<string, ts.TypeNode>, pointerVars?: PointerTracker): StatementIR[] | undefined;
+/**
+ * Hoist a nested function declaration to file scope.
+ * Creates a mangled name (parent__inner) and registers it in the alias map
+ * so that call sites within the parent function get rewritten.
+ */
+export declare function lowerStatementList(statements: readonly ts.Statement[] | ts.NodeArray<ts.Statement>, fileName: string, sourceText: string, diagnostics: Diagnostic[], functionReturnTypes: Map<string, CppTypeHint>, localVariableTypes: Map<string, CppTypeHint>, functionNameForDiagnostics: string, typeAliases?: Map<string, ts.TypeNode>, pointerVars?: PointerTracker): StatementIR[];

package/dist/ir/statement-to-ir.js

@@ -0,0 +1,349 @@
+import ts from "typescript";
+import { isStringEnum } from "../api/shared/index.js";
+import { extractNodeComments, makeDiagnostic, makeSourceSpan } from "./ast-node-utils.js";
+import { isCompileTimeOnlyCallName, isCompileTimeOnlyClassName } from "./compile-time-only.js";
+import { TYPED_ARRAY_ELEMENT_MAP, hoistedNestedEnums, hoistedNestedInterfaces, hoistedNestedTypeAliases, nestedFunctionAliases, nestedClassAliases, mutableArrayVars, arrayLiteralSizes, activeEnumNames, activeStringEnumNames, resetFunctionScopeState } from "./build-ir-state.js";
+import { getCurrentIrTypeScope, bindIrTypeScopeLocals } from "./symbol-types.js";
+import { renderExprAsText } from "./render-expr.js";
+import { expressionToIR } from "./expression-to-ir.js";
+import { enumDeclarationToIR, interfaceDeclarationToIR, typeAliasDeclarationToIR } from "./declaration-builders.js";
+import { forInitializerToIR, incrementorToIR, lowerControlFlowStatement } from "./transformers/control-flow.js";
+export { forInitializerToIR, incrementorToIR, lowerControlFlowStatement };
+import { expressionStatementToIR as delegateExpressionStatementToIR } from "./transformers/expressions.js";
+import { tryResolveHALMethod, resolveHALCallForVarInit, tryResolveHALExpression } from "./transformers/hal-call-resolver.js";
+import { resolveElementValue } from "./transformers/ui-call-resolver.js";
+export { tryResolveHALMethod, resolveHALCallForVarInit, tryResolveHALExpression };
+import { hoistNestedFunction, hoistNestedClass } from "./function-builder.js";
+import { prescanArrayUsage, buildInlineForLoop } from "./transformers/array-methods.js";
+export { prescanArrayUsage, buildInlineForLoop };
+import { callToStatement } from "./transformers/call-statement.js";
+export { callToStatement };
+import { assignmentOperatorToString, updateLocalTypeFromAssignment, extractForInKeys, variableStatementToIR, collectPointerVars } from "./transformers/variables.js";
+export { assignmentOperatorToString, updateLocalTypeFromAssignment, extractForInKeys, variableStatementToIR, collectPointerVars };
+export function expressionStatementToIR(statement, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, pointerVars = new Map()) {
+    return delegateExpressionStatementToIR(statement, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, pointerVars);
+}
+export function lowerStatement(statement, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars = new Map()) {
+    if (ts.isExpressionStatement(statement)) {
+        // Handle arr.forEach(arrowFn) as a standalone statement → inline loop
+        if (ts.isCallExpression(statement.expression) &&
+            ts.isPropertyAccessExpression(statement.expression.expression) &&
+            statement.expression.expression.name.text === "forEach" &&
+            ts.isIdentifier(statement.expression.expression.expression)) {
+            const srcName = statement.expression.expression.expression.text;
+            const srcSize = arrayLiteralSizes.get(srcName);
+            const arrowFn = statement.expression.arguments[0];
+            if (srcSize !== undefined && arrowFn && (ts.isArrowFunction(arrowFn) || ts.isFunctionExpression(arrowFn))) {
+                const param = arrowFn.parameters[0];
+                const paramName = param && ts.isIdentifier(param.name) ? param.name.text : "__x";
+                const span = makeSourceSpan(statement, fileName, sourceText);
+                const comments = extractNodeComments(statement, sourceText);
+                if (!ts.isBlock(arrowFn.body)) {
+                    // Expression body
+                    const bodyIR = expressionToIR(arrowFn.body, sourceText, diagnostics);
+                    return [{
+                            kind: "for",
+                            sourceSpan: span,
+                            leadingComments: comments.leadingComments,
+                            trailingComments: comments.trailingComments,
+                            initializer: { kind: "var_decl", sourceSpan: span, name: "__tc_i", storage: "let", cppType: "int", initializer: { kind: "number", value: 0 } },
+                            condition: { kind: "binary", left: { kind: "identifier", value: "__tc_i" }, operator: "<", right: { kind: "number", value: srcSize } },
+                            increment: { kind: "update", sourceSpan: span, target: "__tc_i", operator: "++", prefix: false },
+                            body: [
+                                { kind: "var_decl", sourceSpan: span, name: paramName, storage: "const", cppType: "auto",
+                                    initializer: { kind: "raw", value: `${srcName}[__tc_i]` } },
+                                { kind: "var_decl", sourceSpan: span, name: "__tc_result", storage: "let", cppType: "auto", initializer: bodyIR },
+                            ],
+                        }];
+                }
+                else {
+                    // Block body — lower statements and prepend param decl
+                    const blockStatements = lowerStatementList(arrowFn.body.statements, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars);
+                    return [{
+                            kind: "for",
+                            sourceSpan: span,
+                            leadingComments: comments.leadingComments,
+                            trailingComments: comments.trailingComments,
+                            initializer: { kind: "var_decl", sourceSpan: span, name: "__tc_i", storage: "let", cppType: "int", initializer: { kind: "number", value: 0 } },
+                            condition: { kind: "binary", left: { kind: "identifier", value: "__tc_i" }, operator: "<", right: { kind: "number", value: srcSize } },
+                            increment: { kind: "update", sourceSpan: span, target: "__tc_i", operator: "++", prefix: false },
+                            body: [
+                                { kind: "var_decl", sourceSpan: span, name: paramName, storage: "const", cppType: "auto",
+                                    initializer: { kind: "raw", value: `${srcName}[__tc_i]` } },
+                                ...blockStatements,
+                            ],
+                        }];
+                }
+            }
+        }
+        // Check for compile-time-only calls first (e.g., registerPlatformStrategy())
+        // These are registration calls that don't need C++ emission
+        if (ts.isCallExpression(statement.expression)) {
+            const call = statement.expression;
+            if (ts.isIdentifier(call.expression)) {
+                const calleeName = call.expression.text;
+                if (isCompileTimeOnlyCallName(calleeName)) {
+                    return []; // Skip silently - no C++ emission needed
+                }
+            }
+            // Also check for method calls like "something.register()" that are compile-time only
+            if (ts.isPropertyAccessExpression(call.expression)) {
+                const method = call.expression.name.text;
+                if (isCompileTimeOnlyCallName(method)) {
+                    return [];
+                }
+            }
+        }
+        // Check for new expressions that are compile-time only (e.g., new NativeStrategy())
+        if (ts.isNewExpression(statement.expression)) {
+            // New expressions at top level in board packages are typically compile-time only
+            // Check if it's a known strategy type
+            if (ts.isIdentifier(statement.expression.expression)) {
+                const className = statement.expression.expression.text;
+                if (isCompileTimeOnlyClassName(className)) {
+                    return []; // Skip silently
+                }
+            }
+        }
+        // ── UI element .value write: screen.led.value = 1 ────────────────────
+        // Lowers to __ui_nodes[N].value = X; ui_mark_dirty(N);
+        if (ts.isBinaryExpression(statement.expression) &&
+            statement.expression.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isPropertyAccessExpression(statement.expression.left) &&
+            statement.expression.left.name.text === "value" &&
+            ts.isPropertyAccessExpression(statement.expression.left.expression) &&
+            ts.isIdentifier(statement.expression.left.expression.expression)) {
+            const treeName = statement.expression.left.expression.expression.text;
+            const elemId = statement.expression.left.expression.name.text;
+            const nodeIdx = resolveElementValue(treeName, elemId);
+            if (nodeIdx !== undefined) {
+                const valIR = expressionToIR(statement.expression.right, sourceText, diagnostics, pointerVars);
+                const valText = renderExprAsText(valIR);
+                return [{
+                        kind: "call",
+                        sourceSpan: makeSourceSpan(statement, fileName, sourceText),
+                        callee: `__RAW_STMT____ui_nodes[${nodeIdx}].value = ${valText}; ui_mark_dirty(${nodeIdx});`,
+                        args: [],
+                    }];
+            }
+        }
+        // ── UI element .text write: screen.ssid.text = "x" ──────────────────
+        // Lowers to strncpy(__ui_nodes[N].textBuffer, "x", UI_TEXT_BUF);
+        //         __ui_nodes[N].textBuffer[UI_TEXT_BUF] = 0; ui_mark_dirty(N);
+        if (ts.isBinaryExpression(statement.expression) &&
+            statement.expression.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isPropertyAccessExpression(statement.expression.left) &&
+            statement.expression.left.name.text === "text" &&
+            ts.isPropertyAccessExpression(statement.expression.left.expression) &&
+            ts.isIdentifier(statement.expression.left.expression.expression)) {
+            const treeName = statement.expression.left.expression.expression.text;
+            const elemId = statement.expression.left.expression.name.text;
+            const nodeIdx = resolveElementValue(treeName, elemId);
+            if (nodeIdx !== undefined) {
+                const valIR = expressionToIR(statement.expression.right, sourceText, diagnostics, pointerVars);
+                const valText = renderExprAsText(valIR);
+                return [{
+                        kind: "call",
+                        sourceSpan: makeSourceSpan(statement, fileName, sourceText),
+                        callee: `__RAW_STMT__strncpy(__ui_nodes[${nodeIdx}].textBuffer, ${valText}, UI_TEXT_BUF); __ui_nodes[${nodeIdx}].textBuffer[UI_TEXT_BUF] = 0; ui_mark_dirty(${nodeIdx});`,
+                        args: [],
+                    }];
+            }
+        }
+        const loweredExpression = expressionStatementToIR(statement, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, pointerVars);
+        return loweredExpression ? [loweredExpression] : undefined;
+    }
+    if (ts.isVariableStatement(statement)) {
+        return variableStatementToIR(statement, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, typeAliases, pointerVars, functionNameForDiagnostics, lowerStatementList);
+    }
+    const controlFlowLowered = lowerControlFlowStatement(statement, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars);
+    if (controlFlowLowered !== null) {
+        return controlFlowLowered;
+    }
+    diagnostics.push(makeDiagnostic(sourceText, statement.pos, `Unsupported statement in function '${functionNameForDiagnostics}'.`, "error", "TS2CPP_UNSUPPORTED_STMT"));
+    return undefined;
+}
+/**
+ * Hoist a nested function declaration to file scope.
+ * Creates a mangled name (parent__inner) and registers it in the alias map
+ * so that call sites within the parent function get rewritten.
+ */
+// ---------------------------------------------------------------------------
+// Array method pre-scan
+// ---------------------------------------------------------------------------
+// Methods that require StaticArray promotion (not all are mutating — indexOf is read-only
+// but needs StaticArray since C arrays don't have an indexOf method).
+export function lowerStatementList(statements, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars = new Map()) {
+    const lowered = [];
+    const nestedNames = [];
+    const nestedClassNames = [];
+    // Phase 1: Pre-scan for nested function declarations — register aliases only.
+    // This ensures sibling functions can reference each other.
+    for (const statement of statements) {
+        if (ts.isFunctionDeclaration(statement) && statement.name) {
+            const originalName = statement.name.text;
+            const safeParentName = functionNameForDiagnostics.replace(/\./g, "_");
+            const mangledName = `${safeParentName}__${originalName}`;
+            nestedFunctionAliases.set(originalName, mangledName);
+            nestedNames.push(originalName);
+        }
+        if (ts.isClassDeclaration(statement) && statement.name) {
+            const originalName = statement.name.text;
+            const safeParentName = functionNameForDiagnostics.replace(/\./g, "_");
+            if (safeParentName) {
+                const mangledName = `${safeParentName}__${originalName}`;
+                nestedClassAliases.set(originalName, mangledName);
+                nestedClassNames.push(originalName);
+            }
+        }
+    }
+    // Phase 1.5: Collect local type aliases into the shared map so that
+    // nested function return types can resolve generic mapped types etc.
+    if (typeAliases) {
+        for (const statement of statements) {
+            if (ts.isTypeAliasDeclaration(statement)) {
+                typeAliases.set(statement.name.text, statement.type);
+            }
+        }
+    }
+    // Phase 1.6: Pre-scan for enum declarations (top-level within this scope and
+    // nested inside functions) so that string-concat chain detection during
+    // lowering knows which enum-typed variables are string-bearing (string enums
+    // lower to const char*). Must run BEFORE hoisting/lowers.
+    for (const statement of statements) {
+        const collectEnums = (node) => {
+            if (ts.isEnumDeclaration(node) && node.name) {
+                activeEnumNames.add(node.name.text);
+                // Determine string-enum-ness from the declaration.
+                let allString = true;
+                let any = false;
+                for (const member of node.members) {
+                    if (member.initializer && ts.isStringLiteral(member.initializer)) {
+                        any = true;
+                    }
+                    else if (member.initializer && !ts.isStringLiteral(member.initializer)) {
+                        allString = false;
+                    }
+                    else {
+                        allString = false;
+                    }
+                }
+                if (any && allString) {
+                    activeStringEnumNames.add(node.name.text);
+                }
+            }
+        };
+        collectEnums(statement);
+        ts.forEachChild(statement, collectEnums);
+    }
+    // Phase 2: Hoist nested functions (process their bodies).
+    for (const statement of statements) {
+        if (ts.isFunctionDeclaration(statement) && statement.name) {
+            hoistNestedFunction(statement, fileName, sourceText, diagnostics, functionReturnTypes, functionNameForDiagnostics, typeAliases, pointerVars, lowerStatementList);
+        }
+    }
+    // Phase 2.5: Hoist nested class declarations.
+    for (const statement of statements) {
+        if (ts.isClassDeclaration(statement) && statement.name) {
+            hoistNestedClass(statement, fileName, sourceText, diagnostics, functionReturnTypes, functionNameForDiagnostics, typeAliases, pointerVars, lowerStatementList);
+        }
+    }
+    // Phase 2.6: Hoist nested enum declarations.
+    for (const statement of statements) {
+        if (ts.isEnumDeclaration(statement)) {
+            const enumIR = enumDeclarationToIR(statement, fileName, sourceText);
+            if (enumIR && !hoistedNestedEnums.some(e => e.name === enumIR.name)) {
+                hoistedNestedEnums.push(enumIR);
+                // Register string-enum-ness so concat-chain detection (expression-to-ir)
+                // recognizes variables of this type as string-bearing.
+                if (isStringEnum(enumIR)) {
+                    activeStringEnumNames.add(enumIR.name);
+                }
+            }
+        }
+    }
+    // Phase 2.6b: Hoist local interface and type alias declarations.
+    // These are type-only but needed for C++ struct generation when used as return types.
+    const scopeName = functionNameForDiagnostics
+        ? `${functionNameForDiagnostics.replace(/\./g, "_")}__types`
+        : undefined;
+    for (const statement of statements) {
+        if (ts.isInterfaceDeclaration(statement) && statement.name) {
+            const ifaceIR = interfaceDeclarationToIR(statement, fileName, sourceText, typeAliases ?? new Map());
+            if (ifaceIR && !hoistedNestedInterfaces.some(i => i.name === ifaceIR.name)) {
+                if (scopeName)
+                    ifaceIR.parentScope = scopeName;
+                hoistedNestedInterfaces.push(ifaceIR);
+            }
+        }
+        if (ts.isTypeAliasDeclaration(statement)) {
+            const aliasIR = typeAliasDeclarationToIR(statement, fileName, sourceText, typeAliases ?? new Map());
+            if (aliasIR && !hoistedNestedTypeAliases.some(a => a.name === aliasIR.name)) {
+                hoistedNestedTypeAliases.push(aliasIR);
+            }
+        }
+    }
+    // Collect pointer variables from this scope (vars initialized with 'new')
+    const scopePointerVars = new Map();
+    for (const statement of statements) {
+        if (ts.isVariableStatement(statement)) {
+            for (const decl of statement.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name) && decl.initializer && ts.isNewExpression(decl.initializer)) {
+                    const ctorText = decl.initializer.expression && ts.isIdentifier(decl.initializer.expression)
+                        ? decl.initializer.expression.text : "";
+                    if (!TYPED_ARRAY_ELEMENT_MAP[ctorText]) {
+                        scopePointerVars.set(decl.name.text, ctorText);
+                    }
+                }
+            }
+        }
+    }
+    // Phase 2.7: Pre-scan for array methods requiring StaticArray promotion.
+    // Clear function-scoped state so variables from previous functions don't leak,
+    // but preserve file-level mutable array tracking (populated by build-ir.ts pre-scan).
+    const savedMutableArrayVars = new Set(mutableArrayVars);
+    const savedArrayLiteralSizes = new Map(arrayLiteralSizes);
+    resetFunctionScopeState();
+    for (const v of savedMutableArrayVars)
+        mutableArrayVars.add(v);
+    for (const [k, v] of savedArrayLiteralSizes)
+        arrayLiteralSizes.set(k, v);
+    // resetFunctionScopeState re-seeded scope.locals from classFields. Now bind
+    // the threaded localVariableTypes map as the scope's locals storage (folding
+    // both the re-seeded classFields entries and any entries the threaded map
+    // already carried, e.g. function parameters). After this, the threaded
+    // `localVariableTypes` param and getCurrentIrTypeScope().locals are the SAME
+    // Map, so writes through either are visible to both — eliminating the old
+    // shadow-sync that copied localVariableTypes into the global activeLocalTypes.
+    const scope = getCurrentIrTypeScope();
+    if (scope) {
+        bindIrTypeScopeLocals(scope, localVariableTypes);
+    }
+    for (const statement of statements) {
+        prescanArrayUsage(statement);
+    }
+    // Phase 3: Process remaining (non-function, non-class) statements.
+    for (const statement of statements) {
+        if (ts.isFunctionDeclaration(statement)) {
+            continue; // Already hoisted
+        }
+        if (ts.isClassDeclaration(statement)) {
+            continue; // Already hoisted
+        }
+        if (ts.isEnumDeclaration(statement)) {
+            continue; // Already hoisted
+        }
+        const result = lowerStatement(statement, fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, scopePointerVars);
+        if (result) {
+            lowered.push(...result);
+        }
+    }
+    // Phase 4: Clean up aliases so they don't leak to sibling scopes.
+    for (const name of nestedNames) {
+        nestedFunctionAliases.delete(name);
+    }
+    for (const name of nestedClassNames) {
+        nestedClassAliases.delete(name);
+    }
+    return lowered;
+}

package/dist/ir/symbol-table.d.ts

@@ -0,0 +1,68 @@
+import type { ProgramIR } from "../api/index.js";
+/**
+ * Per-class accessor map: member name → whether it is a getter, setter, or
+ * both. Keyed by class name, matching the old allClassAccessors shape.
+ */
+export type ClassAccessors = Map<string, "getter" | "setter" | "both">;
+export interface SymbolTable {
+    /** className/interfaceName → fieldName → cppType. Replaces allClassFieldTypes
+     *  and the per-file interfaceFieldTypes cross-module portion. Includes
+     *  extendsClass-inherited fields once resolveInheritance runs. */
+    classFieldTypes: Map<string, Map<string, string>>;
+    /** className → accessor map. Replaces allClassAccessors. */
+    classAccessors: Map<string, ClassAccessors>;
+    /** function name → return cppType. Replaces allFunctionReturnTypes. */
+    functionReturnTypes: Map<string, string>;
+    /** top-level variable name → cppType (non-"auto" only). Replaces
+     *  allVariableTypes. */
+    variableTypes: Map<string, string>;
+    /** All class names across the aggregated files. Replaces allClassNames. */
+    classNames: Set<string>;
+    /** className → parent class name (the `extends X` target). Needed by
+     *  resolveInheritance to copy parent fields into children; not present in
+     *  the old ad-hoc maps (it was read from programIR.classes in the second
+     *  pass) so it is retained here to keep inheritance resolvable from the
+     *  aggregated table alone. */
+    extends: Map<string, string>;
+}
+export declare function createSymbolTable(): SymbolTable;
+/**
+ * Build a SymbolTable from a single file's ProgramIR. This is the per-file
+ * view; cross-file aggregation is done by mergeSymbolTable.
+ *
+ * Mirrors the old transpile.ts:612-666 first pass:
+ *   - class fields, interface fields, accessors, function return types, and
+ *     non-"auto" top-level variable types are collected
+ *   - extendsClass relationships are recorded for the post-merge inheritance
+ *     pass (the old code read them from programIR.classes directly)
+ * Accessor kind merge rule: getter+setter on the same name → "both".
+ *
+ * Does NOT fold parent fields into children yet — that happens once, after
+ * all files are merged, in resolveInheritance (mirroring the old two-pass
+ * structure where the second pass ran after the first pass over all files).
+ */
+export declare function buildSymbolTable(program: ProgramIR): SymbolTable;
+/**
+ * Fold one SymbolTable into an accumulating cross-module table. This is the
+ * merge used during Pass 1 of transpile.ts to build the cross-file view from
+ * every file's per-file table.
+ *
+ * Field-type and accessor entries are merged (later files add to existing
+ * class entries); function return types and variable types are last-write-wins
+ * (matching the old Map.set behavior); class names are unioned; extends
+ * relationships are last-write-wins.
+ */
+export declare function mergeSymbolTable(target: SymbolTable, source: SymbolTable): SymbolTable;
+/**
+ * Apply extendsClass field inheritance across an aggregated SymbolTable.
+ * Mirrors the old transpile.ts:668-688 SECOND pass: for each class that
+ * extends a parent present in the table, copy any parent fields the child does
+ * not already declare. Must run AFTER all files have been merged so cross-file
+ * parents are visible.
+ *
+ * Merge rule (preserved exactly): `!childFields.has(fname)` — a child's own
+ * field declaration wins over the parent's. If the child has no field entry at
+ * all but the parent does, a fresh entry seeded entirely from the parent is
+ * created (mirroring the old `else if (parentFields && !childFields)` branch).
+ */
+export declare function resolveInheritance(table: SymbolTable): void;