dependency-radar 0.6.1 → 0.8.0

package/dist/cli.js

@@ -8,14 +8,24 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const os_1 = require("os");
 const aggregator_1 = require("./aggregator");
+const explain_1 = require("./explain");
 const importGraphRunner_1 = require("./runners/importGraphRunner");
 const npmAudit_1 = require("./runners/npmAudit");
 const npmLs_1 = require("./runners/npmLs");
 const npmOutdated_1 = require("./runners/npmOutdated");
+const lockfileSignals_1 = require("./runners/lockfileSignals");
 const report_1 = require("./report");
+const compare_1 = require("./compare");
+const outputFormats_1 = require("./outputFormats");
+const why_1 = require("./why");
+const schema_1 = require("./schema");
 const failOn_1 = require("./failOn");
 const promises_1 = __importDefault(require("fs/promises"));
 const utils_1 = require("./utils");
+const skippedToolResult = {
+    ok: true,
+    status: "skipped",
+};
 function normalizeSlashes(p) {
     return p.split(path_1.default.sep).join("/");
 }
@@ -424,6 +434,8 @@ function inferPackageManager(rootPkg) {
         return "pnpm";
     if (raw.startsWith("yarn@") || raw === "yarn")
         return "yarn";
+    if (raw.startsWith("bun@") || raw === "bun")
+        return "bun";
     if (raw.startsWith("npm@") || raw === "npm")
         return "npm";
     return undefined;
@@ -436,6 +448,8 @@ async function detectPackageManager(projectPath, rootPkg, workspaceType) {
         return workspaceType;
     if (await detectYarnPnP(projectPath))
         return "yarn";
+    if ((await (0, utils_1.pathExists)(path_1.default.join(projectPath, "bun.lock"))) || (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "bun.lockb"))))
+        return "bun";
     if (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "node_modules", ".pnpm")))
         return "pnpm";
     if (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "node_modules", ".yarn-state.yml")))
@@ -443,10 +457,14 @@ async function detectPackageManager(projectPath, rootPkg, workspaceType) {
     return "npm";
 }
 async function detectScanManager(projectPath, fallback) {
+    if (fallback === "bun" && ((await (0, utils_1.pathExists)(path_1.default.join(projectPath, "bun.lock"))) || (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "bun.lockb")))))
+        return "bun";
     if (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "pnpm-lock.yaml")))
         return "pnpm";
     if (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "yarn.lock")))
         return "yarn";
