sql2sqlx 0.1.0__tar.gz → 0.1.1__tar.gz

{sql2sqlx-0.1.0 → sql2sqlx-0.1.1}/MANIFEST.in

@@ -1,6 +1,5 @@
 include LICENSE
 include README.md
-include CHANGELOG.md
 include CONTRIBUTING.md
 include CITATION.cff
 recursive-include src/sql2sqlx py.typed

{sql2sqlx-0.1.0 → sql2sqlx-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql2sqlx
-Version: 0.1.0
+Version: 0.1.1
 Summary: Convert BigQuery SQL into Dataform SQLX with conservative, dependency-aware migration tooling.
 Author-email: Soumyadip Sarkar <soumyadip@soumyadipsarkar.com>
 License-Expression: Apache-2.0
@@ -8,7 +8,6 @@ Project-URL: Homepage, https://github.com/neuralsorcerer/sql2sqlx
 Project-URL: Documentation, https://neuralsorcerer.github.io/sql2sqlx/
 Project-URL: Source, https://github.com/neuralsorcerer/sql2sqlx
 Project-URL: Issues, https://github.com/neuralsorcerer/sql2sqlx/issues
-Project-URL: Changelog, https://github.com/neuralsorcerer/sql2sqlx/blob/main/CHANGELOG.md
 Keywords: analytics-engineering,bigquery,bigquery-sql,code-generation,data-engineering,dataform,dataform-sqlx,ddl,dependency-graph,dml,elt,etl,gcp,google-cloud,googlesql,migration,sql,sql-converter,sql-migration,sql-parser,sqlx,warehouse-migration
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -56,13 +55,13 @@ BigQuery SQL -> Dataform SQLX migration tooling.
 
 <div align="center">
 
-[![Current Release](https://img.shields.io/github/release/neuralsorcerer/sql2sqlx.svg)](https://github.com/neuralsorcerer/sql2sqlx/releases)
 [![PyPI](https://img.shields.io/pypi/v/sql2sqlx.svg?logo=pypi&logoColor=white)](https://pypi.org/project/sql2sqlx/)
 [![Python 3.10+](https://img.shields.io/badge/Python-3.10+-fcbc2c.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![Test Ubuntu](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_ubuntu.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_ubuntu.yml?query=branch%3Amain)
 [![Test Windows](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_windows.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_windows.yml?query=branch%3Amain)
 [![Test MacOS](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_macos.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_macos.yml?query=branch%3Amain)
 [![Lints](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/lints.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/lints.yml?query=branch%3Amain)
+[![CodeQL](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/codeql.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/codeql.yml?query=branch%3Amain)
 [![Dataform Compile](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/dataform_compile.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/dataform_compile.yml?query=branch%3Amain)
 [![Build](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/build.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/build.yml?query=branch%3Amain)
 [![Documentation](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/docs.yml/badge.svg)](https://neuralsorcerer.github.io/sql2sqlx/)

{sql2sqlx-0.1.0 → sql2sqlx-0.1.1}/README.md

@@ -9,13 +9,13 @@ BigQuery SQL -> Dataform SQLX migration tooling.
 
 <div align="center">
 
-[![Current Release](https://img.shields.io/github/release/neuralsorcerer/sql2sqlx.svg)](https://github.com/neuralsorcerer/sql2sqlx/releases)
 [![PyPI](https://img.shields.io/pypi/v/sql2sqlx.svg?logo=pypi&logoColor=white)](https://pypi.org/project/sql2sqlx/)
 [![Python 3.10+](https://img.shields.io/badge/Python-3.10+-fcbc2c.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![Test Ubuntu](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_ubuntu.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_ubuntu.yml?query=branch%3Amain)
 [![Test Windows](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_windows.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_windows.yml?query=branch%3Amain)
 [![Test MacOS](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_macos.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/test_macos.yml?query=branch%3Amain)
 [![Lints](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/lints.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/lints.yml?query=branch%3Amain)
+[![CodeQL](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/codeql.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/codeql.yml?query=branch%3Amain)
 [![Dataform Compile](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/dataform_compile.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/dataform_compile.yml?query=branch%3Amain)
 [![Build](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/build.yml/badge.svg)](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/build.yml?query=branch%3Amain)
 [![Documentation](https://github.com/neuralsorcerer/sql2sqlx/actions/workflows/docs.yml/badge.svg)](https://neuralsorcerer.github.io/sql2sqlx/)

sql2sqlx-0.1.1/docs/api.md

@@ -0,0 +1,129 @@
+# API reference
+
+Everything in this section is generated from the package's docstrings. The
+narrative below orients you before the autodoc entries.
+
+The public surface is small and stable. Everything importable from the
+top-level `sql2sqlx` package (listed in its `__all__`) is what semantic
+versioning covers.
+
+## Choosing an entry point
+
+Three functions convert; two helpers support them.
+
+:::{list-table}
+:header-rows: 1
+:widths: 26 30 44
+
+* - Function
+  - Input
+  - Writes to disk?
+* - `convert_string(sql, options=None, name="input.sql")`
+  - a SQL string (one or many statements)
+  - No - returns a result you can inspect or `write_result`.
+* - `convert_file(path, options=None)`
+  - one `.sql` file
+  - No - returns a result.
+* - `convert_directory(input_dir, output_dir=None, options=None)`
+  - a directory tree (scanned by `include_glob`)
+  - **Only if** `output_dir` is given.
+:::
+
+`parse_source(...)` exposes just Phase 1 (lex + split + classify) for one
+source, returning a `ParsedFile`; `write_result(result, output_dir)` writes a
+`ConversionResult` to disk (and refuses paths that would escape the
+destination). All three converters run the same three-phase pipeline described
+in [architecture](architecture.md); `convert_directory` additionally
+parallelizes parsing across a process pool.
+
+```{eval-rst}
+.. autofunction:: sql2sqlx.convert_string
+.. autofunction:: sql2sqlx.convert_file
+.. autofunction:: sql2sqlx.convert_directory
+.. autofunction:: sql2sqlx.write_result
+.. autofunction:: sql2sqlx.parse_source
+```
+
+## Options and results
+
+`ConversionOptions` holds every knob; its defaults preserve semantics (see the
+[CLI reference](cli.md) for the flag-to-field mapping). Its `__post_init__`
+**validates and normalizes** on construction: the string enum values
+(`"incremental"`, `"mirror"`, ...) are accepted as well as the enum members, so
+options are easy to build from JSON or config files, and invalid values raise
+`ValueError` immediately rather than silently mis-selecting a strategy.
+
+A conversion returns a `ConversionResult` with two attributes: `files` (the
+generated `SqlxFile` objects, in deterministic sorted-path order) and `report`
+(a [`ConversionReport`](report.md)). All of these are plain, picklable
+dataclasses.
+
+```{eval-rst}
+.. autoclass:: sql2sqlx.ConversionOptions
+   :members:
+
+.. autoclass:: sql2sqlx.InsertStrategy
+   :members:
+.. autoclass:: sql2sqlx.MergeStrategy
+   :members:
+.. autoclass:: sql2sqlx.PlainCreateStrategy
+   :members:
+.. autoclass:: sql2sqlx.IfNotExistsStrategy
+   :members:
+.. autoclass:: sql2sqlx.Layout
+   :members:
+
+.. autoclass:: sql2sqlx.ConversionResult
+   :members:
+.. autoclass:: sql2sqlx.ConversionReport
+   :members:
+.. autoclass:: sql2sqlx.ReportWarning
+   :members:
+.. autoclass:: sql2sqlx.SqlxFile
+   :members:
+.. autoclass:: sql2sqlx.ActionType
+   :members:
+.. autoclass:: sql2sqlx.TableName
+   :members:
+```
+
+## Errors
+
+Every exception raised deliberately by the library derives from
+`Sql2SqlxError`, so a single `except Sql2SqlxError` catches them all.
+Location-aware errors (`LexError`, `SplitError`) carry 1-based `line` and
+`column` attributes. Note that *unsupported-but-valid* SQL never raises - it
+falls back to an `operations` action and a warning; the exceptions are for
+genuinely broken input (unreadable files, lexer failures). During directory
+conversion, a per-file failure is captured in `report.failures` rather than
+aborting the run.
+
+```{eval-rst}
+.. automodule:: sql2sqlx.errors
+   :members:
+```
+
+## Internals
+
+The internal modules are stable enough to build on, but the public surface
+above is what semantic versioning covers.
+
+```{eval-rst}
+.. automodule:: sql2sqlx.lexer
+   :members: tokenize, comment_spans, unquote_identifier, Token, LineIndex
+
+.. automodule:: sql2sqlx.splitter
+   :members:
+
+.. automodule:: sql2sqlx.parser
+   :members: classify_statement
+
+.. automodule:: sql2sqlx.refs
+   :members: scan_ref_sites, parse_table_path, PathMatch
+
+.. automodule:: sql2sqlx.emitter
+   :members:
+
+.. automodule:: sql2sqlx.cli
+   :members: main, build_arg_parser
+```

sql2sqlx-0.1.1/docs/architecture.md

@@ -0,0 +1,170 @@
+# Architecture
+
+sql2sqlx is a three-phase pipeline built on one invariant:
+
+> **Untouched SQL is preserved character-for-character after decoding.** Output
+> bodies are produced by applying *span edits* to slices of the original text -
+> tokens are never re-serialized, so formatting, casing and inline comments
+> survive exactly.
+
+```text
+.sql files
+  |
+  v
+Phase 1: parse each file, in parallel when possible
+  - lexer: tokens and comment spans
+  - splitter: top-level statements
+  - classifier: action drafts and metadata
+  - reference scanner: candidate table read sites
+  |
+  v
+Phase 2: link corpus metadata
+  - creators and duplicate demotion
+  - writer chains and ordering dependencies
+  - hasOutput election
+  - ref resolution and declaration synthesis
+  - action names and output paths
+  |
+  v
+Phase 3: emit SQLX
+  - config blocks
+  - source-span edits
+  - provenance and original comments
+  - .sqlx files
+```
+
+The phases map onto the module layout: `lexer`, `splitter`, `parser` and
+`refs` do Phase 1; `converter._Linker` does Phase 2; `emitter` does Phase 3.
+The shared, picklable data model lives in `model` so parsed results can cross
+process boundaries.
+
+## Phase 1 - lexing, splitting, classifying
+
+This phase is **per file** and has no cross-file dependencies, which is what
+makes it parallelizable.
+
+### Lexer (`sql2sqlx.lexer`)
+
+A single compiled regex alternation, executed by CPython's C regex engine,
+implements the GoogleSQL lexical specification. Every alternative is written to
+match in strictly linear time (no ambiguous nested quantifiers, hence no
+catastrophic backtracking), giving high throughput while remaining exactly
+character-accurate. It recognizes:
+
+- line comments (`--` and `#`) and non-nested block comments (`/* ... */`,
+  ending at the first `*/`, exactly as GoogleSQL defines them);
+- all string/bytes/raw literal forms, including triple-quoted strings and
+  every valid `r`/`b` prefix combination and case, with GoogleSQL's exact
+  backslash-escape rules (a raw literal can never end in an odd number of
+  backslashes, and so on);
+- backtick-quoted identifiers with escapes and embedded dots;
+- numeric literals, named/positional query parameters and system variables,
+  and every GoogleSQL operator and punctuation token.
+
+Tokens carry `(kind, text, start, end)` with character offsets into the
+original text - the anchor for span-exact emission later. Unterminated strings,
+backtick identifiers and block comments raise a `LexError` with an exact
+1-based line and column. Comment spans are captured in the **same pass** (via
+an output list), so no file is ever lexed twice.
+
+### Splitter (`sql2sqlx.splitter`)
+
+Splits the token stream into top-level statements on `;`, but only at
+parenthesis depth 0 **and** with an empty *block-frame stack*. Frames model
+BigQuery scripting constructs - `BEGIN ... END`, `IF ... END IF`, loops, and
+`CASE` - and openers are recognized only in statement position. A bounded
+lookahead distinguishes the scripting `IF cond THEN` from the `IF(a, b, c)`
+function, and `BEGIN [TRANSACTION];` is treated as a statement, not a block
+opener. The splitter is deliberately lenient: a mismatched `END` is tolerated
+rather than fatal, so odd-but-valid scripts still split sensibly.
+
+### Classifier (`sql2sqlx.parser`)
+
+Maps each statement to an `ActionDraft`: its action type, target table,
+already-known `config` entries, the metadata extracted from
+`PARTITION BY`/`CLUSTER BY`/`OPTIONS`, and any classification warnings. This is
+where the opt-in analyses live:
+
+- the select-list aliasing analysis for `INSERT -> incremental` (proving each
+  output name is exactly determinable, or refusing);
+- the MERGE shape proof (all six obligations) plus its target-schema
+  precondition warning;
+- detection of the forms that must fall back (`LIKE`/`CLONE`/`COPY`, column-list
+  CTAS, temp/external/snapshot tables, guarded creates, `INSERT ... VALUES`).
+
+### Reference scanner (`sql2sqlx.refs`)
+
+A context-tracked scan for physical table paths in read positions - after
+`FROM`, `JOIN`, from-list commas and `MERGE ... USING` - carrying per-query
+CTE and range-variable scopes. It models recursive versus ordered CTE
+visibility, correlated scalar subqueries versus non-lateral `FROM` subqueries,
+set-operation branches, implicit aliases and `UNNEST` aliases; `EXTRACT(x FROM
+col)` stays inert, and dashed-project adjacency and target skip-spans (e.g. the
+target of `DELETE FROM x`) are handled without ever re-serializing SQL. The
+output is a list of candidate `RefSite`s (character spans plus the decoded,
+still-unresolved `TableName`).
+
+### Whole-file scripts
+
+Files that use transactions, temporary objects, variables, procedural control
+flow, or dynamic side effects cannot be safely split into independent Dataform
+actions without changing control-flow or scope semantics, so they collapse
+into a **single whole-file `operations` draft**. A conservative nested scan
+still harvests persistent reference sites and write targets from inside the
+script, so dependency wiring works, while temporary names are kept from
+leaking into the corpus.
+
+## Phase 2 - the linker
+
+`_Linker` runs once, single-process, over the lightweight drafts that Phase 1
+produced (parallel workers ship back picklable `ParsedFile`/`ActionDraft`
+objects). In order:
+
+1. one **creator** per resolved target `(project, dataset, table)`; a second
+   producer of the same target is demoted to a verbatim `operations` action
+   (`DUPLICATE_TARGET`), because Dataform allows exactly one owner per target;
+2. **writer chains** per table in corpus order (sorted relative path, then
+   statement position): every writer depends on its predecessor, and a
+   same-file writer also waits for intervening readers, so
+   `DROP x; CREATE x; UPDATE x` keeps its order;
+3. **`hasOutput` election**: an ownerless `operations` action that actually
+   creates its configured output (and only such an action - never mutating
+   DML) is elected as a producer, gaining `hasOutput: true` and a `${self()}`
+   rewrite of its own target path;
+4. **reference resolution** against the `--default-project/--default-dataset`
+   values, rewriting resolved read sites to `${ref(...)}` and adding reader
+   dependencies on each table's latest preceding writer;
+5. **future-owner protection** that leaves an earlier read literal
+   (`FUTURE_CREATOR`) rather than reversing corpus order, plus **cycle
+   detection** that omits an unsafe edge (`DEPENDENCY_CYCLE`) rather than
+   emitting an uncompilable graph;
+6. unique action naming and collision-free output paths - deterministic, so
+   two runs produce identical bytes.
+
+See the [dependency model](dependencies.md) for the full semantics of each
+edge and the warnings they raise.
+
+## Phase 3 - emission
+
+`sql2sqlx.emitter` renders each linked draft to a `.sqlx` file: it builds the
+canonical `config { ... }` block (fixed key order), applies the accumulated
+span edits to a slice of the original source text, emits literal `${` and
+SQLX-unsafe comments through constant placeholders (while inserted
+`${ref()}`/`${self()}` stay active), strips one trailing semicolon, and
+attaches the provenance comment plus the statement's own leading comments. The
+result is UTF-8 with `\n` newlines. See [core concepts](concepts.md) for the
+output anatomy.
+
+## Performance model
+
+Lexing dominates runtime, and it runs at C speed via the master regex pattern.
+Directory conversion parallelizes Phase 1 across a `ProcessPoolExecutor` sized
+by `--jobs` (`0` = one worker per CPU); Phase 2 and Phase 3 are a fast
+single-process metadata pass. Because parsing is embarrassingly parallel and
+linking is cheap, throughput scales with core count on large corpora.
+
+Measured on this package's benchmark (`examples/06_benchmark.py`, 120 files /
+1,056,600 lines / 31.7 MB, single core): **43.8 s ~ 24,100 lines/s**, with
+~96k actions emitted and ~96k references rewritten. Memory is proportional to
+corpus size, because the original text of each file is retained for span-exact
+emission.

sql2sqlx-0.1.1/docs/cli.md

@@ -0,0 +1,211 @@
+# CLI reference
+
+```text
+sql2sqlx INPUT [-o DIR] [options]
+```
+
+The CLI is a thin veneer over [`convert_file`](api.md) and
+[`convert_directory`](api.md). It can also be run as a module:
+`python -m sql2sqlx ...`.
+
+## Input and output modes
+
+`INPUT` is either a single `.sql` **file** or a **directory** of `.sql` files.
+What happens next depends on the input kind and whether `--output` is given:
+
+:::{list-table}
+:header-rows: 1
+:widths: 22 20 58
+
+* - Input
+  - `--output`
+  - Behavior
+* - file
+  - omitted
+  - The generated SQLX is printed to **stdout**; the run summary goes to
+    **stderr**, so `sql2sqlx model.sql > out.sqlx` is clean.
+* - file
+  - given
+  - The generated file(s) are written beneath the output directory.
+* - directory
+  - given
+  - The converted tree is written beneath the output directory.
+* - directory
+  - omitted
+  - **Error**, unless `--dry-run` is passed (a directory has no meaningful
+    stdout form).
+:::
+
+When a single file produces **multiple** actions and is printed to stdout, the
+files are separated by a header line so the stream stays parseable:
+
+```text
+-- ===== active.sqlx =====
+config { ... }
+...
+
+-- ===== customers.sqlx =====
+config { ... }
+...
+```
+
+## Options
+
+:::{list-table}
+:header-rows: 1
+:widths: 34 14 52
+
+* - Flag
+  - Default
+  - Meaning
+* - `-o, --output DIR`
+  - -
+  - Where to write `.sqlx` files (typically your Dataform `definitions/`).
+* - `--report FILE`
+  - -
+  - Write the full JSON [conversion report](report.md) to `FILE`.
+* - `--default-project ID`
+  - -
+  - Project assumed for unqualified table paths (reference resolution only).
+* - `--default-dataset ID`
+  - -
+  - Dataset assumed for unqualified paths; also resolves single-part
+    references to qualified producers.
+* - `--default-location LOCATION`
+  - `US`
+  - Location written into a scaffolded `workflow_settings.yaml`.
+* - `--layout {mirror,flat}`
+  - `mirror`
+  - Mirror the input directory tree, or flatten all output into the root.
+* - `--insert-strategy {incremental,operations}`
+  - `operations`
+  - How `INSERT ... SELECT` converts.
+* - `--merge-strategy {operations,incremental-when-safe}`
+  - `operations`
+  - How `MERGE` converts.
+* - `--plain-create {operations,declaration}`
+  - `operations`
+  - How `CREATE TABLE` **without** `AS SELECT` converts.
+* - `--if-not-exists {table,operations}`
+  - `operations`
+  - How guarded `CREATE TABLE/VIEW IF NOT EXISTS ... AS` converts.
+* - `--declare-external`
+  - off
+  - Emit `declaration` actions under `sources/` for referenced-but-not-produced
+    tables, and `ref()` them too.
+* - `--no-protected`
+  - off
+  - Do **not** mark converted incrementals `protected: true`.
+* - `--no-annotate`
+  - off
+  - Omit the `-- source: file:line` provenance comments.
+* - `--tags A,B`
+  - -
+  - Comma-separated Dataform tags added to every generated action.
+* - `--include GLOB`
+  - `*.sql`
+  - Filename glob for directory scans (must stay within the input directory).
+* - `--encoding ENC`
+  - `utf-8`
+  - Encoding used to read input files (must be a text codec).
+* - `-j, --jobs N`
+  - `0` (auto)
+  - Parser worker processes; `0` = one per CPU, `1` = no multiprocessing.
+* - `--dry-run`
+  - off
+  - Convert and report, but write no `.sqlx` files.
+* - `--overwrite`
+  - off
+  - Allow writing into an output directory that already contains `.sqlx` files.
+* - `--init-project`
+  - off
+  - Also scaffold a `workflow_settings.yaml`.
+* - `-q, --quiet`
+  - -
+  - Suppress the summary.
+* - `-v, --verbose`
+  - -
+  - Also list every warning and generated file.
+* - `--version`
+  - -
+  - Print the version and exit.
+:::
+
+### Strategy flags in depth
+
+The four strategy flags each default to the **semantics-preserving** option
+and let you opt into more idiomatic Dataform structure where you accept the
+trade-off. Their full rules, proof obligations and the warnings they emit are
+documented in [conversion rules](conversion_rules.md):
+
+- `--insert-strategy incremental` produces `type: "incremental"` from
+  `INSERT ... SELECT`, marks it `protected: true` (unless `--no-protected`),
+  and reports `INSERT_INCREMENTAL`.
+- `--merge-strategy incremental-when-safe` converts only MERGEs whose shape is
+  *provably* equivalent to an incremental upsert; everything else stays
+  `operations` with a `MERGE_FALLBACK` reason.
+- `--plain-create declaration` turns bodiless `CREATE TABLE (schema)` DDL into
+  a `declaration` (drops the DDL; use for externally managed tables).
+- `--if-not-exists table` converts guarded `... IF NOT EXISTS ... AS`
+  statements to typed actions and reports the lost create-if-absent guard.
+
+### The `--init-project` scaffold
+
+`--init-project` writes a Dataform-core 3.x `workflow_settings.yaml`. If the
+output directory is named `definitions`, the file is placed in its **parent**
+(the project root); otherwise it is placed inside the output directory. It is
+**never** silently overwritten - pass `--overwrite` to replace an existing one.
+
+```yaml
+defaultProject: "my-gcp-project"        # from --default-project, else "your-gcp-project"
+defaultLocation: "US"                   # from --default-location
+defaultDataset: "analytics"             # from --default-dataset, else "dataform"
+defaultAssertionDataset: "dataform_assertions"
+dataformCoreVersion: "3.0.61"
+```
+
+### The overwrite guard
+
+When writing to a directory, if the output path already contains any `.sqlx`
+files and `--overwrite` is not set, `sql2sqlx` stops with exit code `2` rather
+than risk clobbering hand-written actions. Because conversion is deterministic,
+re-running with `--overwrite` in CI produces the same tree and a clean diff.
+
+## Exit codes
+
+:::{list-table}
+:header-rows: 1
+:widths: 12 88
+
+* - Code
+  - Meaning
+* - `0`
+  - Converted successfully (there may still be warnings).
+* - `1`
+  - One or more input files failed to parse (see `FAILED` lines and the
+    report's `failures`).
+* - `2`
+  - Usage error: bad arguments, a directory input without `--output`/`--dry-run`,
+    the output-directory guard, or an output-write error.
+:::
+
+## Examples
+
+```bash
+# Inspect a single file without writing anything
+sql2sqlx model.sql | less
+
+# Full migration with shape-checked MERGE conversion and source declarations
+sql2sqlx ./sql -o ./definitions \
+    --merge-strategy incremental-when-safe \
+    --declare-external --tags migrated --report report.json
+
+# CI-style dry run that only produces the report
+sql2sqlx ./sql --dry-run --report report.json -q
+
+# Regenerate an existing project deterministically, verbosely
+sql2sqlx ./sql -o ./definitions --overwrite -v
+
+# Convert only staging models, single-process
+sql2sqlx ./sql -o ./definitions --include "stg_*.sql" -j 1
+```