@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Source location span for mapping generated code back to TypeScript.
+ */
+export interface SourceSpan {
+    filePath: string;
+    startOffset: number;
+    endOffset: number;
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+}
+/**
+ * Diagnostic severity levels.
+ */
+export type DiagnosticSeverity = "info" | "warning" | "error";
+/**
+ * Diagnostic message from transpilation or emit.
+ */
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    message: string;
+    /** Actionable fix suggestion, shown as a distinct code block in CLI output. */
+    hint?: string;
+    line?: number;
+    column?: number;
+    code?: string;
+    source?: string;
+    /** Text of the source line for display context. */
+    sourceLine?: string;
+}
+/**
+ * Target profile for code generation.
+ * Frameworks register their own profile names (e.g. "arduino", "stm32", "native").
+ */
+export type TargetProfile = "generic" | (string & {});
+/**
+ * Platform-specific context for code generation.
+ * Frameworks add their own context via the index signature.
+ */
+export interface PlatformContext {
+    console?: {
+        baudRate?: number;
+    };
+    /** Target architecture identifier (e.g., 'avr', 'esp32'). Populated from board config. */
+    architecture?: string;
+    /** Framework-specific data. Each framework reads its own key. */
+    frameworkData?: Record<string, unknown>;
+    [key: string]: unknown;
+}

package/dist/api/shared/types.js

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// Shared types for TypeCAD platform infrastructure
+//
+// These types are used by both the CLI and framework packages.
+// ---------------------------------------------------------------------------
+export {};

package/dist/ast/parse.d.ts

@@ -0,0 +1,2 @@
+import ts from "typescript";
+export declare function parseSource(fileName: string, sourceText: string): ts.SourceFile;

package/dist/ast/parse.js

@@ -0,0 +1,4 @@
+import ts from "typescript";
+export function parseSource(fileName, sourceText) {
+    return ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}

package/dist/cache.d.ts

@@ -0,0 +1,26 @@
+import ts from "typescript";
+export declare class TranspileCache {
+    private readonly npmPackageCache;
+    private readonly packageJsonCache;
+    private readonly sourceFileCache;
+    private readonly fileExistsCache;
+    private readonly fileContentCache;
+    clear(): void;
+    getCachedNpmPackage(fromFile: string, packageName: string): string | undefined;
+    setCachedNpmPackage(fromFile: string, packageName: string, packageDir: string | undefined): void;
+    getCachedPackageJson(packageDir: string): Record<string, unknown> | null | undefined;
+    setCachedPackageJson(packageDir: string, content: Record<string, unknown> | null): void;
+    getOrParseSourceFile(filePath: string, sourceText: string): ts.SourceFile;
+    cachedFileExists(filePath: string): boolean;
+    cachedIsFile(filePath: string): boolean;
+    getOrReadFile(filePath: string): string;
+}
+export declare function clearCaches(): void;
+export declare function getCachedNpmPackage(fromFile: string, packageName: string): string | undefined;
+export declare function setCachedNpmPackage(fromFile: string, packageName: string, packageDir: string | undefined): void;
+export declare function getCachedPackageJson(packageDir: string): Record<string, unknown> | null | undefined;
+export declare function setCachedPackageJson(packageDir: string, content: Record<string, unknown> | null): void;
+export declare function getOrParseSourceFile(filePath: string, sourceText: string): ts.SourceFile;
+export declare function cachedFileExists(filePath: string): boolean;
+export declare function cachedIsFile(filePath: string): boolean;
+export declare function getOrReadFile(filePath: string): string;

package/dist/cache.js

