Skip to main content

lockdocs_core/query/
api.rs

1//! Exact API lookup and version-to-version API comparison.
2
3use super::entries::{npm_import_base, private_path, resolve_alias, split_symbol, tooling_path};
4use super::packages::Resolved;
5use super::render::{provenance, render_entry, truncate, Pack};
6use super::{Answer, Engine};
7use crate::extract::{Entry, Kind};
8use crate::project::Spec;
9use crate::{est_tokens, Dep, Eco};
10use serde_json::json;
11use std::collections::HashSet;
12
13impl Engine {
14    pub fn api(&self, symbol: &str, package: Option<&str>, tokens: usize) -> Result<Answer, String> {
15        let tokens = tokens.clamp(200, 20000);
16        let symbol = symbol.trim().trim_end_matches("()").trim();
17        if symbol.is_empty() {
18            return Err("symbol is required, e.g. `z.object`, `tokio::spawn`, `BaseModel.model_dump`".into());
19        }
20        let mut requested_import = None;
21        let (deps, rest) = match package.filter(|p| !p.trim().is_empty()) {
22            Some(p) => {
23                let spec = Spec::parse(p);
24                let base = npm_import_base(&spec.name);
25                if spec.eco.is_none_or(|e| e == Eco::Npm) && base != spec.name && self.project.find(&spec).is_empty() {
26                    let selector = format!("npm:{base}{}", spec.version.as_ref().map(|v| format!("@{v}")).unwrap_or_default());
27                    requested_import = Some(spec.name);
28                    (self.select(Some(&selector), "")?.0, symbol.to_string())
29                } else {
30                    (self.select(Some(p), "")?.0, symbol.to_string())
31                }
32            }
33            None => match self
34                .npm_import_prefix(symbol)
35                .map(|(dep, import, rest)| {
36                    requested_import = Some(import);
37                    (dep, rest)
38                })
39                .or_else(|| self.package_prefix(symbol))
40            {
41                Some((dep, rest)) => (vec![dep], rest),
42                None => (self.select(None, symbol)?.0, symbol.to_string()),
43            },
44        };
45        let segs: Vec<String> = split_symbol(&rest);
46        let Some(last) = segs.last().map(|l| l.trim_end_matches('!').to_string()) else {
47            // Only a package name: give the overview.
48            return self.docs(
49                Some(&deps.iter().map(|d| format!("{}:{}@{}", d.eco, d.name, d.version)).collect::<Vec<_>>().join(",")),
50                "",
51                tokens,
52            );
53        };
54        let quals: Vec<String> = segs[..segs.len() - 1].iter().map(|s| s.to_ascii_lowercase()).collect();
55        let (ready, missing) = self.resolve_all(&deps);
56        if ready.is_empty() {
57            return Err(missing.into_iter().map(|(_, e)| e).collect::<Vec<_>>().join("\n"));
58        }
59        let mut cands: Vec<(f32, usize, usize)> = Vec::new();
60        let mut applicability = Vec::new();
61        let mut alternatives = Vec::new();
62        let mut unresolved = false;
63        let mut npm_scoped = false;
64        let last_l = last.to_ascii_lowercase();
65        let public_path = segs.join(".");
66        for (pi, (idx, _, _)) in ready.iter().enumerate() {
67            if let Some(api) = &idx.npm_api {
68                npm_scoped = true;
69                let import = requested_import.as_deref().unwrap_or(&idx.name);
70                let mut has_root = false;
71                for root in &api.roots {
72                    let found = api.resolve(root, &public_path, idx.api_entries());
73                    if root.import == import {
74                        has_root = true;
75                        unresolved |= found.unresolved;
76                        for ei in found.entries {
77                            let e = &idx.api_entries()[ei];
78                            cands.push((10.0, pi, ei));
79                            applicability.push(
80                                json!({"import": root.import, "conditions": root.conditions.trim_start_matches('/'), "entrypoint": root.file,
81                                "file": e.file, "line": e.line, "path": e.path}),
82                            );
83                        }
84                    } else if !found.unresolved {
85                        for ei in found.entries {
86                            let e = &idx.api_entries()[ei];
87                            alternatives.push(
88                                json!({"package": idx.id(), "import": root.import, "conditions": root.conditions.trim_start_matches('/'),
89                                "entrypoint": root.file, "path": e.path, "file": e.file, "line": e.line, "signature": e.sig}),
90                            );
91                        }
92                    }
93                }
94                unresolved |= !has_root;
95                continue;
96            }
97            for (ei, e) in idx.api_entries().iter().enumerate() {
98                if e.kind == Kind::Prose {
99                    continue;
100                }
101                let name = e.name.trim_end_matches('!');
102                let exact = name == last;
103                if !exact && name.to_ascii_lowercase() != last_l {
104                    continue;
105                }
106                cands.push((api_score(e, exact, &quals), pi, ei));
107            }
108        }
109        cands.sort_by_key(|(_, pi, ei)| (*pi, *ei));
110        cands.dedup_by_key(|(_, pi, ei)| (*pi, *ei));
111        // Multiple overloads at one declaration are valid. Conflicting files,
112        // packages or conditional editions are not a license to guess.
113        let locations: HashSet<_> = cands
114            .iter()
115            .map(|(_, pi, ei)| (*pi, &ready[*pi].0.api_entries()[*ei].file, &ready[*pi].0.api_entries()[*ei].path))
116            .collect();
117        let ambiguous = npm_scoped && locations.len() > 1 && {
118            let signatures: HashSet<_> = cands.iter().map(|(_, pi, ei)| &ready[*pi].0.api_entries()[*ei].sig).collect();
119            signatures.len() > 1
120        };
121        if npm_scoped && (cands.is_empty() || unresolved || ambiguous) {
122            let status = if ambiguous {
123                "ambiguous"
124            } else if unresolved {
125                "unresolved"
126            } else {
127                "not_exported"
128            };
129            let imports: Vec<_> = ready
130                .iter()
131                .filter(|r| r.0.eco == Eco::Npm)
132                .map(|r| requested_import.as_deref().unwrap_or(&r.0.name))
133                .collect();
134            let mut out = Pack::new(tokens);
135            out.push_raw(&format!(
136                "No verified exact public API match for `{public_path}` from `{}` ({}).\n",
137                imports.join("`, `"),
138                status
139            ));
140            out.push_block(if ambiguous {
141                "Public declarations disagree across entrypoints or export conditions; no signature was selected.\n"
142            } else if unresolved {
143                "Import applicability could not be fully resolved from the installed declarations; no unrelated same-named symbol was substituted.\n"
144            } else {
145                "This symbol is not exported by the requested import entrypoint. Same-named internal declarations are not a match.\n"
146            });
147            for a in alternatives.iter().take(8) {
148                out.push_block(&format!(
149                    "Alternate import `{}` ({}): `{}` — {} {}:{}\n",
150                    a["import"].as_str().unwrap_or(""),
151                    a["conditions"].as_str().unwrap_or(""),
152                    a["signature"].as_str().unwrap_or(""),
153                    a["package"].as_str().unwrap_or(""),
154                    a["file"].as_str().unwrap_or(""),
155                    a["line"]
156                ));
157            }
158            if ambiguous {
159                for a in applicability.iter().take(8) {
160                    out.push_block(&format!(
161                        "Applicable import `{}` ({}) via {} → {}:{}\n",
162                        a["import"].as_str().unwrap_or(""),
163                        a["conditions"].as_str().unwrap_or(""),
164                        a["entrypoint"].as_str().unwrap_or(""),
165                        a["file"].as_str().unwrap_or(""),
166                        a["line"]
167                    ));
168                }
169                for (_, pi, ei) in cands.iter().take(8) {
170                    let idx = &ready[*pi].0;
171                    out.push_block(&render_entry(idx, &idx.api_entries()[*ei], 500));
172                }
173            }
174            return Ok(Answer {
175                json: json!({"status": status, "symbol": public_path, "imports": imports, "provenance": provenance(&ready),
176                "applicability": applicability, "alternatives": alternatives, "tokens": est_tokens(&out.text)}),
177                text: out.text,
178            });
179        }
180        cands.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
181        if cands.is_empty() {
182            // Nothing by that name: fall back to a docs search scoped to the same packages.
183            let pk = ready
184                .iter()
185                .map(|r| format!("{}:{}@{}", r.0.eco, r.0.name, r.0.version))
186                .collect::<Vec<_>>()
187                .join(",");
188            let mut a = self.docs(Some(&pk), &segs.join(" "), tokens)?;
189            a.text = format!(
190                "No symbol named `{last}` in {}; closest documentation:\n\n{}",
191                ready.iter().map(|r| r.0.id()).collect::<Vec<_>>().join(", "),
192                a.text
193            );
194            return Ok(a);
195        }
196        let (_, bpi, bei) = cands[0];
197        let (idx, dep, note) = &ready[bpi];
198        let best0 = &idx.api_entries()[bei];
199        let best = if idx.npm_api.is_some() { best0 } else { resolve_alias(idx, best0) };
200        let mut out = Pack::new(tokens);
201        out.push_raw(&format!(
202            "{} · {} · {}{}\n",
203            idx.id(),
204            idx.eco,
205            idx.source,
206            if dep.from == "requested" {
207                String::new()
208            } else {
209                format!(" · pinned in {}", dep.from)
210            }
211        ));
212        if let Some(u) = &idx.upstream {
213            out.push_raw(&format!("Upstream: {u}\n"));
214        }
215        if let Some(n) = note {
216            out.push_raw(&format!("Note: {n}\n"));
217        }
218        if !std::ptr::eq(best, best0) {
219            out.push_raw(&format!(
220                "`{}` is a re-export of `{}` ({}:{}).\n",
221                best0.path, best.path, best0.file, best0.line
222            ));
223        }
224        if idx.npm_api.is_some() {
225            out.push_raw(&format!(
226                "Public import: `{}` · symbol `{public_path}`\n",
227                requested_import.as_deref().unwrap_or(&idx.name)
228            ));
229            for a in &applicability {
230                out.push_block(&format!(
231                    "Declaration entrypoint: {} ({})\n",
232                    a["entrypoint"].as_str().unwrap_or(""),
233                    a["conditions"].as_str().unwrap_or("")
234                ));
235            }
236        }
237        out.push_block(&render_entry(idx, best, 6000));
238        // Overloads and declaration merging: same path, other entries.
239        let overloads: Vec<&Entry> = idx
240            .api_entries()
241            .iter()
242            .filter(|e| e.path == best.path && e.file == best.file && !std::ptr::eq(*e, best) && e.kind != Kind::Prose && e.kind != Kind::Alias)
243            .take(8)
244            .collect();
245        if !overloads.is_empty() {
246            let mut s = String::from("Other declarations:\n");
247            for e in overloads {
248                s.push_str(&format!("- `{}` — {} {}:{}\n", e.sig, idx.id(), e.file, e.line));
249            }
250            out.push_block(&s);
251        }
252        let mut members_json = Vec::new();
253        if best.kind.is_container() {
254            let sep = if idx.eco == Eco::Cargo { "::" } else { "." };
255            let prefix = format!("{}{sep}", best.path);
256            let members: Vec<&Entry> = idx
257                .api_entries()
258                .iter()
259                .filter(|e| {
260                    e.path.starts_with(&prefix)
261                        && !e.path[prefix.len()..].contains(sep)
262                        && e.kind != Kind::Prose
263                        && (idx.npm_api.is_none() || e.file == best.file)
264                })
265                .collect();
266            if !members.is_empty() {
267                let mut s = format!("Members of {} ({}):\n", best.path, members.len());
268                for m in members.iter().take(80) {
269                    let doc1 = m.doc.lines().next().unwrap_or("");
270                    s.push_str(&format!(
271                        "- `{}`{}{} — {}:{}\n",
272                        m.sig,
273                        if doc1.is_empty() { "" } else { " — " },
274                        truncate(doc1, 120),
275                        m.file,
276                        m.line
277                    ));
278                    members_json.push(json!({"path": m.path, "sig": m.sig, "file": m.file, "line": m.line}));
279                }
280                out.push_block(&s);
281            }
282        }
283        let others: Vec<String> = cands
284            .iter()
285            .skip(1)
286            .filter(|(_, pi, ei)| {
287                let e = &ready[*pi].0.api_entries()[*ei];
288                !(e.path == best.path && e.file == best.file) && !std::ptr::eq(e, best0)
289            })
290            .take(8)
291            .map(|(_, pi, ei)| {
292                let (ix, _, _) = &ready[*pi];
293                let e = &ix.api_entries()[*ei];
294                format!("- {} `{}` — {} {}:{}", e.kind.as_str(), e.path, ix.id(), e.file, e.line)
295            })
296            .collect();
297        if !others.is_empty() {
298            out.push_block(&format!("Other matches:\n{}\n", others.join("\n")));
299        }
300        Ok(Answer {
301            json: json!({
302                "provenance": provenance(&ready), "package": idx.id(), "kind": best.kind.as_str(), "path": best.path, "signature": best.sig, "doc": best.doc,
303                "file": best.file, "line": best.line, "members": members_json, "tokens": est_tokens(&out.text),
304                "status": "exact", "import": if idx.npm_api.is_some() { Some(requested_import.as_deref().unwrap_or(&idx.name)) } else { None },
305                "applicability": applicability, "alternatives": alternatives,
306            }),
307            text: out.text,
308        })
309    }
310
311    fn npm_import_prefix(&self, symbol: &str) -> Option<(Dep, String, String)> {
312        for d in &self.project.deps {
313            if d.eco != Eco::Npm {
314                continue;
315            }
316            let Some(rest) = symbol.strip_prefix(&format!("{}/", d.name)) else {
317                continue;
318            };
319            if let Some((subpath, sym)) = rest.split_once('.') {
320                return Some((d.clone(), format!("{}/{subpath}", d.name), sym.to_string()));
321            }
322        }
323        None
324    }
325
326    /// `zod.z.object` -> (zod, `z.object`); `tokio::spawn` -> (tokio, `spawn`);
327    /// `@tanstack/react-query.useQuery`; `github.com/gin-gonic/gin.Context`.
328    fn package_prefix(&self, symbol: &str) -> Option<(Dep, String)> {
329        let mut best: Option<(usize, Dep)> = None;
330        let bytes = symbol.as_bytes();
331        let mut cuts: Vec<usize> = Vec::new();
332        for i in 0..bytes.len() {
333            if bytes[i] == b'.' || bytes[i] == b'#' || (bytes[i] == b':' && i + 1 < bytes.len() && bytes[i + 1] == b':') {
334                cuts.push(i);
335            }
336        }
337        cuts.push(symbol.len());
338        for &c in &cuts {
339            let cand = &symbol[..c];
340            let spec = Spec::parse(cand);
341            if spec.version.is_some() {
342                continue;
343            }
344            let found = self.project.find(&spec);
345            if let Some(d) = found.first() {
346                if best.as_ref().is_none_or(|(bc, _)| c > *bc) {
347                    best = Some((c, (*d).clone()));
348                }
349            }
350        }
351        let (c, dep) = best?;
352        let rest = symbol[c..].trim_start_matches(['.', '#', ':']).to_string();
353        Some((dep, rest))
354    }
355
356    /// Upgrade report (lockdocs Pro; the caller checks the licence): the API
357    /// difference between the pinned version of `package` and `target`,
358    /// limited to symbols this project uses. The target version is read from
359    /// the same sources as any other version (installed, cached, or fetched
360    /// when fetching is enabled).
361    pub fn upgrade_report(&self, package: &str, target: &str, tokens: usize) -> Result<Answer, String> {
362        let spec = Spec::parse(package);
363        let found = self.project.find(&spec);
364        let dep = found
365            .iter()
366            .find(|d| d.direct)
367            .or_else(|| found.first())
368            .map(|d| (*d).clone())
369            .ok_or_else(|| format!("`{package}` is not pinned in this project's lockfiles; run `resolve` to see packages."))?;
370        let target = target.trim().trim_start_matches('v');
371        if target.is_empty() {
372            return Err("`upgrade_to` needs a target version, e.g. 15.0.0".into());
373        }
374        if target == dep.version.trim_start_matches('v') {
375            return Err(format!("{} is already the pinned version; pick a different target.", dep.id()));
376        }
377        let old = match self.index(&dep) {
378            Resolved::Ready(i, _, _) => i,
379            Resolved::Missing(_, e) => return Err(e),
380        };
381        let target_dep = Dep {
382            eco: dep.eco,
383            name: dep.name.clone(),
384            version: target.to_string(),
385            direct: false,
386            from: "requested".into(),
387        };
388        let new = match self.index(&target_dep) {
389            Resolved::Ready(i, _, _) => i,
390            Resolved::Missing(_, e) => {
391                return Err(format!(
392                    "{e}\nThe target version's files are needed to compare; add --fetch (or LOCKDOCS_FETCH=1) to download exactly {}.",
393                    target_dep.id()
394                ))
395            }
396        };
397        let r = crate::upgrade::report(&self.project.root, &old, &new);
398        let max = tokens.clamp(200, 20000) * 3;
399        let text = if r.text.len() > max {
400            format!("{}\n... truncated to the token budget; raise `tokens`.\n", truncate(&r.text, max))
401        } else {
402            r.text
403        };
404        Ok(Answer { text, json: r.json })
405    }
406}
407
408fn api_score(e: &Entry, exact: bool, quals: &[String]) -> f32 {
409    let mut s = if exact { 10.0 } else { 7.0 };
410    let segs: Vec<String> = split_symbol(&e.path).into_iter().map(|x| x.to_ascii_lowercase()).collect();
411    // A bare name means the top-level API, not a same-named member.
412    if quals.is_empty() {
413        s += if matches!(e.kind, Kind::Method | Kind::Field) { -1.5 } else { 1.5 };
414    }
415    let file = e.file.to_ascii_lowercase();
416    for q in quals {
417        if segs.iter().any(|x| x == q) {
418            s += 3.0;
419        } else if file.contains(q.as_str()) {
420            s += 1.0;
421        }
422    }
423    // The qualifier directly before the name matters most (`Router.route`).
424    if let (Some(q), Some(parent)) = (quals.last(), segs.len().checked_sub(2).map(|i| &segs[i])) {
425        if q == parent {
426            s += 2.0;
427        }
428    }
429    if !e.doc.is_empty() {
430        s += 2.0;
431    }
432    if private_path(e) {
433        s -= 3.0;
434    }
435    if e.legacy {
436        s -= 5.0;
437    }
438    if tooling_path(e) {
439        s -= 3.0;
440    }
441    if e.kind == Kind::Alias {
442        s -= 0.5;
443    }
444    s -= 0.2 * segs.len() as f32;
445    s
446}