@typecad/cuttlefish 0.1.0-alpha.1

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

@@ -0,0 +1,189 @@
+/**
+ * Statement Renderer for C++ code emission.
+ * Encapsulates all statement rendering logic with explicit dependencies.
+ * Extracted from cpp-emitter.ts
+ */
+import type { StatementIR } 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";
+import { ExpressionRenderer } from "./expression-renderer.js";
+/**
+ * Context needed for statement rendering.
+ */
+interface StatementRendererContext {
+    /** 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) pointer variables, consulted to arrow assign/
+     *  update targets (`btn.lastPress = 1` → `btn->lastPress = 1`) when the
+     *  target's receiver is a global pointer (e.g. ISR-captured). Threaded from
+     *  EmitterContext; replaces the file-wide text sweep formerly in
+     *  output-finalizer.ts. */
+    globalPointerVarTypes?: Map<string, string>;
+    /** Set of variable names known to hold string values */
+    stringVarNames?: Set<string>;
+    /** Set of variable names known to be emitted as C arrays */
+    cArrayVarNames?: Set<string>;
+    /** Set of namespace names for scoped access (::) */
+    namespaceNames?: 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 (type-keyed fallback for getter/setter rewriting). */
+    typeAccessorNames?: Map<string, Map<string, "getter" | "setter" | "both">>;
+    /** Imported class names from other transpiled modules */
+    crossModuleClassNames?: Set<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>>;
+    /**
+     * 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 StatementIR nodes to C++ code strings.
+ */
+export declare class StatementRenderer {
+    private readonly strategy;
+    private readonly expressionRenderer;
+    private readonly knownFunctionReturnTypes;
+    private readonly pointerVarTypes?;
+    private readonly globalPointerVarTypes?;
+    private readonly classNameMap?;
+    private readonly varAccessorNames;
+    private readonly crossModuleClassNames?;
+    private readonly enumNames;
+    private readonly stringEnumNames;
+    /** Namespace names — used to rewrite assign-target `Ns.x` to `Ns::x`. */
+    private readonly namespaceNames;
+    private readonly interfaceFieldTypes;
+    /** Shared emit-time diagnostics sink (see StatementRendererContext.diagnostics). */
+    private readonly _diagnostics;
+    constructor(context: StatementRendererContext);
+    /**
+     * Gets the underlying expression renderer for direct use.
+     */
+    getExprRenderer(): ExpressionRenderer;
+    /**
+     * Renders a statement IR node to a C++ string, including any snprintf
+     * prelude lines accumulated during expression rendering.
+     *
+     * @param statement The statement to render
+     * @param forHeader Whether this is for a header file (no semicolons)
+     * @param calleeTransformer Optional transformer for callee names
+     * @param knownVariableTypes Optional override for variable type mapping
+     * @returns Object with prelude lines and the rendered statement
+     */
+    renderWithPrelude(statement: StatementIR, forHeader?: boolean, calleeTransformer?: (callee: string) => string, knownVariableTypes?: Map<string, KnownVariableInfo>): {
+        prelude: string[];
+        statement: string;
+    };
+    /**
+     * Renders a statement IR node to a C++ string.
+     *
+     * @param statement The statement to render
+     * @param forHeader Whether this is for a header file (no semicolons)
+     * @param calleeTransformer Optional transformer for callee names
+     * @param knownVariableTypes Optional override for variable type mapping
+     * @returns The C++ code string
+     */
+    render(statement: StatementIR, forHeader?: boolean, calleeTransformer?: (callee: string) => string, knownVariableTypes?: Map<string, KnownVariableInfo>): string;
+    /**
+     * Arrow the leading receiver of an assign/update target when it is a
+     * module-scope (file-global) pointer variable: `btn.lastPress` →
+     * `btn->lastPress`. This covers ISR-captured globals whose pointer type
+     * wasn't visible at IR build time (the target is a plain string here, not a
+     * property-access IR node). Only the leading receiver is rewritten — a
+     * chain like `btn->field.x` is left alone. Replaces the file-wide text sweep
+     * formerly in output-finalizer.ts.
+     */
+    private arrowGlobalPointerTarget;
+    private fixCrossModuleMethodCall;
+    private renderCall;
+    private renderVarDecl;
+    /**
+     * Renders a typed name with proper C++ syntax.
+     */
+    renderTypedName(cppType: string, name: string, isConst?: boolean, isRef?: boolean): string;
+    /**
+     * Renders function parameters.
+     * Emits `const` for parameters annotated with `Shared<T>` (ownershipKind === 'shared').
+     */
+    renderParameters(parameters: Array<{
+        name: string;
+        cppType: string;
+        defaultValue?: any;
+        isRest?: boolean;
+        ownershipKind?: 'owned' | 'shared' | 'mutable';
+    }>, forHeader?: boolean): string;
+    /**
+     * Public type-mapping entry point for emitters that emit types directly
+     * (function return types, forward declarations) rather than via
+     * renderTypedName. Applies the same string-enum → const char* substitution.
+     */
+    mapTypeForEmit(typeName: string): string;
+    /**
+     * Map a function's return type for emission. Unlike {@link mapTypeForEmit},
+     * this respects the strategy's {@code mapReturnType} contract: the value
+     * produced by {@code mapReturnType} is already final and must NOT be
+     * re-normalised. This matters for entrypoints like {@code main}, whose
+     * mapped {@code int} return type would otherwise be turned back into
+     * {@code long long} by {@code normalizeCppType}.
+     *
+     * For non-entrypoint functions we still apply the string-enum → const char*
+     * substitution (which {@code mapReturnType} does not perform), preserving
+     * existing behaviour for ordinary functions.
+     */
+    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.
+     *
+     * The entrypoint sentinel `__cuttlefish_entrypoint__` maps to the strategy's
+     * entrypoint name (`main` on native, `setup` on Arduino). For every OTHER
+     * name we delegate to `strategy.mapFunctionName`, which is where a target
+     * can rename a user function that would otherwise collide with a C++/
+     * framework reserved name — e.g. the Arduino strategy renames a user
+     * `function main()` to `cuttlefish_main`, because Arduino has no `main()`
+     * (the entrypoints are the auto-generated `setup()`/`loop()`), and a
+     * file-scope `static void main()` collides with C++'s required `int main()`
+     * signature. Routing every name through the strategy here is the single
+     * place that makes such renames actually take effect at emit time.
+     */
+    mapFunctionName(originalName: string): string;
+    /**
+     * Map a TypeScript return type to its C++ equivalent for a specific function.
+     */
+    mapReturnType(fnName: string, tsType: string): string;
+}
+export {};