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

package/dist/ir/identifier-collector.js

@@ -423,6 +423,22 @@ function collectHALOpIdentifiers(op) {
             // handler is a resolved C++ function name (e.g. "myIsr" or a placeholder)
             identifiers.add(op.handler);
             break;
+        case "mqtt.on_message":
+            // handler is the user's onMessage callback name (callback() resolves it to
+            // a string). Without this the tree-shaker drops the function declaration —
+            // the mqtt.on_message op only carries the name, so the function has no
+            // other reference and looks unreachable. Same shape as interrupt.attach.
+            identifiers.add(op.handler);
+            break;
+        case "wifi.on_event":
+            identifiers.add(op.handler);
+            break;
+        case "ble.on_read":
+        case "ble.on_write":
+        case "ble.on_connect":
+        case "ble.on_disconnect":
+            identifiers.add(op.handler);
+            break;
         case "raw": {
             // Raw C++ code may reference user-defined identifiers
             const matches = op.code.match(/[A-Za-z_][A-Za-z0-9_]*/g);
@@ -435,5 +451,24 @@ function collectHALOpIdentifiers(op) {
         }
         // Other HAL ops have only numeric/literal fields — no identifier references
     }
+    // wifi.* / http.* / mqtt.* ops carry resolved C++ expression texts in their
+    // string fields (e.g. wifi.connect ssid: `WIFI_SSID` — a top-level const, or
+    // a quoted literal). Scan every string field for identifiers so referenced
+    // globals survive tree-shaking; quoted literals are skipped.
+    if (op.operation.startsWith("wifi.") || op.operation.startsWith("http.")
+        || op.operation.startsWith("mqtt.")) {
+        for (const value of Object.values(op)) {
+            if (typeof value !== "string" || value === op.operation)
+                continue;
+            if (/^".*"$/.test(value.trim()))
+                continue;
+            const matches = value.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+            if (matches) {
+                for (const match of matches) {
+                    identifiers.add(match);
+                }
+            }
+        }
+    }
     return identifiers;
 }

package/dist/ir/interrupt-analysis.d.ts

@@ -1,4 +1,4 @@
-import type { ProgramIR } from '../api/index.js';
+import type { ProgramIR, StatementIR } from '../api/index.js';
 import type { PeripheralUsage } from './peripheral-usage.js';
 import type { Diagnostic } from '../types.js';
 export { walkNestedStatements as scanNestedStatements } from './utils/walk-ir.js';
