c-next 0.1.61 → 0.1.63

package/src/transpiler/types/IPipelineFile.ts

@@ -0,0 +1,27 @@
+import IDiscoveredFile from "../data/types/IDiscoveredFile";
+
+/**
+ * A file descriptor for the unified transpilation pipeline.
+ *
+ * Supports both disk-based files (from run()) and in-memory sources
+ * (from transpileSource()). The pipeline reads content via:
+ *   file.source ?? this.fs.readFile(file.path)
+ */
+interface IPipelineFile {
+  /** Absolute path to the source file */
+  readonly path: string;
+
+  /** In-memory source content (overrides disk read when set) */
+  readonly source?: string;
+
+  /** The discovered file metadata (type, extension) */
+  readonly discoveredFile: IDiscoveredFile;
+
+  /** When true, collect symbols only — skip code generation */
+  readonly symbolOnly?: boolean;
+
+  /** C-Next includes for transitive enum resolution */
+  readonly cnextIncludes?: ReadonlyArray<{ path: string }>;
+}
+
+export default IPipelineFile;

package/src/transpiler/types/IPipelineInput.ts

@@ -0,0 +1,23 @@
+import IDiscoveredFile from "../data/types/IDiscoveredFile";
+import IPipelineFile from "./IPipelineFile";
+
+/**
+ * Input to the unified transpilation pipeline (_executePipeline).
+ *
+ * Both run() and transpileSource() construct this and delegate to the pipeline.
+ */
+interface IPipelineInput {
+  /** C-Next files to process (in dependency order) */
+  readonly cnextFiles: IPipelineFile[];
+
+  /** C/C++ header files for symbol collection */
+  readonly headerFiles: IDiscoveredFile[];
+
+  /** Whether to write generated output to disk */
+  readonly writeOutputToDisk: boolean;
+
+  /** Skip Stage 4 (symbol conflict check) — standalone mode doesn't need it */
+  readonly skipConflictCheck?: boolean;
+}
+
+export default IPipelineInput;

package/src/transpiler/types/TranspilerState.ts

