@typecad/cuttlefish 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/ir/worker-analysis.js

@@ -0,0 +1,261 @@
+// ---------------------------------------------------------------------------
+// Worker Isolation Analysis (Phase 1/2)
+//
+// Models the safety property of the generalized worker-offload feature: worker
+// functions run on a separate thread of control (a FreeRTOS task / Zephyr
+// workqueue thread), so any shared mutable state between a worker and the main
+// loop() is a real data race that the cooperative model otherwise eliminates.
+//
+// This pass mirrors interrupt-analysis.ts but splits the verdict by the surface
+// a worker shares with main:
+//
+//   (a) Shared GLOBALS — the worker writes a global the main loop reads (or
+//       both write it). The worker can run on a different core, so:
+//         - worker-written + main-read  → promote to volatile + info diagnostic
+//           (mirrors the ISR volatile pass; the barrier contract makes the
+//           write visible, volatile stops the compiler caching the read).
+//         - worker-written + main-written (mutated by both) → warning:
+//           a true data race the barrier alone cannot fix.
+//
+//   (b) Shared BUSES (I2C/SPI/UART/Wire/Serial) — a worker touching a bus is a
+//       HARD ERROR in v1. Rationale: the existing take()/release() bus-ownership
+//       mechanism is statically enforced (peripheral-ownership.ts) but runtime-
+//       UNIMPLEMENTED (take() is a no-op). A bus is a protocol-level conflict
+//       (two masters on the wire), so leaning on a lock that isn't there would
+//       be unsound. Workers are compute/pure-only in v1. When the take/release
+//       runtime backend lands (the named follow-on), this tier flips from
+//       error → allowed-by-take/release.
+//
+// Worker function identification: a worker function is one referenced by a
+// worker.submit HAL op (expr.operation.operation === 'worker.submit'). The op
+// carries fnRef (the C++ symbol), which we correlate to a program function by
+// name. This mirrors how interrupt-analysis identifies ISRs via
+// isInterruptHandler, but resolves through the HAL op instead of a callback
+// flag (worker functions are plain functions, not callbacks).
+// ---------------------------------------------------------------------------
+import { collectAssignedNames, collectReadNames } from './interrupt-analysis.js';
+import { walkProgramIR } from './utils/walk-ir.js';
+// Bus-object prefixes a worker is forbidden from touching in v1. Mirrors the
+// getBusName regex in peripheral-ownership.ts (I2C/SPI/UART/Wire/Serial).
+const BUS_PREFIXES = ['I2C', 'SPI', 'UART', 'Wire', 'Serial'];
+/** True if an identifier/callee string names a bus object (forbidden in workers). */
+function isBusName(name) {
+    // Wire / Serial exactly, or I2C<n> / SPI<n> / UART<n> / Serial<n>.
+    if (name === 'Wire' || name === 'Serial')
+        return true;
+    for (const p of ['I2C', 'SPI', 'UART']) {
+        if (new RegExp(`^${p}\\d`).test(name))
+            return true;
+    }
+    if (/^Serial\d/.test(name))
+        return true;
+    return false;
+}
+/**
+ * Walk every expression in the program, invoking the visitor for worker.submit
+ * HAL ops. HAL ops appear as expressions whose `.operation.operation` is the
+ * op-kind string (mirrors the scan in program-analysis.ts:348).
+ */
+function scanForWorkerSubmitOps(program, visit) {
+    walkProgramIR(program, (stmt) => {
+        walkExpressionsInStatementLocal(stmt, (expr) => {
+            if (expr && typeof expr === 'object'
+                && expr.operation && typeof expr.operation === 'object'
+                && expr.operation.operation === 'worker.submit') {
+                const fnRef = expr.operation.fnRef;
+                if (typeof fnRef === 'string')
+                    visit(fnRef, expr.sourceSpan ?? expr.operation.sourceSpan);
+            }
+        });
+    });
+}
+/** Collect the set of bus object names referenced (read/called) in a body. */
+function collectBusAccesses(stmts, hits) {
+    for (const stmt of stmts) {
+        collectBusAccessesInStatement(stmt, hits);
+        const nested = getNestedStatements(stmt);
+        if (nested)
+            collectBusAccesses(nested, hits);
+    }
+}
+function collectBusAccessesInStatement(stmt, hits) {
+    const s = stmt;
+    // Method calls like Wire.begin() / I2C0.writeByte(...): callee is "Wire.begin".
+    if (s.callee && typeof s.callee === 'string') {
+        const base = s.callee.split('.')[0];
+        if (isBusName(base))
+            hits.push({ name: base, span: s.sourceSpan });
+    }
+    // Identifier references (Wire, Serial, I2C0 used bare).
+    const visit = (expr) => {
+        if (expr && typeof expr === 'object' && expr.kind === 'identifier' && typeof expr.value === 'string') {
+            if (isBusName(expr.value))
+                hits.push({ name: expr.value, span: expr.sourceSpan });
+        }
+    };
+    walkExpressionsInStatementLocal(stmt, visit);
+}
+function walkExpressionsInStatementLocal(stmt, visitor) {
+    const s = stmt;
+    if (s.initializer && typeof s.initializer === 'object')
+        walkExpressionsInExpressionLocal(s.initializer, visitor);
+    if (s.value && typeof s.value === 'object' && 'kind' in s.value)
+        walkExpressionsInExpressionLocal(s.value, visitor);
+    if (s.condition && typeof s.condition === 'object')
+        walkExpressionsInExpressionLocal(s.condition, visitor);
+    if (s.expression && typeof s.expression === 'object' && 'kind' in s.expression)
+        walkExpressionsInExpressionLocal(s.expression, visitor);
+    if (Array.isArray(s.args))
+        for (const a of s.args)
+            walkExpressionsInExpressionLocal(a, visitor);
+    if (s.callee && typeof s.callee === 'object')
+        walkExpressionsInExpressionLocal(s.callee, visitor);
+}
+function walkExpressionsInExpressionLocal(expr, visitor) {
+    if (!expr || typeof expr !== 'object')
+        return;
+    visitor(expr);
+    for (const k of ['left', 'right', 'object', 'property', 'value', 'condition', 'whenTrue', 'whenFalse', 'expression', 'callee', 'target']) {
+        const v = expr[k];
+        if (v && typeof v === 'object' && 'kind' in v)
+            walkExpressionsInExpressionLocal(v, visitor);
+    }
+    if (Array.isArray(expr.args))
+        for (const a of expr.args)
+            walkExpressionsInExpressionLocal(a, visitor);
+    if (Array.isArray(expr.elements))
+        for (const a of expr.elements)
+            walkExpressionsInExpressionLocal(a, visitor);
+}
+function getNestedStatements(stmt) {
+    // Reuse the walk-ir helper if it exposes nesting; otherwise return undefined.
+    const s = stmt;
+    if (Array.isArray(s.body))
+        return s.body;
+    if (Array.isArray(s.statements))
+        return s.statements;
+    if (s.thenBlock && Array.isArray(s.thenBlock.statements))
+        return s.thenBlock.statements;
+    if (s.elseBlock && Array.isArray(s.elseBlock.statements))
+        return s.elseBlock.statements;
+    return undefined;
+}
+/** Find a function in program.functions by name (or originalName). */
+function findFunctionByName(program, name) {
+    return program.functions.find((fn) => fn.name === name || fn.originalName === name);
+}
+/**
+ * Analyze worker isolation: (a) promote volatile for worker-shared globals,
+ * (b) flag shared-mutable globals, (c) hard-error on bus access in workers.
+ *
+ * Mutates the IR for (a) (sets isVolatile=true on qualifying var_decls) and
+ * pushes diagnostics for all three tiers. Returns the diagnostics it added.
+ */
+export function analyzeWorkerIsolation(program, diagnostics) {
+    const added = [];
+    const push = (d) => { diagnostics.push(d); added.push(d); };
+    // 1. Identify worker-submitted functions via worker.submit HAL ops.
+    const workerFnNames = new Set();
+    scanForWorkerSubmitOps(program, (fnRef) => {
+        // fnRef is the C++ symbol; the IR function name is usually the same root.
+        workerFnNames.add(fnRef);
+    });
+    if (workerFnNames.size === 0)
+        return added;
+    // 2. Collect the bodies of worker functions present in this program.
+    const workerBodies = [];
+    for (const name of workerFnNames) {
+        const fn = findFunctionByName(program, name);
+        if (fn && Array.isArray(fn.statements))
+            workerBodies.push(fn.statements);
+    }
+    if (workerBodies.length === 0)
+        return added;
+    // ── Tier (b): bus access in workers → HARD ERROR ────────────────────────
+    for (let i = 0; i < workerFnNames.size; i++) {
+        const name = [...workerFnNames][i];
+        const fn = findFunctionByName(program, name);
+        if (!fn || !Array.isArray(fn.statements))
+            continue;
+        const busHits = [];
+        collectBusAccesses(fn.statements, busHits);
+        for (const hit of busHits) {
+            push({
+                severity: 'error',
+                message: `Worker function '${name}' accesses bus '${hit.name}'. Bus access is forbidden in worker functions because the take()/release() bus-ownership lock is not implemented at runtime — two threads would race on the wire despite validation passing.`,
+                hint: `Keep workers compute/pure-only. Bus-sharing workers require the take()/release() runtime backend (a planned follow-on).`,
+                filePath: (hit.span ?? fn.sourceSpan)?.filePath,
+                line: (hit.span ?? fn.sourceSpan)?.startLine,
+                column: (hit.span ?? fn.sourceSpan)?.startColumn,
+                code: 'worker-bus-access-forbidden',
+                source: 'worker-analysis',
+            });
+        }
+    }
+    // ── Tier (a): shared globals → volatile + warning ───────────────────────
+    const globalVars = new Map();
+    for (const stmt of program.topLevelStatements) {
+        if (stmt.kind === 'var_decl' && typeof stmt.name === 'string') {
+            globalVars.set(stmt.name, stmt);
+        }
+    }
+    if (globalVars.size === 0)
+        return added;
+    // Names assigned inside worker bodies.
+    const workerAssigned = new Set();
+    for (const body of workerBodies)
+        collectAssignedNames(body, workerAssigned);
+    if (workerAssigned.size === 0)
+        return added;
+    // Names assigned AND read in main (non-worker) code.
+    const mainAssigned = new Set();
+    const mainRead = new Set();
+    for (const stmt of program.topLevelStatements) {
+        collectReadNames([stmt], mainRead);
+        collectAssignedNames([stmt], mainAssigned);
+    }
+    for (const fn of program.functions) {
+        // Skip the worker functions themselves when collecting main usage.
+        if (workerFnNames.has(fn.name) || workerFnNames.has(fn.originalName))
+            continue;
+        if (Array.isArray(fn.statements)) {
+            collectReadNames(fn.statements, mainRead);
+            collectAssignedNames(fn.statements, mainAssigned);
+        }
+    }
+    for (const [name, stmt] of globalVars) {
+        if (!workerAssigned.has(name))
+            continue;
+        const workerShared = stmt;
+        if (mainRead.has(name) && !mainAssigned.has(name)) {
+            // worker-written + main-read → promote to volatile (the barrier makes the
+            // write visible; volatile stops the compiler caching the read).
+            if (!workerShared.isVolatile) {
+                workerShared.isVolatile = true;
+                push({
+                    severity: 'info',
+                    message: `'${name}' is written in a worker function and read in main code — emitted as \`volatile\` so the compiler does not cache it in a register across the worker/main boundary.`,
+                    filePath: workerShared.sourceSpan?.filePath,
+                    line: workerShared.sourceSpan?.startLine,
+                    column: workerShared.sourceSpan?.startColumn,
+                    code: 'volatile-worker-shared',
+                    source: 'worker-analysis',
+                });
+            }
+        }
+        else if (mainAssigned.has(name)) {
+            // worker-written + main-written → true data race; barrier alone can't fix.
+            push({
+                severity: 'warning',
+                message: `'${name}' is written by both a worker function and main-thread code — a data race the worker completion barrier alone cannot fix. Restructure so only one side writes it (e.g. the worker writes; main only reads).`,
+                hint: `Move all writes to '${name}' into the worker (or into main); do not mutate it from both.`,
+                filePath: workerShared.sourceSpan?.filePath,
+                line: workerShared.sourceSpan?.startLine,
+                column: workerShared.sourceSpan?.startColumn,
+                code: 'worker-shared-mutable',
+                source: 'worker-analysis',
+            });
+        }
+    }
+    return added;
+}

