WIP: route each dialect's analysis to Polyglot or a native module

Adds analysis_route: a table of dialects whose SQL a native module
analyses, empty for now so every dialect keeps the Polyglot path; the
NativeDialect trait with read_whole; the native parser's first gap in a
model's SQL, normalised and with its placeholders filled as analysis
reads it; and the P026 message for a model whose analysis is skipped.
Not yet wired into the model loop.

Author: kvlonge

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

@@ -0,0 +1,8 @@
+//! The native dialects and the diagnostic a model the native parser cannot read takes.
+
+use crate::analysis_route::types::NativeDialect;
+
+/// Each dialect, by its adapter's analysis dialect name, whose SQL a native module analyses.
+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";

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

@@ -0,0 +1,12 @@
+use crate::analysis_route::constants::NATIVE_DIALECTS;
+use crate::analysis_route::models::AnalysisRoute;
+
+/// The route of `dialect`, an adapter's analysis dialect name; unlisted dialects stay on Polyglot.
+#[must_use]
+pub fn analysis_route(dialect: Option<&str>) -> AnalysisRoute {
+    dialect
+        .and_then(|name| NATIVE_DIALECTS.iter().find(|(native, _)| *native == name))
+        .map_or(AnalysisRoute::Legacy, |(_, module)| {
+            AnalysisRoute::Native(*module)
+        })
+}

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

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

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

@@ -0,0 +1,43 @@
+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;
+
+/// 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.
+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 analysed: String = placeholder_defaults(&normalised, &check.placeholders);
+    Ok(dialect
+        .read_whole(&analysed)
+        .err()
+        .map(|gap| located(&analysed, 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);
+    LocatedGap {
+        construct: gap.construct,
+        line: before.matches('\n').count() + 1,
+        column: before[line_start..].chars().count() + 1,
+    }
+}

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

@@ -0,0 +1,15 @@
+use crate::analysis_route::constants::SKIPPED_ANALYSIS_CODE;
+use crate::analysis_route::models::LocatedGap;
+
+/// P026's code and message for a model whose SQL the dialect's native parser cannot read.
+#[must_use]
+pub fn skipped_analysis(model: &str, dialect: &str, gap: &LocatedGap) -> (&'static str, String) {
+    (
+        SKIPPED_ANALYSIS_CODE,
+        format!(
+            "SQL analysis skipped for model '{model}': the {dialect} parser cannot read {} at \
+             line {}, column {}",
+            gap.construct, gap.line, gap.column
+        ),
+    )
+}

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

@@ -0,0 +1,9 @@
+//! Which engine analyses a dialect's SQL: the Polyglot path, or a native module over SQLQuack.
+
+pub(crate) mod constants;
+pub mod main;
+pub mod models;
+pub mod types;
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,27 @@
+//! The route a dialect's analysis takes, and what stops a native parser reading SQL whole.
+
+use crate::analysis_route::types::NativeDialect;
+
+/// The engine that analyses a dialect's SQL.
+#[derive(Clone, Copy)]
+pub enum AnalysisRoute {
+    /// Polyglot, as before the dialect's native module.
+    Legacy,
+    /// The dialect's native module; a model it cannot read whole is not analysed.
+    Native(&'static dyn NativeDialect),
+}
+
+/// The first construct a native parser cannot read, and its byte offset in the SQL it read.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ParserGap {
+    pub construct: String,
+    pub offset: usize,
+}
+
+/// A gap with the line and column, from 1, of its offset in the analysed SQL.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct LocatedGap {
+    pub construct: String,
+    pub line: usize,
+    pub column: usize,
+}

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

@@ -0,0 +1,4 @@
+#[path = "tests/test_native_gap.rs"]
+mod test_native_gap;
+#[path = "tests/test_types.rs"]
+mod test_types;

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

