razeri-plugin-api 0.2.0

// Copyright (C) 2026 Gabriel Shea
// Licensed under either of the Apache License, Version 2.0 or the MIT
// license, at your option.

//! Resolving a platform name to the dialect that renders it.
//!
//! Every service crate (CLI, API, MCP, AI, pipeline) calls
//! [`resolve_dialect_by_name`] instead of matching on names itself.
//!
//! The accepted spellings are not written down here. Each dialect declares its
//! own name and the aliases it answers to (`DialectInfo::aliases`), and this
//! module reads them off whatever dialects are loaded — so a platform that
//! arrives as a plugin, whether linked in or loaded from a shared library at
//! run time, brings its spellings with it and needs no change to Razeri.

use crate::PlatformDialect;
use crate::dialect::PlatformRegistry;
use std::sync::Arc;
use thiserror::Error;

/// Error returned when a platform name cannot be resolved to one dialect.
#[derive(Debug, Error)]
pub enum ResolveError {
    /// No loaded dialect answers to the name.
    #[error(
        "unknown dialect: '{name}'. {suggestions_text}Registered: {registered}",
        suggestions_text = if suggestions.is_empty() {
            String::new()
        } else {
            format!("Did you mean: {}? ", suggestions.join(", "))
        },
        registered = registered.join(", ")
    )]
    UnknownDialect {
        /// The name that was looked up.
        name: String,
        /// Near-miss suggestions (by edit distance).
        suggestions: Vec<String>,
        /// All registered dialect names.
        registered: Vec<String>,
    },

    /// More than one loaded dialect answers to the name, so it names neither.
    ///
    /// Two plugins claiming one spelling is a mistake in how they are named,
    /// not something to guess at: whichever dialect happened to be found first
    /// would silently render the other one's platform.
    #[error(
        "the platform name '{name}' belongs to {claimed_by_text} at once — use one platform's \
         own name, or load only one of them",
        claimed_by_text = claimed_by.join(" and ")
    )]
    AmbiguousName {
        /// The name that was looked up.
        name: String,
        /// The registered dialects that each answer to it, sorted.
        claimed_by: Vec<String>,
    },
}

/// Resolve a platform name to the dialect that renders it.
///
/// Reads the loaded dialects' declared spellings — the canonical name plus each
/// alias — ignoring case and surrounding whitespace.
///
/// # Errors
///
/// [`ResolveError::UnknownDialect`], with near-miss suggestions, if no loaded
/// dialect answers to the name; [`ResolveError::AmbiguousName`] if two do.
///
/// # Examples
///
/// ```no_run
/// use razeri_plugin_api::ResolveError;
/// use razeri_plugin_api::resolve::resolve_dialect_by_name;
///
/// # fn main() -> Result<(), ResolveError> {
/// let dialect = resolve_dialect_by_name("pg")?;
/// println!("{}", dialect.info().name);
///
/// let dialect = resolve_dialect_by_name("SNOWFLAKE")?;
/// # Ok(())
/// # }
/// ```
pub fn resolve_dialect_by_name(name: &str) -> Result<Arc<dyn PlatformDialect>, ResolveError> {
    let registry = PlatformRegistry::with_auto_discovered();
    resolve_dialect_by_name_with_registry(name, &registry)
}

/// Resolve using an explicit registry — the path a host takes when it has built
/// its own, including one holding dialects loaded at run time.
///
/// # Errors
///
/// The same two errors as [`resolve_dialect_by_name`].
pub fn resolve_dialect_by_name_with_registry(
    name: &str,
    registry: &PlatformRegistry,
) -> Result<Arc<dyn PlatformDialect>, ResolveError> {
    let wanted = name.trim();
    let mut claimants: Vec<String> = registry
        .registered_names()
        .into_iter()
        .filter(|key| answers_to(registry, key, wanted))
        .collect();
    claimants.sort();
    claimants.dedup();

    match claimants.as_slice() {
        [] => {
            let all_names = registered_names(registry);
            let suggestions = near_misses(&wanted.to_lowercase(), &all_names);
            Err(ResolveError::UnknownDialect {
                name: name.to_string(),
                suggestions,
                registered: all_names,
            })
        }
        [only] => registry.get_by_name(only).map(Arc::clone).ok_or_else(|| {
            let all_names = registered_names(registry);
            ResolveError::UnknownDialect {
                name: name.to_string(),
                suggestions: Vec::new(),
                registered: all_names,
            }
        }),
        _ => Err(ResolveError::AmbiguousName { name: wanted.to_string(), claimed_by: claimants }),
    }
}

