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

package/README.md

@@ -62,7 +62,7 @@ Hardware test runner for [TypeCAD](../../README.md). Write vitest-style assertio
 npm install --save-dev @typecad/expect @typecad/cuttlefish
 ```
 
-`@typecad/expect` ships the `cuttlefish-test` CLI. It pairs with [`@typecad/cuttlefish`](https://github.com/justind000/typecode/tree/main/packages/cuttlefish), which transpiles your TypeScript test files to C++ for upload to hardware.
+`@typecad/expect` ships the `cuttlefish-test` CLI. It pairs with [`@typecad/cuttlefish`](https://cuttlefish.typecad.net), which transpiles your TypeScript test files to C++ for upload to hardware.
 
 **Prerequisites:**
 
@@ -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.js

@@ -8,6 +8,14 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { parseConfigAST } from './config.js';
+import { checkArduinoEnv } from '@typecad/arduino-cli';
+/** 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.
  *
@@ -77,6 +85,14 @@ export function transpileTestFile(preprocessedSource, originalFilePath, projectR
  * Compile the Arduino sketch using arduino-cli.
  */
 export function compileSketch(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 {
@@ -91,6 +107,14 @@ export function compileSketch(sketchDir, buildTarget) {
  * Upload the compiled sketch to the board.
  */
 export function uploadSketch(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 {

package/dist/host/config.js

@@ -55,6 +55,7 @@ export function loadConfig(projectRoot, overrides = {}) {
         buildTarget: test.buildTarget ?? raw.frameworkData?.buildTarget ?? 'arduino:avr:uno',
         board: test.board ?? raw.board ?? '@typecad/board-arduino-uno',
         target: raw.target ?? 'avr',
+        framework: raw.framework,
         projectRoot,
     };
 }

package/dist/host/preprocessor.d.ts

@@ -1,6 +1,27 @@
+/**
+ * Describes how the test protocol emits output for a given framework.
+ * Each framework provides its own shim so the preprocessor doesn't hardcode
+ * Serial.* (which would force the Arduino core to be linked).
+ */
+export interface OutputShim {
+    /** The init call emitted in the preamble, e.g. "Serial.begin(115200)". */
+    begin: string;
+    /** Print without newline — receives a fully-formed argument expression. */
+    print: (expr: string) => string;
+    /** Print with newline — receives a fully-formed argument expression. */
+    println: (expr: string) => string;
+    /** The idle-loop delay call after SUITE_END, e.g. "delay(1000)". */
+    delay: string;
+}
+/** Default shim: Arduino HardwareSerial. */
+export declare const serialShim: OutputShim;
+/** AVR native UART shim: routes through framework-avr's _uart_* helpers. */
+export declare const avrUartShim: OutputShim;
 export interface PreprocessorOptions {
     /** Wrap string literals in Arduino F() macro to save SRAM on AVR. */
     isAvr?: boolean;
+    /** Output shim — defaults to serialShim (Arduino HardwareSerial). */
+    shim?: OutputShim;
 }
 /**
  * Preprocess a test file's TypeScript source.
@@ -17,10 +38,12 @@ export declare class PreprocessorContext {
     private varCounter;
     private fnCounter;
     private preambleEmitted;
-    private readonly baudRate;
     readonly isAvr: boolean;
-    constructor(isAvr: boolean);
-    /** Wrap a string literal in F() on AVR to keep it in flash. */
+    readonly shim: OutputShim;
+    constructor(isAvr: boolean, shim?: OutputShim);
+    /** Wrap a string literal in F() on AVR to keep it in flash.
+     *  Only applies when using the serialShim (Arduino core provides F()).
+     *  The avrUartShim runs without the core, so F() is undefined — plain strings. */
     flash(s: string): string;
     /** Emit a line of TypeScript output. */
     emit(line: string): void;

package/dist/host/preprocessor.js

@@ -24,6 +24,20 @@
 import ts from 'typescript';
 import { isDescribeChain, collectChainSegments } from './chain-collector.js';
 import { emitSegments } from './protocol-emitter.js';
+/** Default shim: Arduino HardwareSerial. */
+export const serialShim = {
+    begin: 'Serial.begin(115200)',
+    print: (e) => `Serial.print(${e})`,
+    println: (e) => `Serial.println(${e})`,
+    delay: 'delay(1000)',
+};
+/** AVR native UART shim: routes through framework-avr's _uart_* helpers. */
+export const avrUartShim = {
+    begin: '_uart_init(115200)',
+    print: (e) => `_uart_print_expr(${e})`,
+    println: (e) => `_uart_println_expr(${e})`,
+    delay: '_native_delay_ms(1000)',
+};
 /**
  * Preprocess a test file's TypeScript source.
  *
@@ -35,7 +49,7 @@ import { emitSegments } from './protocol-emitter.js';
  */
 export function preprocess(source, fileName = 'test.ts', options) {
     const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-    const ctx = new PreprocessorContext(options?.isAvr ?? false);
+    const ctx = new PreprocessorContext(options?.isAvr ?? false, options?.shim);
     for (const stmt of sf.statements) {
         if (ts.isImportDeclaration(stmt)) {
             const moduleSpecifier = stmt.moduleSpecifier.text;
@@ -56,16 +70,20 @@ export function preprocess(source, fileName = 'test.ts', options) {
 // PreprocessorContext — shared state threaded through sub-modules
 // ---------------------------------------------------------------------------
 export class PreprocessorContext {
-    constructor(isAvr) {
+    constructor(isAvr, shim = serialShim) {
         this.lines = [];
         this.varCounter = 0;
         this.fnCounter = 0;
         this.preambleEmitted = false;
-        this.baudRate = 115200;
         this.isAvr = isAvr;
+        this.shim = shim;
     }
-    /** Wrap a string literal in F() on AVR to keep it in flash. */
+    /** Wrap a string literal in F() on AVR to keep it in flash.
+     *  Only applies when using the serialShim (Arduino core provides F()).
+     *  The avrUartShim runs without the core, so F() is undefined — plain strings. */
     flash(s) {
+        if (this.shim === avrUartShim)
+            return `"${s}"`;
         return this.isAvr ? `F("${s}")` : `"${s}"`;
     }
     /** Emit a line of TypeScript output. */
@@ -84,8 +102,8 @@ export class PreprocessorContext {
     }
     emitPreamble() {
         this.preambleEmitted = true;
-        this.lines.push(`Serial.begin(${this.baudRate});`);
-        this.lines.push(`Serial.println(${this.flash('[TC:SUITE_START]')});`);
+        this.lines.push(`${this.shim.begin};`);
+        this.lines.push(`${this.shim.println(this.flash('[TC:SUITE_START]'))};`);
     }
     build() {
         return this.lines.join('\n') + '\n';
@@ -97,8 +115,8 @@ export class PreprocessorContext {
 function processExpressionStatement(stmt, sf, ctx) {
     const expr = stmt.expression;
     if (isDoneCall(expr)) {
-        ctx.emit(`Serial.println(${ctx.flash('[TC:SUITE_END]')});`);
-        ctx.emit(`while (true) { delay(1000); }`);
+        ctx.emit(`${ctx.shim.println(ctx.flash('[TC:SUITE_END]'))};`);
+        ctx.emit(`while (true) { ${ctx.shim.delay}; }`);
         return;
     }
     if (isDescribeChain(expr)) {

package/dist/host/protocol-emitter.js

@@ -22,10 +22,10 @@ export function emitSegments(segments, ctx) {
     for (const seg of segments) {
         switch (seg.kind) {
             case 'describe':
-                ctx.emit(`Serial.println(${ctx.flash(`[TC:DESCRIBE:${escapeProtocol(seg.name ?? '')}]`)});`);
+                ctx.emit(`${ctx.shim.println(ctx.flash(`[TC:DESCRIBE:${escapeProtocol(seg.name ?? '')}]`))};`);
                 break;
             case 'it':
-                ctx.emit(`Serial.println(${ctx.flash(`[TC:IT:${escapeProtocol(seg.name ?? '')}]`)});`);
+                ctx.emit(`${ctx.shim.println(ctx.flash(`[TC:IT:${escapeProtocol(seg.name ?? '')}]`))};`);
                 break;
             case 'expect': {
                 if (!seg.matcher)
@@ -67,17 +67,17 @@ export function emitSegments(segments, ctx) {
 export function emitExpectProtocol(actualVar, matcher, matcherArgs, ctx, isString = false) {
     if (isString && matcher === 'toBe') {
         const rawExpected = (matcherArgs[0] ?? '').replace(/^["']|["']$/g, '');
-        ctx.emit(`Serial.print(${ctx.flash(`[TC:EXPECT:${matcher}:`)});`);
-        ctx.emit(`Serial.print("${escapeProtocol(rawExpected)}");`);
-        ctx.emit(`Serial.print(${ctx.flash(':')});`);
-        ctx.emit(`Serial.print(${actualVar});`);
-        ctx.emit(`Serial.println(${ctx.flash(']')});`);
+        ctx.emit(`${ctx.shim.print(ctx.flash(`[TC:EXPECT:${matcher}:`))};`);
+        ctx.emit(`${ctx.shim.print(`"${escapeProtocol(rawExpected)}"`)};`);
+        ctx.emit(`${ctx.shim.print(ctx.flash(':'))};`);
+        ctx.emit(`${ctx.shim.print(actualVar)};`);
+        ctx.emit(`${ctx.shim.println(ctx.flash(']'))};`);
         return;
     }
     const expectedPart = matcherArgs.join(',');
-    ctx.emit(`Serial.print(${ctx.flash(`[TC:EXPECT:${matcher}:${expectedPart}:`)});`);
-    ctx.emit(`Serial.print(${actualVar});`);
-    ctx.emit(`Serial.println(${ctx.flash(']')});`);
+    ctx.emit(`${ctx.shim.print(ctx.flash(`[TC:EXPECT:${matcher}:${expectedPart}:`))};`);
+    ctx.emit(`${ctx.shim.print(actualVar)};`);
+    ctx.emit(`${ctx.shim.println(ctx.flash(']'))};`);
 }
 // ---------------------------------------------------------------------------
 // Expression classification helpers

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 } from './preprocessor.js';
+import { preprocess, serialShim, avrUartShim } from './preprocessor.js';
 import { transpileTestFile, compileSketch, uploadSketch } from './compiler.js';
 import { readSerialOutput } from './serial.js';
 import { parseProtocolLines } from './parser.js';
@@ -84,6 +84,7 @@ 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,
         });
     }
     catch (e) {

package/dist/host/types.d.ts

@@ -116,6 +116,8 @@ export interface ResolvedConfig {
     buildTarget: string;
     board: string;
     target: string;
+    /** Framework package name, e.g. "@typecad/framework-avr". */
+    framework?: string;
     /** Absolute path to project root. */
     projectRoot: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/expect",
-  "version": "0.1.0-alpha.2",
+  "version": "1.0.0-alpha.6",
   "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.6"
   },
   "devDependencies": {
-    "@typecad/cuttlefish": "0.1.0-alpha.2",
+    "@typecad/cuttlefish": "1.0.0-alpha.6",
     "@types/node": "^22.10.7"
   },
   "license": "MIT",