razeri_plugin_api/

conformance.rs

// Copyright (C) 2026 Gabriel Shea
// Licensed under either of the Apache License, Version 2.0 or the MIT
// license, at your option.

//! **Every obligation a dialect owes, reported at once.**
//!
//! Two people built dialects against Razeri's authoring guide without help.
//! Between them they met twenty-seven obligations one `cargo test` at a time —
//! a roster fails, you add a row, the next roster fails. Not one of those
//! failures was discoverable before it fired. This module is the report that
//! answers all of them in one pass.
//!
//! # Running it
//!
//! From your own crate's tests, where your dialect is linked and Razeri's
//! registry can see it:
//!
//! ```no_run
//! # use razeri_plugin_api::conformance;
//! # fn example(my_dialect: &dyn razeri_plugin_api::PlatformDialect) {
//! let report = conformance::check(my_dialect);
//! assert!(report.is_clean(), "{report}");
//! # }
//! ```
//!
//! # What it can and cannot see
//!
//! Everything here is read off the dialect object, so it works wherever your
//! plugin compiles: it grades what your dialect declares and what its
//! renderers return. It runs no SQL, so anything only an engine can settle —
//! whether the SQL your dialect emits is the SQL that engine accepts — stays
//! yours to test against a real instance.
//!
//! # Your dialect's name
//!
//! Your platform's names are yours. `DialectInfo::name` is the one Razeri
//! reports, `aliases` is every other spelling a design may use for it, and the
//! resolver reads both off the dialects that are loaded — so the report asks
//! only that your own spellings reach you, and there is no table inside Razeri
//! for your platform to be missing from. The one thing it will tell you is that
//! a spelling you declared is one another loaded platform also answers to,
//! because then the spelling names neither of you.

use crate::PlatformDialect;
use razeri_plugin_contract::{
    ConstraintEnforcement, DataType, DdlRenderer, DialectCapabilities, DialectFamily, MergeShape,
    ProcedureForm, RoutineKind, RoutineSpec, ScalarFunctionForm, SqlRenderer, TableFunctionForm,
    UNKNOWN_PLATFORM,
};
use std::fmt;

/// How much a finding matters.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Severity {
    /// **This dialect will produce SQL its engine rejects.** Fix it before
    /// anything else.
    Blocking,
    /// **A question this dialect has not answered.** Razeri has a default and
    /// will use it; the default was written for a different engine.
    Unanswered,
    /// Worth a look. Nothing is broken.
    Note,
}

impl fmt::Display for Severity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::Blocking => "must fix",
            Self::Unanswered => "unanswered",
            Self::Note => "worth a look",
        })
    }
}

/// One thing to fix, in the order a reader wants it: what is wrong, then what
/// to do about it.
#[derive(Debug, Clone)]
pub struct Finding {
    /// How much it matters.
    pub severity: Severity,
    /// One line naming what is wrong.
    pub what: String,
    /// One line naming what to do.
    pub fix: String,
}

/// The whole report for one dialect.
#[derive(Debug, Clone)]
pub struct Report {
    /// The dialect's registry name.
    pub dialect: String,
    /// Everything found, worst first.
    pub findings: Vec<Finding>,
}

impl Report {
    /// Whether nothing blocking or unanswered was found.
    ///
    /// Notes do not fail a report: they are observations, not obligations.
    #[must_use]
    pub fn is_clean(&self) -> bool {
        !self.findings.iter().any(|f| f.severity != Severity::Note)
    }

    /// How many findings of one severity.
    #[must_use]
    pub fn count(&self, severity: Severity) -> usize {
        self.findings.iter().filter(|f| f.severity == severity).count()
    }
}

impl fmt::Display for Report {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let name = &self.dialect;
        if self.findings.is_empty() {
            return writeln!(
                f,
                "{name}: nothing to fix. Every question Razeri asks a dialect, this one answers."
            );
        }
        let blocking = self.count(Severity::Blocking);
        let unanswered = self.count(Severity::Unanswered);
        let notes = self.count(Severity::Note);
        writeln!(f, "{name}: {blocking} to fix, {unanswered} unanswered, {notes} worth a look.")?;
        for finding in &self.findings {
            writeln!(f)?;
            writeln!(f, "  [{}] {}", finding.severity, finding.what)?;
            writeln!(f, "      → {}", finding.fix)?;
        }
        Ok(())
    }
}

/// **The report.** Everything about this dialect that Razeri can check by
/// asking it.
///
/// Registration is checked against the dialects linked into this program. A
/// dialect the host loaded at run time is not among them, so report it with
/// [`check_with_registry`] and the registry it was loaded into.
#[must_use]
pub fn check(dialect: &dyn PlatformDialect) -> Report {
    check_with_registry(dialect, &crate::dialect::PlatformRegistry::with_auto_discovered())
}

/// The same report, against a registry the host built — the path for a dialect
/// loaded at run time rather than linked in.
#[must_use]
pub fn check_with_registry(
    dialect: &dyn PlatformDialect,
    registry: &crate::dialect::PlatformRegistry,
) -> Report {
    let info = dialect.info();
    let mut findings = Vec::new();

    check_registration(&info, registry, &mut findings);
    check_family(info.dialect_family, &mut findings);
    check_required_rendering(dialect, &mut findings);
    check_decisions(dialect, &mut findings);
    check_formula_renderer(dialect, &mut findings);
    check_paired_facts(dialect, &mut findings);

    findings.sort_by_key(|f| f.severity);
    Report { dialect: info.name.to_owned(), findings }
}