@@ -189,7 +189,7 @@ class TranspilerState {
 
   /**
    * Get the processed headers Set (for external APIs that require Set access).
-   * Issue #592: Used by IncludeResolver.resolveHeadersTransitively() and IStandaloneTranspiler.
+   * Issue #592: Used by IncludeResolver.resolveHeadersTransitively().
    */
   getProcessedHeadersSet(): Set<string> {
     return this.processedHeaders;

package/src/utils/FormatUtils.ts

@@ -20,11 +20,11 @@ class FormatUtils {
   }
 
   /**
-   * Indent each line of a multi-line string.
+   * Indent each line of a multi-line string (skips empty lines).
    *
    * @param text - The text to indent (may contain newlines)
    * @param level - The indentation level
-   * @returns Text with each line indented
+   * @returns Text with each non-empty line indented
    */
   static indentLines(text: string, level: number): string {
     const prefix = FormatUtils.indent(level);
@@ -34,6 +34,21 @@ class FormatUtils {
       .join("\n");
   }
 
+  /**
+   * Indent ALL lines of a multi-line string (including empty lines).
+   *
+   * @param text - The text to indent (may contain newlines)
+   * @param level - The indentation level
+   * @returns Text with every line indented
+   */
+  static indentAllLines(text: string, level: number): string {
+    const prefix = FormatUtils.indent(level);
+    return text
+      .split("\n")
+      .map((line) => prefix + line)
+      .join("\n");
+  }
+
   /**
    * Join strings with separator, filtering out empty strings.
    *
@@ -59,6 +74,17 @@ class FormatUtils {
     }
     return `{\n${content}\n}`;
   }
+
+  /**
+   * Get the appropriate scope separator for C++ vs C/C-Next.
+   * C++ uses :: for scope resolution, C/C-Next uses _ (underscore).
+   *
+   * @param isCppContext - Whether generating C++ code
+   * @returns "::" for C++ or "_" for C/C-Next
+   */
+  static getScopeSeparator(isCppContext: boolean): string {
+    return isCppContext ? "::" : "_";
+  }
 }
 
 export default FormatUtils;

package/src/utils/MapUtils.ts

@@ -0,0 +1,25 @@
+/**
+ * Map utilities for deep copying and manipulation.
+ * Pure functions for working with Map collections.
+ */
+class MapUtils {
+  /**
+   * Deep copy a Map<string, Set<string>>.
+   * Creates new Map and new Set instances to ensure complete isolation.
+   * Accepts ReadonlyMap/ReadonlySet for flexibility with immutable sources.
+   *
+   * @param source - The source Map to copy (can be readonly)
+   * @returns A new mutable Map with cloned Set values
+   */
+  static deepCopyStringSetMap(
+    source: ReadonlyMap<string, ReadonlySet<string>>,
+  ): Map<string, Set<string>> {
+    const copy = new Map<string, Set<string>>();
+    for (const [key, value] of source) {
+      copy.set(key, new Set(value));
+    }
+    return copy;
+  }
+}
+
+export default MapUtils;

package/src/utils/PostfixAnalysisUtils.ts

@@ -0,0 +1,48 @@
+/**
+ * PostfixAnalysisUtils - Shared utilities for analyzing postfix target operations
+ *
+ * Extracts common logic for analyzing assignment targets that may have
+ * member access (a.b.c) or subscript access (a[i]).
+ */
+import * as Parser from "../transpiler/logic/parser/grammar/CNextParser";
+
+/**
+ * Result of analyzing postfix target operations.
+ */
+interface IPostfixAnalysisResult {
+  /** Chain of identifiers from base through member accesses */
+  readonly identifiers: string[];
+  /** Whether any subscript (array access) operations were found */
+  readonly hasSubscript: boolean;
+}
+
+/**
+ * Analyze postfix target operations to extract identifier chain and detect subscripts.
+ *
+ * Given an assignment target like `a.b.c[i].d`, this extracts:
+ * - identifiers: ["a", "b", "c", "d"]
+ * - hasSubscript: true
+ *
+ * @param baseId - The base identifier (leftmost name)
+ * @param postfixOps - Array of postfix operations (member access or subscript)
+ * @returns Analysis result with identifiers and subscript detection
+ */
+function analyzePostfixOps(
+  baseId: string,
+  postfixOps: Parser.PostfixTargetOpContext[],
+): IPostfixAnalysisResult {
+  const identifiers: string[] = [baseId];
+  let hasSubscript = false;
+
+  for (const op of postfixOps) {
+    if (op.IDENTIFIER()) {
+      identifiers.push(op.IDENTIFIER()!.getText());
+    } else {
+      hasSubscript = true;
+    }
+  }
+
+  return { identifiers, hasSubscript };
+}
+
+export default analyzePostfixOps;

package/src/utils/__tests__/FormatUtils.test.ts

@@ -51,6 +51,35 @@ describe("FormatUtils.indentLines", () => {
   });
 });
 
+// ========================================================================
+// indentAllLines
+// ========================================================================
+describe("FormatUtils.indentAllLines", () => {
+  it("indents single line", () => {
+    expect(FormatUtils.indentAllLines("code;", 1)).toBe("    code;");
+  });
+
+  it("indents multiple lines", () => {
+    expect(FormatUtils.indentAllLines("line1;\nline2;", 1)).toBe(
+      "    line1;\n    line2;",
+    );
+  });
+
+  it("indents empty lines (unlike indentLines)", () => {
+    expect(FormatUtils.indentAllLines("line1;\n\nline2;", 1)).toBe(
+      "    line1;\n    \n    line2;",
+    );
+  });
+
+  it("handles level 0 (no indent)", () => {
+    expect(FormatUtils.indentAllLines("code;", 0)).toBe("code;");
+  });
+
+  it("handles deeper indentation", () => {
+    expect(FormatUtils.indentAllLines("x = 1;", 2)).toBe("        x = 1;");
+  });
+});
+
 // ========================================================================
 // joinNonEmpty
 // ========================================================================
@@ -114,3 +143,16 @@ describe("FormatUtils.INDENT", () => {
     expect(FormatUtils.INDENT.length).toBe(4);
   });
 });
+
+// ========================================================================
+// getScopeSeparator
+// ========================================================================
+describe("FormatUtils.getScopeSeparator", () => {
+  it("returns :: for C++ context", () => {
+    expect(FormatUtils.getScopeSeparator(true)).toBe("::");
+  });
+
+  it("returns _ for C/C-Next context", () => {
+    expect(FormatUtils.getScopeSeparator(false)).toBe("_");
+  });
+});

