Skip to main content

reflex/pulse/extract/surface/
mod.rs

1//! Public surface: which items a user of the code can reach, and under which path.
2//!
3//! Per language, a resolver walks from the package entry points (a crate's `lib.rs`,
4//! a package's `exports`, …) and marks what is reachable. Everything else in a source
5//! file is internal: it appears on Internals pages only.
6
7pub mod go;
8pub mod python;
9pub mod rust;
10
11use crate::parsers::api::{ApiItem, DocComment};
12use std::collections::BTreeMap;
13
14/// Every package the corpus documents.
15#[derive(Debug, Clone, Default)]
16pub struct Surface {
17    pub packages: Vec<Package>,
18}
19
20#[derive(Debug, Clone)]
21/// A unit of distribution: a Rust crate, a Python package, an npm package, a Go module.
22pub struct Package {
23    /// Name as code refers to it (`reflex`, `my_lib`, `requests`).
24    pub name: String,
25    pub lang: crate::models::Language,
26    /// Path separator in `SurfaceModule::path` / `SurfaceItem::path` (`::`, `.`).
27    pub sep: &'static str,
28    /// Distribution name (`reflex-search`).
29    pub package: String,
30    pub manifest: String,
31    pub is_lib: bool,
32    pub root_file: String,
33    /// Tree order; `modules[0]` is the crate root.
34    pub modules: Vec<SurfaceModule>,
35}
36
37#[derive(Debug, Clone)]
38pub struct SurfaceModule {
39    /// `demo`, `demo::store`, `demo::store::db`.
40    pub path: String,
41    pub name: String,
42    pub file: String,
43    pub public: bool,
44    pub doc: Option<DocComment>,
45    pub items: Vec<SurfaceItem>,
46    pub children: Vec<usize>,
47    pub parent: Option<usize>,
48}
49
50#[derive(Debug, Clone)]
51pub struct SurfaceItem {
52    /// For types, `members` also holds methods and associated items from `impl` blocks.
53    pub item: ApiItem,
54    pub file: String,
55    pub public: bool,
56    /// Documented path (`demo::store::Db`, or the re-export path).
57    pub path: String,
58    /// Where it is defined, when `path` is a re-export.
59    pub defined_at: Option<String>,
60    /// File of each member attached from an `impl` block, by index in `item.members`.
61    pub impl_files: BTreeMap<usize, String>,
62}
63
64impl Surface {
65    /// Library packages: the ones with a public API to document.
66    pub fn libraries(&self) -> impl Iterator<Item = &Package> {
67        self.packages.iter().filter(|c| c.is_lib)
68    }
69
70    pub fn extend(&mut self, other: Surface) {
71        self.packages.extend(other.packages);
72    }
73}
74
75impl Package {
76    /// `a`, `b` → `a::b` (or `a.b`).
77    pub fn join(&self, a: &str, b: &str) -> String {
78        format!("{a}{}{b}", self.sep)
79    }
80
81    /// Lowercase language id for symbol ids and code highlighting (`rust`).
82    pub fn lang_id(&self) -> String {
83        serde_json::to_value(self.lang)
84            .ok()
85            .and_then(|v| v.as_str().map(str::to_string))
86            .unwrap_or_else(|| "text".into())
87    }
88}