Skip to main content

lockdocs_core/
npm_api.rs

1//! Public npm declaration graph. Names are resolved through package entrypoints,
2//! not by scoring unrelated declarations which happen to share a short name.
3use crate::extract::{Entry, Kind};
4use serde::{Deserialize, Serialize};
5use serde_json::Value;
6use std::collections::{BTreeMap, BTreeSet};
7use std::path::{Component, Path};
8use tree_sitter::{Node, Parser};
9
10#[derive(Default, Serialize, Deserialize)]
11pub struct PublicApi {
12    pub roots: Vec<Root>,
13    pub entries: Vec<Entry>,
14    modules: BTreeMap<String, Module>,
15}
16
17#[derive(Serialize, Deserialize)]
18pub struct Root {
19    pub import: String,
20    pub conditions: String,
21    pub file: String,
22}
23
24#[derive(Default, Serialize, Deserialize)]
25struct Module {
26    exports: BTreeMap<String, Binding>,
27    imports: BTreeMap<String, Binding>,
28    stars: Vec<String>,
29    incomplete: bool,
30    assignment: Option<String>,
31}
32
33#[derive(Clone, Serialize, Deserialize)]
34enum Binding {
35    Local(String),
36    Named(String, String),
37    Namespace(String),
38}
39
40#[derive(Default)]
41pub struct Resolution {
42    pub entries: BTreeSet<usize>,
43    pub unresolved: bool,
44}
45
46fn text<'a>(n: Node, src: &'a [u8]) -> &'a str {
47    n.utf8_text(src).unwrap_or("")
48}
49fn string(n: Node, src: &[u8]) -> String {
50    text(n, src).trim_matches(['\'', '"']).to_string()
51}
52fn children(n: Node) -> Vec<Node> {
53    n.named_children(&mut n.walk()).collect()
54}
55fn normalize(s: &str) -> Option<String> {
56    let mut parts = Vec::new();
57    for c in Path::new(s).components() {
58        match c {
59            Component::Normal(p) => parts.push(p.to_str()?),
60            Component::ParentDir => {
61                parts.pop()?;
62            }
63            Component::CurDir => {}
64            _ => return None,
65        }
66    }
67    Some(parts.join("/"))
68}
69
70/// Node's JS suffixes in declaration imports refer to declaration siblings.
71fn resolve_file(from: &str, spec: &str, files: &BTreeSet<String>) -> String {
72    if !spec.starts_with('.') {
73        return format!("external:{spec}");
74    }
75    let parent = from.rsplit_once('/').map_or("", |(p, _)| p);
76    let Some(base) = normalize(format!("{parent}/{spec}").trim_start_matches('/')) else {
77        return String::new();
78    };
79    let suffixes = [(".mjs", ".d.mts"), (".cjs", ".d.cts"), (".js", ".d.ts")];
80    for (js, ts) in suffixes {
81        if let Some(stem) = base.strip_suffix(js) {
82            for candidate in [format!("{stem}{ts}"), format!("{stem}.d.ts"), base.clone()] {
83                if files.contains(&candidate) {
84                    return candidate;
85                }
86            }
87        }
88    }
89    for candidate in [
90        base.clone(),
91        format!("{base}.d.ts"),
92        format!("{base}/index.d.ts"),
93        format!("{base}.ts"),
94        format!("{base}/index.ts"),
95    ] {
96        if files.contains(&candidate) {
97            return candidate;
98        }
99    }
100    base
101}
102
103fn names(n: Node, src: &[u8], out: &mut Vec<String>) {
104    if let Some(name) = n.child_by_field_name("name") {
105        out.push(text(name, src).to_string());
106    } else if matches!(n.kind(), "ambient_declaration" | "lexical_declaration" | "variable_declaration") {
107        for c in children(n) {
108            names(c, src, out);
109        }
110    }
111}
112
113fn module(src: &str, file: &str, files: &BTreeSet<String>) -> Module {
114    let mut m = Module::default();
115    let mut parser = Parser::new();
116    let _ = parser.set_language(&tree_sitter_typescript::LANGUAGE_TYPESCRIPT.into());
117    let Some(tree) = parser.parse(src, None) else {
118        m.incomplete = true;
119        return m;
120    };
121    // Errors inside a type body do not change which declaration is exported.
122    // A top-level recovery node may hide an export, so fail closed for that.
123    m.incomplete = children(tree.root_node()).iter().any(|n| n.kind() == "ERROR");
124    let bytes = src.as_bytes();
125    if (file.ends_with(".js") || file.ends_with(".cjs") || file.ends_with(".mjs")) && (src.contains("module.exports") || src.contains("exports.")) {
126        m.incomplete = true;
127    }
128    for n in children(tree.root_node()) {
129        if n.kind() != "import_statement" && n.kind() != "export_statement" {
130            continue;
131        }
132        // A UMD global name does not alter the module's explicit exports.
133        if text(n, bytes).trim_start().starts_with("export as namespace ") {
134            continue;
135        }
136        let target = n.child_by_field_name("source").map(|s| resolve_file(file, &string(s, bytes), files));
137        if n.kind() == "import_statement" {
138            if let Some(clause) = children(n).into_iter().find(|c| c.kind() == "import_clause") {
139                for c in children(clause) {
140                    match c.kind() {
141                        "namespace_import" => {
142                            if let (Some(t), Some(id)) = (&target, children(c).last()) {
143                                m.imports.insert(text(*id, bytes).into(), Binding::Namespace(t.clone()));
144                            }
145                        }
146                        "named_imports" => {
147                            for s in children(c) {
148                                if let (Some(t), Some(name)) = (&target, s.child_by_field_name("name")) {
149                                    let alias = s.child_by_field_name("alias").unwrap_or(name);
150                                    m.imports.insert(text(alias, bytes).into(), Binding::Named(t.clone(), string(name, bytes)));
151                                }
152                            }
153                        }
154                        "identifier" => {
155                            if let Some(t) = &target {
156                                m.imports.insert(text(c, bytes).into(), Binding::Named(t.clone(), "default".into()));
157                            }
158                        }
159                        _ => m.incomplete = true,
160                    }
161                }
162            } else {
163                m.incomplete = true;
164            }
165            continue;
166        }
167        if let Some(d) = n.child_by_field_name("declaration") {
168            let mut ns = Vec::new();
169            names(d, bytes, &mut ns);
170            let default = text(n, bytes).starts_with("export default ");
171            for name in ns {
172                m.exports.insert(if default { "default".into() } else { name.clone() }, Binding::Local(name));
173            }
174        } else if let Some(clause) = children(n).into_iter().find(|c| c.kind() == "export_clause") {
175            for s in children(clause) {
176                if let Some(name) = s.child_by_field_name("name") {
177                    let alias = s.child_by_field_name("alias").unwrap_or(name);
178                    let name = string(name, bytes);
179                    let b = target
180                        .as_ref()
181                        .map_or_else(|| Binding::Local(name.clone()), |t| Binding::Named(t.clone(), name.clone()));
182                    m.exports.insert(string(alias, bytes), b);
183                }
184            }
185        } else if let Some(ns) = children(n).into_iter().find(|c| c.kind() == "namespace_export") {
186            if let (Some(t), Some(id)) = (target, ns.named_child(0)) {
187                m.exports.insert(string(id, bytes), Binding::Namespace(t));
188            }
189        } else if let Some(t) = target {
190            m.stars.push(t);
191        } else if let Some(value) = n
192            .child_by_field_name("value")
193            .or_else(|| text(n, bytes).trim_start().starts_with("export =").then(|| n.named_child(0)).flatten())
194        {
195            let name = text(value, bytes).to_string();
196            if text(n, bytes).trim_start().starts_with("export =") {
197                m.assignment = Some(name.clone());
198            }
199            m.exports.insert("default".into(), Binding::Local(name));
200        } else {
201            m.incomplete = true;
202        }
203    }
204    m
205}
206
207/// Prefer the explicit declaration branch; do not silently combine a source
208/// condition or an implementation file with a different declaration edition.
209fn leaves(v: &Value, condition: &str, out: &mut Vec<(String, String)>) {
210    match v {
211        Value::String(s) => out.push((condition.into(), s.clone())),
212        Value::Object(o) => {
213            if let Some(t) = o.get("types") {
214                leaves(t, &format!("{condition}/types"), out);
215            } else {
216                for (k, v) in o {
217                    leaves(v, &format!("{condition}/{k}"), out);
218                }
219            }
220        }
221        Value::Array(a) => {
222            for (i, v) in a.iter().enumerate() {
223                leaves(v, &format!("{condition}/fallback-{i}"), out);
224            }
225        }
226        _ => {}
227    }
228}
229
230impl PublicApi {
231    pub fn build(name: &str, dir: &Path, sources: &BTreeMap<String, String>) -> Self {
232        let files: BTreeSet<String> = sources.keys().cloned().collect();
233        let modules = sources.iter().map(|(f, s)| (f.clone(), module(s, f, &files))).collect();
234        let pkg: Value = std::fs::read_to_string(dir.join("package.json"))
235            .ok()
236            .and_then(|s| serde_json::from_str(&s).ok())
237            .unwrap_or(Value::Null);
238        let mut paths = BTreeMap::new();
239        if let Some(exports) = pkg.get("exports") {
240            if let Some(o) = exports.as_object().filter(|o| o.keys().any(|k| k.starts_with('.'))) {
241                for (k, v) in o {
242                    paths.insert(k.clone(), v.clone());
243                }
244            } else {
245                paths.insert(".".into(), exports.clone());
246            }
247        } else {
248            let target = pkg
249                .get("types")
250                .or_else(|| pkg.get("typings"))
251                .or_else(|| pkg.get("main"))
252                .and_then(Value::as_str)
253                .unwrap_or("./index.d.ts");
254            paths.insert(".".into(), Value::String(format!("./{}", target.trim_start_matches("./"))));
255        }
256        let routes: Vec<String> = paths.keys().cloned().collect();
257        let mut roots = Vec::new();
258        for (path, value) in paths {
259            if path == "./package.json" {
260                continue;
261            }
262            let mut targets = Vec::new();
263            leaves(&value, "", &mut targets);
264            for (conditions, target) in targets {
265                if let (Some((pre, post)), Some((tp, ts))) = (path.split_once('*'), target.split_once('*')) {
266                    for file in &files {
267                        if let Some(mid) = file.strip_prefix(tp.trim_start_matches("./")).and_then(|s| s.strip_suffix(ts)) {
268                            let public = format!("{pre}{mid}{post}");
269                            let best = routes
270                                .iter()
271                                .filter(|r| {
272                                    if let Some((a, b)) = r.split_once('*') {
273                                        public.starts_with(a) && public.ends_with(b)
274                                    } else {
275                                        **r == public
276                                    }
277                                })
278                                .max_by_key(|r| {
279                                    if let Some((a, b)) = r.split_once('*') {
280                                        (0, a.len(), b.len())
281                                    } else {
282                                        (1, r.len(), 0)
283                                    }
284                                });
285                            if best != Some(&path) {
286                                continue;
287                            }
288                            roots.push(Root {
289                                import: format!("{name}{}{}{}", pre.trim_start_matches('.'), mid, post),
290                                conditions: conditions.clone(),
291                                file: file.clone(),
292                            });
293                        }
294                    }
295                } else {
296                    let file = resolve_file("", &format!("./{}", target.trim_start_matches("./")), &files);
297                    roots.push(Root {
298                        import: format!("{name}{}", path.trim_start_matches('.')),
299                        conditions,
300                        file,
301                    });
302                }
303            }
304        }
305        Self {
306            roots,
307            entries: crate::extract::npm_entries(sources),
308            modules,
309        }
310    }
311
312    /// Rebase an @types declaration graph onto the extraction's citation labels.
313    pub(crate) fn prefixed(mut self, prefix: &str) -> Self {
314        let rebase = |s: &mut String| {
315            if !s.starts_with("external:") {
316                *s = format!("{prefix}{s}");
317            }
318        };
319        let binding = |b: &mut Binding| match b {
320            Binding::Named(file, _) | Binding::Namespace(file) => rebase(file),
321            _ => (),
322        };
323        for e in &mut self.entries {
324            rebase(&mut e.file);
325        }
326        for root in &mut self.roots {
327            rebase(&mut root.file);
328        }
329        self.modules = self
330            .modules
331            .into_iter()
332            .map(|(file, mut m)| {
333                for b in m.exports.values_mut().chain(m.imports.values_mut()) {
334                    binding(b);
335                }
336                for star in &mut m.stars {
337                    rebase(star);
338                }
339                (format!("{prefix}{file}"), m)
340            })
341            .collect();
342        self
343    }
344
345    pub fn resolve(&self, root: &Root, symbol: &str, entries: &[Entry]) -> Resolution {
346        let mut out = Resolution::default();
347        self.exported(&root.file, symbol, entries, &mut BTreeSet::new(), &mut out);
348        out
349    }
350
351    /// Search the declaration graph of this import, including referenced types
352    /// and members, without admitting other editions shipped in the tarball.
353    pub(crate) fn search_files(&self, import: &str) -> BTreeSet<String> {
354        let mut files = BTreeSet::new();
355        let mut pending: Vec<&str> = self.roots.iter().filter(|r| r.import == import).map(|r| r.file.as_str()).collect();
356        while let Some(file) = pending.pop() {
357            if !files.insert(file.to_string()) {
358                continue;
359            }
360            if let Some(m) = self.modules.get(file) {
361                pending.extend(m.stars.iter().map(String::as_str));
362                for b in m.exports.values().chain(m.imports.values()) {
363                    if let Binding::Named(target, _) | Binding::Namespace(target) = b {
364                        pending.push(target);
365                    }
366                }
367            }
368        }
369        files
370    }
371
372    pub(crate) fn search_alias<'a>(&'a self, entry: &'a Entry) -> &'a Entry {
373        if entry.alias_of.is_none() {
374            return entry;
375        }
376        let mut found = Resolution::default();
377        self.exported(&entry.file, &entry.path, &self.entries, &mut BTreeSet::new(), &mut found);
378        if !found.unresolved && found.entries.len() == 1 {
379            &self.entries[*found.entries.first().unwrap()]
380        } else {
381            entry
382        }
383    }
384
385    fn exported(&self, file: &str, path: &str, entries: &[Entry], seen: &mut BTreeSet<(String, String)>, out: &mut Resolution) {
386        if seen.len() > 128 {
387            out.unresolved = true;
388            return;
389        }
390        let key = (file.to_string(), path.to_string());
391        if !seen.insert(key.clone()) {
392            return;
393        }
394        let Some(m) = self.modules.get(file) else {
395            out.unresolved = true;
396            seen.remove(&key);
397            return;
398        };
399        out.unresolved |= m.incomplete;
400        let (name, tail) = path.split_once('.').unwrap_or((path, ""));
401        if let Some(b) = m.exports.get(name) {
402            self.binding(file, b, tail, entries, seen, out);
403        } else if let Some(namespace) = &m.assignment {
404            let local = if path.starts_with(&format!("{namespace}.")) {
405                path.to_string()
406            } else {
407                format!("{namespace}.{path}")
408            };
409            self.binding(file, &Binding::Local(local), "", entries, seen, out);
410        } else if name != "default" {
411            for star in &m.stars {
412                self.exported(star, path, entries, seen, out);
413            }
414        }
415        seen.remove(&key);
416    }
417
418    fn binding(&self, file: &str, b: &Binding, tail: &str, entries: &[Entry], seen: &mut BTreeSet<(String, String)>, out: &mut Resolution) {
419        let extend = |s: &str| if tail.is_empty() { s.to_string() } else { format!("{s}.{tail}") };
420        match b {
421            Binding::Namespace(target) => {
422                if tail.is_empty() {
423                    out.unresolved = true;
424                } else {
425                    self.exported(target, tail, entries, seen, out);
426                }
427            }
428            Binding::Named(target, name) => self.exported(target, &extend(name), entries, seen, out),
429            Binding::Local(name) => {
430                if let Some(import) = self.modules.get(file).and_then(|m| m.imports.get(name)) {
431                    self.binding(file, import, tail, entries, seen, out);
432                } else {
433                    let path = extend(name);
434                    let mut found = false;
435                    for (i, e) in entries.iter().enumerate() {
436                        if e.file == file && e.path == path && e.kind != Kind::Alias && e.kind != Kind::Prose {
437                            out.entries.insert(i);
438                            found = true;
439                        }
440                    }
441                    if !found {
442                        out.unresolved = true;
443                    }
444                }
445            }
446        }
447    }
448}