From d1e7e77db91a50da3e5cdbac24d0be82d8153149 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 11:28:53 +0800 Subject: [PATCH 01/25] feat(scanner,output): report incomplete scan data with diagnostics Track scan completeness by capturing transient OSV detail failures, offline missing records, packument fetch errors, remediation failures, and chain resolution failures. Surface diagnostic warnings in CLI output, HTML report banner, and JSON output when scan data may be incomplete. --- src/index.ts | 8 +-- src/output/html-reporter.ts | 30 ++++++++++- src/output/printers.ts | 52 +++++++++++------- src/output/write-outputs.ts | 6 ++- src/scan/multi-folder-scan.ts | 2 +- src/scanner.ts | 95 +++++++++++++++++++++++++++++++-- src/types.ts | 20 +++++++ tests/cli-integration.test.ts | 15 +++--- tests/html-reporter.test.ts | 31 +++++++++++ tests/multi-folder-scan.test.ts | 2 +- tests/output.test.ts | 42 +++++++++++++++ tests/scanner-cache.test.ts | 56 +++++++++---------- tests/write-outputs.test.ts | 49 ++++++++++++++--- 13 files changed, 335 insertions(+), 73 deletions(-) diff --git a/src/index.ts b/src/index.ts index 5b4f17fc..362e9489 100644 --- a/src/index.ts +++ b/src/index.ts @@ -702,13 +702,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 +740,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 +827,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 +888,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..042775b7 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); 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,23 @@ function renderTransitiveContextCol(finding: SerializedFinding): string {
`; } +function renderCompletenessBanner(data: ReportData): string { + if (data.completeness == null || data.completeness.complete) return ""; + + const diagRows = data.completeness.diagnostics.map(d => + `
  • ${escapeHtml(d.message)}
    • ` + ).join("\\n"); + + return `
    +
    ⚠
    +
    + Scan data is incomplete +

    The scan result may be missing some findings because the following issues occurred:

    +
      ${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/printers.ts b/src/output/printers.ts index 184b1137..ce01a2fd 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,7 +320,7 @@ 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("────────────────────────────────")); @@ -334,26 +334,26 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0) { } 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; + } else { + 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; + 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.` + ) + ); + } else { + console.log( + chalk.yellow( + `▲ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${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.` - ) - ); + printIncompleteWarning(completeness); } export function printOverrideHint(): void { @@ -417,7 +417,7 @@ 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) { @@ -620,9 +620,21 @@ export function printCompactOutput( if (!options?.all) { console.log(chalk.gray(`Run with ${chalk.whiteBright("--verbose")} for fix plan, paths, and full table.`)); } + printIncompleteWarning(options?.completeness); console.log(""); } +export function printIncompleteWarning(completeness?: ScanCompleteness): void { + if (!completeness || completeness.complete) return; + console.log(""); + console.log(chalk.yellow("⚠ Scan data is incomplete.")); + 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(" Re-run the scan to get a complete result.")); +} + function renderSeverityTable(counts: { critical: number; high: number; medium: number; low: number; unknown: number }): string { const labels = ["Critical", "High", "Medium", "Low", "Unknown"]; const coloredValues = [ diff --git a/src/output/write-outputs.ts b/src/output/write-outputs.ts index 17ed9e90..f2abc99e 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 !== false ? "ok" : "partial", + complete: scanState.completeness?.complete ?? true, + diagnostics: scanState.completeness?.diagnostics ?? [], suggestedFixCommands: scanState.suggestedFixCommands, notes: [...scanInput.notes, ...scanState.coverage], warnings: scanInput.warnings, diff --git a/src/scan/multi-folder-scan.ts b/src/scan/multi-folder-scan.ts index 569b9b91..7b3308f9 100644 --- a/src/scan/multi-folder-scan.ts +++ b/src/scan/multi-folder-scan.ts @@ -59,7 +59,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 } = await scanPackages(scanInput.packages, params.batchSize, params.options, { directDependencyNames, scanSource: scanInput.source, scanFilePath: scanInput.filePath, diff --git a/src/scanner.ts b/src/scanner.ts index ece063ca..926c5e70 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, 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"; @@ -107,7 +107,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, @@ -428,6 +428,10 @@ 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; + const npmRemediationCache = new Map(); const parentUpgradeCache = new Map(); const directValidationCount = offline ? 0 : findings.length; @@ -476,7 +480,10 @@ export async function scanPackages( } if (packumentsToPrewarm.size > 0) { await runWithConcurrency([...packumentsToPrewarm], 8, async (name) => { - try { await fetchPackument(name); } catch { /* loop will handle missing packuments */ } + try { await fetchPackument(name); } catch { + packumentFailures.add(name); + log("Packument pre-warm failed", { package: name }); + } }); } } @@ -568,8 +575,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 +605,7 @@ export async function scanPackages( { offline }, ); } catch (error) { + chainResolutionFailureCount += 1; log("Chain resolution failed", { package: finding.pkg.name, version: finding.pkg.version, @@ -633,7 +643,19 @@ export async function scanPackages( unknown: severityCounts.unknown, }); - return findings; + const diagnostics = buildCompletenessDiagnostics({ + transientDetailIds, + offlineMissingDetailIds, + packumentFailures, + remediationFailures, + chainResolutionFailureCount, + }); + const completeness: ScanCompleteness = { + complete: diagnostics.length === 0, + diagnostics, + }; + + return { findings, completeness }; } catch (error) { spinner.fail("Scan failed"); throw error; @@ -847,6 +869,69 @@ function findFirstFixedVersion(vulns: OsvVuln[]): string | null { return fixedVersions.sort(compareVersions)[0]; } +function buildCompletenessDiagnostics(params: { + transientDetailIds: Set; + offlineMissingDetailIds: Set; + packumentFailures: Set; + remediationFailures: Map; + chainResolutionFailureCount: number; +}): ScanDiagnostic[] { + const diagnostics: ScanDiagnostic[] = []; + + if (params.transientDetailIds.size > 0) { + diagnostics.push({ + code: "OSV_DETAIL_TRANSIENT_FAILURE", + severity: "warning", + message: `${params.transientDetailIds.size} advisory detail ${pluralize(params.transientDetailIds.size, "lookup")} failed with a transient error — re-run to retry.`, + impact: "detection", + count: params.transientDetailIds.size, + }); + } + + if (params.offlineMissingDetailIds.size > 0) { + diagnostics.push({ + code: "OSV_DETAIL_OFFLINE_MISSING", + severity: "warning", + message: `${params.offlineMissingDetailIds.size} advisory detail ${pluralize(params.offlineMissingDetailIds.size, "record")} ${pluralize(params.offlineMissingDetailIds.size, "is", "are")} missing from the local advisory database — refresh to sync.`, + impact: "detection", + count: params.offlineMissingDetailIds.size, + }); + } + + if (params.packumentFailures.size > 0) { + diagnostics.push({ + code: "PACKUMENT_FETCH_FAILURE", + severity: "warning", + message: `${params.packumentFailures.size} packument ${pluralize(params.packumentFailures.size, "fetch")} failed — transitive remediation may be incomplete.`, + impact: "remediation", + count: params.packumentFailures.size, + }); + } + + if (params.remediationFailures.size > 0) { + const total = [...params.remediationFailures.values()].reduce((sum, c) => sum + c, 0); + diagnostics.push({ + code: "REMEDIATION_FAILURE", + severity: "warning", + message: `${total} transitive remediation ${pluralize(total, "attempt")} failed — some fix recommendations may be missing.`, + impact: "remediation", + count: total, + }); + } + + if (params.chainResolutionFailureCount > 0) { + diagnostics.push({ + code: "CHAIN_RESOLUTION_FAILURE", + severity: "warning", + message: `${params.chainResolutionFailureCount} chain resolution ${pluralize(params.chainResolutionFailureCount, "attempt")} failed — some validated upgrade chains may be missing.`, + impact: "remediation", + count: params.chainResolutionFailureCount, + }); + } + + return diagnostics; +} + 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..96ef9e35 100644 --- a/src/types.ts +++ b/src/types.ts @@ -200,6 +200,26 @@ export type Baseline = { findings: BaselineEntry[]; }; +export type ScanDiagnosticCode = + | "OSV_DETAIL_TRANSIENT_FAILURE" + | "OSV_DETAIL_OFFLINE_MISSING" + | "PACKUMENT_FETCH_FAILURE" + | "REMEDIATION_FAILURE" + | "CHAIN_RESOLUTION_FAILURE"; + +export type ScanDiagnostic = { + code: ScanDiagnosticCode; + severity: "warning" | "error"; + message: string; + impact: "detection" | "remediation"; + count: 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..eace47ba 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(); @@ -225,7 +226,7 @@ function setupFixModeWithNpmDirectTarget() { packages: [multerDirectFixFinding.pkg], }), ); - scanPackagesMock.mockResolvedValue([multerDirectFixFinding]); + scanPackagesMock.mockResolvedValue({ findings: [multerDirectFixFinding], completeness: emptyCompleteness }); buildSuggestedFixCommandPlanMock.mockReturnValue(npmFixPlan); } @@ -292,7 +293,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", @@ -479,7 +480,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 +647,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 +863,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 +1016,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 +1066,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..f65e26f5 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"); diff --git a/tests/output.test.ts b/tests/output.test.ts index 4f151753..6731ba23 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -25,6 +25,7 @@ import { printActionSummary, printCompactOutput, printFinalStatus, + printIncompleteWarning, printOverrideHint, printSuggestedFixCommands, printSuggestedFixCommandSkips, @@ -2733,3 +2734,44 @@ describe("printSuggestedFixCommands - cooldown warning", () => { expect(output).not.toContain("release cooldown"); }); }); + +describe("printIncompleteWarning", () => { + it("prints nothing when completeness is undefined", () => { + const lines = captureLogs(() => { + printIncompleteWarning(undefined); + }); + expect(lines.join("\n")).not.toContain("Scan data is incomplete"); + }); + + it("prints nothing for a complete scan", () => { + const lines = captureLogs(() => { + printIncompleteWarning({ complete: true, diagnostics: [] }); + }); + expect(lines.join("\n")).not.toContain("Scan data is incomplete"); + }); + + it("prints a warning banner for an incomplete scan", () => { + const lines = captureLogs(() => { + printIncompleteWarning({ + 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).toContain("Scan data is incomplete"); + expect(output).toContain("3 lookups failed"); + expect(output).toContain("1 packument fetch failed"); + expect(output).toContain("Re-run the scan to get a complete result."); + }); + + it("does not print for a complete scan with empty diagnostics", () => { + const lines = captureLogs(() => { + printIncompleteWarning({ complete: true, diagnostics: [] }); + }); + const output = lines.join("\n"); + expect(output).toBe(""); + }); +}); diff --git a/tests/scanner-cache.test.ts b/tests/scanner-cache.test.ts index 57ef1d6f..735f2272 100644 --- a/tests/scanner-cache.test.ts +++ b/tests/scanner-cache.test.ts @@ -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,7 +145,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]?.vulnerabilities).toEqual([]); @@ -246,7 +246,7 @@ describe("scanPackages cache behavior", () => { }); try { - const findings = await scanPackages( + const { findings } = await scanPackages( [mochaPkg, transitivePkg], 100, { @@ -302,7 +302,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 +365,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 +400,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 +433,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 +489,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 +515,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 +551,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 +618,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 +789,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 +829,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 +860,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 +889,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 +917,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 +946,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 +973,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 +1003,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 { @@ -1032,7 +1032,7 @@ 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)); + const { findings: firstFindings } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(firstFindings).toHaveLength(1); expect(firstFindings[0]?.vulnerabilities).toEqual([]); expect(firstFindings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-404-MISSING"]); @@ -1040,7 +1040,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(getVulnMock).not.toHaveBeenCalled(); expect(secondFindings[0]?.vulnerabilities).toEqual([]); expect(secondFindings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-404-MISSING"]); @@ -1074,7 +1074,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 +1127,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,7 +1182,7 @@ describe("scanPackages cache behavior", () => { const debugLog = jest.fn(); try { - const findings = await scanPackages([pkgA, pkgC], 100, createOptions(cacheDir), { + const { findings } = await scanPackages([pkgA, pkgC], 100, createOptions(cacheDir), { directDependencyNames: new Set(["pkg-a"]), }, debugLog); @@ -1246,7 +1246,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, }); @@ -1290,7 +1290,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, diff --git a/tests/write-outputs.test.ts b/tests/write-outputs.test.ts index 95361bd6..9664d9ec 100644 --- a/tests/write-outputs.test.ts +++ b/tests/write-outputs.test.ts @@ -142,13 +142,50 @@ describe("writeOutputs", () => { const [,, planArg, metaArg] = writeCycloneDxReportMock.mock.calls[0] as any[]; expect(metaArg).toBeNull(); }); + }); - it("passes null projectMeta when package.json has no name field", async () => { - existsSyncMock.mockReturnValueOnce(true); - readFileSyncMock.mockReturnValueOnce(JSON.stringify({ version: "1.0.0" })); - await writeOutputs(makeOptions({ cdx: true }), mockScanState, mockScanInput, "/project"); - const [,, planArg, metaArg] = writeCycloneDxReportMock.mock.calls[0] as any[]; - 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" }), + ]); }); }); }); From 46a4ca4652f7c9ab0bcff290d05d718a1367f68d Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 11:48:37 +0800 Subject: [PATCH 02/25] fix(scanner,output,multi-folder-scan): fix completeness propagation and reporting - Pass completeness to writeOutputs call site so JSON output receives real scan completeness instead of always reporting ok/complete - Add onTransientFailure callback to fetchPackument so scanner can track packument failures that were previously silently caught - Add completeness field to MultiFolderScanResult and propagate through multi-folder printer, JSON output, and HTML reports - Add aggregateMultiFolderCompleteness to deduplicate diagnostics across subfolders when aggregating counts - Fix compact mode zero-findings early return that skipped the incomplete scan warning - Differentiate HTML completeness banner text by diagnostic impact: detection failures vs remediation-only failures - Fix HTML banner diagRows join using literal backslash-n - Make ScanState.completeness required to prevent silent downgrades --- src/index.ts | 1 + src/output/html-reporter.ts | 16 ++++++++++++++-- src/output/multi-folder-printer.ts | 4 ++-- src/output/printers.ts | 7 ++++++- src/output/write-outputs.ts | 8 ++++---- src/remediation/npm-registry.ts | 7 ++++++- src/scan/multi-folder-scan.ts | 28 ++++++++++++++++++++++++++-- src/scanner.ts | 8 ++++---- tests/write-outputs.test.ts | 1 + 9 files changed, 64 insertions(+), 16 deletions(-) diff --git a/src/index.ts b/src/index.ts index 362e9489..3204738e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -666,6 +666,7 @@ if (parsedArgs) { coverage: scanState.coverage, minSeverity: scanState.minSeverity, tableFindings: scanState.tableFindings, + completeness: scanState.completeness, overrideFindings, maintenanceFindings, }, scanInput, projectPath); diff --git a/src/output/html-reporter.ts b/src/output/html-reporter.ts index 042775b7..0906e509 100644 --- a/src/output/html-reporter.ts +++ b/src/output/html-reporter.ts @@ -635,15 +635,27 @@ function renderTransitiveContextCol(finding: SerializedFinding): string { function renderCompletenessBanner(data: ReportData): string { if (data.completeness == null || data.completeness.complete) return ""; + const hasDetectionFailure = data.completeness.diagnostics.some(d => d.impact === "detection"); + const hasRemediationFailure = data.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 = data.completeness.diagnostics.map(d => `
  • ${escapeHtml(d.message)}
    • ` - ).join("\\n"); + ).join("\n"); return `
    ⚠
    Scan data is incomplete -

    The scan result may be missing some findings because the following issues occurred:

    +

    ${bannerText}

      ${diagRows}
    `; 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 ce01a2fd..5a69a434 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -425,7 +425,12 @@ export function printCompactOutput( } if (findings.length === 0) { - console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found.")); + if (options?.completeness?.complete === false) { + console.log(chalk.yellow("⚠ No known vulnerabilities were resolved, but scan data is incomplete.")); + printIncompleteWarning(options.completeness); + } else { + console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found.")); + } console.log(""); return; } diff --git a/src/output/write-outputs.ts b/src/output/write-outputs.ts index f2abc99e..953f0e1f 100644 --- a/src/output/write-outputs.ts +++ b/src/output/write-outputs.ts @@ -19,7 +19,7 @@ export type ScanState = { coverage: string[]; minSeverity: string; tableFindings: Finding[]; - completeness?: ScanCompleteness; + completeness: ScanCompleteness; }; function readProjectMeta(projectPath: string): ProjectMeta { @@ -59,9 +59,9 @@ export async function writeOutputs( source: scanInput.source, packageCount: scanInput.packages.length, findingCount: scanState.sorted.length, - status: scanState.completeness?.complete !== false ? "ok" : "partial", - complete: scanState.completeness?.complete ?? true, - diagnostics: scanState.completeness?.diagnostics ?? [], + 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..1d25f24d 100644 --- a/src/remediation/npm-registry.ts +++ b/src/remediation/npm-registry.ts @@ -42,7 +42,10 @@ export function clearPackumentCache(): void { packumentCache.clear(); } -export async function fetchPackument(packageName: string): Promise { +export async function fetchPackument( + packageName: string, + onTransientFailure?: (packageName: string) => void, +): Promise { const cached = packumentCache.get(packageName); if (cached) return cached; @@ -74,6 +77,7 @@ export async function fetchPackument(packageName: string): Promise r.completeness?.diagnostics ?? []).map((d, _i, arr) => { + const sameCode = arr.filter(x => x.code === d.code); + if (sameCode.length > 1) { + const total = sameCode.reduce((sum, x) => sum + x.count, 0); + return { ...d, count: total, message: d.message.replace(/\d+/, String(total)) }; + } + return d; + }); + const seen = new Set(); + const deduped = allDiagnostics.filter(d => { + const key = d.code; + if (seen.has(key)) return false; + seen.add(key); + return true; + }); + return { complete: deduped.length === 0, diagnostics: deduped }; +} + export async function handleMultiFolderScan(params: { projectRoot: string; batchSize: number; @@ -138,6 +161,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 926c5e70..e6192957 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -480,10 +480,10 @@ export async function scanPackages( } if (packumentsToPrewarm.size > 0) { await runWithConcurrency([...packumentsToPrewarm], 8, async (name) => { - try { await fetchPackument(name); } catch { - packumentFailures.add(name); - log("Packument pre-warm failed", { package: name }); - } + await fetchPackument(name, (pkg) => { + packumentFailures.add(pkg); + log("Packument pre-warm failed", { package: pkg }); + }); }); } } diff --git a/tests/write-outputs.test.ts b/tests/write-outputs.test.ts index 9664d9ec..41d6d9c5 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 = { From a95e270f6b835476a3ef985f73d610c1a8e848be Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 12:20:14 +0800 Subject: [PATCH 03/25] fix(scanner,output,html): propagate packument failure tracking through all paths - Pass onTransientFailure callback through resolvePublishedFixVersion, resolveLowestKnownNonVulnerableVersion, validateDirectFixTargets, and resolveChainFix so direct-only scans also track registry failures - Fix printFinalStatus zero-findings path to show incomplete warning instead of conflicting green success when scan data is incomplete - Export renderCompletenessBanner and add per-folder + aggregate completeness banners to multi-folder HTML reports - Update footer text from 'Re-run the scan' to 'Resolve the issues above and re-run the scan' --- src/output/html-reporter.ts | 12 ++++----- src/output/multi-folder-html-reporter.ts | 27 +++++++++++++++++++- src/output/printers.ts | 6 +++-- src/remediation/npm-registry.ts | 10 +++++--- src/remediation/transitive-chain-resolver.ts | 11 +++++--- src/scanner.ts | 11 +++++--- tests/output.test.ts | 2 +- 7 files changed, 58 insertions(+), 21 deletions(-) diff --git a/src/output/html-reporter.ts b/src/output/html-reporter.ts index 0906e509..9c7f6c1f 100644 --- a/src/output/html-reporter.ts +++ b/src/output/html-reporter.ts @@ -254,7 +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); + const completenessBannerHtml = renderCompletenessBanner(data.completeness); const fixPlanHtml = renderFixPlan(data.suggestedFixCommands); const skippedKeys = new Set( (data.suggestedFixCommands?.skipped ?? []).map(s => `${s.package}@${s.version}`) @@ -632,11 +632,11 @@ function renderTransitiveContextCol(finding: SerializedFinding): string { `; } -function renderCompletenessBanner(data: ReportData): string { - if (data.completeness == null || data.completeness.complete) return ""; +export function renderCompletenessBanner(completeness: ScanCompleteness | null | undefined): string { + if (completeness == null || completeness.complete) return ""; - const hasDetectionFailure = data.completeness.diagnostics.some(d => d.impact === "detection"); - const hasRemediationFailure = data.completeness.diagnostics.some(d => d.impact === "remediation"); + const hasDetectionFailure = completeness.diagnostics.some(d => d.impact === "detection"); + const hasRemediationFailure = completeness.diagnostics.some(d => d.impact === "remediation"); let bannerText: string; if (hasDetectionFailure) { @@ -647,7 +647,7 @@ function renderCompletenessBanner(data: ReportData): string { bannerText = "The scan result may be incomplete because the following issues occurred:"; } - const diagRows = data.completeness.diagnostics.map(d => + const diagRows = completeness.diagnostics.map(d => `
  • ${escapeHtml(d.message)}
    • ` ).join("\n"); diff --git a/src/output/multi-folder-html-reporter.ts b/src/output/multi-folder-html-reporter.ts index c07655cd..f236528d 100644 --- a/src/output/multi-folder-html-reporter.ts +++ b/src/output/multi-folder-html-reporter.ts @@ -7,12 +7,13 @@ import { openInBrowser, renderFindingRow, renderFixPlan, + renderCompletenessBanner, serializeHtmlFinding, } from "./html-reporter.js"; import type { SerializedFinding } from "./html-reporter.js"; import { loadLogoDataUri } from "./logos.js"; import { pluralize } from "../utils/string.js"; -import type { SeverityLabel } from "../types.js"; +import type { SeverityLabel, ScanCompleteness } from "../types.js"; type SevCounts = Record; @@ -59,6 +60,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 +73,7 @@ function renderFolderSection( ${escapeHtml(summaryText)}
    + ${completenessBannerHtml} ${fixPlanHtml} ${noticesHtml}
    @@ -127,6 +130,26 @@ export async function writeMultiFolderHtmlReport(params: { ); const folderCount = params.results.length; + const aggregateCompleteness = params.results + .reduce( + (acc, r) => { + if (r.completeness && !r.completeness.complete) { + acc.complete = false; + for (const d of r.completeness.diagnostics) { + const existing = acc.diagnostics.find(x => x.code === d.code); + if (existing) { + existing.count += d.count; + } else { + acc.diagnostics.push({ ...d }); + } + } + } + return acc; + }, + { complete: true, diagnostics: [] }, + ); + 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 +244,8 @@ details[open] .folder-summary::before{transform:rotate(90deg)}
    ${totalCVEs}CVEs
    +${aggregateBannerHtml} + ${folderSectionsHtml}
    diff --git a/src/output/printers.ts b/src/output/printers.ts index 5a69a434..78aa65a5 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -329,7 +329,9 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0, complet : ""; if (findings.length === 0) { - if (overrideCount > 0) { + if (completeness?.complete === false) { + 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.")); @@ -637,7 +639,7 @@ export function printIncompleteWarning(completeness?: ScanCompleteness): void { const prefix = diag.impact === "detection" ? chalk.yellow(" ·") : chalk.gray(" ·"); console.log(prefix + " " + chalk.gray(diag.message)); } - console.log(chalk.gray(" Re-run the scan to get a complete result.")); + 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/remediation/npm-registry.ts b/src/remediation/npm-registry.ts index 1d25f24d..afbe2b94 100644 --- a/src/remediation/npm-registry.ts +++ b/src/remediation/npm-registry.ts @@ -117,8 +117,8 @@ export async function fetchPackument( return promise; } -export async function packageVersionExists(packageName: string, version: string): Promise { - const packument = await fetchPackument(packageName); +export async function packageVersionExists(packageName: string, version: string, onTransientFailure?: (packageName: string) => void): Promise { + const packument = await fetchPackument(packageName, onTransientFailure); if (!packument) return null; return Boolean(packument.versions && version in packument.versions); } @@ -126,8 +126,9 @@ export async function packageVersionExists(packageName: string, version: string) export async function resolvePublishedFixVersion( packageName: string, fixedVersionHint: string, + onTransientFailure?: (packageName: string) => void, ): Promise { - const packument = await fetchPackument(packageName); + const packument = await fetchPackument(packageName, onTransientFailure); if (!packument) { return { resolvedVersion: null, @@ -184,6 +185,7 @@ export async function resolveLowestKnownNonVulnerableVersion( packageName: string, installedVersion: string, vulnerabilities: OsvVuln[], + onTransientFailure?: (packageName: string) => void, ): Promise { if (!looksLikeVersion(installedVersion)) { return { @@ -209,7 +211,7 @@ export async function resolveLowestKnownNonVulnerableVersion( }; } - const packument = await fetchPackument(packageName); + const packument = await fetchPackument(packageName, onTransientFailure); if (!packument) { return { resolvedVersion: null, diff --git a/src/remediation/transitive-chain-resolver.ts b/src/remediation/transitive-chain-resolver.ts index 7d87e4e5..b4e32105 100644 --- a/src/remediation/transitive-chain-resolver.ts +++ b/src/remediation/transitive-chain-resolver.ts @@ -10,6 +10,7 @@ export async function resolveChainFix( installedVersions: Map, packageManager: SuggestedFixPackageManager, options: { offline: boolean }, + onTransientFailure?: (packageName: string) => void, ): Promise { if (options.offline) return null; if (finding.relationship !== "transitive") return null; @@ -27,7 +28,7 @@ export async function resolveChainFix( const directDepCurrentVersion = installedVersions.get(directDepName); if (!directDepCurrentVersion) continue; - const packument = await fetchPackument(directDepName); + const packument = await fetchPackument(directDepName, onTransientFailure); if (!packument?.versions) continue; const candidateVersions = Object.keys(packument.versions) @@ -51,6 +52,7 @@ export async function resolveChainFix( hops, finding.pkg.version, fixedVersion, + onTransientFailure, ); if (!traced) continue; @@ -75,6 +77,7 @@ async function traceChain( remainingPath: string[], vulnerableInstalledVersion: string, fixedVersion: string, + onTransientFailure?: (packageName: string) => void, ): Promise<{ chain: ChainHop[]; safeVersion: string } | null> { if (remainingPath.length === 0) return null; @@ -90,7 +93,7 @@ async function traceChain( return null; } // Range excludes the vulnerable version - find the highest safe published version. - const packument = await fetchPackument(nextName); + const packument = await fetchPackument(nextName, onTransientFailure); if (!packument?.versions) return null; const candidates = Object.keys(packument.versions) @@ -106,7 +109,7 @@ async function traceChain( } // Intermediate hop: resolve the highest version of nextName within range, then recurse. - const packument = await fetchPackument(nextName); + const packument = await fetchPackument(nextName, onTransientFailure); if (!packument?.versions) return null; const candidates = Object.keys(packument.versions) @@ -118,7 +121,7 @@ async function traceChain( if (!resolvedVersion) return null; const nextDeps = packument.versions[resolvedVersion]?.dependencies ?? {}; - const result = await traceChain(nextDeps, remainingPath.slice(1), vulnerableInstalledVersion, fixedVersion); + const result = await traceChain(nextDeps, remainingPath.slice(1), vulnerableInstalledVersion, fixedVersion, onTransientFailure); if (!result) return null; return { diff --git a/src/scanner.ts b/src/scanner.ts index e6192957..e09d45b8 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -459,7 +459,7 @@ export async function scanPackages( if (!offline) { const npmVersionCacheUpdated = await validateDirectFixTargets(findings, (finding) => { updateAnalysisProgress("validating fix target for", `${finding.pkg.name}@${finding.pkg.version}`); - }, { cache, noCache: options.noCache, debugLog: log }); + }, { cache, noCache: options.noCache, debugLog: log, onTransientFailure: (pkg) => packumentFailures.add(pkg) }); if (npmVersionCacheUpdated) { saveCache(cache, cacheDirOverride, options.debug ? log : undefined); } @@ -603,6 +603,7 @@ export async function scanPackages( installedVersions, chainPm, { offline }, + (pkg) => packumentFailures.add(pkg), ); } catch (error) { chainResolutionFailureCount += 1; @@ -625,6 +626,7 @@ export async function scanPackages( cache, noCache: options.noCache, debugLog: log, + onTransientFailure: (pkg) => packumentFailures.add(pkg), }); if (npmVersionCacheUpdated) { saveCache(cache, cacheDirOverride, options.debug ? log : undefined); @@ -705,6 +707,7 @@ async function validateDirectFixTargets( cache: ReturnType; noCache?: boolean; debugLog?: DebugLogger; + onTransientFailure?: (packageName: string) => void; }, ): Promise { const directCandidates = findings.filter(finding => finding.vulnerabilities.length > 0); @@ -727,6 +730,7 @@ async function validateOneDirectFixTarget( cache: ReturnType; noCache?: boolean; debugLog?: DebugLogger; + onTransientFailure?: (packageName: string) => void; }, ): Promise { let npmVersionCacheUpdated = false; @@ -743,6 +747,7 @@ async function validateOneDirectFixTarget( finding.pkg.name, finding.pkg.version, finding.vulnerabilities, + options?.onTransientFailure, ); const fixedVersionHint = finding.firstFixedVersion; @@ -777,7 +782,7 @@ async function validateOneDirectFixTarget( return npmVersionCacheUpdated; } - const hintResolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint); + const hintResolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint, options?.onTransientFailure); if ( hintResolution.resolvedVersion === lowestKnownResolution.resolvedVersion && hintResolution.note @@ -806,7 +811,7 @@ async function validateOneDirectFixTarget( return npmVersionCacheUpdated; } - const resolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint); + const resolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint, options?.onTransientFailure); finding.validatedFirstFixedVersion = resolution.resolvedVersion; finding.fixVersionValidationNote = resolution.note ?? lowestKnownResolution.note; finding.validatedTargetScannedVersions = null; diff --git a/tests/output.test.ts b/tests/output.test.ts index 6731ba23..9a278812 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -2764,7 +2764,7 @@ describe("printIncompleteWarning", () => { expect(output).toContain("Scan data is incomplete"); expect(output).toContain("3 lookups failed"); expect(output).toContain("1 packument fetch failed"); - expect(output).toContain("Re-run the scan to get a complete result."); + expect(output).toContain("Resolve the issues above and re-run the scan."); }); it("does not print for a complete scan with empty diagnostics", () => { From 22f4105ebdc0ed803f52eedae52ef85c92dff0d1 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 12:39:36 +0800 Subject: [PATCH 04/25] fix(scanner,npm-registry,output): use observer pattern for unified packument tracking - Add module-level RegistryFetchObserver with onTransientFailure and onSuccess callbacks, set by scanner via setRegistryFetchObserver - All fetchPackument calls through any remediation path now automatically track transient failures and clear on retry success - Remove duplicate inline completeness aggregation in HTML reporter; use shared aggregateMultiFolderCompleteness from multi-folder-scan - Fix aggregateMultiFolderCompleteness to update message text when merging diagnostic counts - Fix verbose mode printFinalStatus to show 'Partial scan:' prefix instead of conflicting 'Scan complete' when data is incomplete --- src/output/multi-folder-html-reporter.ts | 22 +++------------- src/output/printers.ts | 10 ++++++-- src/remediation/npm-registry.ts | 14 +++++++++++ src/scan/multi-folder-scan.ts | 32 +++++++++++------------- src/scanner.ts | 7 ++++++ 5 files changed, 47 insertions(+), 38 deletions(-) diff --git a/src/output/multi-folder-html-reporter.ts b/src/output/multi-folder-html-reporter.ts index f236528d..e4b45e71 100644 --- a/src/output/multi-folder-html-reporter.ts +++ b/src/output/multi-folder-html-reporter.ts @@ -1,6 +1,7 @@ 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, @@ -13,7 +14,7 @@ import { import type { SerializedFinding } from "./html-reporter.js"; import { loadLogoDataUri } from "./logos.js"; import { pluralize } from "../utils/string.js"; -import type { SeverityLabel, ScanCompleteness } from "../types.js"; +import type { SeverityLabel } from "../types.js"; type SevCounts = Record; @@ -130,24 +131,7 @@ export async function writeMultiFolderHtmlReport(params: { ); const folderCount = params.results.length; - const aggregateCompleteness = params.results - .reduce( - (acc, r) => { - if (r.completeness && !r.completeness.complete) { - acc.complete = false; - for (const d of r.completeness.diagnostics) { - const existing = acc.diagnostics.find(x => x.code === d.code); - if (existing) { - existing.count += d.count; - } else { - acc.diagnostics.push({ ...d }); - } - } - } - return acc; - }, - { complete: true, diagnostics: [] }, - ); + const aggregateCompleteness = aggregateMultiFolderCompleteness(params.results); const aggregateBannerHtml = renderCompletenessBanner(aggregateCompleteness); // Pre-serialize findings once per folder for both HTML rendering and JS filter/sort diff --git a/src/output/printers.ts b/src/output/printers.ts index 78aa65a5..8e005ed4 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -340,16 +340,22 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0, complet const criticalCount = findings.filter(f => f.severity === "critical").length; const highCount = findings.filter(f => f.severity === "high").length; + const incomplete = completeness?.complete === false; + 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.` + incomplete + ? `⚠ Partial scan: ${findings.length} ${pluralize(findings.length, "vulnerability")} resolved${overrideSuffix} (${criticalCount} critical, ${highCount} high). Start with the priority fixes above.` + : `✖ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${overrideSuffix} found (${criticalCount} critical, ${highCount} high). Start with the priority fixes above.` ) ); } else { console.log( chalk.yellow( - `▲ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${overrideSuffix} found. Review the suggested fix plan above.` + incomplete + ? `⚠ Partial scan: ${findings.length} ${pluralize(findings.length, "vulnerability")} resolved${overrideSuffix}. Review the suggested fix plan above.` + : `▲ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${overrideSuffix} found. Review the suggested fix plan above.` ) ); } diff --git a/src/remediation/npm-registry.ts b/src/remediation/npm-registry.ts index afbe2b94..9ec8028a 100644 --- a/src/remediation/npm-registry.ts +++ b/src/remediation/npm-registry.ts @@ -38,6 +38,17 @@ function nextRegistryBatchId(): string { return `r-${String(registryBatchCounter).padStart(2, "0")}`; } +export type RegistryFetchObserver = { + onTransientFailure?: (name: string) => void; + onSuccess?: (name: string) => void; +}; + +let currentObserver: RegistryFetchObserver | null = null; + +export function setRegistryFetchObserver(observer: RegistryFetchObserver | null): void { + currentObserver = observer; +} + export function clearPackumentCache(): void { packumentCache.clear(); } @@ -77,11 +88,13 @@ export async function fetchPackument( return null; } transientFailure = true; + currentObserver?.onTransientFailure?.(packageName); onTransientFailure?.(packageName); return null; } const json = (await response.json()) as Packument; + currentObserver?.onSuccess?.(packageName); if (registryDebugLog) { registryDebugLog("Registry response", { batchId, @@ -94,6 +107,7 @@ export async function fetchPackument( return json; } catch (error) { transientFailure = true; + currentObserver?.onTransientFailure?.(packageName); onTransientFailure?.(packageName); if (registryDebugLog) { registryDebugLog("Registry fetch failed", { diff --git a/src/scan/multi-folder-scan.ts b/src/scan/multi-folder-scan.ts index 8bfa276b..0134e7df 100644 --- a/src/scan/multi-folder-scan.ts +++ b/src/scan/multi-folder-scan.ts @@ -1,6 +1,6 @@ import path from "node:path"; import process from "node:process"; -import type { Finding, ParsedOptions, PackageRef, SeverityLabel, ExitCode, ScanCompleteness } 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"; @@ -108,25 +108,23 @@ export async function runMultiFolderScan(params: { return results; } -function aggregateMultiFolderCompleteness( +export function aggregateMultiFolderCompleteness( results: MultiFolderScanResult[], ): ScanCompleteness { - const allDiagnostics = results.flatMap(r => r.completeness?.diagnostics ?? []).map((d, _i, arr) => { - const sameCode = arr.filter(x => x.code === d.code); - if (sameCode.length > 1) { - const total = sameCode.reduce((sum, x) => sum + x.count, 0); - return { ...d, count: total, message: d.message.replace(/\d+/, String(total)) }; + 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; + existing.message = existing.message.replace(/\d+/, String(existing.count)); + } else { + deduped.set(d.code, { ...d }); + } } - return d; - }); - const seen = new Set(); - const deduped = allDiagnostics.filter(d => { - const key = d.code; - if (seen.has(key)) return false; - seen.add(key); - return true; - }); - return { complete: deduped.length === 0, diagnostics: deduped }; + } + return { complete: deduped.size === 0, diagnostics: [...deduped.values()] }; } export async function handleMultiFolderScan(params: { diff --git a/src/scanner.ts b/src/scanner.ts index e09d45b8..25cc7191 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -17,6 +17,7 @@ import { fetchPackument, resolveLowestKnownNonVulnerableVersion, resolvePublishedFixVersion, + setRegistryFetchObserver, } from "./remediation/npm-registry.js"; import { countBySeverity } from "./utils/severity.js"; import { resolveNpmTransitiveRemediation, resolveTransitiveRemediationViaRegistry } from "./remediation/npm-transitive-resolution.js"; @@ -432,6 +433,11 @@ export async function scanPackages( const remediationFailures = new Map(); let chainResolutionFailureCount = 0; + setRegistryFetchObserver({ + onTransientFailure(name) { packumentFailures.add(name); }, + onSuccess(name) { packumentFailures.delete(name); }, + }); + const npmRemediationCache = new Map(); const parentUpgradeCache = new Map(); const directValidationCount = offline ? 0 : findings.length; @@ -662,6 +668,7 @@ export async function scanPackages( spinner.fail("Scan failed"); throw error; } finally { + setRegistryFetchObserver(null); sourceContext.cleanup(); } } From 3928786449f46c983b063b120448fa67326aa712 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 15:14:26 +0800 Subject: [PATCH 05/25] fix(npm-registry,multi-folder-scan): call onResolved on 404 too, use formatDiagnosticMessage - Rename onSuccess to onResolved in RegistryFetchObserver and call it on 404 responses too, so transient-failure-then-404 retries clear old failure entries - Export formatDiagnosticMessage from scanner and use it in aggregateMultiFolderCompleteness instead of regex replacement for correct pluralization in merged diagnostic messages test: add observer retry tests and multi-folder aggregation tests --- src/remediation/npm-registry.ts | 5 ++- src/scan/multi-folder-scan.ts | 4 +- src/scanner.ts | 21 ++++++++- tests/multi-folder-scan.test.ts | 61 +++++++++++++++++++++++++ tests/scanner-cache.test.ts | 79 +++++++++++++++++++++++++++++++++ 5 files changed, 164 insertions(+), 6 deletions(-) diff --git a/src/remediation/npm-registry.ts b/src/remediation/npm-registry.ts index 9ec8028a..e4526860 100644 --- a/src/remediation/npm-registry.ts +++ b/src/remediation/npm-registry.ts @@ -40,7 +40,7 @@ function nextRegistryBatchId(): string { export type RegistryFetchObserver = { onTransientFailure?: (name: string) => void; - onSuccess?: (name: string) => void; + onResolved?: (name: string) => void; }; let currentObserver: RegistryFetchObserver | null = null; @@ -85,6 +85,7 @@ export async function fetchPackument( }); } if (response.status === 404) { + currentObserver?.onResolved?.(packageName); return null; } transientFailure = true; @@ -94,7 +95,7 @@ export async function fetchPackument( } const json = (await response.json()) as Packument; - currentObserver?.onSuccess?.(packageName); + currentObserver?.onResolved?.(packageName); if (registryDebugLog) { registryDebugLog("Registry response", { batchId, diff --git a/src/scan/multi-folder-scan.ts b/src/scan/multi-folder-scan.ts index 0134e7df..1cc09a23 100644 --- a/src/scan/multi-folder-scan.ts +++ b/src/scan/multi-folder-scan.ts @@ -5,7 +5,7 @@ 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"; @@ -118,7 +118,7 @@ export function aggregateMultiFolderCompleteness( const existing = deduped.get(d.code); if (existing) { existing.count += d.count; - existing.message = existing.message.replace(/\d+/, String(existing.count)); + existing.message = formatDiagnosticMessage(d.code, existing.count); } else { deduped.set(d.code, { ...d }); } diff --git a/src/scanner.ts b/src/scanner.ts index 25cc7191..85263970 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -1,4 +1,4 @@ -import type { Finding, NpmTransitiveGraph, OsvVuln, PackageRef, ParsedOptions, ScanCompleteness, ScanDiagnostic, 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"; @@ -435,7 +435,7 @@ export async function scanPackages( setRegistryFetchObserver({ onTransientFailure(name) { packumentFailures.add(name); }, - onSuccess(name) { packumentFailures.delete(name); }, + onResolved(name) { packumentFailures.delete(name); }, }); const npmRemediationCache = new Map(); @@ -944,6 +944,23 @@ function buildCompletenessDiagnostics(params: { return diagnostics; } +export function formatDiagnosticMessage(code: ScanDiagnosticCode, count: 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 "PACKUMENT_FETCH_FAILURE": + return `${count} packument ${pluralize(count, "fetch")} failed — transitive remediation may be incomplete.`; + case "REMEDIATION_FAILURE": + 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/tests/multi-folder-scan.test.ts b/tests/multi-folder-scan.test.ts index f65e26f5..d1dfaafe 100644 --- a/tests/multi-folder-scan.test.ts +++ b/tests/multi-folder-scan.test.ts @@ -20,6 +20,18 @@ jest.unstable_mockModule("../src/parsers/multi-package.js", () => ({ jest.unstable_mockModule("../src/scanner.js", () => ({ scanPackages: scanPackagesMock, buildCoverageNotes: buildCoverageNotesMock, + formatDiagnosticMessage: (code: string, count: 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"; + return `${count} ${plural} failed — re-run to retry.`; + }, })); jest.unstable_mockModule("../src/output/formatters.js", () => ({ @@ -451,3 +463,52 @@ 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 — transitive remediation 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 — transitive remediation 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."); + }); +}); diff --git a/tests/scanner-cache.test.ts b/tests/scanner-cache.test.ts index 735f2272..a9a31cda 100644 --- a/tests/scanner-cache.test.ts +++ b/tests/scanner-cache.test.ts @@ -1303,4 +1303,83 @@ describe("scanPackages cache behavior", () => { removeDir(tempDir); } }); + + describe("registry fetch observer", () => { + let cacheDir: string; + let dbPath: string; + + beforeEach(async () => { + cacheDir = createTempCacheDir(); + dbPath = path.join(cacheDir, "cve-advisories.db"); + clearPackumentCache(); + }); + + afterEach(() => { + if (fs.existsSync(cacheDir)) removeDir(cacheDir); + }); + + it("marks completeness as complete after transient failure followed by successful retry", async () => { + const pkg: PackageRef = { name: "observer-retry-ok", version: "1.0.0", ecosystem: "npm", paths: [["root", "observer-retry-ok"]] }; + + const db = new LocalAdvisoryDatabase(dbPath); + db.upsertVulnerability({ + id: "OSV-OBSERVER-RETRY", + aliases: ["CVE-2026-OBR"], + affected: [{ package: { ecosystem: "npm", name: "observer-retry-ok" }, ranges: [{ events: [{ introduced: "0" }, { fixed: "2.0.0" }] }] }], + }); + db.close(); + + queryBatchMock.mockResolvedValue({ + vulns: { find: [{ id: "OSV-OBSERVER-RETRY" }], "observer-retry-ok": [{ id: "OSV-OBSERVER-RETRY" }] }, + aliases: [], + details: [{ id: "OSV-OBSERVER-RETRY", aliases: ["CVE-2026-OBR"], affected: [{ package: { ecosystem: "npm", name: "observer-retry-ok" }, ranges: [{ events: [{ introduced: "0" }, { fixed: "2.0.0" }] }] }] }], + }); + + let callCount = 0; + fetchMock.mockImplementation(async () => { + callCount++; + if (callCount === 1) throw new Error("timeout"); + return { ok: true, json: async () => ({ versions: { "2.0.0": {} } }) }; + }); + + const { completeness } = await scanPackages([pkg], 100, createOptions(cacheDir), { + directDependencyNames: new Set(["observer-retry-ok"]), + }); + + expect(completeness.complete).toBe(true); + expect(completeness.diagnostics).toEqual([]); + }); + + it("marks completeness as complete after transient failure followed by 404 on retry", async () => { + const pkg: PackageRef = { name: "observer-retry-404", version: "1.0.0", ecosystem: "npm", paths: [["root", "observer-retry-404"]] }; + + const db = new LocalAdvisoryDatabase(dbPath); + db.upsertVulnerability({ + id: "OSV-OBSERVER-404", + aliases: ["CVE-2026-O404"], + affected: [{ package: { ecosystem: "npm", name: "observer-retry-404" }, ranges: [{ events: [{ introduced: "0" }, { fixed: "2.0.0" }] }] }], + }); + db.close(); + + queryBatchMock.mockResolvedValue({ + vulns: { find: [{ id: "OSV-OBSERVER-404" }], "observer-retry-404": [{ id: "OSV-OBSERVER-404" }] }, + aliases: [], + details: [{ id: "OSV-OBSERVER-404", aliases: ["CVE-2026-O404"], affected: [{ package: { ecosystem: "npm", name: "observer-retry-404" }, ranges: [{ events: [{ introduced: "0" }, { fixed: "2.0.0" }] }] }] }], + }); + + let callCount = 0; + fetchMock.mockImplementation(async () => { + callCount++; + if (callCount === 1) throw new Error("timeout"); + return { ok: false, status: 404 }; + }); + + const { completeness } = await scanPackages([pkg], 100, createOptions(cacheDir), { + directDependencyNames: new Set(["observer-retry-404"]), + }); + + expect(completeness.complete).toBe(true); + expect(completeness.diagnostics).toEqual([]); + }); + }); }); From 2f2e37d6b0c4c534b5ecb124a92e9b06dc47b06e Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 15:20:13 +0800 Subject: [PATCH 06/25] refactor(scanner): use formatDiagnosticMessage in buildCompletenessDiagnostics - Replace manual message construction with formatDiagnosticMessage calls so single-folder and multi-folder aggregation share one message source - Update PACKUMENT_FETCH_FAILURE message: 'transitive remediation' -> 'remediation guidance' since it now covers direct fix validation too --- src/scanner.ts | 12 ++++++------ tests/multi-folder-scan.test.ts | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/scanner.ts b/src/scanner.ts index 85263970..1f89ce3d 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -894,7 +894,7 @@ function buildCompletenessDiagnostics(params: { diagnostics.push({ code: "OSV_DETAIL_TRANSIENT_FAILURE", severity: "warning", - message: `${params.transientDetailIds.size} advisory detail ${pluralize(params.transientDetailIds.size, "lookup")} failed with a transient error — re-run to retry.`, + message: formatDiagnosticMessage("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size), impact: "detection", count: params.transientDetailIds.size, }); @@ -904,7 +904,7 @@ function buildCompletenessDiagnostics(params: { diagnostics.push({ code: "OSV_DETAIL_OFFLINE_MISSING", severity: "warning", - message: `${params.offlineMissingDetailIds.size} advisory detail ${pluralize(params.offlineMissingDetailIds.size, "record")} ${pluralize(params.offlineMissingDetailIds.size, "is", "are")} missing from the local advisory database — refresh to sync.`, + message: formatDiagnosticMessage("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size), impact: "detection", count: params.offlineMissingDetailIds.size, }); @@ -914,7 +914,7 @@ function buildCompletenessDiagnostics(params: { diagnostics.push({ code: "PACKUMENT_FETCH_FAILURE", severity: "warning", - message: `${params.packumentFailures.size} packument ${pluralize(params.packumentFailures.size, "fetch")} failed — transitive remediation may be incomplete.`, + message: formatDiagnosticMessage("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size), impact: "remediation", count: params.packumentFailures.size, }); @@ -925,7 +925,7 @@ function buildCompletenessDiagnostics(params: { diagnostics.push({ code: "REMEDIATION_FAILURE", severity: "warning", - message: `${total} transitive remediation ${pluralize(total, "attempt")} failed — some fix recommendations may be missing.`, + message: formatDiagnosticMessage("REMEDIATION_FAILURE", total), impact: "remediation", count: total, }); @@ -935,7 +935,7 @@ function buildCompletenessDiagnostics(params: { diagnostics.push({ code: "CHAIN_RESOLUTION_FAILURE", severity: "warning", - message: `${params.chainResolutionFailureCount} chain resolution ${pluralize(params.chainResolutionFailureCount, "attempt")} failed — some validated upgrade chains may be missing.`, + message: formatDiagnosticMessage("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount), impact: "remediation", count: params.chainResolutionFailureCount, }); @@ -951,7 +951,7 @@ export function formatDiagnosticMessage(code: ScanDiagnosticCode, count: number) 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 "PACKUMENT_FETCH_FAILURE": - return `${count} packument ${pluralize(count, "fetch")} failed — transitive remediation may be incomplete.`; + return `${count} packument ${pluralize(count, "fetch")} failed — remediation guidance may be incomplete.`; case "REMEDIATION_FAILURE": return `${count} transitive remediation ${pluralize(count, "attempt")} failed — some fix recommendations may be missing.`; case "CHAIN_RESOLUTION_FAILURE": diff --git a/tests/multi-folder-scan.test.ts b/tests/multi-folder-scan.test.ts index d1dfaafe..3ea631e2 100644 --- a/tests/multi-folder-scan.test.ts +++ b/tests/multi-folder-scan.test.ts @@ -497,7 +497,7 @@ describe("aggregateMultiFolderCompleteness", () => { { subfolder: "a", completeness: { complete: false, diagnostics: [ - { code: "PACKUMENT_FETCH_FAILURE" as const, severity: "warning" as const, message: "1 packument fetch failed — transitive remediation may be incomplete.", impact: "remediation" as const, count: 1 }, + { 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 }, ] }, }, @@ -508,7 +508,7 @@ describe("aggregateMultiFolderCompleteness", () => { 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 — transitive remediation may be incomplete."); + 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."); }); }); From e45e9effaacd2e4d874147105a2ceb29759799cf Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 15:41:34 +0800 Subject: [PATCH 07/25] refactor: remove callback param threading, compress repetitive code - Remove onTransientFailure callback from fetchPackument and all downstream functions (resolvePublishedFixVersion, resolveLowest..., resolveChainFix, traceChain, validateDirectFixTargets). RegistryFetchObserver handles all tracking now. - Compress buildCompletenessDiagnostics: extract inner push() helper to eliminate five repeated diagnostic-construction blocks. - Simplify printFinalStatus: single 'incomplete' flag drives all three branches, collapsing duplicate conditional branches. --- src/output/printers.ts | 36 +++++----- src/remediation/npm-registry.ts | 13 ++-- src/remediation/transitive-chain-resolver.ts | 11 ++- src/scanner.ts | 71 ++++---------------- 4 files changed, 37 insertions(+), 94 deletions(-) diff --git a/src/output/printers.ts b/src/output/printers.ts index 8e005ed4..068f3564 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -324,12 +324,13 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0, complet 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 (completeness?.complete === false) { + 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.`)); @@ -339,25 +340,22 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0, complet } else { const criticalCount = findings.filter(f => f.severity === "critical").length; const highCount = findings.filter(f => f.severity === "high").length; - - const incomplete = completeness?.complete === false; - - if (criticalCount > 0 || highCount > 0) { - console.log( - chalk.redBright( - incomplete - ? `⚠ Partial scan: ${findings.length} ${pluralize(findings.length, "vulnerability")} resolved${overrideSuffix} (${criticalCount} critical, ${highCount} high). Start with the priority fixes above.` - : `✖ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${overrideSuffix} found (${criticalCount} critical, ${highCount} high). Start with the priority fixes above.` - ) - ); + const urgent = criticalCount > 0 || highCount > 0; + + const label = `${findings.length} ${pluralize(findings.length, "vulnerability")}`; + + if (incomplete) { + console.log(chalk.yellow( + `⚠ Partial scan: ${label} resolved${overrideSuffix}${urgent ? ` (${criticalCount} critical, ${highCount} high)` : ""}. ${urgent ? "Start with the priority fixes above." : "Review the suggested fix plan above."}` + )); + } 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( - incomplete - ? `⚠ Partial scan: ${findings.length} ${pluralize(findings.length, "vulnerability")} resolved${overrideSuffix}. Review the suggested fix plan above.` - : `▲ Scan complete. ${findings.length} ${pluralize(findings.length, "vulnerability")}${overrideSuffix} found. Review the suggested fix plan above.` - ) - ); + console.log(chalk.yellow( + `▲ Scan complete. ${label}${overrideSuffix} found. Review the suggested fix plan above.` + )); } } diff --git a/src/remediation/npm-registry.ts b/src/remediation/npm-registry.ts index e4526860..b6f04948 100644 --- a/src/remediation/npm-registry.ts +++ b/src/remediation/npm-registry.ts @@ -55,7 +55,6 @@ export function clearPackumentCache(): void { export async function fetchPackument( packageName: string, - onTransientFailure?: (packageName: string) => void, ): Promise { const cached = packumentCache.get(packageName); if (cached) return cached; @@ -90,7 +89,6 @@ export async function fetchPackument( } transientFailure = true; currentObserver?.onTransientFailure?.(packageName); - onTransientFailure?.(packageName); return null; } @@ -109,7 +107,6 @@ export async function fetchPackument( } catch (error) { transientFailure = true; currentObserver?.onTransientFailure?.(packageName); - onTransientFailure?.(packageName); if (registryDebugLog) { registryDebugLog("Registry fetch failed", { batchId, @@ -132,8 +129,8 @@ export async function fetchPackument( return promise; } -export async function packageVersionExists(packageName: string, version: string, onTransientFailure?: (packageName: string) => void): Promise { - const packument = await fetchPackument(packageName, onTransientFailure); +export async function packageVersionExists(packageName: string, version: string): Promise { + const packument = await fetchPackument(packageName); if (!packument) return null; return Boolean(packument.versions && version in packument.versions); } @@ -141,9 +138,8 @@ export async function packageVersionExists(packageName: string, version: string, export async function resolvePublishedFixVersion( packageName: string, fixedVersionHint: string, - onTransientFailure?: (packageName: string) => void, ): Promise { - const packument = await fetchPackument(packageName, onTransientFailure); + const packument = await fetchPackument(packageName); if (!packument) { return { resolvedVersion: null, @@ -200,7 +196,6 @@ export async function resolveLowestKnownNonVulnerableVersion( packageName: string, installedVersion: string, vulnerabilities: OsvVuln[], - onTransientFailure?: (packageName: string) => void, ): Promise { if (!looksLikeVersion(installedVersion)) { return { @@ -226,7 +221,7 @@ export async function resolveLowestKnownNonVulnerableVersion( }; } - const packument = await fetchPackument(packageName, onTransientFailure); + const packument = await fetchPackument(packageName); if (!packument) { return { resolvedVersion: null, diff --git a/src/remediation/transitive-chain-resolver.ts b/src/remediation/transitive-chain-resolver.ts index b4e32105..7d87e4e5 100644 --- a/src/remediation/transitive-chain-resolver.ts +++ b/src/remediation/transitive-chain-resolver.ts @@ -10,7 +10,6 @@ export async function resolveChainFix( installedVersions: Map, packageManager: SuggestedFixPackageManager, options: { offline: boolean }, - onTransientFailure?: (packageName: string) => void, ): Promise { if (options.offline) return null; if (finding.relationship !== "transitive") return null; @@ -28,7 +27,7 @@ export async function resolveChainFix( const directDepCurrentVersion = installedVersions.get(directDepName); if (!directDepCurrentVersion) continue; - const packument = await fetchPackument(directDepName, onTransientFailure); + const packument = await fetchPackument(directDepName); if (!packument?.versions) continue; const candidateVersions = Object.keys(packument.versions) @@ -52,7 +51,6 @@ export async function resolveChainFix( hops, finding.pkg.version, fixedVersion, - onTransientFailure, ); if (!traced) continue; @@ -77,7 +75,6 @@ async function traceChain( remainingPath: string[], vulnerableInstalledVersion: string, fixedVersion: string, - onTransientFailure?: (packageName: string) => void, ): Promise<{ chain: ChainHop[]; safeVersion: string } | null> { if (remainingPath.length === 0) return null; @@ -93,7 +90,7 @@ async function traceChain( return null; } // Range excludes the vulnerable version - find the highest safe published version. - const packument = await fetchPackument(nextName, onTransientFailure); + const packument = await fetchPackument(nextName); if (!packument?.versions) return null; const candidates = Object.keys(packument.versions) @@ -109,7 +106,7 @@ async function traceChain( } // Intermediate hop: resolve the highest version of nextName within range, then recurse. - const packument = await fetchPackument(nextName, onTransientFailure); + const packument = await fetchPackument(nextName); if (!packument?.versions) return null; const candidates = Object.keys(packument.versions) @@ -121,7 +118,7 @@ async function traceChain( if (!resolvedVersion) return null; const nextDeps = packument.versions[resolvedVersion]?.dependencies ?? {}; - const result = await traceChain(nextDeps, remainingPath.slice(1), vulnerableInstalledVersion, fixedVersion, onTransientFailure); + const result = await traceChain(nextDeps, remainingPath.slice(1), vulnerableInstalledVersion, fixedVersion); if (!result) return null; return { diff --git a/src/scanner.ts b/src/scanner.ts index 1f89ce3d..412e3c6a 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -465,7 +465,7 @@ export async function scanPackages( if (!offline) { const npmVersionCacheUpdated = await validateDirectFixTargets(findings, (finding) => { updateAnalysisProgress("validating fix target for", `${finding.pkg.name}@${finding.pkg.version}`); - }, { cache, noCache: options.noCache, debugLog: log, onTransientFailure: (pkg) => packumentFailures.add(pkg) }); + }, { cache, noCache: options.noCache, debugLog: log }); if (npmVersionCacheUpdated) { saveCache(cache, cacheDirOverride, options.debug ? log : undefined); } @@ -486,10 +486,7 @@ export async function scanPackages( } if (packumentsToPrewarm.size > 0) { await runWithConcurrency([...packumentsToPrewarm], 8, async (name) => { - await fetchPackument(name, (pkg) => { - packumentFailures.add(pkg); - log("Packument pre-warm failed", { package: pkg }); - }); + await fetchPackument(name); }); } } @@ -609,7 +606,6 @@ export async function scanPackages( installedVersions, chainPm, { offline }, - (pkg) => packumentFailures.add(pkg), ); } catch (error) { chainResolutionFailureCount += 1; @@ -632,7 +628,6 @@ export async function scanPackages( cache, noCache: options.noCache, debugLog: log, - onTransientFailure: (pkg) => packumentFailures.add(pkg), }); if (npmVersionCacheUpdated) { saveCache(cache, cacheDirOverride, options.debug ? log : undefined); @@ -714,7 +709,6 @@ async function validateDirectFixTargets( cache: ReturnType; noCache?: boolean; debugLog?: DebugLogger; - onTransientFailure?: (packageName: string) => void; }, ): Promise { const directCandidates = findings.filter(finding => finding.vulnerabilities.length > 0); @@ -737,7 +731,6 @@ async function validateOneDirectFixTarget( cache: ReturnType; noCache?: boolean; debugLog?: DebugLogger; - onTransientFailure?: (packageName: string) => void; }, ): Promise { let npmVersionCacheUpdated = false; @@ -754,7 +747,6 @@ async function validateOneDirectFixTarget( finding.pkg.name, finding.pkg.version, finding.vulnerabilities, - options?.onTransientFailure, ); const fixedVersionHint = finding.firstFixedVersion; @@ -789,7 +781,7 @@ async function validateOneDirectFixTarget( return npmVersionCacheUpdated; } - const hintResolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint, options?.onTransientFailure); + const hintResolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint); if ( hintResolution.resolvedVersion === lowestKnownResolution.resolvedVersion && hintResolution.note @@ -818,7 +810,7 @@ async function validateOneDirectFixTarget( return npmVersionCacheUpdated; } - const resolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint, options?.onTransientFailure); + const resolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint); finding.validatedFirstFixedVersion = resolution.resolvedVersion; finding.fixVersionValidationNote = resolution.note ?? lowestKnownResolution.note; finding.validatedTargetScannedVersions = null; @@ -890,56 +882,17 @@ function buildCompletenessDiagnostics(params: { }): ScanDiagnostic[] { const diagnostics: ScanDiagnostic[] = []; - if (params.transientDetailIds.size > 0) { - diagnostics.push({ - code: "OSV_DETAIL_TRANSIENT_FAILURE", - severity: "warning", - message: formatDiagnosticMessage("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size), - impact: "detection", - count: params.transientDetailIds.size, - }); - } - - if (params.offlineMissingDetailIds.size > 0) { - diagnostics.push({ - code: "OSV_DETAIL_OFFLINE_MISSING", - severity: "warning", - message: formatDiagnosticMessage("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size), - impact: "detection", - count: params.offlineMissingDetailIds.size, - }); + function push(code: ScanDiagnosticCode, count: number, impact: ScanDiagnostic["impact"]): void { + if (count > 0) diagnostics.push({ code, severity: "warning", message: formatDiagnosticMessage(code, count), impact, count }); } - if (params.packumentFailures.size > 0) { - diagnostics.push({ - code: "PACKUMENT_FETCH_FAILURE", - severity: "warning", - message: formatDiagnosticMessage("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size), - impact: "remediation", - count: params.packumentFailures.size, - }); - } + const remediationTotal = [...params.remediationFailures.values()].reduce((sum, c) => sum + c, 0); - if (params.remediationFailures.size > 0) { - const total = [...params.remediationFailures.values()].reduce((sum, c) => sum + c, 0); - diagnostics.push({ - code: "REMEDIATION_FAILURE", - severity: "warning", - message: formatDiagnosticMessage("REMEDIATION_FAILURE", total), - impact: "remediation", - count: total, - }); - } - - if (params.chainResolutionFailureCount > 0) { - diagnostics.push({ - code: "CHAIN_RESOLUTION_FAILURE", - severity: "warning", - message: formatDiagnosticMessage("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount), - impact: "remediation", - count: params.chainResolutionFailureCount, - }); - } + push("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size, "detection"); + push("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size, "detection"); + push("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size, "remediation"); + push("REMEDIATION_FAILURE", remediationTotal, "remediation"); + push("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation"); return diagnostics; } From 51a0b0f4c8df9d5d5d8920d5b3d6e08fa4fc1174 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 15:46:42 +0800 Subject: [PATCH 08/25] style(scanner,printers): rename addDiagnostic, fix incomplete color precedence - Rename push() to addDiagnostic() with early-return guard and expanded object literal for readability - Restore redBright for Partial scan with critical/high findings by branching renderStatus on urgent flag --- src/output/printers.ts | 7 +++++-- src/scanner.ts | 21 ++++++++++++++------- 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/src/output/printers.ts b/src/output/printers.ts index 068f3564..d53fccfb 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -345,8 +345,11 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0, complet const label = `${findings.length} ${pluralize(findings.length, "vulnerability")}`; if (incomplete) { - console.log(chalk.yellow( - `⚠ Partial scan: ${label} resolved${overrideSuffix}${urgent ? ` (${criticalCount} critical, ${highCount} high)` : ""}. ${urgent ? "Start with the priority fixes above." : "Review the suggested fix plan above."}` + 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( diff --git a/src/scanner.ts b/src/scanner.ts index 412e3c6a..7131f8e1 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -882,17 +882,24 @@ function buildCompletenessDiagnostics(params: { }): ScanDiagnostic[] { const diagnostics: ScanDiagnostic[] = []; - function push(code: ScanDiagnosticCode, count: number, impact: ScanDiagnostic["impact"]): void { - if (count > 0) diagnostics.push({ code, severity: "warning", message: formatDiagnosticMessage(code, count), impact, count }); + function addDiagnostic(code: ScanDiagnosticCode, count: number, impact: ScanDiagnostic["impact"]): void { + if (count === 0) return; + diagnostics.push({ + code, + severity: "warning", + message: formatDiagnosticMessage(code, count), + impact, + count, + }); } const remediationTotal = [...params.remediationFailures.values()].reduce((sum, c) => sum + c, 0); - push("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size, "detection"); - push("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size, "detection"); - push("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size, "remediation"); - push("REMEDIATION_FAILURE", remediationTotal, "remediation"); - push("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation"); + addDiagnostic("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size, "detection"); + addDiagnostic("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size, "detection"); + addDiagnostic("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size, "remediation"); + addDiagnostic("REMEDIATION_FAILURE", remediationTotal, "remediation"); + addDiagnostic("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation"); return diagnostics; } From 09be1d54946742f8db49f06dd7ceaf5e3669d691 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 15:57:10 +0800 Subject: [PATCH 09/25] style(printers): expand printCompactOutput options type to multi-line --- src/output/printers.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/output/printers.ts b/src/output/printers.ts index d53fccfb..495afcfa 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -426,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; completeness?: ScanCompleteness }, + options?: { + offline?: boolean; + all?: boolean; + subfolder?: string; + packageManager?: string; + completeness?: ScanCompleteness; + }, ) { console.log(""); if (options?.packageManager) { From 9825c77ce743a947f34067281410b766ad130a82 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 22:07:38 +0800 Subject: [PATCH 10/25] test(write-outputs): restore accidentally deleted null-projectMeta test --- tests/write-outputs.test.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/write-outputs.test.ts b/tests/write-outputs.test.ts index 41d6d9c5..842139b8 100644 --- a/tests/write-outputs.test.ts +++ b/tests/write-outputs.test.ts @@ -143,6 +143,14 @@ describe("writeOutputs", () => { const [,, planArg, metaArg] = writeCycloneDxReportMock.mock.calls[0] as any[]; expect(metaArg).toBeNull(); }); + + it("passes null projectMeta when package.json has no name field", async () => { + existsSyncMock.mockReturnValueOnce(true); + readFileSyncMock.mockReturnValueOnce(JSON.stringify({ version: "1.0.0" })); + await writeOutputs(makeOptions({ cdx: true }), mockScanState, mockScanInput, "/project"); + const [,, planArg, metaArg] = writeCycloneDxReportMock.mock.calls[0] as any[]; + expect(metaArg).toBeNull(); + }); }); describe("scan completeness JSON fields", () => { From 095dedd1d9f36c414bdaeeacc9844ff9fcc4cd07 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 22:07:44 +0800 Subject: [PATCH 11/25] refactor(npm-registry): replace global mutable observer with AsyncLocalStorage --- src/remediation/npm-registry.ts | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/src/remediation/npm-registry.ts b/src/remediation/npm-registry.ts index b6f04948..28838e16 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; @@ -43,10 +44,13 @@ export type RegistryFetchObserver = { onResolved?: (name: string) => void; }; -let currentObserver: RegistryFetchObserver | null = null; +const observerStorage = new AsyncLocalStorage(); -export function setRegistryFetchObserver(observer: RegistryFetchObserver | null): void { - currentObserver = observer; +export async function runWithObserver( + observer: RegistryFetchObserver, + fn: () => Promise, +): Promise { + return observerStorage.run(observer, fn); } export function clearPackumentCache(): void { @@ -84,16 +88,16 @@ export async function fetchPackument( }); } if (response.status === 404) { - currentObserver?.onResolved?.(packageName); + observerStorage.getStore()?.onResolved?.(packageName); return null; } transientFailure = true; - currentObserver?.onTransientFailure?.(packageName); + observerStorage.getStore()?.onTransientFailure?.(packageName); return null; } const json = (await response.json()) as Packument; - currentObserver?.onResolved?.(packageName); + observerStorage.getStore()?.onResolved?.(packageName); if (registryDebugLog) { registryDebugLog("Registry response", { batchId, @@ -106,7 +110,7 @@ export async function fetchPackument( return json; } catch (error) { transientFailure = true; - currentObserver?.onTransientFailure?.(packageName); + observerStorage.getStore()?.onTransientFailure?.(packageName); if (registryDebugLog) { registryDebugLog("Registry fetch failed", { batchId, From f4940371641f0928174c9ff2d308bb69542114ad Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 22:07:48 +0800 Subject: [PATCH 12/25] refactor(scanner): use runWithObserver to scope registry observer --- src/scanner.ts | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/scanner.ts b/src/scanner.ts index 7131f8e1..98d6b3fa 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -17,7 +17,7 @@ import { fetchPackument, resolveLowestKnownNonVulnerableVersion, resolvePublishedFixVersion, - setRegistryFetchObserver, + runWithObserver, } from "./remediation/npm-registry.js"; import { countBySeverity } from "./utils/severity.js"; import { resolveNpmTransitiveRemediation, resolveTransitiveRemediationViaRegistry } from "./remediation/npm-transitive-resolution.js"; @@ -432,17 +432,16 @@ export async function scanPackages( const packumentFailures = new Set(); const remediationFailures = new Map(); let chainResolutionFailureCount = 0; + let directCount = 0; + let transitiveCount = 0; - setRegistryFetchObserver({ + await runWithObserver({ onTransientFailure(name) { packumentFailures.add(name); }, onResolved(name) { packumentFailures.delete(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++; @@ -633,6 +632,7 @@ export async function scanPackages( saveCache(cache, cacheDirOverride, options.debug ? log : undefined); } } + }); const severityCounts = countBySeverity(findings); log("Findings classified", { @@ -663,7 +663,6 @@ export async function scanPackages( spinner.fail("Scan failed"); throw error; } finally { - setRegistryFetchObserver(null); sourceContext.cleanup(); } } From 15f0ed452baa8a0ac444579ffe1bfd40bed0230f Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 22:07:56 +0800 Subject: [PATCH 13/25] fix(printers): remove duplicate incomplete banner and fix compact footer --- src/output/printers.ts | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/src/output/printers.ts b/src/output/printers.ts index 495afcfa..c83a6f66 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -362,7 +362,7 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0, complet } } - printIncompleteWarning(completeness); + printIncompleteDiagnostics(completeness); } export function printOverrideHint(): void { @@ -442,7 +442,6 @@ export function printCompactOutput( if (findings.length === 0) { if (options?.completeness?.complete === false) { console.log(chalk.yellow("⚠ No known vulnerabilities were resolved, but scan data is incomplete.")); - printIncompleteWarning(options.completeness); } else { console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found.")); } @@ -623,8 +622,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.` @@ -640,14 +649,13 @@ export function printCompactOutput( if (!options?.all) { console.log(chalk.gray(`Run with ${chalk.whiteBright("--verbose")} for fix plan, paths, and full table.`)); } - printIncompleteWarning(options?.completeness); + printIncompleteDiagnostics(options?.completeness); console.log(""); } -export function printIncompleteWarning(completeness?: ScanCompleteness): void { +export function printIncompleteDiagnostics(completeness?: ScanCompleteness): void { if (!completeness || completeness.complete) return; console.log(""); - console.log(chalk.yellow("⚠ Scan data is incomplete.")); for (const diag of completeness.diagnostics) { const prefix = diag.impact === "detection" ? chalk.yellow(" ·") : chalk.gray(" ·"); console.log(prefix + " " + chalk.gray(diag.message)); From 20fb7a1165d89b8505ca3b0cccce555e76d21b74 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 22:08:01 +0800 Subject: [PATCH 14/25] test(output): update tests for printIncompleteDiagnostics rename --- tests/output.test.ts | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tests/output.test.ts b/tests/output.test.ts index 9a278812..95b9191a 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -25,7 +25,7 @@ import { printActionSummary, printCompactOutput, printFinalStatus, - printIncompleteWarning, + printIncompleteDiagnostics, printOverrideHint, printSuggestedFixCommands, printSuggestedFixCommandSkips, @@ -2735,24 +2735,24 @@ describe("printSuggestedFixCommands - cooldown warning", () => { }); }); -describe("printIncompleteWarning", () => { +describe("printIncompleteDiagnostics", () => { it("prints nothing when completeness is undefined", () => { const lines = captureLogs(() => { - printIncompleteWarning(undefined); + printIncompleteDiagnostics(undefined); }); expect(lines.join("\n")).not.toContain("Scan data is incomplete"); }); it("prints nothing for a complete scan", () => { const lines = captureLogs(() => { - printIncompleteWarning({ complete: true, diagnostics: [] }); + printIncompleteDiagnostics({ complete: true, diagnostics: [] }); }); expect(lines.join("\n")).not.toContain("Scan data is incomplete"); }); - it("prints a warning banner for an incomplete scan", () => { + it("prints diagnostics without a duplicate title for an incomplete scan", () => { const lines = captureLogs(() => { - printIncompleteWarning({ + printIncompleteDiagnostics({ complete: false, diagnostics: [ { code: "OSV_DETAIL_TRANSIENT_FAILURE", severity: "warning", message: "3 lookups failed", impact: "detection", count: 3 }, @@ -2761,7 +2761,7 @@ describe("printIncompleteWarning", () => { }); }); const output = lines.join("\n"); - expect(output).toContain("Scan data is incomplete"); + 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."); @@ -2769,7 +2769,7 @@ describe("printIncompleteWarning", () => { it("does not print for a complete scan with empty diagnostics", () => { const lines = captureLogs(() => { - printIncompleteWarning({ complete: true, diagnostics: [] }); + printIncompleteDiagnostics({ complete: true, diagnostics: [] }); }); const output = lines.join("\n"); expect(output).toBe(""); From d2d6fcf6deda4c96e21d9364c4e6d5f29ecfaa69 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 23:09:09 +0800 Subject: [PATCH 15/25] refactor(npm-registry): cache fetch results and notify observers per caller --- src/remediation/npm-registry.ts | 129 ++++++++++++++++++-------------- 1 file changed, 73 insertions(+), 56 deletions(-) diff --git a/src/remediation/npm-registry.ts b/src/remediation/npm-registry.ts index 28838e16..57ebee10 100644 --- a/src/remediation/npm-registry.ts +++ b/src/remediation/npm-registry.ts @@ -23,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; @@ -57,80 +64,90 @@ export function clearPackumentCache(): void { packumentCache.clear(); } +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) { - observerStorage.getStore()?.onResolved?.(packageName); - return null; - } - transientFailure = true; - observerStorage.getStore()?.onTransientFailure?.(packageName); - 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; - observerStorage.getStore()?.onResolved?.(packageName); + 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, + versionsCount: 0, }); } - return json; - } catch (error) { - transientFailure = true; - observerStorage.getStore()?.onTransientFailure?.(packageName); - 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 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 { From 6b65d977223f9b6dec287dfc947c7ef970c0ca87 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 23:09:19 +0800 Subject: [PATCH 16/25] test(scanner-cache): cover concurrent observer isolation for shared fetches --- tests/scanner-cache.test.ts | 45 ++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/tests/scanner-cache.test.ts b/tests/scanner-cache.test.ts index a9a31cda..7a0fda01 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(); @@ -1381,5 +1381,48 @@ describe("scanPackages cache behavior", () => { expect(completeness.complete).toBe(true); expect(completeness.diagnostics).toEqual([]); }); + + 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); + }); }); }); From e543601be15057d2f774eb86df9a6f37e8e78682 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 23:09:27 +0800 Subject: [PATCH 17/25] fix(printers): print diagnostics for incomplete compact scan with no findings --- src/output/printers.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/output/printers.ts b/src/output/printers.ts index c83a6f66..8bb26fa5 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -442,6 +442,7 @@ export function printCompactOutput( if (findings.length === 0) { 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.")); } From 5c2311854b079248593c74e0680c3bdd5f7b651f Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 23:09:35 +0800 Subject: [PATCH 18/25] test(output): cover incomplete scan output across verbose and compact modes --- tests/output.test.ts | 49 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/tests/output.test.ts b/tests/output.test.ts index 95b9191a..7d5ed840 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -2775,3 +2775,52 @@ describe("printIncompleteDiagnostics", () => { 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); + }); +}); From 5f8543576f97f6011a867a6d561ba2375bc5f372 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 23:46:48 +0800 Subject: [PATCH 19/25] fix(printers): use correct plural form for vulnerability count --- src/output/printers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/output/printers.ts b/src/output/printers.ts index 8bb26fa5..0949168a 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -342,7 +342,7 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0, complet const highCount = findings.filter(f => f.severity === "high").length; const urgent = criticalCount > 0 || highCount > 0; - const label = `${findings.length} ${pluralize(findings.length, "vulnerability")}`; + const label = `${findings.length} ${pluralize(findings.length, "vulnerability", "vulnerabilities")}`; if (incomplete) { const severityNote = urgent ? ` (${criticalCount} critical, ${highCount} high)` : ""; From 84bd6aec5c5c1bf993fdcae2af99b1c225bbfc73 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sat, 25 Jul 2026 23:46:48 +0800 Subject: [PATCH 20/25] test(output): assert plural form in printFinalStatus --- tests/output.test.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/tests/output.test.ts b/tests/output.test.ts index 7d5ed840..bb3005a8 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -2389,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); From abcfd1146fc58cedbad3d4346354b1f076977ded Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sun, 26 Jul 2026 01:14:18 +0800 Subject: [PATCH 21/25] fix(scanner): block incomplete OSV scan baselines --- src/index.ts | 22 +++++++++++++++++ src/scanner.ts | 17 ++++++++++++- src/types.ts | 1 + tests/cli-integration.test.ts | 45 +++++++++++++++++++++++++++++++++++ tests/scanner-cache.test.ts | 28 ++++++++++++++++++---- 5 files changed, 108 insertions(+), 5 deletions(-) diff --git a/src/index.ts b/src/index.ts index 3204738e..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); diff --git a/src/scanner.ts b/src/scanner.ts index 98d6b3fa..2a7a9942 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -222,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]; @@ -234,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); @@ -256,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 }); } @@ -349,7 +355,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`); @@ -357,6 +364,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`); } @@ -649,6 +659,7 @@ export async function scanPackages( const diagnostics = buildCompletenessDiagnostics({ transientDetailIds, offlineMissingDetailIds, + confirmedMissingDetailIds, packumentFailures, remediationFailures, chainResolutionFailureCount, @@ -875,6 +886,7 @@ function findFirstFixedVersion(vulns: OsvVuln[]): string | null { function buildCompletenessDiagnostics(params: { transientDetailIds: Set; offlineMissingDetailIds: Set; + confirmedMissingDetailIds: Set; packumentFailures: Set; remediationFailures: Map; chainResolutionFailureCount: number; @@ -896,6 +908,7 @@ function buildCompletenessDiagnostics(params: { addDiagnostic("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size, "detection"); addDiagnostic("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size, "detection"); + addDiagnostic("OSV_DETAIL_CONFIRMED_MISSING", params.confirmedMissingDetailIds.size, "detection"); addDiagnostic("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size, "remediation"); addDiagnostic("REMEDIATION_FAILURE", remediationTotal, "remediation"); addDiagnostic("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation"); @@ -909,6 +922,8 @@ export function formatDiagnosticMessage(code: ScanDiagnosticCode, count: number) 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": diff --git a/src/types.ts b/src/types.ts index 96ef9e35..fb921929 100644 --- a/src/types.ts +++ b/src/types.ts @@ -203,6 +203,7 @@ export type Baseline = { export type ScanDiagnosticCode = | "OSV_DETAIL_TRANSIENT_FAILURE" | "OSV_DETAIL_OFFLINE_MISSING" + | "OSV_DETAIL_CONFIRMED_MISSING" | "PACKUMENT_FETCH_FAILURE" | "REMEDIATION_FAILURE" | "CHAIN_RESOLUTION_FAILURE"; diff --git a/tests/cli-integration.test.ts b/tests/cli-integration.test.ts index eace47ba..19ec6e9f 100644 --- a/tests/cli-integration.test.ts +++ b/tests/cli-integration.test.ts @@ -29,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(); @@ -104,6 +105,7 @@ jest.unstable_mockModule("../src/output/printers.js", () => ({ printTable: printTableMock, printFinalStatus: printFinalStatusMock, printCompactOutput: printCompactOutputMock, + printIncompleteDiagnostics: printIncompleteDiagnosticsMock, printOverrideHint: printOverrideHintMock, })); @@ -339,6 +341,49 @@ 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("suppresses compact output when --sarif is used", async () => { parseArgsMock.mockReturnValue({ command: "scan", diff --git a/tests/scanner-cache.test.ts b/tests/scanner-cache.test.ts index 7a0fda01..e6b91225 100644 --- a/tests/scanner-cache.test.ts +++ b/tests/scanner-cache.test.ts @@ -1032,18 +1032,38 @@ describe("scanPackages cache behavior", () => { getVulnMock.mockRejectedValue(new Error("OSV vuln fetch failed for OSV-404-MISSING: 404 Not Found")); try { - const { findings: firstFindings } = await scanPackages([pkg], 100, createOptions(cacheDir)); + const { findings: firstFindings, completeness: firstCompleteness } = await scanPackages([pkg], 100, createOptions(cacheDir)); expect(firstFindings).toHaveLength(1); expect(firstFindings[0]?.vulnerabilities).toEqual([]); expect(firstFindings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-404-MISSING"]); + expect(firstCompleteness).toEqual({ + complete: false, + diagnostics: [ + expect.objectContaining({ + code: "OSV_DETAIL_CONFIRMED_MISSING", + impact: "detection", + count: 1, + }), + ], + }); queryBatchMock.mockClear(); getVulnMock.mockClear(); - const { findings: 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(secondCompleteness).toEqual({ + complete: false, + diagnostics: [ + expect.objectContaining({ + code: "OSV_DETAIL_CONFIRMED_MISSING", + impact: "detection", + count: 1, + }), + ], + }); } finally { removeDir(cacheDir); } @@ -1222,7 +1242,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" }; @@ -1264,7 +1284,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); From 59115c87f19cb6df6f1f8faa0117c3859d6d0ac9 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sun, 26 Jul 2026 01:21:25 +0800 Subject: [PATCH 22/25] test(ratchet): cover incomplete scan handling --- tests/cli-integration.test.ts | 91 +++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/tests/cli-integration.test.ts b/tests/cli-integration.test.ts index 19ec6e9f..1261bf70 100644 --- a/tests/cli-integration.test.ts +++ b/tests/cli-integration.test.ts @@ -384,6 +384,97 @@ describe("CLI integration", () => { } }); + 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", From 85a4ef0b821e13c472036a509da7e82815575332 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sun, 26 Jul 2026 09:58:10 +0800 Subject: [PATCH 23/25] fix(scanner): refine incomplete scan diagnostics --- src/scanner.ts | 29 +++++-- tests/scanner-cache.test.ts | 160 ++++++++++++++++++++++++------------ 2 files changed, 128 insertions(+), 61 deletions(-) diff --git a/src/scanner.ts b/src/scanner.ts index 2a7a9942..5538909a 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -312,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( @@ -330,7 +346,7 @@ export async function scanPackages( ); const firstFixedVersion = findFirstFixedVersion(vulnerabilities); - return { + return [{ pkg: result.pkg, vulnerabilities, severity, @@ -346,7 +362,7 @@ export async function scanPackages( recommendedParentUpgrade: undefined, recommendedNpmTransitiveRemediation: undefined, ...(unresolvedIds.length > 0 ? { unresolvedAdvisoryIds: unresolvedIds } : {}), - }; + }]; }); const unresolvedDetailIds = idSet.size > 0 @@ -447,7 +463,6 @@ export async function scanPackages( await runWithObserver({ onTransientFailure(name) { packumentFailures.add(name); }, - onResolved(name) { packumentFailures.delete(name); }, }, async () => { const npmRemediationCache = new Map(); const parentUpgradeCache = new Map(); @@ -659,7 +674,7 @@ export async function scanPackages( const diagnostics = buildCompletenessDiagnostics({ transientDetailIds, offlineMissingDetailIds, - confirmedMissingDetailIds, + confirmedMissingFindingDetailIds, packumentFailures, remediationFailures, chainResolutionFailureCount, @@ -886,7 +901,7 @@ function findFirstFixedVersion(vulns: OsvVuln[]): string | null { function buildCompletenessDiagnostics(params: { transientDetailIds: Set; offlineMissingDetailIds: Set; - confirmedMissingDetailIds: Set; + confirmedMissingFindingDetailIds: Set; packumentFailures: Set; remediationFailures: Map; chainResolutionFailureCount: number; @@ -908,7 +923,7 @@ function buildCompletenessDiagnostics(params: { addDiagnostic("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size, "detection"); addDiagnostic("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size, "detection"); - addDiagnostic("OSV_DETAIL_CONFIRMED_MISSING", params.confirmedMissingDetailIds.size, "detection"); + addDiagnostic("OSV_DETAIL_CONFIRMED_MISSING", params.confirmedMissingFindingDetailIds.size, "detection"); addDiagnostic("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size, "remediation"); addDiagnostic("REMEDIATION_FAILURE", remediationTotal, "remediation"); addDiagnostic("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation"); diff --git a/tests/scanner-cache.test.ts b/tests/scanner-cache.test.ts index e6b91225..175fcc4c 100644 --- a/tests/scanner-cache.test.ts +++ b/tests/scanner-cache.test.ts @@ -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 { @@ -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"); @@ -1033,18 +1032,10 @@ describe("scanPackages cache behavior", () => { try { const { findings: firstFindings, completeness: firstCompleteness } = await scanPackages([pkg], 100, createOptions(cacheDir)); - expect(firstFindings).toHaveLength(1); - expect(firstFindings[0]?.vulnerabilities).toEqual([]); - expect(firstFindings[0]?.unresolvedAdvisoryIds).toEqual(["OSV-404-MISSING"]); + expect(firstFindings).toEqual([]); expect(firstCompleteness).toEqual({ - complete: false, - diagnostics: [ - expect.objectContaining({ - code: "OSV_DETAIL_CONFIRMED_MISSING", - impact: "detection", - count: 1, - }), - ], + complete: true, + diagnostics: [], }); queryBatchMock.mockClear(); @@ -1052,9 +1043,46 @@ describe("scanPackages cache behavior", () => { 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({ @@ -1326,11 +1354,9 @@ describe("scanPackages cache behavior", () => { describe("registry fetch observer", () => { let cacheDir: string; - let dbPath: string; beforeEach(async () => { cacheDir = createTempCacheDir(); - dbPath = path.join(cacheDir, "cve-advisories.db"); clearPackumentCache(); }); @@ -1338,68 +1364,94 @@ describe("scanPackages cache behavior", () => { if (fs.existsSync(cacheDir)) removeDir(cacheDir); }); - it("marks completeness as complete after transient failure followed by successful retry", async () => { - const pkg: PackageRef = { name: "observer-retry-ok", version: "1.0.0", ecosystem: "npm", paths: [["root", "observer-retry-ok"]] }; - - const db = new LocalAdvisoryDatabase(dbPath); - db.upsertVulnerability({ + 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" }] }] }], - }); - db.close(); + }; - queryBatchMock.mockResolvedValue({ - vulns: { find: [{ id: "OSV-OBSERVER-RETRY" }], "observer-retry-ok": [{ id: "OSV-OBSERVER-RETRY" }] }, - aliases: [], - details: [{ 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 () => { + 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], 100, createOptions(cacheDir), { - directDependencyNames: new Set(["observer-retry-ok"]), + const { completeness } = await scanPackages([pkg, parent], 100, createOptions(cacheDir), { + directDependencyNames: new Set(["observer-parent"]), }); - expect(completeness.complete).toBe(true); - expect(completeness.diagnostics).toEqual([]); + expect(callCount).toBe(2); + expect(completeness.complete).toBe(false); + expect(completeness.diagnostics).toEqual([ + expect.objectContaining({ + code: "PACKUMENT_FETCH_FAILURE", + impact: "remediation", + count: 1, + }), + ]); }); - it("marks completeness as complete after transient failure followed by 404 on retry", async () => { - const pkg: PackageRef = { name: "observer-retry-404", version: "1.0.0", ecosystem: "npm", paths: [["root", "observer-retry-404"]] }; - - const db = new LocalAdvisoryDatabase(dbPath); - db.upsertVulnerability({ + 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" }] }] }], - }); - db.close(); + }; - queryBatchMock.mockResolvedValue({ - vulns: { find: [{ id: "OSV-OBSERVER-404" }], "observer-retry-404": [{ id: "OSV-OBSERVER-404" }] }, - aliases: [], - details: [{ 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 () => { + 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], 100, createOptions(cacheDir), { - directDependencyNames: new Set(["observer-retry-404"]), + const { completeness } = await scanPackages([pkg, parent], 100, createOptions(cacheDir), { + directDependencyNames: new Set(["observer-parent"]), }); - expect(completeness.complete).toBe(true); - expect(completeness.diagnostics).toEqual([]); + 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 () => { From ccaffc060fac8f7ad8d540f835813ca8254bf9e5 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sun, 26 Jul 2026 10:06:42 +0800 Subject: [PATCH 24/25] fix(scanner): report remediation package count --- src/scan/multi-folder-scan.ts | 10 ++++++- src/scanner.ts | 26 +++++++++++++++--- src/types.ts | 1 + tests/multi-folder-scan.test.ts | 47 ++++++++++++++++++++++++++++++++- tests/scanner-cache.test.ts | 10 ++++++- 5 files changed, 87 insertions(+), 7 deletions(-) diff --git a/src/scan/multi-folder-scan.ts b/src/scan/multi-folder-scan.ts index 1cc09a23..f0713d96 100644 --- a/src/scan/multi-folder-scan.ts +++ b/src/scan/multi-folder-scan.ts @@ -118,7 +118,15 @@ export function aggregateMultiFolderCompleteness( const existing = deduped.get(d.code); if (existing) { existing.count += d.count; - existing.message = formatDiagnosticMessage(d.code, existing.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 }); } diff --git a/src/scanner.ts b/src/scanner.ts index 5538909a..902a4667 100644 --- a/src/scanner.ts +++ b/src/scanner.ts @@ -908,14 +908,20 @@ function buildCompletenessDiagnostics(params: { }): ScanDiagnostic[] { const diagnostics: ScanDiagnostic[] = []; - function addDiagnostic(code: ScanDiagnosticCode, count: number, impact: ScanDiagnostic["impact"]): void { + 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), + message: formatDiagnosticMessage(code, count, affectedPackageCount), impact, count, + ...(affectedPackageCount === undefined ? {} : { affectedPackageCount }), }); } @@ -925,13 +931,22 @@ function buildCompletenessDiagnostics(params: { 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"); + addDiagnostic( + "REMEDIATION_FAILURE", + remediationTotal, + "remediation", + params.remediationFailures.size, + ); addDiagnostic("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation"); return diagnostics; } -export function formatDiagnosticMessage(code: ScanDiagnosticCode, count: number): string { +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.`; @@ -942,6 +957,9 @@ export function formatDiagnosticMessage(code: ScanDiagnosticCode, count: number) 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.`; diff --git a/src/types.ts b/src/types.ts index fb921929..19ca7d10 100644 --- a/src/types.ts +++ b/src/types.ts @@ -214,6 +214,7 @@ export type ScanDiagnostic = { message: string; impact: "detection" | "remediation"; count: number; + affectedPackageCount?: number; }; export type ScanCompleteness = { diff --git a/tests/multi-folder-scan.test.ts b/tests/multi-folder-scan.test.ts index 3ea631e2..fd2439d4 100644 --- a/tests/multi-folder-scan.test.ts +++ b/tests/multi-folder-scan.test.ts @@ -20,7 +20,7 @@ jest.unstable_mockModule("../src/parsers/multi-package.js", () => ({ jest.unstable_mockModule("../src/scanner.js", () => ({ scanPackages: scanPackagesMock, buildCoverageNotes: buildCoverageNotesMock, - formatDiagnosticMessage: (code: string, count: number) => { + formatDiagnosticMessage: (code: string, count: number, affectedPackageCount?: number) => { const labels: Record = { OSV_DETAIL_TRANSIENT_FAILURE: "advisory detail lookup", OSV_DETAIL_OFFLINE_MISSING: "advisory detail record", @@ -30,6 +30,10 @@ jest.unstable_mockModule("../src/scanner.js", () => ({ }; 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.`; }, })); @@ -511,4 +515,45 @@ describe("aggregateMultiFolderCompleteness", () => { 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/scanner-cache.test.ts b/tests/scanner-cache.test.ts index 175fcc4c..1cc7fc30 100644 --- a/tests/scanner-cache.test.ts +++ b/tests/scanner-cache.test.ts @@ -1230,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" }), From 7278f92ee991d21fcb7c79971fcf13c0f5d11b1b Mon Sep 17 00:00:00 2001 From: luojiyin Date: Sun, 26 Jul 2026 10:12:20 +0800 Subject: [PATCH 25/25] style(printers): remove trailing blank line after diagnostics --- src/output/printers.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/output/printers.ts b/src/output/printers.ts index 0949168a..ee57386e 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -445,8 +445,8 @@ export function printCompactOutput( printIncompleteDiagnostics(options.completeness); } else { console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found.")); + console.log(""); } - console.log(""); return; } @@ -651,7 +651,9 @@ export function printCompactOutput( console.log(chalk.gray(`Run with ${chalk.whiteBright("--verbose")} for fix plan, paths, and full table.`)); } printIncompleteDiagnostics(options?.completeness); - console.log(""); + if (!incomplete) { + console.log(""); + } } export function printIncompleteDiagnostics(completeness?: ScanCompleteness): void {