execsql2 2.16.8__tar.gz → 2.16.13__tar.gz

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

@@ -13,6 +13,67 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [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
+
+### Fixed
+
+- EXECUTE SCRIPT with a variable-substituted target name (e.g., `EXECUTE SCRIPT !!#script_name!!`) now works correctly. Previously, the parser's regex only accepted literal word characters as the script identifier, causing variable targets to fall through to the dispatch table and fail with "EXECUTE SCRIPT should be handled by the AST executor." The parser now recognizes `!!var!!` substitution patterns as valid script identifiers.
+
+______________________________________________________________________
+
+## [2.16.9] - 2026-05-01
+
+### Added
+
+- `SHOW SCRIPTS` metacommand lists all registered SCRIPT definitions with parameter signatures and source locations.
+- `SHOW SCRIPT <name>` metacommand shows detail for a single SCRIPT (parameters, source file and line range, docstring).
+- `.scripts` REPL command lists all registered scripts; `.scripts <name>` shows detail for one script.
+- Default parameter values for SCRIPT definitions: `BEGIN SCRIPT load(schema, table, batch=1000)`. Parameters with defaults can be omitted at call site; the default value is used automatically. Required parameters must precede optional parameters (like Python).
+- Automatic docstring extraction for SCRIPT blocks. Comments (`--` or `/* */`) immediately following `BEGIN SCRIPT` are captured as documentation. A blank line terminates the docstring. Docstrings are displayed by `SHOW SCRIPT`, `SHOW SCRIPTS`, and `.scripts` in the debug REPL.
+
+______________________________________________________________________
+
 ## [2.16.8] - 2026-04-30
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.16.8
+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.8 → execsql2-2.16.13}/docs/about/divergence.md

@@ -52,6 +52,21 @@ ______________________________________________________________________
 | `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                                                                                                                                                                                                                                                                    |
 | `PG_UPSERT`            | QA-checked, FK-dependency-ordered upserts from staging to base schema on PostgreSQL. Integrates [pg-upsert](https://pg-upsert.readthedocs.io/) as an optional dependency. Three modes: full pipeline, QA-only, and schema check. Supports `EXPORT_FAILURES`, `EXPORT_FORMAT`, `EXPORT_MAX_ROWS`, and `STRICT_COLUMNS` keywords. `STRICT_COLUMNS` forces all missing columns to be errors (requires `pg-upsert>=1.22.0`). |
 | `IMPORT … FROM JSON`   | Import a JSON file (array of objects or NDJSON) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                                                                                                                                                                                                                  |
+| `SHOW SCRIPTS`         | List all registered SCRIPT definitions with parameter signatures and source locations. Includes scripts from INCLUDEEd files.                                                                                                                                                                                                                                                                                            |
+| `SHOW SCRIPT <name>`   | Show detail for a single registered SCRIPT: name, parameters (with defaults), source file/line range, and docstring.                                                                                                                                                                                                                                                                                                     |
+
+### SCRIPT Enhancements
+
+| Feature            | Description                                                                                                                                                                                                    |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Default parameters | `BEGIN SCRIPT load(schema, table, batch=1000)` — parameters with defaults can be omitted at call site. Required parameters must precede optional parameters.                                                   |
+| Docstrings         | Comments (`--` or `/* */`) immediately following `BEGIN SCRIPT` are captured as documentation. A blank line terminates the docstring. Displayed by `SHOW SCRIPT`, `SHOW SCRIPTS`, and `.scripts` REPL command. |
+
+### Bug Fixes
+
+| Fix                             | Description                                                                                                                                               |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Variable EXECUTE SCRIPT targets | `EXECUTE SCRIPT !!#var!!` now works — the parser accepts substitution variable patterns as script identifiers, and the executor resolves them at runtime. |
 
 ### Conditional Tests
 
@@ -78,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
 
@@ -131,17 +146,19 @@ execsql2 adds a full interactive debugging system that has no equivalent in upst
 
 **REPL commands** (all dot-prefixed to avoid collisions with variable names and SQL):
 
