sqlbuild 0.59.0__tar.gz → 0.60.0__tar.gz

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/Cargo.lock

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

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.59.0
+Version: 0.60.0
 Requires-Dist: duckdb>=1.3.2
 Requires-Dist: filelock>=3.20.3
 Requires-Dist: polyglot-sql>=0.9.2

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/crates/sqlbuild-kata-native/Cargo.toml

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

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/crates/sqlbuild-kata-native/src/constants.rs

@@ -1,4 +1,5 @@
 pub(crate) const API_VERSION: u32 = 1;
+pub(crate) const SCOPE_METADATA_SCHEMA_VERSION: u32 = 1;
 pub(crate) const BUILT_IN_RULE_NAMESPACE: &str = "SQBK";
 pub(crate) const CUSTOM_RULE_NAMESPACE: &str = "XSQBK";
 pub(crate) const TARGET_DIRECTORY: &str = "target";

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

@@ -0,0 +1,136 @@
+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()
+}
+
+pub(crate) fn scope_index() -> Value {
+    json!({
+        "schema_version": 1,
+        "ownership_roots": [{"path": "models", "resource_kind": "model"}],
+        "resources": [{
+            "identity": "model:orders",
+            "kind": "model",
+            "name": "orders",
+            "path": "models/orders.sql",
+            "ownership_root": "models",
+            "ownership_root_kind": "model"
+        }],
+        "declarations": [{
+            "identity": "enum:status",
+            "kind": "enum",
+            "name": "status",
+            "owner": null,
+            "path": "enums/status.sql",
+            "line": 1,
+            "column": 1,
+            "scope": "global",
+            "ownership_root": "enums",
+            "owning_path": null,
+            "metadata": {"enum": {
+                "members": [{"name": "OPEN"}],
+                "scalar_type": "VARCHAR"
+            }}
+        }, {
+            "identity": "macro:normalize_status",
+            "kind": "macro",
+            "name": "normalize_status",
+            "owner": null,
+            "path": "macros/normalize_status.py",
+            "line": 1,
+            "column": 1,
+            "scope": "global",
+            "ownership_root": "macros",
+            "owning_path": null,
+            "metadata": {"macro": {
+                "parameters": ["status"],
+                "dependencies": ["enum:status"],
+                "source_digest": "digest"
+            }}
+        }],
+        "usages": [{
+            "consumer": "model:orders",
+            "declaration": "enum:status",
+            "kind": "runtime",
+            "through": null,
+            "enum_member": "OPEN"
+        }],
+        "grants": [{
+            "resource": "model:orders",
+            "declaration": "enum:status",
+            "through": "model:expected_orders",
+            "kind": "expected_model"
+        }],
+        "visibility": [{
+            "resource": "model:orders",
+            "declaration": "enum:status",
+            "reason": "global",
+            "through": null
+        }],
+        "inaccessible": [{
+            "resource": "model:orders",
+            "declaration": "constant:private_limit",
+            "reason": "private_owner"
+        }],
+        "diagnostics": [],
+        "complete": true,
+        "completeness": {
+            "discovery": true,
+            "static_visibility": true,
+            "runtime_usage": true,
+            "relationships": true,
+            "placement": true,
+            "promotion_impact": true
+        }
+    })
+}
+
+pub(crate) fn request_with_scope(scope: Value) -> Value {
+    json!({
+        "version": 1,
+        "project_dir": ".",
+        "config": {},
+        "models": [],
+        "public_enums": [],
+        "public_constants": [],
+        "custom_rules": [],
+        "custom_host": null,
+        "project_fingerprint": null,
+        "scope_index": scope
+    })
+}

sqlbuild-0.60.0/crates/sqlbuild-kata-native/src/engine/tests/test_scope_facts.rs

