cve-lite-cli 1.36.1 → 1.38.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 (57) hide show
  1. package/README.md +25 -3
  2. package/dist/advisory/local-db.js +22 -3
  3. package/dist/audit-log/events.js +14 -0
  4. package/dist/cli/args.js +125 -102
  5. package/dist/cli/flags.js +39 -0
  6. package/dist/cli/help.js +8 -3
  7. package/dist/cli/overrides.js +25 -19
  8. package/dist/cli/validate.js +34 -9
  9. package/dist/index.js +6 -1
  10. package/dist/output/compact-truncation.js +35 -0
  11. package/dist/output/cyclonedx.js +6 -3
  12. package/dist/output/formatters.js +10 -2
  13. package/dist/output/html-reporter.js +31 -15
  14. package/dist/output/multi-folder-html-reporter.js +26 -7
  15. package/dist/output/output-dir.js +20 -0
  16. package/dist/output/override-findings-html.js +24 -3
  17. package/dist/output/override-findings-json.js +5 -2
  18. package/dist/output/override-findings-sarif.js +1 -0
  19. package/dist/output/override-findings-terminal.js +21 -1
  20. package/dist/output/printers.js +52 -25
  21. package/dist/output/sarif.js +63 -6
  22. package/dist/output/sbom-file.js +6 -4
  23. package/dist/output/scan-json.js +74 -0
  24. package/dist/output/skipped-override-rules.js +41 -0
  25. package/dist/output/spdx.js +2 -2
  26. package/dist/output/write-outputs.js +22 -32
  27. package/dist/overrides/admitted-scan.js +12 -1
  28. package/dist/overrides/api.js +75 -21
  29. package/dist/overrides/context-builder.js +17 -2
  30. package/dist/overrides/detectors/index.js +2 -0
  31. package/dist/overrides/detectors/oa008-materialized.js +74 -14
  32. package/dist/overrides/detectors/oa009-stale-floor.js +12 -15
  33. package/dist/overrides/detectors/oa010-vulnerable-floor.js +5 -1
  34. package/dist/overrides/detectors/oa011-exceeds-range.js +128 -0
  35. package/dist/overrides/detectors/pd001-override-only-phantom.js +5 -4
  36. package/dist/overrides/detectors/pd002-transitive-only-phantom.js +5 -4
  37. package/dist/overrides/detectors/phantom-utils.js +29 -0
  38. package/dist/overrides/parsing/registry.js +79 -10
  39. package/dist/remediation/fix-commands.js +89 -31
  40. package/dist/remediation/npm-registry.js +9 -1
  41. package/dist/remediation/parent-update-child-note.js +11 -0
  42. package/dist/scan/multi-folder-scan.js +68 -53
  43. package/dist/scan/override-audit.js +49 -0
  44. package/dist/scan/single-scan.js +115 -44
  45. package/dist/scanner.js +35 -11
  46. package/dist/skills/content.js +4 -2
  47. package/dist/usage/scanner.js +219 -28
  48. package/dist/utils/contextual-signals.js +193 -0
  49. package/dist/utils/create-pr.js +21 -2
  50. package/dist/utils/finding.js +5 -0
  51. package/dist/utils/fix-runner.js +15 -2
  52. package/dist/utils/package-json.js +66 -14
  53. package/dist/utils/severity.js +22 -0
  54. package/dist/utils/update-check.js +2 -1
  55. package/dist/utils/version.js +81 -86
  56. package/package.json +3 -1
  57. package/scripts/pr-scan-delta.mjs +7 -4
@@ -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,26 +5,28 @@ 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 { collectAdvisoryIdsForPackage, createPullRequestForFixes, } from "../utils/create-pr.js";
27
+ import { runOverrideAudit } from "./override-audit.js";
28
+ import { buildFixResultAppliedEntries, createPullRequestForFixes, } from "../utils/create-pr.js";
29
+ import { buildCveFixAppliedEvent } from "../audit-log/events.js";
28
30
  import { readBaseline, writeBaseline, filterNewFindings, ratchetOutcome } from "../utils/baseline.js";
