diff --git a/src/index.ts b/src/index.ts index 5b4f17fc..36f48bc2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -38,6 +38,7 @@ import { printCompactOutput, printCoverage, printFinalStatus, + printIncompleteDiagnostics, printOverrideHint, printSkippedDependencies, printSuggestedFixCommands, @@ -578,6 +579,27 @@ if (parsedArgs) { // baseline. Re-saving here would silently absorb a new vulnerability into a // fresh baseline, so a ratcheted CI job could never fail on a regression. if (options.ratchet) { + // A baseline records detection results, so detection-impact gaps make it + // untrustworthy: refuse to save or evaluate one from partial data. + // Remediation-only gaps do not change the finding set, so they only warn. + if (!scanState.completeness.complete) { + printIncompleteDiagnostics(scanState.completeness); + } + const hasDetectionGaps = scanState.completeness.diagnostics.some(d => d.impact === "detection"); + if (hasDetectionGaps) { + console.log(chalk.red("Scan data is incomplete. Refusing to create or evaluate a baseline from partial detection data. Resolve the issues above and re-run --ratchet.")); + auditLogHandle.emit({ + ts: new Date().toISOString(), + type: "scan.finished", + schemaVersion: 1, + durationMs: Date.now() - scanStartTime, + findingsCount: scanState.sorted.length, + exitCode: EXIT_ERROR, + }); + auditLogHandle.close(); + process.exit(EXIT_ERROR); + return; + } const outcome = ratchetOutcome(baseline, scanState.sorted); if (outcome.action === "save") { writeBaseline(projectArg ?? ".", scanState.sorted); @@ -666,6 +688,7 @@ if (parsedArgs) { coverage: scanState.coverage, minSeverity: scanState.minSeverity, tableFindings: scanState.tableFindings, + completeness: scanState.completeness, overrideFindings, maintenanceFindings, }, scanInput, projectPath); @@ -702,13 +725,13 @@ if (parsedArgs) { console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: true })); } printCoverage([...scanInput.notes, ...scanState.coverage]); - printFinalStatus(scanState.sorted, overrideCount); + printFinalStatus(scanState.sorted, overrideCount, scanState.completeness); if (showOverrideHint) printOverrideHint(); } else { const compactPmLabel = scanState.suggestedFixCommands ? `${chalk.cyan(scanState.suggestedFixCommands.packageManager)} ${chalk.gray(`(${scanState.suggestedFixCommands.sourceLabel})`)}` : undefined; - printCompactOutput(scanState.sorted, scanInput, { offline, all: !!options.all, packageManager: compactPmLabel }); + printCompactOutput(scanState.sorted, scanInput, { offline, all: !!options.all, packageManager: compactPmLabel, completeness: scanState.completeness }); if (options.checkOverrides) { console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: false, projectPath })); } @@ -740,6 +763,7 @@ if (parsedArgs) { overrideFindings: options.checkOverrides ? overrideFindings : undefined, // Same undefined-vs-[] convention as overrideFindings above. maintenanceFindings: options.checkMaintenance ? maintenanceFindings : undefined, + completeness: scanState.completeness, }); const { reportPath } = await writeHtmlReport({ outputDir, @@ -826,7 +850,7 @@ async function scanProject(params: { fetchImpl?: typeof fetch; }) { const directDependencyNames = readDirectDependencyNames(params.projectPath, !!params.options.prodOnly); - const findings = await scanPackages(params.scanInput.packages, params.batchSize, params.options, { + const { findings, completeness } = await scanPackages(params.scanInput.packages, params.batchSize, params.options, { directDependencyNames, scanSource: params.scanInput.source, scanFilePath: params.scanInput.filePath, @@ -887,6 +911,7 @@ async function scanProject(params: { tableFindings, suggestedFixCommands, allPackages: params.scanInput.packages, + completeness, }; } diff --git a/src/output/html-reporter.ts b/src/output/html-reporter.ts index 33857e7a..9c7f6c1f 100644 --- a/src/output/html-reporter.ts +++ b/src/output/html-reporter.ts @@ -8,7 +8,7 @@ import { pluralize } from "../utils/string.js"; import { MAL_GIT_SOURCE_PINNED_DISPLAY, MAL_GIT_SOURCE_FLOATING_DISPLAY } from "../constants.js"; import { renderOverrideFindingsHtml } from "./override-findings-html.js"; import { renderMaintenanceFindingsHtml } from "./maintenance-findings-html.js"; -import type { Finding } from "../types.js"; +import type { Finding, ScanCompleteness } from "../types.js"; import type { OverrideFinding } from "../overrides/types.js"; import type { MaintenanceFinding } from "../maintenance/types.js"; import type { SuggestedFixCommandPlan } from "../remediation/fix-commands.js"; @@ -40,6 +40,7 @@ export type ReportData = { skippedDependencies: string[]; overrideFindings?: ReadonlyArray; maintenanceFindings?: ReadonlyArray; + completeness?: ScanCompleteness; }; export function buildReportData(params: { @@ -55,6 +56,7 @@ export function buildReportData(params: { skippedDependencies: string[]; overrideFindings?: ReadonlyArray; maintenanceFindings?: ReadonlyArray; + completeness?: ScanCompleteness; }): ReportData { return { projectPath: params.projectPath, @@ -72,6 +74,7 @@ export function buildReportData(params: { skippedDependencies: params.skippedDependencies, overrideFindings: params.overrideFindings, maintenanceFindings: params.maintenanceFindings, + completeness: params.completeness, }; } @@ -208,6 +211,12 @@ button.header-link:hover{color:var(--link);border-color:var(--link)} .fix-target-note{color:var(--text-3);font-style:italic;font-size:10px} .fix-target-coverage{flex-basis:100%;color:var(--text-3);font-size:10px;line-height:1.45} .chain-proof{font-size:0.78rem;color:var(--text-2);margin-left:6px;font-family:monospace} +.completeness-banner{margin:16px 32px 0;background:#e3b34111;border:1px solid #e3b34144;border-radius:8px;padding:14px 18px;display:flex;gap:14px;align-items:flex-start} +.completeness-banner-icon{font-size:22px;flex-shrink:0;line-height:1} +.completeness-banner-body strong{font-size:13px;color:var(--text);display:block;margin-bottom:4px} +.completeness-banner-body p{font-size:12px;color:var(--text-2);margin:0} +.completeness-banner-body ul{margin:8px 0 0;padding:0 0 0 18px;display:flex;flex-direction:column;gap:3px} +.completeness-banner-body li{font-size:11px;color:var(--text-2);line-height:1.5} .break-badge{font-size:10px;font-weight:700;background:#fb850022;color:#fb8500;border:1px solid #fb850066;border-radius:4px;padding:1px 5px} .tier-ok{display:inline-flex;align-items:center;gap:4px;font-size:10px;padding:2px 8px;border-radius:4px;background:#3fb95022;color:#3fb950;border:1px solid #3fb95033;margin-bottom:6px} .tier-warn{display:inline-flex;align-items:center;gap:4px;font-size:10px;padding:2px 8px;border-radius:4px;background:#e3b34122;color:#e3b341;border:1px solid #e3b34133;margin-bottom:6px} @@ -245,6 +254,7 @@ export function renderHtmlReport(data: ReportData): string { const totalCVEs = new Set(data.findings.flatMap(f => f.vulnerabilities.map(v => v.id))).size; const noticesHtml = renderNotices(data.notes, data.warnings); + const completenessBannerHtml = renderCompletenessBanner(data.completeness); const fixPlanHtml = renderFixPlan(data.suggestedFixCommands); const skippedKeys = new Set( (data.suggestedFixCommands?.skipped ?? []).map(s => `${s.package}@${s.version}`) @@ -319,6 +329,7 @@ ${REPORT_STYLES}
${totalCVEs}CVEs
+${completenessBannerHtml} ${fixPlanHtml}
@@ -621,6 +632,35 @@ function renderTransitiveContextCol(finding: SerializedFinding): string {
`; } +export function renderCompletenessBanner(completeness: ScanCompleteness | null | undefined): string { + if (completeness == null || completeness.complete) return ""; + + const hasDetectionFailure = completeness.diagnostics.some(d => d.impact === "detection"); + const hasRemediationFailure = completeness.diagnostics.some(d => d.impact === "remediation"); + + let bannerText: string; + if (hasDetectionFailure) { + bannerText = "Some vulnerability findings may be incomplete because the following issues occurred:"; + } else if (hasRemediationFailure) { + bannerText = "Vulnerability findings are available, but remediation guidance may be incomplete because the following issues occurred:"; + } else { + bannerText = "The scan result may be incomplete because the following issues occurred:"; + } + + const diagRows = completeness.diagnostics.map(d => + `
  • ${escapeHtml(d.message)}
    • ` + ).join("\n"); + + return `
    +
    ⚠
    +
    + Scan data is incomplete +

    ${bannerText}

    +
      ${diagRows}
    +
    +
    `; +} + function renderNotices(notes: string[], warnings: string[]): string { if (notes.length === 0 && warnings.length === 0) return ""; const total = notes.length + warnings.length; diff --git a/src/output/multi-folder-html-reporter.ts b/src/output/multi-folder-html-reporter.ts index c07655cd..e4b45e71 100644 --- a/src/output/multi-folder-html-reporter.ts +++ b/src/output/multi-folder-html-reporter.ts @@ -1,12 +1,14 @@ import fs from "node:fs"; import path from "node:path"; import type { MultiFolderScanResult } from "../scan/multi-folder-scan.js"; +import { aggregateMultiFolderCompleteness } from "../scan/multi-folder-scan.js"; import { REPORT_STYLES, escapeHtml, openInBrowser, renderFindingRow, renderFixPlan, + renderCompletenessBanner, serializeHtmlFinding, } from "./html-reporter.js"; import type { SerializedFinding } from "./html-reporter.js"; @@ -59,6 +61,7 @@ function renderFolderSection( const findingRowsHtml = serialized.map((f, i) => renderFindingRow(f, idxOffset + i)).join("\n"); const fixPlanHtml = renderFixPlan(result.suggestedFixCommands); const noticesHtml = renderFolderNotices(result.coverage); + const completenessBannerHtml = renderCompletenessBanner(result.completeness); const emptyRow = result.sorted.length === 0 ? `No findings` @@ -71,6 +74,7 @@ function renderFolderSection( ${escapeHtml(summaryText)}
    + ${completenessBannerHtml} ${fixPlanHtml} ${noticesHtml}
    @@ -127,6 +131,9 @@ export async function writeMultiFolderHtmlReport(params: { ); const folderCount = params.results.length; + const aggregateCompleteness = aggregateMultiFolderCompleteness(params.results); + const aggregateBannerHtml = renderCompletenessBanner(aggregateCompleteness); + // Pre-serialize findings once per folder for both HTML rendering and JS filter/sort const allSerialized: SerializedFinding[][] = params.results.map(r => r.sorted.map(f => serializeHtmlFinding(f, r.suggestedFixCommands)), @@ -221,6 +228,8 @@ details[open] .folder-summary::before{transform:rotate(90deg)}
    ${totalCVEs}CVEs
    +${aggregateBannerHtml} + ${folderSectionsHtml}
    diff --git a/src/output/multi-folder-printer.ts b/src/output/multi-folder-printer.ts index b7964707..739c1e90 100644 --- a/src/output/multi-folder-printer.ts +++ b/src/output/multi-folder-printer.ts @@ -49,9 +49,9 @@ export function printMultiFolderResults( } } printCoverage([...result.scanInput.notes, ...result.coverage]); - printFinalStatus(result.sorted); + printFinalStatus(result.sorted, 0, result.completeness); } else { - printCompactOutput(result.sorted, result.scanInput, { offline, all: !!options.all, subfolder: result.subfolder }); + printCompactOutput(result.sorted, result.scanInput, { offline, all: !!options.all, subfolder: result.subfolder, completeness: result.completeness }); } if (i < results.length - 1) { diff --git a/src/output/printers.ts b/src/output/printers.ts index 184b1137..ee57386e 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -1,4 +1,4 @@ -import type { Finding, ScanInput, SeverityLabel } from "../types.js"; +import type { Finding, ScanCompleteness, ScanInput, SeverityLabel } from "../types.js"; import { chalk, stripAnsi } from "../utils/chalk.js"; import { buildSuggestedFixCommandPlan, type SuggestedFixTarget } from "../remediation/fix-commands.js"; import { isMajorVersionBump } from "../utils/version.js"; @@ -320,40 +320,49 @@ export function printTable(findings: Finding[], threshold: SeverityLabel | null, } } -export function printFinalStatus(findings: Finding[], overrideCount = 0) { +export function printFinalStatus(findings: Finding[], overrideCount = 0, completeness?: ScanCompleteness) { console.log(""); console.log(chalk.gray("────────────────────────────────")); + const incomplete = completeness?.complete === false; const overrideSuffix = overrideCount > 0 ? `, ${overrideCount} override hygiene ${pluralize(overrideCount, "issue")}` : ""; if (findings.length === 0) { - if (overrideCount > 0) { + if (incomplete) { + console.log(chalk.yellow("⚠ No known vulnerabilities were resolved, but scan data is incomplete.")); + } else if (overrideCount > 0) { console.log(chalk.yellow(`▲ Scan complete. No known vulnerabilities found, but ${overrideCount} override hygiene ${pluralize(overrideCount, "issue")} detected.`)); } else { console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found.")); } - return; - } - - const criticalCount = findings.filter(f => f.severity === "critical").length; - const highCount = findings.filter(f => f.severity === "high").length; - - if (criticalCount > 0 || highCount > 0) { - console.log( - chalk.redBright( - `✖ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${overrideSuffix} found (${criticalCount} critical, ${highCount} high). Start with the priority fixes above.` - ) - ); - return; + } else { + const criticalCount = findings.filter(f => f.severity === "critical").length; + const highCount = findings.filter(f => f.severity === "high").length; + const urgent = criticalCount > 0 || highCount > 0; + + const label = `${findings.length} ${pluralize(findings.length, "vulnerability", "vulnerabilities")}`; + + if (incomplete) { + const severityNote = urgent ? ` (${criticalCount} critical, ${highCount} high)` : ""; + const action = urgent ? "Start with the priority fixes above." : "Review the suggested fix plan above."; + const renderStatus = urgent ? chalk.redBright : chalk.yellow; + console.log(renderStatus( + `⚠ Partial scan: ${label} resolved${overrideSuffix}${severityNote}. ${action}` + )); + } else if (urgent) { + console.log(chalk.redBright( + `✖ Scan complete. ${label}${overrideSuffix} found (${criticalCount} critical, ${highCount} high). Start with the priority fixes above.` + )); + } else { + console.log(chalk.yellow( + `▲ Scan complete. ${label}${overrideSuffix} found. Review the suggested fix plan above.` + )); + } } - console.log( - chalk.yellow( - `▲ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${overrideSuffix} found. Review the suggested fix plan above.` - ) - ); + printIncompleteDiagnostics(completeness); } export function printOverrideHint(): void { @@ -417,7 +426,13 @@ function wrapCell(value: string, width: number): string[] { export function printCompactOutput( findings: Finding[], scanInput?: ScanInput, - options?: { offline?: boolean; all?: boolean; subfolder?: string; packageManager?: string }, + options?: { + offline?: boolean; + all?: boolean; + subfolder?: string; + packageManager?: string; + completeness?: ScanCompleteness; + }, ) { console.log(""); if (options?.packageManager) { @@ -425,8 +440,13 @@ export function printCompactOutput( } if (findings.length === 0) { - console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found.")); - console.log(""); + if (options?.completeness?.complete === false) { + console.log(chalk.yellow("⚠ No known vulnerabilities were resolved, but scan data is incomplete.")); + printIncompleteDiagnostics(options.completeness); + } else { + console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found.")); + console.log(""); + } return; } @@ -603,8 +623,18 @@ export function printCompactOutput( } // Footer + const incomplete = options?.completeness?.complete === false; const urgentCount = counts.critical + counts.high; - if (urgentCount > 0) { + if (incomplete) { + const label = urgentCount > 0 + ? `${urgentCount} urgent ${pluralize(urgentCount, "issue")} resolved` + : `${findings.length} ${pluralize(findings.length, "issue")} resolved`; + console.log( + chalk.yellow( + `⚠ Partial scan: ${label}.` + ) + ); + } else if (urgentCount > 0) { console.log( chalk.redBright( `✖ Scan complete. ${urgentCount} urgent ${pluralize(urgentCount, "issue")} found.` @@ -620,7 +650,20 @@ export function printCompactOutput( if (!options?.all) { console.log(chalk.gray(`Run with ${chalk.whiteBright("--verbose")} for fix plan, paths, and full table.`)); } + printIncompleteDiagnostics(options?.completeness); + if (!incomplete) { + console.log(""); + } +} + +export function printIncompleteDiagnostics(completeness?: ScanCompleteness): void { + if (!completeness || completeness.complete) return; console.log(""); + for (const diag of completeness.diagnostics) { + const prefix = diag.impact === "detection" ? chalk.yellow(" ·") : chalk.gray(" ·"); + console.log(prefix + " " + chalk.gray(diag.message)); + } + console.log(chalk.gray(" Resolve the issues above and re-run the scan.")); } function renderSeverityTable(counts: { critical: number; high: number; medium: number; low: number; unknown: number }): string { diff --git a/src/output/write-outputs.ts b/src/output/write-outputs.ts index 17ed9e90..953f0e1f 100644 --- a/src/output/write-outputs.ts +++ b/src/output/write-outputs.ts @@ -1,7 +1,7 @@ import fs from "node:fs"; import path from "node:path"; import { chalk } from "../utils/chalk.js"; -import type { ParsedOptions, ScanInput, Finding, PackageRef } from "../types.js"; +import type { ParsedOptions, ScanInput, Finding, PackageRef, ScanCompleteness } from "../types.js"; import type { SuggestedFixCommandPlan } from "../remediation/fix-commands.js"; import type { OverrideFinding } from "../overrides/types.js"; import type { MaintenanceFinding } from "../maintenance/types.js"; @@ -19,6 +19,7 @@ export type ScanState = { coverage: string[]; minSeverity: string; tableFindings: Finding[]; + completeness: ScanCompleteness; }; function readProjectMeta(projectPath: string): ProjectMeta { @@ -58,6 +59,9 @@ export async function writeOutputs( source: scanInput.source, packageCount: scanInput.packages.length, findingCount: scanState.sorted.length, + status: scanState.completeness.complete ? "ok" : "partial", + complete: scanState.completeness.complete, + diagnostics: scanState.completeness.diagnostics, suggestedFixCommands: scanState.suggestedFixCommands, notes: [...scanInput.notes, ...scanState.coverage], warnings: scanInput.warnings, diff --git a/src/remediation/npm-registry.ts b/src/remediation/npm-registry.ts index 9e2fb7e7..57ebee10 100644 --- a/src/remediation/npm-registry.ts +++ b/src/remediation/npm-registry.ts @@ -1,6 +1,7 @@ import { compareVersions, isPreReleaseVersion, looksLikeVersion } from "../utils/version.js"; import type { OsvVuln } from "../types.js"; import type { DebugLogger } from "../output/debug.js"; +import { AsyncLocalStorage } from "node:async_hooks"; export type Packument = { "dist-tags"?: Record; @@ -22,7 +23,14 @@ export type PublishedFixVersionResolution = { publishedAt: string | null; }; -const packumentCache = new Map>(); +// The result is cached instead of the raw Packument so that every caller can +// notify its own observer after awaiting a shared in-flight request. +type PackumentFetchResult = + | { status: "resolved"; packument: Packument } + | { status: "not-found"; packument: null } + | { status: "transient-failure"; packument: null }; + +const packumentCache = new Map>(); const DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org"; let registryDebugLog: DebugLogger | undefined; @@ -38,78 +46,108 @@ function nextRegistryBatchId(): string { return `r-${String(registryBatchCounter).padStart(2, "0")}`; } +export type RegistryFetchObserver = { + onTransientFailure?: (name: string) => void; + onResolved?: (name: string) => void; +}; + +const observerStorage = new AsyncLocalStorage(); + +export async function runWithObserver( + observer: RegistryFetchObserver, + fn: () => Promise, +): Promise { + return observerStorage.run(observer, fn); +} + export function clearPackumentCache(): void { packumentCache.clear(); } -export async function fetchPackument(packageName: string): Promise { +function notifyPackumentObserver(result: PackumentFetchResult, packageName: string): void { + const observer = observerStorage.getStore(); + if (result.status === "transient-failure") { + observer?.onTransientFailure?.(packageName); + } else { + observer?.onResolved?.(packageName); + } +} + +export async function fetchPackument( + packageName: string, +): Promise { const cached = packumentCache.get(packageName); - if (cached) return cached; + let result: PackumentFetchResult; + + if (cached) { + result = await cached; + } else { + const promise = doFetchPackument(packageName); + packumentCache.set(packageName, promise); + result = await promise; + if (result.status === "transient-failure") { + // A later call retries the fetch instead of reusing a cached failure. + packumentCache.delete(packageName); + } + } - const promise = (async () => { - const url = `${DEFAULT_NPM_REGISTRY_URL}/${encodeURIComponent(packageName) - .replace(/%40/g, "@") - .replace(/%2F/g, "/")}`; + notifyPackumentObserver(result, packageName); + return result.packument; +} - const batchId = registryDebugLog ? nextRegistryBatchId() : ""; - const startedAt = registryDebugLog ? Date.now() : 0; - if (registryDebugLog) { - registryDebugLog("Registry fetch", { batchId, package: packageName, url }); - } +async function doFetchPackument(packageName: string): Promise { + const url = `${DEFAULT_NPM_REGISTRY_URL}/${encodeURIComponent(packageName) + .replace(/%40/g, "@") + .replace(/%2F/g, "/")}`; - let transientFailure = false; - try { - const response = await fetch(url); - if (!response.ok) { - if (registryDebugLog) { - registryDebugLog("Registry response", { - batchId, - package: packageName, - status: response.status, - durationMs: Date.now() - startedAt, - versionsCount: 0, - }); - } - if (response.status === 404) { - return null; - } - transientFailure = true; - return null; - } + const batchId = registryDebugLog ? nextRegistryBatchId() : ""; + const startedAt = registryDebugLog ? Date.now() : 0; + if (registryDebugLog) { + registryDebugLog("Registry fetch", { batchId, package: packageName, url }); + } - const json = (await response.json()) as Packument; + try { + const response = await fetch(url); + if (!response.ok) { if (registryDebugLog) { registryDebugLog("Registry response", { batchId, package: packageName, status: response.status, durationMs: Date.now() - startedAt, - versionsCount: Object.keys(json.versions ?? {}).length, - }); - } - return json; - } catch (error) { - transientFailure = true; - if (registryDebugLog) { - registryDebugLog("Registry fetch failed", { - batchId, - package: packageName, - durationMs: Date.now() - startedAt, - error: error instanceof Error - ? { message: error.message, stack: error.stack } - : String(error), + versionsCount: 0, }); } - return null; - } finally { - if (transientFailure) { - packumentCache.delete(packageName); + if (response.status === 404) { + return { status: "not-found", packument: null }; } + return { status: "transient-failure", packument: null }; } - })(); - packumentCache.set(packageName, promise); - return promise; + const json = (await response.json()) as Packument; + if (registryDebugLog) { + registryDebugLog("Registry response", { + batchId, + package: packageName, + status: response.status, + durationMs: Date.now() - startedAt, + versionsCount: Object.keys(json.versions ?? {}).length, + }); + } + return { status: "resolved", packument: json }; + } catch (error) { + if (registryDebugLog) { + registryDebugLog("Registry fetch failed", { + batchId, + package: packageName, + durationMs: Date.now() - startedAt, + error: error instanceof Error + ? { message: error.message, stack: error.stack } + : String(error), + }); + } + return { status: "transient-failure", packument: null }; + } } export async function packageVersionExists(packageName: string, version: string): Promise { diff --git a/src/scan/multi-folder-scan.ts b/src/scan/multi-folder-scan.ts index 569b9b91..f0713d96 100644 --- a/src/scan/multi-folder-scan.ts +++ b/src/scan/multi-folder-scan.ts @@ -1,11 +1,11 @@ import path from "node:path"; import process from "node:process"; -import type { Finding, ParsedOptions, PackageRef, SeverityLabel, ExitCode } from "../types.js"; +import type { Finding, ParsedOptions, PackageRef, SeverityLabel, ExitCode, ScanCompleteness, ScanDiagnostic } from "../types.js"; import { EXIT_OK, EXIT_FINDINGS, EXIT_ERROR } from "../types.js"; import type { SuggestedFixCommandPlan } from "../remediation/fix-commands.js"; import type { ScanInput } from "../types.js"; import { loadMultiplePackages } from "../parsers/multi-package.js"; -import { scanPackages, buildCoverageNotes } from "../scanner.js"; +import { scanPackages, buildCoverageNotes, formatDiagnosticMessage } from "../scanner.js"; import { sortFindingsForOutput } from "../output/formatters.js"; import { normalizeSeverity } from "../osv/severity.js"; import { selectFindingsForTable } from "../output/finding-display.js"; @@ -37,6 +37,7 @@ export interface MultiFolderScanResult { overrideFindings: OverrideFinding[]; /** Maintenance risk (DM001) findings for this folder, populated when --check-maintenance is set. */ maintenanceFindings: MaintenanceFinding[]; + completeness?: ScanCompleteness; } export async function runMultiFolderScan(params: { @@ -59,7 +60,7 @@ export async function runMultiFolderScan(params: { const subfolderAbs = path.join(params.projectRoot, subfolder); const directDependencyNames = readDirectDependencyNames(subfolderAbs, !!params.options.prodOnly); - const findings = await scanPackages(scanInput.packages, params.batchSize, params.options, { + const { findings, completeness } = await scanPackages(scanInput.packages, params.batchSize, params.options, { directDependencyNames, scanSource: scanInput.source, scanFilePath: scanInput.filePath, @@ -100,12 +101,40 @@ export async function runMultiFolderScan(params: { allPackages: scanInput.packages, overrideFindings, maintenanceFindings, + completeness, }); } return results; } +export function aggregateMultiFolderCompleteness( + results: MultiFolderScanResult[], +): ScanCompleteness { + const deduped = new Map(); + for (const r of results) { + if (!r.completeness || r.completeness.complete) continue; + for (const d of r.completeness.diagnostics) { + const existing = deduped.get(d.code); + if (existing) { + existing.count += d.count; + if (d.affectedPackageCount !== undefined) { + existing.affectedPackageCount = + (existing.affectedPackageCount ?? 0) + d.affectedPackageCount; + } + existing.message = formatDiagnosticMessage( + d.code, + existing.count, + existing.affectedPackageCount, + ); + } else { + deduped.set(d.code, { ...d }); + } + } + } + return { complete: deduped.size === 0, diagnostics: [...deduped.values()] }; +} + export async function handleMultiFolderScan(params: { projectRoot: string; batchSize: number; @@ -138,6 +167,7 @@ export async function handleMultiFolderScan(params: { multiFolder: true, folders: results.map(r => r.subfolder), findings: allFindings, + completeness: aggregateMultiFolderCompleteness(results), ...(params.options.checkOverrides ? { overrideFindings: results.flatMap(r => diff --git a/src/scanner.ts b/src/scanner.ts index ece063ca..902a4667 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -1,4 +1,4 @@ -import type { Finding, NpmTransitiveGraph, OsvVuln, PackageRef, ParsedOptions, ScanInput } from "./types.js"; +import type { Finding, NpmTransitiveGraph, OsvVuln, PackageRef, ParsedOptions, ScanCompleteness, ScanDiagnostic, ScanDiagnosticCode, ScanInput } from "./types.js"; import type { PublishedFixVersionResolution } from "./remediation/npm-registry.js"; import { chunk, unique, runWithConcurrency } from "./utils/array.js"; import { isPrivateRegistrySource, isGitSource, hasCommitShaPinning } from "./utils/advisory.js"; @@ -17,6 +17,7 @@ import { fetchPackument, resolveLowestKnownNonVulnerableVersion, resolvePublishedFixVersion, + runWithObserver, } from "./remediation/npm-registry.js"; import { countBySeverity } from "./utils/severity.js"; import { resolveNpmTransitiveRemediation, resolveTransitiveRemediationViaRegistry } from "./remediation/npm-transitive-resolution.js"; @@ -107,7 +108,7 @@ export async function scanPackages( context?: ScanClassificationContext, debugLog?: DebugLogger, fetchImpl?: typeof fetch, -): Promise { +): Promise<{ findings: Finding[]; completeness: ScanCompleteness }> { const log: DebugLogger = debugLog ?? (() => {}); const sourceContext = createAdvisorySource({ osvUrl: options.osvUrl, @@ -221,6 +222,7 @@ export async function scanPackages( const transientDetailIds = new Set(); const offlineMissingDetailIds = new Set(); + const confirmedMissingDetailIds = new Set(); if (idSet.size > 0 && !offline) { const ids = [...idSet]; @@ -233,6 +235,10 @@ export async function scanPackages( if (cached && !isEntryStale(cached, nowMs)) { if (cached.vuln) { vulnMap.set(id, cached.vuln); + } else { + // Negative cache hit: the record was confirmed missing earlier. + // The detail is still unresolved, so the scan stays incomplete. + confirmedMissingDetailIds.add(id); } } else { uncachedIds.push(id); @@ -255,6 +261,7 @@ export async function scanPackages( error: extractErrorMessage(error), }); } else { + confirmedMissingDetailIds.add(id); cache.entries[id] = { vuln: null, cachedAt }; log("OSV detail confirmed missing", { advisoryId: id }); } @@ -305,11 +312,27 @@ export async function scanPackages( saveCache(cache, cacheDirOverride, options.debug ? log : undefined); } - const findings: Finding[] = results.map(result => { + const confirmedMissingFindingDetailIds = new Set(); + const findings: Finding[] = results.flatMap(result => { const vulnerabilities = result.vulnIds .map(id => vulnMap.get(id)) .filter((v): v is OsvVuln => Boolean(v)); const unresolvedIds = result.vulnIds.filter(id => !vulnMap.has(id)); + const hasUnconfirmedMissingDetail = unresolvedIds.some(id => !confirmedMissingDetailIds.has(id)); + + // A confirmed missing detail can result from stale OSV query data. + // Keep the scan complete when no other advisory supports the finding. + if (vulnerabilities.length === 0 && !hasUnconfirmedMissingDetail) { + return []; + } + + if (vulnerabilities.length > 0) { + for (const id of unresolvedIds) { + if (confirmedMissingDetailIds.has(id)) { + confirmedMissingFindingDetailIds.add(id); + } + } + } const severity = maxSeverity(vulnerabilities); const cveAliases = unique( @@ -323,7 +346,7 @@ export async function scanPackages( ); const firstFixedVersion = findFirstFixedVersion(vulnerabilities); - return { + return [{ pkg: result.pkg, vulnerabilities, severity, @@ -339,7 +362,7 @@ export async function scanPackages( recommendedParentUpgrade: undefined, recommendedNpmTransitiveRemediation: undefined, ...(unresolvedIds.length > 0 ? { unresolvedAdvisoryIds: unresolvedIds } : {}), - }; + }]; }); const unresolvedDetailIds = idSet.size > 0 @@ -348,7 +371,8 @@ export async function scanPackages( if (unresolvedDetailIds.length > 0) { const transientCount = unresolvedDetailIds.filter(id => transientDetailIds.has(id)).length; const offlineCount = unresolvedDetailIds.filter(id => offlineMissingDetailIds.has(id)).length; - const otherCount = unresolvedDetailIds.length - transientCount - offlineCount; + const confirmedCount = unresolvedDetailIds.filter(id => confirmedMissingDetailIds.has(id)).length; + const otherCount = unresolvedDetailIds.length - transientCount - offlineCount - confirmedCount; const parts: string[] = []; if (transientCount > 0) { parts.push(`${transientCount} from transient failures — re-run to retry`); @@ -356,6 +380,9 @@ export async function scanPackages( if (offlineCount > 0) { parts.push(`${offlineCount} missing from local advisory database — refresh to sync`); } + if (confirmedCount > 0) { + parts.push(`${confirmedCount} confirmed missing from the OSV API`); + } if (otherCount > 0) { parts.push(`${otherCount} could not be resolved`); } @@ -428,11 +455,18 @@ export async function scanPackages( log("Workspace map", { type: "bun", workspaces: bunWorkspaceMap.size }); } const lockfileWorkspaceMap = pnpmWorkspaceMap ?? bunWorkspaceMap ?? null; + const packumentFailures = new Set(); + const remediationFailures = new Map(); + let chainResolutionFailureCount = 0; + let directCount = 0; + let transitiveCount = 0; + + await runWithObserver({ + onTransientFailure(name) { packumentFailures.add(name); }, + }, async () => { const npmRemediationCache = new Map(); const parentUpgradeCache = new Map(); const directValidationCount = offline ? 0 : findings.length; - let directCount = 0; - let transitiveCount = 0; for (const finding of findings) { if (finding.relationship === "direct") directCount++; else if (finding.relationship === "transitive") transitiveCount++; @@ -476,7 +510,7 @@ export async function scanPackages( } if (packumentsToPrewarm.size > 0) { await runWithConcurrency([...packumentsToPrewarm], 8, async (name) => { - try { await fetchPackument(name); } catch { /* loop will handle missing packuments */ } + await fetchPackument(name); }); } } @@ -568,8 +602,10 @@ export async function scanPackages( parentUpgradeCache.set(remediationCacheKey, finding.recommendedParentUpgrade ?? null); } } catch (error) { + const packageName = finding.pkg.name; + remediationFailures.set(packageName, (remediationFailures.get(packageName) ?? 0) + 1); log("Remediation failed", { - package: finding.pkg.name, + package: packageName, version: finding.pkg.version, error: error instanceof Error ? error.message : String(error), }); @@ -596,6 +632,7 @@ export async function scanPackages( { offline }, ); } catch (error) { + chainResolutionFailureCount += 1; log("Chain resolution failed", { package: finding.pkg.name, version: finding.pkg.version, @@ -620,6 +657,7 @@ export async function scanPackages( saveCache(cache, cacheDirOverride, options.debug ? log : undefined); } } + }); const severityCounts = countBySeverity(findings); log("Findings classified", { @@ -633,7 +671,20 @@ export async function scanPackages( unknown: severityCounts.unknown, }); - return findings; + const diagnostics = buildCompletenessDiagnostics({ + transientDetailIds, + offlineMissingDetailIds, + confirmedMissingFindingDetailIds, + packumentFailures, + remediationFailures, + chainResolutionFailureCount, + }); + const completeness: ScanCompleteness = { + complete: diagnostics.length === 0, + diagnostics, + }; + + return { findings, completeness }; } catch (error) { spinner.fail("Scan failed"); throw error; @@ -847,6 +898,76 @@ function findFirstFixedVersion(vulns: OsvVuln[]): string | null { return fixedVersions.sort(compareVersions)[0]; } +function buildCompletenessDiagnostics(params: { + transientDetailIds: Set; + offlineMissingDetailIds: Set; + confirmedMissingFindingDetailIds: Set; + packumentFailures: Set; + remediationFailures: Map; + chainResolutionFailureCount: number; +}): ScanDiagnostic[] { + const diagnostics: ScanDiagnostic[] = []; + + function addDiagnostic( + code: ScanDiagnosticCode, + count: number, + impact: ScanDiagnostic["impact"], + affectedPackageCount?: number, + ): void { + if (count === 0) return; + diagnostics.push({ + code, + severity: "warning", + message: formatDiagnosticMessage(code, count, affectedPackageCount), + impact, + count, + ...(affectedPackageCount === undefined ? {} : { affectedPackageCount }), + }); + } + + const remediationTotal = [...params.remediationFailures.values()].reduce((sum, c) => sum + c, 0); + + addDiagnostic("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size, "detection"); + addDiagnostic("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size, "detection"); + addDiagnostic("OSV_DETAIL_CONFIRMED_MISSING", params.confirmedMissingFindingDetailIds.size, "detection"); + addDiagnostic("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size, "remediation"); + addDiagnostic( + "REMEDIATION_FAILURE", + remediationTotal, + "remediation", + params.remediationFailures.size, + ); + addDiagnostic("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation"); + + return diagnostics; +} + +export function formatDiagnosticMessage( + code: ScanDiagnosticCode, + count: number, + affectedPackageCount?: number, +): string { + switch (code) { + case "OSV_DETAIL_TRANSIENT_FAILURE": + return `${count} advisory detail ${pluralize(count, "lookup")} failed with a transient error — re-run to retry.`; + case "OSV_DETAIL_OFFLINE_MISSING": + return `${count} advisory detail ${pluralize(count, "record")} ${pluralize(count, "is", "are")} missing from the local advisory database — refresh to sync.`; + case "OSV_DETAIL_CONFIRMED_MISSING": + return `${count} advisory detail ${pluralize(count, "record")} ${pluralize(count, "is", "are")} confirmed missing from the OSV API — affected findings lack detail data.`; + case "PACKUMENT_FETCH_FAILURE": + return `${count} packument ${pluralize(count, "fetch")} failed — remediation guidance may be incomplete.`; + case "REMEDIATION_FAILURE": + if (affectedPackageCount !== undefined) { + return `${count} transitive remediation ${pluralize(count, "attempt")} failed across ${affectedPackageCount} ${pluralize(affectedPackageCount, "package")} — some fix recommendations may be missing.`; + } + return `${count} transitive remediation ${pluralize(count, "attempt")} failed — some fix recommendations may be missing.`; + case "CHAIN_RESOLUTION_FAILURE": + return `${count} chain resolution ${pluralize(count, "attempt")} failed — some validated upgrade chains may be missing.`; + default: + return `${count} unknown diagnostic occurred.`; + } +} + export function buildCoverageNotes(scanInput: ScanInput, offline: boolean): string[] { const notes = [ "CVE Lite CLI checks package versions against OSV advisories. It does not prove exploitability or runtime reachability.", diff --git a/src/types.ts b/src/types.ts index efe06d78..19ca7d10 100644 --- a/src/types.ts +++ b/src/types.ts @@ -200,6 +200,28 @@ export type Baseline = { findings: BaselineEntry[]; }; +export type ScanDiagnosticCode = + | "OSV_DETAIL_TRANSIENT_FAILURE" + | "OSV_DETAIL_OFFLINE_MISSING" + | "OSV_DETAIL_CONFIRMED_MISSING" + | "PACKUMENT_FETCH_FAILURE" + | "REMEDIATION_FAILURE" + | "CHAIN_RESOLUTION_FAILURE"; + +export type ScanDiagnostic = { + code: ScanDiagnosticCode; + severity: "warning" | "error"; + message: string; + impact: "detection" | "remediation"; + count: number; + affectedPackageCount?: number; +}; + +export type ScanCompleteness = { + complete: boolean; + diagnostics: ScanDiagnostic[]; +}; + export type CliCommand = "scan" | "advisories-sync" | "advisories-init" | "install-skill" | "config" | "overrides"; export type ParsedOptions = { diff --git a/tests/cli-integration.test.ts b/tests/cli-integration.test.ts index f1aae86f..1261bf70 100644 --- a/tests/cli-integration.test.ts +++ b/tests/cli-integration.test.ts @@ -13,6 +13,7 @@ const parseArgsMock = jest.fn(); const loadPackagesMock = jest.fn(); const buildNoPackagesMessageMock = jest.fn(); const scanPackagesMock = jest.fn(); +const emptyCompleteness = { complete: true, diagnostics: [] }; const syncOsvAdvisoriesMock = jest.fn(); const printCacheSummaryMock = jest.fn(); const logInfoMock = jest.fn(); @@ -28,6 +29,7 @@ const printSkippedDependenciesMock = jest.fn(); const printTableMock = jest.fn(); const printFinalStatusMock = jest.fn(); const printCompactOutputMock = jest.fn(); +const printIncompleteDiagnosticsMock = jest.fn(); const printOverrideHintMock = jest.fn(); const buildSuggestedFixCommandPlanMock = jest.fn(); const spawnMock = jest.fn(); @@ -103,6 +105,7 @@ jest.unstable_mockModule("../src/output/printers.js", () => ({ printTable: printTableMock, printFinalStatus: printFinalStatusMock, printCompactOutput: printCompactOutputMock, + printIncompleteDiagnostics: printIncompleteDiagnosticsMock, printOverrideHint: printOverrideHintMock, })); @@ -225,7 +228,7 @@ function setupFixModeWithNpmDirectTarget() { packages: [multerDirectFixFinding.pkg], }), ); - scanPackagesMock.mockResolvedValue([multerDirectFixFinding]); + scanPackagesMock.mockResolvedValue({ findings: [multerDirectFixFinding], completeness: emptyCompleteness }); buildSuggestedFixCommandPlanMock.mockReturnValue(npmFixPlan); } @@ -292,7 +295,7 @@ describe("CLI integration", () => { }); buildNoPackagesMessageMock.mockReturnValue("No scannable packages were found."); loadPackagesMock.mockReturnValue(createScanInput()); - scanPackagesMock.mockResolvedValue([]); + scanPackagesMock.mockResolvedValue({ findings: [], completeness: emptyCompleteness }); syncOsvAdvisoriesMock.mockResolvedValue({ advisoryCount: 0, dbPath: "/tmp/advisories.db", @@ -338,6 +341,140 @@ describe("CLI integration", () => { expect(printCompactOutputMock).not.toHaveBeenCalled(); }); + it("rejects --ratchet when advisory detail data is incomplete", async () => { + const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "cve-lite-ratchet-")); + parseArgsMock.mockReturnValue({ + command: "scan", + options: { + ratchet: true, + failOn: "critical", + batchSize: "100", + searchDepth: "4", + minSeverity: "medium", + }, + projectArg: projectDir, + }); + loadPackagesMock.mockReturnValue(createScanInput({ + packages: [{ name: "incomplete-detail", version: "1.0.0", ecosystem: "npm", paths: [["project", "incomplete-detail"]] }], + })); + scanPackagesMock.mockResolvedValue({ + findings: [], + completeness: { + complete: false, + diagnostics: [{ + code: "OSV_DETAIL_CONFIRMED_MISSING", + severity: "warning", + message: "1 advisory detail record is confirmed missing from the OSV API.", + impact: "detection", + count: 1, + }], + }, + }); + + try { + const result = await runIndexModule(); + const { EXIT_ERROR } = await import("../src/types.js"); + + expect(result.exitCode).toBe(EXIT_ERROR); + expect(printIncompleteDiagnosticsMock).toHaveBeenCalledWith(expect.objectContaining({ complete: false })); + expect(result.stdout.join("\n")).toContain("Refusing to create or evaluate a baseline"); + expect(fs.existsSync(path.join(projectDir, ".cve-lite", "baseline.json"))).toBe(false); + } finally { + fs.rmSync(projectDir, { recursive: true, force: true }); + } + }); + + it("rejects --ratchet baseline comparison when detection data is incomplete", async () => { + const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "cve-lite-ratchet-")); + const baselinePath = path.join(projectDir, ".cve-lite", "baseline.json"); + const baseline = { + version: 1, + createdAt: "2026-07-26T00:00:00.000Z", + findings: [], + }; + fs.mkdirSync(path.dirname(baselinePath), { recursive: true }); + fs.writeFileSync(baselinePath, JSON.stringify(baseline, null, 2) + "\n"); + parseArgsMock.mockReturnValue({ + command: "scan", + options: { + ratchet: true, + failOn: "critical", + batchSize: "100", + searchDepth: "4", + minSeverity: "medium", + }, + projectArg: projectDir, + }); + loadPackagesMock.mockReturnValue(createScanInput({ + packages: [{ name: "incomplete-detail", version: "1.0.0", ecosystem: "npm", paths: [["project", "incomplete-detail"]] }], + })); + scanPackagesMock.mockResolvedValue({ + findings: [createFinding()], + completeness: { + complete: false, + diagnostics: [{ + code: "OSV_DETAIL_CONFIRMED_MISSING", + severity: "warning", + message: "1 advisory detail record is confirmed missing from the OSV API.", + impact: "detection", + count: 1, + }], + }, + }); + + try { + const result = await runIndexModule(); + const { EXIT_ERROR } = await import("../src/types.js"); + + expect(result.exitCode).toBe(EXIT_ERROR); + expect(result.stdout.join("\n")).toContain("Refusing to create or evaluate a baseline"); + expect(JSON.parse(fs.readFileSync(baselinePath, "utf8"))).toEqual(baseline); + } finally { + fs.rmSync(projectDir, { recursive: true, force: true }); + } + }); + + it("allows --ratchet to save a baseline when only remediation data is incomplete", async () => { + const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "cve-lite-ratchet-")); + parseArgsMock.mockReturnValue({ + command: "scan", + options: { + ratchet: true, + failOn: "critical", + batchSize: "100", + searchDepth: "4", + minSeverity: "medium", + }, + projectArg: projectDir, + }); + loadPackagesMock.mockReturnValue(createScanInput({ + packages: [{ name: "remediation-gap", version: "1.0.0", ecosystem: "npm", paths: [["project", "remediation-gap"]] }], + })); + scanPackagesMock.mockResolvedValue({ + findings: [], + completeness: { + complete: false, + diagnostics: [{ + code: "PACKUMENT_FETCH_FAILURE", + severity: "warning", + message: "1 packument fetch failed.", + impact: "remediation", + count: 1, + }], + }, + }); + + try { + const result = await runIndexModule(); + + expect(result.exitCode).toBe(0); + expect(printIncompleteDiagnosticsMock).toHaveBeenCalledWith(expect.objectContaining({ complete: false })); + expect(fs.existsSync(path.join(projectDir, ".cve-lite", "baseline.json"))).toBe(true); + } finally { + fs.rmSync(projectDir, { recursive: true, force: true }); + } + }); + it("suppresses compact output when --sarif is used", async () => { parseArgsMock.mockReturnValue({ command: "scan", @@ -479,7 +616,7 @@ describe("CLI integration", () => { projectArg: ".", }); loadPackagesMock.mockReturnValue(createScanInput({ packages: [finding.pkg] })); - scanPackagesMock.mockResolvedValue([finding]); + scanPackagesMock.mockResolvedValue({ findings: [finding], completeness: emptyCompleteness }); const result = await runIndexModule(); @@ -646,7 +783,7 @@ describe("CLI integration", () => { skippedDependencies: ["dependencies:debug@^4.3.0"], }), ); - scanPackagesMock.mockResolvedValue([finding]); + scanPackagesMock.mockResolvedValue({ findings: [finding], completeness: emptyCompleteness }); const result = await runIndexModule(); @@ -862,7 +999,7 @@ describe("CLI integration", () => { loadPackagesMock .mockReturnValueOnce(createScanInput({ source: "package-lock", filePath: "/tmp/project/package-lock.json", packages: [finding.pkg] })) .mockReturnValueOnce(createScanInput({ source: "package-lock", filePath: "/tmp/project/package-lock.json", packages: [finding.pkg] })); - scanPackagesMock.mockResolvedValueOnce([finding]).mockResolvedValueOnce([]); + scanPackagesMock.mockResolvedValueOnce({ findings: [finding], completeness: emptyCompleteness }).mockResolvedValueOnce({ findings: [], completeness: emptyCompleteness }); buildSuggestedFixCommandPlanMock.mockReturnValueOnce({ packageManager: "npm", sourceLabel: "package-lock.json", @@ -1015,7 +1152,7 @@ describe("CLI integration", () => { { name: "lodash", version: "4.17.21", ecosystem: "npm", paths: [["project", "lodash"]] }, ]; loadPackagesMock.mockReturnValue(createScanInput({ packages })); - scanPackagesMock.mockResolvedValue([]); + scanPackagesMock.mockResolvedValue({ findings: [], completeness: emptyCompleteness }); parseArgsMock.mockReturnValue({ command: "scan", options: { @@ -1065,7 +1202,7 @@ describe("CLI integration", () => { { name: "lodash", version: "4.17.21", ecosystem: "npm", paths: [["project", "lodash"]] }, ]; loadPackagesMock.mockReturnValue(createScanInput({ packages })); - scanPackagesMock.mockResolvedValue([]); + scanPackagesMock.mockResolvedValue({ findings: [], completeness: emptyCompleteness }); parseArgsMock.mockReturnValue({ command: "scan", options: { diff --git a/tests/html-reporter.test.ts b/tests/html-reporter.test.ts index 17339392..e36929e9 100644 --- a/tests/html-reporter.test.ts +++ b/tests/html-reporter.test.ts @@ -827,3 +827,34 @@ describe("writeHtmlReport", () => { } }); }); + +describe("scan completeness HTML rendering", () => { + it("does not render a banner when completeness is not set (undefined)", () => { + const data = buildReportData(BASE_PARAMS); + const html = renderHtmlReport(data); + expect(html).not.toContain("Scan data is incomplete"); + }); + + it("does not render a banner for a complete scan", () => { + const data = buildReportData({ ...BASE_PARAMS, completeness: { complete: true, diagnostics: [] } }); + const html = renderHtmlReport(data); + expect(html).not.toContain("Scan data is incomplete"); + }); + + it("renders an incomplete-scan banner with diagnostics when complete is false", () => { + const data = buildReportData({ + ...BASE_PARAMS, + completeness: { + complete: false, + diagnostics: [ + { code: "OSV_DETAIL_TRANSIENT_FAILURE", severity: "warning", message: "3 lookups failed", impact: "detection", count: 3 }, + { code: "PACKUMENT_FETCH_FAILURE", severity: "warning", message: "1 packument fetch failed", impact: "remediation", count: 1 }, + ], + }, + }); + const html = renderHtmlReport(data); + expect(html).toContain("Scan data is incomplete"); + expect(html).toContain("3 lookups failed"); + expect(html).toContain("1 packument fetch failed"); + }); +}); diff --git a/tests/multi-folder-scan.test.ts b/tests/multi-folder-scan.test.ts index 62c6dca8..fd2439d4 100644 --- a/tests/multi-folder-scan.test.ts +++ b/tests/multi-folder-scan.test.ts @@ -1,7 +1,7 @@ import { jest } from "@jest/globals"; const loadMultiplePackagesMock = jest.fn(); -const scanPackagesMock = jest.fn(() => Promise.resolve([])); +const scanPackagesMock = jest.fn(() => Promise.resolve({ findings: [], completeness: { complete: true, diagnostics: [] } })); const buildCoverageNotesMock = jest.fn(() => []); const sortFindingsForOutputMock = jest.fn((f: any[]) => f); const normalizeSeverityMock = jest.fn(() => "medium"); @@ -20,6 +20,22 @@ jest.unstable_mockModule("../src/parsers/multi-package.js", () => ({ jest.unstable_mockModule("../src/scanner.js", () => ({ scanPackages: scanPackagesMock, buildCoverageNotes: buildCoverageNotesMock, + formatDiagnosticMessage: (code: string, count: number, affectedPackageCount?: number) => { + const labels: Record = { + OSV_DETAIL_TRANSIENT_FAILURE: "advisory detail lookup", + OSV_DETAIL_OFFLINE_MISSING: "advisory detail record", + PACKUMENT_FETCH_FAILURE: "packument fetch", + REMEDIATION_FAILURE: "transitive remediation attempt", + CHAIN_RESOLUTION_FAILURE: "chain resolution attempt", + }; + const label = labels[code] ?? "issue"; + const plural = count === 1 ? label : label + "s"; + if (code === "REMEDIATION_FAILURE" && affectedPackageCount !== undefined) { + const packages = affectedPackageCount === 1 ? "package" : "packages"; + return `${count} ${plural} failed across ${affectedPackageCount} ${packages} — re-run to retry.`; + } + return `${count} ${plural} failed — re-run to retry.`; + }, })); jest.unstable_mockModule("../src/output/formatters.js", () => ({ @@ -451,3 +467,93 @@ describe("handleMultiFolderScan - maintenance risk terminal render", () => { expect(written).toContain("maintenance risk"); }); }); + +describe("aggregateMultiFolderCompleteness", () => { + it("merges same-code diagnostics with correct count and pluralized message", async () => { + const { aggregateMultiFolderCompleteness } = await import("../src/scan/multi-folder-scan.js"); + const results = [ + { + subfolder: "apps/api", + completeness: { complete: false, diagnostics: [{ code: "OSV_DETAIL_TRANSIENT_FAILURE" as const, severity: "warning" as const, message: "1 advisory detail lookup failed with a transient error — re-run to retry.", impact: "detection" as const, count: 1 }] }, + }, + { + subfolder: "apps/web", + completeness: { complete: false, diagnostics: [{ code: "OSV_DETAIL_TRANSIENT_FAILURE" as const, severity: "warning" as const, message: "1 advisory detail lookup failed with a transient error — re-run to retry.", impact: "detection" as const, count: 1 }] }, + }, + { + subfolder: "packages/shared", + completeness: { complete: true, diagnostics: [] }, + }, + ] as any; + + const aggregated = aggregateMultiFolderCompleteness(results); + + expect(aggregated.complete).toBe(false); + expect(aggregated.diagnostics).toHaveLength(1); + expect(aggregated.diagnostics[0]!.code).toBe("OSV_DETAIL_TRANSIENT_FAILURE"); + expect(aggregated.diagnostics[0]!.count).toBe(2); + expect(aggregated.diagnostics[0]!.message).toBe("2 advisory detail lookups failed — re-run to retry."); + }); + + it("keeps distinct diagnostic codes separate", async () => { + const { aggregateMultiFolderCompleteness } = await import("../src/scan/multi-folder-scan.js"); + const results = [ + { + subfolder: "a", + completeness: { complete: false, diagnostics: [ + { code: "PACKUMENT_FETCH_FAILURE" as const, severity: "warning" as const, message: "1 packument fetch failed — remediation guidance may be incomplete.", impact: "remediation" as const, count: 1 }, + { code: "REMEDIATION_FAILURE" as const, severity: "warning" as const, message: "3 transitive remediation attempts failed — some fix recommendations may be missing.", impact: "remediation" as const, count: 3 }, + ] }, + }, + ] as any; + + const aggregated = aggregateMultiFolderCompleteness(results); + + expect(aggregated.complete).toBe(false); + expect(aggregated.diagnostics).toHaveLength(2); + expect(aggregated.diagnostics.map(d => d.code).sort()).toEqual(["PACKUMENT_FETCH_FAILURE", "REMEDIATION_FAILURE"]); + expect(aggregated.diagnostics.find(d => d.code === "PACKUMENT_FETCH_FAILURE")!.message).toBe("1 packument fetch failed — remediation guidance may be incomplete."); + expect(aggregated.diagnostics.find(d => d.code === "REMEDIATION_FAILURE")!.message).toBe("3 transitive remediation attempts failed — some fix recommendations may be missing."); + }); + + it("aggregates remediation attempts and affected package counts", async () => { + const { aggregateMultiFolderCompleteness } = await import("../src/scan/multi-folder-scan.js"); + const results = [ + { + subfolder: "a", + completeness: { complete: false, diagnostics: [ + { + code: "REMEDIATION_FAILURE" as const, + severity: "warning" as const, + message: "2 transitive remediation attempts failed across 1 package.", + impact: "remediation" as const, + count: 2, + affectedPackageCount: 1, + }, + ] }, + }, + { + subfolder: "b", + completeness: { complete: false, diagnostics: [ + { + code: "REMEDIATION_FAILURE" as const, + severity: "warning" as const, + message: "1 transitive remediation attempt failed across 2 packages.", + impact: "remediation" as const, + count: 1, + affectedPackageCount: 2, + }, + ] }, + }, + ] as any; + + const aggregated = aggregateMultiFolderCompleteness(results); + const diagnostic = aggregated.diagnostics[0]!; + + expect(diagnostic.count).toBe(3); + expect(diagnostic.affectedPackageCount).toBe(3); + expect(diagnostic.message).toBe( + "3 transitive remediation attempts failed across 3 packages — re-run to retry.", + ); + }); +}); diff --git a/tests/output.test.ts b/tests/output.test.ts index 4f151753..bb3005a8 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -25,6 +25,7 @@ import { printActionSummary, printCompactOutput, printFinalStatus, + printIncompleteDiagnostics, printOverrideHint, printSuggestedFixCommands, printSuggestedFixCommandSkips, @@ -2388,6 +2389,15 @@ describe("printActionSummary - override count", () => { }); describe("printFinalStatus - override count", () => { + it("uses the correct plural form for multiple vulnerabilities", () => { + const consoleSpy = jest.spyOn(console, "log").mockImplementation(() => {}); + printFinalStatus([createFinding(), createFinding()], 0); + const out = consoleSpy.mock.calls.map(c => stripAnsi(String(c[0]))).join("\n"); + expect(out).toContain("2 vulnerabilities"); + expect(out).not.toContain("vulnerabilitys"); + consoleSpy.mockRestore(); + }); + it("includes override count in status when overrides exist but no vulns", () => { const consoleSpy = jest.spyOn(console, "log").mockImplementation(() => {}); printFinalStatus([], 3); @@ -2733,3 +2743,93 @@ describe("printSuggestedFixCommands - cooldown warning", () => { expect(output).not.toContain("release cooldown"); }); }); + +describe("printIncompleteDiagnostics", () => { + it("prints nothing when completeness is undefined", () => { + const lines = captureLogs(() => { + printIncompleteDiagnostics(undefined); + }); + expect(lines.join("\n")).not.toContain("Scan data is incomplete"); + }); + + it("prints nothing for a complete scan", () => { + const lines = captureLogs(() => { + printIncompleteDiagnostics({ complete: true, diagnostics: [] }); + }); + expect(lines.join("\n")).not.toContain("Scan data is incomplete"); + }); + + it("prints diagnostics without a duplicate title for an incomplete scan", () => { + const lines = captureLogs(() => { + printIncompleteDiagnostics({ + complete: false, + diagnostics: [ + { code: "OSV_DETAIL_TRANSIENT_FAILURE", severity: "warning", message: "3 lookups failed", impact: "detection", count: 3 }, + { code: "PACKUMENT_FETCH_FAILURE", severity: "warning", message: "1 packument fetch failed", impact: "remediation", count: 1 }, + ], + }); + }); + const output = lines.join("\n"); + expect(output).not.toContain("Scan data is incomplete"); + expect(output).toContain("3 lookups failed"); + expect(output).toContain("1 packument fetch failed"); + expect(output).toContain("Resolve the issues above and re-run the scan."); + }); + + it("does not print for a complete scan with empty diagnostics", () => { + const lines = captureLogs(() => { + printIncompleteDiagnostics({ complete: true, diagnostics: [] }); + }); + const output = lines.join("\n"); + expect(output).toBe(""); + }); +}); + +describe("incomplete scan output integration", () => { + const incompleteCompleteness = { + complete: false, + diagnostics: [ + { + code: "OSV_DETAIL_TRANSIENT_FAILURE" as const, + severity: "warning" as const, + message: "2 advisory detail lookups failed", + impact: "detection" as const, + count: 2, + }, + ], + }; + + it("verbose output shows a single partial-scan title plus diagnostics", () => { + const lines = captureLogs(() => { + printFinalStatus([createFinding()], 0, incompleteCompleteness); + }); + const output = lines.join("\n"); + expect(output).toContain("Partial scan"); + expect(output).not.toContain("Scan data is incomplete"); + expect(output).not.toContain("Scan complete"); + expect(output).toContain("2 advisory detail lookups failed"); + expect(output).toContain("Resolve the issues above and re-run the scan."); + }); + + it("compact output with findings does not report scan complete", () => { + const lines = captureLogs(() => { + printCompactOutput([createFinding()], createScanInput(), { completeness: incompleteCompleteness }); + }); + const output = lines.join("\n"); + expect(output).toContain("Partial scan"); + expect(output).not.toContain("Scan complete"); + expect(output).toContain("2 advisory detail lookups failed"); + }); + + it("compact output with no findings prints diagnostic details without a duplicate title", () => { + const lines = captureLogs(() => { + printCompactOutput([], createScanInput(), { completeness: incompleteCompleteness }); + }); + const output = lines.join("\n"); + expect(output).toContain("No known vulnerabilities were resolved"); + expect(output).toContain("2 advisory detail lookups failed"); + expect(output).toContain("Resolve the issues above and re-run the scan."); + expect(output).not.toContain("Scan complete"); + expect(output.match(/incomplete/g)?.length ?? 0).toBe(1); + }); +}); diff --git a/tests/scanner-cache.test.ts b/tests/scanner-cache.test.ts index 57ef1d6f..1cc7fc30 100644 --- a/tests/scanner-cache.test.ts +++ b/tests/scanner-cache.test.ts @@ -4,7 +4,7 @@ import path from "node:path"; import { jest } from "@jest/globals"; import type { OsvVuln, PackageRef, ParsedOptions } from "../src/types.js"; import { LocalAdvisoryDatabase } from "../src/advisory/local-db.js"; -import { clearPackumentCache, fetchPackument } from "../src/remediation/npm-registry.js"; +import { clearPackumentCache, fetchPackument, runWithObserver } from "../src/remediation/npm-registry.js"; import { removeDir } from "./test-utils.js"; const queryBatchMock = jest.fn(); @@ -104,7 +104,7 @@ describe("scanPackages cache behavior", () => { getVulnMock.mockResolvedValue(detail); try { - const firstFindings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings: firstFindings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(firstFindings).toHaveLength(1); expect(firstFindings[0]?.vulnerabilities).toEqual([detail]); expect(queryBatchMock).toHaveBeenCalledTimes(1); @@ -113,7 +113,7 @@ describe("scanPackages cache behavior", () => { queryBatchMock.mockClear(); getVulnMock.mockClear(); - const secondFindings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings: secondFindings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(secondFindings).toHaveLength(1); expect(secondFindings[0]?.vulnerabilities).toEqual([detail]); expect(queryBatchMock).not.toHaveBeenCalled(); @@ -145,11 +145,10 @@ describe("scanPackages cache behavior", () => { ); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings, completeness } = await scanPackages([pkg], 100, createOptions(cacheDir)); - expect(findings).toHaveLength(1); - expect(findings[0]?.vulnerabilities).toEqual([]); - expect(findings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-NULL"]); + expect(findings).toEqual([]); + expect(completeness).toEqual({ complete: true, diagnostics: [] }); expect(queryBatchMock).not.toHaveBeenCalled(); expect(getVulnMock).not.toHaveBeenCalled(); } finally { @@ -246,7 +245,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages( + const { findings } = await scanPackages( [mochaPkg, transitivePkg], 100, { @@ -302,7 +301,7 @@ describe("scanPackages cache behavior", () => { db.close(); try { - const findings = await scanPackages([pkg], 100, { + const { findings } = await scanPackages([pkg], 100, { ...createOptions(tempDir), offline: true, offlineDb: dbPath, @@ -365,7 +364,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.firstFixedVersion).toBe("1.0.2"); @@ -400,7 +399,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir), { + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir), { directDependencyNames: new Set(["typescript", "jest"]), }); @@ -433,7 +432,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir), { + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir), { directDependencyNames: new Set(["diff", "typescript"]), }); @@ -489,7 +488,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.firstFixedVersion).toBe("2.0.1"); @@ -515,7 +514,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); // OSV-GOOD detail should be present even though OSV-BAD failed expect(findings).toHaveLength(1); expect(findings[0]?.vulnerabilities).toEqual([goodDetail]); @@ -551,7 +550,7 @@ describe("scanPackages cache behavior", () => { getVulnMock.mockResolvedValue(freshDetail); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); // Both details should appear in the finding expect(findings[0]?.vulnerabilities).toEqual(expect.arrayContaining([cachedDetail, freshDetail])); @@ -618,7 +617,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir), { + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir), { directDependencyNames: new Set(["js-yaml"]), }); @@ -789,7 +788,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.validatedFirstFixedVersion).toBe("4.17.21"); @@ -829,7 +828,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.validatedFirstFixedVersion).toBe("1.0.1"); @@ -860,7 +859,7 @@ describe("scanPackages cache behavior", () => { fetchMock.mockResolvedValue({ ok: false, status: 404 }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.maliciousUnverifiable).toBe(true); } finally { @@ -889,7 +888,7 @@ describe("scanPackages cache behavior", () => { fetchMock.mockResolvedValue({ ok: false, status: 404 }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.maliciousUnverifiable).toBeUndefined(); } finally { @@ -917,7 +916,7 @@ describe("scanPackages cache behavior", () => { fetchMock.mockResolvedValue({ ok: false, status: 404 }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.maliciousUnverifiable).toBeUndefined(); } finally { @@ -946,7 +945,7 @@ describe("scanPackages cache behavior", () => { fetchMock.mockResolvedValue({ ok: false, status: 404 }); try { - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.maliciousUnverifiable).toBeUndefined(); } finally { @@ -973,7 +972,7 @@ describe("scanPackages cache behavior", () => { try { (console.log as jest.Mock).mockClear(); - const findings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(findings).toHaveLength(1); expect(findings[0]?.vulnerabilities).toEqual([goodDetail]); expect(findings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-TRANSIENT"]); @@ -1003,14 +1002,14 @@ describe("scanPackages cache behavior", () => { }); try { - const firstFindings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings: firstFindings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(firstFindings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-RETRY"]); expect(callCount).toBe(1); queryBatchMock.mockClear(); getVulnMock.mockClear(); - const secondFindings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings: secondFindings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(secondFindings[0]?.vulnerabilities).toEqual([detail]); expect(getVulnMock).toHaveBeenCalledWith("OSV-RETRY"); } finally { @@ -1018,7 +1017,7 @@ describe("scanPackages cache behavior", () => { } }); - it("uses negative caching for a confirmed missing detail record", async () => { + it("does not mark a scan incomplete for a confirmed missing detail without a finding", async () => { const cacheDir = createTempCacheDir(); const pkg = createPackage("neg-cache-pkg", "1.0.0"); @@ -1032,18 +1031,67 @@ describe("scanPackages cache behavior", () => { getVulnMock.mockRejectedValue(new Error("OSV vuln fetch failed for OSV-404-MISSING: 404 Not Found")); try { - const firstFindings = await scanPackages([pkg], 100, createOptions(cacheDir)); - expect(firstFindings).toHaveLength(1); - expect(firstFindings[0]?.vulnerabilities).toEqual([]); - expect(firstFindings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-404-MISSING"]); + const { findings: firstFindings, completeness: firstCompleteness } = await scanPackages([pkg], 100, createOptions(cacheDir)); + expect(firstFindings).toEqual([]); + expect(firstCompleteness).toEqual({ + complete: true, + diagnostics: [], + }); queryBatchMock.mockClear(); getVulnMock.mockClear(); - const secondFindings = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings: secondFindings, completeness: secondCompleteness } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(getVulnMock).not.toHaveBeenCalled(); - expect(secondFindings[0]?.vulnerabilities).toEqual([]); - expect(secondFindings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-404-MISSING"]); + expect(secondFindings).toEqual([]); + expect(secondCompleteness).toEqual({ + complete: true, + diagnostics: [], + }); + } finally { + removeDir(cacheDir); + } + }); + + it("marks a confirmed missing detail incomplete when another advisory supports the finding", async () => { + const cacheDir = createTempCacheDir(); + const pkg = createPackage("mixed-detail-pkg", "1.0.0"); + const detail: OsvVuln = { id: "OSV-PRESENT" }; + + queryBatchMock.mockResolvedValue([ + { + package: pkg.name, + version: pkg.version, + vulnerabilities: [{ id: "OSV-PRESENT" }, { id: "OSV-404-MISSING" }], + }, + ]); + getVulnMock.mockImplementation(async (id: string) => { + if (id === "OSV-404-MISSING") { + throw new Error("OSV vuln fetch failed for OSV-404-MISSING: 404 Not Found"); + } + return detail; + }); + fetchMock.mockResolvedValue({ + ok: true, + json: async () => ({ versions: {} }), + }); + + try { + const { findings, completeness } = await scanPackages([pkg], 100, createOptions(cacheDir)); + + expect(findings).toHaveLength(1); + expect(findings[0]?.vulnerabilities).toEqual([detail]); + expect(findings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-404-MISSING"]); + expect(completeness).toEqual({ + complete: false, + diagnostics: [ + expect.objectContaining({ + code: "OSV_DETAIL_CONFIRMED_MISSING", + impact: "detection", + count: 1, + }), + ], + }); } finally { removeDir(cacheDir); } @@ -1074,7 +1122,7 @@ describe("scanPackages cache behavior", () => { try { (console.log as jest.Mock).mockClear(); - const findings = await scanPackages([pkg1, pkg2], 100, { + const { findings } = await scanPackages([pkg1, pkg2], 100, { ...createOptions(cacheDir), json: false, }); @@ -1127,7 +1175,7 @@ describe("scanPackages cache behavior", () => { const debugLog = jest.fn(); try { - const findings = await scanPackages([pkgA, pkgB], 100, createOptions(cacheDir), { + const { findings } = await scanPackages([pkgA, pkgB], 100, createOptions(cacheDir), { directDependencyNames: new Set(["pkg-a"]), scanSource: "package-lock", scanFilePath: lockfilePath, @@ -1182,12 +1230,20 @@ describe("scanPackages cache behavior", () => { const debugLog = jest.fn(); try { - const findings = await scanPackages([pkgA, pkgC], 100, createOptions(cacheDir), { + const { findings, completeness } = await scanPackages([pkgA, pkgC], 100, createOptions(cacheDir), { directDependencyNames: new Set(["pkg-a"]), }, debugLog); const matched = findings.find(f => f.pkg.name === "pkg-c"); expect(matched).toBeDefined(); + expect(completeness.diagnostics).toContainEqual( + expect.objectContaining({ + code: "REMEDIATION_FAILURE", + count: 1, + affectedPackageCount: 1, + message: "1 transitive remediation attempt failed across 1 package — some fix recommendations may be missing.", + }), + ); expect(debugLog).toHaveBeenCalledWith( "Remediation failed", expect.objectContaining({ package: "pkg-c" }), @@ -1222,7 +1278,7 @@ describe("scanPackages cache behavior", () => { clearPackumentCache(); }); - it("warns about transient failures and suggests re-running, but not about confirmed 404s", async () => { + it("warns about transient failures and confirmed missing details", async () => { const cacheDir = createTempCacheDir(); const pkg = createPackage("mix-fail-pkg", "1.0.0"); const goodDetail: OsvVuln = { id: "OSV-MIX-GOOD" }; @@ -1246,7 +1302,7 @@ describe("scanPackages cache behavior", () => { try { (console.log as jest.Mock).mockClear(); - const findings = await scanPackages([pkg], 100, { + const { findings } = await scanPackages([pkg], 100, { ...createOptions(cacheDir), json: false, }); @@ -1264,7 +1320,7 @@ describe("scanPackages cache behavior", () => { expect.stringContaining("1 from transient failures — re-run to retry"), ); expect(console.log).toHaveBeenCalledWith( - expect.stringContaining("1 could not be resolved"), + expect.stringContaining("1 confirmed missing from the OSV API"), ); } finally { removeDir(cacheDir); @@ -1290,7 +1346,7 @@ describe("scanPackages cache behavior", () => { db.close(); try { - const findings = await scanPackages([pkg], 100, { + const { findings } = await scanPackages([pkg], 100, { ...createOptions(tempDir), offline: true, offlineDb: dbPath, @@ -1303,4 +1359,150 @@ describe("scanPackages cache behavior", () => { removeDir(tempDir); } }); + + describe("registry fetch observer", () => { + let cacheDir: string; + + beforeEach(async () => { + cacheDir = createTempCacheDir(); + clearPackumentCache(); + }); + + afterEach(() => { + if (fs.existsSync(cacheDir)) removeDir(cacheDir); + }); + + it("preserves a transient failure after a successful retry", async () => { + const pkg: PackageRef = { + name: "observer-retry-ok", + version: "1.0.0", + ecosystem: "npm", + paths: [["root", "observer-parent", "observer-retry-ok"]], + }; + const parent = createPackage("observer-parent", "1.0.0"); + const detail: OsvVuln = { + id: "OSV-OBSERVER-RETRY", + aliases: ["CVE-2026-OBR"], + affected: [{ package: { ecosystem: "npm", name: "observer-retry-ok" }, ranges: [{ events: [{ introduced: "0" }, { fixed: "2.0.0" }] }] }], + }; + + queryBatchMock.mockResolvedValue([ + { package: pkg.name, version: pkg.version, vulnerabilities: [{ id: detail.id }] }, + { package: parent.name, version: parent.version, vulnerabilities: [] }, + ]); + getVulnMock.mockResolvedValue(detail); + + let callCount = 0; + fetchMock.mockImplementation(async (input: string | URL | Request) => { + if (!String(input).endsWith("/observer-retry-ok")) { + return { ok: true, json: async () => ({ versions: { "1.0.0": {} } }) }; + } + callCount++; + if (callCount === 1) throw new Error("timeout"); + return { ok: true, json: async () => ({ versions: { "2.0.0": {} } }) }; + }); + + const { completeness } = await scanPackages([pkg, parent], 100, createOptions(cacheDir), { + directDependencyNames: new Set(["observer-parent"]), + }); + + expect(callCount).toBe(2); + expect(completeness.complete).toBe(false); + expect(completeness.diagnostics).toEqual([ + expect.objectContaining({ + code: "PACKUMENT_FETCH_FAILURE", + impact: "remediation", + count: 1, + }), + ]); + }); + + it("preserves a transient failure after a 404 retry", async () => { + const pkg: PackageRef = { + name: "observer-retry-404", + version: "1.0.0", + ecosystem: "npm", + paths: [["root", "observer-parent", "observer-retry-404"]], + }; + const parent = createPackage("observer-parent", "1.0.0"); + const detail: OsvVuln = { + id: "OSV-OBSERVER-404", + aliases: ["CVE-2026-O404"], + affected: [{ package: { ecosystem: "npm", name: "observer-retry-404" }, ranges: [{ events: [{ introduced: "0" }, { fixed: "2.0.0" }] }] }], + }; + + queryBatchMock.mockResolvedValue([ + { package: pkg.name, version: pkg.version, vulnerabilities: [{ id: detail.id }] }, + { package: parent.name, version: parent.version, vulnerabilities: [] }, + ]); + getVulnMock.mockResolvedValue(detail); + + let callCount = 0; + fetchMock.mockImplementation(async (input: string | URL | Request) => { + if (!String(input).endsWith("/observer-retry-404")) { + return { ok: true, json: async () => ({ versions: { "1.0.0": {} } }) }; + } + callCount++; + if (callCount === 1) throw new Error("timeout"); + return { ok: false, status: 404 }; + }); + + const { completeness } = await scanPackages([pkg, parent], 100, createOptions(cacheDir), { + directDependencyNames: new Set(["observer-parent"]), + }); + + expect(callCount).toBe(2); + expect(completeness.complete).toBe(false); + expect(completeness.diagnostics).toEqual([ + expect.objectContaining({ + code: "PACKUMENT_FETCH_FAILURE", + impact: "remediation", + count: 1, + }), + ]); + }); + + it("notifies each concurrent caller's observer when sharing an in-flight fetch", async () => { + clearPackumentCache(); + fetchMock.mockImplementation(async () => { + throw new Error("timeout"); + }); + + const failuresA: string[] = []; + const failuresB: string[] = []; + const observerA = { onTransientFailure: (name: string) => { failuresA.push(name); } }; + const observerB = { onTransientFailure: (name: string) => { failuresB.push(name); } }; + + await Promise.all([ + runWithObserver(observerA, () => fetchPackument("shared-package")), + runWithObserver(observerB, () => fetchPackument("shared-package")), + ]); + + expect(failuresA).toEqual(["shared-package"]); + expect(failuresB).toEqual(["shared-package"]); + // The second caller reuses the in-flight request instead of refetching. + expect(fetchMock).toHaveBeenCalledTimes(1); + }); + + it("notifies the caller's observer for a cached result", async () => { + clearPackumentCache(); + fetchMock.mockResolvedValue({ ok: false, status: 404 }); + + const firstCallFailures: string[] = []; + const secondCallResolved: string[] = []; + + await runWithObserver( + { onTransientFailure: (name: string) => { firstCallFailures.push(name); } }, + () => fetchPackument("cached-404-package"), + ); + await runWithObserver( + { onResolved: (name: string) => { secondCallResolved.push(name); } }, + () => fetchPackument("cached-404-package"), + ); + + expect(firstCallFailures).toEqual([]); + expect(secondCallResolved).toEqual(["cached-404-package"]); + expect(fetchMock).toHaveBeenCalledTimes(1); + }); + }); }); diff --git a/tests/write-outputs.test.ts b/tests/write-outputs.test.ts index 95361bd6..842139b8 100644 --- a/tests/write-outputs.test.ts +++ b/tests/write-outputs.test.ts @@ -58,6 +58,7 @@ const mockScanState = { coverage: [], minSeverity: "medium" as const, tableFindings: [], + completeness: { complete: true, diagnostics: [] }, }; const mockScanInput: ScanInput = { @@ -151,4 +152,49 @@ describe("writeOutputs", () => { expect(metaArg).toBeNull(); }); }); + + describe("scan completeness JSON fields", () => { + it("includes complete:true and empty diagnostics for a healthy scan", async () => { + await writeOutputs(makeOptions({ json: true }), mockScanState, mockScanInput, "/tmp/project"); + const [, jsonContent] = writeFileSyncMock.mock.calls[writeFileSyncMock.mock.calls.length - 1] as [string, string]; + const parsed = JSON.parse(jsonContent); + expect(parsed.status).toBe("ok"); + expect(parsed.complete).toBe(true); + expect(parsed.diagnostics).toEqual([]); + }); + + it("includes complete:false and diagnostics when completeness indicates a partial scan", async () => { + const partialState = { + ...mockScanState, + completeness: { + complete: false, + diagnostics: [ + { + code: "OSV_DETAIL_TRANSIENT_FAILURE" as const, + severity: "warning" as const, + message: "5 advisory detail lookups failed with a transient error", + impact: "detection" as const, + count: 5, + }, + { + code: "PACKUMENT_FETCH_FAILURE" as const, + severity: "warning" as const, + message: "2 packument fetches failed", + impact: "remediation" as const, + count: 2, + }, + ], + }, + }; + await writeOutputs(makeOptions({ json: true }), partialState, mockScanInput, "/tmp/project"); + const [, jsonContent] = writeFileSyncMock.mock.calls[writeFileSyncMock.mock.calls.length - 1] as [string, string]; + const parsed = JSON.parse(jsonContent); + expect(parsed.status).toBe("partial"); + expect(parsed.complete).toBe(false); + expect(parsed.diagnostics).toEqual([ + expect.objectContaining({ code: "OSV_DETAIL_TRANSIENT_FAILURE", impact: "detection" }), + expect.objectContaining({ code: "PACKUMENT_FETCH_FAILURE", impact: "remediation" }), + ]); + }); + }); });