polyglot-sql 0.11.0__tar.gz → 0.12.1__tar.gz

{polyglot_sql-0.11.0 → polyglot_sql-0.12.1}/Cargo.lock

@@ -605,7 +605,7 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql"
-version = "0.11.0"
+version = "0.12.1"
 dependencies = [
  "criterion",
  "once_cell",
@@ -623,7 +623,7 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql-ast-derive"
-version = "0.11.0"
+version = "0.12.1"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -632,7 +632,7 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql-ffi"
-version = "0.11.0"
+version = "0.12.1"
 dependencies = [
  "cbindgen",
  "polyglot-sql",
@@ -642,11 +642,11 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql-function-catalogs"
-version = "0.11.0"
+version = "0.12.1"
 
 [[package]]
 name = "polyglot-sql-python"
-version = "0.11.0"
+version = "0.12.1"
 dependencies = [
  "polyglot-sql",
  "pyo3",
@@ -657,7 +657,7 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql-wasm"
-version = "0.11.0"
+version = "0.12.1"
 dependencies = [
  "console_error_panic_hook",
  "js-sys",

{polyglot_sql-0.11.0 → polyglot_sql-0.12.1}/Cargo.toml

@@ -6,7 +6,7 @@ exclude = [
 ]
 
 [workspace.package]
-version = "0.11.0"
+version = "0.12.1"
 edition = "2021"
 license = "MIT"
 authors = ["polyglot contributors"]

{polyglot_sql-0.11.0 → polyglot_sql-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyglot-sql
-Version: 0.11.0
+Version: 0.12.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -112,7 +112,9 @@ polyglot_sql.generate(ast)
 
 ### Complexity Guard Options
 
-`transpile` also accepts `complexity_guard`, a `ComplexityGuardOptions` typed dictionary
+`parse`, `parse_one` (including `into=DataType`), `parse_data_type`, `validate`,
+`validate_with_schema`, `analyze_query`, and `transpile` accept the keyword-only
+`complexity_guard`, a `ComplexityGuardOptions` typed dictionary
 using the shared camelCase keys: `maxParserDepth`, `maxInputBytes`, `maxTokens`,
 `maxAstNodes`, `maxAstDepth`, `maxParenthesisDepth`, and `maxFunctionCallDepth`.
 Omit the argument, pass `None`, or omit a key to use its default. A field-level `None`
@@ -120,15 +122,26 @@ disables that check; a nonnegative integer overrides it. For example:
 
 ```python
 polyglot_sql.transpile(sql, complexity_guard={"maxParserDepth": 128})
+polyglot_sql.validate(sql, dialect="snowflake", complexity_guard={"maxFunctionCallDepth": 128})
+polyglot_sql.parse_one(sql, dialect="snowflake", complexity_guard={"maxFunctionCallDepth": None})
 ```
 
+`analyze_query` also accepts `options={"complexityGuard": {...}}`; do not supply
+both forms in one call. Limits must be nonnegative integers or `None`; booleans,
+floats, out-of-range integers, and unknown guard keys are rejected.
+Omitting the entire guard preserves dialect-specific defaults (including
+ClickHouse's higher function-nesting limit). A supplied dictionary uses the
+shared Rust defaults for omitted fields. Validation reports guard exhaustion
+as diagnostics; parsing and analysis raise `ParseError`.
+
 Parser depth defaults to 1024 logical levels on native targets (32 on WASM) and is
 checked during parsing, before an AST exists. Zero rejects parsing descents.
 Other checks remain independent.
 Raising or disabling limits can permit stack exhaustion and process termination,
 even for trusted generated SQL. Increasing a limit does not increase stack space;
 these limits are not general time/memory budgets. Application owners should control
-overrides. Parsing APIs without guard options inherit the default protection.
+overrides. Other SQL-consuming helpers, including lineage and optimization,
+continue to inherit default protection.
 
 ### Format Guard Behavior
 
@@ -365,9 +378,47 @@ Unknown dialect names raise built-in `ValueError`.
 - `bool(result)` works (`True` when valid)
 
 `strict_syntax=True` rejects compatibility forms such as trailing commas before
-clause boundaries. `semantic=True` adds warning diagnostics W001-W004 for
-`SELECT *`, mixed aggregate projections, `DISTINCT` with `ORDER BY`, and
-`LIMIT` without `ORDER BY`; warnings do not make the result invalid.
+clause boundaries. `semantic=True` checks every query scope and reports errors
+for invalid grouping (`E230`), aggregate placement/nesting (`E231`), and window
+placement/nesting (`E232`). These errors make the result invalid, including with
+`strict=False`. Quality hints remain warnings: `SELECT *` (`W001`), uncertain
+grouping (`W002`), `DISTINCT` with `ORDER BY` (`W003`), and unordered `LIMIT`
+(`W004`). Default validation remains syntax-only.
+
+Schema validation always checks DML targets and references, independently of
+`check_types`. Type checks use lexical query scopes and name-aligned set-operation
+outputs. An empty column list or `*` denotes an open schema; validation is not a
+database execution check and cannot prove runtime/session-dependent behavior.
+
+Analysis options and schemas reject unknown keys, including nested metadata.
+Public `TypedDict` models such as `AnalyzeQueryOptions`, `ValidationSchema`,
+`QueryAnalysis`, and `FunctionCatalogSpec` describe their dictionary payloads.
+Analysis retains best-effort references for missing columns but marks them
+`unknown`, not `resolved`. Lambda-local parameters are not physical dependencies.
+
+Python also accepts a declarative function catalog (Rust offers
+`FunctionCatalogSpec::build` and the existing `FunctionCatalog` trait):
+
+```python
+catalog: polyglot_sql.FunctionCatalogSpec = {
+    "functions": [{
+        "name": "my_udf",
+        "signatures": [{"minArity": 1, "maxArity": 2}],
+    }],
+}
+result = polyglot_sql.validate_with_schema(
+    "SELECT my_udf(1)", {"tables": []}, check_types=True,
+    function_catalog=catalog,
+)
+```
+
+The catalog **replaces** the embedded function name/arity catalog; it does not
+activate `check_types` automatically. Overloads are supported; omitted/null
+`maxArity` means variadic. `nameCase` is `insensitive` by default, or `sensitive`,
+and can be overridden per function. Native typed-function checks remain active.
+Blank names, empty signature lists, negative/noninteger arities, reversed bounds,
+conflicting case overrides, and unknown fields are rejected. Other SDKs do not
+expose this catalog option.
 
 Each `ValidationErrorInfo` has:
 

{polyglot_sql-0.11.0/crates/polyglot-sql-python → polyglot_sql-0.12.1}/README.md

@@ -85,7 +85,9 @@ polyglot_sql.generate(ast)
 
 ### Complexity Guard Options
 
-`transpile` also accepts `complexity_guard`, a `ComplexityGuardOptions` typed dictionary
+`parse`, `parse_one` (including `into=DataType`), `parse_data_type`, `validate`,
+`validate_with_schema`, `analyze_query`, and `transpile` accept the keyword-only
+`complexity_guard`, a `ComplexityGuardOptions` typed dictionary
 using the shared camelCase keys: `maxParserDepth`, `maxInputBytes`, `maxTokens`,
 `maxAstNodes`, `maxAstDepth`, `maxParenthesisDepth`, and `maxFunctionCallDepth`.
 Omit the argument, pass `None`, or omit a key to use its default. A field-level `None`
@@ -93,15 +95,26 @@ disables that check; a nonnegative integer overrides it. For example:
 
 ```python
 polyglot_sql.transpile(sql, complexity_guard={"maxParserDepth": 128})
+polyglot_sql.validate(sql, dialect="snowflake", complexity_guard={"maxFunctionCallDepth": 128})
+polyglot_sql.parse_one(sql, dialect="snowflake", complexity_guard={"maxFunctionCallDepth": None})
 ```
 
+`analyze_query` also accepts `options={"complexityGuard": {...}}`; do not supply
+both forms in one call. Limits must be nonnegative integers or `None`; booleans,
+floats, out-of-range integers, and unknown guard keys are rejected.
+Omitting the entire guard preserves dialect-specific defaults (including
+ClickHouse's higher function-nesting limit). A supplied dictionary uses the
+shared Rust defaults for omitted fields. Validation reports guard exhaustion
+as diagnostics; parsing and analysis raise `ParseError`.
+
 Parser depth defaults to 1024 logical levels on native targets (32 on WASM) and is
 checked during parsing, before an AST exists. Zero rejects parsing descents.
 Other checks remain independent.
 Raising or disabling limits can permit stack exhaustion and process termination,
 even for trusted generated SQL. Increasing a limit does not increase stack space;
 these limits are not general time/memory budgets. Application owners should control
-overrides. Parsing APIs without guard options inherit the default protection.
+overrides. Other SQL-consuming helpers, including lineage and optimization,
+continue to inherit default protection.
 
 ### Format Guard Behavior
 
@@ -338,9 +351,47 @@ Unknown dialect names raise built-in `ValueError`.
 - `bool(result)` works (`True` when valid)
 
 `strict_syntax=True` rejects compatibility forms such as trailing commas before
-clause boundaries. `semantic=True` adds warning diagnostics W001-W004 for
-`SELECT *`, mixed aggregate projections, `DISTINCT` with `ORDER BY`, and
-`LIMIT` without `ORDER BY`; warnings do not make the result invalid.
+clause boundaries. `semantic=True` checks every query scope and reports errors
+for invalid grouping (`E230`), aggregate placement/nesting (`E231`), and window
+placement/nesting (`E232`). These errors make the result invalid, including with
+`strict=False`. Quality hints remain warnings: `SELECT *` (`W001`), uncertain
+grouping (`W002`), `DISTINCT` with `ORDER BY` (`W003`), and unordered `LIMIT`
+(`W004`). Default validation remains syntax-only.
+
+Schema validation always checks DML targets and references, independently of
+`check_types`. Type checks use lexical query scopes and name-aligned set-operation
+outputs. An empty column list or `*` denotes an open schema; validation is not a
+database execution check and cannot prove runtime/session-dependent behavior.
+
+Analysis options and schemas reject unknown keys, including nested metadata.
+Public `TypedDict` models such as `AnalyzeQueryOptions`, `ValidationSchema`,
+`QueryAnalysis`, and `FunctionCatalogSpec` describe their dictionary payloads.
+Analysis retains best-effort references for missing columns but marks them
+`unknown`, not `resolved`. Lambda-local parameters are not physical dependencies.
+
+Python also accepts a declarative function catalog (Rust offers
+`FunctionCatalogSpec::build` and the existing `FunctionCatalog` trait):
+
+```python
+catalog: polyglot_sql.FunctionCatalogSpec = {
+    "functions": [{
+        "name": "my_udf",
+        "signatures": [{"minArity": 1, "maxArity": 2}],
+    }],
+}
+result = polyglot_sql.validate_with_schema(
+    "SELECT my_udf(1)", {"tables": []}, check_types=True,
+    function_catalog=catalog,
+)
+```
+
+The catalog **replaces** the embedded function name/arity catalog; it does not
+activate `check_types` automatically. Overloads are supported; omitted/null
+`maxArity` means variadic. `nameCase` is `insensitive` by default, or `sensitive`,
+and can be overridden per function. Native typed-function checks remain active.
+Blank names, empty signature lists, negative/noninteger arities, reversed bounds,
+conflicting case overrides, and unknown fields are rejected. Other SDKs do not
+expose this catalog option.
 
 Each `ValidationErrorInfo` has:
 

{polyglot_sql-0.11.0 → polyglot_sql-0.12.1}/crates/polyglot-sql/Cargo.toml

@@ -100,14 +100,14 @@ function-catalog-all-dialects = [
 ]
 
 [dependencies]
-polyglot-sql-ast-derive = { path = "../polyglot-sql-ast-derive", version = "0.11.0" }
+polyglot-sql-ast-derive = { path = "../polyglot-sql-ast-derive", version = "0.12.1" }
 serde = { workspace = true }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
 unicode-segmentation = { workspace = true }
 stacker = { version = "0.1", optional = true }
 ts-rs = { version = "12.0", features = ["serde-compat"], optional = true }
-polyglot-sql-function-catalogs = { path = "../polyglot-sql-function-catalogs", version = "0.11.0", optional = true, default-features = false }
+polyglot-sql-function-catalogs = { path = "../polyglot-sql-function-catalogs", version = "0.12.1", optional = true, default-features = false }
 
 [dev-dependencies]
 pretty_assertions = "1.4"

{polyglot_sql-0.11.0 → polyglot_sql-0.12.1}/crates/polyglot-sql/README.md

@@ -25,12 +25,12 @@ By default, `polyglot-sql` enables the full public API. Parser-only consumers ca
 disable default features and opt into only the dialect parsers they need:
 
 ```toml
-polyglot-sql = { version = "0.11.0", default-features = false }
+polyglot-sql = { version = "0.12.1", default-features = false }
 ```
 
 ```toml
 polyglot-sql = {
-    version = "0.11.0",
+    version = "0.12.1",
     default-features = false,
     features = ["dialect-clickhouse"],
 }
@@ -44,14 +44,14 @@ Examples:
 ```toml
 # Parse and generate SQL for one dialect.
 polyglot-sql = {
-    version = "0.11.0",
+    version = "0.12.1",
     default-features = false,
     features = ["generate", "dialect-clickhouse"],
 }
 
 # Cross-dialect transpilation.
 polyglot-sql = {
-    version = "0.11.0",
+    version = "0.12.1",
     default-features = false,
     features = ["transpile", "dialect-clickhouse", "dialect-postgresql"],
 }
@@ -244,6 +244,29 @@ let tables = get_tables(&ast[0]);
 
 ### Validation
 
+Parsing, validation, and query analysis accept per-call `ComplexityGuardOptions`.
+Existing entry points retain their defaults; parsing adds `parse_with_options`,
+`parse_one_with_options`, and `parse_data_type_with_options` (and corresponding
+`Dialect` parsing methods). For example:
+
+```rust
+use polyglot_sql::{parse_one_with_options, ComplexityGuardOptions, DialectType, ParseOptions};
+
+let options = ParseOptions {
+    complexity_guard: Some(ComplexityGuardOptions {
+        max_function_call_depth: Some(128),
+        ..Default::default()
+    }),
+};
+let expression = parse_one_with_options("SELECT COALESCE(value, 0) FROM records", DialectType::Snowflake, &options)?;
+```
+
+`ValidationOptions`, `SchemaValidationOptions`, and `AnalyzeQueryOptions` expose
+the same optional `complexity_guard`. An absent guard preserves dialect-specific
+defaults; `None` on an individual limit disables only that check. Raising or
+disabling limits can permit stack exhaustion; these are not general runtime or
+memory budgets. Use `..Default::default()` when constructing extended options.
+
 ```rust
 use polyglot_sql::{validate_with_options, DialectType, ValidationOptions};
 
@@ -253,6 +276,7 @@ let result = validate_with_options(
     &ValidationOptions {
         strict_syntax: false,
         semantic: true,
+        ..Default::default()
     },
 );
 // W001 and W004 are warnings, so result.valid remains true.
@@ -301,6 +325,7 @@ let opts = SchemaValidationOptions {
     check_references: true,
     strict: None,
     semantic: true,
+    ..Default::default()
 };
 
 let result = validate_with_schema(
@@ -360,6 +385,7 @@ let analysis = analyze_query(
     AnalyzeQueryOptions {
         dialect: DialectType::Generic,
         schema: Some(schema),
+        ..Default::default()
     },
 ).unwrap();
 

{polyglot_sql-0.11.0 → polyglot_sql-0.12.1}/crates/polyglot-sql/benches/performance_hotspots.rs

@@ -210,10 +210,70 @@ fn bench_tokenize_and_parse(c: &mut Criterion) {
     guards.finish();
 }
 
+fn bench_validation_and_analysis(c: &mut Criterion) {
+    #[cfg(all(feature = "semantic", feature = "generate"))]
+    {
+        use polyglot_sql::{
+            analyze_query, validate_with_schema, AnalyzeQueryOptions, SchemaValidationOptions,
+            ValidationSchema,
+        };
+        let schema: ValidationSchema = serde_json::from_value(
+            serde_json::json!({"tables": [{"name":"t", "columns":[{"name":"x", "type":"INT"}]}]}),
+        )
+        .unwrap();
+        let mut group = c.benchmark_group("validation_analysis");
+        group.sample_size(10);
+        for width in [100, 200, 400] {
+            let sql = format!(
+                "SELECT {} FROM t",
+                (0..width)
+                    .map(|i| format!("x + {i} AS c{i}"))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+            group.bench_with_input(BenchmarkId::new("analysis_width", width), &sql, |b, sql| {
+                b.iter(|| {
+                    analyze_query(
+                        black_box(sql),
+                        AnalyzeQueryOptions {
+                            schema: Some(schema.clone()),
+                            dialect: DialectType::PostgreSQL,
+                            ..Default::default()
+                        },
+                    )
+                    .unwrap()
+                });
+            });
+            group.bench_with_input(
+                BenchmarkId::new("validation_width", width),
+                &sql,
+                |b, sql| {
+                    b.iter(|| {
+                        validate_with_schema(
+                            black_box(sql),
+                            DialectType::PostgreSQL,
+                            &schema,
+                            &SchemaValidationOptions {
+                                check_types: true,
+                                semantic: true,
+                                ..Default::default()
+                            },
+                        )
+                    });
+                },
+            );
+        }
+        group.finish();
+    }
+    #[cfg(not(all(feature = "semantic", feature = "generate")))]
+    let _ = c;
+}
+
 criterion_group!(
     benches,
     bench_dialect_construction,
     bench_fresh_vs_reused_dialect,
-    bench_tokenize_and_parse
+    bench_tokenize_and_parse,
+    bench_validation_and_analysis
 );
 criterion_main!(benches);