+    if ((await (0, utils_1.pathExists)(path_1.default.join(projectPath, "bun.lock"))) || (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "bun.lockb"))))
+        return "bun";
     if ((await (0, utils_1.pathExists)(path_1.default.join(projectPath, "package-lock.json"))) ||
         (await (0, utils_1.pathExists)(path_1.default.join(projectPath, "npm-shrinkwrap.json")))) {
         return "npm";
@@ -910,11 +928,15 @@ function buildCombinedDependencyGraph(rootPath, packageMetas, dependencyGraphs)
     return { name: "dependency-radar-workspace", version: "0.0.0", dependencies };
 }
 /**
- * Parse command-line tokens into a populated CliOptions object.
+ * Parse CLI tokens and return a configured CliOptions object reflecting the requested command and flags.
+ *
+ * Recognizes an optional leading command (scan, explain, compare, why, schema), positional operands for
+ * commands that require them (package name for explain/why, compare path for compare), and these flags:
+ * --project, --quiet, --out, --keep-temp, --offline, --json, --format, --sbom, --target-node,
+ * --audit-signatures, --schema, --timestamp, --open, --no-report, --fail-on, --help / -h.
  *
- * Recognizes a leading non-flag token as the command and the following flags:
- * --project, --out, --keep-temp, --offline, --json, --open, --no-report, --fail-on, and --help / -h.
- * The --offline flag disables both audit and outdated checks.
+ * The --offline flag disables both audit and outdated checks. Unknown options or unexpected positional
+ * arguments cause the process to exit with an error.
  *
  * @param argv - Array of CLI tokens (typically process.argv.slice(2))
  * @returns The resolved CliOptions with defaults applied and values overridden by argv
@@ -922,7 +944,9 @@ function buildCombinedDependencyGraph(rootPath, packageMetas, dependencyGraphs)
 function parseArgs(argv) {
     const opts = {
         command: "scan",
+        commandProvided: false,
         project: process.cwd(),
+        quiet: false,
         out: "dependency-radar.html",
         keepTemp: false,
         audit: true,
@@ -931,27 +955,87 @@ function parseArgs(argv) {
         open: false,
         noReport: false,
         failOn: new Set(),
+        format: "html",
+        auditSignatures: false,
+        schema: false,
+        outProvided: false,
+        timestamp: false,
     };
     const args = [...argv];
     if (args[0] && !args[0].startsWith("-")) {
-        opts.command = args.shift();
+        const command = args.shift();
+        if (command === "scan" || command === "explain" || command === "compare" || command === "why" || command === "schema") {
+            opts.command = command;
+            opts.commandProvided = true;
+        }
+        else {
+            opts.invalidCommand = command;
+            return opts;
+        }
     }
     while (args.length) {
         const arg = args.shift();
         if (!arg)
             break;
-        if (arg === "--project" && args[0])
-            opts.project = args.shift();
-        else if (arg === "--out" && args[0])
-            opts.out = args.shift();
+        if (!arg.startsWith("-") && (opts.command === "explain" || opts.command === "why") && !opts.packageName) {
+            opts.packageName = arg;
+        }
+        else if (!arg.startsWith("-") && opts.command === "compare" && !opts.comparePath) {
+            opts.comparePath = arg;
+        }
+        else if (!arg.startsWith("-")) {
+            console.error(`Unexpected argument: "${arg}".`);
+            process.exit(1);
+        }
+        else if (arg === "--project")
+            opts.project = takeOptionValue(args, arg, true);
+        else if (arg === "--quiet")
+            opts.quiet = true;
+        else if (arg === "--out") {
+            opts.out = takeOptionValue(args, arg, true);
+            opts.outProvided = true;
+        }
         else if (arg === "--keep-temp")
             opts.keepTemp = true;
         else if (arg === "--offline") {
             opts.audit = false;
             opts.outdated = false;
         }
-        else if (arg === "--json")
+        else if (arg === "--json") {
             opts.json = true;
+            opts.format = "json";
+        }
+        else if (arg === "--format") {
+            const format = takeOptionValue(args, arg);
+            if (!isReportFormat(format)) {
+                console.error(`Unknown --format: "${format}". Supported formats: html, json, sarif, cyclonedx, spdx.`);
+                process.exit(1);
+            }
+            opts.format = format;
+            opts.json = format === "json";
+        }
+        else if (arg === "--sbom") {
+            const format = takeOptionValue(args, arg);
+            if (format !== "cyclonedx" && format !== "spdx") {
+                console.error('Unknown --sbom format. Supported formats: cyclonedx, spdx.');
+                process.exit(1);
+            }
+            opts.format = format;
+        }
+        else if (arg === "--target-node") {
+            const value = Number.parseInt(takeOptionValue(args, arg), 10);
+            if (!Number.isFinite(value) || value <= 0) {
+                console.error("--target-node must be a positive Node.js major version.");
+                process.exit(1);
+            }
+            opts.targetNodeMajor = value;
+        }
+        else if (arg === "--audit-signatures")
+            opts.auditSignatures = true;
+        else if (arg === "--schema")
+            opts.schema = true;
+        else if (arg === "--timestamp")
+            opts.timestamp = true;
         else if (arg === "--open")
             opts.open = true;
         else if (arg === "--no-report")
@@ -979,31 +1063,128 @@ function parseArgs(argv) {
             printHelp();
             process.exit(0);
         }
+        else {
+            console.error(`Unknown option: "${arg}".`);
+            process.exit(1);
+        }
     }
     return opts;
 }
+/**
+ * Extracts and returns the next CLI token as the value for a given option, consuming it from `args`.
+ *
+ * @param args - Remaining argv tokens; the first element will be removed and returned.
+ * @param option - The option name shown in the error message when a value is missing.
+ * @param allowLeadingDash - When `true`, permit values that begin with `-`; otherwise treat such tokens as missing values.
+ * @returns The consumed option value.
+ * @remarks Exits the process with code 1 and prints an error if no valid value is present.
+ */
+function takeOptionValue(args, option, allowLeadingDash = false) {
+    const value = args[0];
+    if (!value || (!allowLeadingDash && value.startsWith("-"))) {
+        console.error(`Missing value for ${option}.`);
+        process.exit(1);
+    }
+    return args.shift();
+}
+/**
+ * Checks whether a string is a supported report format.
+ *
+ * @param value - The string to test
+ * @returns `true` if `value` is one of `html`, `json`, `sarif`, `cyclonedx`, or `spdx`, `false` otherwise.
+ */
+function isReportFormat(value) {
+    return value === "html" || value === "json" || value === "sarif" || value === "cyclonedx" || value === "spdx";
+}
+/**
+ * Formats a numeric date/time component as a two-digit string.
+ *
+ * @param value - The numeric part (e.g., day, month, hour, or minute) to format
+ * @returns The value as a two-character string, padded with a leading zero when needed
+ */
+function padDatePart(value) {
+    return String(value).padStart(2, "0");
+}
+/**
+ * Formats a Date into a filesystem-safe timestamp string suitable for filenames.
+ *
+ * @param date - The date to format (local time is used).
+ * @returns A string in the form `YYYY-MM-DD_HH-MM-SS` (zero-padded).
+ */
+function formatFilenameTimestamp(date) {
+    return [
+        date.getFullYear(),
+        padDatePart(date.getMonth() + 1),
+        padDatePart(date.getDate()),
+    ].join("-") + "_" + [
+        padDatePart(date.getHours()),
+        padDatePart(date.getMinutes()),
+        padDatePart(date.getSeconds()),
+    ].join("-");
+}
+/**
+ * Insert a local timestamp into the filename portion of an output path.
+ *
+ * If the path has a file extension, the timestamp is inserted before the extension;
+ * otherwise the timestamp is appended to the filename. The directory portion is preserved.
+ *
+ * @param outputPath - The file path whose filename will receive the timestamp
+ * @param date - Date to derive the timestamp from; defaults to the current date/time
+ * @returns The input path with a timestamp embedded into the filename, preserving directory and extension
+ */
+function addTimestampToOutputPath(outputPath, date = new Date()) {
+    const parsed = path_1.default.parse(outputPath);
+    const timestamp = formatFilenameTimestamp(date);
+    const basename = parsed.ext
+        ? `${parsed.name}.${timestamp}${parsed.ext}`
+        : `${parsed.name}.${timestamp}`;
+    return path_1.default.join(parsed.dir, basename);
+}
+/**
+ * Determines whether the given package manager uses registry-based collectors.
+ *
+ * @returns `true` if the manager is `npm`, `pnpm`, or `yarn`, `false` otherwise.
+ */
+function supportsRegistryCollectors(manager) {
+    return manager === "npm" || manager === "pnpm" || manager === "yarn";
+}
 /**
  * Print the CLI usage and available options to the console.
  *
  * Displays the command synopsis and descriptions for supported flags including
- * --project, --out, --json, --no-report, --keep-temp, --offline, --open, and --fail-on.
+ * --project, --out, --json, --timestamp, --no-report, --keep-temp, --offline, --open, and --fail-on.
  */
 function printHelp() {
     console.log(`dependency-radar [scan] [options]
+dependency-radar explain <package-name> [options]
+dependency-radar why <package-name> [options]
+dependency-radar compare <previous dependency-radar.json> [options]
 
 If no command is provided, \`scan\` is run by default.
 
 Options:
   --project <path>   Project folder (default: cwd)
-  --out <path>       Output HTML file (default: dependency-radar.html)
+  --quiet            Suppress progress/info logs but keep summary and failures
+  --out <path>       Output file (default depends on format)
+  --format <format>  Output format: html, json, sarif, cyclonedx, spdx
+  --sbom <format>    Write an SBOM: cyclonedx or spdx
+  --target-node <n>  Add Node major compatibility findings
+  --audit-signatures Verify npm registry signatures/provenance (opt-in, online only)
+  --schema           Print JSON schema, or write it when --out is provided
   --json             Write aggregated data to JSON (default filename: dependency-radar.json)
+  --timestamp        Add a local timestamp to generated report filenames
   --no-report        Do not write HTML/JSON report files or temp artifacts to disk
   --keep-temp        Keep .dependency-radar folder
   --offline          Skip npm audit and npm outdated (useful for offline scans)
   --open             Open the generated report using the system default application
   --fail-on <rules>  Fail with exit code 1 when selected rules are violated
                      Supported: reachable-vuln, production-vuln, high-severity-vuln,
-                                licence-mismatch, copyleft-detected, unknown-licence
+                                licence-mismatch, copyleft-detected, unknown-licence,
+                                supply-chain-source
+
+\`explain\` reuses the same local scan model and prints a terminal view for one package.
+\`why\` prints shortest dependency paths for one package.
+\`compare\` scans the current project and compares it with a previous JSON report.
 `);
 }
 /**
@@ -1070,6 +1251,20 @@ function shouldUseColor() {
     return Boolean(process.stdout.isTTY);
 }
 const COLOR_ENABLED = shouldUseColor();
+function supportsTerminalHyperlinks() {
+    if (!process.stdout.isTTY)
+        return false;
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.TERM === "dumb")
+        return false;
+    return true;
+}
+function formatTerminalLink(label, url) {
+    if (!supportsTerminalHyperlinks())
+        return label;
+    return `\u001B]8;;${url}\u0007${label}\u001B]8;;\u0007`;
+}
 /**
  * Wraps text with ANSI color or style escape sequences when terminal coloring is enabled.
  *
@@ -1270,10 +1465,10 @@ function printCliSummary(summary) {
     const bullet = "•";
     console.log("");
     console.log("Summary:");
-    console.log(`${bullet} Direct deps scanned: ${summary.directDeps}`);
-    console.log(`${bullet} Transitive deps scanned: ${summary.transitiveDeps}`);
+    console.log(`${bullet} Direct dependencies scanned: ${summary.directDeps}`);
+    console.log(`${bullet} Transitive dependencies scanned: ${summary.transitiveDeps}`);
     console.log(`${bullet} Vulnerable packages: ${summary.vulnerablePackages} (${summary.reachableVulnerablePackages} reachable)`);
-    console.log(`${bullet} Unused installed deps: ${summary.unusedInstalledDeps}`);
+    console.log(`${bullet} Dependencies with no static import reference: ${summary.unusedInstalledDeps}`);
     console.log(`${bullet} License mismatches: ${summary.licenseMismatches}`);
     console.log(`${bullet} Major upgrade blockers: ${summary.majorUpgradeBlockers}`);
     const blockerDetails = [];
@@ -1297,36 +1492,45 @@ function printCliSummary(summary) {
     }
     console.log("");
 }
+function formatLabel(format) {
+    if (format === "html")
+        return "Report";
+    if (format === "json")
+        return "JSON";
+    if (format === "sarif")
+        return "SARIF";
+    if (format === "cyclonedx")
+        return "CycloneDX SBOM";
+    return "SPDX SBOM";
+}
 /**
- * Run the CLI "scan" command to collect and aggregate dependency data for a project or workspace.
+ * Run a full dependency analysis for a project/workspace and return the aggregated results.
+ *
+ * Performs workspace detection, per-package collection (audit, dependency trees, import graphs, outdated), merges collected data, runs aggregation and policy evaluation, and optionally writes report artifacts to disk. May create a temporary directory under the project (projectPath/.dependency-radar) and will remove it unless `opts.keepTemp` is set.
  *
- * Detects workspace type and package manager, runs per-package collectors (audit, dependency tree, import graph, outdated),
- * merges collected signals into a workspace-level model, and writes a JSON or HTML report according to CLI options.
- * Manages a temporary working directory and optionally opens the generated report. Exits the process with a non-zero code
- * on fatal errors or when configured policy violations are detected.
+ * @param opts - CLI-resolved options controlling project path, enabled collectors (audit/outdated), artifact format/output, reporting flags, and policy rules.
+ * @param options.shouldWriteArtifacts - If true, write report artifacts (JSON/HTML/SBOM) to the resolved output path.
+ * @param options.emitArtifactSummary - If true, print a summary line about artifact creation to stdout.
+ * @param options.emitWorkspacePackageSummary - If true, print a brief workspace package summary when a workspace is detected.
+ * @returns An AnalysisExecutionResult containing the aggregated report, CLI summary, policy violations, dependency counts, timing, output path/creation status, collector availability, and workspace metadata.
  */
