@typecad/expect 1.0.0-alpha.3 → 1.0.0-alpha.7

package/README.md

@@ -152,13 +152,13 @@ All numeric matchers return the parent `Suite`, so you can continue the chain wi
 
 ```bash
 # Run a specific file
-npx cuttlefish-test examples/my-sensor.test.ts
+npx --package=@typecad/expect cuttlefish-test examples/my-sensor.test.ts
 
 # Run all test files matched by config include patterns
-npx cuttlefish-test
+npx --package=@typecad/expect cuttlefish-test
 
 # Override the port at run-time
-npx cuttlefish-test --port /dev/ttyACM0 examples/my-sensor.test.ts
+npx --package=@typecad/expect cuttlefish-test --port /dev/ttyACM0 examples/my-sensor.test.ts
 ```
 
 Or via the npm script defined in the root `package.json`:
@@ -253,10 +253,10 @@ Example flow:
 
 ```bash
 # 1. Compile and upload the serial-output showcase
-npx cuttlefish src/23-transpiler-showcase.ts --compile --upload --port COM4
+npx @typecad/cuttlefish src/23-transpiler-showcase.ts --compile --upload --port COM4
 
 # 2. Run the on-hardware expect test against the connected Uno
-npx cuttlefish-test examples/24-uno-validation.test.ts --port COM4
+npx --package=@typecad/expect cuttlefish-test examples/24-uno-validation.test.ts --port COM4
 ```
 
 This hybrid workflow is the recommended way to confirm that simple variables, arithmetic, arrays, enums, functions, GPIO, and analog input are behaving correctly on real Uno hardware.

package/dist/host/compiler.d.ts

