feat(analysis): native route skips unreadable models and spells stubs the engine accepts

A native route checks each model's analysis SQL and inline hook statements
with its dialect's parser. A gap warns P026 and the model is not analysed;
under require_sql_analysis it is an error. UDF and cursor stubs take the
dialect's prefix, and a quoted hook parameter becomes the string literal it
is filled with. On ClickHouse's native route, contract types are compared
without top-level Nullable and LowCardinality, and nullability through the
inferred flag. Every dialect stays on the Polyglot route until its native
module is registered.

Author: kvlonge

crates/sqlbuild-analysis/src/analysis_route/constants.rs

@@ -6,3 +6,7 @@ use crate::analysis_route::types::NativeDialect;
 pub(crate) const NATIVE_DIALECTS: &[(&str, &dyn NativeDialect)] = &[];
 /// The warning, or under `require_sql_analysis` the error, for a model analysis skips.
 pub(crate) const SKIPPED_ANALYSIS_CODE: &str = "P026";
+/// ClickHouse's top-level nullability wrapper, which the native profile spells as a flag.
+pub(crate) const NULLABLE_WRAPPER: &str = "Nullable";
+/// ClickHouse's top-level dictionary-encoding wrapper, which leaves the column's type as it is.
+pub(crate) const LOW_CARDINALITY_WRAPPER: &str = "LowCardinality";

crates/sqlbuild-analysis/src/analysis_route/main/clickhouse_type_match.rs

@@ -0,0 +1,51 @@
+use crate::analysis_route::constants::{LOW_CARDINALITY_WRAPPER, NULLABLE_WRAPPER};
+use crate::analysis_route::models::TypeMatch;
+
+/// A declared and an inferred ClickHouse type compared without top-level wrappers, nullability apart.
+#[must_use]
+pub fn clickhouse_type_match(declared: &str, inferred: &str, inferred_nullable: bool) -> TypeMatch {
+    let (declared_base, declared_nullable) = unwrapped(declared);
+    let (inferred_base, wrapped_nullable) = unwrapped(inferred);
+    TypeMatch {
+        same_type: declared_base == inferred_base,
+        nullable_into_non_null: !declared_nullable && (inferred_nullable || wrapped_nullable),
+    }
+}
+
+/// The type inside its top-level `Nullable` and `LowCardinality` wrappers, and whether it is nullable.
+fn unwrapped(type_sql: &str) -> (&str, bool) {
+    let mut current: &str = type_sql.trim();
+    let mut nullable: bool = false;
+    loop {
+        if let Some(inner) = wrapped(current, NULLABLE_WRAPPER) {
+            nullable = true;
+            current = inner;
+        } else if let Some(inner) = wrapped(current, LOW_CARDINALITY_WRAPPER) {
+            current = inner;
+        } else {
+            return (current, nullable);
+        }
+    }
+}
+
+/// The argument of `wrapper(...)` when the whole of `type_sql` is that one call.
+fn wrapped<'a>(type_sql: &'a str, wrapper: &str) -> Option<&'a str> {
+    let head: &str = type_sql.get(..wrapper.len())?;
+    if !head.eq_ignore_ascii_case(wrapper) {
+        return None;
+    }
+    let inner: &str = type_sql[wrapper.len()..]
+        .trim_start()
+        .strip_prefix('(')?
+        .strip_suffix(')')?;
+    let mut depth: usize = 0;
+    for character in inner.chars() {
+        match character {
+            '(' => depth += 1,
+            ')' if depth == 0 => return None,
+            ')' => depth -= 1,
+            _ => {}
+        }
+    }
+    Some(inner.trim())
+}

crates/sqlbuild-analysis/src/analysis_route/main/mod.rs

@@ -1,3 +1,4 @@
 pub mod analysis_route;
+pub mod clickhouse_type_match;
 pub mod native_gap;
 pub mod skipped_analysis;

crates/sqlbuild-analysis/src/analysis_route/main/native_gap.rs

@@ -1,29 +1,19 @@
-use std::collections::HashMap;
-
 use sqlbuild_sqltext::compiler::main::placeholder_defaults::placeholder_defaults;
 
 use crate::analysis_route::models::{LocatedGap, ParserGap};
 use crate::analysis_route::types::NativeDialect;
 use crate::assembly::project::models::SyntaxCheck;
-use crate::semantic_validation::main::normalize::normalize_analysis_sql;
-use crate::semantic_validation::models::NormalizationInput;
+use crate::compiled_project::main::text_position::text_position;
+use crate::compiled_project::models::TextPosition;
+use crate::semantic_validation::main::normalize_native::normalize_native_sql;
 
