@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/library/validate.js

@@ -0,0 +1,175 @@
+// ---------------------------------------------------------------------------
+// `cuttlefish library validate` — the standalone library-package validator.
+//
+// Before this, manifest errors only surfaced at import time inside a
+// transpile. This runs the same checks (and more) on a package directory:
+// manifest schema, file existence, include/gateToken consistency, npm
+// keyword consistency, and an AUTOSAR --strict pass over the shim bytes —
+// the same self-check the generated application runs over them.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { ComplianceContext, runSelfCheck } from "../emit/compliance/index.js";
+import { LIBRARY_MARKER_KEYWORD, libraryCategory } from "./catalog.js";
+function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+export function validateLibraryPackage(dir) {
+    const errors = [];
+    const warnings = [];
+    const root = path.resolve(dir);
+    const fail = (message) => {
+        errors.push(message);
+    };
+    // ── Manifest ───────────────────────────────────────────────────────────
+    const manifestPath = path.join(root, "cuttlefish.library.json");
+    let manifest;
+    if (!fs.existsSync(manifestPath)) {
+        fail("cuttlefish.library.json not found — is this a library package directory?");
+    }
+    else {
+        try {
+            manifest = readJson(manifestPath);
+        }
+        catch (e) {
+            fail(`cuttlefish.library.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (manifest) {
+        for (const field of ["id", "module", "framework", "include", "gateToken"]) {
+            if (typeof manifest[field] !== "string" || manifest[field].length === 0) {
+                fail(`Manifest field '${field}' must be a non-empty string.`);
+            }
+        }
+        if (!Array.isArray(manifest.shims) || manifest.shims.length === 0) {
+            fail("Manifest 'shims' must be a non-empty array.");
+        }
+        const include = typeof manifest.include === "string" ? manifest.include : "";
+        const gateToken = typeof manifest.gateToken === "string" ? manifest.gateToken : "";
+        if (include.length > 0 && gateToken.length > 0 && !include.includes(gateToken)) {
+            fail(`The gate token '${gateToken}' does not appear in the include '${include}' — ` +
+                `the include line is the only guaranteed emission, so contributions would never gate on.`);
+        }
+        // ── Shim files ───────────────────────────────────────────────────────
+        if (Array.isArray(manifest.shims)) {
+            for (const entry of manifest.shims) {
+                if (typeof entry !== "object" ||
+                    entry === null ||
+                    typeof entry.path !== "string" ||
+                    typeof entry.outName !== "string") {
+                    fail("Every 'shims' entry needs string 'path' and 'outName' fields.");
+                    continue;
+                }
+                const shimPath = path.join(root, entry.path);
+                if (!fs.existsSync(shimPath)) {
+                    fail(`Shim file listed in the manifest is missing: ${entry.path}`);
+                }
+            }
+        }
+        // ── Overlay fragment ─────────────────────────────────────────────────
+        if (typeof manifest.overlay === "string" && manifest.overlay.length > 0) {
+            const overlayPath = path.join(root, manifest.overlay);
+            if (!fs.existsSync(overlayPath)) {
+                fail(`Overlay fragment listed in the manifest is missing: ${manifest.overlay}`);
+            }
+        }
+    }
+    // ── package.json consistency ───────────────────────────────────────────
+    const pkgJsonPath = path.join(root, "package.json");
+    let pkgName;
+    let pkgKeywords = [];
+    if (!fs.existsSync(pkgJsonPath)) {
+        warnings.push("No package.json — nothing published, so keyword checks are skipped.");
+    }
+    else {
+        try {
+            const pkg = readJson(pkgJsonPath);
+            if (typeof pkg.name === "string") {
+                pkgName = pkg.name;
+            }
+            if (Array.isArray(pkg.keywords)) {
+                pkgKeywords = pkg.keywords.filter((k) => typeof k === "string");
+            }
+            if (Array.isArray(pkg.files) && !pkg.files.includes("cuttlefish.library.json")) {
+                fail("package.json 'files' must include 'cuttlefish.library.json' or the manifest will not ship.");
+            }
+        }
+        catch (e) {
+            fail(`package.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (pkgKeywords.length > 0 && !pkgKeywords.map((k) => k.toLowerCase()).includes(LIBRARY_MARKER_KEYWORD)) {
+        fail(`package.json keywords must include the marker '${LIBRARY_MARKER_KEYWORD}' — it is what library search scans for.`);
+    }
+    const categoryKeywords = pkgKeywords.filter((k) => k.startsWith("cuttlefish-") && k !== LIBRARY_MARKER_KEYWORD);
+    if (pkgKeywords.length > 0 && categoryKeywords.length === 0) {
+        warnings.push(`No category keyword in package.json — add one of ${LIBRARY_MARKER_KEYWORD}'s siblings (e.g. cuttlefish-led) so the library is browsable by category.`);
+    }
+    for (const kw of categoryKeywords) {
+        const id = kw.slice("cuttlefish-".length);
+        if (!libraryCategory(id)) {
+            warnings.push(`Keyword '${kw}' is not a known category keyword (cuttlefish-<id>).`);
+        }
+    }
+    if (categoryKeywords.length > 1) {
+        warnings.push(`Multiple category keywords (${categoryKeywords.join(", ")}) — search results show the first taxonomy match only.`);
+    }
+    if (manifest && pkgName !== undefined && typeof manifest.module === "string" && manifest.module !== pkgName) {
+        fail(`Manifest 'module' (${manifest.module}) must equal the package.json name (${pkgName}) — ` +
+            `the import specifier users write resolves against the package name.`);
+    }
+    // ── AUTOSAR strict over the shim bytes ─────────────────────────────────
+    const autosarFindings = [];
+    if (manifest && Array.isArray(manifest.shims)) {
+        const headerLines = [];
+        const sourceLines = [];
+        let anyReadable = false;
+        for (const entry of manifest.shims) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const rel = entry.path;
+            if (typeof rel !== "string")
+                continue;
+            const abs = path.join(root, rel);
+            if (!fs.existsSync(abs))
+                continue;
+            anyReadable = true;
+            const content = fs.readFileSync(abs, "utf8").split("\n");
+            if (abs.endsWith(".h") || abs.endsWith(".hpp")) {
+                headerLines.push(...content, "");
+            }
+            else {
+                sourceLines.push(...content, "");
+            }
+        }
+        if (anyReadable) {
+            const ctx = new ComplianceContext("strict");
+            autosarFindings.push(...runSelfCheck(ctx, sourceLines, headerLines));
+        }
+    }
+    for (const finding of autosarFindings) {
+        fail(`AUTOSAR ${finding.ruleId} (${finding.file} line ${finding.line}): ${finding.snippet}`);
+    }
+    return {
+        valid: errors.length === 0,
+        dir: root,
+        errors,
+        warnings,
+        autosarFindings,
+    };
+}
+/** Render the human-readable report. Returns the process exit code (0/1). */
+export function printValidationReport(report) {
+    for (const warning of report.warnings) {
+        console.log(`  ! ${warning}`);
+    }
+    for (const error of report.errors) {
+        console.log(`  x ${error}`);
+    }
+    if (report.valid) {
+        console.log(`  Valid library package${report.warnings.length > 0 ? ` (${report.warnings.length} warning${report.warnings.length === 1 ? "" : "s"})` : ""}.`);
+        return 0;
+    }
+    console.log(`  ${report.errors.length} error${report.errors.length === 1 ? "" : "s"}.`);
+    return 1;
+}

package/dist/library-packages.d.ts

@@ -0,0 +1,95 @@
+import type { LibraryDefinition } from "./types.js";
+/** A native source file a library contributes to the emitted sources. */
+export interface CuttlefishLibraryShim {
+    /** Path of the shim file, relative to the library package root. */
+    path: string;
+    /** File name the shim is written as, in the emitted source directory. */
+    outName: string;
+}
+/** The parsed `cuttlefish.library.json` manifest. */
+export interface CuttlefishLibraryManifest {
+    /** Stable library id (diagnostics / sidecar records). */
+    id: string;
+    /** The import specifier this library resolves (e.g. '@typecad/zephyr-esp32s3-rgb'). */
+    module: string;
+    /** The framework (strategy id) this library requires, e.g. 'zephyr'. */
+    framework: string;
+    /** Build-target prefixes this library supports (matched against buildTarget). */
+    targets?: string[];
+    /** C++ include directive content for the import, e.g. '"__tc_rgbled.h"'. */
+    include: string;
+    /** Token whose presence in emitted sources gates the library's artifacts. */
+    gateToken: string;
+    /** Native shim files written into the emitted source directory. */
+    shims: CuttlefishLibraryShim[];
+    /** CONFIG_ lines contributed to the framework's prj.conf. */
+    kconfig?: string[];
+    /** Path of a devicetree overlay fragment, relative to the package root. */
+    overlay?: string;
+}
+/** A registered library: manifest + resolved package root. */
+export interface RegisteredCuttlefishLibrary {
+    manifest: CuttlefishLibraryManifest;
+    packageRoot: string;
+}
+/** One record of the `libraries.json` sidecar (build-time contribution set). */
+export interface LibrarySidecarEntry {
+    id: string;
+    module: string;
+    framework: string;
+    gateToken: string;
+    kconfig: string[];
+    /** Absolute path of the overlay fragment, or null. */
+    overlay: string | null;
+    /** Shim file names written into the emitted source directory. */
+    shims: string[];
+}
+/** Sidecar file name — written next to the emitted sources. */
+export declare const LIBRARY_SIDECAR_NAME = "libraries.json";
+/** Clear all registrations. Called once per transpilation, before graph build. */
+export declare function resetCuttlefishLibraries(): void;
+/** All libraries registered during this transpilation (import-driven). */
+export declare function getRegisteredCuttlefishLibraries(): RegisteredCuttlefishLibrary[];
+/**
+ * Whether the specifier resolves to a library registered in this
+ * transpilation. Library packages are exempt from the @typecad/* "SDK
+ * imports are type-level only" include skip — their import IS the include
+ * of the shim header.
+ */
+export declare function isRegisteredCuttlefishLibrary(moduleSpecifier: string): boolean;
+/**
+ * Resolve the package root for a bare npm specifier from the importing file,
+ * then register the package as a cuttlefish library if it ships a
+ * `cuttlefish.library.json`. Returns true when the specifier resolved to a
+ * registered library (the import must then be skipped by the graph builder).
+ */
+export declare function registerCuttlefishLibraryFromSpecifier(fromFile: string, moduleSpecifier: string): boolean;
+/** Libdef entries for the registry: import → shim include. */
+export declare function cuttlefishLibraryLibdefs(): LibraryDefinition[];
+/**
+ * Validate registered libraries against the loaded framework (and, when
+ * known, the build target). Throws with an actionable message when a library
+ * cannot work in this project — far earlier and clearer than the native
+ * compiler would.
+ */
+export declare function validateCuttlefishLibraries(frameworkId: string, buildTarget?: string): void;
+/**
+ * Emit the library artifacts for the libraries actually used in this
+ * transpilation, and write the `libraries.json` sidecar:
+ *
+ *   1. scan the emitted sources for each library's gate token;
+ *   2. write (write-if-changed) the shims of every gated library into the
+ *      emitted source directory — the framework scaffold's CMake/program
+ *      regen picks the sources up automatically;
+ *   3. delete shim files recorded in the previous sidecar that are no longer
+ *      used, so removing an import removes its native code;
+ *   4. persist the sidecar (even when empty — that clears stale state).
+ */
+export declare function writeCuttlefishLibraryArtifacts(outDir: string, srcDir: string): void;
+/**
+ * Read the `libraries.json` sidecar for build-time consumers (framework
+ * toolchains). Tolerant of a missing or corrupt file (returns []).
+ */
+export declare function readCuttlefishLibrarySidecar(outDir: string): LibrarySidecarEntry[];
+/** Re-exported for transpile.ts libdef injection convenience. */
+export declare function libraryDefinitionKey(module: string): string;

package/dist/library-packages.js

@@ -0,0 +1,275 @@
+// ---------------------------------------------------------------------------
+// Cuttlefish library packages
+//
+// A library package is an npm package whose root carries a
+// `cuttlefish.library.json` manifest. It contributes native artifacts to the
+// generated firmware application:
+//
+//   - an include mapping (the import emits `#include` of the shim header)
+//   - shim files (native C++ written into the emitted source directory)
+//   - framework build contributions (Kconfig lines, a devicetree overlay
+//     fragment) consumed by the framework toolchain via the sidecar
+//
+// Discovery is import-driven: when the transpile graph builder resolves an
+// import whose package ships the manifest, the package is registered at that
+// moment and its TypeScript is NOT transpiled — the package's own types are
+// the compile-time contract, and the native shim is the implementation.
+// Nothing scans node_modules; an installed-but-never-imported library
+// contributes nothing.
+//
+// The transpiler writes a `libraries.json` sidecar next to the emitted
+// sources (the board-constants.json convention) recording the libraries that
+// were actually used, so build-time consumers (framework toolchains) can
+// re-derive their contributions idempotently from disk.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { toModuleKey } from "./utils/strings.js";
+/** Sidecar file name — written next to the emitted sources. */
+export const LIBRARY_SIDECAR_NAME = "libraries.json";
+const registered = new Map();
+/** Specifiers known NOT to be library packages (avoids repeated resolve attempts). */
+const knownNonLibraries = new Set();
+/** Clear all registrations. Called once per transpilation, before graph build. */
+export function resetCuttlefishLibraries() {
+    registered.clear();
+    knownNonLibraries.clear();
+}
+/** All libraries registered during this transpilation (import-driven). */
+export function getRegisteredCuttlefishLibraries() {
+    return [...registered.values()];
+}
+/**
+ * Whether the specifier resolves to a library registered in this
+ * transpilation. Library packages are exempt from the @typecad/* "SDK
+ * imports are type-level only" include skip — their import IS the include
+ * of the shim header.
+ */
+export function isRegisteredCuttlefishLibrary(moduleSpecifier) {
+    return registered.has(moduleSpecifier.toLowerCase());
+}
+function parseManifest(packageRoot) {
+    const manifestPath = path.join(packageRoot, "cuttlefish.library.json");
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const m = raw;
+    if (typeof m.id !== "string" ||
+        typeof m.module !== "string" ||
+        typeof m.framework !== "string" ||
+        typeof m.include !== "string" ||
+        typeof m.gateToken !== "string" ||
+        !Array.isArray(m.shims) ||
+        m.shims.length === 0) {
+        return undefined;
+    }
+    for (const shim of m.shims) {
+        if (typeof shim?.path !== "string" || typeof shim?.outName !== "string") {
+            return undefined;
+        }
+    }
+    return {
+        id: m.id,
+        module: m.module,
+        framework: m.framework,
+        targets: m.targets,
+        include: m.include,
+        gateToken: m.gateToken,
+        shims: m.shims,
+        kconfig: Array.isArray(m.kconfig) ? m.kconfig.filter((k) => typeof k === "string") : [],
+        overlay: typeof m.overlay === "string" ? m.overlay : undefined,
+    };
+}
+/**
+ * Resolve the package root for a bare npm specifier from the importing file,
+ * then register the package as a cuttlefish library if it ships a
+ * `cuttlefish.library.json`. Returns true when the specifier resolved to a
+ * registered library (the import must then be skipped by the graph builder).
+ */
+export function registerCuttlefishLibraryFromSpecifier(fromFile, moduleSpecifier) {
+    // Only bare npm specifiers ('pkg' or '@scope/pkg'[/subpath]) — relative
+    // imports and node builtins cannot be library packages.
+    if (moduleSpecifier.startsWith(".") || moduleSpecifier.startsWith("node:")) {
+        return false;
+    }
+    const cacheKey = moduleSpecifier.toLowerCase();
+    if (knownNonLibraries.has(cacheKey))
+        return false;
+    if (registered.has(cacheKey))
+        return true;
+    let packageRoot;
+    try {
+        const req = createRequire(path.resolve(fromFile));
+        // Resolve the package entry, then walk up to the nearest package.json —
+        // the package root. (Resolving the manifest subpath directly would be
+        // blocked by exports encapsulation; the entry point always resolves.)
+        const entry = req.resolve(moduleSpecifier);
+        let dir = path.dirname(entry);
+        while (dir !== path.dirname(dir)) {
+            if (fs.existsSync(path.join(dir, "package.json")))
+                break;
+            dir = path.dirname(dir);
+        }
+        if (dir !== path.dirname(dir))
+            packageRoot = dir;
+    }
+    catch {
+        packageRoot = undefined;
+    }
+    if (packageRoot === undefined) {
+        knownNonLibraries.add(cacheKey);
+        return false;
+    }
+    const manifest = parseManifest(packageRoot);
+    if (manifest === undefined) {
+        knownNonLibraries.add(cacheKey);
+        return false;
+    }
+    registered.set(cacheKey, { manifest, packageRoot });
+    return true;
+}
+/** Libdef entries for the registry: import → shim include. */
+export function cuttlefishLibraryLibdefs() {
+    return getRegisteredCuttlefishLibraries().map(({ manifest }) => ({
+        module: manifest.module,
+        include: manifest.include,
+    }));
+}
+/**
+ * Validate registered libraries against the loaded framework (and, when
+ * known, the build target). Throws with an actionable message when a library
+ * cannot work in this project — far earlier and clearer than the native
+ * compiler would.
+ */
+export function validateCuttlefishLibraries(frameworkId, buildTarget) {
+    for (const { manifest } of getRegisteredCuttlefishLibraries()) {
+        if (manifest.framework !== frameworkId) {
+            throw new Error(`Library ${manifest.module} requires the '${manifest.framework}' framework, ` +
+                `but this project uses '${frameworkId}'. ` +
+                `Install the matching framework or a '${frameworkId}' counterpart of this library.`);
+        }
+        if (buildTarget !== undefined &&
+            manifest.targets !== undefined &&
+            manifest.targets.length > 0 &&
+            !manifest.targets.some((t) => buildTarget.toLowerCase().startsWith(t.toLowerCase()))) {
+            throw new Error(`Library ${manifest.module} supports board targets ` +
+                `[${manifest.targets.join(", ")}], but this project builds for '${buildTarget}'.`);
+        }
+    }
+}
+function writeIfChanged(filePath, content) {
+    try {
+        if (fs.existsSync(filePath) && fs.readFileSync(filePath, "utf8") === content)
+            return;
+    }
+    catch {
+        /* fall through and write */
+    }
+    fs.writeFileSync(filePath, content);
+}
+function readEmittedTokens(srcDir) {
+    let out = "";
+    let names = [];
+    try {
+        names = fs.readdirSync(srcDir);
+    }
+    catch {
+        return "";
+    }
+    for (const name of names) {
+        if (!/\.(cpp|cc|c|h|hpp|ino)$/.test(name))
+            continue;
+        try {
+            out += fs.readFileSync(path.join(srcDir, name), "utf8");
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return out;
+}
+function readSidecar(sidecarPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((e) => typeof e === "object" && e !== null && typeof e.module === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Emit the library artifacts for the libraries actually used in this
+ * transpilation, and write the `libraries.json` sidecar:
+ *
+ *   1. scan the emitted sources for each library's gate token;
+ *   2. write (write-if-changed) the shims of every gated library into the
+ *      emitted source directory — the framework scaffold's CMake/program
+ *      regen picks the sources up automatically;
+ *   3. delete shim files recorded in the previous sidecar that are no longer
+ *      used, so removing an import removes its native code;
+ *   4. persist the sidecar (even when empty — that clears stale state).
+ */
+export function writeCuttlefishLibraryArtifacts(outDir, srcDir) {
+    const sidecarPath = path.join(outDir, LIBRARY_SIDECAR_NAME);
+    const previous = readSidecar(sidecarPath);
+    const previousShims = new Set(previous.flatMap((e) => e.shims));
+    const emitted = readEmittedTokens(srcDir);
+    const usedShims = new Set();
+    const entries = [];
+    for (const { manifest, packageRoot } of getRegisteredCuttlefishLibraries()) {
+        if (!emitted.includes(manifest.gateToken))
+            continue;
+        for (const shim of manifest.shims) {
+            let content;
+            try {
+                content = fs.readFileSync(path.join(packageRoot, shim.path), "utf8");
+            }
+            catch {
+                continue; // broken library packaging — the missing header surfaces at compile
+            }
+            writeIfChanged(path.join(srcDir, shim.outName), content);
+            usedShims.add(shim.outName);
+        }
+        entries.push({
+            id: manifest.id,
+            module: manifest.module,
+            framework: manifest.framework,
+            gateToken: manifest.gateToken,
+            kconfig: manifest.kconfig ?? [],
+            overlay: manifest.overlay ? path.join(packageRoot, manifest.overlay) : null,
+            shims: manifest.shims.map((s) => s.outName).filter((n) => usedShims.has(n)),
+        });
+    }
+    // Remove shims from a previous build whose library is no longer used.
+    for (const name of previousShims) {
+        if (usedShims.has(name))
+            continue;
+        try {
+            fs.rmSync(path.join(srcDir, name), { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    writeIfChanged(sidecarPath, JSON.stringify(entries, null, 2) + "\n");
+}
+/**
+ * Read the `libraries.json` sidecar for build-time consumers (framework
+ * toolchains). Tolerant of a missing or corrupt file (returns []).
+ */
+export function readCuttlefishLibrarySidecar(outDir) {
+    return readSidecar(path.join(outDir, LIBRARY_SIDECAR_NAME));
+}
+/** Re-exported for transpile.ts libdef injection convenience. */
+export function libraryDefinitionKey(module) {
+    return toModuleKey(module);
+}

package/dist/mapping/peripheral-names.js

@@ -20,14 +20,19 @@ export function mapPeripheralName(name, strategy) {
         if (mapped)
             return mapped;
     }
-    // Default fallbacks if strategy doesn't provide a mapping
+    // Default fallbacks if strategy doesn't provide a mapping: the canonical
+    // TypeCAD controller names. (The Arduino object names — Serial/Wire/SPI —
+    // went with framework-arduino; every live consumer only parses the
+    // trailing controller digit, which the canonical names carry too.)
     const canonical = name.toUpperCase();
     if (canonical === "UART0")
-        return "Serial";
+        return "UART0";
     if (canonical === "I2C0")
-        return "Wire";
+        return "I2C0";
     if (canonical === "SPI0")
-        return "SPI";
+        return "SPI0";
+    if (canonical === "USB0")
+        return "USB0";
     return undefined;
 }
 // ---------------------------------------------------------------------------

package/dist/mapping/source-map.d.ts

@@ -3,12 +3,11 @@ export declare function writeSourceMap(map: GeneratedSourceMap): string;
 export declare function readSourceMap(mapPath: string): GeneratedSourceMap;
 export declare function makeGeneratedMap(generatedFilePath: string, sourceFilePath: string, entries: SourceMapEntry[]): GeneratedSourceMap;
 export declare function mapCppLocationToTs(map: GeneratedSourceMap, cppLine: number, cppColumn: number, message?: string, cppFilePath?: string): MappedDiagnostic;
-export declare function resolveMapPath(mapFileOrGeneratedFile: string): string;
 /**
- * Resolve source map path for a flattened Arduino sketch
- * When a sketch is flattened, the source map needs to account for merged files
+ * Resolve source map path for a generated program
+ * When a program is flattened, the source map needs to account for merged files
  */
-export declare function resolveSourceMapForSketch(sketchPath: string, originalSourceMapPath?: string): string | undefined;
+export declare function resolveSourceMapForProgram(programPath: string, originalSourceMapPath?: string): string | undefined;
 /**
  * Index of every per-file source map in a build directory, keyed by the
  * normalized generated file path (the .cpp/.h each map covers).

package/dist/mapping/source-map.js

@@ -80,42 +80,36 @@ export function mapCppLocationToTs(map, cppLine, cppColumn, message, cppFilePath
         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
+ * Resolve source map path for a generated program
+ * When a program 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));
+export function resolveSourceMapForProgram(programPath, originalSourceMapPath) {
+    const programDir = path.dirname(programPath);
+    const programName = path.basename(programPath, path.extname(programPath));
     // First try the original source map path
     if (originalSourceMapPath && fs.existsSync(originalSourceMapPath)) {
         return originalSourceMapPath;
     }
-    // Try to find source maps for the sketch directory
+    // Try to find source maps for the program 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
+        path.join(programDir, `${programName}.thcppmap.json`),
+        path.join(programDir, `${programName}.cpp.thcppmap.json`),
+        path.join(programDir, "example.thcppmap.json"), // Common case for example programs
     ];
     for (const mapPath of possibleMaps) {
         if (fs.existsSync(mapPath)) {
             return mapPath;
         }
     }
-    // Look for any .thcppmap.json files in the sketch directory
+    // Look for any .thcppmap.json files in the program directory
     try {
-        const files = fs.readdirSync(sketchDir);
+        const files = fs.readdirSync(programDir);
         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);
+            return path.join(programDir, latest);
         }
     }
     catch {

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

@@ -12,10 +12,10 @@ export declare function topologicalSortFiles(files: string[], dependencies: Map<
  * 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'`).
+ * @param boardTarget  When provided, `@typecad/board` imports fall back to
+ *                      this package specifier (legacy; generated boards win).
  */
-export declare function collectTranspileGraph(entryFile: string, boardPackage?: string, imageDecodeOpts?: {
+export declare function collectTranspileGraph(entryFile: string, boardTarget?: string, imageDecodeOpts?: {
     maxW?: number;
     maxH?: number;
 }): Promise<TranspileGraphResult>;