c-next 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c-next",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A safer C for embedded systems development. Transpiles to clean, readable C.",
   "packageManager": "npm@11.9.0",
   "type": "module",

package/src/lib/__tests__/parseWithSymbols.test.ts

@@ -236,4 +236,232 @@ describe("parseWithSymbols", () => {
       expect(bitmap).toBeDefined();
     });
   });
+
+  describe("id and parentId fields (Issue #823)", () => {
+    it("top-level function has id=name, no parentId", () => {
+      const source = `void setup() { }`;
+
+      const result = parseWithSymbols(source);
+
+      const func = result.symbols.find((s) => s.name === "setup");
+      expect(func?.id).toBe("setup");
+      expect(func?.parentId).toBeUndefined();
+    });
+
+    it("top-level variable has id=name, no parentId", () => {
+      const source = `u32 counter <- 0;`;
+
+      const result = parseWithSymbols(source);
+
+      const variable = result.symbols.find((s) => s.name === "counter");
+      expect(variable?.id).toBe("counter");
+      expect(variable?.parentId).toBeUndefined();
+    });
+
+    it("scope has id=name, no parentId", () => {
+      const source = `scope LED { }`;
+
+      const result = parseWithSymbols(source);
+
+      const scope = result.symbols.find((s) => s.name === "LED");
+      expect(scope?.id).toBe("LED");
+      expect(scope?.parentId).toBeUndefined();
+    });
+
+    it("scope method has id=Scope.method, parentId=Scope", () => {
+      const source = `
+        scope LED {
+          public void toggle() { }
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const func = result.symbols.find((s) => s.name === "toggle");
+      expect(func?.id).toBe("LED.toggle");
+      expect(func?.parentId).toBe("LED");
+    });
+
+    it("scope variable has id=Scope.varName, parentId=Scope", () => {
+      const source = `
+        scope LED {
+          u8 pin <- 13;
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const variable = result.symbols.find((s) => s.name === "pin");
+      expect(variable?.id).toBe("LED.pin");
+      expect(variable?.parentId).toBe("LED");
+    });
+
+    it("enum has id=name, no parentId", () => {
+      const source = `
+        enum Color {
+          RED,
+          GREEN
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const enumSym = result.symbols.find(
+        (s) => s.name === "Color" && s.kind === "enum",
+      );
+      expect(enumSym?.id).toBe("Color");
+      expect(enumSym?.parentId).toBeUndefined();
+    });
+
+    it("enum member has id=Enum.member, parentId=Enum", () => {
+      const source = `
+        enum Color {
+          RED,
+          GREEN
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const member = result.symbols.find(
+        (s) => s.name === "RED" && s.kind === "enumMember",
+      );
+      expect(member?.id).toBe("Color.RED");
+      expect(member?.parentId).toBe("Color");
+    });
+
+    it("bitmap has id=name, no parentId", () => {
+      const source = `
+        bitmap8 Flags {
+          a, b, c, d, e, f, g, h
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const bitmap = result.symbols.find(
+        (s) => s.name === "Flags" && s.kind === "bitmap",
+      );
+      expect(bitmap?.id).toBe("Flags");
+      expect(bitmap?.parentId).toBeUndefined();
+    });
+
+    it("bitmap field has id=Bitmap.field, parentId=Bitmap", () => {
+      const source = `
+        bitmap8 Flags {
+          a, b, c, d, e, f, g, h
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const field = result.symbols.find(
+        (s) => s.name === "a" && s.kind === "bitmapField",
+      );
+      expect(field?.id).toBe("Flags.a");
+      expect(field?.parentId).toBe("Flags");
+    });
+
+    it("register in scope has nested id path", () => {
+      const source = `
+        scope Board {
+          register GPIO @ 0x40000000 {
+            DR: u32 rw @ 0x00,
+          }
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const register = result.symbols.find(
+        (s) => s.name === "GPIO" && s.kind === "register",
+      );
+      expect(register?.id).toBe("Board.GPIO");
+      expect(register?.parentId).toBe("Board");
+    });
+
+    it("register member has id=Scope.Register.member", () => {
+      const source = `
+        scope Board {
+          register GPIO @ 0x40000000 {
+            DR: u32 rw @ 0x00,
+          }
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const member = result.symbols.find(
+        (s) => s.name === "DR" && s.kind === "registerMember",
+      );
+      expect(member?.id).toBe("Board.GPIO.DR");
+      expect(member?.parentId).toBe("Board.GPIO");
+    });
+
+    it("struct has correct id and parentId", () => {
+      const source = `
+        struct Point {
+          i32 x;
+          i32 y;
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const struct = result.symbols.find((s) => s.name === "Point");
+      expect(struct?.id).toBe("Point");
+      expect(struct?.parentId).toBeUndefined();
+    });
+
+    it("struct field has id=Struct.field, parentId=Struct", () => {
+      const source = `
+        struct Point {
+          i32 x;
+          i32 y;
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const fieldX = result.symbols.find(
+        (s) => s.name === "x" && s.kind === "field",
+      );
+      expect(fieldX?.id).toBe("Point.x");
+      expect(fieldX?.parentId).toBe("Point");
+      expect(fieldX?.type).toBe("i32");
+
+      const fieldY = result.symbols.find(
+        (s) => s.name === "y" && s.kind === "field",
+      );
+      expect(fieldY?.id).toBe("Point.y");
+      expect(fieldY?.parentId).toBe("Point");
+    });
+
+    it("struct field in scope has nested id path", () => {
+      const source = `
+        scope Geometry {
+          struct Vector {
+            f32 x;
+            f32 y;
+            f32 z;
+          }
+        }
+      `;
+
+      const result = parseWithSymbols(source);
+
+      const struct = result.symbols.find(
+        (s) => s.name === "Vector" && s.kind === "struct",
+      );
+      expect(struct?.id).toBe("Geometry.Vector");
+      expect(struct?.parentId).toBe("Geometry");
+
+      const fieldX = result.symbols.find(
+        (s) => s.name === "x" && s.kind === "field",
+      );
+      expect(fieldX?.id).toBe("Geometry.Vector.x");
+      expect(fieldX?.parentId).toBe("Geometry.Vector");
+      expect(fieldX?.type).toBe("f32");
+    });
+  });
 });

package/src/lib/parseCHeader.ts

@@ -11,6 +11,7 @@ import ISymbolInfo from "./types/ISymbolInfo";
 import IParseWithSymbolsResult from "./types/IParseWithSymbolsResult";
 import TSymbolKind from "./types/TSymbolKind";
 import TCSymbol from "../transpiler/types/symbols/c/TCSymbol";
+import SymbolPathUtils from "./utils/SymbolPathUtils";
 
 /**
  * Map TCSymbol kind to library TSymbolKind
@@ -63,10 +64,13 @@ function convertTCSymbolsToISymbolInfo(
       // struct and enum have no type field
     }
 
+    const id = SymbolPathUtils.buildSimpleDotPath(parent, sym.name);
     return {
       name: sym.name,
-      fullName: parent ? `${parent}.${sym.name}` : sym.name,
+      fullName: SymbolPathUtils.buildSimpleDotPath(parent, sym.name),
       kind: mapCSymbolKind(sym.kind),
+      id,
+      parentId: parent,
       type,
       parent,
       line: sym.sourceLine ?? 0,

package/src/lib/parseWithSymbols.ts

@@ -10,10 +10,16 @@ import TypeResolver from "../utils/TypeResolver";
 import ISymbolInfo from "./types/ISymbolInfo";
 import IParseWithSymbolsResult from "./types/IParseWithSymbolsResult";
 import TSymbol from "../transpiler/types/symbols/TSymbol";
+import SymbolPathUtils from "./utils/SymbolPathUtils";
+
+// Re-export helpers for use in this module
+const buildScopePath = SymbolPathUtils.buildScopePath;
+const getDotPathId = SymbolPathUtils.getDotPathId;
+const getParentId = SymbolPathUtils.getParentId;
 
 /**
  * ADR-055 Phase 7: Convert TSymbol directly to ISymbolInfo array.
- * Expands compound symbols (bitmaps, enums, registers) into multiple ISymbolInfo entries.
+ * Expands compound symbols (bitmaps, enums, structs, registers) into multiple ISymbolInfo entries.
  */
 function convertTSymbolsToISymbolInfo(symbols: TSymbol[]): ISymbolInfo[] {
   const result: ISymbolInfo[] = [];
@@ -27,7 +33,7 @@ function convertTSymbolsToISymbolInfo(symbols: TSymbol[]): ISymbolInfo[] {
         result.push(...convertEnum(symbol));
         break;
       case "struct":
-        result.push(convertStruct(symbol));
+        result.push(...convertStruct(symbol));
         break;
       case "function":
         result.push(...convertFunction(symbol));
@@ -53,6 +59,8 @@ function convertBitmap(
   const result: ISymbolInfo[] = [];
   const mangledName = SymbolNameUtils.getMangledName(bitmap);
   const parent = bitmap.scope.name || undefined;
+  const bitmapId = getDotPathId(bitmap);
+  const bitmapParentId = getParentId(bitmap.scope);
 
   result.push({
     name: bitmap.name,
@@ -60,6 +68,8 @@ function convertBitmap(
     kind: "bitmap",
     type: bitmap.backingType,
     parent,
+    id: bitmapId,
+    parentId: bitmapParentId,
     line: bitmap.sourceLine,
   });
 
@@ -70,6 +80,8 @@ function convertBitmap(
       fullName: `${mangledName}.${fieldName}`,
       kind: "bitmapField",
       parent: mangledName,
+      id: `${bitmapId}.${fieldName}`,
+      parentId: bitmapId,
       line: bitmap.sourceLine,
       size: fieldInfo.width,
     });
@@ -84,12 +96,16 @@ function convertEnum(
   const result: ISymbolInfo[] = [];
   const mangledName = SymbolNameUtils.getMangledName(enumSym);
   const parent = enumSym.scope.name || undefined;
+  const enumId = getDotPathId(enumSym);
+  const enumParentId = getParentId(enumSym.scope);
 
   result.push({
     name: enumSym.name,
     fullName: mangledName,
     kind: "enum",
     parent,
+    id: enumId,
+    parentId: enumParentId,
     line: enumSym.sourceLine,
   });
 
@@ -100,6 +116,8 @@ function convertEnum(
       fullName: `${mangledName}_${memberName}`,
       kind: "enumMember",
       parent: mangledName,
+      id: `${enumId}.${memberName}`,
+      parentId: enumId,
       line: enumSym.sourceLine,
     });
   }
@@ -109,17 +127,38 @@ function convertEnum(
 
 function convertStruct(
   struct: import("../transpiler/types/symbols/IStructSymbol").default,
-): ISymbolInfo {
+): ISymbolInfo[] {
+  const result: ISymbolInfo[] = [];
   const mangledName = SymbolNameUtils.getMangledName(struct);
   const parent = struct.scope.name || undefined;
+  const structId = getDotPathId(struct);
+  const structParentId = getParentId(struct.scope);
 
-  return {
+  result.push({
     name: struct.name,
     fullName: mangledName,
     kind: "struct",
     parent,
+    id: structId,
+    parentId: structParentId,
     line: struct.sourceLine,
-  };
+  });
+
+  // Add struct fields
+  for (const [fieldName, fieldInfo] of struct.fields) {
+    result.push({
+      name: fieldName,
+      fullName: `${mangledName}.${fieldName}`,
+      kind: "field",
+      type: TypeResolver.getTypeName(fieldInfo.type),
+      parent: mangledName,
+      id: `${structId}.${fieldName}`,
+      parentId: structId,
+      line: struct.sourceLine,
+    });
+  }
+
+  return result;
 }
 
 function convertFunction(
@@ -142,6 +181,8 @@ function convertFunction(
     kind: "function",
     type: returnType,
     parent,
+    id: getDotPathId(func),
+    parentId: getParentId(func.scope),
     signature,
     accessModifier: func.isExported ? "public" : "private",
     line: func.sourceLine,
@@ -163,6 +204,8 @@ function convertVariable(
     kind: "variable",
     type: typeStr,
     parent,
+    id: getDotPathId(variable),
+    parentId: getParentId(variable.scope),
     line: variable.sourceLine,
   };
 }
@@ -173,12 +216,16 @@ function convertRegister(
   const result: ISymbolInfo[] = [];
   const mangledName = SymbolNameUtils.getMangledName(register);
   const parent = register.scope.name || undefined;
+  const registerId = getDotPathId(register);
+  const registerParentId = getParentId(register.scope);
 
   result.push({
     name: register.name,
     fullName: mangledName,
     kind: "register",
     parent,
+    id: registerId,
+    parentId: registerParentId,
     line: register.sourceLine,
   });
 
@@ -189,6 +236,8 @@ function convertRegister(
       fullName: `${mangledName}.${memberName}`,
       kind: "registerMember",
       parent: mangledName,
+      id: `${registerId}.${memberName}`,
+      parentId: registerId,
       accessModifier: memberInfo.access,
       line: register.sourceLine,
     });
@@ -200,10 +249,18 @@ function convertRegister(
 function convertScope(
   scope: import("../transpiler/types/symbols/IScopeSymbol").default,
 ): ISymbolInfo {
+  const scopeId = buildScopePath(scope);
+  const scopeParentId =
+    scope.parent && scope.parent.name !== ""
+      ? buildScopePath(scope.parent)
+      : undefined;
+
   return {
     name: scope.name,
     fullName: scope.name,
     kind: "namespace",
+    id: scopeId,
+    parentId: scopeParentId,
     line: scope.sourceLine,
   };
 }

package/src/lib/types/ISymbolInfo.ts

@@ -12,6 +12,10 @@ interface ISymbolInfo {
   fullName: string;
   /** Kind of symbol */
   kind: TSymbolKind;
+  /** Dot-path identifier matching C-Next syntax (e.g., "LED.toggle", "Color.Red") */
+  id: string;
+  /** Parent's dot-path identifier (e.g., "LED" for "LED.toggle"), absent for top-level */
+  parentId?: string;
   /** Type of the symbol (e.g., "void", "u32") */
   type?: string;
   /** Parent namespace/class/register name */

package/src/lib/utils/SymbolPathUtils.ts

@@ -0,0 +1,87 @@
+/**
+ * Utility functions for building dot-path identifiers for symbols.
+ * Used by parseWithSymbols and parseCHeader to generate unique symbol IDs.
+ */
+
+import IScopeSymbol from "../../transpiler/types/symbols/IScopeSymbol";
+
+/**
+ * Build the dot-path for a scope by walking up the parent chain.
+ * Returns empty string for global scope.
+ *
+ * @example
+ * // For scope "GPIO7" with parent "Teensy4":
+ * buildScopePath(gpio7Scope) // => "Teensy4.GPIO7"
+ */
+function buildScopePath(scope: { name: string; parent?: unknown }): string {
+  if (scope.name === "") {
+    return "";
+  }
+
+  const parts: string[] = [scope.name];
+  let current = scope.parent as IScopeSymbol | undefined;
+
+  // Walk up the parent chain, stopping at global scope or circular reference
+  while (current && current.name !== "" && current !== current.parent) {
+    parts.unshift(current.name);
+    current = current.parent as IScopeSymbol | undefined;
+  }
+
+  return parts.join(".");
+}
+
+/**
+ * Get the dot-path ID for a symbol (e.g., "LED.toggle", "Color.Red").
+ * For top-level symbols, returns just the name.
+ *
+ * @example
+ * getDotPathId({ name: "toggle", scope: { name: "LED" } }) // => "LED.toggle"
+ * getDotPathId({ name: "setup", scope: { name: "" } })     // => "setup"
+ */
+function getDotPathId(symbol: {
+  name: string;
+  scope: { name: string; parent?: unknown };
+}): string {
+  const scopePath = buildScopePath(symbol.scope);
+  if (scopePath === "") {
+    return symbol.name;
+  }
+  return `${scopePath}.${symbol.name}`;
+}
+
+/**
+ * Get the parentId for a symbol (the dot-path of its parent scope).
+ * Returns undefined for top-level symbols.
+ *
+ * @example
+ * getParentId({ name: "LED" })  // => "LED"
+ * getParentId({ name: "" })     // => undefined (global scope)
+ */
+function getParentId(scope: {
+  name: string;
+  parent?: unknown;
+}): string | undefined {
+  const scopePath = buildScopePath(scope);
+  return scopePath === "" ? undefined : scopePath;
+}
+
+/**
+ * Build a simple dot-path from parent and name.
+ * Used for C headers where there's no scope chain.
+ *
+ * @example
+ * buildSimpleDotPath("Color", "RED") // => "Color.RED"
+ * buildSimpleDotPath(undefined, "myFunc") // => "myFunc"
+ */
+function buildSimpleDotPath(parent: string | undefined, name: string): string {
+  return parent ? `${parent}.${name}` : name;
+}
+
+class SymbolPathUtils {
+  static readonly buildScopePath = buildScopePath;
+  static readonly getDotPathId = getDotPathId;
+  static readonly getParentId = getParentId;
+  static readonly buildSimpleDotPath = buildSimpleDotPath;
+}
+
+export default SymbolPathUtils;

package/src/lib/utils/__tests__/SymbolPathUtils.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Unit tests for SymbolPathUtils
+ */
+
+import { describe, expect, it } from "vitest";
+import SymbolPathUtils from "../SymbolPathUtils";
+
+describe("SymbolPathUtils", () => {
+  describe("buildScopePath", () => {
+    it("returns empty string for global scope (empty name)", () => {
+      const globalScope = { name: "" };
+      expect(SymbolPathUtils.buildScopePath(globalScope)).toBe("");
+    });
+
+    it("returns scope name for single-level scope", () => {
+      const scope = { name: "LED", parent: { name: "" } };
+      expect(SymbolPathUtils.buildScopePath(scope)).toBe("LED");
+    });
+
+    it("builds dot-path for nested scopes", () => {
+      const grandparent = { name: "Teensy4", parent: { name: "" } };
+      const parent = { name: "GPIO7", parent: grandparent };
+      const scope = { name: "DataRegister", parent };
+
+      expect(SymbolPathUtils.buildScopePath(scope)).toBe(
+        "Teensy4.GPIO7.DataRegister",
+      );
+    });
+
+    it("handles deeply nested scopes (4+ levels)", () => {
+      const level1 = { name: "Board", parent: { name: "" } };
+      const level2 = { name: "Peripheral", parent: level1 };
+      const level3 = { name: "Register", parent: level2 };
+      const level4 = { name: "Field", parent: level3 };
+
+      expect(SymbolPathUtils.buildScopePath(level4)).toBe(
+        "Board.Peripheral.Register.Field",
+      );
+    });
+
+    it("stops at global scope (empty parent name)", () => {
+      const globalScope = { name: "" };
+      const scope = { name: "LED", parent: globalScope };
+
+      expect(SymbolPathUtils.buildScopePath(scope)).toBe("LED");
+    });
+
+    it("handles circular reference (scope is its own parent)", () => {
+      // This is a defensive check - global scope in the real codebase
+      // is its own parent to avoid null checks
+      const selfRefScope: { name: string; parent: unknown } = {
+        name: "Self",
+        parent: undefined,
+      };
+      selfRefScope.parent = selfRefScope;
+
+      expect(SymbolPathUtils.buildScopePath(selfRefScope)).toBe("Self");
+    });
+  });
+
+  describe("getDotPathId", () => {
+    it("returns just name for top-level symbol", () => {
+      const symbol = { name: "setup", scope: { name: "" } };
+      expect(SymbolPathUtils.getDotPathId(symbol)).toBe("setup");
+    });
+
+    it("returns Scope.name for scoped symbol", () => {
+      const symbol = {
+        name: "toggle",
+        scope: { name: "LED", parent: { name: "" } },
+      };
+      expect(SymbolPathUtils.getDotPathId(symbol)).toBe("LED.toggle");
+    });
+
+    it("returns full dot-path for deeply nested symbol", () => {
+      const grandparent = { name: "Board", parent: { name: "" } };
+      const parent = { name: "GPIO", parent: grandparent };
+      const symbol = { name: "DR", scope: { name: "Register", parent } };
+
+      expect(SymbolPathUtils.getDotPathId(symbol)).toBe(
+        "Board.GPIO.Register.DR",
+      );
+    });
+  });
+
+  describe("getParentId", () => {
+    it("returns undefined for global scope", () => {
+      const globalScope = { name: "" };
+      expect(SymbolPathUtils.getParentId(globalScope)).toBeUndefined();
+    });
+
+    it("returns scope name for single-level scope", () => {
+      const scope = { name: "LED", parent: { name: "" } };
+      expect(SymbolPathUtils.getParentId(scope)).toBe("LED");
+    });
+
+    it("returns full dot-path for nested scope", () => {
+      const grandparent = { name: "Teensy4", parent: { name: "" } };
+      const scope = { name: "GPIO7", parent: grandparent };
+
+      expect(SymbolPathUtils.getParentId(scope)).toBe("Teensy4.GPIO7");
+    });
+  });
+
+  describe("buildSimpleDotPath", () => {
+    it("returns just name when parent is undefined", () => {
+      expect(SymbolPathUtils.buildSimpleDotPath(undefined, "myFunc")).toBe(
+        "myFunc",
+      );
+    });
+
+    it("returns parent.name when parent is defined", () => {
+      expect(SymbolPathUtils.buildSimpleDotPath("Color", "RED")).toBe(
+        "Color.RED",
+      );
+    });
+
+    it("handles empty string parent as truthy (returns path)", () => {
+      // Empty string is falsy in JS, so this behaves like undefined
+      expect(SymbolPathUtils.buildSimpleDotPath("", "name")).toBe("name");
+    });
+  });
+});