@typecad/cuttlefish 0.1.0-alpha.1

package/dist/diagnostics/diagnostics-report.js

@@ -0,0 +1,333 @@
+// ---------------------------------------------------------------------------
+// Diagnostics Report Orchestrator
+//
+// Collects all available build data and generates:
+//   1. diagnostics.md  — human-readable report with Mermaid diagrams
+//   2. diagnostics.json — machine-readable structured data
+//
+// Note: Source maps and transpile diagnostics are EXCLUDED from the
+// Markdown report per user spec. The JSON report includes everything.
+// ---------------------------------------------------------------------------
+import * as path from "path";
+import * as fs from "fs";
+import { analyzeHeapUsage } from "../ir/heap-analysis.js";
+import { buildCallGraph } from "../ir/call-graph.js";
+import { generateMarkdownReport } from "./md-writer.js";
+import { inferGpioMode } from "./json-schema.js";
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function getBoardPinsFromConstants(program) {
+    if (!program?.boardConstants)
+        return [];
+    const pins = [];
+    // Iterate through pins.all.X.name until we find all pins
+    for (let i = 0; i < 100; i++) {
+        const name = program.boardConstants.get(`pins.all.${i}.name`);
+        if (typeof name !== "string")
+            break;
+        const numRaw = program.boardConstants.get(`pins.all.${i}.number`);
+        const num = typeof numRaw === "number" ? numRaw : i;
+        const aliasesRaw = program.boardConstants.get(`pins.all.${i}.aliases`);
+        const aliases = typeof aliasesRaw === "string" ? aliasesRaw.split(",") : [];
+        pins.push({ name, number: num, aliases });
+    }
+    return pins;
+}
+// ── Execution Flow Builder ──────────────────────────────────────────────────
+function buildExecutionFlow(program, callGraph, asyncTaskNames, usesTimers) {
+    // Determine entry points
+    const entryPoints = [];
+    if (callGraph.nodes.has("setup"))
+        entryPoints.push("setup");
+    if (callGraph.nodes.has("loop"))
+        entryPoints.push("loop");
+    // If "main" or other standard entry is present add it
+    for (const name of callGraph.nodes.keys()) {
+        if (name !== "setup" &&
+            name !== "loop" &&
+            name !== "__top_level__" &&
+            name.startsWith("main")) {
+            entryPoints.push(name);
+        }
+    }
+    // Detect ISR handlers
+    const isrHandlers = [];
+    if (program) {
+        // Detect ISR handlers: functions referenced by attachInterrupt or HAL ISR registration
+        for (const fn of program.functions) {
+            // Check if this function appears as a callback in HAL interrupt registration
+            // in __top_level__ or setup statements (handled by existing transpiler diagnostics)
+            // Heuristic: functions named with "isr", "handler", or attached to interrupts
+            const lowerName = fn.originalName.toLowerCase();
+            if (lowerName.includes("isr") || lowerName.includes("handler") || lowerName.includes("interrupt")) {
+                isrHandlers.push(fn.originalName);
+            }
+        }
+    }
+    // Serialize call graph nodes for JSON
+    const serializedNodes = {};
+    for (const [name, node] of callGraph.nodes) {
+        serializedNodes[name] = {
+            name: node.name,
+            kind: node.kind,
+            dependencies: [...node.dependencies],
+            source: node.source ? { line: node.source.line, column: node.source.column } : undefined,
+        };
+    }
+    const serializedReferencedBy = {};
+    for (const [name, refs] of callGraph.referencedBy) {
+        serializedReferencedBy[name] = [...refs];
+    }
+    return {
+        callGraph: {
+            nodes: serializedNodes,
+            referencedBy: serializedReferencedBy,
+        },
+        entryPoints,
+        isrHandlers,
+        asyncTaskNames,
+        usesTimers,
+    };
+}
+// ── Pin Usage Builder ──────────────────────────────────────────────────────
+function buildPinUsage(program, boardPinsData) {
+    const gpio = [];
+    const peripherals = [];
+    if (!program?.peripheralUsage) {
+        return {
+            gpio: [],
+            peripherals: [],
+            summary: { totalPins: boardPinsData.length, usedPins: 0, unusedPins: boardPinsData.length },
+        };
+    }
+    const usage = program.peripheralUsage;
+    // Map board pins to GPIO entries
+    for (const pin of boardPinsData) {
+        // Only include pins that are explicitly used in the sketch to keep the table clean
+        const isExplicitlyUsed = usage.pinsUsed.has(pin.name) ||
+            pin.aliases.some(a => usage.pinsUsed.has(a)) ||
+            (pin.number !== undefined && (usage.outputPins.has(pin.number) ||
+                usage.inputPins.has(pin.number) ||
+                usage.inputPullupPins.has(pin.number) ||
+                usage.inputPulldownPins.has(pin.number) ||
+                usage.pwmPinsUsed.has(pin.number) ||
+                usage.interruptPinsUsed.has(pin.number)));
+        if (isExplicitlyUsed) {
+            const mode = inferGpioMode(usage, pin.name, pin.number);
+            gpio.push({
+                pinName: pin.name,
+                pinNumber: pin.number,
+                mode,
+            });
+        }
+    }
+    // Build peripheral allocations — PeripheralUsageIR only has boolean flags
+    if (usage.i2c) {
+        peripherals.push({
+            type: "i2c",
+            instance: 0,
+            displayName: "I2C",
+            pins: [],
+        });
+    }
+    if (usage.spi) {
+        peripherals.push({
+            type: "spi",
+            instance: 0,
+            displayName: "SPI",
+            pins: [],
+        });
+    }
+    if (usage.uart) {
+        peripherals.push({
+            type: "uart",
+            instance: 0,
+            displayName: "Serial",
+            pins: [],
+        });
+    }
+    if (usage.adc) {
+        peripherals.push({
+            type: "adc",
+            instance: 0,
+            displayName: "ADC",
+            pins: [...usage.adcChannelsUsed].map((ch) => `A${ch}`),
+        });
+    }
+    if (usage.pwm) {
+        peripherals.push({
+            type: "pwm",
+            instance: 0,
+            displayName: "PWM",
+            pins: [...usage.pwmPinsUsed].map((n) => `D${n}`),
+        });
+    }
+    if (usage.timer0) {
+        peripherals.push({
+            type: "timer",
+            instance: 0,
+            displayName: "Timer0 (millis/micros)",
+            pins: [],
+        });
+    }
+    if (usage.externalInterrupts) {
+        peripherals.push({
+            type: "interrupt",
+            instance: 0,
+            displayName: "External Interrupts",
+            pins: [...usage.interruptPinsUsed].map((n) => `D${n}`),
+        });
+    }
+    const usedPins = gpio.filter((p) => p.mode !== "INPUT").length;
+    return {
+        gpio,
+        peripherals,
+        summary: {
+            totalPins: boardPinsData.length,
+            usedPins,
+            unusedPins: boardPinsData.length - usedPins,
+        },
+    };
+}
+// ── Peripheral Conflicts Builder ───────────────────────────────────────────
+function buildPeripheralConflicts(_program) {
+    // This would normally call analyzeResourceConflicts() from resource-analysis.ts
+    // For now, return an empty array — the resource analysis is already run
+    // independently during transpile and its diagnostics are in the Diagnostic array.
+    // We could also import analyzeResourceConflicts directly here, but it requires
+    // BoardConstants which we may or may not have access to.
+    return [];
+}
+// ── Async Tasks Builder ────────────────────────────────────────────────────
+function buildAsyncTasks(asyncTaskNames) {
+    return asyncTaskNames.map((name) => ({
+        name,
+        // intervalMs is unknown without JSDoc annotation parsing (future enhancement)
+        intervalMs: undefined,
+    }));
+}
+// ── Module Graph Builder ───────────────────────────────────────────────────
+function buildModuleGraph(program, preBuilt) {
+    const nodes = new Set();
+    const edges = [];
+    if (program) {
+        const fromName = path.basename(program.fileName);
+        nodes.add(fromName);
+        for (const imp of program.imports) {
+            const toName = imp.moduleSpecifier;
+            nodes.add(toName);
+            edges.push({ from: fromName, to: toName });
+        }
+    }
+    if (preBuilt) {
+        for (const [fullPath] of preBuilt) {
+            const baseName = path.basename(fullPath);
+            nodes.add(baseName);
+        }
+    }
+    return { nodes: [...nodes], edges };
+}
+// ── Tree Shaking Report Builder ────────────────────────────────────────────
+function buildTreeShakingReport(removedSymbols) {
+    return {
+        removedSymbols: removedSymbols ?? [],
+    };
+}
+// ── Build Timing Builder ────────────────────────────────────────────────────
+function buildTimingReport(profiler) {
+    const phases = profiler?.getTimings?.() ?? {};
+    const values = Object.values(phases);
+    const totalMs = values.reduce((sum, v) => sum + v, 0);
+    return { phases, totalMs };
+}
+// ── Main Report Builder ────────────────────────────────────────────────────
+/**
+ * Build the complete DiagnosticsReport from transpile pipeline data.
+ */
+export function buildDiagnosticsReport(input) {
+    const program = input.program;
+    const boardPinsData = input.boardPins ?? getBoardPinsFromConstants(program);
+    // Build call graph
+    const callGraph = program ? buildCallGraph(program) : { nodes: new Map(), referencedBy: new Map() };
+    const executionFlow = buildExecutionFlow(program, callGraph, input.asyncTaskNames, input.usesTimers);
+    const pinUsage = buildPinUsage(program, boardPinsData);
+    const peripheralConflicts = buildPeripheralConflicts(program);
+    const asyncTasks = buildAsyncTasks(input.asyncTaskNames);
+    const heapEstimate = analyzeHeapUsage(program, input.target, callGraph.nodes);
+    const moduleGraph = buildModuleGraph(program, input.preBuilt);
+    const treeShaking = buildTreeShakingReport(input.removedSymbols);
+    const timing = buildTimingReport(input.profiler);
+    return {
+        metadata: {
+            timestamp: new Date().toISOString(),
+            sourceFile: path.basename(input.entryFile),
+            target: input.target,
+            board: input.boardPackage,
+            framework: input.frameworkPackage,
+            buildTarget: input.buildTarget,
+            outputFile: input.outputFile ?? path.basename(input.entryFile, path.extname(input.entryFile)) + ".ino",
+            boardDetails: program?.boardConstants ? {
+                mcu: program.boardConstants.get("mcu"),
+                architecture: program.boardConstants.get("architecture"),
+                flashKb: program.boardConstants.get("memory.flash") / 1024,
+                sramKb: program.boardConstants.get("memory.sram") / 1024,
+                clockSpeedMhz: program.boardConstants.get("clockSpeed") / 1000000,
+            } : undefined,
+        },
+        executionFlow,
+        pinUsage,
+        asyncTasks,
+        heapEstimate,
+        peripheralConflicts,
+        moduleGraph,
+        treeShaking,
+        sourceMaps: input.sourceMaps,
+        buildTiming: timing,
+        transpileDiagnostics: input.diagnostics.length > 0 ? input.diagnostics : undefined,
+    };
+}
+// ── File Writers ────────────────────────────────────────────────────────────
+/**
+ * Write diagnostics.md to the output directory.
+ */
+export function writeDiagnosticsReport(report, program, outDir) {
+    const callGraph = program ? buildCallGraph(program) : { nodes: new Map(), referencedBy: new Map() };
+    // Ensure output directory exists
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    // Write Markdown report
+    const mdPath = path.join(outDir, "diagnostics.md");
+    const mdContent = generateMarkdownReport(report, callGraph);
+    fs.writeFileSync(mdPath, mdContent, "utf-8");
+    // Write JSON report (includes everything)
+    const jsonPath = path.join(outDir, "diagnostics.json");
+    // Convert Sets to arrays for JSON serialization
+    const jsonReport = serializeForJson(report);
+    fs.writeFileSync(jsonPath, JSON.stringify(jsonReport, null, 2), "utf-8");
+}
+/**
+ * Recursively convert Set objects to arrays for JSON serialization.
+ */
+function serializeForJson(obj) {
+    if (obj instanceof Set) {
+        return [...obj];
+    }
+    if (obj instanceof Map) {
+        const result = {};
+        for (const [k, v] of obj) {
+            result[k] = serializeForJson(v);
+        }
+        return result;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(serializeForJson);
+    }
+    if (obj !== null && typeof obj === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = serializeForJson(v);
+        }
+        return result;
+    }
+    return obj;
+}

