pub mod content;
pub mod evidence;
pub mod facts;
pub mod ids;
pub mod text;
pub mod xref;
pub use content::{Block, Card, Inline, MarkdownOrigin, MarkdownText, ParamRow, Stat, SymbolBlock};
pub use facts::{Fact, FactStore, FactValue, Provenance, Subject};
pub use ids::{AnchorId, FactId, ModuleId, PageId, SlugAllocator, SymbolId};
pub use xref::{Linker, RepoInfo, SourceLoc, Target};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
pub const SCHEMA_VERSION: u32 = 1;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Site {
pub schema_version: u32,
pub meta: SiteMeta,
pub tabs: Vec<Tab>,
pub pages: BTreeMap<PageId, Page>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub symbols: BTreeMap<SymbolId, SymbolEntry>,
pub facts: FactStore,
pub report: BuildReport,
#[serde(skip)]
pub evidence: BTreeMap<String, evidence::EvidencePack>,
#[serde(skip)]
pub known_names: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SymbolEntry {
pub name: String,
pub path: String,
pub kind: String,
pub page: PageId,
pub anchor: Option<AnchorId>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SiteMeta {
pub title: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub repo: Option<RepoInfo>,
pub generator: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum TabId {
Docs,
Internals,
}
impl TabId {
pub fn prefix(&self) -> &'static str {
match self {
TabId::Docs => "/docs/",
TabId::Internals => "/internals/",
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Tab {
pub id: TabId,
pub label: String,
pub landing: PageId,
pub nav: Vec<NavNode>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case")]
pub enum NavNode {
Page {
page: PageId,
},
Group {
label: String,
#[serde(default)]
collapsed: bool,
children: Vec<NavNode>,
},
}
impl NavNode {
pub fn page(id: &PageId) -> Self {
NavNode::Page { page: id.clone() }
}
}
pub(crate) fn collect_nav_pages(nav: &[NavNode], out: &mut Vec<PageId>) {
for n in nav {
match n {
NavNode::Page { page } => out.push(page.clone()),
NavNode::Group { children, .. } => collect_nav_pages(children, out),
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Page {
pub id: PageId,
pub tab: TabId,
pub kind: PageKind,
pub title: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
pub route: String,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub badges: Vec<String>,
pub blocks: Vec<Block>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case")]
pub enum PageKind {
Landing,
Architecture,
Module {
module: ModuleId,
},
DependencyMap,
Changelog,
Glossary,
Guide {
source: String,
},
ReferenceModule {
path: String,
},
ReferenceType {
path: String,
},
CliCommand {
command: String,
},
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct BuildReport {
pub files_by_role: BTreeMap<String, usize>,
pub broken_links: Vec<(PageId, Target)>,
pub warnings: Vec<String>,
}
impl Site {
pub fn nav_order(&self, tab: TabId) -> Vec<PageId> {
let Some(t) = self.tabs.iter().find(|t| t.id == tab) else {
return Vec::new();
};
let mut ids = vec![t.landing.clone()];
collect_nav_pages(&t.nav, &mut ids);
ids
}
pub fn fill_narratives(&mut self, mut text: impl FnMut(&str) -> Option<String>) -> usize {
fn fill(blocks: &mut [Block], text: &mut dyn FnMut(&str) -> Option<String>) -> usize {
let mut n = 0;
for b in blocks {
match b {
Block::Narrative { slot, text: t, .. } => {
if let Some(md) = text(slot) {
*t = Some(MarkdownText {
source: md,
origin: MarkdownOrigin::Llm,
from: None,
});
n += 1;
}
}
Block::Callout { body, .. } => n += fill(body, text),
_ => {}
}
}
n
}
self.pages
.values_mut()
.map(|p| fill(&mut p.blocks, &mut text))
.sum()
}
pub fn narrative_slots(&self) -> Vec<String> {
let mut out = Vec::new();
for p in self.pages.values() {
for b in &p.blocks {
if let Block::Narrative { slot, .. } = b {
out.push(slot.clone());
}
}
}
out.sort();
out.dedup();
out
}
pub fn check_links(&mut self) {
let broken = Linker::new(self).broken();
self.report.broken_links = broken;
}
pub fn to_json(&self) -> serde_json::Result<String> {
serde_json::to_string_pretty(self)
}
}