@@ -24,6 +24,10 @@ export interface InterruptHandlerInfo {
  * @returns Array of diagnostics for interrupt-related issues
  */
 export declare function analyzeInterruptSafety(program: ProgramIR, usage: PeripheralUsage, isrUnsafeOps?: Map<string, IsrUnsafeOp>): Diagnostic[];
+/** Collect variable names assigned (written) within a statement body. */
+export declare function collectAssignedNames(stmts: readonly StatementIR[], names: Set<string>): void;
+/** Collect variable names read (referenced) within a statement body. */
+export declare function collectReadNames(stmts: readonly StatementIR[], names: Set<string>): void;
 /**
  * Infer `volatile` for global variables shared between ISR callbacks and main
  * code. Mutates the IR (sets isVolatile=true on qualifying var_decls) and

package/dist/ir/interrupt-analysis.js

@@ -7,21 +7,13 @@
 import { walkNestedStatements, walkExpressionsInExpression } from './utils/walk-ir.js';
 export { walkNestedStatements as scanNestedStatements } from './utils/walk-ir.js';
 /**
- * Default ISR-unsafe operations used when no platform-specific map is provided.
- * Platforms should supply their own list via PlatformStrategy.isrUnsafeOperations().
+ * Fallback ISR-unsafe operations used when no platform-specific map is provided.
+ * Empty by design — the Wiring-derived specifics (delay, Serial.*, I2C*, SPI*)
+ * live in ArduinoStrategy.isrUnsafeOperations(). A generic target has no known
+ * ISR-unsafe surface. The orchestrator passes the loaded framework's map; this
+ * default only applies when none is supplied.
  */
-const DEFAULT_ISR_UNSAFE_OPERATIONS = new Map([
-    ['delay', { reason: 'delay() blocks the CPU and should not be used in interrupt context', severity: 'warning' }],
-    ['delayMicroseconds', { reason: 'delayMicroseconds() blocks and should be avoided in ISRs', severity: 'warning' }],
-    ['Serial.print', { reason: 'Serial.print() may not work correctly in interrupt context', severity: 'info' }],
-    ['Serial.println', { reason: 'Serial.println() may not work correctly in interrupt context', severity: 'info' }],
-    ['Serial.write', { reason: 'Serial.write() may not work correctly in interrupt context', severity: 'info' }],
-    ['Serial.read', { reason: 'Serial.read() may not work correctly in interrupt context', severity: 'info' }],
-    ['I2C0', { reason: 'I2C operations can cause lockups in interrupt context', severity: 'warning' }],
-    ['I2C1', { reason: 'I2C operations can cause lockups in interrupt context', severity: 'warning' }],
-    ['SPI0', { reason: 'SPI operations may cause issues in interrupt context', severity: 'info' }],
-    ['SPI1', { reason: 'SPI operations may cause issues in interrupt context', severity: 'info' }],
-]);
+const DEFAULT_ISR_UNSAFE_OPERATIONS = new Map();
 /**
  * Analyze a program for interrupt handler issues.
  *
@@ -93,9 +85,10 @@ function isInterruptHandlerCallback(callback, parentExpr) {
 function scanStatementForUnsafeOps(stmt, diagnostics, unsafeOps) {
     if (!stmt || typeof stmt !== 'object')
         return;
+    const filePath = stmt.sourceSpan?.filePath;
     if (stmt.kind === 'call') {
         const call = stmt;
-        checkCalleeForUnsafeOp(call.callee, diagnostics, unsafeOps);
+        checkCalleeForUnsafeOp(call.callee, diagnostics, unsafeOps, filePath);
     }
     // HAL-op statements: after HAL resolution, bare Arduino calls like delay()
     // and delayMicroseconds() become structured hal-op statements (timing.delay,
@@ -110,7 +103,7 @@ function scanStatementForUnsafeOps(stmt, diagnostics, unsafeOps) {
             };
             const key = HAL_OP_TO_UNSAFE[op.operation];
             if (key)
-                checkCalleeForUnsafeOp(key, diagnostics, unsafeOps);
+                checkCalleeForUnsafeOp(key, diagnostics, unsafeOps, filePath);
         }
     }
     walkNestedStatements(stmt, (s) => scanStatementForUnsafeOps(s, diagnostics, unsafeOps));
@@ -118,7 +111,7 @@ function scanStatementForUnsafeOps(stmt, diagnostics, unsafeOps) {
 /**
  * Check if a callee is an unsafe operation and generate diagnostic.
  */
-function checkCalleeForUnsafeOp(callee, diagnostics, unsafeOps) {
+function checkCalleeForUnsafeOp(callee, diagnostics, unsafeOps, filePath) {
     if (!callee)
         return;
     // Check direct matches
@@ -128,6 +121,7 @@ function checkCalleeForUnsafeOp(callee, diagnostics, unsafeOps) {
             severity: unsafe.severity,
             message: `${callee}() ${unsafe.reason}`,
             code: 'interrupt-unsafe-operation',
+            filePath,
             source: 'interrupt-analysis',
         });
         return;
@@ -139,6 +133,7 @@ function checkCalleeForUnsafeOp(callee, diagnostics, unsafeOps) {
                 severity: info.severity,
                 message: `${callee} - ${info.reason}`,
                 code: 'interrupt-unsafe-operation',
+                filePath,
                 source: 'interrupt-analysis',
             });
             return;
@@ -240,7 +235,7 @@ function scanExpressionForCallbacks(expr, callback, parentExpr) {
 // emission path already handles isVolatile (statement-renderer.ts).
 // ---------------------------------------------------------------------------
 /** Collect variable names assigned (written) within a statement body. */
-function collectAssignedNames(stmts, names) {
+export function collectAssignedNames(stmts, names) {
     for (const stmt of stmts) {
         const s = stmt;
         if (stmt.kind === 'assign') {
@@ -262,7 +257,7 @@ function collectAssignedNames(stmts, names) {
     }
 }
 /** Collect variable names read (referenced) within a statement body. */
-function collectReadNames(stmts, names) {
+export function collectReadNames(stmts, names) {
     for (const stmt of stmts) {
         walkExpressionsInStatement(stmt, (expr) => {
             if (expr.kind === 'identifier' && typeof expr.value === 'string') {
@@ -354,6 +349,7 @@ export function inferVolatileForIsrSharedVars(program, diagnostics) {
             diagnostics.push({
                 severity: 'info',
                 message: `'${name}' is written in an interrupt handler and read in main code — emitted as \`volatile\` to prevent the compiler from caching it in a register (the classic ISR/loop race).`,
+                filePath: stmt.sourceSpan?.filePath,
                 line: stmt.sourceSpan?.startLine,
                 column: stmt.sourceSpan?.startColumn,
                 code: 'volatile-isr-shared',
@@ -460,6 +456,7 @@ export function detectReentrancyRisk(program, diagnostics) {
                 severity: 'warning',
                 message: `'${name}' is called from both an interrupt handler and main-thread code. An interrupt firing mid-execution can corrupt the function's local state. Wrap the main-thread call in noInterrupts()/interrupts(), or refactor to avoid sharing the function.`,
                 code: 'reentrancy-risk',
+                filePath: program.fileName,
                 source: 'interrupt-analysis',
             });
         }

package/dist/ir/memory-budget-validation.js

@@ -78,6 +78,7 @@ export function validateMemoryBudget(program, boardConstants) {
                     : `Stack and heap share the remaining space; deep call chains or heap allocation risk collision.`),
             hint: `Reduce global/static data, move large buffers to PROGMEM (flash), shorten deep call chains, ` +
                 `or use a board with more SRAM. See the heap estimate in the diagnostics report for a breakdown.`,
+            filePath: program.fileName,
             code: 'memory-budget',
             source: 'memory-budget-validation',
         });

package/dist/ir/network-validation.d.ts

@@ -0,0 +1,4 @@
+import type { ProgramIR } from "../api/index.js";
+import type { Diagnostic } from "../types.js";
+import type { BoardConstants } from "./board-resolver.js";
+export declare function validateNetworkUsage(program: ProgramIR, boardConstants?: BoardConstants): Diagnostic[];

package/dist/ir/network-validation.js

@@ -0,0 +1,184 @@
+// ---------------------------------------------------------------------------
+// Network (WiFi / HTTP) Validation
+//
+// Board-aware, compile-time checks for the WiFi/HTTP HAL:
+//
+//   wifi-no-radio             (error)   wifi.*/http.* used on a board whose
+//                                       architecture has no WiFi radio (avr).
+//   http-without-wifi         (warning) http.* used but the program never
+//                                       brings a WiFi link up (connect /
+//                                       connectSaved / connectAsync / AP).
+//   wifi-blocking-in-loop     (warning) blocking WiFi.connect()/scan() or
+//                                       Http send inside loop() — stalls every
+//                                       iteration; use async/await instead.
+//   wifi-ap-password-short    (error)   WiFi.startAP() with a literal WPA2
+//                                       password shorter than 8 characters —
+//                                       esp_wifi rejects it at runtime.
+//   http-max-body-large       (warning) Http maxBody() above 64 KB — the
+//                                       response buffer is heap-allocated.
+//
+// Follows the ADC-validation convention: checks that need board data return
+// nothing when the data is missing (no MCU-name fallbacks).
+// ---------------------------------------------------------------------------
+import { walkProgramIR, walkNestedStatements } from "./utils/walk-ir.js";
+/** Architectures with no WiFi radio. Driven by the `architecture` board
+ *  constant (from the MCU package); absent data emits nothing. */
+const NO_RADIO_ARCHITECTURES = new Set(["avr"]);
+/** Ops that bring the WiFi link (STA or AP) up. */
+const LINK_UP_OPS = new Set([
+    "wifi.connect",
+    "wifi.connect_start",
+    "wifi.connect_saved",
+    "wifi.ap_start",
+]);
+/** Blocking waits that stall loop() for their full duration. */
+const BLOCKING_LOOP_OPS = new Set([
+    "wifi.connect",
+    "wifi.connect_saved",
+    "wifi.wait_connected",
+    "wifi.wait_disconnected",
+    "wifi.scan",
+    "http.send",
+]);
+/** Strip surrounding quotes from a resolved HAL string field; returns null
+ *  when the field is not a literal (identifier/expression — unknowable). */
+function literalString(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    const match = trimmed.match(/^"((?:[^"\\]|\\.)*)"$/);
+    return match ? match[1] : null;
+}
+function diagAt(stmt, partial) {
+    const s = stmt;
+    return {
+        ...partial,
+        line: s.sourceSpan?.startLine,
+        column: s.sourceSpan?.startColumn,
+        filePath: s.sourceSpan?.filePath,
+        source: "network-validation",
+    };
+}
+/** Pull every wifi./http. op out of a statement: hal-op statements, awaited
+ *  __WIFI_WAIT__/__HTTP_WAIT__ marker calls (hal-expr arg), and hal-expr
+ *  expressions in call args / initializers / conditions. */
+function collectNetworkOps(stmt, out) {
+    const s = stmt;
+    const record = (op) => {
+        const operation = op?.operation;
+        if (typeof operation === "string" && (operation.startsWith("wifi.") || operation.startsWith("http."))) {
+            out.push({ op: op, stmt });
+        }
+    };
+    if (stmt.kind === "hal-op")
+        record(s.operation);
+    const visitExpr = (expr) => {
+        if (!expr || typeof expr !== "object")
+            return;
+        const e = expr;
+        if (e.kind === "hal-expr")
+            record(e.operation);
+        for (const key of ["args", "elements", "parts"]) {
+            if (Array.isArray(e[key]))
+                for (const child of e[key])
+                    visitExpr(child);
+        }
+        for (const key of ["left", "right", "operand", "condition", "whenTrue", "whenFalse", "inner", "value", "expression"]) {
+            if (e[key] && typeof e[key] === "object")
+                visitExpr(e[key]);
+        }
+    };
+    for (const key of ["args", "value", "condition", "initializer", "expression"]) {
+        if (s[key]) {
+            if (Array.isArray(s[key]))
+                for (const child of s[key])
+                    visitExpr(child);
+            else
+                visitExpr(s[key]);
+        }
+    }
+}
+export function validateNetworkUsage(program, boardConstants) {
+    const diagnostics = [];
+    const constants = boardConstants ?? program.boardConstants;
+    // Collect every wifi./http. op in the program.
+    const allOps = [];
+    walkProgramIR(program, (stmt) => collectNetworkOps(stmt, allOps));
+    if (allOps.length === 0)
+        return diagnostics;
+    const wifiOps = allOps.filter(({ op }) => op.operation.startsWith("wifi."));
+    const httpOps = allOps.filter(({ op }) => op.operation.startsWith("http."));
+    // ── wifi-no-radio ────────────────────────────────────────────────────────
+    const architecture = constants?.get("architecture");
+    const archName = typeof architecture === "string" ? architecture.replace(/^["']|["']$/g, "").toLowerCase() : null;
+    if (archName && NO_RADIO_ARCHITECTURES.has(archName)) {
+        const first = allOps[0];
+        diagnostics.push(diagAt(first.stmt, {
+            severity: "error",
+            code: "wifi-no-radio",
+            message: `WiFi/HTTP APIs are used but the target board's architecture ('${archName}') has no WiFi radio.`,
+            hint: "Target a WiFi-capable board (e.g. @typecad/board-esp32-devkit) or remove the WiFi/HTTP calls.",
+        }));
+        // No point piling on the remaining checks for a board that can't radio.
+        return diagnostics;
+    }
+    // ── http-without-wifi ────────────────────────────────────────────────────
+    if (httpOps.length > 0 && !wifiOps.some(({ op }) => LINK_UP_OPS.has(op.operation))) {
+        diagnostics.push(diagAt(httpOps[0].stmt, {
+            severity: "warning",
+            code: "http-without-wifi",
+            message: "HTTP requests are made but the program never brings the WiFi link up — every request will fail at runtime.",
+            hint: "Call WiFi.connect(ssid, password) (or WiFi.connectSaved() / WiFi.startAP()) before sending HTTP requests.",
+        }));
+    }
+    // ── wifi-blocking-in-loop ────────────────────────────────────────────────
+    // Blocking hal-op statements inside loop()'s body stall every iteration.
+    // Awaited forms are rewritten to __WIFI_WAIT__/__HTTP_WAIT__ marker calls
+    // (kind "call"), so only genuine blocking hal-ops are flagged here.
+    const loopFn = program.functions.find((fn) => fn.originalName === "loop");
+    if (loopFn?.statements) {
+        const visit = (stmt) => {
+            if (stmt.kind === "hal-op" && BLOCKING_LOOP_OPS.has(stmt.operation?.operation)) {
+                const opName = stmt.operation.operation;
+                diagnostics.push(diagAt(stmt, {
+                    severity: "warning",
+                    code: "wifi-blocking-in-loop",
+                    message: `Blocking network operation '${opName}' inside loop() stalls every iteration until it completes (seconds for a connect/scan/request).`,
+                    hint: "Move the call into an async function and `await` it — the transpiler lowers awaited WiFi/HTTP calls to non-blocking start + poll states.",
+                }));
+            }
+            walkNestedStatements(stmt, visit);
+        };
+        for (const stmt of loopFn.statements)
+            visit(stmt);
+    }
+    // ── wifi-ap-password-short ───────────────────────────────────────────────
+    for (const { op, stmt } of wifiOps) {
+        if (op.operation !== "wifi.ap_start")
+            continue;
+        const password = literalString(op.password);
+        if (password !== null && password.length > 0 && password.length < 8) {
+            diagnostics.push(diagAt(stmt, {
+                severity: "error",
+                code: "wifi-ap-password-short",
+                message: `WiFi.startAP() password is ${password.length} characters — WPA2 requires at least 8, and esp_wifi rejects shorter ones at runtime.`,
+                hint: "Use a password of 8+ characters, or omit the password entirely for an open access point.",
+            }));
+        }
+    }
+    // ── http-max-body-large ──────────────────────────────────────────────────
+    for (const { op, stmt } of httpOps) {
+        if (op.operation !== "http.set_max_body")
+            continue;
+        const bytes = Number(String(op.bytes).trim());
+        if (Number.isFinite(bytes) && bytes > 65536) {
+            diagnostics.push(diagAt(stmt, {
+                severity: "warning",
+                code: "http-max-body-large",
+                message: `Http maxBody(${bytes}) heap-allocates a ${Math.round(bytes / 1024)} KB response buffer — large buffers risk allocation failure under fragmentation.`,
+                hint: "Keep the response cap at or below 64 KB, or process large payloads in chunks server-side.",
+            }));
+        }
+    }
+    return diagnostics;
+}

package/dist/ir/ownership-analysis.js

@@ -176,6 +176,7 @@ function scanStatementsForByValueMutation(stmts, fnName, byValueParams, diagnost
                             hint: `Use '${baseName}: Mutable<T>' to pass by mutable reference (T&) instead of a copy.`,
                             line: stmt.sourceSpan.startLine,
                             column: stmt.sourceSpan.startColumn,
+                            filePath: stmt.sourceSpan.filePath,
                             code: 'ownership-mutate-copy',
                             source: 'ownership-analysis',
                         });
@@ -330,6 +331,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                                     hint: `const ${stmt.name}: Shared = ${initName};  // borrow by reference instead of copying`,
                                     line: span.startLine,
                                     column: span.startColumn,
+                                    filePath: span.filePath,
                                     code: 'ownership-owned-copy',
                                     source: 'ownership-analysis',
                                 });
@@ -346,6 +348,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                                 hint: `const ${stmt.name}: Shared = ${initName};  // borrow by const reference, zero copy`,
                                 line: span.startLine,
                                 column: span.startColumn,
+                                filePath: span.filePath,
                                 code: 'ownership-implicit-copy',
                                 source: 'ownership-analysis',
                             });
@@ -363,6 +366,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                             hint: `${storageKw} _tmp: Owned = ...;\nconst ${stmt.name}: ${annotLabel} = _tmp;`,
                             line: span.startLine,
                             column: span.startColumn,
+                            filePath: span.filePath,
                             code: 'ownership-temp-ref-warn',
                             source: 'ownership-analysis',
                         });
@@ -386,6 +390,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                     hint: `change '${stmt.target}${typeAnnotation}' → '${stmt.target}: Mutable'  // Mutable allows mutation`,
                     line: span.startLine,
                     column: span.startColumn,
+                    filePath: span.filePath,
                     code: 'ownership-assign-to-ref',
                     source: 'ownership-analysis',
                 });
@@ -430,6 +435,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                         hint: `Use '${baseName}: Mutable<T>' to pass by mutable reference (T&) instead of a copy.`,
                         line: span.startLine,
                         column: span.startColumn,
+                        filePath: span.filePath,
                         code: 'ownership-mutate-copy',
                         source: 'ownership-analysis',
                     });
