Skip to content

fix(aqua): resolve versions by semantic precedence - #11457

Closed
pepicrft wants to merge 2 commits into
jdx:mainfrom
pepicrft:agent/aqua-semver-version-sort
Closed

pepicrft wants to merge 2 commits into
jdx:mainfrom
pepicrft:agent/aqua-semver-version-sort

Conversation

@pepicrft

@pepicrft pepicrft commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

What changed

  • Added an opt-in Aqua backend option, version_sort = "semver", that orders matching releases by semantic versioning precedence.
  • Configured Tuist's Aqua registry entry to use semantic version ordering.
  • Documented the option and its fallback behavior.

Why

mise latest tuist should resolve to the highest stable Tuist version even when an older release line receives a newer backport.

Root cause

The Aqua backend normally preserves the order returned by the upstream release source. When GitHub's marked latest release belongs to another package in the Tuist repository, mise falls back to release chronology. Tuist 4.197.3 was published after 4.202.6, so the chronological fallback selected the lower version.

Approach

The new behavior is opt-in because Aqua packages do not all use semantic versioning. When enabled, mise skips the marked-latest shortcut, collects matching release candidates, and orders valid semantic versions by precedence. If any candidate is not a valid semantic version, mise preserves the upstream order.

Impact

Tuist now resolves latest and version prefixes by semantic version precedence. Existing Aqua tools keep their current ordering unless they explicitly enable the option.

Validation

  • /Users/pepicrft/.cargo/bin/cargo fmt --all -- --check
  • /Users/pepicrft/.cargo/bin/cargo test backend::aqua::tests:: with 52 tests passed
  • git diff --check

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.

Summary by CodeRabbit

  • New Features

    • Added optional version_sort="semver" behavior for Aqua-managed tools, using semantic version precedence for latest and version-prefix matching.
    • When semver parsing succeeds, matching results are semver-sorted; when parsing fails, the original upstream ordering is preserved.
    • Enabled semantic version sorting for the Tuist Aqua backend in the registry configuration.
  • Documentation

    • Documented the Aqua version_sort option, including the semver-based resolution and fallback behavior.

@coderabbitai

coderabbitai Bot commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Adds Aqua semantic version sorting through version_sort = "semver", configures it for Tuist, documents the option, updates version resolution and lockfile handling, threads options through matching APIs, and adds sorting and fallback tests.

Changes

Aqua semantic version sorting

Layer / File(s) Summary
Option contract and configuration
src/backend/aqua.rs, registry/tuist.toml, docs/dev-tools/backends/aqua.md
Defines and documents version_sort = "semver", excludes it from canonical and install-time options, and enables it for Tuist.
Version matching option plumbing
src/backend/mod.rs, src/backend/pipx.rs, src/backend/ubi.rs, src/plugins/core/java.rs, src/plugins/core/python.rs
Extends fuzzy matching to receive resolved tool options and updates backend and plugin call sites and implementations.
Semantic version resolution and validation
src/backend/aqua.rs
Applies semantic ordering during Aqua matching, adjusts latest-stable resolution, and tests lockfile filtering, default ordering, invalid-version fallback, and build metadata.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: jdx

Poem