@@ -0,0 +1,161 @@
+use crate::engine::tests::{helpers, test_types};
+use crate::models::EvaluateRequest;
+use serde_json::json;
+use tempfile::TempDir;
+
+#[test]
+fn given_supported_request_without_scope_facts_when_deserializing_then_scope_is_incomplete()
+-> Result<(), String> {
+    let test_cases = [test_types::MissingScopeFactsTestCase {
+        description: "omitted legacy scope facts are explicitly incomplete",
+        expected_complete: false,
+        expected_runtime_usage: false,
+    }];
+
+    for test_case in &test_cases {
+        let project_dir = TempDir::new().map_err(|error| error.to_string())?;
+        let request: EvaluateRequest =
+            serde_json::from_str(&helpers::request(&project_dir, &json!({})))
+                .map_err(|error| error.to_string())?;
+
+        assert_eq!(
+            request.scope_index.complete, test_case.expected_complete,
+            "{}",
+            test_case.description
+        );
+        assert_eq!(
+            request.scope_index.completeness.runtime_usage, test_case.expected_runtime_usage,
+            "{}",
+            test_case.description
+        );
+    }
+    Ok(())
+}
+
+#[test]
+fn given_complete_scope_facts_when_deserializing_then_typed_request_is_accepted() {
+    let test_cases = [test_types::ScopeFactsTestCase {
+        description: "complete scope facts deserialize",
+        scope: helpers::scope_index(),
+        expected_complete: true,
+        expected_runtime_usage: true,
+        expected_declaration_count: 2,
+        expected_visibility_count: 1,
+    }];
+
+    for test_case in &test_cases {
+        let request: EvaluateRequest =
+            serde_json::from_value(helpers::request_with_scope(test_case.scope.clone()))
+                .expect(test_case.description);
+
+        assert_eq!(
+            request.scope_index.complete, test_case.expected_complete,
+            "{}",
+            test_case.description
+        );
+        assert_eq!(
+            request.scope_index.declarations.len(),
+            test_case.expected_declaration_count,
+            "{}",
+            test_case.description
+        );
+        assert_eq!(
+            request.scope_index.visibility.len(),
+            test_case.expected_visibility_count,
+            "{}",
+            test_case.description
+        );
+    }
+}
+
+#[test]
+fn given_partial_scope_facts_when_deserializing_then_completeness_is_preserved() {
+    let mut partial = helpers::scope_index();
+    partial["complete"] = json!(false);
+    partial["completeness"]["runtime_usage"] = json!(false);
+    partial["diagnostics"] = json!([{
+        "code": "S013",
+        "message": "runtime usage is incomplete",
+        "severity": "warning",
+        "path": "models/orders.sql",
+        "line": 1,
+        "column": 1,
+        "declaration": null,
+        "resource": "model:orders"
+    }]);
+    let test_cases = [test_types::ScopeFactsTestCase {
+        description: "partial scope completeness deserializes",
+        scope: partial,
+        expected_complete: false,
+        expected_runtime_usage: false,
+        expected_declaration_count: 2,
+        expected_visibility_count: 1,
+    }];
+
+    for test_case in &test_cases {
+        let request: EvaluateRequest =
+            serde_json::from_value(helpers::request_with_scope(test_case.scope.clone()))
+                .expect(test_case.description);
+
+        assert_eq!(
+            request.scope_index.complete, test_case.expected_complete,
+            "{}",
+            test_case.description
+        );
+        assert_eq!(
+            request.scope_index.completeness.runtime_usage, test_case.expected_runtime_usage,
+            "{}",
+            test_case.description
+        );
+    }
+}
+
+#[test]
+fn given_malformed_scope_records_when_deserializing_then_request_is_rejected() {
+    let mut missing_field = helpers::scope_index();
+    missing_field["declarations"][0]
+        .as_object_mut()
+        .expect("declaration should be an object")
+        .remove("scope");
+    let mut enum_value_leak = helpers::scope_index();
+    enum_value_leak["declarations"][0]["metadata"]["enum"]["members"][0]["value"] = json!("secret");
+    let mut unknown_field = helpers::scope_index();
+    unknown_field["resources"][0]["absolute_path"] = json!("/tmp/orders.sql");
+    let mut unsupported_schema = helpers::scope_index();
+    unsupported_schema["schema_version"] = json!(999);
+    let test_cases = [
+        test_types::MalformedScopeFactsTestCase {
+            description: "missing declaration field is rejected",
+            scope: missing_field,
+            expected_rejected: true,
+        },
+        test_types::MalformedScopeFactsTestCase {
+            description: "enum value leak is rejected",
+            scope: enum_value_leak,
+            expected_rejected: true,
+        },
+        test_types::MalformedScopeFactsTestCase {
+            description: "unknown resource field is rejected",
+            scope: unknown_field,
+            expected_rejected: true,
+        },
+        test_types::MalformedScopeFactsTestCase {
+            description: "unsupported schema is rejected",
+            scope: unsupported_schema,
+            expected_rejected: true,
+        },
+    ];
+
+    for test_case in &test_cases {
+        let rejected = serde_json::from_value::<EvaluateRequest>(helpers::request_with_scope(
+            test_case.scope.clone(),
+        ))
+        .is_err();
+
+        assert_eq!(
+            rejected, test_case.expected_rejected,
+            "{}",
+            test_case.description
+        );
+    }
+}

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/crates/sqlbuild-kata-native/src/engine/tests/test_types.rs

