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

package/dist/emit/emitters/setup.js

@@ -31,6 +31,80 @@ function filterShimBlock(lines, startMarker, endMarker) {
     }
     return filtered;
 }
+/**
+ * Detect whether a program uses the watchdog timer. The HAL resolver lowers
+ * `WDT.enable/reset/disable` calls to structured `wdt.*` hal-ops, which the
+ * setup emitter then renders as bare `wdt_enable/wdt_reset/wdt_disable` calls
+ * (or constant-folded `wdt_enable(WDTO_*)` macros). All of those require
+ * `<avr/wdt.h>`, so the include is gated on this check instead of being forced
+ * into every AVR program.
+ *
+ * `programAnalysis.usesWDT` is NOT used here: it scans `WDT.`-prefixed
+ * callees and raw-code hal-ops, but the structured `wdt.*` ops carry a typed
+ * operation name with no raw code, so the analysis misses them.
+ *
+ * The recursion mirrors `collectStatementIdentifiers` (identifier-collector.ts)
+ * — the canonical IR walker — so every compound statement shape is covered.
+ */
+function programUsesWdt(program) {
+    const visitStatement = (stmt) => {
+        if (stmt.kind === "hal-op") {
+            const opName = stmt.operation?.operation;
+            if (typeof opName === "string" && opName.startsWith("wdt."))
+                return true;
+        }
+        switch (stmt.kind) {
+            case "block":
+            case "labeled":
+                return visit(stmt.body);
+            case "if":
+                return visit(stmt.thenBranch) || visit(stmt.elseBranch ?? []);
+            case "for":
+                return visit(stmt.body)
+                    || (stmt.initializer ? visitStatement(stmt.initializer) : false);
+            case "while":
+            case "do_while":
+            case "for_of":
+            case "for_in":
+                return visit(stmt.body);
+            case "switch":
+                return stmt.cases.some((c) => visit(c.body ?? []));
+            case "try":
+                return visit(stmt.tryBlock) || visit(stmt.catchBlock ?? []) || visit(stmt.finallyBlock ?? []);
+            default:
+                return false;
+        }
+    };
+    const visit = (statements) => {
+        if (!statements)
+            return false;
+        for (const stmt of statements) {
+            if (visitStatement(stmt))
+                return true;
+        }
+        return false;
+    };
+    if (visit(program.topLevelStatements))
+        return true;
+    for (const fn of program.functions) {
+        if (visit(fn.statements))
+            return true;
+    }
+    for (const cls of program.classes) {
+        for (const m of cls.methods)
+            if (visit(m.statements))
+                return true;
+        for (const g of cls.getters)
+            if (visit(g.statements))
+                return true;
+        for (const s of cls.setters)
+            if (visit(s.statements))
+                return true;
+        if (cls.constructor && visit(cls.constructor.statements))
+            return true;
+    }
+    return false;
+}
 /**
  * Extract a `#ifndef MACRO ... #endif` include-guard block from a shim line
  * list. Used to emit just the macro definition (e.g. CUTTLEFISH_UNDEFINED) in
@@ -118,6 +192,14 @@ export function buildEmitterContext(program, options) {
     })();
     const programAnalysis = analyzeProgram(program, strategy);
     if (options.platformContext) {
+        // The UI runtime's per-frame tick calls millis() (injected by the emitter,
+        // not present in user source), so a mounted UI needs the native millis ISR
+        // even when usesNativeTiming is false. OR entryHasUI() into the flag the
+        // AVR strategy reads when gating native_millis, so framework-avr doesn't
+        // drop the Timer0 ISR from a UI program.
+        if (!programAnalysis.usesNativeTiming && entryHasUI()) {
+            programAnalysis.usesNativeTiming = true;
+        }
         options.platformContext.analysis = programAnalysis;
         if (!options.platformContext.architecture && program.boardConstants) {
             options.platformContext.architecture = program.boardConstants.get("architecture");
@@ -223,6 +305,28 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesStrPtr) {
             shimLines = filterShimBlock(shimLines, '#ifndef CUTTLEFISH_STR_BUF_SIZE', 'inline size_t (strlen)(const __tc_str_ptr& s) { return ::strlen(s.buf); }');
         }
+        // framework-avr native peripheral driver shims. Each block carries a
+        // CUTTLEFISH_*_BEGIN/END marker pair; strip the ones the program doesn't
+        // use. framework-arduino's shimLines contain none of these markers, so
+        // these filters are no-ops there. The strategies also self-gate on the
+        // same flags; this is the defensive backstop (mirrors how usesWDT/etc.
+        // backstop the strategy-side gating above).
+        if (!programAnalysis.usesUart) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_BEGIN', '// CUTTLEFISH_UART_END');
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_EXT_BEGIN', '// CUTTLEFISH_UART_EXT_END');
+        }
+        if (!programAnalysis.usesSPI) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_SPI_BEGIN', '// CUTTLEFISH_SPI_END');
+        }
+        if (!programAnalysis.usesI2C) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TWI_BEGIN', '// CUTTLEFISH_TWI_END');
+        }
+        if (!programAnalysis.usesEEPROM) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_EEPROM_BEGIN', '// CUTTLEFISH_EEPROM_END');
+        }
+        if (!programAnalysis.usesTone) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TONE_BEGIN', '// CUTTLEFISH_TONE_END');
+        }
         profileDiagnostics = [...strategy.profileDiagnostics(program, options.platformContext)];
     }
     for (const imported of program.imports) {
@@ -715,7 +819,13 @@ export function buildEmitterContext(program, options) {
         includes.push(...emittedPolyfills.includes.map((include) => normalizeInclude(include)));
     }
     if (program.requiredIncludes) {
-        includes.push(...program.requiredIncludes);
+        let reqIncludes = [...program.requiredIncludes];
+        // Let the strategy strip stale includes (e.g. framework-avr removes
+        // Arduino library headers it doesn't need — Wire.h, SPI.h, etc.).
+        if (strategy.filterRequiredIncludes) {
+            reqIncludes = strategy.filterRequiredIncludes(reqIncludes);
+        }
+        includes.push(...reqIncludes);
     }
     // UI text bindings lower to snprintf bodies that need <stdio.h>. Pushed here
     // (in buildEmitterContext) rather than in emitUIRuntime because emitPreamble
@@ -739,6 +849,17 @@ export function buildEmitterContext(program, options) {
     if (stringEnumNames.size > 0) {
         includes.push(strategy.cstringHeader());
     }
+    // `<avr/wdt.h>` is only needed when the program actually uses the watchdog.
+    // The HAL resolver lowers WDT.enable/reset/disable to bare wdt_*() calls
+    // (or constant-folded wdt_enable(WDTO_*) macros), all of which require the
+    // header. Detect the structured `wdt.*` hal-ops directly here rather than
+    // relying on programAnalysis.usesWDT (which misses these ops — they carry
+    // a typed operation name, not raw code the analysis scans) or on a forced
+    // include in the AVR profile (which leaked the header into every AVR
+    // program, even ones that never touch the watchdog like `led.toggle()`).
+    if (programUsesWdt(program)) {
+        includes.push("<avr/wdt.h>");
+    }
     // Placeholder defaults for fields that are computed later by other phases
     const noopFixPointer = (c) => c;
     // Demo #18 Finding B: collect the names of non-exported free functions that

package/dist/ir/adc-range-validation.js

@@ -59,7 +59,7 @@ function extractNumericValue(expr) {
 /**
  * Check binary comparison expressions for ADC range issues.
  */
