c-next 0.2.2 → 0.2.4

package/package.json

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

package/src/cli/Runner.ts

@@ -54,7 +54,7 @@ class Runner {
       debugMode: config.debugMode,
     });
 
-    const result = await pipeline.run();
+    const result = await pipeline.transpile({ kind: "files" });
     this._renameOutputIfNeeded(result, explicitOutputFile);
 
     ResultPrinter.print(result);

package/src/cli/__tests__/Runner.test.ts

@@ -30,7 +30,7 @@ describe("Runner", () => {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let processExitSpy: any;
   let mockConfig: ICliConfig;
-  let mockTranspilerInstance: { run: ReturnType<typeof vi.fn> };
+  let mockTranspilerInstance: { transpile: ReturnType<typeof vi.fn> };
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -66,7 +66,7 @@ describe("Runner", () => {
 
     // Mock Transpiler
     mockTranspilerInstance = {
-      run: vi.fn().mockResolvedValue({
+      transpile: vi.fn().mockResolvedValue({
         success: true,
         outputFiles: ["/project/src/main.c"],
         errors: [],
@@ -94,7 +94,7 @@ describe("Runner", () => {
         "src/main.cnx",
       ]);
       expect(Transpiler).toHaveBeenCalled();
-      expect(mockTranspilerInstance.run).toHaveBeenCalled();
+      expect(mockTranspilerInstance.transpile).toHaveBeenCalled();
       expect(ResultPrinter.print).toHaveBeenCalled();
     });
 
@@ -125,7 +125,7 @@ describe("Runner", () => {
     });
 
     it("passes include paths to Transpiler", async () => {
-      // Include discovery now happens inside Transpiler.discoverSources()
+      // Include discovery now happens inside Transpiler.discoverIncludes()
       // Runner just passes config.includeDirs directly
       mockConfig.includeDirs = ["/extra/include"];
 
@@ -168,7 +168,7 @@ describe("Runner", () => {
     it("handles explicit output filename for single file", async () => {
       mockConfig.outputPath = "output/result.c";
 
-      mockTranspilerInstance.run.mockResolvedValue({
+      mockTranspilerInstance.transpile.mockResolvedValue({
         success: true,
         outputFiles: ["/project/output/main.c"],
         errors: [],
@@ -236,7 +236,7 @@ describe("Runner", () => {
     });
 
     it("exits with 0 on success", async () => {
-      mockTranspilerInstance.run.mockResolvedValue({
+      mockTranspilerInstance.transpile.mockResolvedValue({
         success: true,
         outputFiles: ["/project/src/main.c"],
         errors: [],
@@ -248,7 +248,7 @@ describe("Runner", () => {
     });
 
     it("exits with 1 on failure", async () => {
-      mockTranspilerInstance.run.mockResolvedValue({
+      mockTranspilerInstance.transpile.mockResolvedValue({
         success: false,
         outputFiles: [],
         errors: ["Some error"],
@@ -285,7 +285,7 @@ describe("Runner", () => {
     it("doesn't rename when generated file matches explicit path", async () => {
       mockConfig.outputPath = "/project/output/main.c";
 
-      mockTranspilerInstance.run.mockResolvedValue({
+      mockTranspilerInstance.transpile.mockResolvedValue({
         success: true,
         outputFiles: ["/project/output/main.c"],
         errors: [],

package/src/cli/serve/ServeCommand.ts

@@ -19,7 +19,7 @@ import parseWithSymbols from "../../lib/parseWithSymbols";
 import parseCHeader from "../../lib/parseCHeader";
 
 /**
- * Method handler type (async to support Transpiler.transpileSource)
+ * Method handler type (async to support Transpiler.transpile)
  */
 type MethodHandler = (
   params?: Record<string, unknown>,
@@ -286,17 +286,35 @@ class ServeCommand {
       ? { workingDir: dirname(filePath), sourcePath: filePath }
       : undefined;
 
-    const result = await ServeCommand.transpiler.transpileSource(
+    const transpileResult = await ServeCommand.transpiler.transpile({
+      kind: "source",
       source,
-      options,
-    );
+      ...options,
+    });
+    const fileResult =
+      transpileResult.files.find(
+        (f) => f.sourcePath === (filePath ?? "<string>"),
+      ) ?? transpileResult.files[0];
+
+    // When files[] is empty (e.g., parse errors), fall back to aggregate errors
+    if (!fileResult) {
+      return {
+        success: true,
+        result: {
+          success: false,
+          code: "",
+          errors: transpileResult.errors,
+          cppDetected: ServeCommand.transpiler.isCppDetected(),
+        },
+      };
+    }
 
     return {
       success: true,
       result: {
-        success: result.success,
-        code: result.code,
-        errors: result.errors,
+        success: fileResult.success,
+        code: fileResult.code,
+        errors: fileResult.errors,
         cppDetected: ServeCommand.transpiler.isCppDetected(),
       },
     };
@@ -312,12 +330,14 @@ class ServeCommand {
   ): Promise<IMethodResult> {
     const { source, filePath } = params;
 
-    // If transpiler is initialized, run transpileSource to trigger header
+    // If transpiler is initialized, run transpile to trigger header
     // resolution and C++ detection (results are discarded, we just want
     // the side effects on the symbol table)
     if (ServeCommand.transpiler && filePath) {
       try {
-        await ServeCommand.transpiler.transpileSource(source, {
+        await ServeCommand.transpiler.transpile({
+          kind: "source",
+          source,
           workingDir: dirname(filePath),
           sourcePath: filePath,
         });

package/src/transpiler/Transpiler.ts

@@ -5,9 +5,9 @@
  * Key insight from ADR-053: "A single file transpilation is just a project
  * with one .cnx file."
  *
- * Architecture: Both run() and transpileSource() are thin wrappers that
- * discover files and delegate to _executePipeline(). There is ONE pipeline
- * for all transpilation — no branching on context/standalone mode.
+ * Architecture: transpile() is the single entry point. It discovers files
+ * via discoverIncludes(), then delegates to _executePipeline(). There is
+ * ONE pipeline for all transpilation.
  */
 
 import { join, basename, dirname, resolve } from "node:path";
@@ -52,6 +52,7 @@ import ITranspilerResult from "./types/ITranspilerResult";
 import IFileResult from "./types/IFileResult";
 import IPipelineFile from "./types/IPipelineFile";
 import IPipelineInput from "./types/IPipelineInput";
+import TTranspileInput from "./types/TTranspileInput";
 import ITranspileError from "../lib/types/ITranspileError";
 import TranspilerState from "./state/TranspilerState";
 import runAnalyzers from "./logic/analysis/runAnalyzers";
@@ -134,42 +135,33 @@ class Transpiler {
   }
 
   // ===========================================================================
-  // Public API: run() and transpileSource()
+  // Public API
   // ===========================================================================
 
   /**
-   * Execute the unified pipeline from CLI inputs.
+   * Unified entry point for all transpilation.
    *
-   * Stage 1 (file discovery) happens here, then delegates to _executePipeline().
+   * @param input - What to transpile:
+   *   - { kind: 'files' } — discover from config.inputs, write to disk
+   *   - { kind: 'source', source, ... } — transpile in-memory source
+   * @returns ITranspilerResult with per-file results in .files[]
    */
-  async run(): Promise<ITranspilerResult> {
+  async transpile(input: TTranspileInput): Promise<ITranspilerResult> {
     const result = this._initResult();
 
     try {
       await this._initializeRun();
 
-      // Stage 1: Discover source files
-      const { cnextFiles, headerFiles } = await this.discoverSources();
-      if (cnextFiles.length === 0) {
+      const pipelineInput = await this.discoverIncludes(input);
+      if (pipelineInput.cnextFiles.length === 0) {
         return this._finalizeResult(result, "No C-Next source files found");
       }
 
-      this._ensureOutputDirectories();
-
-      // Convert IDiscoveredFile[] to IPipelineFile[] (disk-based, all get code gen)
-      const pipelineFiles: IPipelineFile[] = cnextFiles.map((f) => ({
-        path: f.path,
-        discoveredFile: f,
-      }));
-
-      const input: IPipelineInput = {
-        cnextFiles: pipelineFiles,
-        headerFiles,
-        writeOutputToDisk: true,
-      };
-
-      await this._executePipeline(input, result);
+      if (input.kind === "files") {
+        this._ensureOutputDirectories();
+      }
 
+      await this._executePipeline(pipelineInput, result);
       return await this._finalizeResult(result);
     } catch (err) {
       return this._handleRunError(result, err);
@@ -177,66 +169,27 @@ class Transpiler {
   }
 
   /**
-   * Transpile source code provided as a string.
+   * Stage 1: Discover files and build pipeline input.
    *
-   * Discovers includes from the source, builds an IPipelineInput, and
-   * delegates to the same _executePipeline() as run().
+   * Branches on input kind:
+   * - 'files': filesystem scan, dependency graph, topological sort
+   * - 'source': parse in-memory string, walk include tree
    *
-   * @param source - The C-Next source code as a string
-   * @param options - Options for transpilation
-   * @returns Promise<IFileResult> with generated code or errors
+   * Header directive storage happens via IncludeResolver.resolve() for both
+   * C headers and cnext includes (Issue #854).
    */
-  async transpileSource(
-    source: string,
-    options?: {
-      workingDir?: string;
-      includeDirs?: string[];
-      sourcePath?: string;
-    },
-  ): Promise<IFileResult> {
-    const workingDir = options?.workingDir ?? process.cwd();
-    const additionalIncludeDirs = options?.includeDirs ?? [];
-    const sourcePath = options?.sourcePath ?? "<string>";
-
-    try {
-      await this._initializeRun();
-
-      const input = this._discoverFromSource(
-        source,
-        workingDir,
-        additionalIncludeDirs,
-        sourcePath,
-      );
-
-      const result = this._initResult();
-      await this._executePipeline(input, result);
-
-      // Find our main file's result
-      const fileResult = result.files.find((f) => f.sourcePath === sourcePath);
-      if (fileResult) {
-        return fileResult;
-      }
-
-      // No file result found — pipeline exited early (e.g., parse errors in Stage 3)
-      // Return pipeline errors as a file result
-      if (result.errors.length > 0) {
-        return this.buildErrorResult(sourcePath, result.errors, 0);
-      }
-      return this.buildErrorResult(
-        sourcePath,
-        [
-          {
-            line: 1,
-            column: 0,
-            message: "Pipeline produced no result for source file",
-            severity: "error",
-          },
-        ],
-        0,
-      );
-    } catch (err) {
-      return this.buildCatchResult(sourcePath, err);
+  private async discoverIncludes(
+    input: TTranspileInput,
+  ): Promise<IPipelineInput> {
+    if (input.kind === "files") {
+      return this._discoverFromFiles();
     }
+    return this._discoverFromSource(
+      input.source,
+      input.workingDir ?? process.cwd(),
+      input.includeDirs ?? [],
+      input.sourcePath ?? "<string>",
+    );
   }
 
   // ===========================================================================
@@ -246,7 +199,7 @@ class Transpiler {
   /**
    * The single unified pipeline for all transpilation.
    *
-   * Both run() and transpileSource() delegate here after file discovery.
+   * transpile() delegates here after file discovery via discoverIncludes().
    *
    * Stage 2: Collect symbols from C/C++ headers (includes building analyzer context)
    * Stage 3: Collect symbols from C-Next files
@@ -291,7 +244,7 @@ class Transpiler {
       );
     }
 
-    // Stage 6: Generate headers (only write to disk in run() mode)
+    // Stage 6: Generate headers (only write to disk in files mode)
     if (result.success && input.writeOutputToDisk) {
       this._generateAllHeadersFromPipeline(input.cnextFiles, result);
     }
@@ -395,17 +348,7 @@ class Transpiler {
         return this.buildParseOnlyResult(sourcePath, declarationCount);
       }
 
-      // Run analyzers (reads externalStructFields and symbolTable from CodeGenState)
-      const analyzerErrors = runAnalyzers(tree, tokenStream);
-      if (analyzerErrors.length > 0) {
-        return this.buildErrorResult(
-          sourcePath,
-          analyzerErrors,
-          declarationCount,
-        );
-      }
-
-      // Build symbolInfo for code generation
+      // Build symbolInfo for code generation (before analyzers so they can read it)
       const tSymbols = CNextResolver.resolve(tree, sourcePath);
       let symbolInfo = TSymbolInfoAdapter.convert(tSymbols);
 
@@ -421,6 +364,19 @@ class Transpiler {
         );
       }
 
+      // Make symbols available to analyzers (CodeGenerator.generate() sets this too)
+      CodeGenState.symbols = symbolInfo;
+
+      // Run analyzers (reads symbols, externalStructFields, and symbolTable from CodeGenState)
+      const analyzerErrors = runAnalyzers(tree, tokenStream);
+      if (analyzerErrors.length > 0) {
+        return this.buildErrorResult(
+          sourcePath,
+          analyzerErrors,
+          declarationCount,
+        );
+      }
+
       // Inject cross-file modification data for const inference
       this._setupCrossFileModifications();
 
@@ -450,19 +406,8 @@ class Transpiler {
         this._accumulateFileModifications();
       }
 
-      // ADR-055 Phase 7: Get TSymbols for header generation (auto-const applied during conversion)
-      const fileSymbols =
-        CodeGenState.symbolTable.getTSymbolsByFile(sourcePath);
-
-      // Generate header content
-      const headerCode = this.generateHeaderContent(
-        fileSymbols,
-        sourcePath,
-        this.cppDetected,
-        userIncludes,
-        passByValueCopy,
-        symbolInfo,
-      );
+      // Generate header content (reads from state populated above)
+      const headerCode = this.generateHeaderForFile(file) ?? undefined;
 
       return this.buildSuccessResult(
         sourcePath,
@@ -549,6 +494,15 @@ class Transpiler {
       }
     }
 
+    // Issue #854: Store header directives for cnext includes
+    for (const cnxInclude of resolved.cnextIncludes) {
+      const includePath = resolve(cnxInclude.path);
+      const directive = resolved.headerIncludeDirectives.get(includePath);
+      if (directive) {
+        this.state.setHeaderDirective(includePath, directive);
+      }
+    }
+
     // Walk C-Next includes transitively to build include file list
     const cnextIncludeFiles: IPipelineFile[] = [];
     IncludeTreeWalker.walk(
@@ -619,6 +573,9 @@ class Transpiler {
     CodeGenState.symbolTable.clear();
     // Reset SymbolRegistry for new run (new IFunctionSymbol type system)
     SymbolRegistry.reset();
+    // Reset callback-compatible functions for new run
+    // (populated by FunctionCallAnalyzer, persists through CodeGenState.reset())
+    CodeGenState.callbackCompatibleFunctions = new Set();
   }
 
   /**
@@ -721,8 +678,12 @@ class Transpiler {
       if (file.symbolOnly) {
         continue;
       }
-      const headerPath = this.generateHeader(file.discoveredFile);
-      if (headerPath) {
+      const headerContent = this.generateHeaderForFile(file);
+      if (headerContent) {
+        const headerPath = this.pathResolver.getHeaderOutputPath(
+          file.discoveredFile,
+        );
+        this.fs.writeFile(headerPath, headerContent);
         result.outputFiles.push(headerPath);
       }
     }
@@ -766,7 +727,7 @@ class Transpiler {
   }
 
   // ===========================================================================
-  // Source Discovery (Stage 1 for run())
+  // File Discovery (Stage 1 for files mode)
   // ===========================================================================
 
   /**
@@ -841,7 +802,10 @@ class Transpiler {
    * Issue #580: Track dependencies for topological sorting
    */
   private _processCnextIncludes(
-    resolved: { cnextIncludes: IDiscoveredFile[] },
+    resolved: {
+      cnextIncludes: IDiscoveredFile[];
+      headerIncludeDirectives: Map<string, string>;
+    },
     cnxPath: string,
     depGraph: DependencyGraph,
     cnextFiles: IDiscoveredFile[],
@@ -857,6 +821,12 @@ class Transpiler {
 
       depGraph.addDependency(cnxPath, includePath);
 
+      // Issue #854: Store header directive for cnext include types
+      const directive = resolved.headerIncludeDirectives.get(includePath);
+      if (directive) {
+        this.state.setHeaderDirective(includePath, directive);
+      }
+
       // Don't add if already in the list
       const alreadyExists =
         cnextBaseNames.has(includeBaseName) ||
@@ -944,10 +914,7 @@ class Transpiler {
    * This ensures headers are found based on what the source actually
    * includes, not by blindly scanning include directories.
    */
-  private async discoverSources(): Promise<{
-    cnextFiles: IDiscoveredFile[];
-    headerFiles: IDiscoveredFile[];
-  }> {
+  private async _discoverFromFiles(): Promise<IPipelineInput> {
     // Step 1: Discover C-Next files from inputs (files or directories)
     const cnextFiles: IDiscoveredFile[] = [];
     const fileByPath = new Map<string, IDiscoveredFile>();
@@ -957,7 +924,7 @@ class Transpiler {
     }
 
     if (cnextFiles.length === 0) {
-      return { cnextFiles: [], headerFiles: [] };
+      return { cnextFiles: [], headerFiles: [], writeOutputToDisk: true };
     }
 
     // Step 2: For each C-Next file, resolve its #include directives
@@ -981,7 +948,7 @@ class Transpiler {
     // Issue #580: Sort files topologically for correct cross-file const inference
     const sortedCnextFiles = this._sortFilesByDependency(depGraph, fileByPath);
 
-    // Resolve headers transitively for the run() path
+    // Resolve headers transitively
     const { headers: allHeaders, warnings: headerWarnings } =
       IncludeResolver.resolveHeadersTransitively(
         [...headerSet.values()],
@@ -996,9 +963,16 @@ class Transpiler {
       );
     this.warnings.push(...headerWarnings);
 
+    // Convert IDiscoveredFile[] to IPipelineFile[] (disk-based, all get code gen)
+    const pipelineFiles: IPipelineFile[] = sortedCnextFiles.map((f) => ({
+      path: f.path,
+      discoveredFile: f,
+    }));
+
     return {
-      cnextFiles: sortedCnextFiles,
+      cnextFiles: pipelineFiles,
       headerFiles: allHeaders,
+      writeOutputToDisk: true,
     };
   }
 
@@ -1242,48 +1216,41 @@ class Transpiler {
    * Stage 6: Generate header file for a C-Next file
    * ADR-055 Phase 7: Uses TSymbol directly, converts to IHeaderSymbol for generation.
    */
-  private generateHeader(file: IDiscoveredFile): string | null {
-    const tSymbols = CodeGenState.symbolTable.getTSymbolsByFile(file.path);
+  /**
+   * Generate header content for a single file's exported symbols.
+   * Unified method replacing both generateHeader() and generateHeaderContent().
+   * Reads all needed data from state (populated during Stage 5).
+   */
+  private generateHeaderForFile(file: IPipelineFile): string | null {
+    const sourcePath = file.path;
+    const tSymbols = CodeGenState.symbolTable.getTSymbolsByFile(sourcePath);
     const exportedSymbols = tSymbols.filter((s) => s.isExported);
 
     if (exportedSymbols.length === 0) {
       return null;
     }
 
-    const headerName = basename(file.path).replace(/\.cnx$|\.cnext$/, ".h");
-    const headerPath = this.pathResolver.getHeaderOutputPath(file);
-
-    // Issue #220: Get SymbolCollector for full type definitions
-    const typeInput = this.state.getSymbolInfo(file.path);
+    const headerName = basename(sourcePath).replace(/\.cnx$|\.cnext$/, ".h");
 
-    // Issue #280: Get pass-by-value params from per-file storage for multi-file consistency
-    // This uses the snapshot taken during transpilation, not the current (stale) codeGenerator state.
-    // Fallback to empty map if not found (defensive - should always exist after transpilation).
+    const typeInput = this.state.getSymbolInfo(sourcePath);
     const passByValueParams =
-      this.state.getPassByValueParams(file.path) ??
+      this.state.getPassByValueParams(sourcePath) ??
       new Map<string, Set<string>>();
+    const userIncludes = this.state.getUserIncludes(sourcePath);
 
-    // Issue #424: Get user includes for header generation
-    const userIncludes = this.state.getUserIncludes(file.path);
-
-    // Issue #478, #588: Collect all known enum names from all files for cross-file type handling
     const allKnownEnums = TransitiveEnumCollector.aggregateKnownEnums(
       this.state.getAllSymbolInfo(),
     );
 
-    // Issue #497: Build mapping from external types to their C header includes
     const externalTypeHeaders = ExternalTypeHeaderBuilder.build(
       this.state.getAllHeaderDirectives(),
       CodeGenState.symbolTable,
     );
 
-    // Issue #502: Include symbolTable in typeInput for C++ namespace type detection
     const typeInputWithSymbolTable = typeInput
       ? { ...typeInput, symbolTable: CodeGenState.symbolTable }
       : undefined;
 
-    // ADR-055 Phase 7: Convert TSymbol to IHeaderSymbol with auto-const info
-    // Issue #817: Apply auto-const info same as generateHeaderContent() does
     const unmodifiedParams = this.codeGenerator.getFunctionUnmodifiedParams();
     const headerSymbols = this.convertToHeaderSymbols(
       exportedSymbols,
@@ -1291,7 +1258,7 @@ class Transpiler {
       allKnownEnums,
     );
 
-    const headerContent = this.headerGenerator.generate(
+    return this.headerGenerator.generate(
       headerSymbols,
       headerName,
       {
@@ -1304,9 +1271,6 @@ class Transpiler {
       passByValueParams,
       allKnownEnums,
     );
-
-    this.fs.writeFile(headerPath, headerContent);
-    return headerPath;
   }
 
   /**
@@ -1351,65 +1315,6 @@ class Transpiler {
     }
   }
 
-  /**
-   * Generate header content for exported symbols.
-   * Issue #591: Extracted from transpileSource() for reduced complexity.
-   * ADR-055 Phase 7: Works with TSymbol[], converts to IHeaderSymbol for generation.
-   */
-  private generateHeaderContent(
-    tSymbols: TSymbol[],
-    sourcePath: string,
-    cppMode: boolean,
-    userIncludes: string[],
-    passByValueParams: Map<string, Set<string>>,
-    symbolInfo: ICodeGenSymbols,
-  ): string | undefined {
-    const exportedSymbols = tSymbols.filter((s) => s.isExported);
-
-    if (exportedSymbols.length === 0) {
-      return undefined;
-    }
-
-    // Convert to IHeaderSymbol with auto-const info
-    const unmodifiedParams = this.codeGenerator.getFunctionUnmodifiedParams();
-    const headerSymbols = this.convertToHeaderSymbols(
-      exportedSymbols,
-      unmodifiedParams,
-      symbolInfo.knownEnums,
-    );
-
-    const headerName = basename(sourcePath).replace(/\.cnx$|\.cnext$/, ".h");
-
-    // Get type input from CodeGenState (for struct/enum definitions)
-    const typeInput = CodeGenState.symbols;
-
-    // Issue #497: Build mapping from external types to their C header includes
-    const externalTypeHeaders = ExternalTypeHeaderBuilder.build(
-      this.state.getAllHeaderDirectives(),
-      CodeGenState.symbolTable,
-    );
-
-    // Issue #502: Include symbolTable in typeInput for C++ namespace type detection
-    const typeInputWithSymbolTable = typeInput
-      ? { ...typeInput, symbolTable: CodeGenState.symbolTable }
-      : undefined;
-
-    // Issue #478: Pass all known enums for cross-file type handling
-    return this.headerGenerator.generate(
-      headerSymbols,
-      headerName,
-      {
-        exportedOnly: true,
-        userIncludes,
-        externalTypeHeaders,
-        cppMode,
-      },
-      typeInputWithSymbolTable,
-      passByValueParams,
-      symbolInfo.knownEnums,
-    );
-  }
-
   /**
    * Convert TSymbols to IHeaderSymbols with auto-const information applied.
    * ADR-055 Phase 7: Replaces mutation-based auto-const updating.