Skip to main content

lockdocs_core/
extract.rs

1//! Turn a package's files into entries: API symbols (signature + doc comment)
2//! from TypeScript declarations, JavaScript, Python, Rust and Go sources, and
3//! prose sections from READMEs, changelogs and docs folders.
4
5use serde::{Deserialize, Serialize};
6
7mod docs;
8mod go;
9mod npm;
10mod package;
11mod plan;
12mod python;
13mod rust;
14mod syntax;
15mod typescript;
16
17#[cfg(test)]
18mod tests;
19
20pub(crate) use npm::{npm_entries, npm_sources, npm_stamp};
21pub use package::extract;
22
23#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
24pub enum Kind {
25    Function,
26    Method,
27    Class,
28    Interface,
29    Type,
30    Const,
31    Enum,
32    Struct,
33    Trait,
34    Macro,
35    Module,
36    Field,
37    Alias,
38    Prose,
39}
40
41impl Kind {
42    pub fn as_str(self) -> &'static str {
43        match self {
44            Kind::Function => "function",
45            Kind::Method => "method",
46            Kind::Class => "class",
47            Kind::Interface => "interface",
48            Kind::Type => "type",
49            Kind::Const => "const",
50            Kind::Enum => "enum",
51            Kind::Struct => "struct",
52            Kind::Trait => "trait",
53            Kind::Macro => "macro",
54            Kind::Module => "module",
55            Kind::Field => "field",
56            Kind::Alias => "re-export",
57            Kind::Prose => "doc",
58        }
59    }
60    pub fn is_container(self) -> bool {
61        matches!(self, Kind::Class | Kind::Interface | Kind::Struct | Kind::Trait | Kind::Enum | Kind::Module)
62    }
63}
64
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct Entry {
67    pub kind: Kind,
68    /// Short name (`object`, `spawn`), or the heading path for prose.
69    pub name: String,
70    /// Qualified path: `z.object`, `tokio::task::spawn`, `pydantic.main.BaseModel.model_dump`.
71    pub path: String,
72    /// File relative to the package root.
73    pub file: String,
74    pub line: u32,
75    /// Declaration text without the body.
76    pub sig: String,
77    /// Doc comment, or the prose section text.
78    pub doc: String,
79    /// For re-exports: the local name this entry points at.
80    pub alias_of: Option<String>,
81    /// Lives in a legacy compatibility copy (`zod/v3` inside zod 4,
82    /// `pydantic/v1` inside pydantic 2): ranked below the current API.
83    #[serde(default)]
84    pub legacy: bool,
85    /// Effective module imports in this prose section and its setup examples.
86    #[serde(default)]
87    pub prose_imports: Vec<String>,
88    /// Citation lines of the logical ancestor sections, before chunking.
89    #[serde(default)]
90    pub prose_parents: Vec<u32>,
91}
92
93fn entry(kind: Kind, name: &str, path: String, file: &str, line: u32, sig: String, doc: String) -> Entry {
94    Entry {
95        kind,
96        name: name.to_string(),
97        path,
98        file: file.to_string(),
99        line,
100        sig,
101        doc,
102        alias_of: None,
103        legacy: false,
104        prose_imports: Vec::new(),
105        prose_parents: Vec::new(),
106    }
107}