package/src/utils/__tests__/MapUtils.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import MapUtils from "../MapUtils.js";
+
+describe("MapUtils", () => {
+  describe("deepCopyStringSetMap", () => {
+    it("should return empty map for empty input", () => {
+      const source = new Map<string, Set<string>>();
+      const result = MapUtils.deepCopyStringSetMap(source);
+
+      expect(result.size).toBe(0);
+      expect(result).not.toBe(source);
+    });
+
+    it("should deep copy map with single entry", () => {
+      const source = new Map<string, Set<string>>([
+        ["func1", new Set(["param1", "param2"])],
+      ]);
+
+      const result = MapUtils.deepCopyStringSetMap(source);
+
+      expect(result.size).toBe(1);
+      expect(result.get("func1")).toEqual(new Set(["param1", "param2"]));
+    });
+
+    it("should deep copy map with multiple entries", () => {
+      const source = new Map<string, Set<string>>([
+        ["func1", new Set(["a", "b"])],
+        ["func2", new Set(["c"])],
+        ["func3", new Set(["d", "e", "f"])],
+      ]);
+
+      const result = MapUtils.deepCopyStringSetMap(source);
+
+      expect(result.size).toBe(3);
+      expect(result.get("func1")).toEqual(new Set(["a", "b"]));
+      expect(result.get("func2")).toEqual(new Set(["c"]));
+      expect(result.get("func3")).toEqual(new Set(["d", "e", "f"]));
+    });
+
+    it("should create independent Map instance", () => {
+      const source = new Map<string, Set<string>>([
+        ["func1", new Set(["param1"])],
+      ]);
+
+      const result = MapUtils.deepCopyStringSetMap(source);
+
+      // Modify source - should not affect result
+      source.set("func2", new Set(["new"]));
+      source.delete("func1");
+
+      expect(result.size).toBe(1);
+      expect(result.has("func1")).toBe(true);
+      expect(result.has("func2")).toBe(false);
+    });
+
+    it("should create independent Set instances", () => {
+      const originalSet = new Set(["param1", "param2"]);
+      const source = new Map<string, Set<string>>([["func1", originalSet]]);
+
+      const result = MapUtils.deepCopyStringSetMap(source);
+
+      // Modify original Set - should not affect result
+      originalSet.add("param3");
+      originalSet.delete("param1");
+
+      const resultSet = result.get("func1");
+      expect(resultSet).toBeDefined();
+      expect(resultSet!.has("param1")).toBe(true);
+      expect(resultSet!.has("param2")).toBe(true);
+      expect(resultSet!.has("param3")).toBe(false);
+    });
+
+    it("should handle empty Sets in map", () => {
+      const source = new Map<string, Set<string>>([
+        ["func1", new Set()],
+        ["func2", new Set(["a"])],
+      ]);
+
+      const result = MapUtils.deepCopyStringSetMap(source);
+
+      expect(result.get("func1")?.size).toBe(0);
+      expect(result.get("func2")?.size).toBe(1);
+    });
+  });
+});

package/src/utils/constants/OperatorMappings.ts

@@ -0,0 +1,19 @@
+/**
+ * Operator mapping from C-Next assignment operators to C assignment operators.
+ * Used by assignment handling and control flow generation.
+ */
+const ASSIGNMENT_OPERATOR_MAP: Readonly<Record<string, string>> = {
+  "<-": "=",
+  "+<-": "+=",
+  "-<-": "-=",
+  "*<-": "*=",
+  "/<-": "/=",
+  "%<-": "%=",
+  "&<-": "&=",
+  "|<-": "|=",
+  "^<-": "^=",
+  "<<<-": "<<=",
+  ">><-": ">>=",
+};
+
+export default ASSIGNMENT_OPERATOR_MAP;

package/src/transpiler/logic/StandaloneContextBuilder.ts

