1pub 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 pub max_depth: u8,
37 pub min_files: usize,
38 pub slugs_path: Option<PathBuf>,
40 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
58pub 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
115pub 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 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 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
221pub 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
233fn 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
316pub fn module_page_id(module: &crate::pulse::model::ModuleId) -> PageId {
318 PageId(format!("int/module/{module}"))
319}
320
321pub 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;