c-next 0.2.9 → 0.2.11

package/dist/index.js

@@ -10,7 +10,7 @@ import { hideBin } from "yargs/helpers";
 // package.json
 var package_default = {
   name: "c-next",
-  version: "0.2.9",
+  version: "0.2.11",
   description: "A safer C for embedded systems development. Transpiles to clean, readable C.",
   packageManager: "npm@11.9.0",
   type: "module",
@@ -109966,6 +109966,26 @@ var SymbolTable = class {
    * In C, they must be referred to as 'struct Name', not just 'Name'
    */
   needsStructKeyword = /* @__PURE__ */ new Set();
+  /**
+   * Issue #948: Track typedef names that alias incomplete (forward-declared) struct types.
+   * These are "opaque" types that can only be used as pointers.
+   */
+  opaqueTypes = /* @__PURE__ */ new Set();
+  /**
+   * Issue #958: Track typedef struct type names with their source files.
+   * Maps typeName -> sourceFile. Used for scope variables which should be pointers
+   * when the struct definition comes from a different file than the typedef.
+   * If definition is in the same file as typedef, the entry is removed (value type).
+   * If definition is in a different file, the entry remains (pointer type).
+   */
+  typedefStructTypes = /* @__PURE__ */ new Map();
+  /**
+   * Issue #948: Track struct tag -> typedef name relationships.
+   * When a typedef declares an alias for a struct tag (e.g., typedef struct _foo foo_t),
+   * we record structTagAliases["_foo"] = "foo_t". This allows us to unmark the typedef
+   * as opaque when the full struct definition is later found.
+   */
+  structTagAliases = /* @__PURE__ */ new Map();
   /**
    * Issue #208: Track enum backing type bit widths
    * C++14 typed enums: enum Name : uint8_t { ... } have explicit bit widths
@@ -110594,6 +110614,116 @@ Rename the C-Next symbol to resolve.`
     }
   }
   // ========================================================================
+  // Opaque Type Tracking (Issue #948)
+  // ========================================================================
+  /**
+   * Issue #948: Mark a typedef as aliasing an opaque (forward-declared) struct type.
+   * @param typeName Typedef name (e.g., "widget_t")
+   */
+  markOpaqueType(typeName) {
+    this.opaqueTypes.add(typeName);
+  }
+  /**
+   * Issue #948: Unmark a typedef when full struct definition is found.
+   * Handles edge case: typedef before definition.
+   * @param typeName Typedef name
+   */
+  unmarkOpaqueType(typeName) {
+    this.opaqueTypes.delete(typeName);
+  }
+  /**
+   * Issue #948: Check if a typedef aliases an opaque struct type.
+   * @param typeName Typedef name
+   * @returns true if the type is opaque (forward-declared)
+   */
+  isOpaqueType(typeName) {
+    return this.opaqueTypes.has(typeName);
+  }
+  /**
+   * Issue #948: Get all opaque type names for cache serialization.
+   * @returns Array of opaque typedef names
+   */
+  getAllOpaqueTypes() {
+    return Array.from(this.opaqueTypes);
+  }
+  /**
+   * Issue #948: Restore opaque types from cache.
+   * @param typeNames Array of opaque typedef names
+   */
+  restoreOpaqueTypes(typeNames) {
+    for (const name of typeNames) {
+      this.opaqueTypes.add(name);
+    }
+  }
+  /**
+   * Issue #948: Register a struct tag -> typedef name relationship.
+   * Called when processing: typedef struct _foo foo_t;
+   * This allows unmarking foo_t when struct _foo { ... } is later defined.
+   * @param structTag The struct tag name (e.g., "_foo")
+   * @param typedefName The typedef alias name (e.g., "foo_t")
+   */
+  registerStructTagAlias(structTag, typedefName) {
+    this.structTagAliases.set(structTag, typedefName);
+  }
+  /**
+   * Issue #948: Get the typedef alias for a struct tag, if any.
+   * @param structTag The struct tag name
+   * @returns The typedef alias name, or undefined if none registered
+   */
+  getStructTagAlias(structTag) {
+    return this.structTagAliases.get(structTag);
+  }
+  // ========================================================================
+  // Issue #958: Typedef Struct Type Tracking
+  // ========================================================================
+  /**
+   * Issue #958: Mark a typedef as aliasing a struct type.
+   * Records the source file to enable same-file vs cross-file distinction.
+   * @param typedefName The typedef name (e.g., "widget_t")
+   * @param sourceFile The file where the typedef was declared
+   */
+  markTypedefStructType(typedefName, sourceFile) {
+    this.typedefStructTypes.set(typedefName, sourceFile);
+  }
+  /**
+   * Issue #958: Unmark a typedef struct type when full definition is found.
+   * Only unmarks if the definition is in the SAME file as the typedef declaration.
+   * Cross-file definitions keep the typedef marked (pointer semantics).
+   * @param typeName The typedef name to unmark
+   * @param sourceFile The file where the definition was found
+   */
+  unmarkTypedefStructType(typeName, sourceFile) {
+    const typedefFile = this.typedefStructTypes.get(typeName);
+    if (typedefFile === sourceFile) {
+      this.typedefStructTypes.delete(typeName);
+    }
+  }
+  /**
+   * Issue #958: Check if a typedef aliases a struct type.
+   * Used for scope variables which should be pointers for external struct types.
+   * @param typeName The type name to check
+   * @returns true if this is a typedef'd struct type from C headers
+   */
+  isTypedefStructType(typeName) {
+    return this.typedefStructTypes.has(typeName);
+  }
+  /**
+   * Issue #958: Get all typedef struct types for cache serialization.
+   * @returns Map entries as [typeName, sourceFile] pairs
+   */
+  getAllTypedefStructTypes() {
+    return Array.from(this.typedefStructTypes.entries());
+  }
+  /**
+   * Issue #958: Restore typedef struct types from cache.
+   * @param entries Array of [typeName, sourceFile] pairs
+   */
+  restoreTypedefStructTypes(entries) {
+    for (const [name, sourceFile] of entries) {
+      this.typedefStructTypes.set(name, sourceFile);
+    }
+  }
+  // ========================================================================
   // Enum Bit Width Tracking
   // ========================================================================
   /**
@@ -110710,7 +110840,10 @@ Rename the C-Next symbol to resolve.`
     this.cppSymbolsByFile.clear();
     this.structFields.clear();
     this.needsStructKeyword.clear();
+    this.opaqueTypes.clear();
+    this.structTagAliases.clear();
     this.enumBitWidth.clear();
+    this.typedefStructTypes.clear();
   }
 };
 var SymbolTable_default = SymbolTable;
@@ -110871,6 +111004,16 @@ var CodeGenState = class {
   /** Issue #473: IRQ wrappers for critical sections */
   static needsIrqWrappers = false;
   // ===========================================================================
+  // OPAQUE TYPE SCOPE VARIABLES (Issue #948)
+  // ===========================================================================
+  /**
+   * Tracks scope variables with opaque (forward-declared) struct types.
+   * These are generated as pointers with NULL initialization and should
+   * be passed directly (not with &) since they're already pointers.
+   * Maps qualified name (e.g., "MyScope_widget") to true.
+   */
+  static opaqueScopeVariables = /* @__PURE__ */ new Set();
+  // ===========================================================================
   // C++ MODE STATE (Issue #250)
   // ===========================================================================
   /** Use temp vars instead of compound literals */
@@ -110954,6 +111097,7 @@ var CodeGenState = class {
     this.tempVarCounter = 0;
     this.pendingCppClassAssignments = [];
     this.selfIncludeAdded = false;
+    this.opaqueScopeVariables = /* @__PURE__ */ new Set();
     this.sourcePath = null;
     this.includeDirs = [];
     this.inputs = [];
@@ -111043,6 +111187,22 @@ var CodeGenState = class {
   static isKnownRegister(name) {
     return this.symbols?.knownRegisters.has(name) ?? false;
   }
+  /**
+   * Issue #948: Check if a type name is an opaque (forward-declared) struct type.
+   * Opaque types are incomplete types that can only be used as pointers.
+   * Example: `typedef struct _widget_t widget_t;` without a body makes `widget_t` opaque.
+   */
+  static isOpaqueType(typeName) {
+    return this.symbols?.opaqueTypes.has(typeName) ?? false;
+  }
+  /**
+   * Issue #958: Check if a type name is an external typedef struct type.
+   * External typedef struct types should use pointer semantics for scope variables.
+   * Unlike isOpaqueType, this returns true for both forward-declared and complete structs.
+   */
+  static isTypedefStructType(typeName) {
+    return this.symbolTable?.isTypedefStructType(typeName) ?? false;
+  }
   /**
    * Get type info for a variable.
    * Checks local typeRegistry first, then falls back to SymbolTable
@@ -111482,6 +111642,28 @@ var CodeGenState = class {
     return this.floatShadowCurrent.has(name);
   }
   // ===========================================================================
+  // OPAQUE SCOPE VARIABLE HELPERS (Issue #948)
+  // ===========================================================================
+  /**
+   * Mark a scope variable as having an opaque (forward-declared) struct type.
+   * These are generated as pointers with NULL initialization.
+   *
+   * @param qualifiedName - The fully qualified variable name (e.g., "MyScope_widget")
+   */
+  static markOpaqueScopeVariable(qualifiedName) {
+    this.opaqueScopeVariables.add(qualifiedName);
+  }
+  /**
+   * Check if a scope variable has an opaque type (and is thus a pointer).
+   * Used during access generation to determine if & prefix is needed.
+   *
+   * @param qualifiedName - The fully qualified variable name (e.g., "MyScope_widget")
+   * @returns true if this is an opaque scope variable (already a pointer)
+   */
+  static isOpaqueScopeVariable(qualifiedName) {
+    return this.opaqueScopeVariables.has(qualifiedName);
+  }
+  // ===========================================================================
   // C++ MODE HELPERS
   // ===========================================================================
   /**
@@ -113191,6 +113373,12 @@ var TypeResolver2 = class _TypeResolver {
     if (floatMatch) {
       return "f" + floatMatch[1];
     }
+    if (/^\d+$/.test(text) || /^0[xXbBoO][\da-fA-F]+$/.test(text)) {
+      return "int";
+    }
+    if (/^\d*\.\d+([eE][+-]?\d+)?$/.test(text) || /^\d+[eE][+-]?\d+$/.test(text)) {
+      return "f64";
+    }
     return null;
   }
   /**
@@ -114450,6 +114638,229 @@ var GeneratorRegistry = class {
   }
 };
 
+// src/transpiler/output/codegen/helpers/CppModeHelper.ts
+var CppModeHelper = class {
+  /**
+   * Get address-of expression for struct parameter passing.
+   * C mode: `&expr` (pass pointer to struct)
+   * C++ mode: `expr` (pass reference directly)
+   *
+   * @param expr - The expression to potentially wrap
+   * @returns The expression with address-of operator in C mode
+   */
+  static maybeAddressOf(expr) {
+    return CodeGenState.cppMode ? expr : `&${expr}`;
+  }
+  /**
+   * Get dereference expression for struct parameter access.
+   * C mode: `(*expr)` (dereference pointer)
+   * C++ mode: `expr` (reference can be used directly)
+   *
+   * @param expr - The expression to potentially dereference
+   * @returns The expression with dereference in C mode
+   */
+  static maybeDereference(expr) {
+    return CodeGenState.cppMode ? expr : `(*${expr})`;
+  }
+  /**
+   * Get the type modifier for struct parameter declarations.
+   * C mode: `*` (pointer type)
+   * C++ mode: `&` (reference type)
+   *
+   * @returns The type modifier character
+   */
+  static refOrPtr() {
+    return CodeGenState.cppMode ? "&" : "*";
+  }
+  /**
+   * Get the member access separator for struct parameters.
+   * C mode: `->` (pointer member access)
+   * C++ mode: `.` (reference member access)
+   *
+   * @returns The member access separator
+   */
+  static memberSeparator() {
+    return CodeGenState.cppMode ? "." : "->";
+  }
+  /**
+   * Get NULL literal for the current mode.
+   * C mode: `NULL`
+   * C++ mode: `nullptr`
+   *
+   * @returns The null pointer literal
+   */
+  static nullLiteral() {
+    return CodeGenState.cppMode ? "nullptr" : "NULL";
+  }
+  /**
+   * Generate a cast expression for the current mode.
+   * C mode: `(type)expr`
+   * C++ mode: `static_cast<type>(expr)`
+   *
+   * @param type - The target type
+   * @param expr - The expression to cast
+   * @returns The cast expression
+   */
+  static cast(type, expr) {
+    return CodeGenState.cppMode ? `static_cast<${type}>(${expr})` : `(${type})${expr}`;
+  }
+  /**
+   * Generate a reinterpret cast expression for the current mode.
+   * C mode: `(type)expr`
+   * C++ mode: `reinterpret_cast<type>(expr)`
+   *
+   * @param type - The target type
+   * @param expr - The expression to cast
+   * @returns The cast expression
+   */
+  static reinterpretCast(type, expr) {
+    return CodeGenState.cppMode ? `reinterpret_cast<${type}>(${expr})` : `(${type})${expr}`;
+  }
+  /**
+   * Check if we're in C++ mode.
+   *
+   * @returns True if generating C++ code
+   */
+  static isCppMode() {
+    return CodeGenState.cppMode;
+  }
+};
+var CppModeHelper_default = CppModeHelper;
+
+// src/transpiler/output/codegen/helpers/NarrowingCastHelper.ts
+var EXTENDED_TYPE_WIDTH = {
+  ...TYPE_WIDTH_default,
+  int: 32
+  // C's int after promotion
+};
+var PROMOTED_TO_INT = /* @__PURE__ */ new Set(["u8", "i8", "u16", "i16", "bool"]);
+var FLOAT_TYPES2 = /* @__PURE__ */ new Set(["f32", "f64", "float", "double"]);
+var INTEGER_TYPES2 = /* @__PURE__ */ new Set([
+  "u8",
+  "u16",
+  "u32",
+  "u64",
+  "i8",
+  "i16",
+  "i32",
+  "i64",
+  "uint8_t",
+  "uint16_t",
+  "uint32_t",
+  "uint64_t",
+  "int8_t",
+  "int16_t",
+  "int32_t",
+  "int64_t",
+  "int"
+]);
+var NarrowingCastHelper = class _NarrowingCastHelper {
+  /**
+   * Check if a cast is needed for MISRA 10.3 compliance.
+   * Returns true if:
+   * - Source is wider than target (narrowing)
+   * - Source and target are different essential type categories
+   *
+   * @param sourceType - Type of the expression (C-Next type or "int" for promoted)
+   * @param targetType - Type of the target variable (C-Next type)
+   */
+  static needsCast(sourceType, targetType) {
+    if (sourceType === targetType) {
+      return false;
+    }
+    if (targetType === "bool" && sourceType !== "bool") {
+      return true;
+    }
+    const sourceWidth = EXTENDED_TYPE_WIDTH[sourceType];
+    const targetWidth = EXTENDED_TYPE_WIDTH[targetType];
+    if (sourceWidth === void 0 || targetWidth === void 0) {
+      return false;
+    }
+    return sourceWidth > targetWidth;
+  }
+  /**
+   * Wrap expression with cast if needed for MISRA 10.3 compliance.
+   *
+   * @param expr - The generated C expression
+   * @param sourceType - Type of the expression (C-Next type or "int")
+   * @param targetType - Type of the assignment target (C-Next type)
+   * @returns Expression with cast wrapper if needed, or original expression
+   */
+  static wrap(expr, sourceType, targetType) {
+    if (!_NarrowingCastHelper.needsCast(sourceType, targetType)) {
+      return expr;
+    }
+    if (targetType === "bool") {
+      return `((${expr}) != 0U)`;
+    }
+    const cType = TYPE_MAP_default[targetType] ?? targetType;
+    return CppModeHelper_default.cast(cType, expr);
+  }
+  /**
+   * Determine the result type of C integer promotion for a given type.
+   *
+   * In C, operations on types smaller than int are promoted:
+   * - u8, i8, u16, i16, bool -> int (32-bit)
+   * - u32, i32, u64, i64 -> no promotion (already >= int width)
+   *
+   * @param baseType - The C-Next type of the operand
+   * @returns "int" for promoted types, or the original type
+   */
+  static getPromotedType(baseType) {
+    if (PROMOTED_TO_INT.has(baseType)) {
+      return "int";
+    }
+    return baseType;
+  }
+  /**
+   * Check if a type is a floating-point type.
+   */
+  static isFloatType(typeName) {
+    return FLOAT_TYPES2.has(typeName);
+  }
+  /**
+   * Check if a type is an integer type.
+   */
+  static isIntegerType(typeName) {
+    return INTEGER_TYPES2.has(typeName);
+  }
+  /**
+   * Check if conversion between source and target is a cross-type-category conversion.
+   * MISRA 10.3 requires explicit casts for different essential type categories.
+   */
+  static isCrossTypeCategoryConversion(sourceType, targetType) {
+    const sourceIsFloat = _NarrowingCastHelper.isFloatType(sourceType);
+    const targetIsFloat = _NarrowingCastHelper.isFloatType(targetType);
+    const sourceIsInt = _NarrowingCastHelper.isIntegerType(sourceType);
+    const targetIsInt = _NarrowingCastHelper.isIntegerType(targetType);
+    return sourceIsFloat && targetIsInt || sourceIsInt && targetIsFloat;
+  }
+  /**
+   * Get the appropriate C float type for a C-Next type.
+   */
+  static getCFloatType(typeName) {
+    if (typeName === "f32" || typeName === "float") {
+      return "float";
+    }
+    if (typeName === "f64" || typeName === "double") {
+      return "double";
+    }
+    return "double";
+  }
+  /**
+   * Wrap int-to-float conversion with explicit cast for MISRA 10.3.
+   *
+   * @param expr - The integer expression
+   * @param targetType - The float target type (f32/f64)
+   * @returns Expression with cast
+   */
+  static wrapIntToFloat(expr, targetType) {
+    const floatType = _NarrowingCastHelper.getCFloatType(targetType);
+    return CppModeHelper_default.cast(floatType, expr);
+  }
+};
+var NarrowingCastHelper_default = NarrowingCastHelper;
+
 // src/transpiler/output/codegen/generators/expressions/LiteralGenerator.ts
 var UNSIGNED_64_TYPES = /* @__PURE__ */ new Set(["u64", "uint64_t"]);
 var UNSIGNED_TYPES3 = /* @__PURE__ */ new Set([
@@ -114490,6 +114901,18 @@ var generateLiteral = (node, _input, state, _orchestrator) => {
     effects.push({ type: "include", header: "stdbool" });
     return { code: literalText, effects };
   }
+  if (literalText.startsWith("'")) {
+    const expectedType2 = state?.expectedType;
+    if (expectedType2) {
+      const wrappedCode = NarrowingCastHelper_default.wrap(
+        literalText,
+        "int",
+        expectedType2
+      );
+      return { code: wrappedCode, effects };
+    }
+    return { code: literalText, effects };
+  }
   if (/[fF]32$/.test(literalText)) {
     literalText = literalText.replace(/[fF]32$/, "f");
     return { code: literalText, effects };
@@ -114851,96 +115274,9 @@ var binaryExprGenerators = {
 };
 var BinaryExprGenerator_default = binaryExprGenerators;
 
-// src/transpiler/output/codegen/helpers/CppModeHelper.ts
-var CppModeHelper = class {
-  /**
-   * Get address-of expression for struct parameter passing.
-   * C mode: `&expr` (pass pointer to struct)
-   * C++ mode: `expr` (pass reference directly)
-   *
-   * @param expr - The expression to potentially wrap
-   * @returns The expression with address-of operator in C mode
-   */
-  static maybeAddressOf(expr) {
-    return CodeGenState.cppMode ? expr : `&${expr}`;
-  }
-  /**
-   * Get dereference expression for struct parameter access.
-   * C mode: `(*expr)` (dereference pointer)
-   * C++ mode: `expr` (reference can be used directly)
-   *
-   * @param expr - The expression to potentially dereference
-   * @returns The expression with dereference in C mode
-   */
-  static maybeDereference(expr) {
-    return CodeGenState.cppMode ? expr : `(*${expr})`;
-  }
-  /**
-   * Get the type modifier for struct parameter declarations.
-   * C mode: `*` (pointer type)
-   * C++ mode: `&` (reference type)
-   *
-   * @returns The type modifier character
-   */
-  static refOrPtr() {
-    return CodeGenState.cppMode ? "&" : "*";
-  }
-  /**
-   * Get the member access separator for struct parameters.
-   * C mode: `->` (pointer member access)
-   * C++ mode: `.` (reference member access)
-   *
-   * @returns The member access separator
-   */
-  static memberSeparator() {
-    return CodeGenState.cppMode ? "." : "->";
-  }
-  /**
-   * Get NULL literal for the current mode.
-   * C mode: `NULL`
-   * C++ mode: `nullptr`
-   *
-   * @returns The null pointer literal
-   */
-  static nullLiteral() {
-    return CodeGenState.cppMode ? "nullptr" : "NULL";
-  }
-  /**
-   * Generate a cast expression for the current mode.
-   * C mode: `(type)expr`
-   * C++ mode: `static_cast<type>(expr)`
-   *
-   * @param type - The target type
-   * @param expr - The expression to cast
-   * @returns The cast expression
-   */
-  static cast(type, expr) {
-    return CodeGenState.cppMode ? `static_cast<${type}>(${expr})` : `(${type})${expr}`;
-  }
-  /**
-   * Generate a reinterpret cast expression for the current mode.
-   * C mode: `(type)expr`
-   * C++ mode: `reinterpret_cast<type>(expr)`
-   *
-   * @param type - The target type
-   * @param expr - The expression to cast
-   * @returns The cast expression
-   */
-  static reinterpretCast(type, expr) {
-    return CodeGenState.cppMode ? `reinterpret_cast<${type}>(${expr})` : `(${type})${expr}`;
-  }
-  /**
-   * Check if we're in C++ mode.
-   *
-   * @returns True if generating C++ code
-   */
-  static isCppMode() {
-    return CodeGenState.cppMode;
-  }
-};
-var CppModeHelper_default = CppModeHelper;
-
 // src/transpiler/output/codegen/generators/expressions/UnaryExprGenerator.ts
+var INT32_MIN_LITERAL = "2147483648";
+var INT64_MIN_LITERAL = "9223372036854775808";
 var generateUnaryExpr = (node, _input, _state, orchestrator) => {
   if (node.postfixExpression()) {
     return {
@@ -114951,7 +115287,18 @@ var generateUnaryExpr = (node, _input, _state, orchestrator) => {
   const inner = orchestrator.generateUnaryExpr(node.unaryExpression());
   const text = node.getText();
   if (text.startsWith("!")) return { code: `!${inner}`, effects: [] };
-  if (text.startsWith("-")) return { code: `-${inner}`, effects: [] };
+  if (text.startsWith("-")) {
+    const effects = [];
+    if (inner === INT32_MIN_LITERAL) {
+      effects.push({ type: "include", header: "limits" });
+      return { code: "(int32_t)INT32_MIN", effects };
+    }
+    if (inner === INT64_MIN_LITERAL || inner === INT64_MIN_LITERAL + "LL") {
+      effects.push({ type: "include", header: "limits" });
+      return { code: "(int64_t)INT64_MIN", effects };
+    }
+    return { code: `-${inner}`, effects };
+  }
   if (text.startsWith("~")) {
     const innerType = TypeResolver_default2.getUnaryExpressionType(
       node.unaryExpression()
@@ -115014,15 +115361,18 @@ var generateSizeProperty = (typeInfo) => {
   throw new Error(`Error: .size is only available on string types`);
 };
 var generateBitmapFieldAccess = (result, fieldInfo) => {
+  let expr;
   if (fieldInfo.width === 1) {
-    return { code: `((${result} >> ${fieldInfo.offset}) & 1)`, effects: [] };
+    expr = `((${result} >> ${fieldInfo.offset}) & 1)`;
   } else {
     const mask = (1 << fieldInfo.width) - 1;
-    return {
-      code: `((${result} >> ${fieldInfo.offset}) & 0x${mask.toString(16).toUpperCase()})`,
-      effects: []
-    };
+    expr = `((${result} >> ${fieldInfo.offset}) & 0x${mask.toString(16).toUpperCase()})`;
+  }
+  const targetType = CodeGenState.expectedType;
+  if (targetType) {
+    expr = NarrowingCastHelper_default.wrap(expr, "int", targetType);
   }
+  return { code: expr, effects: [] };
 };
 var accessGenerators = {
   generateCapacityProperty,
@@ -115199,7 +115549,8 @@ var _generateCFunctionArg = (e, targetParam, input, orchestrator) => {
   if (typeInfo?.isPointer) {
     isPointerVariable = true;
   }
-  const needsAddressOf = argType && !argType.endsWith("*") && !argCode.startsWith("&") && !targetParam.isArray && !isPointerVariable && (orchestrator.isStructType(argType) || _parameterExpectsAddressOf(targetParam.baseType, argType, orchestrator));
+  const isOpaqueScopeVar = CodeGenState.isOpaqueScopeVariable(argCode);
+  const needsAddressOf = argType && !argType.endsWith("*") && !argCode.startsWith("&") && !targetParam.isArray && !isPointerVariable && !isOpaqueScopeVar && (orchestrator.isStructType(argType) || _parameterExpectsAddressOf(targetParam.baseType, argType, orchestrator));
   const finalArgCode = needsAddressOf ? `&${argCode}` : argCode;
   return wrapWithCppEnumCast(
     finalArgCode,
@@ -115337,7 +115688,7 @@ var trackPassThroughModifications = (funcName, argExprs, orchestrator) => {
 var CallExprGenerator_default = generateFunctionCall;
 
 // src/utils/TypeCheckUtils.ts
-var INTEGER_TYPES2 = [
+var INTEGER_TYPES3 = [
   "u8",
   "u16",
   "u32",
@@ -115349,7 +115700,7 @@ var INTEGER_TYPES2 = [
 ];
 var UNSIGNED_TYPES4 = ["u8", "u16", "u32", "u64"];
 var SIGNED_TYPES3 = ["i8", "i16", "i32", "i64"];
-var FLOAT_TYPES2 = ["f32", "f64"];
+var FLOAT_TYPES3 = ["f32", "f64"];
 var STANDARD_WIDTHS = [8, 16, 32];
 var TypeCheckUtils = class {
   /**
@@ -115359,7 +115710,7 @@ var TypeCheckUtils = class {
    * @returns true if it's u8, u16, u32, u64, i8, i16, i32, or i64
    */
   static isInteger(typeName) {
-    return INTEGER_TYPES2.includes(typeName);
+    return INTEGER_TYPES3.includes(typeName);
   }
   /**
    * Check if a type name is an unsigned integer type.
@@ -115386,7 +115737,7 @@ var TypeCheckUtils = class {
    * @returns true if it's f32 or f64
    */
   static isFloat(typeName) {
-    return FLOAT_TYPES2.includes(typeName);
+    return FLOAT_TYPES3.includes(typeName);
   }
   /**
    * Check if a type name is a string type (string<N>).
@@ -116618,7 +116969,12 @@ var handleSingleSubscript = (ctx, expr, input, orchestrator, output) => {
   const isRegisterAccess = checkRegisterAccess(ctx, input);
   const identifierTypeInfo = getIdentifierTypeInfo(ctx, input);
   if (isRegisterAccess) {
-    output.result = index === "0" || index === "0U" ? `((${ctx.result}) & 1)` : `((${ctx.result} >> ${index}) & 1)`;
+    let expr2 = index === "0" || index === "0U" ? `((${ctx.result}) & 1)` : `((${ctx.result} >> ${index}) & 1)`;
+    const targetType = CodeGenState.expectedType;
+    if (targetType) {
+      expr2 = NarrowingCastHelper_default.wrap(expr2, "int", targetType);
+    }
+    output.result = expr2;
     return output;
   }
   if (ctx.currentMemberIsArray) {
@@ -116632,7 +116988,12 @@ var handleSingleSubscript = (ctx, expr, input, orchestrator, output) => {
   }
   const isPrimitiveIntMember = ctx.currentStructType && TypeCheckUtils_default.isInteger(ctx.currentStructType);
   if (isPrimitiveIntMember) {
-    output.result = index === "0" || index === "0U" ? `((${ctx.result}) & 1)` : `((${ctx.result} >> ${index}) & 1)`;
+    let expr2 = index === "0" || index === "0U" ? `((${ctx.result}) & 1)` : `((${ctx.result} >> ${index}) & 1)`;
+    const targetType = CodeGenState.expectedType;
+    if (targetType) {
+      expr2 = NarrowingCastHelper_default.wrap(expr2, "int", targetType);
+    }
+    output.result = expr2;
     output.currentStructType = void 0;
     return output;
   }
@@ -116691,7 +117052,12 @@ var handleDefaultSubscript = (ctx, index, typeInfo, output) => {
     isRegisterAccess: false
   });
   if (subscriptKind === "bit_single") {
-    output.result = index === "0" || index === "0U" ? `((${ctx.result}) & 1)` : `((${ctx.result} >> ${index}) & 1)`;
+    let expr = index === "0" || index === "0U" ? `((${ctx.result}) & 1)` : `((${ctx.result} >> ${index}) & 1)`;
+    const targetType = CodeGenState.expectedType;
+    if (targetType) {
+      expr = NarrowingCastHelper_default.wrap(expr, "int", targetType);
+    }
+    output.result = expr;
   } else {
     output.result = `${ctx.result}[${index}]`;
   }
@@ -116718,10 +117084,24 @@ var handleBitRangeSubscript = (ctx, exprs, input, state, orchestrator, effects,
     );
   } else {
     const mask = orchestrator.generateBitMask(width);
+    let expr;
     if (start === "0" || start === "0U") {
-      output.result = `((${ctx.result}) & ${mask})`;
+      expr = `((${ctx.result}) & ${mask})`;
+    } else {
+      expr = `((${ctx.result} >> ${start}) & ${mask})`;
+    }
+    const targetType = CodeGenState.expectedType;
+    if (targetType && ctx.primaryTypeInfo?.baseType) {
+      const promotedSourceType = NarrowingCastHelper_default.getPromotedType(
+        ctx.primaryTypeInfo.baseType
+      );
+      output.result = NarrowingCastHelper_default.wrap(
+        expr,
+        promotedSourceType,
+        targetType
+      );
     } else {
-      output.result = `((${ctx.result} >> ${start}) & ${mask})`;
+      output.result = expr;
     }
   }
   return output;
@@ -117031,6 +117411,21 @@ var generateCriticalStatement = (node, _input, _state, orchestrator) => {
 };
 var CriticalGenerator_default = generateCriticalStatement;
 
+// src/transpiler/output/codegen/types/COMPOUND_TO_BINARY.ts
+var COMPOUND_TO_BINARY = {
+  "+=": "+",
+  "-=": "-",
+  "*=": "*",
+  "/=": "/",
+  "%=": "%",
+  "&=": "&",
+  "|=": "|",
+  "^=": "^",
+  "<<=": "<<",
+  ">>=": ">>"
+};
+var COMPOUND_TO_BINARY_default = COMPOUND_TO_BINARY;
+
 // src/transpiler/output/codegen/generators/statements/AtomicGenerator.ts
 var TYPE_MAP2 = {
   u8: "uint8_t",
@@ -117058,18 +117453,6 @@ var STREX_MAP = {
   u32: "__STREXW",
   i32: "__STREXW"
 };
-var SIMPLE_OP_MAP = {
-  "+=": "+",
-  "-=": "-",
-  "*=": "*",
-  "/=": "/",
-  "%=": "%",
-  "&=": "&",
-  "|=": "|",
-  "^=": "^",
-  "<<=": "<<",
-  ">>=": ">>"
-};
 var CLAMP_OP_MAP = {
   "+=": "add",
   "-=": "sub",
@@ -117083,7 +117466,7 @@ function getClampHelperOp(cOp, typeInfo) {
 }
 function generateInnerAtomicOp(cOp, value, typeInfo) {
   const effects = [];
-  const simpleOp = SIMPLE_OP_MAP[cOp] || "+";
+  const simpleOp = COMPOUND_TO_BINARY_default[cOp] || "+";
   const helperOp = getClampHelperOp(cOp, typeInfo);
   if (helperOp) {
     effects.push({
@@ -117748,8 +118131,14 @@ function generateRegularVariable(varDecl, varName, scopeName, isPrivate, orchest
   const arrayDims = varDecl.arrayDimension();
   const arrayTypeCtx = varDecl.type().arrayType?.() ?? null;
   const isArray = arrayDims.length > 0 || arrayTypeCtx !== null;
-  const type = orchestrator.generateType(varDecl.type());
+  let type = orchestrator.generateType(varDecl.type());
   const fullName = QualifiedNameGenerator_default.forMember(scopeName, varName);
+  const isOpaque = orchestrator.isOpaqueType(type);
+  const isExternalStruct = orchestrator.isTypedefStructType(type);
+  if (isOpaque || isExternalStruct) {
+    type = `${type}*`;
+    orchestrator.markOpaqueScopeVariable(fullName);
+  }
   const constPrefix = isConst ? "const " : "";
   const prefix = isPrivate ? "static " : "";
   let decl = `${prefix}${constPrefix}${type} ${fullName}`;
@@ -117761,7 +118150,11 @@ function generateRegularVariable(varDecl, varName, scopeName, isPrivate, orchest
     decl += orchestrator.generateArrayDimensions(arrayDims);
   }
   decl += ArrayDimensionUtils_default.generateStringCapacityDim(varDecl.type());
-  decl += generateInitializer(varDecl, isArray, orchestrator);
+  if (isOpaque || isExternalStruct) {
+    decl += " = NULL";
+  } else {
+    decl += generateInitializer(varDecl, isArray, orchestrator);
+  }
   return decl + ";";
 }
 function generateScopeFunction(funcDecl, scopeName, isPrivate, orchestrator) {
@@ -117973,6 +118366,7 @@ function generateScopedStructInline(node, scopeName, _input, orchestrator) {
 var ScopeGenerator_default = generateScope;
 
 // src/utils/BitUtils.ts
+var NARROW_TYPES = /* @__PURE__ */ new Set(["u8", "u16", "i8", "i16"]);
 var BitUtils = class _BitUtils {
   /**
    * Convert a boolean expression to an unsigned integer (0U or 1U).
@@ -118063,6 +118457,21 @@ var BitUtils = class _BitUtils {
   static formatHex(value) {
     return `0x${value.toString(16).toUpperCase()}U`;
   }
+  /**
+   * Wrap an expression with a cast for MISRA 10.3 compliance on narrow types.
+   * Bit manipulation operations promote to int; this casts back to the target type.
+   *
+   * @param expr - The expression to potentially wrap
+   * @param targetType - The C-Next type name (e.g., "u8", "u16")
+   * @returns Expression wrapped with cast if narrow, or original expression
+   */
+  static wrapNarrowCast(expr, targetType) {
+    if (!targetType || !NARROW_TYPES.has(targetType)) {
+      return expr;
+    }
+    const cType = TYPE_MAP_default[targetType] ?? targetType;
+    return `(${cType})(${expr})`;
+  }
   /**
    * Generate code to read a single bit from a value.
    * Pattern: ((target >> offset) & 1)
@@ -118109,7 +118518,8 @@ var BitUtils = class _BitUtils {
     const is64Bit = targetType === "u64" || targetType === "i64";
     const one = is64Bit ? "1ULL" : "1U";
     const valueShift = is64Bit ? `((uint64_t)${intValue} << ${offset})` : `(${intValue} << ${offset})`;
-    return `${target} = (${target} & ~(${one} << ${offset})) | ${valueShift};`;
+    const rhs = `(${target} & ~(${one} << ${offset})) | ${valueShift}`;
+    return `${target} = ${_BitUtils.wrapNarrowCast(rhs, targetType)};`;
   }
   /**
    * Generate read-modify-write code for multi-bit assignment.
@@ -118124,7 +118534,8 @@ var BitUtils = class _BitUtils {
    */
   static multiBitWrite(target, offset, width, value, targetType) {
     const mask = _BitUtils.generateMask(width, targetType);
-    return `${target} = (${target} & ~(${mask} << ${offset})) | ((${value} & ${mask}) << ${offset});`;
+    const rhs = `(${target} & ~(${mask} << ${offset})) | ((${value} & ${mask}) << ${offset})`;
+    return `${target} = ${_BitUtils.wrapNarrowCast(rhs, targetType)};`;
   }
   /**
    * Generate write-only register code for single bit assignment.
@@ -118140,7 +118551,8 @@ var BitUtils = class _BitUtils {
   static writeOnlySingleBit(target, offset, value, targetType) {
     const intValue = _BitUtils.boolToInt(value);
     const castPrefix = targetType === "u64" || targetType === "i64" ? "(uint64_t)" : "";
-    return `${target} = (${castPrefix}${intValue} << ${offset});`;
+    const rhs = `(${castPrefix}${intValue} << ${offset})`;
+    return `${target} = ${_BitUtils.wrapNarrowCast(rhs, targetType)};`;
   }
   /**
    * Generate write-only register code for multi-bit assignment.
@@ -118156,7 +118568,8 @@ var BitUtils = class _BitUtils {
    */
   static writeOnlyMultiBit(target, offset, width, value, targetType) {
     const mask = _BitUtils.generateMask(width, targetType);
-    return `${target} = ((${value} & ${mask}) << ${offset});`;
+    const rhs = `((${value} & ${mask}) << ${offset})`;
+    return `${target} = ${_BitUtils.wrapNarrowCast(rhs, targetType)};`;
   }
 };
 var BitUtils_default = BitUtils;
@@ -120717,8 +121130,10 @@ var AssignmentKind = /* @__PURE__ */ ((AssignmentKind2) => {
   AssignmentKind2[AssignmentKind2["GLOBAL_REGISTER_BIT"] = 28] = "GLOBAL_REGISTER_BIT";
   AssignmentKind2[AssignmentKind2["THIS_MEMBER"] = 29] = "THIS_MEMBER";
   AssignmentKind2[AssignmentKind2["THIS_ARRAY"] = 30] = "THIS_ARRAY";
-  AssignmentKind2[AssignmentKind2["MEMBER_CHAIN"] = 31] = "MEMBER_CHAIN";
-  AssignmentKind2[AssignmentKind2["SIMPLE"] = 32] = "SIMPLE";
+  AssignmentKind2[AssignmentKind2["THIS_BIT"] = 31] = "THIS_BIT";
+  AssignmentKind2[AssignmentKind2["THIS_BIT_RANGE"] = 32] = "THIS_BIT_RANGE";
+  AssignmentKind2[AssignmentKind2["MEMBER_CHAIN"] = 33] = "MEMBER_CHAIN";
+  AssignmentKind2[AssignmentKind2["SIMPLE"] = 34] = "SIMPLE";
   return AssignmentKind2;
 })(AssignmentKind || {});
 var AssignmentKind_default = AssignmentKind;
@@ -120760,8 +121175,55 @@ var handlers_default = AssignmentHandlerRegistry;
 function gen() {
   return CodeGenState.generator;
 }
+function tryHandleCompoundNarrowingCast(ctx, target) {
+  if (!ctx.isCompound || !ctx.firstIdTypeInfo) {
+    return null;
+  }
+  const baseType = ctx.firstIdTypeInfo.baseType;
+  const promotedType = NarrowingCastHelper_default.getPromotedType(baseType);
+  if (promotedType !== "int" || baseType === "int") {
+    return null;
+  }
+  const binaryOp = COMPOUND_TO_BINARY_default[ctx.cOp];
+  if (!binaryOp) {
+    return null;
+  }
+  const cType = TYPE_MAP_default[baseType] ?? baseType;
+  const expr = `(${target} ${binaryOp} ${ctx.generatedValue})`;
+  const castExpr = CppModeHelper_default.cast(cType, expr);
+  return `${target} = ${castExpr};`;
+}
+function tryHandleIntToFloatConversion(ctx, target) {
+  if (ctx.isCompound || !ctx.firstIdTypeInfo || !ctx.valueCtx) {
+    return null;
+  }
+  const targetType = ctx.firstIdTypeInfo.baseType;
+  const valueType = TypeResolver_default2.getExpressionType(ctx.valueCtx);
+  if (!valueType) {
+    return null;
+  }
+  if (!NarrowingCastHelper_default.isCrossTypeCategoryConversion(valueType, targetType)) {
+    return null;
+  }
+  if (!NarrowingCastHelper_default.isIntegerType(valueType) || !NarrowingCastHelper_default.isFloatType(targetType)) {
+    return null;
+  }
+  const castedValue = NarrowingCastHelper_default.wrapIntToFloat(
+    ctx.generatedValue,
+    targetType
+  );
+  return `${target} ${ctx.cOp} ${castedValue};`;
+}
 function handleSimpleAssignment(ctx) {
   const target = gen().generateAssignmentTarget(ctx.targetCtx);
+  const compoundResult = tryHandleCompoundNarrowingCast(ctx, target);
+  if (compoundResult) {
+    return compoundResult;
+  }
+  const conversionResult = tryHandleIntToFloatConversion(ctx, target);
+  if (conversionResult) {
+    return conversionResult;
+  }
   return `${target} ${ctx.cOp} ${ctx.generatedValue};`;
 }
 var SimpleHandler_default = handleSimpleAssignment;
@@ -121414,6 +121876,8 @@ function handleStructChainBitRange(ctx) {
 var bitAccessHandlers = [
   [AssignmentKind_default.INTEGER_BIT, handleIntegerBit],
   [AssignmentKind_default.INTEGER_BIT_RANGE, handleIntegerBitRange],
+  [AssignmentKind_default.THIS_BIT, handleIntegerBit],
+  [AssignmentKind_default.THIS_BIT_RANGE, handleIntegerBitRange],
   [AssignmentKind_default.STRUCT_MEMBER_BIT, handleStructMemberBit],
   [AssignmentKind_default.ARRAY_ELEMENT_BIT, handleArrayElementBit],
   [AssignmentKind_default.STRUCT_CHAIN_BIT_RANGE, handleStructChainBitRange]
@@ -121965,14 +122429,28 @@ var AssignmentClassifier = class _AssignmentClassifier {
     return AssignmentKind_default.THIS_MEMBER;
   }
   /**
-   * Classify this.reg[bit] / this.arr[i] patterns with array access.
+   * Classify this.reg[bit] / this.arr[i] / this.flags[3] patterns with array access.
+   * Issue #954: Uses SubscriptClassifier to distinguish array vs bit access.
    */
   static classifyThisWithArrayAccess(ctx, scopedRegName) {
     if (CodeGenState.symbols.knownRegisters.has(scopedRegName)) {
       const hasBitRange = ctx.postfixOps.some((op) => op.COMMA() !== null);
       return hasBitRange ? AssignmentKind_default.SCOPED_REGISTER_BIT_RANGE : AssignmentKind_default.SCOPED_REGISTER_BIT;
     }
-    return AssignmentKind_default.THIS_ARRAY;
+    const typeInfo = CodeGenState.getVariableTypeInfo(scopedRegName);
+    const subscriptKind = SubscriptClassifier_default.classify({
+      typeInfo: typeInfo ?? null,
+      subscriptCount: ctx.lastSubscriptExprCount,
+      isRegisterAccess: false
+    });
+    switch (subscriptKind) {
+      case "bit_single":
+        return AssignmentKind_default.THIS_BIT;
+      case "bit_range":
+        return AssignmentKind_default.THIS_BIT_RANGE;
+      default:
+        return AssignmentKind_default.THIS_ARRAY;
+    }
   }
   /**
    * Classify simple array/bit access (no prefix, no member access).
@@ -122045,7 +122523,8 @@ var AssignmentClassifier = class _AssignmentClassifier {
     if (isGlobalAtomic) {
       return AssignmentKind_default.ATOMIC_RMW;
     }
-    if (typeInfo.overflowBehavior === "clamp" && TypeCheckUtils_default.isInteger(typeInfo.baseType)) {
+    const ARITHMETIC_COMPOUND_OPS = /* @__PURE__ */ new Set(["+=", "-=", "*="]);
+    if (typeInfo.overflowBehavior === "clamp" && TypeCheckUtils_default.isInteger(typeInfo.baseType) && ARITHMETIC_COMPOUND_OPS.has(ctx.cOp)) {
       return AssignmentKind_default.OVERFLOW_CLAMP;
     }
     return null;
@@ -124446,10 +124925,20 @@ ${assignments}`;
     _VariableDeclHelper.validateIntegerInitializer(ctx, typeName, {
       getExpressionType: callbacks.getExpressionType
     });
-    return CodeGenState.withExpectedType(
-      typeName,
-      () => `${decl} = ${callbacks.generateExpression(ctx.expression())}`
-    );
+    return CodeGenState.withExpectedType(typeName, () => {
+      let exprCode = callbacks.generateExpression(ctx.expression());
+      const exprType = callbacks.getExpressionType(ctx.expression());
+      if (exprType && NarrowingCastHelper_default.isCrossTypeCategoryConversion(exprType, typeName)) {
+        if (NarrowingCastHelper_default.isIntegerType(exprType) && NarrowingCastHelper_default.isFloatType(typeName)) {
+          exprCode = NarrowingCastHelper_default.wrapIntToFloat(exprCode, typeName);
+        }
+        if (NarrowingCastHelper_default.isFloatType(exprType) && NarrowingCastHelper_default.isIntegerType(typeName)) {
+          const cType = TYPE_MAP_default[typeName] ?? typeName;
+          exprCode = CppModeHelper_default.cast(cType, exprCode);
+        }
+      }
+      return `${decl} = ${exprCode}`;
+    });
   }
   // ========================================================================
   // Tier 4: Orchestrators (main entry points)
@@ -125310,7 +125799,7 @@ var TypeGenerationHelper_default = TypeGenerationHelper;
 var SIGNED_INTEGERS = /* @__PURE__ */ new Set(["i8", "i16", "i32", "i64"]);
 var UNSIGNED_INTEGERS = /* @__PURE__ */ new Set(["u8", "u16", "u32", "u64"]);
 var ALL_INTEGERS = /* @__PURE__ */ new Set([...SIGNED_INTEGERS, ...UNSIGNED_INTEGERS]);
-var FLOAT_TYPES3 = /* @__PURE__ */ new Set(["f32", "f64"]);
+var FLOAT_TYPES4 = /* @__PURE__ */ new Set(["f32", "f64"]);
 var CastValidator = class _CastValidator {
   /**
    * Check if a type is an integer type.
@@ -125322,7 +125811,7 @@ var CastValidator = class _CastValidator {
    * Check if a type is a floating-point type.
    */
   static isFloatType(typeName) {
-    return FLOAT_TYPES3.has(typeName);
+    return FLOAT_TYPES4.has(typeName);
   }
   /**
    * Check if a type is signed.
@@ -128368,6 +128857,30 @@ typedef ${callbackInfo.returnType} (*${callbackInfo.typedefName})(${paramList});
   isFloatShadowCurrent(shadowName) {
     return CodeGenState.floatShadowCurrent.has(shadowName);
   }
+  /**
+   * Issue #948: Check if a type is an opaque (forward-declared) struct type.
+   * Opaque types can only be used as pointers (cannot be instantiated).
+   * Part of IOrchestrator interface.
+   */
+  isOpaqueType(typeName) {
+    return CodeGenState.isOpaqueType(typeName);
+  }
+  /**
+   * Issue #958: Check if a type is an external typedef struct type.
+   * Used for scope variables which should always be pointers for external struct types.
+   * Part of IOrchestrator interface.
+   */
+  isTypedefStructType(typeName) {
+    return CodeGenState.isTypedefStructType(typeName);
+  }
+  /**
+   * Issue #948: Mark a scope variable as having an opaque type.
+   * These variables are generated as pointers with NULL initialization.
+   * Part of IOrchestrator interface.
+   */
+  markOpaqueScopeVariable(qualifiedName) {
+    CodeGenState.markOpaqueScopeVariable(qualifiedName);
+  }
   // ===========================================================================
   // End IOrchestrator Implementation
   // ===========================================================================
@@ -130334,7 +130847,9 @@ typedef ${callbackInfo.returnType} (*${callbackInfo.typedefName})(${paramList});
     const minComparison = minValue === "0" ? `0.0${floatSuffix}` : `((${floatCastType})${minValue})`;
     const maxComparison = `((${floatCastType})${maxValue})`;
     const finalCast = CppModeHelper_default.cast(targetType, `(${expr})`);
-    return `((${expr}) > ${maxComparison} ? ${maxValue} : (${expr}) < ${minComparison} ? ${minValue} : ${finalCast})`;
+    const castMax = CppModeHelper_default.cast(targetType, maxValue);
+    const castMin = minValue === "0" ? "0" : CppModeHelper_default.cast(targetType, minValue);
+    return `((${expr}) > ${maxComparison} ? ${castMax} : (${expr}) < ${minComparison} ? ${castMin} : ${finalCast})`;
   }
   /**
    * ADR-023: Generate sizeof expression
@@ -132527,6 +133042,7 @@ var TSymbolInfoAdapter = class _TSymbolInfoAdapter {
     const registerMemberCTypes = /* @__PURE__ */ new Map();
     const scopePrivateConstValues = /* @__PURE__ */ new Map();
     const functionReturnTypes = /* @__PURE__ */ new Map();
+    const opaqueTypes = /* @__PURE__ */ new Set();
     for (const symbol of symbols) {
       switch (symbol.kind) {
         case "struct":
@@ -132614,6 +133130,8 @@ var TSymbolInfoAdapter = class _TSymbolInfoAdapter {
       scopePrivateConstValues,
       // Function return types
       functionReturnTypes,
+      // Issue #948: Opaque types
+      opaqueTypes,
       // Methods
       getSingleFunctionForVariable: (scopeName, varName) => _TSymbolInfoAdapter.getSingleFunctionForVariable(
         scopeVariableUsage,
@@ -132811,42 +133329,35 @@ var TSymbolInfoAdapter = class _TSymbolInfoAdapter {
       );
     }
     return {
-      // Type sets - knownEnums and knownScopes are merged
+      ...base,
       knownScopes: mergedKnownScopes,
-      knownStructs: base.knownStructs,
       knownEnums: mergedKnownEnums,
-      knownBitmaps: base.knownBitmaps,
-      knownRegisters: base.knownRegisters,
-      // Scope info
-      scopeMembers: base.scopeMembers,
-      scopeMemberVisibility: base.scopeMemberVisibility,
-      scopeVariableUsage: base.scopeVariableUsage,
-      // Struct info
-      structFields: base.structFields,
-      structFieldArrays: base.structFieldArrays,
-      structFieldDimensions: base.structFieldDimensions,
-      // Enum info - merged
       enumMembers: mergedEnumMembers,
-      // Bitmap info
-      bitmapFields: base.bitmapFields,
-      bitmapBackingType: base.bitmapBackingType,
-      bitmapBitWidth: base.bitmapBitWidth,
-      // Register info
-      scopedRegisters: base.scopedRegisters,
-      registerMemberAccess: base.registerMemberAccess,
-      registerMemberTypes: base.registerMemberTypes,
-      registerBaseAddresses: base.registerBaseAddresses,
-      registerMemberOffsets: base.registerMemberOffsets,
-      registerMemberCTypes: base.registerMemberCTypes,
-      // Private const values
-      scopePrivateConstValues: base.scopePrivateConstValues,
-      // Function return types - merged
-      functionReturnTypes: mergedFunctionReturnTypes,
-      // Methods - delegate to base's implementation
-      getSingleFunctionForVariable: base.getSingleFunctionForVariable,
-      hasPublicSymbols: base.hasPublicSymbols
+      functionReturnTypes: mergedFunctionReturnTypes
     };
   }
+  /**
+   * Issue #948: Merge opaque types from an external source (e.g., SymbolTable)
+   * into an existing ICodeGenSymbols.
+   *
+   * Opaque types are forward-declared struct types (like `typedef struct _foo foo;`)
+   * that come from C headers and need to be tracked for correct scope variable
+   * generation (as pointers with NULL initialization).
+   *
+   * @param base The ICodeGenSymbols from the current file
+   * @param externalOpaqueTypes Array of opaque type names from external sources
+   * @returns New ICodeGenSymbols with merged opaque types
+   */
+  static mergeOpaqueTypes(base, externalOpaqueTypes) {
+    if (externalOpaqueTypes.length === 0) {
+      return base;
+    }
+    const mergedOpaqueTypes = new Set(base.opaqueTypes);
+    for (const typeName of externalOpaqueTypes) {
+      mergedOpaqueTypes.add(typeName);
+    }
+    return { ...base, opaqueTypes: mergedOpaqueTypes };
+  }
 };
 var TSymbolInfoAdapter_default = TSymbolInfoAdapter;
 
@@ -133233,6 +133744,30 @@ var DeclaratorUtils = class _DeclaratorUtils {
     }
     return void 0;
   }
+  /**
+   * Extract the first declarator name from an init-declarator-list.
+   * For "typedef struct _widget_t widget_t;", this returns "widget_t".
+   * Used for Issue #948 opaque type detection.
+   */
+  static extractFirstDeclaratorName(initDeclList) {
+    const initDeclarators = initDeclList.initDeclarator?.();
+    if (!initDeclarators || initDeclarators.length === 0) return void 0;
+    const firstDeclarator = initDeclarators[0].declarator?.();
+    if (!firstDeclarator) return void 0;
+    return _DeclaratorUtils.extractDeclaratorName(firstDeclarator) ?? void 0;
+  }
+  /**
+   * Check if the first declarator in an init-declarator-list has a pointer.
+   * For "typedef struct X *handle_t;", the declarator is "*handle_t" which has a pointer.
+   * Used for Issue #957 to distinguish pointer typedefs from opaque struct typedefs.
+   */
+  static firstDeclaratorHasPointer(initDeclList) {
+    const initDeclarators = initDeclList.initDeclarator?.();
+    if (!initDeclarators || initDeclarators.length === 0) return false;
+    const firstDeclarator = initDeclarators[0].declarator?.();
+    if (!firstDeclarator) return false;
+    return Boolean(firstDeclarator.pointer?.());
+  }
 };
 var DeclaratorUtils_default = DeclaratorUtils;
 
@@ -133245,15 +133780,15 @@ var StructCollector2 = class _StructCollector {
    * @param sourceFile Source file path
    * @param line Source line number
    * @param symbolTable Optional symbol table for field tracking
-   * @param typedefName Optional typedef name for anonymous structs
-   * @param isTypedef Whether this is part of a typedef declaration
-   * @param warnings Array to collect warnings
+   * @param options Optional collection options (typedef info, warnings)
    */
-  static collect(structSpec, sourceFile, line, symbolTable, typedefName, isTypedef, warnings) {
+  static collect(structSpec, sourceFile, line, symbolTable, options = {}) {
+    const { typedefName, isTypedef, warnings, isPointerTypedef } = options;
     const identifier = structSpec.Identifier();
     const name = identifier?.getText() || typedefName;
     if (!name) return null;
     const isUnion = structSpec.structOrUnion()?.getText() === "union";
+    const hasBody = structSpec.structDeclarationList() !== null;
     const fields = _StructCollector.collectFields(
       structSpec,
       name,
@@ -133261,8 +133796,15 @@ var StructCollector2 = class _StructCollector {
       warnings
     );
     const needsStructKeyword = Boolean(identifier && !isTypedef);
-    if (symbolTable && needsStructKeyword) {
-      symbolTable.markNeedsStructKeyword(name);
+    if (symbolTable) {
+      _StructCollector.updateSymbolTable(symbolTable, name, sourceFile, {
+        needsStructKeyword,
+        hasBody,
+        isTypedef,
+        typedefName,
+        structTag: identifier?.getText(),
+        isPointerTypedef
+      });
     }
     return {
       kind: "struct",
@@ -133276,6 +133818,60 @@ var StructCollector2 = class _StructCollector {
       fields: fields.size > 0 ? fields : void 0
     };
   }
+  /**
+   * Update symbol table with struct metadata.
+   * Extracted to reduce cognitive complexity of collect().
+   */
+  static updateSymbolTable(symbolTable, name, sourceFile, options) {
+    const {
+      needsStructKeyword,
+      hasBody,
+      isTypedef,
+      typedefName,
+      structTag,
+      isPointerTypedef
+    } = options;
+    if (needsStructKeyword) {
+      symbolTable.markNeedsStructKeyword(name);
+    }
+    if (isTypedef && !hasBody && typedefName && !isPointerTypedef) {
+      symbolTable.markOpaqueType(typedefName);
+      if (structTag) {
+        symbolTable.registerStructTagAlias(structTag, typedefName);
+      }
+    }
+    if (isTypedef && typedefName && !isPointerTypedef) {
+      symbolTable.markTypedefStructType(typedefName, sourceFile);
+    }
+    if (hasBody) {
+      _StructCollector.unmarkOpaqueTypesOnDefinition(
+        symbolTable,
+        sourceFile,
+        structTag,
+        typedefName
+      );
+    }
+  }
+  /**
+   * Unmark opaque and typedef struct types when a full struct definition is encountered.
+   * Handles: typedef struct _foo foo; struct _foo { ... };
+   * Issue #958: Only unmarks typedefStructTypes when definition is in SAME file.
+   */
+  static unmarkOpaqueTypesOnDefinition(symbolTable, sourceFile, structTag, typedefName) {
+    if (structTag) {
+      const typedefAlias = symbolTable.getStructTagAlias(structTag);
+      symbolTable.unmarkOpaqueType(structTag);
+      symbolTable.unmarkTypedefStructType(structTag, sourceFile);
+      if (typedefAlias) {
+        symbolTable.unmarkOpaqueType(typedefAlias);
+        symbolTable.unmarkTypedefStructType(typedefAlias, sourceFile);
+      }
+    }
+    if (typedefName) {
+      symbolTable.unmarkOpaqueType(typedefName);
+      symbolTable.unmarkTypedefStructType(typedefName, sourceFile);
+    }
+  }
   /**
    * Collect fields from a struct/union definition.
    */
@@ -133412,6 +134008,15 @@ var FunctionCollector2 = class _FunctionCollector {
       isArray: p.isArray
     }));
   }
+  /**
+   * Resolve return type, appending '*' if declarator has a pointer.
+   * Issue #895 Bug B / Issue #945: C grammar puts pointer before directDeclarator
+   * (e.g., `widget_t *func()` has declarator.pointer() !== null)
+   */
+  static _resolveReturnType(baseType, declarator) {
+    const hasPointer = declarator.pointer() !== null;
+    return hasPointer ? `${baseType}*` : baseType;
+  }
   /**
    * Collect a function symbol from a function definition.
    *
@@ -133425,7 +134030,11 @@ var FunctionCollector2 = class _FunctionCollector {
     if (!name) return null;
     const line = funcDef.start?.line ?? 0;
     const declSpecs = funcDef.declarationSpecifiers();
-    const returnType = declSpecs ? DeclaratorUtils_default.extractTypeFromDeclSpecs(declSpecs) : "int";
+    const baseType = declSpecs ? DeclaratorUtils_default.extractTypeFromDeclSpecs(declSpecs) : "int";
+    const returnType = _FunctionCollector._resolveReturnType(
+      baseType,
+      declarator
+    );
     const parameters = _FunctionCollector._mapParameters(
       DeclaratorUtils_default.extractFunctionParameters(declarator)
     );
@@ -133455,8 +134064,10 @@ var FunctionCollector2 = class _FunctionCollector {
     const parameters = _FunctionCollector._mapParameters(
       DeclaratorUtils_default.extractFunctionParameters(declarator)
     );
-    const hasPointer = declarator.pointer() !== null;
-    const returnType = hasPointer ? `${baseType}*` : baseType;
+    const returnType = _FunctionCollector._resolveReturnType(
+      baseType,
+      declarator
+    );
     return {
       kind: "function",
       name,
@@ -133599,39 +134210,33 @@ var CResolver = class _CResolver {
     const line = decl.start?.line ?? 0;
     const isTypedef = DeclaratorUtils_default.hasStorageClass(declSpecs, "typedef");
     const isExtern = DeclaratorUtils_default.hasStorageClass(declSpecs, "extern");
+    const ctx = {
+      sourceFile,
+      line,
+      isTypedef,
+      isExtern,
+      symbols
+    };
     const structSpec = DeclaratorUtils_default.findStructOrUnionSpecifier(declSpecs);
     if (structSpec) {
-      const typedefName = isTypedef ? DeclaratorUtils_default.extractTypedefNameFromSpecs(declSpecs) : void 0;
-      const structSymbol = StructCollector_default2.collect(
+      _CResolver.collectStructSymbol(
         structSpec,
-        sourceFile,
-        line,
+        decl,
+        declSpecs,
+        ctx,
         symbolTable,
-        typedefName,
-        isTypedef,
         warnings
       );
-      if (structSymbol) {
-        symbols.push(structSymbol);
-      }
     }
     const enumSpec = DeclaratorUtils_default.findEnumSpecifier(declSpecs);
     if (enumSpec) {
-      const enumResult = EnumCollector_default2.collect(enumSpec, sourceFile, line);
-      if (enumResult) {
-        symbols.push(enumResult.enum);
-        for (const member of enumResult.members) {
-          symbols.push(member);
-        }
-      }
+      _CResolver.collectEnumSymbols(
+        enumSpec,
+        ctx.sourceFile,
+        ctx.line,
+        ctx.symbols
+      );
     }
-    const ctx = {
-      sourceFile,
-      line,
-      isTypedef,
-      isExtern,
-      symbols
-    };
     const initDeclList = decl.initDeclaratorList();
     if (initDeclList) {
       const baseType = DeclaratorUtils_default.extractTypeFromDeclSpecs(declSpecs);
@@ -133645,6 +134250,63 @@ var CResolver = class _CResolver {
       );
     }
   }
+  /**
+   * Collect struct symbol from a struct specifier.
+   * Extracted to reduce cognitive complexity of collectDeclaration().
+   */
+  static collectStructSymbol(structSpec, decl, declSpecs, ctx, symbolTable, warnings) {
+    const typedefName = ctx.isTypedef ? _CResolver.extractTypedefName(decl, declSpecs) : void 0;
+    const isPointerTypedef = ctx.isTypedef ? _CResolver.isPointerTypedef(decl) : false;
+    const structSymbol = StructCollector_default2.collect(
+      structSpec,
+      ctx.sourceFile,
+      ctx.line,
+      symbolTable,
+      {
+        typedefName,
+        isTypedef: ctx.isTypedef,
+        warnings,
+        isPointerTypedef
+      }
+    );
+    if (structSymbol) {
+      ctx.symbols.push(structSymbol);
+    }
+  }
+  /**
+   * Extract typedef name from declaration.
+   * First try from init-declarator-list, then fall back to specifiers.
+   */
+  static extractTypedefName(decl, declSpecs) {
+    const initDeclList = decl.initDeclaratorList();
+    if (initDeclList) {
+      const name = DeclaratorUtils_default.extractFirstDeclaratorName(initDeclList);
+      if (name) return name;
+    }
+    return DeclaratorUtils_default.extractTypedefNameFromSpecs(declSpecs);
+  }
+  /**
+   * Check if a typedef declaration has a pointer declarator.
+   * For "typedef struct X *Y", the declarator is "*Y" which has a pointer.
+   * Used for Issue #957 to distinguish pointer typedefs from opaque struct typedefs.
+   */
+  static isPointerTypedef(decl) {
+    const initDeclList = decl.initDeclaratorList();
+    if (!initDeclList) return false;
+    return DeclaratorUtils_default.firstDeclaratorHasPointer(initDeclList);
+  }
+  /**
+   * Collect enum symbols from an enum specifier.
+   * Extracted to reduce cognitive complexity of collectDeclaration().
+   */
+  static collectEnumSymbols(enumSpec, sourceFile, line, symbols) {
+    const enumResult = EnumCollector_default2.collect(enumSpec, sourceFile, line);
+    if (!enumResult) return;
+    symbols.push(enumResult.enum);
+    for (const member of enumResult.members) {
+      symbols.push(member);
+    }
+  }
   /**
    * Collect symbols from init declarator list.
    */
@@ -137838,6 +138500,9 @@ var IndexTypeListener = class extends CNextListener {
       if (TypeConstants_default.UNSIGNED_INDEX_TYPES.includes(resolvedType)) {
         continue;
       }
+      if (CodeGenState.isKnownEnum(resolvedType)) {
+        continue;
+      }
       const { line, column } = ParserUtils_default.getPosition(ctx);
       this.analyzer.addError(line, column, "E0852", resolvedType);
       return;
@@ -137927,6 +138592,10 @@ var IndexTypeListener = class extends CNextListener {
       if (TypeConstants_default.SIGNED_TYPES.includes(currentType)) {
         return "bool";
       }
+      const strippedType = currentType.replace(/\[[^\]]*\]$/, "");
+      if (strippedType !== currentType) {
+        return strippedType;
+      }
       return currentType;
     }
     if (op.LPAREN()) {
@@ -138327,7 +138996,7 @@ var CacheKeyGenerator_default = CacheKeyGenerator;
 
 // src/utils/cache/CacheManager.ts
 var defaultFs7 = NodeFileSystem_default.instance;
-var CACHE_VERSION = 4;
+var CACHE_VERSION = 6;
 var TRANSPILER_VERSION = package_default.version;
 var CacheManager = class {
   projectRoot;
@@ -138427,14 +139096,16 @@ var CacheManager = class {
       symbols,
       structFields,
       needsStructKeyword: cachedEntry.needsStructKeyword ?? [],
-      enumBitWidth
+      enumBitWidth,
+      opaqueTypes: cachedEntry.opaqueTypes ?? [],
+      typedefStructTypes: cachedEntry.typedefStructTypes ?? []
     };
   }
   /**
    * Store symbols and struct fields for a file
    * ADR-055 Phase 7: Takes ISerializedSymbol[] directly
    */
-  setSymbols(filePath, symbols, structFields, needsStructKeyword, enumBitWidth) {
+  setSymbols(filePath, symbols, structFields, needsStructKeyword, enumBitWidth, opaqueTypes, typedefStructTypes) {
     if (!this.cache) return;
     let cacheKey;
     try {
@@ -138462,7 +139133,9 @@ var CacheManager = class {
       symbols: serializedSymbols,
       structFields: serializedFields,
       needsStructKeyword,
-      enumBitWidth: serializedEnumBitWidth
+      enumBitWidth: serializedEnumBitWidth,
+      opaqueTypes,
+      typedefStructTypes
     };
     this.cache.setKey(filePath, entry);
     this.dirty = true;
@@ -138490,12 +139163,16 @@ var CacheManager = class {
       filePath,
       symbolTable
     );
+    const opaqueTypes = symbolTable.getAllOpaqueTypes();
+    const typedefStructTypes = symbolTable.getAllTypedefStructTypes();
     this.setSymbols(
       filePath,
       symbols,
       structFields,
       needsStructKeyword,
-      enumBitWidth
+      enumBitWidth,
+      opaqueTypes,
+      typedefStructTypes
     );
   }
   /**
@@ -138938,7 +139615,7 @@ var Transpiler = class {
    * Stage 6: Generate headers (per-file)
    */
   async _executePipeline(input, result) {
-    this._collectAllHeaderSymbols(input.headerFiles, result);
+    await this._collectAllHeaderSymbols(input.headerFiles, result);
     CodeGenState.buildExternalStructFields();
     if (!this._collectAllCNextSymbolsFromPipeline(input.cnextFiles, result)) {
       return;
@@ -139047,6 +139724,13 @@ var Transpiler = class {
           externalEnumSources
         );
       }
+      const externalOpaqueTypes = CodeGenState.symbolTable.getAllOpaqueTypes();
+      if (externalOpaqueTypes.length > 0) {
+        symbolInfo = TSymbolInfoAdapter_default.mergeOpaqueTypes(
+          symbolInfo,
+          externalOpaqueTypes
+        );
+      }
       CodeGenState.symbols = symbolInfo;
       const analyzerErrors = runAnalyzers_default(tree, tokenStream);
       if (analyzerErrors.length > 0) {
@@ -139220,11 +139904,12 @@ var Transpiler = class {
   }
   /**
    * Stage 2: Collect symbols from all C/C++ headers
+   * Issue #945: Made async for preprocessing support.
    */
-  _collectAllHeaderSymbols(headerFiles, result) {
+  async _collectAllHeaderSymbols(headerFiles, result) {
     for (const file of headerFiles) {
       try {
-        this.doCollectHeaderSymbols(file);
+        await this.doCollectHeaderSymbols(file);
         result.filesProcessed++;
       } catch (err) {
         this.warnings.push(`Failed to process header ${file.path}: ${err}`);
@@ -139503,15 +140188,16 @@ var Transpiler = class {
   /**
    * Stage 2: Collect symbols from a single C/C++ header
    * Issue #592: Recursive include processing moved to IncludeResolver.resolveHeadersTransitively()
+   * Issue #945: Added preprocessing support for conditional compilation
    * SonarCloud S3776: Refactored to use helper methods for reduced complexity.
    */
-  doCollectHeaderSymbols(file) {
+  async doCollectHeaderSymbols(file) {
     const absolutePath = resolve12(file.path);
     this.state.markHeaderProcessed(absolutePath);
     if (this.tryRestoreFromCache(file)) {
       return;
     }
-    const content = this.fs.readFile(file.path);
+    const content = await this.getHeaderContent(file);
     this.parseHeaderFile(file, content);
     if (this.config.debugMode) {
       const symbols = CodeGenState.symbolTable.getSymbolsByFile(file.path);
@@ -139542,9 +140228,54 @@ var Transpiler = class {
       cached.needsStructKeyword
     );
     CodeGenState.symbolTable.restoreEnumBitWidths(cached.enumBitWidth);
+    CodeGenState.symbolTable.restoreOpaqueTypes(cached.opaqueTypes);
+    CodeGenState.symbolTable.restoreTypedefStructTypes(
+      cached.typedefStructTypes
+    );
     this.detectCppFromFileType(file);
     return true;
   }
+  /**
+   * Get header content, optionally preprocessed.
+   * Issue #945: Evaluates #if/#ifdef directives using system preprocessor.
+   *
+   * Only preprocesses when necessary to avoid side effects from full expansion.
+   * Preprocessing is needed when the file has conditional compilation patterns
+   * like #if MACRO != 0 that require expression evaluation.
+   */
+  async getHeaderContent(file) {
+    const rawContent = this.fs.readFile(file.path);
+    if (this.config.preprocess === false) {
+      return rawContent;
+    }
+    if (!this.preprocessor.isAvailable()) {
+      return rawContent;
+    }
+    if (!this.needsConditionalPreprocessing(rawContent)) {
+      return rawContent;
+    }
+    const result = await this.preprocessor.preprocess(file.path, {
+      defines: this.config.defines,
+      includePaths: this.config.includeDirs,
+      keepLineDirectives: false
+      // We don't need line mappings for symbol collection
+    });
+    if (!result.success) {
+      this.warnings.push(
+        `Preprocessing failed for ${file.path}: ${result.error}. Using raw content.`
+      );
+      return rawContent;
+    }
+    return result.content;
+  }
+  /**
+   * Check if a header file needs conditional preprocessing.
+   * Issue #945: Only preprocess files with #if expressions that need evaluation.
+   */
+  needsConditionalPreprocessing(content) {
+    const ifExpressionPattern = /#(?:if|elif)\s+(?!defined\s*\()(?![01]\s*(?:$|\n|\/\*|\/\/))\w+/m;
+    return ifExpressionPattern.test(content);
+  }
   /**
    * Restore cached symbols to the symbol table.
    * ADR-055 Phase 7: Converts ISerializedSymbol[] from cache to typed symbols.