@@ -18,10 +18,17 @@ export interface UploadResult {
  */
 export declare function transpileTestFile(preprocessedSource: string, originalFilePath: string, projectRoot: string, buildTarget: string): CompileResult;
 /**
- * Compile the Arduino sketch using arduino-cli.
+ * Compile the sketch. Detects the toolchain from the framework:
+ * - framework-esp32 → idf.py build (via framework-esp32's compileEspIdf)
+ * - everything else → arduino-cli compile
  */
-export declare function compileSketch(sketchDir: string, buildTarget: string): CompileResult;
+export declare function compileSketch(sketchDir: string, buildTarget: string, framework?: string): CompileResult;
 /**
  * Upload the compiled sketch to the board.
  */
-export declare function uploadSketch(sketchDir: string, buildTarget: string, port: string): UploadResult;
+/**
+ * Upload firmware. Detects the toolchain from the framework:
+ * - framework-esp32 → idf.py flash
+ * - everything else → arduino-cli upload
+ */
+export declare function uploadSketch(sketchDir: string, buildTarget: string, port: string, framework?: string): UploadResult;

package/dist/host/compiler.js

@@ -7,7 +7,19 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { parseConfigAST } from './config.js';
+import { checkArduinoEnv } from '@typecad/arduino-cli';
+// createRequire lets us synchronously require CommonJS modules from this ESM
+// file. Used to load framework-esp32's compiled dist at runtime.
+const require_ = createRequire(import.meta.url);
+/** Format a check failure into the `error` field used by CompileResult/UploadResult. */
+function formatEnvFailure(failure) {
+    const lines = [...failure.messages];
+    if (failure.fixCommand)
+        lines.push(`  Fix: ${failure.fixCommand}`);
+    return lines.join('\n');
+}
 /**
  * Transpile preprocessed TypeScript source to a C++ Arduino sketch.
  *
@@ -15,12 +27,35 @@ import { parseConfigAST } from './config.js';
  * transpiler, and returns the path to the generated .ino file.
  */
 export function transpileTestFile(preprocessedSource, originalFilePath, projectRoot, buildTarget) {
-    // Create a build directory for this test file
+    // Create a build directory for this test file.
+    // For idf.py targets, use a SHARED build directory across all test files —
+    // only main/main.cc changes between files, so idf.py can do incremental
+    // builds (ninja detects only the changed .cc and relinks). This turns the
+    // 2nd+ file from a ~130s full rebuild into a ~10-15s incremental build.
+    // For arduino-cli targets, use per-file directories (no incremental benefit).
     const baseName = path.basename(originalFilePath, '.test.ts').replace(/[^a-zA-Z0-9_]/g, '_');
-    const buildDir = path.join(projectRoot, '.build', 'expect', baseName);
+    const isEsp32 = buildTarget === 'esp32' || buildTarget === 'esp32s3' || buildTarget === 'esp32c3' || buildTarget === 'esp32c6';
+    const buildDir = isEsp32
+        ? path.join(projectRoot, '.build', 'expect', 'esp32_shared')
+        : path.join(projectRoot, '.build', 'expect', baseName);
     try {
-        fs.rmSync(buildDir, { recursive: true, force: true });
-        fs.mkdirSync(buildDir, { recursive: true });
+        if (isEsp32 && fs.existsSync(buildDir)) {
+            // Shared ESP32 build dir: preserve it. The transpiler will overwrite
+            // the .ts source and regenerate main.cc; ninja does an incremental build.
+            // Only remove the old .ts file so the transpiler doesn't pick up stale ones.
+            const oldTsFiles = fs.readdirSync(buildDir).filter(f => f.endsWith('.ts'));
+            for (const f of oldTsFiles) {
+                try {
+                    fs.unlinkSync(path.join(buildDir, f));
+                }
+                catch { }
+            }
+        }
+        else {
+            // Fresh dir (first run, or arduino-cli target).
+            fs.rmSync(buildDir, { recursive: true, force: true });
+            fs.mkdirSync(buildDir, { recursive: true });
+        }
     }
     catch {
         return { success: false, sketchDir: buildDir, sketchPath: '', output: '', error: `Failed to create build dir: ${buildDir}` };
@@ -74,9 +109,35 @@ export function transpileTestFile(preprocessedSource, originalFilePath, projectR
     };
 }
 /**
- * Compile the Arduino sketch using arduino-cli.
+ * Compile the sketch. Detects the toolchain from the framework:
+ * - framework-esp32 → idf.py build (via framework-esp32's compileEspIdf)
+ * - everything else → arduino-cli compile
  */
-export function compileSketch(sketchDir, buildTarget) {
+export function compileSketch(sketchDir, buildTarget, framework) {
+    if (framework?.includes('framework-esp32')) {
+        return compileEspIdfSketch(sketchDir, buildTarget);
+    }
+    return compileArduinoSketch(sketchDir, buildTarget);
+}
+/** Resolve the framework-esp32 dist/toolchain directory from node_modules.
+ *  Uses the main export entry point (dist/index.js) to find the dist dir,
+ *  avoiding the package's exports field restriction on subpaths. */
+function resolveFrameworkEsp32Dist() {
+    const indexPath = require_.resolve('@typecad/framework-esp32');
+    // indexPath = .../packages/framework-esp32/dist/index.js
+    // toolchain dir = .../packages/framework-esp32/dist/toolchain
+    return path.join(path.dirname(indexPath), 'toolchain');
+}
+/** Compile via arduino-cli (framework-arduino / framework-avr). */
+function compileArduinoSketch(sketchDir, buildTarget) {
+    // Hard gate: verify arduino-cli + core before spawning.
+    {
+        const gate = checkArduinoEnv(buildTarget);
+        if (!gate.ok) {
+            const message = formatEnvFailure(gate);
+            return { success: false, sketchDir, sketchPath: '', output: message, error: message };
+        }
+    }
     const result = spawnSync('arduino-cli', ['compile', '--fqbn', buildTarget, sketchDir], { encoding: 'utf8', timeout: 120000 });
     const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
     return {
@@ -90,7 +151,76 @@ export function compileSketch(sketchDir, buildTarget) {
 /**
  * Upload the compiled sketch to the board.
  */
-export function uploadSketch(sketchDir, buildTarget, port) {
+/**
+ * Upload firmware. Detects the toolchain from the framework:
+ * - framework-esp32 → idf.py flash
+ * - everything else → arduino-cli upload
+ */
+export function uploadSketch(sketchDir, buildTarget, port, framework) {
+    if (framework?.includes('framework-esp32')) {
+        return uploadEspIdfSketch(sketchDir, buildTarget, port);
+    }
+    return uploadArduinoSketch(sketchDir, buildTarget, port);
+}
+/** Compile via idf.py build (framework-esp32). */
+function compileEspIdfSketch(sketchDir, buildTarget) {
+    try {
+        const projectDir = path.basename(sketchDir) === 'main' ? path.dirname(sketchDir) : sketchDir;
+        const distDir = resolveFrameworkEsp32Dist();
+        const { compileEspIdf } = require_(path.join(distDir, 'compile.js'));
+        const result = compileEspIdf({
+            sourcePath: projectDir,
+            target: buildTarget || 'esp32',
+        });
+        return {
+            success: result.success,
+            sketchDir: projectDir,
+            sketchPath: '',
+            output: result.output,
+            error: result.errorMessage,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            sketchDir,
+            sketchPath: '',
+            output: '',
+            error: `idf.py compile failed: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+}
+/** Upload via idf.py flash (framework-esp32). */
+function uploadEspIdfSketch(sketchDir, buildTarget, port) {
+    try {
+        const projectDir = path.basename(sketchDir) === 'main' ? path.dirname(sketchDir) : sketchDir;
+        const distDir = resolveFrameworkEsp32Dist();
+        const { uploadEspIdf } = require_(path.join(distDir, 'upload.js'));
+        const result = uploadEspIdf(projectDir, port);
+        return {
+            success: result.success,
+            output: result.output,
+            error: result.errorMessage,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            output: '',
+            error: `idf.py flash failed: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+}
+/** Upload via arduino-cli (framework-arduino / framework-avr). */
+function uploadArduinoSketch(sketchDir, buildTarget, port) {
+    // Hard gate: verify arduino-cli + core before spawning.
+    {
+        const gate = checkArduinoEnv(buildTarget);
+        if (!gate.ok) {
+            const message = formatEnvFailure(gate);
+            return { success: false, output: message, error: message };
+        }
+    }
     const result = spawnSync('arduino-cli', ['upload', '--fqbn', buildTarget, '--port', port, sketchDir], { encoding: 'utf8', timeout: 60000 });
     const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
     return {
@@ -150,13 +280,14 @@ function findOutputDir(buildDir, baseName, projectRoot) {
 function hasInoFile(dir) {
     if (!fs.existsSync(dir))
         return false;
-    return fs.readdirSync(dir).some(f => f.endsWith('.ino'));
+    return fs.readdirSync(dir).some(f => f.endsWith('.ino') || f.endsWith('.cc'));
 }
 function findInoFile(dir) {
     if (!fs.existsSync(dir))
         return undefined;
     for (const entry of fs.readdirSync(dir)) {
-        if (entry.endsWith('.ino')) {
+        // Accept .ino (Arduino) and .cc (ESP-IDF main.cc) as entry files.
+        if (entry.endsWith('.ino') || entry.endsWith('.cc')) {
             return path.join(dir, entry);
         }
     }
@@ -166,7 +297,7 @@ function findInoFileRecursive(dir) {
     if (!fs.existsSync(dir))
         return undefined;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        if (entry.name.endsWith('.ino')) {
+        if (entry.name.endsWith('.ino') || entry.name.endsWith('.cc')) {
             return path.join(dir, entry.name);
         }
         if (entry.isDirectory()) {

package/dist/host/preprocessor.d.ts

@@ -17,6 +17,13 @@ export interface OutputShim {
 export declare const serialShim: OutputShim;
 /** AVR native UART shim: routes through framework-avr's _uart_* helpers. */
 export declare const avrUartShim: OutputShim;
+/** ESP-IDF shim: emits console.debug (print, no newline) and console.log
+ *  (println, with newline) calls. The transpiler's transformConsoleCall lowers
+ *  these to printf for framework-esp32. Using different console methods lets
+ *  the lowering distinguish "partial line" (print/debug) from "end of line"
+ *  (println/log) — critical for the [TC:EXPECT:...] protocol format which
+ *  spans multiple print calls on a single line. */
+export declare const espIdfShim: OutputShim;
 export interface PreprocessorOptions {
     /** Wrap string literals in Arduino F() macro to save SRAM on AVR. */
     isAvr?: boolean;

package/dist/host/preprocessor.js

@@ -38,6 +38,18 @@ export const avrUartShim = {
     println: (e) => `_uart_println_expr(${e})`,
     delay: '_native_delay_ms(1000)',
 };
+/** ESP-IDF shim: emits console.debug (print, no newline) and console.log
+ *  (println, with newline) calls. The transpiler's transformConsoleCall lowers
+ *  these to printf for framework-esp32. Using different console methods lets
+ *  the lowering distinguish "partial line" (print/debug) from "end of line"
+ *  (println/log) — critical for the [TC:EXPECT:...] protocol format which
+ *  spans multiple print calls on a single line. */
+export const espIdfShim = {
+    begin: '',
+    print: (e) => `console.debug(${e})`,
+    println: (e) => `console.log(${e})`,
+    delay: 'Timing.delay(1000)',
+};
 /**
  * Preprocess a test file's TypeScript source.
  *

package/dist/host/runner.js

@@ -7,7 +7,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { findTestFiles } from './finder.js';
-import { preprocess, serialShim, avrUartShim } from './preprocessor.js';
+import { preprocess, serialShim, avrUartShim, espIdfShim } from './preprocessor.js';
 import { transpileTestFile, compileSketch, uploadSketch } from './compiler.js';
 import { readSerialOutput } from './serial.js';
 import { parseProtocolLines } from './parser.js';
@@ -84,7 +84,9 @@ async function processTestFile(filePath, config) {
     try {
         preprocessed = preprocess(source, path.basename(filePath), {
             isAvr: config.target === 'avr' || config.target === 'megaavr',
-            shim: config.framework === '@typecad/framework-avr' ? avrUartShim : serialShim,
+            shim: config.framework === '@typecad/framework-avr' ? avrUartShim
+                : config.framework?.includes('framework-esp32') ? espIdfShim
+                    : serialShim,
         });
     }
     catch (e) {
@@ -96,15 +98,15 @@ async function processTestFile(filePath, config) {
     if (!transpileResult.success) {
         return errorResult(filePath, transpileResult.error ?? 'Transpilation failed', startTime);
     }
-    // Step 3: Compile with arduino-cli
+    // Step 3: Compile (arduino-cli or idf.py depending on framework)
     console.log(`  ${DIM}compiling...${RESET}`);
-    const compileResult = compileSketch(transpileResult.sketchDir, config.buildTarget);
+    const compileResult = compileSketch(transpileResult.sketchDir, config.buildTarget, config.framework);
     if (!compileResult.success) {
         return errorResult(filePath, compileResult.error ?? 'Compilation failed', startTime);
     }
-    // Step 4: Upload
+    // Step 4: Upload (arduino-cli or idf.py depending on framework)
     console.log(`  ${DIM}uploading to ${config.test.port}...${RESET}`);
-    const uploadResult = uploadSketch(transpileResult.sketchDir, config.buildTarget, config.test.port);
+    const uploadResult = uploadSketch(transpileResult.sketchDir, config.buildTarget, config.test.port, config.framework);
     if (!uploadResult.success) {
         return errorResult(filePath, uploadResult.error ?? 'Upload failed', startTime);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/expect",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.7",
   "description": "Hardware test framework for TypeCAD — vitest-style assertions over serial",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,10 +39,11 @@
   },
   "dependencies": {
     "typescript": "^5.7.3",
-    "serialport": "^12.0.0"
+    "serialport": "^12.0.0",
+    "@typecad/arduino-cli": "1.0.0-alpha.7"
   },
   "devDependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.3",
+    "@typecad/cuttlefish": "1.0.0-alpha.7",
     "@types/node": "^22.10.7"
   },
   "license": "MIT",