feat(native): parse function headers and resolve function namespaces natively behind the preview engine

Author: kvlonge

crates/sqlbuild-attachments/src/functions/_helpers/mod.rs

@@ -0,0 +1,2 @@
+pub(crate) mod namespace;
+pub(crate) mod values;

crates/sqlbuild-attachments/src/functions/_helpers/namespace.rs

@@ -0,0 +1,30 @@
+//! One of database or schema of a function namespace.
+
+pub(crate) type Part = (
+    Option<String>,
+    Option<String>,
+    Option<String>,
+    Option<String>,
+);
+
+/// `(physical, logical, fingerprint, fingerprint logical)` for one of database or schema.
+pub(crate) fn part(
+    header: Option<&String>,
+    default: Option<&String>,
+    target: Option<&String>,
+    inherit: bool,
+) -> Part {
+    let logical: Option<String> = match header {
+        Some(value) => Some(value.clone()),
+        None if inherit => default.cloned(),
+        None => None,
+    };
+    let physical: Option<String> = match target {
+        None => logical.clone(),
+        Some(value) if header.is_some() || inherit => Some(value.clone()),
+        Some(_) => None,
+    };
+    let fingerprint_logical: Option<String> = header.or(default).cloned();
+    let fingerprint: Option<String> = target.cloned().or_else(|| fingerprint_logical.clone());
+    (physical, logical, fingerprint, fingerprint_logical)
+}

crates/sqlbuild-attachments/src/functions/_helpers/values.rs

@@ -0,0 +1,69 @@
+//! Python's header value checks: non-empty stripped strings, maps and string lists.
+
+use sqlbuild_core::text::main::python_strip::python_strip;
+
+use crate::functions::models::{HeaderValue, NamedType};
+
+/// Python's `TABLE_FUNCTION_RETURN_KEYS`.
+pub(crate) const TABLE_RETURN_KEY: &str = "table";
+
+/// `value.strip()` when `value` is a string that is not blank.
+pub(crate) fn stripped_text(value: Option<&HeaderValue>) -> Option<String> {
+    match value? {
+        HeaderValue::Text(text) if !python_strip(text).is_empty() => {
+            Some(python_strip(text).to_owned())
+        }
+        _ => None,
+    }
+}
+
+/// Named types of a map of non-blank strings; None where Python raises.
+pub(crate) fn named_types(entries: &[(HeaderValue, HeaderValue)]) -> Option<Vec<NamedType>> {
+    let mut named: Vec<NamedType> = Vec::with_capacity(entries.len());
+    for (key, value) in entries {
+        let HeaderValue::Text(raw_name) = key else {
+            return None;
+        };
+        named.push(NamedType {
+            raw_name: raw_name.clone(),
+            name: stripped_text(Some(key))?,
+            type_text: stripped_text(Some(value))?,
+        });
+    }
+    Some(named)
+}
+
+/// Stripped entries of an optional list or tuple of non-blank strings.
+pub(crate) fn stripped_list(value: Option<&HeaderValue>) -> Option<Vec<String>> {
+    match value {
+        None => Some(Vec::new()),
+        Some(HeaderValue::Sequence(items)) => {
+            let mut entries: Vec<String> = Vec::with_capacity(items.len());
+            for item in items {
+                entries.push(stripped_text(Some(item))?);
+            }
+            Some(entries)
+        }
+        Some(_) => None,
+    }
+}
+
+/// An optional string description, stripped.
+pub(crate) fn description(value: Option<&HeaderValue>) -> Option<Option<String>> {
+    match value {
+        None => Some(None),
+        Some(HeaderValue::Text(text)) => Some(Some(python_strip(text).to_owned())),
+        Some(_) => None,
+    }
+}
+
+/// The header value under `key`.
+pub(crate) fn lookup<'header>(
+    header: &'header [(String, HeaderValue)],
+    key: &str,
+) -> Option<&'header HeaderValue> {
+    header
+        .iter()
+        .find(|(name, _)| name == key)
+        .map(|(_, value)| value)
+}

crates/sqlbuild-attachments/src/functions/main/mod.rs

@@ -0,0 +1,2 @@
+pub mod parse_function_header;
+pub mod resolve_function_namespace;

crates/sqlbuild-attachments/src/functions/main/parse_function_header.rs

