@cdxgen/cdxgen 13.2.0 → 13.3.0

package/lib/core/fs.js

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import {
   accessSync,
+  closeSync,
   copyFileSync,
   createReadStream,
   existsSync,
@@ -10,10 +11,14 @@ import {
   lstatSync,
   mkdirSync,
   mkdtempSync,
+  openSync,
   readFileSync,
+  renameSync,
   rmSync,
+  statSync,
   unlinkSync,
   writeFileSync,
+  writeSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import path, { basename, dirname, join, resolve } from "node:path";
@@ -144,6 +149,53 @@ export function safeIsExecutableSync(filePath) {
  * @returns {void}
  */
 export function safeWriteSync(filePath, data, options) {
+  if (isWriteBlocked(filePath)) {
+    return undefined;
+  }
+  writeFileSync(filePath, data, options);
+  recordFilesystemActivity("write", filePath, "completed");
+}
+
+/**
+ * Permission- and dry-run-aware write of a sequence of chunks, for content too
+ * large to join into one string first. The chunks go to a temporary file next
+ * to the target, which is renamed into place once complete, so a chunk may be
+ * read from the file being replaced and a failed write leaves the target as it
+ * was.
+ *
+ * @param {string} filePath File path to write.
+ * @param {Iterable<string|Buffer>} chunks Chunks written in order.
+ * @returns {void}
+ */
+export function safeWriteChunksSync(filePath, chunks) {
+  if (isWriteBlocked(filePath)) {
+    return undefined;
+  }
+  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  const fd = openSync(tempPath, "w");
+  try {
+    for (const chunk of chunks) {
+      const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+      let written = 0;
+      while (written < bytes.length) {
+        written += writeSync(fd, bytes, written);
+      }
+    }
+    closeSync(fd);
+    renameSync(tempPath, filePath);
+  } catch (err) {
+    try {
+      closeSync(fd);
+    } catch {
+      // Already closed before the rename failed.
+    }
+    rmSync(tempPath, { force: true });
+    throw err;
+  }
+  recordFilesystemActivity("write", filePath, "completed");
+}
+
+function isWriteBlocked(filePath) {
   if (isDryRun) {
     recordFilesystemActivity(
       "write",
@@ -151,7 +203,7 @@ export function safeWriteSync(filePath, data, options) {
       "blocked",
       "Dry run mode blocks filesystem writes.",
     );
-    return undefined;
+    return true;
   }
   if (!hasWritePermission(filePath)) {
     if (DEBUG_MODE) {
@@ -163,10 +215,9 @@ export function safeWriteSync(filePath, data, options) {
       "blocked",
       "cdxgen lacks write permission for this path.",
     );
-    return undefined;
+    return true;
   }
-  writeFileSync(filePath, data, options);
-  recordFilesystemActivity("write", filePath, "completed");
+  return false;
 }
 
 /**
@@ -483,6 +534,116 @@ const VERSION_PROBE_ARGS = new Set(["--version", "-version", "version"]);
 const POSIX_SHELL_METACHARACTERS = /[;&|<>$`\\\n\r]/;
 const WINDOWS_SHELL_METACHARACTERS = /[&|<>^%\n\r]/;
 
+/**
+ * Quote one argument of a shell command line that is built as a single
+ * string. The shell flag exists so cmd.exe can resolve bare command names,
+ * `.cmd` shims and scripts, and every argument is data (paths, flags) that
+ * must arrive as one token whatever it contains: joined unquoted, an
+ * argument with spaces splits into several and hands the tool the wrong
+ * tokens.
+ *
+ * Windows follows the quoting rules cmd.exe and the MSVC runtimes share:
+ * wrap in double quotes, doubling the backslashes that precede a quote and
+ * escaping the quote itself. Inside double quotes cmd.exe already treats
+ * `&`, `|`, `<`, `>`, `^` and parentheses as literals, and the
+ * shell-metacharacter block above refuses `%` and the rest before this
+ * runs. A POSIX shell gets single quotes, which no expansion can leave.
+ *
+ * The same quoting is applied to the command itself when it names an
+ * existing file under a path with spaces; a command the shell must parse
+ * (a bare name, `sh -c`) never names a file as a whole and stays verbatim.
+ *
+ * @param {string} arg Argument to quote
+ * @param {boolean} [forWindows] Quote for cmd.exe rather than a POSIX shell; defaults to the current platform
+ * @returns {string} The argument, quoted when the shell needs it
+ */
+export function shellQuoteArgument(arg, forWindows = isWin) {
+  const value = `${arg}`;
+  if (forWindows) {
+    if (value === "") {
+      return '""';
+    }
+    if (!/[\s"]/.test(value)) {
+      return value;
+    }
+    // Every backslash run that precedes a quote doubles, each quote escapes,
+    // and the trailing run doubles for the closing quote this returns. A
+    // character scan keeps it linear; the equivalent `(\\*)"` pattern is
+    // polynomial on runs of backslashes that no quote ends.
+    let quoted = "";
+    let backslashes = 0;
+    for (const ch of value) {
+      if (ch === "\\") {
+        backslashes++;
+        quoted += ch;
+      } else if (ch === '"') {
+        quoted += "\\".repeat(backslashes) + '\\"';
+        backslashes = 0;
+      } else {
+        quoted += ch;
+        backslashes = 0;
+      }
+    }
+    quoted += "\\".repeat(backslashes);
+    return `"${quoted}"`;
+  }
+  if (value === "") {
+    return "''";
+  }
+  if (!/[^-\w@%+=:,./]/.test(value)) {
+    return value;
+  }
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Whether the path names an existing regular file, without throwing on the
+ * many values that are not paths at all (a bare command name, a command with
+ * arguments, anything the shell is meant to parse).
+ *
+ * @param {string} file Candidate path
+ * @returns {boolean} True when a regular file exists at the path
+ */
+function isFileNoThrow(file) {
+  try {
+    return statSync(`${file}`).isFile();
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Build the single command string a shell spawn runs. Every argument is
+ * quoted for the platform shell, so an argument containing spaces stays one
+ * token and cannot alter the command, and a command that is itself a file
+ * under a path with spaces (`C:\Program Files\...\node.exe`) is quoted too;
+ * a command the shell must parse (`sh -c`, a bare name) never names an
+ * existing file as a whole and is left verbatim.
+ *
+ * The one exception is a caller that composes shell fragments itself (sbt
+ * command lines embed their own quoting for the shell to strip): it passes
+ * `rawShellArgs` and keeps the verbatim join, under the shell-metacharacter
+ * block in safeSpawnSync like every other argument.
+ *
+ * @param {string} command The executable
+ * @param {string[]|undefined} args Arguments, when the caller passed any
+ * @param {boolean} [rawShellArgs] Join the arguments verbatim instead of quoting them
+ * @returns {string} The command line the shell will run
+ */
+export function joinShellCommand(command, args, rawShellArgs = false) {
+  let commandToken = `${command}`;
+  if (/\s/.test(commandToken) && isFileNoThrow(commandToken)) {
+    commandToken = shellQuoteArgument(commandToken);
+  }
+  if (!args?.length) {
+    return commandToken;
+  }
+  return [
+    commandToken,
+    ...(rawShellArgs ? args : args.map((arg) => shellQuoteArgument(arg))),
+  ].join(" ");
+}
+
 function hasShellMetacharacters(value) {
   if (value === undefined || value === null) {
     return false;
@@ -696,9 +857,12 @@ export function safeSpawnSync(command, args, options) {
       }
     }
   }
+  // Read before the option is stripped below: a caller composing shell
+  // fragments itself opts out of argument quoting with this flag.
+  const rawShellArgs = options?.cdxgenRawShellArgs === true;
   if (!options) {
     options = {};
-  } else if (options.cdxgenActivity) {
+  } else if (options.cdxgenActivity || options.cdxgenRawShellArgs) {
     options = {
       ...options,
     };
@@ -706,6 +870,9 @@ export function safeSpawnSync(command, args, options) {
   if (options.cdxgenActivity) {
     delete options.cdxgenActivity;
   }
+  if (options.cdxgenRawShellArgs) {
+    delete options.cdxgenRawShellArgs;
+  }
   if (options.shell === true) {
     const unsafeShellToken = getUnsafeShellToken(command, args);
     if (unsafeShellToken !== undefined) {
@@ -817,8 +984,9 @@ export function safeSpawnSync(command, args, options) {
   commandsExecuted.add(command);
   // Fix for DEP0190 warning
   if (options?.shell === true) {
+    const joined = joinShellCommand(command, args, rawShellArgs);
+    command = joined;
     if (args?.length) {
-      command = `${command} ${args.join(" ")}`;
       args = undefined;
     }
   }

package/lib/core/metadataProperties.js

@@ -0,0 +1,97 @@
+/**
+ * The spellings under which a config file may list custom metadata
+ * properties: those of the `--metadata-property` flag, and the plural that
+ * the CDXGEN_METADATA_PROPERTIES environment variable maps to.
+ */
+export const METADATA_PROPERTY_CONFIG_KEYS = [
+  "metadata-property",
+  "metadataProperty",
+  "metadata-properties",
+  "metadataProperties",
+];
+
+// Namespaces whose properties cdxgen itself asserts: `cdx:` is its registered
+// taxonomy, and `internal:` carries its own bookkeeping
+const RESERVED_METADATA_PROPERTY_PREFIXES = ["cdx:", "internal:"];
+
+/**
+ * Report whether a property name belongs to a namespace cdxgen reserves for
+ * the facts it establishes itself, such as `cdx:bom:componentSrcFiles`.
+ *
+ * @param {string} name Property name
+ * @returns {boolean} true for a reserved name
+ */
+export function isReservedMetadataPropertyName(name) {
+  return RESERVED_METADATA_PROPERTY_PREFIXES.some((prefix) =>
+    `${name}`.startsWith(prefix),
+  );
+}
+
+/**
+ * Normalize user-supplied metadata properties into `[{name, value}]`
+ * (discussion 4391).
+ *
+ * Accepted shapes:
+ * - a `name=value` string, or a JSON document holding any of the shapes below
+ *   — an environment variable
+ * - an array of `name=value` strings or `{name, value}` objects — the
+ *   `--metadata-property` flag and a JSON config file
+ * - a plain object mapping a name to a value, or to a list of values for a
+ *   property that repeats — a JSON document or a YAML config file
+ *
+ * Values must be strings, numbers, or booleans. An entry without a name, a
+ * `name=value` string without a separator, and an empty or structured value
+ * are dropped rather than guessed at: a property with a mangled name or an
+ * `[object Object]` value is worse than none.
+ *
+ * @param {unknown} input Properties in any accepted shape
+ * @returns {{name: string, value: string}[]} Normalized properties
+ */
+export function parseMetadataProperties(input) {
+  const properties = [];
+  if (typeof input === "string") {
+    let parsed;
+    try {
+      parsed = JSON.parse(input);
+    } catch (_err) {
+      parsed = undefined;
+    }
+    input =
+      parsed && typeof parsed === "object"
+        ? parsed
+        : [typeof parsed === "string" ? parsed : input];
+  }
+  const append = (name, value) => {
+    if (typeof name !== "string" && typeof name !== "number") {
+      return;
+    }
+    const propName = `${name}`.trim();
+    if (
+      !propName.length ||
+      !["string", "number", "boolean"].includes(typeof value) ||
+      !`${value}`.length
+    ) {
+      return;
+    }
+    properties.push({ name: propName, value: `${value}` });
+  };
+  if (Array.isArray(input)) {
+    for (const entry of input) {
+      if (typeof entry === "string") {
+        const separator = entry.indexOf("=");
+        if (separator > 0) {
+          append(entry.slice(0, separator), entry.slice(separator + 1));
+        }
+      } else if (entry && typeof entry === "object") {
+        append(entry.name, entry.value);
+      }
+    }
+  } else if (input && typeof input === "object") {
+    for (const [name, value] of Object.entries(input)) {
+      for (const avalue of Array.isArray(value) ? value : [value]) {
+        append(name, avalue);
+      }
+    }
+  }
+  return properties;
+}

package/lib/core/projectConfig.js

@@ -1,5 +1,10 @@
 import path from "node:path";
 
+import {
+  isReservedMetadataPropertyName,
+  METADATA_PROPERTY_CONFIG_KEYS,
+  parseMetadataProperties,
+} from "./metadataProperties.js";
 import { toCamel } from "./paths.js";
 
 /**
@@ -87,19 +92,41 @@ function isContainedPath(configDir, value) {
  * whenever that tree is. Path options are therefore confined to the config's
  * own directory - a scanned project may choose where in itself the BOM lands,
  * but not write outside it - and options that redirect data off the host or
- * widen what cdxgen executes are announced on the console.
+ * widen what cdxgen executes are announced on the console. A project may
+ * describe itself with custom metadata properties, but not in the namespaces
+ * cdxgen reserves for the facts it establishes, so a scanned tree cannot pass
+ * its own claims off as cdxgen's.
  *
  * @param {Object} config parsed config file contents
  * @param {string} configDir directory the config file was read from
- * @returns {{config: Object, rejected: string[], announced: string[]}} sanitized config and what it did
+ * @returns {{config: Object, rejected: string[], announced: string[], reservedProperties: string[]}} sanitized config and what it did
  */
 export function sanitizeProjectConfig(config, configDir) {
   if (!config || typeof config !== "object") {
-    return { announced: [], config: {}, rejected: [] };
+    return { announced: [], config: {}, rejected: [], reservedProperties: [] };
   }
   const sanitized = { ...config };
   const rejected = [];
   const announced = [];
+  const reservedProperties = [];
+  for (const key of METADATA_PROPERTY_CONFIG_KEYS) {
+    if (sanitized[key] === undefined) {
+      continue;
+    }
+    const properties = [];
+    for (const aprop of parseMetadataProperties(sanitized[key])) {
+      if (isReservedMetadataPropertyName(aprop.name)) {
+        reservedProperties.push(aprop.name);
+      } else {
+        properties.push(aprop);
+      }
+    }
+    if (properties.length) {
+      sanitized[key] = properties;
+    } else {
+      delete sanitized[key];
+    }
+  }
   for (const option of PATH_OPTIONS) {
     for (const key of optionSpellings(option)) {
       if (sanitized[key] === undefined) {
@@ -118,5 +145,5 @@ export function sanitizeProjectConfig(config, configDir) {
       }
     }
   }
-  return { announced, config: sanitized, rejected };
+  return { announced, config: sanitized, rejected, reservedProperties };
 }