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