-| Command                | Description                                                               |
-| ---------------------- | ------------------------------------------------------------------------- |
-| `.continue` / `.c`     | Resume normal script execution                                            |
-| `.abort` / `.q`        | Halt the script with exit status 1                                        |
-| `.vars` / `.v`         | List all user, system, local, and counter variables (grouped by type)     |
-| `.vars all` / `.v all` | Include environment variables (`&`) in the listing                        |
-| `.next` / `.n`         | Execute the next statement, then pause again (step mode)                  |
-| `.where` / `.w`        | Show the current script file, line number, and upcoming statement text    |
-| `.stack`               | Show the command-list stack (script name, cursor position, nesting depth) |
-| `.set VAR VAL` / `.s`  | Set or update a substitution variable; prints confirmation on success     |
-| `.help` / `.h`         | Show available commands                                                   |
+| Command                | Description                                                                 |
+| ---------------------- | --------------------------------------------------------------------------- |
+| `.continue` / `.c`     | Resume normal script execution                                              |
+| `.abort` / `.q`        | Halt the script with exit status 1                                          |
+| `.vars` / `.v`         | List all user, system, local, and counter variables (grouped by type)       |
+| `.vars all` / `.v all` | Include environment variables (`&`) in the listing                          |
+| `.next` / `.n`         | Execute the next statement, then pause again (step mode)                    |
+| `.where` / `.w`        | Show the current script file, line number, and upcoming statement text      |
+| `.stack`               | Show the command-list stack (script name, cursor position, nesting depth)   |
+| `.set VAR VAL` / `.s`  | Set or update a substitution variable; prints confirmation on success       |
+| `.scripts`             | List all registered SCRIPT definitions with parameters and source locations |
+| `.scripts NAME`        | Show detail for a specific SCRIPT (parameters, source file/line range)      |
+| `.help` / `.h`         | Show available commands                                                     |
 
 **Non-prefixed input** is interpreted as either a variable lookup or ad-hoc SQL:
 

{execsql2-2.16.8 → 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.8 → execsql2-2.16.13}/docs/reference/metacommands.md

@@ -141,6 +141,8 @@ All REPL commands are dot-prefixed to avoid ambiguity with variable names and SQ
 | `.vars all` | Include environment variables (`&`) in the listing |
 | `.next` or `.n` | Execute the next script statement, then pause again (step mode) |
 | `.stack` | Show the command-list stack: script name, cursor index, and nesting depth |
+| `.scripts` | List all registered SCRIPT definitions with parameters and source locations |
+| `.scripts NAME` | Show detail for a specific SCRIPT (parameters, source file/line range) |
 | `.help` | Show the list of available REPL commands |
 
 **Variable inspection and SQL (no dot prefix):**
