aube_resolver/types.rs
1use aube_lockfile::LocalSource;
2use std::collections::{BTreeMap, BTreeSet, HashSet};
3use std::future::Future;
4use std::pin::Pin;
5use std::sync::Arc;
6use std::time::{SystemTime, UNIX_EPOCH};
7
8/// Hook invoked once per resolved package, right after its version has
9/// been picked from the packument and before its dependency set is
10/// enqueued. Implementations may mutate `dependencies`,
11/// `optionalDependencies`, `peerDependencies`, and
12/// `peerDependenciesMeta`; every other field is ignored on the way
13/// back, matching how pnpm's `readPackage` hook is used in the wild.
14///
15/// The trait is deliberately shaped to let a single long-lived node
16/// subprocess implement it — `&mut self` so the impl can own stdin /
17/// stdout halves of the child without interior mutability, and a boxed
18/// future because `async fn` in dyn-compatible traits still requires
19/// third-party crates we haven't pulled in.
20pub trait ReadPackageHook: Send {
21 fn read_package<'a>(
22 &'a mut self,
23 pkg: aube_registry::VersionMetadata,
24 ) -> Pin<Box<dyn Future<Output = Result<aube_registry::VersionMetadata, String>> + Send + 'a>>;
25}
26
27/// Supply-chain mitigation: forbid versions younger than `min_age` for
28/// every package whose name isn't in `exclude`. Mirrors pnpm's
29/// `minimumReleaseAge` / `minimumReleaseAgeExclude` /
30/// `minimumReleaseAgeStrict` triplet. Constructed by the install
31/// command, threaded into [`Resolver::with_minimum_release_age`].
32#[derive(Debug, Clone, Default)]
33pub struct MinimumReleaseAge {
34 /// Minutes a version must have aged in the registry. `0` disables.
35 pub minutes: u64,
36 /// Package names skipped by the cutoff filter entirely.
37 pub exclude: HashSet<String>,
38 /// When true, fail the install if no version satisfies the range
39 /// without violating the cutoff. When false (the pnpm default), the
40 /// resolver falls back to the lowest satisfying version, ignoring
41 /// the cutoff for that pick only.
42 pub strict: bool,
43}
44
45#[derive(Debug, Clone)]
46pub struct DependencyPolicy {
47 pub package_extensions: Vec<PackageExtension>,
48 pub allowed_deprecated_versions: BTreeMap<String, String>,
49 pub trust_policy: TrustPolicy,
50 pub trust_policy_exclude: BTreeSet<String>,
51 pub trust_policy_ignore_after: Option<u64>,
52 pub block_exotic_subdeps: bool,
53}
54
55impl Default for DependencyPolicy {
56 fn default() -> Self {
57 Self {
58 package_extensions: Vec::new(),
59 allowed_deprecated_versions: BTreeMap::new(),
60 trust_policy: TrustPolicy::default(),
61 trust_policy_exclude: BTreeSet::new(),
62 trust_policy_ignore_after: None,
63 block_exotic_subdeps: true,
64 }
65 }
66}
67
68#[derive(Debug, Clone, Default, PartialEq, Eq)]
69pub struct PackageExtension {
70 pub selector: String,
71 pub dependencies: BTreeMap<String, String>,
72 pub optional_dependencies: BTreeMap<String, String>,
73 pub peer_dependencies: BTreeMap<String, String>,
74 pub peer_dependencies_meta: BTreeMap<String, aube_registry::PeerDepMeta>,
75}
76
77#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
78pub enum TrustPolicy {
79 NoDowngrade,
80 #[default]
81 Off,
82}
83
84impl MinimumReleaseAge {
85 /// Compute the absolute ISO-8601 UTC cutoff string. Returns `None`
86 /// when the feature is disabled (`minutes == 0`). Format matches
87 /// the npm registry's `time` map so a lexicographic compare on the
88 /// raw strings doubles as an instant compare.
89 pub fn cutoff(&self) -> Option<String> {
90 if self.minutes == 0 {
91 return None;
92 }
93 let now = SystemTime::now().duration_since(UNIX_EPOCH).ok()?.as_secs();
94 let cutoff_secs = now.saturating_sub(self.minutes * 60);
95 Some(format_iso8601_utc(cutoff_secs))
96 }
97}
98
99/// Format a Unix epoch second count as an ISO-8601 UTC `Z` string. The
100/// resolver only ever compares these against npm registry timestamps,
101/// which are emitted in this exact shape — so we can ship our own
102/// formatter and skip pulling in `chrono`/`time`. Algorithm adapted
103/// from the days-from-epoch trick used by `time` and `civil` crates.
104///
105/// `aube/src/commands/sbom.rs` carries a near-identical formatter
106/// for the SPDX/CycloneDX writers; that one emits seconds-only
107/// (`...:00Z`) since SBOM consumers don't expect millis. Don't merge
108/// without checking which format each caller needs — the npm registry
109/// `time` map always uses `.000Z`, lex compare relies on it.
110pub(crate) fn format_iso8601_utc(epoch_secs: u64) -> String {
111 let days = (epoch_secs / 86_400) as i64;
112 let secs_of_day = epoch_secs % 86_400;
113 let h = secs_of_day / 3600;
114 let m = (secs_of_day % 3600) / 60;
115 let s = secs_of_day % 60;
116 let (y, mo, d) = civil_from_days(days);
117 format!("{y:04}-{mo:02}-{d:02}T{h:02}:{m:02}:{s:02}.000Z")
118}
119
120/// Convert a day count from the Unix epoch (1970-01-01) to a
121/// proleptic Gregorian (year, month, day). Lifted from Howard Hinnant's
122/// `civil_from_days` paper, which the `time` crate uses.
123fn civil_from_days(days: i64) -> (i64, u32, u32) {
124 let z = days + 719_468;
125 let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
126 let doe = (z - era * 146_097) as u64;
127 let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
128 let y = yoe as i64 + era * 400;
129 let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
130 let mp = (5 * doy + 2) / 153;
131 let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
132 let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
133 let y = if m <= 2 { y + 1 } else { y };
134 (y, m, d)
135}
136
137/// A resolved package emitted during resolution, allowing the caller
138/// to start fetching tarballs before resolution is fully complete.
139#[derive(Debug, Clone)]
140pub struct ResolvedPackage {
141 pub dep_path: String,
142 pub name: String,
143 pub version: String,
144 pub integrity: Option<String>,
145 /// Exact tarball URL reported by the packument's `dist.tarball`
146 /// field, or preserved from an existing lockfile. Most npm
147 /// packages can re-derive this from name + version, but JSR's
148 /// npm-compatible registry uses opaque tarball paths, so fetchers
149 /// must prefer this when it is available.
150 pub tarball_url: Option<String>,
151 /// Real registry name when this package is an npm-alias
152 /// (`"h3-v2": "npm:h3@..."`). `name` is the alias (`h3-v2` — the
153 /// folder in `node_modules/`), `alias_of` is what the streaming
154 /// fetch client uses to derive the tarball URL and store-index
155 /// key. `None` for non-aliased packages, in which case `name`
156 /// already matches the registry.
157 pub alias_of: Option<String>,
158 /// Set for non-registry packages (`file:` / `link:`). Downstream
159 /// fetchers short-circuit the tarball path and materialize from
160 /// disk instead.
161 pub local_source: Option<LocalSource>,
162 /// npm `os`/`cpu`/`libc` arrays straight from the packument (or
163 /// lockfile). The streaming fetch coordinator uses them to defer
164 /// tarball downloads for optional natives that won't install on
165 /// the host — a post-resolve catch-up pass after `filter_graph`
166 /// fetches anything that survived the graph trim but got deferred,
167 /// so required-platform-mismatched packages (which `filter_graph`
168 /// doesn't drop) still get their tarball before link.
169 pub os: aube_lockfile::PlatformList,
170 pub cpu: aube_lockfile::PlatformList,
171 pub libc: aube_lockfile::PlatformList,
172 /// Deprecation message from the registry, carried forward so the
173 /// install command can render user-facing warnings without a
174 /// second packument fetch. Only populated on the fresh-resolve
175 /// path; lockfile-reuse and `file:`/`link:` packages carry `None`
176 /// because the packument wasn't consulted. `allowedDeprecatedVersions`
177 /// suppression is applied upstream, so anything set here is meant
178 /// to surface to the user.
179 pub deprecated: Option<Arc<str>>,
180}
181
182impl ResolvedPackage {
183 /// Registry lookup name — `alias_of` when set, otherwise `name`.
184 /// Every tarball URL + store index site routes through this
185 /// accessor so aliased packages resolve to the real registry
186 /// entry without leaking the alias-qualified name into network
187 /// requests (where it would 404).
188 pub fn registry_name(&self) -> &str {
189 self.alias_of.as_deref().unwrap_or(&self.name)
190 }
191}
192
193/// Which version-picking strategy the resolver uses for a workspace.
194/// Mirrors pnpm's `resolution-mode` setting.
195#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
196pub enum ResolutionMode {
197 /// Classic pnpm behavior: every dep resolves to the highest version
198 /// satisfying its range.
199 #[default]
200 Highest,
201 /// Pick the lowest version that satisfies each direct-dep range,
202 /// then constrain transitive picks to versions published on or
203 /// before a cutoff date derived from the max publish time of
204 /// already-locked packages. Matches pnpm's `time-based` mode.
205 TimeBased,
206}