@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/peripheral-validation.js

@@ -0,0 +1,77 @@
+// ---------------------------------------------------------------------------
+// Peripheral Instance Validation
+//
+// Validates that peripheral instances used in the program are available
+// on the target board. Generates compile-time errors for invalid usage.
+// ---------------------------------------------------------------------------
+/**
+ * Get peripheral capacity from board constants.
+ */
+function getPeripheralCapacity(boardConstants) {
+    const defaultCapacity = {
+        i2c: 1,
+        spi: 1,
+        uart: 1,
+    };
+    if (!boardConstants) {
+        return defaultCapacity;
+    }
+    return {
+        i2c: boardConstants.get('peripherals.i2c.count') ?? 1,
+        spi: boardConstants.get('peripherals.spi.count') ?? 1,
+        uart: boardConstants.get('peripherals.uart.count') ?? 1,
+    };
+}
+/**
+ * Validate peripheral usage against board capacity.
+ * Returns an array of diagnostics for any invalid peripheral usage.
+ */
+function validatePeripheralUsage(usage, capacity, boardName = 'this board') {
+    const diagnostics = [];
+    // Validate I2C instances
+    for (const instance of usage.i2cInstancesUsed) {
+        if (instance >= capacity.i2c) {
+            const availableName = capacity.i2c === 1 ? 'I2C0' : `I2C0 through I2C${capacity.i2c - 1}`;
+            diagnostics.push({
+                severity: 'error',
+                message: `I2C${instance} is not available on ${boardName}. Available: ${availableName}`,
+                code: 'peripheral-not-available',
+                source: 'peripheral-validation',
+            });
+        }
+    }
+    // Validate SPI instances
+    for (const instance of usage.spiInstancesUsed) {
+        if (instance >= capacity.spi) {
+            const availableName = capacity.spi === 1 ? 'SPI0' : `SPI0 through SPI${capacity.spi - 1}`;
+            diagnostics.push({
+                severity: 'error',
+                message: `SPI${instance} is not available on ${boardName}. Available: ${availableName}`,
+                code: 'peripheral-not-available',
+                source: 'peripheral-validation',
+            });
+        }
+    }
+    // Validate UART instances
+    for (const instance of usage.uartInstancesUsed) {
+        if (instance >= capacity.uart) {
+            const availableName = capacity.uart === 1 ? 'UART0 (Serial)' : `UART0 through UART${capacity.uart - 1}`;
+            diagnostics.push({
+                severity: 'error',
+                message: `UART${instance} is not available on ${boardName}. Available: ${availableName}`,
+                code: 'peripheral-not-available',
+                source: 'peripheral-validation',
+            });
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Validate peripheral usage and return diagnostics.
+ * This is the main entry point for peripheral validation.
+ */
+export function validatePeripherals(usage, boardConstants) {
+    const capacity = getPeripheralCapacity(boardConstants);
+    const boardName = boardConstants?.get('name') ?? 'this board';
+    return validatePeripheralUsage(usage, capacity, boardName);
+}

package/dist/ir/pin-alias-conflict.d.ts

@@ -0,0 +1,4 @@
+import type { Diagnostic } from '../types.js';
+import type { BoardConstants } from './board-resolver.js';
+import type { PeripheralUsage } from './peripheral-usage.js';
+export declare function validatePinAliasConflicts(usage: PeripheralUsage, boardConstants: BoardConstants | undefined): Diagnostic[];

package/dist/ir/pin-alias-conflict.js

@@ -0,0 +1,34 @@
+import { findBoardPinByName } from './board-pin-utils.js';
+export function validatePinAliasConflicts(usage, boardConstants) {
+    if (!boardConstants || usage.pinsUsed.size === 0) {
+        return [];
+    }
+    const usedNamesByCanonicalPin = new Map();
+    for (const usedPinName of usage.pinsUsed) {
+        const boardPin = findBoardPinByName(usedPinName, boardConstants);
+        if (!boardPin) {
+            continue;
+        }
+        const names = usedNamesByCanonicalPin.get(boardPin.name) ?? new Set();
+        names.add(usedPinName);
+        usedNamesByCanonicalPin.set(boardPin.name, names);
+    }
+    const boardName = boardConstants.get('name');
+    const boardLabel = typeof boardName === 'string' && boardName.length > 0
+        ? ` on ${boardName}`
+        : '';
+    const diagnostics = [];
+    for (const [canonicalPinName, usedNames] of usedNamesByCanonicalPin) {
+        if (usedNames.size < 2) {
+            continue;
+        }
+        const orderedNames = [canonicalPinName, ...Array.from(usedNames).filter(name => name !== canonicalPinName).sort()];
+        diagnostics.push({
+            severity: 'warning',
+            code: 'pin-alias-conflict',
+            source: 'pin-alias-conflict',
+            message: `Pin '${canonicalPinName}' is referenced through multiple names${boardLabel}: ${orderedNames.join(', ')}. These names refer to the same physical pin. Pick one name to keep pin usage and diagnostics unambiguous.`,
+        });
+    }
+    return diagnostics;
+}

package/dist/ir/pin-capability-validation.d.ts

@@ -0,0 +1,6 @@
+import type { ProgramIR } from '../api/index.js';
+import type { Diagnostic } from '../types.js';
+/**
+ * Validate that capability-specific methods are only called on pins that support them.
+ */
+export declare function validatePinCapabilities(program: ProgramIR): Diagnostic[];

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

@@ -0,0 +1,413 @@
+// ---------------------------------------------------------------------------
+// Pin Capability Validation
+//
+// Detects calls to capability-specific methods on pins that don't support them.
+// E.g. D12.readAnalog() — D12 is a digital-only pin, use A0-A5 instead.
+// A0.pwm() — A0 has no PWM, use D3/D5/D6/D9/D10/D11 instead.
+// Produces diagnostics with actionable hints listing the correct pins.
+// ---------------------------------------------------------------------------
+/** Compile-time exhaustiveness check for switch statements on IR kinds. */
+function assertNever(x) {
+    throw new Error(`Unhandled IR kind: ${JSON.stringify(x)}`);
+}
+// ---------------------------------------------------------------------------
+// HAL operation → capability mapping
+// ---------------------------------------------------------------------------
+/** Maps a HAL operation string to the board-definition capability flag it requires. */
+function operationToCapability(op) {
+    if (op === 'pwm.write' || op === 'pwm.get_frequency' || op === 'pwm.get_resolution' || op === 'tone.play') {
+        return 'pwm';
+    }
+    if (op === 'adc.read' || op === 'adc.read_voltage' || op === 'adc.get_resolution') {
+        return 'analogInput';
+    }
+    if (op === 'dac.write') {
+        return 'analogOutput';
+    }
+    if (op === 'interrupt.attach') {
+        return 'interrupt';
+    }
+    // GPIO and timing ops are always available — no capability check needed.
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Board constant lookups
+// ---------------------------------------------------------------------------
+/** Find the human-readable name for a pin number (e.g. 14 → "PC0" or "A0"). */
+function getPinName(pinNumber, boardConstants) {
+    if (!boardConstants)
+        return `pin ${pinNumber}`;
+    const name = boardConstants.get(`pins.all.${pinNumber}.name`);
+    return name ? String(name) : `pin ${pinNumber}`;
+}
+/** Find all pins on this board that support a given capability. */
+function findPinsWithCapability(capability, boardConstants) {
+    if (!boardConstants)
+        return [];
+    const result = [];
+    const funcTypeMap = {
+        pwm: 'pwm',
+        analogInput: 'adc',
+        analogOutput: 'dac',
+        interrupt: 'interrupt',
+    };
+    const funcType = funcTypeMap[capability];
+    for (let i = 0; i < 100; i++) {
+        const name = boardConstants.get(`pins.all.${i}.name`);
+        if (name === undefined)
+            continue;
+        // Check capabilities flag first
+        const capFlag = boardConstants.get(`pins.all.${i}.capabilities.${capability}`);
+        if (capFlag === true || capFlag === 'true') {
+            result.push(String(name));
+            continue;
+        }
+        // Fallback: check functions array
+        if (funcType) {
+            for (let j = 0; j < 10; j++) {
+                const type = boardConstants.get(`pins.all.${i}.functions.${j}.type`);
+                if (type === undefined)
+                    break;
+                if (String(type) === funcType) {
+                    result.push(String(name));
+                    break;
+                }
+            }
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Capability check for a single HAL operation
+// ---------------------------------------------------------------------------
+function checkCapability(operation, sourceLine, sourceCol, boardConstants, diagnostics) {
+    // Only operations with a pin field are capability-checked.
+    const op = operation.operation;
+    if (!('pin' in operation))
+        return;
+    const capability = operationToCapability(op);
+    if (!capability)
+        return; // GPIO/timing — always available.
+    const pin = operation.pin;
+    if (typeof pin !== 'number' || pin < 0)
+        return;
+    // ADC channel reads (ADC.read(channel)) use channel numbers, not pin
+    // numbers — skip capability checking for adc ops where the "pin" is
+    // actually a channel index (0-7 range, below the first analog pin).
+    if (capability === 'analogInput' && op.startsWith('adc.') && pin < 14)
+        return;
+    // Check the pin's capability via the board definition.
+    // Try the capabilities flag first, then fall back to scanning the
+    // functions array (functions.N.type === capability prefix).
+    const capFlag = boardConstants?.get(`pins.all.${pin}.capabilities.${capability}`);
+    if (capFlag === true || capFlag === 'true')
+        return; // Capability confirmed.
+    // Fallback: scan the functions array for a matching type.
+    // PWM capability is indicated by functions[N].type === 'pwm',
+    // ADC by 'adc', interrupts by 'interrupt' (external), DAC by 'dac'.
+    const funcTypeMap = {
+        pwm: 'pwm',
+        analogInput: 'adc',
+        analogOutput: 'dac',
+        interrupt: 'interrupt',
+    };
+    const funcType = funcTypeMap[capability];
+    if (funcType) {
+        let hasCapabilityData = false;
+        for (let i = 0; i < 10; i++) {
+            const type = boardConstants?.get(`pins.all.${pin}.functions.${i}.type`);
+            if (type === undefined)
+                break;
+            hasCapabilityData = true;
+            if (String(type) === funcType)
+                return; // Capability confirmed via functions.
+        }
+        // If the pin has NO functions entries at all AND the capability we're
+        // checking is interrupt (which is stored in capabilities, not functions),
+        // we can't determine support — skip to avoid false positives.
+        if (!hasCapabilityData && capability === 'interrupt')
+            return;
+    }
+    // Capability NOT supported — emit a diagnostic.
+    const pinName = getPinName(pin, boardConstants);
+    const validPins = findPinsWithCapability(capability, boardConstants);
+    const capLabel = capability === 'analogInput' ? 'analog input'
+        : capability === 'analogOutput' ? 'DAC output'
+            : capability === 'interrupt' ? 'external interrupts'
+                : capability.toUpperCase();
+    const hint = validPins.length > 0
+        ? `Use one of: ${validPins.join(', ')}`
+        : `No pins on this board support ${capLabel}.`;
+    diagnostics.push({
+        severity: 'error',
+        code: 'pin-capability-mismatch',
+        message: `${pinName} does not support ${capLabel} on this board.`,
+        hint,
+        line: sourceLine,
+        column: sourceCol,
+        source: 'pin-capability-validation',
+    });
+}
+// ---------------------------------------------------------------------------
+// IR tree scanner
+// ---------------------------------------------------------------------------
+function scanExpression(expr, boardConstants, parentLine, parentCol, diagnostics) {
+    if (!expr || typeof expr !== 'object')
+        return;
+    switch (expr.kind) {
+        case 'binary': {
+            scanExpression(expr.left, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.right, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'ternary': {
+            scanExpression(expr.condition, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.whenTrue, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.whenFalse, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'property-access': {
+            scanExpression(expr.object, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'unary': {
+            scanExpression(expr.operand, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'paren': {
+            scanExpression(expr.inner, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'array': {
+            for (const el of expr.elements) {
+                scanExpression(el, boardConstants, parentLine, parentCol, diagnostics);
+            }
+            break;
+        }
+        case 'object': {
+            for (const field of expr.fields) {
+                scanExpression(field.value, boardConstants, parentLine, parentCol, diagnostics);
+            }
+            break;
+        }
+        case 'callback': {
+            for (const s of expr.statements) {
+                scanStatement(s, boardConstants, diagnostics);
+            }
+            break;
+        }
+        case 'lambda': {
+            for (const s of expr.body) {
+                scanStatement(s, boardConstants, diagnostics);
+            }
+            break;
+        }
+        case 'method-call': {
+            for (const arg of expr.args) {
+                scanExpression(arg, boardConstants, parentLine, parentCol, diagnostics);
+            }
+            break;
+        }
+        case 'element-access': {
+            scanExpression(expr.object, boardConstants, parentLine, parentCol, diagnostics);
+            scanExpression(expr.index, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'string_concat': {
+            for (const part of expr.parts) {
+                scanExpression(part, boardConstants, parentLine, parentCol, diagnostics);
+            }
+            break;
+        }
+        case 'template_string': {
+            scanExpression(expr.expression, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'spread_array': {
+            scanExpression(expr.spreadExpr, boardConstants, parentLine, parentCol, diagnostics);
+            for (const el of expr.additionalElements) {
+                scanExpression(el, boardConstants, parentLine, parentCol, diagnostics);
+            }
+            break;
+        }
+        case 'instanceof': {
+            scanExpression(expr.object, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'await': {
+            scanExpression(expr.value, boardConstants, parentLine, parentCol, diagnostics);
+            break;
+        }
+        case 'hal-expr': {
+            // Expression-form HAL operation (e.g. adc.read used as a value).
+            checkCapability(expr.operation, parentLine, parentCol, boardConstants, diagnostics);
+            break;
+        }
+        case 'number':
+        case 'string':
+        case 'boolean':
+        case 'identifier':
+        case 'raw':
+        case 'tuple-access':
+            break;
+        default:
+            assertNever(expr);
+    }
+}
+function scanStatement(stmt, boardConstants, diagnostics) {
+    if (!stmt || typeof stmt !== 'object')
+        return;
+    const line = stmt.sourceSpan?.startLine;
+    const col = stmt.sourceSpan?.startColumn;
+    switch (stmt.kind) {
+        case 'var_decl': {
+            if (stmt.initializer)
+                scanExpression(stmt.initializer, boardConstants, line, col, diagnostics);
+            break;
+        }
+        case 'assign': {
+            if (stmt.value)
+                scanExpression(stmt.value, boardConstants, line, col, diagnostics);
+            break;
+        }
+        case 'if': {
+            if (stmt.condition)
+                scanExpression(stmt.condition, boardConstants, line, col, diagnostics);
+            for (const s of stmt.thenBranch)
+                scanStatement(s, boardConstants, diagnostics);
+            if (stmt.elseBranch)
+                for (const s of stmt.elseBranch)
+                    scanStatement(s, boardConstants, diagnostics);
+            break;
+        }
+        case 'while':
+        case 'do_while': {
+            if (stmt.condition)
+                scanExpression(stmt.condition, boardConstants, line, col, diagnostics);
+            for (const s of stmt.body)
+                scanStatement(s, boardConstants, diagnostics);
+            break;
+        }
+        case 'for': {
+            if (stmt.condition)
+                scanExpression(stmt.condition, boardConstants, line, col, diagnostics);
+            if (stmt.initializer)
+                scanStatement(stmt.initializer, boardConstants, diagnostics);
+            if (stmt.increment)
+                scanStatement(stmt.increment, boardConstants, diagnostics);
+            for (const s of stmt.body)
+                scanStatement(s, boardConstants, diagnostics);
+            break;
+        }
+        case 'for_of':
+        case 'for_in': {
+            if (stmt.variable)
+                scanStatement(stmt.variable, boardConstants, diagnostics);
+            for (const s of stmt.body)
+                scanStatement(s, boardConstants, diagnostics);
+            break;
+        }
+        case 'return': {
+            if (stmt.value)
+                scanExpression(stmt.value, boardConstants, line, col, diagnostics);
+            break;
+        }
+        case 'call': {
+            for (const arg of stmt.args) {
+                scanExpression(arg, boardConstants, line, col, diagnostics);
+            }
+            break;
+        }
+        case 'hal-op': {
+            // Statement-form HAL operation — the primary capability check target.
+            checkCapability(stmt.operation, line, col, boardConstants, diagnostics);
+            break;
+        }
+        case 'switch': {
+            if (stmt.expression)
+                scanExpression(stmt.expression, boardConstants, line, col, diagnostics);
+            for (const c of stmt.cases) {
+                for (const s of c.body)
+                    scanStatement(s, boardConstants, diagnostics);
+            }
+            break;
+        }
+        case 'block': {
+            for (const s of stmt.body)
+                scanStatement(s, boardConstants, diagnostics);
+            break;
+        }
+        case 'labeled': {
+            for (const s of stmt.body)
+                scanStatement(s, boardConstants, diagnostics);
+            break;
+        }
+        case 'try': {
+            for (const s of stmt.tryBlock)
+                scanStatement(s, boardConstants, diagnostics);
+            if (stmt.catchBlock)
+                for (const s of stmt.catchBlock)
+                    scanStatement(s, boardConstants, diagnostics);
+            if (stmt.finallyBlock)
+                for (const s of stmt.finallyBlock)
+                    scanStatement(s, boardConstants, diagnostics);
+            break;
+        }
+        case 'throw': {
+            if (stmt.value)
+                scanExpression(stmt.value, boardConstants, line, col, diagnostics);
+            break;
+        }
+        case 'update':
+        case 'break':
+        case 'continue':
+        case 'yield':
+        case 'super_call':
+            break;
+        default:
+            assertNever(stmt);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Validate that capability-specific methods are only called on pins that support them.
+ */
+export function validatePinCapabilities(program) {
+    const diagnostics = [];
+    const boardConstants = program.boardConstants;
+    if (program.topLevelStatements) {
+        for (const stmt of program.topLevelStatements) {
+            scanStatement(stmt, boardConstants, diagnostics);
+        }
+    }
+    if (program.functions) {
+        for (const fn of program.functions) {
+            if (fn.statements) {
+                for (const stmt of fn.statements) {
+                    scanStatement(stmt, boardConstants, diagnostics);
+                }
+            }
+        }
+    }
+    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) {
+                            scanStatement(stmt, boardConstants, diagnostics);
+                        }
+                    }
+                }
+            }
+            if (cls.constructor?.statements) {
+                for (const stmt of cls.constructor.statements) {
+                    scanStatement(stmt, boardConstants, diagnostics);
+                }
+            }
+        }
+    }
+    return diagnostics;
+}

package/dist/ir/pin-mode-validation.d.ts

@@ -0,0 +1,10 @@
+import type { ProgramIR } from '../api/index.js';
+import type { Diagnostic } from '../types.js';
+/**
+ * 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 declare function validatePinModeConfig(program: ProgramIR): Diagnostic[];