@cyclonedx/cdxgen 12.2.1 → 12.3.0

package/lib/audit/progress.js

@@ -0,0 +1,137 @@
+import process from "node:process";
+
+const ASCII_FRAMES = ["-", "\\", "|", "/"];
+const CLEAR_LINE = "\r\x1b[2K";
+
+/**
+ * Build a human-readable label for an audit target.
+ *
+ * @param {object} target audit target
+ * @returns {string} formatted target label
+ */
+export function formatTargetLabel(target) {
+  const namespacePrefix = target?.namespace ? `${target.namespace}/` : "";
+  const versionSuffix = target?.version ? `@${target.version}` : "";
+  return `${target?.type || "pkg"}:${namespacePrefix}${target?.name || "unknown"}${versionSuffix}`;
+}
+
+/**
+ * Decide if interactive progress should be shown.
+ *
+ * @param {object} [options] progress options
+ * @returns {boolean} true when spinner-style progress is appropriate
+ */
+export function shouldRenderProgress(options = {}) {
+  if (options.enabled === false) {
+    return false;
+  }
+  const stream = options.stream || process.stderr;
+  if (!stream?.isTTY) {
+    return false;
+  }
+  return process.env.CI !== "true";
+}
+
+/**
+ * Create a dependency-free progress renderer for cdx-audit.
+ *
+ * Progress is always written to stderr so JSON/stdout reports remain clean.
+ *
+ * @param {object} [options] progress options
+ * @returns {{ onProgress: Function, stop: Function }} progress controller
+ */
+export function createProgressTracker(options = {}) {
+  const stream = options.stream || process.stderr;
+  const enabled = shouldRenderProgress({
+    enabled: options.enabled,
+    stream,
+  });
+  let frameIndex = 0;
+  let hasActiveLine = false;
+
+  /**
+   * Write a line or redraw the active line.
+   *
+   * @param {string} text output text
+   * @param {boolean} persist whether to end the line permanently
+   * @returns {void}
+   */
+  function render(text, persist = false) {
+    if (!enabled) {
+      if (persist) {
+        stream.write(`${text}\n`);
+      }
+      return;
+    }
+    stream.write(`${CLEAR_LINE}${text}`);
+    hasActiveLine = true;
+    if (persist) {
+      stream.write("\n");
+      hasActiveLine = false;
+    }
+  }
+
+  /**
+   * Produce the next spinner frame.
+   *
+   * @returns {string} spinner frame
+   */
+  function nextFrame() {
+    const frame = ASCII_FRAMES[frameIndex % ASCII_FRAMES.length];
+    frameIndex += 1;
+    return frame;
+  }
+
+  return {
+    onProgress(event) {
+      const total = event?.total || event?.summary?.totalTargets || 0;
+      if (event?.type === "run:info") {
+        render(event.message, true);
+        return;
+      }
+      if (event?.type === "run:start") {
+        render(
+          `Preparing predictive audit for ${total} package(s)...`,
+          !enabled,
+        );
+        return;
+      }
+      if (event?.type === "target:start") {
+        render(
+          `[${event.index}/${event.total}] ${nextFrame()} ${event.label} — resolving source`,
+        );
+        return;
+      }
+      if (event?.type === "target:stage") {
+        render(
+          `[${event.index}/${event.total}] ${nextFrame()} ${event.label} — ${event.stage}`,
+        );
+        return;
+      }
+      if (event?.type === "target:finish") {
+        const finalSeverity = event?.result?.assessment?.severity || "none";
+        const finalStatus =
+          event?.result?.status === "audited"
+            ? finalSeverity.toUpperCase()
+            : event?.result?.status?.toUpperCase() || "DONE";
+        render(
+          `[${event.index}/${event.total}] done ${event.label} — ${finalStatus}`,
+          true,
+        );
+        return;
+      }
+      if (event?.type === "run:finish") {
+        const summary = event.summary || {};
+        render(
+          `Completed predictive audit: ${summary.scannedTargets || 0}/${summary.totalTargets || 0} scanned, ${summary.erroredTargets || 0} errored, ${summary.skippedTargets || 0} skipped.`,
+          true,
+        );
+      }
+    },
+    stop() {
+      if (enabled && hasActiveLine) {
+        stream.write(CLEAR_LINE);
+      }
+    },
+  };
+}

package/lib/audit/progress.poku.js

