nornir 0.4.32

//! Whole-documentation "book" — assemble *every* markdown source in a repo
//! into one typst-rendered document (PDF / HTML / MD).
//!
//! Where [`super::export::export_repo`] renders a single file (the generated
//! `README.md`), the book gathers the repo's entire doc set:
//!
//!   1. every `*.md` under `.nornir/` (the editable sources — README, CHANGELOG,
//!      design notes, this crate's docs-generation reference, …);
//!   2. every other top-level `<repo>/*.md` (e.g. `plan.md`), *excluding* the
//!      generated managed artifacts (`README.md` / `CHANGELOG.md`) whose source
//!      already comes from `.nornir/`, so nothing is duplicated.
//!
//! Each file becomes a chapter. Marker sections (`<!-- nornir:gen:start:… -->`)
//! are expanded per file via [`super::sections`], so bench tables / dep-graphs
//! are fresh. The chapters are concatenated into one markdown string and handed
//! to the existing typst pipeline with the repo root mounted as the filesystem
//! root, so local images (`.nornir/assets/…`) embed.
//!
//! Everything goes through **typst** — no second rendering engine.
//!
//! Cargo feature: `docs-export`.

use std::path::{Path, PathBuf};

use anyhow::{Context, Result};

use super::export::{self, DocFormat, ExportMeta};
use super::layout::MANAGED_DOCS;
use super::sections::{rewrite_str, Ctx};

/// One assembled chapter of the book.
#[derive(Debug)]
pub struct Chapter {
    /// Source file the chapter came from.
    pub source: PathBuf,
    /// Display title (the file's own leading `# H1`, or derived from its name).
    pub title: String,
    /// Markdown body with marker sections already expanded.
    pub markdown: String,
}

/// Discover and assemble every doc source in `repo_root` into ordered chapters.
///
/// Order: `.nornir/README.md`, `.nornir/CHANGELOG.md`, then the remaining
/// `.nornir/*.md` alphabetically, then the non-generated top-level `*.md`
/// alphabetically.
pub fn collect_chapters(repo_root: &Path, ctx: &Ctx) -> Result<Vec<Chapter>> {
    let mut chapters = Vec::new();
    for path in discover_sources(repo_root) {
        let raw = std::fs::read_to_string(&path)
            .with_context(|| format!("read {}", path.display()))?;
        // Expand marker sections. A file that isn't a nornir source (no markers,
        // or a stray marker-looking line) must not sink the whole book — fall
        // back to its raw text on any rewrite error.
        let body = match rewrite_str(&raw, ctx) {
            Ok((filled, _)) => filled,
            Err(_) => raw,
        };
        // Resolve image paths so they embed regardless of which convention a
        // doc uses. The book mounts repo-root as the typst FS root, so image
        // paths must be ROOT-relative — but a `.nornir/*.md` file may reference
        // an asset SOURCE-relative (`assets/x.svg`, the markdown/web convention,
        // = `.nornir/assets/x.svg`) OR already root-relative (`.nornir/assets/x.svg`).
        // Try source-relative first, then root-relative, and emit whichever
        // exists as a root-relative path. Fixes nornir's `assets/…` refs without
        // breaking holger's `.nornir/assets/…` refs.
        let body = rewrite_image_paths(&body, &path, repo_root);
        let title = chapter_title(&path, &body);
        chapters.push(Chapter {
            source: path,
            title,
            markdown: body,
        });
    }
    Ok(chapters)
}

