aube_resolver/
error.rs

1use crate::ResolveTask;
2use crate::semver_util::highest_stable_version;
3use crate::trust::{MissingTimeDetails, TrustDowngradeDetails};
4use aube_codes::errors::*;
5use aube_registry::Packument;
6
7#[derive(Debug, thiserror::Error)]
8pub enum Error {
9    #[error("no version of {} matches range `{}`", .0.name, .0.range)]
10    NoMatch(Box<NoMatchDetails>),
11    #[error(
12        "no version of {} matching {} is older than {} minute(s) (minimumReleaseAgeStrict=true)",
13        .0.name, .0.range, .0.minutes
14    )]
15    AgeGate(Box<AgeGateDetails>),
16    #[error("registry error for {0}: {1}")]
17    Registry(String, String),
18    #[error(
19        "{}: catalog reference `{}` does not resolve — catalog `{}` is not defined (add it to `catalog:` / `catalogs.{}:` in pnpm-workspace.yaml, or under `workspaces.catalog` / `pnpm.catalog` in package.json)",
20        .0.name, .0.spec, .0.catalog, .0.catalog
21    )]
22    UnknownCatalog(Box<CatalogDetails>),
23    #[error(
24        "{}: catalog reference `{}` does not resolve — catalog `{}` has no entry for `{}`",
25        .0.name, .0.spec, .0.catalog, .0.name
26    )]
27    UnknownCatalogEntry(Box<CatalogDetails>),
28    #[error(
29        "blocked exotic transitive dependency {}@{} from {} (blockExoticSubdeps=true; set blockExoticSubdeps=false to allow trusted git/file/tarball subdeps)",
30        .0.name, .0.spec, .0.parent
31    )]
32    BlockedExoticSubdep(Box<ExoticSubdepDetails>),
33    #[error(
34        "trust downgrade for {}@{} (trustPolicy=no-downgrade): earlier published version {} had {} but this version has {}",
35        .0.name, .0.picked_version, .0.prior_version, .0.prior_evidence.label(),
36        .0.current_evidence.map_or("no trust evidence", |e| e.label())
37    )]
38    TrustDowngrade(Box<TrustDowngradeDetails>),
39    #[error(
40        "trust check failed for {}@{} (trustPolicy=no-downgrade): registry packument has no `time` entry for the picked version",
41        .0.name, .0.version
42    )]
43    TrustCheckMissingTime(Box<MissingTimeDetails>),
44    #[error(
45        "peer-context fixed-point did not converge after {0} iterations. mutually recursive peers, lockfile would be incomplete"
46    )]
47    PeerContextDivergence(usize),
48}
49
50/// Context attached to a `NoMatch` error so the miette `help()` output can
51/// show importer path, parent chain, and what versions the packument
52/// actually contains. Boxed into the enum variant to keep `Error`'s size
53/// under `clippy::result_large_err`.
54#[derive(Debug)]
55pub struct NoMatchDetails {
56    pub name: String,
57    pub range: String,
58    pub importer: String,
59    pub ancestors: Vec<(String, String)>,
60    pub original_spec: Option<String>,
61    /// Up to 5 most-recent version strings from the packument. Stable
62    /// versions are preferred; when the packument contains only
63    /// prereleases we fall back to showing those so the diagnostic
64    /// doesn't misreport the packument as empty.
65    pub available: Vec<String>,
66    /// Total number of versions in the packument, including prereleases
67    /// and unparseable keys. Used by the help text to distinguish a
68    /// genuinely empty packument (wrong registry, missing package) from
69    /// one that only publishes prereleases.
70    pub total_versions: usize,
71    /// True when every shown entry in `available` is a prerelease — the
72    /// user asked for a stable range but the registry only has alpha /
73    /// beta / rc builds. Help text steers them toward `name@next` or a
74    /// prerelease range.
75    pub only_prereleases: bool,
76}
77
78#[derive(Debug)]
79pub struct AgeGateDetails {
80    pub name: String,
81    pub range: String,
82    pub minutes: u64,
83    pub importer: String,
84    pub ancestors: Vec<(String, String)>,
85    /// Version strings that satisfied the range but were blocked by
86    /// the age gate, sorted newest-first. Empty when the cutoff was
87    /// tighter than every published version.
88    pub gated: Vec<String>,
89}
90
91#[derive(Debug)]
92pub struct CatalogDetails {
93    pub name: String,
94    pub spec: String,
95    pub catalog: String,
96    /// For `UnknownCatalog`: the catalog names that *are* defined.
97    /// For `UnknownCatalogEntry`: the package names defined under
98    /// `catalog`. Empty when the catalog map itself is empty, or
99    /// when the error is a chained-catalog case (see `chained_value`).
100    pub available: Vec<String>,
101    /// Set only for the chained-catalog case: the entry exists, but
102    /// its value is itself another `catalog:` reference. Carries the
103    /// offending value (e.g. `catalog:other`) so the help text can
104    /// explain the chain rule rather than pretending the entry is
105    /// missing.
106    pub chained_value: Option<String>,
107}
108
109#[derive(Debug)]
110pub struct ExoticSubdepDetails {
111    pub name: String,
112    pub spec: String,
113    pub parent: String,
114    pub ancestors: Vec<(String, String)>,
115    pub importer: String,
116}
117
118impl miette::Diagnostic for Error {
119    fn code<'a>(&'a self) -> Option<Box<dyn std::fmt::Display + 'a>> {
120        Some(Box::new(match self {
121            Self::NoMatch(_) => ERR_AUBE_NO_MATCHING_VERSION,
122            Self::AgeGate(_) => ERR_AUBE_NO_MATURE_MATCHING_VERSION,
123            Self::Registry(_, _) => ERR_AUBE_REGISTRY_ERROR,
124            Self::UnknownCatalog(_) => ERR_AUBE_UNKNOWN_CATALOG,
125            Self::UnknownCatalogEntry(_) => ERR_AUBE_UNKNOWN_CATALOG_ENTRY,
126            Self::BlockedExoticSubdep(_) => ERR_AUBE_BLOCKED_EXOTIC_SUBDEP,
127            Self::TrustDowngrade(_) => ERR_AUBE_TRUST_DOWNGRADE,
128            Self::TrustCheckMissingTime(_) => ERR_AUBE_TRUST_MISSING_TIME,
129            Self::PeerContextDivergence(_) => ERR_AUBE_PEER_CONTEXT_NOT_CONVERGED,
130        }))
131    }
132
133    fn help<'a>(&'a self) -> Option<Box<dyn std::fmt::Display + 'a>> {
134        match self {
135            Self::NoMatch(d) => Some(Box::new(format_no_match_help(d))),
136            Self::AgeGate(d) => Some(Box::new(format_age_gate_help(d))),
137            Self::Registry(name, msg) => Some(Box::new(format_registry_help(name, msg))),
138            Self::UnknownCatalog(d) => Some(Box::new(format_unknown_catalog_help(d))),
139            Self::UnknownCatalogEntry(d) => Some(Box::new(format_unknown_catalog_entry_help(d))),
140            Self::BlockedExoticSubdep(d) => Some(Box::new(format_exotic_subdep_help(d))),
141            Self::TrustDowngrade(d) => Some(Box::new(format_trust_downgrade_help(d))),
142            Self::TrustCheckMissingTime(d) => Some(Box::new(format_trust_missing_time_help(d))),
143            Self::PeerContextDivergence(_) => None,
144        }
145    }
146}
147
148fn format_trust_downgrade_help(d: &TrustDowngradeDetails) -> String {
149    format!(
150        "a trust downgrade may indicate a supply-chain incident — the publisher's previous releases carried {evidence} but {name}@{ver} does not.\n\
151         to bypass: pin a version that retains evidence, set `trustPolicy = off` in .npmrc / pnpm-workspace.yaml, \
152         or add `{name}` (or `{name}@{ver}`) to `trustPolicyExclude`.",
153        evidence = d.prior_evidence.label(),
154        name = d.name,
155        ver = d.picked_version,
156    )
157}
158
159fn format_trust_missing_time_help(d: &MissingTimeDetails) -> String {
160    format!(
161        "trustPolicy=no-downgrade compares against per-version publish times in the packument. \
162         The registry serving {name} omitted `time[{ver}]` — check the registry config in .npmrc, \
163         or set `trustPolicy = off` to skip the check.",
164        name = d.name,
165        ver = d.version,
166    )
167}
168
169/// Build a `NoMatchDetails` snapshot from the task that failed and the
170/// packument it was looked up against. Captures importer, parent chain,
171/// the original package.json spec (if rewritten by catalog/override/
172/// alias), and a sample of the highest non-prerelease versions so the
173/// diagnostic can tell the user how close they were.
174pub(crate) fn build_no_match(task: &ResolveTask, packument: &Packument) -> NoMatchDetails {
175    let mut stable: Vec<(node_semver::Version, &str)> = Vec::new();
176    let mut prerelease: Vec<(node_semver::Version, &str)> = Vec::new();
177    for v in packument.versions.keys() {
178        let Ok(parsed) = node_semver::Version::parse(v) else {
179            continue;
180        };
181        if parsed.pre_release.is_empty() {
182            stable.push((parsed, v.as_str()));
183        } else {
184            prerelease.push((parsed, v.as_str()));
185        }
186    }
187    stable.sort_by(|a, b| b.0.cmp(&a.0));
188    prerelease.sort_by(|a, b| b.0.cmp(&a.0));
189    let (pool, only_prereleases) = if stable.is_empty() {
190        (prerelease, true)
191    } else {
192        (stable, false)
193    };
194    let available = pool
195        .into_iter()
196        .take(5)
197        .map(|(_, s)| s.to_string())
198        .collect();
199    NoMatchDetails {
200        name: task.name.clone(),
201        range: task.range.clone(),
202        importer: task.importer.clone(),
203        ancestors: task.ancestors.clone(),
204        original_spec: task.original_specifier.clone(),
205        available,
206        total_versions: packument.versions.len(),
207        only_prereleases,
208    }
209}
210
211/// Build an `AgeGateDetails` snapshot: which versions actually
212/// satisfied the range but were blocked by the cutoff. Recomputed from
213/// the packument rather than threaded out of `pick_version` because
214/// the age-gate path is uncommon and the recompute cost is dwarfed by
215/// the resolution itself.
216/// Resolve a `task.range` string that may be a dist-tag (`"latest"`,
217/// `"next"`, …) to the concrete version it points at. Used by the
218/// diagnostic builders where we need to parse the range for display
219/// purposes after `pick_version` has already accepted or rejected it.
220/// Falls back to the raw input when nothing matches — callers treat a
221/// subsequent semver parse failure as "skip, best-effort".
222fn resolve_dist_tag_range(packument: &Packument, range_str: &str) -> String {
223    if let Some(tagged) = packument.dist_tags.get(range_str) {
224        tagged.clone()
225    } else if range_str == "latest"
226        && let Some(v) = highest_stable_version(packument)
227    {
228        v
229    } else {
230        range_str.to_string()
231    }
232}
233
234pub(crate) fn build_age_gate(
235    task: &ResolveTask,
236    packument: &Packument,
237    minutes: u64,
238) -> AgeGateDetails {
239    // Mirror `pick_version`'s dist-tag handling: if `task.range` is a
240    // tag name (e.g. `"latest"`, `"next"`), resolve it to the concrete
241    // version string before parsing. Without this the semver parse
242    // fails silently and the help text drops the "blocked by age gate"
243    // line entirely, losing the most useful diagnostic.
244    let effective = resolve_dist_tag_range(packument, &task.range);
245    let range = node_semver::Range::parse(&effective).ok();
246    let mut gated: Vec<(node_semver::Version, String)> = Vec::new();
247    if let Some(r) = range {
248        for ver in packument.versions.keys() {
249            let Ok(v) = node_semver::Version::parse(ver) else {
250                continue;
251            };
252            if !v.satisfies(&r) {
253                continue;
254            }
255            gated.push((v, ver.clone()));
256        }
257    }
258    gated.sort_by(|a, b| b.0.cmp(&a.0));
259    AgeGateDetails {
260        name: task.name.clone(),
261        range: task.range.clone(),
262        minutes,
263        importer: task.importer.clone(),
264        ancestors: task.ancestors.clone(),
265        gated: gated.into_iter().map(|(_, s)| s).collect(),
266    }
267}
268
269fn format_no_match_help(d: &NoMatchDetails) -> String {
270    let mut s = String::new();
271    push_importer(&mut s, &d.importer);
272    push_chain(&mut s, &d.ancestors, &d.name);
273    if let Some(orig) = &d.original_spec
274        && orig != &d.range
275    {
276        s.push_str(&format!(
277            "original spec: `{orig}` (rewritten to `{}`)\n",
278            d.range
279        ));
280    }
281    if d.available.is_empty() {
282        if d.total_versions == 0 {
283            s.push_str("packument has no versions — check that the package exists on the configured registry");
284        } else {
285            s.push_str(&format!(
286                "packument has {} unparseable version(s) — check registry for non-semver tags",
287                d.total_versions
288            ));
289        }
290    } else if d.only_prereleases {
291        s.push_str(&format!(
292            "no stable versions published; only prereleases available: {}\nhint: request a prerelease explicitly (e.g. `{}@{}`) or via the `next` dist-tag",
293            d.available.join(", "),
294            d.name,
295            d.available.first().map(String::as_str).unwrap_or("next"),
296        ));
297    } else {
298        s.push_str(&format!("available versions: {}", d.available.join(", ")));
299    }
300    s
301}
302
303fn format_age_gate_help(d: &AgeGateDetails) -> String {
304    let mut s = String::new();
305    push_importer(&mut s, &d.importer);
306    push_chain(&mut s, &d.ancestors, &d.name);
307    if !d.gated.is_empty() {
308        s.push_str(&format!(
309            "blocked by age gate: {}\n",
310            d.gated
311                .iter()
312                .take(5)
313                .cloned()
314                .collect::<Vec<_>>()
315                .join(", ")
316        ));
317    }
318    s.push_str("to bypass: loosen `minimumReleaseAge` in .npmrc, set `minimumReleaseAgeStrict=false` to fall back to the lowest satisfying version, or add `");
319    s.push_str(&d.name);
320    s.push_str("` to `minimumReleaseAgeExclude`");
321    s
322}
323
324pub(crate) fn format_registry_help(name: &str, msg: &str) -> String {
325    let kind = classify_registry_error(msg);
326    let mut s = String::new();
327    if !name.is_empty() && name != "(resolver)" {
328        s.push_str(&format!("package: {name}\n"));
329    }
330    s.push_str(match kind {
331        RegistryErrorKind::Tarball => {
332            "tarball download or integrity check failed — try `aube store prune` to clear the cache; if the lockfile references a tarball that moved, delete the lockfile entry for this package and re-resolve"
333        }
334        RegistryErrorKind::Fetch => {
335            "packument fetch failed — verify the registry URL in .npmrc, check auth (`npm login` / `NPM_TOKEN`), and confirm network connectivity"
336        }
337        RegistryErrorKind::Git => {
338            "git dep failed to resolve — confirm the ref exists, that credentials are configured for the host, and that the URL form is supported"
339        }
340        RegistryErrorKind::LocalSpec => {
341            "unparseable local specifier — `file:`/`link:`/`workspace:` paths must be relative to the importer, and `http(s):` URLs must end in `.tgz`"
342        }
343        RegistryErrorKind::Hook => {
344            "pnpmfile `readPackage` hook returned an error — check the hook's stack trace above for the underlying cause"
345        }
346        RegistryErrorKind::ResolverBug => {
347            "internal resolver invariant violated — please report at https://github.com/jdx/aube/discussions with the lockfile and command that reproduced this"
348        }
349        RegistryErrorKind::Generic => {
350            "registry operation failed — see the message above for the underlying cause"
351        }
352    });
353    s
354}
355
356fn format_unknown_catalog_help(d: &CatalogDetails) -> String {
357    let mut s = String::new();
358    if d.available.is_empty() {
359        s.push_str("no catalogs are defined in this workspace; add a `catalog:` block to `pnpm-workspace.yaml` or a `workspaces.catalog` entry in root `package.json`");
360    } else {
361        s.push_str(&format!("defined catalogs: {}", d.available.join(", ")));
362    }
363    s
364}
365
366fn format_unknown_catalog_entry_help(d: &CatalogDetails) -> String {
367    if let Some(chained) = &d.chained_value {
368        return format!(
369            "catalogs cannot chain — replace `{}` with a concrete semver range (e.g. `^1.0.0`) under the catalog entry",
370            chained
371        );
372    }
373    let mut s = String::new();
374    if d.available.is_empty() {
375        s.push_str(&format!(
376            "catalog `{}` is empty; add `{}: <version>` under `catalogs.{}` in pnpm-workspace.yaml",
377            d.catalog, d.name, d.catalog
378        ));
379    } else {
380        let suggestion = suggest_similar(&d.name, &d.available);
381        if let Some(best) = suggestion {
382            s.push_str(&format!(
383                "catalog `{}` defines: {} — did you mean `{}`?",
384                d.catalog,
385                truncate_list(&d.available, 8),
386                best
387            ));
388        } else {
389            s.push_str(&format!(
390                "catalog `{}` defines: {}",
391                d.catalog,
392                truncate_list(&d.available, 8)
393            ));
394        }
395    }
396    s
397}
398
399fn format_exotic_subdep_help(d: &ExoticSubdepDetails) -> String {
400    let mut s = String::new();
401    push_importer(&mut s, &d.importer);
402    push_chain(&mut s, &d.ancestors, &d.name);
403    s.push_str(&format!(
404        "to allow: either pin `{}` in your root package.json (moves the exotic spec out of the transitive graph), or set `blockExoticSubdeps=false` in .npmrc / settings.toml to trust every transitive git/file/tarball dep",
405        d.name
406    ));
407    s
408}
409
410fn push_importer(s: &mut String, importer: &str) {
411    if !importer.is_empty() && importer != "." {
412        s.push_str(&format!("importer: {importer}\n"));
413    }
414}
415
416fn push_chain(s: &mut String, ancestors: &[(String, String)], leaf: &str) {
417    if ancestors.is_empty() {
418        return;
419    }
420    s.push_str("chain: ");
421    for (i, (n, v)) in ancestors.iter().enumerate() {
422        if i > 0 {
423            s.push_str(" > ");
424        }
425        s.push_str(&format!("{n}@{v}"));
426    }
427    s.push_str(&format!(" > {leaf}\n"));
428}
429
430fn truncate_list(items: &[String], max: usize) -> String {
431    if items.len() <= max {
432        items.join(", ")
433    } else {
434        let (head, tail) = items.split_at(max);
435        format!("{} (+{} more)", head.join(", "), tail.len())
436    }
437}
438
439/// Suggest the closest string in `choices` to `needle` using a simple
440/// case-insensitive prefix/substring match, falling back to first-char
441/// equality. Returns `None` when nothing plausibly matches. This is a
442/// deliberately cheap heuristic — good enough for catalog typos,
443/// nothing more.
444fn suggest_similar<'a>(needle: &str, choices: &'a [String]) -> Option<&'a str> {
445    let lower = needle.to_ascii_lowercase();
446    choices
447        .iter()
448        .map(String::as_str)
449        .find(|c| {
450            c.to_ascii_lowercase().contains(&lower) || lower.contains(&c.to_ascii_lowercase())
451        })
452        .or_else(|| {
453            choices
454                .iter()
455                .map(String::as_str)
456                .find(|c| c.chars().next() == needle.chars().next())
457        })
458}
459
460pub(crate) enum RegistryErrorKind {
461    Tarball,
462    Fetch,
463    Git,
464    LocalSpec,
465    Hook,
466    ResolverBug,
467    Generic,
468}
469
470/// Coarse classification by substring match. Registry errors carry
471/// free-form `format!` strings from helper functions that already embed
472/// intent ("fetch ", "tarball ", "git ", "readPackage", etc.), so a
473/// lightweight match on those prefixes lets us pick a targeted help
474/// message without plumbing a new enum through every call site.
475pub(crate) fn classify_registry_error(msg: &str) -> RegistryErrorKind {
476    let lower = msg.to_ascii_lowercase();
477    // Specific-prefix branches (git, hook, local-spec) must run before
478    // the generic `http` / `tarball` substring checks: each of those
479    // error payloads can itself embed an https:// URL or a tarball
480    // path, so a bare substring match on later arms would steal them.
481    if lower.starts_with("git resolve ")
482        || lower.starts_with("git dep ")
483        || lower.starts_with("git task ")
484        || lower.contains("git+")
485    {
486        RegistryErrorKind::Git
487    } else if lower.starts_with("readpackage ") || lower.contains("readpackage hook") {
488        RegistryErrorKind::Hook
489    } else if lower.starts_with("unparseable local specifier") || lower.contains("workspace:") {
490        RegistryErrorKind::LocalSpec
491    } else if lower.contains("tarball") || lower.contains("integrity") {
492        RegistryErrorKind::Tarball
493    } else if lower.starts_with("fetch ") || lower.contains("packument") || lower.contains("http") {
494        RegistryErrorKind::Fetch
495    } else if lower.contains("deferred") || lower.contains("invariant") {
496        RegistryErrorKind::ResolverBug
497    } else {
498        RegistryErrorKind::Generic
499    }
500}
aube_resolver/error.rs

aube_resolver/
error.rs