@@ -0,0 +1,95 @@
+import ts from "typescript";
+import path from "path";
+import fs from "fs";
+import { clearAllProfileCaches } from "./platform/registry.js";
+export class TranspileCache {
+    constructor() {
+        this.npmPackageCache = new Map();
+        this.packageJsonCache = new Map();
+        this.sourceFileCache = new Map();
+        this.fileExistsCache = new Map();
+        this.fileContentCache = new Map();
+    }
+    clear() {
+        this.npmPackageCache.clear();
+        this.packageJsonCache.clear();
+        this.sourceFileCache.clear();
+        this.fileExistsCache.clear();
+        this.fileContentCache.clear();
+        clearAllProfileCaches();
+    }
+    getCachedNpmPackage(fromFile, packageName) {
+        return this.npmPackageCache.get(`${fromFile}|${packageName}`);
+    }
+    setCachedNpmPackage(fromFile, packageName, packageDir) {
+        this.npmPackageCache.set(`${fromFile}|${packageName}`, packageDir);
+    }
+    getCachedPackageJson(packageDir) {
+        return this.packageJsonCache.get(packageDir);
+    }
+    setCachedPackageJson(packageDir, content) {
+        this.packageJsonCache.set(packageDir, content);
+    }
+    getOrParseSourceFile(filePath, sourceText) {
+        const cached = this.sourceFileCache.get(filePath);
+        if (cached)
+            return cached;
+        const extension = path.extname(filePath).toLowerCase();
+        const source = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, extension === ".tsx" ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        this.sourceFileCache.set(filePath, source);
+        return source;
+    }
+    cachedFileExists(filePath) {
+        const cached = this.fileExistsCache.get(filePath);
+        if (cached !== undefined)
+            return cached;
+        const exists = fs.existsSync(filePath);
+        this.fileExistsCache.set(filePath, exists);
+        return exists;
+    }
+    cachedIsFile(filePath) {
+        const cacheKey = `file:${filePath}`;
+        const cached = this.fileExistsCache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const exists = fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+        this.fileExistsCache.set(cacheKey, exists);
+        return exists;
+    }
+    getOrReadFile(filePath) {
+        const cached = this.fileContentCache.get(filePath);
+        if (cached !== undefined)
+            return cached;
+        const content = fs.readFileSync(filePath, "utf8");
+        this.fileContentCache.set(filePath, content);
+        return content;
+    }
+}
+const defaultCache = new TranspileCache();
+export function clearCaches() {
+    defaultCache.clear();
+}
+export function getCachedNpmPackage(fromFile, packageName) {
+    return defaultCache.getCachedNpmPackage(fromFile, packageName);
+}
+export function setCachedNpmPackage(fromFile, packageName, packageDir) {
+    defaultCache.setCachedNpmPackage(fromFile, packageName, packageDir);
+}
+export function getCachedPackageJson(packageDir) {
+    return defaultCache.getCachedPackageJson(packageDir);
+}
+export function setCachedPackageJson(packageDir, content) {
+    defaultCache.setCachedPackageJson(packageDir, content);
+}
+export function getOrParseSourceFile(filePath, sourceText) {
+    return defaultCache.getOrParseSourceFile(filePath, sourceText);
+}
+export function cachedFileExists(filePath) {
+    return defaultCache.cachedFileExists(filePath);
+}
+export function cachedIsFile(filePath) {
+    return defaultCache.cachedIsFile(filePath);
+}
+export function getOrReadFile(filePath) {
+    return defaultCache.getOrReadFile(filePath);
+}

package/dist/cli-utils.d.ts

@@ -0,0 +1,37 @@
+import type { CompileResult, Diagnostic } from "./api/shared/index.js";
+export declare function runExpectTests(options: {
+    port?: string;
+    buildTarget?: string;
+    baud?: number;
+    expectFile?: string;
+}): number;
+export declare function assertTypeScriptInput(filePath: string): void;
+export declare function printDiagnostics(diagnostics: Array<Diagnostic | {
+    severity: string;
+    message: string;
+    hint?: string;
+    line?: number;
+    column?: number;
+    code?: string;
+    sourceLine?: string;
+}>): void;
+/**
+ * Print compiler (g++/native) errors mapped back to the TypeScript source
+ * that generated them.
+ *
+ * The mapped TypeScript errors are the PRIMARY output — shown in the same
+ * rich style as `printDiagnostics` (file:line:col + source line + caret).
+ * Errors that cannot be mapped (e.g. generated runtime shims/polyfills with
+ * no TS origin) are shown afterwards as a demoted, gray C++ fallback so no
+ * information is lost.
+ *
+ * Resolution strategy:
+ *  - If `buildDir` is supplied (native mode), build a per-file source-map
+ *    index over every `*.thcppmap.json` in the dir and map each error via
+ *    its own translation unit's map.
+ *  - Otherwise fall back to the single-map Arduino sketch path so non-native
+ *    frameworks keep their existing behavior.
+ */
+export declare function printMappedCompileErrors(compileResult: CompileResult, originalSourceMapPath?: string, sketchPath?: string, buildDir?: string): {
+    printed: boolean;
+};

package/dist/cli-utils.js

