@typecad/cuttlefish 1.0.0-alpha.3 → 1.0.0-alpha.7

package/dist/lint-cache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persistent cache for the ESLint build gate.
+ *
+ * ESLint is a mandatory correctness gate: it excludes non-AOT code patterns
+ * that the transpiler cannot accept. Running it on every `cuttlefish build`
+ * costs ~3s (38% of a small-project build) and almost always finds nothing on
+ * repeat runs. Its result (zero errors) is a whole-program boolean that
+ * depends only on a small set of inputs, so it is cleanly cacheable.
+ *
+ * Soundness contract:
+ *   - The cache ONLY records a successful (zero-error) lint result.
+ *   - A failing lint never persists (the build aborts anyway).
+ *   - On ANY input change the entry is invalidated and ESLint runs for real.
+ *   - `options.force` and the `CUTTLEFISH_NO_CACHE` env var bypass entirely.
+ *
+ * This mirrors the historical `.cuttlefish-cache.json` timestamp+hash cache
+ * that used to live in this package. It is scoped to the ESLint gate (and the
+ * type-check gate) rather than the transpile-IR pass, because — unlike IR
+ * lowering — these gates' outcomes are whole-program booleans with no
+ * cross-module rehydration requirement.
+ */
+/** Resolve the eslint config the same way runEslintCheck does, to avoid drift. */
+export declare function resolveEslintConfigPath(projectRoot: string): string | undefined;
+/**
+ * Compute the inputs that the ESLint result depends on. Two builds with the
+ * same fingerprint are guaranteed to produce the same lint outcome.
+ */
+export interface LintFingerprint {
+    digest: string;
+    /** Absolute paths that were hashed into the digest (for debugging). */
+    inputs: string[];
+}
+export declare function computeLintFingerprint(projectRoot: string, srcDir: string): LintFingerprint | null;
+export interface GateCacheResult {
+    /** True when the gate can be skipped because the recorded success still holds. */
+    hit: boolean;
+    /** The fingerprint to record after a successful gate run. */
+    fingerprint: LintFingerprint | null;
+}
+/**
+ * Decide whether the ESLint gate can be skipped for this project.
+ *
+ * Returns `hit: true` only when:
+ *   - caching is not disabled, not force-bypassed,
+ *   - a fingerprint can be computed (config + eslint resolvable), and
+ *   - the on-disk cache records a success for that exact fingerprint.
+ *
+ * `force` mirrors TranspileOptions.force and bypasses the cache.
+ */
+export declare function checkLintCache(projectRoot: string, srcDir: string, opts?: {
+    force?: boolean;
+}): GateCacheResult;
+/**
+ * Record a successful ESLint run (zero errors). Never call this after a
+ * failing run — a failing build must not persist a "clean" marker.
+ */
+export declare function recordLintSuccess(projectRoot: string, fingerprint: LintFingerprint): void;
+/** Drop the lint entry (used when the gate is skipped entirely / nothing to cache). */
+export declare function invalidateLint(projectRoot: string): void;

package/dist/lint-cache.js

