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

package/dist/emit/compliance/deviation-ledger.js

@@ -0,0 +1,47 @@
+/**
+ * Append-only store of deviations recorded during emit. Dedupes identical
+ * (ruleId, file, line) entries; supports region deviations via openRegion /
+ * closeRegion. The ledger is the single source of truth that the sidecar
+ * registry is rendered from.
+ */
+export class DeviationLedger {
+    constructor() {
+        this.entries = [];
+        this.openRegionEntry = null;
+    }
+    record(input) {
+        if (this.openRegionEntry) {
+            throw new Error(`Cannot record single-line deviation for ${input.ruleId} while a region is open for ${this.openRegionEntry.ruleId}.`);
+        }
+        const endLine = input.line;
+        this.append({ ...input, endLine, reviewStatus: "auto-generated" });
+    }
+    openRegion(input) {
+        if (this.openRegionEntry) {
+            throw new Error(`Cannot open deviation region for ${input.ruleId}: a region is already open for ${this.openRegionEntry.ruleId}.`);
+        }
+        this.openRegionEntry = { ...input };
+    }
+    closeRegion(endLine) {
+        if (!this.openRegionEntry) {
+            throw new Error("Cannot close a deviation region: no open deviation region.");
+        }
+        if (endLine < this.openRegionEntry.line) {
+            throw new Error(`closeRegion endLine ${endLine} is before the region start line ${this.openRegionEntry.line}.`);
+        }
+        this.append({ ...this.openRegionEntry, endLine, reviewStatus: "auto-generated" });
+        this.openRegionEntry = null;
+    }
+    all() {
+        return this.entries;
+    }
+    /** Used by the self-check to verify every ledger entry has a matching inline comment. */
+    hasEntry(file, line, ruleId) {
+        return this.entries.some((e) => e.file === file && line >= e.line && line <= e.endLine && e.ruleId === ruleId);
+    }
+    append(entry) {
+        const dup = this.entries.some((e) => e.ruleId === entry.ruleId && e.file === entry.file && e.line === entry.line);
+        if (!dup)
+            this.entries.push(entry);
+    }
+}

package/dist/emit/compliance/deviation-writer.d.ts

@@ -0,0 +1,30 @@
+import type { ComplianceContext } from "./compliance-context.js";
+import type { Deviation } from "./types.js";
+export interface RegistryJson {
+    schemaVersion: string;
+    standard: string;
+    tool: string;
+    toolVersion: string;
+    generatedAt: string;
+    emittedArtifact: string;
+    ruleSubset: {
+        id: string;
+        category: string;
+    }[];
+    summary: {
+        totalDeviations: number;
+        byRule: Record<string, number>;
+    };
+    deviations: Array<Deviation & {
+        /** C++ location of the deviation, mirroring the diagnostic messages. */
+        cpp?: {
+            file: string;
+            line: number;
+        };
+    }>;
+}
+/**
+ * Renders the ledger as the sidecar registry JSON. Pure function — does
+ * not touch the filesystem; the caller (finalizeOutput) writes the string.
+ */
+export declare function renderRegistryJson(ctx: ComplianceContext, emittedArtifact: string, toolVersion: string): string;

package/dist/emit/compliance/deviation-writer.js

@@ -0,0 +1,37 @@
+import { RULES } from "./rules.js";
+/**
+ * Renders the ledger as the sidecar registry JSON. Pure function — does
+ * not touch the filesystem; the caller (finalizeOutput) writes the string.
+ */
+export function renderRegistryJson(ctx, emittedArtifact, toolVersion) {
+    const deviations = [...ctx.ledger().all()];
+    const byRule = {};
+    for (const d of deviations) {
+        byRule[d.ruleId] = (byRule[d.ruleId] ?? 0) + 1;
+    }
+    // Derive the C++ artifact name for the cpp field. For header deviations,
+    // the artifact is the .h file (derived from the source artifact name).
+    const sourceArtifact = emittedArtifact;
+    const headerArtifact = emittedArtifact.replace(/\.\w+$/, ".h");
+    const payload = {
+        schemaVersion: "1.0.0",
+        standard: "AUTOSAR C++14",
+        tool: "cuttlefish",
+        toolVersion,
+        generatedAt: new Date().toISOString(),
+        emittedArtifact,
+        ruleSubset: RULES.filter((r) => r.enabled).map((r) => ({ id: r.id, category: r.category })),
+        summary: {
+            totalDeviations: deviations.length,
+            byRule,
+        },
+        deviations: deviations.map((d) => ({
+            ...d,
+            cpp: {
+                file: d.file === "header" ? headerArtifact : sourceArtifact,
+                line: d.line,
+            },
+        })),
+    };
+    return JSON.stringify(payload, null, 2);
+}

