@typecad/cuttlefish 0.1.0-alpha.1

package/dist/emit/emitters/emitter-context.d.ts

@@ -0,0 +1,174 @@
+import type { ProgramIR, StatementIR, ParameterIR } from "../../api/index.js";
+import type { PlatformStrategy } from "../../api/shared/index.js";
+import type { ProgramAnalysisResult } from "../../ir/program-analysis.js";
+import type { EmissionScopeState } from "../snprintf-helpers.js";
+import type { ExpressionRenderer } from "../expression-renderer.js";
+import type { StatementRenderer } from "../statement-renderer.js";
+import type { Diagnostic, EmitMode, SourceMapEntry, SourceSpan } from "../../types.js";
+import type { ResolvedNpmPackage } from "../../transpile/resolution.js";
+import type { BoardConstants } from "../../ir/board-resolver.js";
+import type { LibraryDefinition } from "../../types.js";
+/** Options controlling C++ emission. */
+export interface EmitterOptions {
+    outDir: string;
+    emitMode: EmitMode;
+    target: string;
+    libdefs: Map<string, LibraryDefinition>;
+    emitMaps: boolean;
+    platformContext?: Record<string, unknown>;
+    npmPackage?: ResolvedNpmPackage;
+    npmPackages?: Map<string, ResolvedNpmPackage>;
+    isEntryFile?: boolean;
+    strategy?: PlatformStrategy;
+    nativeModules?: Map<string, {
+        declPath: string;
+        cppPath: string;
+        moduleKey: string;
+    }>;
+    crossModuleClasses?: Set<string>;
+    crossModuleClassFieldTypes?: Map<string, Map<string, string>>;
+    /** Getters/setters declared on classes in OTHER files, keyed by class name.
+     * Lets `obj.getter` access rewrite to `obj->getX()`/`Cls::getX()` even when
+     * the class is imported (demo #14 Finding E — cross-file getter access). */
+    crossModuleClassAccessors?: Map<string, Map<string, "getter" | "setter" | "both">>;
+    crossModuleFunctionReturnTypes?: Map<string, string>;
+    crossModuleEnumNames?: Set<string>;
+    crossModuleStringEnumNames?: Set<string>;
+    crossModuleVariableTypes?: Map<string, string>;
+}
+export interface MappedFunction {
+    name: string;
+    returnType: string;
+    sourceSpan: SourceSpan;
+    leadingComments?: string[];
+    trailingComments?: string[];
+    parameters: ParameterIR[];
+    isAsync?: boolean;
+    typeParameters?: string[];
+    typeParameterConstraints?: Map<string, string>;
+    isReadonlyReturnType?: boolean;
+    isGenerator?: boolean;
+    isExported?: boolean;
+    statements: StatementIR[];
+}
+export interface CallbackFunction {
+    name: string;
+    params: string[];
+    statements: StatementIR[];
+    debounceMs?: number;
+    /**
+     * Return type of the synthesized free function. Defaults to "void" (the
+     * historical ISR/HAL-callback case). Populated from a hoisted lambda's
+     * return-type annotation so a `(x): int16_t => {...}` callback lowers to
+     * `int16_t name(int16_t)` rather than `void name()`.
+     */
+    returnType?: string;
+    /**
+     * Typed parameters of the synthesized free function, carrying both the C++
+     * type and the name. Defaults to [] (the void() ISR case). Populated from a
+     * hoisted lambda's typed params. Used both to render the signature and to
+     * seed the body's emission scope so the params are resolvable.
+     */
+    typedParams?: {
+        name: string;
+        cppType: string;
+    }[];
+}
+export interface AsyncTaskClass {
+    classDef: string;
+    instanceDecl: string;
+    taskVarName: string;
+}
+export interface FixPointerFieldAccessFn {
+    (callee: string): string;
+}
+/**
+ * Shared state bag passed between all sub-emitter steps.
+ */
+export interface EmitterContext {
+    program: ProgramIR;
+    options: EmitterOptions;
+    strategy: PlatformStrategy;
+    programAnalysis: ProgramAnalysisResult;
+    enumNames: Set<string>;
+    stringEnumNames: Set<string>;
+    largeEnumNames: Set<string>;
+    namespaceNames: Set<string>;
+    symbolMap: Record<string, string>;
+    includes: string[];
+    shimLines: string[];
+    baseName: string;
+    effectiveEmitMode: EmitMode;
+    isEntryFile: boolean;
+    isNpmPackage: boolean;
+    isrPrefix: string;
+    reservedNames: ReadonlySet<string>;
+    knownFunctionReturnTypes: Map<string, string>;
+    mappedFunctions: MappedFunction[];
+    /**
+     * Names of non-exported free functions that are CALLED from at least one
+     * class method body (a getter/setter/method/constructor). In split mode an
+     * inline class method body lives in the header, so such a function must be
+     * visible in the header too — otherwise the method body sees
+     * "'fn' was not declared in this scope". These functions are therefore
+     * emitted non-static with a header prototype (like exported functions).
+     * Demo #18 Finding B.
+     */
+    freeFunctionsCalledFromClassMethods: Set<string>;
+    topLevelScope: EmissionScopeState;
+    snprintfCounter: {
+        value: number;
+    };
+    stringVarNames: Set<string>;
+    varAccessorNames: Map<string, Map<string, "getter" | "setter" | "both">>;
+    exprRenderer: ExpressionRenderer;
+    statementRenderer: StatementRenderer;
+    classNameMap?: Map<string, string>;
+    boardConstants?: BoardConstants;
+    restParamFunctions?: Map<string, string>;
+    asyncTaskClasses: AsyncTaskClass[];
+    asyncFunctionOriginalNames: Set<string>;
+    asyncFunctionMappedNames: Set<string>;
+    hasAsyncRuntime: boolean;
+    hasPromiseRuntime: boolean;
+    usesTimers: boolean;
+    emittedPolyfills?: {
+        declarations: string[];
+        definitions: string[];
+        includes: string[];
+    };
+    sourceLines: string[];
+    headerLines: string[];
+    sourceMapEntries: SourceMapEntry[];
+    headerMapEntries: SourceMapEntry[];
+    cArrayVarNames: Set<string>;
+    fnCArrayVarNames: Map<string, Set<string>>;
+    globalPointerVarTypes: Map<string, string>;
+    promotedVarDecls: Map<string, {
+        cppType: string;
+        index: number;
+    }>;
+    callbackFunctions: CallbackFunction[];
+    filteredTopLevelExecutables: StatementIR[];
+    filteredTopLevelDeclarations: StatementIR[];
+    emittedTopLevelStatements: StatementIR[];
+    compiletimeVarNames: Set<string>;
+    fixPointerFieldAccess: FixPointerFieldAccessFn;
+    knownTopLevelObjectTypes: Map<string, string>;
+    knownTopLevelObjectFields: Map<string, Map<string, string>>;
+    currentClassPointerFields?: string[];
+    currentClassPointerFieldTypes?: Map<string, string>;
+    profileDiagnostics: Diagnostic[];
+    /**
+     * Diagnostics produced during emission (e.g. an unregistered HAL operation
+     * the strategy couldn't resolve, surfaced as a warning). Kept separate from
+     * profileDiagnostics for clarity; merged into the final diagnostics list by
+     * finalizeOutput. Shared by reference with ExpressionRenderer /
+     * StatementRenderer so their fallback paths can report without throwing.
+     */
+    emitDiagnostics: Diagnostic[];
+    templateInterfaceNames: Set<string>;
+    interfaceNamespaceMap: Map<string, string>;
+    /** Map of interface name to its field types (e.g., "Task" -> Map("id" -> "std::string", "title" -> "std::string")) */
+    interfaceFieldTypes: Map<string, Map<string, string>>;
+}

