sqlscope-rs 0.1.0__tar.gz

sqlscope_rs-0.1.0/Cargo.lock

@@ -0,0 +1,397 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "ar_archive_writer"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73cd58deff2140a0a8eae87e417bd01db68a33e148aa93d1e8cd837e55e312b6"
+dependencies = [
+ "object",
+]
+
+[[package]]
+name = "cc"
+version = "1.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f74872d07caf508b30a21f6836e7d7016a2eaf7d9ff4f48deaa58cd8a0407630"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "object"
+version = "0.39.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e5a6c098c7a3b6547378093f5cc30bc54fd361ce711e05293a5cc589562739b"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "polyglot-sql"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8bd560fb7445798460480716cac803d740bef433c4043c0cac47a7a0c3f4732f"
+dependencies = [
+ "polyglot-sql-ast-derive",
+ "serde",
+ "serde_json",
+ "stacker",
+ "thiserror",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "polyglot-sql-ast-derive"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a43b746b86d14a9888e8e535efae4e8315a484caa94e9a0d78bdefe58f22e44"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "psm"
+version = "0.1.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4dcd034599e63b970727f70d79e02d62390a4a84f7c6b827c27c46d5ac3fa622"
+dependencies = [
+ "ar_archive_writer",
+ "cc",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "sqlscope"
+version = "0.1.0"
+dependencies = [
+ "polyglot-sql",
+ "regex",
+ "stacker",
+]
+
+[[package]]
+name = "sqlscope-python"
+version = "0.1.0"
+dependencies = [
+ "pyo3",
+ "pyo3-build-config",
+ "sqlscope",
+]
+
+[[package]]
+name = "sqlscope-wasm"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "sqlscope",
+]
+
+[[package]]
+name = "stacker"
+version = "0.1.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "707f49d46706bacf8a2b00d51dace3f9de527c13eec3778f570c411f89e69967"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "libc",
+ "psm",
+ "windows-sys",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

sqlscope_rs-0.1.0/Cargo.toml

@@ -0,0 +1,29 @@
+[workspace]
+resolver = "2"
+members = ["crates/sqlscope", "python"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.88"
+license = "MIT"
+repository = "https://github.com/dcalsky/sqlscope"
+homepage = "https://github.com/dcalsky/sqlscope"
+authors = ["dcalsky <dcalsky@gmail.com>"]
+
+[workspace.dependencies]
+polyglot-sql = { version = "=0.13.1", default-features = false }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+regex = "1"
+
+[profile.release]
+lto = true
+codegen-units = 1
+
+# Size-optimized build of the WebAssembly module embedded in the Go SDK.
+[profile.wasm]
+inherits = "release"
+opt-level = "s"
+strip = true
+panic = "abort"

sqlscope_rs-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: sqlscope-rs
+Version: 0.1.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Summary: Scope-aware SQL analysis and rewriting: row filters, CTE injection, table rewrites, column lineage.
+Keywords: sql,lineage,row-level-security,parser
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/dcalsky/sqlscope
+
+# sqlscope (Python)
+
+Scope-aware SQL analysis and rewriting, backed by the Rust
+[sqlscope](https://github.com/dcalsky/sqlscope) crate.
+
+```bash
+pip install sqlscope-rs
+```
+
+```python
+import sqlscope
+
+sqlscope.apply_row_filter("SELECT id FROM orders", "tenant_id = 7", dialect="postgres")
+# 'SELECT id FROM (SELECT * FROM orders WHERE tenant_id = 7) AS orders'
+
+sqlscope.column_origins(
+    "SELECT o.id, p.amount FROM orders o JOIN payments p ON o.id = p.order_id WHERE o.status = 'PAID'"
+)
+# {'orders': ['id'], 'payments': ['amount']}
+```
+
+See the [project README](https://github.com/dcalsky/sqlscope#readme) for the
+full API.
+

sqlscope_rs-0.1.0/README.md

@@ -0,0 +1,23 @@
+# sqlscope (Python)
+
+Scope-aware SQL analysis and rewriting, backed by the Rust
+[sqlscope](https://github.com/dcalsky/sqlscope) crate.
+
+```bash
+pip install sqlscope-rs
+```
+
+```python
+import sqlscope
+
+sqlscope.apply_row_filter("SELECT id FROM orders", "tenant_id = 7", dialect="postgres")
+# 'SELECT id FROM (SELECT * FROM orders WHERE tenant_id = 7) AS orders'
+
+sqlscope.column_origins(
+    "SELECT o.id, p.amount FROM orders o JOIN payments p ON o.id = p.order_id WHERE o.status = 'PAID'"
+)
+# {'orders': ['id'], 'payments': ['amount']}
+```
+
+See the [project README](https://github.com/dcalsky/sqlscope#readme) for the
+full API.

sqlscope_rs-0.1.0/crates/sqlscope/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "sqlscope"
+description = "Scope-aware SQL analysis and rewriting: row filters, CTE injection, table rewrites, column lineage and references."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+authors.workspace = true
+keywords = ["sql", "lineage", "parser", "row-level-security", "polyglot"]
+categories = ["parser-implementations", "database"]
+readme = "README.md"
+
+[features]
+default = ["stacker"]
+# Grow the native stack on deep parser recursion. Disable for wasm targets.
+stacker = ["polyglot-sql/stacker", "dep:stacker"]
+
+[dependencies]
+polyglot-sql = { workspace = true, features = ["all-dialects", "generate", "ast-tools", "semantic"] }
+regex.workspace = true
+stacker = { version = "0.1", optional = true }

sqlscope_rs-0.1.0/crates/sqlscope/README.md

@@ -0,0 +1,189 @@
+# sqlscope
+
+Scope-aware SQL analysis and rewriting for Rust, Python and Go, built on the
+[polyglot](https://github.com/tobilg/polyglot) SQL engine (30+ dialects).
+
+| Operation | Purpose |
+| --- | --- |
+| `apply_row_filter` | Filter every in-scope table by a predicate (row-level security). |
+| `inject_ctes` | Prepend CTE definitions to a query's root `WITH`. |
+| `rewrite_tables` | Replace table references with derived tables. |
+| `column_origins` | Source columns whose values reach the result (column lineage). |
+| `output_columns` | Names of the columns a statement outputs. |
+| `referenced_columns` | Columns referenced anywhere (filters included), per table. |
+| `column_usages` | Column references together with the clause they appear in. |
+
+Everything works on the parsed AST, never by splicing SQL text, and resolves
+names with SQL scoping rules: CTE shadowing, correlated subqueries, set
+operations, derived tables, `USING`, `PIVOT`, `UNNEST`, lateral views.
+
+## Install
+
+| Language | Package |
+| --- | --- |
+| Rust | `cargo add sqlscope` |
+| Python | `pip install sqlscope-rs` (imported as `sqlscope`; wheels for Linux, macOS, Windows; Python ≥ 3.9) |
+| Go | `go get github.com/dcalsky/sqlscope/go` (pure Go, no cgo) |
+
+## Usage
+
+### Rust
+
+```rust
+use sqlscope::{apply_row_filter, column_origins, Dialect, Options};
+
+let sql = apply_row_filter(
+    "SELECT id FROM orders",
+    "tenant_id = 7",
+    &Options::new().dialect(Dialect::POSTGRES),
+)?;
+assert_eq!(sql, "SELECT id FROM (SELECT * FROM orders WHERE tenant_id = 7) AS orders");
+
+let origins = column_origins(
+    "SELECT o.id, p.amount FROM orders o JOIN payments p ON o.id = p.order_id WHERE o.status = 'PAID'",
+    &Options::new(),
+)?;
+assert_eq!(origins["orders"], ["id"]);
+assert_eq!(origins["payments"], ["amount"]);
+```
+
+### Python
+
+```python
+import sqlscope
+
+sqlscope.apply_row_filter("SELECT id FROM orders", "tenant_id = 7", dialect="postgres")
+# 'SELECT id FROM (SELECT * FROM orders WHERE tenant_id = 7) AS orders'
+
+sqlscope.column_usages("SELECT id FROM orders WHERE status = 'PAID'")
+# [ColumnUsage(table='orders', column='id', clause=<Clause.SELECT>),
+#  ColumnUsage(table='orders', column='status', clause=<Clause.WHERE>)]
+```
+
+### Go
+
+```go
+import "github.com/dcalsky/sqlscope/go"
+
+sql, err := sqlscope.ApplyRowFilter(
+    "SELECT id FROM orders", "tenant_id = 7",
+    sqlscope.WithDialect("postgres"),
+    sqlscope.WithTableNames("orders"),
+)
+
+cols, err := sqlscope.ColumnOrigins(sql,
+    sqlscope.WithSchema(map[string][]string{"orders": {"id", "tenant_id"}}))
+```
+
+The Go SDK runs the Rust engine compiled to WebAssembly with
+[wazero](https://wazero.io). The engine is compiled once per process on first
+use (about a second); call `sqlscope.Init()` at startup to do it eagerly.
+
+## Options
+
+Every operation takes the same options. Settings an operation does not read
+are ignored.
+
+| Rust (`Options::`) | Python keyword | Go | Read by |
+| --- | --- | --- | --- |
+| `dialect` | `dialect` | `WithDialect` | all (default `trino`) |
+| `schema` | `schema` | `WithSchema` | `column_origins`, `output_columns`, `referenced_columns`, `column_usages` |
+| `table_names` | `table_names` | `WithTableNames` | `apply_row_filter` |
+| `table_patterns` | `table_patterns` | `WithTableRegexp` | `apply_row_filter` |
+| `default_db` | `default_db` | `WithDefaultDB` | `apply_row_filter` |
+| `strip_catalogs` | `strip_catalogs` | `WithStripCatalogs` | `rewrite_tables` |
+
+`schema` maps table names (bare, `schema.table` or `catalog.schema.table`) to
+their ordered columns. It expands `*` and attributes unqualified columns. A
+table listed with no columns has zero columns; an unlisted table is unknown.
+
+## Operations
+
+### `apply_row_filter(sql, predicate)`
+
+```text
+SELECT * FROM a  ->  SELECT * FROM (SELECT * FROM a WHERE <predicate>) AS a
+```
+
+Wraps every in-scope physical table of a `SELECT` or set operation in a
+filtered derived table, which keeps the filter correct across outer joins,
+CTEs, subqueries and set operations. CTE references, table functions and
+`DUAL` are never wrapped. The predicate is parsed as one boolean expression
+(extra clauses, statements or unbalanced parentheses are rejected); bind or
+escape its values before calling. Qualified column references
+(`schema.table.col`) are rebound onto the derived-table alias, and
+same-named tables get distinct aliases (`s1_t`, `s2_t`).
+
+### `inject_ctes(sql, ctes)`
+
+Adds `name AS (query)` definitions before the query's existing CTEs, in order,
+so each may use earlier ones. Names that collide with another definition or
+an existing root CTE are rejected.
+
+### `rewrite_tables(sql, rewrites)`
+
+Replaces references to a `schema.table` match key with
+`(SELECT * FROM target)` or a `UNION DISTINCT` over several tables, keeping
+the reference's alias and rebinding qualified columns.
+
+### `column_origins(sql)`
+
+The source columns whose **values** reach the result, keyed by root table.
+Filter-only positions (`WHERE`, `JOIN ... ON`, `GROUP BY`, `HAVING`, top-level
+`ORDER BY`) and the right side of `INTERSECT`/`EXCEPT` are excluded; window
+`PARTITION BY`/`ORDER BY` count. Accepts `CREATE VIEW`, `CREATE TABLE AS`,
+`INSERT ... SELECT` and friends, and the assigned values of `UPDATE`/`MERGE`.
+
+### `output_columns(sql)`
+
+Output column names in order. Unaliased expressions are `_col{i}`; `*`
+expands from the schema or stays `"*"`. Explicit column lists on views,
+`CREATE TABLE` and `INSERT` win. `CREATE TABLE (... LIKE t ...)` needs `t`'s
+schema. Returns none for statements without columns.
+
+### `referenced_columns(sql)` / `column_usages(sql)`
+
+Every column a statement reads, anywhere, including `DELETE`/`UPDATE`/`MERGE`
+— a superset of `column_origins`. `column_usages` adds the clause
+(`SELECT`, `WHERE`, `JOIN_ON`, `GROUP_BY`, `ORDER_BY`, `UPDATE_SET_VALUE`,
+`MERGE_ON`, ...). Projection aliases and ordinals (`ORDER BY 1`) resolve to
+their source columns. Resolution fails open: a reference that cannot be
+attributed precisely is attributed to every candidate table, never dropped.
+
+## Errors
+
+| Kind | Rust `ErrorKind` | Python | Go |
+| --- | --- | --- | --- |
+| Invalid option or argument | `InvalidArgument` | `InvalidArgumentError` | `ErrInvalidArgument` |
+| SQL does not parse | `Parse` | `ParseError` | `ErrParse` |
+| Unsupported statement or input over a safety limit | `Unsupported` | `UnsupportedError` | `ErrUnsupported` |
+| Bug (invalid output) | `Internal` | `InternalError` | `ErrInternal` |
+
+Input is limited to 1 MiB and 256 levels of parser nesting on every platform.
+Rewrites regenerate SQL from the AST (normalized formatting, comments
+removed, optimizer hints kept) and verify that the output parses before
+returning it; when nothing needs rewriting, the input is returned unchanged.
+
+## Development
+
+```bash
+cargo test --workspace --exclude sqlscope-python     # Rust
+cd python && uv venv && uv pip install maturin pytest \
+  && .venv/bin/maturin develop && .venv/bin/pytest    # Python
+scripts/build-wasm.sh && (cd go && go test ./...)     # Go
+```
+
+`scripts/build-wasm.sh` needs the `wasm32-wasip1` Rust target and regenerates
+`go/internal/wasm/sqlscope.wasm.gz`, which is committed so `go get` works. CI
+rebuilds it on every run, tests the Go SDK against the fresh build, and on
+`main` commits it back when it changed.
+
+To release, bump `version` in the root `Cargo.toml`, wait for CI on `main`
+to finish (it may commit an updated engine), then tag that commit:
+`git tag vX.Y.Z && git push origin vX.Y.Z`. The release workflow runs CI,
+publishes the wheels to PyPI, tags the Go module as `go/vX.Y.Z` and attaches
+the wheels, sdist and WebAssembly engine to a GitHub release.
+
+## License
+
+MIT