razeri-plugin-contract 0.1.1

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

//! **Which routine grammar this engine speaks** — the dialect's answer, not a
//! core crate's guess about its name.
//!
//! A stored procedure, a scalar function and a table function are the three
//! places where an engine's SQL stops resembling every other engine's. Razeri
//! composes the routine's *content* — its parameters, its body, its comment —
//! and asks the dialect which grammar to spell it in.
//!
//! All three enums are `#[non_exhaustive]`: Razeri adds a form when it has
//! measured one, and a dialect must state a fallback rather than assume the
//! list it compiled against is the list that ships.
//!
//! # If none of these is your engine
//!
//! Pick the closest measured form and *run the result* — the near-neighbour
//! trap is real, and a form that almost fits fails at `CREATE`, not at review.
//! If nothing fits, [`ProcedureForm::Unsupported`] and
//! [`TableFunctionForm::Unsupported`] carry your own words, and those words are
//! what the author reads instead of another engine's.

/// Which stored-procedure grammar this engine speaks.
///
/// The default is [`ProcedureForm::Agnostic`], Razeri's own annotated form. It
/// parses nowhere: it is the honest answer for a dialect that has not said, and
/// the conformance kit reports it as an unanswered obligation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum ProcedureForm {
    /// PL/pgSQL — a dollar-quoted body with `DECLARE`, `SELECT … INTO`,
    /// `RAISE`, `IF` and an `EXCEPTION` block. `PostgreSQL`, Citus and
    /// `Redshift`, all three measured deploying and running.
    PlPgSql,
    /// `MySQL`/`MariaDB`'s compound statement — the same block structure with
    /// `DELIMITER`-free `BEGIN … END` and no dollar quoting.
    MySql,
    /// T-SQL — `CREATE PROCEDURE … AS BEGIN … END`, `@`-prefixed parameters.
    TSql,
    /// Snowflake Scripting.
    SnowflakeScripting,
    /// Databricks SQL scripting.
    Databricks,
    /// `ClickHouse`.
    ClickHouse,
    /// `GoogleSQL` scripting — `BigQuery`'s, whose body is not quoted at all.
    GoogleSql,
    /// Razeri's agnostic annotated form: ANSI SQL carrying `@razeri:` headers.
    /// It is a design artifact, not something an engine parses.
    #[default]
    Agnostic,
    /// **This engine has no stored procedures.** The string is the orientation
    /// an author reads instead of a syntax error — say what this engine offers
    /// in their place (`DuckDB`'s macros, `SQLite`'s application-level logic),
    /// because the sentence that helps is the one about *this* engine.
    Unsupported(&'static str),
}

/// Which scalar-function grammar this engine speaks.
///
/// The default is [`ScalarFunctionForm::PostgreSql`], which is what an
/// unlisted dialect has always been handed. It is a guess and a dangerous one
/// on a near neighbour: `LANGUAGE SQL IMMUTABLE PARALLEL SAFE` is a *"syntax
/// error at or near `PARALLEL`"* on `Redshift`, an engine that descends from
/// `PostgreSQL` and reports itself as one. State your form.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum ScalarFunctionForm {
    /// `CREATE FUNCTION … RETURNS … LANGUAGE SQL IMMUTABLE PARALLEL SAFE AS
    /// $$…$$` — `PostgreSQL`, Citus and Razeri's agnostic renderer.
    #[default]
    PostgreSql,
    /// `DuckDB`'s `CREATE MACRO`.
    DuckDb,
    /// T-SQL's scalar UDF.
    TSql,
    /// `ClickHouse`'s lambda `CREATE FUNCTION … AS (x) -> …`.
    ClickHouse,
    /// Snowflake's UDF.
    Snowflake,
    /// `MySQL`/`MariaDB`'s `CREATE FUNCTION … DETERMINISTIC`.
    MySql,
    /// Databricks SQL's UDF.
    Databricks,
    /// `GoogleSQL`'s `CREATE FUNCTION` — `BigQuery`'s.
    GoogleSql,
    /// `Redshift`'s: the volatility is mandatory rather than optional, there is
    /// no `PARALLEL SAFE`, `LANGUAGE` follows the body rather than preceding
    /// it, and the body addresses its parameters as `$1` and never by name.
    Redshift,
}

