@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.11

package/dist/safety-hook.d.ts

@@ -0,0 +1,79 @@
+import type { HALOpIR, ProgramIR, RuntimePolyfillIR, Diagnostic } from "./api/shared/index.js";
+/** Context handed to transformIR. */
+export interface SafetyTransformContext {
+    /** True iff the entry file imports `safe` from @typecad/safety. The pass
+     *  uses this as a fast no-op guard. */
+    readonly safetyInUse: boolean;
+    /** Build target (e.g. "esp32", "avr"). Strategies still resolve the
+     *  underlying pinMode/digitalRead symbols; the safety package is target-
+     *  agnostic. */
+    readonly target: string;
+}
+/** Capabilities cuttlefish core needs from the safety engine.
+ *
+ *  Part A uses transformIR + resolveSafetyOp + resolveSemanticCall.
+ *  Part B (ISO 26262 Part 6 rules) adds analyzeIR; Part C (sidecar) will
+ *  add collectSafetyMetadata. Both reuse this same seam with no new core
+ *  machinery. */
+export interface TranspilerSafetyHook {
+    /** Post-build IR transform. Must return a (possibly new) ProgramIR. Part A
+     *  uses this to inject safety.record_pin_mode companions after every
+     *  gpio.pin_mode / safety.pin_mode op. Called only when hasSafetyHook(). */
+    transformIR(program: ProgramIR, ctx: SafetyTransformContext): ProgramIR;
+    /** Resolve a safety.* HAL op to C++ code or expression. Called from the
+     *  extended routeHALOp() for any op whose `operation` starts with "safety.".
+     *  NEVER delegated to a per-target strategy. Returns undefined if the op
+     *  is not recognized (caller emits an unhandled-op warning). */
+    resolveSafetyOp(op: HALOpIR): {
+        code?: string;
+        expression?: string;
+    } | undefined;
+    /** Lower a safe.* TS call to a HAL op. Called from an extension point in
+     *  tryResolveSemanticCall (hal-plugins.ts) when the callee resolves to the
+     *  @typecad/safety package. Returns undefined if not a safety call. */
+    resolveSemanticCall?(callee: string, args: readonly unknown[]): HALOpIR | undefined;
+    /** Provide safety runtime polyfills (mode table + voter). Called from
+     *  buildEmitterContext so the polyfills participate in tree-shaking.
+     *  Returns [] when safety is not in use. */
+    buildPolyfills?(): RuntimePolyfillIR[];
+    /** Part B: read-only ISO 26262 Part 6 software-rule analysis. Called
+     *  after transformIR completes, on the final transformed IR. Returns
+     *  diagnostics that flow into the build's diagnostic list. Diagnostics
+     *  with severity "error" abort the build (via throwIfFatalDiagnostics);
+     *  "warning"/"info" are logged but the build succeeds. */
+    analyzeIR?(program: ProgramIR, ctx: SafetyTransformContext): Diagnostic[];
+    /** Part C: collect safety metadata for sidecar artifact generation.
+     *  Called after analyzeIR completes. Returns structured metadata about
+     *  each safety-critical function (ASIL level, mechanisms, rule results)
+     *  that the caller writes to a sidecar JSON file. */
+    collectSafetyMetadata?(program: ProgramIR, ctx: SafetyTransformContext): SafetyMetadata[];
+}
+/** Set the safety hook. Called by transpile.ts after dynamically loading
+ *  @typecad/safety/engine. Passing null clears it. */
+export declare function setSafetyHook(hook: TranspilerSafetyHook | null): void;
+/** Get the current safety hook, or null if @typecad/safety is not loaded. */
+export declare function getSafetyHook(): TranspilerSafetyHook | null;
+/** Returns true if the safety hook is registered (i.e. @typecad/safety loaded). */
+export declare function hasSafetyHook(): boolean;
+/** Get the safety hook, throwing if it's not set. Use only inside
+ *  `if (hasSafetyHook())` guards. */
+export declare function requireSafetyHook(): TranspilerSafetyHook;
+export type { Diagnostic };
+/** Metadata about one safety-critical function, collected for Part C. */
+export interface SafetyFunctionMetadata {
+    name: string;
+    asilLevel: string;
+    source?: {
+        tsFile: string;
+        tsLine: number;
+    };
+    mechanisms: string[];
+    rules: Record<string, "pass" | {
+        severity: string;
+        message: string;
+    }>;
+}
+/** Result of Part C's metadata collection. */
+export interface SafetyMetadata {
+    functions: SafetyFunctionMetadata[];
+}

