@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/adc-range-validation.js

@@ -0,0 +1,250 @@
+// ---------------------------------------------------------------------------
+// ADC Range Validation
+//
+// Detects comparisons against analogRead() values that exceed the board's
+// ADC resolution (e.g., comparing to > 1023 on a 10-bit Arduino Uno).
+// ---------------------------------------------------------------------------
+/**
+ * Get ADC configuration from board constants.
+ */
+function getADCConfig(boardConstants) {
+    if (!boardConstants)
+        return null;
+    // Try to get ADC resolution from board constants
+    const resolution = boardConstants.get('peripherals.adc.0.resolution');
+    if (resolution !== undefined) {
+        return {
+            resolution,
+            maxValue: Math.pow(2, resolution) - 1,
+        };
+    }
+    // No board ADC resolution available — cannot validate
+    return null;
+}
+/**
+ * Check if an expression is an analog read.
+ *
+ * Two IR shapes carry an ADC read inline:
+ *   - `hal-expr` with operation `adc.read` / `adc.read_voltage` (the structured
+ *     HAL form — the common case for `A0.readAnalog()` inline in a comparison)
+ *   - `raw` whose value text contains `analogRead(` (the lowered text form,
+ *     reached when the HAL op has already been resolved to C++ text)
+ * An assignment `const v = A0.readAnalog(); if (v > 2000)` is NOT caught — `v`
+ * is an identifier by the comparison site, and correlating the two would
+ * require data-flow analysis beyond this validator's scope.
+ */
+function isAnalogRead(expr) {
+    if (!expr || typeof expr !== 'object')
+        return false;
+    if (expr.kind === 'hal-expr') {
+        const op = expr.operation?.operation;
+        return op === 'adc.read' || op === 'adc.read_voltage';
+    }
+    if (expr.kind === 'raw') {
+        return /analogRead\s*\(/.test(expr.value);
+    }
+    return false;
+}
+/**
+ * Try to extract a numeric value from an expression.
+ */
+function extractNumericValue(expr) {
+    if (!expr || typeof expr !== 'object')
+        return null;
+    if (expr.kind === 'number') {
+        return expr.value;
+    }
+    return null;
+}
+/**
+ * Check binary comparison expressions for ADC range issues.
+ */
+function checkComparisonForADCRange(left, operator, right, adcConfig, diagnostics) {
+    // Check if one side is an analog read and the other is a literal
+    let analogReadSide = null;
+    let literalValue = null;
+    if (isAnalogRead(left) && extractNumericValue(right) !== null) {
+        analogReadSide = 'left';
+        literalValue = extractNumericValue(right);
+    }
+    else if (isAnalogRead(right) && extractNumericValue(left) !== null) {
+        analogReadSide = 'right';
+        literalValue = extractNumericValue(left);
+    }
+    if (analogReadSide === null || literalValue === null)
+        return;
+    // Check if the literal exceeds ADC max
+    if (literalValue > adcConfig.maxValue) {
+        // Adjust operator based on which side the analog read is on
+        const comparisonDesc = analogReadSide === 'left'
+            ? `analogRead() ${operator} ${literalValue}`
+            : `${literalValue} ${operator} analogRead()`;
+        diagnostics.push({
+            severity: 'info',
+            message: `Comparison ${comparisonDesc} may never be true. ADC resolution is ${adcConfig.resolution}-bit (max ${adcConfig.maxValue}) on this board.`,
+            code: 'adc-range-warning',
+            source: 'adc-range-validation',
+        });
+    }
+}
+/**
+ * Scan an expression for ADC range issues.
+ */
+function scanExpressionForADCRange(expr, adcConfig, diagnostics) {
+    if (!expr || typeof expr !== 'object')
+        return;
+    // Check binary comparisons
+    if (expr.kind === 'binary') {
+        const bin = expr;
+        const comparisonOps = ['>', '>=', '<', '<=', '===', '==', '!==', '!='];
+        if (comparisonOps.includes(bin.operator)) {
+            checkComparisonForADCRange(bin.left, bin.operator, bin.right, adcConfig, diagnostics);
+        }
+        // Recursively scan both sides
+        scanExpressionForADCRange(bin.left, adcConfig, diagnostics);
+        scanExpressionForADCRange(bin.right, adcConfig, diagnostics);
+    }
+    // Check ternary conditions
+    if (expr.kind === 'ternary') {
+        const ternary = expr;
+        scanExpressionForADCRange(ternary.condition, adcConfig, diagnostics);
+        scanExpressionForADCRange(ternary.whenTrue, adcConfig, diagnostics);
+        scanExpressionForADCRange(ternary.whenFalse, adcConfig, diagnostics);
+    }
+    // Check property access
+    if (expr.kind === 'property-access') {
+        const pa = expr;
+        scanExpressionForADCRange(pa.object, adcConfig, diagnostics);
+    }
+}
+/**
+ * Scan a statement for ADC range issues.
+ */
+function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
+    if (!stmt || typeof stmt !== 'object')
+        return;
+    switch (stmt.kind) {
+        case 'var_decl': {
+            const varDecl = stmt;
+            if (varDecl.initializer) {
+                scanExpressionForADCRange(varDecl.initializer, adcConfig, diagnostics);
+            }
+            break;
+        }
+        case 'assign': {
+            const assign = stmt;
+            if (assign.value) {
+                scanExpressionForADCRange(assign.value, adcConfig, diagnostics);
+            }
+            break;
+        }
+        case 'if': {
+            const ifStmt = stmt;
+            if (ifStmt.condition) {
+                scanExpressionForADCRange(ifStmt.condition, adcConfig, diagnostics);
+            }
+            if (ifStmt.thenBranch) {
+                for (const s of ifStmt.thenBranch) {
+                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                }
+            }
+            if (ifStmt.elseBranch) {
+                for (const s of ifStmt.elseBranch) {
+                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                }
+            }
+            break;
+        }
+        case 'while': {
+            const whileStmt = stmt;
+            if (whileStmt.condition) {
+                scanExpressionForADCRange(whileStmt.condition, adcConfig, diagnostics);
+            }
+            if (whileStmt.body) {
+                for (const s of whileStmt.body) {
+                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                }
+            }
+            break;
+        }
+        case 'for': {
+            const forStmt = stmt;
+            if (forStmt.condition) {
+                scanExpressionForADCRange(forStmt.condition, adcConfig, diagnostics);
+            }
+            if (forStmt.body) {
+                for (const s of forStmt.body) {
+                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                }
+            }
+            break;
+        }
+        case 'return': {
+            const retStmt = stmt;
+            if (retStmt.value) {
+                scanExpressionForADCRange(retStmt.value, adcConfig, diagnostics);
+            }
+            break;
+        }
+        case 'call': {
+            const call = stmt;
+            if (call.args) {
+                for (const arg of call.args) {
+                    scanExpressionForADCRange(arg, adcConfig, diagnostics);
+                }
+            }
+            break;
+        }
+        default:
+            break;
+    }
+}
+/**
+ * Validate ADC range comparisons in a program.
+ *
+ * @param program - The program IR to validate
+ * @param boardConstants - Board constants containing ADC resolution
+ * @returns Array of diagnostics for ADC range issues
+ */
+export function validateADCRange(program, boardConstants) {
+    const diagnostics = [];
+    const adcConfig = getADCConfig(boardConstants);
+    if (!adcConfig)
+        return diagnostics;
+    // Scan top-level statements
+    if (program.topLevelStatements) {
+        for (const stmt of program.topLevelStatements) {
+            scanStatementForADCRange(stmt, adcConfig, diagnostics);
+        }
+    }
+    // Scan function bodies
+    if (program.functions) {
+        for (const fn of program.functions) {
+            if (fn.statements) {
+                for (const stmt of fn.statements) {
+                    scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                }
+            }
+        }
+    }
+    // Scan class methods
+    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) {
+                            scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                        }
+                    }
+                }
+            }
+            if (cls.constructor?.statements) {
+                for (const stmt of cls.constructor.statements) {
+                    scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                }
+            }
+        }
+    }
+    return diagnostics;
+}