package/dist/emit/compliance/index.d.ts

@@ -0,0 +1,7 @@
+export { ComplianceContext } from "./compliance-context.js";
+export { DeviationLedger } from "./deviation-ledger.js";
+export { runSelfCheck } from "./rule-engine.js";
+export { renderRegistryJson } from "./deviation-writer.js";
+export { renderArxml } from "./arxml-writer.js";
+export { RULES, getRule, rulesByCategory } from "./rules.js";
+export type { ComplianceMode, RuleEntry, RuleSeverity, RuleCategory, Deviation, DeviationKind, SelfCheckFinding, } from "./types.js";

package/dist/emit/compliance/index.js

@@ -0,0 +1,6 @@
+export { ComplianceContext } from "./compliance-context.js";
+export { DeviationLedger } from "./deviation-ledger.js";
+export { runSelfCheck } from "./rule-engine.js";
+export { renderRegistryJson } from "./deviation-writer.js";
+export { renderArxml } from "./arxml-writer.js";
+export { RULES, getRule, rulesByCategory } from "./rules.js";

package/dist/emit/compliance/rule-engine.d.ts

@@ -0,0 +1,13 @@
+import type { ComplianceContext } from "./compliance-context.js";
+import type { SelfCheckFinding } from "./types.js";
+/**
+ * Final self-check pass, run inside finalizeOutput after all renderers
+ * have pushed lines. Walks the emitted text once and reports:
+ *   - unrecorded-violation: a banned construct with no matching deviation comment
+ *   - orphan-deviation: a ledger entry with no matching inline comment
+ *
+ * Two layers: renderers are the primary enforcement (Pattern 1 picks the
+ * compliant spelling by construction); this is the secondary net. Neither
+ * is expected to be perfect alone.
+ */
+export declare function runSelfCheck(ctx: ComplianceContext, sourceLines: readonly string[], headerLines: readonly string[]): SelfCheckFinding[];

package/dist/emit/compliance/rule-engine.js

