@typecad/expect 0.1.0-alpha.1

package/dist/host/config.js

@@ -0,0 +1,218 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Configuration loader
+//
+// Reads the `cuttlefish.config.ts` file to extract both the base transpiler
+// configuration and the optional `test` section for test-specific settings.
+// ---------------------------------------------------------------------------
+import path from 'node:path';
+import fs from 'node:fs';
+import ts from 'typescript';
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_TEST_CONFIG = {
+    include: ['tests/**/*.test.ts'],
+    port: '', // Must be provided by user or CLI flag
+    baudRate: 115200,
+    timeout: 30000,
+    serialOpenDelay: 500,
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Load configuration from `cuttlefish.config.ts` in the given project root.
+ *
+ * Parses the config file via the TypeScript AST (no dynamic import) to
+ * extract scalar properties — consistent with how the cuttlefish CLI does it.
+ *
+ * @param projectRoot  Absolute path to the project root.
+ * @param overrides    CLI flag overrides for test config.
+ */
+export function loadConfig(projectRoot, overrides = {}) {
+    const configPath = findConfigFile(projectRoot);
+    if (!configPath) {
+        throw new Error(`No cuttlefish.config.ts found in ${projectRoot}. ` +
+            `Create one or specify --port and --board on the command line.`);
+    }
+    const raw = parseConfigAST(configPath);
+    // Merge test config: defaults < config file < CLI overrides
+    const testFromFile = raw.test ?? {};
+    const test = {
+        include: overrides.include ?? testFromFile.include ?? DEFAULT_TEST_CONFIG.include,
+        exclude: overrides.exclude ?? testFromFile.exclude,
+        port: overrides.port ?? testFromFile.port ?? DEFAULT_TEST_CONFIG.port,
+        baudRate: overrides.baudRate ?? testFromFile.baudRate ?? DEFAULT_TEST_CONFIG.baudRate,
+        timeout: overrides.timeout ?? testFromFile.timeout ?? DEFAULT_TEST_CONFIG.timeout,
+        serialOpenDelay: overrides.serialOpenDelay ?? testFromFile.serialOpenDelay ?? DEFAULT_TEST_CONFIG.serialOpenDelay,
+        resetAfterOpen: overrides.resetAfterOpen ?? testFromFile.resetAfterOpen ?? DEFAULT_TEST_CONFIG.resetAfterOpen,
+        buildTarget: overrides.buildTarget ?? testFromFile.buildTarget,
+        board: overrides.board ?? testFromFile.board,
+        verbose: overrides.verbose ?? testFromFile.verbose,
+    };
+    return {
+        test,
+        buildTarget: test.buildTarget ?? raw.frameworkData?.buildTarget ?? 'arduino:avr:uno',
+        board: test.board ?? raw.board ?? '@typecad/board-arduino-uno',
+        target: raw.target ?? 'avr',
+        projectRoot,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal — Config file discovery
+// ---------------------------------------------------------------------------
+function findConfigFile(projectRoot) {
+    const candidates = [
+        path.join(projectRoot, 'cuttlefish.config.ts'),
+        path.join(projectRoot, 'cuttlefish.config.js'),
+    ];
+    return candidates.find(c => fs.existsSync(c));
+}
+export function parseConfigAST(configPath) {
+    const text = fs.readFileSync(configPath, 'utf8');
+    const sf = ts.createSourceFile(configPath, text, ts.ScriptTarget.Latest, true);
+    const result = {};
+    for (const stmt of sf.statements) {
+        // `const config: CuttlefishConfig = { ... };`
+        if (ts.isVariableStatement(stmt)) {
+            for (const decl of stmt.declarationList.declarations) {
+                if (decl.initializer && ts.isObjectLiteralExpression(decl.initializer)) {
+                    extractConfigProperties(decl.initializer, result);
+                }
+            }
+        }
+        // `export default { ... };`
+        if (ts.isExportAssignment(stmt) && ts.isObjectLiteralExpression(stmt.expression)) {
+            extractConfigProperties(stmt.expression, result);
+        }
+    }
+    return result;
+}
+function extractConfigProperties(obj, out) {
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+            continue;
+        const name = prop.name.text;
+        switch (name) {
+            case 'target':
+                if (ts.isStringLiteral(prop.initializer))
+                    out.target = prop.initializer.text;
+                break;
+            case 'board':
+                if (ts.isStringLiteral(prop.initializer))
+                    out.board = prop.initializer.text;
+                break;
+            case 'frameworkData':
+                if (ts.isObjectLiteralExpression(prop.initializer)) {
+                    out.frameworkData = {};
+                    for (const fProp of prop.initializer.properties) {
+                        if (ts.isPropertyAssignment(fProp) && ts.isIdentifier(fProp.name) && fProp.name.text === 'buildTarget') {
+                            if (ts.isStringLiteral(fProp.initializer))
+                                out.frameworkData.buildTarget = fProp.initializer.text;
+                        }
+                    }
+                }
+                break;
+            case 'framework':
+                if (ts.isStringLiteral(prop.initializer))
+                    out.framework = prop.initializer.text;
+                break;
+            case 'test':
+                if (ts.isObjectLiteralExpression(prop.initializer)) {
+                    out.test = extractTestConfig(prop.initializer);
+                }
+                break;
+            case 'output':
+                if (ts.isObjectLiteralExpression(prop.initializer)) {
+                    out.output = extractOutputConfig(prop.initializer);
+                }
+                break;
+            case 'console':
+                if (ts.isObjectLiteralExpression(prop.initializer)) {
+                    out.console = extractConsoleConfig(prop.initializer);
+                }
+                break;
+        }
+    }
+}
+function extractTestConfig(obj) {
+    const result = {};
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+            continue;
+        const name = prop.name.text;
+        switch (name) {
+            case 'port':
+                if (ts.isStringLiteral(prop.initializer))
+                    result.port = prop.initializer.text;
+                break;
+            case 'baudRate':
+                if (ts.isNumericLiteral(prop.initializer))
+                    result.baudRate = parseInt(prop.initializer.text, 10);
+                break;
+            case 'timeout':
+                if (ts.isNumericLiteral(prop.initializer))
+                    result.timeout = parseInt(prop.initializer.text, 10);
+                break;
+            case 'serialOpenDelay':
+                if (ts.isNumericLiteral(prop.initializer))
+                    result.serialOpenDelay = parseInt(prop.initializer.text, 10);
+                break;
+            case 'buildTarget':
+                if (ts.isStringLiteral(prop.initializer))
+                    result.buildTarget = prop.initializer.text;
+                break;
+            case 'resetAfterOpen':
+                if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword)
+                    result.resetAfterOpen = true;
+                if (prop.initializer.kind === ts.SyntaxKind.FalseKeyword)
+                    result.resetAfterOpen = false;
+                break;
+            case 'board':
+                if (ts.isStringLiteral(prop.initializer))
+                    result.board = prop.initializer.text;
+                break;
+            case 'include':
+                if (ts.isArrayLiteralExpression(prop.initializer)) {
+                    result.include = prop.initializer.elements
+                        .filter(ts.isStringLiteral)
+                        .map(el => el.text);
+                }
+                break;
+            case 'exclude':
+                if (ts.isArrayLiteralExpression(prop.initializer)) {
+                    result.exclude = prop.initializer.elements
+                        .filter(ts.isStringLiteral)
+                        .map(el => el.text);
+                }
+                break;
+        }
+    }
+    return result;
+}
+function extractOutputConfig(obj) {
+    const result = {};
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+            continue;
+        const name = prop.name.text;
+        if (name === 'framework' && ts.isStringLiteral(prop.initializer))
+            result.framework = prop.initializer.text;
+        if (name === 'optimize' && ts.isStringLiteral(prop.initializer))
+            result.optimize = prop.initializer.text;
+        if (name === 'outDir' && ts.isStringLiteral(prop.initializer))
+            result.outDir = prop.initializer.text;
+    }
+    return result;
+}
+function extractConsoleConfig(obj) {
+    const result = {};
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+            continue;
+        if (prop.name.text === 'baudRate' && ts.isNumericLiteral(prop.initializer)) {
+            result.baudRate = parseInt(prop.initializer.text, 10);
+        }
+    }
+    return result;
+}

