rto_render/

obsidian.rs

//! The Obsidian-vault renderer: each graph node becomes a markdown note whose
//! edges are `[[wikilinks]]`, so the provenance-tagged graph is browsable in
//! Obsidian's graph view. Notes carry frontmatter `tags` (`roteiro/kind/*`,
//! `roteiro/lang/*`, `roteiro/status/*`) so the graph is colourable/filterable —
//! edge provenance is shown per-link in the body — surface the node's text as the
//! knowledge base, show an ADR's status, and (when the repository's web host is
//! known) a clickable **Source** link to the file.
//!
//! That text is the node's captured `meta.content` (a doc comment, PDF or image
//! text) *except* where the caller supplies a full `body` — which it does for
//! prose documents, because `meta.content` is an embedding budget and a note
//! rendered from it is the document capped at 1500 characters and collapsed onto
//! one line. See [`note_body`].
//!
//! A generated `_Home` note is the overview: what was
//! scanned, counts by kind, provenance breakdown, ADR statuses, intent-debt (with
//! the files it is densest in), an inventory of secret-**named** config keys and
//! their redaction state, and the most depended-on symbols by directed call
//! fan-in.
//! Built from the same [`Explanation`] the query surface returns, so the vault
//! and the CLI agree.

use std::fmt::Write as _;

use rto_graph::Explanation;

/// Filename of the generated overview note (sorts first in the file list).
pub const HOME_NOTE: &str = "_Home.md";

/// A rendered vault note: its filename (with `.md`) and markdown content.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VaultNote {
    /// Filename including the `.md` extension.
    pub filename: String,
    /// Markdown content.
    pub content: String,
}

/// Map a node key to a filesystem- and wikilink-safe note stem that is **unique
/// per key even after case folding**.
///
/// A name is a lowercased, readable *hint* slugged from the key, followed by an
/// unconditional 64-bit FNV-1a hash of the whole, exact key written as 16 hex
/// digits — `<hint>-<16 hex digits>`. Characters outside `[a-z0-9._-]` collapse
/// to a single `-` in the hint; the hash carries everything the hint threw away.
///
/// **The hash is the unconditional part, not the hint.** A key of nothing but
/// separators slugs to an empty hint, and the name is then the bare 16 hex
/// digits — no hint, and no `-` to join it to. The two forms cannot be confused
/// for one another, which is what makes the exception safe rather than a second
/// naming rule: a hinted name is at least 18 characters and contains a `-`,
/// and a bare one is exactly 16 and contains none. That is argued again at the
/// branch itself, and asserted by
/// `every_name_carries_the_hash_however_short_the_key`.
///
/// # Why the hash is unconditional (issue #574)
///
/// It used to be applied only when the slug overran the filename limit, and the
/// slug alone was lossy twice over. Measured on this repository — 8,239 nodes
/// rendering to 8,135 notes, 104 of them silently overwritten:
///
/// | mechanism | lost | where |
/// | --- | --- | --- |
/// | every character outside the safe set becomes `-` and runs collapse, so `…cytoscape.min.js#$a` and `…cytoscape.min.js#a` are one name | 9 | everywhere |
/// | macOS and Windows fold filename case, so `…#A` and `…#a` are two *names* but one *file* | 95 | macOS, Windows |
///
/// The second mechanism is the trap. A lossless-but-case-sensitive encoding
/// fixes the 9, verifies clean on Linux CI, and still loses 95 notes on a Mac.
/// So the requirement is stated after folding:
///
/// ```text
/// lower(note_name(k1)) == lower(note_name(k2))  implies  k1 == k2
/// ```
///
/// This matters more than lossiness in a cache would, because the note names are
/// the vault's **only** stable interface: `reset_vault_dir` deletes and rebuilds
/// the whole directory on every render, so the one thing that survives a render
/// is a user's own note *outside* the vault linking in by name (issue #442).
///
/// # The trade taken
///
/// Two decisions, and what each bought:
///
/// **The hint is lowercased rather than case-preserved.** Case-preserving would
/// also satisfy the requirement — the hash differs for `#A` and `#a`, so the two
/// names differ in their suffix and stay distinct under folding. It was rejected
/// because lowercasing makes `note_name(k) == note_name(k).to_lowercase()` an
/// invariant of the function, and *that* collapses the folded property into the
/// literal one: there is then no way to write a version of this that is green on
/// Linux and lossy on macOS, which is the defect shape this repository keeps
/// finding. The cost is that `parseHTTPHeader` reads as `parsehttpheader`. That
/// is affordable precisely because the hint is a hint — once a 17-character
/// suffix is mandatory the name is not something anyone types from memory, so
/// its job is to be recognisable in a file list, not to be transcribed.
///
/// **Readability was spent, deliberately.** Every name grows by 17 characters and
/// hand-writing a link now needs Obsidian's autocomplete. The alternatives that
/// keep names short — hashing only the keys observed to collide — make the *set*
/// of collisions platform-dependent, so one key would get one filename on macOS
/// and another on Linux and a synced vault would churn. A name that is uglier
/// everywhere beats a name that is different per platform.
///
/// The mapping is not reversible (the hint is lossy and the hash is one-way), but
/// it does not need to be: every note's frontmatter carries `key:` verbatim, so
/// name → key is recoverable from the vault itself, which is the direction a
/// reader actually needs.
///
/// # What "unique" rests on
///
/// Equal names imply equal hashes, not equal keys — this is a 64-bit hash, not a
/// proof. Over this repository's 8,239 keys there is no collision, and the
/// birthday bound at that size is about 2e-12. Should one ever occur it is
/// *reported*, not silent: `NoteNames` in the render path claims every filename
/// case-insensitively and warns on a repeat. What is proved outright is the
/// folding half — the output is lowercase by construction, so case folding is the
/// identity on it.
#[must_use]
pub fn note_name(key: &str) -> String {
    // Keep the whole stem well under the 255-byte filename limit (leaving room
    // for ".md"). The hint is ASCII, so byte length equals char count and slicing
    // is safe.
    const MAX: usize = 200;
    // '-' plus the 16 hex digits of the hash.
    const SUFFIX: usize = 17;
    const HINT: usize = MAX - SUFFIX;

    let mut hint = String::with_capacity(key.len());
    let mut prev_dash = false;
    for c in key.chars() {
        if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
            hint.push(c.to_ascii_lowercase());
            prev_dash = false;
        } else if !prev_dash {
            hint.push('-');
            prev_dash = true;
        }
    }
    let hint = hint.trim_matches('-');
    // Truncation is only ever cosmetic now: the hash, not the hint, is what keeps
    // a 300-character grouped `use` distinct from its neighbour.
    let hint = hint[..hint.len().min(HINT)].trim_end_matches('-');
    let hash = fnv1a64(key.as_bytes());
    if hint.is_empty() {
        // A key of nothing but separators. Bare hex, and it cannot be confused
        // with a hinted name: those are `<hint>-<16 hex>`, so at least 18
        // characters, and this is exactly 16 with no `-` in it.
        format!("{hash:016x}")
    } else {
        format!("{hint}-{hash:016x}")
    }
}

/// FNV-1a (64-bit) — a dependency-free, deterministic hash carrying everything
/// [`note_name`]'s hint discards. No cryptographic properties needed: nothing
/// here defends against a chosen collision, only against an accidental one.
///
/// 64 bits rather than fewer because the cost of a collision is exactly the
/// defect this suffix exists to fix — a note silently overwritten. At 8k keys a
/// 32-bit hash collides about 0.8% of the time and a 48-bit one about 1e-5;
/// 64 bits is 2e-12, and stays under 1e-10 for a workspace vault an order of
/// magnitude larger.
fn fnv1a64(bytes: &[u8]) -> u64 {
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
    for &b in bytes {
        hash ^= u64::from(b);
        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
    }
    hash
}

/// Emit `value` as a YAML **double-quoted** scalar, `"`-delimited and escaped so
/// it parses back to exactly `value`.
///
/// The one escaping rule for this module's frontmatter. It exists because the
/// three hand-rolled variants it replaced disagreed with each other — `key:` and
/// `project:` turned a `"` into an apostrophe, and `path:` escaped nothing — and
/// two of the three could emit YAML that does not mean what it says:
///
/// | value | was emitted | parsed back as |
/// | --- | --- | --- |
/// | `foo\bar` | `"foo\bar"` | `foo<BS>ar` — `\b` is YAML's **backspace** escape |
/// | `foo\dir` | `"foo\dir"` | *parse error* — `\d` is not a YAML escape |
/// | `say"hi".rs` | `"say"hi".rs"` | *parse error* — the scalar ends at the `"` |
///
/// The first is the dangerous one: seven characters silently become six, and
/// nothing anywhere reports it. The other two cost the reader every property on
/// the note, because Obsidian parses this block as the note's properties and a
/// block that does not parse yields no properties at all rather than an error.
///
/// All three inputs are legal path components on Linux and macOS. None occurs in
/// this repository today, so this is a latent defect rather than an observed one.
///
/// Escapes, per YAML 1.2 §7.3.1: the two structural characters `\` and `"`, then
/// anything a parser is not obliged to accept literally — C0 controls, `DEL`, the
/// C1 range, and the three separators (`U+2028`, `U+2029`, `U+FEFF`) that some
/// parsers treat as line breaks. Short escapes where YAML defines one, so the
/// common cases stay readable, and `\uXXXX` otherwise.
fn yaml_double_quoted(value: &str) -> String {
    let mut out = String::with_capacity(value.len() + 2);
    out.push('"');
    for ch in value.chars() {
        match ch {
            '\\' => out.push_str(r"\\"),
            '"' => out.push_str("\\\""),
            '\n' => out.push_str(r"\n"),
            '\r' => out.push_str(r"\r"),
            '\t' => out.push_str(r"\t"),
            '\u{0}' => out.push_str(r"\0"),
            '\u{7}' => out.push_str(r"\a"),
            '\u{8}' => out.push_str(r"\b"),
            '\u{b}' => out.push_str(r"\v"),
            '\u{c}' => out.push_str(r"\f"),
            '\u{1b}' => out.push_str(r"\e"),
            // Everything else a YAML parser may reject or fold: the rest of C0,
            // DEL, the C1 range, and the separators that can read as line breaks.
            c if (c < ' ')
                || c == '\u{7f}'
                || ('\u{80}'..='\u{9f}').contains(&c)
                || matches!(c, '\u{2028}' | '\u{2029}' | '\u{feff}') =>
            {
                let _ = write!(out, "\\u{:04x}", c as u32);
            }
            c => out.push(c),
        }
    }
    out.push('"');
    out
}

/// Emit `value` in YAML **plain** (unquoted) style when that round-trips, and as
/// [`yaml_double_quoted`] when it would not.
///
/// For the frontmatter fields that are written bare today — `kind`, `lang`,
/// `status`. Those are constrained by *today's* producers (an ADR's status is
/// validated against the house states; kinds and languages come from extraction),
/// but `roteiro load` installs a caller-supplied graph artifact whose nodes carry
/// whatever JSON they carry, so "the producer is careful" is not a property this
/// renderer can rely on. A `status:` of `Accepted: superseded by 0012` emitted
/// bare is a parse error, and `Accepted # pending` silently truncates to
/// `Accepted`.
///
/// Escalating only when needed is what keeps the bytes of an existing vault
/// unchanged — every `kind`, `lang` and `status` in this repository is plain-safe
/// and stays bare. [`is_plain_safe`] is deliberately stricter than YAML's plain
/// grammar for the same reason it is safe: a value it rejects is merely quoted.
fn yaml_scalar(value: &str) -> String {
    if is_plain_safe(value) {
        value.to_owned()
    } else {
        yaml_double_quoted(value)
    }
}

/// Whether `value` can be written as a bare YAML scalar and read back unchanged.
///
/// A conservative allowlist rather than YAML's actual plain-scalar grammar, which
/// is subtle enough (indicator characters, `: ` and ` #` only in some positions,
/// leading and trailing space, implicit typing) that implementing it is how the
/// bug this replaces gets written a second time. Getting this wrong in the
/// strict direction costs a pair of quotation marks; getting it wrong in the
/// permissive direction costs the note's properties.
///
/// So: a leading ASCII letter, then letters, digits, `_`, `-`, `.` and `/` — which
/// covers every kind, language and status this renderer emits — and never a word
/// YAML resolves to a boolean or null. That last exclusion is not hypothetical:
/// `no` is the ISO 639-1 code for Norwegian, and YAML 1.1 parsers read a bare `no`
/// as `false`.
fn is_plain_safe(value: &str) -> bool {
    const NOT_STRINGS: [&str; 11] = [
        "true", "false", "yes", "no", "on", "off", "null", "nil", "none", "y", "n",
    ];
    !value.is_empty()
        && value.starts_with(|c: char| c.is_ascii_alphabetic())
        && value
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.' | '/'))
        && !NOT_STRINGS.contains(&value.to_ascii_lowercase().as_str())
}

/// Which vault a note is being rendered into: a single project's, or one member
/// of a **workspace** vault spanning several repositories.
///
/// This is the whole of the workspace-vault naming rule, in one place. Node keys
/// are **repository-relative** (`file:README.md` names no repo), so every member
/// of a workspace produces the same note name for its `README.md` and one would
/// silently overwrite the rest. Qualifying the key with its project fixes that.
///
/// [`VaultScope::PROJECT`] (`project: None`) is not a degenerate case but the
/// contract: it makes every name in this module reduce to exactly [`note_name`]
/// of the bare key, with nothing qualified and no `project:` frontmatter.
///
/// That reduction is *still* the promise; what it no longer implies is stability
/// against `main`. #570 could say "a single-project vault's names do not move",
/// because the only thing moving them would have been workspace qualification.
/// #574 moves them all, on purpose: the old names were not injective under
/// filename case folding and the vault lost 104 notes to that. The promise here
/// was always about **this axis** — turning workspace mode on must not rename a
/// project's notes — and it holds unchanged. See [`note_name`] for the rename and
/// what it bought.
#[derive(Debug, Clone, Copy)]
pub struct VaultScope<'a> {
    /// The member project this note belongs to, qualifying its name as
    /// `<project>::<key>` — the same form ADR-0009's cross-repo links already use.
    /// `None` ⇒ a single-project vault, and names are unqualified exactly as
    /// before.
    pub project: Option<&'a str>,
    /// The workspace's member project names. An external-ref placeholder whose
    /// target names one of these is a cross-repo edge the vault can actually
    /// follow, so it is rendered as a link straight to that member's note. Empty
    /// for a single-project vault.
    pub members: &'a std::collections::BTreeSet<String>,
}

/// The empty member set backing [`VaultScope::PROJECT`] — a single-project vault
/// has no other members to resolve a cross-repo reference against.
static NO_MEMBERS: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();

impl VaultScope<'_> {
    /// A single-project vault: names are unqualified, and no cross-repo reference
    /// resolves. Every name this produces is byte-identical to [`note_name`] of
    /// the bare key — see the type's documentation for why that reduction is
    /// load-bearing, and for what it does *not* promise.
    pub const PROJECT: Self = Self {
        project: None,
        members: &NO_MEMBERS,
    };
}

impl Default for VaultScope<'_> {
    fn default() -> Self {
        Self::PROJECT
    }
}

impl VaultScope<'_> {
    /// Whether an external-ref placeholder `key` is one this vault resolves for
    /// itself — its target names a member, so every edge to it points at the real
    /// note and the placeholder need not be rendered at all.
    ///
    /// The single rule behind both halves of that: [`link_target`] redirects
    /// exactly the keys this accepts, and the caller skips writing exactly the
    /// notes this accepts. They cannot disagree.
    #[must_use]
    pub fn redirects_external_ref(&self, key: &str) -> bool {
        key.strip_prefix("extref:")
            .and_then(rto_graph::parse_qualified)
            .is_some_and(|(project, _)| self.members.contains(project))
    }
}

/// The note name for a node `key` owned by `scope`'s project.
///
/// In a single-project vault (`scope.project == None`) this *is* [`note_name`].
/// In a workspace vault it is [`note_name`] of the project-qualified key
/// `<project>::<key>` — reusing ADR-0009's qualified form rather than inventing a
/// second one, which is what lets a cross-repo external-ref target (already
/// stored qualified) map to its note by the very same call.
#[must_use]
pub fn scoped_note_name(scope: &VaultScope<'_>, key: &str) -> String {
    match scope.project {
        None => note_name(key),
        Some(project) => note_name(&format!("{project}::{key}")),
    }
}

/// The note an edge pointing at `key` should link to.
///
/// Almost always [`scoped_note_name`]. The exception is the one cross-repo edge
/// the graph already models: a spoke's inferred link to a hub is stored as an
/// edge to a **local external-ref placeholder** (`extref:<project>::<key>`,
/// [`rto_graph::external_ref_key`]) because store integrity requires both ends of
/// an edge in one store. A workspace vault holds both repos' notes, so when the
/// placeholder's target names a member the link is pointed at the **real** note
/// instead of the stand-in.
///
/// This invents no edge. It renders the edge that is there, following the
/// placeholder exactly as [`rto_graph::Workspace::follow_external_ref`] does at
/// query time — the cross-repo graph has only ever been *rendered* one repo at a
/// time.
fn link_target(scope: &VaultScope<'_>, key: &str) -> String {
    if scope.redirects_external_ref(key) {
        // `note_name(qualified)` is by construction the same string
        // `scoped_note_name` produces for that member's own copy of the node.
        // `strip_prefix`, not `trim_start_matches`: the latter strips the prefix
        // repeatedly, which would mangle a target that legitimately starts with it.
        return note_name(key.strip_prefix("extref:").unwrap_or(key));
    }
    scoped_note_name(scope, key)
}