A rabbit hops through tags in line,
Sorting versions crisp and fine.
Semver carrots, neatly spun,
Fallback paths for everyone.
Tuist blooms with Aqua cheer—
Latest picks are hopping here!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed Docstring coverage is 93.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: Aqua version resolution now uses semantic precedence when enabled.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/backend/aqua.rs`:
- Around line 3356-3358: Update the version sorting comparator in the versions
collection flow to use semantic precedence via left.cmp_precedence(right)
instead of Version::cmp. Keep the existing zip, sort, and version extraction
behavior unchanged so build metadata does not affect ordering.
- Around line 745-750: Update the aqua version-matching helper around the
semantic-sort check to accept and use resolved ToolRequest options from
request.options() instead of self.ba.opts(). Thread those options through
fuzzy_match_filter and related callers, preserving the existing semver decision,
and add a request-level regression test covering tools-table version_sort =
"semver".
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 8ed8f931-d110-4ccc-b707-791228757f9c

📥 Commits

Reviewing files that changed from the base of the PR and between 45ed5e6 and f5707b3.

📒 Files selected for processing (3)
  • docs/dev-tools/backends/aqua.md
  • registry/tuist.toml
  • src/backend/aqua.rs

Comment thread src/backend/aqua.rs Outdated
Comment thread src/backend/aqua.rs
@pepicrft
pepicrft marked this pull request as ready for review July 29, 2026 15:06
@greptile-apps

greptile-apps Bot commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

Adds opt-in semantic-precedence sorting for Aqua version matching, enables it for Tuist, propagates tool options through backend matching APIs, and documents fallback to upstream ordering when candidates are not valid semantic versions.

Confidence Score: 5/5

The PR appears safe to merge with no concrete correctness or security defects identified.

Semantic ordering is opt-in, is applied after candidate filtering, falls back without reordering when parsing fails, and the highest-precedence candidate remains the one selected by the existing resolution flow.

Important Files Changed

Filename Overview
src/backend/aqua.rs Adds semantic version sorting, bypasses the marked-latest shortcut when enabled, excludes the resolution-only option from installation state, and covers ordering and fallback behavior with tests.
src/backend/mod.rs Extends fuzzy matching with resolved tool options so backend-specific ordering can be applied during remote and installed version matching.
registry/tuist.toml Enables semantic version ordering for the Tuist Aqua backend while preserving the existing asdf fallback.
docs/dev-tools/backends/aqua.md Documents the new option, its intended use for latest and prefix resolution, and its all-candidates-valid fallback behavior.
src/plugins/core/java.rs Adapts Java’s custom matching implementation and callers to the expanded backend trait contract without changing matching behavior.
src/backend/pipx.rs Adapts PIPX’s PEP 440 matcher to the expanded backend trait signature without behavioral changes.
src/backend/ubi.rs Adapts UBI’s custom matcher to the expanded backend trait signature without behavioral changes.
src/plugins/core/python.rs Adapts Python’s PEP 440 matcher to the expanded backend trait signature without behavioral changes.

Reviews (1): Last reviewed commit: "fix(aqua): honor resolved version sort o..." | Re-trigger Greptile

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: be2ef0f5e5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/backend/aqua.rs
}
};
let mut versions = versions.into_iter().zip(parsed).collect::<Vec<_>>();
versions.sort_by(|(_, left), (_, right)| left.cmp_precedence(right));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Avoid local SemVer ordering for Aqua resolution

For any Aqua tool opting into version_sort = "semver", this comparator determines the final element selected for both latest and prefix requests. This directly violates the repository invariant prohibiting new SemVer comparators for newest-version selection, since mise versions must remain opaque and resolution should preserve backend-defined semantics. Preserve upstream ordering or implement the correction through a package-aware backend path instead. AI-assisted — Tool: Codex; model: OpenAI/GPT-5.6 Sol; version: unavailable.

AGENTS.md reference: AGENTS.md:L221-L225

Useful? React with 👍 / 👎.

risu729 commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Thanks for identifying and demonstrating the Tuist ordering bug here. I opened #11481 as the generic follow-up that supersedes this implementation. It preserves the opt-in SemVer approach, but moves version_order into mise's shared resolution layer so it also covers the pnpm case from the source discussion, bypasses all backend latest shortcuts consistently, and leaves mise-versions/ls-remote data in source order. The new PR links and credits this one in its rationale.

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.

@github-actions

github-actions Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

This PR currently has merge conflicts. If this continues for 7 days, it will be closed automatically.

This is warning day 1 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This comment was generated by an automated workflow.

@github-actions

github-actions Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

This PR currently has merge conflicts. If this continues for 7 days, it will be closed automatically.

This is warning day 2 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This comment was generated by an automated workflow.

@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

This PR currently has merge conflicts. If this continues for 7 days, it will be closed automatically.

This is warning day 3 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This comment was generated by an automated workflow.

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

This PR currently has merge conflicts. If this continues for 7 days, it will be closed automatically.

This is warning day 4 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This comment was generated by an automated workflow.

jdx commented Aug 10, 2026

Copy link
Copy Markdown
Owner

Closing as superseded by #11774, which merged the shared version_order implementation and incorporates the backend-specific boundary explored here.

AI-assisted — Tool: Codex; model: OpenAI/GPT-5.6 Sol; version: unavailable.

@jdx jdx closed this Aug 10, 2026
@pepicrft

Copy link
Copy Markdown
Contributor Author

Thanks @jdx

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants