cve-lite-cli 1.37.0 → 1.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +20 -1
  2. package/dist/cli/args.js +121 -104
  3. package/dist/cli/flags.js +39 -0
  4. package/dist/cli/help.js +6 -3
  5. package/dist/cli/overrides.js +25 -19
  6. package/dist/cli/validate.js +31 -9
  7. package/dist/index.js +6 -1
  8. package/dist/output/compact-truncation.js +35 -0
  9. package/dist/output/formatters.js +10 -2
  10. package/dist/output/html-reporter.js +24 -12
  11. package/dist/output/multi-folder-html-reporter.js +26 -7
  12. package/dist/output/override-findings-html.js +24 -3
  13. package/dist/output/override-findings-json.js +5 -2
  14. package/dist/output/override-findings-sarif.js +1 -0
  15. package/dist/output/override-findings-terminal.js +21 -1
  16. package/dist/output/printers.js +34 -21
  17. package/dist/output/sarif.js +54 -3
  18. package/dist/output/scan-json.js +74 -0
  19. package/dist/output/skipped-override-rules.js +41 -0
  20. package/dist/output/write-outputs.js +16 -28
  21. package/dist/overrides/admitted-scan.js +12 -1
  22. package/dist/overrides/api.js +75 -21
  23. package/dist/overrides/context-builder.js +49 -6
  24. package/dist/overrides/detectors/index.js +2 -0
  25. package/dist/overrides/detectors/oa005-nested-ineffective.js +50 -2
  26. package/dist/overrides/detectors/oa008-materialized.js +72 -13
  27. package/dist/overrides/detectors/oa009-stale-floor.js +12 -15
  28. package/dist/overrides/detectors/oa010-vulnerable-floor.js +5 -1
  29. package/dist/overrides/detectors/oa011-exceeds-range.js +128 -0
  30. package/dist/overrides/detectors/pd001-override-only-phantom.js +5 -4
  31. package/dist/overrides/detectors/pd002-transitive-only-phantom.js +5 -4
  32. package/dist/overrides/detectors/phantom-utils.js +29 -0
  33. package/dist/overrides/parsing/registry.js +79 -10
  34. package/dist/scan/multi-folder-scan.js +65 -51
  35. package/dist/scan/override-audit.js +49 -0
  36. package/dist/scan/single-scan.js +109 -33
  37. package/dist/scanner.js +8 -4
  38. package/dist/skills/content.js +4 -2
  39. package/dist/usage/scanner.js +219 -28
  40. package/dist/utils/contextual-signals.js +193 -0
  41. package/dist/utils/finding.js +5 -0
  42. package/dist/utils/node-builtins.js +32 -0
  43. package/dist/utils/package-json.js +66 -14
  44. package/dist/utils/severity.js +22 -0
  45. package/dist/utils/update-check.js +2 -1
  46. package/dist/utils/version.js +37 -19
  47. package/package.json +1 -1
@@ -1,4 +1,24 @@
1
1
  import { compareVersions, isPreReleaseVersion } from '../../utils/version.js';
2
+ async function classify(attempt, parse) {
3
+ let res;
4
+ try {
5
+ res = await attempt();
6
+ }
7
+ catch {
8
+ return { kind: "failed" };
9
+ }
10
+ if (res.status === 404 || res.status === 410)
11
+ return { kind: "absent" };
12
+ if (!res.ok)
13
+ return { kind: "failed" };
14
+ try {
15
+ const value = await parse(res);
16
+ return value === null ? { kind: "absent" } : { kind: "ok", value };
17
+ }
18
+ catch {
19
+ return { kind: "failed" };
20
+ }
21
+ }
2
22
  /**
3
23
  * Fetch the `dist-tags` map for `pkgName` from the npm registry.
4
24
  *
@@ -10,6 +30,43 @@ import { compareVersions, isPreReleaseVersion } from '../../utils/version.js';
10
30
  * cache the result on `Context.registryDistTags`. This function is single-shot;
11
31
  * caching/batching is the scanner's responsibility.
12
32
  */