/// Rewrite each markdown image's relative path to a repo-root-relative path that
/// actually exists on disk: source-relative first (web semantics), then
/// root-relative (the as-written value). Absolute / `http(s):` / `data:` refs
/// and non-existent paths are left untouched.
fn rewrite_image_paths(body: &str, source: &Path, repo_root: &Path) -> String {
    let src_dir = source.parent().unwrap_or(repo_root);
    let mut out = String::with_capacity(body.len());
    let bytes = body.as_bytes();
    let mut i = 0;
    while i < body.len() {
        // Find the next image start `![`.
        if bytes[i] == b'!' && i + 1 < body.len() && bytes[i + 1] == b'[' {
            if let Some(close_alt) = body[i..].find("](") {
                let lp = i + close_alt + 2; // index just after "]("
                if let Some(rel_close) = body[lp..].find(')') {
                    let inner = &body[lp..lp + rel_close]; // path [+ optional "title"]
                    let (raw_path, title) = match inner.find(char::is_whitespace) {
                        Some(sp) => (&inner[..sp], &inner[sp..]),
                        None => (inner, ""),
                    };
                    let skip = raw_path.is_empty()
                        || raw_path.starts_with('/')
                        || raw_path.starts_with("http://")
                        || raw_path.starts_with("https://")
                        || raw_path.starts_with("data:");
                    let resolved = if skip {
                        None
                    } else {
                        let src_rel = src_dir.join(raw_path);
                        let root_rel = repo_root.join(raw_path);
                        if src_rel.is_file() {
                            src_rel
                                .strip_prefix(repo_root)
                                .ok()
                                .map(|p| p.to_string_lossy().replace('\\', "/"))
                        } else if root_rel.is_file() {
                            None // already correct as-written
                        } else {
                            None // unknown — leave it
                        }
                    };
                    if let Some(newp) = resolved {
                        out.push_str(&body[i..lp]); // through "]("
                        out.push_str(&newp);
                        out.push_str(title);
                        out.push(')');
                        i = lp + rel_close + 1;
                        continue;
                    }
                }
            }
        }
        let ch = body[i..].chars().next().unwrap();
        out.push(ch);
        i += ch.len_utf8();
    }
    out
}

/// Concatenate chapters into one markdown document. Each chapter that does not
/// already begin with a level-1 heading gets one prepended (so every chapter is
/// a top-level section / page break in the rendered output).
pub fn assemble_markdown(chapters: &[Chapter]) -> String {
    let mut out = String::new();
    for ch in chapters {
        if !starts_with_h1(&ch.markdown) {
            out.push_str("# ");
            out.push_str(&ch.title);
            out.push_str("\n\n");
        }
        out.push_str(ch.markdown.trim_end());
        out.push_str("\n\n");
    }
    out
}

/// Assemble + render the whole book for `repo_root` to `format`.
///
/// Returns the rendered bytes plus the list of source files that went into it
/// (in order), for reporting. `ctx` supplies the marker-render context
/// (repo/workspace roots + optional bench run).
pub fn build_book(
    repo_root: &Path,
    ctx: &Ctx,
    format: DocFormat,
) -> Result<(Vec<u8>, Vec<PathBuf>)> {
    let chapters = collect_chapters(repo_root, ctx)?;
    let sources: Vec<PathBuf> = chapters.iter().map(|c| c.source.clone()).collect();
    let md = assemble_markdown(&chapters);

    let (title, version) = read_meta(repo_root);
    // Auto-detect a cover/hero image under .nornir/assets/ — `<reponame>.<ext>`
    // or `cover.<ext>` — and put it on the book's title page. Repo-root-relative
    // so the mounted typst root resolves it.
    let cover_image = detect_cover_image(repo_root).unwrap_or_default();
    let meta = ExportMeta {
        title: format!("{title} — documentation"),
        version,
        generated: chrono::Utc::now().format("%Y-%m-%d").to_string(),
        cover_image,
    };
    let cache_dir = repo_root.join(".nornir/cache/images");
    // Mount repo root so local `.nornir/assets/…` images resolve and embed.
    let bytes = export::export(&md, &meta, format, Some(&cache_dir), Some(repo_root))?;
    Ok((bytes, sources))
}

/// Find a cover/hero image under `.nornir/assets/`: `<reponame>.<ext>` (e.g.
/// `nornir.webp`) or `cover.<ext>`, ext ∈ {svg,png,webp,jpg,jpeg}. Returns it
/// repo-root-relative (forward slashes) so the typst root mount resolves it.
fn detect_cover_image(repo_root: &Path) -> Option<String> {
    let assets = repo_root.join(".nornir/assets");
    let name = repo_root.file_name().and_then(|n| n.to_str()).unwrap_or("");
    let exts = ["svg", "png", "webp", "jpg", "jpeg"];
    let mut stems = Vec::new();
    if !name.is_empty() {
        stems.push(name.to_string());
    }
    stems.push("cover".to_string());
    for stem in stems {
        for ext in exts {
            let p = assets.join(format!("{stem}.{ext}"));
            if p.is_file() {
                return p
                    .strip_prefix(repo_root)
                    .ok()
                    .map(|r| r.to_string_lossy().replace('\\', "/"));
            }
        }
    }
    None
}