-async function run() {
-    var _a;
-    const opts = parseArgs(process.argv.slice(2));
-    if (opts.command !== "scan") {
-        printHelp();
-        process.exit(1);
-        return;
-    }
-    const shouldWriteArtifacts = !opts.noReport;
+async function executeAnalysis(opts, options) {
+    var _a, _b;
+    const shouldWriteArtifacts = options.shouldWriteArtifacts;
     const projectPath = path_1.default.resolve(opts.project);
-    let summary;
-    let policyViolations = [];
-    if (opts.noReport && opts.keepTemp) {
-        console.log(statusLine("⚠", "--keep-temp is ignored when --no-report is enabled."));
-    }
-    if (opts.json && opts.out === "dependency-radar.html") {
-        opts.out = "dependency-radar.json";
-    }
-    let outputPath = path_1.default.resolve(opts.out);
+    let outputPath = opts.outProvided
+        ? path_1.default.resolve(opts.out)
+        : path_1.default.resolve(projectPath, opts.out);
     const startTime = Date.now();
     let dependencyCount = 0;
     let outputCreated = false;
+    if (opts.command === "scan" && opts.noReport && opts.keepTemp && !opts.quiet) {
+        console.log(statusLine("⚠", "--keep-temp is ignored when --no-report is enabled."));
+    }
+    if (!opts.outProvided && opts.format !== "html") {
+        opts.out = (0, outputFormats_1.defaultOutputName)(opts.format);
+        outputPath = path_1.default.resolve(projectPath, opts.out);
+    }
     if (shouldWriteArtifacts) {
         try {
             const stat = await promises_1.default.stat(outputPath).catch(() => undefined);
@@ -1335,22 +1539,24 @@ async function run() {
             if ((stat && stat.isDirectory()) ||
                 endsWithSeparator ||
                 (!stat && !hasExtension)) {
-                outputPath = path_1.default.join(outputPath, opts.json ? "dependency-radar.json" : "dependency-radar.html");
+                outputPath = path_1.default.join(outputPath, (0, outputFormats_1.defaultOutputName)(opts.format));
             }
         }
-        catch (e) {
+        catch {
             // ignore, best-effort path normalization
         }
+        if (opts.timestamp) {
+            outputPath = addTimestampToOutputPath(outputPath);
+        }
     }
     const tempDir = path_1.default.join(projectPath, ".dependency-radar");
-    // Stage 1: detect workspace/package-manager context and collect tool versions.
     const workspace = await detectWorkspace(projectPath);
     const yarnPnP = await detectYarnPnP(projectPath);
     if (workspace.type === "yarn" && workspace.packagePaths.length === 0) {
-        console.error("Yarn Plug'n'Play (nodeLinker: pnp) detected. This is not supported yet.");
-        console.error("Switch to nodeLinker: node-modules or run in a non-PnP environment.");
-        process.exit(1);
-        return;
+        if (!opts.quiet) {
+            console.log(statusLine("⚠", "Yarn Plug'n'Play detected; using the root package and yarn.lock where possible."));
+        }
+        workspace.packagePaths = [projectPath];
     }
     const hasProjectNodeModules = await (0, utils_1.pathExists)(path_1.default.join(projectPath, "node_modules"));
     if (!hasProjectNodeModules) {
@@ -1358,9 +1564,9 @@ async function run() {
             ? "single project"
             : `${workspace.type.toUpperCase()} workspace`;
         const yarnHint = yarnPnP
-            ? " Yarn Plug'n'Play appears enabled; Dependency Radar currently requires node_modules linker."
+            ? " Yarn Plug'n'Play appears enabled; lockfile graph data will be used where possible, but package metadata from zip/cache files is not crawled in this release."
             : "";
-        console.warn(colorLeadingSymbol(`⚠ node_modules was not found at ${projectPath}. Scan completeness may be reduced for this ${workspaceHint}. Run your package manager install (npm install, pnpm install, or yarn install) before scanning.${yarnHint}`));
+        console.warn(colorLeadingSymbol(`⚠ node_modules was not found at ${projectPath}. Scan completeness may be reduced for this ${workspaceHint}. Run your package manager install before scanning when local package metadata is required.${yarnHint}`));
     }
     const rootPkg = await readJsonFile(path_1.default.join(projectPath, "package.json"));
     const projectDependencyPolicy = workspace.pnpmWorkspaceOverrides
@@ -1379,42 +1585,49 @@ async function run() {
         getToolVersion("pnpm", projectPath),
         getToolVersion("yarn", projectPath),
     ]);
+    const bunVersion = await getToolVersion("bun", projectPath);
     const toolVersions = compactToolVersions({
         npm: npmVersion,
         pnpm: pnpmVersion,
         yarn: yarnVersion,
+        bun: bunVersion,
     });
     const packageManagerVersion = scanManager === "npm"
         ? npmVersion
         : scanManager === "pnpm"
             ? pnpmVersion
-            : yarnVersion;
-    if (packageManager === "yarn" && yarnPnP) {
-        console.error("Yarn Plug'n'Play (nodeLinker: pnp) detected. This is not supported yet.");
-        console.error("Switch to nodeLinker: node-modules or run in a non-PnP environment.");
-        process.exit(1);
-        return;
+            : scanManager === "yarn"
+                ? yarnVersion
+                : bunVersion;
+    if (!opts.quiet && packageManager === "yarn" && yarnPnP) {
+        console.log(statusLine("⚠", "Yarn Plug'n'Play detected; using lockfile-derived graph data where available."));
     }
     const packagePaths = workspace.packagePaths;
     const workspaceLabel = workspace.type === "none"
         ? "Single project"
         : `${workspace.type.toUpperCase()} workspace`;
-    console.log(statusLine("✔", `${workspaceLabel} detected`));
-    if (workspace.type !== "none" && scanManager !== workspace.type) {
+    if (!opts.quiet) {
+        console.log(statusLine("✔", `${workspaceLabel} detected`));
+    }
+    if (!opts.quiet && workspace.type !== "none" && scanManager !== workspace.type) {
         console.log(statusLine("✔", `Using ${scanManager.toUpperCase()} for dependency data (lockfile detected)`));
     }
-    const spinner = startSpinner(`Scanning ${workspaceLabel} at ${projectPath}`);
+    const spinner = createProgressReporter(`Scanning ${workspaceLabel} at ${projectPath}`, opts.quiet);
     try {
         if (shouldWriteArtifacts) {
             await (0, utils_1.ensureDir)(tempDir);
         }
-        // Stage 2: run per-package collectors and persist raw tool outputs.
         const packageMetas = await readWorkspacePackageMeta(projectPath, packagePaths);
         const workspaceClassification = buildWorkspaceClassification(projectPath, packageMetas);
         const perPackageAudit = [];
         const perPackageLs = [];
         const perPackageImportGraph = [];
         const perPackageOutdated = [];
+        const supplyChainResult = await (0, lockfileSignals_1.runLockfileSupplyChainSignals)(projectPath, tempDir, {
+            persistToDisk: shouldWriteArtifacts,
+            auditSignatures: opts.auditSignatures,
+            offline: !opts.audit
+        }).catch((err) => ({ ok: false, error: String(err) }));
         for (const meta of packageMetas) {
             spinner.update(`Scanning ${workspaceLabel} (${perPackageLs.length + 1}/${packageMetas.length}) at ${projectPath}`);
             const pkgTempDir = path_1.default.join(tempDir, meta.name.replace(/[^a-zA-Z0-9._-]/g, "_"));
@@ -1423,8 +1636,9 @@ async function run() {
             }
             const [a, l, ig, o] = await Promise.all([
                 opts.audit
+                    && supportsRegistryCollectors(scanManager)
                     ? (0, npmAudit_1.runPackageAudit)(meta.path, pkgTempDir, scanManager, yarnVersion, { persistToDisk: shouldWriteArtifacts }).catch((err) => ({ ok: false, error: String(err) }))
-                    : Promise.resolve(undefined),
+                    : Promise.resolve(opts.audit ? skippedToolResult : undefined),
                 (0, npmLs_1.runNpmLs)(meta.path, pkgTempDir, scanManager, {
                     contextLabel: meta.name,
                     lockfileSearchRoot: projectPath,
@@ -1435,31 +1649,36 @@ async function run() {
                     persistToDisk: shouldWriteArtifacts,
                 }).catch((err) => ({ ok: false, error: String(err) })),
                 opts.outdated
+                    && supportsRegistryCollectors(scanManager)
                     ? (0, npmOutdated_1.runPackageOutdated)(meta.path, pkgTempDir, scanManager, { persistToDisk: shouldWriteArtifacts }).catch((err) => ({ ok: false, error: String(err) }))
-                    : Promise.resolve(undefined),
+                    : Promise.resolve(opts.outdated ? skippedToolResult : undefined),
             ]);
             perPackageAudit.push(a);
             perPackageLs.push(l);
             perPackageImportGraph.push(ig);
             perPackageOutdated.push({ attempted: Boolean(opts.outdated), result: o });
         }
-        // Stage 3: merge per-package results into a workspace-level view.
         if (opts.audit) {
             const auditOk = perPackageAudit.every((r) => r && r.ok);
-            if (auditOk) {
-                spinner.log(statusLine("✔", `${scanManager.toUpperCase()} audit data collected`));
+            const auditSkipped = perPackageAudit.every((r) => (r === null || r === void 0 ? void 0 : r.status) === "skipped");
+            if (!opts.quiet || !auditOk) {
+                spinner.log(statusLine(auditSkipped ? "ℹ" : auditOk ? "✔" : "✖", `${scanManager.toUpperCase()} audit data ${auditSkipped ? "skipped" : auditOk ? "collected" : "unavailable"}`));
+            }
+        }
+        if (opts.auditSignatures && !opts.quiet) {
+            const audit = supplyChainResult.ok ? (_a = supplyChainResult.data) === null || _a === void 0 ? void 0 : _a.signatureAudit : undefined;
+            if ((audit === null || audit === void 0 ? void 0 : audit.status) === "skipped") {
+                spinner.log(statusLine("⚠", "npm audit signatures skipped (--offline)"));
             }
             else {
-                spinner.log(statusLine("✖", `${scanManager.toUpperCase()} audit data unavailable`));
+                spinner.log(statusLine((audit === null || audit === void 0 ? void 0 : audit.ok) ? "✔" : "✖", `npm audit signatures ${(audit === null || audit === void 0 ? void 0 : audit.ok) ? "verified" : "unavailable"}`));
             }
         }
         if (opts.outdated) {
             const outdatedOk = perPackageOutdated.every((r) => r.result && r.result.ok);
-            if (outdatedOk) {
-                spinner.log(statusLine("✔", `${scanManager.toUpperCase()} outdated data collected`));
-            }
-            else {
-                spinner.log(statusLine("✖", `${scanManager.toUpperCase()} outdated data unavailable`));
+            const outdatedSkipped = perPackageOutdated.every((r) => { var _a; return ((_a = r.result) === null || _a === void 0 ? void 0 : _a.status) === "skipped"; });
+            if (!opts.quiet || !outdatedOk) {
+                spinner.log(statusLine(outdatedSkipped ? "ℹ" : outdatedOk ? "✔" : "✖", `${scanManager.toUpperCase()} outdated data ${outdatedSkipped ? "skipped" : outdatedOk ? "collected" : "unavailable"}`));
             }
         }
         const mergedAuditData = mergeAuditResults(perPackageAudit.map((r) => (r && r.ok ? r.data : undefined)));
@@ -1476,7 +1695,6 @@ async function run() {
             : undefined;
         const npmLsResult = { ok: true, data: mergedGraphData };
         const importGraphResult = { ok: true, data: mergedImportGraphData };
-        // Build a merged package.json view for aggregator direct-dep checks.
         const mergedPkgForAggregator = mergeDepsFromWorkspace(packageMetas, workspaceClassification.workspacePackageNames, workspaceClassification.localDependencyNames);
         const auditFailure = opts.audit
             ? perPackageAudit.find((r) => r && !r.ok)
@@ -1491,18 +1709,18 @@ async function run() {
         if (lsFailures.length > 0) {
             const packageList = lsFailures.map((entry) => { var _a; return (_a = entry.meta) === null || _a === void 0 ? void 0 : _a.name; }).filter(Boolean);
             spinner.log(`Dependency tree warning: ${lsFailures.length} package${lsFailures.length === 1 ? "" : "s"} failed (${packageList.join(", ")}).`);
-            spinner.log(`First dependency tree error: ${((_a = lsFailures[0].result) === null || _a === void 0 ? void 0 : _a.error) || "pnpm ls failed"}`);
+            spinner.log(`First dependency tree error: ${((_b = lsFailures[0].result) === null || _b === void 0 ? void 0 : _b.error) || "pnpm ls failed"}`);
         }
         if (importFailures.length > 0) {
             spinner.log(`Import graph warning: ${importFailures.length} package${importFailures.length === 1 ? "" : "s"} failed (${importFailures[0].error || "import graph failed"})`);
         }
-        // Stage 4: aggregate all signals into the final report model.
         const aggregated = await (0, aggregator_1.aggregateData)({
             projectPath,
             auditResult,
             npmLsResult,
             importGraphResult,
             outdatedResult,
+            supplyChainResult,
             pkgOverride: mergedPkgForAggregator,
             projectPackageJson: rootPkg,
             ...(projectDependencyPolicy ? { projectDependencyPolicy } : {}),
@@ -1530,78 +1748,258 @@ async function run() {
             arch: process.arch,
             ci: isCI(),
             ...(toolVersions ? { toolVersions } : {}),
+            ...(typeof opts.targetNodeMajor === "number" ? { targetNodeMajor: opts.targetNodeMajor } : {}),
         });
         dependencyCount = Object.keys(aggregated.dependencies).length;
         const importGraphComplete = perPackageImportGraph.every((result) => result.ok);
-        summary = buildCliSummary(aggregated, {
+        const summary = buildCliSummary(aggregated, {
             importGraphComplete,
         });
-        policyViolations = (0, failOn_1.evaluatePolicyViolations)(aggregated, opts.failOn);
-        if (workspace.type !== "none") {
+        const policyViolations = (0, failOn_1.evaluatePolicyViolations)(aggregated, opts.failOn);
+        if (!opts.quiet && options.emitWorkspacePackageSummary && workspace.type !== "none") {
             console.log(`Detected ${workspace.type.toUpperCase()} workspace with ${packagePaths.length} package${packagePaths.length === 1 ? "" : "s"}.`);
         }
         if (dependencyCount > 0 && shouldWriteArtifacts) {
-            if (opts.json) {
+            if (opts.format === "json") {
                 await promises_1.default.mkdir(path_1.default.dirname(outputPath), { recursive: true });
                 await promises_1.default.writeFile(outputPath, JSON.stringify(aggregated, null, 2), "utf8");
             }
+            else if (opts.format === "sarif") {
+                await promises_1.default.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+                await promises_1.default.writeFile(outputPath, (0, outputFormats_1.renderSarif)(aggregated), "utf8");
+            }
+            else if (opts.format === "cyclonedx") {
+                await promises_1.default.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+                await promises_1.default.writeFile(outputPath, (0, outputFormats_1.renderCycloneDx)(aggregated), "utf8");
+            }
+            else if (opts.format === "spdx") {
+                await promises_1.default.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+                await promises_1.default.writeFile(outputPath, (0, outputFormats_1.renderSpdx)(aggregated), "utf8");
+            }
             else {
                 await (0, report_1.renderReport)(aggregated, outputPath);
             }
             outputCreated = true;
         }
         spinner.stop(true);
-        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-        console.log(statusLine("✔", `Scan complete: ${dependencyCount} dependencies analysed in ${elapsed}s`));
-        if (!shouldWriteArtifacts) {
-            console.log(statusLine("ℹ", "Report output disabled (--no-report); no report artifacts written."));
+        const elapsedSeconds = ((Date.now() - startTime) / 1000).toFixed(1);
+        if (!opts.quiet) {
+            console.log(statusLine("✔", `Scan complete: ${dependencyCount} dependencies analysed in ${elapsedSeconds}s`));
         }
-        else if (outputCreated) {
-            console.log(statusLine("✔", `${opts.json ? "JSON" : "Report"} written to ${outputPath}`));
-        }
-        else {
-            console.log(statusLine("✖", `No dependencies were found - ${opts.json ? "JSON file" : "Report"} not created`));
+        if (!opts.quiet && options.emitArtifactSummary) {
+            if (!shouldWriteArtifacts) {
+                console.log(statusLine("ℹ", "Report output disabled (--no-report); no report artifacts written."));
+            }
+            else if (outputCreated) {
+                console.log(statusLine("✔", `${formatLabel(opts.format)} written to ${outputPath}`));
+            }
+            else {
+                console.log(statusLine("✖", `No dependencies were found - ${formatLabel(opts.format)} not created`));
+            }
         }
+        return {
+            aggregated,
+            summary,
+            policyViolations,
+            dependencyCount,
+            elapsedSeconds,
+            outputCreated,
+            outputPath,
+            shouldWriteArtifacts,
+            collectorAvailability: {
+                audit: !opts.audit
+                    ? "skipped"
+                    : perPackageAudit.every((result) => result && result.ok)
+                        ? "available"
+                        : "unavailable",
+                importGraphComplete,
+            },
+            workspace,
+            packagePaths,
+        };
     }
     catch (err) {
         spinner.stop(false);
-        console.error("Failed to generate report:", err);
-        process.exit(1);
+        throw err;
     }
     finally {
         if (shouldWriteArtifacts) {
             if (!opts.keepTemp) {
                 await (0, utils_1.removeDir)(tempDir);
             }
-            else {
+            else if (!opts.quiet) {
                 console.log(statusLine("✔", `Temporary data kept at ${tempDir}`));
             }
         }
     }
-    if (opts.open && !shouldWriteArtifacts) {
-        console.log(statusLine("✖", "Skipping auto-open because --no-report is enabled."));
+}
+async function runScanCommand(opts) {
+    const result = await executeAnalysis(opts, {
+        shouldWriteArtifacts: !opts.noReport,
+        emitArtifactSummary: true,
+        emitWorkspacePackageSummary: true,
+    });
+    if (!opts.quiet) {
+        if (opts.open && !result.shouldWriteArtifacts) {
+            console.log(statusLine("✖", "Skipping auto-open because --no-report is enabled."));
+        }
+        else if (opts.open && result.outputCreated && !isCI()) {
+            console.log(statusLine("↗", `Opening ${path_1.default.basename(result.outputPath)} using system default ${opts.format === "html" ? "browser" : "application"}.`));
+            openInBrowser(result.outputPath);
+        }
+        else if (opts.open && result.outputCreated && isCI()) {
+            console.log(statusLine("✖", "Skipping auto-open in CI environment."));
+        }
+    }
+    printCliSummary(result.summary);
+    printPolicyViolations(result.policyViolations);
+    if (!opts.quiet) {
+        console.log(`Enrich this scan with maintenance signals, upgrade readiness, and risk modelling at ${formatTerminalLink("https://www.dependency-radar.com", "https://www.dependency-radar.com")}`);
+    }
+    if (result.policyViolations.length > 0) {
+        process.exit(1);
+    }
+}
+async function runExplainCommand(opts) {
+    var _a;
+    const packageName = (_a = opts.packageName) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!packageName) {
+        console.error("Missing package name for explain. Usage: dependency-radar explain <package-name>");
+        process.exit(1);
+        return;
+    }
+    const result = await executeAnalysis(opts, {
+        shouldWriteArtifacts: false,
+        emitArtifactSummary: false,
+        emitWorkspacePackageSummary: false,
+    });
+    const matches = (0, explain_1.findDependenciesByPackageName)(result.aggregated, packageName);
+    console.log("");
+    console.log((0, explain_1.formatExplainOutput)(packageName, matches, {
+        audit: result.collectorAvailability.audit,
+        importGraphComplete: result.collectorAvailability.importGraphComplete,
+    }));
+    if (matches.length === 0) {
+        process.exit(1);
+    }
+}
+async function runWhyCommand(opts) {
+    var _a;
+    const packageName = (_a = opts.packageName) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!packageName) {
+        console.error("Missing package name for why. Usage: dependency-radar why <package-name>");
+        process.exit(1);
+        return;
+    }
+    const result = await executeAnalysis(opts, {
+        shouldWriteArtifacts: false,
+        emitArtifactSummary: false,
+        emitWorkspacePackageSummary: false,
+    });
+    console.log("");
+    const output = (0, why_1.formatWhyOutput)(result.aggregated, packageName);
+    console.log(output);
+    if (output.startsWith("Package not found")) {
+        process.exit(1);
+    }
+}
+async function runCompareCommand(opts) {
+    var _a;
+    const previousPath = (_a = opts.comparePath) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!previousPath) {
+        console.error("Missing previous report path. Usage: dependency-radar compare <previous dependency-radar.json>");
+        process.exit(1);
+        return;
     }
-    else if (opts.open && outputCreated && !isCI()) {
-        console.log(statusLine("↗", `Opening ${path_1.default.basename(outputPath)} using system default ${opts.json ? "application" : "browser"}.`));
-        openInBrowser(outputPath);
+    let previous;
+    try {
+        const parsed = JSON.parse(await promises_1.default.readFile(path_1.default.resolve(previousPath), "utf8"));
+        const schemaVersion = parsed && typeof parsed === "object" ? parsed.schemaVersion : undefined;
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            schemaVersion !== schema_1.REPORT_SCHEMA_VERSION ||
+            !parsed.project ||
+            !parsed.summary ||
+            !parsed.dependencies ||
+            typeof parsed.dependencies !== "object") {
+            console.error(`Previous report schema mismatch: expected schemaVersion ${schema_1.REPORT_SCHEMA_VERSION}, found ${schemaVersion !== null && schemaVersion !== void 0 ? schemaVersion : "missing"}.`);
+            process.exit(1);
+            return;
+        }
+        previous = parsed;
     }
-    else if (opts.open && outputCreated && isCI()) {
-        console.log(statusLine("✖", "Skipping auto-open in CI environment."));
+    catch (err) {
+        console.error(`Could not read previous report at ${previousPath}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+        return;
     }
-    if (summary) {
-        printCliSummary(summary);
+    const result = await executeAnalysis(opts, {
+        shouldWriteArtifacts: false,
+        emitArtifactSummary: false,
+        emitWorkspacePackageSummary: false,
+    });
+    console.log("");
+    console.log((0, compare_1.formatCompareOutput)((0, compare_1.compareReports)(previous, result.aggregated)));
+}
+/**
+ * Run the CLI entrypoint and dispatch to the selected command.
+ */
+async function run() {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.invalidCommand) {
+        printHelp();
+        process.exit(1);
+        return;
     }
-    else {
-        console.log("");
+    try {
+        if ((opts.schema && !opts.commandProvided) || opts.command === "schema") {
+            await runSchemaCommand(opts);
+            return;
+        }
+        if (opts.command === "explain") {
+            await runExplainCommand(opts);
+            return;
+        }
+        if (opts.command === "why") {
+            await runWhyCommand(opts);
+            return;
+        }
+        if (opts.command === "compare") {
+            await runCompareCommand(opts);
+            return;
+        }
+        await runScanCommand(opts);
     }
-    printPolicyViolations(policyViolations);
-    // Always show CTA as the last output
-    console.log("Enrich this scan with maintenance signals, upgrade readiness, and risk modelling at dependency-radar.com");
-    if (policyViolations.length > 0) {
+    catch (err) {
+        console.error("Failed to generate report:", err);
         process.exit(1);
     }
 }
+async function runSchemaCommand(opts) {
+    const schema = (0, schema_1.renderReportJsonSchema)();
+    if (opts.outProvided) {
+        const outputPath = path_1.default.resolve(opts.out);
+        await promises_1.default.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+        await promises_1.default.writeFile(outputPath, schema, "utf8");
+        if (!opts.quiet) {
+            console.log(statusLine("✔", `JSON schema written to ${outputPath}`));
+        }
+        return;
+    }
+    console.log(schema);
+}
 run();
+function createProgressReporter(text, quiet) {
+    if (!quiet)
+        return startSpinner(text);
+    return {
+        stop: () => { },
+        update: () => { },
+        log: (line) => {
+            process.stdout.write(`${colorLeadingSymbol(line)}\n`);
+        },
+    };
+}
 /**
  * Displays a rotating CLI spinner with a message and returns controls to stop, update, or log lines.
  *