@typecad/cuttlefish 0.1.0-alpha.1

package/dist/mapping/source-map.js

@@ -0,0 +1,207 @@
+import path from "node:path";
+import fs from "node:fs";
+import { readText, writeText } from "../utils/fs.js";
+function toSourceMapPath(generatedFilePath) {
+    return `${generatedFilePath}.thcppmap.json`;
+}
+/**
+ * Normalize a file path for comparison across the emitter and g++.
+ * g++ on Windows may emit paths that differ from what the emitter wrote:
+ * drive-letter casing (C:\ vs c:\), forward vs back slashes, and trailing
+ * differences. We normalize separators to "/", lowercase the drive letter
+ * only (Windows is case-insensitive but the rest of a path may be
+ * significant on POSIX), and resolve relatives.
+ */
+function normalizeFilePath(filePath) {
+    let p = path.resolve(filePath);
+    // Normalize separators.
+    p = p.split(path.sep).join("/");
+    // Lowercase the drive letter on Windows ("C:/..." -> "c:/...").
+    if (/^[A-Za-z]:\//.test(p)) {
+        p = p[0].toLowerCase() + p.slice(1);
+    }
+    return p;
+}
+export function writeSourceMap(map) {
+    const mapPath = toSourceMapPath(map.generatedFilePath);
+    writeText(mapPath, JSON.stringify(map, null, 2) + "\n");
+    return mapPath;
+}
+export function readSourceMap(mapPath) {
+    return JSON.parse(readText(mapPath));
+}
+export function makeGeneratedMap(generatedFilePath, sourceFilePath, entries) {
+    return {
+        version: 1,
+        generatedFilePath,
+        sourceFilePath,
+        entries,
+    };
+}
+function scoreEntry(entry, line, column) {
+    if (line < entry.generatedStartLine || line > entry.generatedEndLine) {
+        return Number.POSITIVE_INFINITY;
+    }
+    if (line === entry.generatedStartLine && column < entry.generatedStartColumn) {
+        return Number.POSITIVE_INFINITY;
+    }
+    if (line === entry.generatedEndLine && column > entry.generatedEndColumn) {
+        return Number.POSITIVE_INFINITY;
+    }
+    const lineSpan = Math.max(1, entry.generatedEndLine - entry.generatedStartLine + 1);
+    const colSpan = Math.max(1, entry.generatedEndColumn - entry.generatedStartColumn + 1);
+    return lineSpan * 100000 + colSpan;
+}
+function nearestEntry(entries, line) {
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return entries
+        .slice()
+        .sort((a, b) => {
+        const da = Math.min(Math.abs(a.generatedStartLine - line), Math.abs(a.generatedEndLine - line));
+        const db = Math.min(Math.abs(b.generatedStartLine - line), Math.abs(b.generatedEndLine - line));
+        return da - db;
+    })[0];
+}
+export function mapCppLocationToTs(map, cppLine, cppColumn, message, cppFilePath) {
+    const scored = map.entries
+        .map((entry) => ({ entry, score: scoreEntry(entry, cppLine, cppColumn) }))
+        .filter((item) => Number.isFinite(item.score))
+        .sort((a, b) => a.score - b.score);
+    const best = scored.length > 0 ? scored[0].entry : nearestEntry(map.entries, cppLine);
+    return {
+        cppFilePath: cppFilePath ?? map.generatedFilePath,
+        cppLine,
+        cppColumn,
+        message,
+        mappedTsSpan: best?.tsSpan,
+        nodeKind: best?.nodeKind,
+        symbolName: best?.symbolName,
+    };
+}
+export function resolveMapPath(mapFileOrGeneratedFile) {
+    if (mapFileOrGeneratedFile.endsWith(".thcppmap.json")) {
+        return path.resolve(process.cwd(), mapFileOrGeneratedFile);
+    }
+    return toSourceMapPath(path.resolve(process.cwd(), mapFileOrGeneratedFile));
+}
+/**
+ * Resolve source map path for a flattened Arduino sketch
+ * When a sketch is flattened, the source map needs to account for merged files
+ */
+export function resolveSourceMapForSketch(sketchPath, originalSourceMapPath) {
+    const sketchDir = path.dirname(sketchPath);
+    const sketchName = path.basename(sketchPath, path.extname(sketchPath));
+    // First try the original source map path
+    if (originalSourceMapPath && fs.existsSync(originalSourceMapPath)) {
+        return originalSourceMapPath;
+    }
+    // Try to find source maps for the sketch directory
+    const possibleMaps = [
+        path.join(sketchDir, `${sketchName}.thcppmap.json`),
+        path.join(sketchDir, `${sketchName}.ino.thcppmap.json`),
+        path.join(sketchDir, "example.thcppmap.json"), // Common case for example sketches
+    ];
+    for (const mapPath of possibleMaps) {
+        if (fs.existsSync(mapPath)) {
+            return mapPath;
+        }
+    }
+    // Look for any .thcppmap.json files in the sketch directory
+    try {
+        const files = fs.readdirSync(sketchDir);
+        const mapFiles = files.filter(f => f.endsWith('.thcppmap.json'));
+        if (mapFiles.length > 0) {
+            // Return the most recent one
+            const latest = mapFiles.sort().pop();
+            return path.join(sketchDir, latest);
+        }
+    }
+    catch {
+        // Ignore readdir errors
+    }
+    return undefined;
+}
+/**
+ * Load every `*.thcppmap.json` in `buildDir` (non-recursive) into an index
+ * keyed by the normalized `generatedFilePath`. Returns an empty index if the
+ * directory is missing or contains no maps.
+ */
+export function buildSourceMapIndex(buildDir) {
+    const index = new Map();
+    let files;
+    try {
+        files = fs.readdirSync(buildDir);
+    }
+    catch {
+        return index;
+    }
+    for (const file of files) {
+        if (!file.endsWith(".thcppmap.json"))
+            continue;
+        const mapPath = path.join(buildDir, file);
+        try {
+            const map = JSON.parse(readText(mapPath));
+            if (map && map.generatedFilePath) {
+                index.set(normalizeFilePath(map.generatedFilePath), map);
+            }
+        }
+        catch {
+            // Skip unreadable / malformed maps rather than aborting the whole index.
+        }
+    }
+    return index;
+}
+/**
+ * Map a g++/compiler error back to its TypeScript source span.
+ *
+ * Selects the per-file source map whose `generatedFilePath` matches the
+ * error's `filePath`, then delegates to `mapCppLocationToTs`. If the exact
+ * generated file isn't keyed (e.g. the compiler reported a differently
+ * normalized path, or the error came from a header), falls back to a
+ * directory-wide search across every loaded map.
+ *
+ * Returns a `MappedDiagnostic` whose `mappedTsSpan` is `undefined` when no
+ * map could resolve the location (the caller should treat that as a raw
+ * C++ fallback).
+ */
+export function mapCppErrorToTs(index, error) {
+    const normalized = normalizeFilePath(error.filePath);
+    // 1. Direct hit on the generated file's own map.
+    const direct = index.get(normalized);
+    if (direct) {
+        return mapCppLocationToTs(direct, error.line, error.column, error.message, error.filePath);
+    }
+    // 2. Header / alternate-path fallback: search every loaded map. This
+    //    covers errors reported against a .h (which shares the dir) and any
+    //    remaining path-normalization drift between the compiler and emitter.
+    let best;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const map of index.values()) {
+        // Find the tightest in-range entry across all maps; mapCppLocationToTs
+        // always falls back to a nearest match, so we score ourselves to only
+        // accept a genuinely in-range candidate.
+        const scored = map.entries
+            .map((entry) => ({ entry, score: scoreEntry(entry, error.line, error.column) }))
+            .filter((item) => Number.isFinite(item.score))
+            .sort((a, b) => a.score - b.score);
+        if (scored.length === 0)
+            continue;
+        if (scored[0].score < bestScore) {
+            bestScore = scored[0].score;
+            best = mapCppLocationToTs(map, error.line, error.column, error.message, error.filePath);
+        }
+    }
+    if (best)
+        return best;
+    // 3. Nothing loaded at all — return unmapped so the caller can show the
+    //    raw C++ location.
+    return {
+        cppFilePath: error.filePath,
+        cppLine: error.line,
+        cppColumn: error.column,
+        message: error.message,
+        mappedTsSpan: undefined,
+    };
+}

