execsql2 2.11.0__tar.gz → 2.12.0__tar.gz

{execsql2-2.11.0 → execsql2-2.12.0}/.claude/project_context.md

@@ -67,6 +67,9 @@ src/execsql/               # active codebase — all new work goes here
   importers/
     __init__.py
     base.py / csv.py / ods.py / xls.py / feather.py
+  debug/
+    __init__.py            # debug package
+    repl.py                # x_breakpoint, _debug_repl, REPL helpers (BREAKPOINT metacommand)
   metacommands/
     __init__.py            # DISPATCH_TABLE, format/db constants, re-exports all handlers
     dispatch.py            # build_dispatch_table() — all mcl.add() regex registrations
@@ -189,10 +192,10 @@ Triggered on: push to `main`, any tag `v*.*.*`, pull requests.
 
 ## Versioning
 
-`bump-my-version` manages versions. Current: `2.5.0`. Bump commands:
+`bump-my-version` manages versions. Current: `2.11.0`. Bump commands:
 
-- `just bump-patch` → 2.5.0 → 2.5.1
-- `just bump-minor` → 2.5.0 → 2.6.0
+- `just bump-patch` → 2.11.0 → 2.11.1
+- `just bump-minor` → 2.11.0 → 2.12.0
   Bumps commit + tag. Pre-commit hook runs `uv lock` + stages `uv.lock`.
 
 ## Ruff Config
@@ -254,16 +257,32 @@ the foreseeable future.
 | Dispatch optimization already in place (verified) | 2.5.0          | 2026-04 |
 | PostgreSQL integration tests (9 tests, CI Docker) | 2.5.0          | 2026-04 |
 | MySQL integration tests (9 tests, CI Docker)      | 2.5.0          | 2026-04 |
+| `RuntimeContext` refactor + module proxy           | 2.6.0          | 2026-04 |
+| `noqa` cleanup (180 suppressions removed)          | 2.6.0          | 2026-04 |
+| Coverage raised to 86% (3010 tests)                | 2.6.0          | 2026-04 |
+| Markdown, YAML, XLSX export formats                | 2.7.0          | 2026-04 |
+| `ASSERT` metacommand                               | 2.8.0          | 2026-04 |
+| `--dry-run` variable expansion                     | 2.8.0          | 2026-04 |
+| `--profile` per-statement timing                   | 2.8.0          | 2026-04 |
+| `--ping` connectivity test                         | 2.9.0          | 2026-04 |
+| `--lint` static script analysis                    | 2.9.0          | 2026-04 |
+| Configuration docs audit (6 fixes)                 | 2.9.0          | 2026-04 |
+| `ROW_COUNT_GT/GTE/EQ/LT` conditionals             | 2.10.0         | 2026-04 |
+| `BREAKPOINT` debug REPL with step mode             | 2.10.0         | 2026-04 |
+| Error messages restored (script location, command) | 2.11.0         | 2026-04 |
+| 16-item codebase analysis fix sweep                | 2.11.x         | 2026-04 |
 
 ______________________________________________________________________
 
-### v2.6 — Architecture & Internal Quality
+### Completed milestone detail (v2.6–v2.11)
 
-- [x] **`state.py` → `RuntimeContext` refactor** — 33 mutable globals consolidated into a slotted `RuntimeContext` class with transparent module proxy. `get_context()`/`set_context()` API added. Zero external call-site changes.
-- [x] **`noqa` cleanup in `metacommands/__init__.py`** — removed all 180 redundant `# noqa` comments; `__all__` already satisfies ruff F401.
-- [x] **Coverage push to 86%** — 403 new tests (3010 total) covering `db/base.py` (55→99%), `metacommands/connect.py` (36→100%), `script/engine.py` (77→95%), `exporters/delimited.py` (76→95%). Remaining gap to 90% is in GUI, ODS, and import handlers.
+#### v2.6 — Architecture & Internal Quality
 
