c-next 0.1.9 → 0.1.10

package/README.md

@@ -303,36 +303,38 @@ GPIO7.DR_SET[LED_BIT] <- true;    // Generates: GPIO7_DR_SET = (1 << LED_BIT);
 
 ### Slice Assignment for Memory Operations
 
-Multi-byte copying with bounds-checked `memcpy` generation:
+Multi-byte copying with compile-time validated `memcpy` generation (Issue #234):
 
 ```cnx
 u8 buffer[256];
 u32 magic <- 0x12345678;
-u8 length <- 4;
-u32 offset <- 0;
 
-// Copy 4 bytes from value into buffer at offset
-buffer[offset, length] <- magic;
+// Copy 4 bytes from value into buffer at offset 0
+buffer[0, 4] <- magic;
+
+// Named offsets using const variables
+const u32 HEADER_OFFSET <- 0;
+const u32 DATA_OFFSET <- 8;
+buffer[HEADER_OFFSET, 4] <- magic;
+buffer[DATA_OFFSET, 8] <- timestamp;
 ```
 
-Transpiles to runtime bounds-checked code:
+Transpiles to direct memcpy (bounds validated at compile time):
 
 ```c
 uint8_t buffer[256] = {0};
 uint32_t magic = 0x12345678;
-uint8_t length = 4;
-uint32_t offset = 0;
 
-if (offset + length <= sizeof(buffer)) {
-    memcpy(&buffer[offset], &magic, length);
-}
+memcpy(&buffer[0], &magic, 4);
+memcpy(&buffer[8], &timestamp, 8);
 ```
 
 **Key Features:**
 
-- Runtime bounds checking prevents buffer overflows
-- Enables binary serialization and protocol implementation
-- Works with struct fields: `buffer[offset, len] <- config.magic`
+- **Compile-time bounds checking** prevents buffer overflows at compile time
+- Offset and length must be compile-time constants (literals or `const` variables)
+- Silent runtime failures are now compile-time errors
+- Works with struct fields: `buffer[0, 4] <- config.magic`
 - Distinct from bit operations: array slices use `memcpy`, scalar bit ranges use bit manipulation
 
 ### Scopes (ADR-016)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c-next",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "A safer C for embedded systems development. Transpiles to clean, readable C.",
   "main": "src/index.ts",
   "bin": {
@@ -37,7 +37,7 @@
     "coverage:grammar:console": "tsx scripts/grammar-coverage.ts console",
     "unit": "vitest run",
     "unit:watch": "vitest",
-    "test:all": "npm run unit && npm test"
+    "test:all": "npm run unit && npm run test:q"
   },
   "keywords": [
     "c",

package/src/codegen/CodeGenerator.ts

@@ -1131,6 +1131,20 @@ export default class CodeGenerator implements IOrchestrator {
     output.push(" */");
     output.push("");
 
+    // Issue #230: Self-include for extern "C" linkage
+    // When file has public symbols and headers are being generated,
+    // include own header to ensure proper C linkage
+    if (
+      options?.generateHeaders &&
+      this.symbols!.hasPublicSymbols() &&
+      this.sourcePath
+    ) {
+      const basename = this.sourcePath.replace(/^.*[\\/]/, "");
+      const headerName = basename.replace(/\.cnx$|\.cnext$/, ".h");
+      output.push(`#include "${headerName}"`);
+      output.push("");
+    }
+
     // Pass through #include directives from source
     // C-Next does NOT hardcode any libraries - all includes must be explicit
     // ADR-043: Comments before first include become file-level comments
@@ -5603,9 +5617,43 @@ export default class CodeGenerator implements IOrchestrator {
       if (isActualArray || isISRType) {
         // Check for slice assignment: array[offset, length] <- value
         if (exprs.length === 2) {
-          // Slice assignment - generate memcpy with bounds checking
-          const offset = this._generateExpression(exprs[0]);
-          const length = this._generateExpression(exprs[1]);
+          // Issue #234: Slice assignment requires compile-time constant offset and length
+          // to ensure bounds safety at compile time, not runtime
+          const offsetValue = this._tryEvaluateConstant(exprs[0]);
+          const lengthValue = this._tryEvaluateConstant(exprs[1]);
+
+          const line = exprs[0].start?.line ?? arrayAccessCtx.start?.line ?? 0;
+
+          // Issue #234: Reject slice assignment on multi-dimensional arrays
+          // Slice assignment is only valid on 1D arrays (the innermost dimension)
+          // For multi-dimensional arrays like board[4][8], use board[row][offset, length]
+          // (Note: grammar currently doesn't support this - tracked as future work)
+          if (
+            typeInfo?.arrayDimensions &&
+            typeInfo.arrayDimensions.length > 1
+          ) {
+            throw new Error(
+              `${line}:0 Error: Slice assignment is only valid on one-dimensional arrays. ` +
+                `'${name}' has ${typeInfo.arrayDimensions.length} dimensions. ` +
+                `Access the innermost dimension first (e.g., ${name}[index][offset, length]).`,
+            );
+          }
+
+          // Validate offset is compile-time constant
+          if (offsetValue === undefined) {
+            throw new Error(
+              `${line}:0 Error: Slice assignment offset must be a compile-time constant. ` +
+                `Runtime offsets are not allowed to ensure bounds safety.`,
+            );
+          }
+
+          // Validate length is compile-time constant
+          if (lengthValue === undefined) {
+            throw new Error(
+              `${line}:0 Error: Slice assignment length must be a compile-time constant. ` +
+                `Runtime lengths are not allowed to ensure bounds safety.`,
+            );
+          }
 
           // Compound operators not supported for slice assignment
           if (cOp !== "=") {
@@ -5614,22 +5662,50 @@ export default class CodeGenerator implements IOrchestrator {
             );
           }
 
-          // Set flag to include string.h for memcpy
-          this.needsString = true;
-
-          // Generate bounds-checked memcpy
-          // if (offset + length <= sizeof(buffer)) { memcpy(&buffer[offset], &value, length); }
-          // Issue #213: For string parameters, use capacity for bounds checking
-          // since sizeof(char*) gives pointer size, not buffer size
+          // Determine buffer capacity for compile-time bounds check
+          let capacity: number;
           if (
             typeInfo?.isString &&
             typeInfo.stringCapacity &&
             !typeInfo.isArray
           ) {
-            const capacity = typeInfo.stringCapacity + 1;
-            return `if (${offset} + ${length} <= ${capacity}) { memcpy(&${name}[${offset}], &${value}, ${length}); }`;
+            capacity = typeInfo.stringCapacity + 1;
+          } else if (typeInfo?.arrayDimensions && typeInfo.arrayDimensions[0]) {
+            capacity = typeInfo.arrayDimensions[0];
+          } else {
+            // Can't determine capacity at compile time - this shouldn't happen
+            // for properly tracked arrays, but fall back to error
+            throw new Error(
+              `${line}:0 Error: Cannot determine buffer size for '${name}' at compile time.`,
+            );
           }
-          return `if (${offset} + ${length} <= sizeof(${name})) { memcpy(&${name}[${offset}], &${value}, ${length}); }`;
+
+          // Issue #234: Compile-time bounds validation
+          if (offsetValue + lengthValue > capacity) {
+            throw new Error(
+              `${line}:0 Error: Slice assignment out of bounds: ` +
+                `offset(${offsetValue}) + length(${lengthValue}) = ${offsetValue + lengthValue} ` +
+                `exceeds buffer capacity(${capacity}) for '${name}'.`,
+            );
+          }
+
+          if (offsetValue < 0) {
+            throw new Error(
+              `${line}:0 Error: Slice assignment offset cannot be negative: ${offsetValue}`,
+            );
+          }
+
+          if (lengthValue <= 0) {
+            throw new Error(
+              `${line}:0 Error: Slice assignment length must be positive: ${lengthValue}`,
+            );
+          }
+
+          // Set flag to include string.h for memcpy
+          this.needsString = true;
+
+          // Generate memcpy without runtime bounds check (already validated at compile time)
+          return `memcpy(&${name}[${offsetValue}], &${value}, ${lengthValue});`;
         }
 
         // Normal array element assignment (single index)

package/src/codegen/SymbolCollector.ts

@@ -5,6 +5,7 @@
  * Issue #60: Extracted from CodeGenerator for better separation of concerns.
  */
 
+import { ParserRuleContext } from "antlr4ng";
 import * as Parser from "../parser/grammar/CNextParser";
 import BITMAP_SIZE from "./types/BITMAP_SIZE";
 import BITMAP_BACKING_TYPE from "./types/BITMAP_BACKING_TYPE";
@@ -58,6 +59,16 @@ class SymbolCollector {
   // For scope context during collection (used by getTypeName)
   private _collectingScope: string | null = null;
 
+  // Issue #232: Track which scope variables are used in which functions
+  // Maps "ScopeName_varName" -> Set of function names that use it
+  private _scopeVariableUsage: Map<string, Set<string>> = new Map();
+
+  // Store function declarations for usage analysis
+  private _scopeFunctionBodies: Map<
+    string,
+    Parser.FunctionDeclarationContext[]
+  > = new Map();
+
   // Readonly public accessors
   get knownScopes(): ReadonlySet<string> {
     return this._knownScopes;
@@ -143,6 +154,30 @@ class SymbolCollector {
     return this._registerMemberCTypes;
   }
 
+  // Issue #232: Getter for scope variable usage analysis
+  get scopeVariableUsage(): ReadonlyMap<string, Set<string>> {
+    return this._scopeVariableUsage;
+  }
+
+  /**
+   * Issue #232: Check if a scope variable is used in only one function.
+   * Returns the function name if single-function, null otherwise.
+   */
+  getSingleFunctionForVariable(
+    scopeName: string,
+    varName: string,
+  ): string | null {
+    const fullVarName = `${scopeName}_${varName}`;
+    const usedIn = this._scopeVariableUsage.get(fullVarName);
+
+    if (!usedIn || usedIn.size !== 1) {
+      return null;
+    }
+
+    // Extract the single element from the Set (we know it exists since size === 1)
+    return [...usedIn][0];
+  }
+
   /**
    * Create a new SymbolCollector and collect all symbols from the parse tree.
    * @param tree The C-Next program parse tree
@@ -259,6 +294,12 @@ class SymbolCollector {
         const funcName = funcDecl.IDENTIFIER().getText();
         members.add(funcName);
         memberVisibility.set(funcName, visibility);
+
+        // Issue #232: Store function for usage analysis
+        if (!this._scopeFunctionBodies.has(name)) {
+          this._scopeFunctionBodies.set(name, []);
+        }
+        this._scopeFunctionBodies.get(name)!.push(funcDecl);
       }
 
       // ADR-017: Collect enums declared inside scopes
@@ -322,10 +363,144 @@ class SymbolCollector {
     this._scopeMembers.set(name, members);
     this._scopeMemberVisibility.set(name, memberVisibility);
 
+    // Issue #232: Analyze which functions use which scope variables
+    this.analyzeScopeVariableUsage(name, members);
+
     // Clear collecting scope
     this._collectingScope = null;
   }
 
+  /**
+   * Issue #232: Analyze which scope variables are used in which functions.
+   * Issue #233: Also track which variables are WRITTEN to (for reset injection).
+   * This enables making single-function variables local instead of file-scope.
+   */
+  private analyzeScopeVariableUsage(
+    scopeName: string,
+    members: Set<string>,
+  ): void {
+    const functions = this._scopeFunctionBodies.get(scopeName);
+    if (!functions) return;
+
+    // Collect all variable names (non-function members)
+    const variableNames = new Set<string>();
+    for (const member of members) {
+      // Check if this is a function by seeing if we have it in the function list
+      const isFuncMember = functions.some(
+        (f) => f.IDENTIFIER().getText() === member,
+      );
+      if (!isFuncMember) {
+        variableNames.add(member);
+      }
+    }
+
+    // For each function, find which variables it references and writes
+    for (const funcDecl of functions) {
+      const funcName = funcDecl.IDENTIFIER().getText();
+      const block = funcDecl.block();
+      if (!block) continue;
+
+      // Find all this.varName references in the function body (reads + writes)
+      const usedVars = this.findScopedMemberReferences(block, variableNames);
+
+      // Record usage
+      for (const varName of usedVars) {
+        const fullVarName = `${scopeName}_${varName}`;
+        if (!this._scopeVariableUsage.has(fullVarName)) {
+          this._scopeVariableUsage.set(fullVarName, new Set());
+        }
+        this._scopeVariableUsage.get(fullVarName)!.add(funcName);
+      }
+    }
+  }
+
+  /**
+   * Issue #232: Recursively find all this.varName references in an AST node.
+   * Returns a set of variable names that are referenced.
+   *
+   * `this.temp` parses as PostfixExpressionContext with:
+   * - primaryExpression: 'this'
+   * - postfixOp[0]: '.temp'
+   */
+  private findScopedMemberReferences(
+    node: ParserRuleContext,
+    variableNames: Set<string>,
+  ): Set<string> {
+    const found = new Set<string>();
+
+    // Check if this node is a PostfixExpression with 'this' primary
+    if (node instanceof Parser.PostfixExpressionContext) {
+      const primary = node.primaryExpression();
+      if (primary && primary.getText() === "this") {
+        // Get the first postfixOp - it should be .memberName
+        const ops = node.postfixOp();
+        if (ops.length > 0) {
+          const firstOp = ops[0];
+          const identifier = firstOp.IDENTIFIER();
+          if (identifier) {
+            const memberName = identifier.getText();
+            if (variableNames.has(memberName)) {
+              found.add(memberName);
+            }
+          }
+        }
+      }
+    }
+
+    // Also check thisAccess, thisMemberAccess, thisArrayAccess in lvalue context
+    if (node instanceof Parser.ThisAccessContext) {
+      const identifier = node.IDENTIFIER();
+      if (identifier) {
+        const memberName = identifier.getText();
+        if (variableNames.has(memberName)) {
+          found.add(memberName);
+        }
+      }
+    }
+
+    if (node instanceof Parser.ThisMemberAccessContext) {
+      // First IDENTIFIER after 'this.'
+      const identifiers = node.IDENTIFIER();
+      if (identifiers.length > 0) {
+        const firstMember = identifiers[0].getText();
+        if (variableNames.has(firstMember)) {
+          found.add(firstMember);
+        }
+      }
+    }
+
+    if (node instanceof Parser.ThisArrayAccessContext) {
+      // First IDENTIFIER after 'this.'
+      const identifiers = node.IDENTIFIER();
+      if (identifiers.length > 0) {
+        const firstMember = identifiers[0].getText();
+        if (variableNames.has(firstMember)) {
+          found.add(firstMember);
+        }
+      }
+    }
+
+    // Recursively check all children using .children property.
+    // Type assertion needed because antlr4ng's ParserRuleContext doesn't expose
+    // .children in its public type definitions, but it exists at runtime.
+    const children = (node as { children?: unknown[] }).children;
+    if (children) {
+      for (const child of children) {
+        if (child instanceof ParserRuleContext) {
+          const childFound = this.findScopedMemberReferences(
+            child,
+            variableNames,
+          );
+          for (const v of childFound) {
+            found.add(v);
+          }
+        }
+      }
+    }
+
+    return found;
+  }
+
   /**
    * Collect struct declarations and track field types
    */
@@ -539,6 +714,21 @@ class SymbolCollector {
     }
     return value;
   }
+
+  /**
+   * Issue #230: Check if any scope members are public (exported)
+   * Used to determine if a self-include header is needed for extern "C" linkage
+   */
+  hasPublicSymbols(): boolean {
+    for (const [, visibilityMap] of this._scopeMemberVisibility) {
+      for (const [, visibility] of visibilityMap) {
+        if (visibility === "public") {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
 }
 
 export default SymbolCollector;

package/src/codegen/generators/ISymbolInfo.ts

@@ -91,6 +91,23 @@ interface ISymbolInfo {
 
   /** Register member C types: "reg_member" -> C type (e.g., "uint32_t") */
   readonly registerMemberCTypes: ReadonlyMap<string, string>;
+
+  // === Issue #232: Scope Variable Usage Analysis ===
+
+  /**
+   * Scope variable usage: "Scope_varName" -> Set of function names that use it.
+   * Used to determine if a variable is single-function (can be local).
+   */
+  readonly scopeVariableUsage: ReadonlyMap<string, ReadonlySet<string>>;
+
+  /**
+   * Check if a scope variable is used in only one function.
+   * Returns the function name if single-function, null otherwise.
+   */
+  getSingleFunctionForVariable(
+    scopeName: string,
+    varName: string,
+  ): string | null;
 }
 
 export default ISymbolInfo;

package/src/codegen/generators/declarationGenerators/ScopeGenerator.ts

@@ -30,6 +30,15 @@ import generateScopedRegister from "./ScopedRegisterGenerator";
  * - Visibility control (private -> static, public -> extern)
  * - Organization without runtime overhead
  */
+/**
+ * Issue #232: Information about a single-function variable
+ */
+interface ISingleFunctionVar {
+  varDecl: Parser.VariableDeclarationContext;
+  targetFunction: string;
+  isPrivate: boolean;
+}
+
 const generateScope: TGeneratorFn<Parser.ScopeDeclarationContext> = (
   node: Parser.ScopeDeclarationContext,
   input: IGeneratorInput,
@@ -44,6 +53,10 @@ const generateScope: TGeneratorFn<Parser.ScopeDeclarationContext> = (
   const lines: string[] = [];
   lines.push(`/* Scope: ${name} */`);
 
+  // Issue #232: First pass - identify single-function variables
+  // Maps functionName -> list of variable declarations that are local to it
+  const localVarsForFunction = new Map<string, ISingleFunctionVar[]>();
+
   for (const member of node.scopeMember()) {
     const visibility = member.visibilityModifier()?.getText() || "private";
     const isPrivate = visibility === "private";
@@ -51,8 +64,30 @@ const generateScope: TGeneratorFn<Parser.ScopeDeclarationContext> = (
     // Handle variable declarations
     if (member.variableDeclaration()) {
       const varDecl = member.variableDeclaration()!;
-      const type = orchestrator.generateType(varDecl.type());
       const varName = varDecl.IDENTIFIER().getText();
+
+      // Issue #232: Check if this PRIVATE variable is used in only one function
+      // PUBLIC variables must stay file-scope because they can be accessed from outside
+      const targetFunc = isPrivate
+        ? input.symbols?.getSingleFunctionForVariable(name, varName)
+        : null;
+
+      if (targetFunc) {
+        // Single-function private variable - emit as local, not file-scope
+        if (!localVarsForFunction.has(targetFunc)) {
+          localVarsForFunction.set(targetFunc, []);
+        }
+        localVarsForFunction.get(targetFunc)!.push({
+          varDecl,
+          targetFunction: targetFunc,
+          isPrivate,
+        });
+        // Don't emit file-scope declaration
+        continue;
+      }
+
+      // Multi-function or unused variable - emit at file scope (original behavior)
+      const type = orchestrator.generateType(varDecl.type());
       const fullName = `${name}_${varName}`;
       const prefix = isPrivate ? "static " : "";
 
@@ -99,7 +134,53 @@ const generateScope: TGeneratorFn<Parser.ScopeDeclarationContext> = (
         ? orchestrator.generateParameterList(funcDecl.parameterList()!)
         : "void";
 
-      const body = orchestrator.generateBlock(funcDecl.block());
+      let body = orchestrator.generateBlock(funcDecl.block());
+
+      // Issue #232: Inject local variable declarations for single-function vars
+      const localVars = localVarsForFunction.get(funcName);
+      if (localVars && localVars.length > 0) {
+        // Generate local variable declarations
+        const localDecls: string[] = [];
+        for (const { varDecl } of localVars) {
+          const varType = orchestrator.generateType(varDecl.type());
+          const varName = varDecl.IDENTIFIER().getText();
+          const varFullName = `${name}_${varName}`;
+
+          const arrayDims = varDecl.arrayDimension();
+          const isArray = arrayDims.length > 0;
+          let decl = `    ${varType} ${varFullName}`;
+          if (isArray) {
+            decl += orchestrator.generateArrayDimensions(arrayDims);
+          }
+          // ADR-045: Add string capacity dimension for string arrays
+          if (varDecl.type().stringType()) {
+            const stringCtx = varDecl.type().stringType()!;
+            const intLiteral = stringCtx.INTEGER_LITERAL();
+            if (intLiteral) {
+              const capacity = parseInt(intLiteral.getText(), 10);
+              decl += `[${capacity + 1}]`;
+            }
+          }
+          if (varDecl.expression()) {
+            decl += ` = ${orchestrator.generateExpression(varDecl.expression()!)}`;
+          } else {
+            decl += ` = ${orchestrator.getZeroInitializer(varDecl.type(), isArray)}`;
+          }
+          localDecls.push(decl + ";");
+        }
+
+        // Inject after opening brace: { -> {\n    local_var = init;
+        // Body format is typically "{\n    ...statements...\n}"
+        const openBraceIdx = body.indexOf("{");
+        if (openBraceIdx !== -1) {
+          const afterBrace = body.substring(openBraceIdx + 1);
+          body =
+            body.substring(0, openBraceIdx + 1) +
+            "\n" +
+            localDecls.join("\n") +
+            afterBrace;
+        }
+      }
 
       // ADR-016: Exit function body context
       orchestrator.exitFunctionBody();

package/src/codegen/generators/expressions/BinaryExprGenerator.ts

@@ -8,6 +8,8 @@
  * - Bitwise: |, ^, &
  * - Shift: <<, >> with validation
  * - Arithmetic: +, -, *, /, %
+ *
+ * Issue #235: Includes constant folding for compile-time constant expressions.
  */
 import * as Parser from "../../../parser/grammar/CNextParser";
 import IGeneratorOutput from "../IGeneratorOutput";
@@ -16,6 +18,89 @@ import IGeneratorInput from "../IGeneratorInput";
 import IGeneratorState from "../IGeneratorState";
 import IOrchestrator from "../IOrchestrator";
 
+/**
+ * Issue #235: Try to parse a string as a numeric constant.
+ * Returns the numeric value if it's a simple integer literal, undefined otherwise.
+ * Handles decimal, hex (0x), and binary (0b) formats.
+ */
+const tryParseNumericLiteral = (code: string): number | undefined => {
+  const trimmed = code.trim();
+
+  // Decimal integer (including negative)
+  if (/^-?\d+$/.test(trimmed)) {
+    return parseInt(trimmed, 10);
+  }
+
+  // Hex literal
+  if (/^0[xX][0-9a-fA-F]+$/.test(trimmed)) {
+    return parseInt(trimmed, 16);
+  }
+
+  // Binary literal
+  if (/^0[bB][01]+$/.test(trimmed)) {
+    return parseInt(trimmed.substring(2), 2);
+  }
+
+  return undefined;
+};
+
+/**
+ * Issue #235: Evaluate a constant arithmetic expression.
+ * Returns the result if all operands are numeric and evaluation succeeds,
+ * undefined otherwise (falls back to non-folded code).
+ */
+const tryFoldConstants = (
+  operandCodes: string[],
+  operators: string[],
+): number | undefined => {
+  // Parse all operands as numbers
+  const values = operandCodes.map(tryParseNumericLiteral);
+
+  // If any operand is not a constant, we can't fold
+  if (values.some((v) => v === undefined)) {
+    return undefined;
+  }
+
+  // Evaluate left-to-right with the operators
+  let result = values[0] as number;
+  for (let i = 0; i < operators.length; i++) {
+    const op = operators[i];
+    const rightValue = values[i + 1] as number;
+
+    switch (op) {
+      case "*":
+        result = result * rightValue;
+        break;
+      case "/":
+        // Avoid division by zero - let C compiler handle it
+        if (rightValue === 0) {
+          return undefined;
+        }
+        // Integer division (truncate toward zero like C)
+        result = Math.trunc(result / rightValue);
+        break;
+      case "%":
+        // Avoid modulo by zero
+        if (rightValue === 0) {
+          return undefined;
+        }
+        result = result % rightValue;
+        break;
+      case "+":
+        result = result + rightValue;
+        break;
+      case "-":
+        result = result - rightValue;
+        break;
+      default:
+        // Unknown operator - don't fold
+        return undefined;
+    }
+  }
+
+  return result;
+};
+
 /**
  * Generate C code for an OR expression (lowest precedence binary op).
  */
@@ -320,6 +405,7 @@ const generateShiftExpr = (
 
 /**
  * Generate C code for an additive expression.
+ * Issue #235: Includes constant folding for compile-time constant expressions.
  */
 const generateAdditiveExpr = (
   node: Parser.AdditiveExpressionContext,
@@ -336,25 +422,25 @@ const generateAdditiveExpr = (
 
   // Issue #152: Extract operators in order from parse tree children
   const operators = orchestrator.getOperatorsFromChildren(node);
-  const firstResult = generateMultiplicativeExpr(
-    exprs[0],
-    input,
-    state,
-    orchestrator,
+
+  // Generate code for all operands
+  const operandResults = exprs.map((expr) =>
+    generateMultiplicativeExpr(expr, input, state, orchestrator),
   );
-  effects.push(...firstResult.effects);
-  let result = firstResult.code;
+  const operandCodes = operandResults.map((r) => r.code);
+  operandResults.forEach((r) => effects.push(...r.effects));
 
-  for (let i = 1; i < exprs.length; i++) {
+  // Issue #235: Try constant folding for compile-time constant expressions
+  const foldedResult = tryFoldConstants(operandCodes, operators);
+  if (foldedResult !== undefined) {
+    return { code: String(foldedResult), effects };
+  }
+
+  // Fall back to standard code generation
+  let result = operandCodes[0];
+  for (let i = 1; i < operandCodes.length; i++) {
     const op = operators[i - 1] || "+";
-    const exprResult = generateMultiplicativeExpr(
-      exprs[i],
-      input,
-      state,
-      orchestrator,
-    );
-    effects.push(...exprResult.effects);
-    result += ` ${op} ${exprResult.code}`;
+    result += ` ${op} ${operandCodes[i]}`;
   }
 
   return { code: result, effects };
@@ -363,6 +449,7 @@ const generateAdditiveExpr = (
 /**
  * Generate C code for a multiplicative expression.
  * This is the bottom of the binary chain - delegates to unary via orchestrator.
+ * Issue #235: Includes constant folding for compile-time constant expressions.
  */
 const generateMultiplicativeExpr = (
   node: Parser.MultiplicativeExpressionContext,
@@ -380,11 +467,23 @@ const generateMultiplicativeExpr = (
 
   // Issue #152: Extract operators in order from parse tree children
   const operators = orchestrator.getOperatorsFromChildren(node);
-  let result = orchestrator.generateUnaryExpr(exprs[0]);
 
-  for (let i = 1; i < exprs.length; i++) {
+  // Generate code for all operands
+  const operandCodes = exprs.map((expr) =>
+    orchestrator.generateUnaryExpr(expr),
+  );
+
+  // Issue #235: Try constant folding for compile-time constant expressions
+  const foldedResult = tryFoldConstants(operandCodes, operators);
+  if (foldedResult !== undefined) {
+    return { code: String(foldedResult), effects: [] };
+  }
+
+  // Fall back to standard code generation
+  let result = operandCodes[0];
+  for (let i = 1; i < operandCodes.length; i++) {
     const op = operators[i - 1] || "*";
-    result += ` ${op} ${orchestrator.generateUnaryExpr(exprs[i])}`;
+    result += ` ${op} ${operandCodes[i]}`;
   }
 
   return { code: result, effects: [] };

package/src/codegen/generators/support/HelperGenerator.ts

@@ -1,6 +1,10 @@
 /**
  * Helper function generators for overflow-safe arithmetic and safe division.
  * Extracted from CodeGenerator.ts as part of ADR-053 A5.
+ *
+ * Portability note: Uses __builtin_add_overflow, __builtin_sub_overflow, and
+ * __builtin_mul_overflow intrinsics (GCC 5+, Clang 3.4+). C-Next targets embedded
+ * systems using arm-none-eabi-gcc, so these are available. MSVC is not supported.
  */
 import TYPE_MAP from "../../types/TYPE_MAP";
 import WIDER_TYPE_MAP from "../../types/WIDER_TYPE_MAP";
@@ -33,10 +37,13 @@ function generateSingleHelper(
   switch (operation) {
     case "add":
       if (isUnsigned) {
-        // Unsigned addition: use wider type for b to prevent truncation (Issue #94)
+        // Issue #231: Hybrid approach - check wide operand first, then use builtin
+        // Issue #94: Wide operand check prevents truncation issues
         return `static inline ${cType} cnx_clamp_add_${cnxType}(${cType} a, ${widerType} b) {
-    if (b > ${maxValue} - a) return ${maxValue};
-    return a + (${cType})b;
+    if (b > (${widerType})(${maxValue} - a)) return ${maxValue};
+    ${cType} result;
+    if (__builtin_add_overflow(a, (${cType})b, &result)) return ${maxValue};
+    return result;
 }`;
       } else if (useWiderArithmetic) {
         // Signed addition: compute in wider type, then clamp (Issue #94)
@@ -58,11 +65,14 @@ function generateSingleHelper(
 
     case "sub":
       if (isUnsigned) {
-        // Unsigned subtraction: use wider type for b to prevent truncation (Issue #94)
-        // Cast a to wider type for comparison to handle b > type max
+        // Issue #231: Hybrid approach - check wide operand first, then use builtin
+        // Issue #94: Wide operand check prevents truncation issues
+        // Use > (not >=) since b == a produces valid result 0 via the builtin path
         return `static inline ${cType} cnx_clamp_sub_${cnxType}(${cType} a, ${widerType} b) {
-    if (b >= (${widerType})a) return 0;
-    return a - (${cType})b;
+    if (b > (${widerType})a) return 0;
+    ${cType} result;
+    if (__builtin_sub_overflow(a, (${cType})b, &result)) return 0;
+    return result;
 }`;
       } else if (useWiderArithmetic) {
         // Signed subtraction: compute in wider type, then clamp (Issue #94)
@@ -83,10 +93,13 @@ function generateSingleHelper(
 
     case "mul":
       if (isUnsigned) {
-        // Unsigned multiplication: use wider type for b to prevent truncation (Issue #94)
+        // Issue #231: Hybrid approach - check wide operand first, then use builtin
+        // Issue #94: Wide operand check prevents truncation issues
         return `static inline ${cType} cnx_clamp_mul_${cnxType}(${cType} a, ${widerType} b) {
     if (b != 0 && a > ${maxValue} / b) return ${maxValue};
-    return a * (${cType})b;
+    ${cType} result;
+    if (__builtin_mul_overflow(a, (${cType})b, &result)) return ${maxValue};
+    return result;
 }`;
       } else if (useWiderArithmetic) {
         // Signed multiplication: compute in wider type, then clamp (Issue #94)
@@ -144,13 +157,19 @@ function generateDebugHelper(
   switch (operation) {
     case "add":
       if (isUnsigned) {
-        // Use wider type for b to prevent truncation (Issue #94)
+        // Issue #231: Hybrid approach - check wide operand first, then use builtin
+        // Issue #94: Wide operand check prevents truncation issues
         return `static inline ${cType} cnx_clamp_add_${cnxType}(${cType} a, ${widerType} b) {
-    if (b > ${maxValue} - a) {
+    if (b > (${widerType})(${maxValue} - a)) {
         fprintf(stderr, "PANIC: Integer overflow in ${cnxType} ${opName}\\n");
         abort();
     }
-    return a + (${cType})b;
+    ${cType} result;
+    if (__builtin_add_overflow(a, (${cType})b, &result)) {
+        fprintf(stderr, "PANIC: Integer overflow in ${cnxType} ${opName}\\n");
+        abort();
+    }
+    return result;
 }`;
       } else if (useWiderArithmetic) {
         // Signed addition: compute in wider type, check bounds (Issue #94)
@@ -175,13 +194,20 @@ function generateDebugHelper(
 
     case "sub":
       if (isUnsigned) {
-        // Use wider type for b to prevent truncation (Issue #94)
+        // Issue #231: Hybrid approach - check wide operand first, then use builtin
+        // Issue #94: Wide operand check prevents truncation issues
+        // Use > (not >=) since b == a produces valid result 0 via the builtin path
         return `static inline ${cType} cnx_clamp_sub_${cnxType}(${cType} a, ${widerType} b) {
-    if (b >= (${widerType})a) {
+    if (b > (${widerType})a) {
         fprintf(stderr, "PANIC: Integer underflow in ${cnxType} ${opName}\\n");
         abort();
     }
-    return a - (${cType})b;
+    ${cType} result;
+    if (__builtin_sub_overflow(a, (${cType})b, &result)) {
+        fprintf(stderr, "PANIC: Integer underflow in ${cnxType} ${opName}\\n");
+        abort();
+    }
+    return result;
 }`;
       } else if (useWiderArithmetic) {
         // Signed subtraction: compute in wider type, check bounds (Issue #94)
@@ -206,13 +232,19 @@ function generateDebugHelper(
 
     case "mul":
       if (isUnsigned) {
-        // Use wider type for b to prevent truncation (Issue #94)
+        // Issue #231: Hybrid approach - check wide operand first, then use builtin
+        // Issue #94: Wide operand check prevents truncation issues
         return `static inline ${cType} cnx_clamp_mul_${cnxType}(${cType} a, ${widerType} b) {
     if (b != 0 && a > ${maxValue} / b) {
         fprintf(stderr, "PANIC: Integer overflow in ${cnxType} ${opName}\\n");
         abort();
     }
-    return a * (${cType})b;
+    ${cType} result;
+    if (__builtin_mul_overflow(a, (${cType})b, &result)) {
+        fprintf(stderr, "PANIC: Integer overflow in ${cnxType} ${opName}\\n");
+        abort();
+    }
+    return result;
 }`;
       } else if (useWiderArithmetic) {
         // Signed multiplication: compute in wider type, check bounds (Issue #94)

package/src/codegen/types/ICodeGeneratorOptions.ts

@@ -8,6 +8,11 @@ interface ICodeGeneratorOptions {
   target?: string;
   /** ADR-010: Source file path for validating includes */
   sourcePath?: string;
+  /**
+   * Issue #230: When true, emit self-include for extern "C" linkage.
+   * Only set this when headers will actually be generated alongside the implementation.
+   */
+  generateHeaders?: boolean;
 }
 
 export default ICodeGeneratorOptions;

package/src/pipeline/Pipeline.ts

@@ -565,6 +565,8 @@ class Pipeline {
         {
           debugMode: this.config.debugMode,
           target: this.config.target,
+          sourcePath: file.path, // Issue #230: For self-include header generation
+          generateHeaders: this.config.generateHeaders, // Issue #230: Enable self-include when headers are generated
         },
       );
 
@@ -724,6 +726,7 @@ class Pipeline {
       workingDir?: string; // For resolving relative #includes
       includeDirs?: string[]; // Additional include paths
       sourcePath?: string; // Optional source path for error messages
+      generateHeaders?: boolean; // Issue #230: Enable self-include for extern "C" tests
     },
   ): Promise<IFileResult> {
     const workingDir = options?.workingDir ?? process.cwd();
@@ -868,6 +871,8 @@ class Pipeline {
         {
           debugMode: this.config.debugMode,
           target: this.config.target,
+          sourcePath, // Issue #230: For self-include header generation
+          generateHeaders: options?.generateHeaders, // Issue #230: Enable self-include for extern "C" tests
         },
       );