/// Every spelling the loaded dialects answer to, sorted.
///
/// Read off the dialects themselves, so a plugin's own names appear here the
/// moment it is loaded.
#[must_use]
pub fn accepted_names(registry: &PlatformRegistry) -> Vec<String> {
    let mut names: Vec<String> = registry
        .list()
        .iter()
        .flat_map(|info| info.spellings().into_iter().map(str::to_owned))
        .collect();
    // The keys a host registered under resolve too, whatever the dialect calls
    // itself.
    names.extend(registry.registered_names());
    names.sort();
    names.dedup();
    names
}

/// Every spelling the dialects linked into this program answer to, sorted.
#[must_use]
pub fn all_accepted_names() -> Vec<String> {
    accepted_names(&PlatformRegistry::with_auto_discovered())
}

// ── Internal helpers ────────────────────────────────────────────────────

/// Does the dialect registered under `key` answer to `wanted`?
///
/// The registration key counts alongside the dialect's own declared spellings:
/// a host may register a dialect under a name of its choosing, and the name it
/// chose has to resolve.
fn answers_to(registry: &PlatformRegistry, key: &str, wanted: &str) -> bool {
    if key.trim().eq_ignore_ascii_case(wanted) {
        return true;
    }
    registry.get_by_name(key).is_some_and(|dialect| dialect.info().answers_to(wanted))
}

/// Collect all registered dialect names from the registry.
fn registered_names(registry: &PlatformRegistry) -> Vec<String> {
    let mut names: Vec<String> = registry.list().iter().map(|info| info.name.to_string()).collect();
    names.sort();
    names
}

/// Find near-miss suggestions using Levenshtein distance ≤ 3.
fn near_misses(input: &str, candidates: &[String]) -> Vec<String> {
    let mut scored: Vec<(&str, usize)> = candidates
        .iter()
        .filter_map(|c| {
            let dist = levenshtein(input, c);
            if dist <= 3 { Some((c.as_str(), dist)) } else { None }
        })
        .collect();
    scored.sort_by_key(|(_, d)| *d);
    scored.into_iter().map(|(name, _)| name.to_string()).collect()
}