/// Render a node's [`Explanation`] into an Obsidian note: YAML frontmatter (with
/// `tags` for the graph view and an ADR's `status`), a clickable **Source** link
/// (when `source_base` — a web "blob" base like
/// `https://github.com/org/repo/blob/<sha>` — is known and the node has a path),
/// the content as the knowledge base, and its edges as provenance-labelled
/// wikilinks.
///
/// `body` is the node's **full source text**, which only the caller can fetch:
/// this function is a pure function of the `Explanation`, and an `Explanation`
/// carries no repository, store or blob. When it is `Some`, it replaces
/// `meta.content` in the note's `## Content` section — see [`note_body`] for why
/// replacing is the only correct combination of the two.
#[must_use]
pub fn render_note(ex: &Explanation, source_base: Option<&str>, body: Option<&str>) -> VaultNote {
    render_note_scoped(ex, source_base, body, &VaultScope::PROJECT)
}

/// [`render_note`], for one member of a **workspace** vault: identical except
/// that the note's own name and every link it emits are resolved through `scope`
/// (see [`VaultScope`]).
///
/// With [`VaultScope::PROJECT`] this is [`render_note`] byte for byte, which is
/// how the single-project vault's compatibility promise is kept by construction
/// rather than by a parallel code path that has to be kept in step.
#[must_use]
pub fn render_note_scoped(
    ex: &Explanation,
    source_base: Option<&str>,
    body: Option<&str>,
    scope: &VaultScope<'_>,
) -> VaultNote {
    let meta = &ex.meta;
    let status = meta.get("status").and_then(|v| v.as_str());
    let content = note_body(meta.get("content").and_then(|v| v.as_str()), body);

    let mut c = String::new();
    c.push_str("---\n");
    let _ = writeln!(c, "key: {}", yaml_double_quoted(&ex.node.key));
    let _ = writeln!(c, "kind: {}", yaml_scalar(ex.node.kind.as_str()));
    // Which member this note came from. Absent in a single-project vault, where
    // it would be one constant repeated on every note — and where adding it would
    // change every note's bytes.
    if let Some(project) = scope.project {
        let _ = writeln!(c, "project: {}", yaml_double_quoted(project));
    }
    if let Some(path) = &ex.node.path {
        let _ = writeln!(c, "path: {}", yaml_double_quoted(path));
    }
    if let Some(lang) = &ex.node.lang {
        let _ = writeln!(c, "lang: {}", yaml_scalar(lang));
    }
    if let Some(status) = status {
        let _ = writeln!(c, "status: {}", yaml_scalar(status));
    }
    // Nested tags group in Obsidian's tag pane and colour the graph view.
    c.push_str("tags:\n");
    let _ = writeln!(c, "  - roteiro/kind/{}", tag_slug(&ex.node.kind));
    // Colours the graph view by member, which is the one thing a workspace vault
    // is for and a per-project vault has no use for.
    if let Some(project) = scope.project {
        let _ = writeln!(c, "  - roteiro/project/{}", tag_slug(project));
    }
    if let Some(lang) = &ex.node.lang {
        let _ = writeln!(c, "  - roteiro/lang/{}", tag_slug(lang));
    }
    if let Some(status) = status {
        let _ = writeln!(c, "  - roteiro/status/{}", tag_slug(status));
    }
    c.push_str("---\n\n");

    let _ = writeln!(c, "# {}", ex.node.name);
    if let Some(status) = status {
        let _ = writeln!(c, "\n> **Status:** {status}");
    }

    // A clickable link to the file this node comes from. An absolute URL, so it
    // works from the downloaded vault too (which has no repo files beside it).
    if let (Some(base), Some(path)) = (source_base, ex.node.path.as_deref()) {
        let _ = writeln!(
            c,
            "\n**Source:** [`{path}`]({}/{path})",
            base.trim_end_matches('/')
        );
    }

    // The knowledge base: the full source text, or the captured doc comment /
    // prose / PDF / image text.
    if let Some(content) = content.map(str::trim).filter(|s| !s.is_empty()) {
        c.push_str("\n## Content\n\n");
        c.push_str(content);
        c.push('\n');
    }

    if !ex.outgoing.is_empty() {
        c.push_str("\n## Outgoing\n\n");
        for e in &ex.outgoing {
            let _ = writeln!(
                c,
                "- {} ({}){} → [[{}]]",
                e.kind,
                e.provenance,
                confidence(e.confidence),
                link_target(scope, &e.node)
            );
        }
    }
    if !ex.incoming.is_empty() {
        c.push_str("\n## Incoming\n\n");
        for e in &ex.incoming {
            let _ = writeln!(
                c,
                "- [[{}]] {} ({}){} →",
                link_target(scope, &e.node),
                e.kind,
                e.provenance,
                confidence(e.confidence)
            );
        }
    }

    VaultNote {
        filename: format!("{}.md", scoped_note_name(scope, &ex.node.key)),
        content: c,
    }
}

/// Choose the text a note shows: the caller's full `body` when it has one, else
/// the node's stored `content`.
///
/// The two are **not** complementary, they are the same text at two fidelities,
/// so a note shows one of them and never both. `meta.content` is an embedding
/// budget — extraction caps it (1500 chars) and collapses every whitespace run to
/// a single space, which is right for a store that ships with the graph and wrong
/// for a note: a 23 KB document arrives as one 1500-character line with every
/// heading, table and code fence flattened into it. Where the caller can supply
/// the source, that is what a reader wants; appending the capped rendering
/// underneath it would only restate its first 6% badly.
fn note_body<'a>(content: Option<&'a str>, body: Option<&'a str>) -> Option<&'a str> {
    body.or(content)
}

/// `" (0.82)"` for an inferred edge's confidence, else empty.
fn confidence(c: Option<f64>) -> String {
    c.map_or_else(String::new, |c| format!(" ({c:.2})"))
}

/// A tag-safe slug: lowercase, non-alphanumeric runs → `-`. Keeps Obsidian tags
/// (`roteiro/kind/adr-section`) valid and stable.
fn tag_slug(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut prev_dash = false;
    for ch in s.chars() {
        if ch.is_ascii_alphanumeric() {
            out.push(ch.to_ascii_lowercase());
            prev_dash = false;
        } else if !prev_dash {
            out.push('-');
            prev_dash = true;
        }
    }
    out.trim_matches('-').to_owned()
}

/// One ADR in the overview, with its lifecycle status.
#[derive(Debug, Clone)]
pub struct AdrEntry {
    /// The ADR node key (`adr:<id>`).
    pub key: String,
    /// The ADR title.
    pub name: String,
    /// Lifecycle status (`Accepted`, …), if recorded.
    pub status: Option<String>,
}

/// The `_Home` overview's config-secret inventory figures.
///
/// Counts and file paths only — deliberately not the key names, which belong in
/// `roteiro config-secrets` where the caveat can be stated at length. A vault note
/// is read casually and out of context, which is exactly the wrong place for a
/// list that looks like a secret scan's output.
#[derive(Debug, Clone, Default)]
pub struct ConfigSecretSummary {
    /// Config keys whose **name** matched the secret-name heuristic.
    pub secret_named: usize,
    /// Of those, how many had their value redacted before persistence.
    pub redacted: usize,
    /// Of those, how many are declared in code with no literal value.
    pub declared: usize,
    /// Of those, how many carry an unredacted value. Expected to be zero.
    pub unredacted: usize,
    /// Distinct files carrying at least one secret-named key, ordered and capped
    /// by the caller.
    pub files: Vec<String>,
}

/// One file in the `_Home` overview's intent-debt density table.
#[derive(Debug, Clone)]
pub struct DensityEntry {
    /// Repository-relative path, used for both the wikilink and the label.
    pub path: String,
    /// Retained markers in the file.
    pub markers: u32,
    /// The file's length in lines — the denominator.
    pub lines: u32,
    /// Markers per 1,000 lines.
    pub per_kloc: f64,
}

/// One node in the `_Home` overview's directed-coupling table.
#[derive(Debug, Clone)]
pub struct CouplingEntry {
    /// The node key, for the wikilink.
    pub key: String,
    /// The symbol name.
    pub name: String,
    /// Distinct callers.
    pub fan_in: u32,
    /// Distinct callees.
    pub fan_out: u32,
}

/// Aggregate figures for the vault's `_Home` overview note.
#[derive(Debug, Clone, Default)]
pub struct VaultSummary {
    /// Name of the scanned project (repository directory).
    pub project: String,
    /// Total node and edge counts.
    pub total_nodes: usize,
    /// Total edge count.
    pub total_edges: usize,
    /// `(kind, count)` for each node kind, most-frequent first.
    pub node_counts: Vec<(String, usize)>,
    /// `(provenance, edge count)` — `derived` / `authored` / `inferred`.
    pub edge_provenance: Vec<(String, usize)>,
    /// The ADRs, with status.
    pub adrs: Vec<AdrEntry>,
    /// `(category, count)` of intent-debt markers.
    pub debt: Vec<(String, usize)>,
    /// The files where that debt is most **concentrated**, already ranked and
    /// capped by the caller. Empty when the graph has no markers, or when no
    /// file carrying one has a recorded length.
    pub densest_files: Vec<DensityEntry>,
    /// Secret-named config keys and their redaction state. `None` when the graph
    /// holds no secret-named config key — the section is then absent rather than
    /// rendering a row of zeroes, which would read as a clean bill of health this
    /// lens cannot give.
    pub config_secrets: Option<ConfigSecretSummary>,
    /// The most depended-on symbols by **directed** call fan-in, already ranked
    /// and capped by the caller. Empty when the graph has no `calls` edges.
    pub most_called: Vec<CouplingEntry>,
    /// Web root of the repository (`https://host/owner/repo`), if derivable from
    /// the git remote — for a "Repository" link in the overview, and the
    /// **clone-from** column of a workspace vault's manifest (#442 part 2).
    ///
    /// The web root rather than the raw `origin` fetch URL on purpose: a vault is
    /// made to be handed to someone, and `git@host:owner/repo.git` is only
    /// actionable for a reader who already has SSH access to that host.
    ///
    /// It is **where the code lives, not a guaranteed clone URL**, and the
    /// manifest says so. `repo_web_root` normalises a remote to `https://host/…`,
    /// which clones on the common forges and may not on an unusual one, and says
    /// nothing about whether the reader can read a private repository. A manifest
    /// that promised "clone from here" would be making a claim it cannot check.
    pub repo_url: Option<String>,
    /// Hex commit the graph was rendered from, for a permalink note — and, in a
    /// workspace vault, the commit this member is pinned at.
    ///
    /// With [`Self::repo_url`] it is what makes a workspace vault **replicable**
    /// rather than merely browsable: *"here is my workspace"* is far less useful
    /// than *"here is my workspace **at these commits**"*, and it is what lets a
    /// reader tell a stale vault from a current one instead of guessing.
    pub commit: Option<String>,
    /// The **enabled** `[ingest]` toggles this member was extracted under, by
    /// name (`prose`, `pdf`, …), and its `[debt] ignore` globs.
    ///
    /// The manifest's third leg, after clone URL and commit: those two get a
    /// reader the same *source*, and these two are what decide whether the same
    /// source produces the same *vault*. `[ingest] prose` off means notes with no
    /// captured content; a `[debt] ignore` glob means the debt figures on this
    /// page are already filtered. Without them "reproducible" means "you can
    /// obtain the code", which is a weaker claim than the section makes.
    pub settings: RenderedUnder,
    /// This member's stored analyzer findings (ADR-0012), ordered most severe
    /// first by the caller. Rendered in a workspace vault's `_Home`; read
    /// together with [`Self::coverage`], which is what says whether an empty
    /// list means anything at all.
    pub findings: Vec<FindingEntry>,
    /// Whether an analyzer has ever run against this member — the context that
    /// makes an empty [`Self::findings`] readable rather than reassuring. See
    /// [`Coverage`].
    pub coverage: Coverage,
}

/// Render the vault's overview note: what was scanned, the structure by kind,
/// the provenance breakdown, the decisions (ADRs) and their status, the
/// intent-debt summary, and how to navigate. The entry point for the vault.
#[must_use]
pub fn render_home(s: &VaultSummary) -> VaultNote {
    let mut c = String::new();
    c.push_str("---\ntags:\n  - roteiro/home\n---\n\n");
    let _ = writeln!(c, "# {} — knowledge graph", s.project);
    c.push_str(
        "\n*A browsable snapshot of this codebase as one **knowledge graph**, \
         generated by [Roteiro](https://roteiro.dev). Every symbol, document and \
         decision is a note, linked to the things it relates to.*\n",
    );
    c.push_str(HOW_TO_READ);
    let _ = writeln!(
        c,
        "\n**{} nodes**, **{} edges** across the project.",
        s.total_nodes, s.total_edges
    );
    write_repo_line(&mut c, s);
    write_summary_sections(&mut c, s, &VaultScope::PROJECT, 2);
    c.push_str(NAVIGATING);

    VaultNote {
        filename: HOME_NOTE.to_owned(),
        content: c,
    }
}

/// The "how to read a note" paragraph. Shared verbatim by the single-project and
/// workspace overviews — the notes themselves are identical in both, so a reader
/// who learns the format once has learned it for either.
const HOW_TO_READ: &str = "\n**How to read it.** Open any note to see what a thing is, the intent or \
     docs behind it (its **Content**), where it lives (its **Source** link), \
     and how it connects (**Outgoing**/**Incoming** links). Each link is \
     labelled with how the fact was established — `derived` (extracted from \
     code), `authored` (human intent: ADRs, blueprints, annotations), or \
     `inferred` (a scored suggestion). Open Obsidian's **graph view** to see \
     the whole thing at once.\n";

/// The closing navigation section.
const NAVIGATING: &str = "\n## Navigating this vault\n\n\
     - Open the **graph view** to see the whole codebase; notes are coloured/\
     filterable by their `roteiro/kind/*`, `roteiro/lang/*` and \
     `roteiro/status/*` tags.\n\
     - Each note carries its captured **content** (doc comments, prose, PDF/\
     image text) and its provenance-labelled incoming/outgoing links.\n\
     - Start from an ADR above, or search the tag pane for a kind.\n";

/// `**Repository:** …` — the web root and the commit the graph was rendered from.
fn write_repo_line(c: &mut String, s: &VaultSummary) {
    if let Some(repo) = &s.repo_url {
        let _ = write!(c, "\n**Repository:** [{repo}]({repo})");
        if let Some(commit) = &s.commit {
            let short = &commit[..commit.len().min(12)];
            let _ = write!(c, " · rendered at commit `{short}`");
        }
        c.push('\n');
    }
}

/// Every aggregate the overview carries for **one project**: structure by kind,
/// provenance, ADRs, intent debt (and where it is densest), the config-secret
/// inventory and directed call coupling.
///
/// Factored out of [`render_home`] so a workspace vault's per-member section is
/// *the same code*, not a reimplementation that can drift: the promise in issue
/// #442 is that today's per-project view stays a **subset** of the workspace one
/// rather than a casualty of it. `level` is the markdown heading depth — 2 for a
/// single-project `_Home`, 3 inside a member's section — and `scope` decides
/// whether the wikilinks point at bare or project-qualified notes.
fn write_summary_sections(c: &mut String, s: &VaultSummary, scope: &VaultScope<'_>, level: usize) {
    let hd = &"#".repeat(level);
    let sub = &"#".repeat(level + 1);
    write_structure(c, s, hd);
    write_decisions(c, s, scope, hd);
    write_debt(c, s, scope, hd, sub);
    write_config_secrets(c, s, scope, hd);
    write_coupling(c, s, scope, hd);
}

/// `Structure` (nodes by kind) and `Provenance` (edges by how they were established).
fn write_structure(c: &mut String, s: &VaultSummary, hd: &str) {
    let _ = write!(c, "\n{hd} Structure\n\n| Kind | Count |\n| --- | --- |\n");
    for (kind, n) in &s.node_counts {
        let _ = writeln!(c, "| {kind} | {n} |");
    }

    if !s.edge_provenance.is_empty() {
        let _ = write!(
            c,
            "\n{hd} Provenance\n\n| Provenance | Edges |\n| --- | --- |\n"
        );
        for (prov, n) in &s.edge_provenance {
            let _ = writeln!(c, "| {prov} | {n} |");
        }
    }
}

/// `Decisions (ADRs)` — the recorded decisions and their lifecycle status.
fn write_decisions(c: &mut String, s: &VaultSummary, scope: &VaultScope<'_>, hd: &str) {
    let _ = write!(c, "\n{hd} Decisions (ADRs)\n\n");
    if s.adrs.is_empty() {
        c.push_str("*No ADRs found.*\n");
    } else {
        for adr in &s.adrs {
            let status = adr.status.as_deref().unwrap_or("—");
            let _ = writeln!(
                c,
                "- **{status}** — [[{}|{}]]",
                scoped_note_name(scope, &adr.key),
                adr.name
            );
        }
    }
}

/// `Intent debt` — the marker categories, and the files the debt is densest in.
fn write_debt(c: &mut String, s: &VaultSummary, scope: &VaultScope<'_>, hd: &str, sub: &str) {
    let _ = write!(c, "\n{hd} Intent debt\n\n");
    if s.debt.is_empty() {
        c.push_str("*None recorded.*\n");
    } else {
        c.push_str("| Category | Count |\n| --- | --- |\n");
        for (cat, n) in &s.debt {
            let _ = writeln!(c, "| {cat} | {n} |");
        }
    }

    if !s.densest_files.is_empty() {
        let _ = write!(
            c,
            "\n{sub} Densest files (markers per 1,000 lines)\n\n\
             *Where the debt above is concentrated, rather than where there is \
             most of it — a raw count ranks the biggest file first by \
             construction. The denominator is file length: every line, blanks and \
             comments included, not source lines of code. Prose matches (`for \
             now`, `tbd`) count too, so a design document can rank high.*\n\n"
        );
        c.push_str("| File | Markers | Lines | Per 1k |\n| --- | --- | --- | --- |\n");
        for e in &s.densest_files {
            let _ = writeln!(
                c,
                "| [[{}\\|{}]] | {} | {} | {:.2} |",
                scoped_note_name(scope, &format!("file:{}", e.path)),
                e.path,
                e.markers,
                e.lines,
                e.per_kloc
            );
        }
    }
}