@@ -0,0 +1,101 @@
+import { RULES } from "./rules.js";
+const DEVIATION_COMMENT = /\/\/\s*AUTOSAR\s+Deviation\s+([A-Z]\d[\d-]*[A-Z\d, ]*)/i;
+/**
+ * Final self-check pass, run inside finalizeOutput after all renderers
+ * have pushed lines. Walks the emitted text once and reports:
+ *   - unrecorded-violation: a banned construct with no matching deviation comment
+ *   - orphan-deviation: a ledger entry with no matching inline comment
+ *
+ * Two layers: renderers are the primary enforcement (Pattern 1 picks the
+ * compliant spelling by construction); this is the secondary net. Neither
+ * is expected to be perfect alone.
+ */
+export function runSelfCheck(ctx, sourceLines, headerLines) {
+    if (!ctx.isEnabled())
+        return [];
+    const findings = [];
+    // Pass 1: detect banned constructs in source and header lines.
+    for (const file of ["source", "header"]) {
+        const lines = file === "source" ? sourceLines : headerLines;
+        for (let i = 0; i < lines.length; i++) {
+            const lineNo = i + 1;
+            const line = lines[i];
+            // Strip trailing // comments and skip full comment lines before
+            // running detect regexes — rules shouldn't match words in prose.
+            // Preserve deviation comments (checked separately below).
+            const deviationCommentMatch = line.match(DEVIATION_COMMENT);
+            const codePart = line.replace(/\s*\/\/(?!.*AUTOSAR Deviation).*$/, "");
+            const isFullComment = /^\s*(\/\/|\/\*|\*)/.test(line);
+            const detectTarget = isFullComment ? "" : codePart;
+            // Extract any deviation ruleIds already present on this line.
+            const commentedIds = new Set();
+            if (deviationCommentMatch) {
+                for (const id of deviationCommentMatch[1].split(",").map((s) => s.trim())) {
+                    commentedIds.add(id);
+                }
+            }
+            for (const rule of RULES) {
+                if (!rule.detect)
+                    continue;
+                if (!rule.enabled)
+                    continue;
+                if (rule.exempt && rule.exempt.test(detectTarget))
+                    continue;
+                if (!rule.detect.test(detectTarget))
+                    continue;
+                // Check knownPatterns: if this match falls under a known unavoidable
+                // pattern, record a deviation and suppress the finding.
+                if (rule.knownPatterns) {
+                    const known = rule.knownPatterns.find((kp) => kp.detect.test(detectTarget));
+                    if (known) {
+                        ctx.recordKnownDeviation(rule.id, known.justification, lineNo, file, line.trim(), {
+                            tsFile: "",
+                            tsLine: 0,
+                            kind: known.kind,
+                        });
+                        continue;
+                    }
+                }
+                // Match found. Is it covered by an inline comment or a ledger entry?
+                const covered = commentedIds.has(rule.id) || ctx.ledger().hasEntry(file, lineNo, rule.id);
+                if (!covered) {
+                    findings.push({
+                        ruleId: rule.id,
+                        severity: rule.severity,
+                        line: lineNo,
+                        file,
+                        snippet: line.trim(),
+                        kind: "unrecorded-violation",
+                    });
+                }
+            }
+        }
+    }
+    // Pass 2: orphan-deviation detection. For every ledger entry, confirm an
+    // inline comment exists at the recorded opening line in the right file.
+    // Skip entries from rules that have knownPatterns — those are intentionally
+    // inline-comment-less deviations (the emitted text is pre-baked shim strings
+    // that can't carry inline comments; the deviation lives in the sidecar only).
+    const rulesWithKnownPatterns = new Set(RULES.filter((r) => r.knownPatterns).map((r) => r.id));
+    for (const dev of ctx.ledger().all()) {
+        if (rulesWithKnownPatterns.has(dev.ruleId))
+            continue;
+        const lines = dev.file === "source" ? sourceLines : headerLines;
+        const openingLine = lines[dev.line - 1] ?? "";
+        const commentMatch = openingLine.match(DEVIATION_COMMENT);
+        const coversThis = commentMatch &&
+            commentMatch[1].split(",").map((s) => s.trim()).includes(dev.ruleId);
+        if (!coversThis) {
+            // Opening line must carry the comment.
+            findings.push({
+                ruleId: dev.ruleId,
+                severity: "required",
+                line: dev.line,
+                file: dev.file,
+                snippet: openingLine.trim(),
+                kind: "orphan-deviation",
+            });
+        }
+    }
+    return findings;
+}

package/dist/emit/compliance/rules.d.ts

@@ -0,0 +1,16 @@
+import type { RuleEntry } from "./types.js";
+/**
+ * Curated AUTOSAR C++14 rule subset enforced by the cuttlefish compliance
+ * module. ~50 rules: 39 [C] (enforce-by-construction) and 11 [D] (deviation).
+ *
+ * Detection regexes are deliberately conservative: prefer false-negatives
+ * over false-positives, because a false positive aborts builds in strict
+ * mode. The renderer is the primary enforcement; the self-check is the
+ * secondary net.
+ *
+ * See docs/superpowers/specs/2026-07-26-autosar-compliance-design.md §
+ * "Curated rule subset".
+ */
+export declare const RULES: readonly RuleEntry[];
+export declare function getRule(id: string): RuleEntry | undefined;
+export declare function rulesByCategory(category: "C" | "D"): readonly RuleEntry[];

package/dist/emit/compliance/rules.js

