Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ served it.

## [Unreleased]

### Added

- `Resolution.Upgrade` holds the `UpgradeRoots` pass's first answer (`First`) and whether a time bound or the end of `ctx` cut the pass short (`StoppedByTime`), so a caller can fall back to the first answer without solving again. It is nil with the pass off, and the answer the pass keeps does not change.

## [0.27.0] - 2026-11-18

### Fixed
Expand Down
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ Phase 3.
> **Status: implemented end to end.** `pypirsf/`, `index/`, `pep440set/`,
> `candidate/`, `provider/` and `resolver/` all carry code. `resolver.Resolve`
> is the entry point; keep its exported surface to `Resolve`, `Options`,
> `Resolution`, `ResolutionError`, `MissingExtra` and `Requester`.
> `Resolution`, `ResolutionError`, `MissingExtra`, `YankedPin`, `UpgradeReport`
> and `Requester`.
>
> ⚠️ `resolver` is **no longer the only package Package Manager imports**. PPM
> implements its own `MetadataIndex` (`src/pyindex`) and imports `index/` for the
Expand Down
7 changes: 7 additions & 0 deletions resolver/export_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -62,3 +62,10 @@ func OnCandidate(f func(got *Resolution, kept bool)) (restore func()) {
onCandidate = f
return func() { onCandidate = nil }
}