@@ -0,0 +1,257 @@
+/**
+ * Persistent cache for the ESLint build gate.
+ *
+ * ESLint is a mandatory correctness gate: it excludes non-AOT code patterns
+ * that the transpiler cannot accept. Running it on every `cuttlefish build`
+ * costs ~3s (38% of a small-project build) and almost always finds nothing on
+ * repeat runs. Its result (zero errors) is a whole-program boolean that
+ * depends only on a small set of inputs, so it is cleanly cacheable.
+ *
+ * Soundness contract:
+ *   - The cache ONLY records a successful (zero-error) lint result.
+ *   - A failing lint never persists (the build aborts anyway).
+ *   - On ANY input change the entry is invalidated and ESLint runs for real.
+ *   - `options.force` and the `CUTTLEFISH_NO_CACHE` env var bypass entirely.
+ *
+ * This mirrors the historical `.cuttlefish-cache.json` timestamp+hash cache
+ * that used to live in this package. It is scoped to the ESLint gate (and the
+ * type-check gate) rather than the transpile-IR pass, because — unlike IR
+ * lowering — these gates' outcomes are whole-program booleans with no
+ * cross-module rehydration requirement.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CACHE_VERSION = 2;
+const DEFAULT_CACHE_NAME = ".cuttlefish-cache.json";
+/** Bypass the cache entirely when set (debugging / CI cold runs). */
+function isCacheDisabled() {
+    return process.env.CUTTLEFISH_NO_CACHE === "1" || process.env.CUTTLEFISH_NO_CACHE === "true";
+}
+/**
+ * Hash a file's content. Returns null if the file cannot be read (treated as
+ * "changed" by callers because the input set is no longer what we recorded).
+ */
+function hashFile(absPath) {
+    try {
+        const content = fs.readFileSync(absPath, "utf8");
+        return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hash size + mtime for a file. Used for inputs (eslint config, eslint package)
+ * that we don't want to fully read on every build, and whose identity is
+ * sufficiently captured by size+mtime. Returns null if the file is missing.
+ */
+function fingerprintStat(absPath) {
+    try {
+        const stat = fs.statSync(absPath);
+        return `${stat.size}:${stat.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Transpiler-self fingerprint: invalidate every cache entry when the
+ * transpiler's own compiled sources change. Mirrors the historical
+ * computeToolchainFingerprint() in incremental-cache.ts.
+ */
+let cachedToolchainFingerprint;
+function computeToolchainFingerprint() {
+    if (cachedToolchainFingerprint !== undefined)
+        return cachedToolchainFingerprint;
+    const candidates = [
+        "transpile.js",
+        "lint-cache.js",
+        "eslint-check.js",
+        path.join("emit", "cpp-emitter.js"),
+        path.join("ir", "build-ir.js"),
+        path.join("ir", "ownership-analysis.js"),
+        path.join("ir", "validation-orchestrator.js"),
+    ];
+    const signature = candidates
+        .map((rel) => path.join(__dirname, rel))
+        .filter((p) => fs.existsSync(p))
+        .map((p) => {
+        const stat = fs.statSync(p);
+        return `${path.basename(p)}:${stat.size}:${stat.mtimeMs}`;
+    })
+        .join("|");
+    cachedToolchainFingerprint = crypto.createHash("sha256").update(signature).digest("hex").slice(0, 16);
+    return cachedToolchainFingerprint;
+}
+/** Resolve the eslint config the same way runEslintCheck does, to avoid drift. */
+export function resolveEslintConfigPath(projectRoot) {
+    const cuttlefishConfig = path.join(projectRoot, ".cuttlefish", "eslint.config.mjs");
+    if (fs.existsSync(cuttlefishConfig))
+        return cuttlefishConfig;
+    for (const name of ["eslint.config.mjs", "eslint.config.js", "eslint.config.cjs"]) {
+        const candidate = path.join(projectRoot, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Resolve the eslint package version that runEslintCheck would load. */
+function resolveEslintIdentity(projectRoot) {
+    const resolvers = [
+        createRequire(path.join(projectRoot, "package.json")),
+        require,
+    ];
+    for (const r of resolvers) {
+        try {
+            const eslintPath = r.resolve("eslint");
+            const pkgPath = r.resolve("eslint/package.json");
+            const version = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version ?? "unknown";
+            return { path: eslintPath, version };
+        }
+        catch {
+            // try next resolver
+        }
+    }
+    return null;
+}
+/** Recursively gather .ts/.tsx/.ui files under a directory (the lint input set). */
+function gatherSourceFiles(srcDir) {
+    const out = [];
+    if (!fs.existsSync(srcDir) || !fs.statSync(srcDir).isDirectory())
+        return out;
+    const stack = [srcDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === "out" || entry.name.startsWith("out-"))
+                    continue;
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                const ext = entry.name.toLowerCase();
+                if (ext.endsWith(".ts") || ext.endsWith(".tsx") || ext.endsWith(".ui")) {
+                    out.push(full);
+                }
+            }
+        }
+    }
+    out.sort();
+    return out;
+}
+export function computeLintFingerprint(projectRoot, srcDir) {
+    const configPath = resolveEslintConfigPath(projectRoot);
+    if (!configPath)
+        return null; // no config => runEslintCheck returns [] without loading eslint
+    const eslint = resolveEslintIdentity(projectRoot);
+    if (!eslint)
+        return null; // eslint unresolvable => runEslintCheck returns []
+    const parts = [];
+    parts.push(["toolchain", computeToolchainFingerprint()]);
+    parts.push(["eslint", `${eslint.version}@${eslint.path}`]);
+    parts.push(["config", `${configPath}:${fingerprintStat(configPath) ?? "missing"}`]);
+    const sources = gatherSourceFiles(srcDir);
+    for (const f of sources) {
+        const h = hashFile(f);
+        parts.push(["src", `${f}:${h ?? "missing"}`]);
+    }
+    const digest = crypto
+        .createHash("sha256")
+        .update(parts.map((p) => p.join("=")).join("\n"))
+        .digest("hex")
+        .slice(0, 32);
+    return { digest, inputs: parts.map((p) => p[1]) };
+}
+function cachePathFor(projectRoot) {
+    return path.join(projectRoot, DEFAULT_CACHE_NAME);
+}
+function loadCacheFile(projectRoot) {
+    const cachePath = cachePathFor(projectRoot);
+    try {
+        if (!fs.existsSync(cachePath))
+            return null;
+        const data = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+        if (data.version === CACHE_VERSION &&
+            data.toolchainFingerprint === computeToolchainFingerprint() &&
+            path.resolve(data.rootDir) === path.resolve(projectRoot)) {
+            return data;
+        }
+    }
+    catch {
+        // Corrupt or unreadable — treat as empty.
+    }
+    return null;
+}
+function saveCacheFile(projectRoot, data) {
+    data.updatedAt = Date.now();
+    try {
+        fs.writeFileSync(cachePathFor(projectRoot), JSON.stringify(data, null, 2), "utf8");
+    }
+    catch {
+        // Non-fatal: caching is best-effort. Next build just re-runs the gate.
+    }
+}
+function freshCacheFile(projectRoot) {
+    return {
+        version: CACHE_VERSION,
+        toolchainFingerprint: computeToolchainFingerprint(),
+        rootDir: path.resolve(projectRoot),
+        gates: {},
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    };
+}
+/**
+ * Decide whether the ESLint gate can be skipped for this project.
+ *
+ * Returns `hit: true` only when:
+ *   - caching is not disabled, not force-bypassed,
+ *   - a fingerprint can be computed (config + eslint resolvable), and
+ *   - the on-disk cache records a success for that exact fingerprint.
+ *
+ * `force` mirrors TranspileOptions.force and bypasses the cache.
+ */
+export function checkLintCache(projectRoot, srcDir, opts = {}) {
+    const fingerprint = computeLintFingerprint(projectRoot, srcDir);
+    if (fingerprint === null)
+        return { hit: false, fingerprint: null };
+    if (opts.force || isCacheDisabled())
+        return { hit: false, fingerprint };
+    const data = loadCacheFile(projectRoot);
+    if (!data)
+        return { hit: false, fingerprint };
+    const entry = data.gates.lint;
+    return { hit: entry?.digest === fingerprint.digest, fingerprint };
+}
+/**
+ * Record a successful ESLint run (zero errors). Never call this after a
+ * failing run — a failing build must not persist a "clean" marker.
+ */
+export function recordLintSuccess(projectRoot, fingerprint) {
+    if (isCacheDisabled())
+        return;
+    const data = loadCacheFile(projectRoot) ?? freshCacheFile(projectRoot);
+    data.gates.lint = { digest: fingerprint.digest, recordedAt: Date.now() };
+    saveCacheFile(projectRoot, data);
+}
+/** Drop the lint entry (used when the gate is skipped entirely / nothing to cache). */
+export function invalidateLint(projectRoot) {
+    const data = loadCacheFile(projectRoot);
+    if (data && data.gates.lint) {
+        delete data.gates.lint;
+        saveCacheFile(projectRoot, data);
+    }
+}

package/dist/orchestrator/graph-builder.js

@@ -167,14 +167,18 @@ export function collectTranspileGraph(entryFile, boardPackage) {
             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
+            // Skip @typecad/board, @typecad/board-*, @typecad/mcu-*, @typecad/hal,
+            // 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).
+            // Skipping @typecad/hal is especially important: its 28 source files
+            // (gpio.ts, i2c.ts, spi.ts, etc.) were all walked through full
+            // buildProgramIR, adding ~40 seconds to every transpile.
             if (moduleSpecifier === "@typecad/board"
+                || moduleSpecifier === "@typecad/hal"
                 || moduleSpecifier.startsWith("@typecad/board-")
                 || moduleSpecifier.startsWith("@typecad/mcu-")
                 || moduleSpecifier.startsWith("@typecad/framework-")) {

package/dist/stores/display-profile-store.d.ts

@@ -9,6 +9,7 @@ export declare function setDisplayProfile(profile: DisplayProfile, wiring: {
     address?: number;
     reset?: number;
     buildTarget?: string;
+    psram?: boolean;
 }): void;
 /** Get the current display profile, or a default if none set. */
 export declare function getDisplayProfile(): ResolvedDisplay;

package/dist/stores/display-profile-store.js

@@ -20,6 +20,7 @@ export function setDisplayProfile(profile, wiring) {
         _mountAddress: wiring.address ?? 0x3C,
         _mountReset: wiring.reset ?? -1,
         _buildTarget: wiring.buildTarget,
+        _psram: wiring.psram,
     };
 }
 /** Get the current display profile, or a default if none set. */

package/dist/testing.d.ts

@@ -15,7 +15,7 @@ export type { EmitMode, GeneratedOutputs, TargetProfile, PlatformContext } from
 export { findConfigFile, parseConfigFile, loadCuttlefishConfig, generateVirtualTypeDeclaration, } from "./config-loader.js";
 export { transpileFile } from "./transpile.js";
 export { resetUIEngine, __simulateUIAbsentForTest } from "./ui/ui-bridge.js";
-export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
+export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
 export type { InitProjectOptions } from "./create/index.js";
 export { scaffoldBoardPackages, parseBoardSpec, safeParseBoardSpec, stripJsonc, } from "./create/index.js";
 export type { BoardSpec, ScaffoldBoardResult } from "./create/index.js";
@@ -30,6 +30,8 @@ export { LINT_RULES, ESLINT_OPT_OUT_KINDS, kindRegistryEntries, } from "./ir/fea
 export type { LintRule, FeatureEntry, FeatureStatus, DiagnosticMatch } from "./ir/feature-registry.js";
 export { runEslintCheck } from "./eslint-check.js";
 export type { ESLintError } from "./eslint-check.js";
+export { checkLintCache, recordLintSuccess, invalidateLint, computeLintFingerprint, resolveEslintConfigPath, } from "./lint-cache.js";
+export type { LintFingerprint, GateCacheResult } from "./lint-cache.js";
 export { runSemanticGates } from "./orchestrator/type-checker.js";
 export { canonicalize, buildSemanticFacts, } from "./orchestrator/semantic-facts.js";
 export type { CanonicalType, SemanticFacts, FactStore, ValueCategory, Lifetime, Nullable, SemanticOrigin, AnalysisResult, BindingResolver, } from "./orchestrator/semantic-facts.js";
@@ -40,7 +42,7 @@ export { parseCommandLine } from "./utils/cli.js";
 export { parseHeader, stripPreprocessorBlocks } from "./libdef/header-parser.js";
 export { BaseClassResolver, buildClassIndex } from "./libdef/base-class-resolver.js";
 export type { ResolveResult } from "./libdef/base-class-resolver.js";
-export { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
+export { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
 export { renderExprAsText } from "./ir/render-expr.js";
 export { contextStorage, CompilationContext } from "./ir/build-ir-state.js";
 export type { ExpressionIR } from "./api/index.js";

package/dist/testing.js

@@ -18,7 +18,7 @@ export { transpileFile } from "./transpile.js";
 // ── UI bridge (optional @typecad/ui) ─────────────────────────────────────────
 export { resetUIEngine, __simulateUIAbsentForTest } from "./ui/ui-bridge.js";
 // ── Project scaffolding ──────────────────────────────────────────────────────
-export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
+export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
 // ── Board codegen (`cuttlefish board add`) ───────────────────────────────────
 export { scaffoldBoardPackages, parseBoardSpec, safeParseBoardSpec, stripJsonc, } from "./create/index.js";
 export { BoardGenerators } from "./create/index.js";
@@ -34,6 +34,8 @@ export { prescanUnsupportedFeatures } from "./ir/feature-prescan.js";
 export { LINT_RULES, ESLINT_OPT_OUT_KINDS, kindRegistryEntries, } from "./ir/feature-registry.js";
 // ── ESLint gate ──────────────────────────────────────────────────────────────
 export { runEslintCheck } from "./eslint-check.js";
+// ── ESLint gate cache ────────────────────────────────────────────────────────
+export { checkLintCache, recordLintSuccess, invalidateLint, computeLintFingerprint, resolveEslintConfigPath, } from "./lint-cache.js";
 // ── Semantic gates (TypeChecker-based) ──────────────────────────────────────
 export { runSemanticGates } from "./orchestrator/type-checker.js";
 export { canonicalize, buildSemanticFacts, } from "./orchestrator/semantic-facts.js";
@@ -43,7 +45,7 @@ export { discoverWatchDirs, isRelevantChange } from "./watch.js";
 export { parseCommandLine } from "./utils/cli.js";
 export { parseHeader, stripPreprocessorBlocks } from "./libdef/header-parser.js";
 export { BaseClassResolver, buildClassIndex } from "./libdef/base-class-resolver.js";
-export { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
+export { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
 // ── IR rendering internals (for fail-closed regression tests) ───────────────
 export { renderExprAsText } from "./ir/render-expr.js";
 export { contextStorage, CompilationContext } from "./ir/build-ir-state.js";

package/dist/transpile.d.ts

@@ -1,3 +1,6 @@
 import { GenerateLibdefOptions, GeneratedOutputs, TranspileOptions } from "./types.js";
+import { loadFrameworkPackage } from "./framework-package.js";
+export { loadFrameworkPackage };
+export { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
 export declare function transpileFile(options: TranspileOptions): Promise<GeneratedOutputs>;
 export declare function generateLibraryDefinitions(options: GenerateLibdefOptions): string[];

package/dist/transpile.js

@@ -19,7 +19,7 @@ import { clearCaches, } from "./cache.js";
 import { detectEntryPoints, detectExportedEntryPoints } from "./ir/entry-points.js";
 import { analyzeReachability } from "./ir/reachability.js";
 import { filterProgramIR } from "./ir/filter.js";
-import { setActiveStrategy } from "./ir/hal-resolver.js";
+import { setActiveStrategy, loadHALModules } from "./ir/hal-resolver.js";
 import { CompilationContext, contextStorage } from "./ir/build-ir-state.js";
 import { buildSymbolTable, mergeSymbolTable, resolveInheritance, createSymbolTable } from "./ir/symbol-table.js";
 import { loadBreakpoints, preprocess as debugPreprocess } from "./debug/index.js";
@@ -28,6 +28,7 @@ import { typeCheckFiles } from "./orchestrator/type-checker.js";
 import { runSemanticGates } from "./orchestrator/type-checker.js";
 import { autoGenerateMissingDecls } from "./orchestrator/dts-generator.js";
 import { runEslintCheck, printEslintErrors } from "./eslint-check.js";
+import { checkLintCache, recordLintSuccess } from "./lint-cache.js";
 import { initProfiler, getProfiler } from "./profiler/index.js";
 import { buildDiagnosticsReport, writeDiagnosticsReport } from "./diagnostics/diagnostics-report.js";
 import { resolveImport, } from "./transpile/resolution.js";
@@ -47,17 +48,12 @@ function loadExpectPreprocessor() {
     }
 }
 function cleanOutput(_entryDir, outDir) {
-    // NOTE: incremental transpilation is disabled (see incremental-cache.ts).
-    // Only the output directory is cleaned; do not delete .cuttlefish-cache.json
-    // here so a future incremental implementation can read prior metadata.
-    try {
-        if (fs.existsSync(outDir))
-            fs.rmSync(outDir, { recursive: true, force: true });
-    }
-    catch (e) {
-        if (process.env.CUTTLEFISH_DEBUG)
-            console.error("[transpile] Failed to clean output dir:", e);
-    }
+    // Preserved for incremental-build support: writeText now skips writing when
+    // content is identical, so keeping the existing output dir intact lets
+    // downstream build tools (idf.py/ninja, arduino-cli) reuse their build
+    // caches. Stale files from removed source modules are harmless — they're
+    // not referenced by the current entry file and won't be compiled.
+    // The output dir is still created (via writeText → ensureDir) on first run.
 }
 /**
  * Auto-generates .d.ts files for C++ modules that are missing declarations.
@@ -131,6 +127,8 @@ function applyTreeShaking(programIR, target, treeShakingOptions) {
 import { isStringEnum } from "./api/shared/index.js";
 import { resolveStrategy } from "./platform/registry.js";
 import { loadFrameworkPackage } from "./framework-package.js";
+export { loadFrameworkPackage };
+export { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
 import { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
 function formatFatalDiagnostics(entries) {
     const errors = entries.filter(({ diagnostic }) => diagnostic.severity === "error");
@@ -138,8 +136,9 @@ function formatFatalDiagnostics(entries) {
         `Transpilation aborted because ${errors.length} unsupported pattern${errors.length === 1 ? "" : "s"} were found.`,
     ];
     for (const { filePath, diagnostic } of errors) {
-        const locationBase = filePath
-            ? path.relative(process.cwd(), filePath) || filePath
+        const resolvedFile = filePath ?? diagnostic.filePath;
+        const locationBase = resolvedFile
+            ? path.relative(process.cwd(), resolvedFile) || resolvedFile
             : diagnostic.source ?? "user code";
         const position = diagnostic.line != null
             ? `(${diagnostic.line}:${diagnostic.column ?? 1})`
@@ -241,16 +240,33 @@ export async function transpileFile(options) {
             // Load built-in profiles from the framework package via its exported path
             const registry = new Map();
             if (options.frameworkPackage) {
+                // Built-in display profiles live in the framework's displays/ili9341-spi
+                // module. Non-Arduino frameworks (avr, esp32) may not ship their own
+                // profile registry — fall back to framework-arduino, which all current
+                // frameworks depend on and which owns the canonical profile definitions.
                 const profileMod = await import(options.frameworkPackage + "/displays/ili9341-spi").catch(() => null);
-                if (profileMod?.BUILT_IN_PROFILES) {
-                    for (const [k, v] of Object.entries(profileMod.BUILT_IN_PROFILES)) {
-                        registry.set(k, v);
+                // The fallback uses a non-literal specifier so tsc does not require
+                // framework-arduino to be a build-time dependency (it is an optional
+                // runtime fallback — frameworks like avr/esp32 may not ship their own
+                // profile registry). Declaring it as a dependency would create a cycle
+                // (framework-arduino already depends on cuttlefish).
+                const fallbackPkg = "@typecad/framework-arduino";
+                const fallbackMod = (options.frameworkPackage !== fallbackPkg)
+                    ? await import(fallbackPkg + "/displays/ili9341-spi").catch(() => null)
+                    : null;
+                for (const mod of [profileMod, fallbackMod]) {
+                    if (mod?.BUILT_IN_PROFILES) {
+                        for (const [k, v] of Object.entries(mod.BUILT_IN_PROFILES)) {
+                            registry.set(k, v);
+                        }
                     }
                 }
             }
             const resolved = resolveDisplayProfile(configDisplay, registry);
             const buildTarget = options.platformContext?.frameworkData?.buildTarget;
-            setDisplayProfile(resolved.profile, { cs: resolved.cs, dc: resolved.dc, rst: resolved.rst, bus: resolved.bus, address: resolved.address, reset: resolved.reset, buildTarget });
+            const psramRaw = options.platformContext?.frameworkData?.psram;
+            const psram = psramRaw === 'opi' || psramRaw === 'quad';
+            setDisplayProfile(resolved.profile, { cs: resolved.cs, dc: resolved.dc, rst: resolved.rst, bus: resolved.bus, address: resolved.address, reset: resolved.reset, buildTarget, psram });
         }
         catch {
             // Fall back to default profile — not fatal
@@ -301,22 +317,43 @@ export async function transpileFile(options) {
     }
     // ── ESLint gate ──────────────────────────────────────────────────────────
     // ESLint catches what the type-checker cannot (idiom violations, banned
-    // globals, explicit `any`, etc.). Errors abort the build, mirroring the
-    // type-check behavior above. Skipped alongside type-checking when disabled.
+    // globals, explicit `any`, etc.). It is a mandatory correctness gate: it
+    // excludes non-AOT code patterns the transpiler cannot accept, so it cannot
+    // be dropped. Errors abort the build, mirroring the type-check behavior
+    // above. Skipped alongside type-checking when disabled.
+    //
+    // Because the lint result is a whole-program boolean that depends only on
+    // the source files, the eslint config, and the eslint/transpiler versions,
+    // it is cacheable. On a cache hit we skip the ~3s ESLint run entirely; on a
+    // miss we run ESLint and, only if clean, persist the result. See lint-cache.ts
+    // for the soundness contract.
     if (options.skipLint !== true && options.skipTypeCheck !== true && transpileFiles.length > 0) {
-        profiler.startTimer("lint:eslint");
         // The eslint config lives at the project root (next to cuttlefish.config.ts),
         // not under src/. Fall back to entryDir for ad-hoc API/test callers that pass
         // a bare input file without a configured project.
         const eslintRoot = options.projectRoot ?? entryDir;
-        const eslintErrors = await runEslintCheck(eslintRoot);
-        profiler.endTimer("lint:eslint");
-        if (eslintErrors.length > 0) {
-            // Abort with a formatted message. The structured-diagnostic channel is
-            // not populated here because a thrown error discards the output anyway;
-            // printEslintErrors gives the user file/line/column/caret directly.
-            printEslintErrors(eslintErrors);
-            throw new Error(`ESLint reported ${eslintErrors.length} error${eslintErrors.length === 1 ? "" : "s"} — transpilation aborted.`);
+        const lintCache = checkLintCache(eslintRoot, sourceDir, { force: options.force });
+        if (lintCache.hit) {
+            // Cache hit: previous clean run still applies, skip ESLint entirely.
+            profiler.startTimer("lint:eslint:cached");
+            profiler.endTimer("lint:eslint:cached");
+        }
+        else {
+            profiler.startTimer("lint:eslint");
+            const eslintErrors = await runEslintCheck(eslintRoot);
+            profiler.endTimer("lint:eslint");
+            if (eslintErrors.length > 0) {
+                // Abort with a formatted message. The structured-diagnostic channel is
+                // not populated here because a thrown error discards the output anyway;
+                // printEslintErrors gives the user file/line/column/caret directly.
+                // Do NOT persist a cache entry for a failing run.
+                printEslintErrors(eslintErrors);
+                throw new Error(`ESLint reported ${eslintErrors.length} error${eslintErrors.length === 1 ? "" : "s"} — transpilation aborted.`);
+            }
+            // Clean run: record the fingerprint so subsequent unchanged builds skip.
+            if (lintCache.fingerprint) {
+                recordLintSuccess(eslintRoot, lintCache.fingerprint);
+            }
         }
     }
     const npmPackages = graphResult.npmPackages;
@@ -336,7 +373,7 @@ export async function transpileFile(options) {
                 code: "themeCss-ui-entry-ignored",
                 message: `display.themeCss is ignored for .ui single-file entries; the inline <style> in ${path.basename(options.inputFile)} is the sole CSS source.`,
                 hint: `Move the standalone CSS into the .ui file's <style> block, or change the entry to a .ts file that imports a .ui.html module.`,
-                source: path.basename(options.inputFile),
+                filePath: path.basename(options.inputFile),
             });
         }
     }