-### v2.7 — New Export/Import Formats
+- [x] `state.py` → `RuntimeContext` refactor
+- [x] `noqa` cleanup in `metacommands/__init__.py`
+- [x] Coverage push to 86%
+
+#### v2.7 — New Export/Import Formats
 
 - [x] **Parquet import** — already existed as `IMPORT TO table FROM PARQUET file` (verified present).
 - [x] **YAML export** — `FORMAT YAML` via PyYAML, list-of-dicts with native type preservation.

{execsql2-2.11.0 → execsql2-2.12.0}/CHANGELOG.md

@@ -13,6 +13,46 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.12.0] - 2026-04-01
+
+### Added
+
+- Debug REPL `.where` / `.w` command — shows current script file, line number, and the upcoming statement text (truncated to 120 chars). The entry banner now includes the location (`[Breakpoint] myscript.sql:42`) and `_print_where()` is called automatically on REPL entry via `BREAKPOINT` or step mode.
+- Debug REPL `.set VAR VAL` / `.s VAR VAL` command — sets or updates a substitution variable interactively during a `BREAKPOINT` session. Prints a confirmation line (`VAR = VAL`) on success; prints an error if substitution variables are not initialised.
+- Debug REPL ANSI color output — horizontal rule separators, colored labels ("Breakpoint"/"Step" in bold yellow, filename:line in cyan, type tags in dim green), cyan variable names, dim `=` signs, red error messages, bold SQL column headers, and dim row-count and table borders. Color is auto-detected via TTY and suppressed when `NO_COLOR` or `EXECSQL_NO_COLOR` environment variables are set. Falls back to plain text in non-interactive contexts (CI, piped output). Help text is also colorized with cyan command names and consistent column alignment.
+- Debug REPL shortcut aliases — `.h` for `.help`, `.v` for `.vars`, `.v all` for `.vars all`.
+- Debug REPL step mode banner — when the REPL is re-entered via `.next` / step mode, the entry banner now shows "Step" instead of "Breakpoint" to make it clear the pause is from stepping rather than an explicit `BREAKPOINT` metacommand.
+- `--profile-limit N` CLI option — controls how many top statements appear in the `--profile` timing summary (default: 20). The "not shown" footer message now includes the active limit for clarity.
+- Test coverage raised from 86% to 91% — 274 new tests across `metacommands/io_import.py`, `metacommands/io_export.py`, `metacommands/control.py`, `metacommands/data.py`, `importers/csv.py`, and `gui/console.py`. Coverage floor raised from 85% to 90% in `pyproject.toml`.
+
+### Changed
+
+- `execsql.debug.repl` is now a dedicated package (`src/execsql/debug/repl.py`); previously the REPL lived at `execsql.metacommands.debug_repl`. Internal import paths have been updated throughout. No public API change.
+
+______________________________________________________________________
+
+## [2.11.1] - 2026-04-01
+
+### Fixed
+
+- `x_assert` crash when `exec_log` is None — added null guard on `log_user_msg()` call.
+- `--ping` version-query loop exiting prematurely — `break` was at wrong indentation, skipping fallback queries when the first query returned no rows.
+- `CONSOLE SET WIDTH/HEIGHT` crash — `gui_console_width()`/`gui_console_height()` restored as setter functions with GUI console propagation.
+- `$ERROR_MESSAGE` now contains full `errmsg()` (with script location and timestamp) for non-halting errors.
+- Non-halting SQL and metacommand errors now logged to exec_log.
+- `x_debug_log_subvars` log format — was printing full tuple instead of name/value for local variables.
+- Dead `endloop()` removed from `control.py` — `state.endloop()` is canonical.
+- YAML `append=True` now emits `---` document separator for valid multi-document streams.
+- REPL dot-command parsing consistency between dispatcher and exit-check.
+- `__delattr__` on state proxy uses cached `_DEFAULT_CTX` instead of allocating per call.
+- `write_query_to_xlsx` single-sheet now updates `export_metadata`.
+- `isinstance()` used instead of `type()` equality in `MetaCommandList.add()`.
+- Module docstrings in `conditions.py` and `control.py` moved before imports.
+- FEATHER divergence doc corrected — `polars` only, not `polars + pyarrow`.
+- README pre-commit rev updated to `v2.11.0`; options table completed.
+
+______________________________________________________________________
+
 ## [2.11.0] - 2026-04-01
 
 ### Added