-function checkComparisonForADCRange(left, operator, right, adcConfig, diagnostics) {
+function checkComparisonForADCRange(left, operator, right, adcConfig, filePath, diagnostics) {
     // Check if one side is an analog read and the other is a literal
     let analogReadSide = null;
     let literalValue = null;
@@ -83,6 +83,7 @@ function checkComparisonForADCRange(left, operator, right, adcConfig, diagnostic
             severity: 'info',
             message: `Comparison ${comparisonDesc} may never be true. ADC resolution is ${adcConfig.resolution}-bit (max ${adcConfig.maxValue}) on this board.`,
             code: 'adc-range-warning',
+            filePath,
             source: 'adc-range-validation',
         });
     }
@@ -90,7 +91,7 @@ function checkComparisonForADCRange(left, operator, right, adcConfig, diagnostic
 /**
  * Scan an expression for ADC range issues.
  */
-function scanExpressionForADCRange(expr, adcConfig, diagnostics) {
+function scanExpressionForADCRange(expr, adcConfig, filePath, diagnostics) {
     if (!expr || typeof expr !== 'object')
         return;
     // Check binary comparisons
@@ -98,59 +99,59 @@ function scanExpressionForADCRange(expr, adcConfig, diagnostics) {
         const bin = expr;
         const comparisonOps = ['>', '>=', '<', '<=', '===', '==', '!==', '!='];
         if (comparisonOps.includes(bin.operator)) {
-            checkComparisonForADCRange(bin.left, bin.operator, bin.right, adcConfig, diagnostics);
+            checkComparisonForADCRange(bin.left, bin.operator, bin.right, adcConfig, filePath, diagnostics);
         }
         // Recursively scan both sides
-        scanExpressionForADCRange(bin.left, adcConfig, diagnostics);
-        scanExpressionForADCRange(bin.right, adcConfig, diagnostics);
+        scanExpressionForADCRange(bin.left, adcConfig, filePath, diagnostics);
+        scanExpressionForADCRange(bin.right, adcConfig, filePath, diagnostics);
     }
     // Check ternary conditions
     if (expr.kind === 'ternary') {
         const ternary = expr;
-        scanExpressionForADCRange(ternary.condition, adcConfig, diagnostics);
-        scanExpressionForADCRange(ternary.whenTrue, adcConfig, diagnostics);
-        scanExpressionForADCRange(ternary.whenFalse, adcConfig, diagnostics);
+        scanExpressionForADCRange(ternary.condition, adcConfig, filePath, diagnostics);
+        scanExpressionForADCRange(ternary.whenTrue, adcConfig, filePath, diagnostics);
+        scanExpressionForADCRange(ternary.whenFalse, adcConfig, filePath, diagnostics);
     }
     // Check property access
     if (expr.kind === 'property-access') {
         const pa = expr;
-        scanExpressionForADCRange(pa.object, adcConfig, diagnostics);
+        scanExpressionForADCRange(pa.object, adcConfig, filePath, diagnostics);
     }
 }
 /**
  * Scan a statement for ADC range issues.
  */
-function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
+function scanStatementForADCRange(stmt, adcConfig, filePath, diagnostics) {
     if (!stmt || typeof stmt !== 'object')
         return;
     switch (stmt.kind) {
         case 'var_decl': {
             const varDecl = stmt;
             if (varDecl.initializer) {
-                scanExpressionForADCRange(varDecl.initializer, adcConfig, diagnostics);
+                scanExpressionForADCRange(varDecl.initializer, adcConfig, filePath, diagnostics);
             }
             break;
         }
         case 'assign': {
             const assign = stmt;
             if (assign.value) {
-                scanExpressionForADCRange(assign.value, adcConfig, diagnostics);
+                scanExpressionForADCRange(assign.value, adcConfig, filePath, diagnostics);
             }
             break;
         }
         case 'if': {
             const ifStmt = stmt;
             if (ifStmt.condition) {
-                scanExpressionForADCRange(ifStmt.condition, adcConfig, diagnostics);
+                scanExpressionForADCRange(ifStmt.condition, adcConfig, filePath, diagnostics);
             }
             if (ifStmt.thenBranch) {
                 for (const s of ifStmt.thenBranch) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             if (ifStmt.elseBranch) {
                 for (const s of ifStmt.elseBranch) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -158,11 +159,11 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
         case 'while': {
             const whileStmt = stmt;
             if (whileStmt.condition) {
-                scanExpressionForADCRange(whileStmt.condition, adcConfig, diagnostics);
+                scanExpressionForADCRange(whileStmt.condition, adcConfig, filePath, diagnostics);
             }
             if (whileStmt.body) {
                 for (const s of whileStmt.body) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -170,11 +171,11 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
         case 'for': {
             const forStmt = stmt;
             if (forStmt.condition) {
-                scanExpressionForADCRange(forStmt.condition, adcConfig, diagnostics);
+                scanExpressionForADCRange(forStmt.condition, adcConfig, filePath, diagnostics);
             }
             if (forStmt.body) {
                 for (const s of forStmt.body) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -182,7 +183,7 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
         case 'return': {
             const retStmt = stmt;
             if (retStmt.value) {
-                scanExpressionForADCRange(retStmt.value, adcConfig, diagnostics);
+                scanExpressionForADCRange(retStmt.value, adcConfig, filePath, diagnostics);
             }
             break;
         }
@@ -190,7 +191,7 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
             const call = stmt;
             if (call.args) {
                 for (const arg of call.args) {
-                    scanExpressionForADCRange(arg, adcConfig, diagnostics);
+                    scanExpressionForADCRange(arg, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -214,7 +215,7 @@ export function validateADCRange(program, boardConstants) {
     // Scan top-level statements
     if (program.topLevelStatements) {
         for (const stmt of program.topLevelStatements) {
-            scanStatementForADCRange(stmt, adcConfig, diagnostics);
+            scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
         }
     }
     // Scan function bodies
@@ -222,7 +223,7 @@ export function validateADCRange(program, boardConstants) {
         for (const fn of program.functions) {
             if (fn.statements) {
                 for (const stmt of fn.statements) {
-                    scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                    scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
                 }
             }
         }
@@ -234,14 +235,14 @@ export function validateADCRange(program, boardConstants) {
                 for (const method of cls.methods) {
                     if (method.statements) {
                         for (const stmt of method.statements) {
-                            scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                            scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
                         }
                     }
                 }
             }
             if (cls.constructor?.statements) {
                 for (const stmt of cls.constructor.statements) {
-                    scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                    scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
                 }
             }
         }

package/dist/ir/expression-to-ir.js

@@ -264,15 +264,52 @@ export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new
             return `(sizeof(${safeText}) / sizeof(${safeText}[0]))`;
         }
         if (ts.isCallExpression(receiverNode)) {
-            const returnType = ts.isPropertyAccessExpression(receiverNode.expression) && ts.isIdentifier(receiverNode.expression.expression)
-                ? getCurrentIrTypeScope()?.locals.get(receiverNode.expression.expression.text)
-                : undefined;
-            if (returnType === "std::string")
-                return `static_cast<long long>(${safeText}.length())`;
+            // Case B: a HAL buffer-returning method (I2CDevice.readBytes /
+            // SPIDevice.readRegister) used INLINE as a sub-expression — e.g.
+            // `dev.readBytes(0,6).length`. These methods lower to STATEMENTS (a fill
+            // loop), not a single C++ expression, so by the time we get here the
+            // receiver text is already a leaked `for (...) __buf[__i] = Wire.read()`
+            // statement spliced where an expression is required. The buffer also has
+            // no caller-side name to sizeof. Only the var-init form is supported
+            // (`const data = dev.readBytes(...)`); emit a clear diagnostic so the
+            // user gets an actionable error instead of inscrutable broken C++.
+            if (/\bfor\s*\(/.test(safeText) || /__buf|__spi_buf/.test(safeText)) {
+                const calleeName = ts.isPropertyAccessExpression(receiverNode.expression)
+                    ? receiverNode.expression.name.text : "call";
+                diagnostics.push(makeDiagnostic(sourceText, receiverNode.getStart(), `\`${calleeName}(...)\` returns a buffer and cannot be queried inline. Capture it into a variable first (e.g. \`const data = ${calleeName}(...)\`), then use \`data.length\`.`, "error", "TC_BUFFER_INLINE_LENGTH"));
+                return `0 /* ${calleeName}() result must be captured into a variable to use .length */`;
+            }
+            // Resolve the call's RETURN type (not the receiver object's type, which
+            // the previous code incorrectly did). Method calls resolve via the class
+            // registry; free-function calls resolve by scanning the source AST for
+            // the declared return type.
+            const returnType = resolveExprCppType(receiverNode)
+                ?? resolveCallReturnTypeForNullGuard(receiverNode, sourceText);
+            if (returnType) {
+                const parsed = parseCppType(returnType);
+                // std::string → .length(); any STL container (vector/map/set) → .size().
+                if (parsedIsStdString(returnType)) {
+                    return `static_cast<long long>(${safeText}.length())`;
+                }
+                if (parsedIsVector(returnType) || parsedIsMap(returnType) || parsedIsSet(returnType) || isContainer(parsed)) {
+                    return `static_cast<long long>(${safeText}.size())`;
+                }
+                // A raw pointer / decayed-array return (e.g. uint8_t*) carries no size
+                // at the call site — sizeof would yield sizeof(pointer). This is
+                // genuinely un-sizeable inline; surface it rather than emit wrong code.
+                if (parsedIsPointer(returnType) || /\]\s*$/.test(returnType)) {
+                    const calleeName = ts.isPropertyAccessExpression(receiverNode.expression)
+                        ? receiverNode.expression.name.text
+                        : (ts.isIdentifier(receiverNode.expression) ? receiverNode.expression.text : "call");
+                    diagnostics.push(makeDiagnostic(sourceText, receiverNode.getStart(), `Cannot use \`.length\` on \`${calleeName}()\` which returns a pointer (${returnType}); the size is not available at the call site. Capture the buffer into a variable first.`, "error", "TC_LENGTH_ON_POINTER_RETURN"));
+                    return `0 /* .length unavailable on ${returnType} return */`;
+                }
+            }
             // Cast .size() to long long to match the loop-counter type (TS number ->
             // long long). Without this, `i < vec.size()` compares long long vs
             // size_t (unsigned) and g++ -Wall warns -Wsign-compare on every
-            // indexed loop over an array.
+            // indexed loop over an array. (Fallback for unresolvable return types —
+            // historically every call-result .length landed here.)
             return `static_cast<long long>(${safeText}.size())`;
         }
         // Resolve by concrete cppType first so std::string vars render member calls

package/dist/ir/hal/hal-plugins.js

@@ -580,6 +580,16 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
                 return null;
             return { operation: "spi.set_bit_order", bus, order };
         }
+        case "spiReadBuffer": {
+            const bus = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const count = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (bus === null || count === null)
+                return null;
+            // The buffer arg (args[2]) is only a placeholder for type resolution;
+            // the real target is the caller's variable, rewritten from
+            // __HAL_READ_BUF__ by replaceHalReadBufferPlaceholder.
+            return { operation: "spi.read_buffer", bus, count, buffer: "__HAL_READ_BUF__" };
+        }
         // ── UART ──
         case "uartBegin": {
             const port = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);

package/dist/ir/interrupt-analysis.js

@@ -93,9 +93,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 +111,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 +119,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 +129,7 @@ function checkCalleeForUnsafeOp(callee, diagnostics, unsafeOps) {
             severity: unsafe.severity,
             message: `${callee}() ${unsafe.reason}`,
             code: 'interrupt-unsafe-operation',
+            filePath,
             source: 'interrupt-analysis',
         });
         return;
@@ -139,6 +141,7 @@ function checkCalleeForUnsafeOp(callee, diagnostics, unsafeOps) {
                 severity: info.severity,
                 message: `${callee} - ${info.reason}`,
                 code: 'interrupt-unsafe-operation',
+                filePath,
                 source: 'interrupt-analysis',
             });
             return;
@@ -354,6 +357,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 +464,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/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',
                         });
@@ -908,6 +920,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 +943,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 +971,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',
                             });
@@ -991,6 +1006,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 +1039,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 +1089,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 +1145,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',
                 });