29
31
  import { formatDiagnosticMessage, getCompletenessImpact, shouldFailForIncompleteScan } from "./completeness.js";
30
32
  export async function handleSingleFolderScan(params) {
@@ -150,8 +152,12 @@ export async function handleSingleFolderScan(params) {
150
152
  // --ratchet run skips the override audit entirely - override findings are never
151
153
  // baselined or suppressed.
152
154
  let overrideFindings = [];
155
+ let overrideSkipped = [];
153
156
  if (options.checkOverrides && !options.ratchet) {
154
- const overrideCtx = buildOverrideContext(projectPath, {
157
+ const outcome = await runOverrideAudit({
158
+ projectPath,
159
+ checkNetwork: !!options.checkNetwork,
160
+ osvUrl: options.osvUrl,
155
161
  auditLog,
156
162
  logger: {
157
163
  info: (msg) => debugLog("oa.info", { message: msg }),
@@ -159,10 +165,11 @@ export async function handleSingleFolderScan(params) {
159
165
  error: (msg) => debugLog("oa.error", { message: msg }),
160
166
  debug: (msg) => debugLog("oa.debug", { message: msg }),
161
167
  },
162
- checkNetwork: !!options.checkNetwork,
168
+ debugLog,
169
+ fetchImpl,
163
170
  });
164
- const auditResult = await audit(overrideCtx, { checkNetwork: !!options.checkNetwork });
165
- overrideFindings = auditResult.findings;
171
+ overrideFindings = outcome.findings;
172
+ overrideSkipped = outcome.skipped;
166
173
  }
167
174
  let maintenanceFindings = [];
168
175
  let licenseFindings = [];
@@ -260,15 +267,15 @@ export async function handleSingleFolderScan(params) {
260
267
  // Emit cve.fix.applied for each target in the fix plan
261
268
  if (scanState.suggestedFixCommands?.targets) {
262
269
  for (const target of scanState.suggestedFixCommands.targets) {
263
- auditLog.emit({
270
+ auditLog.emit(buildCveFixAppliedEvent({
264
271
  ts: new Date().toISOString(),
265
- type: "cve.fix.applied",
266
- schemaVersion: 1,
267
272
  package: target.package,
268
273
  fromVersion: target.currentVersion ?? "unknown",
269
274
  toVersion: target.targetVersion,
270
275
  mechanism: target.kind,
271
- });
276
+ childPackage: target.childPackage,
277
+ childTargetVersion: target.childTargetVersion,
278
+ }));
272
279
  }
273
280
  }
274
281
  if (options.fix) {
@@ -286,12 +293,7 @@ export async function handleSingleFolderScan(params) {
286
293
  appliedWithinRangeRefreshCount: fixResult?.appliedWithinRangeRefreshCount ?? 0,
287
294
  findingsBeforeFix,
288
295
  findingsAfterFix: scanState.sorted.length,
289
- applied: (fixResult?.applied ?? []).map(entry => ({
290
- package: entry.package,
291
- from: entry.from,
292
- to: entry.to,
293
- advisories: collectAdvisoryIdsForPackage(findingsBeforeFixList, entry.package),
294
- })),
296
+ applied: buildFixResultAppliedEntries(fixResult?.applied ?? [], findingsBeforeFixList),
295
297
  notAutoApplied: {
296
298
  parentUpgradeCount: fixResult?.parentUpgradeCount ?? 0,
297
299
  breakingUpgradeCount: fixResult?.breakingUpgradeCount ?? 0,
@@ -443,6 +445,9 @@ export async function handleSingleFolderScan(params) {
443
445
  tableFindings: scanState.tableFindings,
444
446
  completeness: scanState.completeness,
445
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,
446
451
  maintenanceFindings,
447
452
  licenseFindings,
448
453
  licenseLimitedToDirectOnly,
@@ -472,7 +477,10 @@ export async function handleSingleFolderScan(params) {
472
477
  }
473
478
  }
474
479
  if (options.checkOverrides && overrideFindings.length > 0) {
475
- 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));
476
484
  }
477
485
  if (options.checkMaintenance && maintenanceFindings.length > 0) {
478
486
  console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: true }));
@@ -498,7 +506,10 @@ export async function handleSingleFolderScan(params) {
498
506
  licenseLimitedToDirectOnly: options.checkLicenses ? licenseLimitedToDirectOnly : undefined,
499
507
  });
500
508
  if (options.checkOverrides) {
501
- 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));
502
513
  }
503
514
  if (options.checkMaintenance && maintenanceFindings.length > 0) {
504
515
  console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: false }));