/// `Config keys named like secrets` — an inventory and its unconditional caveat.
fn write_config_secrets(c: &mut String, s: &VaultSummary, scope: &VaultScope<'_>, hd: &str) {
    if let Some(cs) = &s.config_secrets {
        let _ = write!(c, "\n{hd} Config keys named like secrets\n\n");
        let _ = writeln!(
            c,
            "**{}** secret-named config key(s): {} redacted before storage, {} \
             declared in code without a value, {} unredacted.",
            cs.secret_named, cs.redacted, cs.declared, cs.unredacted
        );
        if cs.unredacted > 0 {
            let _ = writeln!(
                c,
                "\n> [!warning] {} key(s) carry an **unredacted** value. Extraction \
                 always redacts, so these came from an import layer — inspect the \
                 importing tool, not this repository.",
                cs.unredacted
            );
        }
        if !cs.files.is_empty() {
            c.push_str("\nIn:\n");
            for path in &cs.files {
                let _ = writeln!(
                    c,
                    "- [[{}\\|{path}]]",
                    scoped_note_name(scope, &format!("file:{path}"))
                );
            }
        }
        // The caveat is unconditional and comes last, so it is the final thing read
        // in this section. A vault note is browsed out of context; this is exactly
        // where "config keys named like secrets" would otherwise be misread as a
        // secret scan that came back clean.
        c.push_str(
            "\n*An inventory of config keys whose **names** look secret, not a secret \
             scan. Values are redacted before they are stored, so this reports that \
             such keys exist and were redacted — never a value. It cannot see a \
             hardcoded credential in source code, cannot judge whether a value is \
             valid, and cannot tell a real secret from a placeholder. A credential \
             under an innocuous key name (`dsn`, `endpoint`) does not appear here at \
             all, so this section being small says nothing about whether this \
             repository leaks secrets.*\n",
        );
    }
}

/// `Most depended-on (call fan-in)` — directed call coupling, capped.
fn write_coupling(c: &mut String, s: &VaultSummary, scope: &VaultScope<'_>, hd: &str) {
    if !s.most_called.is_empty() {
        let _ = write!(
            c,
            "\n{hd} Most depended-on (call fan-in)\n\n\
             *Distinct callers and callees over `calls` edges — direction kept, so \
             \"everything calls this\" and \"this calls everything\" are not the same \
             row. Call targets are resolved by simple name, so a short, generically-\
             named function can absorb every call to that name: read a large fan-in on \
             one as a question, not a finding.*\n\n"
        );
        c.push_str("| Symbol | Called by | Calls |\n| --- | --- | --- |\n");
        for e in &s.most_called {
            let _ = writeln!(
                c,
                "| [[{}\\|{}]] | {} | {} |",
                scoped_note_name(scope, &e.key),
                e.name,
                e.fan_in,
                e.fan_out
            );
        }
    }
}

/// One member's **version pin**: the revision of a hub it deploys (ADR-0009 step 8).
///
/// # Why it names its hub
///
/// A pin is hub-**relative**, and since #623 a workspace is a snowflake rather
/// than a star: a project can be a spoke of one project and the hub of others, so
/// "the hub version this member pins" has no single referent. `infra` pins
/// `chart`, and `chart` pins `app`. Naming the hub is what lets a reader follow
/// the chain instead of guessing which end of it a bare revision belongs to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MemberPin {
    /// The member doing the pinning — the spoke.
    pub member: String,
    /// The workspace member whose version is pinned — this member's parent in the
    /// dependency graph, not necessarily the workspace's busiest node.
    pub hub: String,
    /// The hub git revision pinned: a submodule sha, or an image tag resolved to a
    /// hub ref. `None` when the member depends on `hub` but declares no version
    /// this tool can resolve.
    ///
    /// `None` is a **finding**, not an absence of one — see the module's rendering
    /// of it, and issue #505, which established that "asked and found nothing" must
    /// not render identically to "never asked".
    pub rev: Option<String>,
    /// Where the pin was read from (`submodule vendor/app`, `image acme/app:1.4.0`).
    /// `None` exactly when `rev` is.
    pub via: Option<String>,
}

/// One cross-repo edge the workspace vault can actually follow: a spoke's node
/// linking to a hub's, through the external-ref placeholder ADR-0009 persists.
///
/// Collected by the caller, which has every member's store open; the renderer
/// only lays them out. Nothing here is a new edge — these are the `inferred`
/// links `roteiro links` already reports, rendered for the first time.
#[derive(Debug, Clone)]
pub struct CrossLink {
    /// The member the edge starts in.
    pub from_project: String,
    /// The source node's key, within `from_project`.
    pub from_key: String,
    /// The source node's display name.
    pub from_name: String,
    /// The edge kind (`links`, …).
    pub kind: String,
    /// Confidence, for an `inferred` edge.
    pub confidence: Option<f64>,
    /// Whether this link was **declared** (`[[links]]` in the source repo's
    /// config, ADR-0009) rather than inferred by key matching.
    ///
    /// The distinction is the whole of ADR-0009's `authored → gold,
    /// inferred → slate`: a declaration is a statement of intent by someone who
    /// knows the topology, a match is a candidate. Until #573 the vault could not
    /// draw it, because nothing persisted an authored cross-repo edge — so this
    /// section carried a blanket caveat saying every row was a candidate.
    pub authored: bool,
    /// The project-qualified target, `<project>::<key>` (ADR-0009).
    pub to_qualified: String,
    /// Whether `to_qualified`'s project is a member of this workspace — and so
    /// whether the link resolves to a note in this vault, or dangles because the
    /// target repository is outside it.
    pub resolves: bool,
}

/// The settings a member's notes were rendered under — the ones that change what
/// the vault *contains*, not the whole merged config.
///
/// Deliberately a short list rather than the effective configuration in full.
/// #442 asks the manifest to record "effective settings", and dumping every
/// resolved key into a shareable artifact would re-open the redaction question
/// this vault already has to warn about, to record settings that cannot change
/// what a reader sees. These two can.
#[derive(Debug, Clone, Default)]
pub struct RenderedUnder {
    /// Enabled `[ingest]` toggles by name, in declaration order. Empty means
    /// every toggle was off — which is a real state and renders as such, not as
    /// an absent row.
    pub ingest: Vec<String>,
    /// `[debt] ignore` globs. Non-empty means the debt figures on this page are
    /// **already filtered**, and a reader comparing them against a fresh
    /// `roteiro debt` without the same config will not match.
    pub debt_ignore: Vec<String>,
}

/// One analyzer finding, as the vault renders it (ADR-0012).
///
/// A render-facing copy rather than `rto_graph::Finding`, matching [`AdrEntry`]
/// and [`CouplingEntry`]: the renderer takes the fields it prints and stays free
/// of the findings model. It deliberately does **not** carry `meta` — that is
/// whatever the analyzer emitted, kept verbatim, and a shareable artifact is the
/// worst place to reproduce "whatever the tool said" unread.
#[derive(Debug, Clone)]
pub struct FindingEntry {
    /// The rule, advisory or check id the analyzer fired (`RUSTSEC-2026-0031`).
    pub rule: String,
    /// The severity the analyzer assigned — **a tool judgement, not a
    /// confidence** — rendered as the analyzer's word rather than the vault's.
    pub severity: String,
    /// One-line summary.
    pub title: String,
    /// The analyzer's full message.
    pub message: String,
    /// Repository-relative path the finding is about, if the analyzer located one.
    pub path: Option<String>,
    /// The analyzer that produced it, so a reader can tell one tool's opinion
    /// from another's rather than reading a merged list as a single verdict.
    pub analyzer: String,
}

/// What a member's analyzer coverage actually is — the distinction the vault
/// must never blur.
///
/// An empty findings list means one of two completely different things, and
/// printing both as "no findings" is the failure `roteiro security status`
/// records as `no-analyzer-on-record`: **nothing has been analyzed** is not
/// **nothing is wrong**. A shareable artifact is the worst place to conflate
/// them, because its reader is the one person who cannot check.
///
/// [`Coverage::NotRun`] is the `Default` deliberately. A `VaultSummary` built
/// from `Default` has had no analyzer run against it, and defaulting the other
/// way would render "no findings" for a member nobody looked at — the exact
/// conflation this type exists to prevent, arrived at by omission.
#[derive(Debug, Clone, Default)]
pub enum Coverage {
    /// No analyzer has ever run against this member. **Not** a clean result.
    #[default]
    NotRun,
    /// At least one analyzer ran, as `(analyzer, version)` per run — so an empty
    /// findings list is attributable to a tool that actually looked.
    Ran(Vec<(String, String)>),
}

/// Aggregate figures for a **workspace** vault's `_Home` overview: the members,
/// each with exactly the aggregates a single-project `_Home` carries, plus the
/// cross-repo links between them.
#[derive(Debug, Clone, Default)]
pub struct WorkspaceSummary {
    /// When this vault was rendered, RFC 3339 UTC.
    ///
    /// A vault is **read-only and point-in-time**. Stamping it is what gives
    /// that property teeth: with the per-member commits, a reader can tell
    /// whether what they are looking at still describes the workspace, rather
    /// than assuming it does.
    pub generated_at: String,
    /// The workspace name (`--workspace-name`).
    pub name: String,
    /// One entry per member repository, in stable name order. Each is the very
    /// same [`VaultSummary`] a per-project vault would render.
    pub members: Vec<VaultSummary>,
    /// Version pins: for each member that depends on another, the hub revision it
    /// deploys (ADR-0009 step 8). One entry per **dependency**, not per member — a
    /// project with two parents pins each of them separately, and a member with no
    /// parents contributes nothing.
    ///
    /// Ordered by the caller, which holds the dependency graph; the renderer only
    /// lays them out.
    pub pins: Vec<MemberPin>,
    /// Cross-repo links between members, already ordered and capped by the caller.
    pub cross_links: Vec<CrossLink>,
    /// Cross-repo links found in total, which `cross_links` may be a capped view
    /// of — so the section can say what it is not showing.
    pub cross_links_total: usize,
    /// How many of `cross_links_total` were **declared** (`[[links]]`) rather
    /// than inferred.
    ///
    /// Counted before the cap, not from `cross_links`: that vector is truncated
    /// to [`WORKSPACE_CROSS_LINK_ROWS`](crate::WORKSPACE_CROSS_LINK_ROWS) rows,
    /// so counting it would describe the rows on screen while reading as a
    /// statement about the workspace — a caption that quietly changes meaning
    /// once a workspace grows past the cap.
    pub cross_links_authored: usize,
}

/// Render a **workspace** vault's overview: the members and their scale, the
/// cross-repo links between them, and then each member's own aggregates —
/// structure, provenance, ADRs, intent debt, config-secret inventory and call
/// coupling — under its own heading.
///
/// The per-member sections are rendered by the same [`write_summary_sections`]
/// the single-project `_Home` uses, so the existing view is a **subset** of this
/// one: someone who came for their repository's coupling and debt tables finds
/// them, rather than a workspace total that averages them away.
#[must_use]
pub fn render_workspace_home(ws: &WorkspaceSummary) -> VaultNote {
    let members: std::collections::BTreeSet<String> =
        ws.members.iter().map(|m| m.project.clone()).collect();

    let mut c = String::new();
    c.push_str("---\ntags:\n  - roteiro/home\n  - roteiro/workspace\n---\n\n");
    let _ = writeln!(c, "# {} — workspace knowledge graph", ws.name);
    c.push_str(
        "\n*A browsable snapshot of a whole **workspace** as one **knowledge \
         graph**, generated by [Roteiro](https://roteiro.dev). Every symbol, \
         document and decision in every member repository is a note, linked to the \
         things it relates to — including across repositories.*\n",
    );
    c.push_str(HOW_TO_READ);
    // The example is *rendered* by `note_name` rather than spelled out. A
    // hand-written spelling of this sentence survived #574 unchanged, so every
    // vault v2.0.0 built stated the pre-#574 naming rule — on the first page a
    // reader opens — while `note_name` was writing something else. This is the
    // one copy that lives in the crate defining the rule, so it can simply ask:
    // a derived example cannot drift, and a spelled one already has.
    //
    // The *key* it names has to be real too, or the fix trades one false
    // sentence in `_Home` for another: `<member>::file:README.md` was fabricated
    // from the member list, and workspace membership does not require a README.
    // A cross-repo link's **source** end is the strongest key available here —
    // `from_project` is a member by definition and `from_key` is a node in that
    // member's own store, which the Cross-repo links table below already links
    // to by name. The *target* end will not do: `resolves == false` means the
    // target repository is outside this vault, so `to_qualified` names no note
    // here — the same false claim one remove away.
    //
    // With no cross-repo links there is no key this function can prove is a
    // node, so the sentence says nothing rather than inventing one. The rule it
    // states is complete without an example; only the illustration is lost.
    let example = ws.cross_links.first().map_or_else(String::new, |l| {
        let key = format!("{}::{}", l.from_project, l.from_key);
        format!(" Here, `{key}` is the note `{}.md`.", note_name(&key))
    });
    let _ = writeln!(
        c,
        "\n**Every note is keyed `<project>::<key>`**, because a node key is \
         repository-relative: the same path or symbol can occur in more than one \
         member, and without the project the second note would overwrite the \
         first. A note's *filename* is derived from that key — a readable \
         lowercase hint, then a hash of the whole key — so no filename contains \
         `::`.{example} Filter the graph view by a member's `roteiro/project/*` \
         tag to see one repository at a time."
    );

    let total_nodes: usize = ws.members.iter().map(|m| m.total_nodes).sum();
    let total_edges: usize = ws.members.iter().map(|m| m.total_edges).sum();
    let _ = writeln!(
        c,
        "\n**{total_nodes} nodes**, **{total_edges} edges** across **{}** member \
         repositor{}.",
        ws.members.len(),
        if ws.members.len() == 1 { "y" } else { "ies" }
    );

    c.push_str("\n## Members\n\n| Project | Nodes | Edges | Repository | Commit |\n| --- | --- | --- | --- | --- |\n");
    for m in &ws.members {
        let repo = m
            .repo_url
            .as_ref()
            .map_or_else(|| "—".to_owned(), |u| format!("[{u}]({u})"));
        let commit = m.commit.as_ref().map_or_else(
            || "—".to_owned(),
            |c| format!("`{}`", &c[..c.len().min(12)]),
        );
        let _ = writeln!(
            c,
            "| [[#{}\\|{}]] | {} | {} | {repo} | {commit} |",
            m.project, m.project, m.total_nodes, m.total_edges
        );
    }
    // `[[#Heading]]`, the form the member rows above already use, rather than a
    // `](#slug)` anchor: the slug a renderer computes and the slug a reader's
    // tool computes are exactly what issue #524 is about, and a manifest is a
    // poor place to find out they disagree.
    c.push_str(
        "\n*The `Repository` and `Commit` columns say where each member came from \
         and what was read. The manifest that makes those reconstructable — and \
         states what this vault carries before you share it — is \
         [[#Reproducing this vault]], below.*\n",
    );

    write_cross_links(&mut c, ws);
    write_findings(&mut c, ws);
    write_manifest(&mut c, ws);

    for m in &ws.members {
        let _ = writeln!(c, "\n## {}", m.project);
        let _ = writeln!(
            c,
            "\n**{} nodes**, **{} edges** in this member.",
            m.total_nodes, m.total_edges
        );
        write_repo_line(&mut c, m);
        let scope = VaultScope {
            project: Some(&m.project),
            members: &members,
        };
        write_summary_sections(&mut c, m, &scope, 3);
    }

    c.push_str(NAVIGATING);

    VaultNote {
        filename: HOME_NOTE.to_owned(),
        content: c,
    }
}

/// The `### Version pins` table — which hub revision each member deploys
/// (ADR-0009 step 8, issue #442).
///
/// # Why this is part of a *manifest* rather than a curiosity
///
/// The rest of the manifest reconstructs the workspace **as rendered**: clone
/// here, check out these commits. Pins answer a different question — what each
/// deployment repo is *running*, which is rarely the commit it was rendered at. A
/// spoke at `HEAD` deploying `app@1.4.0` describes a live system that its own
/// commit id says nothing about.
///
/// # Each pin names its hub
///
/// Because since #623 a workspace is a snowflake, not a star: `infra → chart →
/// app`, where `chart` is a spoke of one and the hub of the others. A column of
/// bare revisions would be ambiguous the moment a workspace has more than one
/// level, and silently so.
///
/// # A member that pins nothing is said to pin nothing
///
/// A dependency with no resolvable version renders as *(none detected)* rather
/// than being dropped. Issue #505 settled the rule this follows: **asked and found
/// nothing** must not render identically to **never asked**. Dropping the row
/// would make a workspace where pin detection is inert look exactly like one with
/// no dependencies at all.
fn write_pins(c: &mut String, ws: &WorkspaceSummary) {
    if ws.pins.is_empty() {
        return;
    }
    c.push_str("\n### Version pins\n\n");
    let found = ws.pins.iter().filter(|p| p.rev.is_some()).count();
    // Both halves agree with the count, not just the noun: "1 of 1 dependency
    // resolve" is what varying one and fixing the other produces.
    let (noun, verb) = if ws.pins.len() == 1 {
        ("dependency", "resolves")
    } else {
        ("dependencies", "resolve")
    };
    let _ = writeln!(
        c,
        "*{found} of {} {noun} {verb} to a hub revision. A pin is what the member \
         **deploys**, which is not the commit it was rendered at.*\n",
        ws.pins.len()
    );
    c.push_str("| Member | Pins | At revision | Read from |\n| --- | --- | --- | --- |\n");
    for p in &ws.pins {
        let _ = writeln!(
            c,
            "| {} | {} | {} | {} |",
            // Names are prose, not spans: `inline_untrusted` escapes `|` so they
            // are table-safe without becoming monospaced. The revision and the
            // source string come from git and from a config file, so they go
            // through `table_cell` like every other value this manifest quotes.
            inline_untrusted(&p.member),
            inline_untrusted(&p.hub),
            p.rev
                .as_deref()
                .map_or_else(|| "*(none detected)*".to_owned(), table_cell),
            p.via.as_deref().map_or_else(|| "—".to_owned(), table_cell),
        );
    }
}

