@typecad/cuttlefish 0.1.0-alpha.1

package/dist/create/init-wizard.js

@@ -0,0 +1,168 @@
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import chalk from "chalk";
+import { KNOWN_TARGETS } from "./init-scaffold.js";
+function validateProjectName(name) {
+    if (!name || name.trim().length === 0) {
+        return "Project name cannot be empty.";
+    }
+    const normalized = name.trim().toLowerCase();
+    if (!/^[a-z][a-z0-9-]*$/.test(normalized)) {
+        return "Project name must start with a letter and contain only lowercase letters, digits, and hyphens.";
+    }
+    if (normalized.length > 64) {
+        return "Project name must be 64 characters or fewer.";
+    }
+    return null;
+}
+async function promptText(rl, prompt, defaultValue, validate) {
+    while (true) {
+        const suffix = defaultValue ? ` (${defaultValue})` : "";
+        const answer = await rl.question(`${chalk.cyan("?")} ${prompt}${suffix}: `);
+        const value = (answer.trim() || (defaultValue ?? "")).trim();
+        if (validate) {
+            const error = validate(value);
+            if (error) {
+                console.log(`  ${chalk.red("✗")} ${error}`);
+                continue;
+            }
+        }
+        return value;
+    }
+}
+async function promptSelect(rl, prompt, options) {
+    console.log(`${chalk.cyan("?")} ${prompt}:`);
+    for (let i = 0; i < options.length; i++) {
+        console.log(`  ${chalk.dim(`${i + 1})`)} ${options[i].label}`);
+    }
+    while (true) {
+        const answer = await rl.question(`  Enter number (1-${options.length}): `);
+        const idx = parseInt(answer.trim(), 10) - 1;
+        if (idx >= 0 && idx < options.length) {
+            return options[idx].value;
+        }
+        console.log(`  ${chalk.red("✗")} Please enter a number between 1 and ${options.length}.`);
+    }
+}
+async function promptConfirm(rl, prompt, defaultValue) {
+    const suffix = defaultValue ? " (Y/n)" : " (y/N)";
+    const answer = await rl.question(`${chalk.cyan("?")} ${prompt}${suffix}: `);
+    const trimmed = answer.trim().toLowerCase();
+    if (trimmed === "")
+        return defaultValue;
+    return trimmed === "y" || trimmed === "yes";
+}
+export async function runInitWizard(partialOptions) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        console.log();
+        console.log(chalk.cyan("⤳ Cuttlefish") + chalk.dim(" — Project Setup"));
+        console.log();
+        // 1. Project name
+        const projectName = partialOptions?.projectName
+            ?? await promptText(rl, "Project name", "my-project", validateProjectName);
+        // 2. Target selection (native first, then embedded boards)
+        const targetOptions = KNOWN_TARGETS.map((t) => ({
+            label: t.isNative
+                ? `${t.displayName} (Windows/Linux executable)`
+                : `${t.displayName} (${t.architecture.toUpperCase()})`,
+            value: t.id,
+        }));
+        let targetId;
+        if (partialOptions?.board) {
+            const found = KNOWN_TARGETS.find((t) => t.id === partialOptions.board);
+            if (found) {
+                targetId = found.id;
+                console.log(`${chalk.cyan("?")} Target: ${chalk.white(found.displayName)} (${chalk.dim(partialOptions.board)})`);
+            }
+            else {
+                console.log(`  ${chalk.yellow("!")} Target '${chalk.white(partialOptions.board)}' not found.`);
+                targetId = await promptSelect(rl, "Target", targetOptions);
+            }
+        }
+        else {
+            targetId = await promptSelect(rl, "Target", targetOptions);
+        }
+        const target = KNOWN_TARGETS.find((t) => t.id === targetId);
+        // 3. Framework (only for embedded targets)
+        let framework = target.framework;
+        let frameworkPackage = target.frameworkPackage;
+        if (!target.isNative) {
+            const frameworkOptions = [
+                { label: "Arduino (digitalWrite, Wire, SPI)", value: 'arduino', pkg: '@typecad/framework-arduino' },
+            ];
+            if (target.architecture === 'avr') {
+                frameworkOptions.push({ label: "Bare-metal AVR (PORTB, etc.)", value: 'avr', pkg: '@typecad/framework-avr' });
+            }
+            if (partialOptions?.framework) {
+                const match = frameworkOptions.find(f => f.value === partialOptions.framework);
+                framework = match?.value ?? partialOptions.framework;
+                frameworkPackage = match?.pkg ?? `@typecad/framework-${partialOptions.framework}`;
+                console.log(`${chalk.cyan("?")} Framework: ${chalk.white(framework)}`);
+            }
+            else if (frameworkOptions.length === 1) {
+                framework = frameworkOptions[0].value;
+                frameworkPackage = frameworkOptions[0].pkg;
+                console.log(`${chalk.cyan("?")} Framework: ${chalk.white(frameworkOptions[0].label)}`);
+            }
+            else {
+                const selected = await promptSelect(rl, "Framework", frameworkOptions.map(f => ({ label: f.label, value: f.value })));
+                const match = frameworkOptions.find(f => f.value === selected);
+                framework = match.value;
+                frameworkPackage = match.pkg;
+            }
+        }
+        // 4. Baud rate (only for embedded)
+        let baudRate;
+        if (!target.isNative) {
+            if (partialOptions?.baud) {
+                baudRate = partialOptions.baud;
+                console.log(`${chalk.cyan("?")} Serial baud rate: ${chalk.white(baudRate)}`);
+            }
+            else {
+                const baudAnswer = await promptText(rl, "Serial baud rate", "9600");
+                baudRate = parseInt(baudAnswer, 10);
+                if (Number.isNaN(baudRate) || baudRate <= 0) {
+                    baudRate = 9600;
+                    console.log(`  ${chalk.dim("Using default: 9600")}`);
+                }
+            }
+        }
+        // 5. Starter sketch
+        let includeSketch;
+        if (partialOptions?.noSketch) {
+            includeSketch = false;
+            console.log(`${chalk.cyan("?")} Create starter sketch: ${chalk.dim("no")}`);
+        }
+        else if (partialOptions?.noSketch === false) {
+            includeSketch = true;
+            console.log(`${chalk.cyan("?")} Create starter sketch: ${chalk.green("yes")}`);
+        }
+        else {
+            includeSketch = await promptConfirm(rl, "Create starter sketch?", true);
+        }
+        return {
+            projectName,
+            targetId: target.id,
+            targetDisplayName: target.displayName,
+            isNative: target.isNative,
+            architecture: target.architecture,
+            boardPackage: target.boardPackage,
+            frameworkPackage,
+            framework,
+            buildTarget: target.buildTarget,
+            mcu: target.mcu,
+            baudRate,
+            includeSketch,
+        };
+    }
+    catch (err) {
+        if (err && typeof err === 'object' && err.code === 'ERR_USE_AFTER_CLOSE') {
+            return null;
+        }
+        throw err;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/debug/breakpoint-loader.d.ts

@@ -0,0 +1,24 @@
+import type { BreakpointMap, RichBreakpoint } from './types.js';
+/**
+ * Default directory for TypeCAD debug files.
+ */
+export declare const CUTTLEFISH_DIR = ".cuttlefish";
+/**
+ * Default filename for breakpoint data.
+ */
+export declare const BREAKPOINTS_FILE = "breakpoints.json";
+/**
+ * Load breakpoints from .cuttlefish/breakpoints.json.
+ *
+ * @param sourceDir The directory containing the source file (or any directory in the project)
+ * @returns BreakpointMap or undefined if no breakpoints file exists
+ */
+export declare function loadBreakpoints(sourceDir: string): BreakpointMap | undefined;
+/**
+ * Get rich breakpoints for a specific file from the BreakpointMap.
+ *
+ * @param breakpoints The breakpoint map
+ * @param fileName The file path to look up
+ * @returns Array of RichBreakpoint objects for the file
+ */
+export declare function getBreakpointsForFile(breakpoints: BreakpointMap, fileName: string): RichBreakpoint[];

package/dist/debug/breakpoint-loader.js

@@ -0,0 +1,137 @@
+// ---------------------------------------------------------------------------
+// @typecad/debug — Breakpoint Loader
+//
+// Loads breakpoint data from .cuttlefish/breakpoints.json, which is written
+// by the VS Code extension when users set breakpoints.
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Default directory for TypeCAD debug files.
+ */
+export const CUTTLEFISH_DIR = '.cuttlefish';
+/**
+ * Default filename for breakpoint data.
+ */
+export const BREAKPOINTS_FILE = 'breakpoints.json';
+/**
+ * Find the .cuttlefish directory by walking up from the given directory.
+ */
+function findCuttlefishDir(startDir) {
+    let currentDir = path.resolve(startDir);
+    while (currentDir !== path.dirname(currentDir)) {
+        const cuttlefishDir = path.join(currentDir, CUTTLEFISH_DIR);
+        if (fs.existsSync(cuttlefishDir) && fs.statSync(cuttlefishDir).isDirectory()) {
+            return cuttlefishDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    // Check root level
+    const rootCuttlefishDir = path.join(currentDir, CUTTLEFISH_DIR);
+    if (fs.existsSync(rootCuttlefishDir) && fs.statSync(rootCuttlefishDir).isDirectory()) {
+        return rootCuttlefishDir;
+    }
+    return undefined;
+}
+/**
+ * Load breakpoints from .cuttlefish/breakpoints.json.
+ *
+ * @param sourceDir The directory containing the source file (or any directory in the project)
+ * @returns BreakpointMap or undefined if no breakpoints file exists
+ */
+export function loadBreakpoints(sourceDir) {
+    const cuttlefishDir = findCuttlefishDir(sourceDir);
+    if (!cuttlefishDir) {
+        return undefined;
+    }
+    const breakpointsPath = path.join(cuttlefishDir, BREAKPOINTS_FILE);
+    if (!fs.existsSync(breakpointsPath)) {
+        return undefined;
+    }
+    try {
+        const content = fs.readFileSync(breakpointsPath, 'utf-8');
+        const data = JSON.parse(content);
+        // Handle VS Code extension format: { "breakpoints": [...] }
+        if (data.breakpoints && Array.isArray(data.breakpoints)) {
+            const map = {};
+            for (const bp of data.breakpoints) {
+                const file = bp.file;
+                if (file && bp.line) {
+                    if (!map[file]) {
+                        map[file] = [];
+                    }
+                    map[file].push({
+                        file,
+                        line: bp.line,
+                        condition: bp.condition,
+                        logMessage: bp.logMessage,
+                    });
+                }
+            }
+            return map;
+        }
+        // Handle direct array format: [...]
+        if (Array.isArray(data)) {
+            const map = {};
+            for (const bp of data) {
+                const file = bp.file;
+                if (file && bp.line) {
+                    if (!map[file]) {
+                        map[file] = [];
+                    }
+                    map[file].push({
+                        file,
+                        line: bp.line,
+                        condition: bp.condition,
+                        logMessage: bp.logMessage,
+                    });
+                }
+            }
+            return map;
+        }
+        // Handle legacy format: { "example.ts": [10, 15] }
+        // Convert to rich breakpoint format
+        const legacy = data;
+        const map = {};
+        for (const [file, lines] of Object.entries(legacy)) {
+            if (Array.isArray(lines)) {
+                map[file] = lines.map(line => ({
+                    file,
+                    line: typeof line === 'number' ? line : line.line,
+                    condition: typeof line === 'object' ? line.condition : undefined,
+                    logMessage: typeof line === 'object' ? line.logMessage : undefined,
+                }));
+            }
+        }
+        return map;
+    }
+    catch (error) {
+        console.warn(`Warning: Failed to parse ${breakpointsPath}: ${error}`);
+        return undefined;
+    }
+}
+/**
+ * Get rich breakpoints for a specific file from the BreakpointMap.
+ *
+ * @param breakpoints The breakpoint map
+ * @param fileName The file path to look up
+ * @returns Array of RichBreakpoint objects for the file
+ */
+export function getBreakpointsForFile(breakpoints, fileName) {
+    // Try exact match first
+    if (breakpoints[fileName]) {
+        return breakpoints[fileName];
+    }
+    // Try basename match
+    const basename = path.basename(fileName);
+    if (breakpoints[basename]) {
+        return breakpoints[basename];
+    }
+    // Try matching against any key that ends with the filename
+    for (const key of Object.keys(breakpoints)) {
+        if (key.endsWith(basename) || fileName.endsWith(key)) {
+            return breakpoints[key];
+        }
+    }
+    return [];
+}

package/dist/debug/index.d.ts

@@ -0,0 +1,3 @@
+export { loadBreakpoints, getBreakpointsForFile, CUTTLEFISH_DIR, BREAKPOINTS_FILE } from './breakpoint-loader.js';
+export { preprocess } from './preprocessor.js';
+export type { BreakpointMap, CapturedVariable } from './types.js';

package/dist/debug/index.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// @typecad/debug — Debug Module
+//
+// Provides breakpoint-based debugging for TypeCAD embedded projects.
+// ---------------------------------------------------------------------------
+export { loadBreakpoints, getBreakpointsForFile, CUTTLEFISH_DIR, BREAKPOINTS_FILE } from './breakpoint-loader.js';
+export { preprocess } from './preprocessor.js';

package/dist/debug/preprocessor.d.ts

@@ -0,0 +1,9 @@
+import type { BreakpointMap } from './types.js';
+export declare function preprocess(options: {
+    /** The source file path (for line number calculation) */
+    fileName: string;
+    /** The breakpoint map loaded from .cuttlefish/breakpoints.json */
+    breakpoints: BreakpointMap;
+    /** The source text to transform */
+    source: string;
+}): string;

package/dist/debug/preprocessor.js

@@ -0,0 +1,214 @@
+// ---------------------------------------------------------------------------
+// @typecad/debug — Debug Preprocessor
+//
+// Transforms TypeScript source by injecting debug code at breakpoint locations.
+// The injected code is generated by the loaded framework's strategy
+// (e.g., Serial.println for Arduino, std::cout for generic targets).
+// ---------------------------------------------------------------------------
+import ts from 'typescript';
+import path from 'node:path';
+import { getBreakpointsForFile } from './breakpoint-loader.js';
+import { getLoadedFramework, hasLoadedFramework } from '../framework-registry.js';
+import { GenericStrategy } from '../platform/generic-strategy.js';
+function getDebugStrategy() {
+    if (hasLoadedFramework()) {
+        const { strategy } = getLoadedFramework();
+        if (strategy.generateDebugInitCode)
+            return strategy;
+    }
+    // Fall back to the generic strategy's std::cout-based debug output
+    return new GenericStrategy();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function preprocess(options) {
+    const { fileName, breakpoints, source } = options;
+    const breakpointLines = getBreakpointsForFile(breakpoints, fileName);
+    if (breakpointLines.length === 0) {
+        return source; // No breakpoints, return unchanged
+    }
+    const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const lines = source.split('\n');
+    const outputLines = [];
+    const relativeFileName = path.basename(fileName);
+    // Create a map of line number (0-indexed) to breakpoint
+    const breakpointMap = new Map();
+    for (const bp of breakpointLines) {
+        breakpointMap.set(bp.line - 1, bp);
+    }
+    // Collect variables in scope at each breakpoint
+    const scopeAnalyzer = new ScopeAnalyzer(sf);
+    const debugStrategy = getDebugStrategy();
+    // Find the first non-import, non-comment line to insert debug init
+    let insertIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        // Skip import statements and comments
+        if (trimmed.startsWith('import ') || trimmed.startsWith('//') || trimmed === '') {
+            insertIndex = i + 1;
+        }
+        else {
+            break;
+        }
+    }
+    // Process each line
+    for (let i = 0; i < lines.length; i++) {
+        // Insert debug init after imports, before first actual code
+        if (i === insertIndex) {
+            const initLines = debugStrategy.generateDebugInitCode?.() ?? [];
+            outputLines.push(...initLines);
+        }
+        const lineNum = i; // 0-indexed
+        const lineText = lines[i];
+        const bp = breakpointMap.get(lineNum);
+        if (bp) {
+            // Get the original line content (trimmed, for display)
+            const displayLine = lineText.trim();
+            // Collect variables in scope at this line
+            const vars = scopeAnalyzer.getVariablesInScope(lineNum);
+            // Inject debug code BEFORE the breakpoint line
+            outputLines.push(...generateBreakpointCode(relativeFileName, lineNum + 1, displayLine, vars, bp, debugStrategy));
+        }
+        // Always include the original line
+        outputLines.push(lineText);
+    }
+    // If all lines were imports/comments, append at end
+    if (insertIndex >= lines.length) {
+        const initLines = debugStrategy.generateDebugInitCode?.() ?? [];
+        outputLines.push(...initLines);
+    }
+    return outputLines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Internal — Breakpoint Code Generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate debug code for a breakpoint.
+ * Delegates to the loaded strategy when available.
+ */
+function generateBreakpointCode(fileName, lineNum, originalLine, variables, bp, debugStrategy) {
+    // If this is a logpoint (has logMessage), generate log-only code
+    if (bp.logMessage) {
+        const parts = parseLogMessage(bp.logMessage);
+        if (debugStrategy.generateDebugLogpointCode) {
+            return debugStrategy.generateDebugLogpointCode({
+                fileName, lineNum, parts,
+                variables: variables.map(v => ({ name: v.name, isFunction: v.isFunction })),
+            });
+        }
+        return [];
+    }
+    // Normalize condition for C++ (convert === to ==, strip semicolons, etc.)
+    const normalizedCondition = bp.condition ? normalizeCondition(bp.condition) : undefined;
+    if (debugStrategy.generateDebugBreakpointCode) {
+        return debugStrategy.generateDebugBreakpointCode({
+            fileName, lineNum, originalLine,
+            variables: variables.map(v => ({ name: v.name, isFunction: v.isFunction })),
+            normalizedCondition,
+        });
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Internal — Log message parsing
+// ---------------------------------------------------------------------------
+function parseLogMessage(message) {
+    const parts = [];
+    let current = '';
+    let i = 0;
+    while (i < message.length) {
+        if (message[i] === '{') {
+            if (current) {
+                parts.push({ type: 'text', value: current });
+                current = '';
+            }
+            let varName = '';
+            i++;
+            while (i < message.length && message[i] !== '}') {
+                varName += message[i];
+                i++;
+            }
+            i++;
+            parts.push({ type: 'variable', value: varName.trim() });
+        }
+        else {
+            current += message[i];
+            i++;
+        }
+    }
+    if (current) {
+        parts.push({ type: 'text', value: current });
+    }
+    return parts;
+}
+function normalizeCondition(condition) {
+    return condition
+        .replace(/;+$/, '')
+        .replace(/===/g, '==')
+        .replace(/!==/g, '!=')
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// Internal — Scope Analysis
+// ---------------------------------------------------------------------------
+class ScopeAnalyzer {
+    constructor(sf) {
+        this.functionVars = new Map();
+        this.sf = sf;
+        this.analyze();
+    }
+    getVariablesInScope(line) {
+        if (this.functionVars.has(line)) {
+            return this.functionVars.get(line);
+        }
+        return this.functionVars.get(-1) || [];
+    }
+    analyze() {
+        const topLevelVars = [];
+        this.collectVariables(this.sf, topLevelVars);
+        this.functionVars.set(-1, topLevelVars);
+        const visit = (node, currentVars) => {
+            if (ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)) {
+                const startLine = this.sf.getLineAndCharacterOfPosition(node.getStart()).line;
+                const endLine = node.body
+                    ? this.sf.getLineAndCharacterOfPosition(node.body.getEnd()).line
+                    : startLine;
+                const localVars = [...currentVars];
+                for (const param of node.parameters) {
+                    if (ts.isIdentifier(param.name)) {
+                        localVars.push({ name: param.name.text });
+                    }
+                }
+                if (node.body) {
+                    this.collectVariables(node.body, localVars);
+                }
+                for (let line = startLine; line <= endLine; line++) {
+                    this.functionVars.set(line, localVars);
+                }
+                return localVars;
+            }
+            ts.forEachChild(node, child => visit(child, currentVars));
+            return currentVars;
+        };
+        visit(this.sf, topLevelVars);
+    }
+    collectVariables(node, vars) {
+        if (ts.isVariableStatement(node)) {
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name)) {
+                    const isFunction = decl.initializer !== undefined && this.isFunctionExpression(decl.initializer);
+                    vars.push({ name: decl.name.text, isFunction });
+                }
+            }
+        }
+        ts.forEachChild(node, child => {
+            if (!ts.isFunctionDeclaration(child) && !ts.isArrowFunction(child) && !ts.isMethodDeclaration(child)) {
+                this.collectVariables(child, vars);
+            }
+        });
+    }
+    isFunctionExpression(expr) {
+        return ts.isArrowFunction(expr) || ts.isFunctionExpression(expr);
+    }
+}

package/dist/debug/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A captured variable at a breakpoint.
+ */
+export interface CapturedVariable {
+    /** Variable name */
+    name: string;
+    /** Whether this is a function (cannot print value) */
+    isFunction?: boolean;
+}
+/**
+ * A rich breakpoint with optional condition and log message.
+ */
+export interface RichBreakpoint {
+    /** Source file path (relative or absolute) */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Optional condition expression (e.g., "counter > 5") */
+    condition?: string;
+    /** Optional log message with {variable} interpolation (e.g., "counter = {counter}") */
+    logMessage?: string;
+}
+/**
+ * Map of file paths to arrays of rich breakpoints.
+ * Loaded from .cuttlefish/breakpoints.json.
+ */
+export type BreakpointMap = Record<string, RichBreakpoint[]>;
+/**
+ * Legacy breakpoint map format (just line numbers).
+ * Used for backward compatibility.
+ */
+export type LegacyBreakpointMap = Record<string, number[]>;

package/dist/debug/types.js

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// @typecad/debug — Debug Types
+//
+// Type definitions for the TypeCAD debugger breakpoint system.
+// ---------------------------------------------------------------------------
+export {};

package/dist/diagnostics/diagnostics-report.d.ts

@@ -0,0 +1,51 @@
+import type { ProgramIR } from "../api/index.js";
+import type { Diagnostic } from "../types.js";
+import type { DiagnosticsReport } from "./json-schema.js";
+export interface DiagnosticsReportInput {
+    /** Entry TypeScript source file path */
+    entryFile: string;
+    /** Program IR for the entry module (after tree-shaking) */
+    program: ProgramIR | null;
+    /** All diagnostics collected during transpilation */
+    diagnostics: Diagnostic[];
+    /** Async task names discovered */
+    asyncTaskNames: string[];
+    /** Whether timers (millis/micros) are used */
+    usesTimers: boolean;
+    /** Target architecture (e.g. "avr", "esp32") */
+    target: string;
+    /** Board package name */
+    boardPackage?: string;
+    /** Framework package name */
+    frameworkPackage?: string;
+    /** Build target identifier */
+    buildTarget?: string;
+    /** Output directory for generated files */
+    outDir?: string;
+    /** Output file path (relative or absolute) */
+    outputFile?: string;
+    /** Pre-build compiled modules (for module graph) */
+    preBuilt?: Map<string, any>;
+    /** Source map entries */
+    sourceMaps?: any[];
+    /** Profiler timing data */
+    profiler?: {
+        getTimings?: () => Record<string, number>;
+    };
+    /** Tree-shaking removed symbols */
+    removedSymbols?: string[];
+    /** Board pins from board constants */
+    boardPins?: Array<{
+        name: string;
+        aliases: string[];
+        number: number;
+    }>;
+}
+/**
+ * Build the complete DiagnosticsReport from transpile pipeline data.
+ */
+export declare function buildDiagnosticsReport(input: DiagnosticsReportInput): DiagnosticsReport;
+/**
+ * Write diagnostics.md to the output directory.
+ */
+export declare function writeDiagnosticsReport(report: DiagnosticsReport, program: ProgramIR | null, outDir: string): void;