@cyclonedx/cdxgen 12.2.0 → 12.3.0

package/lib/helpers/display.js

@@ -2,8 +2,11 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 
-import { createStream, table } from "table";
-
+import {
+  hasComponentRegistryProvenance,
+  REGISTRY_PROVENANCE_ICON,
+} from "./provenanceUtils.js";
+import { createStream, table } from "./table.js";
 import { isSecureMode, safeExistsSync, toCamel } from "./utils.js";
 
 // https://github.com/yangshun/tree-node-cli/blob/master/src/index.js
@@ -16,12 +19,48 @@ const SYMBOLS_ANSI = {
 };
 
 const MAX_TREE_DEPTH = 6;
+const CYCLE_NODE_ICON = "↺";
+const REPEATED_NODE_ICON = "⤴";
 const highlightStr = (s, highlight) => {
   if (highlight && s?.includes(highlight)) {
     s = s.replaceAll(highlight, `\x1b[1;33m${highlight}\x1b[0m`);
   }
   return s;
 };
+
+const formatComponentName = (component, highlight) => {
+  const displayName = highlightStr(component?.name || "", highlight);
+  if (hasComponentRegistryProvenance(component)) {
+    return `${REGISTRY_PROVENANCE_ICON} ${displayName}`;
+  }
+  return displayName;
+};
+
+const printProvenanceLegend = () => {
+  console.log(
+    `Legend: ${REGISTRY_PROVENANCE_ICON} = registry provenance or trusted publishing evidence`,
+  );
+};
+
+/**
+ * Builds legend lines for dependency tree marker icons.
+ *
+ * @param {string[]} treeGraphics Dependency tree lines
+ * @returns {string[]} Legend lines to print after the tree output
+ */
+export const buildDependencyTreeLegendLines = (treeGraphics) => {
+  const legendLines = [];
+  if (treeGraphics.some((line) => line.includes(`${REPEATED_NODE_ICON} `))) {
+    legendLines.push(`${REPEATED_NODE_ICON} = already shown`);
+  }
+  if (treeGraphics.some((line) => line.includes(`${CYCLE_NODE_ICON} `))) {
+    legendLines.push(`${CYCLE_NODE_ICON} = cycle`);
+  }
+  if (!legendLines.length) {
+    return legendLines;
+  }
+  return [`Legend: ${legendLines.join("; ")}`];
+};
 /**
  * Prints the BOM components as a streaming table to the console.
  * Delegates to {@link printOSTable} automatically when the BOM metadata indicates
@@ -30,12 +69,14 @@ const highlightStr = (s, highlight) => {
  * @param {Object} bomJson CycloneDX BOM JSON object
  * @param {string[]} [filterTypes] Optional list of component types to include; all types shown when omitted
  * @param {string} [highlight] Optional string to highlight in the output
+ * @param {string} [summaryText] Optional summary message to print after the table
  * @returns {void}
  */
 export function printTable(
   bomJson,
   filterTypes = undefined,
   highlight = undefined,
+  summaryText = undefined,
 ) {
   if (!bomJson?.components) {
     return;
@@ -60,6 +101,7 @@ export function printTable(
     ],
   };
   const stream = createStream(config);
+  let displayedProvenanceCount = 0;
   stream.write([
     filterTypes?.includes("cryptographic-asset")
       ? "Asset Type / Group"
@@ -82,17 +124,23 @@ export function printTable(
         (comp.tags || []).join(", "),
       ]);
     } else {
+      if (hasComponentRegistryProvenance(comp)) {
+        displayedProvenanceCount += 1;
+      }
       stream.write([
         highlightStr(comp.group || "", highlight),
-        highlightStr(comp.name, highlight),
+        formatComponentName(comp, highlight),
         `\x1b[1;35m${comp.version || ""}\x1b[0m`,
         comp.scope || "",
         (comp.tags || []).join(", "),
       ]);
     }
   }
+  stream.end();
   console.log();
