Skip to content

Add explicit ordering to diagnostic hints - #21577

Merged
zanieb merged 7 commits into
zb/hinted-precursor-20260910from
zb/hint-priority-precursor-20260910
Sep 11, 2026
Merged

zanieb merged 7 commits into
zb/hinted-precursor-20260910from
zb/hint-priority-precursor-20260910

Conversation

@zanieb

@zanieb zanieb commented Sep 10, 2026 •

Copy link
Copy Markdown
Member

Hint ordering currently depends on error-chain traversal and manually appending caller-provided advice. Add HintOrdering::{First, Any, Last} to individual Hint values and Hints collections so error types can specify where their guidance belongs. Borrowed iteration visits the three groups without sorting or allocating; owned iteration sorts the existing vector. Both retain insertion order within each group. Error and warning renderers borrow the collection. Unannotated hints use Any, and merging duplicate messages retains the earliest ordering. The operation reporter's caller-provided hints and tool script usage advice use Last.

Prior work:

This provides the ordering primitive for #17110 without requiring the command-layer collector to special-case error types.

@zanieb zanieb changed the title Add priorities to diagnostic hints Add explicit ordering to diagnostic hints Sep 10, 2026
@zanieb
zanieb force-pushed the zb/hint-priority-precursor-20260910 branch 2 times, most recently from c82a286 to a70281c Compare September 10, 2026 13:20
Comment thread crates/uv-errors/src/lib.rs Resolved
Comment thread crates/uv-errors/src/lib.rs Resolved
Comment thread crates/uv-errors/src/lib.rs Resolved
Comment thread crates/uv-errors/src/lib.rs Resolved
Comment thread crates/uv/src/commands/tool/run.rs Resolved
Comment thread crates/uv/src/commands/diagnostics.rs Resolved
@zanieb
zanieb removed this pull request from stack #21578 September 10, 2026 15:05
@zanieb
zanieb changed the base branch from main to zb/hinted-precursor-20260910 September 10, 2026 15:05
@zanieb
zanieb force-pushed the zb/hint-priority-precursor-20260910 branch from 7a856a9 to 34c8b2d Compare September 10, 2026 15:05
@zanieb
zanieb marked this pull request as ready for review September 10, 2026 15:06
@zanieb
zanieb added this pull request to stack #21585 September 10, 2026 15:07
@zanieb zanieb added internal A refactor or improvement that is not user-facing area:error-messages Messaging when something goes wrong labels Sep 10, 2026
@zanieb
zanieb removed this pull request from stack #21585 September 10, 2026 15:42
@zanieb
zanieb changed the base branch from zb/hinted-precursor-20260910 to main September 10, 2026 15:42
@zanieb
zanieb changed the base branch from main to zb/hinted-precursor-20260910 September 10, 2026 15:42
@zanieb
zanieb added this pull request to stack #21588 September 10, 2026 15:43
@zanieb
zanieb force-pushed the zb/hint-priority-precursor-20260910 branch from 34c8b2d to 0d76651 Compare September 10, 2026 21:51
@zanieb
zanieb force-pushed the zb/hint-priority-precursor-20260910 branch from 0d76651 to a352590 Compare September 11, 2026 18:12
@zanieb
zanieb merged commit 2a80362 into main Sep 11, 2026
135 of 142 checks passed
@zanieb
zanieb deleted the zb/hint-priority-precursor-20260910 branch September 11, 2026 18:37
zanieb added a commit that referenced this pull request Sep 11, 2026
Rename `uv_errors::Hint` to `Hinted`. The trait describes an error's
ability to provide a collection of contextual hints, while `Hint` is a
clearer name for an individual hint value. Update the implementations,
trait bounds, and callers without changing diagnostic output or error
classification.

Prior work:

- #18090 introduced the hint-producing trait and `Hints` collection.
- #20155 made hints explicit in error-chain rendering.

This prepares the concrete `Hint` type in #21577.
zanieb added a commit that referenced this pull request Sep 11, 2026
Route the remaining package-operation errors through `UvError` and the
standard error-chain renderer, then remove uv's direct `miette`
dependency and global hook. Diagnostics use the same source-chain
formatting and hint collection as other commands, with cause-specific
hints before general command advice. No-solution headings omit trailing
punctuation, retain their command context, and are not repeated inside
build-dependency errors. Final errors remain visible with `-q` and are
suppressed with `-qq`.

Classify operation failures by their underlying cause instead of by
which renderer handles them. Each error type owns its classification,
and type-erased build errors forward it. Expected package, resolution,
build, integrity, and lock-validation failures use code 1, while
recognized transport, cache, filesystem, and internal failures use code
2. This deliberately changes some previously inconsistent statuses
without attempting to normalize every standalone command or opaque
archive-error path. Command-line argument errors remain code 2.
Third-party dependencies may still use `miette` internally.

Prior work:

- #14546 removed `miette` from `uv venv`.
- #17535 added first-party line wrapping.
- #18090 established the `Hint` and `Hints` APIs.
- #20155 made hints explicit in error-chain rendering.
- #20156 preserved indentation in multiline causes.
- #20159 migrated `uv build` errors to standard rendering.
- #20160 migrated tool requirement errors to standard rendering.
- #20188 introduced the explicit `UvError` model.
- #20163 routed final errors through `Printer` for `-q` and `-qq`.
- #20217 enabled cause-chain rendering for user errors.
- #21563 added verification of index-provided metadata hashes.
- #21279 reused URL-provided hashes during resolution.
- #21584 renamed the hint-producing trait to `Hinted`.
- #21577 added explicit hint ordering.

Follow-up work:

- #21566 collects hints for batched `uv tool upgrade` failures and fixes
their quiet-mode output.
- #21568 routes Python upgrade request errors and version-file hints
through `UvError`.
- #21587 separates operation-specific diagnostic context from
exit-status classification.
- #21599 renders error and warning causes with compact tree connectors.

This branch was previously deployed

1 inactive deployment
automations — a352590f Deployed Sep 11, 2026 by zanieb via review / security review #46444
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:error-messages Messaging when something goes wrong internal A refactor or improvement that is not user-facing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant