feat: convert PIVOT without an alias column list

Cargo.toml

@@ -13,6 +13,7 @@ members = [
     "crates/sqlquack",
     "crates/sqlquack-polyglot-check",
     "crates/sqlquack-syntax-coverage",
+    "crates/sqlquack-syntax-postgres",
     "crates/sqlquack-python",
 ]
 exclude = ["fuzz"]
@@ -62,6 +63,7 @@ sqlquack-semantics = { path = "crates/sqlquack-semantics" }
 sqlquack-snowflake = { path = "crates/sqlquack-snowflake" }
 sqlquack-syntax = { path = "crates/sqlquack-syntax" }
 sqlquack-syntax-derive = { path = "crates/sqlquack-syntax-derive" }
+sqlquack-syntax-postgres = { path = "crates/sqlquack-syntax-postgres" }
 stacker = "0.1"
 syn = { version = "2", features = ["full"] }
 tempfile = "3"

cases/relational/pivot_unaliased.toml

@@ -0,0 +1,60 @@
+# PIVOT without an alias column list: the names Snowflake gives the key columns, as dbt pivot
+# models leave them.
+category = "relational"
+construct = "node:pivot"
+session_profile = "utc-v1"
+
+[[case]]
+id = "pivot_star_without_alias_list"
+description = "SELECT * over SUM(total) FOR channel IN ('web', 'store') with no alias list. Catches: key columns named web or WEB instead of the quoted text, a missing or NULL key, keys outside the list dropped, and the grouping column kept."
+columns = [{ name = "order_id", type = "NUMBER(38,0)" }, { name = "channel", type = "VARCHAR" }, { name = "total", type = "NUMBER(12,2)" }]
+rows = [
+  ["1", "'web'", "10.50"],
+  ["1", "'web'", "2.25"],
+  ["1", "'store'", "4.00"],
+  ["2", "'store'", "NULL"],
+  ["2", "'phone'", "9.99"],
+  ["3", "NULL", "1.00"],
+  ["3", "'WEB'", "3.00"],
+]
+query = "SELECT * FROM (SELECT order_id, channel, total FROM input) PIVOT(SUM(total) FOR channel IN ('web', 'store')) ORDER BY order_id"
+order = "ordered"
+tags = ["null", "duplicates", "missing-key", "case-sensitive-key"]
+
+[[case]]
+id = "pivot_quoted_key_reference"
+description = "The pivoted key columns read back by their quoted names, \"'web'\" and \"'store'\", through a table alias without a column list. Catches: the names not matching the quoted key text."
+columns = [{ name = "order_id", type = "NUMBER(38,0)" }, { name = "channel", type = "VARCHAR" }, { name = "total", type = "NUMBER(12,2)" }]
+rows = [
+  ["1", "'web'", "10.50"],
+  ["1", "'store'", "4.00"],
+  ["2", "'web'", "1.00"],
+]
+query = "SELECT p.order_id, p.\"'web'\" AS web_total, p.\"'store'\" AS store_total FROM (SELECT order_id, channel, total FROM input) PIVOT(SUM(total) FOR channel IN ('web', 'store')) AS p ORDER BY p.order_id"
+order = "ordered"
+tags = ["null", "missing-key"]
+
+[[case]]
+id = "pivot_mixed_case_keys_without_alias_list"
+description = "Keys with upper case, a space and an underscore, under MAX over BOOLEAN and no alias list. Catches: key names upper-cased, spaces changed, or the quotes dropped."
+columns = [{ name = "customer_id", type = "VARCHAR" }, { name = "consent", type = "VARCHAR" }, { name = "granted", type = "BOOLEAN" }]
+rows = [
+  ["'c-1'", "'Email Opt'", "TRUE"],
+  ["'c-1'", "'SMS_OPT'", "FALSE"],
+  ["'c-2'", "'Email Opt'", "NULL"],
+  ["'c-2'", "'other'", "TRUE"],
+]
+query = "SELECT * FROM (SELECT customer_id, consent, granted FROM input) PIVOT(MAX(granted) FOR consent IN ('Email Opt', 'SMS_OPT')) ORDER BY customer_id"
+order = "ordered"
+tags = ["null", "missing-key", "case-sensitive-key"]
+
+[[case]]
+id = "pivot_without_alias_list_over_no_rows"
+description = "A PIVOT without an alias list over no rows. Catches: a row of NULLs instead of no rows, and the column names and types still described."
+columns = [{ name = "order_id", type = "NUMBER(38,0)" }, { name = "channel", type = "VARCHAR" }, { name = "total", type = "NUMBER(12,2)" }]
+rows = [
+  ["1", "'web'", "10.50"],
+]
+query = "SELECT * FROM (SELECT order_id, channel, total FROM input WHERE total < 0) PIVOT(SUM(total) FOR channel IN ('web', 'store'))"
+order = "bag"
+tags = ["empty-input"]

