@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/pin-mode-validation.js

@@ -0,0 +1,301 @@
+// ---------------------------------------------------------------------------
+// Pin Mode Configuration Validation
+//
+// Detects when GPIO I/O operations are used on pins without prior mode
+// configuration. Generates warnings for reads and info for writes.
+// ---------------------------------------------------------------------------
+import { scanNestedStatements } from './interrupt-analysis.js';
+/** Methods that configure pin mode. */
+const MODE_SET_METHODS = new Set([
+    'inputPullUp', 'inputPullDown', 'outputOpenDrain',
+    'asOutput', 'asInput', 'asInputPullUp',
+]);
+/** Read operations that require prior INPUT or INPUT_PULLUP mode. */
+const READ_METHODS = new Set([
+    'read', 'isHigh', 'isLow', 'readAnalog', 'readVoltage',
+]);
+/** Write operations that implicitly set OUTPUT mode on Arduino. */
+const WRITE_METHODS = new Set([
+    'write', 'high', 'low', 'toggle', 'pulse', 'pwm', 'tone',
+]);
+/** Receiver kinds that represent GPIO pins. */
+const PIN_RECEIVER_KINDS = new Set([
+    'digital', 'pwm', 'analog-input', 'interrupt',
+]);
+/**
+ * Validate that GPIO I/O operations are preceded by mode configuration.
+ *
+ * - Read without prior mode → **warning** (undefined behavior on floating pin)
+ * - Write without prior mode → **info** (Arduino implicitly sets OUTPUT, but
+ *   explicit configuration is recommended)
+ */
+export function validatePinModeConfig(program) {
+    const diagnostics = [];
+    // Track which receivers have had their mode explicitly set
+    const pinModeSet = new Set();
+    const checkCuttlefishCall = (receiver, receiverKind, method) => {
+        if (!receiverKind || !PIN_RECEIVER_KINDS.has(receiverKind))
+            return;
+        // Warn when analog pin is used as digital output — analog capability is lost
+        if (receiverKind === 'analog-input' && method === 'asOutput') {
+            diagnostics.push({
+                severity: 'warning',
+                message: `Analog pin '${receiver}' used as digital output. ` +
+                    `Analog input capability (ADC) is lost while pin is in OUTPUT mode. ` +
+                    `Call ${receiver}.asInput() to restore analog reading.`,
+                code: 'analog-pin-as-output',
+                source: 'pin-mode-validation',
+            });
+        }
+        if (MODE_SET_METHODS.has(method)) {
+            pinModeSet.add(receiver);
+        }
+        else if (READ_METHODS.has(method) && !pinModeSet.has(receiver)) {
+            diagnostics.push({
+                severity: 'warning',
+                message: `Pin '${receiver}' read via '${method}()' without prior mode configuration. ` +
+                    `Call ${receiver}.asInput() or ${receiver}.inputPullUp() first.`,
+                code: 'pin-mode-not-set',
+                source: 'pin-mode-validation',
+            });
+        }
+        else if (WRITE_METHODS.has(method) && !pinModeSet.has(receiver)) {
+            diagnostics.push({
+                severity: 'info',
+                message: `Pin '${receiver}' written via '${method}()' without explicit mode configuration. ` +
+                    `Arduino implicitly sets OUTPUT, but explicit ${receiver}.asOutput() is recommended.`,
+                code: 'pin-mode-not-set',
+                source: 'pin-mode-validation',
+            });
+        }
+    };
+    /**
+     * Recursively scan an expression for cuttlefish-call nodes.
+     * Pin I/O can appear as expressions inside template literals, function args, etc.
+     */
+    /** Infer the receiver kind from the method name. Analog/PWM methods imply
+     *  their respective pin kinds; everything else defaults to digital. */
+    const inferReceiverKind = (method) => {
+        if (method === 'readAnalog' || method === 'readVoltage')
+            return 'analog-input';
+        if (method === 'pwm' || method === 'tone')
+            return 'pwm';
+        // Methods in the read/write/mode sets that aren't analog/pwm are digital.
+        if (READ_METHODS.has(method) || WRITE_METHODS.has(method) || MODE_SET_METHODS.has(method))
+            return 'digital';
+        return undefined;
+    };
+    /** Check a gpio HAL op for pin-mode issues. Used by both scanExpression
+     *  (hal-expr, for reads used as values) and checkStatement (hal-op, for
+     *  standalone writes/calls). */
+    const checkGpioHalOp = (op) => {
+        if (!op)
+            return;
+        const pinKey = `pin${op.pin}`;
+        if (op.operation === 'gpio.set_mode') {
+            pinModeSet.add(pinKey);
+        }
+        else if (op.operation === 'gpio.read' && !pinModeSet.has(pinKey)) {
+            diagnostics.push({
+                severity: 'warning',
+                message: `Pin ${op.pin} read without prior mode configuration. ` +
+                    `Call asInput() or inputPullUp() first — reading a floating pin is undefined behavior.`,
+                code: 'pin-mode-not-set',
+                source: 'pin-mode-validation',
+            });
+        }
+        else if ((op.operation === 'gpio.write' || op.operation === 'gpio.toggle') && !pinModeSet.has(pinKey)) {
+            diagnostics.push({
+                severity: 'info',
+                message: `Pin ${op.pin} written without explicit mode configuration. ` +
+                    `Arduino implicitly sets OUTPUT, but explicit asOutput() is recommended.`,
+                code: 'pin-mode-not-set',
+                source: 'pin-mode-validation',
+            });
+        }
+    };
+    const scanExpression = (expr) => {
+        if (!expr || typeof expr !== 'object')
+            return;
+        const e = expr;
+        if (!e.kind)
+            return;
+        // Method calls on pins: extract receiver + method and dispatch to
+        // checkCuttlefishCall (pre-HAL-resolution fallback path).
+        if (e.kind === 'method-call' && typeof e.callee === 'string') {
+            const callee = e.callee;
+            const dotIdx = callee.lastIndexOf('.');
+            if (dotIdx > 0) {
+                const receiver = callee.slice(0, dotIdx);
+                const method = callee.slice(dotIdx + 1);
+                const receiverKind = inferReceiverKind(method);
+                if (receiverKind) {
+                    checkCuttlefishCall(receiver, receiverKind, method);
+                }
+            }
+        }
+        // HAL expression (read used as a value, e.g. `const v = D2.isHigh()`).
+        // After HAL resolution, pin reads become hal-expr nodes with a gpio.read
+        // operation — this is the common form at validation time.
+        if (e.kind === 'hal-expr' && e.operation) {
+            checkGpioHalOp(e.operation);
+        }
+        // Raw nodes: after full HAL resolution, some pin ops land as their C++ text
+        // (e.g. `digitalRead(2)`, `digitalWrite(2, 1)`) rather than structured
+        // hal-expr nodes. Extract the pin number and apply the same mode check.
+        // This mirrors how peripheral-usage.ts detects gpio via emitted text.
+        if (e.kind === 'raw' && typeof e.value === 'string') {
+            const readMatch = e.value.match(/digitalRead\((\d+)\)/);
+            const writeMatch = e.value.match(/digitalWrite\((\d+)/);
+            const toggleMatch = e.value.match(/digitalWrite\((\d+),\s*digitalRead/);
+            const pin = readMatch ? parseInt(readMatch[1], 10)
+                : writeMatch ? parseInt(writeMatch[1], 10)
+                    : null;
+            if (pin !== null) {
+                const op = toggleMatch
+                    ? { operation: 'gpio.toggle', pin }
+                    : readMatch ? { operation: 'gpio.read', pin }
+                        : { operation: 'gpio.write', pin };
+                checkGpioHalOp(op);
+            }
+        }
+        // Recurse into nested expressions
+        if (e.args && Array.isArray(e.args)) {
+            for (const arg of e.args)
+                scanExpression(arg);
+        }
+        if (e.left)
+            scanExpression(e.left);
+        if (e.right)
+            scanExpression(e.right);
+        if (e.operand)
+            scanExpression(e.operand);
+        if (e.condition && typeof e.condition === 'object')
+            scanExpression(e.condition);
+        if (e.whenTrue)
+            scanExpression(e.whenTrue);
+        if (e.whenFalse)
+            scanExpression(e.whenFalse);
+        if (e.object && typeof e.object === 'object')
+            scanExpression(e.object);
+        // Only recurse into .value when it's an object with a kind (an expression),
+        // not a primitive (number/string/boolean literals carry primitive values).
+        if (e.value && typeof e.value === 'object' && e.value.kind)
+            scanExpression(e.value);
+        if (e.inner)
+            scanExpression(e.inner);
+        if (e.elements && Array.isArray(e.elements)) {
+            for (const elem of e.elements)
+                scanExpression(elem);
+        }
+        if (e.fields && Array.isArray(e.fields)) {
+            for (const field of e.fields) {
+                if (field && field.value)
+                    scanExpression(field.value);
+            }
+        }
+        // Template literal: string_concat has a 'parts' array
+        if (e.parts && Array.isArray(e.parts)) {
+            for (const part of e.parts)
+                scanExpression(part);
+        }
+        // Template literal: template_string wraps an 'expression' (singular)
+        if (e.expression && typeof e.expression === 'object' && e.expression.kind)
+            scanExpression(e.expression);
+        // Callback expressions with nested statements
+        if (e.statements && Array.isArray(e.statements)) {
+            for (const stmt of e.statements)
+                checkStatement(stmt);
+        }
+    };
+    const checkStatement = (stmt) => {
+        if (!stmt || typeof stmt !== 'object')
+            return;
+        // HAL-op statements: track pin-mode state from gpio.set_mode and warn on
+        // gpio.read/write/toggle without prior mode configuration. After HAL
+        // resolution, pin method calls (D2.isHigh(), D2.high()) become these
+        // structured ops — the method-call form no longer exists at validation time.
+        if (stmt.kind === 'hal-op') {
+            checkGpioHalOp(stmt.operation);
+        }
+        // Scan expressions in other statement types for nested cuttlefish-calls
+        if (stmt.kind === 'assign') {
+            const a = stmt;
+            if (a.value)
+                scanExpression(a.value);
+        }
+        if (stmt.kind === 'var_decl') {
+            const v = stmt;
+            if (v.initializer)
+                scanExpression(v.initializer);
+        }
+        if (stmt.kind === 'return') {
+            const r = stmt;
+            if (r.value)
+                scanExpression(r.value);
+        }
+        if (stmt.kind === 'call') {
+            const c = stmt;
+            if (c.args && Array.isArray(c.args)) {
+                for (const arg of c.args)
+                    scanExpression(arg);
+            }
+        }
+        if (stmt.kind === 'if') {
+            const i = stmt;
+            if (i.condition)
+                scanExpression(i.condition);
+        }
+        if (stmt.kind === 'while' || stmt.kind === 'do_while') {
+            const w = stmt;
+            if (w.condition)
+                scanExpression(w.condition);
+        }
+        if (stmt.kind === 'for') {
+            const f = stmt;
+            if (f.condition)
+                scanExpression(f.condition);
+            if (f.initializer)
+                checkStatement(f.initializer);
+            if (f.increment)
+                checkStatement(f.increment);
+        }
+        if (stmt.kind === 'switch') {
+            const s = stmt;
+            if (s.expression)
+                scanExpression(s.expression);
+        }
+        // Recurse into nested statements (if branches, loop bodies, etc.)
+        scanNestedStatements(stmt, checkStatement);
+    };
+    // Scan all program locations
+    if (program.topLevelStatements) {
+        for (const stmt of program.topLevelStatements)
+            checkStatement(stmt);
+    }
+    if (program.functions) {
+        for (const fn of program.functions) {
+            if (fn.statements) {
+                for (const stmt of fn.statements)
+                    checkStatement(stmt);
+            }
+        }
+    }
+    if (program.classes) {
+        for (const cls of program.classes) {
+            if (cls.methods) {
+                for (const method of cls.methods) {
+                    if (method.statements) {
+                        for (const stmt of method.statements)
+                            checkStatement(stmt);
+                    }
+                }
+            }
+            if (cls.constructor?.statements) {
+                for (const stmt of cls.constructor.statements)
+                    checkStatement(stmt);
+            }
+        }
+    }
+    return diagnostics;
+}

package/dist/ir/pin-safety.d.ts

@@ -0,0 +1,11 @@
+import type { PeripheralUsage } from './peripheral-usage.js';
+import type { BoardConstants } from './board-resolver.js';
+import type { Diagnostic } from '../types.js';
+/**
+ * Validate unsafe pin usage and generate warning diagnostics.
+ *
+ * @param usage - Peripheral usage analysis containing pinsUsed set
+ * @param boardConstants - Board constants containing pins.unsafe array
+ * @returns Array of diagnostic warnings for unsafe pin usage
+ */
+export declare function validateUnsafePins(usage: PeripheralUsage, boardConstants: BoardConstants | undefined): Diagnostic[];

package/dist/ir/pin-safety.js

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// Pin Safety Validation
+//
+// Validates that unsafe pins are used with appropriate warnings.
+// Generates diagnostics when pins marked as unsafe are used in the program.
+// ---------------------------------------------------------------------------
+import { findBoardPinByName, formatPinReference } from './board-pin-utils.js';
+function buildUnsafePinMessage(pinName, boardConstants) {
+    const boardName = boardConstants?.get('name');
+    const boardLabel = typeof boardName === 'string' && boardName.length > 0
+        ? ` on ${boardName}`
+        : '';
+    const metadata = findBoardPinByName(pinName, boardConstants);
+    const pinReference = formatPinReference(pinName, metadata);
+    if (metadata?.warnings[0]) {
+        return `${pinReference} is marked as unsafe${boardLabel}. ${metadata.warnings[0]}.`;
+    }
+    if (metadata?.note) {
+        return `${pinReference} is marked as unsafe${boardLabel}. ${metadata.note}.`;
+    }
+    if (metadata && metadata.alternateFunctions.length > 0) {
+        return `${pinReference} is marked as unsafe${boardLabel}. It is also used for ${metadata.alternateFunctions.join(', ')}.`;
+    }
+    return `${pinReference} is marked as unsafe${boardLabel}. Use with caution - this pin may have special boot behavior or conflict with system functions.`;
+}
+/**
+ * Validate unsafe pin usage and generate warning diagnostics.
+ *
+ * @param usage - Peripheral usage analysis containing pinsUsed set
+ * @param boardConstants - Board constants containing pins.unsafe array
+ * @returns Array of diagnostic warnings for unsafe pin usage
+ */
+export function validateUnsafePins(usage, boardConstants) {
+    const diagnostics = [];
+    if (!boardConstants)
+        return diagnostics;
+    if (!usage.pinsUsed || usage.pinsUsed.size === 0)
+        return diagnostics;
+    // Get unsafe pins list (stored as comma-separated string by board-resolver)
+    const unsafePinsStr = boardConstants.get('pins.unsafe');
+    if (!unsafePinsStr)
+        return diagnostics;
+    const unsafePins = unsafePinsStr.split(',').map(s => s.trim());
+    // Check each used pin against the unsafe list
+    for (const pinName of usage.pinsUsed) {
+        const boardPin = findBoardPinByName(pinName, boardConstants);
+        const canonicalPinName = boardPin?.name ?? pinName;
+        if (unsafePins.includes(canonicalPinName)) {
+            diagnostics.push({
+                severity: 'warning',
+                message: buildUnsafePinMessage(pinName, boardConstants),
+                code: 'unsafe-pin-usage',
+                source: 'pin-safety',
+            });
+        }
+    }
+    return diagnostics;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Combined program analysis - single-pass detection of multiple features.
+ *
+ * Instead of traversing the IR multiple times for different checks
+ * (hasConsoleCalls, hasArrayInObjectLiteral, hasThrowStatements, etc.),
+ * this module performs all checks in a single traversal.
+ */
+import { ProgramIR, PlatformStrategy } from "../api/index.js";
+export interface ProgramAnalysisResult {
+    hasConsoleCalls: boolean;
+    hasArrayInObjectLiteral: boolean;
+    hasThrowStatements: boolean;
+    hasStdMathCalls: boolean;
+    usesVectorTypes: boolean;
+    usesStdString: boolean;
+    usesStdFunction: boolean;
+    declaredTypes: string[];
+    usedPolyfillHelpers: Set<string>;
+    usesStringConversion: boolean;
+    usesDateNow: boolean;
+    usesMillis: boolean;
+    usesNullish: boolean;
+    /** True when this file actually emits a cuttlefish_nullish/exists/is_nullish CALL
+     *  (e.g. from a `??` lowering), as opposed to just referencing the
+     *  CUTTLEFISH_UNDEFINED macro via a `null`/`undefined` literal. Used to decide
+     *  whether non-entry headers need the full nullish shim block. */
+    usesNullishHelper: boolean;
+    usesNum: boolean;
+    usesTiming: boolean;
+    usesWDT: boolean;
+    usesStrPtr: boolean;
+    hasSerialBegin: boolean;
+    hasGenerators: boolean;
+    usesStdMap: boolean;
+    /** Number of setInterval/setTimeout call sites in the program. Used to size
+     *  __tc_TimerRuntime::MAX_TIMERS to the observed count (floor 1) rather than
+     *  a blind constant, so a one-timer program links one slot, not eight. */
+    timerCallCount: number;
+}
+/**
+ * Analyze a program IR in a single pass to detect all features.
+ * This replaces multiple separate traversals with one combined traversal.
+ */
+export declare function analyzeProgram(program: ProgramIR, strategy: PlatformStrategy): ProgramAnalysisResult;