@typecad/cuttlefish 0.1.0-alpha.1

package/dist/emit/utils/include-resolver.js

@@ -0,0 +1,155 @@
+/**
+ * Include resolution utilities for C++ code emission.
+ * Handles import resolution, SDK detection, and header normalization.
+ * Extracted from cpp-emitter.ts
+ */
+import path from "node:path";
+import fs from "node:fs";
+/**
+ * Checks if a module specifier resolves to a TypeCAD SDK path.
+ * Cuttlefish SDK files (code/core/*, code/board-*, @typecad/* packages) are
+ * type-level only and should produce no C++ output or #include directives.
+ *
+ * @param moduleSpecifier The import specifier (e.g., "@typecad/hal" or "./pins")
+ * @param fromFile The file path from which the import originates
+ * @returns true if this is a TypeCAD SDK import
+ */
+export function isCuttlefishSDKImport(moduleSpecifier, fromFile) {
+    // All @typecad/* package imports — including the `@typecad/hal` virtual
+    // import, which resolves to the board package — are type-level only and must
+    // not emit a C++ #include. Compare case-insensitively so the documented
+    // mixed-case form is treated identically.
+    const spec = moduleSpecifier.toLowerCase();
+    if (spec.startsWith("@typecad/")) {
+        return true;
+    }
+    // Check for relative imports to code/core or code/board-* paths
+    if (!moduleSpecifier.startsWith(".")) {
+        return false;
+    }
+    const basePath = path.resolve(path.dirname(fromFile), moduleSpecifier);
+    const candidates = [
+        basePath,
+        `${basePath}.ts`,
+        `${basePath}.tsx`,
+        path.join(basePath, "index.ts"),
+        path.join(basePath, "index.tsx"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            const normalized = candidate.replace(/\\/g, "/");
+            if (/\/code\/core\//.test(normalized) || /\/code\/board-/.test(normalized)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Normalizes an include path to proper C++ include format.
+ *
+ * @param include The include path (e.g., "Arduino.h" or "<vector>")
+ * @returns Properly formatted include (e.g., "<Arduino.h>" or "<vector>")
+ */
+export function normalizeInclude(include) {
+    if (include.startsWith("<") || include.startsWith("\"")) {
+        return include;
+    }
+    return `<${include}>`;
+}
+/**
+ * Deduplicates an array while preserving order.
+ *
+ * @param items The array to deduplicate
+ * @returns A new array with duplicates removed
+ */
+export function dedupe(items) {
+    return [...new Set(items)];
+}
+/**
+ * Resolves an import to a local header file if it's from a transpiled npm package.
+ *
+ * @param moduleSpecifier The import specifier
+ * @param npmPackages Map of source paths to npm package info
+ * @param fromFilePath The file path from which the import originates
+ * @returns Information about the resolved include
+ */
+export function resolveTranspiledModuleInclude(moduleSpecifier, npmPackages, fromFilePath) {
+    if (!npmPackages || npmPackages.size === 0) {
+        return { include: "", isTranspiled: false };
+    }
+    if (moduleSpecifier.startsWith(".")) {
+        const normalizedSpecifier = moduleSpecifier.endsWith(".js")
+            ? `${moduleSpecifier.slice(0, -3)}.ts`
+            : moduleSpecifier.endsWith(".mjs")
+                ? `${moduleSpecifier.slice(0, -4)}.ts`
+                : moduleSpecifier;
+        const basePath = path.resolve(path.dirname(fromFilePath), normalizedSpecifier);
+        const candidates = [
+            basePath,
+            `${basePath}.ts`,
+            `${basePath}.tsx`,
+            path.join(basePath, "index.ts"),
+            path.join(basePath, "index.tsx"),
+        ].map((candidate) => path.resolve(candidate));
+        for (const candidate of candidates) {
+            const pkg = npmPackages.get(candidate);
+            if (!pkg) {
+                continue;
+            }
+            const currentPkg = npmPackages.get(path.resolve(fromFilePath));
+            let headerName = `${pkg.moduleKey}.h`;
+            if (currentPkg) {
+                const currentDir = path.posix.dirname(currentPkg.moduleKey.replace(/\\/g, "/"));
+                const targetPath = `${pkg.moduleKey.replace(/\\/g, "/")}.h`;
+                let relativeHeader = path.posix.relative(currentDir, targetPath);
+                if (!relativeHeader.startsWith(".")) {
+                    relativeHeader = `./${relativeHeader}`;
+                }
+                headerName = relativeHeader;
+            }
+            return { include: `"${headerName}"`, isTranspiled: true };
+        }
+        return { include: "", isTranspiled: false };
+    }
+    // Parse the module specifier to get package name and subpath
+    const parts = moduleSpecifier.split("/");
+    let packageName;
+    let subpath;
+    if (moduleSpecifier.startsWith("@")) {
+        packageName = parts.length > 1 ? `${parts[0]}/${parts[1]}` : parts[0];
+        subpath = parts.length > 2 ? parts.slice(2).join("/") : "";
+    }
+    else {
+        packageName = parts[0];
+        subpath = parts.length > 1 ? parts.slice(1).join("/") : "";
+    }
+    // Look for a matching npm package in our transpiled modules
+    // The npmPackages map is keyed by source path, so we need to iterate
+    for (const [sourcePath, pkg] of npmPackages) {
+        // Match by package name (e.g., "@typecad/hal" or "cuttlefish-implementation")
+        if (pkg.packageName === packageName) {
+            // Use the moduleKey from the package info, which is already computed
+            const headerName = `${pkg.moduleKey}.h`;
+            return { include: `"${headerName}"`, isTranspiled: true };
+        }
+    }
+    return { include: "", isTranspiled: false };
+}
+/**
+ * Applies a symbol map to a callee string.
+ * Transforms root identifiers according to the mapping.
+ *
+ * @param callee The original callee (e.g., "console.log" or "myFunc")
+ * @param symbolMap Map of original names to transformed names
+ * @returns The transformed callee
+ */
+export function applySymbolMap(callee, symbolMap) {
+    const firstDot = callee.indexOf(".");
+    if (firstDot === -1) {
+        return symbolMap[callee] ?? callee;
+    }
+    const root = callee.slice(0, firstDot);
+    const rest = callee.slice(firstDot);
+    return `${symbolMap[root] ?? root}${rest}`;
+}

package/dist/emit/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Emitter utilities barrel export.
+ * Re-exports all utility functions for C++ code emission.
+ */
+export { inferObjectFieldType, collectNestedStructDefs, hasArrayInObjectLiteral, hasThrowStatements, hasStdMathCalls, hasConsoleCalls, isConsoleCall, getConsoleMethod, isRuntimeExpression, statementRequiresRuntime, collectPointerVarTypes, collectExpressionIdentifiers, } from "./type-inference.js";
+export { toPascalCaseLocal, generateAsyncTaskClass, type AsyncTaskClassResult, } from "./async-state-machine.js";
+export { isCuttlefishSDKImport, normalizeInclude, dedupe, resolveTranspiledModuleInclude, applySymbolMap, } from "./include-resolver.js";
+export { normalizeComment, emitCommentLines, } from "./comment-helpers.js";

package/dist/emit/utils/index.js

@@ -0,0 +1,12 @@
+/**
+ * Emitter utilities barrel export.
+ * Re-exports all utility functions for C++ code emission.
+ */
+// Type inference utilities
+export { inferObjectFieldType, collectNestedStructDefs, hasArrayInObjectLiteral, hasThrowStatements, hasStdMathCalls, hasConsoleCalls, isConsoleCall, getConsoleMethod, isRuntimeExpression, statementRequiresRuntime, collectPointerVarTypes, collectExpressionIdentifiers, } from "./type-inference.js";
+// Async state machine utilities
+export { toPascalCaseLocal, generateAsyncTaskClass, } from "./async-state-machine.js";
+// Include resolution utilities
+export { isCuttlefishSDKImport, normalizeInclude, dedupe, resolveTranspiledModuleInclude, applySymbolMap, } from "./include-resolver.js";
+// Comment handling utilities
+export { normalizeComment, emitCommentLines, } from "./comment-helpers.js";

package/dist/emit/utils/type-inference.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Type inference utilities for C++ code emission.
+ * Pure functions with no side effects - extracted from cpp-emitter.ts
+ */
+import type { ExpressionIR, StatementIR, PlatformStrategy } from "../../api/index.js";
+/**
+ * Infers the C++ type for an object field based on its initializer value.
+ *
+ * @param value The expression to infer type for
+ * @param pointerVarTypes Map of variable names to their pointer types (e.g., "sensor" -> "Sensor*")
+ * @param knownFunctionReturnTypes Map of function names to their return types
+ * @param knownObjectTypes Map of object names to their types
+ * @param knownObjectFieldTypes Map of object names to their field type maps
+ * @param largeEnumNames Set of enum names with values outside 16-bit int range
+ * @param resolvePinType Optional callback to resolve pin types from the platform strategy
+ * @returns The inferred C++ type string
+ */
+export declare function inferObjectFieldType(value: ExpressionIR, pointerVarTypes?: Map<string, string>, knownFunctionReturnTypes?: Map<string, string>, knownObjectTypes?: Map<string, string>, knownObjectFieldTypes?: Map<string, Map<string, string>>, largeEnumNames?: Set<string>, parentName?: string, fieldName?: string, defaultIntType?: string, resolvePinType?: (objectName: string, fieldName: string) => string | undefined): string;
+/**
+ * Recursively collects nested struct definitions from an object ExpressionIR.
+ * Returns an array of struct definitions ordered from deepest to shallowest,
+ * so that inner structs are defined before outer structs that reference them.
+ *
+ * @param objExpr  The object ExpressionIR to scan for nested objects
+ * @param parentName The variable/struct name prefix for generating struct type names
+ * @param pointerVarTypes Optional pointer variable type map
+ * @param knownFunctionReturnTypes Optional function return type map
+ * @param knownObjectTypes Optional object type map
+ * @param knownObjectFieldTypes Optional object field type map
+ * @param largeEnumNames Optional large enum names set
+ */
+export declare function collectNestedStructDefs(objExpr: Extract<ExpressionIR, {
+    kind: "object";
+}>, parentName: string, pointerVarTypes?: Map<string, string>, knownFunctionReturnTypes?: Map<string, string>, knownObjectTypes?: Map<string, string>, knownObjectFieldTypes?: Map<string, Map<string, string>>, largeEnumNames?: Set<string>): {
+    structName: string;
+    fields: {
+        type: string;
+        name: string;
+    }[];
+}[];
+/**
+ * Checks if a program contains array literals inside object literals.
+ * This affects whether std::vector needs to be included.
+ *
+ * @param program The program IR to analyze
+ * @returns true if arrays in object literals are found
+ */
+export declare function hasArrayInObjectLiteral(program: {
+    topLevelStatements: StatementIR[];
+    functions: Array<{
+        statements: StatementIR[];
+    }>;
+    classes: Array<{
+        fields: Array<{
+            initializer?: ExpressionIR;
+        }>;
+        methods: Array<{
+            statements: StatementIR[];
+        }>;
+        constructor?: {
+            statements: StatementIR[];
+        };
+    }>;
+}): boolean;
+/**
+ * Checks if a program contains throw statements.
+ * This affects whether <stdexcept> needs to be included.
+ *
+ * @param program The program IR to analyze
+ * @returns true if throw statements are found
+ */
+export declare function hasThrowStatements(program: {
+    topLevelStatements: StatementIR[];
+    functions: Array<{
+        statements: StatementIR[];
+    }>;
+    classes: Array<{
+        methods: Array<{
+            statements: StatementIR[];
+        }>;
+        constructor?: {
+            statements: StatementIR[];
+        };
+    }>;
+}): boolean;
+/**
+ * Checks if a program contains std::math function calls.
+ * This affects whether <cmath> or <math.h> needs to be included.
+ *
+ * @param program The program IR to analyze
+ * @returns true if math calls are found
+ */
+export declare function hasStdMathCalls(program: {
+    topLevelStatements: StatementIR[];
+    functions: Array<{
+        statements: StatementIR[];
+    }>;
+    classes: Array<{
+        methods: Array<{
+            statements: StatementIR[];
+        }>;
+        constructor?: {
+            statements: StatementIR[];
+        };
+    }>;
+}): boolean;
+/**
+ * Checks if a program contains console.* calls (console.log, console.error, etc.)
+ *
+ * @param program The program IR to analyze
+ * @returns true if console calls are found
+ */
+export declare function hasConsoleCalls(program: {
+    topLevelStatements: StatementIR[];
+    functions: Array<{
+        statements: StatementIR[];
+    }>;
+    classes: Array<{
+        methods: Array<{
+            statements: StatementIR[];
+        }>;
+        constructor?: {
+            statements: StatementIR[];
+        };
+    }>;
+}, strategy?: PlatformStrategy): boolean;
+/**
+ * Checks if a callee is a console method call (e.g., "console.log", "console.error")
+ */
+export declare function isConsoleCall(callee: string, strategy?: PlatformStrategy): boolean;
+/**
+ * Gets the console method name from a callee (e.g., "log" from "console.log")
+ */
+export declare function getConsoleMethod(callee: string): string;
+/**
+ * Checks if an expression requires runtime execution (cannot be evaluated at global scope in C++).
+ * Compile-time expressions can be placed at global scope; runtime expressions must go in setup()/main().
+ *
+ * @param expr The expression to check
+ * @returns true if the expression requires runtime execution
+ */
+export declare function collectExpressionIdentifiers(expr: ExpressionIR): Set<string>;
+export declare function isRuntimeExpression(expr: ExpressionIR): boolean;
+/**
+ * Checks if a statement requires runtime execution.
+ *
+ * @param statement The statement to check
+ * @returns true if the statement requires runtime execution
+ */
+export declare function statementRequiresRuntime(statement: StatementIR): boolean;
+/**
+ * Collects pointer variable types from program statements.
+ * Variables initialized with 'new ClassName()' get type 'ClassName*'.
+ *
+ * @param statements The statements to analyze
+ * @param classNameMap Optional map for transforming simple class names to fully qualified names
+ * @returns Map of variable names to their pointer types
+ */
+export declare function collectPointerVarTypes(statements: StatementIR[], classNameMap?: Map<string, string>): Map<string, string>;