@@ -449,6 +455,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                     hint: `change '${stmt.target}${typeAnnotation}' → '${stmt.target}: Mutable'  // Mutable allows mutation`,
                     line: span.startLine,
                     column: span.startColumn,
+                    filePath: span.filePath,
                     code: 'ownership-assign-to-ref',
                     source: 'ownership-analysis',
                 });
@@ -461,6 +468,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                     hint: `const ${stmt.target}_ref: Shared = ${stmt.target};  // add this before the move`,
                     line: span.startLine,
                     column: span.startColumn,
+                    filePath: span.filePath,
                     code: 'ownership-use-after-move',
                     source: 'ownership-analysis',
                 });
@@ -477,6 +485,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                         hint: `Use '${upBaseName}: Mutable<T>' to pass by mutable reference (T&) instead of a copy.`,
                         line: span.startLine,
                         column: span.startColumn,
+                        filePath: span.filePath,
                         code: 'ownership-mutate-copy',
                         source: 'ownership-analysis',
                     });
@@ -507,6 +516,7 @@ function analyzeStatement(stmt, scope, diagnostics) {
                                 hint: `return ${retVar.borrowSource} directly as Owned, or change the function to accept '${retVar.borrowSource}: Shared' as a parameter`,
                                 line: span.startLine,
                                 column: span.startColumn,
+                                filePath: span.filePath,
                                 code: 'ownership-return-local-ref',
                                 source: 'ownership-analysis',
                             });
