majordomus_cli/web/

validate.rs

//! Validation: the invariants a topology must satisfy before anything serves or publishes it.
//!
//! A collision here is an error, never an ordering accident: two surfaces claiming one path
//! is refused at the point it is discovered rather than resolved by whichever router
//! happened to insert its route first. Every finding names the surface, the value, where the
//! value came from and what to do about it, because a convention-heavy system that reports
//! "invalid topology" is a system nobody can maintain.

use std::collections::BTreeMap;
use std::path::Path;

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use super::discover::GENERATED_ROOT;
use super::model::{Availability, SurfaceKind, Topology};

/// How much a finding matters.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "kebab-case")]
// `Severity` alone is the index's diagnostic severity; a topology's finding has its own
#[schemars(rename = "SurfaceFindingSeverity")]
// Declared least first, like `model::Severity`, so `Ord` means the same thing in both:
// greater is worse, and every comparator that puts the worst first reads `b.cmp(a)`.
// Declared the other way round, the two enums made identical intent look like opposite
// code, and a change that reconciled the two comparators would have inverted one report.
pub enum Severity {
    /// Worth reading; serving is still coherent.
    Warning,
    /// The topology may not be served or published in this state.
    Error,
}

/// One thing wrong with a topology, said so a person can fix it without reading this file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[schemars(rename = "SurfaceFinding")]
pub struct Finding {
    /// How much it matters.
    pub severity: Severity,
    /// The rule that produced it, stable enough to grep for.
    pub rule: String,
    /// The surface it is about.
    pub surface: String,
    /// What is wrong.
    pub message: String,
    /// What to do about it.
    pub remedy: String,
}

/// Every invariant, over one topology.
///
/// `artifacts` says whether a static surface's directory must already exist: a validation
/// before a build has nothing to find, and one before serving or publishing has everything
/// to lose by finding nothing.
///
/// ```
/// use majordomus_cli::web::{model::*, validate};
/// # use std::collections::BTreeMap;
/// # fn s(id: &str, mount: &str) -> Surface {
/// #     Surface { id: id.into(), title: id.into(), category: Category::Report,
/// #         visibility: Visibility::Public, kind: SurfaceKind::StaticDirectory,
/// #         mount: Mount::parse(mount).unwrap(), producer: "t".into(), feature: None,
/// #         artifact: Some("target/web/x".into()), index: Some("index.html".into()),
/// #         availability: Availability::Both, built_from: None, provenance: BTreeMap::new() }
/// # }
/// let clash = Topology::new(vec![s("a", "/tests"), s("b", "/tests")]);
/// let findings = validate::validate(&clash, std::path::Path::new("."), validate::Artifacts::Ignore);
/// assert!(findings.iter().any(|f| f.rule == "surface.mount-collision"));
/// ```
pub fn validate(topology: &Topology, root: &Path, artifacts: Artifacts) -> Vec<Finding> {
    let mut findings = Vec::new();
    findings.extend(identities(topology));
    findings.extend(mounts(topology));
    findings.extend(shadowing(topology, root));
    findings.extend(namespaces(topology));
    findings.extend(roots(topology, root, artifacts));
    // The worst first, then the canonical order over what is left. The same shape the
    // other two finding lists use (`why::findings`, `product::findings`), and now the same
    // direction: `b.cmp(a)` on a severity whose greater variant is the worse one.
    findings.sort_by(|a, b| {
        b.severity
            .cmp(&a.severity)
            .then_with(|| crate::order::natural_cmp(&a.rule, &b.rule))
            .then_with(|| crate::order::natural_cmp(&a.surface, &b.surface))
    });
    findings
}

/// Whether a static surface's generated directory must exist for the topology to be valid.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Artifacts {
    /// The directory must be there, with its index: what serving and publishing need.
    Required,
    /// The directory may be missing: what a validation before the build can say.
    Ignore,
}

