nordisk/edda

crates/nornir-docgen/src/lib.rs

//! # nornir-docgen — the warehouse-free doc-book + mashup ASSEMBLY half
//!
//! nornir owns generated docs: README.md, CLAUDE.md, CHANGELOG.md. Files (or
//! sections) carrying the marker `<!-- nornir:generated -->` are rewritten in
//! full on each release from the per-repo TOML, the latest `BenchRun` and the
//! bench history. THIS crate is that assembly machinery, lifted verbatim out of
//! nornir's `docs/` subsystem so it releases on its own cadence:
//!
//! - [`sections`] — the `nornir:gen:*` marker engine + every section renderer
//!   (bench tables, the mashup, coverage, depgraph, capabilities, …).
//! - [`layout`] — the managed-docs set, render/check drivers, repo init.
//! - [`bench_status`] — the honest bench-status card (+ the harness probe whose
//!   lstat semantics deliberately never follow symlinks).
//! - [`test_inventory`] — the syn-based `#[test]`/`#[bench]` inventory.
//! - [`hooks`] — the pre-commit hook installer (markdown-only render).
//! - [`pages`] — Codeberg Pages orphan-branch staging (pure gix).
//! - `export` feature: [`export`] (the [`nornir_docbook`] render engine,
//!   re-exported so `book` keeps its seam), [`svg`] (typst depgraph/bar-chart
//!   SVG), [`book`], [`apidoc`], [`ai_context`].
//!
//! ## What stays in nornir
//!
//! Everything that reads the Iceberg warehouse — `docs::warehouse` (the
//! `doc_exports` table), `docs::search` (the tantivy index), `docs::release_book`,
//! the Docs gRPC service, MCP tools and CLI verbs — plus byte-stable
//! `nornir::docs::*` re-export shims over this crate, so every existing call
//! site resolves unchanged.
//!
//! ## The one seam
//!
//! The `depgraph` section's network half (clone missing sibling path-dep repos
//! before `cargo metadata`) is injected via [`Ctx::path_dep_cloner`] — nornir
//! passes its `security::clone_missing_path_dep_siblings`; the default is the
//! pure symlink materialization only. That closure is the ONLY nornir coupling
//! this crate shed on the way out.

/// ★ THE `nornir:claim:` GATE — falsifiable claims a `.nornir/*.md` source
/// carries, evaluated against the working tree by every render entry point in
/// this crate BEFORE any assembly.
///
/// It lives HERE, in the engine, and not in a caller, because callers are plural:
/// nornir goes through its `docs::*` re-exports and dwarves calls [`layout`] and
/// [`book`] directly. Gating a wrapper in one caller gates one road; the other
/// road was measured on 2026-08-27 rendering a document whose claim was false
/// and stamping it DO NOT EDIT with exit 0. See [`claims`] for that measurement.
pub mod claims;
pub use claims::{Claim, ClaimKind, gate_repo as gate_doc_claims};

pub mod sections;
pub use sections::{Ctx, FileReport, assemble_file, check_file};

pub mod bench_status;
pub use bench_status::{
    HarnessProbe, PREVIEW_TOKEN, is_preview, probe_harness, suspect_reasons, suspects,
};

pub mod test_inventory;
pub use test_inventory::{TestInventory, scan as scan_tests, scan_opts as scan_tests_opts};

pub mod hooks;
pub use hooks::{InstallReport, install_hooks, pre_commit_script};

pub mod layout;
pub use layout::{
    DocCheckRow, DocsRenderCfg, MANAGED_DOCS, RenderReport, RepoLayout,
    check_all as render_check_all, check_all_status, check_doc as render_check_doc, check_outcome,
    init_repo, render_all, render_doc, render_sources_in_place,
};

pub mod pages;
pub use pages::{PAGES_BRANCH, PagesBuild, force_push_cmd, index_html, stage_pages_branch};

/// The pure render engine (assembled markdown → typst → PDF/HTML/per-page SVG)
/// — [`nornir_docbook::export`] re-exported verbatim, so [`book`] keeps its
/// `super::export` seam and consumers get one coherent `nornir_docgen` surface.
#[cfg(feature = "export")]
pub mod export {
    pub use nornir_docbook::export::*;
}
#[cfg(feature = "export")]
pub use export::{DocFormat, ExportMeta, export as export_bytes, export_repo};

#[cfg(feature = "export")]
pub mod svg;

#[cfg(feature = "export")]
pub mod book;
#[cfg(feature = "export")]
pub use book::{
    BookRoute, BuiltBook, Chapter, build_book, build_book_svg_pages, build_books, classify,
    collect_chapters, default_routing, load_routing, resolve_version,
};

#[cfg(feature = "export")]
pub mod site;
#[cfg(feature = "export")]
pub use site::{SiteFile, build_site};

#[cfg(feature = "export")]
pub mod apidoc;

#[cfg(feature = "export")]
pub mod ai_context;
#[cfg(feature = "export")]
pub use ai_context::{
    AiContextOpts, AiContextOutput, BuildStats, GenMode, build as build_ai_context,
};