/// Every spelling this dialect answers to has to reach this dialect: its own
/// name, and each alias it declares.
///
/// That is the whole obligation, and it is one the author can meet from their
/// own crate — the spellings are the dialect's own, so there is no list inside
/// Razeri to be missing from and nothing here can ask for a change only Razeri
/// could make. What is worth saying is a spelling that reaches somewhere else:
/// one another loaded platform also claims (so it names neither, and Razeri
/// refuses it), or one that reaches a different platform because the registry
/// holds this dialect under another key.
fn check_registration(
    info: &crate::dialect::DialectInfo,
    registry: &crate::dialect::PlatformRegistry,
    findings: &mut Vec<Finding>,
) {
    let name = info.name;
    if matches!(
        crate::resolve::resolve_dialect_by_name_with_registry(name, registry),
        Err(crate::ResolveError::UnknownDialect { .. })
    ) {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "the name `{name}` does not resolve — nothing in this program registered it"
            ),
            fix: "add `inventory::submit! { DialectRegistration::new(\"<name>\", || \
                  Arc::new(MyDialect)) }` to your crate, and a `pub fn force_link() {}` beside \
                  it that the program using your dialect calls once. A crate nothing links is a \
                  crate the registry cannot see."
                .to_owned(),
        });
        return;
    }
    for spelling in info.spellings() {
        match crate::resolve::resolve_dialect_by_name_with_registry(spelling, registry) {
            Ok(found) if found.info().name == name => {}
            Ok(found) => findings.push(Finding {
                severity: Severity::Blocking,
                what: format!("`{spelling}` reaches `{}` rather than `{name}`", found.info().name),
                fix: format!(
                    "the registry holds `{name}` under another key. Register it under its own \
                     name, or drop `{spelling}` from its aliases."
                ),
            }),
            Err(crate::ResolveError::AmbiguousName { claimed_by, .. }) => findings.push(Finding {
                severity: Severity::Blocking,
                what: format!(
                    "`{spelling}` is claimed by more than one loaded platform ({}), so it names \
                     none of them — Razeri refuses that spelling rather than guessing which one \
                     a design meant",
                    claimed_by.join(" and ")
                ),
                fix: format!(
                    "give this dialect a name no other platform answers to. A platform name is \
                     read off the loaded dialects' own declared spellings, so a spelling another \
                     platform already claims is never `{name}`'s."
                ),
            }),
            Err(_) => findings.push(Finding {
                severity: Severity::Blocking,
                what: format!(
                    "`{spelling}` is declared as a spelling of `{name}` but reaches no platform"
                ),
                fix: format!(
                    "the `{name}` in the registry is a different build of this dialect and does \
                     not declare `{spelling}`. Register the one you are grading."
                ),
            }),
        }
    }
}

/// A family is a claim about spelling, so an unmeasured engine claiming a
/// measured family's name licenses SQL it may reject.
fn check_family(family: DialectFamily, findings: &mut Vec<Finding>) {
    if matches!(family, DialectFamily::Custom(name) if name.trim().is_empty()) {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "this dialect's family is a custom one with no name".to_owned(),
            fix: "give `DialectFamily::Custom` your engine's own name — it is what a report \
                  prints and what a reader looks up."
                .to_owned(),
        });
    }
}

/// The four required methods must answer for every type a design can declare.
fn check_required_rendering(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let declarable = declarable_types();
    let empty_column: Vec<String> = declarable
        .iter()
        .filter(|dt| SqlRenderer::render_data_type(dialect, dt).trim().is_empty())
        .map(|dt| format!("{dt:?}"))
        .collect();
    if !empty_column.is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "`render_data_type` answers nothing for {} of the types a design can declare",
                empty_column.len()
            ),
            fix: "every declarable type needs a column spelling on this engine, even if the \
                  spelling is a wider type that stores it. A blank answer becomes a column \
                  declaration with no type in it."
                .to_owned(),
        });
    }
    let empty_cast: Vec<String> = declarable
        .iter()
        .filter(|dt| SqlRenderer::render_cast_type(dialect, dt).trim().is_empty())
        .map(|dt| format!("{dt:?}"))
        .collect();
    if !empty_cast.is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "`render_cast_type` answers nothing for {} declarable types",
                empty_cast.len()
            ),
            fix: "the generated load opens by casting every source column to its declared type, \
                  so a blank answer fails the load on its first statement."
                .to_owned(),
        });
    }
    let quoted = SqlRenderer::quote_identifier(dialect, "order");
    if quoted == "order" {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "`quote_identifier` returns the identifier unchanged, so a reserved word \
                   reaches this engine bare"
                .to_owned(),
            fix: "wrap the identifier in whatever this engine quotes with — double quotes, \
                  backticks, or brackets."
                .to_owned(),
        });
    }
    if SqlRenderer::render_current_timestamp(dialect).trim().is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "`render_current_timestamp` answers nothing, and every generated load stamps \
                   a row with it"
                .to_owned(),
            fix: "return this engine's own expression for the current moment.".to_owned(),
        });
    }
}

/// The decisions a dialect states rather than inherits.
fn check_decisions(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let spelling = SqlRenderer::sid_spelling(dialect);
    if spelling.platform == UNKNOWN_PLATFORM {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "this dialect states no surrogate-key spelling, so every key it renders calls \
                   an `xxhash64` its engine very likely does not have"
                .to_owned(),
            fix: "override `SqlRenderer::sid_spelling`. Say what this engine calls LOWER and \
                  TRIM, how it joins strings, how it casts to text, and how it spells a 64-bit \
                  hash. If it has no portable hash, name an artifact your prerequisites install \
                  — never the nearest-looking built-in, which keys a warehouse to a number \
                  nothing else can reproduce."
                .to_owned(),
        });
    }

    // **A stated body that says nothing is worse than no body at all.** Razeri
    // writes the `CREATE FUNCTION` envelope around whatever comes back, so an
    // empty one deploys cleanly and returns nothing — every key in the
    // warehouse is then the sentinel or garbage, under a green deploy.
    if let Some(supplied) = SqlRenderer::sid_helper_body(dialect)
        && supplied.body.trim().is_empty()
    {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "this dialect says its surrogate-key helper has a body Razeri cannot compose, \
                   and then supplies an empty one"
                .to_owned(),
            fix: "return the body that computes XXH64 with seed 0 over the UTF-8 bytes of the \
                  one argument, or answer `None` and let Razeri compose the derivation from \
                  your `sid_spelling`. An empty body deploys without error and keys every row \
                  to nothing."
                .to_owned(),
        });
    }

    // A file relation that drops its path reads the same file for every entity
    // — one table filled, the rest filled wrong, and nothing about it fails.
    let probe = "'/razeri/probe.csv'";
    if let Some(relation) = SqlRenderer::delimited_file_relation(dialect, probe)
        && !relation.contains(probe)
    {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "`delimited_file_relation` returns a relation that does not carry the path it \
                   was given"
                .to_owned(),
            fix: "put the literal you were handed where your engine's file relation takes a \
                  path. It arrives already quoted and escaped. A relation that drops it reads \
                  one file for every entity the design binds, and the generated fill loads the \
                  wrong rows without failing."
                .to_owned(),
        });
    }

    check_routine_forms(dialect, findings);

    // The note is what a reader of the DDL learns from, and on an engine with
    // no keyword of its own it is the ONLY place they can learn it.
    if let ConstraintEnforcement::DeclaredOnly(declared) =
        DdlRenderer::constraint_enforcement(dialect)
        && declared.note.split_whitespace().count() < 5
    {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "this dialect says its engine accepts constraints it does not enforce, and \
                   the note explaining that says almost nothing"
                .to_owned(),
            fix: "a reader of your rendered DDL sees a PRIMARY KEY that looks like a \
                  guarantee. Say what this engine really does with the declaration, and where \
                  the guarantee has to come from instead."
                .to_owned(),
        });
    }

    // **The two refusals are different findings, and that is the point of the
    // second variant.** `None` is silence, and silence is unanswered. A stated
    // `Unsupported` is a measured claim; what is left to grade there is whether
    // the sentence is worth reading, because it is the only thing an operator
    // gets where the load would have been.
    match DialectCapabilities::merge_shape(dialect) {
        MergeShape::None => findings.push(Finding {
            severity: Severity::Unanswered,
            what: "this dialect has not stated its upsert shape, so Razeri writes no generated \
                   load for it"
                .to_owned(),
            fix: "if this engine has a MERGE or an upsert statement, say which in \
                  `DialectCapabilities::merge_shape`. If it genuinely has neither, answer \
                  `MergeShape::Unsupported` with your engine's own sentence — a refusal an \
                  operator can act on, rather than a silence."
                .to_owned(),
        }),
        MergeShape::Unsupported(orientation) => {
            check_refusal_copy("the upsert refusal", orientation, findings);
        }
        _ => {}
    }
}

