@typecad/expect 0.1.0-alpha.1

package/dist/host/preprocessor.js

@@ -0,0 +1,115 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — AST Preprocessor
+//
+// Transforms fluent test syntax into flat Serial.print/println protocol
+// calls that the cuttlefish transpiler handles correctly.
+//
+// INPUT (user test file):
+//   describe("A0 analog read")
+//     .it("reads zero").expect(A0.readAnalog()).toBe(0);
+//   done();
+//
+// OUTPUT (preprocessed — fed to transpiler):
+//   Serial.begin(115200);
+//   Serial.println("[TC:SUITE_START]");
+//   Serial.println("[TC:DESCRIBE:A0 analog read]");
+//   Serial.println("[TC:IT:reads zero]");
+//   const __tc_v1: number = A0.readAnalog();
+//   Serial.print("[TC:EXPECT:toBe:0:");
+//   Serial.print(__tc_v1);
+//   Serial.println("]");
+//   Serial.println("[TC:SUITE_END]");
+//   while (true) { delay(1000); }
+// ---------------------------------------------------------------------------
+import ts from 'typescript';
+import { isDescribeChain, collectChainSegments } from './chain-collector.js';
+import { emitSegments } from './protocol-emitter.js';
+/**
+ * Preprocess a test file's TypeScript source.
+ *
+ * 1. Strips `import { ... } from '@typecad/expect'`
+ * 2. Walks top-level expression-statements looking for `describe(...)...` chains
+ * 3. Replaces `done()` with the suite-end sentinel + idle loop
+ * 4. Hoists hardware expressions out of `expect()` into `const` declarations
+ * 5. Wraps everything with Serial.initialize + SUITE_START preamble
+ */
+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);
+    for (const stmt of sf.statements) {
+        if (ts.isImportDeclaration(stmt)) {
+            const moduleSpecifier = stmt.moduleSpecifier.text;
+            if (moduleSpecifier === '@typecad/expect')
+                continue; // strip
+            ctx.emit(stmt.getText(sf));
+        }
+        else if (ts.isExpressionStatement(stmt)) {
+            processExpressionStatement(stmt, sf, ctx);
+        }
+        else {
+            ctx.emit(stmt.getText(sf));
+        }
+    }
+    return ctx.build();
+}
+// ---------------------------------------------------------------------------
+// PreprocessorContext — shared state threaded through sub-modules
+// ---------------------------------------------------------------------------
+export class PreprocessorContext {
+    constructor(isAvr) {
+        this.lines = [];
+        this.varCounter = 0;
+        this.fnCounter = 0;
+        this.preambleEmitted = false;
+        this.baudRate = 115200;
+        this.isAvr = isAvr;
+    }
+    /** Wrap a string literal in F() on AVR to keep it in flash. */
+    flash(s) {
+        return this.isAvr ? `F("${s}")` : `"${s}"`;
+    }
+    /** Emit a line of TypeScript output. */
+    emit(line) {
+        if (!this.preambleEmitted)
+            this.emitPreamble();
+        this.lines.push(line);
+    }
+    /** Generate a unique temporary variable name. */
+    nextVar() {
+        return `__tc_v${++this.varCounter}`;
+    }
+    /** Generate a unique extracted function name. */
+    nextFn() {
+        return `__tc_fn${++this.fnCounter}`;
+    }
+    emitPreamble() {
+        this.preambleEmitted = true;
+        this.lines.push(`Serial.begin(${this.baudRate});`);
+        this.lines.push(`Serial.println(${this.flash('[TC:SUITE_START]')});`);
+    }
+    build() {
+        return this.lines.join('\n') + '\n';
+    }
+}
+// ---------------------------------------------------------------------------
+// Statement processing
+// ---------------------------------------------------------------------------
+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); }`);
+        return;
+    }
+    if (isDescribeChain(expr)) {
+        const segments = collectChainSegments(expr, sf, ctx);
+        emitSegments(segments, ctx);
+        return;
+    }
+    ctx.emit(stmt.getText(sf));
+}
+function isDoneCall(expr) {
+    return (ts.isCallExpression(expr) &&
+        ts.isIdentifier(expr.expression) &&
+        expr.expression.text === 'done');
+}

package/dist/host/protocol-emitter.d.ts

@@ -0,0 +1,29 @@
+import type { PreprocessorContext } from './preprocessor.js';
+import type { ChainSegment } from './chain-collector.js';
+/**
+ * Emit all Serial protocol lines for a collected chain.
+ */
+export declare function emitSegments(segments: ChainSegment[], ctx: PreprocessorContext): void;
+/**
+ * Emit the Serial.print sequence for one assertion.
+ *
+ * Numeric:  Serial.print("[TC:EXPECT:matcher:expected:");
+ *           Serial.print(actual);
+ *           Serial.println("]");
+ *
+ * String:   Serial.print("[TC:EXPECT:matcher:");
+ *           Serial.print("expected");
+ *           Serial.print(":");
+ *           Serial.print(actual);
+ *           Serial.println("]");
+ */
+export declare function emitExpectProtocol(actualVar: string, matcher: string, matcherArgs: string[], ctx: PreprocessorContext, isString?: boolean): void;
+/**
+ * Is the expression "simple" enough to inline without hoisting?
+ * Simple: identifiers, literals.  Complex: anything with method calls.
+ */
+export declare function isSimpleExpression(expr: string): boolean;
+/** Heuristic: does this expression produce a string? */
+export declare function isStringExpression(expr: string): boolean;
+/** Escape characters that could break the protocol line format. */
+export declare function escapeProtocol(s: string): string;

package/dist/host/protocol-emitter.js

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Protocol Emitter
+//
+// Converts collected chain segments into Serial.print/println protocol lines.
+// All logic for the [TC:DESCRIBE:...], [TC:IT:...], [TC:EXPECT:...] wire
+// format lives here.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Segment emission
+// ---------------------------------------------------------------------------
+/**
+ * Emit all Serial protocol lines for a collected chain.
+ */
+export function emitSegments(segments, ctx) {
+    // First pass: emit any extracted function definitions before the protocol
+    for (const seg of segments) {
+        if (seg.kind === 'expect' && seg.extractedFn) {
+            ctx.emit(seg.extractedFn);
+        }
+    }
+    // Second pass: emit protocol lines
+    for (const seg of segments) {
+        switch (seg.kind) {
+            case 'describe':
+                ctx.emit(`Serial.println(${ctx.flash(`[TC:DESCRIBE:${escapeProtocol(seg.name ?? '')}]`)});`);
+                break;
+            case 'it':
+                ctx.emit(`Serial.println(${ctx.flash(`[TC:IT:${escapeProtocol(seg.name ?? '')}]`)});`);
+                break;
+            case 'expect': {
+                if (!seg.matcher)
+                    break; // expect() without matcher — skip
+                const actualExpr = seg.actualExpr ?? '0';
+                const isString = seg.isStringExpect || seg.matcher === 'toContain' || seg.matcher === 'toHaveLength'
+                    || (seg.matcher === 'toBe' && isStringExpression(actualExpr));
+                const typeAnnotation = isString ? 'string' : 'number';
+                if (isSimpleExpression(actualExpr)) {
+                    emitExpectProtocol(actualExpr, seg.matcher, seg.matcherArgs ?? [], ctx, isString);
+                }
+                else {
+                    // Hoist: const __tc_v1: number = A0.readAnalog();
+                    const tmpVar = ctx.nextVar();
+                    ctx.emit(`const ${tmpVar}: ${typeAnnotation} = ${actualExpr};`);
+                    emitExpectProtocol(tmpVar, seg.matcher, seg.matcherArgs ?? [], ctx, isString);
+                }
+                break;
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Protocol line builder
+// ---------------------------------------------------------------------------
+/**
+ * Emit the Serial.print sequence for one assertion.
+ *
+ * Numeric:  Serial.print("[TC:EXPECT:matcher:expected:");
+ *           Serial.print(actual);
+ *           Serial.println("]");
+ *
+ * String:   Serial.print("[TC:EXPECT:matcher:");
+ *           Serial.print("expected");
+ *           Serial.print(":");
+ *           Serial.print(actual);
+ *           Serial.println("]");
+ */
+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(']')});`);
+        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(']')});`);
+}
+// ---------------------------------------------------------------------------
+// Expression classification helpers
+// ---------------------------------------------------------------------------
+/**
+ * Is the expression "simple" enough to inline without hoisting?
+ * Simple: identifiers, literals.  Complex: anything with method calls.
+ */
+export function isSimpleExpression(expr) {
+    return !/\.\w+\s*\(/.test(expr);
+}
+/** Heuristic: does this expression produce a string? */
+export function isStringExpression(expr) {
+    if (/^["']/.test(expr))
+        return true;
+    if (/\.readString|\.readLine/.test(expr))
+        return true;
+    return false;
+}
+/** Escape characters that could break the protocol line format. */
+export function escapeProtocol(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+}

package/dist/host/reporter.d.ts

@@ -0,0 +1,11 @@
+import type { RunResult, FileResult } from './types.js';
+/**
+ * Print a single test file's results immediately.
+ */
+export declare function reportFileResult(file: FileResult, options?: {
+    verbose?: boolean;
+}): void;
+export declare function reportSummary(result: RunResult, options?: {
+    board?: string;
+    port?: string;
+}): void;

package/dist/host/reporter.js

@@ -0,0 +1,200 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Vitest-style console reporter
+//
+// Renders test results to the console with ANSI colors, mimicking vitest's
+// output format.
+//
+// Example output:
+//
+//  cuttlefish-test v0.1.0
+//
+//  ✓ A0 analog read (2 tests)
+//    ✓ reads zero when grounded          2ms
+//    ✓ reads less than 100               1ms
+//
+//  ✗ Temperature sensor (1 of 2 failing)
+//    ✓ reads above freezing              3ms
+//    ✗ reads room temperature            2ms
+//
+//      expect(actual).toBeWithinRange(20, 25)
+//      Actual:   31
+//      Expected: 20–25
+//
+//  Tests   3 passed | 1 failed (4)
+//  Board   Arduino Uno @ COM3
+//  Time    8.42s
+// ---------------------------------------------------------------------------
+import { describeExpected } from './evaluator.js';
+// ---------------------------------------------------------------------------
+// ANSI color codes
+// ---------------------------------------------------------------------------
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const WHITE = '\x1b[37m';
+const RED_BG = '\x1b[41m';
+const GREEN_BG = '\x1b[42m';
+const PASS_ICON = `${GREEN}✓${RESET}`;
+const FAIL_ICON = `${RED}✗${RESET}`;
+const SKIP_ICON = `${YELLOW}↓${RESET}`;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Print a single test file's results immediately.
+ */
+export function reportFileResult(file, options = {}) {
+    const verbose = options.verbose ?? false;
+    reportFile(file, verbose);
+    const failures = collectFailuresFromFile(file);
+    if (failures.length > 0) {
+        console.log(`${BOLD}${RED} FAILURES${RESET}`);
+        console.log();
+        for (const f of failures) {
+            reportFailure(f);
+        }
+    }
+    console.log();
+}
+export function reportSummary(result, options = {}) {
+    const { board, port } = options;
+    reportSummarySection(result, board, port);
+}
+// ---------------------------------------------------------------------------
+// Internal — File reporting
+// ---------------------------------------------------------------------------
+function reportFile(file, verbose) {
+    if (file.skipped) {
+        console.log(` ${SKIP_ICON} ${BOLD}${file.filePath}${RESET} ${YELLOW}(skipped)${RESET}`);
+        if (verbose && file.skipReason) {
+            console.log(`   ${DIM}${file.skipReason}${RESET}`);
+        }
+        console.log();
+        return;
+    }
+    if (file.error) {
+        console.log(` ${FAIL_ICON} ${BOLD}${file.filePath}${RESET} ${RED}(error)${RESET}`);
+        console.log(`   ${DIM}${file.error}${RESET}`);
+        console.log();
+        return;
+    }
+    for (const desc of file.describes) {
+        reportDescribe(desc, verbose);
+    }
+    // Debug output
+    if (verbose && file.debugOutput.length > 0) {
+        console.log(`   ${DIM}── serial debug ──${RESET}`);
+        for (const line of file.debugOutput) {
+            console.log(`   ${DIM}${line}${RESET}`);
+        }
+        console.log();
+    }
+}
+function reportDescribe(desc, verbose) {
+    const totalTests = desc.tests.length;
+    const passedTests = desc.tests.filter(t => t.passed).length;
+    const failedTests = totalTests - passedTests;
+    const icon = desc.passed ? PASS_ICON : FAIL_ICON;
+    const countText = desc.passed
+        ? `${DIM}(${totalTests} test${totalTests !== 1 ? 's' : ''})${RESET}`
+        : `${RED}(${failedTests} of ${totalTests} failing)${RESET}`;
+    console.log(` ${icon} ${BOLD}${desc.name}${RESET} ${countText}`);
+    for (const test of desc.tests) {
+        reportTest(test, verbose);
+    }
+    console.log();
+}
+function reportTest(test, verbose) {
+    const icon = test.passed ? PASS_ICON : FAIL_ICON;
+    const duration = test.durationMs > 0 ? `${DIM}${test.durationMs}ms${RESET}` : '';
+    console.log(`   ${icon} ${test.name}  ${duration}`);
+    // In verbose mode, show passing assertion details too
+    if (verbose && test.passed) {
+        for (const a of test.assertions) {
+            console.log(`     ${DIM}${a.matcher}(${a.expected}) → ${a.actual} ✓${RESET}`);
+        }
+    }
+}
+function collectFailuresFromFile(file) {
+    const failures = [];
+    if (file.error) {
+        return failures;
+    }
+    for (const desc of file.describes) {
+        for (const test of desc.tests) {
+            for (const assertion of test.assertions) {
+                if (!assertion.passed) {
+                    failures.push({
+                        describeName: desc.name,
+                        testName: test.name,
+                        assertion,
+                    });
+                }
+            }
+        }
+    }
+    return failures;
+}
+function reportFailure(f) {
+    const a = f.assertion;
+    console.log(`   ${RED}${BOLD}${f.describeName} > ${f.testName}${RESET}`);
+    console.log();
+    console.log(`     ${DIM}expect(actual).${a.matcher}(${a.expected})${RESET}`);
+    console.log(`     ${RED}Actual:   ${BOLD}${a.actual}${RESET}`);
+    console.log(`     ${GREEN}Expected: ${BOLD}${describeExpected(a.matcher, a.expected)}${RESET}`);
+    console.log();
+}
+// ---------------------------------------------------------------------------
+// Internal — Summary
+// ---------------------------------------------------------------------------
+function reportSummarySection(result, board, port) {
+    // Tests line
+    const passedText = result.totalPassed > 0
+        ? `${GREEN}${BOLD}${result.totalPassed} passed${RESET}`
+        : '';
+    const failedText = result.totalFailed > 0
+        ? `${RED}${BOLD}${result.totalFailed} failed${RESET}`
+        : '';
+    const skippedText = result.totalSkipped > 0
+        ? `${YELLOW}${BOLD}${result.totalSkipped} skipped${RESET}`
+        : '';
+    const parts = [passedText, failedText, skippedText].filter(Boolean).join(`${DIM} | ${RESET}`);
+    const total = result.totalTests + result.totalSkipped;
+    console.log(` ${BOLD}Tests${RESET}   ${parts} ${DIM}(${total})${RESET}`);
+    if (result.totalSkipped > 0) {
+        const skippedFiles = result.files.filter(file => file.skipped).length;
+        const totalFiles = result.files.length;
+        console.log(` ${BOLD}Test Files${RESET}  ${YELLOW}${BOLD}${skippedFiles} skipped${RESET} ${DIM}(${totalFiles})${RESET}`);
+    }
+    // Errors line (compile/upload failures)
+    if (result.totalErrors > 0) {
+        console.log(` ${BOLD}Errors${RESET}  ${RED}${BOLD}${result.totalErrors} file${result.totalErrors !== 1 ? 's' : ''} failed to build${RESET}`);
+    }
+    // Board line
+    if (board || port) {
+        const boardPart = board ?? 'unknown';
+        const portPart = port ? ` @ ${port}` : '';
+        console.log(` ${BOLD}Board${RESET}   ${boardPart}${portPart}`);
+    }
+    // Time line
+    const seconds = (result.durationMs / 1000).toFixed(2);
+    console.log(` ${BOLD}Time${RESET}    ${seconds}s`);
+    // Final status bar
+    if (result.totalFailed > 0 || result.totalErrors > 0) {
+        console.log();
+        const failParts = [];
+        if (result.totalFailed > 0)
+            failParts.push(`${result.totalFailed} test${result.totalFailed !== 1 ? 's' : ''} failed`);
+        if (result.totalErrors > 0)
+            failParts.push(`${result.totalErrors} build error${result.totalErrors !== 1 ? 's' : ''}`);
+        console.log(`${RED_BG}${WHITE}${BOLD} FAIL ${RESET} ${RED}${failParts.join(', ')}${RESET}`);
+    }
+    else {
+        console.log();
+        console.log(`${GREEN_BG}${WHITE}${BOLD} PASS ${RESET} ${GREEN}All tests passed${RESET}`);
+    }
+}

package/dist/host/runner.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedConfig } from './types.js';
+/**
+ * Run all test files matching the configuration.
+ *
+ * @returns Exit code: 0 = all passed, 1 = failures, 2 = error.
+ */
+export declare function run(config: ResolvedConfig): Promise<number>;