@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/async-runtime-static.js

@@ -0,0 +1,201 @@
+// ---------------------------------------------------------------------------
+// Static (heap-free) async runtime C++ code generator
+//
+// For memory-constrained targets that lack <vector>, <string>, and a heap
+// (e.g. AVR: ATmega328P with 2 KB SRAM), the full Promise<T> runtime in
+// promise-runtime.ts cannot be emitted. This generator produces a drop-in
+// replacement that defines the SAME global symbols the HAL `Async` singleton
+// lowers to:
+//
+//   __cuttlefish_async_sleep(ms)
+//   __cuttlefish_async_yield()
+//   __cuttlefish_async_sleep_until(pollMs)
+//   __cuttlefish_async_current_task()
+//   cuttlefish_pump_microtasks()
+//
+// with zero dynamic allocation: fixed-size arrays of timer slots and one-shot
+// task slots, function-pointer + void* context (no std::function), and plain
+// C strings (no std::string).
+//
+// Scope: this covers the HAL `Async` API contract (fire-and-forget scheduling
+// and task introspection). It does NOT implement Promise<T>/.then/.catch
+// chaining — AVR cannot host that without heap + type erasure. The separate
+// async-state-machine.ts path already handles `async function` + `await`
+// heap-free on AVR and is not touched here.
+// ---------------------------------------------------------------------------
+/**
+ * Generate a heap-free static async runtime for C++ targets without <vector>.
+ *
+ * @param capacity Fixed number of timer/task slots. Keep small on constrained
+ *   targets (e.g. 8 on AVR). Caps the number of simultaneously pending
+ *   Async.sleep / sleepUntil / yield operations.
+ */
+export function generateStaticAsyncRuntime(capacity) {
+    return `
+// TypeCAD static (heap-free) async runtime — for targets without <vector>.
+namespace typecad_async_static {
+
+// A one-shot callback with an opaque context. The callback returns true while
+// it wants to keep running, false once complete. Function pointer + void* only
+// (no std::function) so no allocation occurs.
+typedef bool (*AsyncCallback)(void*);
+
+struct AsyncTask {
+  bool active;
+  AsyncCallback fn;
+  void* ctx;
+};
+
+struct AsyncTimer {
+  bool active;
+  bool repeat;          // false = one-shot (Async.sleep), true = periodic (Async.sleepUntil)
+  unsigned long deadline;
+  unsigned long periodMs;
+};
+
+class StaticAsyncRuntime {
+public:
+  static StaticAsyncRuntime& instance() {
+    static StaticAsyncRuntime r;
+    return r;
+  }
+
+  // Arm a one-shot timer that elapses after 'ms' milliseconds. Used by
+  // Async.sleep(ms). Returns false if no slot is free.
+  bool armTimeout(unsigned long ms) {
+    for (int i = 0; i < CAP; ++i) {
+      if (!_timers[i].active) {
+        _timers[i].active = true;
+        _timers[i].repeat = false;
+        _timers[i].deadline = millis() + ms;
+        _timers[i].periodMs = 0;
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Arm a periodic timer that re-arms every 'ms' milliseconds. Used by
+  // Async.sleepUntil(pollMs) — the condition re-check happens caller-side, so
+  // the timer simply fires on a fixed cadence. Returns false if no slot free.
+  bool armInterval(unsigned long ms) {
+    for (int i = 0; i < CAP; ++i) {
+      if (!_timers[i].active) {
+        _timers[i].active = true;
+        _timers[i].repeat = true;
+        _timers[i].deadline = millis() + ms;
+        _timers[i].periodMs = ms;
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Enqueue a one-shot task that runs on the next pump cycle. Used by
+  // Async.yield(). Returns false if the task table is full.
+  bool enqueue(AsyncCallback fn, void* ctx) {
+    if (!fn) return false;
+    for (int i = 0; i < CAP; ++i) {
+      if (!_tasks[i].active) {
+        _tasks[i].active = true;
+        _tasks[i].fn = fn;
+        _tasks[i].ctx = ctx;
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Advance the runtime: expire due timers and run ready tasks. Called from
+  // cuttlefish_pump_microtasks(), which the transpiler injects into loop().
+  void pump() {
+    const unsigned long now = millis();
+    // Timers: one-shot slots deactivate on expiry; periodic slots re-arm.
+    for (int i = 0; i < CAP; ++i) {
+      if (_timers[i].active) {
+        // (now - deadline) handles the millis() 32-bit wrap correctly
+        if ((long)(now - _timers[i].deadline) >= 0) {
+          if (_timers[i].repeat) {
+            _timers[i].deadline = now + _timers[i].periodMs;
+          } else {
+            _timers[i].active = false;
+          }
+        }
+      }
+    }
+    // One-shot tasks: run once, then deactivate regardless of return value
+    // (yield is a single deferred step).
+    for (int i = 0; i < CAP; ++i) {
+      if (_tasks[i].active) {
+        AsyncTask t = _tasks[i];
+        _tasks[i].active = false;
+        if (t.fn) t.fn(t.ctx);
+      }
+    }
+  }
+
+private:
+  static const int CAP = ${capacity};
+  AsyncTimer _timers[CAP];
+  AsyncTask _tasks[CAP];
+};
+
+// Trivial no-op callback for Async.yield(): it only needs to occupy a slot for
+// one pump cycle so that awaiting code observes a deferred step.
+static bool __yieldNoop(void*) { return false; }
+
+} // namespace typecad_async_static
+
+// ── Global-scope HAL symbols (the names the HAL Async module emits) ──
+
+// Async.sleep(ms) — arm a one-shot timer. No value is returned; on heap-free
+// targets the HAL method's result is fire-and-forget scheduling.
+inline void __cuttlefish_async_sleep(unsigned long ms) {
+  typecad_async_static::StaticAsyncRuntime::instance().armTimeout(ms);
+}
+
+// Async.yield() — defer one pump cycle.
+inline void __cuttlefish_async_yield() {
+  typecad_async_static::StaticAsyncRuntime::instance().enqueue(
+    typecad_async_static::__yieldNoop, 0);
+}
+
+// Async.sleepUntil(pollMs) — arm a periodic timer at the poll cadence. The
+// caller's condition is re-evaluated each time the timer elapses.
+inline void __cuttlefish_async_sleep_until(unsigned long pollMs) {
+  typecad_async_static::StaticAsyncRuntime::instance().armInterval(pollMs);
+}
+
+// Async.currentTask() — name of the currently executing task.
+inline const char* __cuttlefish_async_current_task() {
+  return "main";
+}
+
+// Pump entry called from the transpiler-generated loop(). Advances timers and
+// drains one-shot tasks. Same name as the heap-based runtime so the emitter's
+// loop injection is identical across targets.
+inline void cuttlefish_pump_microtasks() {
+  typecad_async_static::StaticAsyncRuntime::instance().pump();
+}
+
+// HAL-level wait for pin edge — polling-based implementation for static
+// (heap-free) targets. Blocks the current task until the pin edge is detected
+// or the timeout elapses. An edge is a transition: for RISING, the pin must
+// first be LOW then go HIGH; for FALLING, first HIGH then go LOW.
+inline void __cuttlefish_wait_pin_edge(int pin, int mode, long timeout) {
+  int targetState = (mode == RISING) ? HIGH : LOW;
+  int idleState = (mode == RISING) ? LOW : HIGH;
+  unsigned long start = millis();
+  // Phase 1: wait for the pin to be in the idle state (the "before" level)
+  while (digitalRead(pin) != idleState) {
+    if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) return;
+    delay(1);
+  }
+  // Phase 2: wait for the transition to the target state (the actual edge)
+  while (digitalRead(pin) != targetState) {
+    if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) return;
+    delay(1);
+  }
+}
+`;
+}