@@ -641,6 +651,7 @@ function analyzeExpression(expr, scope, diagnostics, fallbackSpan) {
                     hint: `const ${name}_ref: Shared = ${name};  // add this before the move`,
                     line: span.startLine,
                     column: span.startColumn,
+                    filePath: span.filePath,
                     code: 'ownership-use-after-move',
                     source: 'ownership-analysis',
                 });
@@ -714,6 +725,7 @@ function analyzeExpression(expr, scope, diagnostics, fallbackSpan) {
                             hint: `const ${match}_ref: Shared = ${match};  // add this before the move`,
                             line: span.startLine,
                             column: span.startColumn,
+                            filePath: span.filePath,
                             code: 'ownership-use-after-move',
                             source: 'ownership-analysis',
                         });
@@ -753,6 +765,12 @@ function analyzeExpression(expr, scope, diagnostics, fallbackSpan) {
             analyzeExpression(expr.inner, scope, diagnostics, span);
             break;
         }
+        case 'call': {
+            for (const arg of expr.args) {
+                analyzeExpression(arg, scope, diagnostics, span);
+            }
+            break;
+        }
         case 'number':
         case 'string':
         case 'boolean':
@@ -908,6 +926,7 @@ function validateConstSuggestions(program, diagnostics) {
                                 message: `'${baseName}' is declared 'const' but its contents are mutated via index assignment — demoted to non-const in C++ so the mutation compiles.`,
                                 line: constEntry.span.startLine,
                                 column: constEntry.span.startColumn,
+                                filePath: constEntry.span.filePath,
                                 code: 'ownership-const-content-mutated',
                                 source: 'ownership-analysis',
                             });