package/dist/safety-hook.js

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// Safety hook — the contract cuttlefish core uses to talk to the optional
+// @typecad/safety package. Modeled on ui-hook.ts.
+//
+// @typecad/safety is an optional peer dependency. When it is installed and
+// imported by a sketch, transpile.ts calls loadSafetyEngine() which dynamic-
+// imports @typecad/safety/engine and calls registerSafetyEngine() to push an
+// implementation of this interface into the registry. When absent, every
+// hasSafetyHook() guard returns false and cuttlefish behaves as before.
+// ---------------------------------------------------------------------------
+// ── Module-level hook state ────────────────────────────────────────────────
+let safetyHook = null;
+/** Set the safety hook. Called by transpile.ts after dynamically loading
+ *  @typecad/safety/engine. Passing null clears it. */
+export function setSafetyHook(hook) {
+    safetyHook = hook;
+}
+/** Get the current safety hook, or null if @typecad/safety is not loaded. */
+export function getSafetyHook() {
+    return safetyHook;
+}
+/** Returns true if the safety hook is registered (i.e. @typecad/safety loaded). */
+export function hasSafetyHook() {
+    return safetyHook !== null;
+}
+/** Get the safety hook, throwing if it's not set. Use only inside
+ *  `if (hasSafetyHook())` guards. */
+export function requireSafetyHook() {
+    if (!safetyHook) {
+        throw new Error("Safety hook is not registered. This code path requires @typecad/safety " +
+            "to be installed and loaded. This should not happen — the hook is set " +
+            "at the start of transpileFile() when safety is detected.");
+    }
+    return safetyHook;
+}

package/dist/testing.d.ts

@@ -12,10 +12,14 @@ export { inferSnprintfArg, createEmissionScopeState, escapeCppStringLiteral } fr
 export { setLoadedFramework } from "./framework-registry.js";
 export { registerPlatformStrategy, resolveStrategy, clearAllProfileCaches } from "./platform/registry.js";
 export type { EmitMode, GeneratedOutputs, TargetProfile, PlatformContext } from "./types.js";
+export { ComplianceContext, runSelfCheck, renderRegistryJson } from "./emit/compliance/index.js";
+export type { ComplianceMode, SelfCheckFinding, Deviation } from "./emit/compliance/index.js";
 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 { resetSafetyEngine, __simulateSafetyAbsentForTest } from "./safety/safety-bridge.js";
+export { setSafetyHook, hasSafetyHook } from "./safety-hook.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 +34,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 +46,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

@@ -11,14 +11,19 @@ export { analyzePeripheralUsage, createEmptyPeripheralUsage } from "./ir/periphe
 export { inferSnprintfArg, createEmissionScopeState, escapeCppStringLiteral } from "./emit/snprintf-helpers.js";
 export { setLoadedFramework } from "./framework-registry.js";
 export { registerPlatformStrategy, resolveStrategy, clearAllProfileCaches } from "./platform/registry.js";