package/dist/api/shared/async-types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Configuration for the async runtime on a given platform.
+ * Framework packages (Arduino, Native, etc.) return this from their
+ * PlatformAsyncStrategy implementation.
+ *
+ * `scheduler` controls how cooperative microtasks are dispatched:
+ *   - "microtask"  — simple FIFO queue pumped in loop()/main() (current default)
+ *   - "freertos"   — FreeRTOS task notifications / queue (future)
+ *   - "thread"     — std::async background thread (native hosted)
+ *
+ * `waitForPinEdge` controls how GPIO edge-waiting is implemented:
+ *   - "interrupt"  — attachInterrupt-based (real ISR, preferred)
+ *   - "polling"    — busy-wait loop polling digitalRead (fallback)
+ *   - "stub"       — resolve immediately (testing/debug only)
+ */
+export interface AsyncRuntimeConfig {
+    /** Queue capacity for the microtask ring buffer (default: 256). */
+    queueCapacity: number;
+    /**
+     * The co-operative scheduling strategy.
+     */
+    scheduler: "microtask" | "freertos" | "thread";
+    /**
+     * How waitForRising/waitForFalling resolve.
+     */
+    waitForPinEdge: "interrupt" | "polling" | "stub";
+    /**
+     * Whether to include the std::vector / std::function based Promise runtime.
+     * Targets without stdlib support (e.g. AVR) set this to false.
+     */
+    hasPromiseRuntime: boolean;
+    /**
+     * Whether the platform supports timer-based setTimeout/setInterval
+     * (as opposed to cooperative polling).
+     */
+    hasTimers: boolean;
+    /**
+     * Names of C++ headers required by the async runtime.
+     * e.g. ["<functional>", "<vector>", "<utility>", "<string>"]
+     */
+    requiredIncludes: string[];
+}