/// Two surfaces may not share an identity: the id is the selector, and an ambiguous
/// selector silently selects the wrong thing.
fn identities(topology: &Topology) -> Vec<Finding> {
    let mut seen: BTreeMap<&str, usize> = BTreeMap::new();
    for surface in &topology.surfaces {
        *seen.entry(surface.id.as_str()).or_default() += 1;
    }
    seen.into_iter()
        .filter(|(_, n)| *n > 1)
        .map(|(id, n)| Finding {
            severity: Severity::Error,
            rule: "surface.duplicate-id".into(),
            surface: id.to_string(),
            message: format!("{n} surfaces claim the id '{id}'"),
            remedy: "give each producer its own id; the id is what --only and --exclude select"
                .into(),
        })
        .collect()
}

/// The reserved mounts: a fixed meaning held by the surface that is supposed to hold it.
///
/// A collision already refuses two surfaces claiming one path, and while both the
/// documentation and the viewer exist that is enough to keep them apart. It is not enough
/// when one of them is gone: remove the documentation surface and nothing stops the viewer
/// taking `/docs`, which is exactly the state this repository was in before. So the
/// reservation is checked against the producer that must own it, not only against whoever
/// else wants it.
///
/// The reservations are about what a *process serves*, which is the world these names have
/// a meaning in; a publication's `/` belongs to the site as it is deployed and always has.
/// So only served surfaces are checked, for the same reason mount ownership is checked per
/// world: a rule applied across both would report a conflict that cannot happen.
///
/// Absence is not a violation. A process that serves no Cockpit, a build made without a
/// site, a topology narrowed to one selector — each is a legitimate subset, and a
/// reservation says who owns a mount *if* it is claimed and *if* its owner is present, never
/// that every reserved mount must exist.
///
/// ```
/// use majordomus_cli::web::{discover, validate, Mount, Topology};
/// let mut surfaces = discover::native_all();
/// // the viewer helps itself to the documentation's name, with the documentation absent
/// let swagger = surfaces.iter_mut().find(|s| s.id == "swagger").unwrap();
/// swagger.mount = Mount::parse(discover::DOCS_MOUNT).unwrap();
/// let findings = validate::validate(
///     &Topology::new(surfaces), std::path::Path::new("."), validate::Artifacts::Ignore);
/// assert!(findings.iter().any(|f| f.rule == "surface.reserved-namespace"), "{findings:?}");
/// ```
fn namespaces(topology: &Topology) -> Vec<Finding> {
    let mut findings = Vec::new();
    for reservation in super::discover::reserved() {
        let Ok(mount) = super::model::Mount::parse(reservation.path) else {
            continue;
        };
        for surface in topology
            .surfaces
            .iter()
            .filter(|s| s.availability.is_served())
        {
            if surface.mount == mount && surface.id != reservation.owner {
                findings.push(Finding {
                    severity: Severity::Error,
                    rule: "surface.reserved-namespace".into(),
                    surface: surface.id.clone(),
                    message: format!(
                        "'{}' is mounted at {mount}, which is reserved for the {} and belongs to '{}'",
                        surface.id, reservation.role, reservation.owner
                    ),
                    remedy: format!(
                        "mount '{}' somewhere else; {mount} means one thing and '{}' is what means it",
                        surface.id, reservation.owner
                    ),
                });
            }
            if surface.id == reservation.owner && surface.mount != mount {
                findings.push(Finding {
                    severity: Severity::Error,
                    rule: "surface.reserved-namespace".into(),
                    surface: surface.id.clone(),
                    message: format!(
                        "'{}' is the {} and is mounted at {} rather than at its reserved {mount}",
                        surface.id, reservation.role, surface.mount
                    ),
                    remedy: format!(
                        "a reserved mount moves in the constant that declares it, so that everything reading it moves too; leave '{}' at {mount}",
                        surface.id
                    ),
                });
            }
        }
    }
    findings
}

