c-next 0.1.70 → 0.1.72

package/src/transpiler/{logic/symbols/types → types/symbols}/IRegisterMemberInfo.ts

@@ -4,16 +4,16 @@
  */
 interface IRegisterMemberInfo {
   /** Offset from base address (as string to support expressions like "0x04") */
-  offset: string;
+  readonly offset: string;
 
   /** C type for the register (e.g., "uint32_t") */
-  cType: string;
+  readonly cType: string;
 
   /** Access mode for the register */
-  access: "rw" | "ro" | "wo" | "w1c" | "w1s";
+  readonly access: "rw" | "ro" | "wo" | "w1c" | "w1s";
 
   /** Optional bitmap type for structured bit access */
-  bitmapType?: string;
+  readonly bitmapType?: string;
 }
 
 export default IRegisterMemberInfo;

package/src/transpiler/types/symbols/IRegisterSymbol.ts

@@ -0,0 +1,18 @@
+import type IBaseSymbol from "./IBaseSymbol";
+import type IRegisterMemberInfo from "./IRegisterMemberInfo";
+
+/**
+ * Symbol representing a register block definition.
+ */
+interface IRegisterSymbol extends IBaseSymbol {
+  /** Discriminator narrowed to "register" */
+  readonly kind: "register";
+
+  /** Base address expression (as string, e.g., "0x40000000") */
+  readonly baseAddress: string;
+
+  /** Map of member name to register member metadata */
+  readonly members: ReadonlyMap<string, IRegisterMemberInfo>;
+}
+
+export default IRegisterSymbol;

package/src/transpiler/types/symbols/IScopeSymbol.ts

@@ -0,0 +1,32 @@
+import type IBaseSymbol from "./IBaseSymbol";
+import type IFunctionSymbol from "./IFunctionSymbol";
+import type TVisibility from "../TVisibility";
+
+/**
+ * Symbol representing a scope (namespace) definition.
+ * Scopes group related functions and variables.
+ *
+ * Note: IScopeSymbol has circular references with IFunctionSymbol.
+ * Functions have a scope, scopes contain functions.
+ */
+interface IScopeSymbol extends IBaseSymbol {
+  /** Discriminator narrowed to "scope" */
+  readonly kind: "scope";
+
+  /** Parent scope (global scope's parent is itself) */
+  readonly parent: IScopeSymbol;
+
+  /** List of member names (local names, not mangled) */
+  readonly members: string[];
+
+  /** Functions in this scope */
+  readonly functions: IFunctionSymbol[];
+
+  /** Variables in this scope */
+  readonly variables: unknown[];
+
+  /** Visibility of each member */
+  readonly memberVisibility: ReadonlyMap<string, TVisibility>;
+}
+
+export default IScopeSymbol;

package/src/transpiler/{logic/symbols/types → types/symbols}/IStructFieldInfo.ts

