NuGet: validate candidate compatibility lazily

[brettfo]

What are you trying to accomplish?

Reduce NuGet analysis work by separating version discovery from package compatibility validation. Analysis now discovers filtered candidate versions without opening every package, then validates package existence and target-framework compatibility lazily in preferred-version order until it finds a usable candidate.

This avoids downloading or opening package archives that cannot be selected and removes the duplicate existence and compatibility archive access previously performed for attempted candidates.

Part of #16372.

Anything you want to highlight for special attention from reviewers?

GetVersionsByNameAsync and the existing GetVersionsAsync overloads remain compatibility-aware because dependency conflict resolution relies on that behavior. Only AnalyzeWorker uses the new raw candidate-discovery path.

Candidate ordering is unchanged:

• Normal updates try the highest version first.
• Security updates try the lowest safe version first.
• Versions excluded by requirements, ignores, vulnerabilities, update types, or cooldown are removed before package compatibility work.

Existence and compatibility are now evaluated through one package read per attempted package identity. Shared version properties still require every associated package ID to exist and be compatible.

How will you know you've accomplished your goal?

Added regression coverage for:

• Selecting a compatible version after skipping a newer incompatible version.
• Selecting the lowest compatible safe version for security updates.
• Preserving existence-only candidate fallback when the installed package fails the conservative compatibility checker.
• Requiring all packages sharing a version property to be compatible.
• Preserving compatibility filtering for existing VersionFinder callers.
• Treating an existing package as acceptable when there are no project frameworks.
• Performing no package download during raw discovery and exactly one download for the selected candidate.
• Reusing a package archive already downloaded into the job cache after source discovery confirms the candidate version.
• Propagating cancellation through compatibility and cooldown metadata I/O.

Validation:

dotnet test nuget\helpers\lib\NuGetUpdater\NuGetUpdater.Core.Test\NuGetUpdater.Core.Test.csproj --no-restore --filter "FullyQualifiedName~NuGetUpdater.Core.Test.Analyze.AnalyzeWorkerTests|FullyQualifiedName~NuGetUpdater.Core.Test.Analyze.CompatibilityCheckerTests|FullyQualifiedName~NuGetUpdater.Core.Test.Analyze.VersionFinderTests" --nologo --verbosity minimal

Passed: 66, Failed: 0, Skipped: 0.

Checklist

• I have run the complete test suite to ensure all tests and linters pass.
• I have thoroughly tested my code changes to ensure they work as expected, including adding additional tests for new functionality.
• I have written clear and descriptive commit messages.
• I have provided a detailed description of the changes in the pull request, including the problem it addresses, how it fixes the problem, and any relevant details about the implementation.
• I have ensured that the code is well-documented and easy to understand.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unconditional candidate compatibility checks regress updates when the installed package already fails the conservative framework checker.

Review effort: Balanced
Findings: 1

Open (1)

• Preserve fallback for packages failing framework compatibility checks · New

What changed in this PR

Optimizes NuGet candidate selection by deferring package downloads and compatibility checks until candidates are evaluated.

Changes:

• Adds raw candidate discovery.
• Combines existence and compatibility validation into one package read.
• Adds regression and download-count coverage.

File	Description
Analyze/​VersionFinder.cs	Separates discovery from compatibility filtering.
Analyze/​CompatabilityChecker.cs	Adds combined existence and compatibility validation.
Analyze/​AnalyzeWorker.cs	Lazily validates ordered candidates.
Analyze/​VersionFinderTests.cs	Tests compatibility-free discovery.
Analyze/​CompatibilityCheckerTests.cs	Tests packages without project frameworks.
Analyze/​AnalyzeWorkerTests.cs	Tests ordering, shared properties, and downloads.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Cached archives can incorrectly satisfy package-existence validation without availability from configured sources.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Validate package availability from configured sources, not just cache · New
• Serve a compatible current package to cover compatibility validation · New

Resolved since last review (1)

• Preserve fallback for packages failing framework compatibility checks

[jmprieur]

LGTM

One optional improvement: I would add a comment or test explaining that Dependabot may use a package already downloaded in the job’s NuGet cache, but only after confirming that the same version is available from an allowed package source. This behavior is intentional, but it may not be obvious to future maintainers (took me a bit of time)

[brettfo]

@jmprieur Addressed the optional maintainability suggestion in 099f6a8. I added a regression that makes the two-part contract explicit: candidate discovery first confirms version 1.1.0 is advertised by the configured source, then compatibility selection reuses the matching archive already in the job-scoped NUGET_PACKAGES cache without downloading it again. The rebased focused suite passes 65/65 tests.

[Copilot]

Note

Copilot was unable to run its full agentic suite in this review.

Copilot review overview

Review effort: Lite
Findings: 2 · 2

Open (4)

• This method accepts a cancellationToken but uses CancellationToken.None for potentially… · New
• This method accepts a cancellationToken but uses CancellationToken.None for potentially… · New
• The file path CompatabilityChecker.cs uses the misspelling 'Compatability' (should be… · New
• Disposing the two readers without a try/finally means that if one Dispose() throws, the other… · New

Resolved since last review (2)

• Validate package availability from configured sources, not just cache
• Serve a compatible current package to cover compatibility validation

[Copilot]

Note

Copilot was unable to run its full agentic suite in this review.

Copilot review overview

Review effort: Lite
Findings: None

Resolved since last review (4)

• This method accepts a cancellationToken but uses CancellationToken.None for potentially…
• This method accepts a cancellationToken but uses CancellationToken.None for potentially…
• Disposing the two readers without a try/finally means that if one Dispose() throws, the other…
• The file path CompatabilityChecker.cs uses the misspelling 'Compatability' (should be…

[jmprieur]

Findings: 2 (0 critical, 2 high, 0 medium, 0 low).

Authored against head 8eeeab88.

[jmprieur]

[high] Confirm allowed-source availability for cached sibling packages

Could we retain source-availability checks for every package sharing the version property before accepting a candidate? Discovery confirms the version only for the primary package, while both new validation branches can read a sibling directly from NUGET_PACKAGES.

If A and B share a property, the configured feed serves A 2.0.0 but not B 2.0.0, and a compatible B 2.0.0 archive is cached, this loop accepts 2.0.0. The removed DoVersionsExistAsync rejected it by checking the allowed sources for each identity. Please keep cache reuse for archive inspection, but independently confirm each sibling's source availability.

[jmprieur]

[high] Preserve primary-package compatibility in the fallback path

Could the existence-only fallback still check compatibility for the primary package? Previously GetVersionsAsync(projectFrameworks, ...) filtered primary-package candidates before this loop, even when the installed version failed the checker. Raw discovery removes that filter.

For a net8.0 project with an incompatible installed package, a feed containing compatible 2.0.0 and net9.0-only 3.0.0 previously selected 2.0.0; this branch now selects 3.0.0. An incompatible current sibling can also disable filtering for the primary package. Keeping the primary's compatibility check lazy, while relaxing only sibling compatibility in this fallback, would preserve the previous selection behavior.