@typecad/cuttlefish 1.0.0-alpha.6 → 1.0.0-alpha.8

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,7 +166,11 @@ function formatFatalDiagnostics(entries) {
         `Transpilation aborted because ${errors.length} unsupported pattern${errors.length === 1 ? "" : "s"} were found.`,
     ];
     for (const { filePath, diagnostic } of errors) {
-        const resolvedFile = filePath ?? diagnostic.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";
@@ -217,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;
@@ -238,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);
@@ -302,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;
@@ -442,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,
@@ -459,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");
@@ -620,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");
@@ -644,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;

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { TargetProfile as CoreTargetProfile, PlatformContext as CorePlatformContext, SourceSpan as CoreSourceSpan, Diagnostic as CoreDiagnostic } from "./api/shared/index.js";
 export type EmitMode = "cpp" | "split";
+export type ComplianceMode = "off" | "warn" | "strict";
 export type TargetProfile = CoreTargetProfile;
 export type PlatformContext = CorePlatformContext;
 export type SourceSpan = CoreSourceSpan;
@@ -95,6 +96,10 @@ export interface TranspileOptions {
     diagnostics?: boolean;
     /** Display profile config from cuttlefish.config.ts */
     display?: import("./api/shared/display-profile.js").DisplayConfig;
+    /** AUTOSAR C++14 compliance mode for emitted code (default: "off"). */
+    autosar?: ComplianceMode;
+    /** When true (and autosar is warn/strict), also emit the .autosar-deviations.arxml sidecar. */
+    autosarArxml?: boolean;
 }
 export interface LibraryDefinitionCondition {
     target?: TargetProfile;
@@ -134,8 +139,10 @@ export interface CommandLineOptions {
     monitor: boolean;
     /** Serial port for upload and monitor (e.g. COM4 or /dev/ttyACM0) */
     port?: string;
-    /** Baud rate for monitor (default: 9600) */
-    baud: number;
+    /** Baud rate for monitor. Undefined when --baud is absent so the consumer
+     *  can fall back to config.console.baudRate (the framework monitor default
+     *  applies only when neither is set). */
+    baud?: number;
     platformContext?: PlatformContext;
     mapFile?: string;
     cppFile?: string;
@@ -168,6 +175,10 @@ export interface CommandLineOptions {
     expectFile?: string;
     /** Generate diagnostics.md and diagnostics.json reports */
     diagnostics?: boolean;
+    /** AUTOSAR C++14 compliance mode for emitted code (default: "off"). */
+    autosar?: ComplianceMode;
+    /** When true (and autosar is warn/strict), also emit the .autosar-deviations.arxml sidecar. */
+    autosarArxml?: boolean;
     /** Config file for preview command */
     configPath?: string;
     /** Project root (dir of cuttlefish.config.ts); passed to transpileFile for the ESLint gate. */

package/dist/ui-hook.d.ts

@@ -9,7 +9,6 @@ export interface LoweredUI {
     screenCount: number;
     imageTables: string;
     keyframeTables: string;
-    scrollMemoryDiagnostics: Diagnostic[];
     diagnostics: Diagnostic[];
 }
 export interface UIModule {
@@ -58,7 +57,23 @@ export interface TranspilerUIHook {
     lowerOnMount(htmlPath: string, opts: LowerOptions): LoweredUI;
     resolveColor(input: string, format: "rgb565" | "rgb666" | "rgb888" | "mono"): number;
     resolveColorInternal(input: string, format: "rgb565" | "rgb666" | "rgb888" | "mono"): number;
-    emitRuntimeHeader(): string;
+    /**
+     * Emits ONLY the CuttlefishGFX class definition (the shared GFX base for
+     * native display paths). Called separately from emitRuntimeHeader so the
+     * class can be emitted BEFORE display adapter declarations that
+     * instantiate CuttlefishGFX by value. Returns "" when active is false
+     * (Arduino path).
+     */
+    emitCuttlefishGfx(active: boolean): string;
+    /**
+     * Options controlling runtime-header emission.
+     *   - nativeDisplayActive: when true, emit the shared CuttlefishGFX class
+     *     (used by native display adapters on AVR/ESP32). Arduino paths pass
+     *     false (default) and use Adafruit_GFX directly.
+     */
+    emitRuntimeHeader(opts?: {
+        nativeDisplayActive?: boolean;
+    }): string;
     splitUiFile(src: string): UiFileParts;
     generateProjectUITypeDeclarations(projectRoot: string): {
         written: string[];
@@ -67,7 +82,6 @@ export interface TranspilerUIHook {
             error: Error;
         }>;
     };
-    analyzeScrollMemory(styled: unknown, budget: number): Diagnostic[];
 }
 /** Set the UI hook. Called by transpile.ts after dynamically loading
  *  @typecad/ui/engine. Passing null clears it (end of transpile run). */

package/dist/utils/cli.js

@@ -17,7 +17,7 @@ export function printHelp() {
     console.log(`  cuttlefish board add <spec.jsonc> [--force]   Generate board + MCU packages from a chip spec`);
     console.log(`  cuttlefish gen-decls <input.cpp|--all <directory>>`);
     console.log(`  cuttlefish map-error <mapFile> [options]`);
-    console.log(`  cuttlefish doctor                              Check that arduino-cli is installed and the board's core is present`);
+    console.log(`  cuttlefish doctor                              Check the active framework's environment (e.g. toolchain + board core)`);
     console.log(`  cuttlefish licenses [--all] [--strict]          Scan this project's Arduino libraries for SPDX licenses (--all: every installed library)`);
     console.log();
     console.log(chalk.gray(`Transpilation is always performed first. Use --compile, --upload, and`));
@@ -39,6 +39,16 @@ export function printHelp() {
     console.log(`  --emit-maps <bool>      Emit source maps: "true" or "false" (default: true)`);
     console.log(`                          Source maps enable mapping C++ errors back to TypeScript`);
     console.log();
+    console.log(`  --autosar[=<mode>]      AUTOSAR C++14 compliance mode for emitted code:`);
+    console.log(`                            off     no enforcement (default)`);
+    console.log(`                            warn    emit AUTOSAR_* diagnostics + sidecar, build still succeeds`);
+    console.log(`                            strict  abort emit on unrecorded required violations`);
+    console.log(`                          A sidecar <name>.autosar-deviations.json is written next to the`);
+    console.log(`                          emitted artifact in warn/strict modes. See COMPLIANCE.md.`);
+    console.log();
+    console.log(`  --autosar-arxml         Also write <name>.autosar-deviations.arxml (Artop/DaVinci).`);
+    console.log(`                          No-op unless --autosar is warn or strict.`);
+    console.log();
     console.log(chalk.cyan(`BUILD COMMANDS`) + chalk.gray(` (chain in order: --compile → --upload → --monitor)`));
     console.log();
     console.log(`  --compile               Compile the generated output using the framework toolchain.`);
@@ -104,6 +114,12 @@ export function printHelp() {
     console.log(`  --diagnostics           Generate diagnostics.md and diagnostics.json reports`);
     console.log(`                          Includes IR graph, heap analysis, and task analysis`);
     console.log();
+    console.log(`  --debug                 Inject Serial.println instrumentation at breakpoints.`);
+    console.log(`                          Reads .cuttlefish/breakpoints.json (written by the`);
+    console.log(`                          TypeCAD Debug VS Code extension). At each breakpoint the`);
+    console.log(`                          firmware prints the location, original line, and in-scope`);
+    console.log(`                          variables, then halts — press ENTER over serial to continue.`);
+    console.log();
     console.log(`  --help, -h              Show this help message`);
     console.log();
     console.log(chalk.cyan(`PROJECT CREATION`));
@@ -211,7 +227,11 @@ function parsePipelineCommand(argv, command, inputFile) {
     const emitMapsFlag = readFirstFlagValue(argv, ["--emit-maps"]);
     const buildTarget = readFirstFlagValue(argv, ["--build-target"]);
     const port = readFirstFlagValue(argv, ["--port"]);
-    const baud = readNumberFlag(argv, ["--baud"], 9600) ?? 9600;
+    // Default to undefined (NOT 9600) so the build/upload/monitor flow's
+    // `options.baud ?? config.console.baudRate` falls through to the configured
+    // baud. Hardcoding 9600 here shadowed config.console.baudRate whenever --baud
+    // was absent (the monitor then opened the port at 9600, ignoring the config).
+    const baud = readNumberFlag(argv, ["--baud"]);
     const frameworkFlag = readFirstFlagValue(argv, ["--framework"]);
     const compile = readBooleanFlag(argv, ["--compile"]);
     const upload = readBooleanFlag(argv, ["--upload"]);
@@ -231,6 +251,32 @@ function parsePipelineCommand(argv, command, inputFile) {
     const keepUnusedTypes = readBooleanFlag(argv, ["--keep-unused-types"]);
     const keepUnusedVariables = readBooleanFlag(argv, ["--keep-unused-variables"]);
     const entryPoints = readRepeatedFlag(argv, "--entry-point");
+    // AUTOSAR C++14 compliance mode for emitted code. Accepts both
+    // `--autosar=strict` (= syntax) and `--autosar strict` (space syntax),
+    // plus the bare `--autosar` (treated as "strict"). Defaults to undefined,
+    // which the emitter treats as "off".
+    let autosar;
+    const autosarFlagIdx = argv.findIndex((a) => a === "--autosar" || a.startsWith("--autosar="));
+    if (autosarFlagIdx !== -1) {
+        const raw = argv[autosarFlagIdx];
+        if (raw === "--autosar") {
+            // Bare flag → strict. (No following value consumed.)
+            autosar = "strict";
+        }
+        else {
+            // --autosar=<mode>
+            const value = raw.slice("--autosar=".length);
+            if (value === "strict" || value === "warn" || value === "off") {
+                autosar = value;
+            }
+            else {
+                throw new Error(`--autosar must be one of: strict, warn, off (got: ${value})`);
+            }
+        }
+    }
+    // --autosar-arxml: also write the .autosar-deviations.arxml sidecar
+    // (Artop/DaVinci tooling). No-op unless --autosar is warn or strict.
+    const autosarArxml = readBooleanFlag(argv, ["--autosar-arxml"]);
     const emitMode = emitFlag === "cpp" || emitFlag === "split" ? emitFlag : "split";
     const emitMaps = emitMapsFlag === undefined ? true : emitMapsFlag !== "false";
     // Accept any target string — the framework package registers its own strategy id.
@@ -281,6 +327,8 @@ function parsePipelineCommand(argv, command, inputFile) {
         expect,
         expectFile,
         frameworkPackage: frameworkFlag,
+        autosar,
+        autosarArxml,
     };
 }
 export function parseCommandLine(argv) {
@@ -339,7 +387,7 @@ export function parseCommandLine(argv) {
             port: port ? String(port) : undefined,
         };
     }
-    // doctor subcommand — verify arduino-cli + board core presence
+    // doctor subcommand — verify the active framework's environment
     if (firstArg === "doctor") {
         return {
             command: "doctor",
@@ -431,12 +479,16 @@ export function parseCommandLine(argv) {
         // gen-decls - generate .d.ts from C++ files
         if (command === "gen-decls") {
             const allFlag = argv.includes("--all");
+            const componentsFlag = argv.includes("--components");
+            if (allFlag && componentsFlag) {
+                throw new Error("gen-decls: --components and --all are mutually exclusive. Use one or the other.");
+            }
             // The positional path may sit at argv[3] or argv[4] depending on whether
             // --all precedes or follows it. Scan argv starting after the subcommand
             // name (argv[2]) for the first token that is not a flag and not a known
             // flag's value. This mirrors the default-pipeline approach of "first
             // non-flag token wins".
-            const booleanFlags = new Set(["--all"]);
+            const booleanFlags = new Set(["--all", "--components"]);
             const valueFlags = new Set([
                 "--emit", "--target", "--outDir", "--out-dir", "--emit-maps", "--build-target",
             ]);
@@ -457,6 +509,28 @@ export function parseCommandLine(argv) {
                 inputPath = tok;
                 break;
             }
+            // --components mode: scan managed_components/ + components/ declared in
+            // cuttlefish.config.ts. Falls back to cwd when no path is given.
+            if (componentsFlag) {
+                const componentsDir = inputPath || process.cwd();
+                return {
+                    command: "gen-decls",
+                    inputFile: undefined,
+                    emitMode,
+                    target,
+                    outDir: outDir ? path.resolve(process.cwd(), outDir) : undefined,
+                    emitMaps,
+                    noTranspile: false,
+                    compile: false,
+                    upload: false,
+                    monitor: false,
+                    watch: false,
+                    baud: 9600,
+                    platformContext,
+                    scanDir: undefined,
+                    componentsDir: path.resolve(process.cwd(), componentsDir),
+                };
+            }
             if (!inputPath && !allFlag) {
                 throw new Error("Missing input C++ file path. Use: gen-decls <file.cpp> or gen-decls --all <directory>");
             }

package/dist/utils/fs.d.ts

@@ -2,3 +2,16 @@ export declare function ensureDir(dirPath: string): void;
 export declare function readText(filePath: string): string;
 export declare function writeText(filePath: string, content: string): void;
 export declare function listFiles(dirPath: string, extension: string): string[];
+/**
+ * Recursive variant of {@link listFiles}. Walks `dirPath` depth-first and
+ * returns every file (in every subdirectory) whose name ends with `extension`.
+ *
+ * Used by {@link loadLibraryDefinitions} so libdefs under nested cache dirs
+ * like `.cuttlefish/component-decls/<component>/` are discovered. Purely
+ * additive vs. the non-recursive `listFiles` — single-level layouts keep
+ * working, nested layouts now also work.
+ *
+ * Returns absolute paths. Unreadable directories are silently skipped
+ * (matches `listFiles`'s not-exist behavior for non-existent roots).
+ */
+export declare function listFilesRecursive(dirPath: string, extension: string): string[];

package/dist/utils/fs.js

@@ -10,6 +10,15 @@ export function readText(filePath) {
 }
 export function writeText(filePath, content) {
     ensureDir(path.dirname(filePath));
+    // Skip writing when content is identical — preserves mtime so downstream
+    // build tools (idf.py/ninja, arduino-cli, make) can skip recompilation.
+    try {
+        if (fs.readFileSync(filePath, "utf8") === content)
+            return;
+    }
+    catch {
+        // File doesn't exist yet — fall through to write.
+    }
     fs.writeFileSync(filePath, content, "utf8");
 }
 export function listFiles(dirPath, extension) {
@@ -21,3 +30,44 @@ export function listFiles(dirPath, extension) {
         .filter((name) => name.toLowerCase().endsWith(extension.toLowerCase()))
         .map((name) => path.join(dirPath, name));
 }
+/**
+ * Recursive variant of {@link listFiles}. Walks `dirPath` depth-first and
+ * returns every file (in every subdirectory) whose name ends with `extension`.
+ *
+ * Used by {@link loadLibraryDefinitions} so libdefs under nested cache dirs
+ * like `.cuttlefish/component-decls/<component>/` are discovered. Purely
+ * additive vs. the non-recursive `listFiles` — single-level layouts keep
+ * working, nested layouts now also work.
+ *
+ * Returns absolute paths. Unreadable directories are silently skipped
+ * (matches `listFiles`'s not-exist behavior for non-existent roots).
+ */
+export function listFilesRecursive(dirPath, extension) {
+    if (!fs.existsSync(dirPath)) {
+        return [];
+    }
+    const ext = extension.toLowerCase();
+    const out = [];
+    const stack = [dirPath];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            // Permission error / race / etc. Skip this subtree.
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(cur, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(ext)) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}