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