@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/pwm-timer-sharing.js

@@ -0,0 +1,93 @@
+import { findBoardPinByName, formatPinReference } from './board-pin-utils.js';
+function extractTimerId(role, timerField) {
+    // Prefer explicit timer field from board definition
+    if (timerField) {
+        return timerField;
+    }
+    if (!role) {
+        return undefined;
+    }
+    // Fall back to parsing AVR OC register naming convention
+    const match = role.match(/^OC(\d+)[A-Z]?$/i);
+    return match ? `timer${match[1]}` : undefined;
+}
+function getPwmTimerPins(boardConstants) {
+    if (!boardConstants) {
+        return [];
+    }
+    const pinsByIndex = new Map();
+    for (const [key, value] of boardConstants) {
+        const nameMatch = key.match(/^pins\.all\.(\d+)\.name$/);
+        if (nameMatch && typeof value === 'string') {
+            const pinIndex = nameMatch[1];
+            const numberValue = boardConstants.get(`pins.all.${pinIndex}.number`);
+            const aliasesValue = boardConstants.get(`pins.all.${pinIndex}.aliases`);
+            const aliases = typeof aliasesValue === 'string' && aliasesValue.length > 0
+                ? aliasesValue.split(',').map(entry => entry.trim()).filter(Boolean)
+                : [];
+            pinsByIndex.set(pinIndex, {
+                pinNumber: typeof numberValue === 'number' ? numberValue : Number(pinIndex),
+                canonicalName: value,
+                aliases,
+                timerId: '',
+            });
+        }
+    }
+    for (const [key, value] of boardConstants) {
+        const typeMatch = key.match(/^pins\.all\.(\d+)\.functions\.\d+\.type$/);
+        if (!typeMatch || value !== 'pwm') {
+            continue;
+        }
+        const pinIndex = typeMatch[1];
+        const roleKey = key.replace(/\.type$/, '.role');
+        const timerKey = key.replace(/\.type$/, '.timer');
+        const timerId = extractTimerId(boardConstants.get(roleKey), boardConstants.get(timerKey));
+        if (!timerId) {
+            continue;
+        }
+        const pin = pinsByIndex.get(pinIndex);
+        if (pin) {
+            pin.timerId = timerId;
+        }
+    }
+    return Array.from(pinsByIndex.values()).filter(pin => pin.timerId.length > 0);
+}
+export function validatePWMTimerSharing(usage, boardConstants) {
+    if (usage.pwmPinsUsed.size < 2 || !boardConstants) {
+        return [];
+    }
+    const boardName = boardConstants.get('name');
+    const boardLabel = typeof boardName === 'string' && boardName.length > 0
+        ? ` on ${boardName}`
+        : '';
+    const pins = getPwmTimerPins(boardConstants);
+    const pinsByTimer = new Map();
+    for (const pin of pins) {
+        if (!usage.pwmPinsUsed.has(pin.pinNumber)) {
+            continue;
+        }
+        const group = pinsByTimer.get(pin.timerId) ?? [];
+        group.push(pin);
+        pinsByTimer.set(pin.timerId, group);
+    }
+    const diagnostics = [];
+    for (const [timerId, timerPins] of pinsByTimer) {
+        if (timerPins.length < 2) {
+            continue;
+        }
+        const references = timerPins
+            .sort((left, right) => left.pinNumber - right.pinNumber)
+            .map((pin) => {
+            const usedNames = [pin.canonicalName, ...pin.aliases].filter(name => usage.pinsUsed.has(name));
+            const preferredName = usedNames[0] ?? pin.canonicalName;
+            return formatPinReference(preferredName, findBoardPinByName(pin.canonicalName, boardConstants));
+        });
+        diagnostics.push({
+            severity: 'info',
+            code: 'pwm-timer-sharing',
+            source: 'pwm-timer-sharing',
+            message: `${references.join(', ')} share ${timerId}${boardLabel}. Duty cycle can differ per pin, but timer-wide PWM settings are shared across that group. Prefer pins on different timer groups if you need independent PWM timing behavior.`,
+        });
+    }
+    return diagnostics;
+}

package/dist/ir/reachability.d.ts