/// A route the executable answers itself, mounted over pages the root application has.
///
/// The nesting rule exempts the root application, because answering what nothing else claims
/// is its whole job. That exemption is right for the topology and blind to one thing: the
/// application does not only answer what nothing else claims — it has *files* at particular
/// paths, and a native route mounted at one of them takes every page beneath it. The
/// topology stays resolvable and the pages stop existing, silently, for anybody using the
/// running executable rather than the published site.
///
/// So this is measured rather than reasoned about: the application's own output is asked
/// whether it has something at the route. A warning, not an error, because which of the two
/// should move is intent — a person decides whether the route or the section is renamed —
/// and refusing to serve until they decide would be worse than telling them.
fn shadowing(topology: &Topology, root: &Path) -> Vec<Finding> {
    let mut findings = Vec::new();
    let Some(application) = topology
        .surfaces
        .iter()
        .find(|s| s.mount.is_root() && s.kind == SurfaceKind::StaticDirectory)
    else {
        return findings;
    };
    let Some(artifact) = application.artifact.as_ref() else {
        return findings;
    };
    let base = root.join(artifact);
    for surface in &topology.surfaces {
        if surface.mount.is_root() || surface.kind == SurfaceKind::StaticDirectory {
            continue;
        }
        let relative = surface.mount.relative();
        if relative.is_empty() {
            continue;
        }
        let target = base.join(&relative);
        if !target.exists() {
            continue;
        }
        let pages = if target.is_dir() {
            count_pages(&target)
        } else {
            1
        };
        findings.push(Finding {
            severity: Severity::Warning,
            rule: "surface.shadows-application".into(),
            surface: format!("{} over {}", surface.id, application.id),
            message: format!(
                "{} answers {} itself, and {} has {} page(s) there ({}/{})",
                surface.id,
                surface.mount,
                application.id,
                pages,
                artifact.display(),
                relative
            ),
            remedy: format!(
                "move {} to a path the application does not use, or move those pages: while \
                 both claim {}, the executable answers and the pages are unreachable",
                surface.id, surface.mount
            ),
        });
    }
    findings
}

/// How many rendered pages a directory of the application holds, at any depth.
fn count_pages(dir: &Path) -> usize {
    let Ok(entries) = std::fs::read_dir(dir) else {
        return 0;
    };
    let mut total = 0;
    for entry in entries.flatten() {
        let path = entry.path();
        if path.is_dir() {
            total += count_pages(&path);
        } else if path.extension().is_some_and(|e| e == "html") {
            total += 1;
        }
    }
    total
}

/// Mount ownership: one owner per path, in each of the two worlds a surface can live in.
///
/// A surface owns its mount and everything under it. Two surfaces claiming one mount is a
/// collision, and a surface mounted inside another's subtree is a shadowing conflict —
/// whichever answered would depend on the router rather than on the declaration. The single
/// exception is a root surface, which exists precisely to answer what nothing else claims.
///
/// The check is per world, because a topology has two. What a running process serves and
/// what a publication contains are different sets of surfaces, and a path claimed in one is
/// not claimed in the other: the site as it is deployed owns `/` of a publication, and the
/// home page owns `/` of a process, and they never meet. Checking them together would
/// report a conflict that cannot happen; checking them apart is what makes the two mounts
/// declarable at all.
fn mounts(topology: &Topology) -> Vec<Finding> {
    let mut findings = Vec::new();
    for world in World::ALL {
        let surfaces: Vec<&super::model::Surface> = topology
            .surfaces
            .iter()
            .filter(|s| world.holds(s))
            .collect();
        for (i, outer) in surfaces.iter().enumerate() {
            for inner in surfaces.iter().skip(i + 1) {
                if outer.mount == inner.mount {
                    findings.push(Finding {
                        severity: Severity::Error,
                        rule: "surface.mount-collision".into(),
                        surface: format!("{} and {}", outer.id, inner.id),
                        message: format!(
                            "both claim {} when {} ({} from {}, {} from {})",
                            outer.mount,
                            world.describe(),
                            outer.id,
                            provenance_of(outer, "mount"),
                            inner.id,
                            provenance_of(inner, "mount")
                        ),
                        remedy: "one path has one owner: change one producer's declared mount"
                            .into(),
                    });
                    continue;
                }
                let (over, under) = if outer.mount.contains(&inner.mount) {
                    (outer, inner)
                } else if inner.mount.contains(&outer.mount) {
                    (inner, outer)
                } else {
                    continue;
                };
                if over.mount.is_root() {
                    continue; // a root surface answers what nothing else claims: that is its job
                }
                findings.push(Finding {
                    severity: Severity::Error,
                    rule: "surface.nested-mount".into(),
                    surface: format!("{} inside {}", under.id, over.id),
                    message: format!(
                        "{} is mounted at {} inside {}, which owns {} and everything under it when {}",
                        under.id,
                        under.mount,
                        over.id,
                        over.mount,
                        world.describe()
                    ),
                    remedy: format!(
                        "move {} outside {}, or let {} produce it as part of its own output",
                        under.id,
                        over.mount.prefix(),
                        over.id
                    ),
                });
            }
        }
    }
    // Grouped so that `dedup_by` sees duplicates adjacent, with the worst of a duplicated
    // pair first so that it is the one that survives. The caller sorts the result again.
    findings.sort_by(|a, b| {
        crate::order::natural_cmp(&a.rule, &b.rule)
            .then_with(|| crate::order::natural_cmp(&a.surface, &b.surface))
            .then_with(|| b.severity.cmp(&a.severity))
    });
    findings.dedup_by(|a, b| a.rule == b.rule && a.surface == b.surface);
    findings
}

