c-next 0.1.50 → 0.1.52

package/README.md

@@ -5,6 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=jlaustill_c-next&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=jlaustill_c-next)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=jlaustill_c-next&metric=coverage)](https://sonarcloud.io/summary/new_code?id=jlaustill_c-next)
+[![Coverage Report](https://img.shields.io/badge/Coverage-Report-blue)](https://jlaustill.github.io/c-next/coverage/)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=jlaustill_c-next&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=jlaustill_c-next)
 
 A safer C for embedded systems development. Transpiles to clean, readable C.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "c-next",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "description": "A safer C for embedded systems development. Transpiles to clean, readable C.",
   "main": "src/index.ts",
   "bin": {
     "cnext": "./bin/cnext.js"
   },
   "scripts": {
-    "antlr": "antlr4ng -Dlanguage=TypeScript -visitor -listener -o src/antlr_parser grammar/CNext.g4",
-    "antlr:c": "antlr4ng -Dlanguage=TypeScript -visitor -listener -o src/antlr_parser/c grammar/C.g4",
-    "antlr:cpp:lexer": "antlr4ng -Dlanguage=TypeScript -o src/antlr_parser/cpp grammar/CPP14Lexer.g4",
-    "antlr:cpp:parser": "antlr4ng -Dlanguage=TypeScript -visitor -listener -o src/antlr_parser/cpp -lib src/antlr_parser/cpp/grammar grammar/CPP14Parser.g4",
+    "antlr": "antlr4ng -Dlanguage=TypeScript -visitor -listener -o src/transpiler/logic/parser grammar/CNext.g4",
+    "antlr:c": "antlr4ng -Dlanguage=TypeScript -visitor -listener -o src/transpiler/logic/parser/c grammar/C.g4",
+    "antlr:cpp:lexer": "antlr4ng -Dlanguage=TypeScript -o src/transpiler/logic/parser/cpp grammar/CPP14Lexer.g4",
+    "antlr:cpp:parser": "antlr4ng -Dlanguage=TypeScript -visitor -listener -o src/transpiler/logic/parser/cpp -lib src/transpiler/logic/parser/cpp/grammar grammar/CPP14Parser.g4",
     "antlr:cpp": "npm run antlr:cpp:lexer && npm run antlr:cpp:parser",
     "antlr:all": "npm run antlr && npm run antlr:c && npm run antlr:cpp",
     "start": "tsx src/index.ts",
@@ -21,11 +21,13 @@
     "test:q": "tsx scripts/test.ts -q",
     "test:update": "tsx scripts/test.ts --update",
     "analyze": "./scripts/static-analysis.sh",
-    "clean": "rm -rf src/antlr_parser",
+    "clean": "rm -rf src/transpiler/logic/parser/grammar src/transpiler/logic/parser/c/grammar src/transpiler/logic/parser/cpp/grammar",
     "prettier:check": "prettier --check .",
     "prettier:fix": "prettier --write .",
-    "oxlint:check": "oxlint src/",
-    "oxlint:fix": "oxlint src/ --fix",
+    "oxlint:check": "oxlint src/ --ignore-pattern '**/parser/grammar/**' --ignore-pattern '**/parser/c/grammar/**' --ignore-pattern '**/parser/cpp/grammar/**'",
+    "oxlint:fix": "oxlint src/ --ignore-pattern '**/parser/grammar/**' --ignore-pattern '**/parser/c/grammar/**' --ignore-pattern '**/parser/cpp/grammar/**' --fix",
+    "depcruise": "depcruise src/transpiler --config .dependency-cruiser.cjs",
+    "depcruise:graph": "depcruise src/transpiler --config .dependency-cruiser.cjs --output-type dot | dot -T svg > dependency-graph.svg",
     "prepare": "husky",
     "prepublishOnly": "npm run prettier:check && npm run oxlint:check && npm test",
     "coverage:check": "tsx scripts/coverage-checker.ts check",
@@ -74,8 +76,10 @@
   ],
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^3.2.4",
     "antlr4ng-cli": "^2.0.0",
+    "dependency-cruiser": "^17.3.7",
     "husky": "^9.1.7",
     "knip": "^5.82.1",
     "lint-staged": "^16.2.7",
@@ -84,9 +88,11 @@
     "vitest": "^3.0.0"
   },
   "dependencies": {
+    "@n1ru4l/toposort": "^0.0.1",
     "antlr4ng": "^3.0.16",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "yargs": "^18.0.0"
   },
   "lint-staged": {
     "*": [

package/src/cli/ArgParser.ts

@@ -0,0 +1,260 @@
+/**
+ * ArgParser
+ * Parses command-line arguments using yargs
+ */
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import ConfigPrinter from "./ConfigPrinter";
+import IParsedArgs from "./types/IParsedArgs";
+
+/**
+ * Interface for yargs parsed result
+ */
+interface IYargsResult {
+  _: (string | number)[];
+  o?: string;
+  output?: string;
+  "header-out"?: string;
+  "base-path"?: string;
+  cpp: boolean;
+  include: string[];
+  target?: string;
+  D: string[];
+  parse: boolean;
+  clean: boolean;
+  config: boolean;
+  verbose: boolean;
+  debug: boolean;
+  preprocess: boolean;
+  cache: boolean;
+  "pio-install": boolean;
+  "pio-uninstall": boolean;
+}
+
+/**
+ * Configure yargs with all options
+ */
+function configureYargs(args: string[], argv: string[]) {
+  return (
+    yargs(args)
+      .scriptName("cnext")
+      .usage(
+        `Usage:
+  cnext <file.cnx>                          Single file (outputs file.c)
+  cnext <file.cnx> -o <output.c>            Single file with explicit output
+  cnext <files...> -o <dir>                 Multi-file mode
+  cnext <dir>                               Directory mode (recursive)
+
+A safer C for embedded systems development.`,
+      )
+
+      // Output options
+      .option("o", {
+        alias: "output",
+        type: "string",
+        describe: "Output file or directory (default: same dir as input)",
+        requiresArg: true,
+      })
+      .option("header-out", {
+        type: "string",
+        describe: "Output directory for header files",
+        requiresArg: true,
+      })
+      .option("base-path", {
+        type: "string",
+        describe:
+          "Strip path prefix from header output (use with --header-out)",
+        requiresArg: true,
+      })
+
+      // Compilation options
+      .option("cpp", {
+        type: "boolean",
+        describe: "Output .cpp instead of .c (for C++ features like Serial)",
+        default: false,
+      })
+      .option("include", {
+        type: "string",
+        array: true,
+        describe: "Additional include directory (can repeat)",
+        requiresArg: true,
+        default: [] as string[],
+      })
+      .option("target", {
+        type: "string",
+        describe: "Target platform for atomic code gen (ADR-049)",
+        requiresArg: true,
+      })
+      .option("D", {
+        type: "string",
+        array: true,
+        describe: "Define preprocessor macro",
+        default: [] as string[],
+      })
+
+      // Mode flags
+      .option("parse", {
+        type: "boolean",
+        describe: "Parse only, don't generate code",
+        default: false,
+      })
+      .option("clean", {
+        type: "boolean",
+        describe: "Delete generated files for all .cnx sources",
+        default: false,
+      })
+      .option("config", {
+        type: "boolean",
+        describe: "Show effective configuration and exit",
+        default: false,
+      })
+
+      // Debug/development options
+      .option("verbose", {
+        type: "boolean",
+        describe: "Show include path discovery",
+        default: false,
+      })
+      .option("debug", {
+        type: "boolean",
+        describe: "Generate panic-on-overflow helpers (ADR-044)",
+        default: false,
+      })
+      .option("preprocess", {
+        type: "boolean",
+        describe:
+          "Run C preprocessor on headers (use --no-preprocess to disable)",
+        default: true,
+      })
+      .option("cache", {
+        type: "boolean",
+        describe: "Enable symbol cache (use --no-cache to disable)",
+        default: true,
+      })
+
+      // PlatformIO integration
+      .option("pio-install", {
+        type: "boolean",
+        describe: "Setup PlatformIO integration",
+        default: false,
+      })
+      .option("pio-uninstall", {
+        type: "boolean",
+        describe: "Remove PlatformIO integration",
+        default: false,
+      })
+
+      // Config file documentation (shown in help)
+      .epilogue(
+        `Examples:
+  cnext main.cnx                            # Outputs main.c (same dir)
+  cnext main.cnx -o build/main.c            # Explicit output path
+  cnext src/*.cnx -o build/                 # Multiple files to directory
+  cnext src/                                # Compile all .cnx files in src/ (recursive)
+
+Target platforms: teensy41, cortex-m7, cortex-m4, cortex-m3, cortex-m0+, cortex-m0, avr
+
+Config files (searched in order, JSON format):
+  cnext.config.json, .cnext.json, .cnextrc
+
+Config options:
+  cppRequired    Output .cpp instead of .c (boolean)
+  noCache        Disable symbol caching (boolean)
+  include        Additional include directories (string[])
+  output         Output directory for generated files (string)
+  headerOut      Separate directory for header files (string)
+  target         Target platform for atomic code gen (string)
+  debugMode      Generate panic-on-overflow helpers (boolean)`,
+      )
+
+      // Version from package.json
+      .version(
+        "version",
+        "Show version",
+        `cnext v${ConfigPrinter.getVersion()}`,
+      )
+      .alias("version", "v")
+
+      // Help
+      .help("help")
+      .alias("help", "h")
+
+      // Fail handler for unknown options
+      .fail((msg, err, yargsInstance) => {
+        if (err) throw err;
+        // Check for -I flag (common GCC mistake)
+        const hasIFlag = argv.some((arg) => arg.startsWith("-I"));
+        if (hasIFlag) {
+          console.error("Error: Unknown flag '-I...'");
+          console.error("  Did you mean: --include <dir>");
+          console.error("");
+          console.error("Example:");
+          console.error("  cnext src --include path/to/headers");
+          process.exit(1);
+        }
+        console.error(msg);
+        console.error("");
+        yargsInstance.showHelp();
+        process.exit(1);
+      })
+  );
+}
+
+/**
+ * Parse command-line arguments using yargs
+ */
+class ArgParser {
+  /**
+   * Parse command-line arguments into a structured object
+   * @param argv - Command-line arguments (typically process.argv)
+   * @returns Parsed arguments object
+   */
+  static parse(argv: string[]): IParsedArgs {
+    const args = hideBin(argv);
+
+    // Show help and exit 0 when no arguments provided
+    if (args.length === 0) {
+      configureYargs([], argv).showHelp("log"); // Output to stdout, not stderr
+      process.exit(0);
+    }
+
+    const parsed = configureYargs(args, argv).parseSync() as IYargsResult;
+
+    // Parse -D defines into a record
+    const defines: Record<string, string | boolean> = {};
+    for (const define of parsed.D) {
+      const eqIndex = define.indexOf("=");
+      if (eqIndex > 0) {
+        defines[define.slice(0, eqIndex)] = define.slice(eqIndex + 1);
+      } else {
+        defines[define] = true;
+      }
+    }
+
+    // Get input files from positional args (everything that isn't an option)
+    const inputFiles = parsed._.map(String);
+
+    return {
+      inputFiles,
+      outputPath: parsed.o ?? "",
+      includeDirs: parsed.include,
+      defines,
+      cppRequired: parsed.cpp,
+      target: parsed.target,
+      preprocess: parsed.preprocess,
+      verbose: parsed.verbose,
+      noCache: !parsed.cache,
+      parseOnly: parsed.parse,
+      headerOutDir: parsed["header-out"],
+      basePath: parsed["base-path"],
+      cleanMode: parsed.clean,
+      showConfig: parsed.config,
+      pioInstall: parsed["pio-install"],
+      pioUninstall: parsed["pio-uninstall"],
+      debugMode: parsed.debug,
+    };
+  }
+}
+
+export default ArgParser;

package/src/{commands → cli}/CleanCommand.ts

@@ -3,9 +3,10 @@
  * Deletes generated files (.c, .cpp, .h, .hpp) that have matching .cnx sources
  */
 
-import { basename, join, relative, resolve } from "node:path";
-import { existsSync, statSync, unlinkSync } from "node:fs";
-import InputExpansion from "../lib/InputExpansion";
+import { basename, join, resolve } from "node:path";
+import { unlinkSync } from "node:fs";
+import InputExpansion from "../transpiler/data/InputExpansion";
+import PathResolver from "../transpiler/data/PathResolver";
 
 /**
  * Command to clean generated output files
@@ -48,6 +49,13 @@ class CleanCommand {
       ? resolve(headerOutDir)
       : resolvedOutDir;
 
+    // Issue #586: Use PathResolver for consistent path calculation
+    const pathResolver = new PathResolver({
+      inputs,
+      outDir,
+      headerOutDir,
+    });
+
     let deletedCount = 0;
 
     // For each .cnx file, calculate and delete generated files
@@ -55,7 +63,7 @@ class CleanCommand {
       const baseName = basename(cnxFile).replace(/\.cnx$|\.cnext$/, "");
 
       // Calculate relative path from input directories
-      const relativePath = this.getRelativePath(cnxFile, inputs);
+      const relativePath = pathResolver.getRelativePathFromInputs(cnxFile);
 
       // Code files (.c and .cpp) go to outDir
       const codeExtensions = [".c", ".cpp"];
@@ -92,39 +100,6 @@ class CleanCommand {
     }
   }
 
-  /**
-   * Get relative path of a file from input directories.
-   * Returns undefined if file is not under any input directory.
-   *
-   * When undefined is returned (e.g., for single file inputs), the caller
-   * falls back to using just the basename, which is correct behavior since
-   * there's no directory structure to preserve.
-   */
-  private static getRelativePath(
-    filePath: string,
-    inputs: string[],
-  ): string | undefined {
-    for (const input of inputs) {
-      const resolvedInput = resolve(input);
-
-      // Skip file inputs - only directories can establish relative structure.
-      // For single file inputs like "cnext myfile.cnx -o build", we return
-      // undefined and the caller uses baseName, which is the correct behavior.
-      if (existsSync(resolvedInput) && statSync(resolvedInput).isFile()) {
-        continue;
-      }
-
-      const rel = relative(resolvedInput, filePath);
-
-      // Check if file is under this input directory
-      if (rel && !rel.startsWith("..")) {
-        return rel;
-      }
-    }
-
-    return undefined;
-  }
-
   /**
    * Delete a file if it exists
    * @returns true if file was deleted, false otherwise

package/src/cli/Cli.ts

@@ -0,0 +1,104 @@
+/**
+ * Cli
+ * Main CLI orchestrator that handles argument parsing, config loading,
+ * and dispatching to appropriate commands
+ */
+
+import { dirname, resolve } from "node:path";
+import ArgParser from "./ArgParser";
+import ConfigLoader from "./ConfigLoader";
+import ConfigPrinter from "./ConfigPrinter";
+import PlatformIOCommand from "./PlatformIOCommand";
+import CleanCommand from "./CleanCommand";
+import ICliResult from "./types/ICliResult";
+import ICliConfig from "./types/ICliConfig";
+import IParsedArgs from "./types/IParsedArgs";
+import IFileConfig from "./types/IFileConfig";
+
+/**
+ * Main CLI orchestrator
+ */
+class Cli {
+  /**
+   * Run the CLI
+   * @returns CLI result with configuration for Runner if transpilation should run
+   */
+  static run(): ICliResult {
+    // Parse arguments (yargs handles --help and --version automatically)
+    const args = ArgParser.parse(process.argv);
+
+    // Early exits for PlatformIO commands
+    if (args.pioInstall) {
+      PlatformIOCommand.install();
+      return { shouldRun: false, exitCode: 0 };
+    }
+
+    if (args.pioUninstall) {
+      PlatformIOCommand.uninstall();
+      return { shouldRun: false, exitCode: 0 };
+    }
+
+    // Load config file (searches up from input file directory)
+    const configDir =
+      args.inputFiles.length > 0
+        ? dirname(resolve(args.inputFiles[0]))
+        : process.cwd();
+    const fileConfig = ConfigLoader.load(configDir);
+
+    // Merge CLI args with file config
+    const config = this.mergeConfig(args, fileConfig);
+
+    // Handle --config: show effective configuration
+    if (args.showConfig) {
+      ConfigPrinter.showConfig(config, fileConfig);
+      return { shouldRun: false, exitCode: 0 };
+    }
+
+    // Validate inputs
+    if (config.inputs.length === 0) {
+      console.error("Error: No input files specified");
+      console.error("Run 'cnext --help' for usage information");
+      return { shouldRun: false, exitCode: 1 };
+    }
+
+    // Handle --clean: delete generated files
+    if (args.cleanMode) {
+      CleanCommand.execute(
+        config.inputs,
+        config.outputPath,
+        config.headerOutDir,
+      );
+      return { shouldRun: false, exitCode: 0 };
+    }
+
+    return { shouldRun: true, exitCode: 0, config };
+  }
+
+  /**
+   * Merge CLI arguments with file configuration
+   * CLI flags take precedence over config file values
+   */
+  private static mergeConfig(
+    args: IParsedArgs,
+    fileConfig: IFileConfig,
+  ): ICliConfig {
+    return {
+      inputs: args.inputFiles,
+      outputPath: args.outputPath || fileConfig.output || "",
+      // Merge include dirs: config includes come first, CLI includes override/append
+      includeDirs: [...(fileConfig.include ?? []), ...args.includeDirs],
+      defines: args.defines,
+      preprocess: args.preprocess,
+      verbose: args.verbose,
+      cppRequired: args.cppRequired ?? fileConfig.cppRequired ?? false,
+      noCache: args.noCache || fileConfig.noCache === true,
+      parseOnly: args.parseOnly,
+      headerOutDir: args.headerOutDir ?? fileConfig.headerOut,
+      basePath: args.basePath ?? fileConfig.basePath,
+      target: args.target ?? fileConfig.target,
+      debugMode: args.debugMode || fileConfig.debugMode,
+    };
+  }
+}
+
+export default Cli;

package/src/cli/ConfigLoader.ts

@@ -0,0 +1,51 @@
+/**
+ * ConfigLoader
+ * Loads configuration from project config files
+ */
+
+import { dirname, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import IFileConfig from "./types/IFileConfig";
+
+/**
+ * Config file names in priority order (highest first)
+ */
+const CONFIG_FILES = ["cnext.config.json", ".cnext.json", ".cnextrc"];
+
+/**
+ * Load configuration from project directory
+ */
+class ConfigLoader {
+  /**
+   * Load config from project directory, searching up the directory tree
+   * @param startDir - Directory to start searching from
+   * @returns Loaded configuration (empty object if no config found)
+   */
+  static load(startDir: string): IFileConfig {
+    let dir = resolve(startDir);
+
+    while (dir !== dirname(dir)) {
+      // Stop at filesystem root
+      for (const configFile of CONFIG_FILES) {
+        const configPath = resolve(dir, configFile);
+        if (existsSync(configPath)) {
+          try {
+            const content = readFileSync(configPath, "utf-8");
+            const config = JSON.parse(content) as IFileConfig;
+            config._path = configPath;
+            return config;
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Warning: Failed to parse ${configPath}: ${message}`);
+            return {};
+          }
+        }
+      }
+      dir = dirname(dir);
+    }
+
+    return {}; // No config found
+  }
+}
+
+export default ConfigLoader;

package/src/cli/ConfigPrinter.ts

@@ -0,0 +1,69 @@
+/**
+ * ConfigPrinter
+ * Displays effective configuration and provides version info
+ */
+
+import ICliConfig from "./types/ICliConfig";
+import IFileConfig from "./types/IFileConfig";
+
+// Read version from package.json to ensure consistency
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const packageJson = require("../../package.json");
+
+/**
+ * Version string from package.json
+ */
+const VERSION = packageJson.version as string;
+
+/**
+ * Print effective configuration and version info
+ */
+class ConfigPrinter {
+  /**
+   * Get the current version string
+   */
+  static getVersion(): string {
+    return VERSION;
+  }
+
+  /**
+   * Display effective configuration
+   * @param config - Merged effective configuration
+   * @param fileConfig - Configuration loaded from file (for displaying path)
+   */
+  static showConfig(config: ICliConfig, fileConfig: IFileConfig): void {
+    console.log("Effective configuration:");
+    console.log("");
+    console.log("  Config file:    " + (fileConfig._path ?? "(none)"));
+    console.log("  cppRequired:    " + config.cppRequired);
+    console.log("  debugMode:      " + (config.debugMode ?? false));
+    console.log("  target:         " + (config.target ?? "(none)"));
+    console.log("  noCache:        " + config.noCache);
+    console.log("  preprocess:     " + config.preprocess);
+    console.log(
+      "  output:         " + (config.outputPath || "(same dir as input)"),
+    );
+    console.log(
+      "  headerOut:      " + (config.headerOutDir ?? "(same as output)"),
+    );
+    console.log("  basePath:       " + (config.basePath ?? "(none)"));
+    console.log(
+      "  include:        " + (config.includeDirs.length > 0 ? "" : "(none)"),
+    );
+    for (const dir of config.includeDirs) {
+      console.log("    - " + dir);
+    }
+    console.log(
+      "  defines:        " +
+        (Object.keys(config.defines).length > 0 ? "" : "(none)"),
+    );
+    for (const [key, value] of Object.entries(config.defines)) {
+      console.log("    - " + key + (value === true ? "" : "=" + value));
+    }
+    console.log("");
+    console.log("Source:");
+    console.log("  CLI flags take precedence over config file values");
+  }
+}
+
+export default ConfigPrinter;