razeri-plugin-contract 0.4.0

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

//! **Whether this engine actually checks the constraints it accepts** — the
//! dialect's answer, and the one place the rendered DDL and the docs read it
//! from.
//!
//! A `PRIMARY KEY` that is enforced and a `PRIMARY KEY` that is decoration look
//! identical in a `CREATE TABLE`. On two of the engines Razeri renders for they
//! are the second thing, and until this seam existed the only place that fact
//! was written down was a book page:
//!
//! - **`BigQuery`** has the words for it. `PRIMARY KEY (x) NOT ENFORCED` is the
//!   only legal spelling — a bare `PRIMARY KEY` is refused — so the engine
//!   itself makes the declaration honest.
//! - **`Redshift`** has no such words. It accepts `PRIMARY KEY`, `FOREIGN KEY`
//!   and `UNIQUE`, enforces none of them, and there is no keyword to say so. A
//!   reader of that DDL has no way to tell it apart from `PostgreSQL`'s, which
//!   is the near-neighbour trap in its purest form.
//!
//! So the seam carries two things: the engine's own **keyword**, where it has
//! one, and a **note** the renderer writes above the constraint list, where it
//! does not. Both are the dialect's words.

/// Whether the engine checks the key, unique and check constraints it accepts.
///
/// `#[non_exhaustive]`, on this module's whole family's rule: Razeri adds an
/// arm when it has measured one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum ConstraintEnforcement {
    /// The engine rejects a row that violates a declared constraint. Eight of
    /// Razeri's registered platforms, and the default: claiming an engine
    /// checks nothing is the unusual assertion, and it is made deliberately,
    /// one dialect at a time.
    #[default]
    Enforced,
    /// **The engine accepts the declaration and checks nothing.** The
    /// constraint is metadata — an optimizer hint, or documentation — and a
    /// violating row is stored without complaint.
    DeclaredOnly(DeclaredOnly),
}

impl ConstraintEnforcement {
    /// The words appended to a rendered key constraint, or `""`.
    ///
    /// This is what [`crate::renderer::DdlRenderer::key_constraint_suffix`]
    /// answers by default, so a dialect states enforcement once and the suffix
    /// follows. Empty on an enforcing engine, and empty on a declaring engine
    /// that has no keyword for it.
    #[must_use]
    pub const fn keyword(self) -> &'static str {
        match self {
            ConstraintEnforcement::DeclaredOnly(declared) => declared.keyword,
            ConstraintEnforcement::Enforced => "",
        }
    }

    /// The sentence the rendered DDL carries above a table's constraints, or
    /// `None` where the engine enforces them.
    ///
    /// `None` on an engine whose *keyword* already says it: `NOT ENFORCED`
    /// written on the constraint line is more precise than a comment above it,
    /// and printing both would say the same thing twice in one statement.
    #[must_use]
    pub const fn ddl_note(self) -> Option<&'static str> {
        match self {
            ConstraintEnforcement::DeclaredOnly(declared) if declared.keyword.is_empty() => {
                Some(declared.note)
            }
            _ => None,
        }
    }

    /// Whether the engine leaves declared constraints unchecked — the fact the
    /// platform docs and the conformance report read.
    #[must_use]
    pub const fn is_declared_only(self) -> bool {
        matches!(self, ConstraintEnforcement::DeclaredOnly(_))
    }
}

/// What a declaring-but-not-enforcing engine says about its own constraints.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DeclaredOnly {
    /// **The engine's own words, appended to every key constraint it renders**
    /// — `BigQuery`'s `" NOT ENFORCED"`, leading space included, because the
    /// suffix is concatenated onto the constraint text.
    ///
    /// `""` where the engine has no such keyword. That is not a lesser answer:
    /// it is the honest one for `Redshift`, and it is what routes the fact into
    /// [`ConstraintEnforcement::ddl_note`] instead.
    pub keyword: &'static str,
    /// **One sentence saying what this engine does with a declared
    /// constraint**, written for whoever is reading the rendered DDL.
    ///
    /// Say what is and is not guaranteed, and where the guarantee has to come
    /// from instead — a reader who learns only *"not enforced"* still does not
    /// know whether their data is safe. It is rendered inside a SQL comment,
    /// so keep it to prose and never spell a statement.
    ///
    /// Required even when `keyword` is non-empty: the docs read it in both
    /// cases, and only the DDL note is skipped where the keyword already
    /// speaks.
    pub note: &'static str,
}

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

    /// The default is the enforcing engine, which is eight of Razeri's ten and
    /// the safe thing to assume of a dialect that has not said.
    #[test]
    fn the_default_is_an_enforcing_engine() {
        assert_eq!(ConstraintEnforcement::default(), ConstraintEnforcement::Enforced);
        assert_eq!(ConstraintEnforcement::default().keyword(), "");
        assert_eq!(ConstraintEnforcement::default().ddl_note(), None);
        assert!(!ConstraintEnforcement::default().is_declared_only());
    }

    /// **The two shapes of "declared only", and the split between them is the
    /// point of the type.** An engine with a keyword writes it on the
    /// constraint; an engine without one gets the comment, and neither gets
    /// both.
    #[test]
    fn a_keyword_speaks_on_the_constraint_and_a_note_speaks_above_it() {
        let with_keyword = ConstraintEnforcement::DeclaredOnly(DeclaredOnly {
            keyword: " NOT ENFORCED",
            note: "keys here are optimizer metadata.",
        });
        assert_eq!(with_keyword.keyword(), " NOT ENFORCED");
        assert_eq!(
            with_keyword.ddl_note(),
            None,
            "the keyword is on the constraint line already — a comment saying it again is one \
             statement making the same claim twice"
        );
        assert!(with_keyword.is_declared_only());

        let without_keyword = ConstraintEnforcement::DeclaredOnly(DeclaredOnly {
            keyword: "",
            note: "this engine accepts the declaration and checks nothing.",
        });
        assert_eq!(without_keyword.keyword(), "");
        assert_eq!(
            without_keyword.ddl_note(),
            Some("this engine accepts the declaration and checks nothing."),
            "with no keyword the comment is the only place a reader of this DDL can learn it"
        );
        assert!(without_keyword.is_declared_only());
    }
}