Skip to main content

solcompat_project/
collect.rs

1//! Collection orchestration: bindings, discovery, resolution, enrichment, and inventory assembly.
2
3use crate::{
4    artifact::parse_artifact,
5    cargo::{cargo_workspace_root, lock_versions, metadata_resolutions, workspace_requirements},
6    client::{collect_client, is_solana_client},
7    config::{
8        default_loader, default_operation, identifier, AnalysisConfig, ArtifactConfig, Config,
9    },
10    discovery::{automatic_id, discover},
11    idl::parse_idl,
12    input::{evidence, exists, inside, label, read_text},
13    program::collect_program,
14    source::rpc::discover_rpc_reads,
15};
16use anyhow::{ensure, Context, Result};
17use serde_json::Value as JsonValue;
18use solcompat_core::{Project, Suppression};
19use std::{
20    collections::BTreeSet,
21    path::{Path, PathBuf},
22};
23
24/// Inventory and policy inputs returned by [`collect`], before rule evaluation.
25/// Tool observations remain empty until an application explicitly probes tools.
26pub struct Collected {
27    pub project: Project,
28    pub suppressions: Vec<Suppression>,
29    pub target: String,
30}
31
32/// Collect a local project without executing tools or project code.
33///
34/// Configuration bindings are applied before automatic discovery. Captured Cargo
35/// metadata replaces matching lockfile resolution; Anchor.toml fills absent Anchor
36/// CLI selections. Returned components are sorted by stable IDs.
37///
38/// Paths are constrained to the selected project, except ancestor Cargo workspace
39/// manifests and lockfiles used for nested workspace resolution. Missing exact
40/// versions remain unresolved; malformed or unsupported inputs return errors.
41pub fn collect(
42    path: &Path,
43    config_path: Option<&Path>,
44    target: Option<&str>,
45    metadata_path: Option<&Path>,
46    extra_artifacts: &[PathBuf],
47) -> Result<Collected> {
48    let root = path
49        .canonicalize()
50        .with_context(|| format!("cannot open project {}", path.display()))?;
51    ensure!(root.is_dir(), "--path must select a directory");
52    let default = root.join("solcompat.toml");
53    let selected = if let Some(p) = config_path {
54        Some(p.to_owned())
55    } else if exists(&default)? {
56        Some(default)
57    } else {
58        None
59    };
60    let (config, config_ev, base) = if let Some(p) = selected {
61        let p = inside(&root, &p)?;
62        let text = read_text(&p)?;
63        let c: Config =
64            toml::from_str(&text).with_context(|| format!("invalid config {}", p.display()))?;
65        ensure!(c.schema_version == 1, "unsupported config schema_version");
66        let ev = evidence(&root, &p, "", "asserted", text.as_bytes());
67        let base = p.parent().unwrap().to_owned();
68        (c, Some(ev), base)
69    } else {
70        (
71            Config {
72                schema_version: 1,
73                analysis: AnalysisConfig::default(),
74                clients: vec![],
75                programs: vec![],
76                idls: vec![],
77                artifacts: vec![],
78                suppressions: vec![],
79            },
80            None,
81            root.clone(),
82        )
83    };
84    let target = target
85        .or(config.analysis.target.as_deref())
86        .unwrap_or("local")
87        .to_owned();
88    ensure!(
89        matches!(
90            target.as_str(),
91            "local" | "mainnet-beta-2026-09-26" | "future-sbpfv3-deployment"
92        ),
93        "unsupported target: {target}"
94    );
95    let metadata = if let Some(path) = metadata_path {
96        let p = inside(&root, path)?;
97        let text = read_text(&p)?;
98        let v: JsonValue = serde_json::from_str(&text).context("invalid cargo metadata JSON")?;
99        ensure!(
100            v.get("version").and_then(|v| v.as_u64()) == Some(1),
101            "cargo metadata version 1 is required"
102        );
103        Some((
104            v,
105            evidence(
106                &root,
107                &p,
108                "/resolve/nodes",
109                "metadata-resolution",
110                text.as_bytes(),
111            ),
112        ))
113    } else {
114        None
115    };
116    let cargo_root = cargo_workspace_root(&root)?;
117    let locks = lock_versions(&cargo_root, &root)?;
118    let inherited_requirements = workspace_requirements(&cargo_root, &root)?;
119    let mut clients = Vec::new();
120    let mut client_paths = BTreeSet::new();
121    let mut client_ids = BTreeSet::new();
122    for (i, c) in config.clients.iter().enumerate() {
123        ensure!(
124            identifier(&c.id) && client_ids.insert(c.id.clone()),
125            "client ids must be valid and unique"
126        );
127        let p = inside(&root, &base.join(&c.manifest))?;
128        let mut client = collect_client(&root, &p, c.id.clone())?;
129        client_paths.insert(client.manifest.clone());
130        crate::client::apply_client_config(&mut client, c, config_ev.as_ref(), i)?;
131        clients.push(client);
132    }
133    let mut manifests = Vec::new();
134    discover(&root, &["package.json"], &mut manifests)?;
135    for p in manifests {
136        let l = label(&root, &p);
137        if client_paths.contains(&l) {
138            continue;
139        }
140        let id = automatic_id("npm", &l);
141        let client = collect_client(&root, &p, id.clone())?;
142        if !is_solana_client(&client) {
143            continue;
144        }
145        ensure!(
146            client_ids.insert(id.clone()),
147            "automatic client id collision: {id}; bind these manifests explicitly"
148        );
149        clients.push(client);
150    }
151    let mut programs = Vec::new();
152    let mut program_paths = BTreeSet::new();
153    let mut program_ids = BTreeSet::new();
154    for (i, c) in config.programs.iter().enumerate() {
155        ensure!(
156            identifier(&c.id) && program_ids.insert(c.id.clone()),
157            "program ids must be valid and unique"
158        );
159        let p = inside(&root, &base.join(&c.manifest))?;
160        let mut prog = collect_program(
161            &root,
162            &p,
163            &locks,
164            &inherited_requirements,
165            c.id.clone(),
166            true,
167        )?
168        .ok_or_else(|| {
169            anyhow::anyhow!(
170                "configured program manifest has no supported program evidence: {}",
171                p.display()
172            )
173        })?;
174        program_paths.insert(prog.manifest.clone());
175        crate::program::apply_program_config(&mut prog, c, config_ev.as_ref(), i);
176        programs.push(prog);
177    }
178    let mut cargo = Vec::new();
179    discover(&root, &["Cargo.toml"], &mut cargo)?;
180    for p in cargo {
181        let l = label(&root, &p);
182        if program_paths.contains(&l) {
183            continue;
184        }
185        let id = automatic_id("program", &l);
186        if let Some(prog) = collect_program(
187            &root,
188            &p,
189            &locks,
190            &inherited_requirements,
191            id.clone(),
192            false,
193        )? {
194            ensure!(
195                program_ids.insert(id.clone()),
196                "automatic program id collision: {id}; bind these manifests explicitly"
197            );
198            programs.push(prog);
199        }
200    }
201    if let Some((metadata, metadata_evidence)) = &metadata {
202        let resolutions = metadata_resolutions(&root, metadata)?;
203        for program in &mut programs {
204            if let Some(dependencies) = resolutions.get(&program.manifest) {
205                let document: toml::Value =
206                    toml::from_str(&read_text(&root.join(&program.manifest))?)?;
207                let (document, _) =
208                    crate::cargo::inherit_dependencies(&document, &inherited_requirements);
209                crate::program::apply_metadata_resolution(program, dependencies, &document);
210                program
211                    .evidence
212                    .retain(|ev| ev.kind != "resolution" || ev.pointer != "/package");
213                program.evidence.push(metadata_evidence.clone());
214            }
215        }
216    }
217    discover_rpc_reads(&root, &mut clients)?;
218    let anchor_toml = root.join("Anchor.toml");
219    if exists(&anchor_toml)? {
220        let path = inside(&root, &anchor_toml)?;
221        let text = read_text(&path)?;
222        let document: toml::Value = toml::from_str(&text).context("invalid Anchor.toml")?;
223        let anchor_version = document
224            .get("toolchain")
225            .and_then(|value| value.get("anchor_version"))
226            .and_then(toml::Value::as_str)
227            .map(str::to_owned);
228        for program in programs
229            .iter_mut()
230            .filter(|program| program.framework == "anchor")
231        {
232            crate::program::apply_anchor_selection(
233                program,
234                anchor_version.as_deref(),
235                evidence(&root, &path, "/toolchain", "declared", text.as_bytes()),
236            );
237        }
238    }
239    let mut idls = Vec::new();
240    let mut idl_ids = BTreeSet::new();
241    for c in &config.idls {
242        ensure!(
243            identifier(&c.id) && idl_ids.insert(c.id.clone()),
244            "IDL ids must be valid and unique"
245        );
246        ensure!(
247            clients.iter().any(|x| x.id == c.client),
248            "IDL {} references unknown client {}",
249            c.id,
250            c.client
251        );
252        let client = clients.iter().find(|x| x.id == c.client).expect("checked");
253        ensure!(
254            client.dependencies.keys().any(|key| key
255                .split_once('/')
256                .is_some_and(|(_, name)| name == c.reader_package)),
257            "IDL reader_package {} is not declared in {}",
258            c.reader_package,
259            client.manifest
260        );
261        idls.push(parse_idl(&root, c, &base)?);
262    }
263    let mut artifacts = Vec::new();
264    let mut artifact_ids = BTreeSet::new();
265    for c in &config.artifacts {
266        ensure!(
267            identifier(&c.id) && artifact_ids.insert(c.id.clone()),
268            "artifact ids must be valid and unique"
269        );
270        ensure!(
271            matches!(
272                c.operation.as_str(),
273                "deploy" | "upgrade" | "finalize" | "execute"
274            ),
275            "unsupported artifact operation"
276        );
277        if let Some(p) = &c.program {
278            ensure!(
279                programs.iter().any(|x| &x.id == p),
280                "artifact references unknown program {p}"
281            );
282        }
283        artifacts.push(parse_artifact(&root, c, &base)?);
284    }
285    for (i, p) in extra_artifacts.iter().enumerate() {
286        let c = ArtifactConfig {
287            id: format!("artifact-{}", i + 1),
288            path: p.clone(),
289            program: None,
290            loader: default_loader(),
291            operation: default_operation(),
292        };
293        artifacts.push(parse_artifact(&root, &c, &root)?);
294    }
295    ensure!(
296        !clients.is_empty() || !programs.is_empty() || !artifacts.is_empty(),
297        "no supported Solana program or npm client manifests found"
298    );
299    for s in &config.suppressions {
300        ensure!(
301            solcompat_core::catalog::rule(&s.rule).is_some_and(|rule| rule.suppressible),
302            "unsupported suppression rule {}",
303            s.rule
304        );
305        ensure!(
306            !s.subject.trim().is_empty() && !s.reason.trim().is_empty(),
307            "suppression subject and reason are required"
308        );
309    }
310    clients.sort_by(|a, b| a.id.cmp(&b.id));
311    programs.sort_by(|a, b| a.id.cmp(&b.id));
312    idls.sort_by(|a, b| a.id.cmp(&b.id));
313    artifacts.sort_by(|a, b| a.id.cmp(&b.id));
314    let name = clients
315        .iter()
316        .find(|c| c.manifest == "package.json")
317        .and_then(|c| c.name.clone())
318        .or_else(|| programs.first().map(|p| p.name.clone()))
319        .unwrap_or_else(|| "selected project".into());
320    Ok(Collected {
321        project: Project {
322            name,
323            clients,
324            programs,
325            idls,
326            artifacts,
327            tools: vec![],
328        },
329        suppressions: config.suppressions,
330        target,
331    })
332}