cases/semi-structured/table_flatten.toml

@@ -0,0 +1,33 @@
+# FLATTEN written as TABLE(FLATTEN(...)) after a comma, with a positional input, as dbt models
+# write it: the same rows as LATERAL FLATTEN(input => ...).
+category = "semi-structured"
+construct = "fn:FLATTEN"
+session_profile = "utc-v1"
+
+[[case]]
+id = "table_flatten_positional_array"
+description = "TABLE(FLATTEN(t.tags)) over an ARRAY column with a positional input: one row per element. Catches: the input not correlated to its row, empty arrays or NULL giving rows, or elements out of order."
+columns = [{ name = "ticket_id", type = "NUMBER(38,0)" }, { name = "tags", type = "ARRAY" }]
+rows = [
+  ["1", "ARRAY_CONSTRUCT('billing', 'urgent')"],
+  ["2", "ARRAY_CONSTRUCT()"],
+  ["3", "NULL"],
+  ["4", "ARRAY_CONSTRUCT('refund')"],
+]
+query = "SELECT t.ticket_id, f.index, f.value::STRING AS tag FROM input t, TABLE(FLATTEN(t.tags)) f ORDER BY t.ticket_id, f.index"
+order = "ordered"
+tags = ["null", "array-index"]
+
+[[case]]
+id = "table_flatten_named_variant_path"
+description = "TABLE(FLATTEN(input => v:items)) over a VARIANT path, with KEY, PATH and VALUE read back. Catches: the named input ignored, objects read as arrays, or JSON null and missing paths giving rows."
+columns = [{ name = "k", type = "NUMBER(2,0)" }, { name = "v", type = "VARIANT" }]
+rows = [
+  ["1", "PARSE_JSON('{\"items\":[{\"sku\":\"A-10\"},{\"sku\":\"B-20\"}]}')"],
+  ["2", "PARSE_JSON('{\"items\":{\"b\":1,\"a\":2}}')"],
+  ["3", "PARSE_JSON('{\"items\":null}')"],
+  ["4", "PARSE_JSON('{}')"],
+]
+query = "SELECT i.k, f.index, f.key, f.path, f.value::VARCHAR AS value FROM input i, TABLE(FLATTEN(input => i.v:items)) f ORDER BY i.k, f.index, f.key"
+order = "ordered"
+tags = ["null", "json-null", "missing-key", "nested", "array-index", "case-sensitive-key"]

coverage/syntax-postgres/README.md