@@ -219,6 +221,10 @@ BEGIN SCRIPT <script_name>
 BEGIN SCRIPT <script_name> WITH PARAMETERS (param1[, param2[,..]])
 ```
 
+```
+BEGIN SCRIPT <script_name>(param1, param2=default_value)
+```
+
 ```
 END SCRIPT [script_name]
 ```
@@ -232,6 +238,56 @@ If the WITH PARAMETERS clause is used, the parameter names specified must be ass
 
 The "WITH" and "PARAMETERS" keywords are both optional.
 
+### Default parameter values
+
+Parameters can have default values using `param=value` syntax. Parameters with defaults are optional at the call site — if omitted, the default value is used. Required parameters (no default) must precede optional parameters.
+
+```sql
+-- !x! BEGIN SCRIPT load_data(schema, table, batch_size=1000, dry_run=false)
+INSERT INTO !!#table!! SELECT * FROM staging LIMIT !!#batch_size!!;
+-- !x! END SCRIPT
+
+-- All of these are valid:
+-- !x! EXECUTE SCRIPT load_data(schema=public, table=users)
+-- !x! EXECUTE SCRIPT load_data(schema=public, table=users, batch_size=500)
+-- !x! EXECUTE SCRIPT load_data(schema=public, table=users, batch_size=500, dry_run=true)
+```
+
+A required parameter after an optional parameter is a parse error:
+
+```sql
+-- Parse error: required parameter 'table' after optional parameter 'batch'
+-- !x! BEGIN SCRIPT bad(schema, batch=1000, table)
+```
+
+### Docstrings
+
+Comments (`--` or `/* */`) immediately following the BEGIN SCRIPT line are captured as the script's docstring. A blank line terminates the docstring. Docstrings are displayed by [SHOW SCRIPT](#show_script), [SHOW SCRIPTS](#show_scripts), and the `.scripts` REPL command.
+
+```sql
+-- !x! BEGIN SCRIPT load_data(schema, table)
+-- Load data from staging into the target table.
+-- Parameters:
+--   schema - Target schema name
+--   table  - Target table name
+
+-- !x! SUB ~batch 1000
+INSERT INTO !!#table!! SELECT * FROM staging;
+-- !x! END SCRIPT
+```
+
+Block comments are also valid:
+
+```sql
+-- !x! BEGIN SCRIPT load_data(schema, table)
+/* Load data from staging into the target table. */
+
+INSERT INTO !!#table!! SELECT * FROM staging;
+-- !x! END SCRIPT
+```
+
+### Other notes
+
 If a script name is provided with the END SCRIPT metacommand, it must match the name used in the corresponding BEGIN SCRIPT metacommand. If it does not, *execsql* will halt with an error message.
 
 A BEGIN/END SCRIPT block can be used in ways similar to a separate script file that is included with the [INCLUDE](#include) metacommand. Both allow the same code to be executed repeatedly, either at different locations in the main script or recursively to perform looping.
@@ -2697,6 +2753,61 @@ Assigns the value of the specified numeric expression to the counter. The next t
 The numeric expression may consist of the simple algebraic operations of addition, subtraction, multiplication, and division. Parentheses may be used to control evaluation order. Numeric values used in the expression may be integers or floating-point numbers, but the result will be reduced to an integer before assignment to the counter variable.
 
 
+## SHOW SCRIPTS { #show_scripts }
+
+```
+SHOW SCRIPTS
+```
+
+Lists all registered SCRIPT definitions with their parameter signatures and source locations. This is useful for discovering what scripts are available at runtime, especially when scripts are loaded from INCLUDEEd files whose paths are determined dynamically.
+
+**Example output:**
+
+```
+Registered scripts (3):
+
+  load_data(schema, table, batch_size=1000)    pipeline.sql:15-42
+  cleanup()                                    init.sql:10-25
+  validate(schema, table)                      pipeline.sql:62-80
+```
+
+Default parameter values are shown in the signature. Use `SHOW SCRIPT <name>` for full detail including docstrings.
+
+If no scripts are registered, prints `No scripts registered.`
+
+## SHOW SCRIPT { #show_script }
+
+```
+SHOW SCRIPT <name>
+```
+
+Shows detail for a single registered SCRIPT definition, including its parameter list (with required/optional status and defaults), source file/line range, and docstring.
+
+**Example:**
+
+```sql
+-- !x! SHOW SCRIPT load_data
+```
+
+**Example output:**
+
+```
+Script: load_data(schema, table, batch_size=1000)
+Source: pipeline.sql:15-42
+Parameters:
+  schema      (required)
+  table       (required)
+  batch_size  (optional, default: 1000)
+
+Load data from staging into the target table.
+```
+
+If the script is not found, prints `No script named '<name>' is registered.`
+
+!!! tip
+    In the debug REPL, use `.scripts` to list all scripts or `.scripts <name>` to show detail for one script.
+
+
 ## SUB { #subcmd }
 
 ```

{execsql2-2.16.8 → execsql2-2.16.13}/extras/vscode-execsql/syntaxes/execsql.tmLanguage.json

