Skip to main content

lockdocs_core/
lib.rs

1//! lockdocs core: read lockfiles, find each dependency's installed sources,
2//! extract API reference and prose, and answer queries with BM25 under a
3//! token budget. Public release-tag docs enrich first-use queries by default;
4//! opt-out and offline controls keep installed/cached answers local.
5
6pub mod bm25;
7pub mod cache;
8pub mod semantic;
9// Preserve the public module names without retaining local implementations.
10pub use semantic as embed;
11pub mod extract;
12pub mod fetch;
13pub mod index;
14pub mod locate;
15pub mod lockfile;
16pub mod markdown;
17pub mod project;
18pub mod query;
19pub use mcp_kit::search as tokenize;
20pub mod upgrade;
21pub mod upstream;
22
23use serde::{Deserialize, Serialize};
24use std::fmt;
25
26/// Package ecosystems lockdocs understands.
27#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
28pub enum Eco {
29    Npm,
30    PyPI,
31    Cargo,
32    Go,
33}
34
35impl Eco {
36    pub fn as_str(self) -> &'static str {
37        match self {
38            Eco::Npm => "npm",
39            Eco::PyPI => "pypi",
40            Eco::Cargo => "cargo",
41            Eco::Go => "go",
42        }
43    }
44    pub fn parse(s: &str) -> Option<Eco> {
45        Some(match s.to_ascii_lowercase().as_str() {
46            "npm" | "node" | "js" | "ts" => Eco::Npm,
47            "pypi" | "pip" | "py" | "python" => Eco::PyPI,
48            "cargo" | "crates" | "crate" | "rust" | "rs" => Eco::Cargo,
49            "go" | "golang" => Eco::Go,
50            _ => return None,
51        })
52    }
53    pub fn all() -> [Eco; 4] {
54        [Eco::Npm, Eco::PyPI, Eco::Cargo, Eco::Go]
55    }
56}
57
58impl fmt::Display for Eco {
59    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
60        f.write_str(self.as_str())
61    }
62}
63
64/// A resolved dependency: an exact version from a lockfile or an install.
65#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
66pub struct Dep {
67    pub eco: Eco,
68    pub name: String,
69    pub version: String,
70    /// Declared by the project itself (not only transitive).
71    pub direct: bool,
72    /// Where the version came from, e.g. `package-lock.json` or `node_modules`.
73    pub from: String,
74}
75
76impl Dep {
77    pub fn id(&self) -> String {
78        format!("{}@{}", self.name, self.version)
79    }
80}
81
82/// Normalize a package name for comparison within an ecosystem.
83pub fn norm_name(eco: Eco, name: &str) -> String {
84    match eco {
85        // PEP 503
86        Eco::PyPI => {
87            let mut out = String::with_capacity(name.len());
88            let mut dash = false;
89            for c in name.chars() {
90                if c == '-' || c == '_' || c == '.' {
91                    if !dash {
92                        out.push('-');
93                    }
94                    dash = true;
95                } else {
96                    out.push(c.to_ascii_lowercase());
97                    dash = false;
98                }
99            }
100            out
101        }
102        Eco::Cargo => name.replace('_', "-").to_ascii_lowercase(),
103        Eco::Npm => name.to_ascii_lowercase(),
104        Eco::Go => name.to_string(),
105    }
106}
107
108/// Conservative token estimate used for budgets: 3 characters per token,
109/// which keeps answers within budget under o200k/cl100k tokenizers for
110/// code-heavy text (the benchmark measures with a real tokenizer).
111pub fn est_tokens(s: &str) -> usize {
112    s.chars().count().div_ceil(3)
113}