@@ -0,0 +1,172 @@
+# PostgreSQL syntax catalogue
+
+The denominator of SQLQuack's PostgreSQL syntax coverage: every documented PostgreSQL 18.6 syntax
+form, one record per form, with a stable id `pg.<family>.<slug>[.<variant>]`. The layout and the
+record formats are those of `coverage/syntax` (see `docs/syntax-coverage.md`); this file records
+what differs.
+
+## Source
+
+The pinned source is the release tarball `postgresql-18.6.tar.bz2` (sha256 in `indexes.toml`),
+not the rendered website. Its DocBook SGML is what postgresql.org/docs/18 is built from, so a
+source id `doc.<docbook-id>` names the page `https://www.postgresql.org/docs/18/<docbook-id>.html`.
+`indexes.toml` also binds the files the page list is read from (`reference.sgml`,
+`ref/allfiles.sgml`, `filelist.sgml`, `postgres.sgml`) and the grammar the omission audit reads
+(`src/backend/parser/gram.y`, `src/include/parser/kwlist.h`).
+
+A page is either
+
+- a SQL command reference page (a `refentry` of the SQL Commands part, 183 pages), or
+- a `sect1` (or a chapter's introduction) of the SQL-language chapters: syntax, ddl, dml,
+  queries, datatype, json, array, rowtypes, rangetypes, func, typeconv, indices, textsearch, mvcc,
+  perform and parallel.
+
+`page_sha256` is the sha256 of that SGML text; `syntax_sha256` of its synopsis blocks and
+signatures.
+
+## Regenerating
+
+```sh
+python -m scripts.fetch_syntax_docs_pg CACHE      # private cache, never committed
+python -m scripts.build_syntax_catalogue_pg --cache CACHE --out coverage/syntax-postgres
+```
+
+The build writes nothing while any input is unresolved: a synopsis block with no disposition, a
+disposition naming no block, a restatement of an uncatalogued form, or a hand form whose page
+changed. PostgreSQL 19 is an in-place rebuild against its tarball; ids follow the same keeping
+rules as the Snowflake catalogue (`scripts/syntax_catalogue/_helpers/forms.py`, reused by import).
+
+## Omission audit (`audit.toml`)
+
+```sh
+python -m scripts.audit_syntax_catalogue_pg --cache CACHE
+```
+
+An independent check against the server's own grammar, `gram.y` and `kwlist.h` of the pinned
+release. It reads every rule of gram.y and spells each alternative of every rule reachable from
+`toplevel_stmt`, `stmt` and the expression rules (720 of 733 rules, with no depth bound) as keyword
+sequences,
+expanding nonterminals that are keyword sets (`DROP object_type_any_name` checks DROP TABLE,
+DROP SEQUENCE and so on). A sequence is covered when some catalogued form, with its page's
+definitions inlined, contains its keywords in order; for a statement the form's leading required
+keywords must also appear in the sequence, so DROP FOREIGN TABLE does not cover DROP TABLE.
+Every kwlist.h keyword that a production uses must appear in some grammar.
+
+`audit.toml` binds the sha256 of gram.y and kwlist.h and gives a reviewed reason for every
+production that no form covers (`[[production]]`, keyed by rule and production text) and every
+keyword that no grammar names (`[[keyword]]`). The audit fails on an unreviewed gap, a review
+naming no current gap, or a changed grammar file. The reasons are of three kinds: syntax gram.y
+accepts that the 18.6 documentation does not document (the spelling ANALYSE, GLOBAL and LOCAL
+before TEMPORARY outside CREATE TABLE, `BETWEEN ASYMMETRIC`, `TREAT`, `NCHAR`); productions that
+only raise an error (CREATE ASSERTION, `ALTER TYPE ... DROP VALUE`, UNENCRYPTED PASSWORD); and
+documented values of a placeholder (`NFC`, `OUT`, `SETOF`). Single-keyword alternatives below a
+statement are checked by the keyword rule only.
+
+`[[unwalked]]` lists each of the 13 rules the walk does not reach with its reason: the start
+symbol and top-level wrappers, the PL/pgSQL-only parse modes and the five keyword category lists.
+The audit fails on an unwalked rule that is not listed. `limits` states what the method does not
+check, such as identifiers, punctuation and adjacency of keywords.
+
+## Form rules
+
+1. **Command pages.** The `<refsynopsisdiv>` synopsis is split into statements at each unindented
+   line that starts with the command's first word (SELECT also `WITH` and `TABLE`). Each
+   statement is a form. `<phrase>where X is:</phrase>` (and `and X is`, `X in ... is`) starts a
+   sub-grammar definition, `[[definition]]` `doc.<page>::<X>`; `can be one of` / `is one of`
+   lists its alternatives one per line.
+2. **Actions.** A statement whose grammar takes `<action> [, ... ]`, where the page lists
+   `action` as alternatives (ALTER TABLE and six other ALTER pages), becomes one form per action, with the
+   action substituted into the statement.
+3. **Other synopsis blocks** (on command pages outside the Synopsis, and in the chapters) each
+   have a reviewed disposition in `hand.toml` `[[block]]`, keyed by page and block sha256:
+   `form` (each production a form; on a command page, older syntax still accepted, named
+   `<page>.<label>`), `calls` (signatures grouped as functions), `definition`, `restated` (the
+   page joins the listed forms' `also_sources`), or `fragment` / `hand` with a reason.
+4. **Functions and operators.** Every `func_signature` of func.sgml is read. Plain call
+   signatures of one function name on one page form one `call` form, `pg.functions.<page>.<name>`;
+   a signature with its own keyword grammar (`substring(... FROM ... FOR ...)`, `WITHIN GROUP`,
+   `ORDER BY` inside the call, the SQL/JSON constructors, keyword functions written without
+   parentheses) is a `special` form per name and keyword skeleton. Operator signatures form one
+   `special` form per operator per page in `expressions`, `pg.expressions.<page>.op-<chars>` or
+   the keywords of a keyword operator. Table sections that catalogue no form are listed in
+   `hand.toml` `[[signatures]]` with the reason.
+5. **Data types.** Each row of the Data Types, Special Character Types, Object Identifier Types
+   and Pseudo-Types tables is a form in `expressions`; aliases are alternatives.
+6. **Hand forms** (`hand.toml` `[[form]]`): lexical syntax and expressions written in prose or
+   examples (identifiers, string and bit-string constants, comments, constructors, named
+   notation, array types, interval fields, range constructors, ILIKE), the comparison operators
+   whose table uses the generic `datatype`, SET SCHEMA and SET NAMES, the SQL function bodies
+   (`RETURN`, `BEGIN ATOMIC`) of CREATE FUNCTION and CREATE PROCEDURE, and the deprecated CREATE
+   ROLE clauses.
+
+Families: `query`, `dml`, `ddl`, `transaction_session`, `security_admin`, `utility`, `functions`,
+`expressions`. There is no `classes` or `scripting` family: PL/pgSQL bodies are string constants
+to the server grammar, and DO and CREATE FUNCTION are catalogued as statements.
+
+## Obligations and cases
+
+```sh
+python -m scripts.build_syntax_obligations_pg [--root ROOT] [--focus focus/postgres.toml]
+```
+
+Obligations are derived for every catalogued form by the shared builder
+(`scripts/syntax_obligations`, reused by import). `scripts/syntax_obligations_pg` adds what is
+Postgres's own: the submission context of each family (statements as written, expressions inside
+`SELECT ( … )` so a trailing keyword is never read as a bare column label, data types inside
+`CAST ( NULL AS … )`), placeholder fills by synopsis name, class rules for operator and function
+placeholders that name a value of a type, and a grammar read that writes a form's bare words in
+upper case (Postgres synopses spell keywords and type names in lower case; every placeholder is
+in angle brackets), with a few list spellings rewritten so the renderer can copy them
+(`GRAMMAR_REWRITES` in its constants: ONLY and `*` as alternatives, as gram.y relation_expr takes
+them; LIMIT and FETCH as one clause; DISTINCT with a required select list; a with_query as
+name AS ( query ); a list's second item written out; a window definition optional inside
+OVER). The grammar is tokenized with Postgres's operators: a run of operator characters
+(`&&`, `<->`, `?-|`, …) is one token, and `\[ \]` in a reading is a literal bracket (array
+constructors, subscripts and array types) rather than an optional part. `limits.toml` holds the
+readings, suppressions and hand-written limits, each with its reason, in the format of
+`coverage/syntax/limits.toml`. Most expressions suppressions are one gram.y fact: every
+operator token is also a prefix operator (`qual_Op a_expr`), so an operator form with its left
+operand left out is valid syntax; with its right operand left out it stays a negative.
+Function parameters written `<name type>` are expressions (gram.y func_arg_expr), whatever
+their name suggests; the catalogue cuts a signature at its return value, so a set-returning
+function's output columns are not read as call syntax.
+
+An obligation keeps its id across rebuilds. `retired.toml` lists every id that has left the
+root, grouped by the commit that retired it, with the reason; the builder reserves those numbers,
+so they are never issued again, and fails if a retired id reappears in `obligations/` or if a
+rebuild drops an id that `retired.toml` does not list, so a changed meaning always takes a new id. Its
+`[[reused]]` rows record the two ids that were issued again with a new meaning before retirement
+was recorded; both forms were approved with the new meaning, so those ids stay.
+
+Cases are written for every catalogued form of the families in `CASED_FAMILIES`, which now
+lists all eight; `focus/postgres.toml` set only the order in which they were taken up.
+`pending.toml` lists cases held out of the receipts because the referee cannot yet run or judge
+them as written, each with the referee change it waits on; a pending case is not verified. Each case has the referee's shape: the session
+`{"TimeZone": "UTC", "statement_timeout": "30s"}`, capture `execute_in_rolled_back_transaction`,
+or `execute_autocommit_in_throwaway_database` for statements Postgres refuses inside a
+transaction block (the referee's `engine.toml` `autocommit` list), no setup, and one statement
+without a terminating semicolon. `elisions/` is not written: the Snowflake elision rules do not
+apply, and the few Postgres `...` fills are style entries.
+
+Receipts (`receipts/*.jsonl`, format `sqlquack-syntax-receipt/2`) are recorded by the Postgres
+referee (`engines/postgres`) against the pinned 18.6 image; the raw records and run audits stay
+private. `runs.toml` records how each run was isolated: the earlier runs shared one long-lived
+container, and the ddl, transaction_session, utility and security_admin runs each had a fresh
+container of the pinned image, removed afterwards, with its start and end state and a repeat
+run that matched. The case build reads them as the shared builder does: an accepted case takes its
+receipt's later stage, and an observed case its receipt's outcome.
+
+`baseline.json` is the claims snapshot (`syntax-coverage snapshot --root
+coverage/syntax-postgres`), bound to catalogue commit 1a48c3c5 and to the Postgres parser's tree
+on `wip/pg-integration` 5348cab6 (tree d7df6560), where `local_parser = "postgres"` runs that
+parser's strict entry point in the checker's isolated worker: any parser error rejects the case.
+It claims 19,346 of 22,726 obligations and the 1,384 forms the reviewers' batches through 22 and 24
+to 28 approved (batch 27 is held until its parser tree lands); a statement the parser keeps as an opaque command is never verified. It holds the 822
+cases Postgres rejects that the parser accepts as opaque, so `syntax-coverage diff
+coverage/syntax-postgres/baseline.json --root coverage/syntax-postgres` fails on any regression
+from here.
+
+`reviews/auditor-<family>.toml` holds the independent reviewers' approvals (D235, D238). Each
+`[[review]]` is copied verbatim from the reviewer's record on `wip/syntax-omission-audit`
+(`coverage/syntax/audits/pg-review-*.toml`) and holds while each form's fingerprint and definition
+hash are unchanged.

coverage/syntax-postgres/aliases.toml

@@ -0,0 +1,12 @@
+# Renamed, split and merged form ids. An old id stays in the catalogue with status
+# absent_from_source and is never reused; `to` lists the forms that now carry its grammar.
+
+[[alias]]
+from = "pg.transaction_session.set-role.none-reset-role"
+to = ["pg.transaction_session.set-role.set-role-none", "pg.transaction_session.set-role.reset-role"]
+reason = "the synopsis reader joined the documented line RESET ROLE onto SET [ SESSION | LOCAL ] ROLE NONE, giving one form for two statements that is not valid SQL; the sql-set-role synopsis lists them as separate lines, now one form each (19aa1f28)"
+
+[[alias]]
+from = "pg.transaction_session.set-session-authorization.default-reset-session-authorization"
+to = ["pg.transaction_session.set-session-authorization.set-session-authorization-default", "pg.transaction_session.set-session-authorization.reset-session-authorization"]
+reason = "the synopsis reader joined the documented line RESET SESSION AUTHORIZATION onto SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT, giving one form for two statements that is not valid SQL; the sql-set-session-authorization synopsis lists them as separate lines, now one form each (19aa1f28)"