@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.6

package/dist/ir/timing-validation.js

@@ -51,6 +51,7 @@ export function validateBlockingDelayInLoop(program) {
                         `or use Async.sleep(ms) / Async.yield() to let other tasks run between checks.`,
                     line: stmt.sourceSpan?.startLine,
                     column: stmt.sourceSpan?.startColumn,
+                    filePath: stmt.sourceSpan?.filePath,
                     code: 'blocking-delay-in-loop',
                     source: 'timing-validation',
                 });

package/dist/ir/transformers/variables.js

@@ -14,6 +14,9 @@ function replaceHalReadBufferPlaceholder(op, varName) {
     if (op.operation === "i2c.read_buffer" && op.buffer === "__HAL_READ_BUF__") {
         return { ...op, buffer: varName };
     }
+    if (op.operation === "spi.read_buffer" && op.buffer === "__HAL_READ_BUF__") {
+        return { ...op, buffer: varName };
+    }
     return op;
 }
 export function assignmentOperatorToString(kind) {
@@ -430,6 +433,45 @@ export function variableStatementToIR(statement, fileName, sourceText, diagnosti
                 const isSingletonReceiver = ts.isIdentifier(receiver) && isHALSingleton(receiver.text);
                 if (result && (!isOwnershipMethod || isSingletonReceiver)) {
                     const isHalOpReturn = result.returnValue === "__hal_op_return__";
+                    // A __TYPED_ARRAY__ return comes ONLY from a HAL method body
+                    // (`return new Uint8Array(count)` in e.g. I2CDevice.readBytes /
+                    // SPIDevice.readRegister). The method's side-effect HAL ops (the
+                    // i2c.read_buffer / spi.read_buffer fill loops) write INTO this buffer
+                    // via the __HAL_READ_BUF__ placeholder (rewritten to `varName`). So the
+                    // buffer var_decl MUST precede the fill ops in emitted order — at top
+                    // level the var_decl is hoisted to file scope which masks this, but a
+                    // function-local `const data = ...readBytes()` would otherwise emit the
+                    // fill loop referencing `data` before its declaration. Detect the typed
+                    // array up front so we can emit its declaration first.
+                    const isTypedArrayReturn = typeof result.returnValue === "string" && result.returnValue.startsWith("__TYPED_ARRAY__:");
+                    if (isTypedArrayReturn && typeof result.returnValue === "string") {
+                        const parts = result.returnValue.split(":");
+                        const elementType = parts[1];
+                        const size = parts[2];
+                        // Force non-const storage (the buffer is written by the fill op) and
+                        // synthesize a zero-init array initializer so the var_decl renderer
+                        // emits `T data[] = { 0, 0, ... }` — a bare `const T data[N];` that
+                        // is later written would fail to compile (assignment to const).
+                        // Mirrors plain `new Uint8Array(N)` (expression-to-ir.ts).
+                        const count = parseInt(size, 10);
+                        const initElements = !isNaN(count) && count > 0 && count <= 256
+                            ? Array(count).fill(0).map(() => ({ kind: "number", value: 0 }))
+                            : [];
+                        lowered.push({
+                            kind: "var_decl",
+                            sourceSpan: makeSourceSpan(declaration, fileName, sourceText),
+                            leadingComments: commentsAssigned ? [] : statementComments.leadingComments,
+                            trailingComments: [],
+                            name: varName,
+                            storage: "let",
+                            cppType: `${elementType}[${size}]`,
+                            initializer: initElements.length > 0
+                                ? { kind: "array", elements: initElements, elementType }
+                                : undefined,
+                        });
+                        activeCArrayVars.add(varName);
+                        commentsAssigned = true;
+                    }
                     if (result.halOps && result.halOps.length > 0) {
                         const sideEffectOps = isHalOpReturn ? result.halOps.slice(0, -1) : result.halOps;
                         const halStmts = sideEffectOps.map(op => ({
@@ -527,24 +569,11 @@ export function variableStatementToIR(statement, fileName, sourceText, diagnosti
                             if (/\b\d+\.\d+\b/.test(result.returnValue)) {
                                 registerFloatVariable(varName);
                             }
+                            // __TYPED_ARRAY__ returns are handled above (declared BEFORE the
+                            // fill ops). Everything else is a scalar/value return captured
+                            // after the side-effect ops.
                             const isTypedArray = result.returnValue.startsWith("__TYPED_ARRAY__:");
-                            if (isTypedArray) {
-                                const parts = result.returnValue.split(":");
-                                const elementType = parts[1];
-                                const size = parts[2];
-                                lowered.push({
-                                    kind: "var_decl",
-                                    sourceSpan: makeSourceSpan(declaration, fileName, sourceText),
-                                    leadingComments: commentsAssigned ? [] : statementComments.leadingComments,
-                                    trailingComments: [],
-                                    name: varName,
-                                    storage,
-                                    cppType: `${elementType}[${size}]`,
-                                    initializer: undefined,
-                                });
-                                activeCArrayVars.add(varName);
-                            }
-                            else {
+                            if (!isTypedArray) {
                                 lowered.push({
                                     kind: "var_decl",
                                     sourceSpan: makeSourceSpan(declaration, fileName, sourceText),

package/dist/ir/try-catch-validation.js

@@ -39,6 +39,7 @@ export function validateTryCatch(program, boardConstants, strategy) {
                 hint: `function readSensor(): number | null {\n  const data = sensor.read();\n  if (!data) return null;  // error path\n  return data.value;       // success path\n}`,
                 line: stmt.sourceSpan?.startLine,
                 column: stmt.sourceSpan?.startColumn,
+                filePath: stmt.sourceSpan?.filePath,
                 source: 'try-catch-validation',
             });
             // Still recurse into nested blocks to find other try/catch
@@ -57,6 +58,7 @@ export function validateTryCatch(program, boardConstants, strategy) {
                 hint: `return null;  // or return an error code`,
                 line: stmt.sourceSpan?.startLine,
                 column: stmt.sourceSpan?.startColumn,
+                filePath: stmt.sourceSpan?.filePath,
                 source: 'try-catch-validation',
             });
             return;

package/dist/ir/type-resolution.js

@@ -33,9 +33,9 @@ const PIN_INTERFACE_TYPE_NAMES = new Set([
     "PinMode", "InterruptMode",
 ]);
 const BUS_INTERFACE_TYPE_NAMES = new Set([
-    "II2CBus", "ISPIBus", "ISerialPort", "IUART",
+    "II2CBus", "ISPIBus", "ISerialPort",
     "I2CConfig", "SPIConfig", "UARTConfig",
-    "I2CAddress", "UARTStatus", "SPITransferOptions",
+    "I2CAddress", "SPITransferOptions",
 ]);
 const STRATEGY_TYPE_NAMES = new Set([
     "NativeStrategy", "ArduinoStrategy", "BoardStrategy",

package/dist/ir/unit-suspicion-validation.js

@@ -130,7 +130,7 @@ function checkSPIFrequency(value) {
  * baud rate used as SPI freq, etc.). Only literal numbers are checked —
  * expressions/variables are opaque to this validator.
  */
-function checkConfigValue(kind, rawValue, diagnostics) {
+function checkConfigValue(kind, rawValue, filePath, diagnostics) {
     // HAL ops carry resolved numeric values as `number` when the source arg was
     // a literal, or as `string` expression text otherwise. Only check numbers.
     const value = typeof rawValue === 'number' ? rawValue
@@ -146,6 +146,7 @@ function checkConfigValue(kind, rawValue, diagnostics) {
             severity: 'warning',
             message,
             code: 'unit-suspicion',
+            filePath,
             source: 'unit-suspicion-validation',
         });
     }
@@ -160,15 +161,16 @@ function scanStatement(stmt, diagnostics) {
     if (!stmt || typeof stmt !== 'object')
         return;
     const s = stmt;
+    const filePath = s.sourceSpan?.filePath;
     // HAL-op statements carry structured operations with resolved values.
     if (stmt.kind === 'hal-op' && s.operation) {
         const op = s.operation;
         switch (op.operation) {
             case 'i2c.set_clock':
-                checkConfigValue('i2c', op.hz, diagnostics);
+                checkConfigValue('i2c', op.hz, filePath, diagnostics);
                 break;
             case 'uart.begin':
-                checkConfigValue('baud', op.baud, diagnostics);
+                checkConfigValue('baud', op.baud, filePath, diagnostics);
                 break;
             // SPI frequency flows through SPISettings construction text, which the
             // HAL op carries as a string — the numeric extraction in
@@ -178,7 +180,7 @@ function scanStatement(stmt, diagnostics) {
                     // SPISettings({freq}, ...) — try to extract the leading frequency.
                     const m = op.settings.match(/^\s*(\d+)/);
                     if (m)
-                        checkConfigValue('spi', parseInt(m[1], 10), diagnostics);
+                        checkConfigValue('spi', parseInt(m[1], 10), filePath, diagnostics);
                 }
                 break;
         }
@@ -188,18 +190,18 @@ function scanStatement(stmt, diagnostics) {
     if (stmt.kind === 'call' && typeof s.callee === 'string' && Array.isArray(s.args)) {
         const method = s.callee.split('.').pop() ?? s.callee;
         if (method === 'setClock' && s.args.length >= 2) {
-            checkConfigValue('i2c', extractNumericValue(s.args[1]), diagnostics);
+            checkConfigValue('i2c', extractNumericValue(s.args[1]), filePath, diagnostics);
         }
         else if (method === 'setBaudRate' || method === 'begin') {
             // Serial.begin(baud) / setBaudRate(baud) — last numeric arg is the baud.
             for (const arg of s.args) {
                 const v = extractNumericValue(arg);
                 if (v !== undefined)
-                    checkConfigValue('baud', v, diagnostics);
+                    checkConfigValue('baud', v, filePath, diagnostics);
             }
         }
         else if (method === 'setFrequency' && s.args.length >= 2) {
-            checkConfigValue('spi', extractNumericValue(s.args[1]), diagnostics);
+            checkConfigValue('spi', extractNumericValue(s.args[1]), filePath, diagnostics);
         }
     }
     // Recurse into nested statements

package/dist/ir/validation-orchestrator.js

@@ -23,13 +23,13 @@ export function runProgramValidations(program, strategy) {
     const diagnostics = [];
     const peripheralUsage = program.peripheralUsage ?? createEmptyPeripheralUsage();
     diagnostics.push(...validatePinCapabilities(program));
-    diagnostics.push(...validatePeripherals(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validateUnsafePins(peripheralUsage, program.boardConstants));
+    diagnostics.push(...validatePeripherals(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validateUnsafePins(peripheralUsage, program.boardConstants, program.fileName));
     diagnostics.push(...analyzeResources(program, resolvedStrategy));
-    diagnostics.push(...validatePinAliasConflicts(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validatePWMTimerSharing(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validateTimer0PWMTimingConflict(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validatePulldownSupport(peripheralUsage, program.boardConstants));
+    diagnostics.push(...validatePinAliasConflicts(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validatePWMTimerSharing(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validateTimer0PWMTimingConflict(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validatePulldownSupport(peripheralUsage, program.boardConstants, program.fileName));
     diagnostics.push(...analyzeInterruptSafety(program, peripheralUsage));
     inferVolatileForIsrSharedVars(program, diagnostics);
     detectReentrancyRisk(program, diagnostics);

package/dist/licenses.d.ts

@@ -0,0 +1,185 @@
+export type CopyleftRisk = "permissive" | "weak-copyleft" | "strong-copyleft" | "unknown";
+export type LicenseSource = "library.properties" | "license-file" | "source-header" | "none";
+export interface LibraryLicenseEntry {
+    name: string;
+    version: string | undefined;
+    /** install_dir as reported by arduino-cli lib list. */
+    path: string;
+    /** Normalized SPDX ID (e.g. "BSD-3-Clause"); undefined if not determined. */
+    spdx: string | undefined;
+    risk: CopyleftRisk;
+    source: LicenseSource;
+}
+export type ScanOutcome = {
+    ok: true;
+    libraries: LibraryLicenseEntry[];
+} | {
+    ok: false;
+    reason: "arduino-cli-not-found" | "arduino-cli-unresponsive" | "no-libraries";
+    message: string;
+};
+/**
+ * Headers the project needs. `source` is "ino" when read from the generated
+ * .ino (authoritative) or "config" when derived from cuttlefish.config.ts
+ * (partial: display/touch only).
+ */
+export type ProjectHeaders = {
+    ok: true;
+    headers: string[];
+    source: "ino" | "config";
+    inoPath?: string;
+} | {
+    ok: false;
+    reason: "no-config" | "no-entry" | "unreadable-ino";
+    message: string;
+};
+/**
+ * Minimal view of ResolvedCuttlefishConfig that resolveProjectHeaders needs.
+ * Kept structural so we don't import the full config type (avoids a cycle).
+ */
+interface ProjectConfig {
+    configPath: string;
+    entry?: string;
+    outputOutDir?: string;
+    /** FQBN, e.g. 'arduino:avr:uno'. Used to resolve the board core for core-bundled libs. */
+    buildTarget?: string;
+    display?: {
+        profile?: string;
+        driver?: string;
+        touch?: {
+            library?: string;
+        };
+    } | null;
+}
+/** Classify a header as a compiler-toolchain C-library header. */
+export declare function isToolchainHeader(header: string): boolean;
+/**
+ * Result of resolving the project's board core directory.
+ */
+export type ProjectCore = {
+    ok: true;
+    coreDir: string;
+} | {
+    ok: false;
+    reason: "no-fqbn" | "no-core";
+    message: string;
+};
+/**
+ * Resolve the project's board-core directory from its FQBN, via
+ * `arduino-cli config dump` (for the packages data dir) and the on-disk
+ * `<data>/packages/<packager>/hardware/<arch>/<version>/` layout. Returns the
+ * highest-versioned core dir. Never throws.
+ *
+ * `runConfigDump` is an injected seam (returns the `config dump` stdout, or ""
+ * on failure) so the function is unit-testable without spawning.
+ */
+export declare function resolveProjectCore(fqbn: string | undefined, runConfigDump: () => string, readdir: (d: string) => string[]): ProjectCore;
+/**
+ * Resolve the project's library headers. Prefers the generated .ino
+ * (authoritative); falls back to display/touch headers derived from config
+ * (partial picture, no transpile required).
+ */
+export declare function resolveProjectHeaders(config: ProjectConfig | undefined, readFile: (p: string) => string | undefined): ProjectHeaders;
+/**
+ * One project header, joined to its owning library or flagged not-installed.
+ */
+export type ProjectLibrary = {
+    kind: "resolved";
+    lib: LibraryLicenseEntry;
+} | {
+    kind: "core";
+    header: string;
+} | {
+    kind: "not-installed";
+    header: string;
+};
+/**
+ * Build a header-basename -> bundled-library map from a board core's bundled
+ * libraries. Scans `<coreDir>/libraries/<Lib>/src/` for .h files (e.g. Wire.h,
+ * SPI.h). Each header maps to a synthetic RawArduinoLibrary so the existing
+ * resolveLibraryLicense can read its license from the bundled lib's header
+ * notice or library.properties.
+ */
+export declare function buildCoreHeaderIndex(coreDir: string, readdir: (d: string) => string[]): Map<string, RawArduinoLibrary>;
+/**
+ * Join each project header to its owning library or classify it. Pipeline:
+ *   1. user library (arduino-cli lib list)  -> resolved (license)
+ *   2. core library (project's own core)    -> resolved (license, e.g. LGPL-2.1)
+ *   3. toolchain header (avr/*, util/*)     -> core (gray, no license)
+ *   4. else                                  -> not-installed
+ *
+ * `coreDir` is optional; when absent, step 2 is skipped.
+ */
+export declare function joinHeadersToLibraries(headers: string[], libs: RawArduinoLibrary[], readdir: (d: string) => string[], readFile: (p: string) => string | undefined, coreDir?: string): ProjectLibrary[];
+/**
+ * Resolve a raw license input (either the short `library.properties` `license=`
+ * value, the full text of a LICENSE file, or a source-file header comment) to a
+ * canonical SPDX ID.
+ *
+ * Matching priority:
+ *   1. SPDX-License-Identifier: <id> marker (authoritative when present)
+ *   2. exact alias match (suits the short properties value)
+ *   3. substring markers match, ALL markers required (suits full LICENSE text)
+ *   4. shortMarkers match, ANY one sufficient (suits sparse header comments
+ *      like Adafruit's "BSD license, all text here must be included")
+ *
+ * Returns the SPDX ID string, or undefined if nothing matched.
+ */
+export declare function identifySpdx(input: string): string | undefined;
+/**
+ * Classify the copyleft risk of a known SPDX ID. Returns "unknown" for
+ * unrecognized ids.
+ */
+export declare function classifyRisk(spdx: string): CopyleftRisk;
+/** Raw library entry as it appears in `arduino-cli lib list --format json`. */
+export interface RawArduinoLibrary {
+    name: string;
+    version?: string;
+    install_dir?: string;
+}
+/**
+ * Options for `scanLicenses`. Production calls omit this object entirely; tests
+ * inject `fakeLibList` and `fakeReadFile` to avoid spawning and disk I/O.
+ */
+export interface ScanOptions {
+    /** Override the `arduino-cli lib list` call. Return null to simulate spawn failure. */
+    fakeLibList?: () => RawArduinoLibrary[] | null;
+    /** Override disk reads of library.properties and LICENSE files. */
+    fakeReadFile?: (p: string) => string | undefined;
+    /** Override directory listings. */
+    fakeReaddir?: (d: string) => string[];
+}
+/**
+ * Normalize either JSON shape (wrapped or bare array) to a flat library list.
+ * Exported for direct unit testing of the dual-shape parsing.
+ */
+export declare function coerceLibList(parsed: unknown): RawArduinoLibrary[];
+/**
+ * Module-level runner override used by presenter tests so `scanLicenses()`
+ * (with no args) does not spawn. Mirrors __setArduinoCliRunnerForTest.
+ */
+export interface LicensesRunner {
+    listLibraries: () => RawArduinoLibrary[] | null;
+    readFile: (p: string) => string | undefined;
+    readdir: (d: string) => string[];
+}
+/** @internal Test-only override of the default runner. */
+export declare function __setLicensesRunnerForTest(runner: LicensesRunner | undefined): void;
+/**
+ * Scan installed Arduino libraries and resolve each one's license. Never throws.
+ */
+export declare function scanLicenses(options?: ScanOptions): ScanOutcome;
+/** @internal Test-only override of the project config (normally loaded via loadCuttlefishConfig). */
+export declare function __setProjectConfigForTest(config: ProjectConfig | undefined): void;
+/** @internal Test-only override of `arduino-cli config dump` stdout. */
+export declare function __setConfigDumpForTest(fn: (() => string) | undefined): void;
+/**
+ * `cuttlefish licenses` presenter. `all === false` (default, project scope)
+ * resolves this project's libraries from the generated .ino (or config
+ * fallback), joins each to an installed library, and reports only those.
+ * `all === true` reports every installed library (the original behavior).
+ * Warns on unknown licenses; flags NOT INSTALLED headers in project scope; sets
+ * process.exitCode under --strict. Never calls process.exit().
+ */
+export declare function runLicensesPresenter(strict: boolean, all: boolean): void;
+export {};