polyglot-sql 0.10.0__tar.gz → 0.12.0__tar.gz

{polyglot_sql-0.10.0 → polyglot_sql-0.12.0}/Cargo.lock

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

{polyglot_sql-0.10.0 → polyglot_sql-0.12.0}/Cargo.toml

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

{polyglot_sql-0.10.0 → polyglot_sql-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyglot-sql
-Version: 0.10.0
+Version: 0.12.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -110,6 +110,39 @@ polyglot_sql.generate(ast)
 # ["SELECT id FROM a UNION ALL SELECT id FROM b ORDER BY id LIMIT 100 OFFSET 10"]
 ```
 
+### Complexity Guard Options
+
+`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`
+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. Other SQL-consuming helpers, including lineage and optimization,
+continue to inherit default protection.
+
 ### Format Guard Behavior
 
 `format_sql` uses Rust core formatting guards with default limits:
@@ -345,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.10.0/crates/polyglot-sql-python → polyglot_sql-0.12.0}/README.md

@@ -83,6 +83,39 @@ polyglot_sql.generate(ast)
 # ["SELECT id FROM a UNION ALL SELECT id FROM b ORDER BY id LIMIT 100 OFFSET 10"]
 ```
 
+### Complexity Guard Options
+
+`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`
+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. Other SQL-consuming helpers, including lineage and optimization,
+continue to inherit default protection.
+
 ### Format Guard Behavior
 
 `format_sql` uses Rust core formatting guards with default limits:
@@ -318,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.10.0 → polyglot_sql-0.12.0}/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.10.0" }
+polyglot-sql-ast-derive = { path = "../polyglot-sql-ast-derive", version = "0.12.0" }
 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.10.0", optional = true, default-features = false }
+polyglot-sql-function-catalogs = { path = "../polyglot-sql-function-catalogs", version = "0.12.0", optional = true, default-features = false }
 
 [dev-dependencies]
 pretty_assertions = "1.4"

{polyglot_sql-0.10.0 → polyglot_sql-0.12.0}/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.10.0", default-features = false }
+polyglot-sql = { version = "0.12.0", default-features = false }
 ```
 
 ```toml
 polyglot-sql = {
-    version = "0.8.0",
+    version = "0.12.0",
     default-features = false,
     features = ["dialect-clickhouse"],
 }
@@ -44,14 +44,14 @@ Examples:
 ```toml
 # Parse and generate SQL for one dialect.
 polyglot-sql = {
-    version = "0.8.0",
+    version = "0.12.0",
     default-features = false,
     features = ["generate", "dialect-clickhouse"],
 }
 
 # Cross-dialect transpilation.
 polyglot-sql = {
-    version = "0.8.0",
+    version = "0.12.0",
     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.10.0 → polyglot_sql-0.12.0}/crates/polyglot-sql/benches/performance_hotspots.rs

@@ -81,6 +81,7 @@ fn many_numbers() -> String {
 
 fn disabled_guards() -> ComplexityGuardOptions {
     ComplexityGuardOptions {
+        max_parser_depth: None,
         max_input_bytes: None,
         max_tokens: None,
         max_ast_nodes: None,
@@ -209,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);