@4da/mcp-server 6.0.1 → 6.1.0

package/dist/tools/upgrade-planner.d.ts

@@ -30,6 +30,8 @@ export interface UpgradePlannerParams {
     max_recommendations?: number;
     risk_threshold?: "all" | "low" | "medium" | "high" | "critical";
     package?: string;
+    /** Project directory to plan for; "*" for every project. Default: the server's project, when it is one. */
+    project_path?: string;
 }
 interface UpgradeRecommendation {
     package: string;
@@ -53,19 +55,37 @@ interface UpgradeRecommendation {
     /** Whether this package is declared in a manifest (direct) or only present via the lockfile (transitive). */
     scope: "direct" | "transitive";
     /**
-     * Direct deps you can bump yourself; transitive fixes arrive via a parent
-     * update or lockfile refresh; `reinstall` = the lockfile's version is fine
+     * Direct deps you can bump yourself; `lockfile_refresh` = transitive, and
+     * every parent's declared requirement already admits a clean version, so
+     * `refreshCommands` fixes it; `waiting_on_upstream` = transitive, and a
+     * parent's requirement excludes every clean version (or could not be
+     * read); `reinstall` = the lockfile's version is fine
      * but node_modules holds another one, so the fix is `installFix`;
      * `no_fix_available` = vulnerable with no fixed release to move to;
      * `not_built_on_this_host` = every advisory is against code this host never compiles.
      */
-    action: "upgrade_direct" | "waiting_on_upstream" | "reinstall" | "no_fix_available" | "not_built_on_this_host";
+    action: "upgrade_direct" | "lockfile_refresh" | "waiting_on_upstream" | "reinstall" | "no_fix_available" | "not_built_on_this_host";
+    /**
+     * For a vulnerable package: whether the target was checked against EVERY
+     * known advisory of the package (`all_advisories`), or only against the
+     * advisories of the installed version because the lookups failed or ran
+     * out of time (`installed_advisories_only`; the target may then be
+     * affected by an advisory the installed version predates).
+     */
+    fixPathChecked?: "all_advisories" | "installed_advisories_only";
+    /** lockfile_refresh: the command to run, per lockfile directory. */
+    refreshCommands?: Array<{
+        dir: string;
+        command: string;
+    }>;
     /** False when the dependency is gated behind a target spec not active on this host (label, never suppressed). */
     platformActive: boolean;
     /** npm: the version node_modules holds, when it differs from `currentVersion` (the lockfile's). */
     installedVersion?: string;
     /** npm: the command that reinstalls from the lockfile, when `installedVersion` is set. */
     installFix?: string;
+    /** No lockfile: the manifest's declared requirement; `currentVersion` is its floor, not an install. */
+    declaredRange?: string;
 }
 interface UpgradePlanResult {
     generatedAt: string;
@@ -76,6 +96,8 @@ interface UpgradePlanResult {
     quickWins: number;
     breakingChanges: number;
     waitingOnUpstream: number;
+    /** Transitive steps a lockfile refresh fixes (every parent already admits a clean version). */
+    lockfileRefreshes: number;
     /** False when no vulnerability scan has run this session — the ranking is then CVE-blind and says so. */
     vulnerabilityDataAvailable: boolean;
     provenance: {
@@ -84,6 +106,8 @@ interface UpgradePlanResult {
     };
     /** Why the 4DA app's own plan was not used (no database, no snapshot, other schema). */
     appPlanUnavailable?: string;
+    /** The project the plan covers, or null when it is not narrowed to one. */
+    projectScope?: string | null;
 }
 export declare const upgradePlannerTool: {
     name: string;
@@ -108,6 +132,10 @@ export declare const upgradePlannerTool: {
                 type: string;
                 description: string;
             };
+            project_path: {
+                type: string;
+                description: string;
+            };
         };
     };
 };

package/dist/tools/upgrade-planner.js

@@ -30,13 +30,16 @@ import { formatAppPlan, readAppPlan } from "./app-plan.js";
 import { dirsLabel, driftFor } from "./install-drift-notes.js";
 import { emptyAnswerNote } from "./package-presence.js";
 import { relativeDir } from "./vulnerability-scan-format.js";
+import { liveIntelFor, resolveProjectScope } from "./project-scope.js";
+import { verifyFixPaths } from "./upgrade-planner-fixpaths.js";
+import { discoveryNote } from "../project-tree.js";
 /** How long a plan waits for its own OSV scan before answering CVE-blind (the scan keeps running). */
 const PLANNER_SCAN_TIMEOUT_MS = 60_000;
 const PROVENANCE_NOTE = "Point-in-time heuristic from local lockfiles plus live registry/OSV lookups. " +
     "Not the 4DA desktop app's cross-project, version-confirmed plan (none was available).";
 export const upgradePlannerTool = {
     name: "upgrade_planner",
-    description: "Ranked dependency upgrade plan — call before upgrading, adding, or auditing any dependency to pick the safest order. When the 4DA desktop app has computed its plan, returns that plan's work order (provenance app_plan): per package the ecosystem, each installed version with its minimum clean target, upgrade type (patch/minor/major), the projects that hold it (direct/dev) and the mechanism (manifest_bump, lockfile_or_parent_update, mixed, no_fix); flagged stale past its freshness horizon. Otherwise falls back to a standalone plan from local lockfiles (provenance standalone_heuristic): the smallest version that fixes each vulnerability (direct and transitive), deprecation and version distance; it runs the OSV scan itself when none has run. `package` narrows either plan to one package. Privacy: the fallback may query public registries and OSV with package names and versions; it never sends source code.",
+    description: "Ranked dependency upgrade plan for one project — call before upgrading, adding, or auditing any dependency to pick the safest order. `project_path` picks the project (default: the one the server was started in; \"*\" for every project). When the 4DA desktop app has computed its plan, returns that plan's work order (provenance app_plan): per package the ecosystem, each installed version with its minimum clean target, upgrade type (patch/minor/major), the projects that hold it (direct/dev) and the mechanism (manifest_bump, lockfile_or_parent_update, mixed, no_fix); flagged stale past its freshness horizon. Otherwise falls back to a standalone plan from local lockfiles (provenance standalone_heuristic): the smallest version that fixes each vulnerability (direct and transitive), checked against every known advisory of the package, whether a lockfile refresh already reaches it (lockfile_refresh with the command) or a parent blocks it (waiting_on_upstream), deprecation and version distance; it runs the OSV scan itself when none has run. `package` narrows either plan to one package. Privacy: the fallback may query public registries and OSV with package names and versions; it never sends source code.",
     inputSchema: {
         type: "object",
         properties: {
@@ -57,10 +60,25 @@ export const upgradePlannerTool = {
                 type: "string",
                 description: "Plan for this one package only (exact name, any ecosystem). Default: every dependency.",
             },
+            project_path: {
+                type: "string",
+                description: "Project directory to plan for: the app's plan is narrowed to the steps (and installed lines) that touch it; the standalone plan resolves that project's lockfiles. \"*\" for every project the app tracks. Default: the project the server was started in, when that directory is a project.",
+            },
         },
     },
 };
 const RISK_LEVELS = { low: 0, medium: 1, high: 2, critical: 3 };
+/** critical > high > medium > low, then fixable now (direct) before transitive, then non-breaking first (quick wins). */
+function planOrder(a, b) {
+    const riskDiff = RISK_LEVELS[b.risk] - RISK_LEVELS[a.risk];
+    if (riskDiff !== 0)
+        return riskDiff;
+    if (a.scope !== b.scope)
+        return a.scope === "direct" ? -1 : 1;
+    if (a.breaking !== b.breaking)
+        return a.breaking ? 1 : -1;
+    return 0;
+}
 function severityToRisk(severities) {
     if (severities.includes("critical"))
         return "critical";
@@ -79,13 +97,23 @@ function higherRisk(a, b) {
     return RISK_LEVELS[b] > RISK_LEVELS[a] ? b : a;
 }
 export async function executeUpgradePlanner(db, params, liveIntel) {
+    const scope = resolveProjectScope(params.project_path);
+    if (scope.kind === "error")
+        throw new Error(scope.error);
+    const scopePath = scope.kind === "project" ? scope.path : null;
     // One brain: the app's plan wins whenever there is one, stale or not (a
     // stale plan is returned flagged, never silently replaced by a heuristic).
+    // It covers every project the app tracks, so it is narrowed to this one.
     const appPlan = readAppPlan(db);
     if (appPlan.kind === "plan")
-        return formatAppPlan(appPlan, params);
-    const standalone = await executeStandalonePlanner(params, liveIntel);
-    return { ...standalone, appPlanUnavailable: appPlan.reason };
+        return formatAppPlan(appPlan, params, scopePath);
+    // The live layer already covers the server's own project; only an explicit
+    // project_path elsewhere resolves another tree.
+    const scoped = scope.kind === "project" && scope.source === "argument"
+        ? liveIntelFor(liveIntel, db, scope)
+        : liveIntel;
+    const standalone = await executeStandalonePlanner(params, scoped);
+    return { ...standalone, appPlanUnavailable: appPlan.reason, projectScope: scopePath ?? standalone.projectPath };
 }
 async function executeStandalonePlanner(params, liveIntel) {
     if (!liveIntel || !liveIntel.isInitialized()) {
@@ -98,6 +126,7 @@ async function executeStandalonePlanner(params, liveIntel) {
             quickWins: 0,
             breakingChanges: 0,
             waitingOnUpstream: 0,
+            lockfileRefreshes: 0,
             vulnerabilityDataAvailable: false,
             provenance: { mode: "standalone_heuristic", note: PROVENANCE_NOTE },
         };
@@ -159,6 +188,8 @@ async function executeStandalonePlanner(params, liveIntel) {
     // Build recommendations — direct deps (registry-informed)
     const recommendations = [];
     const directPackages = new Set();
+    // Per vulnerable step: the per-advisory fixes and where it is pinned, for fix-path verification.
+    const fixPathInputs = new Map();
     for (const dep of registryData) {
         directPackages.add(instanceKey(dep.ecosystem, dep.name, dep.currentVersion));
         const reasons = [];
@@ -201,7 +232,15 @@ async function executeStandalonePlanner(params, liveIntel) {
         // Check version distance
         if (dep.versionsBehind) {
             const d = dep.versionsBehind;
-            if (d.label === "major") {
+            if (d.label === "major" && d.major === 0) {
+                // A 0.x bump: breaking under caret rules, though the major number is unchanged.
+                const n = d.minor > 0 ? d.minor : d.patch;
+                const unit = d.minor > 0 ? "minor version" : "patch";
+                reasons.push(`${n} 0.x ${unit}${n !== 1 ? (unit === "patch" ? "es" : "s") : ""} behind (breaking: below 1.0 a ${unit === "patch" ? "0.0.x patch" : "minor"} bump is a major one)`);
+                if (risk === "low")
+                    risk = "medium";
+            }
+            else if (d.label === "major") {
                 reasons.push(`${d.major} major version${d.major !== 1 ? "s" : ""} behind`);
                 if (risk === "low")
                     risk = "medium";
@@ -238,6 +277,9 @@ async function executeStandalonePlanner(params, liveIntel) {
         // Skip if no upgrade needed (no vuln, not deprecated, not behind, no drift => no reasons)
         if (reasons.length === 0)
             continue;
+        if (dep.declaredRange) {
+            reasons.push(`No lockfile: ${dep.currentVersion} is the floor of the declared range "${dep.declaredRange}", not an installed version`);
+        }
         // Never recommend a downgrade: when the current version is a prerelease
         // AHEAD of the latest stable (rsa 0.10.0-rc.18 vs stable 0.9.10), the
         // stable line is not an upgrade target.
@@ -260,7 +302,7 @@ async function executeStandalonePlanner(params, liveIntel) {
                     : targetVersion
                         ? "upgrade_direct"
                         : "no_fix_available";
-        recommendations.push({
+        const rec = {
             package: dep.name,
             ecosystem: dep.ecosystem,
             currentVersion: dep.currentVersion,
@@ -275,7 +317,12 @@ async function executeStandalonePlanner(params, liveIntel) {
             action,
             platformActive,
             ...(installedVersion ? { installedVersion, installFix } : {}),
-        });
+            ...(dep.declaredRange ? { declaredRange: dep.declaredRange } : {}),
+        };
+        recommendations.push(rec);
+        if (fixable && !reinstallOnly && action === "upgrade_direct" && vulns) {
+            fixPathInputs.set(rec, { fixes: vulns.map((v) => v.fixedVersion).filter((f) => Boolean(f)), sourceDirs: [] });
+        }
     }
     // Transitive vulnerable packages — previously counted in scan totals but
     // never recommended. Surfaced as waiting_on_upstream with honest labels.
@@ -312,7 +359,7 @@ async function executeStandalonePlanner(params, liveIntel) {
                 reasons.push("Affected code is gated behind a target not active on this platform");
             }
             const target = fixedVersions.length > 0 ? maxVersion(fixedVersions, first.ecosystem) : null;
-            recommendations.push({
+            const rec = {
                 package: first.package,
                 ecosystem: first.ecosystem,
                 currentVersion: first.currentVersion,
@@ -325,7 +372,11 @@ async function executeStandalonePlanner(params, liveIntel) {
                 scope: "transitive",
                 action: !platformActive ? "not_built_on_this_host" : target ? "waiting_on_upstream" : "no_fix_available",
                 platformActive,
-            });
+            };
+            recommendations.push(rec);
+            if (rec.action === "waiting_on_upstream") {
+                fixPathInputs.set(rec, { fixes: fixedVersions, sourceDirs: [...new Set(entries.flatMap((e) => e.sourceDirs ?? []))] });
+            }
         }
     }
     // Defensive dedupe: identical (ecosystem, package, version, scope) rows can
@@ -345,22 +396,18 @@ async function executeStandalonePlanner(params, liveIntel) {
         : deduped.filter((r) => RISK_LEVELS[r.risk] >= RISK_LEVELS[threshold]);
     // Sort: critical > high > medium > low, then fixable-now (direct) before
     // waiting-on-upstream (transitive), then non-breaking first (quick wins).
-    filtered.sort((a, b) => {
-        const riskDiff = RISK_LEVELS[b.risk] - RISK_LEVELS[a.risk];
-        if (riskDiff !== 0)
-            return riskDiff;
-        if (a.scope !== b.scope)
-            return a.scope === "direct" ? -1 : 1;
-        if (a.breaking !== b.breaking)
-            return a.breaking ? 1 : -1;
-        return 0;
-    });
+    filtered.sort(planOrder);
     const maxRecs = params.max_recommendations ?? 20;
     const limited = filtered.slice(0, maxRecs);
+    // Verify the fix path of every vulnerable step the plan returns: a target
+    // no advisory affects, and whether a lockfile refresh already reaches it.
+    const unverified = await verifyFixPaths(limited.filter((r) => fixPathInputs.has(r)).map((r) => ({ step: r, ...fixPathInputs.get(r) })), liveIntel);
+    limited.sort(planOrder);
     const upgrades = limited.filter((r) => r.scope === "direct" && r.action === "upgrade_direct");
     const quickWins = upgrades.filter((r) => !r.breaking).length;
     const breakingChanges = upgrades.filter((r) => r.breaking).length;
     const waitingOnUpstream = limited.filter((r) => r.action === "waiting_on_upstream").length;
+    const lockfileRefreshes = limited.filter((r) => r.action === "lockfile_refresh").length;
     const reinstalls = limited.filter((r) => r.action === "reinstall").length;
     const noFix = limited.filter((r) => r.action === "no_fix_available").length;
     const inactive = limited.filter((r) => r.action === "not_built_on_this_host").length;
@@ -373,8 +420,12 @@ async function executeStandalonePlanner(params, liveIntel) {
         parts.push(`${upgrades.length} upgradable directly (${quickWins} non-breaking, ${breakingChanges} crossing a major version)`);
     if (reinstalls > 0)
         parts.push(`${reinstalls} need only a reinstall (node_modules behind the lockfile)`);
+    if (lockfileRefreshes > 0)
+        parts.push(`${lockfileRefreshes} transitive, fixed by a lockfile refresh (every parent already admits a clean version)`);
     if (waitingOnUpstream > 0)
         parts.push(`${waitingOnUpstream} transitive, waiting on upstream`);
+    if (unverified > 0)
+        parts.push(`${unverified} fix target${unverified !== 1 ? "s" : ""} checked only against the installed version's advisories (offline, or OSV or the registry did not answer in time; see fixPathChecked)`);
     if (noFix > 0)
         parts.push(`${noFix} vulnerable with no fixed release yet`);
     if (inactive > 0)
@@ -385,6 +436,9 @@ async function executeStandalonePlanner(params, liveIntel) {
     if (maintenanceNotices.size > 0) {
         parts.push(`${maintenanceNotices.size} unmaintained-package notice${maintenanceNotices.size !== 1 ? "s" : ""} not ranked (no fix exists; see vulnerability_scan maintenance_notices)`);
     }
+    const partial = discoveryNote(liveIntel.getDiscovery());
+    if (partial)
+        parts.push(partial.replace(/[.]$/, ""));
     const nothing = vulnerabilityDataAvailable ? "nothing to upgrade (no known vulnerability, deprecation, or newer release of a direct dependency)" : "no vulnerability data to plan from";
     if (only && limited.length === 0)
         parts.push(emptyAnswerNote(only, liveIntel, includeDev, nothing));
@@ -402,6 +456,7 @@ async function executeStandalonePlanner(params, liveIntel) {
         quickWins,
         breakingChanges,
         waitingOnUpstream,
+        lockfileRefreshes,
         vulnerabilityDataAvailable,
         provenance: { mode: "standalone_heuristic", note: PROVENANCE_NOTE },
     };

package/dist/tools/vulnerability-scan-concise.d.ts

@@ -22,7 +22,9 @@ export interface PackageRow {
     severity: SeverityTier;
     advisories: number;
     ids: string[];
+    /** The version to move to: checked against every advisory of the package when fix_checked says so. */
     fixed_version: string | null;
+    fix_checked: "all_advisories" | "installed_advisories_only";
     unfixed_advisories?: number;
     is_direct: boolean | null;
     is_dev?: true;
@@ -30,7 +32,7 @@ export interface PackageRow {
     summary: string;
 }
 /** One row per package version: worst graded severity, the fix that clears every fixable advisory. */
-export declare function groupByPackage(rows: FormattedVuln[]): PackageRow[];
+export declare function groupByPackage(rows: FormattedVuln[], targets?: FullScan["fix_targets"]): PackageRow[];
 export declare function conciseScanResult(full: FullScan): {
     scan_time: string;
     project_root: string;
@@ -38,6 +40,16 @@ export declare function conciseScanResult(full: FullScan): {
     ecosystems_scanned: string[];
     total_dependencies_scanned: number;
     total_vulnerable_packages: number;
+    coverage?: {
+        complete: false;
+        note: string;
+        lockfiles_not_scanned: number;
+        unresolved_manifests?: {
+            manifest: string;
+            declared_ranges: number;
+            fix: string;
+        }[] | undefined;
+    } | undefined;
     by_severity: import("../live/severity-scope.js").SeverityCounts;
     vulnerable_packages: PackageRow[];
     vulnerable_packages_note?: string | undefined;

package/dist/tools/vulnerability-scan-concise.js

@@ -19,7 +19,7 @@ const MAX_PACKAGES = 40;
 const MAX_RECOMMENDATIONS = 25;
 const IDS_PER_ROW = 3;
 /** One row per package version: worst graded severity, the fix that clears every fixable advisory. */
-export function groupByPackage(rows) {
+export function groupByPackage(rows, targets = {}) {
     const groups = new Map();
     for (const v of rows) {
         const key = `${v.ecosystem}\0${v.package}\0${v.current_version}`;
@@ -30,7 +30,8 @@ export function groupByPackage(rows) {
         const worst = vulns.reduce((a, b) => (SEVERITY_RANK[b.severity] > SEVERITY_RANK[a.severity] ? b : a));
         const fixes = vulns.map((v) => v.fixed_version).filter((f) => Boolean(f));
         const unfixed = vulns.length - fixes.length;
-        const fixed = fixes.length > 0 ? maxVersion(fixes, worst.ecosystem) : null;
+        const checked = targets[`${worst.package}@${worst.current_version}`];
+        const fixed = checked?.checked === "all_advisories" ? checked.target : fixes.length > 0 ? maxVersion(fixes, worst.ecosystem) : null;
         // Unknown (null) only when no advisory row knows; any direct row makes it direct.
         const direct = vulns.some((v) => v.is_direct === true) ? true : vulns.some((v) => v.is_direct === null) ? null : false;
         out.push({
@@ -40,6 +41,7 @@ export function groupByPackage(rows) {
             advisories: vulns.length,
             ids: vulns.slice(0, IDS_PER_ROW).map((v) => v.vuln_id),
             fixed_version: fixed,
+            fix_checked: checked?.checked ?? "installed_advisories_only",
             ...(unfixed > 0 ? { unfixed_advisories: unfixed } : {}),
             is_direct: direct,
             ...(vulns.every((v) => v.is_dev) ? { is_dev: true } : {}),
@@ -57,7 +59,7 @@ export function groupByPackage(rows) {
 export function conciseScanResult(full) {
     const names = (rows) => [...new Set(rows.map((v) => `${v.package}@${v.current_version}`))];
     const vulnerableDrift = full.install_drift.filter((row) => row.vulnerable_installed === true);
-    const packages = groupByPackage(full.vulnerabilities);
+    const packages = groupByPackage(full.vulnerabilities, full.fix_targets);
     const listed = packages.slice(0, MAX_PACKAGES);
     const recommendations = full.recommendations.slice(0, MAX_RECOMMENDATIONS);
     const omittedPackages = packages.length - listed.length;
@@ -69,6 +71,16 @@ export function conciseScanResult(full) {
         ecosystems_scanned: full.ecosystems_scanned,
         total_dependencies_scanned: full.total_dependencies_scanned,
         total_vulnerable_packages: full.total_vulnerable_packages,
+        ...(full.coverage
+            ? {
+                coverage: {
+                    complete: false,
+                    note: full.coverage.note,
+                    lockfiles_not_scanned: full.coverage.lockfiles_not_scanned,
+                    ...("unresolved_manifests" in full.coverage ? { unresolved_manifests: full.coverage.unresolved_manifests } : {}),
+                },
+            }
+            : {}),
         // Every listed advisory, before grouping and trimming.
         by_severity: full.by_severity,
         vulnerable_packages: listed,

package/dist/tools/vulnerability-scan-format.d.ts

@@ -4,13 +4,50 @@
  * provenance. Split out of vulnerability-scan.ts, which keeps execution.
  */
 import type { InstallDriftRecord, ResolutionProvenance, VulnerabilityScanResult } from "../live/types.js";
+import { type TreeDiscovery } from "../project-tree.js";
+import type { CleanTarget } from "../live/osv-ranges.js";
 /** What the formatter needs beyond the scan itself. */
 export interface ScanContext {
     resolution: ResolutionProvenance | null;
     reResolvedThisCall: boolean;
     drift: InstallDriftRecord[];
     includeDev: boolean;
+    /** What the project-tree walk left out; null when the set did not come from a walk. */
+    discovery?: TreeDiscovery | null;
+    /** Manifests with no lockfile, whose ranged dependencies were not scanned. */
+    unresolved?: Array<{
+        dir: string;
+        manifest: string;
+        ranges: number;
+    }>;
+    /**
+     * Upgrade targets checked against every advisory of the package, keyed by
+     * fixTargetKey(); absent when the check could not run (offline, budget).
+     */
+    verifiedTargets?: Map<string, CleanTarget>;
 }
+/** The key a verified target is stored under: one installed copy of a package. */
+export declare function fixTargetKey(ecosystem: string, name: string, version: string): string;
+/**
+ * What the scan did NOT cover, so a clean answer is never mistaken for a
+ * complete one: lockfiles past the project-tree bounds, and manifests with no
+ * lockfile (declared ranges are not installs, so they are not sent to OSV).
+ */
+export declare function scanCoverage(ctx: ScanContext, relative: (dir: string) => string, detailed: boolean): {
+    complete: boolean;
+    note: string;
+    lockfiles_not_scanned: number;
+    skipped_lockfiles?: {
+        path: string;
+        reason: "depth" | "project_limit";
+    }[] | undefined;
+    walk_truncated?: boolean | undefined;
+    unresolved_manifests?: {
+        manifest: string;
+        declared_ranges: number;
+        fix: string;
+    }[] | undefined;
+} | null;
 /**
  * Collapse advisories that are the same finding under different identifiers.
  *
@@ -36,6 +73,21 @@ export declare function relativeDir(dir: string, root: string): string;
 export declare function formatScanResult(result: VulnerabilityScanResult, severityFilter: string | undefined, ctx: ScanContext): {
     scan_time: string;
     project: string;
+    coverage?: {
+        complete: boolean;
+        note: string;
+        lockfiles_not_scanned: number;
+        skipped_lockfiles?: {
+            path: string;
+            reason: "depth" | "project_limit";
+        }[] | undefined;
+        walk_truncated?: boolean | undefined;
+        unresolved_manifests?: {
+            manifest: string;
+            declared_ranges: number;
+            fix: string;
+        }[] | undefined;
+    } | undefined;
     project_root: string;
     workspaces_with_findings: string[];
     host_platform: string;
@@ -113,6 +165,11 @@ export declare function formatScanResult(result: VulnerabilityScanResult, severi
     }[];
     install_drift: Record<string, unknown>[];
     recommendations: string[];
+    fix_targets: Record<string, {
+        target: string | null;
+        checked: "all_advisories" | "installed_advisories_only";
+        note?: string;
+    }>;
     clean_dependencies: number;
     scan_duration_ms: number;
     _meta: {
@@ -127,7 +184,7 @@ export declare function formatScanResult(result: VulnerabilityScanResult, severi
             resolved_at: string | null;
             lockfiles: {
                 path: string;
-                kind: "lockfile" | "manifest";
+                kind: "declared_ranges" | "lockfile" | "manifest";
                 mtime: string | null;
             }[];
             re_resolved_this_call: boolean;

package/dist/tools/vulnerability-scan-format.js

@@ -9,6 +9,55 @@ import { maxSemver } from "../live/semver-utils.js";
 import { isMaintenanceNotice } from "../live/maintenance.js";
 import { countBySeverity, presentedSeverity, scopeAdjustmentReason, SEVERITY_RANK, } from "../live/severity-scope.js";
 import { buildDriftView, groupDriftRows, lockfileAlsoAffected } from "./install-drift-notes.js";
+import { discoveryNote } from "../project-tree.js";
+import { targetNote } from "../live/fix-paths.js";
+import * as path from "node:path";
+/** The key a verified target is stored under: one installed copy of a package. */
+export function fixTargetKey(ecosystem, name, version) {
+    return `${ecosystem}\0${name}\0${version}`;
+}
+/** The command that writes the missing lockfile for a manifest. */
+function lockfileCommand(manifest) {
+    const base = path.basename(manifest);
+    return base === "Cargo.toml" ? "cargo generate-lockfile" : base === "package.json" ? "npm install --package-lock-only" : "your package manager's lock command";
+}
+/**
+ * What the scan did NOT cover, so a clean answer is never mistaken for a
+ * complete one: lockfiles past the project-tree bounds, and manifests with no
+ * lockfile (declared ranges are not installs, so they are not sent to OSV).
+ */
+export function scanCoverage(ctx, relative, detailed) {
+    const discovery = ctx.discovery ?? null;
+    const unresolved = ctx.unresolved ?? [];
+    const notes = [];
+    const walk = discoveryNote(discovery);
+    if (walk)
+        notes.push(walk);
+    const ranged = unresolved.reduce((n, u) => n + u.ranges, 0);
+    if (ranged > 0) {
+        notes.push(`${ranged} dependenc${ranged === 1 ? "y" : "ies"} in ${unresolved.length} manifest${unresolved.length === 1 ? "" : "s"} with no lockfile (${unresolved.slice(0, 3).map((u) => relative(u.manifest)).join(", ")}${unresolved.length > 3 ? ", ..." : ""}) ${ranged === 1 ? "is a declared range" : "are declared ranges"}, not installed versions, and were not checked: run ${[...new Set(unresolved.map((u) => lockfileCommand(u.manifest)))].join(" / ")} there to scan them.`);
+    }
+    if (notes.length === 0)
+        return null;
+    return {
+        complete: false,
+        note: notes.join(" "),
+        lockfiles_not_scanned: discovery?.skippedCount ?? 0,
+        ...(detailed && discovery && discovery.skipped.length > 0
+            ? { skipped_lockfiles: discovery.skipped.map((s) => ({ path: s.path, reason: s.reason })) }
+            : {}),
+        ...(discovery?.walkTruncated ? { walk_truncated: true } : {}),
+        ...(unresolved.length > 0
+            ? {
+                unresolved_manifests: unresolved.map((u) => ({
+                    manifest: relative(u.manifest),
+                    declared_ranges: u.ranges,
+                    fix: `${lockfileCommand(u.manifest)} in ${relative(u.dir)}`,
+                })),
+            }
+            : {}),
+    };
+}
 const SEVERITY_RULE = "`severity` is the grade every 4DA surface presents: a transitive-only dependency caps critical at high, and a dev-only dependency drops one level (critical to high, high to medium, medium to low). Unknown dev scope gets no discount. `advisory_severity` is the advisory's own tier (counted in `advisory_by_severity`); `by_severity` counts the presented grade.";
 const RESOLUTION_NOTE = "Dependency versions were read from these files at resolved_at. Every call re-checks them (stat only) and re-resolves when one changes. `cached` and `osv_cached` describe the OSV advisory lookup, not dependency resolution.";
 /**
@@ -112,9 +161,12 @@ export function formatScanResult(result, severityFilter, ctx) {
     // "project" label hides the fact that a repo root can span several
     // independently-versioned workspaces.
     const scannedProjects = [...new Set(vulns.flatMap((v) => v.sourceDirs ?? []).map(relative))].sort();
+    const coverage = scanCoverage(ctx, relative, true);
     return {
         scan_time: result.scannedAt,
         project: result.projectPath.split(/[/\\]/).pop() || result.projectPath,
+        // Present only when the scan is partial; read it before trusting a clean result.
+        ...(coverage ? { coverage } : {}),
         project_root: result.projectPath,
         // Workspaces under `project_root` that contributed a finding. Advisories
         // below are attributed per entry via `source_dirs`.
@@ -142,7 +194,12 @@ export function formatScanResult(result, severityFilter, ctx) {
         // npm direct dependencies whose node_modules copy is not what the lockfile
         // pins. The lockfile is what every other tool reads; this is what runs.
         install_drift: drift.rows,
-        recommendations: buildRecommendations(active, result.vulnerabilities, relative),
+        recommendations: buildRecommendations(active, result.vulnerabilities, relative, ctx.verifiedTargets),
+        // Per vulnerable package version: the upgrade target checked against every
+        // advisory OSV has for the package. A row's own `fixed_version` fixes
+        // that advisory only, and the highest of them can be affected by another
+        // (openssl 0.10.79, GHSA-phqj-4mhp-q6mq).
+        fix_targets: fixTargets(active, ctx.verifiedTargets),
         clean_dependencies: result.cleanCount,
         scan_duration_ms: result.scanDurationMs,
         _meta: {
@@ -171,7 +228,31 @@ export function formatScanResult(result, severityFilter, ctx) {
         },
     };
 }
-function buildRecommendations(active, all, relative) {
+/** `{ "openssl@0.10.38": { target, checked } }` for every vulnerable package version. */
+function fixTargets(active, verified) {
+    const out = {};
+    const byCopy = new Map();
+    for (const v of active) {
+        if (v.installDriftOf)
+            continue;
+        const key = fixTargetKey(v.ecosystem, v.package, v.currentVersion);
+        byCopy.set(key, [...(byCopy.get(key) ?? []), v]);
+    }
+    for (const [key, vulns] of byCopy) {
+        const label = `${vulns[0].package}@${vulns[0].currentVersion}`;
+        const clean = verified?.get(key);
+        if (clean) {
+            const note = targetNote(clean);
+            out[label] = { target: clean.target, checked: "all_advisories", ...(note ? { note } : {}) };
+        }
+        else {
+            const fixes = vulns.map((v) => v.fixedVersion).filter((f) => Boolean(f));
+            out[label] = { target: fixes.length > 0 ? maxSemver(fixes) : null, checked: "installed_advisories_only" };
+        }
+    }
+    return out;
+}
+function buildRecommendations(active, all, relative, verified) {
     const lines = [];
     const rankOf = (vulns) => Math.max(...vulns.map((v) => SEVERITY_RANK[presentedSeverity(v)]));
     // Name the manifest directories that actually pin the vulnerable version.
@@ -182,32 +263,47 @@ function buildRecommendations(active, all, relative) {
         return dirs.length > 0 ? ` in ${dirs.join(", ")}` : "";
     };
     // Recommendations are derived from platform-active, exploitable vulns only.
+    // One per installed VERSION, each advisory counted once: rsa 0.9.10 (in
+    // relay and src-tauri) and rsa 0.10.0-rc.18 shared RUSTSEC-2023-0071 and
+    // were merged into "rsa 0.9.10 in relay, src-tauri — 2 known
+    // vulnerabilities" (2026-10-07 eval): one advisory, two versions.
     const byPackage = new Map();
     for (const v of active) {
         if (v.installDriftOf)
             continue; // reinstall advice below, not an upgrade
-        const list = byPackage.get(v.package);
-        if (list)
-            list.push(v);
-        else
-            byPackage.set(v.package, [v]);
+        const key = `${v.ecosystem}\0${v.package}\0${v.currentVersion}`;
+        const group = byPackage.get(key) ?? { unique: [], copies: [] };
+        // Every copy names a place; the same advisory on another copy is one finding.
+        group.copies.push(v);
+        if (!group.unique.some((seen) => seen.vulnId === v.vulnId))
+            group.unique.push(v);
+        byPackage.set(key, group);
     }
-    for (const [pkg, pkgVulns] of byPackage) {
+    for (const { unique: pkgVulns, copies } of byPackage.values()) {
+        const pkg = pkgVulns[0].package;
         const highest = pkgVulns[0];
         const breakdown = severityBreakdown(pkgVulns);
         // Target the HIGHEST published fix so the upgrade resolves every fixable CVE,
         // not just the first one. (The old code picked the first fix version, which
         // could leave higher-version-gated CVEs unfixed while claiming to fix them.)
-        const target = maxSemver(pkgVulns.map((v) => v.fixedVersion).filter((v) => Boolean(v)));
+        const highestFix = maxSemver(pkgVulns.map((v) => v.fixedVersion).filter((v) => Boolean(v)));
+        // Checked against every advisory of the package when that could run: the
+        // highest per-advisory fix can itself be affected by another advisory.
+        const clean = verified?.get(fixTargetKey(highest.ecosystem, pkg, highest.currentVersion));
+        const target = clean ? clean.target : highestFix;
         const total = pkgVulns.length;
         const fixable = pkgVulns.filter((v) => v.fixedVersion).length;
-        const where = whereOf(pkgVulns);
+        const where = whereOf(copies);
         let text;
         if (target) {
             const scope = fixable === total
                 ? `${total} CVE${total > 1 ? "s" : ""}`
                 : `${fixable} of ${total} CVEs (${total - fixable} with no published fix)`;
-            text = `Upgrade ${pkg} ${highest.currentVersion} → ${target}${where} — resolves ${scope} [${breakdown}]`;
+            const note = clean ? targetNote(clean) : null;
+            text = `Upgrade ${pkg} ${highest.currentVersion} → ${target}${where} — resolves ${scope} [${breakdown}]${note ? ` (${note})` : ""}`;
+        }
+        else if (clean && highestFix) {
+            text = `Review ${pkg} ${highest.currentVersion}${where} — ${total} known vulnerabilit${total > 1 ? "ies" : "y"} [${breakdown}]; no published version clears every advisory (${clean.floor} is still affected by ${clean.stillAffectedBy.join(", ")})`;
         }
         else {
             text = `Review ${pkg} ${highest.currentVersion}${where} — ${total} known vulnerabilit${total > 1 ? "ies" : "y"} [${breakdown}], no fix version published`;