/// The two worlds a mount can be claimed in. A surface lives in one, the other, or both,
/// and a path is only contested by surfaces that share a world.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum World {
    /// Answered by a running process.
    Served,
    /// Present in a publication's files.
    Published,
}

impl World {
    const ALL: [World; 2] = [World::Served, World::Published];

    fn holds(self, surface: &super::model::Surface) -> bool {
        match self {
            World::Served => surface.availability.is_served(),
            World::Published => surface.availability.is_published(),
        }
    }

    fn describe(self) -> &'static str {
        match self {
            World::Served => "a process serves them",
            World::Published => "a publication holds them",
        }
    }
}

/// What a static surface's directory must be: inside the generated root or the site's own
/// output, present when it is needed, and carrying the index its mount answers with.
fn roots(topology: &Topology, root: &Path, artifacts: Artifacts) -> Vec<Finding> {
    let mut findings = Vec::new();
    for surface in &topology.surfaces {
        match surface.kind {
            SurfaceKind::StaticDirectory => {}
            SurfaceKind::NativeRoute | SurfaceKind::Redirect => {
                if surface.artifact.is_some() {
                    findings.push(Finding {
                        severity: Severity::Warning,
                        rule: "surface.artifact-on-dynamic".into(),
                        surface: surface.id.clone(),
                        message: "a route the executable answers itself names a directory".into(),
                        remedy: "drop the artifact, or declare the surface static".into(),
                    });
                }
                continue;
            }
        }
        let Some(artifact) = surface.artifact.as_ref() else {
            findings.push(Finding {
                severity: Severity::Error,
                rule: "surface.missing-artifact-path".into(),
                surface: surface.id.clone(),
                message: "a static surface names no directory".into(),
                remedy: "declare the directory the producer writes".into(),
            });
            continue;
        };
        let text = artifact.to_string_lossy().replace('\\', "/");
        if artifact.is_absolute() || text.split('/').any(|s| s == "..") {
            findings.push(Finding {
                severity: Severity::Error,
                rule: "surface.artifact-escapes".into(),
                surface: surface.id.clone(),
                message: format!("the directory '{text}' leaves the repository"),
                remedy: "a surface is served from a repository-relative generated directory".into(),
            });
            continue;
        }
        if !(text.starts_with(GENERATED_ROOT) || text.starts_with("site/")) {
            findings.push(Finding {
                severity: Severity::Error,
                rule: "surface.artifact-outside-generated-root".into(),
                surface: surface.id.clone(),
                message: format!(
                    "the directory '{text}' is neither under {GENERATED_ROOT}/ nor the site's output"
                ),
                remedy: format!(
                    "write the producer's output into {GENERATED_ROOT}/{}/",
                    surface.id
                ),
            });
            continue;
        }
        if artifacts == Artifacts::Ignore {
            continue;
        }
        let dir = root.join(artifact);
        if !dir.is_dir() {
            findings.push(Finding {
                severity: Severity::Error,
                rule: "surface.artifact-absent".into(),
                surface: surface.id.clone(),
                message: format!("'{text}' does not exist"),
                remedy: format!("run the producer: {}", surface.producer),
            });
            continue;
        }
        if let Some(index) = surface.index.as_ref() {
            if !dir.join(index).is_file() && surface.availability != Availability::ServedOnly {
                findings.push(Finding {
                    severity: Severity::Error,
                    rule: "surface.index-absent".into(),
                    surface: surface.id.clone(),
                    message: format!(
                        "'{text}/{index}' does not exist, so {} answers with nothing",
                        surface.mount
                    ),
                    remedy: format!("the producer writes {index}, or declares another index"),
                });
            }
        }
    }
    findings
}