package/dist/ir/ast-node-utils.d.ts

@@ -0,0 +1,8 @@
+import ts from "typescript";
+import { Diagnostic, SourceSpan } from "../types.js";
+export declare function makeDiagnostic(sourceText: string, position: number, message: string, severity?: Diagnostic["severity"], code?: string): Diagnostic;
+export declare function makeSourceSpan(node: ts.Node, filePath: string, sourceText: string): SourceSpan;
+export declare function extractNodeComments(node: ts.Node, sourceText: string): {
+    leadingComments: string[];
+    trailingComments: string[];
+};

package/dist/ir/ast-node-utils.js

@@ -0,0 +1,32 @@
+import ts from "typescript";
+import { withLineColumn } from "../utils/strings.js";
+export function makeDiagnostic(sourceText, position, message, severity = "warning", code) {
+    const { line, column } = withLineColumn(sourceText, position);
+    return { severity, message, line, column, code };
+}
+export function makeSourceSpan(node, filePath, sourceText) {
+    const startOffset = node.getStart();
+    const endOffset = node.getEnd();
+    const start = withLineColumn(sourceText, startOffset);
+    const end = withLineColumn(sourceText, endOffset);
+    return {
+        filePath,
+        startOffset,
+        endOffset,
+        startLine: start.line,
+        startColumn: start.column,
+        endLine: end.line,
+        endColumn: end.column,
+    };
+}
+export function extractNodeComments(node, sourceText) {
+    const leadingRanges = ts.getLeadingCommentRanges(sourceText, node.getFullStart()) ?? [];
+    const trailingRanges = ts.getTrailingCommentRanges(sourceText, node.getEnd()) ?? [];
+    const normalize = (ranges) => ranges
+        .map((range) => sourceText.slice(range.pos, range.end).trim())
+        .filter((value) => value.length > 0);
+    return {
+        leadingComments: normalize(leadingRanges),
+        trailingComments: normalize(trailingRanges),
+    };
+}

package/dist/ir/board-pin-utils.d.ts