@@ -0,0 +1,68 @@
+import { ProgramIR, FunctionIR, ClassIR, EnumIR, TypeAliasIR } from "../api/index.js";
+import { CallGraph } from "./call-graph.js";
+import { EntryPointConfig } from "./entry-points.js";
+import { TargetProfile, Diagnostic } from "../types.js";
+/**
+ * Result of reachability analysis
+ */
+export interface ReachabilityResult {
+    /** Functions that are reachable from entry points */
+    reachableFunctions: Set<string>;
+    /** Classes that are reachable from entry points */
+    reachableClasses: Set<string>;
+    /** Enums that are reachable from entry points */
+    reachableEnums: Set<string>;
+    /** Type aliases that are reachable from entry points */
+    reachableTypeAliases: Set<string>;
+    /** Top-level variable names that are reachable from entry points */
+    reachableVariables: Set<string>;
+    /** Indices of reachable top-level statements */
+    reachableTopLevelStatements: number[];
+    /** Unreachable code items */
+    unreachable: {
+        functions: FunctionIR[];
+        classes: ClassIR[];
+        enums: EnumIR[];
+        typeAliases: TypeAliasIR[];
+    };
+    /** Diagnostics for unreachable code */
+    diagnostics: Diagnostic[];
+}
+/**
+ * Options for reachability analysis (internal)
+ */
+interface ReachabilityOptions {
+    /** Target platform */
+    target: TargetProfile;
+    /** Entry point configuration */
+    entryPointConfig?: Partial<EntryPointConfig>;
+    /** Keep enums even if not referenced */
+    keepUnusedEnums?: boolean;
+    /** Keep classes even if not instantiated */
+    keepUnusedClasses?: boolean;
+    /** Keep type aliases even if not used */
+    keepUnusedTypeAliases?: boolean;
+    /** Keep top-level variables even if not referenced */
+    keepUnusedVariables?: boolean;
+    /** Generate diagnostics for unreachable code */
+    reportUnused?: boolean;
+}
+/**
+ * Analyze reachability from entry points in a program
+ */
+export declare function analyzeReachability(program: ProgramIR, callGraph: CallGraph, options: ReachabilityOptions): ReachabilityResult;
+/**
+ * Get statistics about reachability
+ */
+export declare function getReachabilityStats(program: ProgramIR, result: ReachabilityResult): {
+    totalFunctions: number;
+    reachableFunctions: number;
+    totalClasses: number;
+    reachableClasses: number;
+    totalEnums: number;
+    reachableEnums: number;
+    totalTypeAliases: number;
+    reachableTypeAliases: number;
+    reductionPercent: number;
+};
+export {};

package/dist/ir/reachability.js