@@ -930,6 +949,7 @@ function validateConstSuggestions(program, diagnostics) {
                                 message: `'${baseName}' is declared 'const' but a field is mutated via member assignment — demoted to non-const in C++ so the mutation compiles.`,
                                 line: constEntry.span.startLine,
                                 column: constEntry.span.startColumn,
+                                filePath: constEntry.span.filePath,
                                 code: 'ownership-const-content-mutated',
                                 source: 'ownership-analysis',
                             });
@@ -957,6 +977,7 @@ function validateConstSuggestions(program, diagnostics) {
                                 message: `'${baseName}' is declared 'const' but a field is mutated via ++/-- — demoted to non-const in C++ so the mutation compiles.`,
                                 line: constEntry.span.startLine,
                                 column: constEntry.span.startColumn,
+                                filePath: constEntry.span.filePath,
                                 code: 'ownership-const-content-mutated',
                                 source: 'ownership-analysis',
                             });
@@ -968,7 +989,20 @@ function validateConstSuggestions(program, diagnostics) {
                 // keep the binding non-const so push_back/splice/etc. compile. The
                 // callee is the lowered C++ name, e.g. "arr.push_back".
                 if (stmt.kind === 'call' && typeof stmt.callee === 'string') {
-                    const callee = stmt.callee;
+                    // Value-arg array methods (.push/.pop/.fill/...) are lowered in
+                    // call-statement.ts to a fully-formed raw C++ expression wrapped as
+                    // `__RAW_STMT__<receiver>.<method>(<args>)` (e.g. `__RAW_STMT__arr.push_back(1)`).
+                    // Strip the wrapper — and the trailing `(args)` when present — before
+                    // splitting, otherwise the dot parse yields a receiver of
+                    // `__RAW_STMT__arr` and a method of `push_back(1)` and the demotion
+                    // below never fires, leaving a non-compiling `const std::vector` +
+                    // push_back. Mirrors the __RAW_STMT__ handling in program-analysis.ts.
+                    const rawCallee = stmt.callee;
+                    const unwrapped = rawCallee.startsWith('__RAW_STMT__')
+                        ? rawCallee.slice('__RAW_STMT__'.length)
+                        : rawCallee;
+                    const parenIdx = unwrapped.indexOf('(');
+                    const callee = parenIdx > 0 ? unwrapped.slice(0, parenIdx) : unwrapped;
                     const dot = callee.lastIndexOf('.');
                     if (dot > 0) {
                         const receiver = callee.slice(0, dot);
@@ -991,6 +1025,7 @@ function validateConstSuggestions(program, diagnostics) {
                                     message: `'${receiver}' is declared 'const' but its contents are mutated via .${method}() — demoted to non-const in C++ so the mutation compiles.`,
                                     line: constEntry.span.startLine,
                                     column: constEntry.span.startColumn,
+                                    filePath: constEntry.span.filePath,
                                     code: 'ownership-const-content-mutated',
                                     source: 'ownership-analysis',
                                 });
@@ -1023,6 +1058,7 @@ function validateConstSuggestions(program, diagnostics) {
                     message: `'${entry.name}' is never reassigned — emitted as \`const\` so the C++ compiler can place it in ROM and fold it.`,
                     line: entry.span.startLine,
                     column: entry.span.startColumn,
+                    filePath: entry.span.filePath,
                     code: 'ownership-suggest-const',
                     source: 'ownership-analysis',
                 });
@@ -1072,6 +1108,7 @@ function checkBorrowMismatch(program, diagnostics) {
                                     hint: `change '${arg.value}: Shared = ...' → '${arg.value}: Mutable = ...'`,
                                     line: stmt.sourceSpan.startLine,
                                     column: stmt.sourceSpan.startColumn,
+                                    filePath: stmt.sourceSpan.filePath,
                                     code: 'ownership-borrow-mismatch',
                                     source: 'ownership-analysis',
                                 });
