sqlbuild 0.56.1__tar.gz → 0.57.0__tar.gz

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/Cargo.lock

@@ -572,7 +572,7 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "sqlbuild-kata-native"
-version = "0.56.1"
+version = "0.57.0"
 dependencies = [
  "fensu-policy",
  "globset",

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.56.1
+Version: 0.57.0
 Requires-Dist: duckdb>=1.3.2
+Requires-Dist: filelock>=3.20.3
 Requires-Dist: polyglot-sql>=0.9.2
 Requires-Dist: pydantic-settings>=2,<3
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: rich>=15.0.0
 Requires-Dist: sqruff>=0.40.0
-Requires-Dist: sqlparse>=0.5.4
 Requires-Dist: google-cloud-bigquery>=3.37.0 ; extra == 'bigquery'
 Requires-Dist: dagster>=1.13.0 ; extra == 'dagster'
 Requires-Dist: dagster-webserver>=1.13.0 ; extra == 'dagster'

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/crates/sqlbuild-kata-native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlbuild-kata-native"
-version = "0.56.1"
+version = "0.57.0"
 edition.workspace = true
 license.workspace = true
 publish.workspace = true

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/crates/sqlbuild-kata-native/src/configuration/_helpers/loading.rs

@@ -44,6 +44,7 @@ fn validate_raw(value: &toml::Value) -> Result<(), String> {
         "select",
         "ignore",
         "thresholds",
+        "threshold_overrides",
         "rule_options",
         "rule_exceptions",
         "rule_ignores",
@@ -70,6 +71,10 @@ fn validate_raw(value: &toml::Value) -> Result<(), String> {
         ("rule_exceptions", ["rule", "path", "reason"].as_slice()),
         ("rule_ignores", ["rules", "paths", "reason"].as_slice()),
         ("select_star_allow", ["paths", "reason"].as_slice()),
+        (
+            "threshold_overrides",
+            ["paths", "thresholds", "reason"].as_slice(),
+        ),
     ] {
         let Some(entries) = table.get(key).and_then(toml::Value::as_array) else {
             continue;
@@ -101,6 +106,26 @@ pub(crate) fn validate(config: &KataConfig) -> Result<(), String> {
     {
         return Err(format!("unknown kata thresholds: {name}"));
     }
+    for entry in &config.threshold_overrides {
+        if entry.paths.is_empty() || entry.thresholds.is_empty() || entry.reason.trim().is_empty() {
+            return Err("kata.threshold_overrides requires paths, thresholds, and reason".into());
+        }
+        if let Some(name) = entry
+            .thresholds
+            .keys()
+            .find(|key| !["min_audits_per_model", "min_tests_per_model"].contains(&key.as_str()))
+        {
+            return Err(format!("unknown kata threshold override: {name}"));
+        }
+        for pattern in &entry.paths {
+            if pattern.trim().is_empty() {
+                return Err("kata threshold override paths must be non-empty globs".into());
+            }
+            globset::Glob::new(pattern).map_err(|error| {
+                format!("invalid kata threshold override path {pattern}: {error}")
+            })?;
+        }
+    }
     let grammar = ProductRuleCodeGrammar::new("SQBK", "XSQBK")?;
     for selector in config.select.iter().chain(&config.ignore) {
         if !grammar.rule_selector_is_valid(selector) {

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/crates/sqlbuild-kata-native/src/constants.rs

@@ -9,7 +9,6 @@ pub(crate) const BOOLEAN_TYPE: &str = "BOOLEAN";
 pub(crate) const TIMESTAMP_TYPE: &str = "TIMESTAMP";
 pub(crate) const DATE_TYPE: &str = "DATE";
 pub(crate) const NEGATION_OPERATOR: &str = "-";
-pub(crate) const TRIVIAL_JOIN_VALUE: &str = "1";
 pub(crate) const DECLARATION_DOMAIN_COMPONENTS: usize = 3;
 pub(crate) const SQL_AS_KEYWORD_LENGTH: usize = 2;
 pub(crate) const MEANINGLESS_FINAL_NAME: &str = "finalfinal";

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/crates/sqlbuild-kata-native/src/engine/_helpers/evaluation.rs

@@ -2,7 +2,9 @@ use crate::configuration::main::validate as config;
 use crate::constants::{API_VERSION, TARGET_DIRECTORY};
 use crate::engine::_helpers::cache::Cache;
 use crate::models::{EvaluateRequest, EvaluateResponse, Fault, RuleMetadata};
-use crate::rules::main::{assemble_catalogue, evaluate as rules, fingerprint, select};
+use crate::rules::main::{
+    assemble_catalogue, evaluate as rules, fingerprint, resolve_threshold_overrides, select,
+};
 use crate::rules::models::ModelEvaluationRequest;
 use fensu_policy::lifecycle::constants::ANALYSIS_BATCH_SCHEMA_VERSION;
 use fensu_policy::lifecycle::errors::LifecycleError;
@@ -37,6 +39,8 @@ pub(crate) fn evaluate_json(request_json: &str) -> Result<String, String> {
         .map(|rule| (rule.code.clone(), *rule))
         .collect();
     let custom_faults = evaluate_custom_rules(&request, &selected_by_code)?;
+    let threshold_overrides =
+        resolve_threshold_overrides::resolve_threshold_overrides(&request.config)?;
     if selected.is_empty() {
         validate_exception_paths(&request)?;
         let _ = suppress_faults(&request, &selected, Vec::new())?;
@@ -94,6 +98,7 @@ pub(crate) fn evaluate_json(request_json: &str) -> Result<String, String> {
             selected: &selected_by_code,
             request: &request,
             is_anchor: model_index == 0,
+            threshold_overrides: &threshold_overrides,
         })?;
         if let (Some(store), Some(identity)) = (&cache, &fingerprint) {
             store.put(&model.relative_path, identity, &model_faults)?;

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/crates/sqlbuild-kata-native/src/engine/mod.rs

@@ -1,2 +1,5 @@
 pub(crate) mod _helpers;
 pub(crate) mod main;
+
+#[cfg(test)]
+mod tests;

sqlbuild-0.57.0/crates/sqlbuild-kata-native/src/engine/tests/helpers.rs

@@ -0,0 +1,40 @@
+use serde_json::{Value, json};
+use tempfile::TempDir;
+
+pub(crate) fn request(project_dir: &TempDir, config: &Value) -> String {
+    json!({
+        "version": 1,
+        "project_dir": project_dir.path(),
+        "config": config,
+        "models": [{
+            "name": "market__mart__prices",
+            "relative_path": "models/mart/market__mart__prices.sql",
+            "query_sql": "SELECT * FROM prices",
+            "authored_sql": "SELECT * FROM prices"
+        }]
+    })
+    .to_string()
+}
+
+pub(crate) fn threshold_request(
+    project_dir: &TempDir,
+    config: &Value,
+    query_sql: &str,
+    references: &Value,
+) -> String {
+    json!({
+        "version": 1,
+        "project_dir": project_dir.path(),
+        "config": config,
+        "models": [{
+            "name": "market__mart__prices",
+            "relative_path": "models/mart/market__mart__prices.sql",
+            "query_sql": query_sql,
+            "authored_sql": query_sql,
+            "references": references,
+            "declared_audit_count": 1,
+            "targeting_test_count": 1
+        }]
+    })
+    .to_string()
+}

sqlbuild-0.57.0/crates/sqlbuild-kata-native/src/engine/tests/test_evaluation.rs

@@ -0,0 +1,244 @@
+use serde_json::{Value, json};
+use tempfile::TempDir;
+
+use crate::engine::main::evaluate::evaluate_json;
+use crate::engine::tests::helpers;
+use crate::engine::tests::test_types;
+
+#[test]
+fn given_repeated_native_evaluation_when_faulting_then_returns_deterministic_complete_facts()
+-> Result<(), String> {
+    let test_cases = [test_types::NativeEvaluationTestCase {
+        description: "repeated native evaluation preserves every fault fact",
+        config: json!({
+            "select": ["SQBKS001"],
+            "cache": {"enabled": false, "require_cacheable": false}
+        }),
+        expected_faults: json!([{
+            "code": "SQBKS001",
+            "path": "models/mart/market__mart__prices.sql",
+            "line": 1,
+            "column": 1,
+            "message": "model SQL must keep transformation logic in top-level CTEs",
+            "remediation": "Move transformation logic into named top-level CTEs before the terminal SELECT."
+        }]),
+    }];
+
+    for test_case in &test_cases {
+        let project_dir = TempDir::new().map_err(|error| error.to_string())?;
+        let request_json = helpers::request(&project_dir, &test_case.config);
+        let first: Value = serde_json::from_str(&evaluate_json(&request_json)?)
+            .map_err(|error| error.to_string())?;
+        let second: Value = serde_json::from_str(&evaluate_json(&request_json)?)
+            .map_err(|error| error.to_string())?;
+
+        assert_eq!(
+            first["faults"], second["faults"],
+            "{}",
+            test_case.description
+        );
+        assert_eq!(
+            first["faults"], test_case.expected_faults,
+            "{}",
+            test_case.description
+        );
+    }
+    Ok(())
+}
+
+#[test]
+fn given_scoped_suppression_when_evaluating_native_fault_then_returns_no_faults()
+-> Result<(), String> {
+    let test_cases = [test_types::NativeEvaluationTestCase {
+        description: "native evaluation applies a matching scoped suppression",
+        config: json!({
+            "select": ["SQBKS001"],
+            "cache": {"enabled": false, "require_cacheable": false},
+            "rule_ignores": [{
+                "rules": ["SQBKS"],
+                "paths": ["models/mart/**"],
+                "reason": "Tracked migration"
+            }]
+        }),
+        expected_faults: json!([]),
+    }];
+
+    for test_case in &test_cases {
+        let project_dir = TempDir::new().map_err(|error| error.to_string())?;
+        let request_json = helpers::request(&project_dir, &test_case.config);
+        let result: Value = serde_json::from_str(&evaluate_json(&request_json)?)
+            .map_err(|error| error.to_string())?;
+
+        assert_eq!(
+            result["faults"], test_case.expected_faults,
+            "{}",
+            test_case.description
+        );
+    }
+    Ok(())
+}
+
+#[test]
+fn given_path_threshold_overrides_when_evaluating_then_matches_in_authored_order()
+-> Result<(), String> {
+    let project_dir = TempDir::new().map_err(|error| error.to_string())?;
+    let test_cases = [
+        test_types::ThresholdEvaluationTestCase {
+            description: "matching override raises both minima",
+            config: json!({
+                "select": ["SQBKX001", "SQBKX002"],
+                "thresholds": {"min_audits_per_model": 1, "min_tests_per_model": 1},
+                "threshold_overrides": [{
+                    "paths": ["models/mart/**"],
+                    "thresholds": {"min_audits_per_model": 2, "min_tests_per_model": 2},
+                    "reason": "marts require stronger evidence"
+                }],
+                "cache": {"enabled": false}
+            }),
+            query_sql: "SELECT id + 1 AS id FROM prices",
+            references: json!([]),
+            expected_codes: &["SQBKX001", "SQBKX002"],
+        },
+        test_types::ThresholdEvaluationTestCase {
+            description: "near miss keeps global minima",
+            config: json!({
+                "select": ["SQBKX001", "SQBKX002"],
+                "thresholds": {"min_audits_per_model": 1, "min_tests_per_model": 1},
+                "threshold_overrides": [{
+                    "paths": ["models/staging/**"],
+                    "thresholds": {"min_audits_per_model": 2, "min_tests_per_model": 2},
+                    "reason": "staging requires stronger evidence"
+                }],
+                "cache": {"enabled": false}
+            }),
+            query_sql: "SELECT id + 1 AS id FROM prices",
+            references: json!([]),
+            expected_codes: &[],
+        },
+        test_types::ThresholdEvaluationTestCase {
+            description: "last matching override wins",
+            config: json!({
+                "select": ["SQBKX001", "SQBKX002"],
+                "thresholds": {"min_audits_per_model": 1, "min_tests_per_model": 1},
+                "threshold_overrides": [
+                    {
+                        "paths": ["models/**"],
+                        "thresholds": {"min_audits_per_model": 2, "min_tests_per_model": 2},
+                        "reason": "all models require stronger evidence"
+                    },
+                    {
+                        "paths": ["models/mart/**"],
+                        "thresholds": {"min_audits_per_model": 1, "min_tests_per_model": 1},
+                        "reason": "mart migration temporarily uses global minima"
+                    }
+                ],
+                "cache": {"enabled": false}
+            }),
+            query_sql: "SELECT id + 1 AS id FROM prices",
+            references: json!([]),
+            expected_codes: &[],
+        },
+        test_types::ThresholdEvaluationTestCase {
+            description: "audit and test overrides resolve independently",
+            config: json!({
+                "select": ["SQBKX001", "SQBKX002"],
+                "thresholds": {"min_audits_per_model": 1, "min_tests_per_model": 1},
+                "threshold_overrides": [{
+                    "paths": ["models/mart/**"],
+                    "thresholds": {"min_audits_per_model": 2},
+                    "reason": "marts require an additional audit"
+                }],
+                "cache": {"enabled": false}
+            }),
+            query_sql: "SELECT id + 1 AS id FROM prices",
+            references: json!([]),
+            expected_codes: &["SQBKX001"],
+        },
+        test_types::ThresholdEvaluationTestCase {
+            description: "matching override preserves passthrough exemption",
+            config: json!({
+                "select": ["SQBKX001", "SQBKX002"],
+                "threshold_overrides": [{
+                    "paths": ["models/mart/**"],
+                    "thresholds": {"min_audits_per_model": 10, "min_tests_per_model": 10},
+                    "reason": "marts require strong evidence"
+                }],
+                "cache": {"enabled": false}
+            }),
+            query_sql: "WITH upstream AS (SELECT * FROM __ref(\"market__stg__prices\")) SELECT id FROM upstream",
+            references: json!([{"ref_kind": "ref", "ref_name": "market__stg__prices"}]),
+            expected_codes: &[],
+        },
+    ];
+
+    for test_case in &test_cases {
+        let request_json = helpers::threshold_request(
+            &project_dir,
+            &test_case.config,
+            test_case.query_sql,
+            &test_case.references,
+        );
+        let result: Value = serde_json::from_str(&evaluate_json(&request_json)?)
+            .map_err(|error| error.to_string())?;
+        let codes: Vec<&str> = result["faults"]
+            .as_array()
+            .into_iter()
+            .flatten()
+            .filter_map(|fault| fault["code"].as_str())
+            .collect();
+        assert_eq!(codes, test_case.expected_codes, "{}", test_case.description);
+    }
+    Ok(())
+}
+
+#[test]
+fn given_threshold_override_change_when_evaluating_then_ruleset_fingerprint_changes()
+-> Result<(), String> {
+    let project_dir = TempDir::new().map_err(|error| error.to_string())?;
+    let test_cases = [test_types::ThresholdFingerprintTestCase {
+        description: "path threshold changes the ruleset fingerprint",
+        base_config: json!({
+            "select": ["SQBKX002"],
+            "cache": {"enabled": false}
+        }),
+        overridden_config: json!({
+            "select": ["SQBKX002"],
+            "threshold_overrides": [{
+                "paths": ["models/mart/**"],
+                "thresholds": {"min_tests_per_model": 2},
+                "reason": "marts require two focused tests"
+            }],
+            "cache": {"enabled": false}
+        }),
+        expected_different: true,
+    }];
+
+    for test_case in &test_cases {
+        let references = json!([]);
+        let base_request = helpers::threshold_request(
+            &project_dir,
+            &test_case.base_config,
+            "SELECT id + 1 AS id FROM prices",
+            &references,
+        );
+        let overridden_request = helpers::threshold_request(
+            &project_dir,
+            &test_case.overridden_config,
+            "SELECT id + 1 AS id FROM prices",
+            &references,
+        );
+        let base_result: Value = serde_json::from_str(&evaluate_json(&base_request)?)
+            .map_err(|error| error.to_string())?;
+        let overridden_result: Value = serde_json::from_str(&evaluate_json(&overridden_request)?)
+            .map_err(|error| error.to_string())?;
+        let different =
+            base_result["ruleset_fingerprint"] != overridden_result["ruleset_fingerprint"];
+
+        assert_eq!(
+            different, test_case.expected_different,
+            "{}",
+            test_case.description
+        );
+    }
+    Ok(())
+}

sqlbuild-0.57.0/crates/sqlbuild-kata-native/src/engine/tests/test_types.rs

@@ -0,0 +1,22 @@
+use serde_json::Value;
+
+pub(crate) struct NativeEvaluationTestCase {
+    pub(crate) description: &'static str,
+    pub(crate) config: Value,
+    pub(crate) expected_faults: Value,
+}
+
+pub(crate) struct ThresholdEvaluationTestCase {
+    pub(crate) description: &'static str,
+    pub(crate) config: Value,
+    pub(crate) query_sql: &'static str,
+    pub(crate) references: Value,
+    pub(crate) expected_codes: &'static [&'static str],
+}
+
+pub(crate) struct ThresholdFingerprintTestCase {
+    pub(crate) description: &'static str,
+    pub(crate) base_config: Value,
+    pub(crate) overridden_config: Value,
+    pub(crate) expected_different: bool,
+}

sqlbuild-0.57.0/crates/sqlbuild-kata-native/src/engine/tests.rs

@@ -0,0 +1,6 @@
+#[path = "tests/test_evaluation.rs"]
+mod evaluation;
+#[path = "tests/helpers.rs"]
+mod helpers;
+#[path = "tests/test_types.rs"]
+mod test_types;

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/crates/sqlbuild-kata-native/src/models.rs

@@ -43,12 +43,21 @@ pub(crate) struct SelectStarAllow {
     pub reason: String,
 }
 
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ThresholdOverride {
+    pub paths: Vec<String>,
+    pub thresholds: BTreeMap<String, u32>,
+    pub reason: String,
+}
+
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[serde(default, deny_unknown_fields)]
 pub(crate) struct KataConfig {
     pub select: Vec<String>,
     pub ignore: Vec<String>,
     pub thresholds: BTreeMap<String, u32>,
+    pub threshold_overrides: Vec<ThresholdOverride>,
     pub rule_options: BTreeMap<String, BTreeMap<String, Value>>,
     pub rule_exceptions: Vec<RuleException>,
     pub rule_ignores: Vec<RuleIgnore>,
@@ -69,6 +78,7 @@ impl Default for KataConfig {
             select: vec![],
             ignore: vec![],
             thresholds: BTreeMap::new(),
+            threshold_overrides: vec![],
             rule_options: BTreeMap::new(),
             rule_exceptions: vec![],
             rule_ignores: vec![],
@@ -149,6 +159,12 @@ pub(crate) struct CustomRule {
     #[serde(default)]
     pub source: Option<String>,
     #[serde(default)]
+    pub source_line: u64,
+    #[serde(default)]
+    pub source_column: u64,
+    #[serde(default)]
+    pub owner: String,
+    #[serde(default)]
     pub project_wide: bool,
     #[serde(default)]
     pub check_name: String,
@@ -225,6 +241,22 @@ pub(crate) struct EvaluateResponse {
     pub ruleset_fingerprint: String,
 }
 
+#[derive(Clone, Debug, Serialize)]
+pub(crate) struct RuleGuidance {
+    pub good_example: String,
+    pub anti_tautology: String,
+    pub mutation_check: String,
+}
+
+impl RuleGuidance {
+    pub(crate) fn remediation(&self, introduction: &str) -> String {
+        format!(
+            "{introduction}\n\n{}\n\n{}\n\n{}",
+            self.good_example, self.anti_tautology, self.mutation_check
+        )
+    }
+}
+
 #[derive(Clone, Debug, Serialize)]
 pub(crate) struct RuleMetadata {
     pub code: String,
@@ -232,6 +264,7 @@ pub(crate) struct RuleMetadata {
     pub slug: String,
     pub message: String,
     pub remediation: String,
+    pub guidance: Option<RuleGuidance>,
     pub implementation_fingerprint: String,
     pub enabled_by_default: bool,
     pub project_wide: bool,

{sqlbuild-0.56.1 → sqlbuild-0.57.0}/crates/sqlbuild-kata-native/src/rules/_helpers/catalogue.rs

@@ -1,5 +1,5 @@
 use crate::constants::{API_VERSION, BUILT_IN_RULE_NAMESPACE, CUSTOM_RULE_NAMESPACE};
-use crate::models::{CustomRule, ResolveRulesRequest, RuleMetadata};
+use crate::models::{CustomRule, ResolveRulesRequest, RuleGuidance, RuleMetadata};
 use fensu_policy::policy::errors::PolicyError;
 use fensu_policy::policy::main::resolve_policy::resolve_policy;
 use fensu_policy::policy::models::{PolicySelectors, ProductRuleCodeGrammar};
@@ -20,6 +20,7 @@ macro_rules! rule {
             slug: $slug.into(),
             message: $message.into(),
             remediation: $remediation.into(),
+            guidance: None,
             implementation_fingerprint: env!("CARGO_PKG_VERSION").into(),
             enabled_by_default: true,
             project_wide: matches!($code, "SQBKH101" | "SQBKH201" | "SQBKX201"),
@@ -154,21 +155,21 @@ pub(crate) fn catalogue() -> Vec<RuleMetadata> {
             "joins",
             "no-comma-join",
             "implicit comma joins are not permitted",
-            "Replace the comma join with an explicit JOIN ... ON <key> at this FROM.",
+            "Replace the comma-separated source with JOIN ... ON <key> or JOIN ... USING (<key>) at this FROM.",
         ),
         rule!(
             "SQBKJ101",
             "joins",
             "explicit-join-key",
-            "non-cross joins must declare ON or USING",
-            "Add an explicit JOIN ... ON <key> or JOIN ... USING (<key>) condition.",
+            "non-cross joins must declare a constraining ON or USING relationship",
+            "Replace the missing or unconditional constraint with JOIN ... ON <relationship> or JOIN ... USING (<key>); use CROSS JOIN only when a Cartesian product is intended and suppressed through the common policy.",
         ),
         rule!(
             "SQBKJ002",
             "joins",
             "no-cross-join",
             "cross joins require an explicit project exception",
-            "Replace CROSS JOIN with an explicit keyed join, or add a reasoned exact exception when the Cartesian product is intentional.",
+            "Replace CROSS JOIN with JOIN ... ON <relationship> or JOIN ... USING (<key>); when the Cartesian product is intentional, add a reasoned exact exception or scoped ignore through the common policy.",
         ),
         rule!(
             "SQBKN001",
@@ -226,13 +227,7 @@ pub(crate) fn catalogue() -> Vec<RuleMetadata> {
             "non-passthrough models must declare the configured minimum audits",
             "Attach concrete not_null, unique, or accepted_values audits to this model's contract; audits gate promotion when bad rows appear.",
         ),
-        rule!(
-            "SQBKX002",
-            "tests",
-            "minimum-tests",
-            "non-passthrough models must have the configured minimum unit tests",
-            "Add a failable SQL unit test that targets this model's real logic.",
-        ),
+        minimum_tests_rule(),
         rule!(
             "SQBKX201",
             "tests",
@@ -245,6 +240,31 @@ pub(crate) fn catalogue() -> Vec<RuleMetadata> {
     rules
 }
 
+fn minimum_tests_rule() -> RuleMetadata {
+    let guidance = RuleGuidance {
+        good_example: "For example:\n\nTEST();\n\nWITH\n__ref__upstream_model AS (\n  SELECT 1 AS order_id, 2 AS quantity\n),\n__expected__example_model AS (\n  SELECT 1 AS order_id, 4 AS doubled_quantity\n)\nSELECT 1"
+            .into(),
+        anti_tautology: "Choose input rows and concrete expected values that exercise the model's actual filter, join, aggregation, or mapping. Do not merely assert that inputs survive unchanged or re-derive expected values with the model's own logic."
+            .into(),
+        mutation_check: "Prove the test is failable: temporarily perturb the model logic or expected value, confirm the test fails, then revert the mutation."
+            .into(),
+    };
+    RuleMetadata {
+        code: "SQBKX002".into(),
+        family: "tests".into(),
+        slug: "minimum-tests".into(),
+        message: "non-passthrough models must have the configured minimum unit tests".into(),
+        remediation: guidance.remediation(
+            "Add a SQL unit test that mocks each real import and asserts concrete transformed rows.",
+        ),
+        guidance: Some(guidance),
+        implementation_fingerprint: env!("CARGO_PKG_VERSION").into(),
+        enabled_by_default: true,
+        project_wide: false,
+        custom: false,
+    }
+}
+
 pub(crate) fn with_custom(custom: &[CustomRule]) -> Result<Vec<RuleMetadata>, String> {
     let grammar = grammar()?;
     let mut result = catalogue();
@@ -258,6 +278,7 @@ pub(crate) fn with_custom(custom: &[CustomRule]) -> Result<Vec<RuleMetadata>, St
             slug: item.slug.clone(),
             message: item.message.clone(),
             remediation: item.remediation.clone(),
+            guidance: None,
             implementation_fingerprint: item.implementation_fingerprint.clone(),
             enabled_by_default: item.enabled_by_default,
             project_wide: item.project_wide,