refactor: expose structured metadata through splinter registry

Instead of re-parsing SQL comment metadata in docs codegen, expose
structured metadata directly through the registry API.

Changes:
- Add SplinterRuleMetadata struct (description, remediation, requires_supabase)
- Add get_rule_metadata() function to registry
- Update docs codegen to use structured metadata
- Remove duplicate SQL parsing logic
- Update runtime to use new metadata API
- Deprecate rule_requires_supabase() in favor of get_rule_metadata()

This eliminates redundant parsing and provides a cleaner API.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: psteinroe

crates/pgls_splinter/src/lib.rs

@@ -79,8 +79,12 @@ pub async fn run_splinter(
 
     for rule_name in &collector.enabled_rules {
         // Skip Supabase-specific rules if Supabase roles don't exist
-        if !has_supabase_roles && crate::registry::rule_requires_supabase(rule_name) {
-            continue;
+        if !has_supabase_roles {
+            if let Some(metadata) = crate::registry::get_rule_metadata(rule_name) {
+                if metadata.requires_supabase {
+                    continue;
+                }
+            }
         }
 
         // Get embedded SQL content (compile-time included)

crates/pgls_splinter/src/registry.rs

@@ -2,6 +2,16 @@
 
 #![doc = r" Generated file, do not edit by hand, see `xtask/codegen`"]
 use pgls_analyse::RegistryVisitor;
+#[doc = r" Metadata for a splinter rule"]
+#[derive(Debug, Clone, Copy)]
+pub struct SplinterRuleMetadata {
+    #[doc = r" Description of what the rule detects"]
+    pub description: &'static str,
+    #[doc = r" URL to documentation/remediation guide"]
+    pub remediation: &'static str,
+    #[doc = r" Whether this rule requires Supabase roles (anon, authenticated, service_role)"]
+    pub requires_supabase: bool,
+}
 #[doc = r" Visit all splinter rules using the visitor pattern"]
 #[doc = r" This is called during registry building to collect enabled rules"]
 pub fn visit_registry<V: RegistryVisitor>(registry: &mut V) {
@@ -151,6 +161,120 @@ pub fn get_sql_content(rule_name: &str) -> Option<&'static str> {
         _ => None,
     }
 }
+#[doc = r" Get metadata for a rule (camelCase name)"]
+#[doc = r" Returns None if rule not found"]
+#[doc = r""]
+#[doc = r" This provides structured access to rule metadata without requiring SQL parsing"]
+pub fn get_rule_metadata(rule_name: &str) -> Option<SplinterRuleMetadata> {
+    match rule_name {
+        "authRlsInitplan" => Some(SplinterRuleMetadata {
+            description: "Detects if calls to \\`current_setting()\\` and \\`auth.<function>()\\` in RLS policies are being unnecessarily re-evaluated for each row",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0003_auth_rls_initplan",
+            requires_supabase: true,
+        }),
+        "authUsersExposed" => Some(SplinterRuleMetadata {
+            description: "Detects if auth.users is exposed to anon or authenticated roles via a view or materialized view in schemas exposed to PostgREST, potentially compromising user data security.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0002_auth_users_exposed",
+            requires_supabase: true,
+        }),
+        "duplicateIndex" => Some(SplinterRuleMetadata {
+            description: "Detects cases where two ore more identical indexes exist.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0009_duplicate_index",
+            requires_supabase: false,
+        }),
+        "extensionInPublic" => Some(SplinterRuleMetadata {
+            description: "Detects extensions installed in the \\`public\\` schema.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0014_extension_in_public",
+            requires_supabase: false,
+        }),
+        "extensionVersionsOutdated" => Some(SplinterRuleMetadata {
+            description: "Detects extensions that are not using the default (recommended) version.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0022_extension_versions_outdated",
+            requires_supabase: false,
+        }),
+        "fkeyToAuthUnique" => Some(SplinterRuleMetadata {
+            description: "Detects user defined foreign keys to unique constraints in the auth schema.",
+            remediation: "Drop the foreign key constraint that references the auth schema.",
+            requires_supabase: true,
+        }),
+        "foreignTableInApi" => Some(SplinterRuleMetadata {
+            description: "Detects foreign tables that are accessible over APIs. Foreign tables do not respect row level security policies.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0017_foreign_table_in_api",
+            requires_supabase: true,
+        }),
+        "functionSearchPathMutable" => Some(SplinterRuleMetadata {
+            description: "Detects functions where the search_path parameter is not set.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0011_function_search_path_mutable",
+            requires_supabase: false,
+        }),
+        "insecureQueueExposedInApi" => Some(SplinterRuleMetadata {
+            description: "Detects cases where an insecure Queue is exposed over Data APIs",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0019_insecure_queue_exposed_in_api",
+            requires_supabase: true,
+        }),
+        "materializedViewInApi" => Some(SplinterRuleMetadata {
+            description: "Detects materialized views that are accessible over the Data APIs.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0016_materialized_view_in_api",
+            requires_supabase: true,
+        }),
+        "multiplePermissivePolicies" => Some(SplinterRuleMetadata {
+            description: "Detects if multiple permissive row level security policies are present on a table for the same \\`role\\` and \\`action\\` (e.g. insert). Multiple permissive policies are suboptimal for performance as each policy must be executed for every relevant query.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0006_multiple_permissive_policies",
+            requires_supabase: false,
+        }),
+        "noPrimaryKey" => Some(SplinterRuleMetadata {
+            description: "Detects if a table does not have a primary key. Tables without a primary key can be inefficient to interact with at scale.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0004_no_primary_key",
+            requires_supabase: false,
+        }),
+        "policyExistsRlsDisabled" => Some(SplinterRuleMetadata {
+            description: "Detects cases where row level security (RLS) policies have been created, but RLS has not been enabled for the underlying table.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0007_policy_exists_rls_disabled",
+            requires_supabase: false,
+        }),
+        "rlsDisabledInPublic" => Some(SplinterRuleMetadata {
+            description: "Detects cases where row level security (RLS) has not been enabled on tables in schemas exposed to PostgREST",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0013_rls_disabled_in_public",
+            requires_supabase: true,
+        }),
+        "rlsEnabledNoPolicy" => Some(SplinterRuleMetadata {
+            description: "Detects cases where row level security (RLS) has been enabled on a table but no RLS policies have been created.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0008_rls_enabled_no_policy",
+            requires_supabase: false,
+        }),
+        "rlsReferencesUserMetadata" => Some(SplinterRuleMetadata {
+            description: "Detects when Supabase Auth user_metadata is referenced insecurely in a row level security (RLS) policy.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0015_rls_references_user_metadata",
+            requires_supabase: true,
+        }),
+        "securityDefinerView" => Some(SplinterRuleMetadata {
+            description: "Detects views defined with the SECURITY DEFINER property. These views enforce Postgres permissions and row level security policies (RLS) of the view creator, rather than that of the querying user",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0010_security_definer_view",
+            requires_supabase: true,
+        }),
+        "tableBloat" => Some(SplinterRuleMetadata {
+            description: "Detects if a table has excess bloat and may benefit from maintenance operations like vacuum full or cluster.",
+            remediation: "Consider running vacuum full (WARNING: incurs downtime) and tweaking autovacuum settings to reduce bloat.",
+            requires_supabase: false,
+        }),
+        "unindexedForeignKeys" => Some(SplinterRuleMetadata {
+            description: "Identifies foreign key constraints without a covering index, which can impact database performance.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0001_unindexed_foreign_keys",
+            requires_supabase: false,
+        }),
+        "unsupportedRegTypes" => Some(SplinterRuleMetadata {
+            description: "Identifies columns using unsupported reg* types outside pg_catalog schema, which prevents database upgrades using pg_upgrade.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=unsupported_reg_types",
+            requires_supabase: false,
+        }),
+        "unusedIndex" => Some(SplinterRuleMetadata {
+            description: "Detects if an index has never been used and may be a candidate for removal.",
+            remediation: "https://supabase.com/docs/guides/database/database-linter?lint=0005_unused_index",
+            requires_supabase: false,
+        }),
+        _ => None,
+    }
+}
 #[doc = r" Map rule name from SQL result (snake_case) to diagnostic category"]
 #[doc = r" Returns None if rule not found"]
 #[doc = r""]
@@ -225,6 +349,7 @@ pub fn get_rule_category(rule_name: &str) -> Option<&'static ::pgls_diagnostics:
 }
 #[doc = r" Check if a rule requires Supabase roles (anon, authenticated, service_role)"]
 #[doc = r" Rules that require Supabase should be filtered out if these roles don't exist"]
+#[deprecated(note = "Use get_rule_metadata() instead")]
 pub fn rule_requires_supabase(rule_name: &str) -> bool {
     match rule_name {
         "authRlsInitplan" => true,

docs/codegen/src/splinter_docs.rs

@@ -4,16 +4,6 @@ use std::{fs, io::Write as _, path::Path};
 
 use crate::utils::SplinterRuleMetadata;
 
-/// Extract remediation URL from SQL metadata comments
-fn extract_remediation_from_sql(sql: &str) -> Option<String> {
-    for line in sql.lines() {
-        if let Some(url) = line.strip_prefix("-- meta: remediation = ") {
-            return Some(url.trim().to_string());
-        }
-    }
-    None
-}
-
 /// Strip metadata comments from SQL content
 /// Removes all lines starting with "-- meta:"
 fn strip_metadata_from_sql(sql: &str) -> String {
@@ -80,7 +70,7 @@ fn generate_splinter_rule_doc(
     writeln!(content)?;
 
     // Add Supabase requirement notice
-    if splinter_meta.requires_supabase {
+    if splinter_meta.registry_metadata.requires_supabase {
         writeln!(content, "> [!NOTE]")?;
         writeln!(
             content,
@@ -92,15 +82,14 @@ fn generate_splinter_rule_doc(
     writeln!(content, "## Description")?;
     writeln!(content)?;
 
-    // Use description from SQL metadata
-    writeln!(content, "{}", splinter_meta.description)?;
+    // Use description from registry metadata
+    writeln!(content, "{}", splinter_meta.registry_metadata.description)?;
     writeln!(content)?;
 
-    // Add "Learn More" link with remediation URL
-    if let Some(remediation) = extract_remediation_from_sql(splinter_meta.sql_content) {
-        writeln!(content, "[Learn More]({remediation})")?;
-        writeln!(content)?;
-    }
+    // Add "Learn More" link with remediation URL from registry metadata
+    let remediation = splinter_meta.registry_metadata.remediation;
+    writeln!(content, "[Learn More]({remediation})")?;
+    writeln!(content)?;
 
     // Add SQL query section (with metadata stripped)
     writeln!(content, "## SQL Query")?;

docs/codegen/src/utils.rs

@@ -4,13 +4,12 @@ use pgls_analyse::{
 use regex::Regex;
 use std::collections::BTreeMap;
 
-/// Metadata for a splinter rule with SQL content
+/// Metadata for a splinter rule with SQL content and registry metadata
 #[derive(Clone)]
 pub(crate) struct SplinterRuleMetadata {
     pub(crate) metadata: RuleMetadata,
     pub(crate) sql_content: &'static str,
-    pub(crate) requires_supabase: bool,
-    pub(crate) description: String,
+    pub(crate) registry_metadata: pgls_splinter::registry::SplinterRuleMetadata,
 }
 
 pub(crate) fn replace_section(
@@ -95,32 +94,23 @@ impl RegistryVisitor for SplinterRulesVisitor {
             .entry(<R::Group as RuleGroup>::NAME)
             .or_default();
 
-        // Get SQL content and Supabase requirement from registry
+        // Get SQL content and metadata from registry
         let sql_content = pgls_splinter::registry::get_sql_content(R::METADATA.name)
             .unwrap_or("-- SQL content not found");
-        let requires_supabase = pgls_splinter::registry::rule_requires_supabase(R::METADATA.name);
-
-        // Extract description from SQL content metadata
-        let description = extract_description_from_sql(sql_content);
+        let registry_metadata = pgls_splinter::registry::get_rule_metadata(R::METADATA.name)
+            .unwrap_or(pgls_splinter::registry::SplinterRuleMetadata {
+                description: "Detects potential issues in your database schema.",
+                remediation: "https://supabase.com/docs/guides/database/database-advisors",
+                requires_supabase: false,
+            });
 
         group.insert(
             R::METADATA.name,
             SplinterRuleMetadata {
                 metadata: R::METADATA,
                 sql_content,
-                requires_supabase,
-                description,
+                registry_metadata,
             },
         );
     }
 }
-
-fn extract_description_from_sql(sql: &str) -> String {
-    // Look for "-- meta: description = ..." in SQL content
-    for line in sql.lines() {
-        if let Some(desc_line) = line.strip_prefix("-- meta: description = ") {
-            return desc_line.trim().to_string();
-        }
-    }
-    "Detects potential issues in your database schema.".to_string()
-}

xtask/codegen/src/generate_splinter.rs

@@ -502,11 +502,41 @@ fn generate_registry(rules: &BTreeMap<String, SqlRuleMetadata>) -> Result<()> {
         })
         .collect();
 
+    // Generate match arms for metadata lookup (camelCase → SplinterRuleMetadata)
+    let metadata_arms: Vec<_> = rules
+        .values()
+        .map(|rule| {
+            let camel_name = &rule.name;
+            let description = &rule.description;
+            let remediation = &rule.remediation;
+            let requires_supabase = rule.requires_supabase;
+
+            quote! {
+                #camel_name => Some(SplinterRuleMetadata {
+                    description: #description,
+                    remediation: #remediation,
+                    requires_supabase: #requires_supabase,
+                })
+            }
+        })
+        .collect();
+
     let content = quote! {
         //! Generated file, do not edit by hand, see `xtask/codegen`
 
         use pgls_analyse::RegistryVisitor;
 
+        /// Metadata for a splinter rule
+        #[derive(Debug, Clone, Copy)]
+        pub struct SplinterRuleMetadata {
+            /// Description of what the rule detects
+            pub description: &'static str,
+            /// URL to documentation/remediation guide
+            pub remediation: &'static str,
+            /// Whether this rule requires Supabase roles (anon, authenticated, service_role)
+            pub requires_supabase: bool,
+        }
+
         /// Visit all splinter rules using the visitor pattern
         /// This is called during registry building to collect enabled rules
         pub fn visit_registry<V: RegistryVisitor>(registry: &mut V) {
@@ -535,6 +565,17 @@ fn generate_registry(rules: &BTreeMap<String, SqlRuleMetadata>) -> Result<()> {
             }
         }
 
+        /// Get metadata for a rule (camelCase name)
+        /// Returns None if rule not found
+        ///
+        /// This provides structured access to rule metadata without requiring SQL parsing
+        pub fn get_rule_metadata(rule_name: &str) -> Option<SplinterRuleMetadata> {
+            match rule_name {
+                #( #metadata_arms, )*
+                _ => None,
+            }
+        }
+
         /// Map rule name from SQL result (snake_case) to diagnostic category
         /// Returns None if rule not found
         ///
@@ -548,6 +589,7 @@ fn generate_registry(rules: &BTreeMap<String, SqlRuleMetadata>) -> Result<()> {
 
         /// Check if a rule requires Supabase roles (anon, authenticated, service_role)
         /// Rules that require Supabase should be filtered out if these roles don't exist
+        #[deprecated(note = "Use get_rule_metadata() instead")]
         pub fn rule_requires_supabase(rule_name: &str) -> bool {
             match rule_name {
                 #( #supabase_arms, )*