@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/peripheral-ownership.d.ts

@@ -0,0 +1,3 @@
+import type { ProgramIR } from '../api/index.js';
+import type { Diagnostic } from '../types.js';
+export declare function validatePeripheralOwnership(program: ProgramIR): Diagnostic[];

package/dist/ir/peripheral-ownership.js

@@ -0,0 +1,152 @@
+// ---------------------------------------------------------------------------
+// Peripheral Ownership Validation
+//
+// Validates opt-in bus ownership via take()/release(). When take() is used
+// anywhere in the program, this pass checks that:
+//   1. I/O on owned buses only occurs between take() and release()
+//   2. take() is not called on an already-owned bus (double-take error)
+//   3. release() is not called on a bus that wasn't taken
+//
+// If take() is never used, no diagnostics are generated (opt-in).
+// ---------------------------------------------------------------------------
+import { scanNestedStatements } from './interrupt-analysis.js';
+export function validatePeripheralOwnership(program) {
+    const diagnostics = [];
+    const ownedBuses = new Map();
+    const busesRequiringOwnership = new Set();
+    // Helper to extract the bus object from a property access (e.g., I2C0.begin -> I2C0)
+    const getBusName = (callee) => {
+        const busMatch = callee.match(/^(I2C\d|SPI\d|UART\d|Wire|Serial\d?)\b/);
+        return busMatch ? busMatch[1] : undefined;
+    };
+    /** Scan an expression for take() calls. */
+    const scanExpression = (expr, span) => {
+        if (!expr || typeof expr !== 'object')
+            return;
+        if (expr.kind === 'method-call') {
+            const bus = getBusName(expr.callee);
+            if (bus) {
+                if (expr.callee.endsWith('.take')) {
+                    if (ownedBuses.has(bus)) {
+                        diagnostics.push({
+                            severity: 'error',
+                            message: `Double-take: '${bus}' is already owned.`,
+                            hint: `Call '${bus}.release()' before taking it again.`,
+                            line: span.startLine,
+                            column: span.startColumn,
+                            code: 'hal-ownership-double-take',
+                            source: 'peripheral-ownership',
+                        });
+                    }
+                    ownedBuses.set(bus, span);
+                    busesRequiringOwnership.add(bus);
+                }
+            }
+            expr.args.forEach(arg => scanExpression(arg, span));
+        }
+        if (expr.kind === 'callback') {
+            expr.statements.forEach(checkStatement);
+        }
+    };
+    /** Scan a statement for I/O and release() calls. */
+    const checkStatement = (stmt) => {
+        if (!stmt || typeof stmt !== 'object')
+            return;
+        const span = stmt.sourceSpan;
+        if (stmt.kind === 'call') {
+            let bus = getBusName(stmt.callee);
+            let isRelease = stmt.callee.endsWith('.release');
+            let isBegin = stmt.callee.endsWith('.begin');
+            let isTake = stmt.callee.endsWith('.take');
+            // Special case: scan HAL-resolved emits for bus usage
+            if (stmt.callee === '__EMIT__' && stmt.args[0]?.kind === 'string') {
+                const rawCode = stmt.args[0].value;
+                const busMatch = rawCode.match(/\b(Wire|SPI|Serial\d?)\./);
+                if (busMatch) {
+                    const rawBus = busMatch[1];
+                    if (rawBus === 'Wire')
+                        bus = 'I2C0';
+                    else if (rawBus === 'SPI')
+                        bus = 'SPI0';
+                    else if (rawBus.startsWith('Serial'))
+                        bus = 'UART0';
+                }
+            }
+            if (bus) {
+                if (isTake) {
+                    if (ownedBuses.has(bus)) {
+                        diagnostics.push({
+                            severity: 'error',
+                            message: `Double-take: '${bus}' is already owned.`,
+                            hint: `Call '${bus}.release()' before taking it again.`,
+                            line: span.startLine,
+                            column: span.startColumn,
+                            code: 'hal-ownership-double-take',
+                            source: 'peripheral-ownership',
+                        });
+                    }
+                    ownedBuses.set(bus, span);
+                    busesRequiringOwnership.add(bus);
+                }
+                else if (isRelease) {
+                    if (!ownedBuses.has(bus)) {
+                        diagnostics.push({
+                            severity: 'warning',
+                            message: `'${bus}.release()' called but bus was not taken.`,
+                            hint: `Ensure you call '${bus}.take()' before releasing.`,
+                            line: span.startLine,
+                            column: span.startColumn,
+                            code: 'hal-ownership-unowned-release',
+                            source: 'peripheral-ownership',
+                        });
+                    }
+                    ownedBuses.delete(bus);
+                }
+                else if (busesRequiringOwnership.has(bus) && !ownedBuses.has(bus) && !isBegin) {
+                    // If ownership mode is opt-in and active for this bus, all calls must be owned
+                    diagnostics.push({
+                        severity: 'error',
+                        message: `Unowned access: '${bus}' is used without being taken.`,
+                        hint: `Call 'const bus = ${bus}.take();' and use the returned 'bus' object, or ensure '${bus}' is taken in the current scope.`,
+                        line: span.startLine,
+                        column: span.startColumn,
+                        code: 'hal-ownership-unowned-access',
+                        source: 'peripheral-ownership',
+                    });
+                }
+            }
+            stmt.args.forEach(arg => scanExpression(arg, span));
+        }
+        if (stmt.kind === 'var_decl' && stmt.initializer) {
+            scanExpression(stmt.initializer, span);
+        }
+        if (stmt.kind === 'assign' && stmt.value) {
+            scanExpression(stmt.value, span);
+        }
+        // Recurse into nested statements
+        scanNestedStatements(stmt, checkStatement);
+    };
+    // Scan top-level statements
+    for (const stmt of program.topLevelStatements) {
+        checkStatement(stmt);
+    }
+    // Scan function bodies
+    for (const fn of program.functions) {
+        for (const stmt of fn.statements) {
+            checkStatement(stmt);
+        }
+    }
+    // Check for unreleased buses at end of program
+    for (const [bus, busSpan] of ownedBuses) {
+        diagnostics.push({
+            severity: 'warning',
+            message: `'${bus}' was taken but never released.`,
+            hint: `Call '${bus}.release()' when finished with the bus.`,
+            line: busSpan.startLine,
+            column: busSpan.startColumn,
+            code: 'hal-ownership-leak',
+            source: 'peripheral-ownership',
+        });
+    }
+    return diagnostics;
+}