/// The `### Rendered under` table — the settings half of the manifest.
///
/// A clone URL and a commit get a reader the same **source**; these get them the
/// same **vault**. Rendering the same commits with `[ingest] prose` off, or with
/// a different `[debt] ignore`, produces a different document from the same
/// code — so a manifest that omits them promises a reproducibility it cannot
/// deliver, which is worse than promising less.
fn write_rendered_under(c: &mut String, ws: &WorkspaceSummary) {
    c.push_str("\n### Rendered under\n\n");
    c.push_str(
        "*These change what a vault **contains**, so re-rendering the commits \
         above under different ones will not reproduce this document.*\n\n",
    );
    c.push_str("| Member | `[ingest]` | `[debt] ignore` |\n| --- | --- | --- |\n");
    for m in &ws.members {
        let list = |v: &[String]| {
            if v.is_empty() {
                // "none" as a word, not an empty cell: a blank reads as unknown,
                // and these two are the difference between reproducing this
                // vault and something that merely resembles it.
                "*none*".to_owned()
            } else {
                // `[debt] ignore` is user config landing in a table cell: a
                // glob carrying a backtick or a `|` reshapes the row. Not
                // analyzer-sourced, but untrusted for the same reason — the
                // vault did not write it.
                v.iter()
                    .map(|x| table_cell(x))
                    .collect::<Vec<_>>()
                    .join(", ")
            }
        };
        let _ = writeln!(
            c,
            "| {} | {} | {} |",
            inline_untrusted(&m.project),
            list(&m.settings.ingest),
            list(&m.settings.debt_ignore)
        );
    }
}

/// The `## Security findings` section: the stored analyzer output (ADR-0012) for
/// every member.
///
/// # Why this is here at all, stated once
///
/// ADR-0012 keeps findings out of `nodes`/`edges` **specifically** so they cannot
/// reach `export_factset`, and records the alternative as rejected because it
/// would "silently publish tool output into an artifact". This section is that
/// same publication, made **deliberately and visibly** rather than by accident:
/// a workspace vault is a hand-over document, and the owner ruled that it should
/// answer *"what is wrong with this workspace"* as well as *"what is in it"*.
/// The exclusions section says so at the point a reader is about to share it.
///
/// # The distinction this section exists to preserve
///
/// A member with no findings is rendered **two different ways** depending on
/// [`Coverage`], because "no analyzer has run" and "an analyzer ran and found
/// nothing" are opposite facts that look identical when both are printed as an
/// empty list. `roteiro security status` names that failure `no-analyzer-on-record`
/// and refuses to let it read as clean; a shareable artifact must refuse harder,
/// because its reader is the one person who cannot go and check.
fn write_findings(c: &mut String, ws: &WorkspaceSummary) {
    c.push_str("\n## Security findings\n\n");

    let total: usize = ws.members.iter().map(|m| m.findings.len()).sum();
    let unanalyzed = ws
        .members
        .iter()
        .filter(|m| matches!(m.coverage, Coverage::NotRun))
        .count();

    let _ = writeln!(
        c,
        "*Stored analyzer output (ADR-0012). **{total} finding(s)** across \
         {} member(s){}. A severity is the **analyzer's** judgement, not \
         Roteiro's, and a finding is a tool's claim rather than a confirmed \
         defect — read one as something to check, not something proven.*\n",
        ws.members.len(),
        if unanalyzed > 0 {
            format!(", with {unanalyzed} never analyzed at all")
        } else {
            String::new()
        }
    );

    for m in &ws.members {
        match (&m.coverage, m.findings.is_empty()) {
            // Never analyzed. Said loudly, and *not* in the same breath as a
            // member that came back clean — the whole point of the split.
            (Coverage::NotRun, _) => {
                let _ = writeln!(c, "### {} — **not analyzed**\n", m.project);
                c.push_str(
                    "*No analyzer has run against this member, so nothing here is \
                     a statement about it. An empty list is the absence of a \
                     question, not a reassuring answer.*\n\n",
                );
            }
            // Analyzed, nothing found — attributable to a tool that looked.
            (Coverage::Ran(runs), true) => {
                let _ = writeln!(
                    c,
                    "### {} — no findings\n\n*{} ran and reported none.*\n",
                    m.project,
                    describe_runs(runs)
                );
            }
            (Coverage::Ran(runs), false) => {
                let _ = writeln!(
                    c,
                    "### {} — {} finding(s)\n\n*Reported by {}.*\n",
                    m.project,
                    m.findings.len(),
                    describe_runs(runs)
                );
                for f in &m.findings {
                    let at = f
                        .path
                        .as_deref()
                        .map_or_else(String::new, |p| format!(" · {}", inline_code(p)));
                    let _ = writeln!(
                        c,
                        "**{}** · {}{at} — {}\n",
                        inline_code(&f.severity),
                        inline_code(&f.rule),
                        // Prose, not a span: the title is the sentence a reader
                        // scans, so it is escaped rather than monospaced.
                        inline_untrusted(&f.title)
                    );
                    write_analyzer_message(c, f);
                }
            }
        }
    }
}

/// An untrusted value as a **complete code span**, delimiters included.
///
/// A code span renders its content literally — no emphasis, no links, no HTML —
/// so the only thing that can escape one is a backtick run long enough to close
/// it. Widening the delimiter past the longest run inside the value is therefore
/// the whole defence, and it is the *right* defence: backslash-escaping inside a
/// span protects nothing and does show, turning `vendor/**` into `vendor\*\*`
/// on the page.
///
/// Whitespace is still collapsed — a newline ends the line the span sits on
/// however well the span itself is delimited.
///
/// **Not sufficient inside a table cell.** GFM splits a row on `|` *before*
/// inline parsing, so a pipe inside a code span still ends the cell. Use
/// [`table_cell`] there.
fn inline_code(s: &str) -> String {
    let collapsed = s.split_whitespace().collect::<Vec<_>>().join(" ");
    let longest_run = collapsed
        .split(|ch| ch != '`')
        .map(str::len)
        .max()
        .unwrap_or(0);
    let tick = "`".repeat(longest_run + 1);
    // CommonMark strips one leading and trailing space from a span, which is how
    // content that itself starts or ends with a backtick is expressed.
    let pad = if collapsed.starts_with('`') || collapsed.ends_with('`') {
        " "
    } else {
        ""
    };
    format!("{tick}{pad}{collapsed}{pad}{tick}")
}

/// One line of analyzer-sourced text, made safe to interpolate into the note.
///
/// The message gets a fence; **these fields did not**, and they come from the
/// same place. A `title` carrying a newline ends the line it was placed on and
/// starts a new block — one that can open a heading, a list or a table row — so
/// the "quoted, not absorbed" property held for one field out of four. A `rule`
/// or `path` carrying a backtick escapes the code span it is wrapped in.
///
/// Four steps, in order:
///
/// 1. **Collapse every whitespace run to one space.** This is what removes the
///    structural attack: Markdown block constructs need a line start, and after
///    this there are no line starts left inside the value.
/// 2. **HTML-escape `&`, `<`, `>`.** Some of these values land inside raw HTML
///    (`<sub>`, `<details><summary>`), where a backslash escapes nothing — an
///    analyzer named `</sub><script>` would close the tag and keep going. This
///    step is why there is **one** helper rather than a Markdown one and an HTML
///    one: two helpers means two contexts to keep straight, and the reason this
///    function exists at all is that the first version secured one context and
///    missed its neighbour.
/// 3. **Backslash-escape the remaining Markdown punctuation.** A link in a
///    document handed to someone can point anywhere, and a stray backtick or
///    pipe silently reshapes the line it lands in. `<` and `>` are absent from
///    that set because step 2 already turned them into entities.
/// 4. **Defuse bare URLs.** Escaping `[` stops explicit `[text](url)` syntax and
///    nothing else: Obsidian and GFM *linkify* a plain `https://…`, so analyzer
///    text could still hand the reader a clickable link to anywhere. Replacing
///    the scheme's colon with `&#58;` renders identically and matches no
///    linkifier — the reader still sees the URL and can copy it deliberately.
///
/// Safe in both contexts, so a caller never has to know which one it is in.
fn inline_untrusted(s: &str) -> String {
    let collapsed = s.split_whitespace().collect::<Vec<_>>().join(" ");
    let mut out = String::with_capacity(collapsed.len());
    for ch in collapsed.chars() {
        match ch {
            '&' => out.push_str("&amp;"),
            '<' => out.push_str("&lt;"),
            '>' => out.push_str("&gt;"),
            // `&` is deliberately absent below: the entities written above must
            // survive intact, and backslash-escaping their `&` would render them
            // literally.
            '\\' | '`' | '*' | '_' | '[' | ']' | '|' | '#' => {
                out.push('\\');
                out.push(ch);
            }
            _ => out.push(ch),
        }
    }
    defuse_autolinks(&out)
}

/// Stop a bare URL in untrusted text from being turned into a clickable link.
///
/// Escaping `[` covers explicit link syntax; it does nothing about linkification,
/// which is on by default in Obsidian and GFM. `https&#58;//evil.example` renders
/// as `https://evil.example` and matches no autolinker, so the URL stays
/// readable and copyable while ceasing to be a thing the reader can click by
/// accident in a document someone handed them.
fn defuse_autolinks(s: &str) -> String {
    s.replace("https://", "https&#58;//")
        .replace("http://", "http&#58;//")
}

/// [`inline_code`] for a value that lands in a **table cell**.
///
/// A code span is not enough there: GFM splits a row on `|` before it parses
/// inline content, so a pipe inside the span still ends the cell and shifts
/// every column after it. `\|` is the documented escape, and it is applied to
/// the finished span so the delimiter widening still holds.
///
/// The distinction is not cosmetic — it is a third rendering context, and this
/// file has now been wrong about a context twice.
fn table_cell(s: &str) -> String {
    inline_code(s).replace('|', "\\|")
}

/// One finding's full analyzer message, collapsed and **verbatim**.
///
/// Collapsed because the messages are long — a single GHSA advisory runs to
/// paragraphs, and seventeen of them inline turn `_Home` into a wall of text
/// nobody reads, which loses the findings as surely as omitting them. `<details>`
/// keeps every byte in the file (the ruling was to include them in full) while
/// letting the reader see the list first.
///
/// **Verbatim, in a fence, rather than as Markdown.** An analyzer message is
/// tool output travelling into a document that gets handed to people: rendered
/// as Markdown it can open headings that restructure the note, or links that
/// point anywhere. A fence is what makes it text the vault *quotes* rather than
/// text the vault *becomes* — and it preserves the advisory's own line structure,
/// which flattening to one line destroys.
///
/// The fence is sized to beat the longest backtick run in the message, for the
/// reason [`crate::docs`] handles multi-backtick spans: a three-backtick fence
/// around a message that itself contains one ends the block early and spills the
/// remainder into the note as prose.
fn write_analyzer_message(c: &mut String, f: &FindingEntry) {
    let message = f.message.trim();
    if message.is_empty() {
        let _ = writeln!(
            c,
            "<sub>reported by `{}`</sub>\n",
            inline_untrusted(&f.analyzer)
        );
        return;
    }
    let longest_run = message
        .split(|ch| ch != '`')
        .map(str::len)
        .max()
        .unwrap_or(0);
    let fence = "`".repeat(longest_run.max(2) + 1);
    let _ = writeln!(
        c,
        "<details><summary><sub>what `{}` said</sub></summary>\n\n\
         {fence}text\n{message}\n{fence}\n\n</details>\n",
        inline_untrusted(&f.analyzer)
    );
}

/// `analyzer version` for each run that produced a member's findings, joined —
/// so "no findings" names the tool that looked rather than asserting a state of
/// the world.
fn describe_runs(runs: &[(String, String)]) -> String {
    if runs.is_empty() {
        // `Coverage::Ran` with no runs should not occur; say something true
        // rather than rendering an empty clause that reads as a name.
        return "an analyzer".to_owned();
    }
    runs.iter()
        .map(|(a, v)| {
            // `inline_untrusted`, not `inline_code`: this same value is also
            // interpolated into `<summary>`/`<sub>` by `write_analyzer_message`,
            // and keeping one treatment for it means there is no second context
            // to get wrong later. That is the mistake this pair of helpers was
            // introduced to fix, so it is not worth re-creating for monospace.
            let (a, v) = (inline_untrusted(a), inline_untrusted(v));
            // An ingested report often carries no version the producer stated,
            // and the store keeps that as `unknown`. Printing "`osv-scanner`
            // unknown" reads as a version string; saying nothing reads as the
            // absence it is.
            if v.is_empty() || v == "unknown" {
                format!("`{a}`")
            } else {
                format!("`{a}` {v}")
            }
        })
        .collect::<Vec<_>>()
        .join(", ")
}

/// The `## Reproducing this vault` section — the **manifest** half of #442.
///
/// A vault that says *"here is my workspace"* is far less useful than one that
/// says *"here is my workspace **at these commits**"*. With an origin and a
/// commit per member, a reader can clone, check out, and hold exactly what this
/// vault describes; without them they have a picture and no way back to the
/// thing pictured.
///
/// It is also where the reader is told what a shared vault **does not** contain,
/// at the moment they are most likely to share it. Each exclusion is a decision
/// recorded on #442 rather than an oversight, so each is named with its reason.
fn write_manifest(c: &mut String, ws: &WorkspaceSummary) {
    c.push_str("\n## Reproducing this vault\n\n");
    let _ = writeln!(
        c,
        "*Rendered **{}**. A vault is read-only and point-in-time: it describes \
         these repositories at these commits, and does not change when they do.*\n",
        ws.generated_at
    );
    // "Repository", not "Clone from". The value is the **web root derived from
    // the `origin` remote**, which is the right thing to show a reader — an
    // `git@host:owner/repo.git` is only actionable for someone who already has
    // SSH to that host — but it is not guaranteed to be a working clone URL for
    // every forge or for a private repository. Naming the column "Clone from"
    // promised something this cannot deliver, and the manifest's whole value is
    // that its promises hold.

    let any_origin = ws.members.iter().any(|m| m.repo_url.is_some());
    if any_origin {
        // Stated here rather than above the `if`: it says "each repository
        // below", and above the branch it would be followed immediately by
        // "no member has an `origin` remote".
        c.push_str(
            "*Each repository below is the web root derived from that member's \
             `origin` remote — where the code lives, not a guaranteed clone URL. \
             A private repository, or a forge with a different clone path, still \
             needs whatever access you would normally use.*\n\n",
        );
        c.push_str("| Member | Repository | At commit |\n| --- | --- | --- |\n");
        for m in &ws.members {
            let _ = writeln!(
                c,
                "| {} | {} | {} |",
                // The name is prose, not a span — `inline_untrusted` already
                // backslash-escapes `|`, so it is table-safe without becoming
                // monospaced. The two values below *are* spans, and go through
                // `table_cell`: a remote URL and a sha come from git, not from
                // us, and this table sits thirty lines above the one that
                // already knew that.
                inline_untrusted(&m.project),
                m.repo_url
                    .as_deref()
                    .map_or_else(|| "*(no `origin` remote)*".to_owned(), table_cell),
                m.commit
                    .as_deref()
                    .map_or_else(|| "*(unknown)*".to_owned(), table_cell),
            );
        }
    } else {
        // Every member is local-only. Say so rather than rendering a table of
        // "no origin" rows, which reads as a fault rather than as a workspace
        // that was never pushed anywhere.
        c.push_str(
            "*No member has an `origin` remote, so this vault cannot be \
             reconstructed from it — it describes repositories that exist only \
             where it was rendered.*\n",
        );
    }

    write_pins(c, ws);
    write_rendered_under(c, ws);

    c.push_str(
        "\n### Before you share this\n\n\
         Stated here because this is the point at which a vault is handed to \
         someone.\n\n\
         - **It lists this workspace's known security findings** — see *Security \
           findings* above. That is deliberate: a hand-over document should say \
           what is wrong as well as what is there. But it means this file is a \
           list of **unpatched weaknesses and where they are**, and unlike a \
           local store it cannot be un-shared once sent. Treat it as you would \
           the analyzer reports themselves.\n\
         - **Config keys are redacted by *name*, and that is narrower than it \
           looks.** The check matches ten well-known key names and inspects no \
           values, so a secret in a value whose key is not named like one — \
           `DATABASE_URL=postgres://user:pw@host` — is **not** redacted. \
           Tolerable in a local store; materially different in an artifact whose \
           purpose is to be handed on.\n\
         - **Agent memory** (ADR-0013) is the one thing deliberately left out. It \
           is per-developer and uncommitted, it records prose that can carry \
           pasted tokens, stack traces and customer names, and it has **no \
           redaction chokepoint** at all — so unlike the two above, there is no \
           version of it that is safe to include.\n",
    );
}

