Milestones 1 and 2: scaffolding, codegen, oracle, and corpus goldens

[kyleconroy]

Implements the first two milestones of PLAN.md, pinned to libpg_query 17-6.2.2 (PostgreSQL 17.7, patched). Both acceptance gates verified.

Milestone 1 — scaffolding + codegen

• Module github.com/sqlc-dev/oliphant with the single runtime dependency (google.golang.org/protobuf); MIT + PostgreSQL + libpg_query license notices; CI builds and tests with CGO_ENABLED=0 and checks generated files are current.
• Vendored at the pin: srcdata/ (libpg_query metadata JSON + pg_query.proto) and internal/reference/ (gram.y, scan.l, parser.c from the PostgreSQL 17.7 tarball with libpg_query patches 01/03/04/09 applied, plus kwlist.h) — docs-only, with provenance READMEs.
• cmd/generate emits ast/pg_query.pb.go (273 messages, 71 enums), aliases.go (621 root-package type aliases plus every enum const/var, so pg_query.SelectStmt etc. resolve exactly as in pg_query_go), and internal/lexer/keywords.go (491 keywords, four reserved-ness categories + bare-label attribute).
• oliphant.go mirrors pg_query_go's API function-for-function; makefuncs.go ported verbatim; parser subpackage carries the Error type and byte-level entry points. Everything fails loudly with a not-implemented error (pinned by TestNotImplementedErrors) until its milestone lands.
• Gate met: pg_query_go v6.2.2's parse_test.go expected-tree literals compile unchanged (parse_test.go, import path swap only, plus a skip guard until the parser exists).

Milestone 2 — corpus + oracle

• oracle/ is a separate go module — the only cgo anywhere — wrapping pg_query_go v6.2.2 behind a JSONL stdin/stdout protocol. The main module never links it; root go build ./... compiles no C.
• cmd/regenerate derives parser/testdata from the oracle: the PostgreSQL regression suite (224 files; psql metacommands and COPY-FROM-stdin payloads filtered), both deparse corpora (15 + 150 files), the libpg_query inline test tables (inputs transcribed mechanically — expectations only ever come from the oracle), and pg_query_go's fingerprint corpus including the 1.1 MB stress insert.
• Result: 1,525 .test files / 217,229 cases (~80 MB) across eight suites — parse, scan, normalize, normalize_utility, fingerprint, deparse, split_scanner, split_parser — every case starting as todo.
• internal/testfile implements the family's ==/-- corpus format with one addition: content lines colliding with the markers are |-escaped (SQL comment banners of exactly -- are everywhere in the regress files); round-trip is unit-tested.
• Harness: go test ./parser skips todo cases and treats any non-todo failure as a hard regression; -check-parse harvests newly passing cases out of the metadata.json sidecars. cmd/next-test picks the next todo in milestone order (lexer first).
• Regeneration preserves passing status (identical name+input+expectation stays passing), so a pin advance puts exactly the diff back on the todo list.
• Gate met: two full regeneration runs produced byte-identical trees; a weekly regenerate workflow re-verifies reproducibility against a freshly built oracle.

Deliberately deferred

• sqlc endtoend corpus tier (needs per-directory engine classification in the sqlc repo) — suggest importing alongside milestone 4.
• plpgsql_regress/ (milestone 11) and summary goldens (milestone 10).

Verification

• CGO_ENABLED=0 go build ./... && go test ./... green; go vet and gofmt clean.
• Oracle spot-checked against known vectors (SELECT 1 → fingerprint 50fde20626009aba; error goldens carry message/cursorpos/filename/funcname).
• diff -rq over two independent cmd/regenerate runs: no differences.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VbG2Ht5x88uCDisDHUVCcz

---

Generated by Claude Code