Skip to main content

lockdocs_core/
locate.rs

1//! Find a dependency's installed sources on this machine: node_modules,
2//! Python site-packages, the Cargo registry and the Go module cache.
3
4use crate::{norm_name, Dep, Eco};
5use std::path::{Path, PathBuf};
6use std::sync::OnceLock;
7
8/// Where a package's files are.
9#[derive(Debug, Clone)]
10pub struct Source {
11    /// Package root (for Python: the site-packages directory).
12    pub dir: PathBuf,
13    /// Exact file list when the ecosystem records one (Python RECORD).
14    pub files: Option<Vec<PathBuf>>,
15    /// Python METADATA path (its body is the README).
16    pub metadata: Option<PathBuf>,
17    /// The version found on disk (may differ from the lockfile).
18    pub version: String,
19    /// Human label: `node_modules/zod`, `~/.cargo/registry/...`, `fetched: registry.npmjs.org`.
20    pub label: String,
21    pub fetched: bool,
22}
23
24/// Ancestor directories from `root` up to (but not past) the home directory.
25fn ancestors(root: &Path) -> Vec<PathBuf> {
26    let home = dirs::home_dir();
27    let mut out = Vec::new();
28    for a in root.ancestors().take(8) {
29        if Some(a.to_path_buf()) == home && !out.is_empty() {
30            break;
31        }
32        out.push(a.to_path_buf());
33    }
34    out
35}
36
37pub fn locate(dep: &Dep, root: &Path) -> Option<Source> {
38    match dep.eco {
39        Eco::Npm => npm(dep, root),
40        Eco::PyPI => python(dep, root),
41        Eco::Cargo => cargo(dep, root),
42        Eco::Go => go(dep, root),
43    }
44}
45
46// ---------------------------------------------------------------- npm
47
48fn npm_version(dir: &Path) -> Option<String> {
49    let t = std::fs::read_to_string(dir.join("package.json")).ok()?;
50    let v: serde_json::Value = serde_json::from_str(&t).ok()?;
51    v.get("version")?.as_str().map(String::from)
52}
53
54/// Installed version of an npm package reachable from `root`.
55pub fn npm_installed(name: &str, root: &Path) -> Option<(PathBuf, String)> {
56    for a in ancestors(root) {
57        let d = a.join("node_modules").join(name);
58        if let Some(v) = npm_version(&d) {
59            return Some((d, v));
60        }
61    }
62    None
63}
64
65fn npm(dep: &Dep, root: &Path) -> Option<Source> {
66    let mut fallback = None;
67    for a in ancestors(root) {
68        let nm = a.join("node_modules");
69        if !nm.is_dir() {
70            continue;
71        }
72        let d = nm.join(&dep.name);
73        if let Some(v) = npm_version(&d) {
74            if v == dep.version {
75                return Some(src(d, &a, v));
76            }
77            fallback.get_or_insert((d, a.clone(), v));
78        }
79        // pnpm's virtual store keeps every version side by side.
80        let store = nm.join(".pnpm");
81        if store.is_dir() {
82            let prefix = format!("{}@{}", dep.name.replace('/', "+"), dep.version);
83            if let Ok(rd) = std::fs::read_dir(&store) {
84                for e in rd.flatten() {
85                    let f = e.file_name().to_string_lossy().to_string();
86                    if f == prefix || f.starts_with(&format!("{prefix}_")) || f.starts_with(&format!("{prefix}(")) {
87                        let d = e.path().join("node_modules").join(&dep.name);
88                        if let Some(v) = npm_version(&d) {
89                            return Some(src(d, &a, v));
90                        }
91                    }
92                }
93            }
94        }
95    }
96    if let Some(s) = pnp(dep, root) {
97        return Some(s);
98    }
99    let (d, a, v) = fallback?;
100    Some(src(d, &a, v))
101}
102
103// ---------------------------------------------------------------- yarn pnp
104
105/// Yarn Berry cache zip name prefix: `zod-npm-3.23.8-`, `@types-node-npm-20.1.0-`.
106pub fn pnp_zip_prefix(name: &str, version: &str) -> String {
107    format!("{}-npm-{}-", name.replace('/', "-"), version)
108}
109
110/// Yarn caches to look in: project (and ancestors) `.yarn/cache`, then the global cache.
111fn yarn_caches(root: &Path) -> Vec<(PathBuf, Option<PathBuf>)> {
112    let mut out: Vec<(PathBuf, Option<PathBuf>)> = ancestors(root).into_iter().map(|a| (a.join(".yarn").join("cache"), Some(a))).collect();
113    let global = std::env::var_os("YARN_CACHE_FOLDER")
114        .filter(|p| !p.is_empty())
115        .map(PathBuf::from)
116        .or_else(|| dirs::home_dir().map(|h| h.join(".yarn").join("berry").join("cache")));
117    if let Some(g) = global {
118        out.push((g, None));
119    }
120    out
121}
122
123/// A package from a Yarn Plug'n'Play zip cache, unpacked (docs and sources
124/// only) into the lockdocs cache once.
125fn pnp(dep: &Dep, root: &Path) -> Option<Source> {
126    let prefix = pnp_zip_prefix(&dep.name, &dep.version);
127    for (cache, base) in yarn_caches(root) {
128        let Ok(rd) = std::fs::read_dir(&cache) else { continue };
129        let mut zips: Vec<PathBuf> = rd
130            .flatten()
131            .map(|e| e.path())
132            .filter(|p| {
133                p.file_name().is_some_and(|f| {
134                    let f = f.to_string_lossy();
135                    f.starts_with(&prefix) && f.ends_with(".zip")
136                })
137            })
138            .collect();
139        zips.sort();
140        let Some(zip) = zips.into_iter().next() else { continue };
141        let safe = format!("{}@{}-pnp", dep.name, dep.version).replace(['/', '\\', ':'], "+");
142        let dir = crate::cache::dir().join("src").join("npm").join(safe);
143        let marker = dir.join(".lockdocs-complete");
144        if !marker.is_file() {
145            let bytes = std::fs::read(&zip).ok()?;
146            let _ = std::fs::remove_dir_all(&dir);
147            std::fs::create_dir_all(&dir).ok()?;
148            let inner = format!("node_modules/{}/", dep.name);
149            if crate::fetch::unzip(&bytes, &dir, false, Some(&inner)).is_err() {
150                let _ = std::fs::remove_dir_all(&dir);
151                continue;
152            }
153            std::fs::write(&marker, b"").ok()?;
154        }
155        let version = npm_version(&dir).unwrap_or_else(|| dep.version.clone());
156        let label = match base.as_ref().and_then(|b| zip.strip_prefix(b).ok()) {
157            Some(r) => r.display().to_string().replace('\\', "/"),
158            None => tilde(&zip),
159        };
160        return Some(Source {
161            dir,
162            files: None,
163            metadata: None,
164            version,
165            label,
166            fetched: false,
167        });
168    }
169    None
170}
171
172fn src(dir: PathBuf, base: &Path, version: String) -> Source {
173    let label = dir.strip_prefix(base).map(|p| p.display().to_string()).unwrap_or_else(|_| tilde(&dir));
174    Source {
175        dir,
176        files: None,
177        metadata: None,
178        version,
179        label: label.replace('\\', "/"),
180        fetched: false,
181    }
182}
183
184pub fn tilde(p: &Path) -> String {
185    if let Some(h) = dirs::home_dir() {
186        if let Ok(r) = p.strip_prefix(&h) {
187            return format!("~/{}", r.display()).replace('\\', "/");
188        }
189    }
190    p.display().to_string().replace('\\', "/")
191}
192
193// ---------------------------------------------------------------- python
194
195fn glob_site_packages(prefix: &Path, out: &mut Vec<PathBuf>) {
196    let win = prefix.join("Lib").join("site-packages");
197    if win.is_dir() {
198        out.push(win);
199    }
200    for lib in ["lib", "lib64"] {
201        if let Ok(rd) = std::fs::read_dir(prefix.join(lib)) {
202            for e in rd.flatten() {
203                if e.file_name().to_string_lossy().starts_with("python") {
204                    let sp = e.path().join("site-packages");
205                    if sp.is_dir() && !out.contains(&sp) {
206                        out.push(sp);
207                    }
208                }
209            }
210        }
211    }
212}
213
214fn system_site_packages() -> &'static Vec<PathBuf> {
215    static SYS: OnceLock<Vec<PathBuf>> = OnceLock::new();
216    SYS.get_or_init(|| {
217        if std::env::var("LOCKDOCS_NO_SYSTEM_PYTHON").is_ok() {
218            return Vec::new();
219        }
220        let code = "import site,sys\nfor p in site.getsitepackages()+[site.getusersitepackages()]: print(p)";
221        for py in ["python3", "python"] {
222            if let Ok(o) = std::process::Command::new(py).args(["-c", code]).output() {
223                if o.status.success() {
224                    return String::from_utf8_lossy(&o.stdout).lines().map(PathBuf::from).filter(|p| p.is_dir()).collect();
225                }
226            }
227        }
228        Vec::new()
229    })
230}
231
232/// site-packages directories for a project: local virtualenvs first, then the
233/// active environment, then the system interpreter.
234pub fn site_packages(root: &Path) -> Vec<PathBuf> {
235    let mut out = Vec::new();
236    for a in ancestors(root).into_iter().take(3) {
237        for v in [".venv", "venv", "env", ".env"] {
238            let p = a.join(v);
239            if p.join("pyvenv.cfg").is_file() {
240                glob_site_packages(&p, &mut out);
241            }
242        }
243    }
244    for var in ["VIRTUAL_ENV", "CONDA_PREFIX"] {
245        if let Ok(v) = std::env::var(var) {
246            glob_site_packages(Path::new(&v), &mut out);
247        }
248    }
249    for p in system_site_packages() {
250        if !out.contains(p) {
251            out.push(p.clone());
252        }
253    }
254    out
255}
256
257/// A dist-info directory in `sp` for `name`, with its version.
258pub fn dist_infos(sp: &Path) -> Vec<(String, String, PathBuf)> {
259    let mut out = Vec::new();
260    let Ok(rd) = std::fs::read_dir(sp) else { return out };
261    for e in rd.flatten() {
262        let f = e.file_name().to_string_lossy().to_string();
263        let Some(stem) = f.strip_suffix(".dist-info") else { continue };
264        // name-version; names have no '-' after normalization in wheels.
265        let Some((n, v)) = stem.rsplit_once('-') else { continue };
266        out.push((norm_name(Eco::PyPI, n), v.to_string(), e.path()));
267    }
268    out
269}
270
271fn python(dep: &Dep, root: &Path) -> Option<Source> {
272    let want = norm_name(Eco::PyPI, &dep.name);
273    let mut fallback = None;
274    for sp in site_packages(root) {
275        for (n, v, di) in dist_infos(&sp) {
276            if n != want {
277                continue;
278            }
279            let mut s = python_source(&sp, &di, v.clone());
280            for a in ancestors(root).into_iter().take(3) {
281                if let Ok(r) = sp.strip_prefix(&a) {
282                    s.label = r.display().to_string().replace('\\', "/");
283                    break;
284                }
285            }
286            if v == dep.version {
287                return Some(s);
288            }
289            fallback.get_or_insert(s);
290        }
291    }
292    fallback
293}
294
295pub fn python_source(sp: &Path, dist_info: &Path, version: String) -> Source {
296    let mut files = Vec::new();
297    if let Ok(rec) = std::fs::read_to_string(dist_info.join("RECORD")) {
298        for line in rec.lines() {
299            let path = line.split(',').next().unwrap_or("");
300            if path.is_empty() || path.starts_with("..") || path.contains(".dist-info/") || path.contains("__pycache__") {
301                continue;
302            }
303            files.push(PathBuf::from(path));
304        }
305    }
306    let label = tilde(dist_info.parent().unwrap_or(sp));
307    Source {
308        dir: sp.to_path_buf(),
309        files: Some(files),
310        metadata: Some(dist_info.join("METADATA")).filter(|p| p.is_file()),
311        version,
312        label,
313        fetched: false,
314    }
315}
316
317// ---------------------------------------------------------------- cargo
318
319fn cargo_home() -> Option<PathBuf> {
320    std::env::var_os("CARGO_HOME")
321        .map(PathBuf::from)
322        .or_else(|| dirs::home_dir().map(|h| h.join(".cargo")))
323}
324
325fn cargo(dep: &Dep, root: &Path) -> Option<Source> {
326    let dirname = format!("{}-{}", dep.name, dep.version);
327    for a in ancestors(root).into_iter().take(3) {
328        for v in ["vendor", "third_party"] {
329            for cand in [a.join(v).join(&dirname), a.join(v).join(&dep.name)] {
330                if cand.join("Cargo.toml").is_file() {
331                    return Some(src(cand, &a, dep.version.clone()));
332                }
333            }
334        }
335    }
336    if dep.from.ends_with("(git)") {
337        return cargo_git(dep);
338    }
339    let reg = cargo_home()?.join("registry").join("src");
340    for e in std::fs::read_dir(&reg).ok()?.flatten() {
341        let d = e.path().join(&dirname);
342        if d.join("Cargo.toml").is_file() {
343            return Some(Source {
344                label: tilde(&d),
345                dir: d,
346                files: None,
347                metadata: None,
348                version: dep.version.clone(),
349                fetched: false,
350            });
351        }
352    }
353    None
354}
355
356/// A git dependency checked out by Cargo under `$CARGO_HOME/git/checkouts`.
357fn cargo_git(dep: &Dep) -> Option<Source> {
358    let root = cargo_home()?.join("git").join("checkouts");
359    let mut found = None;
360    find_crate(&root, &dep.name, &dep.version, 0, &mut found);
361    let d = found?;
362    Some(Source {
363        label: tilde(&d),
364        dir: d,
365        files: None,
366        metadata: None,
367        version: dep.version.clone(),
368        fetched: false,
369    })
370}
371
372fn find_crate(dir: &Path, name: &str, version: &str, depth: usize, found: &mut Option<PathBuf>) {
373    if depth > 4 || found.is_some() {
374        return;
375    }
376    if let Ok(t) = std::fs::read_to_string(dir.join("Cargo.toml")) {
377        if let Ok(v) = toml::from_str::<toml::Table>(&t) {
378            let pkg = v.get("package");
379            let n = pkg.and_then(|p| p.get("name")).and_then(|n| n.as_str());
380            let ver = pkg.and_then(|p| p.get("version")).and_then(|n| n.as_str());
381            if n == Some(name) && ver == Some(version) {
382                *found = Some(dir.to_path_buf());
383                return;
384            }
385        }
386    }
387    let Ok(rd) = std::fs::read_dir(dir) else { return };
388    let mut subs: Vec<PathBuf> = rd
389        .flatten()
390        .filter(|e| e.file_type().is_ok_and(|t| t.is_dir()))
391        .filter(|e| {
392            let f = e.file_name();
393            let f = f.to_string_lossy();
394            f != "target" && !f.starts_with('.')
395        })
396        .map(|e| e.path())
397        .collect();
398    subs.sort();
399    for s in subs {
400        find_crate(&s, name, version, depth + 1, found);
401    }
402}
403
404// ---------------------------------------------------------------- go
405
406/// Go module cache path escaping: `A` -> `!a`.
407pub fn go_escape(s: &str) -> String {
408    let mut out = String::with_capacity(s.len());
409    for c in s.chars() {
410        if c.is_ascii_uppercase() {
411            out.push('!');
412            out.push(c.to_ascii_lowercase());
413        } else {
414            out.push(c);
415        }
416    }
417    out
418}
419
420fn go_modcache() -> Option<PathBuf> {
421    if let Some(p) = std::env::var_os("GOMODCACHE").filter(|p| !p.is_empty()) {
422        return Some(PathBuf::from(p));
423    }
424    if let Some(p) = std::env::var_os("GOPATH").filter(|p| !p.is_empty()) {
425        let first = std::env::split_paths(&p).next()?;
426        return Some(first.join("pkg").join("mod"));
427    }
428    dirs::home_dir().map(|h| h.join("go").join("pkg").join("mod"))
429}
430
431fn go(dep: &Dep, root: &Path) -> Option<Source> {
432    for a in ancestors(root).into_iter().take(3) {
433        let v = a.join("vendor").join(&dep.name);
434        if v.is_dir() {
435            return Some(src(v, &a, dep.version.clone()));
436        }
437    }
438    let d = go_modcache()?.join(format!("{}@{}", go_escape(&dep.name), go_escape(&dep.version)));
439    if d.is_dir() {
440        return Some(Source {
441            label: tilde(&d),
442            dir: d,
443            files: None,
444            metadata: None,
445            version: dep.version.clone(),
446            fetched: false,
447        });
448    }
449    None
450}
451
452#[cfg(test)]
453mod tests {
454    #[test]
455    fn pnp_names() {
456        assert_eq!(super::pnp_zip_prefix("zod", "3.23.8"), "zod-npm-3.23.8-");
457        assert_eq!(super::pnp_zip_prefix("@types/node", "20.1.0"), "@types-node-npm-20.1.0-");
458        assert!(!"zod-npm-3.23.80-abc-def.zip".starts_with(&super::pnp_zip_prefix("zod", "3.23.8")));
459    }
460
461    #[test]
462    fn go_escaping() {
463        assert_eq!(super::go_escape("github.com/BurntSushi/toml"), "github.com/!burnt!sushi/toml");
464    }
465}