-  if (!filterTypes) {
+  if (summaryText) {
+    console.log(summaryText);
+  } else if (!filterTypes) {
     console.log(
       "BOM includes",
       bomJson?.components?.length || 0,
@@ -103,6 +151,12 @@ export function printTable(
   } else {
     console.log(`Components filtered based on type: ${filterTypes.join(", ")}`);
   }
+  if (displayedProvenanceCount > 0) {
+    printProvenanceLegend();
+    console.log(
+      `${REGISTRY_PROVENANCE_ICON} ${displayedProvenanceCount} component(s) include registry provenance or trusted publishing metadata.`,
+    );
+  }
 }
 const formatProps = (props) => {
   const retList = [];
@@ -135,6 +189,7 @@ export function printOSTable(bomJson) {
       (comp.tags || []).join(", "),
     ]);
   }
+  stream.end();
   console.log();
 }
 /**
@@ -253,6 +308,7 @@ export function printOccurrences(bomJson) {
       stream.write(row);
     }
   }
+  stream.end();
   console.log();
 }
 
@@ -324,19 +380,8 @@ export function printDependencyTree(
   if (!dependencies.length) {
     return;
   }
-  const depMap = {};
-  const shownList = [];
-  for (const d of dependencies) {
-    if (d[mode]?.length) {
-      depMap[d.ref] = d[mode].sort();
-    } else {
-      if (mode === "provides") {
-        shownList.push(d.ref);
-      }
-    }
-  }
-  const treeGraphics = [];
-  recursePrint(depMap, dependencies, 0, shownList, treeGraphics);
+  const treeGraphics = buildDependencyTreeLines(dependencies, mode);
+  const legendLines = buildDependencyTreeLegendLines(treeGraphics);
   // table library is too slow for display large lists.
   // Fixes #491
   if (treeGraphics.length && treeGraphics.length < 100) {
@@ -357,64 +402,203 @@ export function printDependencyTree(
   } else {
     console.log(highlightStr(treeGraphics.slice(0, 500).join("\n"), highlight));
   }
+  if (legendLines.length) {
+    console.log(legendLines.join("\n"));
+  }
 }
 
-const levelPrefix = (level, isLast) => {
-  if (level === 0) {
-    return SYMBOLS_ANSI.EMPTY;
+const dependencyTreePrefix = (ancestorContinuations, isLast) => {
+  let prefix = "";
+  for (const hasNextSibling of ancestorContinuations) {
+    prefix = `${prefix}${hasNextSibling ? "│   " : "    "}`;
   }
-  let prefix = `${isLast ? SYMBOLS_ANSI.LAST_BRANCH : SYMBOLS_ANSI.BRANCH}`;
-  for (let i = 0; i < level - 1; i++) {
-    prefix = `${
-      isLast
-        ? SYMBOLS_ANSI.LAST_BRANCH.replace(" ", "─")
-        : SYMBOLS_ANSI.VERTICAL
-    }${isLast ? "" : SYMBOLS_ANSI.INDENT}${prefix}`;
+  return `${prefix}${isLast ? SYMBOLS_ANSI.LAST_BRANCH : SYMBOLS_ANSI.BRANCH}`;
+};
+
+const dependencyTreeRefKey = (ref) => ref.toLowerCase();
+
+const compareDependencyTreeNodes = (a, b) => {
+  if (a.order !== b.order) {
+    return a.order - b.order;
   }
-  return prefix;
+  return a.ref.localeCompare(b.ref);
 };
 
-const isReallyRoot = (depMap, refStr) => {
-  for (const k of Object.keys(depMap)) {
-    const dependsOn = depMap[k] || [];
-    if (
-      dependsOn.includes(refStr) ||
-      dependsOn.includes(refStr.toLowerCase())
-    ) {
-      return false;
+const createDependencyTreeGraph = (dependencies, mode) => {
+  const nodes = new Map();
+  let nextOrder = 0;
+
+  const ensureNode = (ref) => {
+    if (!ref) {
+      return undefined;
+    }
+    const refKey = dependencyTreeRefKey(ref);
+    if (!nodes.has(refKey)) {
+      nodes.set(refKey, {
+        childKeys: new Set(),
+        children: [],
+        order: nextOrder,
+        parents: new Set(),
+        ref,
+      });
+      nextOrder += 1;
+    }
+    return nodes.get(refKey);
+  };
+
+  for (const dependency of dependencies) {
+    const rawChildren = Array.isArray(dependency?.[mode])
+      ? dependency[mode].filter(Boolean)
+      : [];
+    const childRefs = Array.from(new Set(rawChildren)).sort((a, b) =>
+      a.localeCompare(b),
+    );
+    let parentNode;
+    if (mode !== "provides" || childRefs.length) {
+      parentNode = ensureNode(dependency.ref);
+    }
+    if (!childRefs.length) {
+      continue;
     }
+    parentNode = parentNode || ensureNode(dependency.ref);
+    for (const childRef of childRefs) {
+      const childNode = ensureNode(childRef);
+      if (!parentNode || !childNode) {
+        continue;
+      }
+      parentNode.childKeys.add(dependencyTreeRefKey(childRef));
+      childNode.parents.add(dependencyTreeRefKey(parentNode.ref));
+    }
+  }
+
+  for (const node of nodes.values()) {
+    node.children = Array.from(node.childKeys).sort((a, b) =>
+      compareDependencyTreeNodes(nodes.get(a), nodes.get(b)),
+    );
   }
-  return true;
+
+  return nodes;
 };
 
-const recursePrint = (depMap, subtree, level, shownList, treeGraphics) => {
-  const listToUse = Array.isArray(subtree) ? subtree : [subtree];
-  for (let i = 0; i < listToUse.length; i++) {
-    const l = listToUse[i];
-    const refStr = l.ref || l;
-    if (
-      (level === 0 &&
-        isReallyRoot(depMap, refStr) &&
-        !shownList.includes(refStr.toLowerCase())) ||
-      level > 0
-    ) {
+const renderDependencyTreeNode = (
+  nodes,
+  nodeKey,
+  depth,
+  ancestorContinuations,
+  isLast,
+  renderedNodes,
+  treeGraphics,
+  visitingNodes = new Set(),
+) => {
+  const node = nodes.get(nodeKey);
+  if (!node || renderedNodes.has(nodeKey)) {
+    return;
+  }
+  const prefix =
+    depth === 0
+      ? SYMBOLS_ANSI.EMPTY
+      : dependencyTreePrefix(ancestorContinuations, isLast);
+  treeGraphics.push(`${prefix}${node.ref}`);
+  renderedNodes.add(nodeKey);
+  if (depth >= MAX_TREE_DEPTH) {
+    return;
+  }
+  const nextVisitingNodes = new Set(visitingNodes);
+  nextVisitingNodes.add(nodeKey);
+  const nextAncestorContinuations =
+    depth === 0 ? ancestorContinuations : [...ancestorContinuations, !isLast];
+  const childEntries = [];
+  for (const childKey of node.children) {
+    if (nextVisitingNodes.has(childKey)) {
+      childEntries.push({ childKey, isCycle: true });
+      continue;
+    }
+    if (renderedNodes.has(childKey)) {
+      childEntries.push({ childKey, isRepeated: true });
+      continue;
+    }
+    childEntries.push({ childKey, isCycle: false });
+  }
+  for (let i = 0; i < childEntries.length; i++) {
+    const childEntry = childEntries[i];
+    const childNode = nodes.get(childEntry.childKey);
+    const childIsLast = i === childEntries.length - 1;
+    if (!childNode) {
+      continue;
+    }
+    if (childEntry.isCycle) {
       treeGraphics.push(
-        `${levelPrefix(level, i === listToUse.length - 1)}${refStr}`,
+        `${dependencyTreePrefix(nextAncestorContinuations, childIsLast)}${CYCLE_NODE_ICON} ${childNode.ref}`,
       );
-      shownList.push(refStr.toLowerCase());
-      if (l && depMap[refStr]) {
-        if (level < MAX_TREE_DEPTH) {
-          recursePrint(
-            depMap,
-            depMap[refStr],
-            level + 1,
-            shownList,
-            treeGraphics,
-          );
-        }
-      }
+      continue;
+    }
+    if (childEntry.isRepeated) {
+      treeGraphics.push(
+        `${dependencyTreePrefix(nextAncestorContinuations, childIsLast)}${REPEATED_NODE_ICON} ${childNode.ref}`,
+      );
+      continue;
     }
+    renderDependencyTreeNode(
+      nodes,
+      childEntry.childKey,
+      depth + 1,
+      nextAncestorContinuations,
+      childIsLast,
+      renderedNodes,
+      treeGraphics,
+      nextVisitingNodes,
+    );
+  }
+};
+
+/**
+ * Builds printable dependency tree lines from a BOM dependency graph.
+ * Produces a spanning forest so shared children are rendered once, while
+ * disconnected or cyclic subgraphs are still emitted as dangling trees.
+ *
+ * @param {Object[]} dependencies CycloneDX dependency objects
+ * @param {string} [mode="dependsOn"] Dependency relation to traverse
+ * @returns {string[]} Dependency tree lines ready for console rendering
+ */
+export const buildDependencyTreeLines = (dependencies, mode = "dependsOn") => {
+  const nodes = createDependencyTreeGraph(dependencies, mode);
+  if (!nodes.size) {
+    return [];
+  }
+  const nodeEntries = Array.from(nodes.entries()).sort(([, a], [, b]) =>
+    compareDependencyTreeNodes(a, b),
+  );
+  const rootKeys = nodeEntries
+    .filter(([, node]) => !node.parents.size)
+    .map(([nodeKey]) => nodeKey);
+  const renderedNodes = new Set();
+  const treeGraphics = [];
+  for (let i = 0; i < rootKeys.length; i++) {
+    renderDependencyTreeNode(
+      nodes,
+      rootKeys[i],
+      0,
+      [],
+      i === rootKeys.length - 1,
+      renderedNodes,
+      treeGraphics,
+    );
+  }
+  const danglingNodeKeys = nodeEntries
+    .map(([nodeKey]) => nodeKey)
+    .filter((nodeKey) => !renderedNodes.has(nodeKey));
+  for (let i = 0; i < danglingNodeKeys.length; i++) {
+    renderDependencyTreeNode(
+      nodes,
+      danglingNodeKeys[i],
+      0,
+      [],
+      i === danglingNodeKeys.length - 1,
+      renderedNodes,
+      treeGraphics,
+    );
   }
+  return treeGraphics;
 };
 
 /**

package/lib/helpers/display.poku.js

@@ -1,8 +1,15 @@
 import { readFileSync } from "node:fs";
 
-import { it } from "poku";
+import esmock from "esmock";
+import { assert, it } from "poku";
+import sinon from "sinon";
 
-import { printDependencyTree } from "./display.js";
+import {
+  buildDependencyTreeLegendLines,
+  buildDependencyTreeLines,
+  printDependencyTree,
+} from "./display.js";
+import { REGISTRY_PROVENANCE_ICON } from "./provenanceUtils.js";
 
 it("print tree test", () => {
   const bomJson = JSON.parse(
@@ -10,3 +17,156 @@ it("print tree test", () => {
   );
   printDependencyTree(bomJson);
 });
+
+it("prints a provenance icon for registry-backed components", async () => {
+  const rows = [];
+  const consoleLogStub = sinon.stub(console, "log");
+  try {
+    const { printTable } = await esmock("./display.js", {
+      "./table.js": {
+        createStream: () => ({
+          end() {
+            // intentional no-op for stream stub
+          },
+          write(row) {
+            rows.push(row);
+          },
+        }),
+        table: sinon.stub().returns(""),
+      },
+      "./utils.js": {
+        isSecureMode: false,
+        safeExistsSync: sinon.stub(),
+        toCamel: sinon.stub(),
+      },
+    });
+
+    printTable(
+      {
+        components: [
+          {
+            group: "",
+            name: "left-pad",
+            properties: [
+              {
+                name: "cdx:npm:provenanceUrl",
+                value:
+                  "https://registry.npmjs.org/-/npm/v1/attestations/left-pad",
+              },
+            ],
+            type: "library",
+            version: "1.3.0",
+          },
+          {
+            group: "",
+            name: "lodash",
+            properties: [],
+            type: "library",
+            version: "4.17.21",
+          },
+        ],
+        dependencies: [],
+      },
+      undefined,
+      undefined,
+      "Found 1 trusted component.",
+    );
+
+    assert.strictEqual(rows[1][1], `${REGISTRY_PROVENANCE_ICON} left-pad`);
+    assert.strictEqual(rows[2][1], "lodash");
+    sinon.assert.calledWithExactly(
+      consoleLogStub,
+      "Found 1 trusted component.",
+    );
+    sinon.assert.calledWithExactly(
+      consoleLogStub,
+      `Legend: ${REGISTRY_PROVENANCE_ICON} = registry provenance or trusted publishing evidence`,
+    );
+    sinon.assert.calledWithExactly(
+      consoleLogStub,
+      `${REGISTRY_PROVENANCE_ICON} 1 component(s) include registry provenance or trusted publishing metadata.`,
+    );
+  } finally {
+    consoleLogStub.restore();
+  }
+});
+
+it("renders shared dependencies once while including dangling trees", () => {
+  const treeLines = buildDependencyTreeLines([
+    {
+      ref: "pkg:root/a@1.0.0",
+      dependsOn: ["pkg:shared/c@1.0.0"],
+    },
+    {
+      ref: "pkg:root/b@1.0.0",
+      dependsOn: ["pkg:shared/c@1.0.0"],
+    },
+    {
+      ref: "pkg:shared/c@1.0.0",
+      dependsOn: ["pkg:leaf/d@1.0.0"],
+    },
+    {
+      ref: "pkg:cycle/e@1.0.0",
+      dependsOn: ["pkg:cycle/f@1.0.0"],
+    },
+    {
+      ref: "pkg:cycle/f@1.0.0",
+      dependsOn: ["pkg:cycle/e@1.0.0"],
+    },
+  ]);
+
+  assert.deepStrictEqual(treeLines, [
+    "pkg:root/a@1.0.0",
+    "└── pkg:shared/c@1.0.0",
+    "    └── pkg:leaf/d@1.0.0",
+    "pkg:root/b@1.0.0",
+    "└── ⤴ pkg:shared/c@1.0.0",
+    "pkg:cycle/e@1.0.0",
+    "└── pkg:cycle/f@1.0.0",
+    "    └── ↺ pkg:cycle/e@1.0.0",
+  ]);
+  assert.deepStrictEqual(buildDependencyTreeLegendLines(treeLines), [
+    "Legend: ⤴ = already shown; ↺ = cycle",
+  ]);
+});
+
+it("omits empty providers while marking shared provides with an icon", () => {
+  const treeLines = buildDependencyTreeLines(
+    [
+      {
+        ref: "pkg:npm/app@1.0.0",
+        provides: ["crypto/aes", "crypto/sha256"],
+      },
+      {
+        ref: "pkg:npm/helper@1.0.0",
+        provides: ["crypto/sha256"],
+      },
+      {
+        ref: "pkg:npm/unused@1.0.0",
+      },
+    ],
+    "provides",
+  );
+
+  assert.deepStrictEqual(treeLines, [
+    "pkg:npm/app@1.0.0",
+    "├── crypto/aes",
+    "└── crypto/sha256",
+    "pkg:npm/helper@1.0.0",
+    "└── ⤴ crypto/sha256",
+  ]);
+  assert.deepStrictEqual(buildDependencyTreeLegendLines(treeLines), [
+    "Legend: ⤴ = already shown",
+  ]);
+});
+
+it("returns no legend lines when the dependency tree has no markers", () => {
+  assert.deepStrictEqual(
+    buildDependencyTreeLegendLines([
+      "pkg:root/a@1.0.0",
+      "└── pkg:shared/c@1.0.0",
+      "    └── pkg:leaf/d@1.0.0",
+    ]),
+    [],
+  );
+});

package/lib/helpers/exportUtils.js

@@ -0,0 +1,123 @@
+import path from "node:path";
+
+const SUPPORTED_EXPORT_FORMATS = new Set(["cyclonedx", "spdx"]);
+const EXPORT_FORMAT_ALIASES = {
+  cdx: "cyclonedx",
+  cyclonedx: "cyclonedx",
+  spdx: "spdx",
+  "spdx-json": "spdx",
+  spdx3: "spdx",
+  "spdx3-json": "spdx",
+};
+
+/**
+ * Normalize the requested export formats.
+ *
+ * @param {string|string[]|undefined|null} format Raw format value
+ * @returns {string[]} Normalized export formats
+ */
+export function normalizeOutputFormats(format) {
+  if (format === undefined || format === null || format === "") {
+    return [];
+  }
+  const values = Array.isArray(format) ? format : [format];
+  const normalized = new Set();
+  for (const value of values) {
+    if (!value) {
+      continue;
+    }
+    for (const token of `${value}`.split(",")) {
+      const normalizedToken = EXPORT_FORMAT_ALIASES[token.trim().toLowerCase()];
+      if (normalizedToken && SUPPORTED_EXPORT_FORMATS.has(normalizedToken)) {
+        normalized.add(normalizedToken);
+      }
+    }
+  }
+  return Array.from(normalized);
+}
+
+/**
+ * Derive the SPDX output path from a base output path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} SPDX output path
+ */
+export function deriveSpdxOutputPath(outputPath) {
+  if (!outputPath) {
+    return "bom.spdx.json";
+  }
+  if (outputPath.endsWith(".spdx.json")) {
+    return outputPath;
+  }
+  if (outputPath.endsWith(".cdx.json")) {
+    return outputPath.replace(/\.cdx\.json$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".json")) {
+    return outputPath.replace(/\.json$/u, ".spdx.json");
+  }
+  return `${outputPath}.spdx.json`;
+}
+
+/**
+ * Derive the CycloneDX output path from a base output path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} CycloneDX output path
+ */
+export function deriveCycloneDxOutputPath(outputPath) {
+  if (!outputPath) {
+    return "bom.json";
+  }
+  if (outputPath.endsWith(".spdx.json")) {
+    return outputPath.replace(/\.spdx\.json$/u, ".cdx.json");
+  }
+  return outputPath;
+}
+
+/**
+ * Determine the final output plan for the requested export formats.
+ *
+ * @param {object} options CLI options
+ * @returns {{ formats: Set<string>, outputs: Record<string, string>, explicitFormat: boolean }} Output plan
+ */
+export function createOutputPlan(options) {
+  const explicitFormat =
+    options?.format !== undefined &&
+    options?.format !== null &&
+    options?.format !== "";
+  const requestedFormats = normalizeOutputFormats(options?.format);
+  const outputPath = options?.output || "bom.json";
+  const formats = new Set(
+    requestedFormats.length
+      ? requestedFormats
+      : [outputPath.endsWith(".spdx.json") ? "spdx" : "cyclonedx"],
+  );
+  const outputs = {};
+  if (formats.has("cyclonedx")) {
+    outputs.cyclonedx =
+      outputPath.endsWith(".spdx.json") && formats.size > 1
+        ? deriveCycloneDxOutputPath(outputPath)
+        : outputPath;
+  }
+  if (formats.has("spdx")) {
+    if (!formats.has("cyclonedx") || outputPath.endsWith(".spdx.json")) {
+      outputs.spdx =
+        outputPath === "bom.json"
+          ? deriveSpdxOutputPath(outputPath)
+          : outputPath;
+    } else {
+      outputs.spdx = deriveSpdxOutputPath(outputPath);
+    }
+  }
+  return { formats, outputs, explicitFormat };
+}
+
+/**
+ * Return the output directory for a planned export path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} Output directory
+ */
+export function getOutputDirectory(outputPath) {
+  return path.dirname(outputPath);
+}