@@ -1,5 +1,6 @@
 /**
- * Struct field information
+ * Serialized struct field information for caching.
+ * Uses string types instead of TType for JSON serialization.
  */
 interface IStructFieldInfo {
   /** Field type (e.g., "uint32_t", "uint16_t") */

package/src/transpiler/types/symbols/IStructSymbol.ts

@@ -0,0 +1,15 @@
+import type IBaseSymbol from "./IBaseSymbol";
+import type IFieldInfo from "./IFieldInfo";
+
+/**
+ * Symbol representing a struct type definition.
+ */
+interface IStructSymbol extends IBaseSymbol {
+  /** Discriminator narrowed to "struct" */
+  readonly kind: "struct";
+
+  /** Map of field name to field metadata */
+  readonly fields: ReadonlyMap<string, IFieldInfo>;
+}
+
+export default IStructSymbol;

package/src/transpiler/types/symbols/IVariableSymbol.ts

@@ -0,0 +1,30 @@
+import type IBaseSymbol from "./IBaseSymbol";
+import type TType from "../TType";
+
+/**
+ * Symbol representing a variable (global, static, or extern).
+ */
+interface IVariableSymbol extends IBaseSymbol {
+  /** Discriminator narrowed to "variable" */
+  readonly kind: "variable";
+
+  /** Variable type */
+  readonly type: TType;
+
+  /** Whether this variable is const */
+  readonly isConst: boolean;
+
+  /** Whether this variable is atomic (volatile in C) */
+  readonly isAtomic: boolean;
+
+  /** Whether this variable is an array */
+  readonly isArray: boolean;
+
+  /** Array dimensions if isArray is true - numbers for resolved, strings for macros */
+  readonly arrayDimensions?: ReadonlyArray<number | string>;
+
+  /** Initial value expression (as string) */
+  readonly initialValue?: string;
+}
+
+export default IVariableSymbol;

package/src/transpiler/types/symbols/SymbolGuards.ts

@@ -0,0 +1,43 @@
+import type TSymbol from "./TSymbol";
+import type IFunctionSymbol from "./IFunctionSymbol";
+import type IScopeSymbol from "./IScopeSymbol";
+import type IStructSymbol from "./IStructSymbol";
+import type IEnumSymbol from "./IEnumSymbol";
+import type IVariableSymbol from "./IVariableSymbol";
+import type IBitmapSymbol from "./IBitmapSymbol";
+import type IRegisterSymbol from "./IRegisterSymbol";
+
+/**
+ * Type guard functions for TSymbol discriminated union.
+ */
+class SymbolGuards {
+  static isFunction(symbol: TSymbol): symbol is IFunctionSymbol {
+    return symbol.kind === "function";
+  }
+
+  static isScope(symbol: TSymbol): symbol is IScopeSymbol {
+    return symbol.kind === "scope";
+  }
+
+  static isStruct(symbol: TSymbol): symbol is IStructSymbol {
+    return symbol.kind === "struct";
+  }
+
+  static isEnum(symbol: TSymbol): symbol is IEnumSymbol {
+    return symbol.kind === "enum";
+  }
+
+  static isVariable(symbol: TSymbol): symbol is IVariableSymbol {
+    return symbol.kind === "variable";
+  }
+
+  static isBitmap(symbol: TSymbol): symbol is IBitmapSymbol {
+    return symbol.kind === "bitmap";
+  }
+
+  static isRegister(symbol: TSymbol): symbol is IRegisterSymbol {
+    return symbol.kind === "register";
+  }
+}
+
+export default SymbolGuards;

package/src/transpiler/types/symbols/TAnySymbol.ts

@@ -0,0 +1,22 @@
+import type TSymbol from "./TSymbol";
+import type TCSymbol from "./c/TCSymbol";
+import type TCppSymbol from "./cpp/TCppSymbol";
+
+/**
+ * Union of all symbol types across all supported languages (C-Next, C, C++).
+ *
+ * Use this type when handling symbols that could come from any source file type:
+ * - C-Next (.cnx) → TSymbol
+ * - C (.c, .h) → TCSymbol
+ * - C++ (.cpp, .hpp) → TCppSymbol
+ *
+ * The `sourceLanguage` field can be used to narrow the type:
+ * ```typescript
+ * if (symbol.sourceLanguage === ESourceLanguage.CNext) {
+ *   // TypeScript knows symbol is TSymbol here
+ * }
+ * ```
+ */
+type TAnySymbol = TSymbol | TCSymbol | TCppSymbol;
+
+export default TAnySymbol;

package/src/transpiler/types/symbols/TSymbol.ts

@@ -0,0 +1,32 @@
+import type IFunctionSymbol from "./IFunctionSymbol";
+import type IScopeSymbol from "./IScopeSymbol";
+import type IStructSymbol from "./IStructSymbol";
+import type IEnumSymbol from "./IEnumSymbol";
+import type IVariableSymbol from "./IVariableSymbol";
+import type IBitmapSymbol from "./IBitmapSymbol";
+import type IRegisterSymbol from "./IRegisterSymbol";
+
+/**
+ * Discriminated union of all C-Next symbol types.
+ *
+ * Use the `kind` field to narrow to a specific symbol type:
+ * ```typescript
+ * if (symbol.kind === "struct") {
+ *   // TypeScript knows symbol is IStructSymbol here
+ * }
+ * ```
+ *
+ * Note: For C and C++ symbols, use TCSymbol and TCppSymbol respectively.
+ * These are kept separate because C/C++ symbols have different properties
+ * (e.g., no scope reference, string types instead of TType).
+ */
+type TSymbol =
+  | IFunctionSymbol
+  | IScopeSymbol
+  | IStructSymbol
+  | IEnumSymbol
+  | IVariableSymbol
+  | IBitmapSymbol
+  | IRegisterSymbol;
+
+export default TSymbol;

package/src/transpiler/types/symbols/__tests__/IBaseSymbol.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import type IBaseSymbol from "../IBaseSymbol";
+import type TSymbolKindCNext from "../../symbol-kinds/TSymbolKindCNext";
+import ESourceLanguage from "../../../../utils/types/ESourceLanguage";
+
+describe("IBaseSymbol", () => {
+  it("accepts valid symbol with TSymbolKindCNext kind", () => {
+    // Create a mock scope for circular reference using object literal with self-reference
+    const mockScope: IBaseSymbol = {
+      kind: "scope",
+      name: "global",
+      scope: null as unknown as IBaseSymbol, // Will be set after creation
+      sourceFile: "test.cnx",
+      sourceLine: 1,
+      sourceLanguage: ESourceLanguage.CNext,
+      isExported: true,
+    };
+    // Use Object.defineProperty to set the circular reference
+    Object.defineProperty(mockScope, "scope", { value: mockScope });
+
+    const symbol: IBaseSymbol = {
+      kind: "function" as TSymbolKindCNext,
+      name: "testFunc",
+      scope: mockScope,
+      sourceFile: "test.cnx",
+      sourceLine: 10,
+      sourceLanguage: ESourceLanguage.CNext,
+      isExported: true,
+    };
+
+    expect(symbol.kind).toBe("function");
+    expect(symbol.name).toBe("testFunc");
+    expect(symbol.sourceLanguage).toBe(ESourceLanguage.CNext);
+  });
+
+  it("kind field accepts all TSymbolKindCNext values", () => {
+    const validKinds: TSymbolKindCNext[] = [
+      "function",
+      "variable",
+      "struct",
+      "enum",
+      "enum_member",
+      "bitmap",
+      "bitmap_field",
+      "register",
+      "register_member",
+      "scope",
+    ];
+
+    // Type check - if this compiles, the types are correct
+    validKinds.forEach((kind) => {
+      const partial: Pick<IBaseSymbol, "kind"> = { kind };
+      expect(partial.kind).toBe(kind);
+    });
+  });
+});

package/src/transpiler/types/symbols/__tests__/SymbolGuards.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import SymbolGuards from "../SymbolGuards";
+import type TSymbol from "../TSymbol";
+import type IFunctionSymbol from "../IFunctionSymbol";
+import type IStructSymbol from "../IStructSymbol";
+import ESourceLanguage from "../../../../utils/types/ESourceLanguage";
+
+describe("SymbolGuards", () => {
+  // Helper to create a minimal mock symbol
+  const createMockSymbol = (kind: string): TSymbol => {
+    const mockScope = { kind: "scope" } as unknown;
+    (mockScope as { scope: unknown }).scope = mockScope;
+
+    return {
+      kind,
+      name: "test",
+      scope: mockScope,
+      sourceFile: "test.cnx",
+      sourceLine: 1,
+      sourceLanguage: ESourceLanguage.CNext,
+      isExported: true,
+    } as TSymbol;
+  };
+
+  it("isFunction returns true for function symbols", () => {
+    const funcSymbol = {
+      ...createMockSymbol("function"),
+      parameters: [],
+      returnType: { kind: "primitive", primitive: "void" },
+      visibility: "public",
+      body: null,
+    } as IFunctionSymbol;
+
+    expect(SymbolGuards.isFunction(funcSymbol)).toBe(true);
+    expect(SymbolGuards.isStruct(funcSymbol)).toBe(false);
+  });
+
+  it("isStruct returns true for struct symbols", () => {
+    const structSymbol = {
+      ...createMockSymbol("struct"),
+      fields: new Map(),
+    } as IStructSymbol;
+
+    expect(SymbolGuards.isStruct(structSymbol)).toBe(true);
+    expect(SymbolGuards.isFunction(structSymbol)).toBe(false);
+  });
+
+  it("all guards return false for non-matching kinds", () => {
+    const funcSymbol = createMockSymbol("function") as TSymbol;
+
+    expect(SymbolGuards.isScope(funcSymbol)).toBe(false);
+    expect(SymbolGuards.isEnum(funcSymbol)).toBe(false);
+    expect(SymbolGuards.isVariable(funcSymbol)).toBe(false);
+    expect(SymbolGuards.isBitmap(funcSymbol)).toBe(false);
+    expect(SymbolGuards.isRegister(funcSymbol)).toBe(false);
+  });
+});

package/src/transpiler/types/symbols/c/ICBaseSymbol.ts

@@ -0,0 +1,28 @@
+import type TSymbolKindC from "../../symbol-kinds/TSymbolKindC";
+import type ESourceLanguage from "../../../../utils/types/ESourceLanguage";
+
+/**
+ * Base interface for all C language symbol types.
+ * C symbols use simple strings for types since they pass through to codegen unchanged.
+ */
+interface ICBaseSymbol {
+  /** Symbol kind - discriminator for type narrowing */
+  readonly kind: TSymbolKindC;
+
+  /** Symbol name */
+  readonly name: string;
+
+  /** Source file where the symbol is defined */
+  readonly sourceFile: string;
+
+  /** Line number in the source file */
+  readonly sourceLine: number;
+
+  /** Source language - always C for C symbols */
+  readonly sourceLanguage: ESourceLanguage.C;
+
+  /** Whether this symbol is exported/public */
+  readonly isExported: boolean;
+}
+
+export default ICBaseSymbol;

package/src/transpiler/types/symbols/c/ICEnumMemberSymbol.ts

@@ -0,0 +1,17 @@
+import type ICBaseSymbol from "./ICBaseSymbol";
+
+/**
+ * Symbol representing a C enum member.
+ */
+interface ICEnumMemberSymbol extends ICBaseSymbol {
+  /** Discriminator narrowed to "enum_member" */
+  readonly kind: "enum_member";
+
+  /** Parent enum name */
+  readonly parent: string;
+
+  /** Optional explicit value */
+  readonly value?: number;
+}
+
+export default ICEnumMemberSymbol;

package/src/transpiler/types/symbols/c/ICEnumSymbol.ts

@@ -0,0 +1,17 @@
+import type ICBaseSymbol from "./ICBaseSymbol";
+
+/**
+ * Symbol representing a C enum type definition.
+ */
+interface ICEnumSymbol extends ICBaseSymbol {
+  /** Discriminator narrowed to "enum" */
+  readonly kind: "enum";
+
+  /** Enum members with their values */
+  readonly members: ReadonlyArray<{
+    readonly name: string;
+    readonly value?: number;
+  }>;
+}
+
+export default ICEnumSymbol;

package/src/transpiler/types/symbols/c/ICFieldInfo.ts

@@ -0,0 +1,16 @@
+/**
+ * Metadata for a C struct field.
+ * Uses simple strings for types since C types pass through unchanged.
+ */
+interface ICFieldInfo {
+  /** Field name */
+  readonly name: string;
+
+  /** Field type as string (e.g., "int", "char*") */
+  readonly type: string;
+
+  /** Array dimensions if this field is an array */
+  readonly arrayDimensions?: ReadonlyArray<number>;
+}
+
+export default ICFieldInfo;

package/src/transpiler/types/symbols/c/ICFunctionSymbol.ts

@@ -0,0 +1,21 @@
+import type ICBaseSymbol from "./ICBaseSymbol";
+import type ICParameterInfo from "./ICParameterInfo";
+
+/**
+ * Symbol representing a C function definition or declaration.
+ */
+interface ICFunctionSymbol extends ICBaseSymbol {
+  /** Discriminator narrowed to "function" */
+  readonly kind: "function";
+
+  /** Return type as string */
+  readonly type: string;
+
+  /** Function parameters */
+  readonly parameters?: ReadonlyArray<ICParameterInfo>;
+
+  /** Whether this is a declaration (prototype) vs definition */
+  readonly isDeclaration?: boolean;
+}
+
+export default ICFunctionSymbol;

package/src/transpiler/types/symbols/c/ICParameterInfo.ts

@@ -0,0 +1,19 @@
+/**
+ * Parameter info for C functions.
+ * Uses simple strings for types since C types pass through unchanged.
+ */
+interface ICParameterInfo {
+  /** Parameter name (may be empty for prototypes) */
+  readonly name: string;
+
+  /** Parameter type as string (e.g., "int", "const char*") */
+  readonly type: string;
+
+  /** Whether this parameter is const */
+  readonly isConst: boolean;
+
+  /** Whether this parameter is an array */
+  readonly isArray: boolean;
+}
+
+export default ICParameterInfo;

package/src/transpiler/types/symbols/c/ICStructSymbol.ts

@@ -0,0 +1,21 @@
+import type ICBaseSymbol from "./ICBaseSymbol";
+import type ICFieldInfo from "./ICFieldInfo";
+
+/**
+ * Symbol representing a C struct or union type definition.
+ */
+interface ICStructSymbol extends ICBaseSymbol {
+  /** Discriminator narrowed to "struct" */
+  readonly kind: "struct";
+
+  /** Whether this is a union (true) or struct (false) */
+  readonly isUnion: boolean;
+
+  /** Map of field name to field metadata (only populated if SymbolTable was provided) */
+  readonly fields?: ReadonlyMap<string, ICFieldInfo>;
+
+  /** Whether this struct requires 'struct' keyword when referenced */
+  readonly needsStructKeyword?: boolean;
+}
+
+export default ICStructSymbol;

package/src/transpiler/types/symbols/c/ICTypedefSymbol.ts

@@ -0,0 +1,14 @@
+import type ICBaseSymbol from "./ICBaseSymbol";
+
+/**
+ * Symbol representing a C typedef.
+ */
+interface ICTypedefSymbol extends ICBaseSymbol {
+  /** Discriminator narrowed to "type" */
+  readonly kind: "type";
+
+  /** The underlying type being aliased */
+  readonly type: string;
+}
+
+export default ICTypedefSymbol;

package/src/transpiler/types/symbols/c/ICVariableSymbol.ts

@@ -0,0 +1,26 @@
+import type ICBaseSymbol from "./ICBaseSymbol";
+
+/**
+ * Symbol representing a C variable.
+ */
+interface ICVariableSymbol extends ICBaseSymbol {
+  /** Discriminator narrowed to "variable" */
+  readonly kind: "variable";
+
+  /** Variable type as string */
+  readonly type: string;
+
+  /** Whether this variable is const */
+  readonly isConst?: boolean;
+
+  /** Whether this variable is extern */
+  readonly isExtern?: boolean;
+
+  /** Whether this variable is an array */
+  readonly isArray?: boolean;
+
+  /** Array dimensions if this is an array */
+  readonly arrayDimensions?: ReadonlyArray<number | string>;
+}
+
+export default ICVariableSymbol;

package/src/transpiler/types/symbols/c/TCSymbol.ts

@@ -0,0 +1,26 @@
+import type ICStructSymbol from "./ICStructSymbol";
+import type ICEnumSymbol from "./ICEnumSymbol";
+import type ICEnumMemberSymbol from "./ICEnumMemberSymbol";
+import type ICFunctionSymbol from "./ICFunctionSymbol";
+import type ICVariableSymbol from "./ICVariableSymbol";
+import type ICTypedefSymbol from "./ICTypedefSymbol";
+
+/**
+ * Discriminated union of all C language symbol types.
+ *
+ * Use the `kind` field to narrow to a specific symbol type:
+ * ```typescript
+ * if (symbol.kind === "struct") {
+ *   // TypeScript knows symbol is ICStructSymbol here
+ * }
+ * ```
+ */
+type TCSymbol =
+  | ICStructSymbol
+  | ICEnumSymbol
+  | ICEnumMemberSymbol
+  | ICFunctionSymbol
+  | ICVariableSymbol
+  | ICTypedefSymbol;
+
+export default TCSymbol;

package/src/transpiler/types/symbols/cpp/ICppBaseSymbol.ts

@@ -0,0 +1,31 @@
+import type TSymbolKindCpp from "../../symbol-kinds/TSymbolKindCpp";
+import type ESourceLanguage from "../../../../utils/types/ESourceLanguage";
+
+/**
+ * Base interface for all C++ language symbol types.
+ * C++ symbols use simple strings for types since they pass through to codegen unchanged.
+ */
+interface ICppBaseSymbol {
+  /** Symbol kind - discriminator for type narrowing */
+  readonly kind: TSymbolKindCpp;
+
+  /** Symbol name */
+  readonly name: string;
+
+  /** Source file where the symbol is defined */
+  readonly sourceFile: string;
+
+  /** Line number in the source file */
+  readonly sourceLine: number;
+
+  /** Source language - always Cpp for C++ symbols */
+  readonly sourceLanguage: ESourceLanguage.Cpp;
+
+  /** Whether this symbol is exported/public */
+  readonly isExported: boolean;
+
+  /** Parent namespace or class name */
+  readonly parent?: string;
+}
+
+export default ICppBaseSymbol;

package/src/transpiler/types/symbols/cpp/ICppClassSymbol.ts

@@ -0,0 +1,15 @@
+import type ICppBaseSymbol from "./ICppBaseSymbol";
+import type ICppFieldInfo from "./ICppFieldInfo";
+
+/**
+ * Symbol representing a C++ class or struct type definition.
+ */
+interface ICppClassSymbol extends ICppBaseSymbol {
+  /** Discriminator narrowed to "class" */
+  readonly kind: "class";
+
+  /** Map of field name to field metadata (only populated if SymbolTable was provided) */
+  readonly fields?: ReadonlyMap<string, ICppFieldInfo>;
+}
+
+export default ICppClassSymbol;

package/src/transpiler/types/symbols/cpp/ICppEnumMemberSymbol.ts

@@ -0,0 +1,14 @@
+import type ICppBaseSymbol from "./ICppBaseSymbol";
+
+/**
+ * Symbol representing a C++ enum member.
+ */
+interface ICppEnumMemberSymbol extends ICppBaseSymbol {
+  /** Discriminator narrowed to "enum_member" */
+  readonly kind: "enum_member";
+
+  /** Optional explicit value */
+  readonly value?: number;
+}
+
+export default ICppEnumMemberSymbol;

package/src/transpiler/types/symbols/cpp/ICppEnumSymbol.ts

@@ -0,0 +1,14 @@
+import type ICppBaseSymbol from "./ICppBaseSymbol";
+
+/**
+ * Symbol representing a C++ enum type definition.
+ */
+interface ICppEnumSymbol extends ICppBaseSymbol {
+  /** Discriminator narrowed to "enum" */
+  readonly kind: "enum";
+
+  /** Optional bit width for typed enums (e.g., 8 for uint8_t backing type) */
+  readonly bitWidth?: number;
+}
+
+export default ICppEnumSymbol;

package/src/transpiler/types/symbols/cpp/ICppFieldInfo.ts

@@ -0,0 +1,16 @@
+/**
+ * Metadata for a C++ class/struct field.
+ * Uses simple strings for types since C++ types pass through unchanged.
+ */
+interface ICppFieldInfo {
+  /** Field name */
+  readonly name: string;
+
+  /** Field type as string (e.g., "int", "std::string") */
+  readonly type: string;
+
+  /** Array dimensions if this field is an array */
+  readonly arrayDimensions?: ReadonlyArray<number>;
+}
+
+export default ICppFieldInfo;