@@ -1127,6 +1164,7 @@ function checkDanglingBorrowsOnScopeExit(exitingScope, diagnostics, span) {
                     hint: `move '${v.borrowSource}' to the outer scope, or ensure '${v.name}' does not outlive it`,
                     line: span.startLine,
                     column: span.startColumn,
+                    filePath: span.filePath,
                     code: 'ownership-dangling-borrow',
                     source: 'ownership-analysis',
                 });

package/dist/ir/peripheral-ownership.js

@@ -32,6 +32,7 @@ export function validatePeripheralOwnership(program) {
                             severity: 'error',
                             message: `Double-take: '${bus}' is already owned.`,
                             hint: `Call '${bus}.release()' before taking it again.`,
+                            filePath: span.filePath,
                             line: span.startLine,
                             column: span.startColumn,
                             code: 'hal-ownership-double-take',
@@ -79,6 +80,7 @@ export function validatePeripheralOwnership(program) {
                             severity: 'error',
                             message: `Double-take: '${bus}' is already owned.`,
                             hint: `Call '${bus}.release()' before taking it again.`,
+                            filePath: span.filePath,
                             line: span.startLine,
                             column: span.startColumn,
                             code: 'hal-ownership-double-take',
@@ -94,6 +96,7 @@ export function validatePeripheralOwnership(program) {
                             severity: 'warning',
                             message: `'${bus}.release()' called but bus was not taken.`,
                             hint: `Ensure you call '${bus}.take()' before releasing.`,
+                            filePath: span.filePath,
                             line: span.startLine,
                             column: span.startColumn,
                             code: 'hal-ownership-unowned-release',
@@ -108,6 +111,7 @@ export function validatePeripheralOwnership(program) {
                         severity: 'error',
                         message: `Unowned access: '${bus}' is used without being taken.`,
                         hint: `Call 'const bus = ${bus}.take();' and use the returned 'bus' object, or ensure '${bus}' is taken in the current scope.`,
+                        filePath: span.filePath,
                         line: span.startLine,
                         column: span.startColumn,
                         code: 'hal-ownership-unowned-access',
@@ -142,6 +146,7 @@ export function validatePeripheralOwnership(program) {
             severity: 'warning',
             message: `'${bus}' was taken but never released.`,
             hint: `Call '${bus}.release()' when finished with the bus.`,
+            filePath: busSpan.filePath,
             line: busSpan.startLine,
             column: busSpan.startColumn,
             code: 'hal-ownership-leak',

package/dist/ir/peripheral-validation.d.ts

@@ -5,4 +5,4 @@ import { Diagnostic } from '../types.js';
  * Validate peripheral usage and return diagnostics.
  * This is the main entry point for peripheral validation.
  */
-export declare function validatePeripherals(usage: PeripheralUsage, boardConstants: BoardConstants | undefined): Diagnostic[];
+export declare function validatePeripherals(usage: PeripheralUsage, boardConstants: BoardConstants | undefined, filePath: string): Diagnostic[];

package/dist/ir/peripheral-validation.js

@@ -26,7 +26,7 @@ function getPeripheralCapacity(boardConstants) {
  * Validate peripheral usage against board capacity.
  * Returns an array of diagnostics for any invalid peripheral usage.
  */
-function validatePeripheralUsage(usage, capacity, boardName = 'this board') {
+function validatePeripheralUsage(usage, capacity, boardName, filePath) {
     const diagnostics = [];
     // Validate I2C instances
     for (const instance of usage.i2cInstancesUsed) {
@@ -36,6 +36,7 @@ function validatePeripheralUsage(usage, capacity, boardName = 'this board') {
                 severity: 'error',
                 message: `I2C${instance} is not available on ${boardName}. Available: ${availableName}`,
                 code: 'peripheral-not-available',
+                filePath,
                 source: 'peripheral-validation',
             });
         }
@@ -48,6 +49,7 @@ function validatePeripheralUsage(usage, capacity, boardName = 'this board') {
                 severity: 'error',
                 message: `SPI${instance} is not available on ${boardName}. Available: ${availableName}`,
                 code: 'peripheral-not-available',
+                filePath,
                 source: 'peripheral-validation',
             });
         }
@@ -60,6 +62,7 @@ function validatePeripheralUsage(usage, capacity, boardName = 'this board') {
                 severity: 'error',
                 message: `UART${instance} is not available on ${boardName}. Available: ${availableName}`,
                 code: 'peripheral-not-available',
+                filePath,
                 source: 'peripheral-validation',
             });
         }
@@ -70,8 +73,8 @@ function validatePeripheralUsage(usage, capacity, boardName = 'this board') {
  * Validate peripheral usage and return diagnostics.
  * This is the main entry point for peripheral validation.
  */
-export function validatePeripherals(usage, boardConstants) {
+export function validatePeripherals(usage, boardConstants, filePath) {
     const capacity = getPeripheralCapacity(boardConstants);
     const boardName = boardConstants?.get('name') ?? 'this board';
-    return validatePeripheralUsage(usage, capacity, boardName);
+    return validatePeripheralUsage(usage, capacity, boardName, filePath);
 }

package/dist/ir/pin-alias-conflict.d.ts

@@ -1,4 +1,4 @@
 import type { Diagnostic } from '../types.js';
 import type { BoardConstants } from './board-resolver.js';
 import type { PeripheralUsage } from './peripheral-usage.js';
-export declare function validatePinAliasConflicts(usage: PeripheralUsage, boardConstants: BoardConstants | undefined): Diagnostic[];
+export declare function validatePinAliasConflicts(usage: PeripheralUsage, boardConstants: BoardConstants | undefined, filePath: string): Diagnostic[];