razeri-plugin-contract 0.1.0

// Copyright (C) 2026 Gabriel Shea <gshea@ideapivot.com> - All Rights Reserved

//! Boolean capability flags with conservative defaults.
//!
//! [`DialectCapabilities`] tells the rendering layer what syntax features
//! the platform supports. Defaults are conservative (`false` / ANSI-safe),
//! so unknown platforms produce safe SQL.

use crate::merge_shape::MergeShape;

/// Level 6 — Boolean capability flags with conservative defaults.
///
/// These flags tell the rendering layer what syntax features the platform supports.
/// Defaults are `false` / conservative, so unknown platforms produce safe ANSI SQL.
pub trait DialectCapabilities {
    // ═══════════════════════════════════════════════════════════════
    // DML Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// **How this engine performs the upsert Razeri's generated load is.**
    ///
    /// See [`MergeShape`]. The default is a refusal, because the honest answer
    /// for an engine nobody has measured is that Razeri does not know how to
    /// load it — not that it spells its upsert the way `MySQL` does.
    fn merge_shape(&self) -> MergeShape {
        MergeShape::None
    }

    /// Whether the platform supports INSERT ... ON CONFLICT (PostgreSQL-style upsert).
    fn supports_on_conflict(&self) -> bool {
        false
    }

    /// Whether the platform supports INSERT OVERWRITE.
    fn supports_insert_overwrite(&self) -> bool {
        false
    }

    /// Whether the platform supports UPDATE ... FROM.
    fn supports_update_from(&self) -> bool {
        false
    }

    /// Whether the platform supports RETURNING / OUTPUT clauses.
    fn supports_returning(&self) -> bool {
        false
    }

    // ═══════════════════════════════════════════════════════════════
    // Query Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// Whether the platform supports Common Table Expressions (WITH).
    fn supports_cte(&self) -> bool {
        true
    }

    /// Whether the platform supports recursive CTEs.
    fn supports_recursive_cte(&self) -> bool {
        true
    }

    /// Whether the platform supports window functions.
    fn supports_window_functions(&self) -> bool {
        true
    }

    /// Whether the platform supports named windows (WINDOW clause).
    fn supports_named_windows(&self) -> bool {
        true
    }

    /// Whether the platform supports QUALIFY clause.
    fn supports_qualify(&self) -> bool {
        false
    }

    /// Whether the platform supports GROUPS frame type in window functions.
    fn supports_groups_frame(&self) -> bool {
        false
    }

    /// Whether the platform supports NULLS FIRST/LAST in ORDER BY.
    fn supports_nulls_ordering(&self) -> bool {
        true
    }

    // ═══════════════════════════════════════════════════════════════
    // DDL Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// Whether the platform supports IDENTITY columns.
    fn supports_identity(&self) -> bool {
        false
    }

    /// Whether the platform supports sequences (CREATE SEQUENCE).
    fn supports_sequences(&self) -> bool {
        false
    }

    /// Whether the platform supports schema namespacing.
    fn supports_schemas(&self) -> bool {
        true
    }

    /// Whether the platform supports bulk load (COPY, BULK INSERT, etc.).
    fn supports_bulk_load(&self) -> bool {
        false
    }

    /// Whether the platform supports stored procedures.
    fn supports_stored_procedures(&self) -> bool {
        false
    }

    /// Whether the platform **stores functions at all** — a routine the schema
    /// creates and later calls by name, in any spelling.
    ///
    /// Nearly every engine razeri reaches has one: `CREATE FUNCTION` on
    /// `PostgreSQL`, `MySQL`, `MariaDB`, Snowflake, `SQL Server` and Databricks,
    /// a `MACRO` on `DuckDB`, a lambda `CREATE FUNCTION` on `ClickHouse`.
    ///
    /// **`SQLite` answers `false`, and it is the reason this question is asked
    /// out loud.** `SQLite` has no `CREATE FUNCTION` statement in any spelling
    /// and no `CREATE PROCEDURE` either — a function there is registered by the
    /// program that opens the database, so nothing written into a schema script
    /// can create one. Inheriting the `PostgreSQL` form wrote
    /// `CREATE OR REPLACE FUNCTION … LANGUAGE SQL RETURN …` into `schema.sql`,
    /// which `SQLite` answers with `near "CREATE": syntax error` part way
    /// through the script, so the build refuses in front of the script instead.
    ///
    /// The default is `true`, matching [`Self::supports_table_functions`] and
    /// for the same reason: refusing is the destructive answer, so a refusal
    /// fires only where an engine is KNOWN to have no form, never because a
    /// dialect forgot to answer. That reverses the conservative-`false` default
    /// this trait uses for flags that *add* syntax — here `false` is the
    /// unusual claim, and it is made deliberately, one dialect at a time.
    fn supports_stored_functions(&self) -> bool {
        true
    }