/// The one override nothing tells an author about, and every formula in every
/// design goes through it.
fn check_formula_renderer(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let formula = SqlRenderer::to_formula_renderer(dialect);
    let dialect_name = SqlRenderer::dialect_name(dialect);
    if formula.dialect_name() != dialect_name && dialect_name != "ansi" {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "`to_formula_renderer` was not overridden, so every formula in every design \
                   renders through Razeri's ANSI defaults instead of this dialect"
                .to_owned(),
            fix: "return `Box::new(Self)`. It is one line, nothing fails without it, and every \
                  formula this engine sees is silently somebody else's."
                .to_owned(),
        });
    }
}

/// **The three routine grammars a dialect states**, and what each answer owes.
///
/// A grammar Razeri carries needs nothing further. A refusal owes words a
/// reader can act on. `Custom` owes the render method it promised — see
/// [`check_custom_grammar`].
fn check_routine_forms(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    match SqlRenderer::procedure_form(dialect) {
        // Razeri's own agnostic renderer answers `Agnostic` on purpose: the
        // annotated form IS its output. Every other dialect that answers it has
        // simply not said.
        ProcedureForm::Agnostic if SqlRenderer::is_agnostic_dialect(dialect) => {}
        ProcedureForm::Agnostic => findings.push(Finding {
            severity: Severity::Unanswered,
            what: "this dialect states no stored-procedure grammar, so Razeri emits its own \
                   annotated form — which no engine parses"
                .to_owned(),
            fix: "override `SqlRenderer::procedure_form` with the grammar this engine speaks, \
                  or with `ProcedureForm::Unsupported(\"…\")` and a sentence saying what it \
                  offers instead."
                .to_owned(),
        }),
        ProcedureForm::Unsupported(orientation) => {
            check_refusal_copy("the stored-procedure refusal", orientation, findings);
        }
        ProcedureForm::Custom(grammar) => check_custom_grammar(
            CustomGrammar {
                kind: RoutineKind::Procedure,
                grammar,
                form_method: "procedure_form",
                render_method: "render_procedure",
                noun: "procedures",
            },
            |spec| SqlRenderer::render_procedure(dialect, spec),
            findings,
        ),
        _ => {}
    }

    match SqlRenderer::scalar_function_form(dialect) {
        ScalarFunctionForm::Unsupported(orientation) => {
            check_refusal_copy("the scalar-function refusal", orientation, findings);
        }
        ScalarFunctionForm::Custom(grammar) => check_custom_grammar(
            CustomGrammar {
                kind: RoutineKind::ScalarFunction,
                grammar,
                form_method: "scalar_function_form",
                render_method: "render_scalar_function",
                noun: "scalar functions",
            },
            |spec| SqlRenderer::render_scalar_function(dialect, spec),
            findings,
        ),
        _ => {}
    }

    match SqlRenderer::table_function_form(dialect) {
        TableFunctionForm::Unsupported(orientation) => {
            check_refusal_copy("the table-function refusal", orientation, findings);
        }
        TableFunctionForm::Custom(grammar) => check_custom_grammar(
            CustomGrammar {
                kind: RoutineKind::TableFunction,
                grammar,
                form_method: "table_function_form",
                render_method: "render_table_function",
                noun: "table functions",
            },
            |spec| SqlRenderer::render_table_function(dialect, spec),
            findings,
        ),
        _ => {}
    }
}

/// One routine kind whose grammar a dialect said it spells itself.
#[derive(Clone, Copy)]
struct CustomGrammar {
    /// Which routine kind the claim is about.
    kind: RoutineKind,
    /// The grammar's own name, as the dialect wrote it.
    grammar: &'static str,
    /// The method that carried the claim.
    form_method: &'static str,
    /// The method that owes the rendering.
    render_method: &'static str,
    /// What to call the routines in a sentence.
    noun: &'static str,
}

