execsql2 2.16.12__tar.gz → 2.16.13__tar.gz

{execsql2-2.16.12 → execsql2-2.16.13}/CHANGELOG.md

@@ -13,12 +13,45 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.16.13] - 2026-05-01
+
+### Added
+
+- `execsql-format`: The `--indent` flag now controls SQL indentation in addition to metacommand indentation. Previously only metacommand depth was affected; now sqlglot's `pad` and `indent` parameters follow the same value (default 4).
+- `execsql-format`: New `--leading-comma` flag places commas at the start of lines instead of the end (e.g., `  , col2` instead of `col1,`).
+
+### Fixed
+
+- `execsql-format`: Fixed SQL corruption when formatting scripts with comments interleaved within multi-line SQL statements (e.g., `SELECT` with comment lines between columns, `CASE` with comments before `WHEN` clauses). Previously, the formatter split statements at comment boundaries and sent each fragment to sqlglot independently, which produced broken output (commas became semicolons, CASE expressions were split apart, content was silently dropped). The formatter now uses a marker-based round-trip: comments are replaced with inline markers before formatting so sqlglot sees the complete statement, then markers are restored to their original `--` comment style and position in the output. Comments that sqlglot's AST drops (e.g., inside CASE expressions) are detected and re-inserted at the best matching position using token-based heuristics.
+- `execsql-format`: Fixed `/* */` block comments containing `-- !x!` metacommand markers being incorrectly processed as real metacommands. This caused the block comment to be broken apart, with `*/` becoming `* /` and commented-out code being mangled. The formatter now tracks block comment boundaries and skips metacommand processing inside them.
+- `execsql-format`: Fixed blank lines within multi-line SQL statements (e.g., between column groups in a large `SELECT`) incorrectly splitting the statement into separate formatting blocks, causing each fragment to be formatted independently and producing invalid SQL.
+- `execsql-format`: Added safety checks to the sqlglot formatting pass — if sqlglot produces more statements than the input contained or drops significant content, the formatter now falls back to the original text instead of emitting corrupted SQL.
+
+______________________________________________________________________
+
 ## [2.16.12] - 2026-05-01
 
+### Changed
+
+- Lowered coverage threshold from 90% to 89% — SCRIPT introspection code is tested via subprocess integration tests which don't contribute to in-process coverage, and Windows CI skips TTY/POSIX tests that contribute ~1% on other platforms.
+
+### Added
+
+- Unit tests for `_parse_param_defs`, `_format_script_signature`, `_format_script_source`, and `SHOW SCRIPTS`/`SHOW SCRIPT` handlers.
+- Parser coverage tests for default parameters and docstring extraction.
+
 ______________________________________________________________________
 
 ## [2.16.11] - 2026-05-01
 
+### Fixed
+
+- Multi-line `/* */` block comment docstrings in `BEGIN SCRIPT` blocks now capture all lines correctly. Previously, the doc collection guard ran on block comment continuation lines, classified them as "non-comment", and stopped doc collection before the block comment handler could process them.
+
+### Added
+
+- 12 parser tests covering default parameters and docstring extraction (single-line, multi-line, block comments, empty separators, metacommand termination, required-after-optional validation).
+
 ______________________________________________________________________
 
 ## [2.16.10] - 2026-05-01