    /// Whether the platform has a **table-valued function** — a routine a query
    /// selects FROM, returning columns rather than one value.
    ///
    /// Most engines have one in some spelling: `RETURNS TABLE(…)` on
    /// `PostgreSQL`, Snowflake and Databricks, an inline TVF on SQL Server, a
    /// table `MACRO` on `DuckDB`, a parameterized view on `ClickHouse`.
    ///
    /// **`MySQL` and `MariaDB` answer `false`, and they are the reason this
    /// question exists.** A stored function there returns exactly one value;
    /// there is no clause that returns a relation, in any spelling. Rendering
    /// `RETURNS TABLE` for them produced `ERROR 1064 … syntax error` in the
    /// middle of a schema script (measured on `MySQL` 8.4 and `MariaDB` 11.4),
    /// so the build refuses in front of the script instead.
    ///
    /// The default is `true`: a refusal fires only where an engine is KNOWN to
    /// have no form, never because a dialect forgot to answer.
    fn supports_table_functions(&self) -> bool {
        true
    }

    /// Whether the platform supports tasks / scheduled jobs.
    fn supports_tasks(&self) -> bool {
        false
    }

    /// Whether the platform supports native table partitioning.
    fn supports_partitioning(&self) -> bool {
        true
    }

    /// Whether the platform supports materialized views.
    fn supports_materialized_views(&self) -> bool {
        true
    }

    /// Whether the platform supports generated/computed columns.
    fn supports_generated_columns(&self) -> bool {
        true
    }

    /// Whether the platform supports JSONB or native JSON type.
    fn supports_json(&self) -> bool {
        true
    }

    // ═══════════════════════════════════════════════════════════════
    // Type Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// Whether the platform supports unsigned integers natively.
    fn supports_unsigned_integers(&self) -> bool {
        false
    }

    /// Whether the platform supports arrays natively.
    fn supports_arrays(&self) -> bool {
        false
    }

    /// Whether the platform supports native BOOLEAN type (vs BIT).
    fn supports_boolean(&self) -> bool {
        true
    }

    // ═══════════════════════════════════════════════════════════════
    // Limits & Defaults
    // ═══════════════════════════════════════════════════════════════

