Skip to main content

reflex/pulse/build/
mod.rs

1//! Build the Docs Model ([`Site`]) from the index.
2//!
3//! ```text
4//! Corpus (files, roles, edges, README) ─┐
5//! ModuleGraph (modules, edges, cycles) ─┼─► facts ─► Internals tab ─► Docs tab ─► Site
6//! git history ──────────────────────────┘
7//! ```
8//! Nothing here calls an LLM. Narrative blocks carry structural fallbacks; the writing
9//! pass fills them later by slot id.
10
11pub mod cli_ref;
12pub mod docs_tab;
13pub mod evidence;
14pub mod guides;
15pub mod internals_tab;
16pub mod links;
17pub mod modules;
18pub mod reference;
19pub mod releases;
20
21use crate::cache::CacheManager;
22use crate::pulse::extract::Corpus;
23use crate::pulse::model::{
24    Block, BuildReport, FactId, FactStore, Inline, NavNode, Page, PageId, PageKind, RepoInfo,
25    SCHEMA_VERSION, Site, SiteMeta, SlugAllocator, Subject, Tab, TabId,
26};
27use anyhow::Result;
28use modules::ModuleGraph;
29use std::collections::BTreeMap;
30use std::path::PathBuf;
31
32#[derive(Debug, Clone)]
33pub struct BuildOptions {
34    pub title: String,
35    /// 1 = top-level modules only, 2 = also subdirectories with 3+ source files.
36    pub max_depth: u8,
37    pub min_files: usize,
38    /// Where slugs persist between runs; `None` keeps them in memory only.
39    pub slugs_path: Option<PathBuf>,
40    /// Detect the git remote for source permalinks.
41    pub detect_repo: bool,
42    pub reference: reference::ReferenceOptions,
43}
44
45impl BuildOptions {
46    pub fn new(title: impl Into<String>) -> Self {
47        Self {
48            title: title.into(),
49            max_depth: 2,
50            min_files: 1,
51            slugs_path: None,
52            detect_repo: true,
53            reference: reference::ReferenceOptions::default(),
54        }
55    }
56}
57
58/// Build the model for the index in `cache`.
59pub fn build_site(cache: &CacheManager, opts: &BuildOptions) -> Result<Site> {
60    let corpus = Corpus::load(cache)?;
61    let graph = ModuleGraph::build(&corpus, opts.max_depth, opts.min_files);
62    let repo = opts
63        .detect_repo
64        .then(|| RepoInfo::detect(&corpus.root))
65        .flatten();
66
67    let slugs = match &opts.slugs_path {
68        Some(p) => SlugAllocator::load(p),
69        None => SlugAllocator::default(),
70    };
71    let mut b = SiteBuilder::new(opts.title.clone(), repo, slugs);
72    b.report.files_by_role = corpus.role_counts();
73    compute_facts(&mut b.facts, &corpus, &graph);
74
75    let apis = crate::pulse::extract::api_cache::load(cache, &corpus).unwrap_or_else(|e| {
76        log::warn!("API extraction skipped: {e:#}");
77        Default::default()
78    });
79    let content = crate::pulse::extract::ContentAccess::open(cache);
80    let mut rust = crate::pulse::extract::surface::Surface::resolve_rust(&corpus, &apis, &content);
81    rust.extend(crate::pulse::extract::surface::Surface::resolve_go(
82        &corpus, &apis, &content,
83    ));
84    rust.extend(crate::pulse::extract::surface::Surface::resolve_python(
85        &corpus, &apis, &content,
86    ));
87
88    let guides = guides::collect(&corpus, &content);
89    let (guide_nav, contributing_nav) = guides::build(&mut b, &corpus, &guides);
90    internals_tab::build(&mut b, &corpus, &graph, &apis, contributing_nav);
91    let commands = crate::pulse::extract::cli::find_commands(&rust);
92    let mut reference_nav = cli_ref::build(&mut b, &commands);
93    reference_nav.extend(reference::build(&mut b, &rust, &opts.reference));
94    let changelog_md = corpus
95        .files
96        .iter()
97        .find(|f| f.path.eq_ignore_ascii_case("CHANGELOG.md"))
98        .and_then(|f| content.read(&f.path));
99    let releases = releases::collect(&corpus.root, changelog_md);
100    docs_tab::build(&mut b, &corpus, &graph, &releases, guide_nav, reference_nav);
101
102    let (mut site, slugs) = b.finish();
103    links::resolve_markdown_links(&mut site);
104    let (packs, known) = evidence::build(&site, &corpus, &graph, &apis, &rust, &commands, &guides);
105    site.evidence = packs;
106    site.known_names = known;
107    if let Some(p) = &opts.slugs_path
108        && let Err(e) = slugs.save(p)
109    {
110        log::warn!("could not save {}: {e}", p.display());
111    }
112    Ok(site)
113}
114
115/// Collects pages, facts and nav while the tabs are built.
116pub struct SiteBuilder {
117    title: String,
118    repo: Option<RepoInfo>,
119    slugs: SlugAllocator,
120    pub facts: FactStore,
121    pub pages: BTreeMap<PageId, Page>,
122    pub symbols: BTreeMap<crate::pulse::model::SymbolId, crate::pulse::model::SymbolEntry>,
123    pub tabs: Vec<Tab>,
124    pub report: BuildReport,
125}
126
127impl SiteBuilder {
128    pub fn new(title: String, repo: Option<RepoInfo>, slugs: SlugAllocator) -> Self {
129        Self {
130            title,
131            repo,
132            slugs,
133            facts: FactStore::default(),
134            pages: BTreeMap::new(),
135            symbols: BTreeMap::new(),
136            tabs: Vec::new(),
137            report: BuildReport::default(),
138        }
139    }
140
141    pub fn title(&self) -> &str {
142        &self.title
143    }
144
145    pub fn repo(&self) -> Option<&RepoInfo> {
146        self.repo.as_ref()
147    }
148
149    /// Add a page. `slug` is `None` for a tab landing (`/` or `/internals/`), else
150    /// slash-separated, already-slugified segments under the tab prefix.
151    pub fn add_page(&mut self, spec: PageSpec) -> PageId {
152        let route = match (&spec.slug, spec.tab) {
153            (None, TabId::Docs) => "/".to_string(),
154            (None, tab) => tab.prefix().to_string(),
155            (Some(wanted), tab) => {
156                let slug = self.slugs.assign(&spec.id, wanted);
157                format!("{}{slug}/", tab.prefix())
158            }
159        };
160        let id = spec.id.clone();
161        self.pages.insert(
162            id.clone(),
163            Page {
164                id: spec.id,
165                tab: spec.tab,
166                kind: spec.kind,
167                title: spec.title,
168                description: spec.description,
169                route,
170                badges: spec.badges,
171                blocks: spec.blocks,
172            },
173        );
174        id
175    }
176
177    pub fn add_tab(&mut self, id: TabId, label: &str, landing: PageId, nav: Vec<NavNode>) {
178        self.tabs.push(Tab {
179            id,
180            label: label.to_string(),
181            landing,
182            nav,
183        });
184    }
185
186    /// A fact id, asserting the fact exists (a missing fact is a builder bug).
187    pub fn fact(&self, subject: &Subject, key: &str) -> FactId {
188        let id = FactStore::id_for(subject, key);
189        debug_assert!(self.facts.contains(&id), "missing fact {id}");
190        id
191    }
192
193    pub fn fact_inline(&self, subject: &Subject, key: &str) -> Inline {
194        Inline::fact(self.fact(subject, key))
195    }
196
197    fn finish(self) -> (Site, SlugAllocator) {
198        let mut tabs = self.tabs;
199        tabs.sort_by_key(|t| t.id);
200        let mut site = Site {
201            schema_version: SCHEMA_VERSION,
202            meta: SiteMeta {
203                title: self.title,
204                description: None,
205                repo: self.repo,
206                generator: format!("rfx {}", env!("CARGO_PKG_VERSION")),
207            },
208            tabs,
209            pages: self.pages,
210            symbols: self.symbols,
211            facts: self.facts,
212            report: self.report,
213            evidence: BTreeMap::new(),
214            known_names: Vec::new(),
215        };
216        site.check_links();
217        (site, self.slugs)
218    }
219}
220
221/// Arguments for [`SiteBuilder::add_page`].
222pub struct PageSpec {
223    pub id: PageId,
224    pub tab: TabId,
225    pub kind: PageKind,
226    pub title: String,
227    pub description: Option<String>,
228    pub slug: Option<String>,
229    pub badges: Vec<String>,
230    pub blocks: Vec<Block>,
231}
232
233/// Every number the site states, computed once.
234fn compute_facts(facts: &mut FactStore, corpus: &Corpus, graph: &ModuleGraph) {
235    use crate::pulse::extract::FileRole;
236    let source: Vec<_> = corpus.with_role(FileRole::Source).collect();
237    let q = |s: &str| s.to_string();
238    facts.count(
239        Subject::Site,
240        "source_files",
241        source.len() as u64,
242        &q("files table, role = source"),
243    );
244    facts.count(
245        Subject::Site,
246        "source_lines",
247        source.iter().map(|(_, f)| f.lines).sum(),
248        &q("sum(line_count), role = source"),
249    );
250    facts.count(
251        Subject::Site,
252        "indexed_files",
253        corpus.files.len() as u64,
254        &q("files table"),
255    );
256    facts.count(
257        Subject::Site,
258        "modules",
259        graph.modules.len() as u64,
260        &q("module detection over source files"),
261    );
262    let mut langs: BTreeMap<String, usize> = BTreeMap::new();
263    for (_, f) in &source {
264        *langs
265            .entry(crate::pulse::extract::language_name(f.language))
266            .or_insert(0) += 1;
267    }
268    facts.count(
269        Subject::Site,
270        "languages",
271        langs.len() as u64,
272        &q("distinct languages, role = source"),
273    );
274    facts.count(
275        Subject::Site,
276        "module_cycles",
277        graph.cycles().len() as u64,
278        &q("strongly connected module groups"),
279    );
280
281    for (mi, m) in graph.modules.iter().enumerate() {
282        let subject = Subject::Module(m.id.clone());
283        let sub_files: usize = graph
284            .children(mi)
285            .iter()
286            .map(|&c| graph.modules[c].files.len())
287            .sum();
288        facts.count(
289            subject.clone(),
290            "files",
291            m.files.len() as u64,
292            &q("source files owned by the module"),
293        );
294        facts.count(
295            subject.clone(),
296            "files_with_submodules",
297            (m.files.len() + sub_files) as u64,
298            &q("source files in the module and its submodules"),
299        );
300        facts.count(subject.clone(), "lines", m.lines, &q("sum(line_count)"));
301        facts.count(
302            subject.clone(),
303            "dependencies",
304            graph.dependencies(mi).len() as u64,
305            &q("modules imported from (resolved imports)"),
306        );
307        facts.count(
308            subject,
309            "dependents",
310            graph.dependents(mi).len() as u64,
311            &q("modules importing it (resolved imports)"),
312        );
313    }
314}
315
316/// Page id of a module page.
317pub fn module_page_id(module: &crate::pulse::model::ModuleId) -> PageId {
318    PageId(format!("int/module/{module}"))
319}
320
321/// Slug of a module page under the Internals prefix.
322pub fn module_slug(module: &crate::pulse::model::ModuleId) -> String {
323    if module.as_str() == "." {
324        return "modules/root".into();
325    }
326    let segs: Vec<String> = module
327        .as_str()
328        .split('/')
329        .map(crate::pulse::model::ids::slugify)
330        .collect();
331    format!("modules/{}", segs.join("/"))
332}
333
334#[cfg(test)]
335mod tests;