package/dist/libdef/c-to-decl.d.ts

@@ -0,0 +1,27 @@
+/**
+ * C-header to TypeScript declaration generator.
+ *
+ * Complements cpp-to-decl.ts (which is class-focused). ESP-IDF components
+ * are mostly C: free functions, opaque handles, typedef'd enums and structs.
+ *
+ * EMISSION POLICY — names match the C header 1-to-1.
+ *
+ *   esp_err_t esp_wifi_init(const wifi_config_t *config);
+ *
+ * becomes
+ *
+ *   export declare function esp_wifi_init(config: number): esp_err_t;
+ *
+ * not `esp_wifi.init(...)`. ESP-IDF examples call `esp_wifi_init`, never
+ * `esp_wifi.init`; the dotted form has no C++ representation (there is no
+ * `esp_wifi` object or namespace in the real header) and would not link.
+ * Mirroring the C names verbatim means the transpiler lowers TS calls
+ * directly to valid C with zero translation.
+ *
+ * Spec: docs/superpowers/specs/2026-07-19-demo-wifi-design.md
+ */
+/**
+ * Top-level entry: read a header file, write `<header>.d.ts` alongside it.
+ * Returns the output path, or null if no declarations could be extracted.
+ */
+export declare function generateCDecl(filePath: string, outputPath?: string): string | null;