/// Which **table-valued function** grammar this engine speaks — the routine a
/// query selects `FROM`, returning columns rather than one value.
///
/// The default is [`TableFunctionForm::PostgreSql`], which is what an unlisted
/// dialect has always been handed. Four engines in Razeri's own set have no
/// table-valued function they can render, and each says so in **its own words**
/// through [`TableFunctionForm::Unsupported`] — because a refusal written once
/// per *kind* tells a `Redshift` author about `MySQL`, and the sentence that
/// helps is the one about their engine.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum TableFunctionForm {
    /// `CREATE FUNCTION … RETURNS TABLE(…)` / `RETURNS SETOF …` over a
    /// dollar-quoted body — `PostgreSQL`, Citus, and Razeri's agnostic
    /// renderer.
    #[default]
    PostgreSql,
    /// `DuckDB`'s table `MACRO`: `CREATE MACRO f(x) AS TABLE SELECT …`. There
    /// is no `RETURNS` clause at all, which is why riding the `PostgreSQL` arm
    /// was `Parser Error: syntax error at or near "RETURNS"`.
    DuckDb,
    /// `GoogleSQL`'s `CREATE TABLE FUNCTION` — `BigQuery`'s.
    GoogleSql,
    /// T-SQL's two shapes: the inline TVF (`RETURNS TABLE AS RETURN (…)`) and
    /// the multi-statement one (`RETURNS @t TABLE(…) BEGIN … RETURN END`).
    TSql,
    /// `ClickHouse`'s parameterized view, addressed with `{param:Type}`.
    ClickHouse,
    /// Snowflake's UDTF, including the staged-handler registration.
    Snowflake,
    /// Databricks SQL's `CREATE FUNCTION … RETURNS TABLE … RETURN <query>`.
    Databricks,
    /// **This engine has no table-valued function.**
    ///
    /// The string is the orientation an author reads — at build time, when
    /// Razeri refuses to write the routine, and again in the rendered refusal
    /// if anything asks the renderer directly. Write it fix-first: say what
    /// this engine offers *instead* before saying what it lacks, name the
    /// `artifact:` values a designer would reach for, and name the near form if
    /// there is one, because a near form the author will find on their own is
    /// the thing that costs them a day.
    ///
    /// It is prose that lands inside a SQL comment, so it must never spell a
    /// complete statement.
    Unsupported(&'static str),
}

impl TableFunctionForm {
    /// The dialect's own refusal wording, or `None` where this engine has the
    /// form.
    ///
    /// The one accessor both surfaces read — the build door that declines to
    /// write the routine, and the renderer that would otherwise emit DDL — so
    /// neither one carries a second copy of the words.
    #[must_use]
    pub const fn refusal(self) -> Option<&'static str> {
        match self {
            TableFunctionForm::Unsupported(orientation) => Some(orientation),
            _ => None,
        }
    }
}

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

    /// The defaults are what an undecided dialect gets, and they are the
    /// behaviour Razeri has always had for an unlisted platform.
    #[test]
    fn the_defaults_are_the_agnostic_procedure_and_the_postgres_functions() {
        assert_eq!(ProcedureForm::default(), ProcedureForm::Agnostic);
        assert_eq!(ScalarFunctionForm::default(), ScalarFunctionForm::PostgreSql);
        assert_eq!(TableFunctionForm::default(), TableFunctionForm::PostgreSql);
    }

    /// A form that renders carries no refusal; an `Unsupported` one carries the
    /// dialect's own sentence and nothing else does.
    #[test]
    fn only_the_unsupported_form_carries_refusal_wording() {
        assert_eq!(TableFunctionForm::PostgreSql.refusal(), None);
        assert_eq!(TableFunctionForm::GoogleSql.refusal(), None);
        assert_eq!(
            TableFunctionForm::Unsupported("my engine has none").refusal(),
            Some("my engine has none")
        );
    }
}