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    /// Identical entrypoints and transparent full-surface barrels share prose.
398    /// Root searches also cover additive public helpers with disjoint names.
399    /// Shared dependencies and legacy search widening never establish edition
400    /// compatibility.
401    pub(crate) fn compatible_imports(&self, selected: &str, package: &str) -> BTreeSet<&str> {
402        let mut targets: BTreeMap<&str, Option<BTreeSet<&str>>> = BTreeMap::new();
403        for root in &self.roots {
404            let files = targets.entry(&root.import).or_insert_with(|| Some(BTreeSet::new()));
405            match (files.as_mut(), self.canonical_barrel(&root.file)) {
406                (Some(files), Some(file)) => {
407                    files.insert(file);
408                }
409                _ => *files = None,
410            }
411        }
412        let Some(Some(selected_files)) = targets.get(selected) else {
413            return BTreeSet::new();
414        };
415        // A root package search also covers additive public helpers. Their
416        // names must be fully known and disjoint from the root surface; graph
417        // intersection never establishes compatibility between API editions.
418        let public_names = |import: &str| -> Option<BTreeSet<String>> {
419            let mut names = BTreeSet::new();
420            for root in self.roots.iter().filter(|r| r.import == import) {
421                names.extend(self.export_names(&root.file, &mut BTreeSet::new())?);
422            }
423            (!names.is_empty()).then_some(names)
424        };
425        let selected_names = (selected == package).then(|| public_names(selected)).flatten();
426        targets
427            .iter()
428            .filter_map(|(&import, files)| {
429                (import == selected
430                    || selected_files.len() == 1 && files.as_ref() == Some(selected_files)
431                    || selected_names
432                        .as_ref()
433                        .is_some_and(|names| public_names(import).is_some_and(|other| names.is_disjoint(&other))))
434                .then_some(import)
435            })
436            .collect()
437    }
438
439    fn export_names(&self, file: &str, seen: &mut BTreeSet<String>) -> Option<BTreeSet<String>> {
440        if seen.len() > 128 || !seen.insert(file.to_string()) {
441            return None;
442        }
443        let m = self.modules.get(file)?;
444        if m.incomplete || m.assignment.is_some() {
445            return None;
446        }
447        let mut names: BTreeSet<String> = m.exports.keys().cloned().collect();
448        for target in &m.stars {
449            let mut forwarded = self.export_names(target, seen)?;
450            forwarded.remove("default");
451            names.extend(forwarded);
452        }
453        seen.remove(file);
454        Some(names)
455    }
456
457    fn canonical_barrel<'a>(&'a self, mut file: &'a str) -> Option<&'a str> {
458        let mut seen = BTreeSet::new();
459        while seen.insert(file) {
460            let m = self.modules.get(file)?;
461            if !m.incomplete && m.assignment.is_none() && m.stars.len() == 1 {
462                let target = m.stars[0].as_str();
463                let forwarded = |(export, b): (&String, &Binding)| match b {
464                    Binding::Named(f, name) => f == target && name == export && name != "default",
465                    Binding::Local(name) => {
466                        matches!(m.imports.get(name), Some(Binding::Named(f, original)) if f == target && original == export && original != "default")
467                    }
468                    Binding::Namespace(_) => false,
469                };
470                if m.exports.iter().all(forwarded) && self.modules.contains_key(target) {
471                    file = target;
472                    continue;
473                }
474            }
475            return Some(file);
476        }
477        None
478    }
479
480    pub(crate) fn search_alias<'a>(&'a self, entry: &'a Entry) -> &'a Entry {
481        if entry.alias_of.is_none() {
482            return entry;
483        }
484        let mut found = Resolution::default();
485        self.exported(&entry.file, &entry.path, &self.entries, &mut BTreeSet::new(), &mut found);
486        if !found.unresolved && found.entries.len() == 1 {
487            &self.entries[*found.entries.first().unwrap()]
488        } else {
489            entry
490        }
491    }
492
493    fn exported(&self, file: &str, path: &str, entries: &[Entry], seen: &mut BTreeSet<(String, String)>, out: &mut Resolution) {
494        if seen.len() > 128 {
495            out.unresolved = true;
496            return;
497        }
498        let key = (file.to_string(), path.to_string());
499        if !seen.insert(key.clone()) {
500            return;
501        }
502        let Some(m) = self.modules.get(file) else {
503            out.unresolved = true;
504            seen.remove(&key);
505            return;
506        };
507        out.unresolved |= m.incomplete;
508        let (name, tail) = path.split_once('.').unwrap_or((path, ""));
509        if let Some(b) = m.exports.get(name) {
510            self.binding(file, b, tail, entries, seen, out);
511        } else if let Some(namespace) = &m.assignment {
512            let local = if path.starts_with(&format!("{namespace}.")) {
513                path.to_string()
514            } else {
515                format!("{namespace}.{path}")
516            };
517            self.binding(file, &Binding::Local(local), "", entries, seen, out);
518        } else if name != "default" {
519            for star in &m.stars {
520                self.exported(star, path, entries, seen, out);
521            }
522        }
523        seen.remove(&key);
524    }
525
526    fn binding(&self, file: &str, b: &Binding, tail: &str, entries: &[Entry], seen: &mut BTreeSet<(String, String)>, out: &mut Resolution) {
527        let extend = |s: &str| if tail.is_empty() { s.to_string() } else { format!("{s}.{tail}") };
528        match b {
529            Binding::Namespace(target) => {
530                if tail.is_empty() {
531                    out.unresolved = true;
532                } else {
533                    self.exported(target, tail, entries, seen, out);
534                }
535            }
536            Binding::Named(target, name) => self.exported(target, &extend(name), entries, seen, out),
537            Binding::Local(name) => {
538                if let Some(import) = self.modules.get(file).and_then(|m| m.imports.get(name)) {
539                    self.binding(file, import, tail, entries, seen, out);
540                } else {
541                    let path = extend(name);
542                    let mut found = false;
543                    for (i, e) in entries.iter().enumerate() {
544                        if e.file == file && e.path == path && e.kind != Kind::Alias && e.kind != Kind::Prose {
545                            out.entries.insert(i);
546                            found = true;
547                        }
548                    }
549                    if !found {
550                        out.unresolved = true;
551                    }
552                }
553            }
554        }
555    }
556}