@4da/mcp-server 6.2.4 → 6.2.5

package/dist/tools/upgrade-impact-literals.js

@@ -20,6 +20,27 @@ import path from "node:path";
 /** Punctuation that makes a fragment syntax rather than a name. */
 const SYNTAX_CHARS = /[/:*{}?$%@#<>]/g;
 const WORD = /[A-Za-z_][\w-]*/g;
+/** WORD, with a Rust raw identifier (`r#type`) read as one token. */
+const WORD_OR_RAW = /r#[A-Za-z_]\w*|[A-Za-z_][\w-]*/g;
+/**
+ * The part of an entry that names the OLD syntax. "from X to Y" -> X;
+ * "... instead of X" -> X; otherwise the text before the replacement is named
+ * (";", "use", "instead", "in favour of", "replaced by/with", "->", "now").
+ * Before 6.2.5 the whole entry was read when it had no "from ... to", so
+ * thiserror 2's "`{r#type}` ... is no longer accepted; simply use ... `{type}`"
+ * took the new `{type}` for the old syntax and flagged every `{name}` format
+ * string in the project (audit 2026-10-12, B-7).
+ */
+function oldSide(text) {
+    const fromTo = /\bfrom\b([\s\S]*?)\bto\b/i.exec(text);
+    if (fromTo)
+        return fromTo[1];
+    const insteadOf = /\binstead of\b([\s\S]*)$/i.exec(text);
+    if (insteadOf)
+        return insteadOf[1];
+    const cut = /;|\binstead\b|\buse\b|\bin favou?r of\b|\breplaced? (?:by|with)\b|->|→|\bnow\b/i.exec(text);
+    return cut ? text.slice(0, cut.index) : text;
+}
 const MAX_FILES = 300;
 const MAX_FILE_BYTES = 512 * 1024;
 const MAX_HITS_PER_ENTRY = 5;
@@ -32,8 +53,7 @@ function escapeRegex(text) {
  * migrated project already uses) is never reported as needing a change.
  */
 export function oldSyntaxShapes(entryText) {
-    const fromTo = /\bfrom\b([\s\S]*?)\bto\b/i.exec(entryText);
-    const scope = fromTo ? fromTo[1] : entryText;
+    const scope = oldSide(entryText);
     const shapes = [];
     for (const [, fragment] of scope.matchAll(/`([^`\s]{2,40})`/g)) {
         // A path or call (`Router::route`, `res.json()`, `a.b`) is a symbol, not syntax.
@@ -45,8 +65,10 @@ export function oldSyntaxShapes(entryText) {
             continue;
         let pattern = "";
         let last = 0;
-        for (const m of fragment.matchAll(WORD)) {
-            pattern += escapeRegex(fragment.slice(last, m.index)) + "[A-Za-z_][\\w-]*";
+        for (const m of fragment.matchAll(WORD_OR_RAW)) {
+            // A Rust raw identifier keeps its `r#`: `{r#type}` is not any `{x#y}`.
+            const placeholder = m[0].startsWith("r#") ? "r#[A-Za-z_]\\w*" : "[A-Za-z_][\\w-]*";
+            pattern += escapeRegex(fragment.slice(last, m.index)) + placeholder;
             last = (m.index ?? 0) + m[0].length;
         }
         pattern += escapeRegex(fragment.slice(last));

package/dist/tools/upgrade-impact-report.d.ts

@@ -28,6 +28,8 @@ export interface ReportEntry {
     details?: string[];
     touches_your_code?: boolean;
     matched_symbols?: string[];
+    /** Cargo features this project enables that the entry names (a renamed or removed feature). */
+    matched_features?: string[];
     /** String literals in your code that use the syntax this entry retires (route patterns and the like). */
     matched_literals?: Array<{
         file: string;
@@ -55,7 +57,9 @@ export interface ShapedChangelog {
     duplicates?: number;
 }
 /** Flag, order and trim changelog sections. Counts always cover every entry, trimmed or not. */
-export declare function shapeChangelog(sections: ChangelogSection[], symbols: string[], format: ResponseFormat): ShapedChangelog;
+export declare function shapeChangelog(sections: ChangelogSection[], symbols: string[], format: ResponseFormat, 
+/** Cargo features the project enables on the crate (upgrade-impact-features.ts). */
+features?: string[]): ShapedChangelog;
 export type UpgradeType = "patch" | "minor" | "major" | "prerelease" | "unknown";
 /**
  * Upgrade class by semver. A 0.x minor bump is reported as "major": under

package/dist/tools/upgrade-impact-report.js

@@ -20,12 +20,15 @@
 import { classifyHeading } from "../live/changelog-classify.js";
 import { compareVersionPrecedence, parseSemverPrecedence } from "../live/semver-precedence.js";
 import { matchSymbols } from "./upgrade-impact-callsites.js";
+import { matchFeatures } from "./upgrade-impact-features.js";
 const CONCISE_NEUTRAL_PER_VERSION = 20;
 const CONCISE_ADDITIVE_PER_VERSION = 3;
 const DETAILED_ENTRY_CAP = 400;
 const KIND_ORDER = { breaking: 0, security: 1, deprecation: 2, change: 3 };
 /** Flag, order and trim changelog sections. Counts always cover every entry, trimmed or not. */
-export function shapeChangelog(sections, symbols, format) {
+export function shapeChangelog(sections, symbols, format, 
+/** Cargo features the project enables on the crate (upgrade-impact-features.ts). */
+features = []) {
     const out = {
         sections: [], breaking: 0, deprecations: 0, security: 0, touching: 0, touchingSymbols: [],
     };
@@ -37,7 +40,17 @@ export function shapeChangelog(sections, symbols, format) {
     // once. Measured 2026-10-02 in an agent eval: axum 0.7.9 -> 0.8.4 reported
     // "20 breaking changes" for about ten distinct ones.
     const seen = new Set();
-    const key = (text) => text.toLowerCase().replace(/\(\[?#\d+\]?\)|\[#\d+\]|#\d+/g, "").replace(/[^a-z0-9]+/g, " ").trim();
+    // GitHub release notes list a change twice: the summary line, then the PR
+    // line with its conventional-commit prefix and "by @user in <url>" (reqwest
+    // 0.13: 12 such pairs). Neither makes it a different change.
+    const key = (text) => text
+        .toLowerCase()
+        .replace(/\s+by @[\w.-]+(?:\[bot\])?\s+in\s+https?:\/\/\S+/g, "")
+        .replace(/https?:\/\/\S+/g, "")
+        .replace(/^\W*(?:feat|fix|chore|docs|refactor|perf|test|build|ci|style|deps)(?:\([^)]*\))?!?:\s*/, "")
+        .replace(/\(\[?#\d+\]?\)|\[#\d+\]|#\d+/g, "")
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
     for (const section of sections) {
         const unique = section.entries.filter((e) => {
             const k = key(e.text);
@@ -58,13 +71,19 @@ export function shapeChangelog(sections, symbols, format) {
             };
             if (e.kind === "breaking" || e.kind === "deprecation") {
                 // The nested points name the affected functions (date-fns 3.0) as often as the entry does.
-                const matched = matchSymbols([e.text, ...(e.details ?? [])].join(" "), symbols);
-                if (matched.length > 0) {
-                    entry.touches_your_code = true;
+                const text = [e.text, ...(e.details ?? [])].join(" ");
+                const matched = matchSymbols(text, symbols);
+                const matchedFeatures = matchFeatures(text, features);
+                if (matched.length > 0)
                     entry.matched_symbols = matched;
+                if (matchedFeatures.length > 0)
+                    entry.matched_features = matchedFeatures;
+                if (matched.length > 0 || matchedFeatures.length > 0) {
+                    entry.touches_your_code = true;
                     if (e.kind === "breaking") {
                         out.touching++;
                         matched.forEach((s) => touched.add(s));
+                        matchedFeatures.forEach((f) => touched.add(`feature "${f}"`));
                     }
                 }
             }
@@ -208,6 +227,8 @@ export function summarize(input) {
             breaking = flagged;
         if (input.changelogFrom)
             breaking += ` (from ${input.changelogFrom})`;
+        if (input.changelog === "partial" && input.githubHint)
+            breaking += ` (the changelog covers only part of the range${hint})`;
     }
     const advisories = input.advisoriesFixed === null ? "advisories unknown (OSV unreachable)" : `${input.advisoriesFixed} advisories fixed`;
     const path = input.pathChange

package/dist/tools/upgrade-impact.js

@@ -36,6 +36,7 @@ import { enrichGoVersions, goBasePath, goMajorPath, goPathMajor, goTagPrefix, go
 import { scanCallSites } from "./upgrade-impact-callsites.js";
 import { resolveChangelog } from "./upgrade-impact-changelog.js";
 import { pythonImportNames } from "./upgrade-impact-imports.js";
+import { projectCargoFeatures } from "./upgrade-impact-features.js";
 import { flagOldSyntax } from "./upgrade-impact-literals.js";
 import { nearestVersions, shapeChangelog, summarize, upgradeType } from "./upgrade-impact-report.js";
 /**
@@ -319,7 +320,9 @@ export async function analyzeUpgradeImpact(params, ctx) {
             : Promise.resolve({ total_files: 0, files: [], symbols_used: [] }),
     ]);
     const { changelog, range } = resolved;
-    const shaped = shapeChangelog(range.sections, yourCode.symbols_used, params.response_format === "detailed" ? "detailed" : "concise");
+    // Cargo features this project enables on the crate: a renamed or removed one is a breaking change symbols cannot see.
+    const features = eco === "crates.io" ? projectCargoFeatures(ctx.projectRoot, index.name, ctx.installed) : [];
+    const shaped = shapeChangelog(range.sections, yourCode.symbols_used, params.response_format === "detailed" ? "detailed" : "concise", features);
     // Route and pattern syntax the upgrade retires, found in this project's string literals.
     const literal = await flagOldSyntax(shaped.sections, yourCode.files, ctx.projectRoot);
     shaped.touching += literal.newlyTouching;
@@ -380,7 +383,9 @@ export async function analyzeUpgradeImpact(params, ctx) {
             : {}),
         your_code: py
             ? { ...yourCode, import_names: py.names, import_name_source: py.source, import_name_note: importNameNote(py, index.name) }
-            : yourCode,
+            : features.length > 0
+                ? { ...yourCode, cargo_features: features }
+                : yourCode,
         advisories_fixed: advisoriesFixed,
         advisories_remaining: advTo,
         ...(advFrom === null || advTo === null ? { advisories_note: "OSV.dev could not be reached; advisory fields are null, not empty." } : {}),
@@ -403,7 +408,9 @@ export async function analyzeUpgradeImpact(params, ctx) {
             touchingSymbols: shaped.touchingSymbols,
             changelog: !changelog.found ? "missing" : !counted ? "no_entries" : range.coversRange ? "complete" : "partial",
             changelogFrom: fromGithub ? "GitHub release notes" : null,
-            githubHint: resolved.github_fallback?.how_to_enable ? "FOURDA_GITHUB_CHANGELOG=true reads GitHub release notes" : null,
+            githubHint: resolved.github_fallback?.how_to_enable
+                ? "to read the GitHub release notes, set FOURDA_GITHUB_CHANGELOG=true in this MCP server's environment (opt-in; see github_fallback)"
+                : null,
             advisoriesFixed: advisoriesFixed ? advisoriesFixed.length : null,
             pathChange: pathChange ? { from: fromName, to: targetName, files: yourCode.total_files } : null,
         }),

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

@@ -2,13 +2,109 @@
  * Fix-path verification for upgrade_planner steps (see live/fix-paths.ts):
  * the target must clear EVERY known advisory of the package, and a
  * transitive step is "waiting on upstream" only when a parent's declared
- * requirement actually excludes every clean version.
+ * requirement actually excludes every clean version AND nothing about the
+ * parent's releases could be read.
  *
- * Runs on the steps the plan returns, within a time budget. A step whose
- * lookups fail or run out of time keeps its unverified answer and says so in
- * `fixPathChecked`.
+ * When a parent blocks the refresh and has a newer release, the step names
+ * the move (readiness audit H1, 2026-10-16; the 4DA app's
+ * `evidence/upgrade_parent.rs::parent_move`): the smallest parent release
+ * whose own declared requirement admits a clean version, read from the
+ * registry, and that is itself clear of the parent's own advisories; then
+ * the dependency the project DECLARES that moves it, the parent itself or
+ * every declared dependency it arrives through (readiness review
+ * 2026-10-17). A parent the walk cannot tie to a declaration names no lever
+ * and no command: `npm install <transitive>@v` would add it as a direct
+ * dependency. When the new requirement still admits the installed copy, an
+ * install keeps that copy (npm 10.9.2, checked 2026-10-17: express 4.21.2 ->
+ * 4.22.0 kept path-to-regexp 0.1.12 under `~0.1.12`), so the step names the
+ * refresh that follows.
+ *
+ * Runs on the steps the plan returns, within a time budget, each on a draft
+ * of its step: a lookup that runs out of time never writes to the step
+ * afterwards. A step whose lookups fail or run out of time keeps its
+ * unverified answer and says so in `fixPathChecked`.
  */
 import type { LiveIntelligence } from "../live/index.js";
+import { type LockfileFormat } from "../live/lockfile-parents.js";
+/** One dependency the project declares that moves a blocking parent. */
+export interface ParentLever {
+    name: string;
+    version: string;
+    /** The release of it that brings the fix in; null when it could not be worked out (the reason says what to check). */
+    to: string | null;
+    /** True when `to` crosses a major version (a 0.x minor counts). */
+    breaking: boolean;
+    /** The command that moves it to `to`, per declaring project directory (the declared operator kept). */
+    commands?: Array<{
+        dir: string;
+        command: string;
+        refresh?: true;
+    }>;
+    /** A manifest edit, where no single verified command makes it (a workspace-inherited crate, a requirements pin). */
+    instructions?: Array<{
+        dir: string;
+        instruction: string;
+    }>;
+    /** Set only when `to` was lifted above it (one release per dependency): the lever's OWN smallest release that brings the fix in. */
+    smallest?: string;
+    /** Through a transitive parent: the parent's smallest release that admits a clean copy, which the lever must bring in at least. */
+    floor?: string;
+    /** Through a transitive parent: the parent release `to` brings in. */
+    brings?: string;
+    /**
+     * Set when this lever names no release although the parent's release is known (the app's
+     * per-lever ParentStanding, pr-011): it is flagged malicious, every release that would bring the
+     * fix in brings in an advisory it lacks, none does, or it is already at its latest release.
+     */
+    outcome?: "malicious" | StuckOutcome;
+}
+/**
+ * One blocking parent that can move: the release of it that admits a clean
+ * version of the package, and the declared dependencies that move it.
+ */
+export interface ParentUpgrade {
+    /** The installed parent whose requirement excludes every clean version. */
+    parent: string;
+    from: string;
+    /** The smallest release of `parent` clear of its own advisories whose requirement admits a clean version (raised to the one release its lever names); null when its requirements could not be read, or when it leaves the tree (`goesAway`). */
+    to: string | null;
+    /** True when `to` crosses a major version of `parent` (mongodb 2.2.36 -> 3.1.3). */
+    breaking: boolean;
+    /** `to`'s requirement on the package; null when `to` no longer depends on it. Absent when `to` is null. */
+    requirement?: string | null;
+    /** True when `to` declares the package only as a peer dependency (npm 7+ installs it). */
+    peer?: boolean;
+    /** The version `to`'s requirement resolves the package to (its newest match), when the registry's version list was read. */
+    resolvesTo?: string | null;
+    /** When `to` is null: the parent's newest release, which may or may not admit a clean version. */
+    latest?: string;
+    /** Set only when `to` was lifted above it (one release per dependency): the parent's own smallest release that admits a clean copy. */
+    smallest?: string;
+    /**
+     * The parent will not move (no release admits a clean version, or it is already its newest), but
+     * every declared dependency it arrives through has a release that no longer brings it in: the
+     * levers name those releases, and the vulnerable copy goes away from that path with them (`to`
+     * is then null, as the parent leaves the tree).
+     */
+    goesAway?: boolean;
+    /**
+     * What the project declares and bumps: the parent itself when a manifest declares it, else
+     * every declared dependency it arrives through (at most three; `moreLevers` counts the
+     * rest). Empty when none could be tied to a declaration: then `leverUnknown` says why and
+     * no command is named.
+     */
+    levers: ParentLever[];
+    moreLevers?: number;
+    leverUnknown?: string;
+    /**
+     * The refresh to run after the lever's install: the new requirement still admits the
+     * installed copy, which an install keeps (npm 10.9.2), so the install alone does not fix it.
+     */
+    refreshCommands?: Array<{
+        dir: string;
+        command: string;
+    }>;
+}
 /** The planner fields this step reads and rewrites. */
 export interface FixPathStep {
     package: string;
@@ -30,6 +126,25 @@ export interface FixPathStep {
     }>;
     /** lockfile_refresh: true when not every parent's requirement could be read and the verdict comes from semver compatibility. */
     refreshInferred?: boolean;
+    /** upgrade_direct: the command that moves the declared dependency to targetVersion, per declaring project directory. */
+    upgradeCommands?: Array<{
+        dir: string;
+        command: string;
+        refresh?: true;
+    }>;
+    /** upgrade_direct: a manifest edit where no single verified command makes it. */
+    upgradeInstructions?: Array<{
+        dir: string;
+        instruction: string;
+    }>;
+    /** upgrade_parent / override_or_replace: the releases of the blocking parents that admit a clean version. */
+    parentUpgrades?: ParentUpgrade[];
+    /**
+     * Releases the registry withdrew (yanked, deprecated) that the target steps over; with no
+     * target, the only releases that fixed it (FX-H5). The reasons say which and why.
+     */
+    withheld?: string[];
+    isDev?: boolean;
 }
 export interface FixPathInput {
     step: FixPathStep;
@@ -37,6 +152,48 @@ export interface FixPathInput {
     fixes: string[];
     /** Manifest directories that pin this copy (the scan's sourceDirs). */
     sourceDirs: string[];
+    /** Advisories (one per alias group) that name no fixed version: `id` to print, `ids` every id of the group (M2). */
+    unfixed?: Array<{
+        id: string;
+        ids: string[];
+    }>;
 }
+type Intel = Pick<LiveIntelligence, "getFixPathSources" | "lockfileFor" | "getProjectRoot" | "getResolvedDeps"> & Partial<Pick<LiveIntelligence, "queryAdvisories">>;
 /** Verify and rewrite the steps in place. Returns how many could not be verified (offline, failure, budget). */
-export declare function verifyFixPaths(inputs: FixPathInput[], liveIntel: Pick<LiveIntelligence, "getFixPathSources" | "lockfileFor" | "getProjectRoot">, budgetMs?: number): Promise<number>;
+export declare function verifyFixPaths(inputs: FixPathInput[], liveIntel: Intel, budgetMs?: number): Promise<number>;
+/**
+ * Each blocking parent of a planned step, in the app's ParentStanding terms: a release (the parent
+ * upgrade), or deprecated / latest / none_admits / unread / undecided / malicious.
+ */
+export declare function parentOutcomes(step: FixPathStep): Array<{
+    parent: string;
+    from: string;
+    outcome: string;
+    upgrade?: ParentUpgrade;
+}>;
+/** The 4DA app's ParentStanding names, for what a parent cannot do (parent_release vectors). */
+export type StuckOutcome = "deprecated" | "latest" | "none_admits" | "introduces";
+/**
+ * One release per dependency across ALL rows (final release audit of 6.2.5, finding 4; readiness
+ * review 2026-10-17, finding 2). NodeGoat named express-session 1.18.1 on the cookie row, 1.18.2 on
+ * the on-headers row and 1.19.0 on its own row (and 1.18.1 still requires on-headers ~1.0.2,
+ * which is vulnerable); xsv named crossbeam-channel 0.4.4 on its own row and 0.5.0 as a lever.
+ *
+ * Per declared dependency, the release is the highest of what its rows need (each lever's
+ * release, its own row's target) that
+ * - crosses no major the installed version is not already crossed by a row's only fix (a row
+ *   whose only fix is across a major makes the release breaking, and it is flagged);
+ * - no advisory of the dependency affects (the predicate dependency_check decides by);
+ * - still brings in every lever's fix (each lever's own check at that release).
+ * Every row that names the dependency then gives that release and that command, and everything
+ * derived from the release is recomputed at it (the parent's requirement and resolvesTo, the
+ * refresh that follows or not: 7b). A dependency for which no release passes is left as it is,
+ * and its rows say why.
+ *
+ * The advisory lookups are bounded (RECONCILE_BUDGET_MS); a release that could not be checked in
+ * time is not chosen, and nothing is written after the budget runs out.
+ */
+export declare function reconcileDirectTargets(steps: FixPathStep[], inputs: FixPathInput[], liveIntel: Intel, budgetMs?: number): Promise<void>;
+/** How to force one transitive version, per lockfile format. */
+export declare function overrideHint(format: LockfileFormat, name: string, target: string): string;
+export {};

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

@@ -25,6 +25,8 @@
 import type { FourDADatabase } from "../db.js";
 import type { LiveIntelligence } from "../live/index.js";
 import { type AppPlanResult } from "./app-plan.js";
+import { type ParentUpgrade } from "./upgrade-planner-fixpaths.js";
+import type { VulnerabilityCoverage } from "../live/types.js";
 export interface UpgradePlannerParams {
     include_dev?: boolean;
     max_recommendations?: number;
@@ -63,10 +65,33 @@ interface UpgradeRecommendation {
      * none could be read and the target leaves the semver-compatible range);
      * `reinstall` = the lockfile's version is fine
      * but node_modules holds another one, so the fix is `installFix`;
+     * `upgrade_parent` = transitive, a parent's requirement excludes every clean
+     * version and a newer release of that parent exists: `parentUpgrades` names
+     * the smallest release whose own requirement admits a clean version (read
+     * from the registry), through the direct dependency it arrives by when the
+     * parent is transitive, or the parent's newest release to check when its
+     * requirements could not be read;
+     * `override_or_replace` = transitive, a parent's requirement excludes every
+     * clean version and that parent will not move (deprecated, already at its
+     * latest release, or no release up to the latest admits one): force the version (npm `overrides`, pnpm
+     * `pnpm.overrides`, yarn `resolutions`, Cargo `[patch]`) or replace the parent;
      * `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.
+     * `not_built_on_this_host` = every advisory is against code this host never compiles;
+     * `upgrade_parent_unverified` = transitive, a parent release that admits a clean version exists,
+     * but no release of the declared dependency that brings it in was verified (every lever's `to`
+     * is null): `parentUpgrades` says what to check; nothing is counted as fixed;
+     * `remove_dependency` = the installed copy is flagged malicious and no release is clean of
+     * it (crossenv: 1.0.0 and 1.0.1 are malware), or the installed version is a placeholder and every
+     * newer release is known-affected: remove or replace the dependency. A malware record with a
+     * clean later release (fsevents 1.2.9, MAL-2023-462, clean from 1.2.11) is an upgrade instead;
+     * `hold_current` = no advisory affects the installed version, and every newer release is
+     * known-affected or withdrawn: stay on it (the reasons say why).
+     * Every release a row offers, the newest one included, is checked against the package's
+     * advisories and the registry's withdrawals, as dependency_check checks one.
      */
-    action: "upgrade_direct" | "lockfile_refresh" | "waiting_on_upstream" | "reinstall" | "no_fix_available" | "not_built_on_this_host";
+    action: "upgrade_direct" | "lockfile_refresh" | "upgrade_parent" | "upgrade_parent_unverified" | "waiting_on_upstream" | "override_or_replace" | "reinstall" | "no_fix_available" | "not_built_on_this_host" | "remove_dependency" | "hold_current";
+    /** upgrade_parent / override_or_replace: the parent release that admits a clean version, per blocking parent that can move. */
+    parentUpgrades?: ParentUpgrade[];
     /**
      * For a vulnerable package: whether the target was checked against EVERY
      * known advisory of the package (`all_advisories`), or only against the
@@ -75,11 +100,37 @@ interface UpgradeRecommendation {
      * affected by an advisory the installed version predates).
      */
     fixPathChecked?: "all_advisories" | "installed_advisories_only";
+    /**
+     * Releases the registry withdrew (crates.io/PyPI yanked; npm deprecated with a later clean
+     * release on its line) that targetVersion steps over, or, with no target, the only releases
+     * that fixed it: "no installable fix", not "no fix published". The reasons say why (FX-H5).
+     */
+    withheld?: string[];
     /** lockfile_refresh: the command to run, per lockfile directory. */
     refreshCommands?: Array<{
         dir: string;
         command: string;
     }>;
+    /**
+     * upgrade_direct: the command that moves the declared dependency to
+     * targetVersion where it is declared, per lockfile directory (npm install,
+     * pnpm up, yarn upgrade / yarn up, cargo add with --dev for a
+     * dev-dependency). Absent for tools no command is named for.
+     */
+    upgradeCommands?: Array<{
+        dir: string;
+        command: string;
+        refresh?: true;
+    }>;
+    /**
+     * upgrade_direct: a manifest edit where no single verified command makes it (a workspace-inherited
+     * crate, a requirements.txt pin). Also on a PyPI row, direct or transitive, whose pin sits in a
+     * compiled requirements file: the re-compile with `--upgrade-package` (audit 6.2.5 A-4).
+     */
+    upgradeInstructions?: Array<{
+        dir: string;
+        instruction: string;
+    }>;
     /**
      * lockfile_refresh: true when not every parent's requirement could be read
      * (none read excludes the target) and the target is semver-compatible with
@@ -95,7 +146,7 @@ interface UpgradeRecommendation {
     /** No lockfile: the manifest's declared requirement; `currentVersion` is its floor, not an install. */
     declaredRange?: string;
 }
-interface UpgradePlanResult {
+export interface UpgradePlanResult {
     generatedAt: string;
     projectPath: string;
     totalDeps: number;
@@ -106,8 +157,12 @@ interface UpgradePlanResult {
     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. */
+    /** Transitive steps fixed by upgrading the parent that pins them (`parentUpgrades` names the release). */
+    parentUpgradeSteps: number;
+    /** False unless OSV answered for EVERY dependency in scope: a plan over missing or partial data is not CVE-aware. */
     vulnerabilityDataAvailable: boolean;
+    /** Present when the vulnerability check is missing or incomplete: what was not checked and why. */
+    vulnerabilityCoverage?: VulnerabilityCoverage;
     provenance: {
         mode: "standalone_heuristic";
         note: string;