@@ -0,0 +1,224 @@
+import { getReachableSymbols } from "./call-graph.js";
+import { detectEntryPoints } from "./entry-points.js";
+import { resolveStrategy } from "../platform/registry.js";
+/**
+ * Analyze reachability from entry points in a program
+ */
+export function analyzeReachability(program, callGraph, options) {
+    const { target, entryPointConfig, keepUnusedEnums = false, keepUnusedClasses = false, keepUnusedTypeAliases = false, keepUnusedVariables = false, reportUnused = false, } = options;
+    // Detect entry points — derive from platform strategy instead of hardcoded target strings
+    const strategy = resolveStrategy(target);
+    const strategyEntryPoints = strategy.requiresLoopFunction()
+        ? [strategy.entrypointFunctionName(), "loop"]
+        : [strategy.entrypointFunctionName()];
+    const entryPoints = detectEntryPoints(program, entryPointConfig, strategyEntryPoints);
+    // Get all reachable symbols from entry points
+    const reachableSymbols = getReachableSymbols(callGraph, entryPoints);
+    // Get defined symbols
+    const definedFunctions = new Map();
+    for (const fn of program.functions) {
+        definedFunctions.set(fn.originalName, fn);
+    }
+    const definedClasses = new Map();
+    for (const cls of program.classes) {
+        definedClasses.set(cls.name, cls);
+    }
+    const definedEnums = new Map();
+    for (const enumDef of program.enums) {
+        definedEnums.set(enumDef.name, enumDef);
+    }
+    const definedTypeAliases = new Map();
+    for (const typeAlias of program.typeAliases) {
+        definedTypeAliases.set(typeAlias.name, typeAlias);
+    }
+    // Determine reachable items
+    const reachableFunctions = new Set();
+    const reachableClasses = new Set();
+    const reachableEnums = new Set();
+    const reachableTypeAliases = new Set();
+    const reachableVariables = new Set();
+    // Collect names of top-level var_decl statements
+    const definedVariables = new Set();
+    for (const stmt of program.topLevelStatements) {
+        if (stmt.kind === "var_decl") {
+            definedVariables.add(stmt.name);
+        }
+    }
+    // All top-level statements are reachable by definition
+    const reachableTopLevelStatements = program.topLevelStatements.map((_, index) => index);
+    // Check each symbol for reachability
+    for (const symbol of reachableSymbols) {
+        if (definedFunctions.has(symbol)) {
+            reachableFunctions.add(symbol);
+        }
+        if (definedClasses.has(symbol)) {
+            reachableClasses.add(symbol);
+        }
+        if (definedEnums.has(symbol)) {
+            reachableEnums.add(symbol);
+        }
+        if (definedTypeAliases.has(symbol)) {
+            reachableTypeAliases.add(symbol);
+        }
+        if (definedVariables.has(symbol)) {
+            reachableVariables.add(symbol);
+        }
+    }
+    // Mark base classes as reachable when their derived classes are reachable.
+    // The call graph only tracks direct references, not inheritance relationships.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const cls of program.classes) {
+            if (reachableClasses.has(cls.name) && cls.extendsClass && !reachableClasses.has(cls.extendsClass)) {
+                reachableClasses.add(cls.extendsClass);
+                changed = true;
+            }
+        }
+    }
+    // Apply keep options
+    if (keepUnusedEnums) {
+        for (const [name] of definedEnums) {
+            reachableEnums.add(name);
+        }
+    }
+    if (keepUnusedClasses) {
+        for (const [name] of definedClasses) {
+            reachableClasses.add(name);
+        }
+    }
+    if (keepUnusedTypeAliases) {
+        for (const [name] of definedTypeAliases) {
+            reachableTypeAliases.add(name);
+        }
+    }
+    if (keepUnusedVariables) {
+        for (const name of definedVariables) {
+            reachableVariables.add(name);
+        }
+    }
+    // Collect unreachable items
+    const unreachableFunctions = [];
+    const unreachableClasses = [];
+    const unreachableEnums = [];
+    const unreachableTypeAliases = [];
+    const diagnostics = [];
+    for (const [name, fn] of definedFunctions) {
+        if (!reachableFunctions.has(name)) {
+            unreachableFunctions.push(fn);
+            if (reportUnused) {
+                diagnostics.push({
+                    severity: "info",
+                    message: `Function '${name}' is unreachable and will be removed from output.`,
+                    line: fn.sourceSpan.startLine,
+                    column: fn.sourceSpan.startColumn,
+                    code: "TS2CPP_UNREACHABLE_FUNCTION",
+                });
+            }
+        }
+    }
+    for (const [name, cls] of definedClasses) {
+        if (!reachableClasses.has(name)) {
+            unreachableClasses.push(cls);
+            if (reportUnused) {
+                diagnostics.push({
+                    severity: "info",
+                    message: `Class '${name}' is unreachable and will be removed from output.`,
+                    line: cls.sourceSpan.startLine,
+                    column: cls.sourceSpan.startColumn,
+                    code: "TS2CPP_UNREACHABLE_CLASS",
+                });
+            }
+        }
+    }
+    for (const [name, enumDef] of definedEnums) {
+        if (!reachableEnums.has(name)) {
+            unreachableEnums.push(enumDef);
+            // NOTE: Enum reachability warnings are currently disabled because enums may be
+            // referenced in type annotations or used for their type information without
+            // appearing in the runtime dependency graph. An enum may be used to type a
+            // variable or parameter, making it appear "unreachable" even though it was used.
+            //
+            // Future improvement: Track enum usage in type annotations and enable this
+            // warning when we can accurately detect truly unused enums.
+            //
+            // if (reportUnused) {
+            //   diagnostics.push({
+            //     severity: "info",
+            //     message: `Enum '${name}' is unreachable and will be removed from output.`,
+            //     line: enumDef.sourceSpan.startLine,
+            //     column: enumDef.sourceSpan.startColumn,
+            //     code: "TS2CPP_UNREACHABLE_ENUM",
+            //   });
+            // }
+        }
+    }
+    for (const [name, typeAlias] of definedTypeAliases) {
+        if (!reachableTypeAliases.has(name)) {
+            unreachableTypeAliases.push(typeAlias);
+            // NOTE: Type alias reachability warnings are currently disabled because TypeScript
+            // type aliases are compile-time only and don't always appear in the IR's dependency
+            // graph. A type alias may be used for type annotations that get erased during
+            // transpilation, making it appear "unreachable" even though it was used.
+            //
+            // Future improvement: Track type alias usage in type annotations and enable
+            // this warning when we can accurately detect truly unused type aliases.
+            //
+            // if (reportUnused) {
+            //   diagnostics.push({
+            //     severity: "info",
+            //     message: `Type alias '${name}' is unreachable and will be removed from output.`,
+            //     line: typeAlias.sourceSpan.startLine,
+            //     column: typeAlias.sourceSpan.startColumn,
+            //     code: "TS2CPP_UNREACHABLE_TYPE_ALIAS",
+            //   });
+            // }
+        }
+    }
+    return {
+        reachableFunctions,
+        reachableClasses,
+        reachableEnums,
+        reachableTypeAliases,
+        reachableVariables,
+        reachableTopLevelStatements,
+        unreachable: {
+            functions: unreachableFunctions,
+            classes: unreachableClasses,
+            enums: unreachableEnums,
+            typeAliases: unreachableTypeAliases,
+        },
+        diagnostics,
+    };
+}
+/**
+ * Get statistics about reachability
+ */
+export function getReachabilityStats(program, result) {
+    const totalFunctions = program.functions.length;
+    const totalClasses = program.classes.length;
+    const totalEnums = program.enums.length;
+    const totalTypeAliases = program.typeAliases.length;
+    const reachableFunctions = result.reachableFunctions.size;
+    const reachableClasses = result.reachableClasses.size;
+    const reachableEnums = result.reachableEnums.size;
+    const reachableTypeAliases = result.reachableTypeAliases.size;
+    const totalItems = totalFunctions + totalClasses + totalEnums + totalTypeAliases;
+    const reachableItems = reachableFunctions + reachableClasses + reachableEnums + reachableTypeAliases;
+    const totalVariables = program.topLevelStatements.filter((s) => s.kind === "var_decl").length;
+    const reachableVariableCount = result.reachableVariables.size;
+    const totalAll = totalItems + totalVariables;
+    const reachableAll = reachableItems + reachableVariableCount;
+    const reductionPercent = totalAll > 0 ? ((totalAll - reachableAll) / totalAll) * 100 : 0;
+    return {
+        totalFunctions,
+        reachableFunctions,
+        totalClasses,
+        reachableClasses,
+        totalEnums,
+        reachableEnums,
+        totalTypeAliases,
+        reachableTypeAliases,
+        reductionPercent,
+    };
+}

