execsql2 2.18.0__tar.gz → 2.18.1__tar.gz

{execsql2-2.18.0 → execsql2-2.18.1}/.github/workflows/ci-cd.yml

@@ -283,7 +283,7 @@ jobs:
                   name: ${{ github.event.repository.name }}
                   path: dist/
             - name: Create release
-              uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65  # v2
+              uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
               with:
                   draft: false
                   prerelease: false

{execsql2-2.18.0 → execsql2-2.18.1}/CHANGELOG.md

@@ -13,6 +13,18 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.18.1] - 2026-05-28
+
+### Changed
+
+- Internal: `execsql.cli.lint_ast` has been folded into `execsql.cli.lint`; the AST walker entry point is now `execsql.cli.lint.lint()`. Code that imported `execsql.cli.lint_ast.lint_ast` should import `execsql.cli.lint.lint` instead.
+
+### Removed
+
+- Internal: the unused `run_when_false` and `run_in_batch` flags on `MetaCommand` (and the matching keyword arguments on `MetaCommandList.add()`) — neither has been consulted since v2.16.0. Code that still passes either kwarg to `mcl.add()` will raise `TypeError`.
+
+______________________________________________________________________
+
 ## [2.18.0] - 2026-05-27
 
 ### Added

{execsql2-2.18.0 → execsql2-2.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.18.0
+Version: 2.18.1
 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
@@ -228,44 +228,46 @@ execsql script.sql                          # read connection from config file
 
 ## Options
 
-| Flag                                  | Description                                                       |
-| ------------------------------------- | ----------------------------------------------------------------- |
-| `-t {p,m,s,l,k,a,f,o,d}`              | Database type                                                     |
-| `-u USER`                             | Database username                                                 |
-| `-p PORT`                             | Server port                                                       |
-| `-a VALUE`                            | Set substitution variable `$ARG_x`                                |
-| `-b` / `--boolean-int`                | Treat integers 0 and 1 as boolean values                          |
-| `-c SCRIPT`                           | Execute inline SQL or metacommand string                          |
-| `-d`                                  | Auto-create export directories                                    |
-| `-e ENCODING` / `--database-encoding` | Character encoding used in the database                           |
-| `-f ENCODING`                         | Script file encoding (default: UTF-8)                             |
-| `-g ENCODING` / `--output-encoding`   | Encoding for WRITE and EXPORT output                              |
-| `-i ENCODING` / `--import-encoding`   | Encoding for data files used with IMPORT                          |
-| `-l`                                  | Write run log to `~/execsql.log`                                  |
-| `-m`                                  | List metacommands and exit                                        |
-| `-n`                                  | Create a new SQLite or PostgreSQL database if it does not exist   |
-| `-o` / `--online-help`                | Open the online documentation in the default browser              |
-| `-s N` / `--scan-lines`               | Lines to scan for IMPORT format detection (0 = scan entire file)  |
-| `-v {0,1,2,3}`                        | GUI level (0=none, 1=password, 2=selection, 3=full)               |
-| `-w`                                  | Skip password prompt when a username is supplied                  |
-| `-y` / `--encodings`                  | List available encoding names and exit                            |
-| `-z KB` / `--import-buffer`           | Import buffer size in KB (default: 32)                            |
-| `--dsn URL`                           | Connection string (e.g. `postgresql://user:pass@host/db`)         |
-| `--output-dir DIR`                    | Default base directory for EXPORT output files                    |
-| `--dry-run`                           | Parse the script and report commands without executing            |
-| `--lint`                              | Static analysis: check structure and warn on issues (no DB)       |
-| `--parse-tree`                        | Print the script's AST structure and exit (no DB)                 |
-| `--list-plugins`                      | List discovered plugins and exit                                  |
-| `--ping`                              | Test database connectivity and exit                               |
-| `--profile`                           | Show per-statement timing summary after execution                 |
-| `--profile-limit N`                   | Top N statements to display in `--profile` summary (default: 20)  |
-| `--progress`                          | Show a progress bar for long-running IMPORT operations            |
-| `--config FILE`                       | Load an explicit config file (highest priority after CLI args)    |
-| `--no-system-cmd`                     | Disable the `SYSTEM_CMD` metacommand (safer for CI / shared envs) |
-| `--init-config`                       | Print a default `execsql.conf` template to stdout and exit        |
-| `--debug`                             | Start in step-through debug mode (REPL pauses before each stmt)   |
-| `--dump-keywords`                     | Print metacommand keywords as JSON and exit                       |
-| `--gui-framework {tkinter,textual}`   | GUI framework for interactive prompts                             |
+| Flag                                  | Description                                                        |
+| ------------------------------------- | ------------------------------------------------------------------ |
+| `-t {p,m,s,l,k,a,f,o,d}`              | Database type                                                      |
+| `-u USER`                             | Database username                                                  |
+| `-p PORT`                             | Server port                                                        |
+| `-a VALUE`                            | Set substitution variable `$ARG_x`                                 |
+| `-b` / `--boolean-int`                | Treat integers 0 and 1 as boolean values                           |
+| `-c SCRIPT`                           | Execute inline SQL or metacommand string                           |
+| `-d`                                  | Auto-create export directories                                     |
+| `-e ENCODING` / `--database-encoding` | Character encoding used in the database                            |
+| `-f ENCODING`                         | Script file encoding (default: UTF-8)                              |
+| `-g ENCODING` / `--output-encoding`   | Encoding for WRITE and EXPORT output                               |
+| `-i ENCODING` / `--import-encoding`   | Encoding for data files used with IMPORT                           |
+| `-l`                                  | Write run log to `~/execsql.log`                                   |
+| `-m`                                  | List metacommands and exit                                         |
+| `-n`                                  | Create a new SQLite or PostgreSQL database if it does not exist    |
+| `-o` / `--online-help`                | Open the online documentation in the default browser               |
+| `-s N` / `--scan-lines`               | Lines to scan for IMPORT format detection (0 = scan entire file)   |
+| `-v {0,1,2,3}`                        | GUI level (0=none, 1=password, 2=selection, 3=full)                |
+| `-w`                                  | Skip password prompt when a username is supplied                   |
+| `-y` / `--encodings`                  | List available encoding names and exit                             |
+| `-z KB` / `--import-buffer`           | Import buffer size in KB (default: 32)                             |
+| `--dsn URL`                           | Connection string (e.g. `postgresql://user:pass@host/db`)          |
+| `--output-dir DIR`                    | Default base directory for EXPORT output files                     |
+| `--dry-run`                           | Parse the script and report commands without executing             |
+| `--lint`                              | Static analysis: check structure and warn on issues (no DB)        |
+| `--parse-tree`                        | Print the script's AST structure and exit (no DB)                  |
+| `--list-plugins`                      | List discovered plugins and exit                                   |
+| `--ping`                              | Test database connectivity and exit                                |
+| `--profile`                           | Show per-statement timing summary after execution                  |
+| `--profile-limit N`                   | Top N statements to display in `--profile` summary (default: 20)   |
+| `--progress`                          | Show a progress bar for long-running IMPORT operations             |
+| `--config FILE`                       | Load an explicit config file (highest priority after CLI args)     |
+| `--no-system-cmd`                     | Disable the `SYSTEM_CMD` metacommand (safer for CI / shared envs)  |
+| `--no-rm-file`                        | Disable the `RM_FILE` metacommand (no script-driven file deletion) |
+| `--no-serve`                          | Disable the `SERVE` metacommand (no script-driven file streaming)  |
+| `--init-config`                       | Print a default `execsql.conf` template to stdout and exit         |
+| `--debug`                             | Start in step-through debug mode (REPL pauses before each stmt)    |
+| `--dump-keywords`                     | Print metacommand keywords as JSON and exit                        |
+| `--gui-framework {tkinter,textual}`   | GUI framework for interactive prompts                              |
 
 Run `execsql --help` for the full option list, or `execsql -m` to list all metacommands.
 
@@ -393,7 +395,7 @@ execsql-format --check scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.11.0
+    rev: v2.18.0
     hooks:
       - id: execsql-format
         args: [--in-place]

{execsql2-2.18.0 → execsql2-2.18.1}/README.md

@@ -99,44 +99,46 @@ execsql script.sql                          # read connection from config file
 
 ## Options
 
-| Flag                                  | Description                                                       |
-| ------------------------------------- | ----------------------------------------------------------------- |
-| `-t {p,m,s,l,k,a,f,o,d}`              | Database type                                                     |
-| `-u USER`                             | Database username                                                 |
-| `-p PORT`                             | Server port                                                       |
-| `-a VALUE`                            | Set substitution variable `$ARG_x`                                |
-| `-b` / `--boolean-int`                | Treat integers 0 and 1 as boolean values                          |
-| `-c SCRIPT`                           | Execute inline SQL or metacommand string                          |
-| `-d`                                  | Auto-create export directories                                    |
-| `-e ENCODING` / `--database-encoding` | Character encoding used in the database                           |
-| `-f ENCODING`                         | Script file encoding (default: UTF-8)                             |
-| `-g ENCODING` / `--output-encoding`   | Encoding for WRITE and EXPORT output                              |
-| `-i ENCODING` / `--import-encoding`   | Encoding for data files used with IMPORT                          |
-| `-l`                                  | Write run log to `~/execsql.log`                                  |
-| `-m`                                  | List metacommands and exit                                        |
-| `-n`                                  | Create a new SQLite or PostgreSQL database if it does not exist   |
-| `-o` / `--online-help`                | Open the online documentation in the default browser              |
-| `-s N` / `--scan-lines`               | Lines to scan for IMPORT format detection (0 = scan entire file)  |
-| `-v {0,1,2,3}`                        | GUI level (0=none, 1=password, 2=selection, 3=full)               |
-| `-w`                                  | Skip password prompt when a username is supplied                  |
-| `-y` / `--encodings`                  | List available encoding names and exit                            |
-| `-z KB` / `--import-buffer`           | Import buffer size in KB (default: 32)                            |
-| `--dsn URL`                           | Connection string (e.g. `postgresql://user:pass@host/db`)         |
-| `--output-dir DIR`                    | Default base directory for EXPORT output files                    |
-| `--dry-run`                           | Parse the script and report commands without executing            |
-| `--lint`                              | Static analysis: check structure and warn on issues (no DB)       |
-| `--parse-tree`                        | Print the script's AST structure and exit (no DB)                 |
-| `--list-plugins`                      | List discovered plugins and exit                                  |
-| `--ping`                              | Test database connectivity and exit                               |
-| `--profile`                           | Show per-statement timing summary after execution                 |
-| `--profile-limit N`                   | Top N statements to display in `--profile` summary (default: 20)  |
-| `--progress`                          | Show a progress bar for long-running IMPORT operations            |
-| `--config FILE`                       | Load an explicit config file (highest priority after CLI args)    |
-| `--no-system-cmd`                     | Disable the `SYSTEM_CMD` metacommand (safer for CI / shared envs) |
-| `--init-config`                       | Print a default `execsql.conf` template to stdout and exit        |
-| `--debug`                             | Start in step-through debug mode (REPL pauses before each stmt)   |
-| `--dump-keywords`                     | Print metacommand keywords as JSON and exit                       |
-| `--gui-framework {tkinter,textual}`   | GUI framework for interactive prompts                             |
+| Flag                                  | Description                                                        |
+| ------------------------------------- | ------------------------------------------------------------------ |
+| `-t {p,m,s,l,k,a,f,o,d}`              | Database type                                                      |
+| `-u USER`                             | Database username                                                  |
+| `-p PORT`                             | Server port                                                        |
+| `-a VALUE`                            | Set substitution variable `$ARG_x`                                 |
+| `-b` / `--boolean-int`                | Treat integers 0 and 1 as boolean values                           |
+| `-c SCRIPT`                           | Execute inline SQL or metacommand string                           |
+| `-d`                                  | Auto-create export directories                                     |
+| `-e ENCODING` / `--database-encoding` | Character encoding used in the database                            |
+| `-f ENCODING`                         | Script file encoding (default: UTF-8)                              |
+| `-g ENCODING` / `--output-encoding`   | Encoding for WRITE and EXPORT output                               |
+| `-i ENCODING` / `--import-encoding`   | Encoding for data files used with IMPORT                           |
+| `-l`                                  | Write run log to `~/execsql.log`                                   |
+| `-m`                                  | List metacommands and exit                                         |
+| `-n`                                  | Create a new SQLite or PostgreSQL database if it does not exist    |
+| `-o` / `--online-help`                | Open the online documentation in the default browser               |
+| `-s N` / `--scan-lines`               | Lines to scan for IMPORT format detection (0 = scan entire file)   |
+| `-v {0,1,2,3}`                        | GUI level (0=none, 1=password, 2=selection, 3=full)                |
+| `-w`                                  | Skip password prompt when a username is supplied                   |
+| `-y` / `--encodings`                  | List available encoding names and exit                             |
+| `-z KB` / `--import-buffer`           | Import buffer size in KB (default: 32)                             |
+| `--dsn URL`                           | Connection string (e.g. `postgresql://user:pass@host/db`)          |
+| `--output-dir DIR`                    | Default base directory for EXPORT output files                     |
+| `--dry-run`                           | Parse the script and report commands without executing             |
+| `--lint`                              | Static analysis: check structure and warn on issues (no DB)        |
+| `--parse-tree`                        | Print the script's AST structure and exit (no DB)                  |
+| `--list-plugins`                      | List discovered plugins and exit                                   |
+| `--ping`                              | Test database connectivity and exit                                |
+| `--profile`                           | Show per-statement timing summary after execution                  |
+| `--profile-limit N`                   | Top N statements to display in `--profile` summary (default: 20)   |
+| `--progress`                          | Show a progress bar for long-running IMPORT operations             |
+| `--config FILE`                       | Load an explicit config file (highest priority after CLI args)     |
+| `--no-system-cmd`                     | Disable the `SYSTEM_CMD` metacommand (safer for CI / shared envs)  |
+| `--no-rm-file`                        | Disable the `RM_FILE` metacommand (no script-driven file deletion) |
+| `--no-serve`                          | Disable the `SERVE` metacommand (no script-driven file streaming)  |
+| `--init-config`                       | Print a default `execsql.conf` template to stdout and exit         |
+| `--debug`                             | Start in step-through debug mode (REPL pauses before each stmt)    |
+| `--dump-keywords`                     | Print metacommand keywords as JSON and exit                        |
+| `--gui-framework {tkinter,textual}`   | GUI framework for interactive prompts                              |
 
 Run `execsql --help` for the full option list, or `execsql -m` to list all metacommands.
 
@@ -264,7 +266,7 @@ execsql-format --check scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.11.0
+    rev: v2.18.0
     hooks:
       - id: execsql-format
         args: [--in-place]

{execsql2-2.18.0 → execsql2-2.18.1}/docs/about/divergence.md

@@ -296,9 +296,10 @@ ______________________________________________________________________
 
 ## Removed Features
 
-| Feature                              | Reason                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Airspeed template processor          | The `airspeed` library (Velocity clone) is unmaintained since ~2018. Use `FORMAT jinja` instead. The `airspeed` value for `template_processor` in `execsql.conf` is no longer accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Python 2 compatibility               | All Python 2 constructs (`stringtypes`, `u""` literals, `optparse`, etc.) have been removed. execsql2 requires Python 3.10+.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `FREE` keyword on `PROMPT DISPLAY`   | The non-blocking display behavior was only implemented in the console backend; the Textual and Tkinter GUI backends ignored it. Removed rather than partially supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Legacy command-list execution engine | The `CommandList` data class, `IfLevels` / `IfItem` classes, and the `.run()` methods on `SqlStmt` / `MetacommandStmt` / `ScriptCmd` were the flat command-list engine inherited from the monolith. The AST executor has been the sole engine since v2.16.0; everything dependent on the flat-engine bookkeeping (`runscripts`, `check_iflevels`, `endloop`, and the `commandliststack` / `loopcommandstack` / `compiling_loop` / `loop_nest_level` / `if_stack` / `savedscripts` slots on `RuntimeContext`) has been removed. Variable scoping migrated to the unified `ast_exec_stack` via the new `ExecFrame` data class. Advanced consumers that read `_state.commandliststack` directly should use `_state.current_localvars()` / `current_paramvals()` / `outer_script_scopes()` instead. |
+| Feature                                                  | Reason                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Airspeed template processor                              | The `airspeed` library (Velocity clone) is unmaintained since ~2018. Use `FORMAT jinja` instead. The `airspeed` value for `template_processor` in `execsql.conf` is no longer accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Python 2 compatibility                                   | All Python 2 constructs (`stringtypes`, `u""` literals, `optparse`, etc.) have been removed. execsql2 requires Python 3.10+.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `FREE` keyword on `PROMPT DISPLAY`                       | The non-blocking display behavior was only implemented in the console backend; the Textual and Tkinter GUI backends ignored it. Removed rather than partially supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Legacy command-list execution engine                     | The `CommandList` data class, `IfLevels` / `IfItem` classes, and the `.run()` methods on `SqlStmt` / `MetacommandStmt` / `ScriptCmd` were the flat command-list engine inherited from the monolith. The AST executor has been the sole engine since v2.16.0; everything dependent on the flat-engine bookkeeping (`runscripts`, `check_iflevels`, `endloop`, and the `commandliststack` / `loopcommandstack` / `compiling_loop` / `loop_nest_level` / `if_stack` / `savedscripts` slots on `RuntimeContext`) has been removed. Variable scoping migrated to the unified `ast_exec_stack` via the new `ExecFrame` data class. Advanced consumers that read `_state.commandliststack` directly should use `_state.current_localvars()` / `current_paramvals()` / `outer_script_scopes()` instead. |
+| `run_when_false` / `run_in_batch` flags on `MetaCommand` | The two boolean flags on `MetaCommand` (and the matching keyword arguments on `MetaCommandList.add()`) were the flat-engine's dispatch-time gates: `run_when_false` let `ELSE` / `ENDIF` handlers fire even when the IF stack was false, and `run_in_batch` permitted `END BATCH` / `ROLLBACK` to run inside a `BEGIN BATCH` block. Under the AST executor IF branching is structural, so handlers only execute on the chosen branch; the live `BEGIN BATCH` gate is `BatchLevels.in_batch()`. Neither flag was read by any live code path; both were removed in v2.18.1 along with the two tests that pinned their presence on every dispatch entry. Code that passed these kwargs to `mcl.add()` will raise `TypeError`.                                                                      |

{execsql2-2.18.0 → execsql2-2.18.1}/docs/dev/adding_metacommands.md

@@ -26,7 +26,7 @@ ______________________________________________________________________
 1. It extracts the leading keyword and narrows candidates via the keyword index, falling back to the full list if no keyword matches.
 1. It calls the handler, passing all named regex groups plus `"metacommandline"` as keyword arguments.
 
-Conditional branching (`IF` / `ELSEIF` / `ELSE` / `ENDIF`) is **structural** under the AST executor — the parser turns those metacommands into `IfBlock` AST nodes and the executor only invokes handlers for the branch it actually entered. Handlers therefore do not need to consult any IF state, and `run_when_false` is no longer honoured.
+Conditional branching (`IF` / `ELSEIF` / `ELSE` / `ENDIF`) is **structural** under the AST executor — the parser turns those metacommands into `IfBlock` AST nodes and the executor only invokes handlers for the branch it actually entered. Handlers therefore do not need to consult any IF state; the `run_when_false` and `run_in_batch` flags that used to gate dispatch under the flat command-list engine were removed in v2.18.1.
 
 ### Handler naming conventions
 
@@ -114,8 +114,6 @@ mcl.add(
 | `matching_regexes` | `str` or `tuple[str, ...]` | required | One regex string, or a tuple of strings all mapped to the same handler                                            |
 | `exec_func`        | callable                   | required | The handler function                                                                                              |
 | `description`      | `str \| None`              | `None`   | Human-readable keyword name (shown in `DEBUG WRITE METACOMMANDLIST` and `--dump-keywords`)                        |
-| `run_in_batch`     | `bool`                     | `False`  | Allow execution inside an open `BEGIN_BATCH`/`END_BATCH` block                                                    |
-| `run_when_false`   | `bool`                     | `False`  | Execute even when the `IF`-stack condition is false (needed for `ELSE`, `ENDIF`, etc.)                            |
 | `set_error_flag`   | `bool`                     | `True`   | Update `_state.status.metacommand_error` on success/failure                                                       |
 | `category`         | `str \| None`              | `None`   | Keyword category for `--dump-keywords` and VS Code grammar generation (e.g., `"action"`, `"control"`, `"config"`) |
 

{execsql2-2.18.0 → execsql2-2.18.1}/docs/dev/architecture.md

@@ -85,7 +85,7 @@ flowchart LR
 | `api.py`        | Public `execsql.run()` Python entry point for notebooks, pipelines, and library use                                           |
 | `config.py`     | `ConfigData` (INI merging), `StatObj` (runtime flags), `WriteHooks` (stdout/stderr redirection)                               |
 | `state.py`      | Thread-local runtime store — all shared mutable state lives here, isolated per-thread                                         |
-| `script/`       | AST parser/executor, `CommandList`, `MetaCommandList`, `SubVarSet`, `ScriptFile`                                              |
+| `script/`       | AST node types, parser, `MetaCommandList`, `SubVarSet`, `BatchLevels`, `ScriptExecSpec`, `set_system_vars()`                  |
 | `metacommands/` | `build_dispatch_table()`, all `x_*` handlers, `build_conditional_table()`, all `xf_*` predicates                              |
 | `db/`           | `Database` ABC, `DatabasePool`, 9 adapter modules (postgres, sqlite, duckdb, mysql, sqlserver, oracle, firebird, access, dsn) |
 | `exporters/`    | `ExportRecord`, `ExportMetadata`, `WriteSpec`, 20+ format writers (CSV, JSON, XML, HTML, etc.)                                |
@@ -110,7 +110,7 @@ execsql2 parses scripts into an AST and walks the tree to execute. There is no s
 - **`script/ast.py`** — defines 9 `Node` subclasses (`SqlStatement`, `MetaCommandStatement`, `Comment`, `IfBlock`, `LoopBlock`, `BatchBlock`, `ScriptBlock`, `SqlBlock`, `IncludeDirective`) plus the `Script` root and supporting types (`SourceSpan` for source locations, `ConditionModifier` for ANDIF/ORIF, `ElseIfClause`, `ParamDef`).
 - **`script/parser.py`** — `parse_script(path)` / `parse_string(text)` produce a `Script` tree. All block structures (IF/LOOP/BATCH/SCRIPT/SQL) are resolved at parse time into nested nodes; the parser also reports structural errors (unmatched blocks).
 - **`script/executor.py`** — `execute(tree, ctx=)` walks the tree via `_execute_nodes()` / `_execute_node()`. SQL and metacommands delegate to the existing dispatch tables. INCLUDE'd files are parsed and recursed into natively; circular INCLUDE references are detected via `ctx.include_chain` and reported. Named SCRIPT blocks register in `ctx.ast_scripts` (instance-scoped) for later `EXECUTE SCRIPT` lookup. `ON ERROR_HALT` / `ON CANCEL_HALT EXECUTE SCRIPT` deferred scripts also run through the AST executor.
-- **`cli/lint_ast.py`** — AST-based linter for variable and INCLUDE checks; structural validation lives in the parser.
+- **`cli/lint.py`** — AST-based linter for variable and INCLUDE checks plus the Rich result printer; structural validation lives in the parser.
 
 Use `--parse-tree` to print the AST without executing.
 
@@ -139,7 +139,7 @@ Metacommands are lines in SQL scripts prefixed with `-- !x!`. At import time, `m
 
 ### How dispatch works
 
-`MetacommandStmt.run()` delegates to `_state.metacommandlist.eval(cmd_str)`. The dispatcher extracts the leading keyword, narrows ~225 entries to a small candidate set via a keyword index, then tests each candidate's compiled regex against the full command. The matched handler is called with the regex's named groups as keyword arguments plus `metacommandline` (the original unmodified line), and its hit counter is incremented.
+For each `MetaCommandStatement` AST node, the executor calls `_exec_metacommand()` in `script/executor.py`, which delegates to `_state.metacommandlist.eval(cmd_str)`. The dispatcher extracts the leading keyword, narrows ~225 entries to a small candidate set via a keyword index, then tests each candidate's compiled regex against the full command. The matched handler is called with the regex's named groups as keyword arguments plus `metacommandline` (the original unmodified line), and its hit counter is incremented.
 
 ### Handler conventions
 
@@ -160,7 +160,7 @@ The `IF`/`ELSEIF`/`ELSE`/`ENDIF` metacommands control conditional execution stru
 
 `_execute_if()` evaluates the IF condition (and any ANDIF/ORIF modifiers) via `CondParser`, then walks the chosen branch (the IF body, one of the ELSEIF clauses, or the ELSE body). For tracking and REPL introspection it pushes a non-scope `ExecFrame` (`kind="if"`/`"elseif"`/`"else"`) onto `ctx.ast_exec_stack` whose `scope_ref` points at the enclosing SCRIPT/main scope; the frame is popped when the branch finishes.
 
-Because branching is structural, the legacy `_state.if_stack` / `IfLevels` machinery and the `run_when_false` flag on metacommand handlers are no longer in use; the dispatch handlers for `IF` / `ELSEIF` / `ELSE` / `ENDIF` / `ANDIF` / `ORIF` / `BREAK` / `BEGIN BATCH` / `END BATCH` remain registered as `ErrInfo` stubs so a parser regression that bypassed the AST would fail loudly instead of silently.
+Because branching is structural, the executor never consults dispatch-time flags to decide whether an IF/ELSE/ELSEIF/ENDIF/ANDIF/ORIF handler should fire — the parser has already chosen the live branch. The corresponding dispatch entries (and the `BREAK` / `BEGIN BATCH` / `END BATCH` entries) remain registered as `ErrInfo` stubs so that a parser regression which let one of those metacommands fall through to the dispatch table would fail loudly rather than silently. (The pre-AST flat-command-list engine relied on a `_state.if_stack` + `IfLevels` state machine and matching `run_when_false` / `run_in_batch` flags on `MetaCommand`; both were removed once the AST became the sole execution engine.)
 
 ### CondParser
 

{execsql2-2.18.0 → execsql2-2.18.1}/extras/vscode-execsql/README.md

@@ -43,13 +43,13 @@ ______________________________________________________________________
 Create a symlink from the VSCode extensions directory to this folder:
 
 ```sh
-ln -s /path/to/execsql/vscode-execsql ~/.vscode/extensions/execsql-syntax
+ln -s /path/to/execsql/extras/vscode-execsql ~/.vscode/extensions/execsql-syntax
 ```
 
 For example, if you cloned the repo to `./execsql`:
 
 ```sh
-ln -s ./execsql/vscode-execsql ~/.vscode/extensions/execsql-syntax
+ln -s "$(pwd)/execsql/extras/vscode-execsql" ~/.vscode/extensions/execsql-syntax
 ```
 
 ### Windows
@@ -57,13 +57,13 @@ ln -s ./execsql/vscode-execsql ~/.vscode/extensions/execsql-syntax
 Create a directory junction using Command Prompt **as Administrator**:
 
 ```cmd
-mklink /J "%USERPROFILE%\.vscode\extensions\execsql-syntax" "C:\path\to\execsql\vscode-execsql"
+mklink /J "%USERPROFILE%\.vscode\extensions\execsql-syntax" "C:\path\to\execsql\extras\vscode-execsql"
 ```
 
 Or using PowerShell **as Administrator**:
 
 ```powershell
-New-Item -ItemType Junction -Path "$env:USERPROFILE\.vscode\extensions\execsql-syntax" -Target "C:\path\to\execsql\vscode-execsql"
+New-Item -ItemType Junction -Path "$env:USERPROFILE\.vscode\extensions\execsql-syntax" -Target "C:\path\to\execsql\extras\vscode-execsql"
 ```
 
 ### After installing

{execsql2-2.18.0 → execsql2-2.18.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.18.0"
+version = "2.18.1"
 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" }
@@ -168,7 +168,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.18.0"
+current_version = "2.18.1"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{execsql2-2.18.0 → execsql2-2.18.1}/src/execsql/cli/__init__.py

@@ -8,8 +8,7 @@ Submodules:
 - :mod:`execsql.cli.help`      — Rich-formatted help output & console objects
 - :mod:`execsql.cli.dsn`       — Connection-string (DSN URL) parser
 - :mod:`execsql.cli.run`       — Core execution logic (``_run``, ``_connect_initial_db``, ``_ping_db``, ``_print_dry_run``, ``_print_profile``)
-- :mod:`execsql.cli.lint_ast`  — AST-based ``--lint`` static analyser
-- :mod:`execsql.cli.lint`      — Shared lint result printing (``_print_lint_results``) used by the AST linter
+- :mod:`execsql.cli.lint`      — AST-based ``--lint`` static analyser and Rich result printer
 """
 
 from __future__ import annotations
@@ -554,8 +553,7 @@ def main(
     # Lint: AST-based static analysis (no DB connection needed)
     # ------------------------------------------------------------------
     if lint:
-        from execsql.cli.lint import _print_lint_results
-        from execsql.cli.lint_ast import lint_ast
+        from execsql.cli.lint import _print_lint_results, lint as _lint_script
         from execsql.script.parser import parse_script, parse_string
 
         label = script_name or "<inline>"
@@ -576,7 +574,7 @@ def main(
             exit_code = _print_lint_results(issues, label)
             raise typer.Exit(code=exit_code) from exc
 
-        issues = lint_ast(tree, script_path=script_name)
+        issues = _lint_script(tree, script_path=script_name)
         exit_code = _print_lint_results(issues, label)
         raise typer.Exit(code=exit_code)
 

execsql2-2.18.0/src/execsql/cli/lint_ast.py → execsql2-2.18.1/src/execsql/cli/lint.py

@@ -1,29 +1,37 @@
-"""AST-based static analysis (lint) for execsql scripts.
-
-Performs the same checks as :mod:`execsql.cli.lint` but operates on the
-:class:`~execsql.script.ast.Script` tree instead of a flat
-:class:`~execsql.script.engine.CommandList`.
-
-Advantages over the flat linter:
-
-- **No runtime state required** — works with the AST parser alone, so it
-  can run as an early exit in the CLI without initialising ``_state``.
-- **Structural validation is free** — the AST parser already rejects
-  unmatched IF/LOOP/BATCH/SCRIPT blocks at parse time with precise source
-  spans.  This linter only needs to report variable and INCLUDE issues.
-- **Script blocks are in the tree** — ``EXECUTE SCRIPT`` targets are
-  resolved by finding :class:`ScriptBlock` nodes, not by looking up
-  ``_state.savedscripts``.
-
-Checks performed
-----------------
-1. **Parse errors** — the AST parser rejects unmatched blocks, so any
-   parse failure is reported as an error with the parser's message.
-2. **Potentially undefined variables** — same heuristic as the flat linter.
-3. **EXECUTE SCRIPT target resolution** — warns when a target name does
-   not correspond to a :class:`ScriptBlock` in the same file.
-4. **Missing INCLUDE files** — warns when the file does not exist on disk.
-5. **Empty script** — warns when no nodes were parsed.
+"""AST-based static analysis (``--lint``) for execsql scripts.
+
+Operates on the :class:`~execsql.script.ast.Script` tree produced by
+:func:`execsql.script.parser.parse_script` / ``parse_string``. Runs as
+an early CLI exit — no DB connection and no ``_state`` initialisation
+required.
+
+Checks performed:
+
+1. **Parse errors** — the AST parser rejects unmatched IF / LOOP /
+   BATCH / SCRIPT blocks at parse time with precise source spans;
+   ``cli/__init__.py`` reports any parse failure as a lint error before
+   :func:`lint` is even called.
+2. **Empty scripts** — warns when no nodes were parsed.
+3. **Potentially undefined variables** — flags ``!!$VAR!!`` references
+   with no preceding ``SUB``-family definition, ignoring built-in
+   ``$VAR`` names discovered from the package source and the
+   non-``$`` sigils (``~``, ``#``, ``+``, ``@``, ``&``) that resolve at
+   runtime.
+4. **Missing INCLUDE files** — warns when the resolved target does not
+   exist on disk (skipped when ``IF EXISTS`` is present).
+5. **EXECUTE SCRIPT target resolution** — warns when a target name does
+   not correspond to a :class:`ScriptBlock` in the same file (skipped
+   when ``IF EXISTS`` is present).
+
+Public surface:
+
+- :func:`lint` — entry point; returns a list of
+  ``(severity, source, line_no, message)`` tuples.
+- :func:`_print_lint_results` — Rich console formatter for those
+  tuples; returns the ``--lint`` process exit code (``1`` when any
+  error-severity issue is present, ``0`` otherwise).
+- :data:`_Issue`, :func:`_error`, :func:`_warning` — tuple type alias
+  and constructors used by the walker and the formatter.
 """
 
 from __future__ import annotations
@@ -44,11 +52,27 @@ from execsql.script.ast import (
     SqlStatement,
 )
 
-__all__ = ["lint_ast"]
+__all__ = ["_Issue", "_error", "_print_lint_results", "_warning", "lint"]
 
 
 # ---------------------------------------------------------------------------
-# Variable-related patterns (shared with the flat linter)
+# Issue tuple type and constructors
+# ---------------------------------------------------------------------------
+
+
+_Issue = tuple[str, str, int, str]  # (severity, source, line_no, message)
+
+
+def _error(source: str, line_no: int, message: str) -> _Issue:
+    return ("error", source, line_no, message)
+
+
+def _warning(source: str, line_no: int, message: str) -> _Issue:
+    return ("warning", source, line_no, message)
+
+
+# ---------------------------------------------------------------------------
+# Variable-related patterns
 # ---------------------------------------------------------------------------
 
 _RX_SUB = re.compile(r"^\s*SUB\s+(?P<name>[+~]?\w+)\s+", re.I)
@@ -72,22 +96,7 @@ _RX_VAR_REF = re.compile(r"!!([$@&~#+]?\w+)!!", re.I)
 
 
 # ---------------------------------------------------------------------------
-# Issue tuple helpers
-# ---------------------------------------------------------------------------
-
-_Issue = tuple[str, str, int, str]  # (severity, source, line_no, message)
-
-
-def _error(source: str, line_no: int, message: str) -> _Issue:
-    return ("error", source, line_no, message)
-
-
-def _warning(source: str, line_no: int, message: str) -> _Issue:
-    return ("warning", source, line_no, message)
-
-
-# ---------------------------------------------------------------------------
-# Built-in variable discovery (reuse from flat linter)
+# Built-in variable discovery
 # ---------------------------------------------------------------------------
 
 
@@ -396,11 +405,11 @@ def _lint_nodes(
 
 
 # ---------------------------------------------------------------------------
-# Public API
+# Public entry point
 # ---------------------------------------------------------------------------
 
 
-def lint_ast(
+def lint(
     script: Script,
     script_path: str | None = None,
 ) -> list[_Issue]:
@@ -437,3 +446,61 @@ def lint_ast(
     )
 
     return issues
+
+
+# ---------------------------------------------------------------------------
+# Result printing
+# ---------------------------------------------------------------------------
+
+
+def _print_lint_results(issues: list[_Issue], script_label: str) -> int:
+    """Print lint issues to the console using Rich formatting.
+
+    Args:
+        issues: List of ``(severity, source, line_no, message)`` tuples.
+        script_label: Human-readable label for the script (file path or
+            ``<inline>``), shown in the summary line.
+
+    Returns:
+        ``1`` if any errors were found, ``0`` if only warnings or nothing.
+    """
+    from execsql.cli.help import _console
+
+    n_errors = sum(1 for sev, *_ in issues if sev == "error")
+    n_warnings = sum(1 for sev, *_ in issues if sev == "warning")
+
+    _console.print(f"\n[bold cyan]Lint:[/bold cyan] {script_label}")
+    _console.print()
+
+    if not issues:
+        _console.print("[bold green]No issues found.[/bold green]")
+        _console.print()
+        return 0
+
+    # Sort: errors first, then warnings; within each group sort by line number.
+    _sev_order = {"error": 0, "warning": 1}
+    sorted_issues = sorted(issues, key=lambda i: (_sev_order.get(i[0], 9), i[2]))
+
+    # Compute the widest location string so columns align.
+    locs: list[str] = []
+    for _, source, line_no, _ in sorted_issues:
+        locs.append(f"{source}:{line_no}" if line_no else source)
+    loc_width = max(len(loc) for loc in locs) if locs else 0
+
+    for (severity, _source, _line_no, message), loc in zip(sorted_issues, locs):
+        pad = " " * (loc_width - len(loc))
+        if severity == "error":
+            _console.print(f"  [bold red]ERROR  [/bold red]  [dim]{loc}[/dim]{pad}  {message}")
+        else:
+            _console.print(f"  [bold yellow]WARNING[/bold yellow]  [dim]{loc}[/dim]{pad}  {message}")
+
+    _console.print()
+    parts = []
+    if n_errors:
+        parts.append(f"[bold red]{n_errors} error{'s' if n_errors != 1 else ''}[/bold red]")
+    if n_warnings:
+        parts.append(f"[bold yellow]{n_warnings} warning{'s' if n_warnings != 1 else ''}[/bold yellow]")
+    _console.print("  " + ", ".join(parts))
+    _console.print()
+
+    return 1 if n_errors > 0 else 0