{execsql2-2.16.12 → execsql2-2.16.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.16.12
+Version: 2.16.13
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql

{execsql2-2.16.12 → execsql2-2.16.13}/docs/about/divergence.md

@@ -93,9 +93,9 @@ New options in `execsql.conf`:
 
 ### Tools
 
-| Tool             | Description                                                                                                                                                                                    |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `execsql-format` | Standalone CLI for normalizing metacommand indentation and uppercasing SQL keywords. Supports `--check` and `--in-place` modes. Also available as a [pre-commit hook](../guides/formatter.md). |
+| Tool             | Description                                                                                                                                                                                                                                                                                                 |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `execsql-format` | Standalone CLI for normalizing metacommand indentation and uppercasing SQL keywords. Supports `--check`, `--in-place`, `--indent N` (controls both metacommand and SQL indentation), and `--leading-comma` (commas at start of lines) modes. Also available as a [pre-commit hook](../guides/formatter.md). |
 
 ### GUI
 

{execsql2-2.16.12 → execsql2-2.16.13}/docs/guides/formatter.md

@@ -24,13 +24,14 @@ By default, formatted output is written to stdout. Use `--in-place` to overwrite
 
 ### Options { #options }
 
-| Option             | Default  | Description                                                                                         |
-| ------------------ | -------- | --------------------------------------------------------------------------------------------------- |
-| `FILE_OR_DIR`      | required | One or more files or directories to format. Directories are searched recursively for `*.sql` files. |
-| `--check`          | off      | Exit with code 1 if any file would be reformatted. Does not write any changes. Useful in CI.        |
-| `-i`, `--in-place` | off      | Modify files in place instead of writing to stdout.                                                 |
-| `--no-sql`         | off      | Skip SQL reformatting via sqlglot. Only normalizes metacommand indentation and keyword casing.      |
-| `--indent N`       | `4`      | Number of spaces per indent level.                                                                  |
+| Option             | Default  | Description                                                                                                    |
+| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------- |
+| `FILE_OR_DIR`      | required | One or more files or directories to format. Directories are searched recursively for `*.sql` files.            |
+| `--check`          | off      | Exit with code 1 if any file would be reformatted. Does not write any changes. Useful in CI.                   |
+| `-i`, `--in-place` | off      | Modify files in place instead of writing to stdout.                                                            |
+| `--no-sql`         | off      | Skip SQL reformatting via sqlglot. Only normalizes metacommand indentation and keyword casing.                 |
+| `--indent N`       | `4`      | Spaces per indent level. Controls both metacommand block depth and SQL indentation (columns, subqueries, etc). |
+| `--leading-comma`  | off      | Place commas at the start of lines instead of the end (e.g. `  , col2` instead of `col1,`).                    |
 
 ## What Gets Formatted { #what-gets-formatted }
 
@@ -64,11 +65,28 @@ Metacommands that open a block (`IF`, `LOOP`, `BEGIN SCRIPT`, `BEGIN BATCH`, `BE
 
 ### SQL block formatting { #sql-formatting }
 
-SQL statements between metacommands are re-indented to match the current block depth and reformatted using [sqlglot](https://sqlglot.com/) in PostgreSQL dialect with pretty-printing enabled. Comment-only lines (single-line `--` and block `/* */` comments) are passed through without being sent to sqlglot.
+SQL statements between metacommands are re-indented to match the current block depth and reformatted using [sqlglot](https://sqlglot.com/) in PostgreSQL dialect with pretty-printing enabled.
 
-execsql substitution variables (`!!varname!!`, `!{varname}!`) are replaced with valid SQL identifiers before formatting, then restored afterward, so the formatter does not corrupt them.
+The `--indent` flag controls SQL indentation in addition to metacommand depth. For example, `--indent 4` (the default) produces 4-space indented column lists, subqueries, and CASE branches. `--indent 2` gives a more compact style.
 
-If sqlglot cannot parse a SQL statement, the original text is preserved unchanged.
+#### Comment handling
+
+Comments interleaved within SQL statements (e.g. `--` comments between SELECT columns, or inside CASE expressions) are preserved through formatting using a marker-based round-trip:
+
+1. Each comment line is replaced with a unique inline marker attached to the next SQL line.
+1. sqlglot formats the complete statement (no fragmentation).
+1. Markers are restored to their original `--` comment style and position.
+1. Comments that sqlglot's AST drops (e.g. inside CASE WHEN) are detected and re-inserted at the best matching position.
+
+Block comments (`/* */`) that contain `-- !x!` metacommand markers (e.g. commented-out code blocks) are recognized and passed through without metacommand processing.
+
+#### Variable preservation
+
+execsql substitution variables (`!!varname!!`, `!{varname}!`) are replaced with valid SQL identifiers before formatting, then restored afterward, so the formatter does not corrupt them — including in schema-qualified names (`!!staging!!.!!table!!`), CASE expressions, JOIN conditions, and string concatenation.
+
+#### Fallback behavior
+
+If sqlglot cannot parse a SQL statement, or if safety checks detect that formatting would corrupt the SQL (e.g. statement count changes, significant content loss), the original text is preserved unchanged.
 
 Use `--no-sql` to skip SQL reformatting entirely and only normalize metacommands.
 
@@ -112,6 +130,22 @@ Exit code is `0` if all files are already formatted, `1` if any file would chang
 execsql-format --indent 2 --in-place myscript.sql
 ```
 
+### Use leading commas
+
+```bash
+execsql-format --leading-comma --in-place myscript.sql
+```
+
+This places commas at the start of each line instead of the end:
+
+```sql
+SELECT
+    a
+    , b
+    , c
+FROM t;
+```
+
 ### Skip SQL reformatting
 
 Format only metacommand indentation and casing, leaving SQL statements untouched:
@@ -143,13 +177,14 @@ select id,name,created_at from users where active = true order by name;
 -- !x! IF(EQUAL(!!schema!!, "public"))
     -- !x! WRITE "Checking public schema..."
     SELECT
-      id,
-      name,
-      created_at
+        id,
+        name,
+        created_at
     FROM users
     WHERE
-      active = TRUE
-    ORDER BY name;
+        active = TRUE
+    ORDER BY
+        name;
 -- !x! ENDIF
 ```
 
@@ -180,6 +215,10 @@ The hook runs on `*.sql` files. Pass any CLI options via `args`:
 # Custom indent width
 - id: execsql-format
   args: [--in-place, --indent, "2"]
+
+# Leading commas
+- id: execsql-format
+  args: [--in-place, --leading-comma]
 ```
 
 ## Exit Codes { #exit-codes }

{execsql2-2.16.12 → execsql2-2.16.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.16.12"
+version = "2.16.13"
 description = "Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -165,7 +165,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.16.12"
+current_version = "2.16.13"
 commit = true
 tag = true
 tag_name = "v{new_version}"