c-next 0.1.70 → 0.1.72

package/src/transpiler/logic/symbols/SymbolTable.ts

@@ -1,14 +1,27 @@
 /**
  * Unified Symbol Table
  * Stores symbols from all source languages and detects conflicts
+ *
+ * ADR-055 Phase 7: Fully typed symbol storage using discriminated unions.
+ * - TSymbol: C-Next symbols (rich type system with TType)
+ * - TCSymbol: C header symbols (string types)
+ * - TCppSymbol: C++ header symbols (string types)
  */
 
-import ISymbol from "../../../utils/types/ISymbol";
 import ESourceLanguage from "../../../utils/types/ESourceLanguage";
-import ESymbolKind from "../../../utils/types/ESymbolKind";
 import LiteralUtils from "../../../utils/LiteralUtils";
-import IConflict from "./types/IConflict";
-import IStructFieldInfo from "./types/IStructFieldInfo";
+import IConflict from "../../types/IConflict";
+import IStructFieldInfo from "../../types/symbols/IStructFieldInfo";
+import TSymbol from "../../types/symbols/TSymbol";
+import TCSymbol from "../../types/symbols/c/TCSymbol";
+import TCppSymbol from "../../types/symbols/cpp/TCppSymbol";
+import TAnySymbol from "../../types/symbols/TAnySymbol";
+import IStructSymbol from "../../types/symbols/IStructSymbol";
+import IEnumSymbol from "../../types/symbols/IEnumSymbol";
+import IFunctionSymbol from "../../types/symbols/IFunctionSymbol";
+import IVariableSymbol from "../../types/symbols/IVariableSymbol";
+import TypeResolver from "../../../utils/TypeResolver";
+import SymbolNameUtils from "./cnext/utils/SymbolNameUtils";
 
 /**
  * Central symbol table for cross-language interoperability
@@ -19,11 +32,39 @@ import IStructFieldInfo from "./types/IStructFieldInfo";
  * - OK: Function overloads in C++ (different signatures)
  */
 class SymbolTable {
-  /** All symbols indexed by name */
-  private readonly symbols: Map<string, ISymbol[]> = new Map();
+  // ========================================================================
+  // C-Next Symbol Storage (TSymbol)
+  // ========================================================================
+
+  /** All C-Next TSymbols indexed by name */
+  private readonly tSymbols: Map<string, TSymbol[]> = new Map();
+
+  /** C-Next TSymbols indexed by source file */
+  private readonly tSymbolsByFile: Map<string, TSymbol[]> = new Map();
+
+  // ========================================================================
+  // C Symbol Storage (TCSymbol)
+  // ========================================================================
+
+  /** All C symbols indexed by name */
+  private readonly cSymbols: Map<string, TCSymbol[]> = new Map();
+
+  /** C symbols indexed by source file */
+  private readonly cSymbolsByFile: Map<string, TCSymbol[]> = new Map();
+
+  // ========================================================================
+  // C++ Symbol Storage (TCppSymbol)
+  // ========================================================================
+
+  /** All C++ symbols indexed by name */
+  private readonly cppSymbols: Map<string, TCppSymbol[]> = new Map();
 
-  /** Symbols indexed by source file */
-  private readonly byFile: Map<string, ISymbol[]> = new Map();
+  /** C++ symbols indexed by source file */
+  private readonly cppSymbolsByFile: Map<string, TCppSymbol[]> = new Map();
+
+  // ========================================================================
+  // Auxiliary Data (shared across languages)
+  // ========================================================================
 
   /** Struct field information: struct name -> (field name -> field info) */
   private readonly structFields: Map<string, Map<string, IStructFieldInfo>> =
@@ -42,331 +83,466 @@ class SymbolTable {
    */
   private readonly enumBitWidth: Map<string, number> = new Map();
 
+  // ========================================================================
+  // C-Next Symbol Methods (TSymbol)
+  // ========================================================================
+
   /**
-   * Add a symbol to the table
+   * Add a C-Next TSymbol to the table
    */
-  addSymbol(symbol: ISymbol): void {
+  addTSymbol(symbol: TSymbol): void {
     // Add to name index
-    const existing = this.symbols.get(symbol.name);
+    const existing = this.tSymbols.get(symbol.name);
     if (existing) {
       existing.push(symbol);
     } else {
-      this.symbols.set(symbol.name, [symbol]);
+      this.tSymbols.set(symbol.name, [symbol]);
     }
 
     // Add to file index
-    const fileSymbols = this.byFile.get(symbol.sourceFile);
+    const fileSymbols = this.tSymbolsByFile.get(symbol.sourceFile);
     if (fileSymbols) {
       fileSymbols.push(symbol);
     } else {
-      this.byFile.set(symbol.sourceFile, [symbol]);
+      this.tSymbolsByFile.set(symbol.sourceFile, [symbol]);
+    }
+
+    // Auto-register struct fields for TypeResolver.getMemberTypeInfo()
+    if (symbol.kind === "struct") {
+      this.registerStructFields(symbol);
+    }
+  }
+
+  /**
+   * Register struct fields in structFields map for cross-file type resolution.
+   * Called automatically when adding struct symbols.
+   */
+  private registerStructFields(struct: IStructSymbol): void {
+    const mangledName = SymbolNameUtils.getMangledName(struct);
+
+    for (const [fieldName, fieldInfo] of struct.fields) {
+      // Convert TType to string for structFields map
+      const typeString = TypeResolver.getTypeName(fieldInfo.type);
+
+      // Filter to only numeric dimensions (structFields doesn't support string dims)
+      const numericDims = fieldInfo.dimensions?.filter(
+        (d): d is number => typeof d === "number",
+      );
+
+      this.addStructField(
+        mangledName,
+        fieldName,
+        typeString,
+        numericDims && numericDims.length > 0 ? numericDims : undefined,
+      );
     }
   }
 
   /**
-   * Add multiple symbols at once
+   * Add multiple C-Next TSymbols at once
    */
-  addSymbols(symbols: ISymbol[]): void {
+  addTSymbols(symbols: TSymbol[]): void {
     for (const symbol of symbols) {
-      this.addSymbol(symbol);
+      this.addTSymbol(symbol);
     }
   }
 
   /**
-   * Get a symbol by name (returns first match, or undefined)
+   * Get a TSymbol by name (returns first match, or undefined)
    */
-  getSymbol(name: string): ISymbol | undefined {
-    const symbols = this.symbols.get(name);
+  getTSymbol(name: string): TSymbol | undefined {
+    const symbols = this.tSymbols.get(name);
     return symbols?.[0];
   }
 
   /**
-   * Get all symbols with a given name (for overload detection)
+   * Get all TSymbols with a given name (for overload detection)
    */
-  getOverloads(name: string): ISymbol[] {
-    return this.symbols.get(name) ?? [];
+  getTOverloads(name: string): TSymbol[] {
+    return this.tSymbols.get(name) ?? [];
   }
 
   /**
-   * Check if a symbol exists
+   * Get TSymbols by source file
    */
-  hasSymbol(name: string): boolean {
-    return this.symbols.has(name);
+  getTSymbolsByFile(file: string): TSymbol[] {
+    return this.tSymbolsByFile.get(file) ?? [];
   }
 
   /**
-   * Check if a symbol has conflicts
+   * Get all TSymbols
    */
-  hasConflict(name: string): boolean {
-    const symbols = this.symbols.get(name);
-    if (!symbols || symbols.length <= 1) {
-      return false;
+  getAllTSymbols(): TSymbol[] {
+    const result: TSymbol[] = [];
+    for (const symbols of this.tSymbols.values()) {
+      result.push(...symbols);
     }
+    return result;
+  }
+
+  /**
+   * Get all struct symbols (type-safe filtering)
+   */
+  getStructSymbols(): IStructSymbol[] {
+    return this.getAllTSymbols().filter(
+      (s): s is IStructSymbol => s.kind === "struct",
+    );
+  }
 
-    return this.detectConflict(symbols) !== null;
+  /**
+   * Get all enum symbols (type-safe filtering)
+   */
+  getEnumSymbols(): IEnumSymbol[] {
+    return this.getAllTSymbols().filter(
+      (s): s is IEnumSymbol => s.kind === "enum",
+    );
   }
 
   /**
-   * Get all conflicts in the symbol table
-   * Per user requirement: Strict errors for cross-language conflicts
+   * Get all function symbols (type-safe filtering)
    */
-  getConflicts(): IConflict[] {
-    const conflicts: IConflict[] = [];
+  getFunctionSymbols(): IFunctionSymbol[] {
+    return this.getAllTSymbols().filter(
+      (s): s is IFunctionSymbol => s.kind === "function",
+    );
+  }
 
-    for (const [, symbols] of this.symbols) {
-      if (symbols.length <= 1) continue;
+  /**
+   * Get all variable symbols (type-safe filtering)
+   */
+  getVariableSymbols(): IVariableSymbol[] {
+    return this.getAllTSymbols().filter(
+      (s): s is IVariableSymbol => s.kind === "variable",
+    );
+  }
 
-      const conflict = this.detectConflict(symbols);
-      if (conflict) {
-        conflicts.push(conflict);
-      }
+  /**
+   * Get struct field type directly from TSymbol storage.
+   * This method queries IStructSymbol.fields directly, eliminating the need
+   * for the separate structFields Map for C-Next symbols.
+   *
+   * @param structName Name of the struct
+   * @param fieldName Name of the field
+   * @returns Field type string or undefined if not found
+   */
+  getTStructFieldType(
+    structName: string,
+    fieldName: string,
+  ): string | undefined {
+    const struct = this.getTOverloads(structName).find(
+      (s): s is IStructSymbol => s.kind === "struct",
+    );
+    if (!struct) {
+      return undefined;
     }
-
-    return conflicts;
+    const field = struct.fields.get(fieldName);
+    return field ? TypeResolver.getTypeName(field.type) : undefined;
   }
 
   /**
-   * Get symbols by source file
+   * Check if a TSymbol exists by name
    */
-  getSymbolsByFile(file: string): ISymbol[] {
-    return this.byFile.get(file) ?? [];
+  hasTSymbol(name: string): boolean {
+    return this.tSymbols.has(name);
   }
 
   /**
-   * Get symbols by source language
+   * Get TSymbol count
    */
-  getSymbolsByLanguage(lang: ESourceLanguage): ISymbol[] {
-    const result: ISymbol[] = [];
-    for (const symbols of this.symbols.values()) {
-      for (const symbol of symbols) {
-        if (symbol.sourceLanguage === lang) {
-          result.push(symbol);
-        }
-      }
+  getTSize(): number {
+    let count = 0;
+    for (const symbols of this.tSymbols.values()) {
+      count += symbols.length;
     }
-    return result;
+    return count;
   }
 
+  // ========================================================================
+  // C Symbol Methods (TCSymbol)
+  // ========================================================================
+
   /**
-   * Get all symbols
+   * Add a C symbol to the table
    */
-  getAllSymbols(): ISymbol[] {
-    const result: ISymbol[] = [];
-    for (const symbols of this.symbols.values()) {
-      result.push(...symbols);
+  addCSymbol(symbol: TCSymbol): void {
+    // Add to name index
+    const existing = this.cSymbols.get(symbol.name);
+    if (existing) {
+      existing.push(symbol);
+    } else {
+      this.cSymbols.set(symbol.name, [symbol]);
+    }
+
+    // Add to file index
+    const fileSymbols = this.cSymbolsByFile.get(symbol.sourceFile);
+    if (fileSymbols) {
+      fileSymbols.push(symbol);
+    } else {
+      this.cSymbolsByFile.set(symbol.sourceFile, [symbol]);
     }
-    return result;
   }
 
   /**
-   * Add struct field information
-   * @param structName Name of the struct
-   * @param fieldName Name of the field
-   * @param fieldType Type of the field (e.g., "uint32_t")
-   * @param arrayDimensions Optional array dimensions if field is an array
+   * Add multiple C symbols at once
    */
-  addStructField(
-    structName: string,
-    fieldName: string,
-    fieldType: string,
-    arrayDimensions?: number[],
-  ): void {
-    let fields = this.structFields.get(structName);
-    if (!fields) {
-      fields = new Map();
-      this.structFields.set(structName, fields);
+  addCSymbols(symbols: TCSymbol[]): void {
+    for (const symbol of symbols) {
+      this.addCSymbol(symbol);
     }
-
-    fields.set(fieldName, {
-      type: fieldType,
-      arrayDimensions,
-    });
   }
 
   /**
-   * Get struct field type
-   * @param structName Name of the struct
-   * @param fieldName Name of the field
-   * @returns Field type or undefined if not found
+   * Get a C symbol by name (returns first match, or undefined)
    */
-  getStructFieldType(
-    structName: string,
-    fieldName: string,
-  ): string | undefined {
-    const fields = this.structFields.get(structName);
-    return fields?.get(fieldName)?.type;
+  getCSymbol(name: string): TCSymbol | undefined {
+    const symbols = this.cSymbols.get(name);
+    return symbols?.[0];
   }
 
   /**
-   * Get struct field info (type and array dimensions)
-   * @param structName Name of the struct
-   * @param fieldName Name of the field
-   * @returns Field info or undefined if not found
+   * Get all C symbols with a given name
    */
-  getStructFieldInfo(
-    structName: string,
-    fieldName: string,
-  ): IStructFieldInfo | undefined {
-    const fields = this.structFields.get(structName);
-    return fields?.get(fieldName);
+  getCOverloads(name: string): TCSymbol[] {
+    return this.cSymbols.get(name) ?? [];
   }
 
   /**
-   * Issue #196 Bug 3: Mark a struct as requiring 'struct' keyword in C
-   * @param structName Name of the struct (e.g., "NamedPoint")
+   * Get C symbols by source file
    */
-  markNeedsStructKeyword(structName: string): void {
-    this.needsStructKeyword.add(structName);
+  getCSymbolsByFile(file: string): TCSymbol[] {
+    return this.cSymbolsByFile.get(file) ?? [];
   }
 
   /**
-   * Issue #196 Bug 3: Check if a struct requires 'struct' keyword in C
-   * @param structName Name of the struct
-   * @returns true if the struct was defined as 'struct Name { ... }' without typedef
+   * Get all C symbols
    */
-  checkNeedsStructKeyword(structName: string): boolean {
-    return this.needsStructKeyword.has(structName);
+  getAllCSymbols(): TCSymbol[] {
+    const result: TCSymbol[] = [];
+    for (const symbols of this.cSymbols.values()) {
+      result.push(...symbols);
+    }
+    return result;
   }
 
+  // ========================================================================
+  // C++ Symbol Methods (TCppSymbol)
+  // ========================================================================
+
   /**
-   * Issue #196 Bug 3: Get all struct names requiring 'struct' keyword
-   * @returns Array of struct names
+   * Add a C++ symbol to the table
    */
-  getAllNeedsStructKeyword(): string[] {
-    return Array.from(this.needsStructKeyword);
+  addCppSymbol(symbol: TCppSymbol): void {
+    // Add to name index
+    const existing = this.cppSymbols.get(symbol.name);
+    if (existing) {
+      existing.push(symbol);
+    } else {
+      this.cppSymbols.set(symbol.name, [symbol]);
+    }
+
+    // Add to file index
+    const fileSymbols = this.cppSymbolsByFile.get(symbol.sourceFile);
+    if (fileSymbols) {
+      fileSymbols.push(symbol);
+    } else {
+      this.cppSymbolsByFile.set(symbol.sourceFile, [symbol]);
+    }
   }
 
   /**
-   * Issue #196 Bug 3: Restore needsStructKeyword from cache
-   * @param structNames Array of struct names requiring 'struct' keyword
+   * Add multiple C++ symbols at once
    */
-  restoreNeedsStructKeyword(structNames: string[]): void {
-    for (const name of structNames) {
-      this.needsStructKeyword.add(name);
+  addCppSymbols(symbols: TCppSymbol[]): void {
+    for (const symbol of symbols) {
+      this.addCppSymbol(symbol);
     }
   }
 
   /**
-   * Issue #208: Add enum bit width for a typed enum
-   * @param enumName Name of the enum (e.g., "EPressureType")
-   * @param bitWidth Bit width from backing type (e.g., 8 for uint8_t)
+   * Get a C++ symbol by name (returns first match, or undefined)
    */
-  addEnumBitWidth(enumName: string, bitWidth: number): void {
-    this.enumBitWidth.set(enumName, bitWidth);
+  getCppSymbol(name: string): TCppSymbol | undefined {
+    const symbols = this.cppSymbols.get(name);
+    return symbols?.[0];
   }
 
   /**
-   * Issue #208: Get enum bit width for a typed enum
-   * @param enumName Name of the enum
-   * @returns Bit width or undefined if not a typed enum
+   * Get all C++ symbols with a given name
    */
-  getEnumBitWidth(enumName: string): number | undefined {
-    return this.enumBitWidth.get(enumName);
+  getCppOverloads(name: string): TCppSymbol[] {
+    return this.cppSymbols.get(name) ?? [];
   }
 
   /**
-   * Issue #208: Get all enum bit widths for cache serialization
-   * @returns Map of enum name -> bit width
+   * Get C++ symbols by source file
    */
-  getAllEnumBitWidths(): Map<string, number> {
-    return this.enumBitWidth;
+  getCppSymbolsByFile(file: string): TCppSymbol[] {
+    return this.cppSymbolsByFile.get(file) ?? [];
   }
 
   /**
-   * Issue #208: Restore enum bit widths from cache
-   * @param bitWidths Map of enum name -> bit width
+   * Get all C++ symbols
    */
-  restoreEnumBitWidths(bitWidths: Map<string, number>): void {
-    for (const [enumName, width] of bitWidths) {
-      this.enumBitWidth.set(enumName, width);
+  getAllCppSymbols(): TCppSymbol[] {
+    const result: TCppSymbol[] = [];
+    for (const symbols of this.cppSymbols.values()) {
+      result.push(...symbols);
     }
+    return result;
   }
 
+  // ========================================================================
+  // Cross-Language Methods
+  // ========================================================================
+
   /**
-   * Get all fields for a struct
-   * @param structName Name of the struct
-   * @returns Map of field names to field info, or undefined if struct not found
+   * Get all symbols across all languages
    */
-  getStructFields(
-    structName: string,
-  ): Map<string, IStructFieldInfo> | undefined {
-    return this.structFields.get(structName);
+  getAllSymbols(): TAnySymbol[] {
+    return [
+      ...this.getAllTSymbols(),
+      ...this.getAllCSymbols(),
+      ...this.getAllCppSymbols(),
+    ];
   }
 
   /**
-   * Get all struct fields for cache serialization
-   * @returns Map of struct name -> (field name -> field info)
+   * Get first symbol matching a name across all languages.
+   * Searches TSymbol, then C, then C++ collections.
+   * Used by ISymbolLookup interface for constructor detection.
    */
-  getAllStructFields(): Map<string, Map<string, IStructFieldInfo>> {
-    return this.structFields;
+  getSymbol(name: string): TAnySymbol | undefined {
+    return (
+      this.getTSymbol(name) ?? this.getCSymbol(name) ?? this.getCppSymbol(name)
+    );
   }
 
   /**
-   * Restore struct fields from cache
-   * Merges cached fields into the existing structFields map
-   * @param fields Map of struct name -> (field name -> field info)
+   * Get all overloads for a name across all languages
    */
-  restoreStructFields(
-    fields: Map<string, Map<string, IStructFieldInfo>>,
-  ): void {
-    for (const [structName, fieldMap] of fields) {
-      // Get or create the struct's field map
-      let existingFields = this.structFields.get(structName);
-      if (!existingFields) {
-        existingFields = new Map();
-        this.structFields.set(structName, existingFields);
-      }
+  getOverloads(name: string): TAnySymbol[] {
+    return [
+      ...this.getTOverloads(name),
+      ...this.getCOverloads(name),
+      ...this.getCppOverloads(name),
+    ];
+  }
 
-      // Merge fields
-      for (const [fieldName, fieldInfo] of fieldMap) {
-        existingFields.set(fieldName, fieldInfo);
-      }
-    }
+  /**
+   * Get symbols by source file across all languages
+   */
+  getSymbolsByFile(file: string): TAnySymbol[] {
+    return [
+      ...this.getTSymbolsByFile(file),
+      ...this.getCSymbolsByFile(file),
+      ...this.getCppSymbolsByFile(file),
+    ];
   }
 
   /**
-   * Get struct names defined in a specific source file
-   * @param file Source file path
-   * @returns Array of struct names defined in that file
+   * Get symbols by source language
    */
-  getStructNamesByFile(file: string): string[] {
-    const fileSymbols = this.byFile.get(file) ?? [];
-    // Issue #196: Include any symbol that has struct fields registered
-    // The dual-parse strategy may register typedef'd anonymous structs as variables
-    // (e.g., "typedef struct { ... } Rectangle;" -> Rectangle has kind=variable)
-    // But the C parser still adds struct fields for it
-    const symbolNames = fileSymbols.map((s) => s.name);
-    return symbolNames.filter((name) => this.structFields.has(name));
+  getSymbolsByLanguage(lang: ESourceLanguage): TAnySymbol[] {
+    switch (lang) {
+      case ESourceLanguage.CNext:
+        return this.getAllTSymbols();
+      case ESourceLanguage.C:
+        return this.getAllCSymbols();
+      case ESourceLanguage.Cpp:
+        return this.getAllCppSymbols();
+    }
   }
 
   /**
-   * Clear all symbols
+   * Check if a symbol exists in any language
    */
-  clear(): void {
-    this.symbols.clear();
-    this.byFile.clear();
-    this.structFields.clear();
-    this.needsStructKeyword.clear();
-    this.enumBitWidth.clear();
+  hasSymbol(name: string): boolean {
+    return (
+      this.tSymbols.has(name) ||
+      this.cSymbols.has(name) ||
+      this.cppSymbols.has(name)
+    );
   }
 
   /**
-   * Get symbol count
+   * Get total symbol count
    */
   get size(): number {
+    return this.getTSize() + this.getCSize() + this.getCppSize();
+  }
+
+  /**
+   * Get C symbol count
+   */
+  getCSize(): number {
     let count = 0;
-    for (const symbols of this.symbols.values()) {
+    for (const symbols of this.cSymbols.values()) {
       count += symbols.length;
     }
     return count;
   }
 
+  /**
+   * Get C++ symbol count
+   */
+  getCppSize(): number {
+    let count = 0;
+    for (const symbols of this.cppSymbols.values()) {
+      count += symbols.length;
+    }
+    return count;
+  }
+
+  // ========================================================================
+  // Conflict Detection
+  // ========================================================================
+
+  /**
+   * Check if a symbol has conflicts
+   */
+  hasConflict(name: string): boolean {
+    const allSymbols = this.getOverloads(name);
+    if (allSymbols.length <= 1) {
+      return false;
+    }
+
+    return this.detectConflict(allSymbols) !== null;
+  }
+
+  /**
+   * Get all conflicts in the symbol table
+   * Per user requirement: Strict errors for cross-language conflicts
+   */
+  getConflicts(): IConflict[] {
+    const conflicts: IConflict[] = [];
+    const allNames = new Set<string>();
+
+    // Collect all symbol names from all languages
+    for (const name of this.tSymbols.keys()) allNames.add(name);
+    for (const name of this.cSymbols.keys()) allNames.add(name);
+    for (const name of this.cppSymbols.keys()) allNames.add(name);
+
+    for (const name of allNames) {
+      const symbols = this.getOverloads(name);
+      if (symbols.length <= 1) continue;
+
+      const conflict = this.detectConflict(symbols);
+      if (conflict) {
+        conflicts.push(conflict);
+      }
+    }
+
+    return conflicts;
+  }
+
   /**
    * Detect if a set of symbols with the same name represents a conflict
    */
-  private detectConflict(symbols: ISymbol[]): IConflict | null {
+  private detectConflict(symbols: TAnySymbol[]): IConflict | null {
     // Filter out pure declarations (extern in C) - they don't count as definitions
-    const definitions = symbols.filter((s) => !s.isDeclaration);
+    const definitions = symbols.filter(
+      (s) => !("isDeclaration" in s && s.isDeclaration),
+    );
 
     if (definitions.length <= 1) {
       // 0 or 1 definitions = no conflict
@@ -374,47 +550,58 @@ class SymbolTable {
     }
 
     // Issue #221: Filter out function parameters from conflict detection
-    // Function parameters have a parent (their containing function) but their name
-    // is NOT qualified with the parent prefix (unlike scope-level variables like Math_counter).
-    // Parameters with the same name in different functions are not conflicts.
+    // Function parameters have a parent but their name is NOT qualified with the parent prefix.
     const globalDefinitions = definitions.filter((def) => {
-      // If no parent, it's a global symbol - keep it
-      if (!def.parent) return true;
-
-      // Variables with a parent need special handling
-      if (def.kind === ESymbolKind.Variable) {
-        // Scope-level variables have qualified names (e.g., "Math_counter" with parent "Math")
-        // Function parameters have unqualified names (e.g., "x" with parent "Math_add")
-        // If the name starts with parent_, it's a scope-level variable - keep it
-        // If not, it's a function parameter - filter it out
-        const isQualifiedName = def.name.startsWith(def.parent + "_");
-        return isQualifiedName;
+      // C-Next variables with scope need special handling
+      if (
+        def.sourceLanguage === ESourceLanguage.CNext &&
+        def.kind === "variable"
+      ) {
+        // After sourceLanguage check, def is narrowed to TSymbol
+        // After kind check, def is narrowed to IVariableSymbol
+        // Global scope means no conflict filtering needed
+        if (def.scope.name === "") return true;
+        // Scope-level variables vs function parameters:
+        // We can't easily distinguish here, so keep all for now
+        return true;
+      }
+      // C/C++ symbols: check parent field
+      if ("parent" in def && def.parent) {
+        // Non-variable symbols with parents are kept
+        if (def.kind !== "variable") return true;
+        // Variables with parents might be function parameters - filter out
+        return false;
       }
-
-      // Non-variable symbols with parents (functions, enums, etc.) are kept
       return true;
     });
 
     if (globalDefinitions.length <= 1) {
-      // After filtering parameters, 0 or 1 definitions = no conflict
       return null;
     }
 
     // Check for C++ function overloads (different signatures are OK)
-    const cppFunctions = definitions.filter(
-      (s) => s.sourceLanguage === ESourceLanguage.Cpp && s.signature,
+    const cppFunctions = globalDefinitions.filter(
+      (s) =>
+        s.sourceLanguage === ESourceLanguage.Cpp &&
+        s.kind === "function" &&
+        "parameters" in s,
     );
-    if (cppFunctions.length === definitions.length) {
-      // All are C++ functions with signatures
-      const uniqueSignatures = new Set(cppFunctions.map((s) => s.signature));
+    if (cppFunctions.length === globalDefinitions.length) {
+      // All are C++ functions with signatures - check for unique signatures
+      const signatures = cppFunctions.map((f) => {
+        if ("parameters" in f && f.parameters) {
+          const params = f.parameters as ReadonlyArray<{ type?: string }>;
+          return params.map((p) => p.type ?? "").join(",");
+        }
+        return "";
+      });
+      const uniqueSignatures = new Set(signatures);
       if (uniqueSignatures.size === cppFunctions.length) {
-        // All signatures are unique = valid overload, no conflict
         return null;
       }
     }
 
     // Check for cross-language conflict (C-Next vs C or C++)
-    // Issue #221: Use globalDefinitions for C-Next to exclude function parameters
     const cnextDefs = globalDefinitions.filter(
       (s) => s.sourceLanguage === ESourceLanguage.CNext,
     );
@@ -426,7 +613,6 @@ class SymbolTable {
     );
 
     if (cnextDefs.length > 0 && (cDefs.length > 0 || cppDefs.length > 0)) {
-      // C-Next + C/C++ conflict = ERROR
       const locations = globalDefinitions.map(
         (s) =>
           `${s.sourceLanguage.toUpperCase()} (${s.sourceFile}:${s.sourceLine})`,
@@ -441,26 +627,261 @@ class SymbolTable {
     }
 
     // Multiple definitions in same language (excluding overloads) = ERROR
+    // Issue #817: Group by scope AND kind - symbols in different scopes don't conflict,
+    // and symbols with different kinds (variable vs scope) don't conflict either
     if (cnextDefs.length > 1) {
-      const locations = cnextDefs.map((s) => `${s.sourceFile}:${s.sourceLine}`);
-      return {
-        symbolName: cnextDefs[0].name,
-        definitions: cnextDefs,
-        severity: "error",
-        message: `Symbol conflict: '${cnextDefs[0].name}' is defined multiple times in C-Next:\n  ${locations.join("\n  ")}`,
-      };
+      const byScopeAndKind = this.groupCNextSymbolsByScopeAndKind(cnextDefs);
+
+      // Check each scope+kind group for conflicts (multiple symbols in same scope with same kind)
+      for (const symbols of byScopeAndKind.values()) {
+        if (symbols.length > 1) {
+          const locations = symbols.map(
+            (s) => `${s.sourceFile}:${s.sourceLine}`,
+          );
+          const scopeName = symbols[0].scope.name;
+          const displayName =
+            scopeName === ""
+              ? symbols[0].name
+              : `${scopeName}.${symbols[0].name}`;
+          return {
+            symbolName: displayName,
+            definitions: symbols,
+            severity: "error",
+            message: `Symbol conflict: '${displayName}' is defined multiple times in C-Next:\n  ${locations.join("\n  ")}`,
+          };
+        }
+      }
     }
 
     // Same symbol in C and C++ - typically OK (same symbol)
-    // But if they have different types, might be a warning
     if (cDefs.length > 0 && cppDefs.length > 0) {
-      // For now, allow C/C++ to share symbols (common pattern)
       return null;
     }
 
     return null;
   }
 
+  /**
+   * Issue #817: Group C-Next symbols by scope name and kind.
+   *
+   * Symbols in different scopes don't conflict (Foo.enabled vs Bar.enabled
+   * generate Foo_enabled and Bar_enabled). Symbols with different kinds also
+   * don't conflict (variable LED vs scope LED are distinct).
+   *
+   * @param symbols C-Next symbols to group (must all be TSymbol)
+   * @returns Map from "scopeName:kind" key to array of symbols
+   */
+  private groupCNextSymbolsByScopeAndKind(
+    symbols: TAnySymbol[],
+  ): Map<string, TSymbol[]> {
+    const byScopeAndKind = new Map<string, TSymbol[]>();
+
+    for (const def of symbols) {
+      const tSymbol = def as TSymbol;
+      const scopeName = tSymbol.scope.name;
+      const key = `${scopeName}:${tSymbol.kind}`;
+      const existing = byScopeAndKind.get(key);
+      if (existing) {
+        existing.push(tSymbol);
+      } else {
+        byScopeAndKind.set(key, [tSymbol]);
+      }
+    }
+
+    return byScopeAndKind;
+  }
+
+  // ========================================================================
+  // Struct Field Information
+  // ========================================================================
+
+  /**
+   * Add struct field information
+   * @param structName Name of the struct
+   * @param fieldName Name of the field
+   * @param fieldType Type of the field (e.g., "uint32_t")
+   * @param arrayDimensions Optional array dimensions if field is an array
+   */
+  addStructField(
+    structName: string,
+    fieldName: string,
+    fieldType: string,
+    arrayDimensions?: number[],
+  ): void {
+    let fields = this.structFields.get(structName);
+    if (!fields) {
+      fields = new Map();
+      this.structFields.set(structName, fields);
+    }
+
+    fields.set(fieldName, {
+      type: fieldType,
+      arrayDimensions,
+    });
+  }
+
+  /**
+   * Get struct field type
+   * @param structName Name of the struct
+   * @param fieldName Name of the field
+   * @returns Field type or undefined if not found
+   */
+  getStructFieldType(
+    structName: string,
+    fieldName: string,
+  ): string | undefined {
+    const fields = this.structFields.get(structName);
+    return fields?.get(fieldName)?.type;
+  }
+
+  /**
+   * Get struct field info (type and array dimensions)
+   * @param structName Name of the struct
+   * @param fieldName Name of the field
+   * @returns Field info or undefined if not found
+   */
+  getStructFieldInfo(
+    structName: string,
+    fieldName: string,
+  ): IStructFieldInfo | undefined {
+    const fields = this.structFields.get(structName);
+    return fields?.get(fieldName);
+  }
+
+  /**
+   * Get all fields for a struct
+   * @param structName Name of the struct
+   * @returns Map of field names to field info, or undefined if struct not found
+   */
+  getStructFields(
+    structName: string,
+  ): Map<string, IStructFieldInfo> | undefined {
+    return this.structFields.get(structName);
+  }
+
+  /**
+   * Get all struct fields for cache serialization
+   * @returns Map of struct name -> (field name -> field info)
+   */
+  getAllStructFields(): Map<string, Map<string, IStructFieldInfo>> {
+    return this.structFields;
+  }
+
+  /**
+   * Restore struct fields from cache
+   * Merges cached fields into the existing structFields map
+   * @param fields Map of struct name -> (field name -> field info)
+   */
+  restoreStructFields(
+    fields: Map<string, Map<string, IStructFieldInfo>>,
+  ): void {
+    for (const [structName, fieldMap] of fields) {
+      let existingFields = this.structFields.get(structName);
+      if (!existingFields) {
+        existingFields = new Map();
+        this.structFields.set(structName, existingFields);
+      }
+
+      for (const [fieldName, fieldInfo] of fieldMap) {
+        existingFields.set(fieldName, fieldInfo);
+      }
+    }
+  }
+
+  /**
+   * Get struct names defined in a specific source file
+   * @param file Source file path
+   * @returns Array of struct names defined in that file
+   */
+  getStructNamesByFile(file: string): string[] {
+    const fileSymbols = this.getSymbolsByFile(file);
+    const symbolNames = fileSymbols.map((s) => s.name);
+    return symbolNames.filter((name) => this.structFields.has(name));
+  }
+
+  // ========================================================================
+  // Struct Keyword Tracking
+  // ========================================================================
+
+  /**
+   * Issue #196 Bug 3: Mark a struct as requiring 'struct' keyword in C
+   * @param structName Name of the struct (e.g., "NamedPoint")
+   */
+  markNeedsStructKeyword(structName: string): void {
+    this.needsStructKeyword.add(structName);
+  }
+
+  /**
+   * Issue #196 Bug 3: Check if a struct requires 'struct' keyword in C
+   * @param structName Name of the struct
+   * @returns true if the struct was defined as 'struct Name { ... }' without typedef
+   */
+  checkNeedsStructKeyword(structName: string): boolean {
+    return this.needsStructKeyword.has(structName);
+  }
+
+  /**
+   * Issue #196 Bug 3: Get all struct names requiring 'struct' keyword
+   * @returns Array of struct names
+   */
+  getAllNeedsStructKeyword(): string[] {
+    return Array.from(this.needsStructKeyword);
+  }
+
+  /**
+   * Issue #196 Bug 3: Restore needsStructKeyword from cache
+   * @param structNames Array of struct names requiring 'struct' keyword
+   */
+  restoreNeedsStructKeyword(structNames: string[]): void {
+    for (const name of structNames) {
+      this.needsStructKeyword.add(name);
+    }
+  }
+
+  // ========================================================================
+  // Enum Bit Width Tracking
+  // ========================================================================
+
+  /**
+   * Issue #208: Add enum bit width for a typed enum
+   * @param enumName Name of the enum (e.g., "EPressureType")
+   * @param bitWidth Bit width from backing type (e.g., 8 for uint8_t)
+   */
+  addEnumBitWidth(enumName: string, bitWidth: number): void {
+    this.enumBitWidth.set(enumName, bitWidth);
+  }
+
+  /**
+   * Issue #208: Get enum bit width for a typed enum
+   * @param enumName Name of the enum
+   * @returns Bit width or undefined if not a typed enum
+   */
+  getEnumBitWidth(enumName: string): number | undefined {
+    return this.enumBitWidth.get(enumName);
+  }
+
+  /**
+   * Issue #208: Get all enum bit widths for cache serialization
+   * @returns Map of enum name -> bit width
+   */
+  getAllEnumBitWidths(): Map<string, number> {
+    return this.enumBitWidth;
+  }
+
+  /**
+   * Issue #208: Restore enum bit widths from cache
+   * @param bitWidths Map of enum name -> bit width
+   */
+  restoreEnumBitWidths(bitWidths: Map<string, number>): void {
+    for (const [enumName, width] of bitWidths) {
+      this.enumBitWidth.set(enumName, width);
+    }
+  }
+
+  // ========================================================================
+  // External Array Dimension Resolution
+  // ========================================================================
+
   /**
    * Issue #461: Resolve external const array dimensions
    *
@@ -472,59 +893,102 @@ class SymbolTable {
    * external .cnx files that were not available during initial symbol collection.
    */
   resolveExternalArrayDimensions(): void {
-    // Build a map of all const values from the symbol table
+    const constValues = this.buildConstValuesMap();
+    if (constValues.size === 0) {
+      return;
+    }
+    this.resolveArrayDimensionsWithConstants(constValues);
+  }
+
+  /**
+   * Build a map of const variable names to their integer values.
+   */
+  private buildConstValuesMap(): Map<string, number> {
     const constValues = new Map<string, number>();
-    for (const symbol of this.getAllSymbols()) {
-      if (
-        symbol.kind === ESymbolKind.Variable &&
-        symbol.isConst &&
-        symbol.initialValue !== undefined
-      ) {
-        const value = LiteralUtils.parseIntegerLiteral(symbol.initialValue);
-        if (value !== undefined) {
-          constValues.set(symbol.name, value);
+    for (const symbol of this.getAllTSymbols()) {
+      if (symbol.kind === "variable" && symbol.isConst) {
+        // After kind check, symbol is narrowed to IVariableSymbol
+        if (symbol.initialValue !== undefined) {
+          const value = LiteralUtils.parseIntegerLiteral(symbol.initialValue);
+          if (value !== undefined) {
+            constValues.set(symbol.name, value);
+          }
         }
       }
     }
+    return constValues;
+  }
 
-    // If no const values found, nothing to resolve
-    if (constValues.size === 0) {
-      return;
-    }
-
-    // Scan all variable symbols for unresolved array dimensions
-    for (const symbol of this.getAllSymbols()) {
+  /**
+   * Resolve string array dimensions using const values lookup.
+   */
+  private resolveArrayDimensionsWithConstants(
+    constValues: Map<string, number>,
+  ): void {
+    for (const symbol of this.getAllTSymbols()) {
       if (
-        symbol.kind === ESymbolKind.Variable &&
+        symbol.kind === "variable" &&
         symbol.isArray &&
         symbol.arrayDimensions
       ) {
-        let modified = false;
-        const resolvedDimensions = symbol.arrayDimensions.map((dim) => {
-          // If dimension is numeric, keep it
-          const numericValue = Number.parseInt(dim, 10);
-          if (!Number.isNaN(numericValue)) {
-            return dim;
-          }
-
-          // Try to resolve from const values
-          const constValue = constValues.get(dim);
-          if (constValue !== undefined) {
-            modified = true;
-            return String(constValue);
-          }
-
-          // Keep original (unresolved macro reference)
-          return dim;
-        });
+        // After kind check, symbol is narrowed to IVariableSymbol
+        this.resolveVariableArrayDimensions(symbol, constValues);
+      }
+    }
+  }
 
-        if (modified) {
-          // Update the symbol's array dimensions
-          symbol.arrayDimensions = resolvedDimensions;
-        }
+  /**
+   * Resolve array dimensions for a single variable symbol.
+   */
+  private resolveVariableArrayDimensions(
+    variable: IVariableSymbol,
+    constValues: Map<string, number>,
+  ): void {
+    let modified = false;
+    const resolvedDimensions = variable.arrayDimensions!.map((dim) => {
+      if (typeof dim === "number") {
+        return dim;
       }
+      const constValue = constValues.get(dim);
+      if (constValue !== undefined) {
+        modified = true;
+        return constValue;
+      }
+      return dim;
+    });
+
+    if (modified) {
+      // Mutate in place - symbol is already in storage, cloning would require
+      // updating all maps. The readonly typing prevents accidental mutations
+      // elsewhere; this controlled mutation is intentional during resolution.
+      (
+        variable as unknown as { arrayDimensions: (number | string)[] }
+      ).arrayDimensions = resolvedDimensions;
     }
   }
+
+  // ========================================================================
+  // Clear / Reset
+  // ========================================================================
+
+  /**
+   * Clear all symbols
+   */
+  clear(): void {
+    // C-Next
+    this.tSymbols.clear();
+    this.tSymbolsByFile.clear();
+    // C
+    this.cSymbols.clear();
+    this.cSymbolsByFile.clear();
+    // C++
+    this.cppSymbols.clear();
+    this.cppSymbolsByFile.clear();
+    // Auxiliary
+    this.structFields.clear();
+    this.needsStructKeyword.clear();
+    this.enumBitWidth.clear();
+  }
 }
 
 export default SymbolTable;