@@ -0,0 +1,250 @@
+import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import { buildSourceMapIndex, mapCppErrorToTs, mapCppLocationToTs, readSourceMap, resolveSourceMapForSketch, } from "./mapping/source-map.js";
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function resolveExpectCliPath() {
+    try {
+        return require.resolve("@typecad/expect/dist/host/cli.js");
+    }
+    catch {
+        const monorepoPath = path.resolve(__dirname, "..", "..", "expect", "dist", "host", "cli.js");
+        if (fs.existsSync(monorepoPath))
+            return monorepoPath;
+        const nmPath = path.resolve(__dirname, "..", "node_modules", "@typecad", "expect", "dist", "host", "cli.js");
+        if (fs.existsSync(nmPath))
+            return nmPath;
+        return "cuttlefish-test";
+    }
+}
+export function runExpectTests(options) {
+    const expectCliPath = resolveExpectCliPath();
+    const args = [expectCliPath];
+    if (options.port)
+        args.push("--port", options.port);
+    if (options.buildTarget)
+        args.push("--build-target", options.buildTarget);
+    if (options.baud)
+        args.push("--baud", String(options.baud));
+    if (options.expectFile)
+        args.push(path.resolve(process.cwd(), options.expectFile));
+    const result = spawnSync(process.execPath, args, {
+        encoding: "utf8",
+        cwd: process.cwd(),
+        timeout: 0,
+        stdio: "inherit",
+    });
+    return result.status ?? 1;
+}
+export function assertTypeScriptInput(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    if (extension !== ".ts" && extension !== ".tsx" && extension !== ".ui") {
+        throw new Error(`Expected a .ts, .tsx, or .ui file, received '${extension || "<no extension>"}'.`);
+    }
+}
+export function printDiagnostics(diagnostics) {
+    for (const diagnostic of diagnostics) {
+        const position = diagnostic.line && diagnostic.column ? chalk.gray(`(${diagnostic.line},${diagnostic.column})`) : "";
+        const code = diagnostic.code ? chalk.gray(` [${diagnostic.code}]`) : "";
+        let severityLabel;
+        let hintColor;
+        if (diagnostic.severity === "error") {
+            severityLabel = chalk.red.bold("error");
+            hintColor = chalk.red;
+        }
+        else if (diagnostic.severity === "warning") {
+            severityLabel = chalk.yellow.bold("warning");
+            hintColor = chalk.yellow;
+        }
+        else {
+            severityLabel = chalk.cyan.bold(diagnostic.severity);
+            hintColor = chalk.cyan;
+        }
+        const location = position ? ` ${position}` : "";
+        const header = `${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
+        if (diagnostic.severity === "error") {
+            console.error(header);
+        }
+        else {
+            console.warn(header);
+        }
+        if (diagnostic.sourceLine && diagnostic.column != null) {
+            const col = diagnostic.column;
+            const prefix = "    ";
+            const sourceOutput = prefix + diagnostic.sourceLine;
+            if (diagnostic.severity === "error") {
+                console.error(sourceOutput);
+            }
+            else {
+                console.warn(sourceOutput);
+            }
+            const caret = prefix + " ".repeat(Math.max(0, col - 1)) + "^";
+            if (diagnostic.severity === "error") {
+                console.error(chalk.gray(caret));
+            }
+            else {
+                console.warn(chalk.gray(caret));
+            }
+        }
+        if (diagnostic.hint) {
+            const hintLines = diagnostic.hint.split("\n");
+            for (const hintLine of hintLines) {
+                const formatted = hintColor(`  \u21b3  ${hintLine}`);
+                if (diagnostic.severity === "error") {
+                    console.error(formatted);
+                }
+                else {
+                    console.warn(formatted);
+                }
+            }
+        }
+    }
+}
+/**
+ * Print compiler (g++/native) errors mapped back to the TypeScript source
+ * that generated them.
+ *
+ * The mapped TypeScript errors are the PRIMARY output — shown in the same
+ * rich style as `printDiagnostics` (file:line:col + source line + caret).
+ * Errors that cannot be mapped (e.g. generated runtime shims/polyfills with
+ * no TS origin) are shown afterwards as a demoted, gray C++ fallback so no
+ * information is lost.
+ *
+ * Resolution strategy:
+ *  - If `buildDir` is supplied (native mode), build a per-file source-map
+ *    index over every `*.thcppmap.json` in the dir and map each error via
+ *    its own translation unit's map.
+ *  - Otherwise fall back to the single-map Arduino sketch path so non-native
+ *    frameworks keep their existing behavior.
+ */
+export function printMappedCompileErrors(compileResult, originalSourceMapPath, sketchPath, buildDir) {
+    if (compileResult.errors.length === 0) {
+        return { printed: false };
+    }
+    // Build the source-map index (native: per-file maps; otherwise single map).
+    let index;
+    if (buildDir) {
+        index = buildSourceMapIndex(buildDir);
+        if (index.size === 0)
+            index = undefined;
+    }
+    let singleMap;
+    if (!index) {
+        let sourceMapPath = originalSourceMapPath;
+        if (sketchPath && !sourceMapPath) {
+            sourceMapPath = resolveSourceMapForSketch(sketchPath, originalSourceMapPath);
+        }
+        singleMap = sourceMapPath ? readSourceMap(sourceMapPath) : undefined;
+    }
+    const mapped = [];
+    const unmapped = [];
+    for (const error of compileResult.errors) {
+        const mappedDiag = index
+            ? mapCppErrorToTs(index, error)
+            : singleMap
+                ? mapCppLocationToTs(singleMap, error.line, error.column, error.message, error.filePath)
+                : undefined;
+        const span = mappedDiag?.mappedTsSpan;
+        if (span) {
+            mapped.push({
+                error,
+                tsFile: span.filePath,
+                tsLine: span.startLine,
+                tsColumn: span.startColumn,
+                sourceLine: readSourceLine(span.filePath, span.startLine),
+                nodeKind: mappedDiag?.nodeKind,
+                symbolName: mappedDiag?.symbolName,
+            });
+        }
+        else {
+            unmapped.push(error);
+        }
+    }
+    // Primary: mapped TypeScript errors (rich format, mirrors printDiagnostics).
+    for (const item of mapped) {
+        printMappedTsError(item.error, item.tsFile, item.tsLine, item.tsColumn, item.sourceLine, item.nodeKind, item.symbolName);
+    }
+    // Demoted fallback: raw C++ errors with no TS origin.
+    if (unmapped.length > 0) {
+        if (mapped.length > 0) {
+            console.error("");
+        }
+        console.error(chalk.gray(`Unmapped (generated-code) ${unmapped.length === 1 ? "error" : "errors"}:`));
+        for (const error of unmapped) {
+            const rel = relativeForDisplay(error.filePath);
+            const line = chalk.gray(`  \u21b3 (generated C++) ${rel}(${error.line},${error.column}): ${error.severity}: ${error.message}`);
+            if (error.severity === "error") {
+                console.error(line);
+            }
+            else {
+                console.warn(line);
+            }
+        }
+    }
+    return { printed: mapped.length > 0 || unmapped.length > 0 };
+}
+/** Read a single 1-based source line for caret display; returns undefined on failure. */
+function readSourceLine(filePath, line) {
+    try {
+        const content = fs.readFileSync(filePath, "utf8");
+        return content.split(/\r?\n/)[line - 1];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Make a path relative to cwd for display, falling back to the original. */
+function relativeForDisplay(filePath) {
+    try {
+        const rel = path.relative(process.cwd(), filePath);
+        return rel && !rel.startsWith("..") ? rel : filePath;
+    }
+    catch {
+        return filePath;
+    }
+}
+/** Print one mapped error in the rich printDiagnostics style. */
+function printMappedTsError(error, tsFile, tsLine, tsColumn, sourceLine, nodeKind, symbolName) {
+    const rel = relativeForDisplay(tsFile);
+    const position = chalk.gray(`(${tsLine},${tsColumn})`);
+    let severityLabel;
+    if (error.severity === "error") {
+        severityLabel = chalk.red.bold("error");
+    }
+    else if (error.severity === "warning") {
+        severityLabel = chalk.yellow.bold("warning");
+    }
+    else {
+        severityLabel = chalk.cyan.bold(String(error.severity));
+    }
+    const origin = symbolName ? chalk.gray(` [${nodeKind ?? "generated"}: ${symbolName}]`) : nodeKind ? chalk.gray(` [${nodeKind}]`) : "";
+    const header = `${chalk.cyan(rel)} ${position} ${severityLabel}${origin}: ${chalk.white(error.message)}`;
+    if (error.severity === "error") {
+        console.error(header);
+    }
+    else {
+        console.warn(header);
+    }
+    if (sourceLine) {
+        const prefix = "    ";
+        const col = tsColumn;
+        const sourceOutput = prefix + sourceLine;
+        if (error.severity === "error") {
+            console.error(sourceOutput);
+        }
+        else {
+            console.warn(sourceOutput);
+        }
+        const caret = prefix + " ".repeat(Math.max(0, col - 1)) + "^";
+        if (error.severity === "error") {
+            console.error(chalk.gray(caret));
+        }
+        else {
+            console.warn(chalk.gray(caret));
+        }
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};