-/// The first gap of the native parser in `check`'s SQL, normalised as analysis reads it, with the
-/// model's placeholder values filled; none when the parser reads it whole.
-///
-/// # Errors
-///
-/// The normalisation's message when the SQL cannot be normalised.
+/// The native parser's first gap in `check`'s analysis SQL, with the dialect's stub spelling.
 pub fn native_gap(
     dialect: &dyn NativeDialect,
     check: &SyntaxCheck,
 ) -> Result<Option<LocatedGap>, String> {
-    let normalised: String = normalize_analysis_sql(NormalizationInput {
-        sql: check.sql.clone(),
-        dialect: dialect.name().to_owned(),
-        stubs: HashMap::new(),
-        placeholders: HashMap::new(),
-    })?;
+    let normalised: String =
+        normalize_native_sql(&check.sql, dialect.name(), dialect.stub_prefix())?;
     let analysed: String = placeholder_defaults(&normalised, &check.placeholders);
     Ok(dialect
         .read_whole(&analysed)
@@ -34,10 +24,10 @@ pub fn native_gap(
 /// The gap with the line and column of its offset; an offset past the end is the end.
 fn located(sql: &str, gap: ParserGap) -> LocatedGap {
     let before: &str = sql.get(..gap.offset).unwrap_or(sql);
-    let line_start: usize = before.rfind('\n').map_or(0, |newline| newline + 1);
+    let position: TextPosition = text_position(sql, before.chars().count());
     LocatedGap {
         construct: gap.construct,
-        line: before.matches('\n').count() + 1,
-        column: before[line_start..].chars().count() + 1,
+        line: position.line,
+        column: position.column,
     }
 }

crates/sqlbuild-analysis/src/analysis_route/models.rs

@@ -25,3 +25,11 @@ pub struct LocatedGap {
     pub line: usize,
     pub column: usize,
 }
+
+/// How an inferred column type meets its declared type: the type itself, then its nullability.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct TypeMatch {
+    pub same_type: bool,
+    /// The inferred column may be null, but its declared type does not allow it.
+    pub nullable_into_non_null: bool,
+}

crates/sqlbuild-analysis/src/analysis_route/tests.rs

@@ -1,3 +1,5 @@
+#[path = "tests/test_clickhouse_type_match.rs"]
+mod test_clickhouse_type_match;
 #[path = "tests/test_native_gap.rs"]
 mod test_native_gap;
 #[path = "tests/test_types.rs"]

crates/sqlbuild-analysis/src/analysis_route/tests/test_clickhouse_type_match.rs

@@ -0,0 +1,92 @@
+use crate::analysis_route::main::clickhouse_type_match::clickhouse_type_match;
+use crate::analysis_route::models::TypeMatch;
+use crate::analysis_route::tests::test_types::TypeMatchTestCase;
+
+#[test]
+fn given_clickhouse_column_types_when_matching_then_wrappers_are_stripped_and_nullability_compared_apart()
+ {
+    let test_cases = [
+        TypeMatchTestCase {
+            description: "a nullable String flag matches DESCRIBE's Nullable(String)",
+            declared: "Nullable(String)",
+            inferred: "String",
+            inferred_nullable: true,
+            expected_match: TypeMatch {
+                same_type: true,
+                nullable_into_non_null: false,
+            },
+        },
+        TypeMatchTestCase {
+            description: "a declared LowCardinality(String) is a String",
+            declared: "LowCardinality(String)",
+            inferred: "String",
+            inferred_nullable: false,
+            expected_match: TypeMatch {
+                same_type: true,
+                nullable_into_non_null: false,
+            },
+        },
+        TypeMatchTestCase {
+            description: "LowCardinality around Nullable allows null",
+            declared: "LowCardinality(Nullable(String))",
+            inferred: "Nullable(String)",
+            inferred_nullable: false,
+            expected_match: TypeMatch {
+                same_type: true,
+                nullable_into_non_null: false,
+            },
+        },
+        TypeMatchTestCase {
+            description: "a nullable inference into a plain String declaration is a nullability conflict",
+            declared: "String",
+            inferred: "String",
+            inferred_nullable: true,
+            expected_match: TypeMatch {
+                same_type: true,
+                nullable_into_non_null: true,
+            },
+        },
+        TypeMatchTestCase {
+            description: "a non-null inference into a Nullable declaration is no conflict",
+            declared: "Nullable(Int64)",
+            inferred: "Int64",
+            inferred_nullable: false,
+            expected_match: TypeMatch {
+                same_type: true,
+                nullable_into_non_null: false,
+            },
+        },
+        TypeMatchTestCase {
+            description: "different base types differ whatever their wrappers",
+            declared: "Nullable(Int32)",
+            inferred: "Int64",
+            inferred_nullable: true,
+            expected_match: TypeMatch {
+                same_type: false,
+                nullable_into_non_null: false,
+            },
+        },
+        TypeMatchTestCase {
+            description: "a Nullable nested inside Array is part of the type, not stripped",
+            declared: "Array(Nullable(String))",
+            inferred: "Array(String)",
+            inferred_nullable: false,
+            expected_match: TypeMatch {
+                same_type: false,
+                nullable_into_non_null: false,
+            },
+        },
+    ];
+    for test_case in test_cases {
+        assert_eq!(
+            clickhouse_type_match(
+                test_case.declared,
+                test_case.inferred,
+                test_case.inferred_nullable
+            ),
+            test_case.expected_match,
+            "{}",
+            test_case.description
+        );
+    }
+}