@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/emit/expression-renderer.d.ts

@@ -188,8 +188,8 @@ export declare class ExpressionRenderer {
      * String-enum operands are passed through unchanged (they're `const char*`).
      *
      * This is the assignment/argument-site counterpart to the operator-level
-     * enum wrapping in renderBinary. SUPPORT_MATRIX §1.7: enum values used as
-     * integers need an explicit cast in C++.
+     * enum wrapping in renderBinary. Enum values used as integers need an
+     * explicit cast in C++.
      */
     renderEnumSafeValue(expr: ExpressionIR, knownVariableTypes?: Map<string, KnownVariableInfo>): string;
     /**
@@ -206,7 +206,7 @@ export declare class ExpressionRenderer {
      *     operand → `static_cast<EnumType>(value)` (int → enum). C++ `enum
      *     class` does not implicitly convert FROM an integral storage type
      *     either, so reading an `int`/`uint8_t` cell back into an enum-typed
-     *     local needs the reverse cast. SUPPORT_MATRIX §1.7.
+     *     local needs the reverse cast.
      *
      * This closes the "enum↔integral storage boundary" family — the previous
      * point-specific casts handled enum-as-array-index (demo #28 E) and

package/dist/emit/expression-renderer.js

@@ -179,8 +179,17 @@ export class ExpressionRenderer {
                 break;
             case "hal-expr": {
                 const resolved = routeHALOp(expr.operation, this.strategy);
+                // A method body's preceding side-effect ops (bus transactions, pin
+                // configures) must run even in expression position — wrap them with
+                // the value in a GCC statement-expression.
+                const prefix = (expr.prefixOps ?? [])
+                    .map((op) => routeHALOp(op, this.strategy))
+                    .map((r) => r?.code ?? `/* unhandled hal-op prefix: dropped */`)
+                    .join(' ');
                 if (resolved?.expression) {
-                    rendered = resolved.expression;
+                    rendered = prefix
+                        ? `({ ${prefix} ${resolved.expression}; })`
+                        : resolved.expression;
                 }
                 else if (resolved?.code) {
                     // Strip trailing semicolon and a leading `return ` for expression
@@ -189,7 +198,8 @@ export class ExpressionRenderer {
                     // `return` keyword is invalid (avr-g++: "expected primary-expression
                     // before 'return'") and would leak as
                     // `strcmp(return Preferences.getString(...), ...)`. Demo #33 Finding C.
-                    rendered = resolved.code.replace(/;\s*$/, "").replace(/^\s*return\s+/, "");
+                    const asExpr = resolved.code.replace(/;\s*$/, "").replace(/^\s*return\s+/, "");
+                    rendered = prefix ? `({ ${prefix} ${asExpr}; })` : asExpr;
                 }
                 else {
                     // Unregistered HAL op: surface as a warning so the user sees it, but
@@ -862,7 +872,7 @@ export class ExpressionRenderer {
         // must be cast to an integral type — a C++ `enum class` does not
         // implicitly convert to `size_t`, so `vector[enumValue]` fails to compile.
         // `renderEnumSafeValue` already wraps numeric-enum operands in
-        // `static_cast<int>(...)` (SUPPORT_MATRIX §1.7); route the index through it
+        // `static_cast<int>(...)`; route the index through it
         // (with the in-scope variable types so a bare enum-typed identifier
         // resolves) so enum indices lower correctly. Non-enum indices are passed
         // through unchanged. Demo #28 Finding E.
@@ -886,8 +896,8 @@ export class ExpressionRenderer {
      * String-enum operands are passed through unchanged (they're `const char*`).
      *
      * This is the assignment/argument-site counterpart to the operator-level
-     * enum wrapping in renderBinary. SUPPORT_MATRIX §1.7: enum values used as
-     * integers need an explicit cast in C++.
+     * enum wrapping in renderBinary. Enum values used as integers need an
+     * explicit cast in C++.
      */
     renderEnumSafeValue(expr, knownVariableTypes) {
         const rendered = this.render(expr, undefined, knownVariableTypes);
@@ -919,7 +929,7 @@ export class ExpressionRenderer {
      *     operand → `static_cast<EnumType>(value)` (int → enum). C++ `enum
      *     class` does not implicitly convert FROM an integral storage type
      *     either, so reading an `int`/`uint8_t` cell back into an enum-typed
-     *     local needs the reverse cast. SUPPORT_MATRIX §1.7.
+     *     local needs the reverse cast.
      *
      * This closes the "enum↔integral storage boundary" family — the previous
      * point-specific casts handled enum-as-array-index (demo #28 E) and
@@ -1155,7 +1165,7 @@ export class ExpressionRenderer {
         // Wrap enum-class operands in static_cast<int>() for arithmetic operators
         // (+, -, *, /) and bitwise operators (&, |, ^, <<, >>). C++ enum class
         // values don't interoperate with int implicitly — `trophic - 1`, `a | b`,
-        // `x & MASK` all fail without the cast. SUPPORT_MATRIX §1.7/§5.1. The
+        // `x & MASK` all fail without the cast. The
         // shared castEnumOperandsForOperator helper handles detection + defensive
         // symmetry in one place.
         const numericOps = new Set(["+", "-", "*", "/", "&", "|", "^", "<<", ">>"]);

package/dist/emit/route-hal-op.js

@@ -11,70 +11,39 @@
 //
 // Output-pin state tracking is also handled here, centrally, so every
 // strategy benefits without per-strategy changes:
-// - gpio.read with `trackedValue` never reaches the strategy (a hardware
-//   read of a direction-only output is not portable, e.g. Zephyr); it folds
-//   to a constant or the tracked shadow variable.
-// - gpio.write / gpio.toggle flagged `updatesShadow` get the shadow variable
+// - (pin-state-tracking removed: every gpio.* op lowers through the strategy)
 //   update appended to whatever the strategy produced. The flag is baked
 //   into the op at IR-build time (markShadowUpdatingOps) — emit must not
 //   consult live tracker state, because all files build (each resetting the
 //   tracker) before any file emits.
 // ---------------------------------------------------------------------------
 import { getSafetyHook } from "../safety-hook.js";
-import { pinShadowVarName } from "../ir/pin-state-tracking.js";
+import { markHalOpResolved } from "../ir/build-ir-state.js";
 export function routeHALOp(op, strategy) {
+    // An op resolved here during IR-build-time method inlining may never exist
+    // as an IR node (its text is baked into the calling method's emit lines),
+    // so record it for program-analysis's peripheral usage flags — every
+    // branch, matching the IR-node paths (display.* sets usesGPIO/usesDisplay,
+    // safety.* maps the __tc_safety_* helpers).
     if (typeof op.operation === "string") {
         if (op.operation.startsWith("display.")) {
-            return strategy.resolveDisplayOp?.(op);
+            const r = strategy.resolveDisplayOp?.(op);
+            if (r)
+                markHalOpResolved(op.operation);
+            return r;
         }
         if (op.operation.startsWith("safety.")) {
             // Safety ops are resolved by the @typecad/safety package via hook.
             // Returns undefined if the package is not loaded (caller emits an
             // unhandled-op warning).
-            return getSafetyHook()?.resolveSafetyOp?.(op);
+            const r = getSafetyHook()?.resolveSafetyOp?.(op);
+            if (r)
+                markHalOpResolved(op.operation);
+            return r;
         }
     }
-    if (op.operation === "gpio.read" && op.trackedValue) {
-        // Tracked OUTPUT-pin read: software truth, never a hardware read.
-        if (op.trackedValue === "high")
-            return { expression: "true" };
-        if (op.trackedValue === "low")
-            return { expression: "false" };
-        return { expression: pinShadowVarName(op.pin) };
-    }
     const resolved = strategy.resolveHALOperation?.(op);
-    // Toggle on a shadow-tracked pin must not use the strategy's default
-    // read-modify-write form (e.g. digitalWrite(p, digitalRead(p) ...) on
-    // Arduino) — reading the pin back is exactly what tracking avoids. Lower
-    // it as a write of the shadow's current value, then flip the shadow.
-    if (op.operation === "gpio.toggle" && op.updatesShadow) {
-        const varName = pinShadowVarName(op.pin);
-        const writeOp = {
-            operation: "gpio.write",
-            pin: op.pin,
-            value: varName,
-            ...(op.port !== undefined ? { port: op.port } : {}),
-        };
-        const writeResolved = strategy.resolveHALOperation?.(writeOp);
-        const flip = `${varName} = (!${varName});`;
-        if (writeResolved?.code) {
-            return { ...writeResolved, code: `${writeResolved.code}\n${flip}` };
-        }
-        if (writeResolved?.expression) {
-            return { ...writeResolved, expression: `${writeResolved.expression}, ${flip}` };
-        }
-        return { code: flip };
-    }
-    if (op.operation === "gpio.write" && op.updatesShadow) {
-        const varName = pinShadowVarName(op.pin);
-        const update = `${varName} = ((${op.value}) != 0);`;
-        if (resolved?.code) {
-            return { ...resolved, code: `${resolved.code}\n${update}` };
-        }
-        if (resolved?.expression) {
-            return { ...resolved, expression: `${resolved.expression}, ${update}` };
-        }
-        return { code: update };
-    }
+    if (resolved)
+        markHalOpResolved(op.operation);
     return resolved;
 }

package/dist/emit/snprintf-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { AssignmentIR, ExpressionIR, StatementIR, VariableDeclarationIR } from "../api/shared/index.js";
+import type { ExpressionIR, StatementIR, VariableDeclarationIR } from "../api/shared/index.js";
 import type { PlatformStrategy } from "../api/shared/index.js";
 import type { KnownVariableInfo, SnprintfArgRenderResult, SnprintfRenderResult, EmissionScopeState, SnprintfExpressionRenderer } from "../api/shared/index.js";
 import { escapeCppStringLiteral } from "../utils/strings.js";
@@ -12,6 +12,4 @@ export declare function createChildEmissionScope(baseScope: EmissionScopeState,
 export declare function recordVariableType(statement: VariableDeclarationIR, scopeState: EmissionScopeState): void;
 export { escapeCppStringLiteral };
 export declare function inferSnprintfArg(expr: ExpressionIR, strategy: PlatformStrategy, scopeState: EmissionScopeState, renderExpression: SnprintfExpressionRenderer, pointerVarTypes?: Map<string, string>, knownFunctionReturnTypes?: Map<string, string>, stringVarNames?: Set<string>): SnprintfArgRenderResult | undefined;
-export declare function buildSnprintfRenderResult(expr: ExpressionIR, strategy: PlatformStrategy, scopeState: EmissionScopeState, renderExpression: SnprintfExpressionRenderer, pointerVarTypes?: Map<string, string>, knownFunctionReturnTypes?: Map<string, string>, stringVarNames?: Set<string>): SnprintfRenderResult | undefined;
-export declare function shouldUseSnprintfForString(statement: VariableDeclarationIR | AssignmentIR, strategy: PlatformStrategy): boolean;
 export declare function statementNeedsSnprintf(statement: StatementIR, strategy: PlatformStrategy): boolean;

package/dist/emit/snprintf-helpers.js

@@ -7,7 +7,7 @@
 // All logic lives in the CLI; no framework package dependency.
 // Types are imported from @typecad/cuttlefish/api/shared.
 // ---------------------------------------------------------------------------
-import { escapeCppStringLiteral, escapeSnprintfFormatFragment } from "../utils/strings.js";
+import { escapeCppStringLiteral } from "../utils/strings.js";
 import { cppTypeForHalOp } from "./utils/hal-op-cpp-type.js";
 import { parsedElementString, parsedIsStringLike } from "../api/shared/cpp-type-ir.js";
 // ---------------------------------------------------------------------------
@@ -387,46 +387,8 @@ export function inferSnprintfArg(expr, strategy, scopeState, renderExpression, p
     }
 }
 // ---------------------------------------------------------------------------
-// Snprintf render result builder
-// ---------------------------------------------------------------------------
-export function buildSnprintfRenderResult(expr, strategy, scopeState, renderExpression, pointerVarTypes, knownFunctionReturnTypes, stringVarNames) {
-    if (expr.kind !== "string_concat") {
-        return undefined;
-    }
-    let formatString = "";
-    const args = [];
-    let estimatedLength = 1;
-    const preludeLines = [];
-    for (const part of expr.parts) {
-        if (part.kind === "string") {
-            // These literal parts are concatenated into the snprintf *format* string,
-            // so any embedded `%` must be doubled or snprintf misreads it on hardware.
-            formatString += escapeSnprintfFormatFragment(part.value);
-            estimatedLength += part.value.length;
-            continue;
-        }
-        const innerExpr = part.kind === "template_string" ? part.expression : part;
-        const arg = inferSnprintfArg(innerExpr, strategy, scopeState, renderExpression, pointerVarTypes, knownFunctionReturnTypes, stringVarNames);
-        if (!arg) {
-            return undefined;
-        }
-        formatString += arg.format;
-        args.push(arg.arg);
-        estimatedLength += arg.estimatedLength;
-        preludeLines.push(...arg.preludeLines);
-    }
-    return { formatString, args, estimatedLength: Math.max(estimatedLength, 16), preludeLines };
-}
-// ---------------------------------------------------------------------------
 // Snprintf usage detection
 // ---------------------------------------------------------------------------
-export function shouldUseSnprintfForString(statement, strategy) {
-    if (!strategy.useSnprintfForStrings()) {
-        return false;
-    }
-    const value = statement.kind === "var_decl" ? statement.initializer : statement.value;
-    return value?.kind === "string_concat";
-}
 export function statementNeedsSnprintf(statement, strategy) {
     if (!strategy.useSnprintfForStrings()) {
         return false;

package/dist/emit/statement-renderer.d.ts

@@ -171,10 +171,6 @@ export declare class StatementRenderer {
     mapReturnTypeForEmit(fnName: string, returnType: string): string;
     private normalizeCppType;
     private inferFieldType;
-    /**
-     * Transform console.log/error/warn calls based on target platform.
-     */
-    private transformConsoleCall;
     private renderEmitArg;
     /**
      * Map a function name to its platform-specific name.

package/dist/emit/statement-renderer.js

@@ -6,7 +6,7 @@
 import { routeHALOp } from "./route-hal-op.js";
 import { activeNamespaceNames } from "../ir/build-ir-state.js";
 import { ExpressionRenderer, transformTypeName, normalizeRawExpression } from "./expression-renderer.js";
-import { isConsoleCall, getConsoleMethod, inferObjectFieldType, collectNestedStructDefs } from "./utils/index.js";
+import { inferObjectFieldType, collectNestedStructDefs } from "./utils/index.js";
 import { escapeCppKeyword, escapeTrailingMember } from "../utils/strings.js";
 import { accessorGetterName, accessorSetterName } from "./utils/cpp-helpers.js";
 import { parseCppType, bareType, parsedIsPointer, parsedIsVector, parsedElementString, parsedIsPlainStructType } from "../api/shared/cpp-type-ir.js";
@@ -270,7 +270,7 @@ export class StatementRenderer {
                 // `return nullptr;` / `return CUTTLEFISH_UNDEFINED;` — those are
                 // integer/pointer literals that won't convert to the struct type.
                 // Lower to a value-initialized `return {};` instead. The `T | null`
-                // union already strips to `T` (SUPPORT_MATRIX §1.8), so the function
+                // union already strips to `T`, so the function
                 // signature really does return the struct. Demo #14 Finding A.
                 const retType = statement.functionReturnType;
                 if (retType && isStructReturnType(retType, this.strategy) && isNullishReturnValue(statement.value)) {
@@ -383,29 +383,46 @@ export class StatementRenderer {
                 return "co_yield;";
             }
             if (statement.kind === "block") {
-                return `{`;
+                // Blocks reach the single-line renderer as async state-machine segment
+                // pre-statements (chained HAL calls lower to a block of hal-ops). The
+                // former bare `{` dropped the block body AND emitted an unbalanced
+                // brace. Mirrors the line-appender's block emission: empty body →
+                // no-op, otherwise brace + rendered statements.
+                const bodyLines = statement.body
+                    .map((nested) => this.render(nested, forHeader, calleeTransformer, knownVariableTypes))
+                    .filter((line) => line.length > 0);
+                if (bodyLines.length === 0) {
+                    return "";
+                }
+                return ["{", ...bodyLines, "}"].join("\n");
             }
             if (statement.kind === "hal-op") {
                 const resolved = routeHALOp(statement.operation, this.strategy);
-                if (resolved?.code) {
-                    // Strip leading 'return ' from raw hal-op code when emitted as a
-                    // standalone statement.  The HAL definition includes `return` because
-                    // the TypeScript stub returns a value, but the C++ statement context
-                    // (e.g. inside void setup()) does not expect it.
-                    let code = resolved.code;
-                    if (code.startsWith('return '))
-                        code = code.slice('return '.length);
-                    // A raw hal-op statement (e.g. `Async.sleep(10)` →
-                    // `__cuttlefish_async_sleep(10)`) is a complete C++ statement and
-                    // needs a terminating semicolon, unless it already ends with one or
-                    // with `}` (a compound block).
-                    if (!forHeader && !code.endsWith(';') && !code.endsWith('}')) {
-                        code = code + ';';
+                if (resolved) {
+                    // `{ code: '' }` is a registered op's deliberate elision (sentinel
+                    // facts — an absent request body, insecure=false) — emit nothing and
+                    // do NOT fall through to the unregistered-op warning.
+                    if (resolved.code) {
+                        // Strip leading 'return ' from raw hal-op code when emitted as a
+                        // standalone statement.  The HAL definition includes `return` because
+                        // the TypeScript stub returns a value, but the C++ statement context
+                        // (e.g. inside void setup()) does not expect it.
+                        let code = resolved.code;
+                        if (code.startsWith('return '))
+                            code = code.slice('return '.length);
+                        // A raw hal-op statement (e.g. `Async.sleep(10)` →
+                        // `__cuttlefish_async_sleep(10)`) is a complete C++ statement and
+                        // needs a terminating semicolon, unless it already ends with one or
+                        // with `}` (a compound block).
+                        if (!forHeader && !code.endsWith(';') && !code.endsWith('}')) {
+                            code = code + ';';
+                        }
+                        return code;
                     }
-                    return code;
-                }
-                if (resolved?.expression) {
-                    return forHeader ? resolved.expression : `${resolved.expression};`;
+                    if (resolved.expression) {
+                        return forHeader ? resolved.expression : `${resolved.expression};`;
+                    }
+                    return "";
                 }
                 // Unregistered HAL op: surface as a warning so the user sees it, but
                 // keep HAL as an extensibility point. The bare comment is retained as
@@ -506,6 +523,11 @@ export class StatementRenderer {
             if (code) {
                 return forHeader ? code.replace(/;$/, "") : code;
             }
+            // A resolved op with no code/expression is a deliberate elision
+            // (sentinel facts) — emit nothing, no placeholder comment.
+            if (resolved) {
+                return "";
+            }
             return `/* unhandled awaited hal-op: ${statement.args[0].operation.operation} */`;
         }
         // Handle emit() — compile-time C++ injection
@@ -513,9 +535,16 @@ export class StatementRenderer {
             const rawText = statement.args.map(arg => this.renderEmitArg(arg)).join("");
             return forHeader ? rawText : `${rawText.endsWith(';') ? rawText : rawText + ';'}`;
         }
-        // Handle console.* calls specially
-        if (isConsoleCall(statement.callee)) {
-            return this.transformConsoleCall(statement.callee, statement.args, forHeader, knownVariableTypes);
+        // console.* is not a supported API — it was a TypeScript carry-over whose
+        // lowering (platform print + a config section routing it) cost more than
+        // it bought. Programs write to a serial console explicitly instead.
+        if (statement.callee.startsWith("console.")) {
+            this._diagnostics.push({
+                severity: "error",
+                code: "console-unsupported",
+                message: `console.${statement.callee.slice("console.".length)}() is not supported — write to a serial console instead: \`USB0.writeLine(...)\` (USB CDC) or \`UART0.writeLine(...)\` from the board module.`,
+            });
+            return "";
         }
         let callee = statement.callee;
         if (callee.startsWith("this.")) {
@@ -781,7 +810,7 @@ export class StatementRenderer {
                     ? `${arrayType} ${safeSpreadArrName}[] = { ${initializerText} }`
                     : `${arrayType} ${safeSpreadArrName}[] = { ${initializerText} };`;
             }
-            // Enum ↔ integral storage boundary (SUPPORT_MATRIX §1.7). TS lets an
+            // Enum ↔ integral storage boundary. TS lets an
             // enum and a number flow into each other freely (enums ARE numbers at
             // runtime), but the lowered C++ `enum class` has NO implicit conversion
             // in EITHER direction: `const n: int = Color.Red` AND
@@ -917,26 +946,6 @@ export class StatementRenderer {
         return inferObjectFieldType(value, this.pointerVarTypes, this.knownFunctionReturnTypes, undefined, undefined, undefined, // largeEnumNames - would need to pass through
         parentName, fieldName, this.strategy.defaultNumericType(this._compliance), (o, n) => this.strategy.resolvePinType?.(o, n));
     }
-    /**
-     * Transform console.log/error/warn calls based on target platform.
-     */
-    transformConsoleCall(callee, args, forHeader, knownVariableTypes) {
-        const method = getConsoleMethod(callee);
-        const renderedArgs = args.map((arg) => {
-            let rendered = this.expressionRenderer.render(arg, undefined, knownVariableTypes);
-            if (arg.kind === "identifier" && knownVariableTypes) {
-                const varInfo = knownVariableTypes.get(arg.value);
-                if (varInfo && this.enumNames.has(varInfo.cppType)) {
-                    rendered = `static_cast<int>(${rendered})`;
-                }
-            }
-            if (arg.kind === "property-access" && arg.isEnum) {
-                rendered = `static_cast<int>(${rendered})`;
-            }
-            return rendered;
-        }).join(" << ");
-        return this.strategy.transformConsoleCall(method, renderedArgs, forHeader);
-    }
     renderEmitArg(arg) {
         if (arg.kind === "string")
             return arg.value;

package/dist/emit/utils/async-state-machine.d.ts

@@ -5,14 +5,6 @@
  */
 import type { StatementIR } from "../../api/index.js";
 import type { PlatformStrategy } from "../../api/shared/index.js";
-/**
- * Converts a string to PascalCase.
- * Used for generating class names from function names.
- *
- * @param str The input string (e.g., "my_function" or "myFunction")
- * @returns PascalCase string (e.g., "MyFunction")
- */
-export declare function toPascalCaseLocal(str: string): string;
 /**
  * Result of generating an async task class.
  */
@@ -23,6 +15,21 @@ export interface AsyncTaskClassResult {
     instanceDecl: string;
     /** The task variable name for use in loop() */
     taskVarName: string;
+    /** For async METHODS: the definition of the starter function the in-class
+     *  body calls (binds the owner and arms STATE_0). Emitted after the task
+     *  class; the matching prototype must precede the owning class. */
+    starterDef?: string;
+}
+/** Options for generateAsyncTaskClass. */
+export interface AsyncTaskClassOptions {
+    /** Owning class name for async METHODS: the task binds `this` to an owner
+     *  pointer set by start(owner); segment code that renders `this->x` is
+     *  rewritten to `_owner->x` by the embedding renderStatement callback. */
+    ownerClassName?: string;
+    /** Invoked for every awaited call that has no cooperative lowering (the
+     *  call would be silently dropped). The emitter surfaces it as a
+     *  diagnostic instead of emitting wrong code. */
+    onUnsupportedAwait?: (callee: string, span: StatementIR["sourceSpan"] | undefined) => void;
 }
 /**
  * Generates a cooperative state-machine class for an async function.
@@ -39,4 +46,4 @@ export interface AsyncTaskClassResult {
  * @param knownFunctionReturnTypes Map of function names to their return types
  * @returns The class definition, instance declaration, and task variable name
  */
-export declare function generateAsyncTaskClass(fnName: string, fnStatements: StatementIR[], strategy: PlatformStrategy, knownFunctionReturnTypes: Map<string, string>, renderStatement: (stmt: StatementIR, forHeader: boolean, strategy: PlatformStrategy, pointerVarTypes?: Map<string, string>, calleeTransformer?: (callee: string) => string, knownFunctionReturnTypes?: Map<string, string>) => string): AsyncTaskClassResult;
+export declare function generateAsyncTaskClass(fnName: string, fnStatements: StatementIR[], strategy: PlatformStrategy, knownFunctionReturnTypes: Map<string, string>, renderStatement: (stmt: StatementIR, forHeader: boolean, strategy: PlatformStrategy, pointerVarTypes?: Map<string, string>, calleeTransformer?: (callee: string) => string, knownFunctionReturnTypes?: Map<string, string>) => string, options?: AsyncTaskClassOptions): AsyncTaskClassResult;