@@ -0,0 +1,188 @@
+import process from "node:process";
+
+import { assert, describe, it } from "poku";
+
+import {
+  createProgressTracker,
+  formatTargetLabel,
+  shouldRenderProgress,
+} from "./progress.js";
+
+function createStream(isTTY = true) {
+  return {
+    isTTY,
+    writes: [],
+    write(chunk) {
+      this.writes.push(chunk);
+    },
+  };
+}
+
+describe("formatTargetLabel()", () => {
+  it("formats namespace and version when present", () => {
+    assert.strictEqual(
+      formatTargetLabel({
+        name: "requests",
+        namespace: "pallets",
+        type: "pypi",
+        version: "2.32.3",
+      }),
+      "pypi:pallets/requests@2.32.3",
+    );
+  });
+});
+
+describe("shouldRenderProgress()", () => {
+  it("disables interactive progress for non-tty streams", () => {
+    assert.strictEqual(
+      shouldRenderProgress({
+        stream: createStream(false),
+      }),
+      false,
+    );
+  });
+});
+
+describe("createProgressTracker()", () => {
+  it("persists preflight info messages before target execution begins", () => {
+    const originalCI = process.env.CI;
+    delete process.env.CI;
+
+    try {
+      const stream = createStream(true);
+      const tracker = createProgressTracker({ stream });
+
+      tracker.onProgress({
+        message:
+          "Predictive audit selected 50 of 120 package(s) (12 required + 38 additional) using required-first prioritization. This may take several minutes depending on repository lookups and child SBOM generation.",
+        total: 50,
+        type: "run:info",
+      });
+      tracker.onProgress({
+        total: 50,
+        type: "run:start",
+      });
+      tracker.stop();
+
+      const output = stream.writes.join("");
+      assert.match(output, /selected 50 of 120 package\(s\)/);
+      assert.match(
+        output,
+        /Preparing predictive audit for 50 package\(s\)\.\.\./,
+      );
+    } finally {
+      if (originalCI === undefined) {
+        delete process.env.CI;
+      } else {
+        process.env.CI = originalCI;
+      }
+    }
+  });
+
+  it("renders the current package name and stage to stderr-like streams in interactive mode", () => {
+    const originalCI = process.env.CI;
+    delete process.env.CI;
+
+    try {
+      const stream = createStream(true);
+      const tracker = createProgressTracker({ stream });
+
+      tracker.onProgress({
+        total: 2,
+        type: "run:start",
+      });
+      tracker.onProgress({
+        index: 1,
+        label: "npm:left-pad@1.3.0",
+        total: 2,
+        type: "target:start",
+      });
+      tracker.onProgress({
+        index: 1,
+        label: "npm:left-pad@1.3.0",
+        stage: "generating child SBOM",
+        total: 2,
+        type: "target:stage",
+      });
+      tracker.onProgress({
+        index: 1,
+        label: "npm:left-pad@1.3.0",
+        result: {
+          assessment: {
+            severity: "medium",
+          },
+          status: "audited",
+        },
+        total: 2,
+        type: "target:finish",
+      });
+      tracker.stop();
+
+      const output = stream.writes.join("");
+      assert.match(output, /npm:left-pad@1.3.0/);
+      assert.match(output, /generating child SBOM/);
+      assert.match(output, /done npm:left-pad@1.3.0 — MEDIUM/);
+    } finally {
+      if (originalCI === undefined) {
+        delete process.env.CI;
+      } else {
+        process.env.CI = originalCI;
+      }
+    }
+  });
+
+  it("persists only start and finish updates when CI disables interactive progress", () => {
+    const originalCI = process.env.CI;
+    process.env.CI = "true";
+
+    try {
+      const stream = createStream(true);
+      const tracker = createProgressTracker({ stream });
+
+      tracker.onProgress({
+        total: 2,
+        type: "run:start",
+      });
+      tracker.onProgress({
+        index: 1,
+        label: "npm:left-pad@1.3.0",
+        total: 2,
+        type: "target:start",
+      });
+      tracker.onProgress({
+        index: 1,
+        label: "npm:left-pad@1.3.0",
+        stage: "generating child SBOM",
+        total: 2,
+        type: "target:stage",
+      });
+      tracker.onProgress({
+        index: 1,
+        label: "npm:left-pad@1.3.0",
+        result: {
+          assessment: {
+            severity: "medium",
+          },
+          status: "audited",
+        },
+        total: 2,
+        type: "target:finish",
+      });
+      tracker.stop();
+
+      const output = stream.writes.join("");
+      assert.match(
+        output,
+        /Preparing predictive audit for 2 package\(s\)\.\.\./,
+      );
+      assert.doesNotMatch(output, /generating child SBOM/);
+      assert.match(output, /done npm:left-pad@1.3.0 — MEDIUM/);
+    } finally {
+      if (originalCI === undefined) {
+        delete process.env.CI;
+      } else {
+        process.env.CI = originalCI;
+      }
+    }
+  });
+});