@typecad/cuttlefish 0.1.0-alpha.1

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

@@ -0,0 +1,283 @@
+/**
+ * Expression Renderer for C++ code emission.
+ * Encapsulates all expression rendering logic with explicit dependencies.
+ * Extracted from cpp-emitter.ts
+ */
+import type { ExpressionIR } from "../api/index.js";
+import type { PlatformStrategy } from "../api/shared/index.js";
+import type { BoardConstants } from "../ir/board-resolver.js";
+import type { KnownVariableInfo } from "../api/shared/index.js";
+import type { Diagnostic } from "../types.js";
+/**
+ * Context needed for expression rendering.
+ */
+interface ExpressionRendererContext {
+    /** The platform strategy for target-specific rendering */
+    strategy: PlatformStrategy;
+    /** Board constants for Board.definition.* access */
+    boardConstants?: BoardConstants;
+    /** Map of class simple names to fully qualified names (framework library imports) */
+    classNameMap?: Map<string, string>;
+    /** Set of enum names for scoped enum access (::) */
+    enumNames: Set<string>;
+    /** Set of string enum names (lowered to const char* namespaces; members are const char*) */
+    stringEnumNames?: Set<string>;
+    /** Set of enum names with values outside 16-bit int range */
+    largeEnumNames: Set<string>;
+    /** Map of function names to their return types */
+    knownFunctionReturnTypes?: Map<string, string>;
+    /** Map of variable names to their inferred C++ types (for snprintf format specifiers) */
+    knownVariableTypes?: Map<string, KnownVariableInfo>;
+    /** Map of variable names to their pointer types */
+    pointerVarTypes?: Map<string, string>;
+    /** Module-scope (file-global) variables resolved to pointer C++ types, used
+     *  to decide `->` vs `.` when a bare identifier resolves to a global pointer
+     *  (e.g. an ISR-captured `const btn = new Button()` accessed inside a hoisted
+     *  callback, where the local-scope type map is empty). Replaces the
+     *  file-wide `\b${name}\.` → `${name}->` text sweep that previously patched
+     *  this in output-finalizer.ts. */
+    globalPointerVarTypes?: Map<string, string>;
+    /** Set of variable names known to hold string values (for snprintf %s) */
+    stringVarNames?: Set<string>;
+    /** Set of variable names known to be emitted as C arrays */
+    cArrayVarNames?: Set<string>;
+    /** Set of namespace names for scoped access (::) instead of (.) */
+    namespaceNames?: Set<string>;
+    /** Cross-module class names recognized by the expression renderer. */
+    crossModuleClassNames?: Set<string>;
+    /** Map of variable names to their class's accessor map for getter/setter rewriting */
+    varAccessorNames?: Map<string, Map<string, "getter" | "setter" | "both">>;
+    /**
+     * Map of class type names to their accessor map. Used as a fallback when a
+     * member access's receiver isn't in `varAccessorNames` (e.g. a for-of loop
+     * variable, a function-call return, or a chained access) but its resolved
+     * C++ type names a class with getters. Lets the getter rewrite
+     * (`obj.prop` → `obj->getProp()`) fire for any pointer-valued receiver of a
+     * known class type, not just `this` and explicitly-registered variables.
+     */
+    typeAccessorNames?: Map<string, Map<string, "getter" | "setter" | "both">>;
+    /** Optional transformer for expression values */
+    exprTransformer?: (expr: string) => string;
+    /** Shared counter for unique snprintf buffer names across statement renders */
+    snprintfCounter?: {
+        value: number;
+    };
+    /** Map of interface/type name to field C++ types */
+    interfaceFieldTypes?: Map<string, Map<string, string>>;
+    /** Names of top-level const object variables (e.g. `const CONFIG = {...}`),
+     *  used to distinguish `.` member access on an instance from `::` on a
+     *  namespace/class. */
+    knownTopLevelObjectTypes?: Map<string, string>;
+    /**
+     * Shared sink for emit-time diagnostics. When provided, the renderer's
+     * fallback paths (e.g. an unregistered HAL operation) push structured
+     * warnings here instead of silently emitting placeholder comments. The
+     * array is the same one finalizeOutput merges into the final diagnostics
+     * list. Optional so ad-hoc/test constructions still work.
+     */
+    diagnostics?: Diagnostic[];
+}
+/**
+ * Renders ExpressionIR nodes to C++ code strings.
+ */
+export declare class ExpressionRenderer {
+    private readonly strategy;
+    private readonly boardConstants?;
+    private readonly classNameMap?;
+    private readonly enumNames;
+    private readonly stringEnumNames;
+    private readonly largeEnumNames;
+    private readonly knownFunctionReturnTypes?;
+    private readonly knownVariableTypes?;
+    private readonly pointerVarTypes?;
+    private readonly globalPointerVarTypes?;
+    private readonly stringVarNames?;
+    private readonly cArrayVarNames?;
+    private readonly namespaceNames;
+    private readonly varAccessorNames;
+    private readonly typeAccessorNames;
+    private readonly interfaceFieldTypes;
+    private readonly knownTopLevelObjectTypes?;
+    /** Accumulated snprintf prelude lines (buffer declarations, dtostrf calls, snprintf calls). */
+    private _preludeLines;
+    /** Monotonic counter for unique snprintf buffer names. Shared across renders when provided. */
+    private _snprintfCounter;
+    /** Shared emit-time diagnostics sink (see ExpressionRendererContext.diagnostics). */
+    private readonly _diagnostics;
+    constructor(context: ExpressionRendererContext);
+    /**
+     * Gets the board constants (for access by statement renderer).
+     */
+    getBoardConstants(): BoardConstants | undefined;
+    /**
+     * Clear accumulated prelude lines. Call before each top-level render.
+     */
+    clearPrelude(): void;
+    /**
+     * Drain accumulated prelude lines and clear. The caller is responsible
+     * for emitting these lines before the statement that uses the expression.
+     */
+    drainPrelude(): string[];
+    /**
+     * Push lines directly into the prelude buffer. Used by the statement renderer
+     * to inject multi-statement expansions (e.g. Wire read setup) that must appear
+     * before the surrounding statement.
+     */
+    pushPrelude(lines: string[]): void;
+    /**
+     * Renders an expression IR node to a C++ string.
+     *
+     * @param expr The expression to render
+     * @param exprTransformer Optional transformer for raw expressions
+     * @param knownVariableTypes Optional override for variable type mapping
+     * @returns The C++ code string
+     */
+    render(expr: ExpressionIR, exprTransformer?: (expr: string) => string, knownVariableTypes?: Map<string, KnownVariableInfo>): string;
+    private renderIdentifier;
+    private renderRaw;
+    private renderTernary;
+    private normalizeRecordType;
+    private inferExpressionCppType;
+    /**
+     * True when a C++ type name denotes a string value: either the strategy's
+     * built-in string-like types (std::string, const char*, Arduino String, …)
+     * OR a TypeScript string-enum name, which is lowered to `const char*`.
+     */
+    private isStringLikeCppType;
+    private shouldSkipStringWrap;
+    /**
+     * Resolve an expression to its C++ type when possible (consulting
+     * `knownVariableTypes`, interface/class field type maps, enum/string-enum
+     * sets, etc.). Returns `undefined` when the type cannot be determined.
+     *
+     * Public so emit-layer callers (e.g. the switch emitter in line-appender)
+     * can make type-aware lowering decisions — see demo #16 gap #1: a `switch`
+     * on a struct field of enum type must not be wrapped in `std::string(...)`.
+     */
+    inferCppType(expr: ExpressionIR, knownVariableTypes?: Map<string, KnownVariableInfo>): string | undefined;
+    private renderKnownStringValue;
+    private renderStringConcat;
+    private renderTemplateString;
+    /**
+     * Build snprintf format string and args from string_concat parts.
+     * Returns the buffer name on success, or undefined if snprintf can't handle it.
+     */
+    private buildSnprintfFromParts;
+    /**
+     * Infer printf format specifier for an expression.
+     * Returns format string, rendered arg, estimated length, and optional prelude lines, or undefined if unknown.
+     */
+    inferFormatSpecifier(expr: ExpressionIR, exprTransformer?: (expr: string) => string, knownVariableTypes?: Map<string, KnownVariableInfo>): {
+        format: string;
+        arg: string;
+        estimatedLength: number;
+        preludeLines?: string[];
+    } | undefined;
+    private renderArray;
+    private renderObject;
+    private renderSpreadArray;
+    private renderInstanceof;
+    private renderElementAccess;
+    private isEnumComparisonOperand;
+    /**
+     * Render an expression value that will be assigned to a non-enum lvalue,
+     * passed as a non-enum argument, or otherwise consumed where C++ `enum class`
+     * won't implicitly convert. If the value is a numeric-enum operand, wrap it
+     * in `static_cast<int>(...)` so it composes with int-typed targets (e.g.
+     * `links[0] = LinkFlag.Wired` → `links[0] = static_cast<int>(LinkFlag::Wired)`).
+     * 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++.
+     */
+    renderEnumSafeValue(expr: ExpressionIR, knownVariableTypes?: Map<string, KnownVariableInfo>): string;
+    /**
+     * Render a value that will be stored into an lvalue of a known C++ type
+     * (an `assign` target, a `var_decl` initializer, a `push_back` argument,
+     * ...). Centralizes the **enum ↔ integral storage boundary** so every
+     * assignment/initialization site lowers consistently:
+     *
+     *   - target is a numeric C++ type, value is a numeric-enum operand →
+     *     `static_cast<int>(value)` (enum → int). This is the existing
+     *     `renderEnumSafeValue` direction, now driven by the target type
+     *     instead of duplicated per site.
+     *   - target is a C++ `enum class`, value is a numeric/element-access
+     *     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.
+     *
+     * This closes the "enum↔integral storage boundary" family — the previous
+     * point-specific casts handled enum-as-array-index (demo #28 E) and
+     * enum-as-Map-key (demo #28 E review) but NOT enum stored into integral
+     * storage, integral storage read back into an enum, or an enum value
+     * passed to `push_back` on an integral-element vector. Demo #32 Finding A.
+     *
+     * String enums (`const char*`) and string-like targets are passed through
+     * unchanged. Unknown/auto target types are passed through unchanged
+     * (safer than a wrong cast).
+     */
+    renderValueForTarget(expr: ExpressionIR, targetType: string | undefined, knownVariableTypes?: Map<string, KnownVariableInfo>, exprTransformer?: (expr: string) => string): string;
+    /**
+     * Resolve a rendered C++ lvalue STRING (the `target` carried by an `assign`
+     * IR node, e.g. `this->nxt[r][c]`, `cells[i]`, `flag`) to its declared C++
+     * element/value type. This is the string-target counterpart to
+     * `inferExpressionCppType`'s element-access / property-access / identifier
+     * branches: the assign target is already rendered to text at IR-build time,
+     * so the emit layer must recover its type from the text + the shared type
+     * maps (the same maps `inferExpressionCppType` consults).
+     *
+     * Structural, not regex-rewrite: it splits the base from trailing `[...]`
+     * subscripts, resolves the base via the class-field / local / global-pointer
+     * maps, then unwraps one `std::vector<T>` / `StaticArray<T,N>` layer per
+     * subscript. Returns `undefined` when the type can't be resolved confidently
+     * — callers fall through to plain rendering (never an incorrect cast).
+     * Demo #32 Finding A.
+     */
+    inferLvalueCppType(target: string, knownVariableTypes?: Map<string, KnownVariableInfo>): string | undefined;
+    /**
+     * Resolve a subscript-free rendered base (`this->field`, `obj->field`,
+     * `obj.field`, or a bare local name) to its declared C++ type. The string
+     * counterpart of `inferExpressionCppType`'s identifier / property-access
+     * branches. Demo #32 Finding A.
+     */
+    private resolveLvalueBaseType;
+    /**
+     * Shared enum-operand wrapping for binary operators. Detects whether each
+     * side is a numeric-enum operand (excluding string enums), casts it to int,
+     * and applies defensive symmetry: if exactly one side is an enum, the other
+     * side is also cast so the operator sees `int op int`. Returns the
+     * (possibly rewrapped) left and right strings.
+     *
+     * Used by the arithmetic, bitwise, and comparison branches of renderBinary
+     * so the enum-cast logic lives in one place rather than three.
+     */
+    private castEnumOperandsForOperator;
+    /**
+     * Returns true when an expression is a string-enum member access, i.e. it
+     * resolves to a `constexpr const char*` (e.g. `Color.Red` where Color is a
+     * TS string enum). Such operands must NOT be static_cast<int>'d in
+     * comparisons — they compare as C-strings instead.
+     */
+    private isStringEnumOperand;
+    private getNumericEnumOperandName;
+    private renderBinary;
+    private renderUnary;
+    private renderPropertyAccess;
+    private renderCallback;
+    private renderLambda;
+    private renderMethodCall;
+    private escapeFinalMemberName;
+}
+/**
+ * Normalizes a raw expression string for C++ output.
+ * Handles === to == conversion, enum access, and class name transformation.
+ */
+export declare function normalizeRawExpression(value: string, strategy: PlatformStrategy, classNameMap?: Map<string, string>): string;
+/**
+ * Transform type names to their fully qualified names (with namespaces).
+ * E.g., "SHT3x*" -> "Microfire::SHT3x*", "SHT3x" -> "Microfire::SHT3x"
+ */
+export declare function transformTypeName(cppType: string, classNameMap: Map<string, string> | undefined): string;
+export {};