@@ -348,7 +385,7 @@ export async function transpileFile(options) {
     if (hasUIHook()) {
         for (const mod of requireUIHook().allUIModules()) {
             for (const d of mod.diagnostics) {
-                diagnostics.push({ ...d, source: d.source ?? path.basename(mod.htmlPath) });
+                diagnostics.push({ ...d, filePath: d.filePath ?? path.basename(mod.htmlPath) });
             }
         }
     }
@@ -458,6 +495,15 @@ export async function transpileFile(options) {
     };
     profiler.startTimer("ir:build-all");
     profiler.captureMemorySnapshot("ir:pre-build");
+    // Load + parse the @typecad/hal source files ONCE for this transpile run.
+    // buildProgramIR used to force-reload HAL per graph file (O(files) re-reads
+    // and re-parses of all 28 HAL modules); warming it here makes the per-file
+    // loadHALModules() call inside buildProgramIR a cheap no-op. A fresh run of
+    // transpileFile always reaches this point, so edits to @typecad/hal source
+    // are picked up on the next build.
+    profiler.startTimer("ir:load-hal");
+    loadHALModules(true);
+    profiler.endTimer("ir:load-hal");
     const rawIRArray = await Promise.all(filesToProcess.map(buildRawIR));
     profiler.captureMemorySnapshot("ir:post-build");
     profiler.endTimer("ir:build-all");
@@ -466,7 +512,7 @@ export async function transpileFile(options) {
     if (hasUIHook()) {
         for (const mod of requireUIHook().allUIModules()) {
             for (const d of mod.mountDiagnostics) {
-                diagnostics.push({ ...d, source: d.source ?? path.basename(mod.htmlPath) });
+                diagnostics.push({ ...d, filePath: d.filePath ?? path.basename(mod.htmlPath) });
             }
         }
     }

package/dist/types.d.ts

@@ -114,7 +114,11 @@ export interface LibraryDefinition {
     variants?: LibraryDefinitionVariant[];
 }
 export interface CommandLineOptions {
-    command: "default" | "build" | "gen-libdefs" | "gen-decls" | "map-error" | "preview";
+    command: "default" | "build" | "gen-libdefs" | "gen-decls" | "map-error" | "preview" | "doctor" | "licenses";
+    /** For `licenses`: treat unknown/missing licenses as failures (exit 1). */
+    strict?: boolean;
+    /** For `licenses`: scan all installed libraries (default: this project's only). */
+    all?: boolean;
     inputFile?: string;
     emitMode: EmitMode;
     target: TargetProfile;