@@ -0,0 +1,13 @@
+import type { BoardConstants } from './board-resolver.js';
+interface BoardPinInfo {
+    number?: number;
+    name: string;
+    aliases: string[];
+    warnings: string[];
+    note?: string;
+    alternateFunctions: string[];
+}
+export declare function getBoardPins(boardConstants: BoardConstants | undefined): BoardPinInfo[];
+export declare function findBoardPinByName(pinName: string, boardConstants: BoardConstants | undefined): BoardPinInfo | undefined;
+export declare function formatPinReference(usedPinName: string, boardPin: BoardPinInfo | undefined): string;
+export {};

package/dist/ir/board-pin-utils.js

@@ -0,0 +1,65 @@
+function parseCsvField(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map(entry => entry.trim())
+        .filter(Boolean);
+}
+export function getBoardPins(boardConstants) {
+    if (!boardConstants) {
+        return [];
+    }
+    const pins = [];
+    for (const [key, value] of boardConstants) {
+        if (!key.startsWith('pins.all.') || !key.endsWith('.name') || typeof value !== 'string') {
+            continue;
+        }
+        const prefix = key.slice(0, -'.name'.length);
+        const numberValue = boardConstants.get(`${prefix}.number`);
+        const aliases = parseCsvField(boardConstants.get(`${prefix}.aliases`));
+        const warnings = parseCsvField(boardConstants.get(`${prefix}.warnings`));
+        const alternateFunctions = parseCsvField(boardConstants.get(`${prefix}.alternateFunctions`));
+        const noteValue = boardConstants.get(`${prefix}.notes`);
+        pins.push({
+            number: typeof numberValue === 'number' ? numberValue : undefined,
+            name: value,
+            aliases,
+            warnings,
+            note: typeof noteValue === 'string' && noteValue.length > 0 ? noteValue : undefined,
+            alternateFunctions,
+        });
+    }
+    return pins.sort((left, right) => {
+        const leftNumber = left.number ?? Number.MAX_SAFE_INTEGER;
+        const rightNumber = right.number ?? Number.MAX_SAFE_INTEGER;
+        return leftNumber - rightNumber || left.name.localeCompare(right.name);
+    });
+}
+export function findBoardPinByName(pinName, boardConstants) {
+    const pins = getBoardPins(boardConstants);
+    const match = pins.find(pin => pin.name === pinName || pin.aliases.includes(pinName));
+    if (match)
+        return match;
+    // Fallback: resolve D/A patterns by pin number.
+    // D3 → pin with number 3, A0 → pin with number 0+analogOffset.
+    const dMatch = pinName.match(/^D(\d+)$/);
+    if (dMatch) {
+        const num = parseInt(dMatch[1], 10);
+        return pins.find(pin => pin.number === num);
+    }
+    const aMatch = pinName.match(/^A(\d+)$/);
+    if (aMatch && boardConstants) {
+        const offset = Number(boardConstants.get('pins.analogOffset') ?? 0);
+        const num = parseInt(aMatch[1], 10) + offset;
+        return pins.find(pin => pin.number === num);
+    }
+    return undefined;
+}
+export function formatPinReference(usedPinName, boardPin) {
+    if (!boardPin || usedPinName === boardPin.name) {
+        return `Pin '${usedPinName}'`;
+    }
+    return `Pin '${usedPinName}' (alias of ${boardPin.name})`;
+}

package/dist/ir/board-resolver.d.ts

@@ -0,0 +1,36 @@
+import type { BoardConstants } from "../api/shared/index.js";
+export type { BoardConstants };
+/**
+ * Returns a set of default board constants (standard Arduino Uno-like)
+ * used as a fallback when no specific board manifest is loaded.
+ */
+export declare function getDefaultBoardConstants(): BoardConstants;
+/**
+ * Parse a TypeScript board-definition source file and return a flat map of
+ * all compile-time constant scalar values exported as a `BoardDefinition`.
+ *
+ * Properties whose values are arrays, spread elements, or other non-literal
+ * expressions are silently skipped (no partial constant maps for board pins
+ * etc. are needed by the emitter).
+ *
+ * @param defFilePath  Absolute path to the board definition `index.ts`.
+ */
+export declare function resolveBoardConstants(defFilePath: string): BoardConstants;
+/**
+ * Given a source file path and a relative import module specifier, check
+ * whether the import resolves to a TypeCAD board-definition package
+ * (path pattern: /code/board-*\/index.ts).
+ *
+ * Returns the absolute path to the board index.ts on match, otherwise
+ * undefined.
+ */
+export declare function tryResolveBoardDefFile(fromFile: string, moduleSpecifier: string, boardPackage?: string): string | undefined;
+/**
+ * Resolve the framework-specific build target (e.g. Arduino FQBN) from the
+ * board package's manifest.
+ *
+ * @param boardPackage  Board package identifier or path.
+ * @param configPath    Path to the project config file (for relative resolution).
+ * @param framework     Target framework name (default: 'arduino').
+ */
+export declare function resolveBoardBuildTarget(boardPackage: string, configPath: string, framework?: string): string | undefined;