@@ -1,150 +0,0 @@
-/**
- * StandaloneContextBuilder
- * Issue #591: Extracted from Transpiler.transpileSource() to reduce complexity
- *
- * Handles standalone-mode initialization:
- * - Parse C/C++ headers and collect symbols
- * - Recursively parse C-Next includes
- * - Store header include directives
- */
-
-import IDiscoveredFile from "../data/types/IDiscoveredFile";
-import IncludeTreeWalker from "../data/IncludeTreeWalker";
-import IncludeResolver from "../data/IncludeResolver";
-
-/** Inferred type from IncludeResolver.resolve() return type */
-type TResolvedIncludes = ReturnType<
-  InstanceType<typeof IncludeResolver>["resolve"]
->;
-
-/**
- * Interface for the Transpiler methods needed by StandaloneContextBuilder.
- * This decouples the builder from the concrete Transpiler class.
- */
-interface IStandaloneTranspiler {
-  /** Parse and collect symbols from a C/C++ header file (no recursion, Issue #592) */
-  collectHeaderSymbols(header: IDiscoveredFile): void;
-
-  /** Parse and collect symbols from a C-Next include file */
-  collectCNextSymbols(cnxInclude: IDiscoveredFile): void;
-
-  /** Get the configured include directories */
-  getIncludeDirs(): readonly string[];
-
-  /** Store header include directive for type headers */
-  setHeaderIncludeDirective(headerPath: string, directive: string): void;
-
-  /** Add a warning message */
-  addWarning(message: string): void;
-
-  /** Get already-processed header paths (for deduplication) */
-  getProcessedHeaders(): Set<string>;
-
-  /** Is debug mode enabled? */
-  isDebugMode(): boolean;
-}
-
-// Interface is not exported - Transpiler uses duck typing
-
-/**
- * Builds standalone context by processing headers and C-Next includes.
- *
- * In standalone mode (when transpileSource() is called without a context),
- * this builder initializes the symbol table by:
- * 1. Parsing all C/C++ headers to collect type definitions
- * 2. Recursively parsing all C-Next includes for cross-file symbols
- * 3. Storing header include directives for generated header files
- */
-class StandaloneContextBuilder {
-  /**
-   * Build the standalone context by processing all includes.
-   *
-   * @param transpiler - The transpiler instance (via interface)
-   * @param resolved - The resolved includes from IncludeResolver
-   */
-  static build(
-    transpiler: IStandaloneTranspiler,
-    resolved: TResolvedIncludes,
-  ): void {
-    // Step 4a: Parse C/C++ headers to populate symbol table
-    // Issue #592: Use resolveHeadersTransitively for recursive include discovery
-    StandaloneContextBuilder.processHeaders(transpiler, resolved);
-
-    // Step 4b: Recursively parse C-Next includes for cross-file symbols
-    StandaloneContextBuilder.processCNextIncludes(
-      transpiler,
-      resolved.cnextIncludes,
-    );
-  }
-
-  /**
-   * Process C/C++ headers to collect symbols.
-   * Issue #592: Uses IncludeResolver.resolveHeadersTransitively() for recursive discovery
-   */
-  private static processHeaders(
-    transpiler: IStandaloneTranspiler,
-    resolved: TResolvedIncludes,
-  ): void {
-    const includeDirs = transpiler.getIncludeDirs();
-
-    // Issue #592: Resolve all headers transitively (including nested includes)
-    const { headers: allHeaders, warnings: headerWarnings } =
-      IncludeResolver.resolveHeadersTransitively(
-        resolved.headers,
-        [...includeDirs],
-        {
-          onDebug: transpiler.isDebugMode()
-            ? (msg) => console.log(`[DEBUG] ${msg}`)
-            : undefined,
-          processedPaths: transpiler.getProcessedHeaders(),
-        },
-      );
-
-    // Add any warnings from header resolution
-    for (const warning of headerWarnings) {
-      transpiler.addWarning(warning);
-    }
-
-    // Process all headers (now in dependency order, no recursion needed)
-    for (const header of allHeaders) {
-      try {
-        transpiler.collectHeaderSymbols(header);
-        // Issue #497: Store the include directive for this header
-        const directive = resolved.headerIncludeDirectives.get(header.path);
-        if (directive) {
-          transpiler.setHeaderIncludeDirective(header.path, directive);
-        }
-      } catch (err) {
-        transpiler.addWarning(
-          `Failed to process header ${header.path}: ${err}`,
-        );
-      }
-    }
-  }
-
-  /**
-   * Recursively process C-Next includes to collect symbols.
-   * Issue #294: Enables cross-file scope references (e.g., decoder.getSpn() -> decoder_getSpn())
-   * Issue #465: Recursively process transitive includes for enum info
-   * Issue #591: Uses shared IncludeTreeWalker to eliminate duplicate traversal code
-   */
-  private static processCNextIncludes(
-    transpiler: IStandaloneTranspiler,
-    cnextIncludes: IDiscoveredFile[],
-  ): void {
-    const includeDirs = transpiler.getIncludeDirs();
-
-    IncludeTreeWalker.walk(cnextIncludes, includeDirs, (file) => {
-      try {
-        transpiler.collectCNextSymbols(file);
-      } catch (err) {
-        transpiler.addWarning(
-          `Failed to process C-Next include ${file.path}: ${err}`,
-        );
-        return false; // Stop traversing this branch on error
-      }
-    });
-  }
-}
-
-export default StandaloneContextBuilder;