package/dist/libdef/c-to-decl.js

@@ -0,0 +1,397 @@
+/**
+ * C-header to TypeScript declaration generator.
+ *
+ * Complements cpp-to-decl.ts (which is class-focused). ESP-IDF components
+ * are mostly C: free functions, opaque handles, typedef'd enums and structs.
+ *
+ * EMISSION POLICY — names match the C header 1-to-1.
+ *
+ *   esp_err_t esp_wifi_init(const wifi_config_t *config);
+ *
+ * becomes
+ *
+ *   export declare function esp_wifi_init(config: number): esp_err_t;
+ *
+ * not `esp_wifi.init(...)`. ESP-IDF examples call `esp_wifi_init`, never
+ * `esp_wifi.init`; the dotted form has no C++ representation (there is no
+ * `esp_wifi` object or namespace in the real header) and would not link.
+ * Mirroring the C names verbatim means the transpiler lowers TS calls
+ * directly to valid C with zero translation.
+ *
+ * Spec: docs/superpowers/specs/2026-07-19-demo-wifi-design.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { stripPreprocessorBlocks } from './header-parser.js';
+const BUILTIN_TS_TYPES = new Set(['number', 'string', 'boolean', 'void', 'any']);
+/**
+ * Map a C type string to a TS type string. Pointer types become `number`
+ * (handles/opaque addresses) since the transpiler treats C pointers as
+ * numbers anyway. Unknown named types are returned as-is so they resolve
+ * to a typedef alias emitted by this same header (or fall back to `number`
+ * via the alias-emission pass in generateCDecl).
+ */
+function mapCTypeToTs(cType) {
+    let t = cType.trim();
+    // Strip leading `const`/`volatile` qualifiers — they don't affect the TS shape.
+    t = t.replace(/^(?:const|volatile)\s+/, '');
+    const typeMap = {
+        int: 'number',
+        'unsigned int': 'number',
+        'unsigned': 'number',
+        'short': 'number',
+        'unsigned short': 'number',
+        'long': 'number',
+        'unsigned long': 'number',
+        'long long': 'number',
+        'unsigned long long': 'number',
+        uint8_t: 'number',
+        uint16_t: 'number',
+        uint32_t: 'number',
+        uint64_t: 'number',
+        int8_t: 'number',
+        int16_t: 'number',
+        int32_t: 'number',
+        int64_t: 'number',
+        size_t: 'number',
+        ssize_t: 'number',
+        intptr_t: 'number',
+        uintptr_t: 'number',
+        float: 'number',
+        double: 'number',
+        bool: 'boolean',
+        _Bool: 'boolean',
+        void: 'void',
+        char: 'number',
+    };
+    if (typeMap[t])
+        return typeMap[t];
+    // Strip a trailing pointer; pointers are number-typed handles/addresses.
+    if (t.endsWith('*'))
+        return 'number';
+    return t;
+}
+/** Parse function signatures like `esp_err_t foo(int x, const char *y);`. */
+function parseFunctions(stripped) {
+    const fns = [];
+    const fnRegex = /^([\w\s\*]+?)\s+(\w+)\s*\(([^;]*)\)\s*;/gm;
+    let m;
+    while ((m = fnRegex.exec(stripped)) !== null) {
+        const returnType = m[1].trim();
+        const name = m[2];
+        const paramsRaw = m[3].trim();
+        // Skip non-function declarations these regexes might catch.
+        if (returnType === 'typedef' || returnType === 'struct' || returnType === 'enum')
+            continue;
+        if (returnType === 'static' || returnType === 'extern' || returnType === 'inline')
+            continue;
+        if (name === 'if' || name === 'for' || name === 'while' || name === 'return' || name === 'switch')
+            continue;
+        fns.push({ returnType, name, params: parseParams(paramsRaw) });
+    }
+    return fns;
+}
+function parseParams(raw) {
+    if (!raw || raw === 'void')
+        return [];
+    return raw.split(',').map((part, idx) => {
+        let trimmed = part.trim();
+        trimmed = trimmed.split('=')[0].trim();
+        if (!trimmed)
+            return { type: '', name: `_arg${idx}` };
+        // C array declarator on a parameter: `<type> <name>[<size>]` or `<type> <name>[]`.
+        // Normalize: the array decays to a pointer in C anyway, so we record the
+        // base type and the original name. e.g. `uint8_t mac[6]` → type="uint8_t",
+        // name="mac"; `uint8_t mac[]` → same.
+        const arrParam = trimmed.match(/^(.*?)\b(\w+)\s*\[[^\]]*\]\s*$/);
+        if (arrParam) {
+            const type = arrParam[1].trim();
+            // If the type is empty (e.g. bare `mac[6]` with no preceding type),
+            // fall through to the default parser rather than emitting a bogus type.
+            if (type)
+                return { type, name: arrParam[2] };
+        }
+        // A parameter is `<type> <name>` where name is the trailing identifier
+        // and type is everything before. For function-pointer params (rare in
+        // user-facing IDF APIs) we fall back to treating the whole thing as a
+        // type with a synthesized name.
+        if (trimmed.includes('(*)')) {
+            return { type: trimmed, name: `_arg${idx}` };
+        }
+        const m = trimmed.match(/^(.*?)(\b\w+)$/);
+        if (!m)
+            return { type: trimmed, name: `_arg${idx}` };
+        let type = m[1].trim();
+        const name = m[2];
+        // If the regex left the * glued to the name, pull it back to the type.
+        if (!type && trimmed.includes('*')) {
+            type = '*';
+        }
+        return { type: type || trimmed, name };
+    });
+}
+/** Parse typedef'd enums: `typedef enum { A, B=2, C } foo_t;`. */
+function parseEnumTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+enum\s*(?:\w+\s*)?\{([^}]*)\}\s*(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const body = m[1];
+        const name = m[2];
+        const members = body.split(',').map((s) => s.trim()).filter(Boolean);
+        let next = 0;
+        const values = members.map((mem) => {
+            const eq = mem.indexOf('=');
+            if (eq >= 0) {
+                const val = parseInt(mem.slice(eq + 1).trim(), 10);
+                if (!Number.isNaN(val))
+                    next = val + 1;
+                return { name: mem.slice(0, eq).trim(), value: Number.isNaN(val) ? undefined : val };
+            }
+            const v = next++;
+            return { name: mem, value: v };
+        });
+        tds.push({ kind: 'enum', name, values });
+    }
+    return tds;
+}
+/** Parse typedef'd structs: `typedef struct { int x; } foo_t;` or
+ *  `typedef struct foo { int x; } foo_t;`. Handles array fields
+ *  (`int arr[6]`) by recording the array-ness on the field. */
+function parseStructTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+struct\s*(?:\w+\s*)?\{([^}]*)\}\s*(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const body = m[1];
+        const name = m[2];
+        const fields = body
+            .split(';')
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .map((field, idx) => {
+            // Array field: `<type> <name>[<size>]` → name + isArray.
+            const arr = field.match(/^(.*?)\b(\w+)\s*\[[^\]]*\]\s*$/);
+            if (arr) {
+                return { type: arr[1].trim() || field, name: arr[2], isArray: true };
+            }
+            const pm = field.match(/^(.*?)(\b\w+)$/);
+            if (!pm)
+                return { type: field, name: `_f${idx}`, isArray: false };
+            return { type: pm[1].trim() || field, name: pm[2], isArray: false };
+        });
+        tds.push({ kind: 'struct', name, fields });
+    }
+    return tds;
+}
+/** Parse opaque handle typedefs: `typedef struct foo *foo_handle_t;`. */
+function parseOpaqueTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+struct\s+\w+\s*\*\s*(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        tds.push({ kind: 'opaque', name: m[1] });
+    }
+    return tds;
+}
+/** Parse function-pointer typedefs: `typedef void (*handler_t)(void *arg);`.
+ *  Emits as `any` — TS has no faithful representation of a C function pointer,
+ *  and IDF user code that registers one needs `rawCpp()` anyway. */
+function parseFuncPtrTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+[\w\s\*]+?\(\s*\*\s*(\w+)\s*\)\s*\([^;]*\)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        tds.push({ kind: 'funcptr', name: m[1] });
+    }
+    return tds;
+}
+/** Parse plain alias typedefs: `typedef int esp_err_t;`, `typedef uint32_t foo_t;`.
+ *  These are extremely common in ESP-IDF (esp_err_t, TickType_t, etc.). */
+function parseAliasTypedefs(stripped) {
+    const tds = [];
+    // `typedef <type> <name>;` where <type> is a single token (possibly with
+    // qualifiers) and <name> is the alias. Struct/enum/funcptr typedefs are
+    // handled by their own parsers, so exclude those keywords here.
+    const re = /typedef\s+(?!struct\b)(?!enum\b)(?!union\b)([\w\s\*]+?)\s+(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const aliasedType = m[1].trim();
+        const name = m[2];
+        // Skip if this is actually the tail of a struct/enum/funcptr typedef that
+        // a sibling parser already consumed (defensive — the negative lookahead
+        // should already exclude those, but the regex can still match fragments
+        // inside a `typedef struct { ... } foo_t;` body in edge cases).
+        if (aliasedType === '' || aliasedType.includes('{'))
+            continue;
+        // Skip array typedefs: `typedef uint8_t mac[6];` is NOT a plain alias.
+        // It would parse as aliasedType="uint8_t" name="mac" with the regex, but
+        // the trailing `[6]` between name and `;` makes it an array typedef — the
+        // regex's `\s*;` lookahead fails to match `[6];`, so this branch only
+        // fires for true plain aliases. Defensive: bail if the captured aliasedType
+        // somehow contains a `[` (would indicate a parse fragment).
+        if (aliasedType.includes('['))
+            continue;
+        tds.push({ kind: 'alias', name, aliasedType });
+    }
+    return tds;
+}
+/** Parse `#define FOO 42` and `#define BAR "str"` (integers and strings only). */
+function parseSimpleDefines(content) {
+    const out = [];
+    const re = /^\s*#define\s+(\w+)\s+(.+?)\s*$/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        const name = m[1];
+        const value = m[2].trim();
+        if (/^-?\d+$/.test(value) || /^"[^"]*"$/.test(value)) {
+            out.push({ name, value });
+        }
+    }
+    return out;
+}
+// Strip C-style comments so they don't interfere with parsing.
+// Block comments and line comments are both removed; preprocessor
+// directives are preserved (stripPreprocessorBlocks handles those next).
+function stripComments(content) {
+    return content.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+}
+function parseHeader(content) {
+    const noComments = stripComments(content);
+    const stripped = stripPreprocessorBlocks(noComments);
+    return {
+        functions: parseFunctions(stripped),
+        typedefs: [
+            ...parseEnumTypedefs(stripped),
+            ...parseStructTypedefs(stripped),
+            ...parseOpaqueTypedefs(stripped),
+            ...parseFuncPtrTypedefs(stripped),
+            ...parseAliasTypedefs(stripped),
+        ],
+        defines: parseSimpleDefines(noComments),
+    };
+}
+function emitEnumTypedef(td) {
+    const literalUnion = td.values.every((v) => typeof v.value === 'number')
+        ? td.values.map((v) => v.value).join(' | ')
+        : 'number';
+    const lines = [`export type ${td.name} = ${literalUnion};`];
+    // Export named constants so user code can reference WIFI_MODE_STA directly,
+    // exactly as ESP-IDF examples do.
+    for (const v of td.values) {
+        lines.push(`export const ${v.name}: ${td.name} = ${v.value ?? 0};`);
+    }
+    return lines;
+}
+function emitStructTypedef(td) {
+    const fields = td.fields.map((f) => {
+        const tsType = mapCTypeToTs(f.type);
+        return `  ${f.name}: ${f.isArray ? `${tsType}[]` : tsType};`;
+    });
+    return [`export interface ${td.name} {`, ...fields, `}`];
+}
+function emitTypedef(td) {
+    switch (td.kind) {
+        case 'enum':
+            return emitEnumTypedef(td);
+        case 'struct':
+            return emitStructTypedef(td);
+        case 'opaque':
+            return [`export type ${td.name} = number;`];
+        case 'alias':
+            return [`export type ${td.name} = ${mapCTypeToTs(td.aliasedType)};`];
+        case 'funcptr':
+            // Function-pointer typedefs have no faithful TS representation. Emit
+            // `any` with a comment so users know to use `rawCpp()` for callbacks.
+            return [
+                `// ${td.name} is a C function-pointer typedef; TS has no faithful representation.`,
+                `export type ${td.name} = any;`,
+            ];
+    }
+}
+/** Emit a free function declaration, name matching the C header 1-to-1. */
+function emitFunction(fn) {
+    const params = fn.params.map((p, idx) => {
+        const name = p.name || `_arg${idx}`;
+        const tsType = p.type === '' ? 'any' : mapCTypeToTs(p.type);
+        return `${name}: ${tsType}`;
+    });
+    const returnType = mapCTypeToTs(fn.returnType);
+    return `export declare function ${fn.name}(${params.join(', ')}): ${returnType};`;
+}
+/**
+ * Top-level entry: read a header file, write `<header>.d.ts` alongside it.
+ * Returns the output path, or null if no declarations could be extracted.
+ */
+export function generateCDecl(filePath, outputPath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    const content = fs.readFileSync(filePath, 'utf8');
+    const header = parseHeader(content);
+    // Collect every type name the header defines so the alias-emission pass
+    // below doesn't emit spurious `export type X = number;` for types that
+    // are already declared.
+    const knownTypes = new Set([
+        ...header.typedefs.map((t) => t.name),
+        ...BUILTIN_TS_TYPES,
+    ]);
+    // Find referenced types that aren't declared anywhere in this header and
+    // aren't builtins — emit them as `export type X = number;` so the .d.ts
+    // compiles standalone. (Common case: a header references `esp_err_t` from
+    // another header without re-typedef'ing it.)
+    const referencedTypes = new Set();
+    for (const f of header.functions) {
+        referencedTypes.add(mapCTypeToTs(f.returnType));
+        for (const p of f.params)
+            referencedTypes.add(mapCTypeToTs(p.type));
+    }
+    for (const td of header.typedefs) {
+        if (td.kind === 'struct') {
+            for (const f of td.fields)
+                referencedTypes.add(mapCTypeToTs(f.type));
+        }
+        else if (td.kind === 'alias') {
+            referencedTypes.add(mapCTypeToTs(td.aliasedType));
+        }
+    }
+    const aliasesToEmit = [...referencedTypes].filter((t) => !knownTypes.has(t) && !t.includes('|') && !BUILTIN_TS_TYPES.has(t));
+    // Nothing to emit → tell the caller.
+    if (header.functions.length === 0 &&
+        header.typedefs.length === 0 &&
+        header.defines.length === 0 &&
+        aliasesToEmit.length === 0) {
+        return null;
+    }
+    const lines = [
+        '// Auto-generated by cuttlefish gen-decls. Do not edit.',
+        '// Source: ' + path.basename(filePath),
+        '// C names are preserved verbatim; calls lower 1-to-1 to the C header.',
+        '',
+    ];
+    // Standalone type aliases for cross-header references (e.g. esp_err_t).
+    for (const a of aliasesToEmit) {
+        lines.push(`export type ${a} = number;`);
+    }
+    if (aliasesToEmit.length > 0)
+        lines.push('');
+    // Typedefs (enums, structs, opaque handles, aliases, function pointers).
+    for (const td of header.typedefs) {
+        lines.push(...emitTypedef(td), '');
+    }
+    // #define constants (integer/string literals only).
+    for (const d of header.defines) {
+        lines.push(`export const ${d.name}: ${/^"/.test(d.value) ? 'string' : 'number'} = ${d.value};`);
+    }
+    if (header.defines.length > 0)
+        lines.push('');
+    // Free functions, named 1-to-1 with the C header.
+    for (const fn of header.functions) {
+        lines.push(emitFunction(fn));
+    }
+    const outPath = outputPath ?? filePath.replace(/\.h$/i, '.d.ts');
+    const outContent = lines.join('\n') + '\n';
+    if (!fs.existsSync(outPath) || fs.readFileSync(outPath, 'utf8') !== outContent) {
+        fs.writeFileSync(outPath, outContent, 'utf8');
+    }
+    return outPath;
+}