fn provenance_of(surface: &super::model::Surface, field: &str) -> String {
    surface
        .provenance
        .get(field)
        .map(|p| p.to_string())
        .unwrap_or_else(|| "an unrecorded source".into())
}

/// Does this set of findings stop a topology from being served or published?
pub fn blocking(findings: &[Finding]) -> bool {
    findings.iter().any(|f| f.severity == Severity::Error)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::web::model::{Availability, Category, Mount, Surface, Visibility};
    use std::collections::BTreeMap;

    /// The deployment's root: a static surface at `/` that a publication holds and no
    /// process serves, which is what the site as it is deployed actually is.
    fn deployment(id: &str) -> Surface {
        Surface {
            availability: Availability::PublishedOnly,
            ..surface(id, "/", Some("site/public"))
        }
    }

    fn surface(id: &str, mount: &str, artifact: Option<&str>) -> Surface {
        Surface {
            id: id.into(),
            title: id.into(),
            category: Category::Report,
            visibility: Visibility::Public,
            kind: if artifact.is_some() {
                SurfaceKind::StaticDirectory
            } else {
                SurfaceKind::NativeRoute
            },
            mount: Mount::parse(mount).unwrap(),
            producer: format!("producer of {id}"),
            feature: None,
            artifact: artifact.map(Into::into),
            index: artifact.map(|_| "index.html".to_string()),
            availability: if artifact.is_some() {
                Availability::Both
            } else {
                Availability::ServedOnly
            },
            built_from: None,
            provenance: BTreeMap::new(),
        }
    }

    #[test]
    fn a_clean_topology_has_nothing_to_say() {
        let t = Topology::new(vec![
            deployment("app"),
            surface("tests", "/tests", Some("target/web/tests")),
            surface("api", "/api/v1", None),
        ]);
        let findings = validate(&t, Path::new("/nonexistent"), Artifacts::Ignore);
        assert!(findings.is_empty(), "{findings:?}");
    }

    #[test]
    fn the_root_application_may_hold_every_other_surface() {
        let t = Topology::new(vec![
            deployment("app"),
            surface("tests", "/tests", Some("target/web/tests")),
        ]);
        assert!(validate(&t, Path::new("/nonexistent"), Artifacts::Ignore).is_empty());
    }

    #[test]
    fn nesting_under_anything_else_is_refused_with_both_names() {
        let t = Topology::new(vec![
            surface("tests", "/tests", Some("target/web/tests")),
            surface("ui", "/tests/ui", Some("target/web/ui")),
        ]);
        let findings = validate(&t, Path::new("/nonexistent"), Artifacts::Ignore);
        let nested = findings
            .iter()
            .find(|f| f.rule == "surface.nested-mount")
            .expect("nesting is a finding");
        assert!(nested.message.contains("/tests/ui"), "{}", nested.message);
        assert!(nested.remedy.contains("tests"), "{}", nested.remedy);
    }

    #[test]
    fn a_reserved_mount_held_by_the_wrong_producer_is_refused_with_both_names() {
        let mut surfaces = crate::web::discover::native_all();
        let swagger = surfaces.iter_mut().find(|s| s.id == "swagger").unwrap();
        swagger.mount = Mount::parse(crate::web::discover::DOCS_MOUNT).unwrap();
        let findings = validate(
            &Topology::new(surfaces),
            Path::new("/nonexistent"),
            Artifacts::Ignore,
        );
        let finding = findings
            .iter()
            .find(|f| f.rule == "surface.reserved-namespace")
            .expect("the viewer taking the documentation's name is a finding");
        assert!(finding.message.contains("/docs"), "{}", finding.message);
        assert!(finding.message.contains("docs"), "{}", finding.message);
        assert!(blocking(&findings));
    }

    #[test]
    fn a_reserved_owner_that_wandered_off_its_mount_is_refused() {
        let mut surfaces = crate::web::discover::native_all();
        let swagger = surfaces.iter_mut().find(|s| s.id == "swagger").unwrap();
        swagger.mount = Mount::parse("/api-viewer").unwrap();
        let findings = validate(
            &Topology::new(surfaces),
            Path::new("/nonexistent"),
            Artifacts::Ignore,
        );
        assert!(findings
            .iter()
            .any(|f| f.rule == "surface.reserved-namespace"));
    }

    #[test]
    fn a_reserved_mount_nobody_claims_is_not_a_finding() {
        // a process that serves no Cockpit, a build with no site, a topology narrowed by a
        // selector: each is a legitimate subset, and absence is not a violation
        let surfaces: Vec<Surface> = crate::web::discover::native_all()
            .into_iter()
            .filter(|s| s.id == "openapi")
            .collect();
        let findings = validate(
            &Topology::new(surfaces),
            Path::new("/nonexistent"),
            Artifacts::Ignore,
        );
        assert!(findings.is_empty(), "{findings:?}");
    }

    #[test]
    fn the_declared_topology_of_this_repository_holds_every_reserved_name() {
        let mut surfaces = crate::web::discover::native_all();
        surfaces.extend(crate::web::discover::application(Path::new("/nonexistent")));
        // the fixture has no site, so the two site surfaces are absent; what is present
        // must still sit where it is reserved to sit
        let findings = validate(
            &Topology::new(surfaces),
            Path::new("/nonexistent"),
            Artifacts::Ignore,
        );
        assert!(findings.is_empty(), "{findings:?}");
    }

    /// The failure mode the reservation exists for: a second producer publishing the
    /// crate's reference at its canonical mount — a copy of the rustdoc under another id,
    /// written by somebody who thought it should also be "a report". Two answers for one
    /// path, and whichever the router consulted first would be the reference.
    #[test]
    fn a_second_surface_at_the_rustdoc_mount_is_a_duplicate_canonical_route() {
        use crate::web::discover::{self, Runtime, RUSTDOC, RUSTDOC_MOUNT};
        let tmp = tempfile::tempdir().unwrap();
        let krate = tmp.path().join(crate::capability::model::CRATE_DIR);
        std::fs::create_dir_all(krate.join("src")).unwrap();
        std::fs::write(krate.join("Cargo.toml"), "").unwrap();
        std::fs::write(krate.join("src/lib.rs"), "//! x\n").unwrap();
        let copy = tmp.path().join(GENERATED_ROOT).join("rust-api");
        std::fs::create_dir_all(&copy).unwrap();
        std::fs::write(
            copy.join(discover::DECLARATION_FILE),
            r#"{"schema":"web-surface/v1","id":"rust-api","mount":"/rustdoc"}"#,
        )
        .unwrap();

        let topology = discover::discover(tmp.path(), Runtime::full()).unwrap();
        let findings = validate(&topology, tmp.path(), Artifacts::Ignore);
        assert!(blocking(&findings), "{findings:?}");
        let collision = findings
            .iter()
            .find(|f| f.rule == "surface.mount-collision")
            .expect("two owners of one path is a collision");
        assert!(collision.surface.contains(RUSTDOC), "{}", collision.surface);
        assert!(
            collision.surface.contains("rust-api"),
            "{}",
            collision.surface
        );
        // each side says where its claim came from, so the reader knows which to move
        assert!(
            collision
                .message
                .contains("target/web/rust-api/surface.json"),
            "{}",
            collision.message
        );
        let reserved = findings
            .iter()
            .find(|f| f.rule == "surface.reserved-namespace" && f.surface == "rust-api")
            .expect("the copy is refused by name, not only as half of a collision");
        assert!(
            reserved.message.contains(RUSTDOC_MOUNT),
            "{}",
            reserved.message
        );

        // and the reservation holds with the owner gone: in a repository whose crate was
        // moved, nothing else may help itself to the reference's name
        std::fs::remove_dir_all(&krate).unwrap();
        let orphaned = discover::discover(tmp.path(), Runtime::full()).unwrap();
        assert!(orphaned.get(RUSTDOC).is_none());
        let findings = validate(&orphaned, tmp.path(), Artifacts::Ignore);
        assert!(
            findings
                .iter()
                .any(|f| f.rule == "surface.reserved-namespace" && f.surface == "rust-api"),
            "{findings:?}"
        );
    }

    #[test]
    fn a_surface_inside_the_rustdoc_mount_is_refused_as_nesting() {
        let t = Topology::new(vec![
            deployment("app"),
            surface("rustdoc", "/rustdoc", Some("target/web/rustdoc")),
            surface("search", "/rustdoc/search", Some("target/web/search")),
        ]);
        let findings = validate(&t, Path::new("/nonexistent"), Artifacts::Ignore);
        assert!(
            findings
                .iter()
                .any(|f| f.rule == "surface.nested-mount" && f.surface == "search inside rustdoc"),
            "{findings:?}"
        );
    }

    #[test]
    fn an_artifact_outside_the_generated_root_is_refused() {
        let t = Topology::new(vec![surface("rogue", "/rogue", Some("docs"))]);
        let findings = validate(&t, Path::new("/nonexistent"), Artifacts::Ignore);
        assert!(findings
            .iter()
            .any(|f| f.rule == "surface.artifact-outside-generated-root"));
    }

    #[test]
    fn an_artifact_that_walks_out_of_the_repository_is_refused() {
        let t = Topology::new(vec![surface(
            "rogue",
            "/rogue",
            Some("target/web/../../etc"),
        )]);
        let findings = validate(&t, Path::new("/nonexistent"), Artifacts::Ignore);
        assert!(findings
            .iter()
            .any(|f| f.rule == "surface.artifact-escapes"));
    }

    #[test]
    fn a_missing_directory_is_a_finding_only_when_the_artifact_is_required() {
        let t = Topology::new(vec![surface("tests", "/tests", Some("target/web/tests"))]);
        assert!(validate(&t, Path::new("/nonexistent"), Artifacts::Ignore).is_empty());
        let required = validate(&t, Path::new("/nonexistent"), Artifacts::Required);
        assert!(required.iter().any(|f| f.rule == "surface.artifact-absent"));
        assert!(blocking(&required));
    }

    #[test]
    fn adding_an_unrelated_surface_does_not_disturb_the_others() {
        let before = Topology::new(vec![
            deployment("app"),
            surface("tests", "/tests", Some("target/web/tests")),
        ]);
        let after = Topology::new(vec![
            deployment("app"),
            surface("tests", "/tests", Some("target/web/tests")),
            surface(
                "example-report",
                "/example-report",
                Some("target/web/example-report"),
            ),
        ]);
        assert!(validate(&after, Path::new("/nonexistent"), Artifacts::Ignore).is_empty());
        assert_eq!(before.owner("/tests/x").unwrap().id, "tests");
        assert_eq!(after.owner("/tests/x").unwrap().id, "tests");
        assert_eq!(
            after.owner("/example-report/i").unwrap().id,
            "example-report"
        );
    }
}