package/dist/diagnostics/json-schema.d.ts

@@ -0,0 +1,138 @@
+import type { PeripheralUsageIR } from "../api/index.js";
+import type { Diagnostic, SourceSpan } from "../types.js";
+export interface GpioPinEntry {
+    pinName: string;
+    pinNumber?: number;
+    mode: "OUTPUT" | "INPUT" | "INPUT_PULLUP" | "INPUT_PULLDOWN" | "ANALOG" | "PWM";
+    /** If this pin is also allocated to a peripheral, list the peripheral name */
+    peripheralRole?: string;
+}
+export interface PeripheralAllocation {
+    type: "i2c" | "spi" | "uart" | "adc" | "pwm" | "timer" | "interrupt";
+    instance: number;
+    displayName: string;
+    pins: string[];
+}
+export interface CallGraphNodeEntry {
+    name: string;
+    kind: "function" | "class" | "enum" | "variable" | "type_alias";
+    dependencies: string[];
+    source?: {
+        line: number;
+        column: number;
+    };
+}
+export interface ExecutionFlow {
+    callGraph: {
+        nodes: Record<string, CallGraphNodeEntry>;
+        referencedBy: Record<string, string[]>;
+    };
+    entryPoints: string[];
+    /** Functions that are ISR handlers (attached via attachInterrupt or similar) */
+    isrHandlers: string[];
+    /** Async task names discovered during transpilation */
+    asyncTaskNames: string[];
+    /** Whether millis/micros timer is engaged */
+    usesTimers: boolean;
+}
+export interface AsyncTaskEntry {
+    name: string;
+    /** If a JSDoc @interval annotation was found */
+    intervalMs?: number;
+}
+export interface HeapEstimate {
+    globalVariables: {
+        name: string;
+        cppType: string;
+        estimatedBytes: number;
+    }[];
+    structSizes: Record<string, number>;
+    stringLiterals: {
+        value: string;
+        estimatedBytes: number;
+    }[];
+    totalStaticBytes: number;
+    /** Approximate stack depth derived from call graph maximum path length */
+    estimatedStackDepth: number;
+    /** The deepest call paths discovered during analysis */
+    stackPaths: string[][];
+    notes: string[];
+}
+export interface PeripheralConflictEntry {
+    pinName: string;
+    peripheralName: string;
+    role: string;
+    severity: "error" | "warning";
+    message: string;
+    suggestion: string;
+    sourceSpan?: SourceSpan;
+}
+export interface ModuleGraph {
+    nodes: string[];
+    edges: {
+        from: string;
+        to: string;
+    }[];
+}
+export interface TreeShakingReport {
+    removedSymbols: string[];
+}
+export interface SourceMapEntry {
+    generatedStartLine: number;
+    generatedStartColumn: number;
+    generatedEndLine: number;
+    generatedEndColumn: number;
+    tsSpan: SourceSpan;
+    nodeKind: string;
+    symbolName?: string;
+}
+export interface BuildTiming {
+    phases: Record<string, number>;
+    totalMs: number;
+}
+export interface DiagnosticsReport {
+    metadata: {
+        timestamp: string;
+        sourceFile: string;
+        target: string;
+        board?: string;
+        framework?: string;
+        buildTarget?: string;
+        outputFile: string;
+        boardDetails?: {
+            mcu?: string;
+            architecture?: string;
+            flashKb?: number;
+            sramKb?: number;
+            clockSpeedMhz?: number;
+        };
+    };
+    executionFlow: ExecutionFlow;
+    pinUsage: {
+        gpio: GpioPinEntry[];
+        peripherals: PeripheralAllocation[];
+        summary: {
+            totalPins: number;
+            usedPins: number;
+            unusedPins: number;
+        };
+    };
+    asyncTasks: AsyncTaskEntry[];
+    heapEstimate: HeapEstimate;
+    peripheralConflicts: PeripheralConflictEntry[];
+    /** Available in JSON only — excluded from Markdown per user request */
+    moduleGraph?: ModuleGraph;
+    /** Available in JSON only */
+    treeShaking?: TreeShakingReport;
+    /** Available in JSON only */
+    sourceMaps?: SourceMapEntry[];
+    /** Available in JSON only */
+    buildTiming?: BuildTiming;
+    /** Available in JSON only */
+    transpileDiagnostics?: Diagnostic[];
+}
+/**
+ * Infer the GPIO mode for a pin based on peripheral usage data.
+ * Uses PeripheralUsageIR from core (the type available at runtime).
+ */
+export declare function inferGpioMode(usage: PeripheralUsageIR, _pinName: string, pinNumber: number | undefined): GpioPinEntry["mode"];

