linter: add require-enum-value-ordering rule

crates/squawk_linter/src/lib.rs

@@ -53,6 +53,7 @@ use rules::renaming_column;
 use rules::renaming_table;
 use rules::require_concurrent_index_creation;
 use rules::require_concurrent_index_deletion;
+use rules::require_enum_value_ordering;
 use rules::require_timeout_settings;
 use rules::transaction_nesting;
 // xtask:new-rule:rule-import
@@ -90,6 +91,7 @@ pub enum Rule {
     BanTruncateCascade,
     RequireTimeoutSettings,
     BanUncommittedTransaction,
+    RequireEnumValueOrdering,
     // xtask:new-rule:error-name
 }
 
@@ -132,6 +134,7 @@ impl TryFrom<&str> for Rule {
             "ban-truncate-cascade" => Ok(Rule::BanTruncateCascade),
             "require-timeout-settings" => Ok(Rule::RequireTimeoutSettings),
             "ban-uncommitted-transaction" => Ok(Rule::BanUncommittedTransaction),
+            "require-enum-value-ordering" => Ok(Rule::RequireEnumValueOrdering),
             // xtask:new-rule:str-name
             _ => Err(format!("Unknown violation name: {s}")),
         }
@@ -194,6 +197,7 @@ impl fmt::Display for Rule {
             Rule::BanTruncateCascade => "ban-truncate-cascade",
             Rule::RequireTimeoutSettings => "require-timeout-settings",
             Rule::BanUncommittedTransaction => "ban-uncommitted-transaction",
+            Rule::RequireEnumValueOrdering => "require-enum-value-ordering",
             // xtask:new-rule:variant-to-name
         };
         write!(f, "{val}")