@@ -0,0 +1,61 @@
+//! Python's SQL and Python function header parsing, before template expansion.
+
+use crate::functions::_helpers::values::{
+    TABLE_RETURN_KEY, description, lookup, named_types, stripped_list, stripped_text,
+};
+use crate::functions::models::{
+    FunctionHeader, FunctionLanguage, FunctionReturns, HeaderValue, NamedType,
+};
+
+/// The parsed header, or None wherever Python raises for its shape.
+#[must_use]
+pub fn parse_function_header(
+    header: &[(String, HeaderValue)],
+    language: FunctionLanguage,
+) -> Option<FunctionHeader> {
+    let returns: FunctionReturns = match (language, lookup(header, "returns")?) {
+        (_, HeaderValue::Text(_)) => {
+            FunctionReturns::Type(stripped_text(lookup(header, "returns"))?)
+        }
+        (FunctionLanguage::Sql, HeaderValue::Map(entries)) => table_returns(entries)?,
+        _ => return None,
+    };
+    let arguments: Vec<NamedType> = match lookup(header, "arguments") {
+        None => Vec::new(),
+        Some(HeaderValue::Map(entries)) => named_types(entries)?,
+        Some(_) => return None,
+    };
+    let python: bool = language == FunctionLanguage::Python;
+    Some(FunctionHeader {
+        arguments,
+        returns,
+        runtime_version: if python {
+            Some(stripped_text(lookup(header, "runtime_version"))?)
+        } else {
+            None
+        },
+        entry_point: if python {
+            Some(stripped_text(lookup(header, "entry_point"))?)
+        } else {
+            None
+        },
+        packages: if python {
+            stripped_list(lookup(header, "packages"))?
+        } else {
+            Vec::new()
+        },
+        tags: stripped_list(lookup(header, "tags"))?,
+        description: description(lookup(header, "description"))?,
+    })
+}
+
+/// Python's `returns (table (...))`: exactly the `table` key with a non-empty column map.
+fn table_returns(entries: &[(HeaderValue, HeaderValue)]) -> Option<FunctionReturns> {
+    let [(HeaderValue::Text(key), HeaderValue::Map(columns))] = entries else {
+        return None;
+    };
+    if key != TABLE_RETURN_KEY || columns.is_empty() {
+        return None;
+    }
+    Some(FunctionReturns::Table(named_types(columns)?))
+}

crates/sqlbuild-attachments/src/functions/main/resolve_function_namespace.rs

@@ -0,0 +1,33 @@
+//! Python's SQL and Python function namespace and fingerprint namespace resolution.
+
+use crate::functions::_helpers::namespace::part;
+use crate::functions::models::{FunctionLanguage, FunctionNamespace, NamespaceInputs};
+
+/// The physical, logical and fingerprint namespace Python's attachment assigns.
+#[must_use]
+pub fn resolve_function_namespace(inputs: &NamespaceInputs) -> FunctionNamespace {
+    let inherit: bool =
+        inputs.language == FunctionLanguage::Sql || inputs.inherit_default_namespace;
+    let (database, logical_database, fingerprint_database, fingerprint_logical_database) = part(
+        inputs.header_database.as_ref(),
+        inputs.default_database.as_ref(),
+        inputs.target_database.as_ref(),
+        inherit,
+    );
+    let (schema, logical_schema, fingerprint_schema, fingerprint_logical_schema) = part(
+        inputs.header_schema.as_ref(),
+        inputs.default_schema.as_ref(),
+        inputs.target_schema.as_ref(),
+        inherit,
+    );
+    FunctionNamespace {
+        database,
+        schema,
+        logical_database,
+        logical_schema,
+        fingerprint_database,
+        fingerprint_schema,
+        fingerprint_logical_database,
+        fingerprint_logical_schema,
+    }
+}

crates/sqlbuild-attachments/src/functions/mod.rs

@@ -0,0 +1,6 @@
+pub(crate) mod _helpers;
+pub mod main;
+pub mod models;
+
+#[cfg(test)]
+mod tests;

crates/sqlbuild-attachments/src/functions/models.rs