// ----- discovery -------------------------------------------------------------

fn discover_sources(repo_root: &Path) -> Vec<PathBuf> {
    let mut out = Vec::new();

    // .nornir/*.md — the editable sources.
    let nornir_dir = repo_root.join(".nornir");
    let mut nornir_md = list_md(&nornir_dir);
    // README first, CHANGELOG second, then the rest alphabetically.
    nornir_md.sort_by(|a, b| source_rank(a).cmp(&source_rank(b)).then_with(|| a.cmp(b)));
    out.extend(nornir_md);

    // <repo>/*.md, minus the generated managed artifacts (their source is in
    // .nornir/ and is already included above) and minus non-doc scratch /
    // agent-instruction files (see `is_book_chapter`).
    let mut root_md: Vec<PathBuf> = list_md(repo_root)
        .into_iter()
        .filter(|p| {
            let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("");
            !MANAGED_DOCS.contains(&name) && is_book_chapter(name)
        })
        .collect();
    root_md.sort();
    out.extend(root_md);

    out
}

/// Whether a top-level `<repo>/<name>.md` belongs in the rendered doc-book.
///
/// Discovery is otherwise "every top-level `*.md`", which sweeps in files that
/// are not documentation: `CLAUDE.md` (agent instructions) and `*-inbox.md`
/// scratch pads. These are skipped by convention so the book is the project's
/// actual docs, not its working notes. (`.nornir/*.md` sources are always
/// included — that directory is nornir's curated namespace.)
fn is_book_chapter(name: &str) -> bool {
    let lower = name.to_ascii_lowercase();
    if lower == "claude.md" {
        return false;
    }
    // `*-inbox.md` / `*_inbox.md` and a bare `inbox.md`.
    if let Some(stem) = lower.strip_suffix(".md") {
        if stem == "inbox" || stem.ends_with("-inbox") || stem.ends_with("_inbox") {
            return false;
        }
    }
    true
}

/// Sort key so README.md sorts first, CHANGELOG.md second, everything else after.
fn source_rank(p: &Path) -> u8 {
    match p.file_name().and_then(|n| n.to_str()) {
        Some("README.md") => 0,
        Some("CHANGELOG.md") => 1,
        _ => 2,
    }
}

/// Top-level `*.md` files in `dir` (non-recursive), as sorted absolute paths.
fn list_md(dir: &Path) -> Vec<PathBuf> {
    let mut v = Vec::new();
    let Ok(rd) = std::fs::read_dir(dir) else {
        return v;
    };
    for entry in rd.flatten() {
        let path = entry.path();
        if path.is_file()
            && path
                .extension()
                .and_then(|e| e.to_str())
                .map(|e| e.eq_ignore_ascii_case("md"))
                .unwrap_or(false)
        {
            v.push(path);
        }
    }
    v.sort();
    v
}

// ----- chapter helpers -------------------------------------------------------

fn starts_with_h1(md: &str) -> bool {
    md.lines()
        .map(str::trim_start)
        .find(|l| !l.is_empty())
        .map(|l| l.starts_with("# "))
        .unwrap_or(false)
}

/// A chapter's title: the file's own leading `# H1` if present, else a name
/// derived from the file stem (`docs-generation` → `Docs Generation`).
fn chapter_title(path: &Path, body: &str) -> String {
    if let Some(line) = body.lines().map(str::trim_start).find(|l| !l.is_empty()) {
        if let Some(h) = line.strip_prefix("# ") {
            return h.trim().to_string();
        }
    }
    let stem = path
        .file_stem()
        .and_then(|s| s.to_str())
        .unwrap_or("untitled");
    titleize(stem)
}