/// **A dialect that says it spells its own grammar has to spell it.**
///
/// `Custom` moves the whole rendering to the dialect: Razeri substitutes no
/// near-neighbour grammar and refuses nothing, because both of those say
/// something false — one about the engine's syntax, the other about whether the
/// engine has the routine at all. So the claim is only worth anything with the
/// method behind it, and a dialect that made the claim and left the method
/// alone ships a build that stops on the routine.
///
/// The check is the question itself: hand the render method the shape it will
/// receive and see whether anything comes back.
///
/// Parameters:
/// - `claim`: which kind, which grammar, and the two method names to name;
/// - `render`: the dialect's render method for that kind;
/// - `findings`: where the report is collected.
fn check_custom_grammar(
    claim: CustomGrammar,
    render: impl Fn(&RoutineSpec) -> Option<String>,
    findings: &mut Vec<Finding>,
) {
    let CustomGrammar { kind, grammar, form_method, render_method, noun } = claim;
    // The grammar's name is a name, not a refusal: it is read in a report and
    // in a comment, so it has to say something and does not have to say much.
    if grammar.trim().is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!("`{form_method}` says Custom, and names no grammar"),
            fix: "carry your grammar's own name — `Custom(\"PL/SQL\")`. It is what a reader \
                  of a report, and of the comment Razeri writes where a routine could not be \
                  rendered, is told this engine speaks."
                .to_owned(),
        });
    }

    let mut probe = RoutineSpec::new(kind, "razeri_conformance_probe");
    probe.or_replace = true;
    if render(&probe).is_none_or(|rendered| rendered.trim().is_empty()) {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "`{form_method}` says Custom({grammar:?}), so this dialect must render {noun} \
                 itself — and `{render_method}` returns nothing"
            ),
            fix: format!(
                "override `SqlRenderer::{render_method}`. It receives the routine Razeri \
                 composed — name, parameters with their types already in your spelling, body, \
                 comment — and returns the whole CREATE statement your engine parses. Razeri \
                 emits what you return and writes nothing of its own: a near-neighbour grammar \
                 fails on deploy, and a refusal would say this engine has no {noun} when it \
                 has them in a grammar of its own."
            ),
        });
    }
}

/// A refusal that does not say what to do instead is a wall.
fn check_refusal_copy(subject: &str, copy: &str, findings: &mut Vec<Finding>) {
    if copy.trim().is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!("{subject} has no words in it"),
            fix: "say what this engine offers instead. A reader who hits a refusal needs the \
                  next thing to try, and it has to be about their engine."
                .to_owned(),
        });
        return;
    }
    if copy.split_whitespace().count() < 5 {
        findings.push(Finding {
            severity: Severity::Note,
            what: format!("{subject} is very short"),
            fix: "a refusal earns its place by naming the alternative — what this engine has \
                  instead of the thing it cannot do."
                .to_owned(),
        });
    }
}

/// Fourteen facts are declared twice and must agree.
fn check_paired_facts(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let caps: &dyn DialectCapabilities = dialect;
    let ren: &dyn SqlRenderer = dialect;
    let ddl: &dyn DdlRenderer = dialect;
    let mut disagreements: Vec<&'static str> = Vec::new();

    macro_rules! pair {
        ($m:ident, $renderer_value:expr) => {
            if caps.$m() != $renderer_value {
                disagreements.push(stringify!($m));
            }
        };
    }
    pair!(supports_on_conflict, ren.supports_on_conflict());
    pair!(supports_insert_overwrite, ren.supports_insert_overwrite());
    pair!(supports_update_from, ren.supports_update_from());
    pair!(supports_named_windows, ren.supports_named_windows());
    pair!(supports_compound_assignment, ren.supports_compound_assignment());
    pair!(supports_window_frame_exclude, ren.supports_window_frame_exclude());
    pair!(supports_merge_not_matched_by_source, ren.supports_merge_not_matched_by_source());
    pair!(merge_not_matched_keyword, ren.merge_not_matched_keyword());
    pair!(uses_alter_table_update, ren.uses_alter_table_update());
    pair!(supports_multi_table_insert, ren.supports_multi_table_insert());
    pair!(supports_cascade_drop, ddl.supports_cascade_drop());
    pair!(supports_sync_drop, ddl.supports_sync_drop());
    pair!(supports_force_drop, ddl.supports_force_drop());

    // **The fourteenth, whose two sides are different types.** The capability
    // is a boolean; the renderer answer is a form that either renders or
    // carries a refusal. Both are read — the build door reads the form, and
    // registry-walking rosters read the capability — so a dialect claiming a
    // table function on one side and refusing on the other has an engine that
    // both does and does not have one. `SQLite` was exactly that on the day
    // this check was written: `false` since the capability existed, and a
    // renderer still inheriting PostgreSQL's `RETURNS TABLE`.
    if caps.supports_table_functions() != ren.table_function_form().refusal().is_none() {
        disagreements.push("supports_table_functions");
    }

    if !disagreements.is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "this dialect declares {} fact(s) two ways and the two disagree: {}",
                disagreements.len(),
                disagreements.join(", ")
            ),
            fix: "each of these is declared once on the capability trait and once in the \
                  renderer hierarchy, and Razeri reads both. Decide which is true of your engine \
                  and move the other one to match."
                .to_owned(),
        });
    }
}