33
+ /** Shared request shape for both lookups. */
34
+ async function packumentOutcome(pkgName, opts, parse) {
35
+ const baseUrl = opts.baseUrl ?? 'https://registry.npmjs.org';
36
+ const timeoutMs = opts.timeoutMs ?? 5000;
37
+ const fetchImpl = opts.fetchImpl ?? fetch;
38
+ const url = `${baseUrl}/${encodeRegistryPath(pkgName)}`;
39
+ const controller = new AbortController();
40
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
41
+ try {
42
+ return await classify(() => fetchImpl(url, {
43
+ signal: controller.signal,
44
+ headers: {
45
+ Accept: 'application/vnd.npm.install-v1+json',
46
+ 'User-Agent': 'override-audit-cli',
47
+ },
48
+ }), parse);
49
+ }
50
+ finally {
51
+ clearTimeout(timer);
52
+ }
53
+ }
54
+ async function distTagsOutcome(pkgName, opts) {
55
+ return packumentOutcome(pkgName, opts, async (res) => {
56
+ const body = await res.json();
57
+ return body['dist-tags'] ?? null;
58
+ });
59
+ }
60
+ async function versionsOutcome(pkgName, opts) {
61
+ return packumentOutcome(pkgName, opts, async (res) => {
62
+ const body = await res.json();
63
+ if (!body.versions)
64
+ return null;
65
+ return Object.keys(body.versions)
66
+ .filter((v) => !isPreReleaseVersion(v))
67
+ .sort(compareVersions);
68
+ });
69
+ }
13
70
  export async function fetchDistTags(pkgName, opts = {}) {
14
71
  const baseUrl = opts.baseUrl ?? 'https://registry.npmjs.org';
15
72
  const timeoutMs = opts.timeoutMs ?? 5000;
@@ -42,14 +99,20 @@ export async function fetchDistTags(pkgName, opts = {}) {
42
99
  * (per-package), so a single 404 doesn't tank the whole batch.
43
100
  */
44
101
  export async function fetchDistTagsBatch(pkgNames, opts = {}) {
45
- const out = new Map();
102
+ const results = new Map();
103
+ const failed = [];
46
104
  const unique = Array.from(new Set(pkgNames));
47
105
  await Promise.all(unique.map(async (name) => {
48
- const tags = await fetchDistTags(name, opts);
49
- if (tags)
50
- out.set(name, tags);
106
+ const outcome = await distTagsOutcome(name, opts);
107
+ if (outcome.kind === "ok") {
108
+ results.set(name, outcome.value);
109
+ }
110
+ else if (outcome.kind === "failed") {
111
+ failed.push(name);
112
+ }
113
+ // `absent` is deliberately neither: the registry answered and said no such package.
51
114
  }));
52
- return out;
115
+ return { results, failed };
53
116
  }
54
117
  /**
55
118
  * Fetch every published version of `pkgName`, ascending, excluding prereleases.
@@ -94,14 +157,20 @@ export async function fetchVersions(pkgName, opts = {}) {
94
157
  * collapse to an absent entry rather than failing the batch.
95
158
  */
96
159
  export async function fetchVersionsBatch(pkgNames, opts = {}) {
97
- const out = new Map();
160
+ const results = new Map();
161
+ const failed = [];
98
162
  const unique = Array.from(new Set(pkgNames));
99
163
  await Promise.all(unique.map(async (name) => {
100
- const versions = await fetchVersions(name, opts);
101
- if (versions)
102
- out.set(name, versions);
164
+ const outcome = await versionsOutcome(name, opts);
165
+ if (outcome.kind === "ok") {
166
+ results.set(name, outcome.value);
167
+ }
168
+ else if (outcome.kind === "failed") {
169
+ failed.push(name);
170
+ }
171
+ // `absent` is deliberately neither, same as the dist-tags batch above.
103
172
  }));
104
- return out;
173
+ return { results, failed };
105
174
  }
106
175
  /**
107
176
  * Encode a package name for the registry URL.
@@ -4,28 +4,29 @@ import process from "node:process";
4
4
  import { EXIT_OK, EXIT_FINDINGS, EXIT_ERROR } from "../types.js";
5
5
  import { loadMultiplePackages } from "../parsers/multi-package.js";
6
6
  import { scanPackages, buildCoverageNotes } from "../scanner.js";
7
- import { sortFindingsForOutput, serializeFinding, logInfo } from "../output/formatters.js";
7
+ import { sortFindingsForOutput, logInfo } from "../output/formatters.js";
8
+ import { buildMultiFolderScanJson } from "../output/scan-json.js";
8
9
  import { resolveOutputDir, displayOutputPath } from "../output/output-dir.js";
9
10
  import { normalizeSeverity } from "../osv/severity.js";
10
11
  import { selectFindingsForTable } from "../output/finding-display.js";
11
12
  import { buildSuggestedFixCommandPlan } from "../remediation/fix-commands.js";
12
13
  import { readDirectDependencyNames, hasOverrideEntries } from "../utils/package-json.js";
13
- import { DEFAULT_SEARCH_DEPTH, severityOrder, OVERRIDES_COMMAND } from "../constants.js";
14
+ import { DEFAULT_SEARCH_DEPTH, OVERRIDES_COMMAND } from "../constants.js";
14
15
  import { printMultiFolderResults } from "../output/multi-folder-printer.js";
15
16
  import { printOverrideHint } from "../output/printers.js";
16
17
  import { writeMultiFolderHtmlReport } from "../output/multi-folder-html-reporter.js";
17
18
  import { chalk } from "../utils/chalk.js";
18
19
  import { getCliVersion } from "../utils/version-info.js";
19
- import { buildOverrideContext, audit } from "../overrides/index.js";
20
+ import { runOverrideAudit } from "./override-audit.js";
20
21
  import { NULL_AUDIT_LOG } from "../audit-log/index.js";
21
22
  import { detectDM001 } from "../maintenance/dm001-maintenance-risk.js";
22
23
  import { detectLicenseIssues } from "../licenses/license-check.js";
23
24
  import { renderLicenseFindings } from "../output/license-terminal.js";
24
- import { reachesFailOn } from "../utils/severity.js";
25
+ import { failingGateSummary } from "../utils/severity.js";
25
26
  import { readBaseline, writeBaseline, filterNewFindings, ratchetOutcome } from "../utils/baseline.js";
26
27
  import { pluralize } from "../utils/string.js";
27
28
  import { aggregateMultiFolderCompleteness, formatDiagnosticMessage, getCompletenessImpact, shouldFailForIncompleteScan, } from "./completeness.js";
28
- import { scanProjectForPackageUsage } from "../usage/scanner.js";
29
+ import { scanProjectForPackageUsage, usageScanTruncationWarning } from "../usage/scanner.js";
29
30
  export async function runMultiFolderScan(params) {
30
31
  const searchDepth = Math.max(0, Number(params.options.searchDepth || DEFAULT_SEARCH_DEPTH));
31
32
  const folders = loadMultiplePackages(params.projectRoot, !!params.options.prodOnly, searchDepth);
@@ -45,22 +46,37 @@ export async function runMultiFolderScan(params) {
45
46
  scanFilePath: scanInput.filePath,
46
47
  }, undefined, params.fetchImpl);
47
48
  // Mirror single-folder scanProject: annotate / filter by source imports per subfolder.
49
+ let usageTruncated = false;
48
50
  if (params.options.usage) {
49
51
  logInfo(`Scanning ${subfolder}/ source for usage hints...`, params.options);
50
52
  const pkgNames = new Set(findings.map(f => f.pkg.name));
51
- const usageData = scanProjectForPackageUsage(subfolderAbs, pkgNames);
53
+ const usageResult = scanProjectForPackageUsage(subfolderAbs, pkgNames);
54
+ const usageData = usageResult.usage;
55
+ usageTruncated = usageResult.truncated;
52
56
  for (const finding of findings) {
53
57
  const files = usageData[finding.pkg.name];
54
- if (files) {
55
- finding.usage = {
56
- imported: files.length > 0,
57
- files,
58
- };
58
+ if (!files)
59
+ continue;
60
+ if (files.length > 0) {
61
+ finding.usage = { imported: true, files };
62
+ }
63
+ else if (usageTruncated) {
64
+ // A truncated scan cannot prove a package is unused: unknown, not false.
65
+ finding.usage = { imported: null, files };
59
66
  }
67
+ else {
68
+ finding.usage = { imported: false, files };
69
+ }
70
+ }
71
+ if (usageResult.truncated) {
72
+ // Push into the folder's scan warnings so --json and the HTML report
73
+ // disclose it; printMultiFolderResults prints the same array in terminal mode.
74
+ scanInput.warnings.push(usageScanTruncationWarning({ subfolder, onlyUsed: !!params.options.onlyUsed }));
60
75
  }
61
76
  }
62
77
  let finalFindings = findings;
63
- if (params.options.onlyUsed) {
78
+ if (params.options.onlyUsed && !usageTruncated) {
79
+ // Truncated: "not scanned" is not "not imported", so don't narrow the gate.
64
80
  finalFindings = finalFindings.filter(f => f.usage?.imported);
65
81
  }
66
82
  let sorted = sortFindingsForOutput(finalFindings);
@@ -83,14 +99,21 @@ export async function runMultiFolderScan(params) {
83
99
  // Override hygiene is independent of the CVE ratchet/baseline. A --ratchet
84
100
  // run skips the override audit entirely (same boundary as single-folder).
85
101
  let overrideFindings = [];
102
+ let overrideSkipped = [];
86
103
  if (params.options.checkOverrides && !params.options.ratchet) {
87
- const overrideCtx = buildOverrideContext(subfolderAbs, {
104
+ // Per folder, through the same helper the single-folder path uses. Building the
105
+ // advisory source here is what lets OA010 run at all; passing only checkNetwork
106
+ // left it recording "no advisory source was available" for every folder.
107
+ const outcome = await runOverrideAudit({
108
+ projectPath: subfolderAbs,
109
+ checkNetwork: !!params.options.checkNetwork,
110
+ osvUrl: params.options.osvUrl,
88
111
  auditLog: params.auditLog ?? NULL_AUDIT_LOG,
89
112
  logger: { info: () => { }, warn: () => { }, error: () => { }, debug: () => { } },
90
- checkNetwork: !!params.options.checkNetwork,
113
+ fetchImpl: params.fetchImpl,
91
114
  });
92
- const overrideAudit = await audit(overrideCtx, { checkNetwork: !!params.options.checkNetwork });
93
- overrideFindings = overrideAudit.findings;
115
+ overrideFindings = outcome.findings;
116
+ overrideSkipped = outcome.skipped;
94
117
  }
95
118
  // Maintenance from the baseline-filtered set. Skipped under --ratchet because
96
119
  // that path always early-exits on CVE save/gate (same as single-folder).
@@ -124,6 +147,7 @@ export async function runMultiFolderScan(params) {
124
147
  allPackages: scanInput.packages,
125
148
  completeness,
126
149
  overrideFindings,
150
+ overrideSkipped,
127
151
  maintenanceFindings,
128
152
  licenseFindings,
129
153
  licenseLimitedToDirectOnly,
@@ -141,6 +165,9 @@ function handleMultiFolderRatchet(results, projectRoot, options) {
141
165
  let anyNewFindings = false;
142
166
  let hasDetectionGaps = false;
143
167
  for (const r of results) {
168
+ for (const warning of r.scanInput.warnings) {
169
+ console.log(chalk.yellow(warning));
170
+ }
144
171
  const { hasDetectionGap } = getCompletenessImpact(r.completeness);
145
172
  if (hasDetectionGap) {
146
173
  hasDetectionGaps = true;
@@ -252,33 +279,13 @@ export async function handleMultiFolderScan(params) {
252
279
  if (params.options.json) {
253
280
  // Match single-folder writeOutputs: timestamped file in cwd, not stdout dump.
254
281
  // Help text and CI both treat --json as "save a JSON file".
255
- const allFindings = results.flatMap(r => r.sorted.map(f => ({ ...serializeFinding(f, r.suggestedFixCommands), subfolder: r.subfolder })));
256
- const payload = {
257
- multiFolder: true,
282
+ const payload = buildMultiFolderScanJson({
283
+ results,
258
284
  projectPath: params.projectRoot,
259
- folders: results.map(r => r.subfolder),
260
- findingCount: allFindings.length,
261
- status: aggregatedCompleteness.complete ? "ok" : "partial",
262
- complete: aggregatedCompleteness.complete,
263
- diagnostics: aggregatedCompleteness.diagnostics,
264
- findings: allFindings,
265
- ...(params.options.checkOverrides
266
- ? {
267
- overrideFindings: results.flatMap(r => r.overrideFindings.map(f => ({ ...f, subfolder: r.subfolder }))),
268
- }
269
- : {}),
270
- ...(params.options.checkMaintenance
271
- ? {
272
- maintenanceFindings: results.flatMap(r => r.maintenanceFindings.map(f => ({ ...f, subfolder: r.subfolder }))),
273
- }
274
- : {}),
275
- ...(params.options.checkLicenses
276
- ? {
277
- licenseFindings: results.flatMap(r => r.licenseFindings.map(f => ({ ...f, subfolder: r.subfolder }))),
278
- }
279
- : {}),
280
- scannedAt: new Date().toISOString(),
281
- };
285
+ includeOverrides: !!params.options.checkOverrides,
286
+ includeMaintenance: !!params.options.checkMaintenance,
287
+ includeLicenses: !!params.options.checkLicenses,
288
+ });
282
289
  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
283
290
  const jsonFilename = `cve-lite-scan-${ts}.json`;
284
291
  const jsonOutputPath = path.join(resolveOutputDir(params.options.output), jsonFilename);
@@ -288,10 +295,13 @@ export async function handleMultiFolderScan(params) {
288
295
  else {
289
296
  printMultiFolderResults(results, params.options);
290
297
  if (params.options.checkOverrides) {
291
- const { renderOverrideFindings } = await import("../output/override-findings-terminal.js");
298
+ const { renderOverrideFindings, renderSkippedOverrideRules } = await import("../output/override-findings-terminal.js");
292
299
  for (const r of results) {
293
300
  process.stdout.write(`\n${chalk.bold.cyan(`📁 ${r.subfolder}/`)} ${chalk.gray("override hygiene")}\n`);
294
- console.log(renderOverrideFindings(r.overrideFindings, { verbose: !!params.options.verbose, projectPath: path.join(params.projectRoot, r.subfolder) }));
301
+ console.log(renderOverrideFindings(r.overrideFindings, { verbose: !!params.options.verbose, projectPath: path.join(params.projectRoot, r.subfolder), rulesSkipped: r.overrideSkipped.length > 0 }));
302
+ if (r.overrideSkipped.length > 0) {
303
+ console.log(renderSkippedOverrideRules(r.overrideSkipped));
304
+ }
295
305
  }
296
306
  }
297
307
  if (params.options.checkMaintenance) {
@@ -334,22 +344,26 @@ export async function handleMultiFolderScan(params) {
334
344
  });
335
345
  console.log(`${chalk.gray("Report:")} ${chalk.cyan(reportPath)}`);
336
346
  }
337
- const failLevel = normalizeSeverity(params.options.failOn);
338
347
  const allSorted = results.flatMap(r => r.sorted);
339
348
  const allOverrideFindings = results.flatMap(r => r.overrideFindings);
340
349
  const allMaintenanceFindings = results.flatMap(r => r.maintenanceFindings);
341
- // Mirror single-folder exit policy in src/index.ts: CVE + override + maintenance
342
- // all count toward --fail-on. Without overrides here, multi-folder CI using
343
- // --check-overrides --fail-on high would exit 0 despite high OA findings.
344
- const shouldFail = allSorted.some(f => severityOrder[f.severity] >= severityOrder[failLevel]) ||
345
- reachesFailOn(allOverrideFindings, params.options.failOn) ||
346
- reachesFailOn(allMaintenanceFindings, params.options.failOn);
350
+ // Mirror single-folder exit policy in src/scan/single-scan.ts: CVE + override +
351
+ // maintenance all count toward --fail-on. Without overrides here, multi-folder CI
352
+ // using --check-overrides --fail-on high would exit 0 despite high OA findings.
353
+ const gateLine = failingGateSummary([
354
+ { label: "vulnerability", findings: allSorted },
355
+ { label: "override hygiene", findings: allOverrideFindings },
356
+ { label: "maintenance risk", findings: allMaintenanceFindings },
357
+ ], params.options.failOn);
358
+ const shouldFail = gateLine !== null;
347
359
  const incompleteFailure = shouldFailForIncompleteScan(aggregatedCompleteness, params.options.incompletePolicy);
348
360
  const exitCode = incompleteFailure
349
361
  ? EXIT_ERROR
350
362
  : shouldFail
351
363
  ? EXIT_FINDINGS
352
364
  : EXIT_OK;
365
+ if (gateLine && !params.options.json)
366
+ console.log(chalk.red(gateLine));
353
367
  auditLog.emit({
354
368
  ts: new Date(scanFinishedAt).toISOString(),
355
369
  type: "scan.finished",
@@ -0,0 +1,49 @@
1
+ // One place that runs the override-hygiene audit, so the three entry points cannot drift
2
+ // in what they wire up: a single-folder scan, a multi-folder scan, and the `overrides`
3
+ // subcommand. That drift is what #1222 was: the scan path threaded the network opt-in
4
+ // through but never built the advisory source OA010 needs, so the rule silently no-opped
5
+ // while the flag looked wired up.
6
+ import { audit, buildOverrideContext } from "../overrides/index.js";
7
+ import { createAdvisorySource } from "../scanner.js";
8
+ export async function runOverrideAudit(params) {
9
+ const ctx = buildOverrideContext(params.projectPath, {
10
+ auditLog: params.auditLog,
11
+ logger: params.logger,
12
+ checkNetwork: params.checkNetwork,
13
+ });
14
+ // OA010 needs an advisory source on top of the network opt-in. Built here rather than
15
+ // inside audit() so the overrides module stays free of a scanner import, and closed in
16
+ // the finally so an offline database handle never leaks.
17
+ //
18
+ // Always an online source. On the scan paths that is because validate.ts rejects both
19
+ // offline flags alongside `--check-network`. On the `overrides` subcommand it is because
20
+ // that subcommand dispatches BEFORE validateOptions runs and its parser has a tight flag
21
+ // allowlist that rejects `--offline` as unknown. Two different mechanisms, same result,
22
+ // so do not remove either believing the other covers it.
23
+ //
24
+ // A consequence: createAdvisorySource only returns a real `cleanup` on its offline
25
+ // branch, so the call below is a no-op on every reachable path today. Kept as insurance
26
+ // in case an offline route ever becomes legal here.
27
+ const advisory = params.checkNetwork
28
+ ? createAdvisorySource({
29
+ osvUrl: params.osvUrl,
30
+ debugLog: params.debugLog,
31
+ fetchImpl: params.fetchImpl,
32
+ })
33
+ : null;
34
+ try {
35
+ const result = await audit(ctx, {
36
+ checkNetwork: params.checkNetwork,
37
+ advisorySource: advisory?.advisorySource,
38
+ // The registry calls behind OA007 and OA010 must use the same fetch the scan uses,
39
+ // or a corporate CA certificate configured through `config set ca-cert` never
40
+ // reaches them. NODE_EXTRA_CA_CERTS is read only at process start, which is why a
41
+ // cert-aware fetch is threaded explicitly.
42
+ registry: { fetchImpl: params.fetchImpl },
43
+ });
44
+ return { findings: result.findings, skipped: result.skippedDetectors };
45
+ }
46
+ finally {
47
+ advisory?.cleanup();
48
+ }
49
+ }
@@ -5,25 +5,26 @@ import { normalizeSeverity } from "../osv/severity.js";
5
5
  import { OVERRIDES_COMMAND } from "../constants.js";
6
6
  import { chalk } from "../utils/chalk.js";
7
7
  import { buildSuggestedFixCommandPlan } from "../remediation/fix-commands.js";
8
- import { scanProjectForPackageUsage } from "../usage/scanner.js";
8
+ import { scanProjectForPackageUsage, usageScanTruncationWarning } from "../usage/scanner.js";
9
9
  import { offlineDbSyncHint } from "../utils/network.js";
10
10
  import { formatAdvisoryDbFreshness } from "../utils/time.js";
11
11
  import { pluralize } from "../utils/string.js";
12
12
  import { EXIT_ERROR } from "../types.js";
13
13
  import { formatAdvisorySourceLine, logInfo, logWarn, printCacheSummary, sortFindingsForOutput, } from "../output/formatters.js";
14
- import { countBySeverity, reachesFailOn } from "../utils/severity.js";
14
+ import { countBySeverity, failingGateSummary } from "../utils/severity.js";
15
15
  import { buildReportData, writeHtmlReport } from "../output/html-reporter.js";
16
+ import { buildScanJson } from "../output/scan-json.js";
16
17
  import { writeOutputs } from "../output/write-outputs.js";
17
18
  import { selectFindingsForTable } from "../output/finding-display.js";
18
19
  import { printActionSummary, printCompactOutput, printCoverage, printFinalStatus, printOverrideHint, printSkippedDependencies, printSuggestedFixCommands, printSuggestedFixCommandSkips, printSummary, printTable, } from "../output/printers.js";
19
- import { renderOverrideFindings } from "../output/override-findings-terminal.js";
20
+ import { renderOverrideFindings, renderSkippedOverrideRules } from "../output/override-findings-terminal.js";
20
21
  import { detectDM001 } from "../maintenance/dm001-maintenance-risk.js";
21
22
  import { renderMaintenanceFindings } from "../output/maintenance-terminal.js";
22
23
  import { detectLicenseIssues } from "../licenses/license-check.js";
23
24
  import { renderLicenseFindings } from "../output/license-terminal.js";
24
25
  import { readDirectDependencyNames, hasOverrideEntries } from "../utils/package-json.js";
25
26
  import { applyFixesIfRequested, printFixModeSummary, writeFixResultJson, } from "../utils/fix-runner.js";
26
- import { audit, buildOverrideContext } from "../overrides/index.js";
27
+ import { runOverrideAudit } from "./override-audit.js";
27
28
  import { buildFixResultAppliedEntries, createPullRequestForFixes, } from "../utils/create-pr.js";
28
29
  import { buildCveFixAppliedEvent } from "../audit-log/events.js";
29
30
  import { readBaseline, writeBaseline, filterNewFindings, ratchetOutcome } from "../utils/baseline.js";
@@ -151,8 +152,12 @@ export async function handleSingleFolderScan(params) {
151
152
  // --ratchet run skips the override audit entirely - override findings are never
152
153
  // baselined or suppressed.
153
154
  let overrideFindings = [];
155
+ let overrideSkipped = [];
154
156
  if (options.checkOverrides && !options.ratchet) {
155
- const overrideCtx = buildOverrideContext(projectPath, {
157
+ const outcome = await runOverrideAudit({
158
+ projectPath,
159
+ checkNetwork: !!options.checkNetwork,
160
+ osvUrl: options.osvUrl,
156
161
  auditLog,
157
162
  logger: {
158
163
  info: (msg) => debugLog("oa.info", { message: msg }),
@@ -160,10 +165,11 @@ export async function handleSingleFolderScan(params) {
160
165
  error: (msg) => debugLog("oa.error", { message: msg }),
161
166
  debug: (msg) => debugLog("oa.debug", { message: msg }),
162
167
  },
163
- checkNetwork: !!options.checkNetwork,
168
+ debugLog,
169
+ fetchImpl,
164
170
  });
165
- const auditResult = await audit(overrideCtx, { checkNetwork: !!options.checkNetwork });
166
- overrideFindings = auditResult.findings;
171
+ overrideFindings = outcome.findings;
172
+ overrideSkipped = outcome.skipped;
167
173
  }
168
174
  let maintenanceFindings = [];
169
175
  let licenseFindings = [];
@@ -439,6 +445,9 @@ export async function handleSingleFolderScan(params) {
439
445
  tableFindings: scanState.tableFindings,
440
446
  completeness: scanState.completeness,
441
447
  overrideFindings,
448
+ // undefined when override checking was not requested, so an absent field in the
449
+ // JSON means "never audited" rather than "audited and nothing skipped".
450
+ overrideSkipped: options.checkOverrides ? overrideSkipped : undefined,
442
451
  maintenanceFindings,
443
452
  licenseFindings,
444
453
  licenseLimitedToDirectOnly,
@@ -468,7 +477,10 @@ export async function handleSingleFolderScan(params) {
468
477
  }
469
478
  }
470
479
  if (options.checkOverrides && overrideFindings.length > 0) {
471
- console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: true, projectPath }));
480
+ console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: true, projectPath, rulesSkipped: overrideSkipped.length > 0 }));
481
+ }
482
+ if (options.checkOverrides && overrideSkipped.length > 0) {
483
+ console.log("\n" + renderSkippedOverrideRules(overrideSkipped));
472
484
  }
473
485
  if (options.checkMaintenance && maintenanceFindings.length > 0) {
474
486
  console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: true }));
@@ -494,7 +506,10 @@ export async function handleSingleFolderScan(params) {
494
506
  licenseLimitedToDirectOnly: options.checkLicenses ? licenseLimitedToDirectOnly : undefined,
495
507
  });
496
508
  if (options.checkOverrides) {
497
- console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: false, projectPath }));
509
+ console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: false, projectPath, rulesSkipped: overrideSkipped.length > 0 }));
510
+ }
511
+ if (options.checkOverrides && overrideSkipped.length > 0) {
512
+ console.log("\n" + renderSkippedOverrideRules(overrideSkipped));
498
513
  }
499
514
  if (options.checkMaintenance && maintenanceFindings.length > 0) {
500
515
  console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: false }));
@@ -520,15 +535,42 @@ export async function handleSingleFolderScan(params) {
520
535
  // undefined (not []) when override checking was not requested, so the HTML
521
536
  // report omits the Override hygiene panel entirely on a plain scan.
522
537
  overrideFindings: options.checkOverrides ? overrideFindings : undefined,
538
+ skippedOverrideRules: options.checkOverrides ? overrideSkipped : undefined,
523
539
  // Same undefined-vs-[] convention as overrideFindings above.
524
540
  maintenanceFindings: options.checkMaintenance ? maintenanceFindings : undefined,
525
541
  licenseFindings: options.checkLicenses ? licenseFindings : undefined,
526
542
  licenseLimitedToDirectOnly: options.checkLicenses ? licenseLimitedToDirectOnly : undefined,
527
543
  completeness: scanState.completeness,
528
544
  });
545
+ // report.json follows the --json schema, plus scannedAt/cliVersion/
546
+ // lockfileSource for a saved artifact and per-finding riskSummary/nextAction (stdout --json
547
+ // stays unchanged via buildScanJson alone).
548
+ const jsonPayload = {
549
+ ...buildScanJson({
550
+ projectPath,
551
+ scanInput,
552
+ findings: scanState.sorted,
553
+ suggestedFixCommands: scanState.suggestedFixCommands,
554
+ coverage: scanState.coverage,
555
+ completeness: scanState.completeness,
556
+ overrideFindings,
557
+ // Gated on the flag deliberately, unlike overrideFindings above. An absent
558
+ // skippedOverrideRules means override checking never ran; an empty array means it
559
+ // ran and every rule ran. Passing this unconditionally would collapse the two.
560
+ overrideSkipped: options.checkOverrides ? overrideSkipped : undefined,
561
+ maintenanceFindings,
562
+ licenseFindings,
563
+ licenseLimitedToDirectOnly,
564
+ }),
565
+ scannedAt: reportData.scannedAt,
566
+ cliVersion: reportData.cliVersion,
567
+ lockfileSource: reportData.lockfileSource,
568
+ findings: reportData.findings,
569
+ };
529
570
  const { reportPath } = await writeHtmlReport({
530
571
  outputDir,
531
572
  data: reportData,
573
+ jsonPayload,
532
574
  autoOpen: !options.noOpen,
533
575
  });
534
576
  console.log(`${chalk.gray("Report:")} ${chalk.cyan(reportPath)}`);
@@ -546,15 +588,20 @@ export async function handleSingleFolderScan(params) {
546
588
  console.log(chalk.yellow(`${scanState.sorted.length} new ${scanState.sorted.length === 1 ? "finding" : "findings"} above baseline - ${suppressedCount} existing ${suppressedCount === 1 ? "finding" : "findings"} suppressed`));
547
589
  }
548
590
  }
549
- // Override hygiene findings count toward --fail-on too, using the shared
550
- // reachesFailOn helper from src/utils/severity.ts, the same logic used by
551
- // the standalone `overrides` command. Without this, a CI run
591
+ // Override hygiene findings count toward --fail-on too. Without this, a CI run
552
592
  // of `cve-lite . --check-overrides --fail-on high` would exit 0 despite high-severity
553
593
  // override findings, giving a false sense of protection. overrideFindings is empty
554
594
  // unless --check-overrides (and non-ratchet), so this is a no-op otherwise.
555
- const shouldFail = reachesFailOn(scanState.sorted, options.failOn) ||
556
- reachesFailOn(overrideFindings, options.failOn) ||
557
- reachesFailOn(maintenanceFindings, options.failOn);
595
+ // The gate and the line that explains it come from one call, so the exit code
596
+ // and the printed reason cannot drift apart.
597
+ const gateLine = failingGateSummary([
598
+ { label: "vulnerability", findings: scanState.sorted },
599
+ { label: "override hygiene", findings: overrideFindings },
600
+ { label: "maintenance risk", findings: maintenanceFindings },
601
+ ], options.failOn);
602
+ const shouldFail = gateLine !== null;
603
+ if (gateLine && !options.json && !options.fix)
604
+ console.log(chalk.red(gateLine));
558
605
  // In fix mode, remaining transitive findings cannot be auto-fixed.
559
606
  // Exiting non-zero would prevent the Action PR step from running.
560
607
  const incompleteFailure = shouldFailForIncompleteScan(scanState.completeness, options.incompletePolicy);
@@ -581,42 +628,71 @@ export async function scanProject(params) {
581
628
  scanSource: params.scanInput.source,
582
629
  scanFilePath: params.scanInput.filePath,
583
630
  }, params.debugLog, params.fetchImpl);
631
+ let usageTruncated = false;
584
632
  if (params.options.usage) {
585
633
  logInfo(`Scanning project source for usage hints...`, params.options);
586
634
  const usageStartedAt = Date.now();
587
635
  const pkgNames = new Set(findings.map(f => f.pkg.name));
588
- const usageData = scanProjectForPackageUsage(params.projectPath, pkgNames);
636
+ const usageResult = scanProjectForPackageUsage(params.projectPath, pkgNames);
637
+ const usageData = usageResult.usage;
638
+ usageTruncated = usageResult.truncated;
589
639
  let matchedPackages = 0;
590
640
  for (const finding of findings) {
591
641
  const files = usageData[finding.pkg.name];
592
- if (files) {
593
- if (files.length > 0) {
594
- matchedPackages += 1;
595
- }
596
- finding.usage = {
597
- imported: files.length > 0,
598
- files,
599
- };
642
+ if (!files)
643
+ continue;
644
+ if (files.length > 0) {
645
+ matchedPackages += 1;
646
+ finding.usage = { imported: true, files };
647
+ }
648
+ else if (usageTruncated) {
649
+ // Absence during a truncated walk is not proof of non-use: unknown, not false.
650
+ finding.usage = { imported: null, files };
651
+ }
652
+ else {
653
+ // Only a complete scan can conclude a package is genuinely unused.
654
+ finding.usage = { imported: false, files };
600
655
  }
601
656
  }
657
+ if (usageResult.truncated) {
658
+ // Push into the scan warnings so machine consumers (--json, HTML report)
659
+ // see the same disclosure the terminal prints.
660
+ const warning = usageScanTruncationWarning({ onlyUsed: !!params.options.onlyUsed });
661
+ params.scanInput.warnings.push(warning);
662
+ logWarn(warning, params.options);
663
+ }
602
664
  if (params.options.debug) {
603
665
  params.debugLog("Usage scan", {
604
666
  durationMs: Date.now() - usageStartedAt,
605
667
  packagesChecked: pkgNames.size,
606
668
  matchedPackages,
669
+ truncated: usageResult.truncated,
670
+ scannedFiles: usageResult.scannedFiles,
607
671
  });
608
672
  }
609
673
  }
610
674
  let finalFindings = findings;
611
675
  if (params.options.onlyUsed) {
612
- const beforeCount = finalFindings.length;
613
- finalFindings = finalFindings.filter(f => f.usage?.imported);
614
- if (params.options.debug) {
615
- params.debugLog("Findings filtered", {
616
- reason: "only-used",
617
- before: beforeCount,
618
- after: finalFindings.length,
619
- });
676
+ if (usageTruncated) {
677
+ // Truncated: absence is not proof of unused; keep findings so --fail-on isn't narrowed.
678
+ if (params.options.debug) {
679
+ params.debugLog("Findings filtered", {
680
+ reason: "only-used-skipped-truncated-usage-scan",
681
+ before: findings.length,
682
+ after: findings.length,
683
+ });
684
+ }
685
+ }
686
+ else {
687
+ const beforeCount = finalFindings.length;
688
+ finalFindings = finalFindings.filter(f => f.usage?.imported);
689
+ if (params.options.debug) {
690
+ params.debugLog("Findings filtered", {
691
+ reason: "only-used",
692
+ before: beforeCount,
693
+ after: finalFindings.length,
694
+ });
695
+ }
620
696
  }
621
697
  }
622
698
  const offline = !!params.options.offline || !!params.options.offlineDb;