feat: add opt-in SQBRPYTHON rules for project Python

Cargo.toml

@@ -75,6 +75,10 @@ axum-server = { version = "0.8", default-features = false, features = ["tls-rust
 # Compresses the server's larger JSON reads and UI assets for browsers.
 tower-http = { version = "0.6", default-features = false, features = ["compression-gzip"] }
 fensu-policy = "=0.22.0"
+# Fensu's Python facts and core rules without their Python bindings: the default `python`
+# feature adds PyO3, rusqlite, flate2 and sha2.
+fensu-facts = { version = "=0.30.0", default-features = false }
+fensu-native = { version = "=0.30.0", default-features = false }
 futures-util = { version = "0.3", default-features = false, features = ["std"] }
 # `sqb` names compute log captures with random ids, as `uuid.uuid4().hex`.
 getrandom = "0.4"

benchmarks/duckshop/edge_cases/python_rules/conforming/audits/generic/expression_is_true.sql

@@ -0,0 +1,5 @@
+AUDIT ();
+
+SELECT *
+FROM @relation
+WHERE NOT (@expression)

benchmarks/duckshop/edge_cases/python_rules/conforming/hooks/python/notify.py

@@ -0,0 +1,6 @@
+"""Note each finished build."""
+
+
+def note_build(ctx: object) -> None:
+    """Note one finished build."""
+    print(ctx)

benchmarks/duckshop/edge_cases/python_rules/conforming/models/shipments.sql

@@ -0,0 +1,2 @@
+MODEL (description "Shipped orders.", audit_factories [shipment_quality]);
+SELECT 1 AS shipment_id

benchmarks/duckshop/edge_cases/python_rules/conforming/python/fulfillment/shipment_export/main.py

@@ -0,0 +1,9 @@
+"""Write each shipped order as one carrier line."""
+
+from python.utils.currency import amounts
+
+
+def export_shipments(ctx: object) -> None:
+    """Write each shipped order as one carrier line."""
+    label: str = "Expédition"
+    print(label, amounts.cents_text(1250), ctx)

benchmarks/duckshop/edge_cases/python_rules/conforming/python/fulfillment/shipment_export/node.py

@@ -0,0 +1,10 @@
+"""Export shipped orders to the carrier."""
+
+from python.fulfillment.shipment_export.main import export_shipments
+from sqlbuild.tasks import task
+
+
+@task
+def shipment_export(ctx: object) -> None:
+    """Export shipped orders to the carrier."""
+    export_shipments(ctx)

benchmarks/duckshop/edge_cases/python_rules/conforming/python/fulfillment/shipment_quality/factories.py

@@ -0,0 +1,15 @@
+"""Audit cases every shipment table shares."""
+
+from sqlbuild.audits import AuditCase, audit_factory
+
+
+@audit_factory
+def shipment_quality() -> list[AuditCase]:
+    """Every shipment has a positive identifier."""
+    return [
+        AuditCase(
+            name="positive_shipment_id",
+            definition="expression_is_true",
+            arguments={"expression": "shipment_id > 0"},
+        )
+    ]

benchmarks/duckshop/edge_cases/python_rules/conforming/python/utils/currency/amounts.py

@@ -0,0 +1,6 @@
+"""Format money for carrier files."""
+
+
+def cents_text(cents: int) -> str:
+    """Return cents as a decimal amount."""
+    return f"{cents // 100}.{cents % 100:02d}"

benchmarks/duckshop/edge_cases/python_rules/expected_findings.json

@@ -0,0 +1,16 @@
+{
+  "select": ["SQBRPYTHON", "SQBRPYTHON306"],
+  "findings": [
+    ["SQBRPYTHON101", "hooks/python/alert.py", 4, 11],
+    ["SQBRPYTHON613", "python/inventory/__init__.py", 1, 1],
+    ["SQBRPYTHON002", "python/inventory/common/__init__.py", 1, 1],
+    ["SQBRPYTHON306", "python/inventory/common/stock.py", 4, 1],
+    ["SQBRPYTHON305", "python/inventory/main/publish.py", 1, 1],
+    ["SQBRPYTHON306", "python/inventory/main/publish.py", 4, 1],
+    ["SQBRPYTHON617", "python/inventory/restock/main.py", 1, 1],
+    ["SQBRPYTHON306", "python/inventory/restock/main.py", 4, 1],
+    ["SQBRPYTHON306", "python/inventory/restock/main.py", 9, 1],
+    ["SQBRPYTHON001", "python/report.py", 1, 1],
+    ["SQBRPYTHON614", "python/report.py", 1, 1]
+  ]
+}

benchmarks/duckshop/edge_cases/python_rules/violations/hooks/python/alert.py

@@ -0,0 +1,6 @@
+"""Alert on failed builds."""
+
+
+def alert(ctx, reason: str) -> None:
+    """Alert on one failed build."""
+    print(ctx, reason)

benchmarks/duckshop/edge_cases/python_rules/violations/python/inventory/common/stock.py

@@ -0,0 +1,6 @@
+"""Stock levels."""
+
+
+def stock_level(sku: str) -> int:
+    """Return the stock level of one product."""
+    return len(sku)

benchmarks/duckshop/edge_cases/python_rules/violations/python/inventory/main/publish.py

@@ -0,0 +1,6 @@
+"""Publish stock levels."""
+
+
+def publish_levels() -> None:
+    """Publish stock levels."""
+    print("levels")

benchmarks/duckshop/edge_cases/python_rules/violations/python/inventory/restock/main.py

@@ -0,0 +1,11 @@
+"""Restock products."""
+
+
+def restock(sku: str) -> None:
+    """Restock one product."""
+    print(sku)
+
+
+def recount(sku: str) -> None:
+    """Recount one product."""
+    print(sku)

benchmarks/duckshop/edge_cases/python_rules/violations/python/report.py

@@ -0,0 +1 @@
+"""A module directly under python/."""

crates/sqlbuild-cli/src/native_commands/_helpers/rules.rs

@@ -43,14 +43,21 @@ fn option_spec(option: &BuiltinOption) -> OptionSpec {
             OptionValue::Tuple(Vec::new()),
             Some(OptionKind::Other(DICT_TYPE_NAME.to_owned())),
         ),
+        BuiltinOptionKind::Integer { default, .. } => {
+            (OptionKind::Int, OptionValue::Int(i64::from(default)), None)
+        }
+    };
+    let minimum: Option<i64> = match option.kind {
+        BuiltinOptionKind::Integer { minimum, .. } => Some(i64::from(minimum)),
+        _ => None,
     };
     OptionSpec {
         name: option.name.to_owned(),
         description: option.description.to_owned(),
         value_type,
         default,
         choices: Vec::new(),
-        minimum: None,
+        minimum,
         maximum: None,
         minimum_items: None,
         item_type,
@@ -63,6 +70,7 @@ fn option_text(option: &BuiltinOption) -> OptionText {
         BuiltinOptionKind::Boolean => FALSE_REPR.to_owned(),
         BuiltinOptionKind::StringList(defaults) => string_tuple_repr(defaults),
         BuiltinOptionKind::TableList => EMPTY_TUPLE_REPR.to_owned(),
+        BuiltinOptionKind::Integer { default, .. } => default.to_string(),
     };
     OptionText {
         name: option.name.to_owned(),

crates/sqlbuild-discovery/src/python_paths/main/mod.rs

@@ -1 +1,2 @@
+pub mod supported_python_paths;
 pub mod unsupported_python_paths;

crates/sqlbuild-discovery/src/python_paths/main/supported_python_paths.rs

@@ -0,0 +1,14 @@
+//! Project Python files under the documented executable roots.
+
+use std::path::Path;
+
+use crate::python_paths::_helpers::python_files::python_files;
+use crate::python_paths::_helpers::supported::is_supported;
+
+/// Each supported Python file below `project_dir` as relative parts, sorted part by part.
+pub fn supported_python_paths(project_dir: &Path) -> Vec<Vec<String>> {
+    python_files(project_dir)
+        .into_iter()
+        .filter(|parts| is_supported(parts))
+        .collect()
+}

crates/sqlbuild-discovery/src/python_paths/tests.rs

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

crates/sqlbuild-discovery/src/python_paths/tests/test_supported_python_paths.rs

@@ -0,0 +1,52 @@
+use crate::python_paths::main::supported_python_paths::supported_python_paths;
+use crate::python_paths::tests::test_types::SupportedPathsTestCase;
+
+#[test]
+fn given_project_python_when_listing_supported_paths_then_only_documented_roots_remain() {
+    let test_cases = [
+        SupportedPathsTestCase {
+            description: "documented roots sorted by parts, skipping hidden, generated and undocumented files",
+            files: &[
+                "python/orders/main.py",
+                "adapter.py",
+                "orchestration/sensors/stock.py",
+                "functions/python/f.py",
+                "models/a/_sqlbuild/hooks/python/h.py",
+                "helpers.py",
+                "models/x.py",
+                ".hidden/x.py",
+                "target/x.py",
+                "python/__pycache__/main.py",
+            ],
+            expected_supported: &[
+                "adapter.py",
+                "functions/python/f.py",
+                "models/a/_sqlbuild/hooks/python/h.py",
+                "orchestration/sensors/stock.py",
+                "python/orders/main.py",
+            ],
+        },
+        SupportedPathsTestCase {
+            description: "a project without Python",
+            files: &[],
+            expected_supported: &[],
+        },
+    ];
+    for test_case in test_cases {
+        let directory = tempfile::tempdir().expect("temporary project");
+        for file in test_case.files {
+            let path = directory.path().join(file);
+            std::fs::create_dir_all(path.parent().expect("parent")).expect("folders");
+            std::fs::write(&path, "").expect("file");
+        }
+        let supported: Vec<String> = supported_python_paths(directory.path())
+            .into_iter()
+            .map(|parts| parts.join("/"))
+            .collect();
+        assert_eq!(
+            supported, test_case.expected_supported,
+            "{}",
+            test_case.description
+        );
+    }
+}

crates/sqlbuild-discovery/src/python_paths/tests/test_types.rs

@@ -4,3 +4,10 @@ pub(super) struct PythonPathsTestCase {
     pub(super) files: &'static [&'static str],
     pub(super) expected_unsupported: &'static [&'static str],
 }
+
+/// One project layout and the Python files the Python rules read.
+pub(super) struct SupportedPathsTestCase {
+    pub(super) description: &'static str,
+    pub(super) files: &'static [&'static str],
+    pub(super) expected_supported: &'static [&'static str],
+}

crates/sqlbuild-pysource/src/definition_locations/_helpers/decorators.rs

@@ -0,0 +1,16 @@
+//! How a decorator expression is named.
+
+use ruff_python_ast::Expr;
+
+/// The decorator's last name segment, looking through a call: `udf`, `sqlbuild.udf` and `udf(...)` all name `udf`.
+pub(crate) fn decorator_name(expression: &Expr) -> Option<&str> {
+    let target: &Expr = match expression {
+        Expr::Call(call) => &call.func,
+        _ => expression,
+    };
+    match target {
+        Expr::Name(name) => Some(name.id.as_str()),
+        Expr::Attribute(attribute) => Some(attribute.attr.as_str()),
+        _ => None,
+    }
+}

crates/sqlbuild-pysource/src/definition_locations/_helpers/mod.rs

@@ -0,0 +1 @@
+pub(crate) mod decorators;