@@ -93,7 +93,7 @@
     },
     "action-keywords": {
       "comment": "sub, write, execute script, export, etc.",
-      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|pg_upsert\\s+check|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|pg_upsert\\s+qa|sub_tempfile|write\\s+script|import_file|set\\s+counter|sub_decrypt|sub_encrypt|autocommit|breakpoint|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_upsert|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
+      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|pg_upsert\\s+check|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|pg_upsert\\s+qa|show\\s+scripts|sub_tempfile|write\\s+script|import_file|set\\s+counter|show\\s+script|sub_decrypt|sub_encrypt|autocommit|breakpoint|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_upsert|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
       "name": "keyword.other.execsql"
     },
     "config-event-keywords": {

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.16.8"
+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.8"
+current_version = "2.16.13"
 commit = true
 tag = true
 tag_name = "v{new_version}"
@@ -188,7 +188,7 @@ addopts = [
     "--cov=execsql",
     "--cov-branch",
     "--cov-report=xml",
-    "--cov-fail-under=90",
+    "--cov-fail-under=89",
     "--strict-markers",
     "--strict-config",
     "--color=yes",

{execsql2-2.16.8 → execsql2-2.16.13}/src/execsql/debug/repl.py

@@ -111,6 +111,8 @@ _HELP_COMMANDS = [
     (".where", ".w", "Show the current script location and upcoming statement"),
     (".stack", "", "Show the command-list stack (script name, line, depth)"),
     (".set VAR VAL", ".s", "Set or update a substitution variable"),
+    (".scripts", "", "List all registered SCRIPT definitions"),
+    (".scripts NAME", "", "Show detail for a specific SCRIPT"),
     (".help", ".h", "Show this help text"),
 ]
 
@@ -290,6 +292,12 @@ def _handle_dot_command(line: str) -> None:
             varname = parts[0]
             value = parts[1] if len(parts) > 1 else ""
             _set_var(varname, value)
+    elif cmd.startswith("scripts"):
+        rest = cmd[7:].strip()
+        if rest:
+            _print_script_detail(rest)
+        else:
+            _print_scripts()
     else:
         _write(f"  {_c(_RED, 'Unknown command:')} {line!r}. Type '.help' for available commands.\n")
 
@@ -507,3 +515,54 @@ def _set_var(varname: str, value: str) -> None:
     else:
         subvars.add_substitution(varname, value)
     _write(f"  {_c(_CYAN, varname)} {_c(_DIM, '=')} {value}\n")
+
+
+def _print_scripts() -> None:
+    """Print all registered SCRIPT definitions."""
+    from execsql.metacommands.debug import _format_script_signature, _format_script_source
+
+    scripts = _state.ast_scripts
+    if not scripts:
+        _write("  (no scripts registered)\n\n")
+        return
+    _write_rule(f" {_c(_BOLD + _YELLOW, 'Scripts')} {_c(_DIM, f'({len(scripts)})')} ")
+    sigs = {name: _format_script_signature(name, block.param_defs) for name, block in scripts.items()}
+    max_sig = max(len(s) for s in sigs.values())
+    for name, block in scripts.items():
+        sig = sigs[name]
+        src = _format_script_source(block.span)
+        _write(f"  {_c(_CYAN, sig):<{max_sig + len(_CYAN) + len(_RESET)}}  {_c(_DIM, src)}\n")
+    _write("\n")
+
+
+def _print_script_detail(name: str) -> None:
+    """Print detail for a single SCRIPT definition."""
+    from execsql.metacommands.debug import _format_script_signature, _format_script_source
+
+    script_name = name.lower()
+    scripts = _state.ast_scripts
+    if script_name not in scripts:
+        _write(f"  {_c(_RED, 'No script named')} {_c(_CYAN, repr(script_name))} {_c(_RED, 'is registered.')}\n")
+        return
+    block = scripts[script_name]
+    sig = _format_script_signature(block.name, block.param_defs)
+    src = _format_script_source(block.span)
+    _write_rule(f" {_c(_BOLD + _YELLOW, 'Script')} {_c(_DIM, '──')} {_c(_CYAN, sig)} ")
+    _write(f"  {_c(_BOLD, 'Source:')}     {src}\n")
+    if block.param_defs:
+        _write(f"  {_c(_BOLD, 'Parameters:')}\n")
+        max_name = max(len(p.name) for p in block.param_defs)
+        for p in block.param_defs:
+            if p.default is not None:
+                _write(
+                    f"    {_c(_CYAN, p.name):<{max_name + len(_CYAN) + len(_RESET)}}  {_c(_DIM, f'(optional, default: {p.default})')}\n",
+                )
+            else:
+                _write(f"    {_c(_CYAN, p.name):<{max_name + len(_CYAN) + len(_RESET)}}  {_c(_DIM, '(required)')}\n")
+    else:
+        _write(f"  {_c(_BOLD, 'Parameters:')} (none)\n")
+    if block.doc:
+        _write("\n")
+        for doc_line in block.doc.split("\n"):
+            _write(f"  {_c(_DIM, doc_line)}\n")
+    _write("\n")