1use 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 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 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 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 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 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 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 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 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}