package/dist/orchestrator/dts-generator.d.ts

@@ -0,0 +1,17 @@
+export declare function tryGenerateLibDecl(modulePath: string, file: string): string | undefined;
+/**
+ * Extracts module path from "Cannot find module" error messages.
+ * Returns the module path (relative or bare module name), undefined otherwise.
+ */
+export declare function extractMissingModulePath(errorMessage: string): string | undefined;
+/**
+ * Attempts to find a .cpp file for a missing module.
+ * Checks both direct path and index patterns.
+ */
+export declare function findCppForModule(fromFile: string, modulePath: string): string | undefined;
+/**
+ * Auto-generates .d.ts files for C++ modules that are missing declarations.
+ * Also tries to generate declarations for framework libraries.
+ * Returns list of generated files.
+ */
+export declare function autoGenerateMissingDecls(files: string[], errors: string[]): string[];

package/dist/orchestrator/dts-generator.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+import fs from "node:fs";
+import { generateDeclFromCpp } from "../libdef/cpp-to-decl.js";
+import { getLoadedFramework, hasLoadedFramework } from "../framework-registry.js";
+export function tryGenerateLibDecl(modulePath, file) {
+    try {
+        if (hasLoadedFramework()) {
+            const { libDeclGenerator } = getLoadedFramework();
+            if (libDeclGenerator) {
+                return libDeclGenerator(modulePath, file);
+            }
+        }
+    }
+    catch {
+        // No loaded framework.
+    }
+    return undefined;
+}
+/**
+ * Extracts module path from "Cannot find module" error messages.
+ * Returns the module path (relative or bare module name), undefined otherwise.
+ */
+export function extractMissingModulePath(errorMessage) {
+    const match = errorMessage.match(/Cannot find module '([^']+)' or its corresponding type declarations/);
+    return match ? match[1] : undefined;
+}
+/**
+ * Attempts to find a .cpp file for a missing module.
+ * Checks both direct path and index patterns.
+ */
+export function findCppForModule(fromFile, modulePath) {
+    const basePath = path.resolve(path.dirname(fromFile), modulePath);
+    const candidates = [
+        `${basePath}.cpp`,
+        path.join(basePath, "index.cpp"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Auto-generates .d.ts files for C++ modules that are missing declarations.
+ * Also tries to generate declarations for framework libraries.
+ * Returns list of generated files.
+ */
+export function autoGenerateMissingDecls(files, errors) {
+    const generated = [];
+    const processedModules = new Set();
+    for (const error of errors) {
+        const modulePath = extractMissingModulePath(error);
+        if (!modulePath || processedModules.has(modulePath)) {
+            continue;
+        }
+        processedModules.add(modulePath);
+        // Try relative C++ module first
+        if (modulePath.startsWith(".")) {
+            for (const file of files) {
+                const cppPath = findCppForModule(file, modulePath);
+                if (cppPath) {
+                    const result = generateDeclFromCpp(cppPath);
+                    if (result) {
+                        generated.push(result);
+                    }
+                    break;
+                }
+            }
+        }
+        else {
+            // Try framework library for bare module imports
+            for (const file of files) {
+                const declPath = tryGenerateLibDecl(modulePath, file);
+                if (declPath) {
+                    generated.push(declPath);
+                    break;
+                }
+            }
+        }
+    }
+    return generated;
+}

package/dist/orchestrator/graph-builder.d.ts

@@ -0,0 +1,18 @@
+import { TranspileGraphResult } from "../transpile/resolution.js";
+/**
+ * Sort files in dependency order using Kahn's algorithm.
+ * Dependencies come before dependents so that include ordering is correct
+ * (e.g., if A imports B, B appears before A in the result).
+ *
+ * Falls back to the original order for any files involved in dependency cycles.
+ */
+export declare function topologicalSortFiles(files: string[], dependencies: Map<string, Set<string>>): string[];
+/**
+ * Collects all files that need to be transpiled, following both relative and npm imports.
+ * Also detects native C++ modules (.d.ts + .cpp pairs).
+ * Files are returned in dependency order (dependencies before dependents).
+ *
+ * @param boardPackage  When provided, `@typecad/board` imports resolve to this
+ *                      board package (e.g. `'@typecad/board-arduino-uno'`).
+ */
+export declare function collectTranspileGraph(entryFile: string, boardPackage?: string): TranspileGraphResult;

package/dist/orchestrator/graph-builder.js

@@ -0,0 +1,218 @@
+import path from "node:path";
+import ts from "typescript";
+import { readText } from "../utils/fs.js";
+import { detectNativeCppModule, getNpmPackageInfoForFile, isInNodeModules, resolveImport, isCuttlefishSDKPath, } from "../transpile/resolution.js";
+import { requireUIHook } from "../ui-hook.js";
+/**
+ * Sort files in dependency order using Kahn's algorithm.
+ * Dependencies come before dependents so that include ordering is correct
+ * (e.g., if A imports B, B appears before A in the result).
+ *
+ * Falls back to the original order for any files involved in dependency cycles.
+ */
+export function topologicalSortFiles(files, dependencies) {
+    if (files.length <= 1)
+        return [...files];
+    const fileSet = new Set(files);
+    // Build reverse adjacency list: dep → Set<files that depend on dep>
+    const dependents = new Map();
+    const inDegree = new Map();
+    for (const f of files) {
+        dependents.set(f, new Set());
+        inDegree.set(f, 0);
+    }
+    for (const [file, deps] of dependencies) {
+        if (!fileSet.has(file))
+            continue;
+        for (const dep of deps) {
+            if (fileSet.has(dep) && dep !== file) {
+                dependents.get(dep).add(file);
+                inDegree.set(file, (inDegree.get(file) ?? 0) + 1);
+            }
+        }
+    }
+    // Kahn's algorithm: start with files that have no in-edges
+    const queue = [];
+    for (const f of files) {
+        if (inDegree.get(f) === 0) {
+            queue.push(f);
+        }
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        const file = queue.shift();
+        sorted.push(file);
+        for (const dependent of dependents.get(file) ?? []) {
+            const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+            inDegree.set(dependent, newDegree);
+            if (newDegree === 0) {
+                queue.push(dependent);
+            }
+        }
+    }
+    // If there are cycles, append remaining files in original order
+    if (sorted.length < files.length) {
+        const sortedSet = new Set(sorted);
+        for (const f of files) {
+            if (!sortedSet.has(f))
+                sorted.push(f);
+        }
+    }
+    return sorted;
+}
+/**
+ * Collects all files that need to be transpiled, following both relative and npm imports.
+ * Also detects native C++ modules (.d.ts + .cpp pairs).
+ * Files are returned in dependency order (dependencies before dependents).
+ *
+ * @param boardPackage  When provided, `@typecad/board` imports resolve to this
+ *                      board package (e.g. `'@typecad/board-arduino-uno'`).
+ */
+export function collectTranspileGraph(entryFile, boardPackage) {
+    const ordered = [];
+    const pending = [path.resolve(entryFile)];
+    const visited = new Set();
+    const npmPackages = new Map();
+    const nativeModules = new Map();
+    const uiModules = new Set();
+    // Track dependency edges for topological sorting
+    const dependencies = new Map();
+    while (pending.length > 0) {
+        const filePath = pending.shift();
+        if (!filePath || visited.has(filePath)) {
+            continue;
+        }
+        visited.add(filePath);
+        // Skip TypeCAD SDK files — they are type-level definitions only
+        if (isCuttlefishSDKPath(filePath)) {
+            continue;
+        }
+        ordered.push(filePath);
+        const fileDeps = new Set();
+        dependencies.set(filePath, fileDeps);
+        const sourceText = readText(filePath);
+        const extension = path.extname(filePath).toLowerCase();
+        // .ui single-file component: split into script/style/template. The <script>
+        // becomes the TS source for graph walking; the template+style are registered
+        // as a UI module at a synthetic .ui.html path (so loadUIModuleFromText caches
+        // it + the UI registry generates the type declaration under types/). The script's
+        // `screen` reference resolves to the in-file template.
+        if (extension === ".ui") {
+            const ui = requireUIHook();
+            const parts = ui.splitUiFile(sourceText);
+            // Register the template as a UI module at <file>.ui.html (synthetic path).
+            const uiHtmlPath = filePath + ".html";
+            ui.loadUIModuleFromText(uiHtmlPath, parts.html, parts.style, filePath);
+            uiModules.add(uiHtmlPath);
+            // Use the <script> as the TS source for import-graph walking. Inject an
+            // implicit `import { screen } from './<base>.ui.html'` so the script can
+            // reference `screen` without an explicit import.
+            const baseName = path.basename(filePath, ".ui");
+            const scriptWithImport = `import { screen } from './${baseName}.ui.html';\n` + parts.script;
+            const uiSource = ts.createSourceFile(filePath, scriptWithImport, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+            // Walk the script's imports to discover dependencies.
+            for (const statement of uiSource.statements) {
+                let moduleSpecifier;
+                if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+                    moduleSpecifier = statement.moduleSpecifier.text;
+                }
+                else if (ts.isExportDeclaration(statement) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
+                    moduleSpecifier = statement.moduleSpecifier.text;
+                }
+                if (!moduleSpecifier)
+                    continue;
+                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui")
+                    continue;
+                if (moduleSpecifier.startsWith("@typecad/"))
+                    continue;
+                const resolved = resolveImport(filePath, moduleSpecifier, boardPackage);
+                if (!resolved)
+                    continue;
+                if (resolved.uiModule)
+                    continue; // already handled above
+                fileDeps.add(resolved.sourcePath);
+                if (!visited.has(resolved.sourcePath))
+                    pending.push(resolved.sourcePath);
+            }
+            continue; // .ui file itself is not a TS file; the script is inlined at emit
+        }
+        const source = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, extension === ".tsx" ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        for (const statement of source.statements) {
+            let moduleSpecifier;
+            if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+                moduleSpecifier = statement.moduleSpecifier.text;
+            }
+            else if (ts.isExportDeclaration(statement) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
+                moduleSpecifier = statement.moduleSpecifier.text;
+            }
+            if (!moduleSpecifier) {
+                continue;
+            }
+            // Check for native C++ module (.d.ts + .cpp pair)
+            const nativeModule = detectNativeCppModule(filePath, moduleSpecifier);
+            if (nativeModule) {
+                nativeModules.set(moduleSpecifier, nativeModule);
+                continue; // Don't try to resolve as TypeScript
+            }
+            // Skip @typecad/expect — it provides type-level stubs only.
+            // The AST preprocessor rewrites all expect calls before transpilation.
+            if (moduleSpecifier === "@typecad/expect") {
+                continue;
+            }
+            // Skip @typecad/ui (and the future @typecad/ui rename) — it provides
+            // compile-time authoring stubs only. ui.mount/signal/bind calls are
+            // intercepted by tryResolveUICall and lowered to IR; the package itself
+            // must NOT be emitted as a C++ module (it would synthesize a bogus
+            // _ui_t struct for the `ui` namespace value).
+            if (moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/ui") {
+                continue;
+            }
+            // Skip @typecad/board, @typecad/board-*, @typecad/mcu-*, and
+            // @typecad/framework-* — these packages ship src/ for HAL metadata
+            // introspection (hal-parser.ts, board-resolver.ts) but their source
+            // must NOT be transpiled to C++. The HAL resolver loads class/method
+            // metadata from these files separately; emitting them as C++ produces
+            // thousands of lines of stub functions (board(), gpioWrite(), etc.)
+            // and pulls in unsupported types (Promise, variant, Object.freeze).
+            if (moduleSpecifier === "@typecad/board"
+                || moduleSpecifier.startsWith("@typecad/board-")
+                || moduleSpecifier.startsWith("@typecad/mcu-")
+                || moduleSpecifier.startsWith("@typecad/framework-")) {
+                continue;
+            }
+            const resolved = resolveImport(filePath, moduleSpecifier, boardPackage);
+            // .ui.html modules: load into the UI registry, record the path, and don't
+            // push onto `pending` (they are never parsed as TypeScript).
+            if (resolved?.uiModule) {
+                requireUIHook().loadUIModule(resolved.sourcePath);
+                uiModules.add(resolved.sourcePath);
+                // Track the dependency edge so topological sort orders the importer
+                // after the (virtual) UI module.
+                fileDeps.add(resolved.sourcePath);
+                continue;
+            }
+            if (resolved) {
+                // Track dependency edge for topological sorting
+                fileDeps.add(resolved.sourcePath);
+                if (!visited.has(resolved.sourcePath)) {
+                    pending.push(resolved.sourcePath);
+                    if (resolved.npmPackage) {
+                        npmPackages.set(resolved.sourcePath, resolved.npmPackage);
+                    }
+                    else if (isInNodeModules(resolved.sourcePath)) {
+                        // If the file is in node_modules but wasn't resolved as an npm package,
+                        // it was reached via relative import from another npm package file.
+                        // Create npm package info for it.
+                        const npmInfo = getNpmPackageInfoForFile(resolved.sourcePath, moduleSpecifier);
+                        if (npmInfo) {
+                            npmPackages.set(resolved.sourcePath, npmInfo);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Sort files in dependency order (dependencies before dependents)
+    const sorted = topologicalSortFiles(ordered, dependencies);
+    return { files: sorted, npmPackages, nativeModules, uiModules };
+}

package/dist/orchestrator/semantic-facts-verifier.d.ts

@@ -0,0 +1,38 @@
+import ts from "typescript";
+import type { Diagnostic } from "../types.js";
+import { TYPED_ARRAY_NAMES } from "./semantic-facts.js";
+import type { FactStore } from "./semantic-facts.js";
+export type UnknownTypeSeverity = "error" | "warning" | "off";
+export interface VerifierOptions {
+    /** Severity for expressions whose canonical type is "unknown".
+     *  Default "warning" — see module header. */
+    unknownTypeSeverity?: UnknownTypeSeverity;
+}
+export interface VerifierResult {
+    /** Diagnostics produced by the verifier (may be empty). */
+    diagnostics: Diagnostic[];
+    /** Counts for measurement/reporting. Use to size the blast radius before
+     *  flipping unknownTypeSeverity to "error". */
+    counts: {
+        expressionsVisited: number;
+        unknownTypeExpressions: number;
+    };
+}
+/**
+ * Verify semantic-fact completeness across user files.
+ *
+ * Walks every expression, computes its CanonicalType, and emits a diagnostic
+ * for each one that resolves to "unknown" (at the configured severity).
+ *
+ * If `facts` is passed, the walk also POPULATES the store with the computed
+ * `type` (CanonicalType) and `cppType` for each expression. This is the single
+ * place concrete per-expression type facts are recorded — Phase 3 of the type-
+ * resolution consolidation — so gate rules can read them without re-deriving
+ * from the ts.TypeChecker, and so a future pipeline reorder can populate the
+ * same fields from the ProgramIR SymbolTable instead. See SemanticFacts.cppType.
+ */
+export declare function verifyFacts(program: ts.Program, userFiles: string[], options?: VerifierOptions & {
+    facts?: FactStore;
+}): VerifierResult;
+/** Re-export so callers can introspect the typed-array name set if needed. */
+export { TYPED_ARRAY_NAMES };