package/dist/emit/emitters/emitter-context.js

@@ -0,0 +1 @@
+export {};

package/dist/emit/emitters/entrypoint-synthesizer.d.ts

@@ -0,0 +1,2 @@
+import type { EmitterContext } from "./emitter-context.js";
+export declare function synthesizeEntrypoints(ctx: EmitterContext): void;

package/dist/emit/emitters/entrypoint-synthesizer.js

@@ -0,0 +1,175 @@
+import { entryHasUI } from "../../ui-hook.js";
+import { uiPressBindings, watchPinSpecs } from "../../ir/transformers/ui-call-resolver.js";
+import { getDisplayProfile } from "../../stores/display-profile-store.js";
+function isDisplayInitStatement(statement) {
+    return statement.kind === "hal-op" && statement.operation.operation === "display.init";
+}
+export function synthesizeEntrypoints(ctx) {
+    const { program, strategy, isEntryFile, mappedFunctions } = ctx;
+    const entrypointFunctionName = strategy.entrypointFunctionName();
+    // Merge top-level executables into the entrypoint function
+    if (isEntryFile && ctx.filteredTopLevelExecutables.length > 0) {
+        const epName = entrypointFunctionName;
+        const existingEp = mappedFunctions.find(fn => fn.name === epName);
+        const setupInitLines = strategy.setupInitCode?.(program, ctx.options.platformContext) ?? [];
+        const setupInitStmts = setupInitLines.map(line => ({
+            kind: "call",
+            callee: `__RAW_STMT__${line}`,
+            args: [],
+            sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 },
+        }));
+        const displayInitStmts = [];
+        const topLevelExecutableStmts = ctx.filteredTopLevelExecutables.filter((statement) => {
+            if (isDisplayInitStatement(statement)) {
+                displayInitStmts.push(statement);
+                return false;
+            }
+            return true;
+        });
+        // UI hardware/runtime setup. Only emitted when a UI is mounted.
+        const uiSetupStmts = [];
+        if (entryHasUI()) {
+            // Touch controller begin (if touch is configured). Hardware setup runs
+            // before ui_init() so the first frame starts from a fully initialized
+            // display/touch stack.
+            const tProfile = getDisplayProfile();
+            if (tProfile.touch) {
+                uiSetupStmts.push({ kind: "call", callee: `__RAW_STMT__touch_init();`, args: [],
+                    sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 } });
+            }
+            // ISR-based press/release wiring (legacy) + pin-watchers (ui.watchPin).
+            // These are GPIO-hardware APIs: pinMode/attachInterrupt/digitalPinToInterrupt
+            // are Arduino core symbols, and ui_poll_inputs reads pins via digitalRead.
+            // On a host target with no GPIO (SDL native: strategy.modelsGpio()===false)
+            // they have no equivalent — emitting them yields undefined symbols or a
+            // silent no-op. Gate on modelsGpio and surface a clear diagnostic instead.
+            const modelsGpio = strategy.modelsGpio?.() ?? true;
+            const pressBindings = uiPressBindings();
+            const pinWatchers = watchPinSpecs();
+            if (!modelsGpio && (pressBindings.length > 0 || pinWatchers.length > 0)) {
+                const which = pressBindings.length > 0 && pinWatchers.length > 0
+                    ? "ui.press and ui.watchPin"
+                    : pressBindings.length > 0 ? "ui.press" : "ui.watchPin";
+                ctx.emitDiagnostics.push({
+                    severity: "error",
+                    code: "gpio-unsupported-on-target",
+                    message: `${which} require GPIO hardware, which this target (${ctx.options.target}) does not model. Use the browser preview to exercise pin-driven UI, or target @typecad/framework-arduino.`,
+                    source: program.fileName,
+                });
+            }
+            if (modelsGpio) {
+                for (const pb of pressBindings) {
+                    const mode = pb.edge === "press" ? "FALLING" : "RISING";
+                    uiSetupStmts.push({ kind: "call", callee: `__RAW_STMT__pinMode(${pb.pin}, INPUT_PULLUP);`, args: [],
+                        sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 } }, { kind: "call", callee: `__RAW_STMT__attachInterrupt(digitalPinToInterrupt(${pb.pin}), ${pb.handlerName}, ${mode});`, args: [],
+                        sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 } });
+                }
+                // Pin-watchers (from ui.watchPin): set pin mode so ui_poll_inputs can read it
+                for (const wp of pinWatchers) {
+                    uiSetupStmts.push({ kind: "call", callee: `__RAW_STMT__pinMode(${wp.pin}, INPUT_PULLUP);`, args: [],
+                        sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 } });
+                }
+            }
+            // Initial draw: mark all UI nodes dirty so the first ui_tick renders.
+            uiSetupStmts.push({ kind: "call", callee: `__RAW_STMT__ui_init();`, args: [],
+                sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 } });
+        }
+        const allSetupInitStmts = [...setupInitStmts, ...displayInitStmts, ...uiSetupStmts];
+        if (existingEp) {
+            existingEp.statements = [...allSetupInitStmts, ...topLevelExecutableStmts, ...existingEp.statements];
+        }
+        else {
+            const isMain = epName === "main";
+            // Route through mapReturnType so platform strategies can special-case the
+            // entrypoint signature (e.g. NativeStrategy keeps main → int instead of
+            // normalizing int → long long). The emitted return type is then treated
+            // as final by mapReturnTypeForEmit (no re-normalisation).
+            const mapReturnType = (fnName, tsType) => ctx.statementRenderer.mapReturnType(fnName, tsType);
+            const returnType = mapReturnType(epName, isMain ? "int" : "void");
+            const stmts = isMain
+                ? [...allSetupInitStmts, ...topLevelExecutableStmts, { kind: "return", sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 }, value: { kind: "number", value: 0 } }]
+                : [...allSetupInitStmts, ...topLevelExecutableStmts];
+            const insertFn = {
+                name: epName,
+                originalName: epName,
+                returnType,
+                sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 },
+                leadingComments: [`// Auto-generated ${epName}() for top-level statements`],
+                trailingComments: undefined,
+                parameters: [],
+                isAsync: false,
+                typeParameters: undefined,
+                typeParameterConstraints: undefined,
+                isReadonlyReturnType: false,
+                statements: stmts,
+            };
+            if (isMain) {
+                mappedFunctions.push(insertFn);
+            }
+            else {
+                mappedFunctions.unshift(insertFn);
+            }
+        }
+    }
+    // Ensure the entrypoint function exists even when all executables were filtered
+    if (isEntryFile && !mappedFunctions.some((fn) => fn.name === entrypointFunctionName)) {
+        const isMain = entrypointFunctionName === "main";
+        const mapReturnType = (fnName, tsType) => ctx.statementRenderer.mapReturnType(fnName, tsType);
+        const returnType = mapReturnType(entrypointFunctionName, isMain ? "int" : "void");
+        const stmts = isMain
+            ? [{ kind: "return", sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 }, value: { kind: "number", value: 0 } }]
+            : [];
+        const insertFn = {
+            name: entrypointFunctionName,
+            returnType,
+            sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 },
+            leadingComments: undefined,
+            trailingComments: undefined,
+            parameters: [],
+            isAsync: false,
+            typeParameters: undefined,
+            typeParameterConstraints: undefined,
+            isReadonlyReturnType: false,
+            statements: stmts,
+        };
+        if (isMain) {
+            mappedFunctions.push(insertFn);
+        }
+        else {
+            mappedFunctions.unshift(insertFn);
+        }
+    }
+    // Some platforms require a loop function even if empty
+    if (isEntryFile && strategy.requiresLoopFunction() && !mappedFunctions.some((fn) => fn.name === "loop")) {
+        mappedFunctions.push({
+            name: "loop",
+            returnType: "void",
+            sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 },
+            leadingComments: ctx.hasAsyncRuntime ? ["// Auto-generated loop() for async microtask pumping"] : undefined,
+            trailingComments: undefined,
+            parameters: [],
+            isAsync: false,
+            typeParameters: undefined,
+            typeParameterConstraints: undefined,
+            isReadonlyReturnType: false,
+            statements: [],
+        });
+    }
+    // Only generate main() for entry files when there's no loop-based strategy
+    if (isEntryFile && ctx.hasAsyncRuntime && !strategy.requiresLoopFunction() && !mappedFunctions.some((fn) => fn.name === "main")) {
+        const mapReturnType = (fnName, tsType) => ctx.statementRenderer.mapReturnType(fnName, tsType);
+        mappedFunctions.push({
+            name: "main",
+            returnType: mapReturnType("main", "int"),
+            sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 },
+            leadingComments: ["// Auto-generated main() for async microtask pumping"],
+            trailingComments: undefined,
+            parameters: [],
+            isAsync: false,
+            typeParameters: undefined,
+            typeParameterConstraints: undefined,
+            isReadonlyReturnType: false,
+            statements: [{ kind: "return", sourceSpan: { filePath: program.fileName, startOffset: 0, endOffset: 0, startLine: 1, startColumn: 1, endLine: 1, endColumn: 1 }, value: { kind: "number", value: 0 } }],
+        });
+    }
+}

package/dist/emit/emitters/function-emitter-impl.d.ts

@@ -0,0 +1,19 @@
+import type { EmitterContext } from "./emitter-context.js";
+export declare function emitPostClassDeclarations(ctx: EmitterContext): void;
+export declare function emitCallbackFunctions(ctx: EmitterContext): void;
+export declare function emitFunctions(ctx: EmitterContext): void;
+/**
+ * Emit forward declarations for ALL free functions (and ISR callbacks) BEFORE
+ * class bodies. A class method may call a free function declared later in the
+ * same source file; if that function's forward declaration only appears after
+ * the class (as it did historically via emitCallbackFunctions/emitFunctions),
+ * g++ reports "'fn' was not declared in this scope" inside the class body.
+ *
+ * This runs at cpp-emitter.ts step 6.5, ahead of emitClasses (step 7). The
+ * definition-only emission in emitCallbackFunctions/emitFunctions below no
+ * longer re-emits these declarations (they are dropped there to avoid
+ * duplicates). Template/generic functions get template prototypes here so
+ * earlier functions can call them before their definitions later in the same
+ * translation unit.
+ */
+export declare function emitFunctionForwardDeclarations(ctx: EmitterContext): void;