{execsql2-2.11.0 → execsql2-2.12.0}/CLAUDE.md

@@ -37,13 +37,13 @@ A multi-agent system where specialized agents collaborate to improve, extend, de
 1. **Research** — Oracle investigates codebase, finds relevant code paths and impact
 1. **Plan** — DBA synthesizes research into implementation approach, aligns with human
 1. **Implement** — Patcher writes code, Oracle advises on architecture
-1. **Test** — QA writes/runs tests, verifies coverage stays above 80%
+1. **Test** — QA writes/runs tests, verifies coverage stays above 90%
 1. **Document** — Scribe updates docs, Herald updates changelog
 1. **Review** — Inspector does final code review before human merge
 
 ## Constraints
 
-- Coverage floor (80%) must be maintained — QA blocks any change that drops it
+- Coverage floor (90%) must be maintained — QA blocks any change that drops it
 - Backwards compatibility with upstream execsql v1.130.1 unless explicitly approved
 - No destructive git operations without human approval
 - Agents should always read `.claude/project_context.md` before starting work

{execsql2-2.11.0 → execsql2-2.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.11.0
+Version: 2.12.0
 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: Repository, https://github.com/geocoug/execsql
 Project-URL: Issues, https://github.com/geocoug/execsql/issues
@@ -220,8 +220,11 @@ execsql script.sql                          # read connection from config 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                |
 | `--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)     |
+| `--ping`                            | Test database connectivity and exit                             |
+| `--profile`                         | Show per-statement timing summary after execution               |
 | `--progress`                        | Show a progress bar for long-running IMPORT operations          |
 | `--debug`                           | Start in step-through debug mode (REPL pauses before each stmt) |
 | `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
@@ -298,7 +301,7 @@ execsql-format --check scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.4.4
+    rev: v2.11.0
     hooks:
       - id: execsql-format
         args: [--in-place]

{execsql2-2.11.0 → execsql2-2.12.0}/README.md

@@ -110,8 +110,11 @@ execsql script.sql                          # read connection from config 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                |
 | `--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)     |
+| `--ping`                            | Test database connectivity and exit                             |
+| `--profile`                         | Show per-statement timing summary after execution               |
 | `--progress`                        | Show a progress bar for long-running IMPORT operations          |
 | `--debug`                           | Start in step-through debug mode (REPL pauses before each stmt) |
 | `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
@@ -188,7 +191,7 @@ execsql-format --check scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.4.4
+    rev: v2.11.0
     hooks:
       - id: execsql-format
         args: [--in-place]

{execsql2-2.11.0 → execsql2-2.12.0}/docs/about/divergence.md

@@ -24,7 +24,8 @@ ______________________________________________________________________
 | `--gui-framework`               | Select GUI backend: `tkinter` (default) or `textual` (terminal UI).                                                                                                                                                                                                                                                                     |
 | `--debug`                       | Start in step-through debug mode. The debug REPL pauses before each statement, as if `BREAKPOINT` were at the top with `.next` always active.                                                                                                                                                                                           |
 | `--dry-run`                     | Parse the script and print the full command list without connecting to a database or executing anything. Substitution variables already populated at parse time (env vars, `--assign-arg` values, built-in start-time vars) are expanded in the output; execution-time variables (`$DB_NAME`, `$CURRENT_TIME`, etc.) remain unexpanded. |
-| `--profile`                     | Record wall-clock time for each SQL and metacommand statement. After the script completes, print a summary table sorted by elapsed time (descending), showing time, percentage of total, source location, command type, and a command preview. Top 20 slowest statements are shown.                                                     |
+| `--profile`                     | Record wall-clock time for each SQL and metacommand statement. After the script completes, print a summary table sorted by elapsed time (descending), showing time, percentage of total, source location, command type, and a command preview.                                                                                          |
+| `--profile-limit N`             | Number of top statements to display in the `--profile` summary (default: 20). Remaining statements are counted and noted in the output footer.                                                                                                                                                                                          |
 | `--ping`                        | Test database connectivity and exit. Connects using the supplied connection parameters, queries for the server version, and prints a one-line success message (exit 0) or the error (exit 1). No script file argument is required.                                                                                                      |
 | `--lint`                        | Parse the script and perform static analysis without connecting to a database. Reports unmatched IF/ENDIF, LOOP/END LOOP, and BEGIN BATCH/END BATCH blocks (errors), potentially undefined `!!$VAR!!` references (warnings), and missing INCLUDE file targets (warnings). Exits 0 if no errors, 1 if errors found.                      |
 
@@ -33,19 +34,19 @@ ______________________________________________________________________
 | Format            | Description                                                                                                          |
 | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
 | `PARQUET`         | Export query or table results to Apache Parquet via `polars`.                                                        |
-| `FEATHER`         | Export to Apache Feather/IPC via `polars` + `pyarrow` (upstream used `pandas`).                                      |
+| `FEATHER`         | Export to Apache Feather/IPC via `polars` (upstream used `pandas` + `pyarrow`).                                      |
 | `YAML`            | Export query or table results as a YAML sequence of mappings via `PyYAML`.                                           |
 | `MARKDOWN` / `MD` | Export query or table results as a GitHub-Flavored Markdown (GFM) pipe table. Pure Python, no optional dependencies. |
 | `XLSX`            | Export query or table results to an Excel XLSX workbook via `openpyxl` (single or multi-sheet).                      |
 
 ### Metacommands
 
-| Metacommand            | Description                                                                                                                                                                    |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `ASSERT`               | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks.          |
-| `BREAKPOINT`           | Pause script execution and drop into an interactive debug REPL. Inspect variables, run ad-hoc SQL, and step through the script. Silently skipped in non-TTY (CI) environments. |
-| `CONFIG SHOW_PROGRESS` | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                                 |
-| `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                          |
+| Metacommand            | Description                                                                                                                                                           |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ASSERT`               | Evaluate a condition and raise an error (halting the script) if it is false. Supports all IF conditions. Optional quoted failure message. Skipped in false IF blocks. |
+| `BREAKPOINT`           | Pause script execution and drop into an interactive debug REPL. See [Debugging](#debugging) below for full details.                                                   |
+| `CONFIG SHOW_PROGRESS` | Enable the Rich progress bar for IMPORT operations at runtime.                                                                                                        |
+| `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                 |
 
 ### Conditional Tests
 
@@ -106,6 +107,46 @@ New options in `execsql.conf`:
 | `py.typed` marker           | PEP 561 marker enabling downstream static type checking.                                                        |
 | Structured keyword registry | `--dump-keywords` introspects the dispatch table and outputs JSON used by the grammar generator and test suite. |
 
+### Debugging { #debugging }
+
+execsql2 adds a full interactive debugging system that has no equivalent in upstream execsql.
+
+**`BREAKPOINT` metacommand** — insert `-- !x! BREAKPOINT` anywhere in a script to pause execution and drop into a debug REPL. The REPL provides a `execsql debug>` prompt where you can inspect state and interact with the database before resuming.
+
+**`--debug` CLI flag** — start the script in step-through mode, pausing before every statement as if `BREAKPOINT` were inserted at the top with `.next` always active.
+
+**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                                                   |
+
+**Non-prefixed input** is interpreted as either a variable lookup or ad-hoc SQL:
+
+| Input                          | Behavior                                                                         |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| `logfile`                      | Print the value of the `logfile` substitution variable                           |
+| `$ARG_1`                       | Print the value of a system/built-in variable                                    |
+| `SELECT count(*) FROM orders;` | Execute SQL against the current database and pretty-print the results in a table |
+
+**Key behaviors:**
+
+- **Non-interactive safety** — `BREAKPOINT` is silently skipped when `sys.stdin` is not a TTY (CI pipelines, piped input, cron). Scripts never hang in automation.
+- **Ad-hoc SQL** — any input ending with `;` is executed against the current database connection using the same cursor and transaction state as the script. Queries return a formatted table; DML statements (INSERT, UPDATE, DELETE) execute and commit/rollback according to the current autocommit and batch settings.
+- **Variable inspection** — bare names look up user-defined variables (e.g., `logfile`); sigil-prefixed names look up system (`$`), environment (`&`), local (`~`), or counter (`@`) variables. If a `$`-prefixed name isn't found, the REPL strips the sigil and retries (since `SUB` stores keys without a prefix).
+- **Step mode** — `.next` executes exactly one statement then re-enters the REPL. When stepping, the entry banner shows "Step" instead of "Breakpoint" to distinguish stepping from an explicit `BREAKPOINT`. Combined with `.where`, `.vars`, and SQL queries, this allows line-by-line script debugging with full state visibility.
+- **Location display** — on entry to the REPL (via `BREAKPOINT` or step mode) the banner shows a horizontal rule with the label ("Breakpoint" or "Step"), the current filename and line number, and the upcoming statement. Use `.where` (or `.w`) at any time to re-display this information.
+- **ANSI color output** — the REPL uses ANSI color on TTY outputs: bold yellow for section labels, cyan for filenames and variable names, dim for separators and `=` signs, red for error messages, bold for SQL column headers, and dim italic for `NULL` values. Color is suppressed when `NO_COLOR` or `EXECSQL_NO_COLOR` environment variables are set, or when the output stream is not a TTY.
+- **Readline support** — on platforms where `readline` is available (macOS, Linux), the REPL supports arrow-key history navigation and line editing.
+
 ______________________________________________________________________
 
 ## Changed Behavior

{execsql2-2.11.0 → execsql2-2.12.0}/docs/guides/debugging.md

@@ -38,6 +38,47 @@ DEBUG WRITE <script_name> [[APPEND] TO <filename>]
 
 This is an alias for the [WRITE SCRIPT](../reference/metacommands.md#write_script) metacommand.
 
+# Interactive Debug REPL (BREAKPOINT)
+
+Insert `-- !x! BREAKPOINT` anywhere in a script to pause execution and drop into the interactive debug REPL:
+
+```sql
+-- !x! BREAKPOINT
+SELECT * FROM orders WHERE status = 'pending';
+```
+
+The REPL prints the current file name, line number, and the upcoming statement when it opens:
+
+```
+[Breakpoint] myscript.sql:42 — Script paused. Type '.help' for commands, '.c' to resume.
+  myscript.sql:42  (sql)
+  → SELECT * FROM orders WHERE status = 'pending';
+execsql debug>
+```
+
+**Available commands:**
+
+| Command        | Shortcut | Description                                                               |
+| -------------- | -------- | ------------------------------------------------------------------------- |
+| `.continue`    | `.c`     | Resume normal script execution                                            |
+| `.abort`       | `.q`     | Halt the script with exit status 1                                        |
+| `.vars`        | `.v`     | List user, system, local, and counter substitution variables              |
+| `.vars all`    | `.v all` | Include environment variables (`&`) in the listing                        |
+| `.next`        | `.n`     | Execute the next statement, then pause again (step mode)                  |
+| `.where`       | `.w`     | Re-display the current script location and upcoming statement             |
+| `.stack`       |          | Show the command-list stack (script name, cursor position, nesting depth) |
+| `.set VAR VAL` | `.s`     | Set or update a substitution variable                                     |
+| `.help`        | `.h`     | Show available commands                                                   |
+
+Anything not starting with `.` is treated as a variable lookup or SQL:
+
+- A bare name (e.g. `logfile`) prints the value of that substitution variable.
+- Any input ending with `;` is executed as SQL against the current database (expects columns returned, e.g. SELECT).
+
+The `--debug` CLI flag starts execution in step mode, pausing before every statement.
+
+In non-interactive environments (CI, piped input) `BREAKPOINT` is silently skipped so automated pipelines are never blocked.
+
 The ON ERROR_HALT metacommands allow custom reporting (or cleanup) actions to be taken when errors occur.
 
 Setting the configuration setting [write_warnings](../reference/configuration.md#write_warnings) to "Yes" can also assist with debugging by displaying conditions that may result from errors in the script.

{execsql2-2.11.0 → execsql2-2.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.11.0"
+version = "2.12.0"
 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" }
@@ -158,7 +158,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.11.0"
+current_version = "2.12.0"
 commit = true
 commit_args = "--no-verify"
 tag = true
@@ -182,7 +182,7 @@ addopts = [
     "--cov=execsql",
     "--cov-branch",
     "--cov-report=xml",
-    "--cov-fail-under=85",
+    "--cov-fail-under=90",
     "--strict-markers",
     "--strict-config",
     "--color=yes",

{execsql2-2.11.0 → execsql2-2.12.0}/src/execsql/cli/__init__.py

@@ -278,6 +278,11 @@ def main(
         "--profile",
         help="Record per-statement execution times and print a timing summary after the script completes.",
     ),
+    profile_limit: int = typer.Option(
+        20,
+        "--profile-limit",
+        help="Number of top statements to show in the --profile timing summary (default: 20).",
+    ),
     debug: bool = typer.Option(
         False,
         "--debug",
@@ -449,6 +454,7 @@ def main(
         output_dir=output_dir,
         progress=progress,
         profile=profile,
+        profile_limit=profile_limit,
         ping=ping,
         lint=lint,
         debug=debug,

{execsql2-2.11.0 → execsql2-2.12.0}/src/execsql/cli/lint.py

@@ -194,7 +194,7 @@ def _lint_cmdlist(
     for cmd in cmdlist.cmdlist:
         src = cmd.source
         lno = cmd.line_no
-        stmt = cmd.command.statement if cmd.command_type == "sql" else cmd.command.statement
+        stmt = cmd.command.statement
 
         if cmd.command_type == "sql":
             # SQL statements: check for variable references only

{execsql2-2.11.0 → execsql2-2.12.0}/src/execsql/cli/run.py

@@ -8,6 +8,7 @@ and drives the main execution loop.  Separated from argument parsing
 from __future__ import annotations
 
 import atexit
+from typing import Any
 import datetime
 import getpass
 import os
@@ -70,12 +71,14 @@ def _print_dry_run(cmdlist: object) -> None:
 # ---------------------------------------------------------------------------
 
 
-def _print_profile(profile_data: list[tuple]) -> None:
+def _print_profile(profile_data: list[tuple], limit: int = 20) -> None:
     """Print a per-statement timing summary to stdout.
 
     Args:
         profile_data: List of ``(source, line_no, command_type, elapsed_secs,
             command_text_preview)`` tuples collected during execution.
+        limit: Maximum number of top statements to display (default: 20).
+            All statements are included in totals regardless of this value.
     """
     if not profile_data:
         _console.print("[dim]Profile: no statements recorded.[/dim]")
@@ -84,9 +87,9 @@ def _print_profile(profile_data: list[tuple]) -> None:
     total_secs = sum(row[3] for row in profile_data)
     n = len(profile_data)
 
-    # Sort descending by elapsed time; show top 20 (or all if <= 20).
+    # Sort descending by elapsed time; show top `limit` (or all if <= limit).
     sorted_data = sorted(profile_data, key=lambda r: r[3], reverse=True)
-    display = sorted_data[:20]
+    display = sorted_data[:limit]
 
     _console.print()
     _console.print(f"[bold cyan]Profile:[/bold cyan] {n} statement{'s' if n != 1 else ''} in {total_secs:.3f}s")
@@ -114,10 +117,10 @@ def _print_profile(profile_data: list[tuple]) -> None:
             f"{preview_short}",
         )
 
-    if len(sorted_data) > 20:
-        omitted = len(sorted_data) - 20
+    if len(sorted_data) > limit:
+        omitted = len(sorted_data) - limit
         _console.print(
-            f"[dim]  ... {omitted} more statement{'s' if omitted != 1 else ''} not shown (top 20 by time)[/dim]",
+            f"[dim]  ... {omitted} more statement{'s' if omitted != 1 else ''} not shown (top {limit} by time)[/dim]",
         )
 
     _console.print()
@@ -128,7 +131,7 @@ def _print_profile(profile_data: list[tuple]) -> None:
 # ---------------------------------------------------------------------------
 
 
-def _ping_db(db) -> None:
+def _ping_db(db: Any) -> None:
     """Test connectivity for *db*, print connection details, and exit.
 
     Attempts to execute ``SELECT version()`` (or ``SELECT sqlite_version()``
@@ -156,7 +159,7 @@ def _ping_db(db) -> None:
             curs.close()
             if row and row[0]:
                 version_str = str(row[0]).split("\n")[0].strip()
-            break
+                break
         except Exception:
             continue
 
@@ -212,6 +215,7 @@ def _run(
     output_dir: str | None = None,
     progress: bool = False,
     profile: bool = False,
+    profile_limit: int = 20,
     ping: bool = False,
     lint: bool = False,
     debug: bool = False,
@@ -551,7 +555,7 @@ def _run(
     if debug:
         _state.step_mode = True
 
-    _execute_script_direct(conf, profile=profile)
+    _execute_script_direct(conf, profile=profile, profile_limit=profile_limit)
 
 
 # ---------------------------------------------------------------------------
@@ -610,7 +614,7 @@ def _execute_script_textual_console(conf: ConfigData) -> None:
     _state.exec_log.log_exit_end()
 
 
-def _execute_script_direct(conf: ConfigData, *, profile: bool = False) -> None:
+def _execute_script_direct(conf: ConfigData, *, profile: bool = False, profile_limit: int = 20) -> None:
     """Run runscripts() in the current (main) thread — used when Textual is not active.
 
     Args:
@@ -618,6 +622,8 @@ def _execute_script_direct(conf: ConfigData, *, profile: bool = False) -> None:
         profile: When ``True``, print a per-statement timing summary after the
             script completes.  Timing data must already have been activated on
             ``_state.profile_data`` before this function is called.
+        profile_limit: Maximum number of top statements to display in the
+            profile summary (default: 20).
     """
     import execsql.state as _state
     import execsql.utils.gui as _gui
@@ -644,7 +650,7 @@ def _execute_script_direct(conf: ConfigData, *, profile: bool = False) -> None:
                 gui_console_off()
         _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
         if profile and _state.profile_data is not None:
-            _print_profile(_state.profile_data)
+            _print_profile(_state.profile_data, limit=profile_limit)
         sys.exit(exc.code)
     except ConfigError:
         raise
@@ -672,7 +678,7 @@ def _execute_script_direct(conf: ConfigData, *, profile: bool = False) -> None:
             gui_console_off()
     _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
     if profile and _state.profile_data is not None:
-        _print_profile(_state.profile_data)
+        _print_profile(_state.profile_data, limit=profile_limit)
     _state.exec_log.log_exit_end()
 
 

execsql2-2.12.0/src/execsql/debug/__init__.py

@@ -0,0 +1,6 @@
+"""Debug utilities for execsql.
+
+This package contains interactive debugging tools for execsql scripts:
+
+- :mod:`execsql.debug.repl` — the ``BREAKPOINT`` metacommand REPL.
+"""