package/dist/ir/peripheral-symbols.d.ts

@@ -0,0 +1,7 @@
+type PeripheralReceiverKind = "i2c" | "spi" | "serial";
+export declare function inferPeripheralKindByName(name: string): PeripheralReceiverKind | undefined;
+export declare function parsePeripheralInstance(name: string): {
+    kind: PeripheralReceiverKind;
+    index: number;
+} | undefined;
+export {};

package/dist/ir/peripheral-symbols.js

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Peripheral symbol helpers
+//
+// Shared detection/parsing for named bus instances like I2C0, SPI1, UART0,
+// Serial, and Serial2.
+// ---------------------------------------------------------------------------
+const I2C_INSTANCE_PATTERN = /^I2C(\d+)$/;
+const SPI_INSTANCE_PATTERN = /^SPI(\d+)$/;
+const UART_INSTANCE_PATTERN = /^UART(\d+)$/;
+const SERIAL_INSTANCE_PATTERN = /^Serial(\d*)$/;
+import { getCurrentBoardConstants } from "./build-ir-state.js";
+export function inferPeripheralKindByName(name) {
+    const resolved = resolveCanonicalPeripheral(name);
+    return resolved?.kind;
+}
+export function parsePeripheralInstance(name) {
+    return resolveCanonicalPeripheral(name);
+}
+/**
+ * Resolves a peripheral name (e.g. "UART0", "Serial", "Wire", "I2C1")
+ * to its canonical kind and index using the current board manifest aliases.
+ */
+function resolveCanonicalPeripheral(name) {
+    const bc = getCurrentBoardConstants();
+    // 1. Check if name is already canonical (UART0, I2C1, etc.)
+    const canonicalMatch = name.match(/^(UART|I2C|SPI)(\d+)$/);
+    if (canonicalMatch) {
+        return {
+            kind: canonicalMatch[1] === "UART" ? "serial" : canonicalMatch[1].toLowerCase(),
+            index: parseInt(canonicalMatch[2], 10)
+        };
+    }
+    // 2. Check if name is a platform alias (e.g. "Serial" -> UART0)
+    if (bc) {
+        for (const [key, value] of bc.entries()) {
+            if (key.startsWith("peripherals.aliases.") && value === name) {
+                const canonical = key.replace("peripherals.aliases.", "");
+                const match = canonical.match(/^(UART|I2C|SPI)(\d+)$/);
+                if (match) {
+                    return {
+                        kind: match[1] === "UART" ? "serial" : match[1].toLowerCase(),
+                        index: parseInt(match[2], 10)
+                    };
+                }
+            }
+        }
+    }
+    // 3. Fallback to standard Arduino patterns (e.g. Serial2 -> UART2)
+    const serialMatch = name.match(/^Serial(\d*)$/);
+    if (serialMatch) {
+        return {
+            kind: "serial",
+            index: serialMatch[1] === "" ? 0 : parseInt(serialMatch[1], 10)
+        };
+    }
+    return undefined;
+}