    /// The default schema name for this platform.
    fn default_schema(&self) -> &'static str {
        "public"
    }

    /// Maximum identifier length for this platform.
    fn max_identifier_length(&self) -> usize {
        63
    }

    /// Maximum number of columns in a table (approximate).
    fn max_columns(&self) -> usize {
        10000
    }

    /// Maximum query parameters (approximate, 0 = unlimited).
    fn max_parameters(&self) -> usize {
        0
    }

    // ═══════════════════════════════════════════════════════════════
    // Drop Capabilities (Phase 1 debt removal)
    // ═══════════════════════════════════════════════════════════════

    /// Whether DROP supports CASCADE modifier.
    fn supports_cascade_drop(&self) -> bool {
        true
    }

    /// Whether DROP FUNCTION requires parameter types for overloaded functions.
    fn supports_function_overloading(&self) -> bool {
        false
    }

    /// Whether DROP supports SYNC modifier (`ClickHouse`).
    fn supports_sync_drop(&self) -> bool {
        false
    }

    /// Whether DROP supports FORCE modifier (Databricks).
    fn supports_force_drop(&self) -> bool {
        false
    }

    // ═══════════════════════════════════════════════════════════════
    // DML Extended Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// Whether the platform supports compound assignment (e.g., `col += value`).
    fn supports_compound_assignment(&self) -> bool {
        false
    }

    /// Whether the platform supports EXCLUDE clause in window frame specs.
    fn supports_window_frame_exclude(&self) -> bool {
        false
    }

    /// Whether the platform supports MERGE NOT MATCHED BY SOURCE.
    fn supports_merge_not_matched_by_source(&self) -> bool {
        false
    }

    /// Keyword emitted for MERGE NOT MATCHED branch.
    fn merge_not_matched_keyword(&self) -> &'static str {
        "WHEN NOT MATCHED"
    }

    /// Whether the platform supports UPDATE SET * / INSERT * in MERGE.
    fn supports_merge_star_syntax(&self) -> bool {
        false
    }

    /// Whether an UPDATE is spelled `ALTER TABLE … UPDATE` (`ClickHouse`).
    ///
    /// An earlier name said "insert", which is the one thing this
    /// capability has never been about. **There is a second declaration of the
    /// same fact** on [`crate::SqlRenderer::uses_alter_table_update`], which is
    /// the one `razeri_sql::domain::update` and `razeri_materialize` both
    /// consult; `razeri-dialect-clickhouse` overrides both and they agree
    /// today. Two definitions of one capability is the keyed-two-ways defect
    /// one scale down, and collapsing them is future work — recorded here so the
    /// next reader finds the duplication named rather than discovering it from
    /// an ambiguous-method error.
    fn uses_alter_table_update(&self) -> bool {
        false
    }

    /// Whether the platform supports multi-table INSERT (Snowflake).
    fn supports_multi_table_insert(&self) -> bool {
        false
    }

    // ═══════════════════════════════════════════════════════════════
    // DDL / Namespace Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// The SQL keyword for the schema-level namespace.
    ///
    /// Most platforms use `SCHEMA` (`CREATE SCHEMA IF NOT EXISTS ...`).
    /// `ClickHouse` uses `DATABASE` (`CREATE DATABASE IF NOT EXISTS ...`).
    fn schema_namespace_keyword(&self) -> &'static str {
        "SCHEMA"
    }

    // ═══════════════════════════════════════════════════════════════
    // Comment Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// Whether the platform supports `#` as a single-line comment delimiter.
    ///
    /// Default: `false`. Only `ClickHouse` uses hash-style comments.
    fn supports_hash_comments(&self) -> bool {
        false
    }

    // ═══════════════════════════════════════════════════════════════
    // Script Formatting
    // ═══════════════════════════════════════════════════════════════

    /// Batch separator keyword required between DDL statements in a script.
    ///
    /// SQL Server / T-SQL requires `GO` between `CREATE FUNCTION`, `CREATE VIEW`,
    /// and `CREATE PROCEDURE` statements. Other platforms return `None` and use
    /// double-newlines between statements.
    fn batch_separator(&self) -> Option<&'static str> {
        None
    }

    // ═══════════════════════════════════════════════════════════════
    // Transaction Capabilities
    // ═══════════════════════════════════════════════════════════════

    /// Whether several statements in a script can be committed or discarded
    /// together as one unit.
    ///
    /// A generated load is a sequence of writes that only make sense finished.
    /// An SCD-2 load, for instance, closes the standing version into `_history`
    /// and then re-opens `_current` on the new attributes; a process that dies
    /// between the two leaves a closed version that `_current` still holds open,
    /// and because `_history` is keyed on (surrogate, version start), the next
    /// load writes the same key again and the engine refuses it. Every load
    /// after the crash fails until somebody deletes that row by hand.
    ///
    /// Wrapping the load in one transaction is what makes the crash a no-op
    /// instead. This flag says whether the platform offers that at all. It
    /// defaults to `true` because a transaction spanning several statements is
    /// core SQL and nearly every engine has it; a platform that does not
    /// overrides it, and the load script then says plainly that the operator
    /// owns the boundary.
    fn supports_multi_statement_transactions(&self) -> bool {
        true
    }

    /// How this platform opens a transaction.
    ///
    /// The ANSI spelling, which `MySQL` and `MariaDB` also use. `DuckDB`,
    /// `SQLite`, `SQL Server` and `Snowflake` say `BEGIN TRANSACTION`;
    /// `PostgreSQL` and `Citus` say `BEGIN`.
    fn begin_transaction_keyword(&self) -> &'static str {
        "START TRANSACTION"
    }

    /// How this platform commits one.
    ///
    /// `COMMIT` everywhere razeri reaches except `SQL Server`, which spells it
    /// `COMMIT TRANSACTION`.
    fn commit_transaction_keyword(&self) -> &'static str {
        "COMMIT"
    }

    /// Whether emptying a table with `TRUNCATE` ends the open transaction.
    ///
    /// `MySQL` and `MariaDB` treat `TRUNCATE TABLE` as schema change, and a
    /// schema change commits everything before it and cannot be rolled back.
    /// A generated load clears its staging table that way, so on those two
    /// platforms the transaction around the load does not reach back past the
    /// most recent staging clear. Everywhere else `TRUNCATE` is an ordinary
    /// statement inside the transaction.
    fn truncate_commits_implicitly(&self) -> bool {
        false
    }

    // ═══════════════════════════════════════════════════════════════
    // Storage / Partition / Compression Capabilities
    // (Time-Partitioning Plan — Phase 1)
    // ═══════════════════════════════════════════════════════════════

    /// Whether the platform supports a server-side partition function definable
    /// at design time (`T-SQL` `PARTITION FUNCTION`, `PostgreSQL` `PARTITION BY`,
    /// `MySQL` `PARTITION BY`, `ClickHouse` `PARTITION BY`).
    ///
    /// `Snowflake` / `DuckDB` return `false` because micro-partitioning is automatic
    /// and not user-definable.
    fn supports_partition_function(&self) -> bool {
        false
    }

    /// Whether the platform supports adding/removing partition boundaries on a
    /// live table (`T-SQL` `ALTER PARTITION FUNCTION SPLIT/MERGE RANGE`,
    /// `PostgreSQL` `ATTACH/DETACH PARTITION`, `MySQL` `REORGANIZE PARTITION`).
    fn supports_partition_split_merge(&self) -> bool {
        false
    }

    /// Whether the platform supports a columnstore index (`T-SQL` clustered/non-clustered
    /// columnstore; `ClickHouse` via `MergeTree` engine; not natively in `PostgreSQL` / `MySQL`).
    fn supports_columnstore_index(&self) -> bool {
        false
    }

    /// Whether the platform realizes a columnstore as a **table storage engine**
    /// rather than an index (`MariaDB` `ENGINE=ColumnStore`). This is deliberately
    /// distinct from [`Self::supports_columnstore_index`]: a design that asks for
    /// `index: { kind: clustered_columnstore }` is honoured on such a platform by
    /// selecting the engine, but it must NOT inherit the `T-SQL`
    /// index machinery — the composite-PK demotion to `UNIQUE NONCLUSTERED` keys
    /// off `supports_columnstore_index`, and an engine-columnstore keeps its
    /// ordinary primary key. So the two capabilities are separate axes: "supports
    /// columnstore at all" is the disjunction of them.
    fn columnstore_is_table_engine(&self) -> bool {
        false
    }

    /// Whether the platform has a clustering-key concept distinct from primary key
    /// (`Snowflake` `CLUSTER BY`, Delta Liquid Clustering / `Z-ORDER`, `ClickHouse` `ORDER BY`).
    fn supports_clustering_key(&self) -> bool {
        false
    }

    /// Whether the platform supports user-controllable table compression
    /// (`T-SQL` `DATA_COMPRESSION = PAGE/ROW/COLUMNSTORE`, `MySQL` `ROW_FORMAT=COMPRESSED`,
    /// `ClickHouse` `CODEC(ZSTD)`, Delta `delta.compressionCodec`).
    fn supports_table_compression(&self) -> bool {
        false
    }

    /// Whether the platform requires every column referenced by the partition
    /// key to also appear in the table's PRIMARY KEY (or any UNIQUE
    /// constraint).
    ///
    /// `PostgreSQL` enforces this with `SQLSTATE 0A000` ("unique constraint on
    /// partitioned table must include all partitioning columns"). `T-SQL`,
    /// `MySQL`, `ClickHouse`, `Snowflake`, and `DuckDB` do not impose this
    /// restriction.
    fn partition_requires_pk_includes_field(&self) -> bool {
        false
    }
}

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

    struct DefaultDialect;
    impl DialectCapabilities for DefaultDialect {}

    /// Assert default DML capability flags are conservative.
    /// Parameters:
    /// - d: Dialect capabilities implementation under test.
    fn assert_default_dml_capabilities(d: &impl DialectCapabilities) {
        assert_eq!(d.merge_shape(), MergeShape::None);
        assert!(!d.supports_on_conflict());
        assert!(!d.supports_insert_overwrite());
        assert!(!d.supports_update_from());
        assert!(!d.supports_returning());
    }

    /// Assert default query capability flags and ANSI-safe behavior.
    /// Parameters:
    /// - d: Dialect capabilities implementation under test.
    fn assert_default_query_capabilities(d: &impl DialectCapabilities) {
        assert!(d.supports_cte());
        assert!(d.supports_recursive_cte());
        assert!(d.supports_window_functions());
        assert!(d.supports_named_windows());
        assert!(!d.supports_qualify());
        assert!(!d.supports_groups_frame());
        assert!(d.supports_nulls_ordering());
    }

    /// Assert default DDL capability and type flags are conservative.
    /// Parameters:
    /// - d: Dialect capabilities implementation under test.
    fn assert_default_ddl_and_type_capabilities(d: &impl DialectCapabilities) {
        assert!(!d.supports_identity());
        assert!(!d.supports_sequences());
        assert!(d.supports_schemas());
        assert!(!d.supports_bulk_load());
        assert!(!d.supports_stored_procedures());
        // The two routine-form questions default the other way on purpose:
        // answering `false` REFUSES a build, so it is never the answer an
        // unknown platform falls into.
        assert!(d.supports_stored_functions());
        assert!(d.supports_table_functions());
        assert!(!d.supports_tasks());
        assert!(d.supports_partitioning());
        assert!(d.supports_materialized_views());
        assert!(d.supports_generated_columns());
        assert!(d.supports_json());
        assert!(!d.supports_unsigned_integers());
        assert!(!d.supports_arrays());
        assert!(d.supports_boolean());
    }

    /// Assert default platform limits and storage capability flags.
    /// Parameters:
    /// - d: Dialect capabilities implementation under test.
    fn assert_default_limits_and_storage_capabilities(d: &impl DialectCapabilities) {
        assert_eq!(d.default_schema(), "public");
        assert_eq!(d.max_identifier_length(), 63);
        assert_eq!(d.max_columns(), 10000);
        assert_eq!(d.max_parameters(), 0);
        assert!(!d.supports_partition_function());
        assert!(!d.supports_partition_split_merge());
        assert!(!d.supports_columnstore_index());
        assert!(!d.supports_clustering_key());
        assert!(!d.supports_table_compression());
    }

    #[test]
    fn defaults_are_conservative() {
        let d = DefaultDialect;
        assert_default_dml_capabilities(&d);
        assert_default_query_capabilities(&d);
        assert_default_ddl_and_type_capabilities(&d);
        assert_default_limits_and_storage_capabilities(&d);
    }

    #[test]
    fn overrides_work() {
        struct PostgresLike;
        impl DialectCapabilities for PostgresLike {
            fn merge_shape(&self) -> MergeShape {
                MergeShape::Merge(MergeRestrictions::none())
            }
            fn supports_on_conflict(&self) -> bool {
                true
            }
            fn supports_returning(&self) -> bool {
                true
            }
            fn supports_identity(&self) -> bool {
                true
            }
            fn supports_sequences(&self) -> bool {
                true
            }
            fn supports_arrays(&self) -> bool {
                true
            }
            fn max_columns(&self) -> usize {
                1600
            }
        }

        let d = PostgresLike;
        assert!(d.merge_shape().merges());
        assert!(d.supports_on_conflict());
        assert!(d.supports_returning());
        assert!(d.supports_identity());
        assert!(d.supports_sequences());
        assert!(d.supports_arrays());
        assert_eq!(d.max_columns(), 1600);
        // Untouched defaults
        assert!(!d.supports_insert_overwrite());
        assert!(d.supports_cte());
    }

    #[test]
    fn new_capability_defaults_are_conservative() {
        let d = DefaultDialect;
        // Drop capabilities
        assert!(d.supports_cascade_drop()); // true = ANSI default
        assert!(!d.supports_function_overloading());
        assert!(!d.supports_sync_drop());
        assert!(!d.supports_force_drop());
        // DML extended
        assert!(!d.supports_compound_assignment());
        assert!(!d.supports_window_frame_exclude());
        assert!(!d.supports_merge_not_matched_by_source());
        assert_eq!(d.merge_not_matched_keyword(), "WHEN NOT MATCHED");
        assert!(!d.supports_merge_star_syntax());
        assert!(!d.uses_alter_table_update());
        assert!(!d.supports_multi_table_insert());
        // DDL / Namespace
        assert_eq!(d.schema_namespace_keyword(), "SCHEMA");
    }

    /// The default transaction answer is the ANSI one: a load can be wrapped,
    /// in the standard spelling, and clearing a staging table stays inside the
    /// wrap. Every platform that differs says so on its own dialect.
    #[test]
    fn the_default_load_wrap_is_the_ansi_one() {
        let d = DefaultDialect;
        assert!(d.supports_multi_statement_transactions());
        assert_eq!(d.begin_transaction_keyword(), "START TRANSACTION");
        assert_eq!(d.commit_transaction_keyword(), "COMMIT");
        assert!(!d.truncate_commits_implicitly());
    }
}