Version Resolution Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Version Resolution Engine is a core component of Numan responsible for determining compatibility between registry packages and the local environment. It evaluates package versions against two primary constraints: the active Nushell (Nu) version and the host platform's architecture/OS triple. This engine ensures that users only install artifacts that are functional on their specific system, preventing runtime failures due to ABI mismatches or missing binary support.
The engine is primarily utilized during search, info, and install operations. It provides a strict evaluation for plugins—which are ABI-locked to specific Nu versions—and a advisory evaluation for modules, scripts, and completions, which generally possess higher compatibility across Nu versions.
Sources: src/core/resolve.rs, AGENTS.md:144-150
Architecture and Components
The resolution logic is encapsulated within the Resolver struct, which maintains state regarding the target platform and the current Nu version.
Core Data Structures
| Structure | Description | File Path |
|---|---|---|
Resolver | The main engine struct. Holds Platform and NuVersion. | src/core/resolve.rs |
Incompatibility | Enum representing why a version failed resolution (e.g., NuTooOld, NuTooNew, NoPlatformArtifact). | src/core/resolve.rs |
NuVersion | Represents a specific Nushell version (e.g., 0.113.1) and handles semantic version constraint matching. | src/core/nu_version.rs |
Platform | Stores the OS, architecture, and environment triple (e.g., x86_64-unknown-linux-gnu). | src/core/platform.rs |
Sources: src/core/resolve.rs:9-40, src/core/nu_version.rs
Resolution Flow Diagram
The following diagram illustrates how the engine classifies a package version based on incoming environment data and package metadata.
Sources: src/core/resolve.rs:42-88
Resolution Logic
The engine performs a multi-stage check to determine if a specific VersionEntry is suitable for the current environment.
1. Platform Matching
For packages containing binary artifacts (primarily plugins), the engine checks the Artifact map for the current platform triple. If a package requires a binary but lacks one for the host OS/Arch, it is immediately flagged as incompatible.
Sources: src/core/resolve.rs:49-56, src/cmd/info.rs:40-45
2. Nushell Version Constraints
Packages define their Nu compatibility using semantic version ranges (e.g., >=0.113.0 <0.114.0). The NuVersion module parses these ranges and compares them against the detected or managed Nu binary.
- Plugins: Are strictly locked to Nu minor versions.
- Modules: Labeled as
not ABI-lockedin search results, though they may still have version constraints.
Sources: src/core/nu_version.rs, src/cmd/search.rs:136-150
3. Classification and Ranking
When multiple versions exist, the engine identifies the latest compatible version. If no versions are compatible, it identifies the newest version and classifies why it failed (e.g., "needs Nu >= X.Y.Z").
Sources: src/core/resolve.rs:77-88, src/cmd/search.rs:55-75
Integration with CLI Commands
The resolution engine powers the user-facing logic in several subcommands to provide clear feedback on why certain packages cannot be installed.
Search and Info Feedback
numan search: Hides incompatible packages by default. When--allis used, it displays short labels like[needs Nu 0.113.x]or[no artifact for aarch64-apple-darwin].numan info: Provides a detailed breakdown of every available version and its specific compatibility status relative to the user's current Nu version.
Sources: src/cmd/search.rs:85-115, src/cmd/info.rs:36-55
Managed Nu Resolution
The VersionManager in nu/version_manager.rs interacts with the resolution engine by providing the "active" Nu version. Numan supports side-by-side installs where the active version is tracked in nu_state/active-version.json. The Resolution Engine uses this specific version to perform its checks.
Sources: src/nu/version_manager.rs:188-215, CHANGELOG.md:15-25
Key Implementation Details
// src/core/resolve.rs:42-50
pub fn classify_version(&self, entry: &VersionEntry) -> Option<Incompatibility> {
// 1. Platform Check
if entry.artifact.kind == "binary" && !entry.artifact.targets.contains_key(&self.platform.triple) {
return Some(Incompatibility::NoPlatformArtifact {
triple: self.platform.triple.clone(),
});
}
// ... Nu version check follows
}
Sources: src/core/resolve.rs:42-50
Summary of Resolution States
| State | Internal Enum / Logic | User Display (Short Label) |
|---|---|---|
| Compatible | None (from classify_version) | [compatible] or [not ABI-locked] |
| Nu Version Too Old | Incompatibility::NuTooOld | [needs Nu <constraint>] |
| Nu Version Too New | Incompatibility::NuTooNew | [needs Nu <constraint>] |
| Missing Platform | Incompatibility::NoPlatformArtifact | [no artifact for <triple>] |
Sources: src/core/resolve.rs:17-40, src/cmd/search.rs:136-150
The Version Resolution Engine provides the fundamental safety checks that distinguish Numan from a simple file downloader. By strictly enforcing Nu version and platform constraints, it maintains the integrity of the Nushell environment across updates.
Sources: README.md:16-30, src/core/resolve.rs