// AfterSolve calls f after each solve Resolve runs until restore is called.
// Not safe with parallel tests.
func AfterSolve(f func()) (restore func()) {
onSteps = func(int) { f() }
return func() { onSteps = nil }
}
24 changes: 23 additions & 1 deletion resolver/resolver.go
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,8 @@ type Options struct {
// re-solve still spends budget. Every re-solve uses these same Options.
//
// It never fails a resolution: if the budget or ctx ends, or no re-solve
// helps, the best complete answer so far is returned.
// helps, the best complete answer so far is returned. Resolution.Upgrade
// holds the first answer and whether time cut the pass short.
UpgradeRoots int

// UpgradeTimeFactor, when above zero, bounds the UpgradeRoots pass in time:
Expand Down Expand Up @@ -326,6 +327,27 @@ type Resolution struct {
// requirer in the solution that pins it exactly, root or transitive, so a
// caller can warn. Sorted by (package, requester).
YankedPins []YankedPin

// Upgrade reports on the UpgradeRoots pass. It is nil when the pass is off
// or the first solve fails.
Upgrade *UpgradeReport
}

// UpgradeReport says how the UpgradeRoots pass went.
type UpgradeReport struct {
// First is the first solve's answer, the one Resolve returns with the pass
// off. Its Upgrade is nil, and it shares no maps or slices with the
// Resolution that holds it.
First *Resolution

// StoppedByTime is true when time cut the pass short: UpgradeTimeFactor or
// UpgradeMaxTime was reached, or the pass ran into the end of ctx. The kept
// answer then depends on timing; use First for a repeatable one. A pass
// ended by the step bounds, the UpgradeRoots budget, or running out of
// roots to try is not stopped by time. It can still be true if time ran out
// just as the pass would have ended anyway; a caller then only falls back
// to First.
StoppedByTime bool
}

// YankedPin is a selected yanked version and one requirer that pins it.
Expand Down
80 changes: 72 additions & 8 deletions resolver/upgrade.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ package resolver

import (
"context"
"maps"
"math"
"slices"
"strconv"
Expand Down Expand Up @@ -41,6 +42,9 @@ func levelsBetween(hi, lo level) int {
type usability struct {
p *provider.Provider
memo map[usableKey]bool

// failed, if set, is called when an index lookup fails.
failed func()
}

type usableKey struct {
Expand All @@ -57,6 +61,9 @@ func (u *usability) ok(name index.PackageName, v version.Version) bool {
}
got, err := u.p.Usable(name, v)
if err != nil {
if u.failed != nil {
u.failed()
}
return false
}
u.memo[k] = got
Expand Down Expand Up @@ -246,8 +253,8 @@ func upgradeStepLimit(opts Options, baseSteps int) (limit int, ok bool) {
}

// upgradeRoots is the pass behind Options.UpgradeRoots. base is a valid answer
// to reqs, and baseDur and baseSteps are what it took; the result is base or a
// valid answer that scores strictly better.
// to reqs, and baseDur and baseSteps are what it took; the result is base's
// answer or a valid one that scores strictly better, with an UpgradeReport.
func upgradeRoots(
ctx context.Context,
reqs []requirement.Requirement,
Expand All @@ -257,23 +264,57 @@ func upgradeRoots(
baseDur time.Duration,
baseSteps int,
) *Resolution {
best, byTime := upgradePass(ctx, reqs, idx, opts, base, baseDur, baseSteps)
if best == base {
// First must not alias the answer the caller gets.
best = cloneResolution(base)
}
best.Upgrade = &UpgradeReport{First: base, StoppedByTime: byTime}
return best
}

// upgradePass runs the pass. byTime is whether a time bound or the end of ctx
// cut it short.
func upgradePass(
ctx context.Context,
reqs []requirement.Requirement,
idx index.MetadataIndex,
opts Options,
base *Resolution,
baseDur time.Duration,
baseSteps int,
) (_ *Resolution, byTime bool) {
passStart := now()
limit, timed := upgradeTimeLimit(opts, baseDur)
stepLimit, stepped := upgradeStepLimit(opts, baseSteps)
spent := 0 // solver steps the re-solves have used
// cut is set once a re-solve is stopped by the time bound; the pass then
// ends. A re-solve stopped by the step bound leaves spent at stepLimit.
cut := false
clockUp := false // the time bound was reached between re-solves
// ctxEnded notes a ctx end the pass ran into, as opposed to one after it.
ctxCut := false
ctxEnded := func() bool {
if ctx.Err() != nil {
ctxCut = true
}
return ctxCut
}
timeUp := func() bool {
return cut || (stepped && spent >= stepLimit) || (timed && now().Sub(passStart) >= limit)
if cut || (stepped && spent >= stepLimit) {
return true
}
clockUp = timed && now().Sub(passStart) >= limit
return clockUp
}
u := &usability{
p: provider.New(ctx, idx, providerOptions(reqs, opts)),
memo: map[usableKey]bool{},
}
u.failed = func() { ctxEnded() }
roots := upgradeRootSet(ctx, reqs, idx, opts, base, u)
if len(roots) == 0 {
return base
return base, ctxEnded()
}
best := base
// best is scored only once a re-solve has an answer to compare it with:
Expand Down Expand Up @@ -316,7 +357,7 @@ func upgradeRoots(
spent += steps.used
if err != nil {
// Stopped by the time bound, not the caller: no gain, and the pass ends.
if ctx.Err() == nil && solveCtx.Err() != nil {
if !ctxEnded() && solveCtx.Err() != nil {
cut = true
}
return nil
Expand All @@ -326,6 +367,8 @@ func upgradeRoots(
scored = true
}
kept := objective(roots, got).less(bestScore)
// An index may report a ctx end as unusable metadata, so scoring hides it.
ctxEnded()
if onCandidate != nil {
onCandidate(got, kept)
}
Expand All @@ -335,7 +378,7 @@ func upgradeRoots(
return got
}

for budget > 0 && ctx.Err() == nil && !timeUp() {
for budget > 0 && !ctxEnded() && !timeUp() {
// The untried root furthest behind (at least one level); the first by
// name on a tie. A root behind only in versions is not tried.
var pick *upRoot
Expand All @@ -349,6 +392,7 @@ func upgradeRoots(
}
}
if pick == nil {
ctxEnded() // the pick read the index too
break
}
done[pick.name] = true
Expand Down Expand Up @@ -383,7 +427,7 @@ func upgradeRoots(
lo := accept(got) // highest level index known to work
hi := len(bounds) // lowest level index known to fail
triedTop := false
for hi-lo > 1 && budget > 0 && ctx.Err() == nil && !timeUp() {
for hi-lo > 1 && budget > 0 && !ctxEnded() && !timeUp() {
mid := hi - 1
if triedTop {
mid = (lo + hi) / 2
Expand All @@ -396,7 +440,24 @@ func upgradeRoots(
}
}
}
return best
return best, cut || clockUp || ctxCut
}

// cloneResolution copies r's maps and slices, so the copy shares none with r.
func cloneResolution(r *Resolution) *Resolution {
c := *r
c.Pinned = maps.Clone(r.Pinned)
c.Order = slices.Clone(r.Order)
if r.Extras != nil {
c.Extras = make(map[index.PackageName][]string, len(r.Extras))
for k, v := range r.Extras {
c.Extras[k] = slices.Clone(v)
}
}
c.Unusable = slices.Clone(r.Unusable)
c.MissingExtras = slices.Clone(r.MissingExtras)
c.YankedPins = slices.Clone(r.YankedPins)
return &c
}

// upgradeRootSet lists, sorted by name, each root project that base pinned,
Expand Down Expand Up @@ -432,6 +493,9 @@ func upgradeRootSet(
}
vs, err := idx.Versions(ctx, n)
if err != nil {
if u.failed != nil {
u.failed()
}
continue
}
if len(vs) == 0 {
Expand Down
75 changes: 75 additions & 0 deletions resolver/upgrade_clone_internal_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
// SPDX-License-Identifier: Apache-2.0 OR MIT

package resolver

import (
"reflect"
"testing"

"github.com/posit-dev/go-pyresolver/index"
"github.com/posit-dev/go-pyresolver/provider"
"github.com/posit-dev/go-python-packaging/version"
)

// fullResolution fills every map and slice field of a Resolution.
func fullResolution() *Resolution {
a := index.NewPackageName("a")
v := version.MustParse("1.0")
root := Requester{Root: true}
return &Resolution{
Pinned: map[index.PackageName]version.Version{a: v},
Order: []index.PackageName{a},
Extras: map[index.PackageName][]string{a: {"x"}},
Unusable: []provider.Unusable{{Package: provider.Project(a), Version: v, Reason: "r"}},
MissingExtras: []MissingExtra{{Package: a, Version: v, Extra: "y", RequestedBy: root}},
YankedPins: []YankedPin{{Package: a, Version: v, RequestedBy: root}},
}
}

func TestCloneResolutionSharesNothing(t *testing.T) {
r, want := fullResolution(), fullResolution()
c := cloneResolution(r)
a := index.NewPackageName("a")
c.Pinned[a] = version.MustParse("9.0")
c.Order[0] = index.NewPackageName("z")
c.Extras[a][0] = "changed"
c.Unusable[0].Reason = "changed"
c.MissingExtras[0].Extra = "changed"
c.YankedPins[0].Package = index.NewPackageName("z")
if !reflect.DeepEqual(r, want) {
t.Errorf("changing the copy changed the original: %+v", r)
}
}

// Fails when Resolution gains a map, slice or pointer field that
// cloneResolution does not copy.
func TestCloneResolutionCoversEveryField(t *testing.T) {
r := fullResolution()
c := cloneResolution(r)
rv, cv := reflect.ValueOf(r).Elem(), reflect.ValueOf(c).Elem()
for i := range rv.NumField() {
name := rv.Type().Field(i).Name
f, g := rv.Field(i), cv.Field(i)
switch f.Kind() {
case reflect.Map, reflect.Slice:
if f.Len() == 0 {
t.Errorf("%s: fill it in fullResolution", name)
continue
}
if f.UnsafePointer() == g.UnsafePointer() {
t.Errorf("%s: cloneResolution shares it", name)
}
if f.Kind() == reflect.Map && f.Type().Elem().Kind() == reflect.Slice {
for _, k := range f.MapKeys() {
if f.MapIndex(k).UnsafePointer() == g.MapIndex(k).UnsafePointer() {
t.Errorf("%s[%v]: cloneResolution shares the inner slice", name, k)
}
}
}
case reflect.Pointer, reflect.Interface, reflect.Chan, reflect.Func:
if name != "Upgrade" { // nil on the answer upgradeRoots copies
t.Errorf("%s: decide whether cloneResolution must copy it", name)
}
}
}
}
Loading