fn titleize(stem: &str) -> String {
    stem.split(['-', '_'])
        .filter(|w| !w.is_empty())
        .map(|w| {
            let mut c = w.chars();
            match c.next() {
                Some(first) => first.to_uppercase().collect::<String>() + c.as_str(),
                None => String::new(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Read `(name, version)` from the repo's `Cargo.toml`; falls back to the
/// directory name and [`resolve_version`].
fn read_meta(repo_root: &Path) -> (String, String) {
    let dir_name = repo_root
        .file_name()
        .and_then(|n| n.to_str())
        .unwrap_or("project")
        .to_string();
    let name = std::fs::read_to_string(repo_root.join("Cargo.toml"))
        .ok()
        .and_then(|c| toml::from_str::<toml::Value>(&c).ok())
        .and_then(|p| {
            p.get("package")
                .or_else(|| p.get("workspace").and_then(|w| w.get("package")))
                .and_then(|p| p.get("name"))
                .and_then(|v| v.as_str())
                .map(str::to_string)
        })
        .unwrap_or(dir_name);
    (name, resolve_version(repo_root))
}

/// Resolve a display version for a repo from its root `Cargo.toml`.
///
/// Order: `[package].version`, then `[workspace.package].version`. A **virtual
/// workspace** (e.g. holger, znippy) declares neither, so we fall back to the
/// *modal* version across its members — the version most of the crates share is
/// the workspace's release version. Returns `0.0.0` only when nothing resolves.
pub fn resolve_version(repo_root: &Path) -> String {
    let Ok(content) = std::fs::read_to_string(repo_root.join("Cargo.toml")) else {
        return "0.0.0".to_string();
    };
    let Ok(parsed) = toml::from_str::<toml::Value>(&content) else {
        return "0.0.0".to_string();
    };
    // Direct package / workspace-package version.
    if let Some(v) = parsed
        .get("package")
        .or_else(|| parsed.get("workspace").and_then(|w| w.get("package")))
        .and_then(|p| p.get("version"))
        .and_then(|v| v.as_str())
    {
        return v.to_string();
    }
    // Virtual workspace: take the modal member version.
    let ws_pkg_version = parsed
        .get("workspace")
        .and_then(|w| w.get("package"))
        .and_then(|p| p.get("version"))
        .and_then(|v| v.as_str());
    let members = parsed
        .get("workspace")
        .and_then(|w| w.get("members"))
        .and_then(|m| m.as_array())
        .map(|a| a.iter().filter_map(|v| v.as_str()).collect::<Vec<_>>())
        .unwrap_or_default();
    modal_member_version(repo_root, &members, ws_pkg_version).unwrap_or_else(|| "0.0.0".into())
}

/// The most frequent concrete version across workspace `members` (each a path,
/// possibly a trailing-`/*` glob). `version.workspace = true` resolves to
/// `ws_pkg_version`. Ties break toward the version seen first in member order.
fn modal_member_version(
    repo_root: &Path,
    members: &[&str],
    ws_pkg_version: Option<&str>,
) -> Option<String> {
    let mut counts: Vec<(String, usize)> = Vec::new();
    let mut bump = |v: String| {
        if let Some(e) = counts.iter_mut().find(|(k, _)| *k == v) {
            e.1 += 1;
        } else {
            counts.push((v, 1));
        }
    };
    for m in members {
        let dirs = if let Some(prefix) = m.strip_suffix("/*") {
            // Expand a simple trailing glob one level deep.
            std::fs::read_dir(repo_root.join(prefix))
                .map(|rd| {
                    rd.flatten()
                        .map(|e| e.path())
                        .filter(|p| p.is_dir())
                        .collect::<Vec<_>>()
                })
                .unwrap_or_default()
        } else {
            vec![repo_root.join(m)]
        };
        for dir in dirs {
            let Ok(c) = std::fs::read_to_string(dir.join("Cargo.toml")) else {
                continue;
            };
            let Ok(p) = toml::from_str::<toml::Value>(&c) else {
                continue;
            };
            let ver = p.get("package").and_then(|pkg| pkg.get("version"));
            let resolved = match ver {
                Some(toml::Value::String(s)) => Some(s.clone()),
                // `version.workspace = true`
                Some(toml::Value::Table(t)) if t.get("workspace").is_some() => {
                    ws_pkg_version.map(str::to_string)
                }
                _ => None,
            };
            if let Some(v) = resolved {
                bump(v);
            }
        }
    }
    counts.into_iter().max_by_key(|(_, n)| *n).map(|(v, _)| v)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn write(p: &Path, s: &str) {
        std::fs::create_dir_all(p.parent().unwrap()).unwrap();
        std::fs::write(p, s).unwrap();
    }

    #[test]
    fn discovers_and_orders_sources() {
        let t = tempfile::tempdir().unwrap();
        let root = t.path();
        write(&root.join(".nornir/README.md"), "# Readme\n\nbody\n");
        write(&root.join(".nornir/CHANGELOG.md"), "# Changelog\n");
        write(&root.join(".nornir/design.md"), "# Design\n");
        write(&root.join("plan.md"), "# Plan\n");
        // Generated managed artifact at the root — must be skipped (dedup).
        write(&root.join("README.md"), "generated\n");
        // Non-doc files — must be skipped by the chapter convention.
        write(&root.join("CLAUDE.md"), "agent instructions\n");
        write(&root.join("znippy-inbox.md"), "scratch\n");

        let got: Vec<String> = discover_sources(root)
            .iter()
            .map(|p| {
                let parent = p.parent().unwrap().file_name().unwrap().to_str().unwrap();
                let name = p.file_name().unwrap().to_str().unwrap();
                format!("{parent}/{name}")
            })
            .collect();
        let root_name = root.file_name().unwrap().to_str().unwrap();
        assert_eq!(
            got,
            vec![
                ".nornir/README.md".to_string(),
                ".nornir/CHANGELOG.md".to_string(),
                ".nornir/design.md".to_string(),
                // top-level README.md excluded; plan.md kept
                format!("{root_name}/plan.md"),
            ]
        );
    }

    #[test]
    fn is_book_chapter_skips_non_docs() {
        assert!(!is_book_chapter("CLAUDE.md"));
        assert!(!is_book_chapter("claude.md"));
        assert!(!is_book_chapter("znippy-inbox.md"));
        assert!(!is_book_chapter("inbox.md"));
        assert!(!is_book_chapter("notes_inbox.md"));
        // Real docs stay.
        assert!(is_book_chapter("WORKSPACE.md"));
        assert!(is_book_chapter("plan.md"));
        assert!(is_book_chapter("design.md"));
    }

    #[test]
    fn assemble_prepends_h1_only_when_missing() {
        let chapters = vec![
            Chapter {
                source: "a.md".into(),
                title: "Alpha".into(),
                markdown: "# Alpha\n\nhas its own h1\n".into(),
            },
            Chapter {
                source: "b.md".into(),
                title: "Beta".into(),
                markdown: "## sub only\n\nno h1\n".into(),
            },
        ];
        let md = assemble_markdown(&chapters);
        // First chapter keeps its single H1 (not doubled).
        assert_eq!(md.matches("# Alpha").count(), 1);
        // Second chapter gets a synthesized H1 from its title.
        assert!(md.contains("# Beta"));
        assert!(md.contains("## sub only"));
    }

    #[test]
    fn resolve_version_prefers_package_then_modal_member() {
        // Concrete [package].version wins outright.
        let t = tempfile::tempdir().unwrap();
        write(&t.path().join("Cargo.toml"), "[package]\nname='x'\nversion='1.2.3'\n");
        assert_eq!(resolve_version(t.path()), "1.2.3");

        // Virtual workspace: modal member version (3×0.9.0 vs 1×0.1.0).
        let w = tempfile::tempdir().unwrap();
        write(
            &w.path().join("Cargo.toml"),
            "[workspace]\nmembers=['a','b','c','d']\n",
        );
        for (m, v) in [("a", "0.9.0"), ("b", "0.9.0"), ("c", "0.9.0"), ("d", "0.1.0")] {
            write(
                &w.path().join(m).join("Cargo.toml"),
                &format!("[package]\nname='{m}'\nversion='{v}'\n"),
            );
        }
        assert_eq!(resolve_version(w.path()), "0.9.0");

        // Nothing resolvable → 0.0.0.
        let e = tempfile::tempdir().unwrap();
        write(&e.path().join("Cargo.toml"), "[workspace]\nmembers=[]\n");
        assert_eq!(resolve_version(e.path()), "0.0.0");
    }

    #[test]
    fn titleize_basic() {
        assert_eq!(titleize("docs-generation"), "Docs Generation");
        assert_eq!(titleize("design_notes"), "Design Notes");
    }

    /// Regression: rendering the book for a repo whose key matches the running
    /// self-repo (`nornir`) but whose checkout lives in a differently-named dir
    /// must land the PDF at the *configured* `<repo>/docs/book.pdf` — the real
    /// path — assembling the repo's real `.nornir/*.md`, NOT an empty stub under
    /// a temp dir.
    ///
    /// The historical bug: `[repo.nornir] path = "nornir-orch"` was ignored, so
    /// `docs book nornir` resolved by-name to the wrong (or absent) checkout and
    /// wrote an empty ~16KB `book.pdf`. This drives the same seam end-to-end:
    /// `repo_dir_for` (override) → `build_book` (real sources) →
    /// `RepoLayout::export_path` (real `docs/`), asserting a non-trivial PDF at
    /// the real path and explicitly NOT under `/tmp`.
    #[cfg(feature = "docs-export")]
    #[test]
    fn self_repo_book_lands_at_real_docs_path_not_tmp() {
        use crate::config::{Nornir, Repo};
        use crate::docs::RepoLayout;

        let ws = tempfile::tempdir().unwrap();
        let ws_root = ws.path();
        // The self-repo's *key* is `nornir`, but its checkout dir is named
        // `nornir-orch` — exactly the dogfooding case. By-name resolution would
        // miss it; the `path` override must redirect to it.
        let repo_dir = ws_root.join("nornir-orch");
        write(&repo_dir.join("Cargo.toml"), "[package]\nname='nornir'\nversion='9.9.9'\n");
        // Several real `.nornir/*.md` sources, each with real prose, so the
        // assembled book is non-trivial (many pages) rather than an empty stub.
        let body = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. \
            Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \
            Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.\n\n"
            .repeat(40);
        for (name, title) in [
            ("README.md", "Nornir"),
            ("design.md", "Design"),
            ("guide.md", "Guide"),
            ("bencher.md", "Bencher"),
            ("warehouse.md", "Warehouse"),
        ] {
            write(
                &repo_dir.join(format!(".nornir/{name}")),
                &format!("# {title}\n\n{body}"),
            );
        }

        let mut nornir = Nornir::default();
        nornir.repo.insert(
            "nornir".into(),
            Repo { path: "nornir-orch".into(), ..Default::default() },
        );

        // Resolve through the same seam the CLI handler uses.
        let resolved = nornir.repo_dir_for(ws_root, "nornir");
        assert_eq!(resolved, repo_dir, "override must redirect `nornir` → nornir-orch dir");

        // Build the book PDF from the resolved (real) checkout and write it to
        // the repo's `docs/` via the layout — the exact CLI write path.
        let ctx = Ctx::new(&resolved, ws_root, None);
        let format = DocFormat::parse("pdf").unwrap();
        let (bytes, sources) = build_book(&resolved, &ctx, format).unwrap();

        let layout = RepoLayout::new(&resolved);
        let out = layout.export_path("book", format.extension());
        std::fs::create_dir_all(out.parent().unwrap()).unwrap();
        std::fs::write(&out, &bytes).unwrap();

        // Lands at the configured repo's real docs/book.pdf — under the
        // resolved repo root, NOT at the global self-stub the bug produced
        // (`<temp_dir>/nornir/docs/book.pdf`).
        assert_eq!(out, repo_dir.join("docs/book.pdf"));
        assert!(
            out.starts_with(&repo_dir),
            "book must land under the resolved repo root {}, got {}",
            repo_dir.display(),
            out.display(),
        );
        let self_stub = std::env::temp_dir().join("nornir/docs/book.pdf");
        assert_ne!(out, self_stub, "book must not be written to the global self-stub");
        // Assembled from the real multi-source set, not an empty stub.
        assert!(sources.len() > 1, "expected >1 source, got {}", sources.len());
        assert!(out.is_file(), "book.pdf must exist at {}", out.display());
        let size = std::fs::metadata(&out).unwrap().len();

        // Baseline: the same pipeline over an *empty* repo (no `.nornir/*.md`)
        // is the "empty-stub" the bug produced. The real book must dwarf it.
        let empty = tempfile::tempdir().unwrap();
        write(&empty.path().join("Cargo.toml"), "[package]\nname='nornir'\nversion='9.9.9'\n");
        let empty_ctx = Ctx::new(empty.path(), empty.path(), None);
        let (empty_bytes, empty_sources) = build_book(empty.path(), &empty_ctx, format).unwrap();
        assert!(empty_sources.is_empty(), "empty repo must yield no sources");
        assert!(
            size as usize > empty_bytes.len() * 2,
            "book.pdf ({size} bytes) must dwarf the empty stub ({} bytes) — \
             empty-stub regression",
            empty_bytes.len(),
        );
        assert!(
            size > 50_000,
            "book.pdf must be non-trivial, got {size} bytes — empty-stub regression",
        );
    }
}