+// ── AUTOSAR compliance module (test-visible) ───────────────────────────────
+export { ComplianceContext, runSelfCheck, renderRegistryJson } from "./emit/compliance/index.js";
 // ── Config loader ───────────────────────────────────────────────────────────
 export { findConfigFile, parseConfigFile, loadCuttlefishConfig, generateVirtualTypeDeclaration, } from "./config-loader.js";
 // ── Transpiler internal API ─────────────────────────────────────────────────
 export { transpileFile } from "./transpile.js";
 // ── UI bridge (optional @typecad/ui) ─────────────────────────────────────────
 export { resetUIEngine, __simulateUIAbsentForTest } from "./ui/ui-bridge.js";
+// ── Safety bridge (optional @typecad/safety) ────────────────────────────────
+export { resetSafetyEngine, __simulateSafetyAbsentForTest } from "./safety/safety-bridge.js";
+export { setSafetyHook, hasSafetyHook } from "./safety-hook.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 +39,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 +50,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

@@ -3,15 +3,33 @@ import path from "node:path";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import ts from "typescript";
+// Read once at module load. Used to populate the AUTOSAR deviation sidecar's
+// `toolVersion` field. Falls back to "unknown" if the read fails (e.g. tests
+// that import the module from an unexpected location).
+const CUTTLEFISH_VERSION = (() => {
+    try {
+        const require_ = createRequire(import.meta.url);
+        // transpile.ts lives in src/, compiled to dist/transpile.js. The package
+        // root is one level up from dist/, so from dist/ the path is ../package.json.
+        // From src/ (TypeScript source used by tests) it's also ../package.json.
+        const pkg = require_("../package.json");
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
 import { buildProgramIR } from "./ir/build-ir.js";
 import { classDeclarationToIR } from "./ir/declaration-builders.js";
 import { clickHandlers } from "./ir/transformers/ui-call-resolver.js";
 import { requireUIHook, hasUIHook } from "./ui-hook.js";
 import { loadUIEngine } from "./ui/ui-bridge.js";
+import { hasSafetyHook, requireSafetyHook } from "./safety-hook.js";
+import { loadSafetyEngine } from "./safety/safety-bridge.js";
 import { setDisplayProfile, resetDisplayProfile } from "./stores/display-profile-store.js";
 import { setThemeCss, resetThemeCss, setThemeClass } from "./stores/theme-store.js";
 import { emitCpp, registerAllEnumNames } from "./emit/cpp-emitter.js";
-import { readText } from "./utils/fs.js";
+import { readText, writeText } from "./utils/fs.js";
 import { debug as logDebug, info } from "./utils/logger.js";
 import { loadLibraryDefinitions, generateLibdefStubs } from "./libdef/registry.js";
 import { buildCallGraph } from "./ir/call-graph.js";
@@ -19,7 +37,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 +46,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,23 +66,30 @@ 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.
  * Also tries to generate declarations for framework libraries.
  * Returns list of generated files.
  */
+/**
+ * True iff the program imports `@typecad/safety` anywhere. The safety
+ * transform pass uses this as its fast no-op guard — when no file imports
+ * safety, the pass returns the program unchanged.
+ */
+function entryImportsSafety(program) {
+    for (const imp of program.imports) {
+        if (imp.moduleSpecifier === "@typecad/safety")
+            return true;
+    }
+    return false;
+}
 /**
  * Apply tree-shaking to program IR if enabled
  */
@@ -131,6 +157,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 +166,13 @@ 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
+        // Prefer diagnostic.filePath (set explicitly by the emitter, e.g. AUTOSAR
+        // diagnostics that map a C++ line back to TS) over the wrapper's filePath
+        // (the TS source file being processed, which may not be the right pointer
+        // for emit-stage diagnostics).
+        const resolvedFile = diagnostic.filePath ?? filePath;
+        const locationBase = resolvedFile
+            ? path.relative(process.cwd(), resolvedFile) || resolvedFile
             : diagnostic.source ?? "user code";
         const position = diagnostic.line != null
             ? `(${diagnostic.line}:${diagnostic.column ?? 1})`
@@ -216,6 +249,10 @@ export async function transpileFile(options) {
     // requireUIHook() works throughout this transpile run. Gracefully no-ops
     // when @typecad/ui is absent (pure TS→C++ transpile).
     await loadUIEngine();
+    // Load the safety engine from @typecad/safety (if installed). Sets up the
+    // hook so requireSafetyHook() works throughout this transpile run.
+    // Gracefully no-ops when @typecad/safety is absent.
+    await loadSafetyEngine();
     const entryFile = path.resolve(options.inputFile);
     const entryDir = path.dirname(entryFile);
     const sourceDir = entryDir;
@@ -237,24 +274,29 @@ export async function transpileFile(options) {
     const configDisplay = options.display;
     if (configDisplay) {
         const { resolveDisplayProfile } = await import("./api/shared/display-profile.js");
-        try {
-            // Load built-in profiles from the framework package via its exported path
-            const registry = new Map();
-            if (options.frameworkPackage) {
-                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);
-                    }
+        // Build the named-profile registry. Prefer the strategy's hook (per-framework
+        // canonical profiles — Arduino returns its BUILT_IN_PROFILES, Zephyr returns
+        // its DT-binding profiles). Fall back to the legacy dynamic import of the
+        // framework's displays/ili9341-spi module when the strategy provides none.
+        // The registry maps a config `profile` name (e.g. "st7796-zephyr") to its
+        // DisplayProfile; an empty registry makes resolveDisplayProfile fall back to
+        // the bare default driver (config.driver ?? "ili9341") when no profile name
+        // is set, or throw "Unknown display profile" when one is.
+        let registry = new Map();
+        if (strategy.getProfileRegistry) {
+            registry = strategy.getProfileRegistry();
+        }
+        else if (options.frameworkPackage) {
+            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);
                 }
             }
-            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 });
-        }
-        catch {
-            // Fall back to default profile — not fatal
         }
+        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 });
         // Apply theme CSS override if specified.
         if (configDisplay.themeCss) {
             setThemeCss(configDisplay.themeCss);
@@ -301,22 +343,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 +399,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 +411,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) });
             }
         }
     }