@@ -20,3 +20,24 @@ pub(crate) struct ThresholdFingerprintTestCase {
     pub(crate) overridden_config: Value,
     pub(crate) expected_different: bool,
 }
+
+pub(crate) struct ScopeFactsTestCase {
+    pub(crate) description: &'static str,
+    pub(crate) scope: Value,
+    pub(crate) expected_complete: bool,
+    pub(crate) expected_runtime_usage: bool,
+    pub(crate) expected_declaration_count: usize,
+    pub(crate) expected_visibility_count: usize,
+}
+
+pub(crate) struct MalformedScopeFactsTestCase {
+    pub(crate) description: &'static str,
+    pub(crate) scope: Value,
+    pub(crate) expected_rejected: bool,
+}
+
+pub(crate) struct MissingScopeFactsTestCase {
+    pub(crate) description: &'static str,
+    pub(crate) expected_complete: bool,
+    pub(crate) expected_runtime_usage: bool,
+}

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/crates/sqlbuild-kata-native/src/engine/tests.rs

@@ -2,5 +2,7 @@
 mod evaluation;
 #[path = "tests/helpers.rs"]
 mod helpers;
+#[path = "tests/test_scope_facts.rs"]
+mod scope_facts;
 #[path = "tests/test_types.rs"]
 mod test_types;

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/crates/sqlbuild-kata-native/src/lib.rs

@@ -6,3 +6,4 @@ mod constants;
 mod engine;
 mod models;
 mod rules;
+mod scope_metadata;

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/crates/sqlbuild-kata-native/src/models.rs

@@ -2,7 +2,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::collections::BTreeMap;
 
