@cdxgen/cdxgen 0.0.1 → 13.0.1

package/lib/cli/cliOptions.js

@@ -0,0 +1,543 @@
+/**
+ * CLI argument → options conversion for cdxgen.
+ *
+ * Extracts the complex arg-to-options mapping from `bin/cdxgen.js` into
+ * pure, testable functions with no side-effects (no process.exit, no
+ * console output).
+ *
+ * Architecture note: This module is a helper and must NOT import from
+ * `lib/cli/index.js` or `lib/stages/`. See AGENTS.md "Module layering
+ * rules".
+ *
+ */
+
+import { join, resolve } from "node:path";
+
+import { isSecureMode, readEnvironmentVariable } from "../core/activity.js";
+import { PROJECT_TYPE_ALIASES } from "../core/env.js";
+import {
+  DEFAULT_CDX_SPEC_VERSION,
+  normalizeCycloneDxComponentTypeFilter,
+} from "../inventory/bomUtils.js";
+import { isHbomOnlyProjectTypes } from "../inventory/hbom.js";
+
+/**
+ * CycloneDX spec versions accepted as generation targets in v13.
+ * 1.4 and 1.5 are below the floor; output downgrade is still supported
+ * internally by postgen.js.
+ * @type {number[]}
+ */
+const ACCEPTED_SPEC_VERSIONS = [1.6, 1.7, 2.0];
+
+/**
+ * Validate the `--spec-version` value against the v13 spec floor (1.6).
+ *
+ * Returns `null` when the value is an accepted generation target, or an
+ * actionable error string when it is rejected. The error message for
+ * sub-floor versions (1.4 / 1.5) explains that output downgrade still
+ * exists, so users are not left without a migration path.
+ *
+ * @param {number} specVersion  The parsed `--spec-version` value.
+ * @param {string} [commandName]  The invoked binary name for the message.
+ * @returns {string|null}  Error message, or `null` when valid.
+ */
+export function validateSpecVersion(specVersion, commandName = "cdxgen") {
+  if (specVersion === 1.4 || specVersion === 1.5) {
+    return (
+      `${commandName}: --spec-version ${specVersion} is below the v13 spec floor (1.6) and is no longer accepted as a generation target. ` +
+      "Accepted values: --spec-version 1.6, --spec-version 1.7, or --spec-version 2.0. " +
+      `Generating with 1.6 or 1.7 produces a 1.6 or 1.7 document — it will not emit CycloneDX ${specVersion}. ` +
+      `cdxgen still contains the ${specVersion} output-downgrade logic and it remains reachable by library callers that pass \`specVersion: ${specVersion}\` to createBom(); only the CLI target is restricted. ` +
+      `To get a ${specVersion} document from the CLI, generate 1.6 and convert the result with an external tool such as \`cyclonedx-cli convert --output-version v1_${String(specVersion).split(".")[1]}\`. ` +
+      "See MIGRATING-TO-V13.md for details."
+    );
+  }
+  if (!ACCEPTED_SPEC_VERSIONS.includes(Number(specVersion))) {
+    const shown = Number.isNaN(Number(specVersion))
+      ? `'${specVersion}' (not a number)`
+      : String(specVersion);
+    return `${commandName}: --spec-version ${shown} is not supported. Accepted values: 1.6, 1.7, 2.0.`;
+  }
+  return null;
+}
+
+/**
+ * The set of valid CycloneDX lifecycle values for the `post-build`
+ * lifecycle that have dedicated SBOM support.
+ * @type {ReadonlySet<string>}
+ */
+const POST_BUILD_SUPPORTED_PROJECT_TYPES = new Set([
+  "csharp",
+  "dotnet",
+  "container",
+  "docker",
+  "podman",
+  "oci",
+  "android",
+  "apk",
+  "aab",
+  "go",
+  "golang",
+  "rust",
+  "rust-lang",
+  "cargo",
+  "caxa",
+]);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a value was explicitly provided by the user (i.e., is not
+ * the yargs default). Yargs always populates default values, so we cannot
+ * simply check for truthiness.
+ *
+ * We detect "user-provided" by checking whether the actual value differs
+ * from the declared yargs default. This is robust for primitive types
+ * (number, string, boolean) which is the case for all cdxgen CLI flags.
+ *
+ * @param {*} value    The value from the parsed args
+ * @param {*} yaDefault The default declared in yargs `.option()`
+ * @returns {boolean}  True when the user explicitly set this flag
+ */
+export function isUserProvided(value, yaDefault) {
+  return value !== undefined && value !== yaDefault;
+}
+
+/**
+ * Apply command-name-based defaults to the raw parsed args. When cdxgen is
+ * invoked via a symlink or alias (e.g. `obom`, `cbom`, `spdxgen`, `aibom`),
+ * certain args receive implicit values.
+ *
+ * **Pure function** — returns a shallow copy of `args` with mutations; the
+ * original `args` object is not modified.
+ *
+ * @param {object} args               Parsed yargs argv
+ * @param {string} invokedCommandName Binary name without extension
+ * @returns {object} A shallow copy of args with alias-based defaults applied
+ */
+export function applyCommandNameDefaults(args, invokedCommandName) {
+  const result = { ...args };
+
+  if (invokedCommandName.includes("obom") && !result.type) {
+    result.type = ["os"];
+  }
+  if (invokedCommandName.includes("spdxgen") && !result.format) {
+    result.format = "spdx";
+  }
+  if (invokedCommandName.includes("aibom") && !result.type) {
+    result.type = ["ai"];
+    result.includeFormulation = true;
+    if (!result.bomAuditCategories) {
+      result.bomAuditCategories = "ai-bom";
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build the initial `options` object from parsed CLI args. This performs
+ * the field renames and derived-value computations that create the shape
+ * expected by `createBom`.
+ *
+ * @param {object} args               Parsed yargs argv (after command-name
+ *                                    defaults have been applied)
+ * @param {object} context
+ * @param {string} context.filePath          Resolved source path
+ * @param {boolean} context.isRemoteOrPurl   True when source is a URL or purl
+ * @returns {object} The initial options object
+ */
+/**
+ * Resolve the BOM output target.
+ *
+ * `-` is the stdout marker and is kept literal rather than resolved to a path,
+ * so downstream logic recognizes it before any sandbox check treats it as a
+ * writable file. Under secure mode the default filename is resolved to an
+ * absolute path so the permission prompt names a real location.
+ *
+ * @param {object} args Parsed CLI arguments
+ * @param {object} context Resolution context
+ * @param {string} context.filePath Scan path
+ * @param {boolean} context.isRemoteOrPurl Whether the scan target is remote
+ * @returns {string} Output path, or "-" for stdout
+ */
+function resolveOutputTarget(args, { filePath, isRemoteOrPurl }) {
+  if (args.output === "-") {
+    return "-";
+  }
+  if (!isSecureMode || args.output !== "bom.json") {
+    return args.output;
+  }
+  return isRemoteOrPurl
+    ? resolve(args.output)
+    : resolve(join(filePath, args.output));
+}
+
+export function buildInitialOptions(args, { filePath, isRemoteOrPurl }) {
+  const res = Object.assign({}, args, {
+    projectType: args.type,
+    multiProject: args.recurse,
+    noBabel: args.noBabel || args.babel === false,
+    project: args.projectId,
+    deep: args.deep || args.evidence,
+    aiProvenance: args.aiProvenance,
+    output: resolveOutputTarget(args, { filePath, isRemoteOrPurl }),
+    exclude: args.exclude || args.excludeRegex,
+    include: args.include || args.includeRegex,
+    noIgnore: args.noIgnore,
+    gitAiNotesRef: args.gitAiNotesRef || "refs/notes/ai",
+    // License normalization and enrichment are on by default; the only escape
+    // hatch is the corresponding environment variable.
+    licenseEnhance:
+      readEnvironmentVariable("CDXGEN_LICENSE_ENHANCE") !== "false",
+    licenseEnrich: readEnvironmentVariable("CDXGEN_LICENSE_ENRICH") !== "false",
+    licensePolicy:
+      args.licensePolicy || readEnvironmentVariable("CDXGEN_LICENSE_POLICY"),
+    licenseRef:
+      args.licenseRef === true ||
+      readEnvironmentVariable("CDXGEN_LICENSE_REF") === "true",
+  });
+
+  if (res.licenseEnhance !== undefined) {
+    process.env.CDXGEN_LICENSE_ENHANCE = String(res.licenseEnhance);
+  }
+  if (res.licenseEnrich !== undefined) {
+    process.env.CDXGEN_LICENSE_ENRICH = String(res.licenseEnrich);
+  }
+  if (res.licensePolicy !== undefined) {
+    process.env.CDXGEN_LICENSE_POLICY = String(res.licensePolicy);
+  } else {
+    delete process.env.CDXGEN_LICENSE_POLICY;
+  }
+  if (res.licenseRef !== undefined) {
+    process.env.CDXGEN_LICENSE_REF = String(res.licenseRef);
+  }
+
+  return res;
+}
+
+/**
+ * Check whether the supplied project types include an OS inventory type
+ * (`os` or an alias such as `linux`, `windows`, `macos`).
+ *
+ * @param {string|string[]|undefined|null} projectTypes Project types.
+ * @returns {boolean} True when an OS inventory type is requested.
+ */
+function hasOsProjectType(projectTypes) {
+  if (!projectTypes) {
+    return false;
+  }
+  const values = Array.isArray(projectTypes) ? projectTypes : [projectTypes];
+  const osTypes = new Set(["os", ...(PROJECT_TYPE_ALIASES.os || [])]);
+  return values
+    .flatMap((projectType) => `${projectType}`.split(","))
+    .some((projectType) => osTypes.has(projectType.trim().toLowerCase()));
+}
+
+/**
+ * @typedef {object} OptionsWarning
+ * @property {"info"|"warn"|"error"} level   Severity level
+ * @property {string}                message Human-readable description
+ */
+
+/**
+ * Apply command-specific, standard, and security overrides to the options
+ * object. This covers:
+ *
+ * - Dedup of `projectType`
+ * - `cbom` / `saasbom` command overrides
+ * - `cdxgen-secure` mode
+ * - Dry-run mode
+ * - Standards-driven specVersion default
+ * - HBOM formulation suppression
+ *
+ * **Mutates `options` in place** and returns a list of warnings that the
+ * caller should surface to the user (e.g. via `console.warn`).
+ *
+ * @param {object} options               The options object from Phase 2
+ * @param {object} context
+ * @param {string} context.invokedCommandName  Binary name (e.g. "cbom")
+ * @param {boolean} context.userSetSpecVersion True when the user explicitly
+ *                                             passed `--spec-version`
+ * @param {boolean} [context.isDryRun=false]   Current dry-run state
+ * @returns {OptionsWarning[]} Warnings to surface to the user
+ */
+export function applyPostConstructionOverrides(options, context) {
+  const { invokedCommandName, userSetSpecVersion, isDryRun = false } = context;
+  const warnings = [];
+
+  if (options.projectType && Array.isArray(options.projectType)) {
+    options.projectType = Array.from(new Set(options.projectType));
+  }
+
+  // --- cbom / saasbom command overrides ----------------------------------
+  if (["cbom", "saasbom"].includes(invokedCommandName)) {
+    if (invokedCommandName.includes("cbom")) {
+      if (normalizeCycloneDxComponentTypeFilter(options.componentType).length) {
+        warnings.push({
+          level: "error",
+          message:
+            "The cbom command does not support --component-type. Use cdxgen with --include-crypto when you need component-type filtering.",
+        });
+      }
+      // Crypto evidence collection analyses source code with atom, which is
+      // meaningless and extremely slow for OS inventories (discussion #4310).
+      // Refuse the combination and direct users to obom.
+      if (hasOsProjectType(options.projectType)) {
+        warnings.push({
+          level: "error",
+          message:
+            "The cbom command does not support OS inventory project types (-t os). Use the obom command instead to generate an OBOM for an operating system installation.",
+        });
+        return warnings;
+      }
+      options.includeCrypto = true;
+    }
+    options.evidence = true;
+    // Only set the default spec version if the user did not explicitly provide one
+    if (!userSetSpecVersion) {
+      options.specVersion = DEFAULT_CDX_SPEC_VERSION;
+    }
+    options.deep = true;
+  }
+
+  // --- cdxgen-secure command overrides -----------------------------------
+  if (invokedCommandName.includes("cdxgen-secure")) {
+    warnings.push({
+      level: "info",
+      message:
+        "NOTE: Secure mode only restricts cdxgen from performing certain activities such as package installation. It does not provide security guarantees in the presence of malicious code.",
+    });
+    options.installDeps = false;
+  }
+
+  // --- Dry-run mode overrides --------------------------------------------
+  if (isDryRun) {
+    options.installDeps = false;
+  }
+
+  // When a standard is requested, the minimum spec version is 1.6
+  if (options.standard) {
+    if (!userSetSpecVersion) {
+      options.specVersion = DEFAULT_CDX_SPEC_VERSION;
+    } else if (options.specVersion < 1.6) {
+      warnings.push({
+        level: "warn",
+        message:
+          "WARNING: Standards (definition.standards) requires CycloneDX specifications version 1.6 or above. Overriding the version to 1.6 automatically.",
+      });
+      options.specVersion = 1.6;
+    }
+  }
+
+  // --- HBOM formulation suppression --------------------------------------
+  const isHbomOnly = isHbomOnlyProjectTypes(options.projectType);
+  if (options.includeFormulation && isHbomOnly) {
+    warnings.push({
+      level: "info",
+      message:
+        "NOTE: Ignoring formulation collection for HBOM-only invocations because the resulting hardware BOM does not need workflow or dependency-tree enrichment.",
+    });
+    options.includeFormulation = false;
+  } else if (options.includeFormulation) {
+    if (options.serverUrl) {
+      warnings.push({
+        level: "warn",
+        message: `WARNING: The formulation section may include sensitive data such as emails and secrets. This data will be submitted to '${options.serverUrl}' automatically.`,
+      });
+    } else {
+      warnings.push({
+        level: "info",
+        message:
+          "NOTE: The formulation section may include sensitive data such as emails and secrets.\nPlease review the generated SBOM before distribution or LLM training.",
+      });
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Apply advanced option expansion based on `profile`, `lifecycle`, and
+ * `technique` settings. This is the extracted form of the
+ * `applyAdvancedOptions()` function that was previously inline in
+ * `bin/cdxgen.js`.
+ *
+ * **Mutates `options` in place.**
+ *
+ * Design note: Several profiles unconditionally override user flags like
+ * `deep`, `evidence`, and `installDeps`. This is intentional — the profile
+ * is a "meta-flag" that sets a curated combination. When users select a
+ * profile, they opt into its opinionated defaults.
+ *
+ * @param {object} options    The options object
+ * @param {object} [context]
+ * @param {boolean} [context.isSecureMode]  Whether cdxgen runs in secure mode
+ * @returns {OptionsWarning[]} Warnings for the caller
+ */
+export function applyAdvancedOptions(options, context = {}) {
+  const secureMode = context.isSecureMode ?? isSecureMode;
+  const warnings = [];
+  const isHbomOnly = isHbomOnlyProjectTypes(options.projectType);
+
+  // --- Profile expansion -------------------------------------------------
+  switch (options.profile) {
+    case "appsec":
+      options.deep = true;
+      options.bomAudit = true;
+      break;
+    case "research":
+      options.deep = true;
+      options.evidence = true;
+      options.includeCrypto = true;
+      break;
+    case "operational":
+      if (options?.projectType) {
+        // Avoid duplicate "os" entries when the user already specified it
+        if (!options.projectType.includes("os")) {
+          options.projectType.push("os");
+        }
+      } else {
+        options.projectType = ["os"];
+      }
+      options.bomAudit = true;
+      break;
+    case "threat-modeling":
+      options.deep = true;
+      options.evidence = true;
+      options.bomAudit = true;
+      break;
+    case "license-compliance":
+      process.env.FETCH_LICENSE = "true";
+      break;
+    case "ml-tiny":
+      process.env.FETCH_LICENSE = "true";
+      options.deep = false;
+      options.evidence = false;
+      options.includeCrypto = false;
+      options.installDeps = false;
+      options.bomAudit = false;
+      break;
+    case "machine-learning":
+    case "ml":
+      process.env.FETCH_LICENSE = "true";
+      options.deep = true;
+      options.evidence = false;
+      options.includeCrypto = false;
+      options.installDeps = !secureMode;
+      break;
+    case "deep-learning":
+    case "ml-deep":
+      process.env.FETCH_LICENSE = "true";
+      options.deep = true;
+      options.evidence = true;
+      options.includeCrypto = true;
+      options.installDeps = !secureMode;
+      options.bomAudit = true;
+      break;
+    default:
+      break;
+  }
+
+  // --- Lifecycle expansion -----------------------------------------------
+  switch (options.lifecycle) {
+    case "pre-build":
+      options.installDeps = false;
+      break;
+    case "post-build":
+      if (
+        !options.projectType ||
+        !POST_BUILD_SUPPORTED_PROJECT_TYPES.has(options.projectType[0])
+      ) {
+        warnings.push({
+          level: "error",
+          message:
+            "PREVIEW: post-build lifecycle SBOM generation is supported only for limited project types.",
+        });
+      }
+      options.installDeps = true;
+      break;
+    default:
+      break;
+  }
+
+  // --- Technique expansion -----------------------------------------------
+  if (options?.technique && Array.isArray(options.technique)) {
+    if (options.technique.includes("source-code-analysis")) {
+      options.deep = true;
+      options.evidence = true;
+    }
+  }
+
+  // --- BOM audit → auto-formulation --------------------------------------
+  if (options.bomAudit) {
+    if (isHbomOnly) {
+      // HBOM-only: skip formulation
+    } else if (!options.includeFormulation) {
+      warnings.push({
+        level: "info",
+        message:
+          "NOTE: Automatically collecting formulation information. The section may include sensitive data such as emails and secrets.\nPlease review the generated SBOM before distribution or LLM training.",
+      });
+      options.includeFormulation = true;
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Build the complete `options` object from parsed CLI arguments.
+ *
+ * This is the single entry point that replaces the ~330 lines of inline
+ * imperative code in `bin/cdxgen.js`. It orchestrates all four phases:
+ *
+ * 1. Command-name alias expansion
+ * 2. Initial options construction (field renames, derived values)
+ * 3. Post-construction overrides (dedup, command flags, specVersion)
+ * 4. Advanced options (profile, lifecycle, technique)
+ *
+ * Returns both the options object and a list of warnings that the caller
+ * (typically `bin/cdxgen.js`) should surface to the user.
+ *
+ * @param {object} args               Raw parsed yargs argv
+ * @param {object} context
+ * @param {string} context.invokedCommandName  Binary name without extension
+ * @param {string} context.filePath            Resolved source path
+ * @param {boolean} context.isRemoteOrPurl     True for URL/purl sources
+ * @param {boolean} context.userSetSpecVersion True when the user explicitly
+ *                                             passed `--spec-version`
+ * @param {boolean} [context.isDryRun=false]   Dry-run mode
+ * @param {boolean} [context.isSecureMode]     Secure mode
+ * @returns {{ options: object, warnings: OptionsWarning[] }}
+ */
+export function buildOptionsFromArgs(args, context) {
+  const {
+    invokedCommandName,
+    filePath,
+    isRemoteOrPurl,
+    userSetSpecVersion,
+    isDryRun = false,
+  } = context;
+
+  const expandedArgs = applyCommandNameDefaults(args, invokedCommandName);
+  const options = buildInitialOptions(expandedArgs, {
+    filePath,
+    isRemoteOrPurl,
+  });
+  const phase3Warnings = applyPostConstructionOverrides(options, {
+    invokedCommandName,
+    userSetSpecVersion,
+    isDryRun,
+  });
+  const phase4Warnings = applyAdvancedOptions(options, {
+    isSecureMode: context.isSecureMode,
+  });
+
+  return {
+    options,
+    warnings: [...phase3Warnings, ...phase4Warnings],
+  };
+}