@@ -0,0 +1,191 @@
+/**
+ * Curated AUTOSAR C++14 rule subset enforced by the cuttlefish compliance
+ * module. ~50 rules: 39 [C] (enforce-by-construction) and 11 [D] (deviation).
+ *
+ * Detection regexes are deliberately conservative: prefer false-negatives
+ * over false-positives, because a false positive aborts builds in strict
+ * mode. The renderer is the primary enforcement; the self-check is the
+ * secondary net.
+ *
+ * See docs/superpowers/specs/2026-07-26-autosar-compliance-design.md §
+ * "Curated rule subset".
+ */
+export const RULES = [
+    // ── A. Preprocessor & macros ──────────────────────────────────────────
+    { id: "A16-0-1", title: "No #include of unused header", severity: "required", category: "C", enabled: true },
+    { id: "A16-0-3", title: "No #include inside namespace", severity: "required", category: "C",
+        detect: /^\s*namespace\s+\w+\s*\{[^}]*#include/m, enabled: true },
+    { id: "A16-0-4", title: "No #define inside another #define", severity: "required", category: "C", enabled: true },
+    { id: "A16-0-5", title: "Header file path unambiguous", severity: "required", category: "C", enabled: true },
+    { id: "A16-0-8", title: "#include not used for textual inclusion of code", severity: "required", category: "D", enabled: true },
+    { id: "A16-7-1", title: "Header guards via #pragma once", severity: "required", category: "C",
+        detect: /#ifndef\s+\w+_H\s*$/,
+        exempt: /#pragma once/,
+        enabled: true },
+    // ── B. Type safety & conversions ──────────────────────────────────────
+    { id: "M5-0-3", title: "Implicit narrowing conversion forbidden", severity: "required", category: "C", enabled: true },
+    { id: "M5-0-7", title: "C-style cast shall not be used", severity: "required", category: "C",
+        detect: /(^|[^:\w.])\(\s*(?:uint\d+_t|int\d+_t|int|char|double|float|bool|size_t|long|short|unsigned\s+\w+)\s*\)\s*[a-zA-Z_(]/,
+        exempt: /static_cast|dynamic_cast|reinterpret_cast|const_cast/,
+        enabled: true },
+    { id: "M5-0-10", title: "No reinterpret_cast", severity: "required", category: "D",
+        detect: /reinterpret_cast</, enabled: true,
+        knownPatterns: [
+            {
+                // freeHeap() on AVR exposes no numeric API — avr-libc publishes the
+                // heap boundary as the linker symbols __heap_start (int) and __brkval
+                // (int*). Computing the free byte count requires subtracting two
+                // addresses, which is only expressible as a pointer→integer cast.
+                // This is the canonical AUTOSAR category-D "unavoidable platform
+                // constraint" deviation. ESP32 uses ESP.getFreeHeap() and needs no
+                // cast; this pattern matches only the AVR idiom.
+                detect: /reinterpret_cast<size_t>\(&(v|__heap_start)\)|reinterpret_cast<size_t>\(__brkval\)/,
+                justification: "AVR freeHeap() measures the gap between the stack and heap via the avr-libc __heap_start/__brkval linker symbols; pointer-to-integer conversion is the only way to compute a byte distance between two addresses on a target with no numeric free-heap API.",
+                kind: "polyfill",
+            },
+        ],
+    },
+    { id: "M5-2-8", title: "No pointer arithmetic out of bounds", severity: "required", category: "C", enabled: true },
+    { id: "A5-2-2", title: "No static_cast downcast of polymorphic type", severity: "required", category: "C", enabled: true },
+    { id: "M5-3-2", title: "No bitwise ops on signed narrow types", severity: "required", category: "C", enabled: true,
+        knownPatterns: [
+            {
+                detect: /<<\s*8|>>\s*\d/,
+                justification: "Display color packing (RGB565/RGB888) requires bitwise shifts on narrow types; restructuring would change pixel layout.",
+                kind: "ts-literal",
+            },
+        ],
+    },
+    { id: "A5-3-2", title: "No bitwise assignment on signed narrow types", severity: "required", category: "C", enabled: true },
+    { id: "A7-1-1", title: "const on objects that are not modified", severity: "required", category: "C", enabled: true },
+    { id: "A7-1-5", title: "auto only for function returns, non-fundamental types, generic lambdas, trailing return types", severity: "required", category: "C",
+        detect: /\bauto\b/, enabled: true,
+        knownPatterns: [
+            {
+                // A7-1-5 permits auto for: (1) function call return types,
+                // (2) non-fundamental type initializers, (3) generic lambda params,
+                // (4) trailing return type syntax. The self-check can't distinguish
+                // these from first principles, so we record a deviation for every
+                // auto usage. The renderer separately avoids auto for fundamental
+                // types (numbers) under --autosar by substituting int32_t/float/etc.
+                detect: /\bauto\b/,
+                justification: "auto is used for function return types (case 1) and non-fundamental types (case 2) as permitted by A7-1-5; fundamental-type auto is substituted to explicit fixed-width types by the renderer.",
+                kind: "other",
+            },
+        ],
+    },
+    { id: "A7-1-6", title: "No typedef outside a function -> use using alias", severity: "required", category: "C",
+        detect: /\btypedef\b/, exempt: /\busing\b/, enabled: true,
+        knownPatterns: [
+            {
+                detect: /\btypedef\b/,
+                justification: "ESP32 BLE/WiFi callback APIs and async runtimes require C-style function-pointer typedefs for framework interop.",
+                kind: "freestanding-function",
+            },
+        ],
+    },
+    { id: "A7-2-1", title: "Enumerators use scoped enums (enum class)", severity: "required", category: "C",
+        detect: /\benum\s+(?!class\b|struct\b)\w+/, enabled: true,
+        knownPatterns: [
+            {
+                detect: /\benum\s+(?:UINodeKind|UIProperty)\b/,
+                justification: "UI runtime internal enums (UINodeKind, UIProperty) use unscoped form for C ABI compatibility; converting to enum class would require updating 58 references across the runtime header.",
+                kind: "other",
+            },
+        ],
+    },
+    // ── C. Memory & objects ───────────────────────────────────────────────
+    { id: "A18-0-1", title: "<cstring> over C headers", severity: "required", category: "C",
+        detect: /#include\s+<string\.h>/, enabled: true },
+    { id: "A18-5-8", title: "No new/delete on plain objects", severity: "required", category: "D",
+        detect: /\bnew\s+(?:[A-Z_]|\()|\bdelete\s+(?:\w+\s*\[|\w)/, enabled: true,
+        knownPatterns: [
+            {
+                detect: /\bnew\s+\(|new\s+\(std::nothrow\)|new\s+\(ps_malloc|new\s+(?:Cuttlefish|GFX|Sdl)/,
+                justification: "UI runtime allocates canvas buffers and draw-order arrays on the heap via new/new(std::nothrow); no stack alternative exists for dynamic-size buffers on embedded targets.",
+                kind: "raw-array",
+            },
+            {
+                detect: /\bdelete\s+\w/,
+                justification: "UI runtime frees heap-allocated canvas buffers via delete; matches the new(std::nothrow) allocation.",
+                kind: "raw-array",
+            },
+        ],
+    },
+    { id: "A18-5-10", title: "No malloc/calloc/realloc", severity: "required", category: "C",
+        detect: /\b(malloc|calloc|realloc)\s*\(/, enabled: true,
+        knownPatterns: [
+            {
+                // Offscreen canvas allocation (CuttlefishCanvas16/CuttlefishCanvasMono
+                // object + pixel buffer). On targets built with
+                // CONFIG_REQUIRES_FULL_LIBCPP but without CONFIG_CPP_EXCEPTIONS (e.g.
+                // Zephyr ESP32 display builds), C++ `operator new` throws
+                // std::bad_alloc on OOM, and the `new (std::nothrow)` wrapper's
+                // internal catch cannot unwind without the EH runtime — it falls
+                // through to std::terminate → abort on the first allocation failure.
+                // malloc returns NULL on OOM with no exception path, which the
+                // runtime's existing canvas-null-checks degrade gracefully. This is
+                // the canonical category-C "platform library constraint" deviation:
+                // the alternative (operator new) is the very thing that crashes. The
+                // object is placement-constructed on the malloc'd memory and freed via
+                // an explicit dtor + free, so the vtable/lifetime are correct.
+                detect: /malloc\s*\(/,
+                justification: "Canvas object/buffer allocation on full-libcpp-without-exceptions targets; malloc avoids the operator-new std::bad_alloc → std::terminate → abort path. OOM returns NULL and the runtime degrades gracefully.",
+                kind: "ts-literal",
+            },
+        ],
+    },
+    { id: "A27-0-4", title: "No function returning std::move of local", severity: "required", category: "C",
+        detect: /return\s+std::move\s*\(/, enabled: true },
+    { id: "M5-2-9", title: "No copy of volatile std::atomic", severity: "required", category: "C", enabled: true },
+    // ── D. Functions & interfaces ─────────────────────────────────────────
+    { id: "A8-4-2", title: "Forward-declare parameters before use", severity: "required", category: "C", enabled: true },
+    { id: "A8-4-10", title: "Single return per function", severity: "advisory", category: "D", enabled: true },
+    { id: "M3-2-1", title: "All static-storage objects const-initialized", severity: "required", category: "D", enabled: true },
+    { id: "M3-2-3", title: "No aggregate inits the compiler can't order statically", severity: "required", category: "C", enabled: true },
+    { id: "M3-2-4", title: "No non-trivial init at static storage", severity: "required", category: "D", enabled: true },
+    { id: "A3-1-1", title: "final on leaf classes", severity: "required", category: "C", enabled: true },
+    { id: "A3-1-5", title: "All virtual methods have override or final", severity: "required", category: "C", enabled: true },
+    { id: "A10-3-1", title: "No function hiding in derived classes", severity: "required", category: "C", enabled: true },
+    { id: "A8-4-7", title: "One definition of an inline function", severity: "required", category: "C", enabled: true },
+    // ── E. Control flow & exceptions ──────────────────────────────────────
+    { id: "A5-1-1", title: "No recursion", severity: "required", category: "C", enabled: true },
+    { id: "A15-0-2", title: "noexcept on functions that can't throw", severity: "advisory", category: "C", enabled: true,
+        knownPatterns: [
+            {
+                detect: /\bnoexcept\b/,
+                justification: "noexcept annotation requires whole-function throw analysis (Phase 5); recorded as advisory deviation until then.",
+                kind: "other",
+            },
+        ],
+    },
+    { id: "A15-5-1", title: "Destructors must not throw", severity: "required", category: "C", enabled: true },
+    { id: "M15-1-3", title: "No throw expressions; no try/catch", severity: "required", category: "D",
+        detect: /\bthrow\b|\btry\s*\{|\bcatch\s*\(/, enabled: true },
+    { id: "A7-5-1", title: "[[fallthrough]] required where switch falls through", severity: "required", category: "C", enabled: true },
+    { id: "M6-2-1", title: "switch must have default", severity: "required", category: "C", enabled: true },
+    { id: "M6-4-3", title: "for condition guarded against finite iteration", severity: "required", category: "C", enabled: true },
+    { id: "A6-5-1", title: "for/while have single loop variable", severity: "required", category: "C", enabled: true },
+    // ── F. Literal & style ────────────────────────────────────────────────
+    { id: "A2-10-5", title: "Identifier reuse across scopes limited", severity: "advisory", category: "C", enabled: true },
+    { id: "A2-13-1", title: "Only hex literals are bitwise", severity: "required", category: "D", enabled: true },
+    { id: "A3-9-1", title: "Fixed-width integers (uint32_t not unsigned int)", severity: "required", category: "C", enabled: true },
+    { id: "M4-5-1", title: "No magic numbers; named constants", severity: "advisory", category: "D", enabled: true },
+    { id: "A18-1-1", title: "C-style arrays -> std::array", severity: "required", category: "D", enabled: true },
+    { id: "A8-4-4", title: "No goto", severity: "required", category: "C",
+        detect: /\bgoto\s+\w+;/, enabled: true },
+    { id: "A7-1-2", title: "No register keyword", severity: "required", category: "C",
+        detect: /(?<![A-Za-z0-9_])register\s+(?:int|char|short|long|unsigned|float|double|bool|void|uint\d+_t|int\d+_t|size_t|auto)/, enabled: true },
+    // ── G. Source organization ────────────────────────────────────────────
+    { id: "A3-3-2", title: "No unreachable code", severity: "required", category: "C", enabled: true },
+    { id: "A0-1-1", title: "No unused variables/functions", severity: "required", category: "C", enabled: true },
+    { id: "A2-11-1", title: "No identifier is simultaneously typedef and another entity", severity: "required", category: "C", enabled: true },
+    { id: "M0-1-2", title: "No value-convertible dead code", severity: "required", category: "C", enabled: true },
+    { id: "A7-3-1", title: "No public/protected mutable non-static members", severity: "required", category: "D", enabled: true },
+];
+export function getRule(id) {
+    return RULES.find((r) => r.id === id);
+}
+export function rulesByCategory(category) {
+    return RULES.filter((r) => r.category === category);
+}

package/dist/emit/compliance/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared types for the AUTOSAR C++14 compliance module.
+ * See docs/superpowers/specs/2026-07-26-autosar-compliance-design.md.
+ */
+export type ComplianceMode = "off" | "warn" | "strict";
+export type RuleSeverity = "required" | "advisory";
+export type RuleCategory = "C" | "D";
+export type DeviationKind = "hal-instance" | "lowered-exception" | "ts-literal" | "polyfill" | "freestanding-function" | "raw-array" | "other";
+/** A single AUTOSAR C++14 rule entry in the curated subset. */
+export interface RuleEntry {
+    id: string;
+    title: string;
+    severity: RuleSeverity;
+    category: RuleCategory;
+    /** Anchored regex that detects the banned construct in emitted text. Optional: absence means rule is enforced structurally only. */
+    detect?: RegExp;
+    /** Regex that, if matched on the same line, suppresses the detect match (e.g. the `static_cast` spelling for M5-0-7). */
+    exempt?: RegExp;
+    /** Per-rule kill switch. When false, the rule is loaded but neither renderer-gated nor self-checked. */
+    enabled: boolean;
+    /**
+     * Known unavoidable patterns for this rule. When the self-check detects a
+     * match for a knownPattern, it records a deviation (instead of flagging an
+     * unrecorded-violation) and suppresses the diagnostic. Used for rules whose
+     * violations are structural and can't be eliminated (e.g. function-pointer
+     * typedefs in ESP32 callbacks, signed bitwise in display color math).
+     */
+    knownPatterns?: Array<{
+        detect: RegExp;
+        justification: string;
+        kind: DeviationKind;
+    }>;
+}
+/** One recorded deviation, accumulated during emit. */
+export interface Deviation {
+    ruleId: string;
+    file: "source" | "header";
+    line: number;
+    endLine: number;
+    snippet: string;
+    justification: string;
+    reviewStatus: "auto-generated" | "accepted";
+    /** Traceability back to the originating TypeScript. Populated from the source-map. */
+    source?: {
+        tsFile: string;
+        tsLine: number;
+        kind: DeviationKind;
+    };
+}
+/** A finding from the post-emit self-check pass. */
+export interface SelfCheckFinding {
+    ruleId: string;
+    severity: RuleSeverity;
+    line: number;
+    file: "source" | "header";
+    snippet: string;
+    kind: "unrecorded-violation" | "orphan-deviation";
+}
+export declare const COMPLIANCE_TYPES_MODULE = true;

package/dist/emit/compliance/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for the AUTOSAR C++14 compliance module.
+ * See docs/superpowers/specs/2026-07-26-autosar-compliance-design.md.
+ */
+// Tagged sentinel export so `import * as` resolves to a non-empty namespace
+// even though every other export here is a type. This lets the types.test.ts
+// runtime-import check actually verify the module is present.
+export const COMPLIANCE_TYPES_MODULE = true;

package/dist/emit/cpp-emitter.js

@@ -1,5 +1,5 @@
 import { buildEmitterContext } from "./emitters/setup.js";
-import { emitPreamble } from "./emitters/output-finalizer.js";
+import { emitPreamble, emitAsyncTaskClasses, finalizeOutput } from "./emitters/output-finalizer.js";
 import { runTopLevelPreprocessing } from "./emitters/top-level-prep.js";
 import { synthesizeEntrypoints } from "./emitters/entrypoint-synthesizer.js";
 import { emitTypeDeclarations } from "./emitters/type-decl-emitter.js";
@@ -7,7 +7,6 @@ import { emitNamespaces } from "./emitters/namespace-emitter.js";
 import { emitClasses } from "./emitters/class-emitter.js";
 import { emitPostClassDeclarations, emitCallbackFunctions, emitFunctions, emitFunctionForwardDeclarations } from "./emitters/function-emitter-impl.js";
 import { emitUIRuntime } from "./emitters/ui-emitter.js";
-import { finalizeOutput } from "./emitters/output-finalizer.js";
 const globalEnumNames = new Set();
 const globalLargeEnumNames = new Set();
 export function registerAllEnumNames(enums) {
@@ -21,7 +20,7 @@ export function registerAllEnumNames(enums) {
 export function emitCpp(program, options) {
     // 1. Build shared emitter context (strategy, renderers, analysis, etc.)
     const ctx = buildEmitterContext(program, options);
-    // 2. Emit preamble (includes, polyfills, async task classes, shims)
+    // 2. Emit preamble (includes, polyfills, shims) — async task classes deferred
     emitPreamble(ctx);
     // 2.5. Emit UI runtime (header structs + static tables) — entry file only,
     //      when a UI is mounted. File-scope, must precede any function using it.
@@ -32,6 +31,8 @@ export function emitCpp(program, options) {
     synthesizeEntrypoints(ctx);
     // 5. Emit type declarations (enums, type aliases, interfaces, top-level constants)
     emitTypeDeclarations(ctx);
+    // 5.5. Async state machines — after globals so WIFI_SSID etc. are in scope
+    emitAsyncTaskClasses(ctx);
     // 6. Emit namespaces
     emitNamespaces(ctx);
     // 6.5. Emit function forward declarations (split mode — must precede class definitions)

package/dist/emit/emitters/class-emitter.js

@@ -221,7 +221,12 @@ export function emitClasses(ctx) {
             if (classDef.typeParameters && classDef.typeParameters.length > 0) {
                 appendSourceLine(ctx, `template<typename ${classDef.typeParameters.join(", typename ")}>`);
             }
-            appendSourceLine(ctx, `class ${classDef.name}${inheritanceClause} {`);
+            // A3-1-1: stamp `final` on leaf classes (nothing inherits from them).
+            // baseClassesNeeded holds every class name that appears as an
+            // extendsClass somewhere in the program. Disabled when autosar is off.
+            const isLeaf = !baseClassesNeeded.has(classDef.name);
+            const finalKw = ctx.compliance.isEnabled() && isLeaf ? " final" : "";
+            appendSourceLine(ctx, `class ${classDef.name}${inheritanceClause}${finalKw} {`);
         }
         const publicFields = classDef.fields.filter(f => f.visibility === "public");
         const privateFields = classDef.fields.filter(f => f.visibility === "private");

package/dist/emit/emitters/emitter-context.d.ts

@@ -4,10 +4,11 @@ import type { ProgramAnalysisResult } from "../../ir/program-analysis.js";
 import type { EmissionScopeState } from "../snprintf-helpers.js";
 import type { ExpressionRenderer } from "../expression-renderer.js";
 import type { StatementRenderer } from "../statement-renderer.js";
-import type { Diagnostic, EmitMode, SourceMapEntry, SourceSpan } from "../../types.js";
+import type { Diagnostic, EmitMode, ComplianceMode, SourceMapEntry, SourceSpan } from "../../types.js";
 import type { ResolvedNpmPackage } from "../../transpile/resolution.js";
 import type { BoardConstants } from "../../ir/board-resolver.js";
 import type { LibraryDefinition } from "../../types.js";
+import type { ComplianceContext } from "../compliance/compliance-context.js";
 /** Options controlling C++ emission. */
 export interface EmitterOptions {
     outDir: string;
@@ -35,6 +36,12 @@ export interface EmitterOptions {
     crossModuleEnumNames?: Set<string>;
     crossModuleStringEnumNames?: Set<string>;
     crossModuleVariableTypes?: Map<string, string>;
+    /** AUTOSAR C++14 compliance mode. Default 'off' — feature is opt-in. */
+    autosar?: ComplianceMode;
+    /** Tool version, written into the sidecar deviation registry. */
+    toolVersion?: string;
+    /** When true (and autosar is warn/strict), also write the .autosar-deviations.arxml sidecar. */
+    autosarArxml?: boolean;
 }
 export interface MappedFunction {
     name: string;
@@ -56,6 +63,11 @@ export interface CallbackFunction {
     params: string[];
     statements: StatementIR[];
     debounceMs?: number;
+    /**
+     * True for GPIO / hardware ISR callbacks only. WiFi event handlers, timers,
+     * and setInterval use the same hoist path but must NOT get IRAM_ATTR.
+     */
+    isInterruptHandler?: boolean;
     /**
      * Return type of the synthesized free function. Defaults to "void" (the
      * historical ISR/HAL-callback case). Populated from a hoisted lambda's
@@ -141,6 +153,20 @@ export interface EmitterContext {
     headerLines: string[];
     sourceMapEntries: SourceMapEntry[];
     headerMapEntries: SourceMapEntry[];
+    /**
+     * Active debug mode. When 'gdb', appendSourceLine emits `#line` markers
+     * before lines whose TS source span transitions. 'printf' = no markers.
+     * Resolved once from strategy.debugMode(buildTarget) during setup.
+     */
+    debugMode: 'gdb' | 'printf';
+    /**
+     * The {filePath, line} of the most recently emitted linemarker, or null if
+     * none yet. Used by appendSourceLine for transition detection.
+     */
+    lastEmittedSource: {
+        filePath: string;
+        line: number;
+    } | null;
     cArrayVarNames: Set<string>;
     fnCArrayVarNames: Map<string, Set<string>>;
     globalPointerVarTypes: Map<string, string>;
@@ -171,4 +197,5 @@ export interface EmitterContext {
     interfaceNamespaceMap: Map<string, string>;
     /** Map of interface name to its field types (e.g., "Task" -> Map("id" -> "std::string", "title" -> "std::string")) */
     interfaceFieldTypes: Map<string, Map<string, string>>;
+    compliance: ComplianceContext;
 }