@@ -421,6 +425,9 @@ impl Linter {
         if self.rules.contains(&Rule::BanUncommittedTransaction) {
             ban_uncommitted_transaction(self, file);
         }
+        if self.rules.contains(&Rule::RequireEnumValueOrdering) {
+            require_enum_value_ordering(self, file);
+        }
         // xtask:new-rule:rule-call
 
         // locate any ignores in the file

crates/squawk_linter/src/rules/mod.rs

@@ -26,6 +26,7 @@ pub(crate) mod renaming_column;
 pub(crate) mod renaming_table;
 pub(crate) mod require_concurrent_index_creation;
 pub(crate) mod require_concurrent_index_deletion;
+pub(crate) mod require_enum_value_ordering;
 pub(crate) mod require_timeout_settings;
 pub(crate) mod transaction_nesting;
 // xtask:new-rule:mod-decl
@@ -58,6 +59,7 @@ pub(crate) use renaming_column::renaming_column;
 pub(crate) use renaming_table::renaming_table;
 pub(crate) use require_concurrent_index_creation::require_concurrent_index_creation;
 pub(crate) use require_concurrent_index_deletion::require_concurrent_index_deletion;
+pub(crate) use require_enum_value_ordering::require_enum_value_ordering;
 pub(crate) use require_timeout_settings::require_timeout_settings;
 pub(crate) use transaction_nesting::transaction_nesting;
 // xtask:new-rule:export

crates/squawk_linter/src/rules/require_enum_value_ordering.rs

@@ -0,0 +1,105 @@
+use squawk_syntax::{
+    Parse, SourceFile, SyntaxKind,
+    ast::{self, AstNode},
+};
+
+use crate::{Linter, Rule, Violation};
+
+pub(crate) fn require_enum_value_ordering(ctx: &mut Linter, parse: &Parse<SourceFile>) {
+    let file = parse.tree();
+    for stmt in file.stmts() {
+        if let ast::Stmt::AlterType(alter_type) = stmt {
+            let syntax = alter_type.syntax();
+
+            let mut has_add = false;
+            let mut has_value = false;
+            let mut has_before_or_after = false;
+
+            for child in syntax.children_with_tokens() {
+                match child.kind() {
+                    SyntaxKind::ADD_KW => has_add = true,
+                    SyntaxKind::VALUE_KW if has_add => has_value = true,
+                    SyntaxKind::BEFORE_KW | SyntaxKind::AFTER_KW if has_value => {
+                        has_before_or_after = true;
+                    }
+                    _ => {}
+                }
+            }
+
+            if has_add && has_value && !has_before_or_after {
+                ctx.report(
+                    Violation::for_node(
+                        Rule::RequireEnumValueOrdering,
+                        "ALTER TYPE ... ADD VALUE without BEFORE or AFTER appends the value to the end of the enum, which may result in unexpected ordering.".into(),
+                        syntax,
+                    )
+                    .help("Add BEFORE or AFTER to specify the position of the new enum value. Example: ALTER TYPE my_enum ADD VALUE 'new_value' BEFORE 'existing_value';"),
+                );
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use insta::assert_snapshot;
+
+    use crate::Rule;
+    use crate::test_utils::{lint_errors, lint_ok};
+
+    #[test]
+    fn err_add_value_without_ordering() {
+        let sql = r#"
+ALTER TYPE my_enum ADD VALUE 'new_value';
+"#;
+        assert_snapshot!(lint_errors(sql, Rule::RequireEnumValueOrdering));
+    }
+
+    #[test]
+    fn err_add_value_if_not_exists_without_ordering() {
+        let sql = r#"
+ALTER TYPE my_enum ADD VALUE IF NOT EXISTS 'new_value';
+"#;
+        assert_snapshot!(lint_errors(sql, Rule::RequireEnumValueOrdering));
+    }
+
+    #[test]
+    fn ok_add_value_before() {
+        let sql = r#"
+ALTER TYPE my_enum ADD VALUE 'new_value' BEFORE 'existing_value';
+"#;
+        lint_ok(sql, Rule::RequireEnumValueOrdering);
+    }
+
+    #[test]
+    fn ok_add_value_after() {
+        let sql = r#"
+ALTER TYPE my_enum ADD VALUE 'new_value' AFTER 'existing_value';
+"#;
+        lint_ok(sql, Rule::RequireEnumValueOrdering);
+    }
+
+    #[test]
+    fn ok_add_value_if_not_exists_before() {
+        let sql = r#"
+ALTER TYPE my_enum ADD VALUE IF NOT EXISTS 'new_value' BEFORE 'existing_value';
+"#;
+        lint_ok(sql, Rule::RequireEnumValueOrdering);
+    }
+
+    #[test]
+    fn ok_rename_value() {
+        let sql = r#"
+ALTER TYPE my_enum RENAME VALUE 'old' TO 'new';
+"#;
+        lint_ok(sql, Rule::RequireEnumValueOrdering);
+    }
+
+    #[test]
+    fn ok_add_attribute() {
+        let sql = r#"
+ALTER TYPE my_type ADD ATTRIBUTE name text;
+"#;
+        lint_ok(sql, Rule::RequireEnumValueOrdering);
+    }
+}

crates/squawk_linter/src/rules/snapshots/squawk_linter__rules__require_enum_value_ordering__test__err_add_value_if_not_exists_without_ordering.snap

@@ -0,0 +1,11 @@
+---
+source: crates/squawk_linter/src/rules/require_enum_value_ordering.rs
+assertion_line: 63
+expression: "lint_errors(sql, Rule::RequireEnumValueOrdering)"
+---
+warning[require-enum-value-ordering]: ALTER TYPE ... ADD VALUE without BEFORE or AFTER appends the value to the end of the enum, which may result in unexpected ordering.
+  ╭▸ 
+2 │ ALTER TYPE my_enum ADD VALUE IF NOT EXISTS 'new_value';
+  │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  │
+  ╰ help: Add BEFORE or AFTER to specify the position of the new enum value. Example: ALTER TYPE my_enum ADD VALUE 'new_value' BEFORE 'existing_value';

crates/squawk_linter/src/rules/snapshots/squawk_linter__rules__require_enum_value_ordering__test__err_add_value_without_ordering.snap

@@ -0,0 +1,11 @@
+---
+source: crates/squawk_linter/src/rules/require_enum_value_ordering.rs
+assertion_line: 55
+expression: "lint_errors(sql, Rule::RequireEnumValueOrdering)"
+---
+warning[require-enum-value-ordering]: ALTER TYPE ... ADD VALUE without BEFORE or AFTER appends the value to the end of the enum, which may result in unexpected ordering.
+  ╭▸ 
+2 │ ALTER TYPE my_enum ADD VALUE 'new_value';
+  │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  │
+  ╰ help: Add BEFORE or AFTER to specify the position of the new enum value. Example: ALTER TYPE my_enum ADD VALUE 'new_value' BEFORE 'existing_value';

docs/docs/require-enum-value-ordering.md

@@ -0,0 +1,28 @@
+
+---
+id: require-enum-value-ordering
+title: require-enum-value-ordering
+---
+
+## problem
+
+Using `ALTER TYPE ... ADD VALUE` without specifying `BEFORE` or `AFTER` appends the new value to the end of the enum type. This can lead to unexpected ordering, especially when enum values have a meaningful order (e.g., status workflows, severity levels).
+
+```sql
+-- bad
+ALTER TYPE status ADD VALUE 'pending_review';
+```
+
+## solution
+
+Explicitly specify where the new value should be inserted using `BEFORE` or `AFTER`.
+
+```sql
+-- good
+ALTER TYPE status ADD VALUE 'pending_review' BEFORE 'approved';
+ALTER TYPE status ADD VALUE 'pending_review' AFTER 'submitted';
+```
+
+## links
+
+- https://www.postgresql.org/docs/current/sql-altertype.html

docs/sidebars.js

@@ -34,6 +34,7 @@ module.exports = {
       "syntax-error",
       "require-timeout-settings",
       "ban-uncommitted-transaction",
+      "require-enum-value-ordering",
       // xtask:new-rule:error-name
     ],
   },

docs/src/pages/index.js

@@ -202,6 +202,11 @@ const rules = [
     tags: ["schema"],
     description: "Ensure all transactions are committed",
   },
+  {
+    name: "require-enum-value-ordering",
+    tags: ["schema"],
+    description: "Require BEFORE or AFTER when adding enum values",
+  },
   // xtask:new-rule:rule-doc-meta
 ]