package/dist/ir/register-decorators.d.ts

@@ -0,0 +1,6 @@
+import ts from "typescript";
+export declare function getRegisterAddress(node: ts.ClassDeclaration): number | undefined;
+export declare function getBitsRange(node: ts.PropertyDeclaration): {
+    hi: number;
+    lo: number;
+} | undefined;

package/dist/ir/register-decorators.js

@@ -0,0 +1,49 @@
+import ts from "typescript";
+export function getRegisterAddress(node) {
+    const decorators = ts.canHaveDecorators?.(node)
+        ? ts.getDecorators?.(node)
+        : node.decorators;
+    if (!decorators)
+        return undefined;
+    for (const dec of decorators) {
+        if (!ts.isCallExpression(dec.expression))
+            continue;
+        const callee = dec.expression.expression;
+        if (!ts.isIdentifier(callee) || callee.text !== "register")
+            continue;
+        const args = dec.expression.arguments;
+        if (args.length < 1)
+            continue;
+        const arg = args[0];
+        if (ts.isNumericLiteral(arg) || ts.isBigIntLiteral?.(arg)) {
+            return Number(arg.text);
+        }
+        if (ts.isPrefixUnaryExpression(arg) && arg.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(arg.operand)) {
+            return -Number(arg.operand.text);
+        }
+    }
+    return undefined;
+}
+export function getBitsRange(node) {
+    const decorators = ts.canHaveDecorators?.(node)
+        ? ts.getDecorators?.(node)
+        : node.decorators;
+    if (!decorators)
+        return undefined;
+    for (const dec of decorators) {
+        if (!ts.isCallExpression(dec.expression))
+            continue;
+        const callee = dec.expression.expression;
+        if (!ts.isIdentifier(callee) || callee.text !== "bits")
+            continue;
+        const args = dec.expression.arguments;
+        if (args.length < 2)
+            continue;
+        const hiArg = args[0];
+        const loArg = args[1];
+        if (ts.isNumericLiteral(hiArg) && ts.isNumericLiteral(loArg)) {
+            return { hi: Number(hiArg.text), lo: Number(loArg.text) };
+        }
+    }
+    return undefined;
+}