@@ -0,0 +1,74 @@
+//! Function header values as Python holds them and what Python's attachment parses from them.
+
+/// One authored header value: text, a mapping, a list or tuple, or anything else.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum HeaderValue {
+    Text(String),
+    Map(Vec<(HeaderValue, HeaderValue)>),
+    Sequence(Vec<HeaderValue>),
+    Other,
+}
+
+/// Which function file kind's header rules apply.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum FunctionLanguage {
+    Sql,
+    Python,
+}
+
+/// One argument or return column: the authored name, the stripped name and the stripped type.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct NamedType {
+    /// Python's error messages quote the name as authored.
+    pub raw_name: String,
+    pub name: String,
+    pub type_text: String,
+}
+
+/// A scalar return type or table function columns, with types before template expansion.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum FunctionReturns {
+    Type(String),
+    Table(Vec<NamedType>),
+}
+
+/// Stripped header values; argument, return and column types are still unexpanded templates.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct FunctionHeader {
+    pub arguments: Vec<NamedType>,
+    pub returns: FunctionReturns,
+    pub tags: Vec<String>,
+    pub description: Option<String>,
+    /// Python functions only: `runtime_version`, `entry_point` and `packages`.
+    pub runtime_version: Option<String>,
+    pub entry_point: Option<String>,
+    pub packages: Vec<String>,
+}
+
+/// The project and target namespace a function resolves against, already expanded.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct NamespaceInputs {
+    /// The function header's own `database` and `schema`, when they are strings.
+    pub header_database: Option<String>,
+    pub header_schema: Option<String>,
+    pub default_database: Option<String>,
+    pub default_schema: Option<String>,
+    pub target_database: Option<String>,
+    pub target_schema: Option<String>,
+    /// Python functions without their own namespace inherit the project defaults.
+    pub language: FunctionLanguage,
+    pub inherit_default_namespace: bool,
+}
+
+/// Python's resolved physical, logical and fingerprint namespace of one function.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct FunctionNamespace {
+    pub database: Option<String>,
+    pub schema: Option<String>,
+    pub logical_database: Option<String>,
+    pub logical_schema: Option<String>,
+    pub fingerprint_database: Option<String>,
+    pub fingerprint_schema: Option<String>,
+    pub fingerprint_logical_database: Option<String>,
+    pub fingerprint_logical_schema: Option<String>,
+}

crates/sqlbuild-attachments/src/functions/tests.rs

@@ -0,0 +1,8 @@
+#[path = "tests/helpers.rs"]
+mod helpers;
+#[path = "tests/test_parse_function_header.rs"]
+mod parse_function_header;
+#[path = "tests/test_resolve_function_namespace.rs"]
+mod resolve_function_namespace;
+#[path = "tests/test_types.rs"]
+mod test_types;

crates/sqlbuild-attachments/src/functions/tests/helpers.rs

@@ -0,0 +1,47 @@
+use crate::functions::models::{FunctionLanguage, HeaderValue, NamedType, NamespaceInputs};
+
+pub(super) fn text(value: &str) -> HeaderValue {
+    HeaderValue::Text(value.to_owned())
+}
+
+pub(super) fn map(entries: &[(&str, HeaderValue)]) -> HeaderValue {
+    let mut pairs: Vec<(HeaderValue, HeaderValue)> = Vec::new();
+    for (key, value) in entries {
+        pairs.push((text(key), value.clone()));
+    }
+    HeaderValue::Map(pairs)
+}
+
+pub(super) fn header(entries: &[(&str, HeaderValue)]) -> Vec<(String, HeaderValue)> {
+    let mut pairs: Vec<(String, HeaderValue)> = Vec::new();
+    for (key, value) in entries {
+        pairs.push(((*key).to_owned(), value.clone()));
+    }
+    pairs
+}
+
+pub(super) fn owned(value: Option<&str>) -> Option<String> {
+    value.map(str::to_owned)
+}
+
+/// Header `udfs`, defaults `analytics.shared`, target `prod_db` with no target schema.
+pub(super) fn namespace_inputs(language: FunctionLanguage, inherit: bool) -> NamespaceInputs {
+    NamespaceInputs {
+        header_database: None,
+        header_schema: owned(Some("udfs")),
+        default_database: owned(Some("analytics")),
+        default_schema: owned(Some("shared")),
+        target_database: owned(Some("prod_db")),
+        target_schema: None,
+        language,
+        inherit_default_namespace: inherit,
+    }
+}
+
+pub(super) fn named(raw_name: &str, name: &str, type_text: &str) -> NamedType {
+    NamedType {
+        raw_name: raw_name.to_owned(),
+        name: name.to_owned(),
+        type_text: type_text.to_owned(),
+    }
+}