package/dist/api/shared/async-types.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// Shared async runtime configuration types
+//
+// Defines the PlatformAsyncStrategy sub-interface that framework packages
+// implement to provide platform-specific async/scheduling behavior.
+// The Async HAL module uses these to emit the correct C++ runtime code.
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/shared/board-resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Flat map from dot-path key to scalar constant value.
+ *
+ * Examples (for Arduino Uno):
+ *   "id"           → "arduino-uno"
+ *   "mcu"          → "ATmega328P"
+ *   "clockSpeed"   → 16000000
+ *   "memory.flash" → 32768
+ *   "memory.sram"  → 2048
+ *   "memory.eeprom"→ 1024
+ */
+export type BoardConstants = Map<string, string | number | boolean>;

package/dist/api/shared/board-resolver.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// Board constant types
+//
+// Types for compile-time constant extraction from board definitions.
+// The implementation (which uses TypeScript compiler API) remains in CLI.
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/shared/cpp-type-ir.d.ts

@@ -0,0 +1,229 @@
+/** Fixed-width / builtin scalar type names used by the transpiler. */
+export type CppPrimitiveName = "int" | "long" | "long long" | "unsigned int" | "unsigned long" | "unsigned long long" | "short" | "unsigned short" | "float" | "double" | "long double" | "bool" | "void" | "char" | "signed char" | "unsigned char" | "size_t" | "ssize_t" | "intptr_t" | "uintptr_t" | "ptrdiff_t" | "int8_t" | "int16_t" | "int32_t" | "int64_t" | "uint8_t" | "uint16_t" | "uint32_t" | "uint64_t";
+/**
+ * Structured representation of a C++ type.
+ *
+ * Construct via the `CppTypeIR.*` builders or by parsing a string with
+ * `parseCppType`. Inspect via `kind`. Render back to a string with
+ * `renderCppType`.
+ */
+export type CppTypeIR = 
+/** Builtin scalar (`int`, `double`, `uint8_t`, `void`, …). */
+{
+    kind: "primitive";
+    name: CppPrimitiveName;
+}
+/** Unresolved / template-parameter / unknown — renders as the literal `auto`. */
+ | {
+    kind: "auto";
+}
+/** `std::string`. Modeled separately from `primitive` because it is a class
+ *  type with reference semantics and is detected by `isStringLike`. */
+ | {
+    kind: "string";
+}
+/** `__tc_str_ptr` sentinel — marks an expression that must be passed as `.c_str()`. */
+ | {
+    kind: "strPtr";
+}
+/** A user-defined named type (struct/class/enum/typedef/typename) with
+ *  optional template arguments. The `args` are the *parsed* template args. */
+ | {
+    kind: "named";
+    name: string;
+    args?: CppTypeIR[];
+}
+/** Pointer to `base`. Renders as `${render(base)}*`. */
+ | {
+    kind: "pointer";
+    base: CppTypeIR;
+}
+/** Reference to `base`. `isConst` distinguishes `T&` from `const T&`. */
+ | {
+    kind: "reference";
+    base: CppTypeIR;
+    isConst: boolean;
+}
+/** Top-level const qualification: `const T` (prefix) or `T const` (suffix). */
+ | {
+    kind: "qualified";
+    base: CppTypeIR;
+    isConst: boolean;
+}
+/** `std::vector<element>`. */
+ | {
+    kind: "vector";
+    element: CppTypeIR;
+}
+/** `std::set<element>`. */
+ | {
+    kind: "set";
+    element: CppTypeIR;
+}
+/** `std::map<key, value>`. */
+ | {
+    kind: "map";
+    key: CppTypeIR;
+    value: CppTypeIR;
+}
+/** `std::tuple<...elements>`. */
+ | {
+    kind: "tuple";
+    elements: CppTypeIR[];
+}
+/** `std::variant<...members>`. */
+ | {
+    kind: "variant";
+    members: CppTypeIR[];
+}
+/** `std::function<returnType(params...)>`. */
+ | {
+    kind: "function";
+    returnType: CppTypeIR;
+    params: CppTypeIR[];
+}
+/** Compile-time fixed-size array: `__tc_StaticArray<element, size>` or
+ *  C-array `element[size]`. `size` is undefined for `element[]`. */
+ | {
+    kind: "staticArray";
+    element: CppTypeIR;
+    size?: number;
+}
+/** C-array decayed form `element[]` / `element[size]` (distinct from
+ *  `staticArray` which carries the `__tc_StaticArray` marker). */
+ | {
+    kind: "cArray";
+    element: CppTypeIR;
+    size?: number;
+}
+/** Coroutine generator pseudo-type `__tc_Generator<yieldType>`. */
+ | {
+    kind: "generator";
+    yieldType: CppTypeIR;
+}
+/** Smart pointer wrappers `std::shared_ptr<inner>` / `std::unique_ptr<inner>`.
+ *  `wrapper` is the smart-pointer class name. */
+ | {
+    kind: "smartPointer";
+    wrapper: "std::shared_ptr" | "std::unique_ptr";
+    inner: CppTypeIR;
+}
+/** Escape hatch for a type token the parser does not yet model explicitly.
+ *  Renders back as `raw` unchanged. Lets migration be incremental. */
+ | {
+    kind: "opaque";
+    raw: string;
+};
+/** All discriminator strings, useful for exhaustive switches. */
+export type CppTypeKind = CppTypeIR["kind"];
+export declare function splitTemplateArgs(inner: string): string[];
+export declare function parseCppType(s: string): CppTypeIR;
+export declare function renderCppType(ir: CppTypeIR): string;
+/** True for `T*` (any depth of indirection). */
+export declare function isPointer(ir: CppTypeIR): boolean;
+/** True for `T&` (and `const T&`). */
+export declare function isReference(ir: CppTypeIR): boolean;
+/** True for any container that supports element/index access:
+ *  vector, set, map, staticArray, cArray. */
+export declare function isContainer(ir: CppTypeIR): boolean;
+export declare function isVector(ir: CppTypeIR): boolean;
+export declare function isMap(ir: CppTypeIR): boolean;
+export declare function isSet(ir: CppTypeIR): boolean;
+export declare function isTuple(ir: CppTypeIR): boolean;
+export declare function isVariant(ir: CppTypeIR): boolean;
+export declare function isStdFunction(ir: CppTypeIR): boolean;
+export declare function isStaticArray(ir: CppTypeIR): boolean;
+export declare function isCArray(ir: CppTypeIR): boolean;
+/** True for `std::string` / `__tc_str_ptr` / `const char*`-ish string types.
+ *  Does NOT consult platform strategy — callers that need platform-aware string
+ *  detection (e.g. Arduino `String`) should still call `strategy.isStringLikeType`. */
+export declare function isStringLike(ir: CppTypeIR): boolean;
+/** True for builtin scalars (`int`, `double`, …) and `std::string`/`bool`.
+ *  Corresponds to the `isPrimitiveCppType` helpers in statement-renderer. */
+export declare function isPrimitive(ir: CppTypeIR): boolean;
+/** Peel pointer/reference/const qualification and return the underlying type.
+ *  `Foo*` → `Foo`, `const Bar&` → `Bar`, `std::vector<T>*` → `std::vector<T>`.
+ *  Corresponds to the `replace(/\*$/, "").replace(/^const\s+/, "").trim()`
+ *  idiom scattered through expression-renderer / setup. */
+export declare function bareType(ir: CppTypeIR): CppTypeIR;
+/** Element type of a vector/set/staticArray/cArray, or the value type of a map.
+ *  Returns undefined for non-containers. Replaces the duplicated
+ *  `slice("std::vector<".length, -1).trim()` copies. */
+export declare function elementOf(ir: CppTypeIR): CppTypeIR | undefined;
+/** Coarse kind bucket for the snprintf format-specifier dispatcher
+ *  (`emit/snprintf-helpers.ts`). Replaces the `cppType === "int" || ...` ladder. */
+export type CppFormatKind = "bool" | "int" | "uint" | "long" | "ulong" | "float" | "string" | "char" | "pointer" | "other";
+export declare function formatKindOf(ir: CppTypeIR): CppFormatKind;
+export declare const CppTypeIR: {
+    primitive: (name: CppPrimitiveName) => CppTypeIR;
+    auto: () => CppTypeIR;
+    string: () => CppTypeIR;
+    bool: () => CppTypeIR;
+    void: () => CppTypeIR;
+    int: () => CppTypeIR;
+    double: () => CppTypeIR;
+    named: (name: string, args?: CppTypeIR[]) => CppTypeIR;
+    pointer: (base: CppTypeIR) => CppTypeIR;
+    reference: (base: CppTypeIR, isConst?: boolean) => CppTypeIR;
+    const_: (base: CppTypeIR) => CppTypeIR;
+    vector: (element: CppTypeIR) => CppTypeIR;
+    set: (element: CppTypeIR) => CppTypeIR;
+    map: (key: CppTypeIR, value: CppTypeIR) => CppTypeIR;
+    tuple: (elements: CppTypeIR[]) => CppTypeIR;
+    variant: (members: CppTypeIR[]) => CppTypeIR;
+    function: (returnType: CppTypeIR, params: CppTypeIR[]) => CppTypeIR;
+    staticArray: (element: CppTypeIR, size?: number) => CppTypeIR;
+    cArray: (element: CppTypeIR, size?: number) => CppTypeIR;
+    generator: (yieldType: CppTypeIR) => CppTypeIR;
+    smartPointer: (wrapper: "std::shared_ptr" | "std::unique_ptr", inner: CppTypeIR) => CppTypeIR;
+    strPtr: () => CppTypeIR;
+    opaque: (raw: string) => CppTypeIR;
+};
+export declare function parsedIsPointer(cppType: string): boolean;
+export declare function parsedIsStringLike(cppType: string): boolean;
+export declare function parsedIsPrimitive(cppType: string): boolean;
+export declare function parsedIsContainer(cppType: string): boolean;
+export declare function parsedIsVector(cppType: string): boolean;
+export declare function parsedIsMap(cppType: string): boolean;
+export declare function parsedIsSet(cppType: string): boolean;
+export declare function parsedIsTuple(cppType: string): boolean;
+export declare function parsedIsVariant(cppType: string): boolean;
+export declare function parsedIsStaticArray(cppType: string): boolean;
+/** True for `std::string` (and `std::string&`, `const std::string`, etc.). */
+export declare function parsedIsStdString(cppType: string): boolean;
+export declare function parsedElementOf(cppType: string): CppTypeIR | undefined;
+/** Element/value type of a container, rendered back to a string. Replaces the
+ *  `slice("std::vector<".length, -1).trim()` idiom at consumer sites. */
+export declare function parsedElementString(cppType: string): string | undefined;
+/** Bare (pointer/const/reference-stripped) type rendered as a string. Replaces
+ *  `cppType.replace(/\*$/, "").replace(/^const\s+/, "").trim()` at consumer sites. */
+export declare function parsedBareString(cppType: string): string;
+export declare function parsedBareType(cppType: string): CppTypeIR;
+/**
+ * Collect every user-named type referenced anywhere inside a C++ type string
+ * (including nested template args, pointer bases, vector elements, etc.).
+ * Replaces the historical "match all identifiers then filter primitives"
+ * idiom used for dependency tracking in call-graph analysis.
+ *
+ * Returns only `named`-kind names — primitives, `std::string`, `auto`, etc.
+ * are excluded because they are not user-defined types.
+ */
+export declare function collectNamedTypes(ir: CppTypeIR): string[];
+/** String-in convenience for `collectNamedTypes(parseCppType(s))`. */
+export declare function parsedCollectNamedTypes(cppType: string): string[];
+/** True if the type is a plain struct/class name with no template args, pointer,
+ *  reference, array, or container wrapper — i.e. the kind of type that a
+ *  `return null` should lower to `return {};` (value-init).
+ *  Replaces the `!includes("<") && !endsWith("*") && !endsWith("]")` idiom. */
+export declare function parsedIsPlainStructType(cppType: string): boolean;
+/**
+ * True for types that own a string buffer and therefore need `.c_str()` when
+ * passed to a C variadic (printf/snprintf): `std::string`, `__tc_str_ptr`,
+ * and platform string types like Arduino `String`. NOT true for `const char*`
+ * / `char*`, which are already C-strings.
+ *
+ * This is the structured replacement for the
+ * `normalized === "std::string" || normalized === "String" || normalized === "__tc_str_ptr"`
+ * idiom in the snprintf/expression renderers.
+ */
+export declare function needsCStrForStringLike(cppType: string): boolean;