From 549c49c1e5dbb8d2323bbbb6d011a0e9e6f2ffad Mon Sep 17 00:00:00 2001 From: Corey Butler <770982+coreybutler@users.noreply.github.com> Date: Tue, 10 Nov 2026 12:26:58 -0600 Subject: [PATCH] feat: add alpha alias and preserve Node.js prerelease tags Resolve alpha to the newest -alpha* catalog row, keep full prerelease tags through Find, and allow Governance builds to opt latest into tip-of-index via LatestIncludesPrerelease hook. --- resolver/local.go | 37 ++++++++--- resolver/resolver.go | 132 ++++++++++++++++++++++++++++++++------ resolver/resolver_test.go | 71 +++++++++++++++++++- resolver/status.go | 4 +- 4 files changed, 214 insertions(+), 30 deletions(-) diff --git a/resolver/local.go b/resolver/local.go index 60228b8..febf151 100644 --- a/resolver/local.go +++ b/resolver/local.go @@ -19,6 +19,25 @@ func NormalizeVersion(version string) string { return strings.Split(v, "-")[0] } +// CanonicalVersion strips a leading "v" and lowercases, but keeps prerelease +// and build metadata. Examples: "v27.0.0-alpha.0.0.0" → "27.0.0-alpha.0.0.0". +func CanonicalVersion(version string) string { + v := strings.TrimSpace(version) + return strings.TrimPrefix(strings.ToLower(v), "v") +} + +// IsUnstableVersion reports whether version carries prerelease/build metadata +// (any '-' after the core x.y.z tag). +func IsUnstableVersion(version string) bool { + return strings.Contains(CanonicalVersion(version), "-") +} + +// IsAlphaVersion reports whether version is a Node.js alpha prerelease +// (canonical form contains "-alpha"). +func IsAlphaVersion(version string) bool { + return strings.Contains(CanonicalVersion(version), "-alpha") +} + // ScanInstalled returns all installed Node.js versions from the configured // install root, sorted in descending semver order. Only directories that // contain node.exe are included. @@ -114,12 +133,14 @@ func LatestInstalledMatch(spec string, installed ...[]string) (string, bool) { return "", false } -// CheckInstalledLocally reports whether an exact x.y.z version is present on -// disk without making any network requests. Returns (canonicalVersion, true) on -// success. Non-exact specs (partial, aliases) always return ("", false). +// CheckInstalledLocally reports whether an exact x.y.z (or x.y.z-prerelease) +// version is present on disk without making any network requests. Returns +// (canonicalVersion, true) on success. Non-exact specs (partial, aliases) +// always return ("", false). func CheckInstalledLocally(spec string) (string, bool) { - normalized := NormalizeVersion(spec) - parts := strings.Split(normalized, ".") + canonical := CanonicalVersion(spec) + core := NormalizeVersion(canonical) + parts := strings.Split(core, ".") if len(parts) != 3 { return "", false } @@ -133,11 +154,11 @@ func CheckInstalledLocally(spec string) (string, bool) { } root := settings.Expand(settings.Global().Root) - nodeExe := filepath.Join(root, "v"+normalized, "node.exe") + nodeExe := filepath.Join(root, "v"+canonical, "node.exe") if _, err := os.Stat(nodeExe); err != nil { return "", false } - return normalized, true + return canonical, true } func isPartialVersionSpec(version string) bool { @@ -175,7 +196,7 @@ func isExactVersionSpec(version string) bool { } // isNamedSpecifier reports CLI tokens that must be resolved through Find -// (latest, lts, default, current, user aliases) rather than local-only +// (latest, lts, alpha, default, current, user aliases) rather than local-only // partial matching. func isNamedSpecifier(version string) bool { if isPartialVersionSpec(version) || isExactVersionSpec(version) { diff --git a/resolver/resolver.go b/resolver/resolver.go index 07834e4..09fc55b 100644 --- a/resolver/resolver.go +++ b/resolver/resolver.go @@ -12,42 +12,68 @@ import ( semver "github.com/Masterminds/semver/v3" ) +// LatestIncludesPrerelease reports whether the reserved "latest" alias should +// resolve to the absolute tip of index.tab (including prereleases). Community +// builds leave this nil/false. Certified Governance builds may set it when +// HKLM LatestIncludesPrerelease=1. +var LatestIncludesPrerelease func() bool + +// OnLegacyLatestResolved is invoked when "latest" resolves under +// LatestIncludesPrerelease. Certified builds use it for structured warnings. +var OnLegacyLatestResolved func(resolved string) + // FindVersion returns the best matching version for a given version string, along with its npm version. // The input version string can be a full version (e.g. "v16.13.0"), a major.minor (e.g. "16.13"), or just a major version (e.g. "16"). -// Aliases "latest", "lts", and "lts/" are also accepted. +// Aliases "latest", "lts", "lts/", and "alpha" are also accepted. // The function will attempt to find the best match based on the available versions. func Find(version string) (string, string, error) { // Resolve aliases before normal version parsing. lower := strings.ToLower(strings.TrimSpace(version)) - v := strings.TrimPrefix(strings.TrimSpace(version), "v") + raw := strings.TrimPrefix(strings.TrimSpace(version), "v") + v := raw isUserAlias := false + preservedPrerelease := "" - if _, err := strconv.Atoi(strings.Split(v, ".")[0]); err != nil { + if _, err := strconv.Atoi(strings.Split(strings.Split(v, "-")[0], ".")[0]); err != nil { isUserAlias = true } - if isUserAlias || lower == "latest" || lower == "lts" || strings.HasPrefix(lower, "lts/") { + if isUserAlias || lower == "latest" || lower == "lts" || lower == "alpha" || strings.HasPrefix(lower, "lts/") { resolved, err := alias(lower) if err != nil { return "", "", err } v = resolved + if IsUnstableVersion(resolved) { + // Alias already produced a concrete prerelease tag (alpha / legacy latest). + return CanonicalVersion(resolved), "", nil + } + } else if IsUnstableVersion(raw) { + // Explicit prerelease/exact tag typed by the user — keep the full tag. + preservedPrerelease = CanonicalVersion(raw) } - // Strip prerelease/build metadata for partial/exact matching. Explicit - // prerelease installs are not supported yet (reserved aliases alpha/beta); + // Strip prerelease/build metadata for partial numeric matching only. // `latest` already skips prerelease rows so this strip does not invent a // missing GA tag like 27.0.0 from 27.0.0-alpha.0.0.0 (nvm#1554). - v = strings.Split(v, "-")[0] + core := strings.Split(v, "-")[0] + + if preservedPrerelease != "" { + // Exact prerelease: skip catalog so air-gapped installs work. + if isExactVersionSpec(core) { + return preservedPrerelease, "", nil + } + core = NormalizeVersion(preservedPrerelease) + } // Exact x.y.z is already concrete (typed by the user, or after alias // resolution). Skip index.tab so air-gapped `nvm install 24.22.1` can // use a local archive without DNS. - if isExactVersionSpec(v) { - return NormalizeVersion(v), "", nil + if isExactVersionSpec(core) && preservedPrerelease == "" { + return NormalizeVersion(core), "", nil } - parts := strings.Split(v, ".") + parts := strings.Split(core, ".") major := parts[0] @@ -70,20 +96,33 @@ func Find(version string) (string, string, error) { return "", "", fmt.Errorf("version %s not found", version) } + if preservedPrerelease != "" { + for _, row := range versions { + if strings.EqualFold(CanonicalVersion(row[0]), preservedPrerelease) { + return CanonicalVersion(row[0]), row[2], nil + } + } + return "", "", fmt.Errorf("version %s not found", version) + } + if minor != "" { - for _, v := range versions { - if strings.HasPrefix(v[0], major+"."+minor+".") { + for _, row := range versions { + tag := CanonicalVersion(row[0]) + if strings.HasPrefix(tag, major+"."+minor+".") { if patch == "" { - return v[0], v[2], nil + return tag, row[2], nil } - if strings.EqualFold(v[0], major+"."+minor+"."+patch) { - return v[0], v[2], nil + if strings.EqualFold(NormalizeVersion(tag), major+"."+minor+"."+patch) && !IsUnstableVersion(tag) { + return tag, row[2], nil + } + if strings.EqualFold(tag, major+"."+minor+"."+patch) { + return tag, row[2], nil } } } } - return versions[0][0], versions[0][2], nil + return CanonicalVersion(versions[0][0]), versions[0][2], nil } // LTSName returns the LTS codename for the given version (e.g. "Jod", "Iron"), @@ -104,7 +143,7 @@ func LTSName(version string) string { } // alias resolves a named alias to a concrete version string. -// Supported aliases: "latest", "lts", "lts/", "default", "current". +// Supported aliases: "latest", "lts", "lts/", "alpha", "default", "current". func alias(version string) (string, error) { v := strings.ToLower(strings.TrimSpace(version)) @@ -121,9 +160,27 @@ func alias(version string) (string, error) { if err != nil { return "", err } + if LatestIncludesPrerelease != nil && LatestIncludesPrerelease() { + tag, err := latestTip(all) + if err != nil { + return "", err + } + if OnLegacyLatestResolved != nil { + OnLegacyLatestResolved(tag) + } + return tag, nil + } return latestStable(all) } + if v == "alpha" { + all, err := List() + if err != nil { + return "", err + } + return latestAlpha(all) + } + if v == "lts" { all, err := List() if err != nil { @@ -177,7 +234,7 @@ func latestStable(versions [][]string) (string, error) { if len(ver) == 0 { continue } - tag := strings.TrimPrefix(strings.TrimSpace(ver[0]), "v") + tag := CanonicalVersion(ver[0]) if tag == "" || strings.Contains(tag, "-") { continue } @@ -186,6 +243,43 @@ func latestStable(versions [][]string) (string, error) { return "", fmt.Errorf("no stable versions found") } +// latestTip returns the absolute newest index.tab row, including prereleases. +// Used when Governance LatestIncludesPrerelease is enabled. +func latestTip(versions [][]string) (string, error) { + if len(versions) == 0 { + return "", fmt.Errorf("no versions found") + } + for _, ver := range versions { + if len(ver) == 0 { + continue + } + tag := CanonicalVersion(ver[0]) + if tag == "" { + continue + } + return tag, nil + } + return "", fmt.Errorf("no versions found") +} + +// latestAlpha returns the newest index.tab row whose version contains "-alpha". +func latestAlpha(versions [][]string) (string, error) { + if len(versions) == 0 { + return "", fmt.Errorf("no versions found") + } + for _, ver := range versions { + if len(ver) == 0 { + continue + } + tag := CanonicalVersion(ver[0]) + if tag == "" || !IsAlphaVersion(tag) { + continue + } + return tag, nil + } + return "", fmt.Errorf("no alpha versions found") +} + // Resolve returns the best concrete Node.js version for the given input. // It accepts: // - Named aliases: "latest", "lts", "lts/" @@ -210,7 +304,7 @@ func Resolve(version string) (string, error) { } // Handle reserved aliases and plain/partial versions via Find, which covers - // "latest", "lts", "lts/", "18", "18.20", "18.20.1", "v18.20.1". + // "latest", "lts", "lts/", "alpha", "18", "18.20", "18.20.1", "v18.20.1". resolved, _, err := Find(v) if err == nil { return resolved, nil diff --git a/resolver/resolver_test.go b/resolver/resolver_test.go index 23d942f..8012ec5 100644 --- a/resolver/resolver_test.go +++ b/resolver/resolver_test.go @@ -3,7 +3,7 @@ package resolver import "testing" func TestFindExactVersionSkipsCatalog(t *testing.T) { - for _, spec := range []string{"24.22.1", "v24.22.1", "24.22.1-rc.1"} { + for _, spec := range []string{"24.22.1", "v24.22.1"} { got, npm, err := Find(spec) if err != nil { t.Fatalf("Find(%q) error = %v", spec, err) @@ -17,6 +17,19 @@ func TestFindExactVersionSkipsCatalog(t *testing.T) { } } +func TestFindExactPrereleaseKeepsTag(t *testing.T) { + got, npm, err := Find("24.22.1-rc.1") + if err != nil { + t.Fatalf("Find(prerelease) error = %v", err) + } + if got != "24.22.1-rc.1" { + t.Fatalf("Find(prerelease) = %q, want 24.22.1-rc.1", got) + } + if npm != "" { + t.Fatalf("Find(prerelease) npm = %q, want empty (no catalog)", npm) + } +} + func TestLatestStableSkipsPrereleaseHead(t *testing.T) { // Mirrors nodejs.org/dist/index.tab order when an alpha leads the catalog. rows := [][]string{ @@ -41,3 +54,59 @@ func TestLatestStableEmptyOrOnlyPrerelease(t *testing.T) { t.Fatal("expected error when only prereleases exist") } } + +func TestLatestAlphaPicksLeadingAlpha(t *testing.T) { + rows := [][]string{ + {"27.0.0-alpha.0.0.0", "2026-10-29", "12.1.0", "", "-"}, + {"26.13.0", "2026-10-28", "11.20.0", "Lithium", "-"}, + {"26.0.0-alpha.1", "2026-01-01", "11.0.0", "", "-"}, + } + got, err := latestAlpha(rows) + if err != nil { + t.Fatalf("latestAlpha error = %v", err) + } + if got != "27.0.0-alpha.0.0.0" { + t.Fatalf("latestAlpha = %q, want 27.0.0-alpha.0.0.0", got) + } +} + +func TestLatestAlphaNone(t *testing.T) { + if _, err := latestAlpha([][]string{{"26.13.0", "", "", "", ""}}); err == nil { + t.Fatal("expected error when no alphas exist") + } +} + +func TestLatestTipReturnsPrereleaseHead(t *testing.T) { + rows := [][]string{ + {"27.0.0-alpha.0.0.0", "2026-10-29", "12.1.0", "", "-"}, + {"26.13.0", "2026-10-28", "11.20.0", "Lithium", "-"}, + } + got, err := latestTip(rows) + if err != nil { + t.Fatalf("latestTip error = %v", err) + } + if got != "27.0.0-alpha.0.0.0" { + t.Fatalf("latestTip = %q, want 27.0.0-alpha.0.0.0", got) + } +} + +func TestIsAlphaAndUnstableHelpers(t *testing.T) { + if !IsAlphaVersion("v27.0.0-alpha.0.0.0") { + t.Fatal("expected alpha") + } + if IsAlphaVersion("27.0.0-rc.1") { + t.Fatal("rc must not count as alpha") + } + if !IsUnstableVersion("27.0.0-rc.1") { + t.Fatal("expected unstable") + } + if IsUnstableVersion("27.0.0") { + t.Fatal("GA must be stable") + } +} + +func TestCanonicalVersion(t *testing.T) { + if got := CanonicalVersion("V27.0.0-Alpha.0.0.0"); got != "27.0.0-alpha.0.0.0" { + t.Fatalf("CanonicalVersion = %q", got) + } +} diff --git a/resolver/status.go b/resolver/status.go index d868f14..67c67f0 100644 --- a/resolver/status.go +++ b/resolver/status.go @@ -114,7 +114,7 @@ func resolveInstalledVersion(requestedVersion string, resolvePartialRemotely boo } // resolveLocalOnlyAlias maps default/current and user-defined aliases without -// touching the network. latest/lts still require the catalog via Find. +// touching the network. latest/lts/alpha still require the catalog via Find. func resolveLocalOnlyAlias(version string) (string, bool) { v := strings.ToLower(strings.TrimSpace(version)) if v == "" { @@ -127,7 +127,7 @@ func resolveLocalOnlyAlias(version string) (string, bool) { } return active, true } - if v == "latest" || v == "lts" || strings.HasPrefix(v, "lts/") { + if v == "latest" || v == "lts" || v == "alpha" || strings.HasPrefix(v, "lts/") { return "", false }