package/dist/diagnostics/json-schema.js

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// Diagnostics Report — JSON Schema Types
+// ---------------------------------------------------------------------------
+// ── Pin Role Inference ─────────────────────────────────────────────────────
+/**
+ * Infer the GPIO mode for a pin based on peripheral usage data.
+ * Uses PeripheralUsageIR from core (the type available at runtime).
+ */
+export function inferGpioMode(usage, _pinName, pinNumber) {
+    if (pinNumber !== undefined) {
+        if (usage.pwmPinsUsed.has(pinNumber))
+            return "PWM";
+        if (usage.adcChannelsUsed.has(pinNumber))
+            return "ANALOG";
+        if (usage.interruptPinsUsed.has(pinNumber))
+            return "INPUT_PULLUP";
+        if (usage.outputPins.has(pinNumber))
+            return "OUTPUT";
+        if (usage.inputPullupPins.has(pinNumber))
+            return "INPUT_PULLUP";
+        if (usage.inputPulldownPins.has(pinNumber))
+            return "INPUT_PULLDOWN";
+        if (usage.inputPins.has(pinNumber))
+            return "INPUT";
+    }
+    return "INPUT";
+}

package/dist/diagnostics/md-writer.d.ts

@@ -0,0 +1,10 @@
+import type { CallGraph } from "../ir/call-graph.js";
+import type { DiagnosticsReport } from "./json-schema.js";
+/**
+ * Generate the complete diagnostics.md report as a string.
+ *
+ * @param report - The full diagnostics report with all data populated.
+ * @param callGraph - The raw CallGraph (Map-based) for Mermaid node walk.
+ * @returns The complete Markdown string ready to write to disk.
+ */
+export declare function generateMarkdownReport(report: DiagnosticsReport, callGraph: CallGraph): string;