/// The `## Cross-repo links` section: the edges that only a workspace vault can
/// show, and the honest statement of what is missing from them.
fn write_cross_links(c: &mut String, ws: &WorkspaceSummary) {
    c.push_str("\n## Cross-repo links\n\n");
    if ws.cross_links.is_empty() {
        c.push_str(
            "*None. These are the `inferred` cross-repo links `roteiro links \
             --infer --write` persists (ADR-0009); a workspace whose members have \
             never been inferred over has none recorded yet.*\n",
        );
        return;
    }
    // The caveat is per-row now, because the two provenances are no longer the
    // same claim: an **authored** row was declared by someone who knows the
    // topology, an **inferred** row is a scored guess. Saying "these are all
    // candidates" over a table containing declarations would understate the
    // declarations exactly as saying nothing would overstate the matches.
    let authored = ws.cross_links_authored;
    // `saturating_sub`: `WorkspaceSummary` is public, so a caller can hand us a
    // count larger than the total. In release that subtraction wraps and the
    // caption reports billions of inferred links — a rendering function should
    // not be the place an inconsistent input becomes nonsense. The debug
    // assertion says which caller was wrong, in the build that can afford to.
    debug_assert!(
        authored <= ws.cross_links_total,
        "cross_links_authored ({authored}) exceeds cross_links_total ({})",
        ws.cross_links_total
    );
    let inferred = ws.cross_links_total.saturating_sub(authored);
    let _ = writeln!(
        c,
        "*A spoke's config key and the hub key it corresponds to, across \
         repositories — the one thing a per-project vault structurally cannot \
         show. **{authored} declared** (`[[links]]`, ADR-0009 — a statement of \
         intent) and **{inferred} inferred** (`roteiro links --infer --write` — \
         read those as candidate correspondences).*\n"
    );
    c.push_str("| From | | To | Kind |\n| --- | --- | --- | --- |\n");
    for l in &ws.cross_links {
        let from_scope = VaultScope {
            project: Some(&l.from_project),
            members: &NO_MEMBERS,
        };
        let to = if l.resolves {
            format!("[[{}\\|{}]]", note_name(&l.to_qualified), l.to_qualified)
        } else {
            // Outside this workspace: there is no note to link to, and a wikilink
            // to a note that does not exist reads in Obsidian as one that is
            // merely unwritten.
            format!("`{}` *(outside this workspace)*", l.to_qualified)
        };
        // `declared` rather than a confidence score: an authored link carries no
        // score by construction, so an empty cell there would read as "confidence
        // unknown" instead of "not that kind of claim".
        let how = if l.authored {
            " *(declared)*".to_owned()
        } else {
            confidence(l.confidence)
        };
        let _ = writeln!(
            c,
            "| [[{}\\|{}]] | {} | {to} | {}{how} |",
            scoped_note_name(&from_scope, &l.from_key),
            l.from_name,
            l.from_project,
            l.kind,
        );
    }
    if ws.cross_links_total > ws.cross_links.len() {
        let _ = writeln!(
            c,
            "\n*Showing {} of {} — the full report is `roteiro links --matrix`.*",
            ws.cross_links.len(),
            ws.cross_links_total
        );
    }
    c.push_str(
        "\n*Shown in one direction only. The edge lives in the spoke's store, \
         pointing at a local placeholder for the hub's node, so the hub's own note \
         carries no matching **Incoming** entry — Obsidian's **Backlinks** pane \
         still shows it, because the link is in the vault.*\n",
    );
}

#[cfg(test)]
mod tests {
    use super::{
        AdrEntry, ConfigSecretSummary, CouplingEntry, Coverage, CrossLink, DensityEntry,
        FindingEntry, HOME_NOTE, MemberPin, RenderedUnder, VaultScope, VaultSummary,
        WorkspaceSummary, note_name, render_home, render_note, render_note_scoped,
        render_workspace_home, scoped_note_name,
    };
    use rto_graph::{EdgeRef, Explanation, NodeSummary};

    /// The shape of a name, pinned once so a change to it is a deliberate edit
    /// here rather than a diff spread over twenty other assertions.
    ///
    /// Everything else in this module composes `note_name` instead of repeating
    /// its output, because those tests are about *which key a link points at* and
    /// were never about the spelling.
    #[test]
    fn note_name_is_a_lowercase_hint_and_a_hash_of_the_whole_key() {
        assert_eq!(
            note_name("sym:rust:src/a.rs#Store"),
            "sym-rust-src-a.rs-store-b4cbf6633003361f"
        );
        assert_eq!(note_name("adr:0001"), "adr-0001-559a2e837953b2ff");
        assert_eq!(
            note_name("file:src/main.rs"),
            "file-src-main.rs-4a72627453f6780e"
        );
        // Deterministic: the suffix is a pure function of the key, so a vault
        // renders the same names on every machine and every run.
        assert_eq!(note_name("adr:0001"), note_name("adr:0001"));
    }

    /// **The property `note_name` exists to have** (issue #574): distinct keys
    /// give distinct notes *on a case-folding filesystem*, which is where the
    /// vault was losing them.
    ///
    /// Asserted over lowercased names, not names. On macOS and Windows two names
    /// differing only in case are one file, so a name set that is distinct as
    /// strings can still be a vault with notes missing — and Linux CI cannot see
    /// it. Folding here makes the assertion say what the filesystem says, on
    /// every platform.
    ///
    /// The keys are the two mechanisms that were actually losing notes, taken
    /// from this repository's own render rather than invented: the vendored
    /// `cytoscape.min.js` bundle whose minified single-letter symbols differ only
    /// by a sigil or by case, and a pair of grouped Rust `use` keys differing
    /// only by a trailing comma. `render_cli` runs the same assertion end to end
    /// over a rendered vault; this is the unit-level statement of it.
    #[test]
    fn distinct_keys_give_distinct_notes_even_after_case_folding() {
        const JS: &str = "sym:javascript:crates/roteiro/src/assets/cytoscape.min.js";
        let keys: Vec<String> = [
            // Slug lossiness: the sigil and the letter both slugged to the same
            // thing (9 notes lost this way, on every platform).
            format!("{JS}#$a"),
            format!("{JS}#a"),
            format!("{JS}#$o"),
            format!("{JS}#o"),
            // Case folding: distinct names, one file (95 notes lost this way, and
            // only on macOS and Windows).
            format!("{JS}#A"),
            format!("{JS}#O"),
            format!("{JS}#S"),
            format!("{JS}#s"),
            // Real source symbols, same shape.
            "sym:rust:crates/rto-exec/src/sandbox_store.rs#Store".into(),
            "sym:rust:crates/rto-exec/src/sandbox_store.rs#store".into(),
            // A trailing comma is the whole difference between these two.
            "import:rust:crate::engine::{ChatRequest,Engine,ModelInfo,}".into(),
            "import:rust:crate::engine::{ChatRequest,Engine,ModelInfo}".into(),
            // Nothing but separators: no hint at all, so the name is bare hash.
            "::".into(),
            "##".into(),
            // Over the length bound, differing only past the truncation point —
            // the case truncation alone used to merge.
            format!("import:rust:{}A", "a::b::c,".repeat(60)),
            format!("import:rust:{}a", "a::b::c,".repeat(60)),
        ]
        .into();

        let folded: std::collections::BTreeSet<String> =
            keys.iter().map(|k| note_name(k).to_lowercase()).collect();
        assert_eq!(
            folded.len(),
            keys.len(),
            "two keys share a note after case folding; the vault would hold one \
             file for both and report two"
        );
    }

    /// Case folding is the identity on a note name, so the assertion above is not
    /// weaker than the filesystem it stands in for.
    ///
    /// This is the reason the hint is lowercased rather than case-preserved: it
    /// makes "distinct names" and "distinct files on macOS" the same statement,
    /// so there is no version of this module that passes on Linux and loses notes
    /// on a Mac. Without it, the two assertions could drift apart and only the
    /// weaker one would ever run in CI.
    #[test]
    fn a_note_name_is_already_lowercase() {
        for key in [
            "sym:rust:src/a.rs#Store",
            "file:README.md",
            "app::file:CHANGELOG.md",
            "sym:javascript:a.js#ABC",
        ] {
            let name = note_name(key);
            assert_eq!(name, name.to_lowercase(), "`{key}` kept case in its name");
        }
    }

    /// `_Home` is a name in the same namespace as every note, and it is not
    /// derived from a key — so nothing must be able to collide with it. The
    /// mandatory suffix gives that for free: every generated name either ends in
    /// `-<16 hex>` or *is* 16 hex digits, and `_home` is neither.
    #[test]
    fn no_key_can_claim_the_home_note() {
        for key in ["_Home", "file:_Home", "_home", "::_Home::"] {
            assert_ne!(
                format!("{}.md", note_name(key)).to_lowercase(),
                HOME_NOTE.to_lowercase(),
                "`{key}` would overwrite the overview note"
            );
        }
    }

    #[test]
    fn render_note_emits_frontmatter_and_wikilinks() {
        let ex = Explanation {
            schema: rto_graph::SCHEMA,
            node: NodeSummary {
                key: "sym:rust:a.rs#main".into(),
                kind: "fn".into(),
                name: "main".into(),
                path: Some("a.rs".into()),
                lang: Some("rust".into()),
            },
            meta: serde_json::Value::Null,
            outgoing: vec![EdgeRef {
                kind: "calls".into(),
                provenance: "derived",
                confidence: None,
                node: "sym:rust:a.rs#helper".into(),
            }],
            incoming: vec![EdgeRef {
                kind: "references".into(),
                provenance: "authored",
                confidence: None,
                node: "adr:0001".into(),
            }],
        };
        let note = render_note(&ex, None, None);
        assert_eq!(
            note.filename,
            format!("{}.md", note_name("sym:rust:a.rs#main"))
        );
        assert!(note.content.contains("kind: fn"));
        // No source base → no Source link.
        assert!(!note.content.contains("**Source:**"));
        assert!(note.content.contains("# main"));
        assert!(note.content.contains(&format!(
            "- calls (derived) → [[{}]]",
            note_name("sym:rust:a.rs#helper")
        )));
        assert!(note.content.contains(&format!(
            "- [[{}]] references (authored) →",
            note_name("adr:0001")
        )));
        // Tags for the graph view.
        assert!(note.content.contains("- roteiro/kind/fn"));
        assert!(note.content.contains("- roteiro/lang/rust"));
    }

    #[test]
    fn note_name_bounds_long_keys_deterministically() {
        let long = format!("import:rust:{}", "a::b::c,".repeat(60));
        let a = note_name(&long);
        let b = note_name(&long);
        assert_eq!(a, b, "deterministic");
        assert!(
            a.len() <= 205,
            "bounded under the filename limit: {}",
            a.len()
        );
        assert_ne!(
            note_name(&format!("{long}x")),
            a,
            "different keys stay distinct after truncation"
        );
        // Truncation must not leave a doubled separator before the suffix — the
        // hint is trimmed after cutting, not before.
        assert!(!a.contains("--"), "{a}");
    }

    /// A short key is bounded too, and every name carries the suffix — the hash
    /// is no longer reached for only when the hint overruns.
    ///
    /// That gating was the defect (#574): two keys short enough to skip the hash
    /// had nothing left to tell them apart once the slug had flattened them.
    #[test]
    fn every_name_carries_the_hash_however_short_the_key() {
        for key in ["a", "adr:0001", "file:README.md"] {
            let name = note_name(key);
            let (hint, hash) = name.rsplit_once('-').expect("a suffixed name");
            assert!(!hint.is_empty(), "{name}");
            assert_eq!(hash.len(), 16, "{name}");
            assert!(
                hash.chars().all(|c| c.is_ascii_hexdigit()),
                "the suffix is the key's hash, not part of the hint: {name}"
            );
        }
        // A key with no hint at all is the bare hash, which cannot be mistaken
        // for a hinted name (those are at least 18 characters).
        let bare = note_name("::");
        assert_eq!(bare.len(), 16, "{bare}");
        assert!(!bare.contains('-'), "{bare}");
    }

    #[test]
    fn render_note_surfaces_content_and_status() {
        let ex = Explanation {
            schema: rto_graph::SCHEMA,
            node: NodeSummary {
                key: "adr:0001".into(),
                kind: "adr".into(),
                name: "Build Roteiro".into(),
                path: Some("docs/adr/0001.md".into()),
                lang: None,
            },
            meta: serde_json::json!({ "status": "Accepted", "content": "The decision text." }),
            outgoing: vec![],
            incoming: vec![],
        };
        let note = render_note(&ex, Some("https://github.com/org/repo/blob/abc123"), None);
        assert!(note.content.contains("status: Accepted"));
        assert!(note.content.contains("- roteiro/status/accepted"));
        assert!(note.content.contains("> **Status:** Accepted"));
        assert!(note.content.contains("## Content\n\nThe decision text."));
        // A clickable link to the actual ADR file on the repository host.
        assert!(
            note.content.contains(
                "**Source:** [`docs/adr/0001.md`](https://github.com/org/repo/blob/abc123/docs/adr/0001.md)"
            ),
            "{}",
            note.content
        );
    }

    /// The structured document a prose note is supposed to reproduce: headings, a
    /// table and a fenced code block, none of which survive whitespace collapse.
    const DOC: &str = "# Working offline\n\nRoteiro is **offline-capable**.\n\n| Host | What |\n| --- | --- |\n| `example.com` | models |\n\n```sh\nroteiro model pull\n```\n";

    fn prose_note(content: Option<&str>) -> Explanation {
        Explanation {
            schema: rto_graph::SCHEMA,
            node: NodeSummary {
                key: "file:docs/OFFLINE_SETUP.md".into(),
                kind: "file".into(),
                name: "OFFLINE_SETUP.md".into(),
                path: Some("docs/OFFLINE_SETUP.md".into()),
                lang: None,
            },
            meta: content.map_or(
                serde_json::Value::Null,
                |c| serde_json::json!({ "content": c }),
            ),
            outgoing: vec![],
            incoming: vec![],
        }
    }

    /// The whole readability defect, in one assertion pair: a note built from
    /// `meta.content` alone is the document whitespace-collapsed onto one line,
    /// and a note built from the source is the document.
    ///
    /// The newline count is the claim. A character count alone would pass on a
    /// note that had merely grown longer while staying flat, which is exactly the
    /// failure being fixed — `meta.content` is capped *and* collapsed, and only
    /// the collapse is what makes it unreadable.
    #[test]
    fn a_supplied_body_supersedes_the_collapsed_stored_content() {
        // What extraction stores: the same text, whitespace-collapsed.
        let collapsed = DOC.split_whitespace().collect::<Vec<_>>().join(" ");
        let ex = prose_note(Some(&collapsed));

        let note = render_note(&ex, None, Some(DOC));
        assert!(
            note.content.contains(DOC.trim()),
            "the source document is reproduced verbatim: {}",
            note.content
        );
        assert!(
            !note.content.contains(&collapsed),
            "the collapsed rendering is replaced, not appended: {}",
            note.content
        );
        assert!(
            note.content.contains("\n| Host | What |\n"),
            "a table needs its own lines to be a table: {}",
            note.content
        );
        assert!(
            note.content.contains("\n```sh\n"),
            "a fenced block needs its own lines to be a fence: {}",
            note.content
        );

        // The flat control: the same node with no body is the one-line note.
        let flat = render_note(&ex, None, None);
        assert!(
            flat.content.contains(&collapsed),
            "without a body the stored content is still shown: {}",
            flat.content
        );
        assert!(
            content_lines(&note.content) > content_lines(&flat.content),
            "structure restored: {} line(s) with a body vs {} without",
            content_lines(&note.content),
            content_lines(&flat.content)
        );
        assert_eq!(
            content_lines(&flat.content),
            1,
            "the defect: the stored content is a single line"
        );
    }

    /// A doc comment is a summary of a definition, not a document, and its note is
    /// correct as it stands. The caller supplies no body for these, so this pins
    /// the unchanged path — the fix must not depend on every node gaining one.
    #[test]
    fn a_note_with_no_body_is_unchanged() {
        let ex = Explanation {
            schema: rto_graph::SCHEMA,
            node: NodeSummary {
                key: "sym:rust:a.rs#main".into(),
                kind: "fn".into(),
                name: "main".into(),
                path: Some("a.rs".into()),
                lang: Some("rust".into()),
            },
            meta: serde_json::json!({ "content": "Entry point." }),
            outgoing: vec![],
            incoming: vec![],
        };
        assert!(
            render_note(&ex, None, None)
                .content
                .contains("## Content\n\nEntry point.")
        );
    }

    /// Lines in the note's `## Content` section.
    fn content_lines(note: &str) -> usize {
        let body = note
            .split_once("## Content\n\n")
            .map_or("", |(_, rest)| rest);
        let body = body.split_once("\n## ").map_or(body, |(head, _)| head);
        body.trim_end().lines().count()
    }

    #[test]
    fn render_note_shows_inferred_confidence() {
        let ex = Explanation {
            schema: rto_graph::SCHEMA,
            node: NodeSummary {
                key: "file:a.md".into(),
                kind: "file".into(),
                name: "a.md".into(),
                path: Some("a.md".into()),
                lang: None,
            },
            meta: serde_json::Value::Null,
            outgoing: vec![EdgeRef {
                kind: "related".into(),
                provenance: "inferred",
                confidence: Some(0.82),
                node: "file:b.md".into(),
            }],
            incoming: vec![],
        };
        let note = render_note(&ex, None, None);
        assert!(
            note.content.contains(&format!(
                "related (inferred) (0.82) → [[{}]]",
                note_name("file:b.md")
            )),
            "{}",
            note.content
        );
    }

    /// The single-project `_Home` fixture, extracted so the test that reads its
    /// rendering stays about the rendering. Every field is populated: the
    /// sections it drives are individually omitted when empty, so a partial
    /// fixture would silently stop exercising them.
    fn home_summary() -> VaultSummary {
        VaultSummary {
            project: "demo".into(),
            total_nodes: 3,
            total_edges: 2,
            node_counts: vec![("fn".into(), 2), ("adr".into(), 1)],
            edge_provenance: vec![("derived".into(), 1), ("authored".into(), 1)],
            adrs: vec![AdrEntry {
                key: "adr:0001".into(),
                name: "First".into(),
                status: Some("Accepted".into()),
            }],
            debt: vec![("todo".into(), 4)], // roteiro:ignore
            densest_files: vec![DensityEntry {
                path: "src/small.rs".into(),
                markers: 3,
                lines: 120,
                per_kloc: 25.0,
            }],
            config_secrets: Some(ConfigSecretSummary {
                secret_named: 4,
                redacted: 3,
                declared: 1,
                unredacted: 0,
                files: vec![".env".into()],
            }),
            most_called: vec![CouplingEntry {
                key: "sym:rust:a.rs#helper".into(),
                name: "helper".into(),
                fan_in: 7,
                fan_out: 1,
            }],
            repo_url: Some("https://github.com/org/repo".into()),
            commit: Some("abcdef0123456789".into()),
            findings: vec![],
            coverage: Coverage::NotRun,
            settings: RenderedUnder::default(),
        }
    }

