Skip to main content

offline_registry/
resolve.rs

1//! Package resolution: expand a requested package set (or a workflow +
2//! platform) into the full ordered install list with versions, peer
3//! dependencies, platform-compatibility checks, and license call-outs.
4
5use std::collections::{BTreeMap, BTreeSet, VecDeque};
6
7use serde::Serialize;
8
9use crate::store::Registry;
10use crate::RegistryError;
11
12#[derive(Debug, Clone, Serialize)]
13#[serde(rename_all = "camelCase")]
14pub struct ResolvedPackage {
15    pub name: String,
16    pub version: String,
17    pub registry: String,
18    pub license: String,
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub license_note: Option<String>,
21    /// Why this package is in the set: `requested` or `required by <pkg>`.
22    pub reason: String,
23    pub status: String,
24    /// The package's own install instruction, when its registry has no
25    /// default command (a Swift package, a release download).
26    #[serde(skip_serializing_if = "Option::is_none")]
27    pub install: Option<String>,
28}
29
30#[derive(Debug, Clone, Serialize)]
31#[serde(rename_all = "camelCase")]
32pub struct Resolution {
33    pub platform: String,
34    pub packages: Vec<ResolvedPackage>,
35    /// Peer dependencies the host app must provide (name -> version range).
36    pub peer_dependencies: BTreeMap<String, String>,
37    /// Ready-to-run install commands.
38    pub install_commands: Vec<String>,
39    /// Non-fatal compatibility or licensing notices.
40    pub warnings: Vec<String>,
41}
42
43impl Registry {
44    /// Resolve an explicit package list for a platform.
45    pub fn resolve_packages(
46        &self,
47        requested: &[String],
48        platform: &str,
49    ) -> Result<Resolution, RegistryError> {
50        let mut order: Vec<String> = Vec::new();
51        let mut seen: BTreeSet<String> = BTreeSet::new();
52        let mut reasons: BTreeMap<String, String> = BTreeMap::new();
53        let mut queue: VecDeque<String> = VecDeque::new();
54
55        for name in requested {
56            let pkg = self
57                .package(name)
58                .ok_or_else(|| RegistryError::NotFound(format!("package `{name}`")))?;
59            reasons.insert(pkg.name.clone(), "requested".to_string());
60            queue.push_back(pkg.name.clone());
61        }
62
63        while let Some(name) = queue.pop_front() {
64            if !seen.insert(name.clone()) {
65                continue;
66            }
67            order.push(name.clone());
68            let pkg = self.package(&name).expect("validated in registry load");
69            for req in &pkg.requires {
70                reasons
71                    .entry(req.clone())
72                    .or_insert_with(|| format!("required by {name}"));
73                queue.push_back(req.clone());
74            }
75        }
76
77        let mut warnings = Vec::new();
78        let mut peer_dependencies = BTreeMap::new();
79        let mut packages = Vec::new();
80        for name in &order {
81            let pkg = self.package(name).expect("seen packages exist");
82            if !pkg.platforms.iter().any(|p| p == platform) {
83                return Err(RegistryError::Incompatible(format!(
84                    "package `{}` supports platforms [{}], not `{platform}`",
85                    pkg.name,
86                    pkg.platforms.join(", ")
87                )));
88            }
89            if pkg.status != "stable" {
90                warnings.push(format!(
91                    "`{}` is {} — pin carefully and expect API changes",
92                    pkg.name, pkg.status
93                ));
94            }
95            if let Some(note) = &pkg.license_note {
96                warnings.push(format!("`{}` ({}): {}", pkg.name, pkg.license, note));
97            }
98            for (peer, range) in &pkg.peer_dependencies {
99                peer_dependencies.insert(peer.clone(), range.clone());
100            }
101            packages.push(ResolvedPackage {
102                name: pkg.name.clone(),
103                version: pkg.version.clone(),
104                registry: pkg.registry.clone(),
105                license: pkg.license.clone(),
106                license_note: pkg.license_note.clone(),
107                reason: reasons
108                    .get(name)
109                    .cloned()
110                    .unwrap_or_else(|| "requested".to_string()),
111                status: pkg.status.clone(),
112                install: pkg.install.clone(),
113            });
114        }
115
116        let install_commands = build_install_commands(&packages);
117        Ok(Resolution {
118            platform: platform.to_string(),
119            packages,
120            peer_dependencies,
121            install_commands,
122            warnings,
123        })
124    }
125
126    /// Resolve everything a workflow needs on a given platform.
127    pub fn resolve_workflow(
128        &self,
129        workflow_name: &str,
130        platform: &str,
131    ) -> Result<Resolution, RegistryError> {
132        let wf = self
133            .workflow(workflow_name)
134            .ok_or_else(|| RegistryError::NotFound(format!("workflow `{workflow_name}`")))?;
135        let pkgs = wf.packages.get(platform).ok_or_else(|| {
136            RegistryError::Incompatible(format!(
137                "workflow `{workflow_name}` supports platforms [{}], not `{platform}`",
138                wf.packages.keys().cloned().collect::<Vec<_>>().join(", ")
139            ))
140        })?;
141        self.resolve_packages(pkgs, platform)
142    }
143}
144
145fn build_install_commands(packages: &[ResolvedPackage]) -> Vec<String> {
146    let by_default = |registry: &str| -> Vec<String> {
147        packages
148            .iter()
149            .filter(|p| p.registry == registry && p.install.is_none())
150            .map(|p| match registry {
151                "pypi" => format!("{}=={}", p.name, p.version),
152                _ => format!("{}@{}", p.name, p.version),
153            })
154            .collect()
155    };
156    let mut cmds = Vec::new();
157    for (registry, command) in [
158        ("npm", "npm install"),
159        ("crates", "cargo add"),
160        ("pypi", "pip install"),
161    ] {
162        let names = by_default(registry);
163        if !names.is_empty() {
164            cmds.push(format!("{command} {}", names.join(" ")));
165        }
166    }
167    // A package with its own instruction (a Swift package, a release
168    // download, a crate that needs features) is installed as it says.
169    cmds.extend(packages.iter().filter_map(|p| p.install.clone()));
170    cmds
171}