@@ -524,15 +535,41 @@ export async function handleSingleFolderScan(params) {
524
535
  // undefined (not []) when override checking was not requested, so the HTML
525
536
  // report omits the Override hygiene panel entirely on a plain scan.
526
537
  overrideFindings: options.checkOverrides ? overrideFindings : undefined,
538
+ skippedOverrideRules: options.checkOverrides ? overrideSkipped : undefined,
527
539
  // Same undefined-vs-[] convention as overrideFindings above.
528
540
  maintenanceFindings: options.checkMaintenance ? maintenanceFindings : undefined,
529
541
  licenseFindings: options.checkLicenses ? licenseFindings : undefined,
530
542
  licenseLimitedToDirectOnly: options.checkLicenses ? licenseLimitedToDirectOnly : undefined,
531
543
  completeness: scanState.completeness,
532
544
  });
545
+ // report.json follows the --json schema, plus scannedAt/cliVersion for a
546
+ // 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
+ findings: reportData.findings,
568
+ };
533
569
  const { reportPath } = await writeHtmlReport({
534
570
  outputDir,
535
571
  data: reportData,
572
+ jsonPayload,
536
573
  autoOpen: !options.noOpen,
537
574
  });
538
575
  console.log(`${chalk.gray("Report:")} ${chalk.cyan(reportPath)}`);
@@ -550,15 +587,20 @@ export async function handleSingleFolderScan(params) {
550
587
  console.log(chalk.yellow(`${scanState.sorted.length} new ${scanState.sorted.length === 1 ? "finding" : "findings"} above baseline - ${suppressedCount} existing ${suppressedCount === 1 ? "finding" : "findings"} suppressed`));
551
588
  }
552
589
  }
553
- // Override hygiene findings count toward --fail-on too, using the shared
554
- // reachesFailOn helper from src/utils/severity.ts, the same logic used by
555
- // the standalone `overrides` command. Without this, a CI run
590
+ // Override hygiene findings count toward --fail-on too. Without this, a CI run
556
591
  // of `cve-lite . --check-overrides --fail-on high` would exit 0 despite high-severity
557
592
  // override findings, giving a false sense of protection. overrideFindings is empty
558
593
  // unless --check-overrides (and non-ratchet), so this is a no-op otherwise.
559
- const shouldFail = reachesFailOn(scanState.sorted, options.failOn) ||
560
- reachesFailOn(overrideFindings, options.failOn) ||
561
- reachesFailOn(maintenanceFindings, options.failOn);
594
+ // The gate and the line that explains it come from one call, so the exit code
595
+ // and the printed reason cannot drift apart.
596
+ const gateLine = failingGateSummary([
597
+ { label: "vulnerability", findings: scanState.sorted },
598
+ { label: "override hygiene", findings: overrideFindings },
599
+ { label: "maintenance risk", findings: maintenanceFindings },
600
+ ], options.failOn);
601
+ const shouldFail = gateLine !== null;
602
+ if (gateLine && !options.json && !options.fix)
603
+ console.log(chalk.red(gateLine));
562
604
  // In fix mode, remaining transitive findings cannot be auto-fixed.
563
605
  // Exiting non-zero would prevent the Action PR step from running.
564
606
  const incompleteFailure = shouldFailForIncompleteScan(scanState.completeness, options.incompletePolicy);