-use crate::constants::API_VERSION;
+use crate::constants::{API_VERSION, SCOPE_METADATA_SCHEMA_VERSION};
 
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 #[serde(default, deny_unknown_fields)]
@@ -131,6 +131,279 @@ pub(crate) struct Declaration {
     pub render_as: Option<String>,
 }
 
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ResourceKind {
+    Model,
+    Test,
+    Scenario,
+    Hook,
+    Function,
+    Audit,
+    Source,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum DeclarationKind {
+    Macro,
+    Enum,
+    Constant,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ScopeKind {
+    Global,
+    Inherited,
+    Local,
+    Private,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum UsageKind {
+    Runtime,
+    Generated,
+    DeclarationDependency,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum GrantKind {
+    ExpectedModel,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum VisibilityReason {
+    Global,
+    InheritedAncestor,
+    LocalOwner,
+    PrivateOwner,
+    ExpectedModel,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum InaccessibleReason {
+    LocalBoundary,
+    SiblingScope,
+    DescendantScope,
+    UnrelatedScope,
+    PrivateOwner,
+    UnsupportedResourceKind,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum DiagnosticSeverity {
+    Error,
+    Warning,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub(crate) enum ScopeDiagnosticCode {
+    S001,
+    S002,
+    S003,
+    S004,
+    S005,
+    S006,
+    S007,
+    S008,
+    S009,
+    S010,
+    S011,
+    S012,
+    S013,
+    S014,
+    S015,
+    S016,
+    S017,
+    S018,
+    S019,
+    S020,
+    S021,
+    S022,
+    S023,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeOwnershipRoot {
+    pub path: String,
+    pub resource_kind: Option<ResourceKind>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeResource {
+    pub identity: String,
+    pub kind: ResourceKind,
+    pub name: String,
+    pub path: String,
+    pub ownership_root: String,
+    pub ownership_root_kind: Option<ResourceKind>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeMacroMetadata {
+    pub parameters: Vec<String>,
+    pub dependencies: Vec<String>,
+    pub source_digest: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeEnumMember {
+    pub name: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeEnumMetadata {
+    pub members: Vec<ScopeEnumMember>,
+    pub scalar_type: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeConstantMetadata {
+    pub logical_type: String,
+    pub collection_kind: Option<String>,
+    pub item_count: Option<u64>,
+    pub nullable: bool,
+    pub render_as: Option<String>,
+}
+
+#[derive(Clone, Debug, Default, Deserialize, Serialize)]
+#[serde(default, deny_unknown_fields)]
+pub(crate) struct ScopeDeclarationMetadata {
+    pub r#macro: Option<ScopeMacroMetadata>,
+    pub r#enum: Option<ScopeEnumMetadata>,
+    pub constant: Option<ScopeConstantMetadata>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeDeclaration {
+    pub identity: String,
+    pub kind: DeclarationKind,
+    pub name: String,
+    pub owner: Option<String>,
+    pub path: String,
+    pub line: u64,
+    pub column: u64,
+    pub scope: ScopeKind,
+    pub ownership_root: String,
+    pub owning_path: Option<String>,
+    pub metadata: ScopeDeclarationMetadata,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeUsage {
+    pub consumer: String,
+    pub declaration: String,
+    pub kind: UsageKind,
+    pub through: Option<String>,
+    pub enum_member: Option<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeGrant {
+    pub resource: String,
+    pub declaration: String,
+    pub through: String,
+    pub kind: GrantKind,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeVisibility {
+    pub resource: String,
+    pub declaration: String,
+    pub reason: VisibilityReason,
+    pub through: Option<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeInaccessible {
+    pub resource: String,
+    pub declaration: String,
+    pub reason: InaccessibleReason,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeDiagnostic {
+    pub code: ScopeDiagnosticCode,
+    pub message: String,
+    pub severity: DiagnosticSeverity,
+    pub path: Option<String>,
+    pub line: Option<u64>,
+    pub column: Option<u64>,
+    pub declaration: Option<String>,
+    pub resource: Option<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeCompleteness {
+    pub discovery: bool,
+    pub static_visibility: bool,
+    pub runtime_usage: bool,
+    pub relationships: bool,
+    pub placement: bool,
+    pub promotion_impact: bool,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ScopeIndexFacts {
+    #[serde(deserialize_with = "crate::scope_metadata::deserialize_scope_schema_version")]
+    pub schema_version: u32,
+    pub ownership_roots: Vec<ScopeOwnershipRoot>,
+    pub resources: Vec<ScopeResource>,
+    pub declarations: Vec<ScopeDeclaration>,
+    pub usages: Vec<ScopeUsage>,
+    pub grants: Vec<ScopeGrant>,
+    pub visibility: Vec<ScopeVisibility>,
+    pub inaccessible: Vec<ScopeInaccessible>,
+    pub diagnostics: Vec<ScopeDiagnostic>,
+    pub complete: bool,
+    pub completeness: ScopeCompleteness,
+}
+
+impl Default for ScopeIndexFacts {
+    fn default() -> Self {
+        Self {
+            schema_version: SCOPE_METADATA_SCHEMA_VERSION,
+            ownership_roots: vec![],
+            resources: vec![],
+            declarations: vec![],
+            usages: vec![],
+            grants: vec![],
+            visibility: vec![],
+            inaccessible: vec![],
+            diagnostics: vec![],
+            complete: false,
+            completeness: ScopeCompleteness {
+                discovery: false,
+                static_visibility: false,
+                runtime_usage: false,
+                relationships: false,
+                placement: false,
+                promotion_impact: false,
+            },
+        }
+    }
+}
+
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 #[serde(default, deny_unknown_fields)]
 pub(crate) struct Model {
@@ -195,6 +468,7 @@ pub(crate) struct EvaluateRequest {
     pub models: Vec<Model>,
     pub public_enums: Vec<Declaration>,
     pub public_constants: Vec<Declaration>,
+    pub scope_index: ScopeIndexFacts,
     pub custom_rules: Vec<CustomRule>,
     pub custom_host: Option<CustomHostSpec>,
     pub project_fingerprint: Option<String>,
@@ -227,6 +501,7 @@ impl Default for EvaluateRequest {
             models: vec![],
             public_enums: vec![],
             public_constants: vec![],
+            scope_index: ScopeIndexFacts::default(),
             custom_rules: vec![],
             custom_host: None,
             project_fingerprint: None,

sqlbuild-0.60.0/crates/sqlbuild-kata-native/src/scope_metadata.rs

@@ -0,0 +1,16 @@
+use serde::{Deserialize, Deserializer};
+
+use crate::constants::SCOPE_METADATA_SCHEMA_VERSION;
+
+pub(crate) fn deserialize_scope_schema_version<'de, D>(deserializer: D) -> Result<u32, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let version = u32::deserialize(deserializer)?;
+    if version != SCOPE_METADATA_SCHEMA_VERSION {
+        return Err(serde::de::Error::custom(format!(
+            "unsupported scope metadata schema version {version}; expected {SCOPE_METADATA_SCHEMA_VERSION}"
+        )));
+    }
+    Ok(version)
+}

{sqlbuild-0.59.0 → sqlbuild-0.60.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlbuild"
-version = "0.59.0"
+version = "0.60.0"
 description = "Typed, test-first SQL pipelines with local E2E testing"
 readme = "README.md"
 requires-python = ">=3.12"