@@ -0,0 +1,112 @@
+use crate::analysis_route::main::analysis_route::analysis_route;
+use crate::analysis_route::main::native_gap::native_gap;
+use crate::analysis_route::main::skipped_analysis::skipped_analysis;
+use crate::analysis_route::models::{AnalysisRoute, LocatedGap, ParserGap};
+use crate::analysis_route::tests::test_types::NativeGapTestCase;
+use crate::analysis_route::types::NativeDialect;
+use crate::assembly::project::models::SyntaxCheck;
+
+/// A test dialect whose parser refuses the word PIVOT and an unfilled `@@@` placeholder.
+struct PivotlessDialect;
+
+impl NativeDialect for PivotlessDialect {
+    fn name(&self) -> &'static str {
+        "postgres"
+    }
+
+    fn read_whole(&self, sql: &str) -> Result<(), ParserGap> {
+        let refused = ["PIVOT", "@@@"]
+            .iter()
+            .filter_map(|word| sql.find(word).map(|offset| (offset, *word)))
+            .min();
+        match refused {
+            Some((offset, word)) => Err(ParserGap {
+                construct: word.to_owned(),
+                offset,
+            }),
+            None => Ok(()),
+        }
+    }
+}
+
+#[test]
+fn given_any_dialect_when_routing_analysis_then_it_stays_on_the_legacy_path() {
+    for dialect in [
+        Some("postgres"),
+        Some("snowflake"),
+        Some("duckdb"),
+        Some("sqlite"),
+        Some("bigquery"),
+        Some("databricks"),
+        Some("clickhouse"),
+        Some("tsql"),
+        None,
+    ] {
+        assert!(
+            matches!(analysis_route(dialect), AnalysisRoute::Legacy),
+            "{dialect:?}"
+        );
+    }
+}
+
+#[test]
+fn given_model_sql_when_probing_the_native_parser_then_its_gap_is_located_after_placeholders() {
+    let test_cases = [
+        NativeGapTestCase {
+            description: "SQL the parser reads whole has no gap",
+            sql: "SELECT 1 AS a",
+            placeholders: &[],
+            expected_gap: None,
+        },
+        NativeGapTestCase {
+            description: "a placeholder is filled before the parser reads the SQL",
+            sql: "SELECT * FROM t WHERE region = @@@region",
+            placeholders: &[("region", "'eu'")],
+            expected_gap: None,
+        },
+        NativeGapTestCase {
+            description: "the gap's line and column count from 1, in characters",
+            sql: "SELECT 'é' AS a\nFROM t\n  PIVOT (sum(x) FOR y IN (1))",
+            placeholders: &[],
+            expected_gap: Some(LocatedGap {
+                construct: "PIVOT".to_owned(),
+                line: 3,
+                column: 3,
+            }),
+        },
+    ];
+    for test_case in test_cases {
+        let check = SyntaxCheck {
+            sql: test_case.sql.to_owned(),
+            placeholders: test_case
+                .placeholders
+                .iter()
+                .map(|(name, value)| ((*name).to_owned(), (*value).to_owned()))
+                .collect(),
+        };
+        assert_eq!(
+            native_gap(&PivotlessDialect, &check),
+            Ok(test_case.expected_gap),
+            "{}",
+            test_case.description
+        );
+    }
+}
+
+#[test]
+fn given_a_located_gap_when_skipping_analysis_then_p026_names_the_model_and_the_gap() {
+    let gap = LocatedGap {
+        construct: "PIVOT".to_owned(),
+        line: 3,
+        column: 3,
+    };
+    assert_eq!(
+        skipped_analysis("orders_pivot", "postgres", &gap),
+        (
+            "P026",
+            "SQL analysis skipped for model 'orders_pivot': the postgres parser cannot read PIVOT \
+             at line 3, column 3"
+                .to_owned()
+        )
+    );
+}

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

@@ -0,0 +1,8 @@
+use crate::analysis_route::models::LocatedGap;
+
+pub(super) struct NativeGapTestCase {
+    pub(super) description: &'static str,
+    pub(super) sql: &'static str,
+    pub(super) placeholders: &'static [(&'static str, &'static str)],
+    pub(super) expected_gap: Option<LocatedGap>,
+}