@@ -585,42 +627,71 @@ export async function scanProject(params) {
585
627
  scanSource: params.scanInput.source,
586
628
  scanFilePath: params.scanInput.filePath,
587
629
  }, params.debugLog, params.fetchImpl);
630
+ let usageTruncated = false;
588
631
  if (params.options.usage) {
589
632
  logInfo(`Scanning project source for usage hints...`, params.options);
590
633
  const usageStartedAt = Date.now();
591
634
  const pkgNames = new Set(findings.map(f => f.pkg.name));
592
- const usageData = scanProjectForPackageUsage(params.projectPath, pkgNames);
635
+ const usageResult = scanProjectForPackageUsage(params.projectPath, pkgNames);
636
+ const usageData = usageResult.usage;
637
+ usageTruncated = usageResult.truncated;
593
638
  let matchedPackages = 0;
594
639
  for (const finding of findings) {
595
640
  const files = usageData[finding.pkg.name];
596
- if (files) {
597
- if (files.length > 0) {
598
- matchedPackages += 1;
599
- }
600
- finding.usage = {
601
- imported: files.length > 0,
602
- files,
603
- };
641
+ if (!files)
642
+ continue;
643
+ if (files.length > 0) {
644
+ matchedPackages += 1;
645
+ finding.usage = { imported: true, files };
646
+ }
647
+ else if (usageTruncated) {
648
+ // Absence during a truncated walk is not proof of non-use: unknown, not false.
649
+ finding.usage = { imported: null, files };
650
+ }
651
+ else {
652
+ // Only a complete scan can conclude a package is genuinely unused.
653
+ finding.usage = { imported: false, files };
604
654
  }
605
655
  }
656
+ if (usageResult.truncated) {
657
+ // Push into the scan warnings so machine consumers (--json, HTML report)
658
+ // see the same disclosure the terminal prints.
659
+ const warning = usageScanTruncationWarning({ onlyUsed: !!params.options.onlyUsed });
660
+ params.scanInput.warnings.push(warning);
661
+ logWarn(warning, params.options);
662
+ }
606
663
  if (params.options.debug) {
607
664
  params.debugLog("Usage scan", {
608
665
  durationMs: Date.now() - usageStartedAt,
609
666
  packagesChecked: pkgNames.size,
610
667
  matchedPackages,
668
+ truncated: usageResult.truncated,
669
+ scannedFiles: usageResult.scannedFiles,
611
670
  });
612
671
  }
613
672
  }
614
673
  let finalFindings = findings;
615
674
  if (params.options.onlyUsed) {
616
- const beforeCount = finalFindings.length;
617
- finalFindings = finalFindings.filter(f => f.usage?.imported);
618
- if (params.options.debug) {
619
- params.debugLog("Findings filtered", {
620
- reason: "only-used",
621
- before: beforeCount,
622
- after: finalFindings.length,
623
- });
675
+ if (usageTruncated) {
676
+ // Truncated: absence is not proof of unused; keep findings so --fail-on isn't narrowed.
677
+ if (params.options.debug) {
678
+ params.debugLog("Findings filtered", {
679
+ reason: "only-used-skipped-truncated-usage-scan",
680
+ before: findings.length,
681
+ after: findings.length,
682
+ });
683
+ }
684
+ }
685
+ else {
686
+ const beforeCount = finalFindings.length;
687
+ finalFindings = finalFindings.filter(f => f.usage?.imported);
688
+ if (params.options.debug) {
689
+ params.debugLog("Findings filtered", {
690
+ reason: "only-used",
691
+ before: beforeCount,
692
+ after: finalFindings.length,
693
+ });
694
+ }
624
695
  }
625
696
  }
626
697
  const offline = !!params.options.offline || !!params.options.offlineDb;
package/dist/scanner.js CHANGED
@@ -2,7 +2,7 @@ import { fetchEpssScores } from "./epss/client.js";
2
2
  import { chunk, runWithConcurrency } from "./utils/array.js";
3
3
  import { isPrivateRegistrySource, isGitSource, hasCommitShaPinning } from "./utils/advisory.js";
4
4
  import { extractCveAliases, hasMaliciousAdvisory } from "./utils/vuln.js";
5
- import { compareVersions, isPreReleaseVersion, looksLikeVersion } from "./utils/version.js";
5
+ import { compareVersions, isPreReleaseVersion, normalizeAdvisoryVersion } from "./utils/version.js";
6
6
  import { loadCache, saveCache, isEntryStale } from "./osv/cache.js";
7
7
  import { maxSeverity } from "./osv/severity.js";
8
8
  import { createSpinner } from "./output/spinner.js";
@@ -201,7 +201,13 @@ export async function scanPackages(packages, batchSize, options, context, debugL
201
201
  const uncachedForNpm = [];
202
202
  for (const pkg of allNpmPkgs) {
203
203
  const key = getPackageCacheKey(pkg);
204
- const cached = cache.npmAdvisoryEntries[key];
204
+ // `--no-cache` was honoured for OSV queries and the registry publish-date
205
+ // lookups but never here, so a flag whose whole purpose is to take the
206
+ // cache out of the picture still served this block from it, and two
207
+ // consecutive --no-cache runs could disagree. Writing back is deliberate
208
+ // and matches the other caches, which a test already pins; only the read
209
+ // is skipped (#1166).
210
+ const cached = options.noCache ? undefined : cache.npmAdvisoryEntries[key];
205
211
  if (cached && !isEntryStale(cached, nowMs)) {
206
212
  const newCachedVulns = cached.vulns.filter(v => !existingVulnIds.has(v.id));
207
213
  if (newCachedVulns.length > 0) {
@@ -265,7 +271,12 @@ export async function scanPackages(packages, batchSize, options, context, debugL
265
271
  const nowMs = Date.now();
266
272
  const uncachedIds = [];
267
273
  for (const id of ids) {
268
- const cached = cache.entries[id];
274
+ // Same gap as the npm advisory block above: the advisory detail cache
275
+ // was read regardless of the flag, so a --no-cache run could still
276
+ // restore a previously cached detail, including a negative entry that
277
+ // marks the scan incomplete. The write below stays unguarded, as it is
278
+ // for the other caches (#1166).
279
+ const cached = options.noCache ? undefined : cache.entries[id];
269
280
  if (cached && !isEntryStale(cached, nowMs)) {
270
281
  if (cached.vuln) {
271
282
  vulnMap.set(id, cached.vuln);
@@ -752,7 +763,7 @@ async function validateOneDirectFixTarget(finding, options) {
752
763
  };
753
764
  npmVersionCacheUpdated = true;
754
765
  };
755
- if (lowestKnownResolution.resolvedVersion) {
766
+ if (lowestKnownResolution.resolvedVersion && lowestKnownResolution.verified) {
756
767
  finding.validatedFirstFixedVersion = lowestKnownResolution.resolvedVersion;
757
768
  finding.validatedTargetScannedVersions = lowestKnownResolution.candidatesChecked;
758
769
  finding.validatedTargetKnownVulnerableVersions = lowestKnownResolution.candidatesKnownVulnerable;
@@ -787,11 +798,15 @@ async function validateOneDirectFixTarget(finding, options) {
787
798
  return npmVersionCacheUpdated;
788
799
  }
789
800
  const resolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint);
790
- finding.validatedFirstFixedVersion = resolution.resolvedVersion;
791
- finding.fixVersionValidationNote = resolution.note ?? lowestKnownResolution.note;
801
+ // Publication confirms availability, not that every advisory is fixed.
802
+ finding.validatedFirstFixedVersion = null;
803
+ finding.fixVersionValidationNote = [
804
+ lowestKnownResolution.note ?? `A non-vulnerable version could not be confirmed for ${finding.pkg.name}.`,
805
+ resolution.note,
806
+ ].filter(Boolean).join(" ");
792
807
  finding.validatedTargetScannedVersions = null;
793
808
  finding.validatedTargetKnownVulnerableVersions = null;
794
- setPublishedDate(resolution);
809
+ finding.fixVersionPublishedAt = null;
795
810
  logFixValidation();
796
811
  return npmVersionCacheUpdated;
797
812
  }
@@ -852,9 +867,13 @@ function affectedEntryMatchesPackage(affected, packageName, ecosystem) {
852
867
  */
853
868
  function versionWithinAffectedWindow(version, introduced, fixed) {
854
869
  if (introduced && introduced !== "0") {
855
- if (!looksLikeVersion(introduced))
870
+ // Advisories write boundaries with fewer than three components, so `2` means
871
+ // 2.0.0. Normalizing rather than rejecting keeps the window usable, and a
872
+ // value that is not a version at all still returns null and bails (#1192).
873
+ const normalizedIntroduced = normalizeAdvisoryVersion(introduced);
874
+ if (!normalizedIntroduced)
856
875
  return false;
857
- if (compareVersions(version, introduced) < 0)
876
+ if (compareVersions(version, normalizedIntroduced) < 0)
858
877
  return false;
859
878
  }
860
879
  return compareVersions(version, fixed) < 0;
@@ -886,8 +905,13 @@ function collectAdvisoryFixes(vuln, packageName, ecosystem, installedVersion) {
886
905
  introduced = event.introduced;
887
906
  continue;
888
907
  }
889
- const fixed = event.fixed;
890
- if (!fixed || !looksLikeVersion(fixed) || isPreReleaseVersion(fixed))
908
+ // `fixed: "1.22"` is 1.22.0. Requiring a strict X.Y.Z here discarded the
909
+ // event, and a finding whose every candidate was discarded reported "no
910
+ // fix available", which tells a developer to stop looking for a fix that
911
+ // exists (#1192). A value that cannot be read in full is still dropped,
912
+ // so a commit hash from a GIT range never becomes a fix version.
913
+ const fixed = normalizeAdvisoryVersion(event.fixed);
914
+ if (!fixed || isPreReleaseVersion(fixed))
891
915
  continue;
892
916
  all.push(fixed);
893
917
  if (installedVersion && versionWithinAffectedWindow(installedVersion, introduced, fixed)) {
@@ -12,7 +12,8 @@ Key fields in each finding:
12
12
  - \`recommendedAction\` — human-readable fix guidance
13
13
  - \`cves\` — CVE IDs
14
14
  - \`dependencyPaths\` — chains showing how the package is pulled in
15
- - \`usage.imported\` — whether the package is actually imported in source files
15
+ - \`usage.imported\` — whether the package is imported in source files; \`null\` when the usage scan hit its file cap (import status unknown), and \`usage\` itself is \`null\` when \`--usage\` was not run
16
+ - \`contextualSignals\` — heuristic prioritization hints (\`usage\`, \`reachabilityHint\`, \`exposure\`). Not exploitability verdicts; \`not_imported\` / \`not_indicated\` does not mean safe or unreachable
16
17
 
17
18
  Top-level \`suggestedFixCommands\` contains grouped, copy-ready fix commands.
18
19
 
@@ -22,10 +23,11 @@ Top-level \`suggestedFixCommands\` contains grouped, copy-ready fix commands.
22
23
  2. Direct dependencies before transitive
23
24
  3. If \`usage.imported === false\`, flag as lower practical risk but do not dismiss
24
25
  4. If \`runnableFixCommand\` is present, that is the exact command to run — prefer it over manual guidance
26
+ 5. Treat \`contextualSignals\` as triage context only — never as exploitability or runtime reachability
25
27
 
26
28
  ### Codebase analysis
27
29
 
28
- - Cross-reference vulnerable packages against source file imports to confirm reachability
30
+ - Cross-reference vulnerable packages against source file imports as a heuristic only; an import match is not proof of runtime reachability
29
31
  - Check \`package.json\` version constraints for direct dependency findings
30
32
  - Use \`dependencyPaths\` to trace transitive chains and identify which parent package to upgrade
31
33
  - Look for patterns: a single parent responsible for multiple transitive findings (fixing the parent clears all of them)