@openrewrite/recipes-nodejs 0.37.0-20260104-170507 → 0.37.0-20260106-082310

package/src/security/dependency-vulnerability-check.ts

@@ -37,6 +37,11 @@ import {
 import * as semver from "semver";
 import * as path from "path";
 import {parseSeverity, Severity, severityOrdinal, Vulnerability, VulnerabilityDatabase} from "./vulnerability";
+import {
+    findDirectUpgradeThatFixesTransitive,
+    extractVersionFromLockFile,
+    DependencyScope as NpmUtilsDependencyScope
+} from "./npm-utils";
 
 /**
  * All dependency scopes that can contain dependencies in package.json.
@@ -51,6 +56,23 @@ const ALL_DEPENDENCY_SCOPES: DependencyScope[] = [
  */
 export type UpgradeDelta = 'none' | 'patch' | 'minor' | 'major';
 
+/**
+ * Strategy for handling transitive dependency vulnerabilities.
+ *
+ * - 'report': Report transitive vulnerabilities but don't fix them. (Default)
+ * - 'override': Add overrides/resolutions for transitives that aren't fixed
+ *               by direct dependency upgrades. Runs an extra npm install
+ *               to check which transitives are still vulnerable after
+ *               applying direct fixes, then adds overrides only for those.
+ * - 'prefer-direct-upgrade': First applies minimum direct dependency upgrades,
+ *                            then for any remaining transitive vulnerabilities,
+ *                            tries to find a higher direct dependency version
+ *                            that fixes them. Falls back to overrides if no
+ *                            suitable direct upgrade exists. Queries npm registry.
+ *                            Most thorough, slowest.
+ */
+export type TransitiveFixStrategy = 'report' | 'override' | 'prefer-direct-upgrade';
+
 /**
  * Row for the vulnerability report data table.
  */
@@ -194,18 +216,43 @@ interface VulnerableDependency {
  * Represents a fix to apply for a vulnerability.
  */
 interface VulnerabilityFix {
-    /** Package name to upgrade */
+    /** Package name to upgrade (the vulnerable package) */
     packageName: string;
     /** Version to upgrade to */
     newVersion: string;
-    /** Whether this is a transitive dependency fix */
+    /** Whether the vulnerable package is a transitive dependency */
     isTransitive: boolean;
     /** CVEs this fix resolves */
     cves: string[];
+    /** CVE summaries for generating comments (CVE ID -> summary) */
+    cveSummaries: Map<string, string>;
     /** The scope where this dependency was found (for direct deps) */
     scope?: DependencyScope;
     /** The original major version (for version-specific overrides) */
     originalMajorVersion?: number;
+    /**
+     * For transitive vulnerabilities, info about the direct dependency that brings
+     * this transitive in. Used by prefer-direct-upgrade to find higher versions
+     * of the direct dependency that might fix the transitive.
+     */
+    directDepInfo?: {
+        name: string;
+        version: string;
+        scope: DependencyScope;
+    };
+    /**
+     * If set, fix this transitive vulnerability by upgrading a direct dependency
+     * instead of using overrides. This is preferred when a newer version of a
+     * direct dependency includes a fixed version of the vulnerable transitive.
+     */
+    fixViaDirectUpgrade?: {
+        /** Name of the direct dependency to upgrade */
+        directDepName: string;
+        /** Version to upgrade the direct dependency to */
+        directDepVersion: string;
+        /** Scope of the direct dependency */
+        directDepScope: DependencyScope;
+    };
 }
 
 /**
@@ -285,14 +332,17 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
     scope?: DependencyScope;
 
     @Option({
-        displayName: "Override transitives",
-        description: "When enabled, transitive dependencies with vulnerabilities will have their versions overridden " +
-            "using npm overrides, yarn resolutions, or pnpm overrides. " +
-            "By default only direct dependencies have their version numbers upgraded.",
+        displayName: "Transitive fix strategy",
+        description: "Strategy for handling transitive dependency vulnerabilities. " +
+            "'report' only reports them without fixing. " +
+            "'override' adds overrides only for transitives not fixed by direct upgrades (runs extra npm install to verify). " +
+            "'prefer-direct-upgrade' tries to find higher direct dependency versions that fix transitives, falls back to overrides (queries npm registry). " +
+            "Default is 'report'.",
         required: false,
-        example: "true"
+        example: "override",
+        valid: ["report", "override", "prefer-direct-upgrade"]
     })
-    overrideTransitive?: boolean;
+    transitiveFixStrategy?: TransitiveFixStrategy;
 
     @Option({
         displayName: "Maximum upgrade delta",
@@ -341,21 +391,34 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
     })
     fixDeclaredVersions?: boolean;
 
+    @Option({
+        displayName: "Add override comments",
+        description: "When enabled, adds a comment field (e.g., '//overrides') alongside overrides to document which CVEs " +
+            "each override is fixing. This helps with auditing and knowing when overrides can be removed. " +
+            "Default is true.",
+        required: false,
+        example: "true"
+    })
+    addOverrideComments?: boolean;
+
     /** Cached compiled regex for CVE pattern matching */
     private cvePatternRegex?: RegExp;
 
     constructor(options?: {
         scope?: DependencyScope;
-        overrideTransitive?: boolean;
+        transitiveFixStrategy?: TransitiveFixStrategy;
         maximumUpgradeDelta?: UpgradeDelta;
         minimumSeverity?: string;
         cvePattern?: string;
         fixDeclaredVersions?: boolean;
+        addOverrideComments?: boolean;
     }) {
         super(options);
+        this.transitiveFixStrategy ??= 'report';
         this.maximumUpgradeDelta ??= 'patch';
         this.minimumSeverity ??= Severity.LOW;
         this.fixDeclaredVersions ??= false;
+        this.addOverrideComments ??= true;
         if (options?.minimumSeverity) {
             this.minimumSeverity = parseSeverity(options.minimumSeverity);
         }
@@ -369,6 +432,102 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
         }
     }
 
+    /**
+     * Returns true if transitive vulnerabilities should be scanned.
+     */
+    private shouldScanTransitives(): boolean {
+        return this.transitiveFixStrategy !== 'report';
+    }
+
+    /**
+     * Returns true if transitive vulnerabilities should be fixed with overrides.
+     */
+    private shouldFixTransitives(): boolean {
+        return this.transitiveFixStrategy !== 'report';
+    }
+
+    /**
+     * Returns true if we should verify that transitive fixes are still needed
+     * after applying direct fixes (for override and prefer-direct-upgrade strategies).
+     */
+    private shouldVerifyTransitiveFixes(): boolean {
+        return this.transitiveFixStrategy === 'override' ||
+            this.transitiveFixStrategy === 'prefer-direct-upgrade';
+    }
+
+    /**
+     * Filters out transitive fixes that are no longer needed based on the lock file
+     * after applying direct fixes. Returns only the fixes that are still required.
+     *
+     * @param fixes All computed fixes
+     * @param lockFileContent The lock file content after applying direct fixes
+     * @param packageManager The package manager used
+     * @param db The vulnerability database
+     */
+    private filterRemainingTransitiveFixes(
+        fixes: VulnerabilityFix[],
+        lockFileContent: string,
+        packageManager: PackageManager,
+        db: VulnerabilityDatabase
+    ): VulnerabilityFix[] {
+        const result: VulnerabilityFix[] = [];
+
+        for (const fix of fixes) {
+            // Always keep direct fixes and fixes via direct upgrade
+            if (!fix.isTransitive || fix.fixViaDirectUpgrade) {
+                result.push(fix);
+                continue;
+            }
+
+            // For transitive fixes, check if the package is still vulnerable in the lock file
+            const resolvedVersion = extractVersionFromLockFile(
+                lockFileContent,
+                fix.packageName,
+                packageManager
+            );
+
+            if (!resolvedVersion) {
+                // Package not found in lock file - might have been removed by direct upgrade
+                // Skip this fix (transitive is no longer in the tree)
+                continue;
+            }
+
+            // Check if the resolved version is still vulnerable
+            const isStillVulnerable = this.isVersionStillVulnerable(
+                fix.packageName,
+                resolvedVersion,
+                fix.cves,
+                db
+            );
+
+            if (isStillVulnerable) {
+                // Transitive is still vulnerable, keep the fix
+                result.push(fix);
+            }
+            // Otherwise, the direct upgrade already fixed it - skip the override
+        }
+
+        return result;
+    }
+
+    /**
+     * Checks if a package version is still vulnerable to any of the specified CVEs.
+     */
+    private isVersionStillVulnerable(
+        packageName: string,
+        version: string,
+        cves: string[],
+        db: VulnerabilityDatabase
+    ): boolean {
+        const vulns = db.getVulnerabilities(packageName);
+        for (const vuln of vulns) {
+            if (cves.includes(vuln.cve) && this.isVersionAffected(version, vuln)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     override initialValue(_ctx: ExecutionContext): Accumulator {
         return {
             // DependencyRecipeAccumulator fields
@@ -589,8 +748,8 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
             }
         }
 
-        // Recurse into transitive dependencies if overrideTransitive is enabled
-        if (this.overrideTransitive) {
+        // Recurse into transitive dependencies if we need to scan them
+        if (this.shouldScanTransitives()) {
             const transitives = [
                 ...(resolved.dependencies || []),
                 ...(resolved.devDependencies || []),
@@ -643,6 +802,7 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                 // Check if the declared minimum version is vulnerable
                 const vulns = db.getVulnerabilities(dep.name);
                 const affectedCves: string[] = [];
+                const affectedCveSummaries = new Map<string, string>();
                 let highestFixVersion: string | undefined;
 
                 for (const vuln of vulns) {
@@ -660,6 +820,7 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                     if (this.isVersionAffected(declaredMinVersion, vuln) &&
                         !this.isVersionAffected(dep.resolved.version, vuln)) {
                         affectedCves.push(vuln.cve);
+                        affectedCveSummaries.set(vuln.cve, vuln.summary);
 
                         // Find fix version for this vulnerability.
                         // Only use fixedVersion - don't guess based on lastAffectedVersion
@@ -683,6 +844,7 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                             scope,
                             isTransitive: false,
                             cves: affectedCves,
+                            cveSummaries: affectedCveSummaries,
                             originalMajorVersion: majorVersion
                         });
                     }
@@ -821,13 +983,23 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
      * major versions in the dependency tree (e.g., semver@6.x and semver@7.x).
      * Recursively checks if fix versions have their own vulnerabilities.
      *
+     * For transitive vulnerabilities, first tries to find a direct dependency upgrade
+     * that includes a fixed version of the transitive. Falls back to overrides if
+     * no suitable direct dependency upgrade is found.
+     *
      * @param vulnerabilities The vulnerabilities found during scanning
      * @param db The vulnerability database
+     * @param projectContext Context needed to check direct dependency upgrades
      */
-    private computeFixes(
+    private async computeFixes(
         vulnerabilities: VulnerableDependency[],
-        db: VulnerabilityDatabase
-    ): VulnerabilityFix[] {
+        db: VulnerabilityDatabase,
+        projectContext?: {
+            packageManager: PackageManager;
+            originalPackageJson: string;
+            configFiles?: Record<string, string>;
+        }
+    ): Promise<VulnerabilityFix[]> {
         if (this.isReportOnly()) {
             return [];
         }
@@ -865,9 +1037,12 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
             // Find the highest fix version needed across all vulnerabilities for this package@major
             let highestFixVersion: string | undefined;
             const cves: string[] = [];
+            const cveSummaries = new Map<string, string>();
             let isTransitive = true;
             let scope: DependencyScope | undefined;
             let originalVersion: string | undefined;
+            // Track the direct dependency that brings in this transitive (from the first vuln's path)
+            let directDepInfo: { name: string; version: string; scope: DependencyScope } | undefined;
 
             for (const vuln of vulns) {
                 // Track the original version for delta checking
@@ -875,6 +1050,16 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                     originalVersion = vuln.resolved.version;
                 }
 
+                // Track direct dependency info for transitive vulnerabilities
+                if (!vuln.isDirect && vuln.path.length > 0 && !directDepInfo) {
+                    const directDep = vuln.path[0];
+                    directDepInfo = {
+                        name: directDep.name,
+                        version: directDep.version,
+                        scope: vuln.scope || 'dependencies'
+                    };
+                }
+
                 // Check if upgradeable within delta
                 if (!this.isUpgradeableWithinDelta(vuln.resolved.version, vuln.vulnerability)) {
                     continue;
@@ -899,6 +1084,7 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                 }
 
                 cves.push(vuln.vulnerability.cve);
+                cveSummaries.set(vuln.vulnerability.cve, vuln.vulnerability.summary);
 
                 if (vuln.isDirect) {
                     isTransitive = false;
@@ -915,20 +1101,134 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                     db
                 );
 
-                fixes.push({
+                const fix: VulnerabilityFix = {
                     packageName,
                     newVersion: safeVersion || highestFixVersion,
                     isTransitive,
                     cves,
+                    cveSummaries,
                     scope,
-                    originalMajorVersion: originalMajor
-                });
+                    originalMajorVersion: originalMajor,
+                    // Store direct dependency info for potential later use by prefer-direct-upgrade
+                    directDepInfo: isTransitive && directDepInfo ? {
+                        name: directDepInfo.name,
+                        version: directDepInfo.version,
+                        scope: directDepInfo.scope
+                    } : undefined
+                };
+
+                fixes.push(fix);
             }
         }
 
         return fixes;
     }
 
+    /**
+     * Tries to find a direct dependency upgrade that fixes a transitive vulnerability.
+     * Returns the version to upgrade to, or undefined if no suitable upgrade found.
+     */
+    private async tryFindDirectDepUpgrade(
+        transitivePackageName: string,
+        requiredFixVersion: string,
+        directDepInfo: { name: string; version: string; scope: DependencyScope },
+        projectContext: {
+            packageManager: PackageManager;
+            originalPackageJson: string;
+            configFiles?: Record<string, string>;
+        },
+        db: VulnerabilityDatabase
+    ): Promise<string | undefined> {
+        // Create a vulnerability check function for the transitive
+        const isVulnerable = (version: string): boolean => {
+            try {
+                // Version is vulnerable if it's less than the required fix version
+                return semver.lt(version, requiredFixVersion);
+            } catch {
+                return true; // Assume vulnerable if we can't parse
+            }
+        };
+
+        // Create a delta check function based on recipe settings
+        const isWithinDelta = (from: string, to: string): boolean => {
+            return this.isVersionWithinDelta(from, to);
+        };
+
+        try {
+            const upgradeVersion = await findDirectUpgradeThatFixesTransitive(
+                projectContext.packageManager,
+                directDepInfo.name,
+                directDepInfo.version,
+                transitivePackageName,
+                isVulnerable,
+                isWithinDelta,
+                projectContext.originalPackageJson,
+                directDepInfo.scope as NpmUtilsDependencyScope,
+                projectContext.configFiles
+            );
+
+            return upgradeVersion;
+        } catch {
+            return undefined;
+        }
+    }
+
+    /**
+     * For each remaining transitive fix, tries to find a higher direct dependency version
+     * that fixes the transitive vulnerability. Modifies fixes in place by setting
+     * `fixViaDirectUpgrade` when a suitable upgrade is found.
+     *
+     * @param fixes The transitive fixes that are still needed after applying direct fixes
+     * @param updateInfo Project update info containing package manager and config
+     * @param db The vulnerability database
+     * @returns The fixes array with `fixViaDirectUpgrade` set where applicable
+     */
+    private async tryDirectUpgradesForTransitives(
+        fixes: VulnerabilityFix[],
+        updateInfo: ProjectUpdateInfo,
+        db: VulnerabilityDatabase
+    ): Promise<VulnerabilityFix[]> {
+        const result: VulnerabilityFix[] = [];
+
+        for (const fix of fixes) {
+            // Skip if no direct dependency info available
+            if (!fix.directDepInfo) {
+                result.push(fix);
+                continue;
+            }
+
+            // Try to find a direct dependency upgrade that fixes this transitive
+            const directUpgradeVersion = await this.tryFindDirectDepUpgrade(
+                fix.packageName,
+                fix.newVersion,
+                fix.directDepInfo,
+                {
+                    packageManager: updateInfo.packageManager,
+                    originalPackageJson: updateInfo.originalPackageJson,
+                    configFiles: updateInfo.configFiles
+                },
+                db
+            );
+
+            if (directUpgradeVersion) {
+                // Found a direct upgrade that fixes the transitive
+                result.push({
+                    ...fix,
+                    fixViaDirectUpgrade: {
+                        directDepName: fix.directDepInfo.name,
+                        directDepVersion: directUpgradeVersion,
+                        directDepScope: fix.directDepInfo.scope
+                    }
+                });
+            } else {
+                // No direct upgrade found, will use override
+                result.push(fix);
+            }
+        }
+
+        return result;
+    }
+
     override async scanner(acc: Accumulator): Promise<TreeVisitor<any, ExecutionContext>> {
         const recipe = this;
 
@@ -1036,7 +1336,12 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                 let fixes: VulnerabilityFix[] = [];
                 if (vulnerabilities.length > 0) {
                     acc.vulnerableByProject.set(doc.sourcePath, vulnerabilities);
-                    fixes = recipe.computeFixes(vulnerabilities, acc.db);
+                    const originalPackageJson = storedContent || await TreePrinters.print(doc);
+                    fixes = await recipe.computeFixes(vulnerabilities, acc.db, {
+                        packageManager: pm,
+                        originalPackageJson,
+                        configFiles: Object.keys(configFiles).length > 0 ? configFiles : undefined
+                    });
                 }
 
                 // Fix declared versions for preventive upgrades (when enabled)
@@ -1487,13 +1792,103 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
      * Runs the package manager in a temporary directory to update the lock file.
      * Writes a modified package.json with all new versions, then runs install.
      * All file contents are provided from in-memory sources (SourceFiles), not read from disk.
+     *
+     * For 'override' and 'prefer-direct-upgrade' strategies, this uses a two-phase approach:
+     * 1. First run with only direct fixes (+ fixes via direct upgrade)
+     * 2. Check the resulting lock file for remaining transitive vulnerabilities
+     * 3. If any remain, add overrides and run again
      */
     private async runPackageManagerInstall(
         acc: Accumulator,
         updateInfo: ProjectUpdateInfo,
         fixes: VulnerabilityFix[]
     ): Promise<void> {
-        // Create modified package.json with all the new version constraints
+        // Separate direct fixes from transitive fixes
+        const directFixes = fixes.filter(f => !f.isTransitive || f.fixViaDirectUpgrade);
+        const transitiveFixes = fixes.filter(f => f.isTransitive && !f.fixViaDirectUpgrade);
+
+        // For 'override' and 'prefer-direct-upgrade', use two-phase approach
+        if (this.shouldVerifyTransitiveFixes() && transitiveFixes.length > 0) {
+            // Phase 1: Apply only direct fixes and check what transitives are still vulnerable
+            const phase1PackageJson = this.createModifiedPackageJson(
+                updateInfo.originalPackageJson,
+                directFixes,
+                updateInfo.packageManager
+            );
+
+            const phase1Result = await runInstallInTempDir(
+                updateInfo.packageManager,
+                phase1PackageJson,
+                {
+                    configFiles: updateInfo.configFiles
+                }
+            );
+
+            if (!phase1Result.success || !phase1Result.lockFileContent) {
+                // Phase 1 failed, fall back to applying all fixes
+                const modifiedPackageJson = this.createModifiedPackageJson(
+                    updateInfo.originalPackageJson,
+                    fixes,
+                    updateInfo.packageManager
+                );
+
+                const result = await runInstallInTempDir(
+                    updateInfo.packageManager,
+                    modifiedPackageJson,
+                    {
+                        configFiles: updateInfo.configFiles
+                    }
+                );
+
+                storeInstallResult(result, acc, updateInfo, modifiedPackageJson);
+                return;
+            }
+
+            // Filter out transitive fixes that are no longer needed
+            let remainingTransitiveFixes = this.filterRemainingTransitiveFixes(
+                transitiveFixes,
+                phase1Result.lockFileContent,
+                updateInfo.packageManager,
+                acc.db
+            );
+
+            if (remainingTransitiveFixes.length === 0) {
+                // All transitives were fixed by direct upgrades - use phase 1 result
+                storeInstallResult(phase1Result, acc, updateInfo, phase1PackageJson);
+                return;
+            }
+
+            // For 'prefer-direct-upgrade', try to find higher direct dependency versions
+            // that fix the remaining transitive vulnerabilities
+            if (this.transitiveFixStrategy === 'prefer-direct-upgrade') {
+                remainingTransitiveFixes = await this.tryDirectUpgradesForTransitives(
+                    remainingTransitiveFixes,
+                    updateInfo,
+                    acc.db
+                );
+            }
+
+            // Phase 2: Apply remaining transitive fixes (either as direct upgrades or overrides)
+            const finalFixes = [...directFixes, ...remainingTransitiveFixes];
+            const finalPackageJson = this.createModifiedPackageJson(
+                updateInfo.originalPackageJson,
+                finalFixes,
+                updateInfo.packageManager
+            );
+
+            const finalResult = await runInstallInTempDir(
+                updateInfo.packageManager,
+                finalPackageJson,
+                {
+                    configFiles: updateInfo.configFiles
+                }
+            );
+
+            storeInstallResult(finalResult, acc, updateInfo, finalPackageJson);
+            return;
+        }
+
+        // When there are no transitive fixes, apply all fixes directly
         const modifiedPackageJson = this.createModifiedPackageJson(
             updateInfo.originalPackageJson,
             fixes,
@@ -1521,6 +1916,11 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
     /**
      * Runs the package manager in a temporary directory for a workspace.
      * Handles direct dependency fixes in workspace members and transitive fixes in root.
+     *
+     * For 'override' and 'prefer-direct-upgrade' strategies, this uses a two-phase approach:
+     * 1. First run with only direct fixes (+ fixes via direct upgrade)
+     * 2. Check the resulting lock file for remaining transitive vulnerabilities
+     * 3. If any remain, add overrides and run again
      */
     private async runWorkspacePackageManagerInstall(
         acc: Accumulator,
@@ -1530,39 +1930,32 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
         const memberPaths = acc.workspaceRoots.get(rootPath) || [];
         const pm = rootUpdateInfo.packageManager;
 
-        // Collect all transitive fixes from root and members (for root overrides)
+        // Collect all fixes from root and members, separating direct from transitive
+        const allDirectFixes: VulnerabilityFix[] = [];
         const allTransitiveFixes: VulnerabilityFix[] = [];
 
         // Process root fixes
         const rootFixes = acc.fixesByProject.get(rootPath) || [];
-        const rootDirectFixes = rootFixes.filter(f => !f.isTransitive);
-        const rootTransitiveFixes = rootFixes.filter(f => f.isTransitive);
+        const rootDirectFixes = rootFixes.filter(f => !f.isTransitive || f.fixViaDirectUpgrade);
+        const rootTransitiveFixes = rootFixes.filter(f => f.isTransitive && !f.fixViaDirectUpgrade);
+        allDirectFixes.push(...rootDirectFixes);
         allTransitiveFixes.push(...rootTransitiveFixes);
 
         // Process member fixes and collect transitive fixes
         const memberDirectFixes = new Map<string, VulnerabilityFix[]>();
         for (const memberPath of memberPaths) {
             const memberFixes = acc.fixesByProject.get(memberPath) || [];
-            const directFixes = memberFixes.filter(f => !f.isTransitive);
-            const transitiveFixes = memberFixes.filter(f => f.isTransitive);
+            const directFixes = memberFixes.filter(f => !f.isTransitive || f.fixViaDirectUpgrade);
+            const transitiveFixes = memberFixes.filter(f => f.isTransitive && !f.fixViaDirectUpgrade);
 
             if (directFixes.length > 0) {
                 memberDirectFixes.set(memberPath, directFixes);
+                allDirectFixes.push(...directFixes);
             }
             allTransitiveFixes.push(...transitiveFixes);
         }
 
-        // Create modified root package.json (with direct fixes + all transitive overrides)
-        const rootOriginalContent = acc.allPackageJsonContents.get(rootPath) || rootUpdateInfo.originalPackageJson;
-        const modifiedRootPackageJson = this.createModifiedPackageJson(
-            rootOriginalContent,
-            [...rootDirectFixes, ...allTransitiveFixes],
-            pm
-        );
-
         // Create modified workspace member package.json files (with direct fixes only)
-        // Keep the full package.json content including workspace: dependencies so Yarn
-        // can properly resolve them in the temp directory
         const workspacePackages: Record<string, string> = {};
         for (const memberPath of memberPaths) {
             const originalContent = acc.allPackageJsonContents.get(memberPath);
@@ -1573,28 +1966,110 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
             const directFixes = memberDirectFixes.get(memberPath);
             let modifiedContent: string;
             if (directFixes && directFixes.length > 0) {
-                // Apply direct dependency fixes to this member
                 modifiedContent = this.createModifiedPackageJsonDirectOnly(
                     originalContent,
                     directFixes
                 );
-                // Store the modified content for the actual output
                 acc.modifiedWorkspaceMemberContents.set(memberPath, modifiedContent);
             } else {
                 modifiedContent = originalContent;
             }
 
-            // Keep the full package.json including workspace: dependencies
             workspacePackages[memberPath] = modifiedContent;
         }
 
-        // Note: We intentionally do NOT pass the original lock file content.
-        // npm (and other package managers) don't apply overrides to already-resolved
-        // dependencies in an existing lock file. By not passing the original lock file,
-        // we force a fresh resolution that respects the overrides.
+        const rootOriginalContent = acc.allPackageJsonContents.get(rootPath) || rootUpdateInfo.originalPackageJson;
+
+        // For 'override' and 'prefer-direct-upgrade', use two-phase approach
+        if (this.shouldVerifyTransitiveFixes() && allTransitiveFixes.length > 0) {
+            // Phase 1: Apply only direct fixes
+            const phase1RootPackageJson = this.createModifiedPackageJson(
+                rootOriginalContent,
+                rootDirectFixes,
+                pm
+            );
+
+            const phase1Result = await runWorkspaceInstallInTempDir(
+                pm,
+                phase1RootPackageJson,
+                {
+                    configFiles: rootUpdateInfo.configFiles,
+                    workspacePackages
+                }
+            );
+
+            if (!phase1Result.success || !phase1Result.lockFileContent) {
+                // Phase 1 failed, fall back to applying all fixes
+                const modifiedRootPackageJson = this.createModifiedPackageJson(
+                    rootOriginalContent,
+                    [...rootDirectFixes, ...allTransitiveFixes],
+                    pm
+                );
+
+                const result = await runWorkspaceInstallInTempDir(
+                    pm,
+                    modifiedRootPackageJson,
+                    {
+                        configFiles: rootUpdateInfo.configFiles,
+                        workspacePackages
+                    }
+                );
+
+                storeInstallResult(result, acc, rootUpdateInfo, modifiedRootPackageJson);
+                return;
+            }
+
+            // Filter out transitive fixes that are no longer needed
+            let remainingTransitiveFixes = this.filterRemainingTransitiveFixes(
+                allTransitiveFixes,
+                phase1Result.lockFileContent,
+                pm,
+                acc.db
+            );
+
+            if (remainingTransitiveFixes.length === 0) {
+                // All transitives were fixed by direct upgrades - use phase 1 result
+                storeInstallResult(phase1Result, acc, rootUpdateInfo, phase1RootPackageJson);
+                return;
+            }
+
+            // For 'prefer-direct-upgrade', try to find higher direct dependency versions
+            // that fix the remaining transitive vulnerabilities
+            if (this.transitiveFixStrategy === 'prefer-direct-upgrade') {
+                remainingTransitiveFixes = await this.tryDirectUpgradesForTransitives(
+                    remainingTransitiveFixes,
+                    rootUpdateInfo,
+                    acc.db
+                );
+            }
+
+            // Phase 2: Apply remaining transitive fixes (either as direct upgrades or overrides)
+            const finalRootPackageJson = this.createModifiedPackageJson(
+                rootOriginalContent,
+                [...rootDirectFixes, ...remainingTransitiveFixes],
+                pm
+            );
+
+            const finalResult = await runWorkspaceInstallInTempDir(
+                pm,
+                finalRootPackageJson,
+                {
+                    configFiles: rootUpdateInfo.configFiles,
+                    workspacePackages
+                }
+            );
+
+            storeInstallResult(finalResult, acc, rootUpdateInfo, finalRootPackageJson);
+            return;
+        }
+
+        // When there are no transitive fixes, apply all fixes directly
+        const modifiedRootPackageJson = this.createModifiedPackageJson(
+            rootOriginalContent,
+            [...rootDirectFixes, ...allTransitiveFixes],
+            pm
+        );
 
-        // Run workspace install with full workspace structure
-        // We keep workspace: dependencies and the workspaces field so Yarn can resolve them
         const result = await runWorkspaceInstallInTempDir(
             pm,
             modifiedRootPackageJson,
@@ -1655,6 +2130,10 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
             fixesByPackage.set(fix.packageName, existing);
         }
 
+        // Track overrides added and their CVE comments for the comment field
+        // Maps override key (e.g., "lodash" or "semver@^6") to CVE comment string
+        const overrideComments = new Map<string, string>();
+
         for (const fix of fixes) {
             if (!fix.isTransitive && fix.scope) {
                 // Direct dependency: update the version in the scope
@@ -1663,6 +2142,20 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                     packageJson[fix.scope][fix.packageName] = applyVersionPrefix(originalVersion, fix.newVersion);
                 }
             } else if (fix.isTransitive) {
+                // If we found a direct dependency upgrade that fixes this transitive vulnerability,
+                // upgrade that direct dependency instead of using overrides. This is preferred because:
+                // 1. It's cleaner - no override/resolution clutter in package.json
+                // 2. It's more compatible - the direct dep author tested with their transitive deps
+                // 3. Future installs work naturally without forced versions
+                if (fix.fixViaDirectUpgrade) {
+                    const {directDepName, directDepVersion, directDepScope} = fix.fixViaDirectUpgrade;
+                    if (packageJson[directDepScope]?.[directDepName]) {
+                        const originalVersion = packageJson[directDepScope][directDepName];
+                        packageJson[directDepScope][directDepName] = applyVersionPrefix(originalVersion, directDepVersion);
+                        continue; // Skip the override logic below
+                    }
+                }
+
                 // Check if this package is also a direct dependency in any scope.
                 // Package managers handle overrides for direct dependencies differently:
                 // - npm: EOVERRIDE error - doesn't allow overrides that conflict with direct deps
@@ -1697,6 +2190,8 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                                 versionSpecificKey,
                                 fix.newVersion
                             );
+                            // Track comment for this override
+                            overrideComments.set(versionSpecificKey, this.generateOverrideComment(fix));
                         } else {
                             // Yarn doesn't support version-specific resolutions
                             // Skip this fix - the direct dependency at a higher version is already safe
@@ -1739,7 +2234,7 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                 if (useVersionSpecificOverride) {
                     // Use version-specific override for packages with multiple major versions
                     // e.g., "semver@^6": "6.3.1", "semver@^7": "7.5.2"
-                    // Note: This only works for npm, pnpm, and bun - not Yarn
+                    // Note: This works for npm, pnpm, and bun - not Yarn
                     const versionSpecificKey = `${fix.packageName}@^${fix.originalMajorVersion}`;
                     packageJson = applyOverrideToPackageJson(
                         packageJson,
@@ -1747,6 +2242,8 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                         versionSpecificKey,
                         fix.newVersion
                     );
+                    // Track comment for this override
+                    overrideComments.set(versionSpecificKey, this.generateOverrideComment(fix));
                 } else {
                     // Single major version and no existing version-specific overrides
                     // Use simple package override
@@ -1756,34 +2253,93 @@ export class DependencyVulnerabilityCheck extends ScanningRecipe<Accumulator> {
                         fix.packageName,
                         fix.newVersion
                     );
-                }
-
-                // For pnpm, also add as devDependency. This is needed because pnpm's
-                // overrides don't work reliably in all cases:
-                // 1. Auto-installed peer dependencies when autoInstallPeers is enabled
-                // 2. Packages with multiple major versions in the dependency tree
-                // 3. Optional dependencies resolved before overrides take effect
-                // Adding as devDependency ensures pnpm installs the specified version.
-                if (packageManager === PackageManager.Pnpm) {
-                    if (!packageJson.devDependencies) {
-                        packageJson.devDependencies = {};
-                    }
-                    // Only add if not already a direct dependency in any scope
-                    if (!packageJson.dependencies?.[fix.packageName] &&
-                        !packageJson.devDependencies[fix.packageName] &&
-                        !packageJson.peerDependencies?.[fix.packageName] &&
-                        !packageJson.optionalDependencies?.[fix.packageName]) {
-                        // Use version prefix based on maximumUpgradeDelta to allow
-                        // future patches that might fix additional vulnerabilities
-                        const prefix = this.getVersionPrefixForDelta();
-                        packageJson.devDependencies[fix.packageName] = prefix + fix.newVersion;
-                    }
+                    // Track comment for this override
+                    overrideComments.set(fix.packageName, this.generateOverrideComment(fix));
                 }
             }
         }
 
+        // Add override comments if enabled and there are comments to add
+        if (this.addOverrideComments && overrideComments.size > 0) {
+            packageJson = this.addOverrideCommentsToPackageJson(
+                packageJson,
+                packageManager,
+                overrideComments
+            );
+        }
+
         return JSON.stringify(packageJson, null, 2);
     }
+
+    /**
+     * Generates a comment string for an override from its CVE summaries.
+     * Format: "CVE-XXXX-YYYY: summary; CVE-ZZZZ-WWWW: summary"
+     */
+    private generateOverrideComment(fix: VulnerabilityFix): string {
+        if (!fix.cveSummaries || fix.cveSummaries.size === 0) {
+            // Fallback: just list CVE IDs if no summaries available
+            return fix.cves.join(', ');
+        }
+
+        const parts: string[] = [];
+        for (const cve of fix.cves) {
+            const summary = fix.cveSummaries.get(cve);
+            if (summary) {
+                // Truncate summary if too long (keep first 80 chars)
+                const truncatedSummary = summary.length > 80
+                    ? summary.substring(0, 77) + '...'
+                    : summary;
+                parts.push(`${cve}: ${truncatedSummary}`);
+            } else {
+                parts.push(cve);
+            }
+        }
+        return parts.join('; ');
+    }
+
+    /**
+     * Adds a comment field alongside the overrides/resolutions to document CVEs.
+     * Merges with existing comments, updating entries for packages being modified.
+     * Uses different field names based on package manager:
+     * - npm/bun: "//overrides"
+     * - pnpm: "//pnpm.overrides"
+     * - yarn: "//resolutions"
+     */
+    private addOverrideCommentsToPackageJson(
+        packageJson: Record<string, any>,
+        packageManager: PackageManager,
+        comments: Map<string, string>
+    ): Record<string, any> {
+        // Determine the comment field name based on package manager
+        let commentFieldName: string;
+        switch (packageManager) {
+            case PackageManager.Npm:
+            case PackageManager.Bun:
+                commentFieldName = '//overrides';
+                break;
+            case PackageManager.Pnpm:
+                commentFieldName = '//pnpm.overrides';
+                break;
+            case PackageManager.YarnClassic:
+            case PackageManager.YarnBerry:
+                commentFieldName = '//resolutions';
+                break;
+            default:
+                return packageJson;
+        }
+
+        // Get existing comments (if any) and merge with new ones
+        const existingComments: Record<string, string> = packageJson[commentFieldName] || {};
+        const mergedComments: Record<string, string> = {...existingComments};
+
+        // Add/update comments for new overrides
+        for (const [key, comment] of comments) {
+            mergedComments[key] = comment;
+        }
+
+        packageJson[commentFieldName] = mergedComments;
+        return packageJson;
+    }
 }
 
 /**