Improve heuristics for Ruby-style dependency graphs

Author: seuros

README.md

@@ -397,7 +397,7 @@ Contributions welcome! Please:
 This package is derived from the tinyrange project:
 - **Original Repository:** https://github.com/tinyrange/tinyrange
 - **Original Package:** experimental/pubgrub
-- **Version:** v0.3.1 (Oct 31, 2025)
+- **Version:** v0.3.2 (Nov 1, 2025)
 - **Original Copyright:** Copyright 2024 The University of Queensland
 - **Original License:** Apache 2.0
 

partial_solution.go

@@ -21,6 +21,14 @@ import (
 	"strings"
 )
 
+const (
+	constraintScoreEmpty     = 0
+	constraintScoreUnknown   = 1000
+	constraintScoreUnbounded = 1_000_000
+
+	maxConstraintPriority = int(^uint(0) >> 1)
+)
+
 // partialSolution maintains the evolving solution during dependency resolution.
 // It tracks assignments (decisions and derivations) organized by package name
 // and decision level, supporting efficient backtracking and version set queries.
@@ -233,8 +241,15 @@ func (ps *partialSolution) isComplete() bool {
 
 // nextDecisionCandidate finds the next package that needs a version decision.
 // Returns the package name and true if found, or EmptyName and false if none.
+//
+// Heuristic: Prefer packages with tighter constraints (smaller allowed sets)
+// to reduce search space early. This helps avoid exploring dead ends when
+// there are many interdependent packages.
 func (ps *partialSolution) nextDecisionCandidate() (Name, bool) {
 	seen := make(map[Name]bool)
+	bestScore := maxConstraintPriority
+	bestName := EmptyName()
+	found := false
 
 	for _, assign := range ps.assignments {
 		name := assign.name
@@ -246,12 +261,63 @@ func (ps *partialSolution) nextDecisionCandidate() (Name, bool) {
 		}
 		seen[name] = true
 
-		if !ps.hasDecision(name) {
-			return name, true
+		if ps.hasDecision(name) {
+			continue
+		}
+
+		score := ps.constraintScore(name)
+		if !found || score < bestScore || (score == bestScore && name.Value() < bestName.Value()) {
+			bestScore = score
+			bestName = name
+			found = true
+		}
+	}
+
+	if !found {
+		return EmptyName(), false
+	}
+
+	return bestName, true
+}
+
+// constraintScore estimates how constrained a package is.
+// Lower scores indicate tighter constraints (should be resolved earlier).
+// Returns a large number if unconstrained (to deprioritize).
+func (ps *partialSolution) constraintScore(name Name) int {
+	return constraintScoreForSet(ps.allowedSet(name))
+}
+
+// constraintScoreForSet scores a VersionSet using the same heuristic as constraintScore.
+func constraintScoreForSet(allowed VersionSet) int {
+	if allowed == nil {
+		return constraintScoreUnknown
+	}
+
+	if intervalSet, ok := allowed.(*VersionIntervalSet); ok {
+		numIntervals := len(intervalSet.intervals)
+		if numIntervals == 0 {
+			// Empty set - should fail fast, highest priority
+			return constraintScoreEmpty
 		}
+		if numIntervals == 1 {
+			interval := intervalSet.intervals[0]
+			// Check if fully unbounded (negative infinity to positive infinity)
+			if interval.lower.isNegInfinity() && interval.upper.isPosInfinity() {
+				// Fully unbounded - lowest priority
+				return constraintScoreUnbounded
+			}
+		}
+		// More intervals = more holes/exclusions = typically tighter
+		// But a single tight interval is also good
+		// Use interval count as proxy for constraint tightness
+		return numIntervals
 	}
 
-	return EmptyName(), false
+	// Fallback: if we can't analyze the set structure, use medium priority
+	if allowed.IsEmpty() {
+		return constraintScoreEmpty // Empty = impossible, resolve immediately to fail fast
+	}
+	return constraintScoreUnknown // Unknown structure = medium priority
 }
 
 // hasDecision returns true if there's a decision assignment for the package.

solver.go

@@ -188,14 +188,18 @@ func (s *Solver) Solve(root Term) (Solution, error) {
 			allowedStr = allowed.String()
 		}
 		pending := state.partial.pendingPackages()
+
+		// Log constraint score for the selected package (heuristic debugging)
+		constraintScore := state.partial.constraintScore(nextPkg)
 		s.debug("selecting package",
 			"step", steps,
 			"package", nextPkg,
 			"allowed", allowedStr,
+			"constraint_score", constraintScore,
 			"pending", joinNameValues(pending),
 		)
 
-		ver, found, err := state.pickVersion(nextPkg)
+		ver, found, score, err := state.pickVersion(nextPkg)
 		if err != nil {
 			return nil, err
 		}
@@ -210,7 +214,14 @@ func (s *Solver) Solve(root Term) (Solution, error) {
 			continue
 		}
 
-		s.debug("making decision", "step", steps, "package", nextPkg, "version", ver)
+		// Log dependency score for the chosen version (heuristic debugging)
+		depScore := score
+		s.debug("making decision",
+			"step", steps,
+			"package", nextPkg,
+			"version", ver,
+			"dep_score", depScore,
+		)
 
 		assign := state.partial.addDecision(nextPkg, ver)
 		state.traceAssignment("decision", assign)

solver_complex_test.go

@@ -0,0 +1,119 @@
+package pubgrub
+
+import (
+	"testing"
+)
+
+// TestComplexRubyGemsScenario tests a more realistic scenario with multiple
+// packages that all transitively depend on shared dependencies.
+//
+// This simulates what happens in a real Rails project where many gems
+// depend on common utilities like rubyzip, and wrong version choices
+// early in the search can lead to dead ends.
+//
+// Package structure:
+// - root → [roo, rubyXL, caxlsx, another_gem]
+// - All four packages use rubyzip with different constraints
+// - PubGrub must choose rubyzip version that works for ALL of them
+//
+// This test will help identify if PubGrub's unit propagation and
+// conflict learning are working efficiently.
+func TestComplexRubyGemsScenario(t *testing.T) {
+	source := NewMapSource()
+
+	// Add rubyzip versions
+	source.Add("rubyzip", "1.3.0", nil)
+	source.Add("rubyzip", "2.3.0", nil)
+	source.Add("rubyzip", "2.4.0", nil)
+	source.Add("rubyzip", "2.4.1", nil)
+	source.Add("rubyzip", "3.0.0", nil)
+	source.Add("rubyzip", "3.1.0", nil)
+
+	// Add roo versions - note that OLD versions require rubyzip >= 3.0
+	source.Add("roo", "2.1.0", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 3.0.0, < 4.0.0"},
+	})
+	source.Add("roo", "2.5.0", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 3.0.0, < 4.0.0"},
+	})
+	source.Add("roo", "2.9.0", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 3.0.0, < 4.0.0"},
+	})
+	// Only 2.10.1 and 3.0.0 are compatible with rubyzip 2.x
+	source.Add("roo", "2.10.1", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 1.3.0, < 3.0.0"},
+	})
+	source.Add("roo", "3.0.0", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 3.0.0, < 4.0.0"},
+	})
+
+	// Add rubyXL versions - all require rubyzip ~> 2.4
+	source.Add("rubyXL", "3.4.14", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 2.4.0, < 3.0.0"},
+	})
+	source.Add("rubyXL", "3.4.25", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 2.4.0, < 3.0.0"},
+	})
+	source.Add("rubyXL", "3.4.34", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 2.4.0, < 3.0.0"},
+	})
+
+	// Add caxlsx which also depends on rubyzip
+	source.Add("caxlsx", "3.3.0", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 1.6.0, < 3.0.0"},
+	})
+	source.Add("caxlsx", "4.0.0", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 2.3.0, < 4.0.0"},
+	})
+
+	// Add another gem that prefers older rubyzip
+	source.Add("zip_tricks", "5.6.0", []Dependency{
+		{Name: "rubyzip", Constraint: ">= 1.3.0, < 3.0.0"},
+	})
+
+	// Root depends on all four packages
+	rootSource := NewRootSource()
+	rootSource.AddPackage(MakeName("roo"), NewAnyVersionCondition())
+	rootSource.AddPackage(MakeName("rubyXL"), NewAnyVersionCondition())
+	rootSource.AddPackage(MakeName("caxlsx"), NewAnyVersionCondition())
+	rootSource.AddPackage(MakeName("zip_tricks"), NewAnyVersionCondition())
+
+	// Create solver
+	solver := NewSolver(rootSource, source)
+
+	// Solve
+	solution, err := solver.Solve(rootSource.Term())
+	if err != nil {
+		t.Fatalf("Expected solution but got error: %v", err)
+	}
+
+	// Verify solution
+	solutionMap := make(map[string]string)
+	for _, pkg := range solution {
+		if pkg.Name.Value() != "$$root" {
+			solutionMap[pkg.Name.Value()] = pkg.Version.String()
+		}
+	}
+
+	// The only valid solution should use rubyzip 2.4.x
+	// because that's the intersection of all constraints:
+	// - roo 2.10.1: >= 1.3.0, < 3.0.0
+	// - rubyXL: >= 2.4.0, < 3.0.0
+	// - caxlsx: depends on which version, but should work with 2.4.x
+	// - zip_tricks: >= 1.3.0, < 3.0.0
+	//
+	// Intersection: >= 2.4.0, < 3.0.0 → rubyzip 2.4.1
+
+	if solutionMap["roo"] != "2.10.1" {
+		t.Errorf("Expected roo 2.10.1, got %s", solutionMap["roo"])
+	}
+	if solutionMap["rubyzip"] < "2.4.0" || solutionMap["rubyzip"] >= "3.0.0" {
+		t.Errorf("Expected rubyzip in [2.4.0, 3.0.0), got %s", solutionMap["rubyzip"])
+	}
+
+	// Print solution for debugging
+	t.Logf("Solution found:")
+	for name, version := range solutionMap {
+		t.Logf("  %s = %s", name, version)
+	}
+}