Functional Scope (In-Scope)
- Semantic Version Constraint Parsing: Parses constraints such as caret (
^) and tilde (~) to establish semantic version boundaries. - Topological Dependency Resolution: Uses depth-first recursive searching to select the highest compatible package version.
- Version Conflict Mitigation: Evaluates incoming version boundaries and detects conflicting restrictions within overlapping branches.
- Circular Dependency Interception: Identifies cyclic dependencies using graph back-edge detection during tree traversal.
Explicit Boundaries (Out-of-Scope)
- Network-Bound Package Downloading: Ignores physical tarball downloading, HTTP streaming, and disk extract processes.
- Concurrent Multi-User Locking: Excludes physical OS-level lock files and concurrent filesystem updates.
Clean reference designs demonstrating deterministic dependency graph resolution in Java and Python:
// ─── JAVA BLUEPRINT ──────────────────────────────────────────────────────────
import java.util.*;
class PackageVersion implements Comparable<PackageVersion> {
private final int major;
private final int minor;
private final int patch;
public PackageVersion(String versionStr) {
String[] parts = versionStr.split("\\.");
this.major = Integer.parseInt(parts[0]);
this.minor = parts.length > 1 ? Integer.parseInt(parts[1]) : 0;
this.patch = parts.length > 2 ? Integer.parseInt(parts[2]) : 0;
}
public int getMajor() { return major; }
public int getMinor() { return minor; }
public int getPatch() { return patch; }
@Override
public int compareTo(PackageVersion o) {
if (this.major != o.major) return Integer.compare(this.major, o.major);
if (this.minor != o.minor) return Integer.compare(this.minor, o.minor);
return Integer.compare(this.patch, o.patch);
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof PackageVersion)) return false;
PackageVersion that = (PackageVersion) o;
return major == that.major && minor == that.minor && patch == that.patch;
}
@Override
public int hashCode() {
return Objects.hash(major, minor, patch);
}
@Override
public String toString() {
return major + "." + minor + "." + patch;
}
}
class DependencyConstraint {
private final String packageName;
private final String constraint;
public DependencyConstraint(String packageName, String constraint) {
this.packageName = packageName;
this.constraint = constraint;
}
public String getPackageName() { return packageName; }
public String getConstraint() { return constraint; }
public boolean isSatisfiedBy(PackageVersion version) {
if (constraint.startsWith("^")) {
PackageVersion base = new PackageVersion(constraint.substring(1));
return version.compareTo(base) >= 0 && version.getMajor() == base.getMajor();
} else if (constraint.startsWith("~")) {
PackageVersion base = new PackageVersion(constraint.substring(1));
return version.compareTo(base) >= 0 && version.getMajor() == base.getMajor() && version.getMinor() == base.getMinor();
} else {
PackageVersion base = new PackageVersion(constraint);
return version.equals(base);
}
}
}
class PackageMetadata {
private final String name;
private final PackageVersion version;
private final List<DependencyConstraint> dependencies;
public PackageMetadata(String name, String version, List<DependencyConstraint> dependencies) {
this.name = name;
this.version = new PackageVersion(version);
this.dependencies = dependencies;
}
public String getName() { return name; }
public PackageVersion getVersion() { return version; }
public List<DependencyConstraint> getDependencies() { return dependencies; }
}
class Registry {
private final Map<String, List<PackageMetadata>> packages = new java.util.concurrent.ConcurrentHashMap<>();
public synchronized void register(PackageMetadata pkg) {
packages.computeIfAbsent(pkg.getName(), k -> new ArrayList<>()).add(pkg);
packages.get(pkg.getName()).sort((a, b) -> b.getVersion().compareTo(a.getVersion()));
}
public synchronized List<PackageMetadata> getVersions(String packageName) {
List<PackageMetadata> list = packages.get(packageName);
if (list == null) return Collections.emptyList();
return new ArrayList<>(list);
}
}
class DependencyResolver {
private final Registry registry;
public DependencyResolver(Registry registry) {
this.registry = registry;
}
public Map<String, String> resolve(String rootPackage, String rootVersionConstraint) throws Exception {
Map<String, String> resolved = new LinkedHashMap<>();
Set<String> visiting = new HashSet<>();
resolveHelper(rootPackage, new DependencyConstraint(rootPackage, rootVersionConstraint), resolved, visiting);
return resolved;
}
private void resolveHelper(String name, DependencyConstraint constraint, Map<String, String> resolved, Set<String> visiting) throws Exception {
if (visiting.contains(name)) {
throw new IllegalStateException("Circular dependency detected at package: " + name);
}
if (resolved.containsKey(name)) {
PackageVersion resolvedVer = new PackageVersion(resolved.get(name));
if (!constraint.isSatisfiedBy(resolvedVer)) {
throw new IllegalStateException("Version conflict: " + name + " is already resolved to " + resolvedVer + " which does not satisfy constraint " + constraint.getConstraint());
}
return;
}
List<PackageMetadata> candidates = registry.getVersions(name);
PackageMetadata selected = null;
for (PackageMetadata candidate : candidates) {
if (constraint.isSatisfiedBy(candidate.getVersion())) {
selected = candidate;
break;
}
}
if (selected == null) {
throw new IllegalArgumentException("No compatible version found for package " + name + " matching constraint " + constraint.getConstraint());
}
visiting.add(name);
resolved.put(name, selected.getVersion().toString());
for (DependencyConstraint dep : selected.getDependencies()) {
resolveHelper(dep.getPackageName(), dep, resolved, visiting);
}
visiting.remove(name);
}
}
public class Main {
public static void main(String[] args) {
System.out.println("=== INITIALIZING PACKAGE REGISTRY ===");
Registry registry = new Registry();
registry.register(new PackageMetadata("left-pad", "1.0.0", Collections.emptyList()));
registry.register(new PackageMetadata("left-pad", "1.1.0", Collections.emptyList()));
registry.register(new PackageMetadata("left-pad", "1.2.0", Collections.emptyList()));
registry.register(new PackageMetadata("ui-utils", "2.0.0", Arrays.asList(
new DependencyConstraint("left-pad", "^1.1.0")
)));
registry.register(new PackageMetadata("app", "1.0.0", Arrays.asList(
new DependencyConstraint("left-pad", "^1.0.0"),
new DependencyConstraint("ui-utils", "^2.0.0")
)));
DependencyResolver resolver = new DependencyResolver(registry);
System.out.println("\\n=== 1. RESOLVING DIAMOND DEPENDENCY ===");
try {
Map<String, String> result = resolver.resolve("app", "^1.0.0");
System.out.println("Successful Resolution: " + result);
} catch (Exception e) {
System.out.println("Resolution Failed: " + e.getMessage());
}
System.out.println("\\n=== 2. DETECTING STRICT VERSION CONFLICTS ===");
registry.register(new PackageMetadata("logger", "1.5.0", Collections.emptyList()));
registry.register(new PackageMetadata("logger", "2.0.0", Collections.emptyList()));
registry.register(new PackageMetadata("auth-lib", "1.0.0", Arrays.asList(
new DependencyConstraint("logger", "^1.0.0")
)));
registry.register(new PackageMetadata("conflict-app", "1.0.0", Arrays.asList(
new DependencyConstraint("auth-lib", "^1.0.0"),
new DependencyConstraint("logger", "~2.0.0")
)));
try {
Map<String, String> result = resolver.resolve("conflict-app", "^1.0.0");
System.out.println("Resolved conflict-app: " + result);
} catch (Exception e) {
System.out.println("Conflict Detected: " + e.getMessage() + " (Expected)");
}
System.out.println("\\n=== 3. DETECTING CIRCULAR DEPENDENCY ===");
registry.register(new PackageMetadata("pkg-a", "1.0.0", Arrays.asList(new DependencyConstraint("pkg-b", "^1.0.0"))));
registry.register(new PackageMetadata("pkg-b", "1.0.0", Arrays.asList(new DependencyConstraint("pkg-c", "^1.0.0"))));
registry.register(new PackageMetadata("pkg-c", "1.0.0", Arrays.asList(new DependencyConstraint("pkg-a", "^1.0.0"))));
try {
Map<String, String> result = resolver.resolve("pkg-a", "^1.0.0");
System.out.println("Resolved pkg-a: " + result);
} catch (Exception e) {
System.out.println("Circular Dependency: " + e.getMessage() + " (Expected)");
}
}
}