Skip to main content

reflex/parsers/api/
mod.rs

1//! API extraction: the documented surface of a source file.
2//!
3//! The symbol index ([`crate::parsers`]) answers "where is `X` defined"; it keeps
4//! name, kind and span only, because it sits on the query hot path. Docs need more:
5//! the signature, the doc comment, visibility, the container (`impl Foo`), fields,
6//! variants and methods. This module extracts that from one file's source.
7//!
8//! Pulse runs it at generation time over source-role files and caches the result by
9//! content hash (see `pulse::extract::api_cache`), so `rfx index` pays nothing for it.
10
11pub mod doc;
12pub mod go;
13pub mod pydoc;
14pub mod python;
15pub mod rust;
16
17use crate::models::Language;
18use serde::{Deserialize, Serialize};
19
20/// Bump when the output of any extractor changes; cached results are then rebuilt.
21pub const EXTRACTOR_VERSION: u32 = 5;
22
23/// The documented surface of one file.
24#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
25pub struct ApiFile {
26    /// Inner doc comment of the file (`//!`), or the module docstring (Python).
27    #[serde(default, skip_serializing_if = "Option::is_none")]
28    pub module_doc: Option<DocComment>,
29    /// Top-level items, in source order. Members nest inside their parent.
30    pub items: Vec<ApiItem>,
31    /// `mod foo;` declarations (Rust), in source order.
32    #[serde(default, skip_serializing_if = "Vec::is_empty")]
33    pub mod_decls: Vec<ModDecl>,
34    /// `pub use` re-exports (Rust), `from x import A` (Python), in source order.
35    #[serde(default, skip_serializing_if = "Vec::is_empty")]
36    pub reexports: Vec<ReExport>,
37    /// The package the file declares (`package foo` in Go), for languages with one.
38    #[serde(default, skip_serializing_if = "Option::is_none")]
39    pub package: Option<String>,
40    /// The file's explicit export list, when it declares one (Python `__all__`).
41    #[serde(default, skip_serializing_if = "Option::is_none")]
42    pub exports: Option<Vec<String>>,
43}
44
45#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
46#[serde(rename_all = "kebab-case")]
47pub enum ApiKind {
48    Module,
49    Function,
50    Method,
51    Struct,
52    /// A class (Python, TypeScript, Java, …).
53    Class,
54    Enum,
55    Variant,
56    Field,
57    Trait,
58    TypeAlias,
59    AssociatedType,
60    Const,
61    Static,
62    Macro,
63    Union,
64    /// A Go interface (a TypeScript/Java/C# interface).
65    Interface,
66}
67
68impl ApiKind {
69    /// Types get their own reference page; everything else is listed on its module
70    /// or type page.
71    pub fn is_type(&self) -> bool {
72        matches!(
73            self,
74            ApiKind::Struct
75                | ApiKind::Class
76                | ApiKind::Enum
77                | ApiKind::Trait
78                | ApiKind::Union
79                | ApiKind::Interface
80        )
81    }
82
83    pub fn label(&self) -> &'static str {
84        match self {
85            ApiKind::Module => "module",
86            ApiKind::Function => "fn",
87            ApiKind::Method => "method",
88            ApiKind::Struct => "struct",
89            ApiKind::Class => "class",
90            ApiKind::Enum => "enum",
91            ApiKind::Variant => "variant",
92            ApiKind::Field => "field",
93            ApiKind::Trait => "trait",
94            ApiKind::TypeAlias => "type",
95            ApiKind::AssociatedType => "associated type",
96            ApiKind::Const => "const",
97            ApiKind::Static => "static",
98            ApiKind::Macro => "macro",
99            ApiKind::Union => "union",
100            ApiKind::Interface => "interface",
101        }
102    }
103}
104
105#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
106#[serde(tag = "type", content = "scope", rename_all = "kebab-case")]
107pub enum Visibility {
108    /// `pub`, `export`, an uppercase Go name.
109    Public,
110    /// `pub(crate)`, `pub(super)`, `pub(in path)`.
111    Restricted(String),
112    /// No modifier where one is required to be public.
113    Private,
114    /// Visibility follows the container (trait methods, enum variants).
115    Inherited,
116}
117
118impl Visibility {
119    pub fn is_public(&self) -> bool {
120        matches!(self, Visibility::Public | Visibility::Inherited)
121    }
122}
123
124/// One documented item.
125#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
126pub struct ApiItem {
127    pub name: String,
128    pub kind: ApiKind,
129    pub visibility: Visibility,
130    /// Declaration text up to the body, whitespace-collapsed (`pub fn f(x: u32) -> u8`).
131    pub signature: String,
132    #[serde(default, skip_serializing_if = "Option::is_none")]
133    pub sig: Option<SigParts>,
134    #[serde(default, skip_serializing_if = "Option::is_none")]
135    pub doc: Option<DocComment>,
136    /// Attributes other than doc comments: `derive(Debug, Clone)`, `cfg(test)`.
137    #[serde(default, skip_serializing_if = "Vec::is_empty")]
138    pub attrs: Vec<String>,
139    #[serde(default, skip_serializing_if = "Option::is_none")]
140    pub deprecated: Option<Deprecation>,
141    /// `#[doc(hidden)]`.
142    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
143    pub hidden: bool,
144    /// Inside `#[cfg(test)]`.
145    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
146    pub test_only: bool,
147    /// 1-based lines of the whole item.
148    pub start_line: u32,
149    pub end_line: u32,
150    /// For methods and associated items: `impl Trait for Type`'s trait, if any.
151    #[serde(default, skip_serializing_if = "Option::is_none")]
152    pub trait_impl: Option<String>,
153    /// For impl members: the implementing type as written (`Foo<T>`).
154    #[serde(default, skip_serializing_if = "Option::is_none")]
155    pub self_type: Option<String>,
156    /// Fields, variants, methods, associated items; inline module contents.
157    #[serde(default, skip_serializing_if = "Vec::is_empty")]
158    pub members: Vec<ApiItem>,
159}
160
161#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
162pub struct SigParts {
163    #[serde(default, skip_serializing_if = "Option::is_none")]
164    pub generics: Option<String>,
165    /// `&self`, `&mut self`, `self`.
166    #[serde(default, skip_serializing_if = "Option::is_none")]
167    pub receiver: Option<String>,
168    #[serde(default, skip_serializing_if = "Vec::is_empty")]
169    pub params: Vec<Param>,
170    #[serde(default, skip_serializing_if = "Option::is_none")]
171    pub returns: Option<String>,
172    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
173    pub is_async: bool,
174    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
175    pub is_unsafe: bool,
176    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
177    pub is_const: bool,
178}
179
180#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
181pub struct Param {
182    pub name: String,
183    pub ty: String,
184}
185
186#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
187pub struct Deprecation {
188    #[serde(default, skip_serializing_if = "Option::is_none")]
189    pub since: Option<String>,
190    #[serde(default, skip_serializing_if = "Option::is_none")]
191    pub note: Option<String>,
192}
193
194/// A doc comment, as markdown, plus the parts the renderer lays out separately.
195#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
196pub struct DocComment {
197    /// The comment with markers stripped (`///`, `//!`, `/** */`).
198    pub markdown: String,
199    /// First paragraph, as plain-ish markdown.
200    pub summary: String,
201    /// `# Errors`, `# Panics`, `# Safety`, `# Examples`, … keyed by lowercase heading.
202    #[serde(default, skip_serializing_if = "Vec::is_empty")]
203    pub sections: Vec<(String, String)>,
204    /// Code fences; rustdoc hidden lines (`# `) removed.
205    #[serde(default, skip_serializing_if = "Vec::is_empty")]
206    pub examples: Vec<CodeExample>,
207    /// Intra-doc links as written: `Foo`, `crate::x::Bar`, `Self::new`.
208    #[serde(default, skip_serializing_if = "Vec::is_empty")]
209    pub links: Vec<String>,
210    /// 1-based lines of the comment.
211    pub start_line: u32,
212    pub end_line: u32,
213}
214
215#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
216pub struct CodeExample {
217    pub lang: String,
218    pub code: String,
219    /// Rustdoc compiles bare and `rust` fences unless marked `ignore`/`no_run`/`text`.
220    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
221    pub doctest: bool,
222}
223
224/// `mod foo;` / `pub mod foo;` / `mod foo { … }`.
225#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
226pub struct ModDecl {
227    pub name: String,
228    pub visibility: Visibility,
229    /// `true` for `mod foo { … }` (its items are in [`ApiItem::members`]).
230    pub inline: bool,
231    /// `#[path = "…"]`, if present.
232    #[serde(default, skip_serializing_if = "Option::is_none")]
233    pub path_attr: Option<String>,
234    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
235    pub test_only: bool,
236    pub line: u32,
237}
238
239/// `pub use a::b::C;` / `pub use a::b::C as D;` / `pub use a::b::*;`.
240/// Python: `from .x import A` / `from .x import A as B` / `from pkg.sub import *`.
241#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
242pub struct ReExport {
243    /// Path as written, `::`-separated (`crate::query::QueryEngine`). Python keeps its
244    /// dots and relative prefix, with the imported name last (`.x.A`, `..A`, `pkg.sub.*`).
245    pub path: String,
246    /// Name it is exported under (`QueryEngine`, `D`, or `*`).
247    pub name: String,
248    pub visibility: Visibility,
249    pub line: u32,
250}
251
252/// Whether [`extract`] handles this language.
253pub fn has_extractor(language: Language) -> bool {
254    matches!(language, Language::Rust | Language::Go | Language::Python)
255}
256
257/// Extract the API of one file, if its language has an extractor.
258pub fn extract(language: Language, source: &str) -> Option<ApiFile> {
259    match language {
260        Language::Rust => rust::extract(source).ok(),
261        Language::Go => go::extract(source).ok(),
262        Language::Python => python::extract(source).ok(),
263        _ => None,
264    }
265}
266
267/// Collapse runs of whitespace to one space.
268pub(crate) fn collapse_ws(s: &str) -> String {
269    let mut out = String::with_capacity(s.len());
270    let mut space = false;
271    for c in s.chars() {
272        if c.is_whitespace() {
273            space = true;
274        } else {
275            if space && !out.is_empty() {
276                out.push(' ');
277            }
278            space = false;
279            out.push(c);
280        }
281    }
282    out
283}