    #[test]
    fn render_home_summarises_the_graph() {
        let summary = home_summary();
        let note = render_home(&summary);
        assert_eq!(note.filename, HOME_NOTE);
        assert!(note.content.contains("# demo — knowledge graph"));
        assert!(note.content.contains("**3 nodes**, **2 edges**"));
        assert!(note.content.contains("| fn | 2 |"));
        assert!(note.content.contains("| derived | 1 |"));
        assert!(note.content.contains(&format!(
            "**Accepted** — [[{}|First]]",
            note_name("adr:0001")
        )));
        assert!(note.content.contains("| todo | 4 |")); // roteiro:ignore
        // Directed coupling: the two fans are separate columns, and the wikilink's
        // own `|` is escaped so it cannot break the table it sits in.
        assert!(
            note.content.contains(&format!(
                "| [[{}\\|helper]] | 7 | 1 |",
                note_name("sym:rust:a.rs#helper")
            )),
            "{}",
            note.content
        );
        assert!(
            note.content.contains("resolved by simple name"),
            "the precision caveat travels with the figures"
        );
        // Density: the count and the denominator are both shown, so the ratio can
        // be checked rather than taken on trust, and the wikilink's own `|` is
        // escaped so it cannot break the table it sits in.
        assert!(
            note.content.contains(&format!(
                "| [[{}\\|src/small.rs]] | 3 | 120 | 25.00 |",
                note_name("file:src/small.rs")
            )),
            "{}",
            note.content
        );
        assert!(
            note.content.contains("not source lines of code"),
            "the denominator caveat travels with the figures"
        );
        // Config secrets: counts and files, and no key names — a vault note is
        // browsed out of context, which is the wrong place for a list that would
        // read as a secret scan's output.
        assert!(
            note.content.contains(
                "**4** secret-named config key(s): 3 redacted before storage, 1 \
                 declared in code without a value, 0 unredacted."
            ),
            "{}",
            note.content
        );
        assert!(
            note.content
                .contains(&format!("- [[{}\\|.env]]", note_name("file:.env"))),
            "{}",
            note.content
        );
        assert!(
            note.content.contains("not a secret scan")
                && note.content.contains("cannot see a hardcoded credential"),
            "the limitation travels with the figures: {}",
            note.content
        );
        assert!(
            !note.content.contains("[!warning]"),
            "no warning when nothing is unredacted: {}",
            note.content
        );
        // A repository link + short-commit permalink note.
        assert!(
            note.content
                .contains("**Repository:** [https://github.com/org/repo](https://github.com/org/repo) · rendered at commit `abcdef012345`"),
            "{}",
            note.content
        );
    }

    #[test]
    fn render_home_omits_density_for_a_graph_with_no_markers() {
        // A clean repository has no markers, so there is no density to rank. An
        // empty table under a heading reads as "measured, and there is nothing";
        // the section is absent instead. Same rule as the coupling table below.
        let note = render_home(&VaultSummary {
            project: "clean".into(),
            total_nodes: 1,
            ..VaultSummary::default()
        });
        assert!(
            !note.content.contains("Densest files"),
            "no heading without rows: {}",
            note.content
        );
        // The intent-debt section itself still renders — density is an addition
        // to it, not a replacement.
        assert!(note.content.contains("## Intent debt"));
        assert!(note.content.contains("*None recorded.*"));
    }

    #[test]
    fn render_home_omits_config_secrets_rather_than_rendering_zeroes() {
        // A row of zeroes under this heading would read as "scanned, and clean" —
        // a conclusion the lens cannot support, since a credential under an
        // innocuous key name never appears in it. The section is absent instead.
        let note = render_home(&VaultSummary {
            project: "clean".into(),
            total_nodes: 1,
            ..VaultSummary::default()
        });
        assert!(
            !note.content.contains("named like secrets"),
            "no heading without figures: {}",
            note.content
        );
    }

    #[test]
    fn render_home_warns_loudly_about_an_unredacted_value() {
        // Extraction cannot produce this state, so if it appears something else
        // put an unredacted value in the store — and the note must say where to
        // look rather than implicating the repository.
        let note = render_home(&VaultSummary {
            project: "imported".into(),
            total_nodes: 1,
            config_secrets: Some(ConfigSecretSummary {
                secret_named: 1,
                redacted: 0,
                declared: 0,
                unredacted: 1,
                files: vec!["imported.env".into()],
            }),
            ..VaultSummary::default()
        });
        assert!(
            note.content.contains("[!warning]") && note.content.contains("**unredacted**"),
            "{}",
            note.content
        );
        assert!(
            note.content.contains("came from an import layer"),
            "and it points at the importing tool, not the repository: {}",
            note.content
        );
    }

    #[test]
    fn render_home_omits_coupling_for_a_graph_with_no_calls() {
        // A prose-only vault has no `calls` edges. An empty table under a heading
        // reads as "measured, and there is nothing" — the section is absent instead.
        let note = render_home(&VaultSummary {
            project: "docs".into(),
            total_nodes: 1,
            ..VaultSummary::default()
        });
        assert!(
            !note.content.contains("Most depended-on"),
            "no heading without rows: {}",
            note.content
        );
        // The rest of the overview is unaffected.
        assert!(note.content.contains("# docs — knowledge graph"));
    }

    // ---- Workspace vaults (issue #442 part 1) --------------------------------

    /// A `Explanation` for `key`, with one outgoing edge to `to`.
    fn node_linking_to(key: &str, name: &str, to: &str) -> Explanation {
        Explanation {
            schema: rto_graph::SCHEMA,
            node: NodeSummary {
                key: key.into(),
                kind: "config_key".into(),
                name: name.into(),
                path: Some("config.toml".into()),
                lang: None,
            },
            meta: serde_json::Value::Null,
            outgoing: vec![EdgeRef {
                kind: "links".into(),
                provenance: "inferred",
                confidence: Some(0.91),
                node: to.into(),
            }],
            incoming: vec![],
        }
    }

    fn members(names: &[&str]) -> std::collections::BTreeSet<String> {
        names.iter().map(|s| (*s).to_owned()).collect()
    }

    /// **Rewritten deliberately under #574.** #570 landed this as "a project
    /// scope leaves every note name exactly as it was", and read that two ways at
    /// once: `PROJECT` reduces to `note_name`, *and* `note_name` itself does not
    /// move. #574 breaks the second half on purpose — the old names were not
    /// injective under filename case folding and this repository's vault lost 104
    /// notes to it — so the two halves are separated here rather than having
    /// expected values quietly updated underneath the old title.
    ///
    /// What survives is the half #570 was actually about, and it is unweakened:
    /// **turning workspace mode on must not rename a project's notes.** Names may
    /// move when `note_name` changes, for a reason argued at `note_name`; they may
    /// never move because a repository happens to sit inside a configured
    /// workspace, because that would happen by inference rather than by a release.
    ///
    /// The other half of #570's promise — that a project render is byte-identical
    /// apart from names — is now [`render_note_is_the_project_scoped_render_byte_for_byte`]
    /// and `render_cli`'s end-to-end pair.
    #[test]
    fn a_project_scope_never_qualifies_a_name() {
        // A user's own notes live outside the vault and link into it *by name*
        // (#442), so a rename breaks them silently, with no error and nothing to
        // grep for. Whatever workspace mode does, `VaultScope::PROJECT` must
        // reduce to `note_name` of the bare key.
        for key in [
            "file:README.md",
            "adr:0001",
            "sym:rust:src/a.rs#Store",
            "extref:other::file:README.md",
            "cfgkey:config.toml#serve.addr",
        ] {
            assert_eq!(
                scoped_note_name(&VaultScope::PROJECT, key),
                note_name(key),
                "single-project name moved for `{key}`"
            );
            // And the qualified form really is a different name, so the assertion
            // above is not vacuously true of every scope.
            let ms = members(&["app"]);
            assert_ne!(
                scoped_note_name(
                    &VaultScope {
                        project: Some("app"),
                        members: &ms,
                    },
                    key
                ),
                note_name(key),
                "qualification must move the name for `{key}`, or nothing above holds"
            );
        }
    }

    #[test]
    fn render_note_is_the_project_scoped_render_byte_for_byte() {
        let ex = node_linking_to("cfgkey:config.toml#addr", "addr", "sym:rust:a.rs#A");
        assert_eq!(
            render_note(&ex, Some("https://h/b"), Some("body")),
            render_note_scoped(&ex, Some("https://h/b"), Some("body"), &VaultScope::PROJECT),
            "the unscoped entry point must stay the scoped one at PROJECT, so the \
             two cannot drift apart"
        );
    }

    #[test]
    fn each_member_gets_its_own_note_for_the_same_key() {
        // The collision the whole feature exists for: node keys are
        // repository-relative, so every member's `README.md` is `file:README.md`.
        let ms = members(&["api", "sdk"]);
        let names: Vec<String> = ["api", "sdk"]
            .iter()
            .map(|p| {
                scoped_note_name(
                    &VaultScope {
                        project: Some(p),
                        members: &ms,
                    },
                    "file:README.md",
                )
            })
            .collect();
        assert_eq!(
            names,
            [
                note_name("api::file:README.md"),
                note_name("sdk::file:README.md")
            ]
        );
        assert_ne!(names[0], names[1], "two members must not share one note");
    }

    /// The two names this feature has, pinned together in one place.
    ///
    /// They are easy to conflate and were, in this PR, described inconsistently
    /// in two doc comments — the **key** is `<project>::<key>` (ADR-0009's
    /// cross-repo form, which is why cross-repo links resolve), and the **note
    /// name** is [`note_name`] of that key, in which `::` has become `-`. A
    /// reader told the wrong one goes looking for a file with `::` in it.
    ///
    /// Asserting both here means the next description that drifts has something
    /// to disagree with, rather than waiting for a reviewer to read two comments
    /// side by side.
    #[test]
    fn the_qualified_key_and_the_note_name_are_different_strings() {
        let ms = members(&["app"]);
        let scope = VaultScope {
            project: Some("app"),
            members: &ms,
        };
        // The key: project-qualified, `::` intact — this is what the graph and
        // ADR-0009's external refs use.
        let qualified = "app::file:README.md";
        // The note name: `note_name` of exactly that key, `::` slugged to `-`,
        // the whole hint lowercased, and the key's own hash appended.
        assert_eq!(
            scoped_note_name(&scope, "file:README.md"),
            "app-file-readme.md-a114bde6dcaba1c1"
        );
        assert_eq!(note_name(qualified), "app-file-readme.md-a114bde6dcaba1c1");
        assert!(
            !scoped_note_name(&scope, "file:README.md").contains("::"),
            "no note name ever contains `::`"
        );
        // And on disk the stem gains the extension, which is the string a reader
        // actually looks for.
        let note = render_note_scoped(
            &node_with("file:README.md", Some("README.md"), None),
            None,
            None,
            &scope,
        );
        assert_eq!(note.filename, "app-file-readme.md-a114bde6dcaba1c1.md");
    }

    /// `_Home` must *show* a name, not spell the form out.
    ///
    /// The test above pins the distinction in the code. It did not stop the
    /// distinction being described wrongly in the same file, because it guards
    /// the function and not the sentences: `render_workspace_home` went on
    /// writing the pre-#574 form into the `_Home` of every workspace vault
    /// v2.0.0 built, and nothing here disagreed with it.
    ///
    /// So this asserts the property that made that possible is gone — the
    /// paragraph now contains a string `note_name` actually produced for a key
    /// the workspace really holds, which a hand-written spelling cannot
    /// satisfy. It is not a tautology despite both sides calling `note_name`:
    /// what it rejects is the *shape* of the old copy, a form written out by
    /// hand next to the function that could have rendered it.
    ///
    /// That the *key* is real is the other half, and the reason the example is
    /// drawn from `cross_links` rather than invented from the member list —
    /// a name rendered for a node the vault does not hold is a true sentence
    /// about a note nobody can open. The empty case is
    /// `the_workspace_home_claims_no_example_note_when_it_has_no_real_key`.
    fn finding(rule: &str, severity: &str, message: &str) -> FindingEntry {
        FindingEntry {
            rule: rule.to_owned(),
            severity: severity.to_owned(),
            title: "a title".to_owned(),
            message: message.to_owned(),
            path: Some("Cargo.lock".to_owned()),
            analyzer: "osv-scanner".to_owned(),
        }
    }

