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

package/dist/debug/preprocessor.js

@@ -40,6 +40,12 @@ export function preprocess(options) {
     // Collect variables in scope at each breakpoint
     const scopeAnalyzer = new ScopeAnalyzer(sf);
     const debugStrategy = getDebugStrategy();
+    // Per-file breakpoint ID counter. Each HALTING breakpoint gets a stable
+    // integer ID so the codegen can emit a per-breakpoint disable flag (skipped
+    // via the 's' key at runtime). IDs are scoped to this file and reset per
+    // preprocess() call, so they stay small and deterministic across builds.
+    // Logpoints never halt and don't need an ID.
+    let nextBreakpointId = 0;
     // Find the first non-import, non-comment line to insert debug init
     let insertIndex = 0;
     for (let i = 0; i < lines.length; i++) {
@@ -67,8 +73,12 @@ export function preprocess(options) {
             const displayLine = lineText.trim();
             // Collect variables in scope at this line
             const vars = scopeAnalyzer.getVariablesInScope(lineNum);
+            // Halting breakpoints get a per-file ID (used by the codegen to emit a
+            // disable flag the user can toggle at runtime with the 's' key). Logpoints
+            // never halt, so they pass no ID.
+            const breakpointId = bp.logMessage ? undefined : nextBreakpointId++;
             // Inject debug code BEFORE the breakpoint line
-            outputLines.push(...generateBreakpointCode(relativeFileName, lineNum + 1, displayLine, vars, bp, debugStrategy));
+            outputLines.push(...generateBreakpointCode(relativeFileName, lineNum + 1, displayLine, vars, bp, debugStrategy, breakpointId));
         }
         // Always include the original line
         outputLines.push(lineText);
@@ -87,14 +97,14 @@ export function preprocess(options) {
  * Generate debug code for a breakpoint.
  * Delegates to the loaded strategy when available.
  */
-function generateBreakpointCode(fileName, lineNum, originalLine, variables, bp, debugStrategy) {
+function generateBreakpointCode(fileName, lineNum, originalLine, variables, bp, debugStrategy, breakpointId) {
     // If this is a logpoint (has logMessage), generate log-only code
     if (bp.logMessage) {
         const parts = parseLogMessage(bp.logMessage);
         if (debugStrategy.generateDebugLogpointCode) {
             return debugStrategy.generateDebugLogpointCode({
                 fileName, lineNum, parts,
-                variables: variables.map(v => ({ name: v.name, isFunction: v.isFunction })),
+                variables: variables.map(v => ({ name: v.name, isFunction: v.isFunction, cppType: v.cppType })),
             });
         }
         return [];
@@ -104,8 +114,9 @@ function generateBreakpointCode(fileName, lineNum, originalLine, variables, bp,
     if (debugStrategy.generateDebugBreakpointCode) {
         return debugStrategy.generateDebugBreakpointCode({
             fileName, lineNum, originalLine,
-            variables: variables.map(v => ({ name: v.name, isFunction: v.isFunction })),
+            variables: variables.map(v => ({ name: v.name, isFunction: v.isFunction, cppType: v.cppType })),
             normalizedCondition,
+            breakpointId,
         });
     }
     return [];
@@ -162,52 +173,180 @@ class ScopeAnalyzer {
         if (this.functionVars.has(line)) {
             return this.functionVars.get(line);
         }
-        return this.functionVars.get(-1) || [];
+        // Module-scope (top-level): filter by declaration order so breakpoints
+        // before a variable's declaration don't reference it (use-before-declare).
+        const topVars = this.functionVars.get(-1) || [];
+        return topVars.filter(v => v.declLine === undefined || v.declLine < line);
     }
     analyze() {
+        // Top-level (module-scope) variables. Iterating sf.statements is reliable
+        // across TS statement-classification variants (a bare `let x = 0;` can be
+        // parsed as either VariableStatement or FirstStatement; both expose
+        // .declarationList, so read it uniformly).
         const topLevelVars = [];
-        this.collectVariables(this.sf, topLevelVars);
+        for (const stmt of this.sf.statements) {
+            this.collectVariablesFromStatement(stmt, topLevelVars);
+        }
         this.functionVars.set(-1, topLevelVars);
-        const visit = (node, currentVars) => {
-            if (ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)) {
-                const startLine = this.sf.getLineAndCharacterOfPosition(node.getStart()).line;
-                const endLine = node.body
-                    ? this.sf.getLineAndCharacterOfPosition(node.body.getEnd()).line
-                    : startLine;
-                const localVars = [...currentVars];
-                for (const param of node.parameters) {
-                    if (ts.isIdentifier(param.name)) {
-                        localVars.push({ name: param.name.text });
-                    }
-                }
-                if (node.body) {
-                    this.collectVariables(node.body, localVars);
-                }
-                for (let line = startLine; line <= endLine; line++) {
-                    this.functionVars.set(line, localVars);
+        // Record a scope entry for every line inside each function body, capturing
+        // enclosing-scope vars + parameters + body locals. Nested functions get
+        // their own entries that shadow the parent on their line range.
+        //
+        // Per-line scope filtering: body locals are only in scope on lines STRICTLY
+        // AFTER their declaration line. The breakpoint dump is injected at the
+        // START of the breakpoint line (before that line's own declaration runs),
+        // so a local declared on line N is not yet in scope at line N. Params and
+        // enclosing-scope vars are in scope from the function's first line.
+        const recordFunction = (node, currentVars) => {
+            const startLine = this.sf.getLineAndCharacterOfPosition(node.getStart()).line;
+            const endLine = node.body
+                ? this.sf.getLineAndCharacterOfPosition(node.body.getEnd()).line
+                : startLine;
+            // Always-in-scope from the function's first line: enclosing vars + params.
+            const alwaysInScope = [...currentVars];
+            for (const param of node.parameters) {
+                if (ts.isIdentifier(param.name)) {
+                    alwaysInScope.push({
+                        name: param.name.text,
+                        // Params have no initializer; infer from the annotation only.
+                        cppType: this.inferCppTypeFromAnnotation(param.type),
+                    });
                 }
-                return localVars;
             }
-            ts.forEachChild(node, child => visit(child, currentVars));
-            return currentVars;
-        };
-        visit(this.sf, topLevelVars);
-    }
-    collectVariables(node, vars) {
-        if (ts.isVariableStatement(node)) {
-            for (const decl of node.declarationList.declarations) {
-                if (ts.isIdentifier(decl.name)) {
-                    const isFunction = decl.initializer !== undefined && this.isFunctionExpression(decl.initializer);
-                    vars.push({ name: decl.name.text, isFunction });
-                }
+            // Body locals carry their own declaration line for per-line filtering.
+            const bodyLocals = [];
+            if (node.body) {
+                this.collectVariablesInBody(node.body, bodyLocals, recordFunction);
+            }
+            for (let line = startLine; line <= endLine; line++) {
+                // A body local is in scope at `line` only if declared on a strictly
+                // earlier line (declLine < line). This prevents both compile errors
+                // (use-before-declaration on the declaring line) and runtime reads of
+                // uninitialized locals at breakpoints above the declaration.
+                const localsInScope = bodyLocals.filter(v => v.declLine === undefined || v.declLine < line);
+                this.functionVars.set(line, [...alwaysInScope, ...localsInScope]);
             }
+        };
+        // Find top-level functions, then recurse into their bodies for nested ones.
+        for (const stmt of this.sf.statements) {
+            this.findAndRecordFunctions(stmt, topLevelVars, recordFunction);
+        }
+    }
+    /** Collect variables declared directly by a single statement (top-level use). */
+    collectVariablesFromStatement(stmt, vars) {
+        if (ts.isVariableStatement(stmt) && stmt.declarationList) {
+            this.collectFromDeclarationList(stmt.declarationList, vars);
         }
-        ts.forEachChild(node, child => {
-            if (!ts.isFunctionDeclaration(child) && !ts.isArrowFunction(child) && !ts.isMethodDeclaration(child)) {
-                this.collectVariables(child, vars);
+        else if (this.isFirstStatementVariableDeclaration(stmt)) {
+            this.collectFromDeclarationList(stmt.declarationList, vars);
+        }
+    }
+    /**
+     * Walk a function body collecting locals, recursing into nested functions so
+     * they get their own scope entry (without leaking their locals to the parent).
+     */
+    collectVariablesInBody(body, vars, recordFunction) {
+        ts.forEachChild(body, (child) => {
+            if (ts.isFunctionDeclaration(child) || ts.isArrowFunction(child) || ts.isMethodDeclaration(child)) {
+                // Nested function: record its scope, but do not add its name to this
+                // scope's printable vars (it's a function value).
+                recordFunction(child, vars);
+                return;
             }
+            this.collectVariablesFromStatement(child, vars);
+            this.collectVariablesInBody(child, vars, recordFunction);
         });
     }
+    /** Recurse looking for function declarations to record. */
+    findAndRecordFunctions(node, currentVars, recordFunction) {
+        if (ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)) {
+            recordFunction(node, currentVars);
+            return; // recordFunction already walks the body for nested functions.
+        }
+        ts.forEachChild(node, (child) => this.findAndRecordFunctions(child, currentVars, recordFunction));
+    }
+    collectFromDeclarationList(list, vars) {
+        for (const decl of list.declarations) {
+            if (ts.isIdentifier(decl.name)) {
+                const isFunction = decl.initializer !== undefined && this.isFunctionExpression(decl.initializer);
+                // declLine is the 0-indexed source line of the declaration. Used by
+                // recordFunction to filter body locals per line (declLine < line).
+                const declLine = this.sf.getLineAndCharacterOfPosition(decl.getStart()).line;
+                vars.push({
+                    name: decl.name.text,
+                    isFunction,
+                    declLine,
+                    cppType: isFunction ? undefined : this.inferCppType(decl),
+                });
+            }
+        }
+    }
+    /**
+     * Infer a coarse C++ type category from an explicit `: T` type annotation
+     * node. Returns `unknown` when there is no annotation or it isn't a primitive
+     * keyword we recognize.
+     */
+    inferCppTypeFromAnnotation(typeNode) {
+        if (!typeNode)
+            return 'unknown';
+        if (typeNode.kind === ts.SyntaxKind.BooleanKeyword)
+            return 'bool';
+        if (typeNode.kind === ts.SyntaxKind.StringKeyword)
+            return 'string';
+        if (typeNode.kind === ts.SyntaxKind.NumberKeyword)
+            return 'float'; // TS number → %g is the safe choice
+        if (typeNode.kind === ts.SyntaxKind.BigIntKeyword)
+            return 'long';
+        return 'unknown';
+    }
+    /**
+     * Infer a coarse C++ type category from a variable declaration, WITHOUT a
+     * TypeChecker (the debug path is parse-only). Priority:
+     *   1. Explicit `: T` annotation (authoritative).
+     *   2. Initializer shape (literal kind, or a small allowlist of known HAL
+     *      calls like millis()/micros() → long).
+     *   3. `unknown` — printf codegens cast to double + %g so it always compiles.
+     *
+     * Function-valued vars are handled by the caller (isFunction); this returns
+     * unknown for them but the caller skips emission of function-typed vars.
+     */
+    inferCppType(decl) {
+        // 1. Explicit type annotation wins.
+        const fromAnnotation = this.inferCppTypeFromAnnotation(decl.type);
+        if (fromAnnotation !== 'unknown')
+            return fromAnnotation;
+        // 2. Initializer shape.
+        const init = decl.initializer;
+        if (init) {
+            if (init.kind === ts.SyntaxKind.TrueKeyword || init.kind === ts.SyntaxKind.FalseKeyword)
+                return 'bool';
+            if (ts.isStringLiteral(init))
+                return 'string';
+            if (ts.isNoSubstitutionTemplateLiteral(init) || ts.isTemplateExpression(init))
+                return 'string';
+            if (ts.isNumericLiteral(init)) {
+                // Integer literal unless it contains '.' or an exponent marker.
+                return /[.eE]/.test(init.text) ? 'float' : 'int';
+            }
+            if (ts.isCallExpression(init)) {
+                // A small allowlist of HAL calls with known C++ return types.
+                const callee = ts.isIdentifier(init.expression) ? init.expression.text : '';
+                if (callee === 'millis' || callee === 'micros')
+                    return 'long';
+            }
+        }
+        // 3. Anything else (references, binary expressions, unknown calls, …).
+        return 'unknown';
+    }
+    /**
+     * TS sometimes parses a bare `let x = 0;` as a FirstStatement node rather
+     * than a VariableStatement. Detect that case by shape (has declarationList).
+     */
+    isFirstStatementVariableDeclaration(node) {
+        if (node.kind !== ts.SyntaxKind.FirstStatement)
+            return false;
+        return Object.prototype.hasOwnProperty.call(node, 'declarationList');
+    }
     isFunctionExpression(expr) {
         return ts.isArrowFunction(expr) || ts.isFunctionExpression(expr);
     }

package/dist/debug/types.d.ts

@@ -6,7 +6,30 @@ export interface CapturedVariable {
     name: string;
     /** Whether this is a function (cannot print value) */
     isFunction?: boolean;
+    /**
+     * Coarse C++ type category, inferred from the declaration's annotation or
+     * initializer shape (no TypeChecker is available in the debug path). Used by
+     * printf-based codegens (ESP-IDF) to pick the right format specifier; ignored
+     * by type-agnostic codegens (Arduino's Serial.println).
+     */
+    cppType?: DebugCppType;
+    /**
+     * 0-indexed source line on which this variable is declared. Used by the
+     * scope analyzer to exclude not-yet-declared locals from a breakpoint's
+     * variable dump (the dump is injected at the START of the breakpoint line,
+     * before that line's own declaration executes).
+     */
+    declLine?: number;
 }
+/**
+ * Coarse C++ type category for debug variable formatting.
+ *
+ * The debug preprocessor has no TypeChecker (it uses parse-only
+ * createSourceFile), so this is inferred from explicit `: T` annotations and
+ * initializer shape. `unknown` is the fallback; printf-based codegens cast to
+ * `double` and use `%g` so the code always compiles.
+ */
+export type DebugCppType = 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
 /**
  * A rich breakpoint with optional condition and log message.
  */

package/dist/diagnostics/mermaid-builder.d.ts

@@ -2,7 +2,7 @@ import type { CallGraph } from "../ir/call-graph.js";
 import type { GpioPinEntry, PeripheralAllocation, AsyncTaskEntry, ExecutionFlow, HeapEstimate, PeripheralConflictEntry, ModuleGraph, TreeShakingReport, BuildTiming } from "./json-schema.js";
 /**
  * Build a categorized architecture diagram showing how the sketch
- * is organized: entry points, HAL objects, Arduino APIs (grouped by
+ * is organized: entry points, HAL objects, HAL APIs (grouped by
  * subsystem), state variables, and custom functions.
  *
  * Noise symbols (true/false/HIGH/board chain) are filtered out.

package/dist/diagnostics/mermaid-builder.js

@@ -41,30 +41,40 @@ const BOARD_CHAIN = new Set([
     "TypeCAD", "Arduino", "Uno", "Nano", "Mega", "Mega2560",
     "Demo", "Board", "ATmega328P", "Features", "Esp32", "DevKit",
 ]);
-/** Known Arduino / HAL runtime API calls. */
-function isArduinoAPI(name) {
-    const apis = [
-        // GPIO
-        "digitalWrite", "digitalRead", "analogWrite", "analogRead", "pinMode",
-        // Serial
-        "Serial", "println", "print", "read", "write",
-        // Audio
-        "tone", "noTone",
-        // Timing
-        "millis", "micros", "delay", "delayMicroseconds",
-        // Interrupts
-        "attachInterrupt", "detachInterrupt",
-        // SPI / Shift
-        "shiftOut", "shiftIn", "pulseIn",
-        // HAL event tokens (from Button, etc.)
-        "pressed", "released", "input",
-    ];
-    return apis.includes(name);
+/**
+ * Known HAL runtime API call names used for diagram coloring/grouping.
+ *
+ * This is the cross-framework Wiring-derived HAL surface (the call names that
+ * appear in emitted C++ across Arduino-core, ESP32 Arduino, RP2040 Arduino,
+ * etc.). It is a diagnostic heuristic for grouping nodes in the mermaid
+ * execution-flow and interrupt-map diagrams — not emitted code. The set is
+ * generic: it identifies "this is a HAL/runtime call" for coloring purposes,
+ * regardless of which Wiring-derived framework produced it.
+ */
+const HAL_API_NAMES = new Set([
+    // GPIO
+    "digitalWrite", "digitalRead", "analogWrite", "analogRead", "pinMode",
+    // Serial
+    "Serial", "println", "print", "read", "write",
+    // Audio
+    "tone", "noTone",
+    // Timing
+    "millis", "micros", "delay", "delayMicroseconds",
+    // Interrupts
+    "attachInterrupt", "detachInterrupt",
+    // SPI / Shift
+    "shiftOut", "shiftIn", "pulseIn",
+    // HAL event tokens (from Button, etc.)
+    "pressed", "released", "input",
+]);
+/** Recognize a HAL/runtime API call name for diagram coloring. */
+function isHalApi(name) {
+    return HAL_API_NAMES.has(name);
 }
 // ── Execution Flow Diagram ──────────────────────────────────────────────────
 /**
  * Build a categorized architecture diagram showing how the sketch
- * is organized: entry points, HAL objects, Arduino APIs (grouped by
+ * is organized: entry points, HAL objects, HAL APIs (grouped by
  * subsystem), state variables, and custom functions.
  *
  * Noise symbols (true/false/HIGH/board chain) are filtered out.
@@ -133,7 +143,7 @@ export function buildExecutionFlowDiagram(flow, callGraph) {
         if (entry.has(name) || isr.has(name) || async.has(name))
             continue;
         const node = callGraph.nodes.get(name);
-        if (isArduinoAPI(name)) {
+        if (isHalApi(name)) {
             apis.push(name);
         }
         else if (node?.kind === "function") {
@@ -187,9 +197,9 @@ export function buildExecutionFlowDiagram(flow, callGraph) {
         lines.push("  end");
         lines.push("");
     }
-    // --- Arduino APIs (grouped by subsystem) ─────────────────────────
+    // --- HAL APIs (grouped by subsystem) ─────────────────────────────
     if (apis.length > 0) {
-        lines.push("  subgraph APIs[\"Arduino APIs\"]");
+        lines.push("  subgraph APIs[\"HAL APIs\"]");
         lines.push("    direction LR");
         const groups = {
             "GPIO": ["digitalWrite", "digitalRead", "analogWrite", "analogRead", "pinMode"],
@@ -333,7 +343,7 @@ export function buildInterruptMap(flow, callGraph) {
             return;
         visited.add(name);
         const node = callGraph.nodes.get(name);
-        const style = isRoot ? ":::isr" : (isArduinoAPI(name) ? ":::api" : ":::logic");
+        const style = isRoot ? ":::isr" : (isHalApi(name) ? ":::api" : ":::logic");
         const shape = isRoot ? `[[${esc(name)}]]` : `(${esc(name)})`;
         lines.push(`  ${name}${shape}${style}`);
         if (node) {

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

@@ -0,0 +1,11 @@
+import type { ComplianceContext } from "./compliance-context.js";
+/**
+ * Render the deviation ledger as an AUTOSAR ARXML XML projection.
+ *
+ * ARXML is the AUTOSAR-standard interchange format consumed by tooling
+ * like Artop and DaVinci. This is a *projection* of the same ledger that
+ * `renderRegistryJson` produces — single source of truth, two renderings.
+ * Many teams only need the JSON; ARXML generation is gated behind
+ * `--autosar-arxml` so projects that don't need it pay no cost.
+ */
+export declare function renderArxml(ctx: ComplianceContext, emittedArtifact: string): string;

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

@@ -0,0 +1,34 @@
+/** Escape XML special characters in text/attribute content. */
+function escapeXml(s) {
+    return s.replace(/[<>&'"]/g, (c) => c === "<" ? "&lt;" :
+        c === ">" ? "&gt;" :
+            c === "&" ? "&amp;" :
+                c === "'" ? "&apos;" :
+                    "&quot;");
+}
+/**
+ * Render the deviation ledger as an AUTOSAR ARXML XML projection.
+ *
+ * ARXML is the AUTOSAR-standard interchange format consumed by tooling
+ * like Artop and DaVinci. This is a *projection* of the same ledger that
+ * `renderRegistryJson` produces — single source of truth, two renderings.
+ * Many teams only need the JSON; ARXML generation is gated behind
+ * `--autosar-arxml` so projects that don't need it pay no cost.
+ */
+export function renderArxml(ctx, emittedArtifact) {
+    const deviations = ctx.ledger().all();
+    const body = deviations.map((d) => {
+        const source = d.source
+            ? `\n    <SOURCE TS-FILE="${escapeXml(d.source.tsFile)}" TS-LINE="${d.source.tsLine}" KIND="${d.source.kind}"/>`
+            : "";
+        return `  <DEVIATION RULE="${d.ruleId}" LINE="${d.line}" END-LINE="${d.endLine}" STATUS="${d.reviewStatus}">
+    <JUSTIFICATION>${escapeXml(d.justification)}</JUSTIFICATION>
+    <SNIPPET>${escapeXml(d.snippet)}</SNIPPET>${source}
+  </DEVIATION>`;
+    }).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<AUTOSAR xmlns="http://autosar.org/schema/r4.0" ARTIFACT="${escapeXml(emittedArtifact)}">
+${body}
+</AUTOSAR>
+`;
+}

package/dist/emit/compliance/compliance-context.d.ts

@@ -0,0 +1,57 @@
+import { DeviationLedger } from "./deviation-ledger.js";
+import type { ComplianceMode, DeviationKind } from "./types.js";
+/**
+ * Per-emit compliance bag, threaded through EmitterContext. Owns the
+ * deviation ledger and exposes the renderer-facing API.
+ *
+ * When mode === "off" (the default), every method is a no-op: helpers
+ * return their input unchanged, nothing is recorded. This is what lets
+ * the feature land without changing any existing emitted output.
+ */
+export declare class ComplianceContext {
+    private readonly complianceMode;
+    private readonly ledgerInstance;
+    private readonly bannedKinds;
+    constructor(complianceMode: ComplianceMode);
+    mode(): ComplianceMode;
+    isEnabled(): boolean;
+    ledger(): Readonly<DeviationLedger>;
+    /**
+     * Record a deviation for a known unavoidable pattern (used by the
+     * self-check's knownPatterns mechanism). Unlike emitWithDeviation, this
+     * does NOT append an inline comment — the deviation is recorded in the
+     * ledger only, so the sidecar lists it. The emitted C++ text is unchanged.
+     */
+    recordKnownDeviation(ruleId: string, justification: string, line: number, file: "source" | "header", snippet: string, source?: {
+        tsFile: string;
+        tsLine: number;
+        kind: DeviationKind;
+    }): void;
+    /** Renderer gate: should it avoid the banned spelling for this rule? */
+    isBanned(ruleId: string): boolean;
+    /**
+     * Returns `line` with an appended inline deviation comment, and records
+     * the deviation(s) to the ledger atomically. The two cannot drift apart.
+     *
+     * `line` is the C++ text the renderer was already going to emit (without
+     * a trailing newline). `currentLine` is the 1-based line number it will
+     * occupy in the emitted file (used for the ledger).
+     */
+    emitWithDeviation(line: string, ruleId: string | string[], justification: string, currentLine?: number, file?: "source" | "header", source?: {
+        tsFile: string;
+        tsLine: number;
+        kind: DeviationKind;
+    }): string;
+    /**
+     * Opens a deviation region. Returns the opening line with the inline
+     * comment appended (the renderer emits this as the first line of the
+     * block). The matching closeDeviationRegion records the endLine.
+     */
+    openDeviationRegion(ruleId: string, justification: string, startLine: number, openingSnippet: string, file?: "source" | "header"): string;
+    closeDeviationRegion(endLine: number): void;
+    /**
+     * Optional positive assertion: "I deliberately satisfied ruleId here."
+     * No-op today; recorded for future coverage tooling.
+     */
+    noteCompliant(_ruleId: string): void;
+}

package/dist/emit/compliance/compliance-context.js

@@ -0,0 +1,113 @@
+import { DeviationLedger } from "./deviation-ledger.js";
+import { getRule, rulesByCategory } from "./rules.js";
+/**
+ * Per-emit compliance bag, threaded through EmitterContext. Owns the
+ * deviation ledger and exposes the renderer-facing API.
+ *
+ * When mode === "off" (the default), every method is a no-op: helpers
+ * return their input unchanged, nothing is recorded. This is what lets
+ * the feature land without changing any existing emitted output.
+ */
+export class ComplianceContext {
+    constructor(complianceMode) {
+        this.complianceMode = complianceMode;
+        this.ledgerInstance = new DeviationLedger();
+        // Precompute the set of [C]-category rule ids once.
+        this.bannedKinds = new Set(rulesByCategory("C").map((r) => r.id));
+    }
+    mode() {
+        return this.complianceMode;
+    }
+    isEnabled() {
+        return this.complianceMode !== "off";
+    }
+    ledger() {
+        return this.ledgerInstance;
+    }
+    /**
+     * Record a deviation for a known unavoidable pattern (used by the
+     * self-check's knownPatterns mechanism). Unlike emitWithDeviation, this
+     * does NOT append an inline comment — the deviation is recorded in the
+     * ledger only, so the sidecar lists it. The emitted C++ text is unchanged.
+     */
+    recordKnownDeviation(ruleId, justification, line, file, snippet, source) {
+        if (!this.isEnabled())
+            return;
+        this.ledgerInstance.record({
+            ruleId,
+            file,
+            line,
+            snippet,
+            justification,
+            source,
+        });
+    }
+    /** Renderer gate: should it avoid the banned spelling for this rule? */
+    isBanned(ruleId) {
+        if (!this.isEnabled())
+            return false;
+        return this.bannedKinds.has(ruleId);
+    }
+    /**
+     * Returns `line` with an appended inline deviation comment, and records
+     * the deviation(s) to the ledger atomically. The two cannot drift apart.
+     *
+     * `line` is the C++ text the renderer was already going to emit (without
+     * a trailing newline). `currentLine` is the 1-based line number it will
+     * occupy in the emitted file (used for the ledger).
+     */
+    emitWithDeviation(line, ruleId, justification, currentLine = 0, file = "source", source) {
+        if (!this.isEnabled())
+            return line;
+        const ids = Array.isArray(ruleId) ? ruleId : [ruleId];
+        for (const id of ids) {
+            if (!getRule(id)) {
+                throw new Error(`Unknown AUTOSAR rule id: ${id}`);
+            }
+        }
+        const tag = ids.join(", ");
+        for (const id of ids) {
+            this.ledgerInstance.record({
+                ruleId: id,
+                file,
+                line: currentLine,
+                snippet: line,
+                justification,
+                source,
+            });
+        }
+        return `${line}  // AUTOSAR Deviation ${tag}: ${justification}`;
+    }
+    /**
+     * Opens a deviation region. Returns the opening line with the inline
+     * comment appended (the renderer emits this as the first line of the
+     * block). The matching closeDeviationRegion records the endLine.
+     */
+    openDeviationRegion(ruleId, justification, startLine, openingSnippet, file = "source") {
+        if (!this.isEnabled())
+            return openingSnippet;
+        if (!getRule(ruleId)) {
+            throw new Error(`Unknown AUTOSAR rule id: ${ruleId}`);
+        }
+        this.ledgerInstance.openRegion({
+            ruleId,
+            file,
+            line: startLine,
+            snippet: openingSnippet,
+            justification,
+        });
+        return `${openingSnippet}  // AUTOSAR Deviation ${ruleId}: ${justification}`;
+    }
+    closeDeviationRegion(endLine) {
+        if (!this.isEnabled())
+            return;
+        this.ledgerInstance.closeRegion(endLine);
+    }
+    /**
+     * Optional positive assertion: "I deliberately satisfied ruleId here."
+     * No-op today; recorded for future coverage tooling.
+     */
+    noteCompliant(_ruleId) {
+        // intentionally no-op; reserved for future use.
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { Deviation } from "./types.js";
+/** Input shape for recording a deviation (line + endLine derived from context). */
+export interface DeviationInput {
+    ruleId: string;
+    file: "source" | "header";
+    line: number;
+    snippet: string;
+    justification: string;
+    source?: Deviation["source"];
+}
+/**
+ * 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 declare class DeviationLedger {
+    private readonly entries;
+    private openRegionEntry;
+    record(input: DeviationInput): void;
+    openRegion(input: DeviationInput): void;
+    closeRegion(endLine: number): void;
+    all(): readonly Deviation[];
+    /** Used by the self-check to verify every ledger entry has a matching inline comment. */
+    hasEntry(file: "source" | "header", line: number, ruleId: string): boolean;
+    private append;
+}