package/dist/host/evaluator.d.ts

@@ -0,0 +1,14 @@
+import type { MatcherName } from './types.js';
+/**
+ * Evaluate a single assertion on the host side.
+ *
+ * @param matcher   The matcher name (e.g. `'toBe'`, `'toBeLessThan'`).
+ * @param expected  The expected value(s) as a raw string from the serial protocol.
+ * @param actual    The actual value as a raw string from the serial protocol.
+ * @returns `true` if the assertion passes.
+ */
+export declare function evaluate(matcher: MatcherName, expected: string, actual: string): boolean;
+/**
+ * Return a human-readable description of what the matcher checks.
+ */
+export declare function describeExpected(matcher: MatcherName, expected: string): string;

package/dist/host/evaluator.js

@@ -0,0 +1,113 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Assertion evaluator
+//
+// All assertion logic runs on the host (computer) side.  The firmware only
+// sends raw actual/expected values over serial — the host does the math.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate a single assertion on the host side.
+ *
+ * @param matcher   The matcher name (e.g. `'toBe'`, `'toBeLessThan'`).
+ * @param expected  The expected value(s) as a raw string from the serial protocol.
+ * @param actual    The actual value as a raw string from the serial protocol.
+ * @returns `true` if the assertion passes.
+ */
+export function evaluate(matcher, expected, actual) {
+    switch (matcher) {
+        case 'toBe':
+            return evaluateToBe(expected, actual);
+        case 'toNotBe':
+            return !evaluateToBe(expected, actual);
+        case 'toBeGreaterThan':
+            return toNum(actual) > toNum(expected);
+        case 'toBeGreaterThanOrEqual':
+            return toNum(actual) >= toNum(expected);
+        case 'toBeLessThan':
+            return toNum(actual) < toNum(expected);
+        case 'toBeLessThanOrEqual':
+            return toNum(actual) <= toNum(expected);
+        case 'toBeCloseTo': {
+            // expected format: "value,precision" e.g. "3.14,2"
+            const parts = expected.split(',');
+            const expVal = toNum(parts[0] ?? '0');
+            const precision = parts.length > 1 ? parseInt(parts[1], 10) : 2;
+            const tolerance = Math.pow(10, -precision);
+            return Math.abs(toNum(actual) - expVal) < tolerance;
+        }
+        case 'toBeWithinRange': {
+            // expected format: "min,max"
+            const parts = expected.split(',');
+            const min = toNum(parts[0] ?? '0');
+            const max = toNum(parts[1] ?? '0');
+            const val = toNum(actual);
+            return val >= min && val <= max;
+        }
+        case 'toBeTruthy':
+            return toNum(actual) !== 0;
+        case 'toBeFalsy':
+            return toNum(actual) === 0;
+        case 'toContain':
+            return actual.includes(expected);
+        case 'toHaveLength':
+            return actual.length === parseInt(expected, 10);
+        default: {
+            const _exhaustive = matcher;
+            return false;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public — Human-readable descriptions
+// ---------------------------------------------------------------------------
+/**
+ * Return a human-readable description of what the matcher checks.
+ */
+export function describeExpected(matcher, expected) {
+    switch (matcher) {
+        case 'toBe': return `to be ${expected}`;
+        case 'toNotBe': return `to not be ${expected}`;
+        case 'toBeGreaterThan': return `to be > ${expected}`;
+        case 'toBeGreaterThanOrEqual': return `to be >= ${expected}`;
+        case 'toBeLessThan': return `to be < ${expected}`;
+        case 'toBeLessThanOrEqual': return `to be <= ${expected}`;
+        case 'toBeCloseTo': {
+            const parts = expected.split(',');
+            const precision = parts[1] ?? '2';
+            return `to be close to ${parts[0]} (±${Math.pow(10, -parseInt(precision, 10))})`;
+        }
+        case 'toBeWithinRange': {
+            const parts = expected.split(',');
+            return `to be within ${parts[0]}–${parts[1]}`;
+        }
+        case 'toBeTruthy': return 'to be truthy (≠ 0)';
+        case 'toBeFalsy': return 'to be falsy (= 0)';
+        case 'toContain': return `to contain "${expected}"`;
+        case 'toHaveLength': return `to have length ${expected}`;
+        default: {
+            const _exhaustive = matcher;
+            return `${matcher}(${expected})`;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+function evaluateToBe(expected, actual) {
+    // Try numeric comparison first
+    // Use Number() instead of parseFloat() so hex literals like "0x10" are
+    // correctly parsed (parseFloat stops at the "x" and returns 0).
+    const numExp = Number(expected);
+    const numAct = Number(actual);
+    if (!isNaN(numExp) && !isNaN(numAct)) {
+        return numAct === numExp;
+    }
+    // Fall back to string comparison
+    return actual === expected;
+}
+function toNum(s) {
+    const n = Number(s);
+    return isNaN(n) ? 0 : n;
+}

package/dist/host/finder.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Find all test files matching the include glob patterns.
+ *
+ * Supports patterns like `tests/**\/*.test.ts`, `src/**\/*.test.ts`, or exact
+ * file paths like `src/sketch.ts`.  Only files ending in `.test.ts` are
+ * returned.
+ *
+ * @param projectRoot  Absolute path to the project root.
+ * @param include      Glob patterns to match.
+ * @returns Absolute paths to found test files, sorted alphabetically.
+ */
+export declare function findTestFiles(projectRoot: string, include: string[]): string[];

package/dist/host/finder.js

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Test file finder
+//
+// Globs for test files matching the configured include patterns.
+// ---------------------------------------------------------------------------
+import path from 'node:path';
+import fs from 'node:fs';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Find all test files matching the include glob patterns.
+ *
+ * Supports patterns like `tests/**\/*.test.ts`, `src/**\/*.test.ts`, or exact
+ * file paths like `src/sketch.ts`.  Only files ending in `.test.ts` are
+ * returned.
+ *
+ * @param projectRoot  Absolute path to the project root.
+ * @param include      Glob patterns to match.
+ * @returns Absolute paths to found test files, sorted alphabetically.
+ */
+export function findTestFiles(projectRoot, include) {
+    const seen = new Set();
+    for (const pattern of include) {
+        for (const f of expandPattern(projectRoot, pattern)) {
+            if (f.endsWith('.test.ts') && !seen.has(f)) {
+                seen.add(f);
+            }
+        }
+    }
+    return [...seen].sort();
+}
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+function expandPattern(projectRoot, pattern) {
+    const normalized = pattern.replace(/\\/g, '/');
+    // Exact file path (no wildcards)
+    if (!normalized.includes('*')) {
+        const abs = path.resolve(projectRoot, normalized);
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile())
+            return [abs];
+        return [];
+    }
+    // Split on the first ** or * to get directory prefix
+    const starIdx = normalized.indexOf('*');
+    const dirPart = normalized.slice(0, starIdx).replace(/\/$/, '');
+    const absDir = path.resolve(projectRoot, dirPart || '.');
+    if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory())
+        return [];
+    // Use recursive readdir, then match each relative path against the full pattern
+    const regex = globToRegex(normalized.slice(dirPart ? dirPart.length + 1 : 0));
+    const results = [];
+    for (const entry of fs.readdirSync(absDir, { recursive: true })) {
+        const rel = entry.toString().replace(/\\/g, '/');
+        if (regex.test(rel) && rel.endsWith('.test.ts')) {
+            const abs = path.resolve(absDir, rel);
+            if (fs.statSync(abs, { throwIfNoEntry: false })?.isFile()) {
+                results.push(abs);
+            }
+        }
+    }
+    return results;
+}
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    // **/ matches zero or more path segments, * matches within a single segment
+    const pattern = escaped.replace(/\?/g, '[^/]').replace(/\*\*\//g, '(.+/)?').replace(/\*/g, '[^/]*');
+    return new RegExp(`^${pattern}$`);
+}

package/dist/host/parser.d.ts

@@ -0,0 +1,5 @@
+import type { DescribeResult } from './types.js';
+/**
+ * Parse raw protocol lines into structured describe/test/assertion results.
+ */
+export declare function parseProtocolLines(rawLines: string[]): DescribeResult[];

package/dist/host/parser.js

@@ -0,0 +1,196 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — Protocol parser
+//
+// Parses protocol lines from serial output into structured test results.
+//
+// Protocol format:
+//   [TC:SUITE_START]
+//   [TC:DESCRIBE:name]
+//   [TC:IT:name]
+//   [TC:EXPECT:matcher:expected:actual]
+//   [TC:SUITE_END]
+// ---------------------------------------------------------------------------
+import { evaluate } from './evaluator.js';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Parse raw protocol lines into structured describe/test/assertion results.
+ */
+export function parseProtocolLines(rawLines) {
+    const lines = rawLines.map(parseSingleLine).filter(Boolean);
+    return buildResults(lines);
+}
+// ---------------------------------------------------------------------------
+// Internal — Line parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse a single protocol line into its tag and fields.
+ *
+ * Format: `[TC:TAG:field1:field2:...]`
+ *
+ * The last field of EXPECT lines may contain colons (e.g. string values),
+ * so we parse carefully.
+ */
+function parseSingleLine(raw) {
+    // Strip brackets: "[TC:..." → "TC:..."
+    const inner = raw.replace(/^\[/, '').replace(/\]$/, '');
+    if (!inner.startsWith('TC:'))
+        return null;
+    // Split on first `:` after `TC` to get the tag
+    const withoutPrefix = inner.slice(3); // remove "TC:"
+    const colonIdx = withoutPrefix.indexOf(':');
+    let tag;
+    let rest;
+    if (colonIdx === -1) {
+        tag = withoutPrefix;
+        rest = '';
+    }
+    else {
+        tag = withoutPrefix.slice(0, colonIdx);
+        rest = withoutPrefix.slice(colonIdx + 1);
+    }
+    if (!isValidTag(tag))
+        return null;
+    const fields = rest.length > 0 ? splitFields(tag, rest) : [];
+    return { tag: tag, fields, raw };
+}
+function isValidTag(tag) {
+    return ['SUITE_START', 'DESCRIBE', 'IT', 'EXPECT', 'SUITE_END'].includes(tag);
+}
+/**
+ * Split field string into segments.
+ *
+ * For EXPECT lines, the format is `matcher:expected:actual` where the actual
+ * value is everything after the last colon-separated segment.
+ * For DESCRIBE/IT, there's only one field (the name).
+ */
+function splitFields(tag, rest) {
+    if (tag === 'DESCRIBE' || tag === 'IT') {
+        return [rest]; // name may contain colons — treat as single field
+    }
+    if (tag === 'EXPECT') {
+        // Format: matcher:expected:actual
+        // matcher is always a single word, expected may contain commas (for range)
+        // actual is the last segment (everything after the last unescaped colon)
+        return splitExpectFields(rest);
+    }
+    return rest.split(':');
+}
+/**
+ * Split EXPECT fields: `toBe:0:11` → ['toBe', '0', '11']
+ *
+ * We know the structure: matcher is first, then expected value(s), then actual
+ * value as the final segment.
+ */
+function splitExpectFields(rest) {
+    const parts = rest.split(':');
+    if (parts.length < 3)
+        return parts;
+    // First part is the matcher name
+    const matcher = parts[0];
+    // Last part is the actual value
+    const actual = parts[parts.length - 1];
+    // Everything in between is the expected value (may have been split on : if
+    // it contained colons, so rejoin)
+    const expected = parts.slice(1, -1).join(':');
+    return [matcher, expected, actual];
+}
+// ---------------------------------------------------------------------------
+// Internal — Result building
+// ---------------------------------------------------------------------------
+function buildResults(lines) {
+    const describes = [];
+    let currentDescribe = null;
+    let currentTest = null;
+    for (const line of lines) {
+        switch (line.tag) {
+            case 'SUITE_START':
+                // No-op — we already know we're starting
+                break;
+            case 'DESCRIBE': {
+                // Close previous test + describe if open
+                if (currentTest && currentDescribe) {
+                    finalizeTest(currentTest);
+                    currentDescribe.tests.push(currentTest);
+                    currentTest = null;
+                }
+                if (currentDescribe) {
+                    finalizeDescribe(currentDescribe);
+                    describes.push(currentDescribe);
+                }
+                currentDescribe = {
+                    name: line.fields[0] ?? 'unnamed',
+                    tests: [],
+                    passed: true,
+                };
+                break;
+            }
+            case 'IT': {
+                // Close previous test if open
+                if (currentTest && currentDescribe) {
+                    finalizeTest(currentTest);
+                    currentDescribe.tests.push(currentTest);
+                }
+                currentTest = {
+                    name: line.fields[0] ?? 'unnamed',
+                    assertions: [],
+                    passed: true,
+                    durationMs: 0,
+                };
+                break;
+            }
+            case 'EXPECT': {
+                if (!currentTest) {
+                    // EXPECT outside of IT — create an implicit test
+                    currentTest = {
+                        name: '(implicit)',
+                        assertions: [],
+                        passed: true,
+                        durationMs: 0,
+                    };
+                }
+                const [matcher, expected, actual] = line.fields;
+                if (matcher) {
+                    const assertion = {
+                        matcher: matcher,
+                        expected: expected ?? '',
+                        actual: actual ?? '',
+                        passed: evaluate(matcher, expected ?? '', actual ?? ''),
+                    };
+                    currentTest.assertions.push(assertion);
+                }
+                break;
+            }
+            case 'SUITE_END': {
+                if (currentTest && currentDescribe) {
+                    finalizeTest(currentTest);
+                    currentDescribe.tests.push(currentTest);
+                    currentTest = null;
+                }
+                if (currentDescribe) {
+                    finalizeDescribe(currentDescribe);
+                    describes.push(currentDescribe);
+                    currentDescribe = null;
+                }
+                break;
+            }
+        }
+    }
+    // Handle unterminated groups
+    if (currentTest && currentDescribe) {
+        finalizeTest(currentTest);
+        currentDescribe.tests.push(currentTest);
+    }
+    if (currentDescribe) {
+        finalizeDescribe(currentDescribe);
+        describes.push(currentDescribe);
+    }
+    return describes;
+}
+function finalizeTest(test) {
+    test.passed = test.assertions.every(a => a.passed);
+}
+function finalizeDescribe(desc) {
+    desc.passed = desc.tests.every(t => t.passed);
+}

package/dist/host/preprocessor.d.ts

@@ -0,0 +1,33 @@
+export interface PreprocessorOptions {
+    /** Wrap string literals in Arduino F() macro to save SRAM on AVR. */
+    isAvr?: boolean;
+}
+/**
+ * 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 declare function preprocess(source: string, fileName?: string, options?: PreprocessorOptions): string;
+export declare class PreprocessorContext {
+    private lines;
+    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. */
+    flash(s: string): string;
+    /** Emit a line of TypeScript output. */
+    emit(line: string): void;
+    /** Generate a unique temporary variable name. */
+    nextVar(): string;
+    /** Generate a unique extracted function name. */
+    nextFn(): string;
+    private emitPreamble;
+    build(): string;
+}