    fn ws_with(members: Vec<VaultSummary>) -> WorkspaceSummary {
        WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members,
            pins: Vec::new(),
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        }
    }

    /// An analyzer message is **tool output** being embedded in a document that
    /// gets handed to people. It must be quoted, never absorbed: a message
    /// carrying its own fence would otherwise close the block early and spill the
    /// rest into the note as vault prose — headings and links included.
    #[test]
    fn an_analyzer_message_cannot_break_out_of_its_fence() {
        let mut api = member_summary("api", 1);
        api.coverage = Coverage::Ran(vec![("osv-scanner".into(), "1.9.0".into())]);
        api.findings = vec![finding(
            "GHSA-x",
            "high",
            "before
```
## not a vault heading
```
after",
        )];
        let c = render_workspace_home(&ws_with(vec![api])).content;

        // The fence opened must be longer than any run inside the message, so the
        // message's own ``` is content rather than a terminator.
        assert!(
            c.contains("````text"),
            "fence widened past the message's own: {c}"
        );
        assert!(
            c.contains("## not a vault heading"),
            "and the text is still all there: {c}"
        );
        // Nothing between the finding and the next section may be loose prose.
        let after = c.split("````text").nth(1).expect("a fenced block");
        let body = after.split("````").next().expect("a closing fence");
        assert!(
            body.contains("## not a vault heading"),
            "the heading is INSIDE the fence, not outside it: {body}"
        );
    }

    /// The fence secured the **message**. Every other analyzer-sourced field on a
    /// finding is interpolated into a line of prose, and they come from the same
    /// place — so a title carrying a newline used to end its line and start a new
    /// block, which can open a heading the vault never wrote.
    #[test]
    fn every_analyzer_sourced_field_is_quoted_not_absorbed() {
        let mut api = member_summary("api", 1);
        api.coverage = Coverage::Ran(vec![("osv-scanner".into(), "1.9.0".into())]);
        api.findings = vec![FindingEntry {
            // Each field carries a different escape hatch.
            rule: "R-1`x".to_owned(),
            severity: "high".to_owned(),
            // Newlines, a heading, a link, and a list marker — the last of which
            // no escape set covers, so only the whitespace collapse stops it.
            title: "broken\n\n## an injected heading\n\n- a list item\n\n[a link](http://evil)"
                .to_owned(),
            message: "fine".to_owned(),
            path: Some("src/a`b.rs".to_owned()),
            analyzer: "osv-scanner".to_owned(),
        }];
        let c = render_workspace_home(&ws_with(vec![api])).content;

        assert!(
            !c.contains("\n## an injected heading"),
            "a newline in a title must not start a block: {c}"
        );
        assert!(
            !c.contains("[a link](http://evil)"),
            "and a link must not survive as a link: {c}"
        );
        // The text is still readable — escaped, not deleted. Losing it would be a
        // different failure: a finding whose title vanished is a finding nobody
        // acts on.
        assert!(c.contains("an injected heading"), "the words remain: {c}");
        // A widened delimiter, not a backslash: inside a span the backslash
        // would show, and `vendor/**` would reach the reader as `vendor\*\*`.
        assert!(
            c.contains("``R-1`x``"),
            "the span widens past the backtick inside it: {c}"
        );

        // The structural property, asserted directly rather than inferred from
        // the absence of a heading: the whole finding stays on **one line**. An
        // escape set can neutralise `#` and `[`, and a newline would still end
        // the line and start a block — and nothing escapes a `-` list marker.
        let line = c
            .lines()
            .find(|l| l.contains("R-1"))
            .unwrap_or_else(|| panic!("the finding renders: {c}"));
        assert!(
            line.contains("a link") && line.contains("a list item"),
            "every part of the title stays on the finding's own line: {line}"
        );
    }

    /// The analyzer name is interpolated into **raw HTML** (`<sub>`,
    /// `<details><summary>`), where a backslash escapes nothing. Fixing the
    /// Markdown surface and leaving this one is how the first version of the
    /// escaping shipped.
    #[test]
    fn analyzer_text_cannot_break_out_of_the_html_it_sits_in() {
        let mut api = member_summary("api", 1);
        let hostile = "osv</sub><script>alert(1)</script>".to_owned();
        api.coverage = Coverage::Ran(vec![(hostile.clone(), "1.0".into())]);
        api.findings = vec![FindingEntry {
            rule: "R-1".to_owned(),
            severity: "high".to_owned(),
            title: "t".to_owned(),
            message: "m".to_owned(),
            path: None,
            analyzer: hostile,
        }];
        let c = render_workspace_home(&ws_with(vec![api])).content;

        assert!(
            !c.contains("<script>"),
            "a tag in analyzer text must not survive as a tag: {c}"
        );
        assert!(
            !c.contains("osv</sub>"),
            "and must not close the element it was placed inside: {c}"
        );
        // Escaped, not dropped: the reader still sees which analyzer said it.
        assert!(c.contains("&lt;script&gt;"), "the text remains, inert: {c}");
    }

    /// `[debt] ignore` is user config, not analyzer output — but the vault did
    /// not write it either, and it lands in a table cell where a `|` reshapes
    /// the row.
    #[test]
    fn a_config_glob_cannot_reshape_the_settings_table() {
        let mut api = member_summary("api", 1);
        api.settings = RenderedUnder {
            ingest: vec!["prose".into()],
            debt_ignore: vec!["a`b|c".into()],
        };
        let c = render_workspace_home(&ws_with(vec![api])).content;
        // Scoped to the settings table. The manifest table above it also has a
        // row starting `| api |`, and a bare `.find` matched *that* one — so the
        // first version of this test asserted against a row containing no glob
        // at all, and stayed green with the escaping removed.
        let section = c
            .split("### Rendered under")
            .nth(1)
            .unwrap_or_else(|| panic!("the settings section: {c}"));
        let row = section
            .lines()
            .find(|l| l.starts_with("| api |"))
            .unwrap_or_else(|| panic!("a settings row: {section}"));
        // Count **cell delimiters**, not `|` characters: an escaped `\|` is
        // content, and GFM does not split on it. Counting raw pipes would fail
        // on the correct output and pass on some wrong ones.
        let delimiters = row
            .char_indices()
            .filter(|&(i, ch)| ch == '|' && !row[..i].ends_with('\\'))
            .count();
        assert_eq!(
            delimiters, 4,
            "the row keeps exactly its own four cell delimiters: {row}"
        );
    }

    /// The manifest is a table too. `table_cell` was written for the settings
    /// table and not applied to this one, thirty lines above it — a remote URL
    /// and a project name both come from git rather than from us.
    #[test]
    fn a_remote_url_cannot_reshape_the_manifest_row() {
        let mut api = member_summary("api", 1);
        api.repo_url = Some("https://host/a|b/c".to_owned());
        api.commit = Some("dead`beef".to_owned());
        let c = render_workspace_home(&ws_with(vec![api])).content;

        let section = c
            .split("## Reproducing this vault")
            .nth(1)
            .unwrap_or_else(|| panic!("the manifest: {c}"));
        let row = section
            .lines()
            .find(|l| l.starts_with("| api |"))
            .unwrap_or_else(|| panic!("a manifest row: {section}"));
        let delimiters = row
            .char_indices()
            .filter(|&(i, ch)| ch == '|' && !row[..i].ends_with('\\'))
            .count();
        assert_eq!(
            delimiters, 4,
            "the row keeps exactly its own four cell delimiters: {row}"
        );
        assert!(
            row.contains("``dead`beef``"),
            "and a backtick in a sha widens its span: {row}"
        );
    }

    /// Escaping `[` stops explicit link syntax and nothing else. Obsidian and
    /// GFM linkify a bare URL, so analyzer text could still hand the reader
    /// something clickable in a document they were given.
    #[test]
    fn a_bare_url_in_analyzer_text_is_not_left_clickable() {
        let mut api = member_summary("api", 1);
        api.coverage = Coverage::Ran(vec![("osv-scanner".into(), "1.9.0".into())]);
        api.findings = vec![FindingEntry {
            rule: "R-1".to_owned(),
            severity: "high".to_owned(),
            title: "see https://evil.example/path for details".to_owned(),
            message: "m".to_owned(),
            path: None,
            analyzer: "osv-scanner".to_owned(),
        }];
        let c = render_workspace_home(&ws_with(vec![api])).content;

        assert!(
            !c.contains("https://evil.example"),
            "a bare URL must not survive in linkifiable form: {c}"
        );
        // Rendered identically for a reader, and still copyable — defusing it
        // must not amount to hiding it.
        assert!(c.contains("https&#58;//evil.example/path"), "{c}");
    }

    /// The two empty states are opposite facts and must never render alike.
    #[test]
    fn an_unanalyzed_member_never_reads_as_one_that_came_back_clean() {
        let mut looked = member_summary("api", 1);
        looked.coverage = Coverage::Ran(vec![("osv-scanner".into(), "1.9.0".into())]);
        let never = member_summary("sdk", 1); // Coverage::NotRun by default
        let c = render_workspace_home(&ws_with(vec![looked, never])).content;

        assert!(c.contains("### api — no findings"), "{c}");
        assert!(
            c.contains("osv-scanner` 1.9.0 ran and reported none"),
            "{c}"
        );
        assert!(c.contains("### sdk — **not analyzed**"), "{c}");
        assert!(
            !c.contains("### sdk — no findings"),
            "an unanalyzed member must never be rendered as clean: {c}"
        );
        assert!(c.contains("1 never analyzed at all"), "counted too: {c}");
    }

    /// The severity a finding carries is the **analyzer's** word. An unrecognised
    /// level is rendered as given rather than mapped onto a known rung, because
    /// mapping it would be inventing a judgement the tool did not make.
    #[test]
    fn an_unrecognised_severity_keeps_the_analyzers_own_label() {
        let mut api = member_summary("api", 1);
        api.coverage = Coverage::Ran(vec![("semgrep".into(), "1.2.3".into())]);
        api.findings = vec![finding("R-1", "WARNING", "msg")];
        let c = render_workspace_home(&ws_with(vec![api])).content;
        assert!(c.contains("**`WARNING`**"), "{c}");
    }

    /// #442: the manifest records what each member **deploys**, not only the
    /// commit it was rendered at — and each pin names the hub it is relative to.
    ///
    /// A snowflake fixture on purpose (`infra → chart → app`), because a star
    /// would let a bare-revision column pass: it is only when a workspace has two
    /// levels that "the hub version" stops having one answer. And deliberately
    /// mixed — one dependency resolves, one does not — so the row that reports
    /// *finding nothing* is exercised rather than assumed.
    #[test]
    fn the_manifest_records_each_members_pin_and_which_hub_it_is_relative_to() {
        let ws = WorkspaceSummary {
            generated_at: "2026-08-26T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![
                member_summary("infra", 3),
                member_summary("chart", 4),
                member_summary("app", 9),
            ],
            pins: vec![
                MemberPin {
                    member: "chart".into(),
                    hub: "app".into(),
                    rev: Some("1.4.0".into()),
                    via: Some("image acme/app:1.4.0".into()),
                },
                MemberPin {
                    member: "infra".into(),
                    hub: "chart".into(),
                    rev: None,
                    via: None,
                },
            ],
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let c = render_workspace_home(&ws).content;

        assert!(c.contains("### Version pins"), "{c}");
        // The hub is named per row. Without this the table is ambiguous the moment
        // a workspace has more than one level — which is exactly this fixture.
        assert!(
            c.contains("| chart | app | `1.4.0` |") || c.contains("| chart | app |"),
            "the pin names its hub: {c}"
        );
        assert!(
            c.contains("image acme/app:1.4.0"),
            "says where it read it: {c}"
        );

        // The unresolved dependency is REPORTED, not dropped. #505's rule: asked
        // and found nothing must not render as never asked.
        assert!(c.contains("| infra | chart |"), "the row survives: {c}");
        assert!(c.contains("(none detected)"), "and says so: {c}");

        // The count separates what was asked from what was found.
        assert!(
            c.contains("1 of 2 dependencies resolve"),
            "counts found against asked: {c}"
        );
    }

    /// A one-dependency workspace reads as English.
    ///
    /// Varying the noun and fixing the verb produced "1 of 1 dependency resolve",
    /// which is the failure mode of pluralising by hand: the two halves have to
    /// agree with the same count, not one of them with the count and the other
    /// with a guess. Two-member workspaces are common enough that this renders.
    #[test]
    fn the_pins_caption_agrees_with_a_single_dependency() {
        let ws = WorkspaceSummary {
            generated_at: "2026-08-26T10:00:00Z".to_owned(),
            name: "pair".into(),
            members: vec![member_summary("deploy", 2), member_summary("app", 5)],
            pins: vec![MemberPin {
                member: "deploy".into(),
                hub: "app".into(),
                rev: Some("1.4.0".into()),
                via: Some("image acme/app:1.4.0".into()),
            }],
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let c = render_workspace_home(&ws).content;
        assert!(
            c.contains("1 of 1 dependency resolves"),
            "singular noun and singular verb: {c}"
        );
    }

    /// A workspace whose members depend on nothing has no pins section at all —
    /// rather than an empty table, which reads as a fault.
    #[test]
    fn a_workspace_with_no_dependencies_has_no_pins_table() {
        let ws = WorkspaceSummary {
            generated_at: "2026-08-26T10:00:00Z".to_owned(),
            name: "solo".into(),
            members: vec![member_summary("only", 1)],
            pins: Vec::new(),
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let c = render_workspace_home(&ws).content;
        assert!(!c.contains("Version pins"), "{c}");
    }

    /// #442 part 2: the vault says how to reconstruct the workspace it describes,
    /// and what it deliberately leaves out.
    ///
    /// A vault that says *"here is my workspace"* is far less useful than one
    /// that says *"here is my workspace at these commits"* — and the exclusions
    /// are stated at the point a reader is most likely to share it, because that
    /// is when they matter.
    #[test]
    fn the_workspace_home_says_how_to_reproduce_itself_and_what_it_omits() {
        let mut api = member_summary("api", 7);
        api.repo_url = Some("https://github.com/acme/api".to_owned());
        api.commit = Some("4e0d5a6afd0b1c2d".to_owned());
        // Deliberately **mixed**: one member reproducible, one not. A fixture where
        // every member has a remote never exercises the row that says so, and the
        // gap is the thing a reader most needs to see.
        let mut sdk = member_summary("sdk", 4);
        sdk.repo_url = None;
        sdk.commit = None;
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![api, sdk],
            pins: Vec::new(),
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let c = render_workspace_home(&ws).content;

        assert!(c.contains("2026-08-22T10:00:00Z"), "stamped: {c}");
        assert!(c.contains("read-only and point-in-time"), "{c}");
        assert!(c.contains("https://github.com/acme/api"), "clone-from: {c}");
        assert!(c.contains("4e0d5a6afd0b1c2d"), "pinned commit: {c}");
        // A member with no remote is named as such rather than omitted — a gap in
        // the manifest is the reader's problem to know about, not ours to hide.
        assert!(c.contains("no `origin` remote"), "{c}");

        // The share-time warning, each item with its reason. Two of the three are
        // about what the vault *carries*, not what it omits — the owner ruled
        // findings in, so this section warns rather than reassures.
        assert!(
            c.contains("cannot be un-shared"),
            "including findings has a consequence, stated where it is acted on: {c}"
        );
        assert!(
            c.contains("Agent memory"),
            "the one genuine exclusion is still named: {c}"
        );
        assert!(
            c.contains("no redaction chokepoint"),
            "with its reason: {c}"
        );
        // The limit of what *is* included, which is narrower than it looks.
        assert!(
            c.contains("DATABASE_URL"),
            "the redaction gap is shown, not described: {c}"
        );
    }

    /// The manifest records the settings a re-render must match, because a clone
    /// URL and a commit get a reader the same **source** and not the same
    /// **vault**: `[ingest] prose` off produces notes with no captured content,
    /// and a `[debt] ignore` glob means the debt figures on the page are already
    /// filtered.
    #[test]
    fn the_manifest_records_the_settings_a_re_render_would_have_to_match() {
        let mut api = member_summary("api", 1);
        api.settings = RenderedUnder {
            ingest: vec!["prose".into(), "pdf".into()],
            debt_ignore: vec!["vendor/**".into()],
        };
        // A member with everything off is a real state, and must not render as a
        // blank cell that reads as "unknown".
        let sdk = member_summary("sdk", 1);
        let c = render_workspace_home(&ws_with(vec![api, sdk])).content;

        assert!(c.contains("### Rendered under"), "{c}");
        assert!(c.contains("`prose`, `pdf`"), "the enabled toggles: {c}");
        assert!(c.contains("`vendor/**`"), "the debt filter: {c}");
        assert!(
            c.contains("| sdk | *none* | *none* |"),
            "all-off is stated, not left blank: {c}"
        );
        assert!(
            c.contains("will not reproduce this document"),
            "and the section says why it is there: {c}"
        );
    }

    /// A workspace of purely local repositories cannot be reconstructed, and the
    /// vault says so instead of rendering a table of blanks — which would read as
    /// a fault rather than as repositories that were never pushed anywhere.
    #[test]
    fn a_vault_with_no_remotes_says_it_cannot_be_reconstructed() {
        // `member_summary` gives every member a remote, so it must be cleared —
        // the fixture has to actually be the case it names.
        let mut api = member_summary("api", 1);
        api.repo_url = None;
        api.commit = None;
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "local".into(),
            members: vec![api],
            pins: Vec::new(),
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let c = render_workspace_home(&ws).content;
        assert!(c.contains("cannot be reconstructed"), "{c}");
        assert!(
            !c.contains("| Member | Repository |"),
            "no empty table: {c}"
        );
    }

    /// #573: the cross-repo section distinguishes a **declaration** from a
    /// **match**, and says how many of each.
    ///
    /// Before authored links could be persisted, every row was a candidate and
    /// the section said so in one blanket caveat. That caveat is now false for
    /// declared rows, and an edge that exists but renders as a guess leaves
    /// ADR-0009's `authored → gold` path just as unreachable as no edge at all —
    /// so the rendering is part of the contract, not decoration.
    #[test]
    fn the_cross_repo_section_separates_declared_links_from_inferred_ones() {
        let link = |authored: bool, key: &str| CrossLink {
            from_project: "sdk".into(),
            from_key: format!("cfgkey:config.toml#{key}"),
            from_name: key.into(),
            kind: "references".into(),
            // A declaration carries no score by construction; a match does.
            confidence: if authored { None } else { Some(0.91) },
            to_qualified: format!("api::cfgkey:config.toml#{key}"),
            resolves: true,
            authored,
        };
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![member_summary("api", 7), member_summary("sdk", 4)],
            pins: Vec::new(),
            cross_links: vec![link(true, "addr"), link(false, "port")],
            // Totals deliberately **larger** than the two rows shown: the caption
            // is a statement about the workspace, and `cross_links` is a capped
            // view of it. Counting the rows would give 1 and 1 here and read as
            // correct — which is exactly the bug, invisible until a workspace
            // outgrows the cap.
            cross_links_total: 9,
            cross_links_authored: 4,
        };
        let c = render_workspace_home(&ws).content;

        assert!(
            c.contains("**4 declared**"),
            "the caption counts the workspace, not the rows on screen: {c}"
        );
        assert!(c.contains("**5 inferred**"), "{c}");
        assert!(
            !c.contains("not authored facts"),
            "the blanket caveat is false once a declared row can appear: {c}"
        );
        // Per row: a declaration is marked as one, and a match keeps its score.
        assert!(c.contains("references *(declared)*"), "{c}");
        assert!(c.contains("references (0.91)"), "{c}");
    }

    #[test]
    fn the_workspace_home_names_an_example_note_name_actually_produces() {
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![member_summary("api", 7), member_summary("sdk", 4)],
            pins: Vec::new(),
            cross_links: vec![CrossLink {
                from_project: "sdk".into(),
                from_key: "cfgkey:config.toml#addr".into(),
                from_name: "addr".into(),
                kind: "links".into(),
                confidence: Some(0.91),
                to_qualified: "api::cfgkey:config.toml#addr".into(),
                resolves: true,
                authored: false,
            }],
            cross_links_total: 1,
            cross_links_authored: 0,
        };
        let note = render_workspace_home(&ws);

        // The source end of the first cross-repo link, rendered through the real
        // function. `from_project` is a member and `from_key` is one of its own
        // nodes, so this is a note the render writes rather than one the
        // sentence assumes.
        let expected = format!("{}.md", note_name("sdk::cfgkey:config.toml#addr"));
        assert!(
            note.content.contains(&expected),
            "the naming paragraph must show a real name ({expected}), not a \
             hand-written form:\n{}",
            note.content
        );
        // And the key form it is derived *from* is still stated, because that is
        // the half a reader needs to look a note up by its frontmatter.
        assert!(
            note.content.contains("`<project>::<key>`"),
            "{}",
            note.content
        );
        // No filename anywhere in the vault carries `::`.
        assert!(!expected.contains("::"), "{expected}");
    }

    /// With no cross-repo links there is no key the renderer can prove is a
    /// node, so it must say nothing rather than fabricate one.
    ///
    /// The example this replaced was `<first member>::file:README.md`, invented
    /// from the member list — and membership does not require a README, so
    /// `_Home` could assert a note that was never written. That is the very
    /// defect this PR exists to fix, one remove away, so the empty case gets an
    /// assertion of its own rather than an assumption.
    #[test]
    fn the_workspace_home_claims_no_example_note_when_it_has_no_real_key() {
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![member_summary("api", 7), member_summary("sdk", 4)],
            pins: Vec::new(),
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let note = render_workspace_home(&ws);

        assert!(
            !note.content.contains("is the note "),
            "no cross-repo link means no provable key, so no `Here, X is the \
             note Y` claim:\n{}",
            note.content
        );
        // The fabricated form specifically: never emitted, with or without links.
        assert!(
            !note.content.contains("::file:README.md"),
            "{}",
            note.content
        );
        // The rule itself is still stated — only the illustration is absent.
        assert!(
            note.content.contains("`<project>::<key>`")
                && note.content.contains("no filename contains `::`"),
            "{}",
            note.content
        );
    }

    #[test]
    fn a_member_note_declares_which_member_it_came_from() {
        let ms = members(&["api"]);
        let ex = node_linking_to("cfgkey:config.toml#addr", "addr", "sym:rust:a.rs#A");
        let note = render_note_scoped(
            &ex,
            None,
            None,
            &VaultScope {
                project: Some("api"),
                members: &ms,
            },
        );
        assert_eq!(
            note.filename,
            format!("{}.md", note_name("api::cfgkey:config.toml#addr"))
        );
        assert!(
            note.content.contains("project: \"api\""),
            "{}",
            note.content
        );
        assert!(
            note.content.contains("- roteiro/project/api"),
            "the tag is what filters the graph view to one repository: {}",
            note.content
        );
        // A within-member edge is qualified to the same member, not left bare.
        assert!(
            note.content
                .contains(&format!("→ [[{}]]", note_name("api::sym:rust:a.rs#A"))),
            "{}",
            note.content
        );
    }

    #[test]
    fn a_project_note_declares_no_project() {
        let ex = node_linking_to("cfgkey:config.toml#addr", "addr", "sym:rust:a.rs#A");
        let note = render_note(&ex, None, None);
        assert!(!note.content.contains("project:"), "{}", note.content);
        assert!(
            !note.content.contains("roteiro/project/"),
            "a per-project vault would carry one constant on every note — and \
             adding it would change every note's bytes: {}",
            note.content
        );
    }

    #[test]
    fn a_cross_repo_edge_links_straight_to_the_other_members_note() {
        // ADR-0009: the spoke's edge points at a *local placeholder* for the hub's
        // node, because store integrity needs both ends in one store. A workspace
        // vault holds both, so the link goes to the real note. No new edge — the
        // resolver already follows this placeholder at query time.
        let ms = members(&["spoke", "hub"]);
        let scope = VaultScope {
            project: Some("spoke"),
            members: &ms,
        };
        let ex = node_linking_to(
            "cfgkey:config.toml#addr",
            "addr",
            &rto_graph::external_ref_key("hub::cfgkey:config.toml#addr"),
        );
        let note = render_note_scoped(&ex, None, None, &scope);
        assert!(
            note.content.contains(&format!(
                "→ [[{}]]",
                note_name("hub::cfgkey:config.toml#addr")
            )),
            "the edge must land on the hub's own note: {}",
            note.content
        );
        assert!(
            !note.content.contains("extref"),
            "and never on the placeholder: {}",
            note.content
        );
        // The same rule decides that the placeholder is not written as a note, so
        // the two halves cannot disagree.
        assert!(
            scope.redirects_external_ref(&rto_graph::external_ref_key(
                "hub::cfgkey:config.toml#addr"
            ))
        );
    }

    #[test]
    fn a_cross_repo_edge_out_of_the_workspace_keeps_its_placeholder() {
        // The target repo is not in this vault, so there is no note to point at.
        // Redirecting anyway would produce a link that resolves to nothing —
        // Obsidian shows that as merely unwritten, which is a worse lie than a
        // placeholder that honestly says "elsewhere".
        let ms = members(&["spoke"]);
        let scope = VaultScope {
            project: Some("spoke"),
            members: &ms,
        };
        let key = rto_graph::external_ref_key("elsewhere::cfgkey:config.toml#addr");
        assert!(!scope.redirects_external_ref(&key));
        let ex = node_linking_to("cfgkey:config.toml#addr", "addr", &key);
        let note = render_note_scoped(&ex, None, None, &scope);
        assert!(
            note.content.contains(&format!(
                "→ [[{}]]",
                note_name("spoke::extref:elsewhere::cfgkey:config.toml#addr")
            )),
            "{}",
            note.content
        );
    }

    #[test]
    fn a_single_project_vault_never_redirects_an_external_ref() {
        // No members ⇒ nothing to resolve against, so today's vault keeps rendering
        // the placeholder exactly as it does now.
        let key = rto_graph::external_ref_key("hub::cfgkey:config.toml#addr");
        assert!(!VaultScope::PROJECT.redirects_external_ref(&key));
        assert_eq!(
            scoped_note_name(&VaultScope::PROJECT, &key),
            note_name(&key)
        );
    }

    fn member_summary(project: &str, fan_in: u32) -> VaultSummary {
        VaultSummary {
            project: project.to_owned(),
            total_nodes: 3,
            total_edges: 2,
            node_counts: vec![("fn".into(), 2)],
            edge_provenance: vec![("derived".into(), 2)],
            adrs: vec![AdrEntry {
                key: "adr:0001".into(),
                name: "First".into(),
                status: Some("Accepted".into()),
            }],
            debt: vec![("todo".into(), 4)], // roteiro:ignore
            densest_files: vec![DensityEntry {
                path: "src/small.rs".into(),
                markers: 3,
                lines: 120,
                per_kloc: 25.0,
            }],
            config_secrets: None,
            most_called: vec![CouplingEntry {
                key: "sym:rust:a.rs#helper".into(),
                name: "helper".into(),
                fan_in,
                fan_out: 1,
            }],
            repo_url: Some(format!("https://github.com/org/{project}")),
            commit: Some("abcdef0123456789".into()),
            findings: vec![],
            coverage: Coverage::NotRun,
            settings: RenderedUnder::default(),
        }
    }

    #[test]
    fn the_workspace_home_keeps_every_members_own_aggregates() {
        // The promise in issue #442: the existing per-project `_Home` view is a
        // *subset* of the workspace one, not a casualty of it. Someone who came for
        // their repository's coupling and debt tables must still find them —
        // not a workspace total that averages them away.
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![member_summary("api", 7), member_summary("sdk", 4)],
            pins: Vec::new(),
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let note = render_workspace_home(&ws);
        assert_eq!(note.filename, HOME_NOTE);
        assert!(
            note.content
                .contains("# platform — workspace knowledge graph")
        );
        // Summed, and the members listed.
        assert!(
            note.content
                .contains("**6 nodes**, **4 edges** across **2** member")
        );
        assert!(note.content.contains("| [[#api\\|api]] | 3 | 2 |"));

        for project in ["api", "sdk"] {
            assert!(
                note.content.contains(&format!("\n## {project}\n")),
                "each member gets its own section"
            );
        }
        // Today's sections, one level deeper, once per member.
        for section in [
            "### Structure",
            "### Provenance",
            "### Decisions (ADRs)",
            "### Intent debt",
            "#### Densest files",
            "### Most depended-on",
        ] {
            assert_eq!(
                note.content.matches(section).count(),
                2,
                "`{section}` must appear once per member: {}",
                note.content
            );
        }
        // And every link inside a member's section resolves within that member.
        assert!(note.content.contains(&format!(
            "**Accepted** — [[{}|First]]",
            note_name("api::adr:0001")
        )));
        assert!(note.content.contains(&format!(
            "**Accepted** — [[{}|First]]",
            note_name("sdk::adr:0001")
        )));
        assert!(note.content.contains(&format!(
            "[[{}\\|helper]] | 7 |",
            note_name("api::sym:rust:a.rs#helper")
        )));
        assert!(note.content.contains(&format!(
            "[[{}\\|src/small.rs]]",
            note_name("sdk::file:src/small.rs")
        )));
    }

    #[test]
    fn the_workspace_home_renders_cross_repo_links_and_marks_the_ones_it_cannot_follow() {
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![member_summary("api", 7), member_summary("sdk", 4)],
            pins: Vec::new(),
            cross_links: vec![
                CrossLink {
                    from_project: "sdk".into(),
                    from_key: "cfgkey:config.toml#addr".into(),
                    from_name: "addr".into(),
                    kind: "links".into(),
                    confidence: Some(0.91),
                    to_qualified: "api::cfgkey:config.toml#addr".into(),
                    resolves: true,
                    authored: false,
                },
                CrossLink {
                    from_project: "sdk".into(),
                    from_key: "cfgkey:config.toml#other".into(),
                    from_name: "other".into(),
                    kind: "links".into(),
                    confidence: None,
                    to_qualified: "absent::cfgkey:config.toml#other".into(),
                    resolves: false,
                    authored: false,
                },
            ],
            cross_links_total: 2,
            cross_links_authored: 0,
        };
        let note = render_workspace_home(&ws);
        // Resolvable: a link to the other member's note, with its confidence.
        assert!(
            note.content.contains(&format!(
                "| [[{}\\|addr]] | sdk | [[{}\\|api::cfgkey:config.toml#addr]] | links (0.91) |",
                note_name("sdk::cfgkey:config.toml#addr"),
                note_name("api::cfgkey:config.toml#addr"),
            )),
            "{}",
            note.content
        );
        // Outside the workspace: stated as such, never as a wikilink — Obsidian
        // renders a link to a missing note as one that is merely unwritten.
        assert!(
            note.content
                .contains("`absent::cfgkey:config.toml#other` *(outside this workspace)*"),
            "{}",
            note.content
        );
        assert!(
            !note.content.contains("[[absent-"),
            "a dangling wikilink would read as a note someone forgot to write: {}",
            note.content
        );
    }

    #[test]
    fn the_workspace_home_says_when_it_has_truncated_the_cross_links() {
        // A capped table that does not say it is capped reads as the whole set.
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![member_summary("api", 7)],
            pins: Vec::new(),
            cross_links: vec![CrossLink {
                from_project: "api".into(),
                from_key: "cfgkey:config.toml#addr".into(),
                from_name: "addr".into(),
                kind: "links".into(),
                confidence: None,
                to_qualified: "api::cfgkey:config.toml#addr".into(),
                resolves: true,
                authored: false,
            }],
            cross_links_total: 40,
            cross_links_authored: 0,
        };
        let note = render_workspace_home(&ws);
        assert!(note.content.contains("Showing 1 of 40"), "{}", note.content);
        assert!(note.content.contains("roteiro links --matrix"));
    }

    #[test]
    fn a_workspace_with_no_cross_repo_links_says_why_rather_than_showing_nothing() {
        let ws = WorkspaceSummary {
            generated_at: "2026-08-22T10:00:00Z".to_owned(),
            name: "platform".into(),
            members: vec![member_summary("api", 7)],
            pins: Vec::new(),
            cross_links: vec![],
            cross_links_total: 0,
            cross_links_authored: 0,
        };
        let note = render_workspace_home(&ws);
        assert!(note.content.contains("## Cross-repo links"));
        assert!(
            note.content.contains("links --infer --write"),
            "an empty section must name what would fill it, or it reads as \
             \"these repos are unrelated\": {}",
            note.content
        );
        // Singular, because getting this wrong on a one-member workspace is the
        // kind of thing nobody notices until it ships.
        assert!(note.content.contains("**1** member repository."));
    }

    // ---- YAML frontmatter escaping -------------------------------------------

    /// Parse a note's frontmatter block with a **real** YAML parser and return
    /// `field`'s value, or the parse error.
    ///
    /// Every assertion below goes through this rather than checking the emitted
    /// bytes. An escaper that is wrong in a self-consistent way passes a
    /// byte-comparison — that is precisely how `"foo\bar"` survived: it looks
    /// exactly like what was asked for, and means something else.
    fn frontmatter_field(note: &str, field: &str) -> Result<Option<String>, String> {
        let block = note
            .strip_prefix("---\n")
            .and_then(|rest| rest.split_once("\n---\n"))
            .map(|(block, _)| block)
            .expect("note must open with a frontmatter block");
        let docs = yaml_rust2::YamlLoader::load_from_str(block).map_err(|e| e.to_string())?;
        Ok(docs[0][field].as_str().map(ToOwned::to_owned))
    }

    /// A node whose key, path and language are whatever the test needs.
    fn node_with(key: &str, path: Option<&str>, lang: Option<&str>) -> Explanation {
        Explanation {
            schema: rto_graph::SCHEMA,
            node: NodeSummary {
                key: key.into(),
                kind: "fn".into(),
                name: "n".into(),
                path: path.map(ToOwned::to_owned),
                lang: lang.map(ToOwned::to_owned),
            },
            meta: serde_json::Value::Null,
            outgoing: vec![],
            incoming: vec![],
        }
    }

    /// The three measured failure modes of the escaping this replaced, each
    /// asserted on the **parsed** value.
    ///
    /// Before the fix: `foo\bar` parsed back as `foo<BS>ar` (silently six
    /// characters, not seven), and the other two made the whole block
    /// unparseable — which in Obsidian costs the note *every* property, with no
    /// error shown.
    #[test]
    fn a_backslash_or_quote_in_a_path_still_parses_back_to_itself() {
        for path in [
            r"foo\bar",     // `\b` was YAML's backspace escape: silent corruption
            r"foo\dir",     // `\d` is not a YAML escape at all: parse error
            "say\"hi\".rs", // an unescaped `"` ended the scalar early: parse error
            r"a\\b",
            "trailing-backslash\\",
        ] {
            let note = render_note(&node_with("file:x", Some(path), None), None, None);
            assert_eq!(
                frontmatter_field(&note.content, "path"),
                Ok(Some(path.to_owned())),
                "path {path:?} must round-trip"
            );
        }
    }

    /// `key:` is not hypothetical for this: node keys already carry `:` and `#`,
    /// and a symbol name can contain a quotation mark.
    #[test]
    fn a_node_key_round_trips_whatever_punctuation_it_carries() {
        for key in [
            "sym:rust:src/a.rs#Store",
            r"sym:rust:src\weird.rs#Thing",
            "sym:rust:a.rs#say\"hi\"",
            "cfgkey:config.toml#serve.addr",
        ] {
            let note = render_note(&node_with(key, None, None), None, None);
            assert_eq!(
                frontmatter_field(&note.content, "key"),
                Ok(Some(key.to_owned())),
                "key {key:?} must round-trip"
            );
        }
        // The old rule turned a `"` into an apostrophe, so the note reported a key
        // that was not the node's key — parseable, and wrong.
        let note = render_note(
            &node_with("sym:rust:a.rs#say\"hi\"", None, None),
            None,
            None,
        );
        assert!(
            !note.content.contains("say'hi'"),
            "a quotation mark must be escaped, not rewritten: {}",
            note.content
        );
    }

    /// A member directory name is a path component, so it reaches the same rule.
    #[test]
    fn a_member_project_name_round_trips() {
        let ms: std::collections::BTreeSet<String> =
            std::iter::once(r"odd\name".to_owned()).collect();
        let note = render_note_scoped(
            &node_with("file:x", None, None),
            None,
            None,
            &VaultScope {
                project: Some(r"odd\name"),
                members: &ms,
            },
        );
        assert_eq!(
            frontmatter_field(&note.content, "project"),
            Ok(Some(r"odd\name".to_owned()))
        );
    }

    /// The **bare** fields are the other half of the same class, and were missed
    /// by the review that found the quoted ones: `status` is written unquoted, and
    /// `roteiro load` installs a caller-supplied artifact whose nodes carry
    /// whatever they carry.
    #[test]
    fn a_bare_field_is_quoted_only_when_being_bare_would_change_it() {
        let with_status = |status: &str| {
            let mut ex = node_with("adr:0001", None, None);
            ex.meta = serde_json::json!({ "status": status });
            render_note(&ex, None, None)
        };

        // Would be a parse error bare; would silently truncate bare.
        for status in [
            "Accepted: superseded by 0012",
            "Accepted # pending",
            "{draft}",
            "",
        ] {
            let note = with_status(status);
            assert_eq!(
                frontmatter_field(&note.content, "status"),
                Ok(Some(status.to_owned())),
                "status {status:?} must round-trip"
            );
        }

        // …and a safe one stays bare, which is what keeps an existing vault's
        // bytes unchanged.
        let note = with_status("Accepted");
        assert!(
            note.content.contains("\nstatus: Accepted\n"),
            "a plain-safe status must not gain quotes: {}",
            note.content
        );
    }

    /// `no` is Norwegian, and a bare `no` reads as `false` to a YAML **1.1**
    /// parser.
    ///
    /// The only assertion here that pins emitted bytes, and deliberately so:
    /// `yaml-rust2` implements YAML 1.2, whose core schema resolves a bare `no`
    /// to the *string* `no`, so a round-trip through this test's own oracle
    /// cannot see the problem — it passes either way. The exposure is to the
    /// parser on the other side, and Obsidian's is not this one. Quoting costs
    /// two characters on a value that never occurs here; guessing which YAML
    /// version every downstream reader implements does not seem like the better
    /// bet.
    #[test]
    fn a_language_that_spells_a_yaml_boolean_is_quoted() {
        let note = render_note(&node_with("file:x", None, Some("no")), None, None);
        assert!(
            note.content.contains("\nlang: \"no\"\n"),
            "a bare `no` is `false` to a 1.1 parser and must be quoted: {}",
            note.content
        );
        assert_eq!(
            frontmatter_field(&note.content, "lang"),
            Ok(Some("no".to_owned())),
            "and it must still read back as the string: {}",
            note.content
        );
        // And an ordinary language is untouched.
        let rust = render_note(&node_with("file:x", None, Some("rust")), None, None);
        assert!(rust.content.contains("\nlang: rust\n"), "{}", rust.content);
    }

    /// Control characters and the separators some parsers fold as line breaks.
    #[test]
    fn control_characters_cannot_break_out_of_the_block() {
        for path in [
            "a\nb",
            "a\tb",
            "a\u{0}b",
            "a\u{2028}b",
            "a\u{7f}b",
            "a\u{85}b",
        ] {
            let note = render_note(&node_with("file:x", Some(path), None), None, None);
            assert_eq!(
                frontmatter_field(&note.content, "path"),
                Ok(Some(path.to_owned())),
                "path {path:?} must round-trip"
            );
            // A raw newline would end the scalar and inject a sibling key.
            assert_eq!(
                note.content.matches("\npath: ").count(),
                1,
                "the value must stay on one line: {}",
                note.content
            );
        }
    }

    /// The escaping is *only* an escaping: for a value with nothing to escape it
    /// must emit the same bytes it always did, or #442's promise that a
    /// single-project vault is byte-identical does not hold.
    #[test]
    fn an_ordinary_value_is_emitted_exactly_as_before() {
        let note = render_note(
            &node_with("sym:rust:src/a.rs#Store", Some("src/a.rs"), Some("rust")),
            None,
            None,
        );
        assert!(
            note.content
                .contains("\nkey: \"sym:rust:src/a.rs#Store\"\n")
        );
        assert!(note.content.contains("\nkind: fn\n"));
        assert!(note.content.contains("\npath: \"src/a.rs\"\n"));
        assert!(note.content.contains("\nlang: rust\n"));
    }

    /// The plain-style decision is checked against a real parser rather than
    /// against itself: whatever `is_plain_safe` accepts must actually round-trip
    /// bare, and whatever it rejects must round-trip quoted.
    #[test]
    fn the_plain_style_decision_agrees_with_a_real_yaml_parser() {
        for value in [
            "fn",
            "config_key",
            "rust",
            "Accepted",
            "a.b",
            "a/b",
            "a-b_c",
            "no",
            "yes",
            "true",
            "null",
            "y",
            "N",
            "",
            " lead",
            "trail ",
            "a: b",
            "a #c",
            "{x}",
            "[x]",
            "*x",
            "&x",
            "!x",
            "#x",
            ">x",
            "|x",
            "%x",
            "@x",
            "`x",
            "\"x",
            "'x",
            ",x",
            "123",
            "1.5",
            "-x",
            ".x",
            "a\\b",
        ] {
            let emitted = super::yaml_scalar(value);
            let doc = format!("v: {emitted}");
            let parsed = yaml_rust2::YamlLoader::load_from_str(&doc)
                .unwrap_or_else(|e| panic!("{value:?} emitted {emitted:?}: {e}"));
            assert_eq!(
                parsed[0]["v"].as_str(),
                Some(value),
                "{value:?} emitted as {emitted:?} did not round-trip"
            );
        }
    }
}