@typecad/expect 0.1.0-alpha.1

package/dist/host/runner.js

@@ -0,0 +1,256 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Test runner pipeline
+//
+// Orchestrates the full test cycle:
+//   discover → preprocess → transpile → compile → upload → serial → parse → evaluate → report
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+import { findTestFiles } from './finder.js';
+import { preprocess } from './preprocessor.js';
+import { transpileTestFile, compileSketch, uploadSketch } from './compiler.js';
+import { readSerialOutput } from './serial.js';
+import { parseProtocolLines } from './parser.js';
+import { reportFileResult, reportSummary } from './reporter.js';
+// ---------------------------------------------------------------------------
+// ANSI codes (for inline progress messages)
+// ---------------------------------------------------------------------------
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run all test files matching the configuration.
+ *
+ * @returns Exit code: 0 = all passed, 1 = failures, 2 = error.
+ */
+export async function run(config) {
+    const startTime = Date.now();
+    // 1. Discover test files
+    const testFiles = findTestFiles(config.projectRoot, config.test.include);
+    if (testFiles.length === 0) {
+        console.log(`${YELLOW}No test files found matching: ${config.test.include.join(', ')}${RESET}`);
+        return 0;
+    }
+    console.log(`${DIM}Found ${testFiles.length} test file${testFiles.length !== 1 ? 's' : ''}${RESET}`);
+    console.log();
+    // 2. Process each file sequentially (one compile/upload cycle per file)
+    const fileResults = [];
+    for (const filePath of testFiles) {
+        const result = await processTestFile(filePath, config);
+        fileResults.push(result);
+        reportFileResult(result, { verbose: config.test.verbose });
+    }
+    // 3. Aggregate results
+    const runResult = aggregateResults(fileResults, Date.now() - startTime);
+    // 4. Final summary
+    reportSummary(runResult, {
+        board: config.board,
+        port: config.test.port,
+    });
+    return (runResult.totalFailed > 0 || runResult.totalErrors > 0) ? 1 : 0;
+}
+// ---------------------------------------------------------------------------
+// Internal — Process a single test file through the full pipeline
+// ---------------------------------------------------------------------------
+async function processTestFile(filePath, config) {
+    const startTime = Date.now();
+    const relativePath = path.relative(config.projectRoot, filePath);
+    // Read source
+    let source;
+    try {
+        source = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (e) {
+        return errorResult(filePath, `Failed to read file: ${e.message}`, startTime);
+    }
+    const skipReason = getSkipReason(source, relativePath, config);
+    if (skipReason) {
+        return skippedResult(relativePath, skipReason, startTime);
+    }
+    // Validate port only for files that will actually compile/upload. This lets
+    // target-incompatible files be skipped without requiring hardware to be
+    // connected.
+    if (!config.test.port) {
+        return errorResult(filePath, 'No serial port specified. Use --port <port> or set test.port in cuttlefish.config.ts', startTime);
+    }
+    console.log(`${CYAN}●${RESET} ${relativePath}`);
+    // Step 1: Preprocess
+    console.log(`  ${DIM}preprocessing...${RESET}`);
+    let preprocessed;
+    try {
+        preprocessed = preprocess(source, path.basename(filePath), {
+            isAvr: config.target === 'avr' || config.target === 'megaavr',
+        });
+    }
+    catch (e) {
+        return errorResult(filePath, `Preprocessing failed: ${e.message}`, startTime);
+    }
+    // Step 2: Transpile to C++
+    console.log(`  ${DIM}transpiling...${RESET}`);
+    const transpileResult = transpileTestFile(preprocessed, filePath, config.projectRoot, config.buildTarget);
+    if (!transpileResult.success) {
+        return errorResult(filePath, transpileResult.error ?? 'Transpilation failed', startTime);
+    }
+    // Step 3: Compile with arduino-cli
+    console.log(`  ${DIM}compiling...${RESET}`);
+    const compileResult = compileSketch(transpileResult.sketchDir, config.buildTarget);
+    if (!compileResult.success) {
+        return errorResult(filePath, compileResult.error ?? 'Compilation failed', startTime);
+    }
+    // Step 4: Upload
+    console.log(`  ${DIM}uploading to ${config.test.port}...${RESET}`);
+    const uploadResult = uploadSketch(transpileResult.sketchDir, config.buildTarget, config.test.port);
+    if (!uploadResult.success) {
+        return errorResult(filePath, uploadResult.error ?? 'Upload failed', startTime);
+    }
+    // Step 5: Read serial output
+    console.log(`  ${DIM}reading serial output...${RESET}`);
+    const serialResult = await readSerialOutput(config.test.port, config.test.baudRate, config.test.timeout, config.test.serialOpenDelay, { resetAfterOpen: config.test.resetAfterOpen ?? config.target === 'esp32' });
+    if (serialResult.error && !serialResult.completed) {
+        return errorResult(filePath, serialResult.error, startTime);
+    }
+    // Step 6: Parse protocol lines
+    const describes = parseProtocolLines(serialResult.protocolLines);
+    const durationMs = Date.now() - startTime;
+    const passed = describes.every(d => d.passed);
+    return {
+        filePath: relativePath,
+        describes,
+        passed,
+        durationMs,
+        debugOutput: serialResult.debugLines,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal — Helpers
+// ---------------------------------------------------------------------------
+function errorResult(filePath, error, startTime) {
+    return {
+        filePath,
+        describes: [],
+        passed: false,
+        durationMs: Date.now() - startTime,
+        debugOutput: [],
+        error,
+    };
+}
+function skippedResult(filePath, reason, startTime) {
+    return {
+        filePath,
+        describes: [],
+        passed: true,
+        durationMs: Date.now() - startTime,
+        debugOutput: [],
+        skipped: true,
+        skipReason: reason,
+    };
+}
+function aggregateResults(files, durationMs) {
+    let totalTests = 0;
+    let totalPassed = 0;
+    let totalFailed = 0;
+    let totalErrors = 0;
+    let totalSkipped = 0;
+    for (const file of files) {
+        if (file.skipped) {
+            totalSkipped++;
+            continue;
+        }
+        for (const desc of file.describes) {
+            for (const test of desc.tests) {
+                totalTests++;
+                if (test.passed)
+                    totalPassed++;
+                else
+                    totalFailed++;
+            }
+        }
+        if (file.error) {
+            totalErrors++;
+        }
+    }
+    return {
+        files,
+        totalTests,
+        totalPassed,
+        totalFailed,
+        totalErrors,
+        totalSkipped,
+        durationMs,
+    };
+}
+function getSkipReason(source, relativePath, config) {
+    const excludedByConfig = config.test.exclude?.find(pattern => matchesTestPattern(relativePath, pattern));
+    if (excludedByConfig) {
+        return `matched test.exclude pattern '${excludedByConfig}'`;
+    }
+    const skipTarget = findTargetDirective(source, 'typecad-skip-target');
+    if (skipTarget && targetListMatches(skipTarget.targets, config)) {
+        return skipTarget.reason ?? `skipped for target '${targetLabel(config)}'`;
+    }
+    const onlyTarget = findTargetDirective(source, 'typecad-only-target');
+    if (onlyTarget && !targetListMatches(onlyTarget.targets, config)) {
+        return onlyTarget.reason ?? `requires target '${onlyTarget.targets.join(', ')}'`;
+    }
+    return undefined;
+}
+function findTargetDirective(source, directive) {
+    const re = new RegExp(`@${directive}\\s+([^:\\r\\n]+)(?::\\s*(.*))?`, 'i');
+    const match = source.match(re);
+    if (!match)
+        return undefined;
+    const targets = match[1]
+        .split(/[,\s]+/)
+        .map(s => s.trim().toLowerCase())
+        .filter(Boolean);
+    if (targets.length === 0)
+        return undefined;
+    return { targets, reason: match[2]?.trim() || undefined };
+}
+function targetListMatches(targets, config) {
+    const tokens = new Set();
+    if (config.target)
+        tokens.add(config.target.toLowerCase());
+    if (config.buildTarget) {
+        const buildTarget = config.buildTarget.toLowerCase();
+        tokens.add(buildTarget);
+        const parts = buildTarget.split(':');
+        if (parts[0])
+            tokens.add(parts[0]);
+        if (parts[1])
+            tokens.add(parts[1]);
+        if (parts[2])
+            tokens.add(parts[2]);
+    }
+    if (config.board) {
+        const board = config.board.toLowerCase();
+        tokens.add(board);
+        const lastSegment = board.split('/').pop();
+        if (lastSegment)
+            tokens.add(lastSegment);
+    }
+    return targets.some(target => target === '*' || tokens.has(target.toLowerCase()));
+}
+function targetLabel(config) {
+    return config.buildTarget || config.target || config.board || 'unknown';
+}
+function matchesTestPattern(relativePath, pattern) {
+    const normalizedPath = relativePath.replace(/\\/g, '/');
+    const normalizedPattern = pattern.replace(/\\/g, '/');
+    if (!normalizedPattern.includes('*') && !normalizedPattern.includes('?')) {
+        return normalizedPath === normalizedPattern;
+    }
+    return globToRegex(normalizedPattern).test(normalizedPath);
+}
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const pattern = escaped
+        .replace(/\?/g, '[^/]')
+        .replace(/\*\*\//g, '(.+/)?')
+        .replace(/\*/g, '[^/]*');
+    return new RegExp(`^${pattern}$`);
+}

package/dist/host/serial.d.ts

@@ -0,0 +1,28 @@
+export interface SerialReadResult {
+    /** Lines starting with [TC: — the protocol data. */
+    protocolLines: string[];
+    /** All other serial output — debug prints, boot messages, etc. */
+    debugLines: string[];
+    /** Whether SUITE_END was received before timeout. */
+    completed: boolean;
+    /** If the read was cut short by an error. */
+    error?: string;
+}
+export interface SerialReadOptions {
+    /** Toggle ESP32-style DTR/RTS reset after the port is open and listeners are attached. */
+    resetAfterOpen?: boolean;
+    /** How long to hold reset active when resetAfterOpen is enabled. */
+    resetPulseMs?: number;
+}
+/**
+ * Read serial output from the device and separate protocol lines from debug.
+ *
+ * Uses the `serialport` npm package.  The port is opened, data is accumulated
+ * line-by-line.  Reading stops when a `[TC:SUITE_END]` line is received or
+ * the timeout expires.
+ *
+ * @param port     Serial port path (e.g. `'COM3'`, `'/dev/ttyACM0'`).
+ * @param baudRate Baud rate — must match what the preprocessor emits.
+ * @param timeoutMs How long to wait for SUITE_END.
+ */
+export declare function readSerialOutput(port: string, baudRate: number, timeoutMs: number, serialOpenDelay?: number, options?: SerialReadOptions): Promise<SerialReadResult>;

package/dist/host/serial.js

@@ -0,0 +1,129 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Serial reader
+//
+// Opens a serial port after firmware upload, reads lines until [TC:SUITE_END]
+// or timeout.  Filters protocol lines from debug output.
+// ---------------------------------------------------------------------------
+import { PROTOCOL_PREFIX } from './types.js';
+/**
+ * Read serial output from the device and separate protocol lines from debug.
+ *
+ * Uses the `serialport` npm package.  The port is opened, data is accumulated
+ * line-by-line.  Reading stops when a `[TC:SUITE_END]` line is received or
+ * the timeout expires.
+ *
+ * @param port     Serial port path (e.g. `'COM3'`, `'/dev/ttyACM0'`).
+ * @param baudRate Baud rate — must match what the preprocessor emits.
+ * @param timeoutMs How long to wait for SUITE_END.
+ */
+export async function readSerialOutput(port, baudRate, timeoutMs, serialOpenDelay = 500, options = {}) {
+    // Dynamic import — serialport is a native dependency
+    const { SerialPort } = await import('serialport');
+    const protocolLines = [];
+    const debugLines = [];
+    let completed = false;
+    let pending = '';
+    return new Promise((resolve) => {
+        let resolved = false;
+        const cleanup = (callback) => {
+            sp.removeAllListeners();
+            if (sp.isOpen) {
+                sp.close(() => callback());
+            }
+            else {
+                try {
+                    sp.close();
+                }
+                catch {
+                    // ignore close errors for unopened ports
+                }
+                callback();
+            }
+        };
+        const finish = (error) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            cleanup(() => resolve({ protocolLines, debugLines, completed, error }));
+        };
+        const handleLine = (line) => {
+            const trimmed = line.trim();
+            if (trimmed.startsWith(PROTOCOL_PREFIX)) {
+                protocolLines.push(trimmed);
+                if (trimmed.includes('SUITE_END')) {
+                    completed = true;
+                    // Give a brief delay for any trailing output
+                    setTimeout(() => finish(), 200);
+                }
+            }
+            else if (trimmed.length > 0) {
+                debugLines.push(trimmed);
+            }
+        };
+        const handleChunk = (chunk) => {
+            pending += chunk.toString();
+            while (true) {
+                const lf = pending.indexOf('\n');
+                const cr = pending.indexOf('\r');
+                const indexes = [lf, cr].filter(i => i >= 0);
+                if (indexes.length === 0)
+                    break;
+                const next = Math.min(...indexes);
+                const delimiter = pending[next];
+                const line = pending.slice(0, next);
+                pending = pending.slice(next + 1);
+                // Treat CRLF as one newline.
+                if (delimiter === '\r' && pending.startsWith('\n')) {
+                    pending = pending.slice(1);
+                }
+                handleLine(line);
+            }
+        };
+        const resetAfterOpen = options.resetAfterOpen ?? false;
+        const resetPulseMs = options.resetPulseMs ?? 100;
+        const resetBoard = () => {
+            if (!resetAfterOpen)
+                return;
+            // ESP32 DevKit boards use RTS for EN/reset and DTR for GPIO0/boot.
+            // Keep GPIO0 high (DTR false), pulse EN low (RTS true), then release.
+            sp.set({ dtr: false, rts: true }, (assertErr) => {
+                if (assertErr) {
+                    finish(`Failed to assert serial reset on ${port}: ${assertErr.message}`);
+                    return;
+                }
+                setTimeout(() => {
+                    sp.set({ dtr: false, rts: false }, (releaseErr) => {
+                        if (releaseErr) {
+                            finish(`Failed to release serial reset on ${port}: ${releaseErr.message}`);
+                        }
+                    });
+                }, resetPulseMs);
+            });
+        };
+        // Open serial port
+        const sp = new SerialPort({ path: port, baudRate, autoOpen: false });
+        // Timeout guard
+        const timer = setTimeout(() => {
+            if (pending.trim().length > 0) {
+                handleLine(pending);
+                pending = '';
+            }
+            finish(completed ? undefined : `Timeout after ${timeoutMs}ms — no [TC:SUITE_END] received`);
+        }, timeoutMs);
+        sp.on('data', handleChunk);
+        sp.on('error', (err) => {
+            finish(`Serial error: ${err.message}`);
+        });
+        // Give the device time to reset after upload (Arduino resets on serial open)
+        setTimeout(() => {
+            sp.open((err) => {
+                if (err) {
+                    finish(`Failed to open ${port}: ${err.message}`);
+                    return;
+                }
+                resetBoard();
+            });
+        }, serialOpenDelay);
+    });
+}

package/dist/host/types.d.ts

@@ -0,0 +1,121 @@
+/** The prefix that every protocol line starts with. */
+export declare const PROTOCOL_PREFIX = "[TC:";
+export declare const PROTOCOL_SUFFIX = "]";
+/**
+ * All protocol line types emitted by firmware.
+ */
+export type ProtocolTag = 'SUITE_START' | 'DESCRIBE' | 'IT' | 'EXPECT' | 'SUITE_END';
+/**
+ * A single parsed protocol line.
+ */
+export interface ProtocolLine {
+    tag: ProtocolTag;
+    /** Payload segments (split on `:` after the tag). */
+    fields: string[];
+    /** The original raw line from serial. */
+    raw: string;
+}
+/**
+ * All supported matcher names.
+ */
+export type MatcherName = 'toBe' | 'toBeGreaterThan' | 'toBeGreaterThanOrEqual' | 'toBeLessThan' | 'toBeLessThanOrEqual' | 'toBeCloseTo' | 'toBeWithinRange' | 'toBeTruthy' | 'toBeFalsy' | 'toNotBe' | 'toContain' | 'toHaveLength';
+/**
+ * A single assertion result after host-side evaluation.
+ */
+export interface AssertionResult {
+    matcher: MatcherName;
+    /** Expected value(s) as raw string from serial. */
+    expected: string;
+    /** Actual value as raw string from serial. */
+    actual: string;
+    /** Whether the assertion passed. */
+    passed: boolean;
+}
+/**
+ * A single `it(...)` test case result.
+ */
+export interface TestResult {
+    name: string;
+    assertions: AssertionResult[];
+    /** Whether all assertions passed. */
+    passed: boolean;
+    /** Time between IT start and next IT / describe end (ms). */
+    durationMs: number;
+}
+/**
+ * A single `describe(...)` group result.
+ */
+export interface DescribeResult {
+    name: string;
+    tests: TestResult[];
+    /** Whether all tests passed. */
+    passed: boolean;
+}
+/**
+ * Result of running one test file.
+ */
+export interface FileResult {
+    filePath: string;
+    describes: DescribeResult[];
+    passed: boolean;
+    durationMs: number;
+    /** Non-test serial output (lines without [TC: prefix). */
+    debugOutput: string[];
+    /** True when the file was intentionally skipped before compile/upload. */
+    skipped?: boolean;
+    /** Human-readable skip reason. */
+    skipReason?: string;
+    /** If the file didn't compile or upload. */
+    error?: string;
+}
+/**
+ * Result of the entire test run.
+ */
+export interface RunResult {
+    files: FileResult[];
+    totalTests: number;
+    totalPassed: number;
+    totalFailed: number;
+    /** Pipeline errors (compile/upload failures) — tracked separately from test failures. */
+    totalErrors: number;
+    /** Files intentionally skipped before compile/upload. */
+    totalSkipped: number;
+    durationMs: number;
+}
+/**
+ * Test-specific configuration — the `test` section of `cuttlefish.config.ts`.
+ */
+export interface TestConfig {
+    /** Glob patterns for test files. Default: `['tests/**\/*.test.ts']`. */
+    include: string[];
+    /** Glob patterns for test files to skip after discovery. */
+    exclude?: string[];
+    /** Serial port (e.g. `'COM3'`, `'/dev/ttyACM0'`). */
+    port: string;
+    /** Serial baud rate. Default: `115200`. */
+    baudRate: number;
+    /** Timeout in ms waiting for SUITE_END. Default: `30000`. */
+    timeout: number;
+    /** Delay in ms before opening serial port (after board reset). Default: `500`. */
+    serialOpenDelay?: number;
+    /** Toggle ESP32-style DTR/RTS reset after opening the serial port. */
+    resetAfterOpen?: boolean;
+    /** Framework-specific build target override. */
+    buildTarget?: string;
+    /** Board package override. */
+    board?: string;
+    /** Show debug serial output and passing assertion details. */
+    verbose?: boolean;
+}
+/**
+ * Resolved configuration used by the runner.
+ */
+export interface ResolvedConfig {
+    test: TestConfig;
+    /** From cuttlefish.config.ts root. */
+    buildTarget: string;
+    board: string;
+    target: string;
+    /** Absolute path to project root. */
+    projectRoot: string;
+}

package/dist/host/types.js

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Host-side types
+//
+// Internal type definitions used by the host runner (Node.js process) to
+// represent parsed serial output, assertion results, and test reports.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Serial protocol
+// ---------------------------------------------------------------------------
+/** The prefix that every protocol line starts with. */
+export const PROTOCOL_PREFIX = '[TC:';
+export const PROTOCOL_SUFFIX = ']';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { Suite, Expectation, StringExpectation } from './types.js';
+export { describe, done } from './stubs.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Barrel re-export
+//
+// Users import from this package:
+//   import { describe, done } from '@typecad/expect';
+// ---------------------------------------------------------------------------
+export { describe, done } from './stubs.js';

package/dist/stubs.d.ts

@@ -0,0 +1,17 @@
+import type { Suite } from './types.js';
+/**
+ * Open a describe group.  Returns a `Suite` to chain `.it()` / `.expect()`.
+ *
+ * @example
+ * ```ts
+ * describe("A0 analog read")
+ *   .it("reads zero").expect(A0.readAnalog()).toBe(0);
+ * ```
+ */
+export declare function describe(_name: string): Suite;
+/**
+ * Mark the end of test execution.  Must be the last statement in every
+ * test file.  Emits the `[TC:SUITE_END]` sentinel and enters an idle loop
+ * so the host runner knows the firmware is done.
+ */
+export declare function done(): void;

package/dist/stubs.js

@@ -0,0 +1,26 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Firmware stubs
+//
+// These provide types to the user's IDE. The test preprocessor rewrites every
+// call into Serial protocol statements before the cuttlefish transpiler ever
+// sees them, so the runtime bodies are no-ops (only reached if the preprocessor
+// is skipped, e.g. type-checking in the IDE).
+// ---------------------------------------------------------------------------
+/**
+ * Open a describe group.  Returns a `Suite` to chain `.it()` / `.expect()`.
+ *
+ * @example
+ * ```ts
+ * describe("A0 analog read")
+ *   .it("reads zero").expect(A0.readAnalog()).toBe(0);
+ * ```
+ */
+export function describe(_name) {
+    return undefined;
+}
+/**
+ * Mark the end of test execution.  Must be the last statement in every
+ * test file.  Emits the `[TC:SUITE_END]` sentinel and enters an idle loop
+ * so the host runner knows the firmware is done.
+ */
+export function done() { }

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Numeric assertion — provides matchers that compare a numeric `actual` value
+ * against an `expected` value.  Each matcher returns the parent `Suite` so
+ * the chain can continue with `.it()` or another `.expect()`.
+ */
+export interface Expectation {
+    /** Exact equality: `actual === expected`. */
+    toBe(expected: number): Suite;
+    /** Strict greater-than: `actual > expected`. */
+    toBeGreaterThan(n: number): Suite;
+    /** Greater-than or equal: `actual >= expected`. */
+    toBeGreaterThanOrEqual(n: number): Suite;
+    /** Strict less-than: `actual < expected`. */
+    toBeLessThan(n: number): Suite;
+    /** Less-than or equal: `actual <= expected`. */
+    toBeLessThanOrEqual(n: number): Suite;
+    /**
+     * Approximate equality: `|actual − expected| < 10^(−precision)`.
+     * @param n        The expected value.
+     * @param precision  Number of decimal digits (default 2 → 0.01 tolerance).
+     */
+    toBeCloseTo(n: number, precision?: number): Suite;
+    /** Range check: `actual >= min && actual <= max`. */
+    toBeWithinRange(min: number, max: number): Suite;
+    /** Truthy: `actual !== 0`. */
+    toBeTruthy(): Suite;
+    /** Falsy: `actual === 0`. */
+    toBeFalsy(): Suite;
+    /** Not-equal: `actual !== expected`. */
+    toNotBe(expected: number): Suite;
+}
+/**
+ * String assertion — provides matchers that compare a string `actual` value.
+ */
+export interface StringExpectation {
+    /** Exact string equality. */
+    toBe(expected: string): Suite;
+    /** Substring check. */
+    toContain(substring: string): Suite;
+    /** Length check. */
+    toHaveLength(n: number): Suite;
+    /** Not-equal. */
+    toNotBe(expected: string): Suite;
+}
+/**
+ * A test suite — the return value of `describe()`.  Supports fluent chaining
+ * of `.it()` and `.expect()` calls.
+ *
+ * @example
+ * ```ts
+ * describe("A0 reads")
+ *   .it("reads zero when grounded")
+ *     .expect(A0.readAnalog()).toBe(0)
+ *   .it("reads less than 100")
+ *     .expect(A0.readAnalog()).toBeLessThan(100);
+ * ```
+ */
+export interface Suite {
+    /** Start a new test case within the current describe group. */
+    it(name: string): Suite;
+    /** Assert a numeric value (or a function that returns one). */
+    expect(actual: number | (() => number)): Expectation;
+    /** Assert a string value (or a function that returns one). */
+    expectString(actual: string | (() => string)): StringExpectation;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Firmware-side types
+//
+// These interfaces define the fluent API that users write in test files.
+// They exist purely for TypeScript IntelliSense — the preprocessor rewrites
+// all calls to Serial protocol statements before transpilation.
+// ---------------------------------------------------------------------------
+export {};