@@ -441,7 +504,13 @@ export async function transpileFile(options) {
             }
             sourceText = preprocess(sourceText, filePath);
         }
-        if (options.debug && breakpoints) {
+        // Printf instrumentation runs only in printf debug mode. In gdb mode
+        // (e.g. ESP32-S3), --debug emits #line markers at the emit stage and
+        // uses VS Code native breakpoints; the printf preprocessor is skipped
+        // so the source reaches IR/emit unmodified.
+        const buildTarget = options.platformContext?.frameworkData?.buildTarget;
+        const debugMode = strategy.debugMode?.(buildTarget) ?? 'printf';
+        if (options.debug && breakpoints && debugMode === 'printf') {
             const instrumented = debugPreprocess({
                 fileName: filePath,
                 breakpoints,
@@ -458,6 +527,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 +544,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) });
             }
         }
     }
@@ -619,6 +697,60 @@ export async function transpileFile(options) {
     profiler.startTimer("emit:register-enums");
     registerAllEnumNames(allEnumIRs);
     profiler.endTimer("emit:register-enums");
+    // ── Phase D: safety transform pass ──────────────────────────────────────
+    // When @typecad/safety is in use, run its post-build IR transform to inject
+    // safety ops (e.g. companion safety.record_pin_mode after every
+    // gpio.pin_mode). Produces new IR per file; no-op when safety is off or
+    // absent.
+    if (hasSafetyHook()) {
+        profiler.startTimer("safety:transform");
+        const hook = requireSafetyHook();
+        for (const [filePath, item] of preBuilt) {
+            const newIR = hook.transformIR(item.programIR, {
+                safetyInUse: entryImportsSafety(item.programIR),
+                target: options.target,
+            });
+            preBuilt.set(filePath, { ...item, programIR: newIR });
+        }
+        profiler.endTimer("safety:transform");
+        // Part B: ISO 26262 Part 6 read-only IR analysis. Runs after transformIR
+        // so it sees the final IR (including injected safety ops). Returned
+        // diagnostics flow into the build's diagnostic list; error-severity
+        // diagnostics abort via throwIfFatalDiagnostics.
+        if (hook.analyzeIR) {
+            profiler.startTimer("safety:analyze");
+            for (const [, item] of preBuilt) {
+                const irDiags = hook.analyzeIR(item.programIR, {
+                    safetyInUse: entryImportsSafety(item.programIR),
+                    target: options.target,
+                });
+                if (irDiags.length > 0) {
+                    diagnostics.push(...irDiags);
+                }
+            }
+            profiler.endTimer("safety:analyze");
+        }
+        // Part C: collect safety metadata and write sidecar artifact.
+        if (hook.collectSafetyMetadata) {
+            profiler.startTimer("safety:collect");
+            for (const [filePath, item] of preBuilt) {
+                if (!entryImportsSafety(item.programIR))
+                    continue;
+                const metadata = hook.collectSafetyMetadata(item.programIR, {
+                    safetyInUse: true,
+                    target: options.target,
+                });
+                if (metadata.length > 0 && metadata[0].functions.length > 0) {
+                    const { renderSafetySidecar } = await import("./safety/sidecar-bridge.js");
+                    const toolVersion = CUTTLEFISH_VERSION;
+                    const sidecarPath = path.join(outDir, path.basename(filePath).replace(/\.\w+$/, ".safety-sidecar.json"));
+                    const sidecarJson = await renderSafetySidecar(metadata[0], toolVersion);
+                    writeText(sidecarPath, sidecarJson);
+                }
+            }
+            profiler.endTimer("safety:collect");
+        }
+    }
     // ── Pass 2: emit (only for files that needed retranspilation) ─────────────
     profiler.startTimer("emit:all");
     profiler.captureMemorySnapshot("emit:pre");
@@ -643,6 +775,9 @@ export async function transpileFile(options) {
             crossModuleEnumNames: allEnumNames,
             crossModuleStringEnumNames: allStringEnumNames,
             crossModuleVariableTypes: allVariableTypes,
+            autosar: options.autosar,
+            toolVersion: CUTTLEFISH_VERSION,
+            autosarArxml: options.autosarArxml,
         };
         // Pass the already-resolved strategy (framework-loaded or target-based)
         emitOptions.strategy = strategy;
@@ -689,6 +824,7 @@ export async function transpileFile(options) {
     profiler.endTimer("post:flatten");
     // Profiler session ends (profiling disabled - no report generation)
     // ── Generate diagnostics report if enabled ──────────────────────────────
+    let diagnosticsReportPath;
     if (options.diagnostics) {
         try {
             const entryPreBuilt = preBuilt.get(entryFile);
@@ -708,17 +844,23 @@ export async function transpileFile(options) {
                 removedSymbols: allRemovedSymbols,
             });
             writeDiagnosticsReport(report, entryPreBuilt?.programIR ?? null, outDir);
+            diagnosticsReportPath = path.join(outDir, "diagnostics.md");
         }
         catch (e) {
-            // Diagnostics report generation is best-effort; don't fail the build
-            if (options.debug) {
-                logDebug(`Diagnostics report generation failed: ${e instanceof Error ? e.message : String(e)}`, true);
-            }
+            // Diagnostics report generation is best-effort; don't fail the build,
+            // but surface the failure so the user knows --diagnostics didn't work.
+            diagnostics.push({
+                severity: "warning",
+                message: `Diagnostics report generation failed: ${e instanceof Error ? e.message : String(e)}`,
+                code: "diagnostics-report-failed",
+                source: "transpile",
+            });
         }
     }
     return {
         ...entryOutputs,
         diagnostics,
+        diagnosticsReportPath,
     };
 }
 export function generateLibraryDefinitions(options) {