package/dist/ir/peripheral-usage.d.ts

@@ -0,0 +1,54 @@
+import type { ProgramIR } from '../api/index.js';
+/**
+ * Tracks which hardware peripherals are used in the program.
+ */
+export interface PeripheralUsage {
+    /** ADC is used (analogRead on A0-A5) */
+    adc: boolean;
+    /** PWM is used (analogWrite on D3, D5, D6, D9, D10, D11) */
+    pwm: boolean;
+    /** External interrupts are used (attachInterrupt on D2, D3) */
+    externalInterrupts: boolean;
+    /** Timer0-based timing is used (millis, micros) */
+    timer0: boolean;
+    /** I2C bus is used */
+    i2c: boolean;
+    /** SPI bus is used */
+    spi: boolean;
+    /** UART/Serial is used */
+    uart: boolean;
+    /** Specific PWM pins used (for targeted timer initialization) */
+    pwmPinsUsed: Set<number>;
+    /** Specific ADC channels used */
+    adcChannelsUsed: Set<number>;
+    /** Pins configured as output (for batch DDR initialization) */
+    outputPins: Set<number>;
+    /** Pins configured as input with pullup */
+    inputPullupPins: Set<number>;
+    /** Pins configured as input (no pullup) */
+    inputPins: Set<number>;
+    /** Pins configured as input with pulldown */
+    inputPulldownPins: Set<number>;
+    /** Specific I2C bus instances used (0 for I2C0, 1 for I2C1, etc.) */
+    i2cInstancesUsed: Set<number>;
+    /** Specific SPI bus instances used (0 for SPI0, 1 for SPI1, etc.) */
+    spiInstancesUsed: Set<number>;
+    /** Specific UART instances used (0 for UART0/Serial, 1 for UART1/Serial1, etc.) */
+    uartInstancesUsed: Set<number>;
+    /** All pin names used (for unsafe pin validation) */
+    pinsUsed: Set<string>;
+    /** Specific pins used for external interrupts */
+    interruptPinsUsed: Set<number>;
+}
+/**
+ * Create an empty PeripheralUsage object.
+ */
+export declare function createEmptyPeripheralUsage(): PeripheralUsage;
+/**
+ * Analyze a program's IR to detect peripheral usage.
+ */
+export declare function analyzePeripheralUsage(program: ProgramIR): PeripheralUsage;
+/**
+ * Parse pin number from receiver string (D13 -> 13, A0 -> 14, LED -> 13)
+ */
+export declare function parsePinNumber(receiver: string): number | null;