/// Every type a design can declare, which is the set the required methods owe
/// an answer for.
fn declarable_types() -> Vec<DataType> {
    vec![
        DataType::tinyint(),
        DataType::smallint(),
        DataType::int(),
        DataType::bigint(),
        DataType::double(),
        DataType::boolean(),
        DataType::text(),
        DataType::varchar(200),
        DataType::uuid(),
        DataType::json(),
        DataType::date(),
        DataType::timestamp(),
        DataType::timestamp_tz(),
        DataType::decimal(18, 2),
    ]
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dialect::DialectInfo;
    use razeri_plugin_contract::{
        Concat, DmlRenderer, ExpressionRenderer, FormulaRenderer, MergeRestrictions,
        ProcedureRenderer, ReplicationRenderer, ScalarFunctionForm, SidSpelling, StorageRenderer,
        TaskRenderer, TextCast,
    };
    use std::marker::PhantomData;

    // ── The broken fixture ────────────────────────────────────────────
    //
    // A plugin that compiles, registers nothing it should, and answers every
    // question with somebody else's default. This is what the kit exists to
    // catch, and it is deliberately the plugin an author gets by implementing
    // only the four required methods and stopping — which the guide, until
    // now, told them was enough.

    struct BrokenPlugin;

    impl SqlRenderer for BrokenPlugin {
        fn render_data_type(&self, _dt: &DataType) -> String {
            String::new()
        }
        fn quote_identifier(&self, name: &str) -> String {
            name.to_owned()
        }
        fn render_cast_type(&self, _dt: &DataType) -> String {
            String::new()
        }
        fn qualify_name(&self, _schema: Option<&str>, name: &str) -> String {
            name.to_owned()
        }
        fn render_current_timestamp(&self) -> String {
            String::new()
        }
        fn dialect_name(&self) -> &'static str {
            "brokendb"
        }
        // No `sid_spelling`, no `procedure_form`, no `to_formula_renderer` —
        // and one fact declared twice, two ways.
        fn supports_on_conflict(&self) -> bool {
            true
        }
    }
    impl ExpressionRenderer for BrokenPlugin {}
    impl DdlRenderer for BrokenPlugin {}
    impl DmlRenderer for BrokenPlugin {}
    impl ProcedureRenderer for BrokenPlugin {}
    impl FormulaRenderer for BrokenPlugin {}
    impl TaskRenderer for BrokenPlugin {}
    impl ReplicationRenderer for BrokenPlugin {}
    impl StorageRenderer for BrokenPlugin {}
    impl DialectCapabilities for BrokenPlugin {
        fn supports_on_conflict(&self) -> bool {
            false
        }
    }
    impl PlatformDialect for BrokenPlugin {
        fn info(&self) -> DialectInfo {
            DialectInfo {
                name: "brokendb",
                display_name: "Broken DB",
                aliases: &[],
                dialect_family: DialectFamily::Custom(""),
                family: "Broken",
                is_cloud_native: false,
                is_olap: false,
                is_postgres_compatible: false,
            }
        }
    }

    // ── The answered fixture, under two names ─────────────────────────
    //
    // The same plugin with every question answered, carrying the name it
    // registers under as a type parameter. Neither name is one Razeri knows a
    // spelling for; the difference is that one of them is in the registry and
    // the other is in nothing at all. Those are two different facts about a
    // dialect, and they read as two different reports.

    trait FixtureName: Send + Sync + 'static {
        /// The registry name this fixture answers to.
        const NAME: &'static str;
        /// How this fixture's engine joins the parts of a composite key. Most
        /// of them take the inherited variadic `CONCAT`; the one that does not
        /// is the point of it being a knob.
        const CONCAT: Concat = Concat::Function("CONCAT");
    }

    /// Answered, and nothing linked it — what an author sees running the report
    /// from a crate whose registration nobody calls.
    struct Unlinked;
    impl FixtureName for Unlinked {
        const NAME: &'static str = "healthydb";
    }

    /// Answered and registered, under a name Razeri ships no spelling for —
    /// the shape of every dialect written outside Razeri's own tree.
    struct Outside;
    impl FixtureName for Outside {
        const NAME: &'static str = "outsidedb";
    }

    /// Answered, and joining composite keys with a `CONCAT` that takes exactly
    /// two arguments — the shape of Db2 and of older Oracle releases. Nothing
    /// about the join is an obligation, so the report on it must read exactly
    /// like the report on a variadic engine.
    struct BinaryConcat;
    impl FixtureName for BinaryConcat {
        const NAME: &'static str = "binaryconcatdb";
        const CONCAT: Concat = Concat::FunctionBinary("CONCAT");
    }

    struct Answered<N: FixtureName>(PhantomData<N>);

    impl<N: FixtureName> Answered<N> {
        const fn new() -> Self {
            Self(PhantomData)
        }
    }

    type HealthyPlugin = Answered<Unlinked>;
    type OutsidePlugin = Answered<Outside>;

    inventory::submit! {
        crate::builder::DialectRegistration::new(
            Outside::NAME,
            || std::sync::Arc::new(OutsidePlugin::new()),
        )
    }

    impl<N: FixtureName> SqlRenderer for Answered<N> {
        fn render_data_type(&self, dt: &DataType) -> String {
            razeri_plugin_contract::agnostic::render_data_type_ansi(dt)
        }
        fn quote_identifier(&self, name: &str) -> String {
            format!("\"{name}\"")
        }
        fn qualify_name(&self, schema: Option<&str>, name: &str) -> String {
            schema.map_or_else(
                || self.quote_identifier(name),
                |s| format!("{}.{}", self.quote_identifier(s), self.quote_identifier(name)),
            )
        }
        fn render_current_timestamp(&self) -> String {
            "NOW()".to_owned()
        }
        fn dialect_name(&self) -> &'static str {
            N::NAME
        }
        fn sid_spelling(&self) -> SidSpelling {
            SidSpelling {
                platform: N::NAME,
                hash: ("answered_xxhash64(", ")"),
                cast_type: TextCast::Direct("STRING"),
                concat: N::CONCAT,
                through_helper: false,
                ..razeri_plugin_contract::ANSI_SID_SPELLING
            }
        }
        fn procedure_form(&self) -> ProcedureForm {
            ProcedureForm::Unsupported(
                "This engine has no stored procedures; write the load as a scheduled query \
                 instead.",
            )
        }
        fn scalar_function_form(&self) -> ScalarFunctionForm {
            ScalarFunctionForm::PostgreSql
        }
        fn to_formula_renderer(&self) -> Box<dyn FormulaRenderer> {
            Box::new(Self::new())
        }
    }
    impl<N: FixtureName> ExpressionRenderer for Answered<N> {}
    impl<N: FixtureName> DdlRenderer for Answered<N> {}
    impl<N: FixtureName> DmlRenderer for Answered<N> {}
    impl<N: FixtureName> ProcedureRenderer for Answered<N> {}
    impl<N: FixtureName> FormulaRenderer for Answered<N> {}
    impl<N: FixtureName> TaskRenderer for Answered<N> {}
    impl<N: FixtureName> ReplicationRenderer for Answered<N> {}
    impl<N: FixtureName> StorageRenderer for Answered<N> {}
    impl<N: FixtureName> DialectCapabilities for Answered<N> {
        fn merge_shape(&self) -> MergeShape {
            MergeShape::Merge(MergeRestrictions::none())
        }
    }
    impl<N: FixtureName> PlatformDialect for Answered<N> {
        fn info(&self) -> DialectInfo {
            DialectInfo {
                name: N::NAME,
                display_name: "An Answered Engine",
                // It answers to its own name and nothing else, which is the
                // shape of a plugin that declares no extra spellings.
                aliases: &[],
                dialect_family: DialectFamily::Custom(N::NAME),
                family: "Answered",
                is_cloud_native: false,
                is_olap: false,
                is_postgres_compatible: false,
            }
        }
    }

    // ── The twin: a dialect that claims a name another platform answers to ──
    //
    // Answered in every other respect, so the only thing its report can be
    // about is the spelling it took.

    struct Twin;

    impl SqlRenderer for Twin {
        fn render_data_type(&self, dt: &DataType) -> String {
            razeri_plugin_contract::agnostic::render_data_type_ansi(dt)
        }
        fn quote_identifier(&self, name: &str) -> String {
            format!("\"{name}\"")
        }
        fn qualify_name(&self, _schema: Option<&str>, name: &str) -> String {
            self.quote_identifier(name)
        }
        fn render_current_timestamp(&self) -> String {
            "NOW()".to_owned()
        }
    }
    impl ExpressionRenderer for Twin {}
    impl DdlRenderer for Twin {}
    impl DmlRenderer for Twin {}
    impl ProcedureRenderer for Twin {}
    impl FormulaRenderer for Twin {}
    impl TaskRenderer for Twin {}
    impl ReplicationRenderer for Twin {}
    impl StorageRenderer for Twin {}
    impl DialectCapabilities for Twin {}
    impl PlatformDialect for Twin {
        fn info(&self) -> DialectInfo {
            DialectInfo {
                name: "twindb",
                display_name: "Twin DB",
                // The name the answered fixture already answers to.
                aliases: &["healthydb"],
                dialect_family: DialectFamily::Custom("twindb"),
                family: "Twin",
                is_cloud_native: false,
                is_olap: false,
                is_postgres_compatible: false,
            }
        }
    }

    /// Every finding whose `what` line mentions one of these subjects.
    fn mentions(report: &Report, needle: &str) -> bool {
        report.findings.iter().any(|f| f.what.contains(needle) || f.fix.contains(needle))
    }

    /// **The kit's own red.** A plugin that implements the four required
    /// methods and stops is exactly what the guide used to produce, and every
    /// one of these findings is a defect a shipped dialect actually had.
    #[test]
    fn the_kit_catches_a_deliberately_broken_plugin() {
        let report = check(&BrokenPlugin);
        assert!(!report.is_clean(), "the broken plugin reported clean:\n{report}");

        assert!(mentions(&report, "does not resolve"), "unregistered:\n{report}");
        assert!(mentions(&report, "custom one with no name"), "unnamed family:\n{report}");
        assert!(mentions(&report, "render_data_type"), "empty column types:\n{report}");
        assert!(mentions(&report, "render_cast_type"), "empty cast types:\n{report}");
        assert!(mentions(&report, "identifier unchanged"), "no quoting:\n{report}");
        assert!(mentions(&report, "render_current_timestamp"), "no now():\n{report}");
        assert!(mentions(&report, "surrogate-key spelling"), "unspelled key:\n{report}");
        assert!(mentions(&report, "stored-procedure grammar"), "no procedure form:\n{report}");
        assert!(mentions(&report, "upsert shape"), "no merge shape:\n{report}");
        assert!(mentions(&report, "to_formula_renderer"), "formula renderer:\n{report}");
        assert!(mentions(&report, "supports_on_conflict"), "paired fact:\n{report}");

        assert!(
            report.count(Severity::Blocking) >= 8,
            "the broken plugin owes more than {} blocking fixes:\n{report}",
            report.count(Severity::Blocking)
        );
    }

    /// **The kit does not cry wolf.** The same plugin with its questions
    /// answered reports only what is actually true of it: it is not
    /// registered in this test binary, and nothing else.
    #[test]
    fn the_kit_reports_only_registration_on_a_plugin_that_answered_everything() {
        let report = check(&HealthyPlugin::new());
        let unregistered: Vec<&Finding> =
            report.findings.iter().filter(|f| f.what.contains("does not resolve")).collect();
        assert_eq!(unregistered.len(), 1, "the registration finding is the honest one here");
        assert_eq!(
            report.findings.len(),
            1,
            "a plugin that answered every question owes nothing else:\n{report}"
        );
    }

    /// **A join written for a two-argument `CONCAT` is an answer, not a
    /// shortfall.** The report on a dialect that states it reads exactly like
    /// the report on a variadic one, and the key it renders nests pairwise
    /// instead of widening a call the engine does not have.
    #[test]
    fn the_kit_takes_a_two_argument_concat_as_an_answer_like_any_other() {
        let binary = Answered::<BinaryConcat>::new();
        let report = check(&binary);
        assert_eq!(
            report.findings.len(),
            check(&HealthyPlugin::new()).findings.len(),
            "the join form is a decision, so stating this one owes nothing extra:\n{report}"
        );
        assert!(
            !report.to_string().contains("joins"),
            "nothing about the join is outstanding:\n{report}"
        );

        let key = razeri_plugin_contract::sid::sid_expression(
            SqlRenderer::sid_spelling(&binary),
            None,
            &["a".to_owned(), "b".to_owned(), "c".to_owned()],
        );
        assert!(
            key.contains("CONCAT(CONCAT("),
            "a two-argument engine gets one call per pair:\n{key}"
        );
    }

    /// **A dialect written outside Razeri reaches a clean report.** It is
    /// reached the way every out-of-tree dialect is reached — it registered, and
    /// the resolver reads the loaded dialects' own declared spellings — so there
    /// is nothing for Razeri to be missing it from and nothing for the report to
    /// ask of its author.
    #[test]
    fn a_dialect_registered_under_its_own_name_reaches_a_clean_report() {
        assert!(
            crate::resolve_dialect_by_name(Outside::NAME).is_ok(),
            "the fixture registers through the registry, which is the whole path being graded"
        );
        // The precondition that used to read "no row in Razeri's table": no
        // other loaded platform declares this name, so the fixture is reached
        // only because it registered and said so itself.
        let registry = crate::dialect::PlatformRegistry::with_auto_discovered();
        assert!(
            registry
                .list()
                .iter()
                .filter(|info| info.name != Outside::NAME)
                .all(|info| !info.answers_to(Outside::NAME)),
            "the fixture's name must be one no other platform claims"
        );

        let report = check(&OutsidePlugin::new());
        assert!(report.findings.is_empty(), "nothing is owed here:\n{report}");
        assert!(report.is_clean(), "and the report says so:\n{report}");
        assert_eq!(report.count(Severity::Blocking), 0, "{report}");
        assert!(
            report.to_string().contains("nothing to fix"),
            "a clean dialect is told it is clean:\n{report}"
        );
    }

    /// **A platform cannot be reachable under an alias but not under its own
    /// name.** That used to be a judgement about a hand-written table, which
    /// could spell a platform `mynew_db` and never `mynewdb`. A dialect now
    /// declares its own spellings and its own name leads them, so the defect is
    /// unrepresentable rather than caught — and this is the assertion that keeps
    /// it that way.
    #[test]
    fn a_platform_is_never_reachable_by_an_alias_but_not_by_its_own_name() {
        let registry = crate::dialect::PlatformRegistry::with_auto_discovered();
        for info in registry.list() {
            assert_eq!(
                info.spellings().first().copied(),
                Some(info.name),
                "a platform's own name leads its spellings"
            );
            assert!(info.answers_to(info.name), "{} answers to its own name", info.name);
        }
    }

    /// **A name another platform already answers to is a collision, not a
    /// registration.** A dialect claiming a spelling Healthy DB answers to is
    /// named as the collision it is — with both platforms named, and a fix its
    /// author can actually perform — rather than being reported as an
    /// unregistered platform, which is a different problem with a different fix.
    #[test]
    fn a_name_razeri_reads_as_another_platform_is_blocking_and_says_which() {
        let mut registry = crate::dialect::PlatformRegistry::new();
        registry.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));
        registry.register("twindb".to_owned(), std::sync::Arc::new(Twin));

        let report = check_with_registry(&Twin, &registry);
        let collision = report
            .findings
            .iter()
            .find(|f| f.what.contains("claimed by more than one loaded platform"))
            .unwrap_or_else(|| panic!("the collision is reported:\n{report}"));
        assert_eq!(collision.severity, Severity::Blocking, "{collision:?}");
        assert!(collision.what.contains("healthydb"), "the other platform is named: {collision:?}");
        assert!(collision.what.contains("twindb"), "{collision:?}");
        assert!(collision.fix.contains("name no other platform answers to"), "{collision:?}");
        assert!(
            !mentions(&report, "does not resolve"),
            "a collision is not an unregistered platform:\n{report}"
        );
    }

    /// A platform reached under its own name owes nothing, whatever the case or
    /// the surrounding whitespace, and a name nothing has ever heard of is
    /// simply unknown rather than a finding against this dialect.
    #[test]
    fn registration_is_silent_on_a_platform_reached_under_its_own_name() {
        let mut registry = crate::dialect::PlatformRegistry::new();
        registry.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));

        let mut findings = Vec::new();
        check_registration(&HealthyPlugin::new().info(), &registry, &mut findings);
        assert!(findings.is_empty(), "{findings:?}");

        for spelling in ["healthydb", "HealthyDB", "  healthydb  "] {
            assert!(
                crate::resolve::resolve_dialect_by_name_with_registry(spelling, &registry).is_ok(),
                "'{spelling}' is the same platform"
            );
        }
        assert!(
            crate::resolve::resolve_dialect_by_name_with_registry("nosuchdb", &registry).is_err()
        );
    }

    /// **A dialect the host loaded at run time can be graded at all.** [`check`]
    /// asks the dialects linked into this program, which one loaded from a
    /// shared library is not among; [`check_with_registry`] asks the registry it
    /// was loaded into, and the registration judgement is answered from there.
    #[test]
    fn a_dialect_the_host_loaded_reports_clean_against_its_own_registry() {
        let mut registry = crate::dialect::PlatformRegistry::new();
        registry.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));

        let report = check_with_registry(&HealthyPlugin::new(), &registry);
        assert!(
            report.is_clean(),
            "a loaded dialect that answered everything owes nothing:\n{report}"
        );
    }

    /// **Every fix an outside author can read is a fix in their own crate.** A
    /// report that names a file inside Razeri is telling an author to edit a
    /// tree they do not have, and the fix cannot be performed at all.
    #[test]
    fn no_fix_line_sends_an_author_into_razeris_own_tree() {
        let mut collided = crate::dialect::PlatformRegistry::new();
        collided.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));
        collided.register("twindb".to_owned(), std::sync::Arc::new(Twin));

        let mut fixes: Vec<String> = Vec::new();
        for report in [
            check(&BrokenPlugin),
            check(&HealthyPlugin::new()),
            check(&OutsidePlugin::new()),
            // The collision and the unregistered-name judgements, which are the
            // two registration findings an author can actually reach.
            check_with_registry(&Twin, &collided),
            check_with_registry(&Twin, &crate::dialect::PlatformRegistry::new()),
        ] {
            fixes.extend(report.findings.iter().map(|f| f.fix.clone()));
        }
        assert!(fixes.len() >= 10, "the sweep reached the findings: {}", fixes.len());
        for fix in &fixes {
            for path in ["schemas/", "crates/", ".json", "scripts/", "razeri-design"] {
                assert!(
                    !fix.contains(path),
                    "a fix line names `{path}`, which is not in the author's crate:\n  {fix}"
                );
            }
        }
    }

    /// **A dialect that claims its own grammar and does not spell it is
    /// blocking**, and the finding names the method it owes.
    ///
    /// `Custom` is a promise that the dialect renders the routine itself, and
    /// Razeri keeps its side by writing nothing: no near-neighbour grammar,
    /// which fails on deploy, and no refusal, which would tell an author their
    /// engine has no routines when it has a whole language. A promise with
    /// nothing behind it is therefore a build that stops, and it has to be
    /// findable before the deploy rather than during it.
    #[test]
    fn a_custom_grammar_without_a_render_method_is_blocking_on_all_three_kinds() {
        for (kind, form_method, render_method) in [
            (RoutineKind::Procedure, "procedure_form", "render_procedure"),
            (RoutineKind::ScalarFunction, "scalar_function_form", "render_scalar_function"),
            (RoutineKind::TableFunction, "table_function_form", "render_table_function"),
        ] {
            let mut promised = Vec::new();
            check_custom_grammar(
                CustomGrammar {
                    kind,
                    grammar: "PL/SQL",
                    form_method,
                    render_method,
                    noun: "routines",
                },
                |_| None,
                &mut promised,
            );
            assert_eq!(promised.len(), 1, "{form_method}: {promised:?}");
            assert_eq!(promised[0].severity, Severity::Blocking, "{promised:?}");
            assert!(promised[0].what.contains(form_method), "{promised:?}");
            assert!(promised[0].what.contains("PL/SQL"), "{promised:?}");
            assert!(promised[0].fix.contains(render_method), "{promised:?}");

            // The same claim, kept: nothing to report.
            let mut kept = Vec::new();
            check_custom_grammar(
                CustomGrammar {
                    kind,
                    grammar: "PL/SQL",
                    form_method,
                    render_method,
                    noun: "routines",
                },
                |spec| Some(format!("CREATE {} …", spec.name)),
                &mut kept,
            );
            assert!(kept.is_empty(), "{form_method}: a kept promise is not a finding: {kept:?}");
        }
    }

    /// **A render method that answers with nothing at all is the same defect.**
    ///
    /// An override that returns an empty string is a routine razeri would emit
    /// as blank space in the middle of a schema, which is worse than an error:
    /// nothing in the deploy says anything is missing.
    #[test]
    fn a_custom_render_method_that_returns_nothing_is_blocking() {
        let mut findings = Vec::new();
        check_custom_grammar(
            CustomGrammar {
                kind: RoutineKind::Procedure,
                grammar: "PL/SQL",
                form_method: "procedure_form",
                render_method: "render_procedure",
                noun: "procedures",
            },
            |_| Some("   \n".to_owned()),
            &mut findings,
        );
        assert_eq!(findings.len(), 1, "{findings:?}");
        assert_eq!(findings[0].severity, Severity::Blocking, "{findings:?}");
    }

    /// **A `Custom` grammar with no name gives a reader nothing to read.**
    #[test]
    fn a_custom_grammar_with_no_name_is_blocking() {
        let mut findings = Vec::new();
        check_custom_grammar(
            CustomGrammar {
                kind: RoutineKind::ScalarFunction,
                grammar: "  ",
                form_method: "scalar_function_form",
                render_method: "render_scalar_function",
                noun: "scalar functions",
            },
            |spec| Some(format!("CREATE FUNCTION {}", spec.name)),
            &mut findings,
        );
        assert_eq!(findings.len(), 1, "{findings:?}");
        assert!(findings[0].what.contains("names no grammar"), "{findings:?}");
    }

    /// **A stated fact that is empty, and a stated fact that ignores its
    /// argument.**
    ///
    /// Both answers deploy without an error and are wrong in the data: an empty
    /// helper body keys every row to nothing, and a file relation that drops
    /// its path reads one file for every entity a design binds. Neither is
    /// visible anywhere else, which is why the kit grades them.
    #[test]
    fn a_stated_key_body_that_is_blank_and_a_file_relation_that_drops_its_path_are_blocking() {
        struct Overstated;
        impl SqlRenderer for Overstated {
            fn render_data_type(&self, dt: &DataType) -> String {
                razeri_plugin_contract::agnostic::render_data_type_ansi(dt)
            }
            fn quote_identifier(&self, name: &str) -> String {
                format!("\"{name}\"")
            }
            fn qualify_name(&self, _schema: Option<&str>, name: &str) -> String {
                name.to_owned()
            }
            fn render_current_timestamp(&self) -> String {
                "CURRENT_TIMESTAMP".to_owned()
            }
            fn dialect_name(&self) -> &'static str {
                "overstateddb"
            }
            fn sid_helper_body(&self) -> Option<razeri_plugin_contract::SidHelperBody> {
                Some(razeri_plugin_contract::SidHelperBody {
                    language: razeri_plugin_contract::SidHelperLanguage::JavaScript,
                    body: "   \n  ",
                })
            }
            fn delimited_file_relation(&self, _path_literal: &str) -> Option<String> {
                Some("read_csv_auto('/tmp/whatever.csv')".to_owned())
            }
        }
        impl ExpressionRenderer for Overstated {}
        impl DdlRenderer for Overstated {}
        impl DmlRenderer for Overstated {}
        impl ProcedureRenderer for Overstated {}
        impl FormulaRenderer for Overstated {}
        impl TaskRenderer for Overstated {}
        impl ReplicationRenderer for Overstated {}
        impl StorageRenderer for Overstated {}
        impl DialectCapabilities for Overstated {}
        impl PlatformDialect for Overstated {
            fn info(&self) -> DialectInfo {
                DialectInfo {
                    name: "overstateddb",
                    display_name: "Overstated DB",
                    aliases: &[],
                    dialect_family: DialectFamily::Custom(""),
                    family: "Overstated",
                    is_cloud_native: false,
                    is_olap: false,
                    is_postgres_compatible: false,
                }
            }
        }

        let report = check(&Overstated);
        for (fragment, why) in [
            ("supplies an empty one", "a blank helper body"),
            ("does not carry the path", "a file relation that drops its path"),
        ] {
            let found = report
                .findings
                .iter()
                .find(|f| f.what.contains(fragment))
                .unwrap_or_else(|| panic!("{why} is not graded:\n{report}"));
            assert_eq!(found.severity, Severity::Blocking, "{why}: {found:?}");
        }

        // And silence is not a finding. The fully-answered fixture states
        // neither fact — the majority answer — and owes nothing for it.
        let quiet = check(&HealthyPlugin::new());
        for fragment in ["supplies an empty one", "does not carry the path"] {
            assert!(
                !quiet.findings.iter().any(|f| f.what.contains(fragment)),
                "silence is the default and owes nothing:\n{quiet}"
            );
        }
    }

    /// **A stated refusal is a claim, and a claim owes the reader words** — the
    /// same grading every other refusal gets, because these words are the only
    /// thing an operator finds where the load would have been.
    #[test]
    fn a_stated_upsert_refusal_is_graded_as_copy_and_a_silent_one_as_unanswered() {
        let mut mute = Vec::new();
        check_refusal_copy("the upsert refusal", "no merge", &mut mute);
        assert_eq!(mute.len(), 1, "a three-word refusal is a wall: {mute:?}");
        assert!(mute[0].what.contains("the upsert refusal"), "{mute:?}");

        let silence = check(&BrokenPlugin);
        assert!(
            silence
                .findings
                .iter()
                .any(|f| f.severity == Severity::Unanswered && f.what.contains("upsert shape")),
            "a dialect that never answered is unanswered, not wrong:\n{silence}"
        );
        assert!(
            silence.findings.iter().any(|f| f.fix.contains("MergeShape::Unsupported")),
            "the fix line names the way to state a measured refusal:\n{silence}"
        );
    }

    /// The report leads with what to fix and says it in words a reader can
    /// act on — no identifiers from Razeri's own record-keeping, and a
    /// one-line count before the detail.
    #[test]
    fn the_report_reads_as_a_summary_then_a_fix_list() {
        let text = check(&BrokenPlugin).to_string();
        let first = text.lines().next().expect("a summary line");
        assert!(first.starts_with("brokendb:"), "{first}");
        assert!(first.contains("to fix"), "{first}");
        assert!(text.contains("      → "), "every finding names the fix:\n{text}");
    }
}