/// Simple Levenshtein distance (no allocation beyond the DP row).
fn levenshtein(a: &str, b: &str) -> usize {
    let a_bytes = a.as_bytes();
    let b_bytes = b.as_bytes();
    let m = a_bytes.len();
    let n = b_bytes.len();

    let mut prev: Vec<usize> = (0..=n).collect();
    let mut curr = vec![0; n + 1];

    for i in 1..=m {
        curr[0] = i;
        for j in 1..=n {
            let cost = usize::from(a_bytes[i - 1] != b_bytes[j - 1]);
            curr[j] = (prev[j] + 1).min(curr[j - 1] + 1).min(prev[j - 1] + cost);
        }
        std::mem::swap(&mut prev, &mut curr);
    }
    prev[n]
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dialect::{DialectInfo, PlatformDialect, PlatformRegistry};
    use razeri_plugin_contract::DataType;
    use razeri_plugin_contract::DialectFamily;
    use razeri_plugin_contract::{
        DdlRenderer, DialectCapabilities, DmlRenderer, ExpressionRenderer, FormulaRenderer,
        ProcedureRenderer, ReplicationRenderer, SqlRenderer, StorageRenderer, TaskRenderer,
    };

    /// Minimal test dialect.
    struct StubDialect {
        info: DialectInfo,
    }

    impl SqlRenderer for StubDialect {
        fn render_data_type(&self, _dt: &DataType) -> String {
            String::new()
        }
        fn quote_identifier(&self, name: &str) -> String {
            format!("\"{name}\"")
        }
        fn qualify_name(&self, _schema: Option<&str>, name: &str) -> String {
            self.quote_identifier(name)
        }
        fn render_current_timestamp(&self) -> String {
            String::new()
        }
    }
    impl ExpressionRenderer for StubDialect {}
    impl DdlRenderer for StubDialect {}
    impl DmlRenderer for StubDialect {}
    impl ProcedureRenderer for StubDialect {}
    impl FormulaRenderer for StubDialect {}
    impl TaskRenderer for StubDialect {}
    impl DialectCapabilities for StubDialect {}
    impl ReplicationRenderer for StubDialect {}
    impl StorageRenderer for StubDialect {}
    impl PlatformDialect for StubDialect {
        fn info(&self) -> DialectInfo {
            self.info.clone()
        }
    }

    /// The shipped-platform shape in miniature: a name, and the other
    /// spellings that name answers to.
    fn test_registry() -> PlatformRegistry {
        let mut reg = PlatformRegistry::new();
        let entries: &[(&str, &str, &[&str], DialectFamily, &str)] = &[
            (
                "postgres",
                "PostgreSQL",
                &["postgresql", "pg"],
                DialectFamily::PostgreSql,
                "PostgreSQL",
            ),
            ("snowflake", "Snowflake", &["sf"], DialectFamily::Snowflake, "Snowflake"),
            (
                "sqlserver",
                "SQL Server",
                &["tsql", "mssql", "sql_server"],
                DialectFamily::TSql,
                "T-SQL",
            ),
            ("databricks", "Databricks", &["dbx", "spark"], DialectFamily::SparkSql, "Spark SQL"),
            ("clickhouse", "ClickHouse", &["ch"], DialectFamily::ClickHouse, "ClickHouse SQL"),
            ("duckdb", "DuckDB", &["duck"], DialectFamily::PostgreSql, "PostgreSQL"),
            ("citus", "Citus", &["citusdb"], DialectFamily::PostgreSql, "PostgreSQL"),
            ("mariadb", "MariaDB", &["mariadb_columnstore"], DialectFamily::MariaDB, "MariaDB"),
            ("mysql", "MySQL", &[], DialectFamily::MariaDB, "MariaDB"),
            ("agnostic", "Agnostic", &[], DialectFamily::Razeri, "ANSI"),
            ("sqlite", "SQLite", &[], DialectFamily::MariaDB, "SQLite"),
        ];
        for &(name, display, aliases, family, fam_str) in entries {
            reg.register(name.to_string(), Arc::new(stub(name, display, aliases, family, fam_str)));
        }
        reg
    }

    fn stub(
        name: &'static str,
        display: &'static str,
        aliases: &'static [&'static str],
        family: DialectFamily,
        fam_str: &'static str,
    ) -> StubDialect {
        StubDialect {
            info: DialectInfo {
                name,
                display_name: display,
                aliases,
                dialect_family: family,
                family: fam_str,
                is_cloud_native: false,
                is_olap: false,
                is_postgres_compatible: false,
            },
        }
    }

    fn resolved(name: &str, registry: &PlatformRegistry) -> String {
        resolve_dialect_by_name_with_registry(name, registry)
            .unwrap_or_else(|e| panic!("'{name}' resolves: {e}"))
            .info()
            .name
            .to_owned()
    }

    /// Every spelling a loaded dialect declares resolves back to that dialect.
    ///
    /// The resolver keeps no list of its own, so this is the whole contract:
    /// what the dialects say is what Razeri accepts.
    #[test]
    fn every_declared_spelling_resolves_to_the_dialect_that_declared_it() {
        let reg = test_registry();
        for info in reg.list() {
            for spelling in info.spellings() {
                assert_eq!(resolved(spelling, &reg), info.name, "spelling '{spelling}'");
            }
        }
    }

    #[test]
    fn the_declared_spellings_are_the_accepted_names_and_nothing_else_is() {
        let reg = test_registry();
        let accepted = accepted_names(&reg);
        for info in reg.list() {
            for spelling in info.spellings() {
                assert!(accepted.contains(&spelling.to_owned()), "'{spelling}' is accepted");
            }
        }
        for name in accepted {
            assert!(
                reg.list().iter().any(|info| info.spellings().contains(&name.as_str())),
                "'{name}' is accepted, so some loaded dialect declares it"
            );
        }
    }

    #[test]
    fn resolution_ignores_case_and_surrounding_whitespace() {
        let reg = test_registry();
        assert_eq!(resolved("SNOWFLAKE", &reg), "snowflake");
        assert_eq!(resolved("  DuckDB  ", &reg), "duckdb");
        assert_eq!(resolved("PG", &reg), "postgres");
    }

    #[test]
    fn a_name_the_host_registered_resolves_even_if_the_dialect_never_declared_it() {
        let mut reg = PlatformRegistry::new();
        reg.register(
            "housename".to_string(),
            Arc::new(stub("mydb", "MyDB", &[], DialectFamily::Custom("mydb"), "MyDB")),
        );
        assert_eq!(resolved("housename", &reg), "mydb");
        assert_eq!(resolved("mydb", &reg), "mydb");
    }

    /// **A platform Razeri has never heard of resolves by the names it brings
    /// with it.** Nothing in this crate mentions `outsidedb` or `odb` — the
    /// dialect declares them and the resolver reads them off the registry, which
    /// is what makes a dialect loaded at run time as usable as a built-in one.
    #[test]
    fn a_dialect_razeri_never_heard_of_resolves_by_its_own_spellings() {
        let mut reg = test_registry();
        reg.register(
            "outsidedb".to_string(),
            Arc::new(stub(
                "outsidedb",
                "Outside DB",
                &["odb", "outside_db"],
                DialectFamily::Custom("outsidedb"),
                "OutsideDB",
            )),
        );
        for spelling in ["outsidedb", "odb", "outside_db", "  ODB "] {
            assert_eq!(resolved(spelling, &reg), "outsidedb", "spelling '{spelling}'");
        }
        // It renders through the same trait objects as any built-in.
        let dialect = resolve_dialect_by_name_with_registry("odb", &reg).expect("resolves");
        assert_eq!(dialect.quote_identifier("orders"), "\"orders\"");
        assert!(accepted_names(&reg).contains(&"odb".to_string()));
    }

    #[test]
    fn resolve_unknown_returns_error_with_suggestions() {
        let reg = test_registry();
        let result = resolve_dialect_by_name_with_registry("postres", &reg);
        let Err(err) = result else { panic!("expected error") };
        let msg = err.to_string();
        assert!(msg.contains("unknown dialect"), "error should mention unknown dialect: {msg}");
        assert!(msg.contains("postgres"), "error should suggest postgres: {msg}");
    }

    #[test]
    fn resolve_completely_unknown_returns_registered_list() {
        let reg = test_registry();
        let result = resolve_dialect_by_name_with_registry("zzzznotadb", &reg);
        let Err(err) = result else { panic!("expected error") };
        let msg = err.to_string();
        assert!(msg.contains("Registered:"), "error should list registered: {msg}");
    }

    /// **A spelling two platforms claim names neither, and saying so is the
    /// point.** Handing back whichever was found first would render one
    /// platform's SQL under the other's name.
    #[test]
    fn a_spelling_two_dialects_claim_is_refused_and_both_are_named() {
        let mut reg = test_registry();
        reg.register(
            "sparkler".to_string(),
            Arc::new(stub(
                "sparkler",
                "Sparkler",
                &["spark"],
                DialectFamily::Custom("sparkler"),
                "Sparkler",
            )),
        );
        let Err(err) = resolve_dialect_by_name_with_registry("spark", &reg) else {
            panic!("a spelling two dialects claim must not resolve")
        };
        let msg = err.to_string();
        assert!(msg.contains("databricks"), "names the first claimant: {msg}");
        assert!(msg.contains("sparkler"), "names the second claimant: {msg}");
        assert!(msg.contains("use one platform's own name"), "says what to do: {msg}");
        // The unshared spellings still resolve — one shared alias does not take
        // either platform down with it.
        assert_eq!(resolved("databricks", &reg), "databricks");
        assert_eq!(resolved("dbx", &reg), "databricks");
        assert_eq!(resolved("sparkler", &reg), "sparkler");
    }

    #[test]
    fn a_dialect_claiming_another_dialects_own_name_is_refused_too() {
        let mut reg = test_registry();
        reg.register(
            "impostor".to_string(),
            Arc::new(stub(
                "impostor",
                "Impostor",
                &["duckdb"],
                DialectFamily::Custom("impostor"),
                "Impostor",
            )),
        );
        let Err(err) = resolve_dialect_by_name_with_registry("duckdb", &reg) else {
            panic!("a claimed name must not resolve to whichever came first")
        };
        assert!(err.to_string().contains("impostor"), "{err}");
    }

    #[test]
    fn levenshtein_distance_basic() {
        assert_eq!(levenshtein("postgres", "postgres"), 0);
        assert_eq!(levenshtein("postgre", "postgres"), 1);
        assert_eq!(levenshtein("postgrse", "postgres"), 2);
        assert_eq!(levenshtein("", "abc"), 3);
    }
}