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

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',
                 });

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[];

package/dist/ir/pin-alias-conflict.js

@@ -1,5 +1,5 @@
 import { findBoardPinByName } from './board-pin-utils.js';
-export function validatePinAliasConflicts(usage, boardConstants) {
+export function validatePinAliasConflicts(usage, boardConstants, filePath) {
     if (!boardConstants || usage.pinsUsed.size === 0) {
         return [];
     }
@@ -26,6 +26,7 @@ export function validatePinAliasConflicts(usage, boardConstants) {
         diagnostics.push({
             severity: 'warning',
             code: 'pin-alias-conflict',
+            filePath,
             source: 'pin-alias-conflict',
             message: `Pin '${canonicalPinName}' is referenced through multiple names${boardLabel}: ${orderedNames.join(', ')}. These names refer to the same physical pin. Pick one name to keep pin usage and diagnostics unambiguous.`,
         });