package/dist/ir/render-expr.d.ts

@@ -0,0 +1,4 @@
+import ts from "typescript";
+import { ExpressionIR } from "../api/index.js";
+export declare function calleeToText(expr: ts.LeftHandSideExpression): string;
+export declare function renderExprAsText(expr: ExpressionIR): string;

package/dist/ir/render-expr.js

@@ -0,0 +1,127 @@
+import ts from "typescript";
+import { nestedFunctionAliases, getContext } from "./build-ir-state.js";
+import { escapeCppStringLiteral } from "../utils/strings.js";
+import { routeHALOp } from "../emit/route-hal-op.js";
+export function calleeToText(expr) {
+    if (ts.isIdentifier(expr)) {
+        const alias = nestedFunctionAliases.get(expr.text);
+        return alias ?? expr.text;
+    }
+    if (ts.isPropertyAccessExpression(expr)) {
+        return `${calleeToText(expr.expression)}.${expr.name.text}`;
+    }
+    return expr.getText();
+}
+/**
+ * Push a diagnostic onto the current build's diagnostics sink (the same array
+ * returned in ProgramIR.diagnostics). No-op if no build is in progress (e.g.
+ * ad-hoc calls from tests), so renderExprAsText remains usable in isolation.
+ */
+function pushDiagnostic(severity, code, message) {
+    const diagnostics = getContext().diagnostics;
+    if (!diagnostics)
+        return;
+    diagnostics.push({ severity, message, code });
+}
+export function renderExprAsText(expr) {
+    switch (expr.kind) {
+        case "number": {
+            if (expr.cppType === "float" || expr.cppType === "double" || !Number.isInteger(expr.value)) {
+                const str = `${expr.value}`;
+                return str.includes('.') || str.includes('e') || str.includes('E')
+                    ? `${str}f`
+                    : `${str}.0f`;
+            }
+            return `${expr.value}`;
+        }
+        case "string":
+            // Route through the shared `escapeCppStringLiteral` helper (the SAME one
+            // the template-literal / snprintf path uses) so a standalone-rendered
+            // string literal is escaped identically to one rendered inside a template
+            // literal. Previously this only escaped `"` — so a literal whose decoded
+            // text held a control char or backslash (e.g. a `'\n'`/`'\t'`/`'\\'`
+            // argument to an array/string method) emitted a RAW newline/tab/backslash
+            // inside the C++ string literal, producing an unterminated literal that
+            // corrupted lexing of the entire rest of the file. Demo #29 Finding A.
+            return `"${escapeCppStringLiteral(expr.value)}"`;
+        case "boolean":
+            return expr.value ? "true" : "false";
+        case "identifier":
+            return expr.value;
+        case "raw":
+            return expr.value;
+        case "element-access":
+            return `${renderExprAsText(expr.object)}[${renderExprAsText(expr.index)}]`;
+        case "tuple-access":
+            return `std::get<${expr.index}>(${renderExprAsText(expr.object)})`;
+        case "await":
+            return renderExprAsText(expr.value);
+        case "ternary":
+            return `(${renderExprAsText(expr.condition)} ? ${renderExprAsText(expr.whenTrue)} : ${renderExprAsText(expr.whenFalse)})`;
+        case "array": {
+            const elements = expr.elements.map((e) => renderExprAsText(e)).join(", ");
+            return `{ ${elements} }`;
+        }
+        case "object":
+            const fieldValues = expr.fields.map((f) => `${renderExprAsText(f.value)}`).join(", ");
+            return `{ ${fieldValues} }`;
+        case "binary":
+            return `${renderExprAsText(expr.left)} ${expr.operator} ${renderExprAsText(expr.right)}`;
+        case "unary":
+            return `${expr.operator}${renderExprAsText(expr.operand)}`;
+        case "property-access": {
+            const objText = renderExprAsText(expr.object);
+            if (expr.isEnum || expr.isNamespace || expr.isStatic) {
+                return `${objText}::${expr.property}`;
+            }
+            const isPointer = expr.isPointer || (expr.object.kind === "raw" && expr.object.value === "this");
+            const sep = isPointer ? "->" : ".";
+            return `${objText}${sep}${expr.property}`;
+        }
+        case "paren":
+            return `(${renderExprAsText(expr.inner)})`;
+        case "callback":
+            return `/* __callback__ */`;
+        case "lambda":
+            return `/* __lambda__ */`;
+        case "method-call": {
+            const argsText = expr.args.map(a => renderExprAsText(a)).join(", ");
+            return `${expr.callee}(${argsText})`;
+        }
+        case "template_string":
+            return renderExprAsText(expr.expression);
+        case "string_concat":
+            return expr.parts.map(p => renderExprAsText(p)).join(" + ");
+        case "hal-expr": {
+            const strategy = getContext().activeStrategy;
+            if (strategy?.resolveHALOperation || strategy?.resolveDisplayOp) {
+                const resolved = routeHALOp(expr.operation, strategy);
+                if (resolved?.expression)
+                    return resolved.expression;
+                if (resolved?.code)
+                    return resolved.code.replace(/;\s*$/, "");
+            }
+            // Unregistered HAL op: surface as a warning so the user sees it, but keep
+            // HAL as an extensibility point (a strategy may intentionally leave some
+            // ops unimplemented). The bare comment is retained as a visual marker.
+            pushDiagnostic("warning", "TS2CPP_UNHANDLED_HAL", `HAL operation '${expr.operation.operation}' is not registered with the platform strategy; emitting a placeholder comment.`);
+            return `/* unhandled hal-expr: ${expr.operation.operation} */`;
+        }
+        case "instanceof":
+            return `(typeid(*${renderExprAsText(expr.object)}) == typeid(${expr.className}))`;
+        case "spread_array":
+            return renderExprAsText(expr.spreadExpr);
+        default: {
+            // An ExpressionIR kind renderExprAsText doesn't know how to render is a
+            // transpiler bug (the renderer should cover every kind the IR builders
+            // can produce). Previously this silently emitted "0 /* unsupported_expr */"
+            // into the C++ output. Now we push an error diagnostic — the fatal-gate
+            // check in transpile.ts aborts the build — and throw so that callers
+            // running outside the build (e.g. tests) fail loudly rather than
+            // continuing with placeholder C++.
+            const kind = expr.kind ?? "<unknown>";
+            pushDiagnostic("error", "TS2CPP_UNSUPPORTED_EXPR", `Expression IR kind '${kind}' has no renderer and cannot be emitted to C++.`);
+            throw new Error(`renderExprAsText: unsupported ExpressionIR kind '${kind}'`);
+        }
+    }
+}

package/dist/ir/resource-analysis.d.ts

@@ -0,0 +1,19 @@
+import { ProgramIR, PlatformStrategy, Diagnostic } from "../api/index.js";
+export interface ResourceUsage {
+    pins: Map<string, {
+        source: string;
+        peripheral?: string;
+    }>;
+    peripherals: Map<string, {
+        source: string;
+        instance: number;
+    }>;
+}
+/**
+ * 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 declare function analyzeResources(program: ProgramIR, strategy: PlatformStrategy): Diagnostic[];