tsql-fabric-debugger 0.3.2__tar.gz

tsql_fabric_debugger-0.3.2/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+mutants/
+.mypy_cache/
+.ruff_cache/
+*.csv
+.DS_Store

tsql_fabric_debugger-0.3.2/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+## 0.3.2 — 2026-09-07
+
+- **Result sets grouped per step**: the `tsqlFabricResultSet` DAP event now
+  carries `{line, sets: [{columns, rows, truncated}]}` — one event per step,
+  with **all** of that step's result sets under `sets`. A statement that
+  returns several result sets is delivered together instead of only the last
+  one. (Event shape change; consumers should read `sets`.)
+
+## 0.3.1 — 2026-09-07
+
+Hardening round (concurrency + privacy review):
+
+- **`save_state()` privacy**: the docstring and the on-save message now warn
+  that the JSON file is plain-text and may contain warehouse/production data —
+  store it safely and delete when done.
+- **Teardown robustness**: `dap.py` `_close_root` detaches the debugger before
+  closing, so a `SIGTERM`/`SIGINT` arriving mid-`close()` cannot leave a
+  half-torn-down session (idempotent even under `BaseException`).
+- **Docs hygiene**: example procedure/parameter names generalized
+  (`dbo.load_sales` / `@year`) across README, docstrings and the CHANGELOG —
+  no internal/proprietary identifiers in the published package.
+
+## 0.3.0 — 2026-09-04
+
+Debugger parity with mainstream tools (pdb/debugpy, Chrome DevTools), driven
+by a feature-gap analysis:
+
+- **`step_out()`**: finish the current context and stop one level up — the
+  remaining sub-steps of an expanded IF/WHILE (a WHILE stops at its
+  re-evaluation step), or the whole active child debugger (OUTPUTs
+  collected). Honors breakpoints on the way.
+- **`eval(expr)`**: one-shot server-side evaluation of a T-SQL expression
+  with the current variables — the single-use counterpart of `watch()`.
+- **`stack()`**: the frame stack — procedures in the nested-EXEC chain plus
+  the expanded-block frames (loop iteration included).
+- **`stop_on_error="any"`**: `run_all()`/`run_until()`/`step_out()` also
+  pause on errors a CATCH handled (after the CATCH emulation) — the
+  "break on caught exceptions" of DevTools.
+- **`break_at(..., hits=N, once=True)`**: hit-count breakpoints (fire from
+  the Nth pass) and one-shot breakpoints. `breaks()` now returns
+  `{line: {"condition", "hits", "once", "count"}}` (was `{line: condition}`).
+- **Logpoints**: `log_at(line, expr)` echoes a value when a line executes,
+  without ever stopping (`clear_logpoints()`, `logpoints()`). Fires inside
+  auto-expanded blocks and on IF/WHILE headers.
+- **DAP adapter**: `tsql-fabric-dap` speaks the Debug Adapter Protocol over
+  stdio — debug the `.sql` visually from VS Code (via a DAP bridge
+  extension), nvim-dap or any DAP client: gutter/conditional/hit-count
+  breakpoints, step over/into/out, variables pane, hover/REPL evaluation,
+  CATCH-handled-error exception filter. Never commits; disconnect rolls back.
+  Result sets a step returns are printed to the Debug Console as a text table
+  and emitted as a `tsqlFabricResultSet` custom event
+  (`{line, columns, rows, truncated}`) for clients that render a grid.
+
+Hardening from a 4-persona review (data engineer, data analyst, QA, DBA):
+expression validation that blocks batch-breaking typos (comments, `;`,
+unbalanced quotes) in watch/eval/logpoint/break conditions; broken breakpoint
+conditions pause instead of crashing; `reset()` zeroes breakpoint hit
+counters; a WHILE hitting `max_loop_iterations` pauses `run_all()` instead of
+silently running post-loop steps on partial state; `eval()` failures no
+longer pollute `ERROR_MESSAGE()`; logpoints are disarmed during CATCH
+emulation.
+
+Robustness against orphaned warehouse sessions (a debugger process killed
+without close() leaves its transaction open, holding locks):
+
+- **`kill_orphan_sessions(server, database, min_idle_seconds=900)`** (and
+  `tsql-debug --kill-orphans [--min-idle N]`): KILL library-tagged sessions
+  sleeping with an open transaction past the idle threshold, so the server
+  rolls them back and releases their locks.
+- The `tsql-debug` and `tsql-fabric-dap` entry points install a SIGTERM
+  handler: a polite kill runs close()+ROLLBACK instead of orphaning the
+  session (SIGKILL still needs the janitor above).
+
+
+## 0.2.3 — 2026-09-04
+
+Usability (driven by end-user feedback):
+
+- **`proc_name=`**: debug a DEPLOYED procedure by name — no more manual
+  `OBJECT_DEFINITION` boilerplate. `TSQLDebugger(proc_name="dbo.load_sales", ...)`
+  and `run_procedure(proc_name=..., ...)` fetch the source straight from the
+  warehouse on a short-lived session (a name without schema resolves to dbo).
+  Exactly one of `sql_file`/`sql_text`/`proc_name` must be given.
+- **`fetch_source(proc_name, server, database)`** is now public, for when you
+  want the source text itself.
+
+## 0.2.2 — 2026-09-04
+
+Usability (driven by end-user feedback):
+
+- **`run_all(into=True)`**: run the whole procedure the `step_into()` way —
+  every `IF`/`WHILE` is expanded, so each branch taken and each loop
+  iteration becomes its own logged step. Replaces the low-level
+  `while not dbg._finished and dbg._pos < len(dbg._steps): dbg.step_into()`
+  loop with a single call. Statements that are not blocks (and loops with
+  `BREAK`/`CONTINUE`) run whole, exactly as `run_all()` already does. Fully
+  backward compatible — the default is `into=False`.
+- **`show_error()` / `last_error()`**: inspect a failure without scanning the
+  log by hand. `last_error()` returns the most recent ERROR log entry (or
+  `None`); `show_error()` runs `show_detail()` on it — replacing the
+  `erro = next(e for e in dbg._log if e["status"] == "ERROR");
+  dbg.show_detail(erro["step"])` idiom with a single call.
+
+## 0.2.1 — 2026-09-04
+
+Usability (driven by end-user feedback that the API was too low-level):
+
+- **`summarize(log)`**: a one-glance verdict of a run — "OK, all N steps ran"
+  or "FAILED at step X (line Y): <message>", noting when a CATCH handled it.
+  Returns the facts as a dict (`ok`, `steps`, `error_step`, `error_line`,
+  `error`, `handled`). Pairs with `run_procedure` for a simple "run and tell
+  me what happened" flow, no step-by-step needed.
+- **`find_step(contains=... | line=...)`**: locate a step by a text fragment
+  or a file line, instead of hand-writing
+  `next(i for i, s in enumerate(dbg._steps, 1) if ...)`.
+- **`jump_to` and `run_until` now accept a text fragment or `line=<n>`**, not
+  only a step number — `dbg.run_until("MAX(SEQREC)")`, `dbg.jump_to(line=40)`.
+  Fully backward compatible (a number still works exactly as before).
+
+## 0.2.0 — 2026-09-03
+
+Productivity release — the items that turn a step executor into a debugger:
+
+- **Nested EXEC step-into**: `step_into()` on `EXEC schema.proc ...` fetches
+  the child's source from the warehouse and returns a child debugger that
+  shares the parent's session/transaction; OUTPUT arguments and @@ROWCOUNT
+  copy back on completion, and an unhandled child error propagates to the
+  parent's CATCH exactly like the real EXEC. `abort_child()` discards.
+  Dynamic SQL/sp_executesql/expression arguments fall back to step-over.
+
+- **Breakpoints**: `break_at(line, condition=None)` stops `run_all()` BEFORE
+  the matching step; file lines are stable across expansions, conditions run
+  server-side with the current variables, and `run_all()` auto-expands
+  IF/WHILE blocks that contain a breakpoint. `clear_breaks()`, `breaks()`.
+- **Watches**: `watch(expr, name)` appends expressions to every capture
+  batch — values echo after each step and via `watches()`. `unwatch()`.
+- **State snapshots**: `save_state(path)` / `load_state(source)` serialize
+  the variable environment (datetime/Decimal/bytes-safe JSON) — pair with
+  `jump_to()` to resume a session another day.
+- **Replay**: `reset()` rolls back, restores the pristine step plan and the
+  initial parameter values, and replays from step 1 on a fresh connection.
+- **`;`-less T-SQL**: statements now also split on the next statement-starting
+  keyword at level 0, with legal mid-statement continuations respected
+  (INSERT..SELECT, UPDATE..SET, WITH..consumer; MERGE never auto-splits).
+  Legacy code without terminators debugs statement by statement.
+- **Execution diffs**: `diff_logs(log_a, log_b)` aligns two runs by
+  (line, kind) and reports only the divergences.
+- **Large-value offload** (`offload_threshold`): strings above the threshold
+  live in a server-side session temp table and are hydrated into variables
+  per batch — uploaded once per change instead of re-sent on every step
+  (graceful fallback if the endpoint lacks temp tables).
+- **`lock_timeout`**: a session opened with `lock_timeout=<seconds>` fails a
+  lock-blocked statement fast (error 1222) instead of hanging behind another
+  session's lock — the anti-hang for orphaned-transaction locks (constructor,
+  `run_script`, and `--lock-timeout` on the CLI). It bounds the wait; only
+  the server can reap the orphan itself.
+- **Memory bounds**: `history_batches=N` prunes old SUCCESS payloads
+  (batch text/result sets) keeping the last N and every ERROR; `step_into`
+  on WHILE now prunes the previous iteration's executed sub-steps, so long
+  loops no longer grow the step list per iteration.
+- **Test coverage**: a programmable fake pyodbc session (`tests/conftest.py`)
+  drives the engine offline, adding 32 engine tests and bringing `engine.py`
+  into the mutation-testing scope (previously scanner/parser only).
+
+Post-implementation adversarial review (second pass) fixed: UNION/EXCEPT/
+INTERSECT no longer split a statement (with or without ';'); a child ending
+in error propagates to the parent CATCH instead of reporting SUCCESS;
+breakpoints on a block's own header line stop before the block (and blocks
+containing breakpoints auto-expand only for BODY lines); WHILE loops with
+BREAK/CONTINUE containing a breakpoint stop before the loop instead of
+silently running through; detached children cannot silently reconnect as
+independent sessions; child guards on step_into/run_step/run_until; table
+variables are rejected as EXEC arguments; the server-side offload table is
+namespaced per debugger instance (parent/child same-named variables never
+collide) and its creation state travels between parent and child; nested
+loop pruning handles inner loops; reset()/close() detach an active child.
+
+## 0.1.0 — 2026-09-03
+
+First release.
+
+Fixes from the four-lens pre-publish review (internal review —
+data analyst, data engineer, DBA and developer/QA perspectives):
+
+- **CLI**: exit-code computation no longer crashes on the base install
+  (without pandas); quoted `--param` values force strings (leading zeros,
+  literal "NULL"); strict int/float inference (no `1e5`/`nan`/`inf` floats);
+  missing file returns exit 2 with a clean message; loose-script fallback
+  warns and honors `--commit`; `--step-timeout` exposed; documented exit
+  codes.
+- **Engine correctness**: post-CATCH skip covers nested TRY blocks
+  (catch-id stack); connection/internal failures are echoed as `[FATAL]` and
+  re-raised instead of silently finishing; the error entry (not the CATCH's
+  last entry) is returned to the caller; `DECLARE` and `RETURN` inside the
+  emulated CATCH work; bare `THROW` in the CATCH aborts like the real
+  re-raise; step_into condition failures route through the CATCH like
+  step(); the full `ERROR_*()` family is emulated; session `SET` options
+  persist (unparameterized batches); result sets produced before a failure
+  are kept.
+- **Parser**: `IF ... ELSE` without `;` before the ELSE; `COPY`/`GRANT`/
+  `DENY`/`REVOKE`/`DBCC` end an IF condition; bodies without an outer
+  `BEGIN...END` (incl. starting at `BEGIN TRY`) parse correctly; catch
+  registration is idempotent across WHILE re-expansions; multi-encoding
+  `.sql` reading (UTF-8/BOM, UTF-16 BOM, cp1252).
+- **Session lifecycle (DBA)**: context-manager support (`with ... as dbg:`);
+  exception-safe `close()`; public `rollback()`; Ctrl+C cancels the running
+  statement server-side and rolls back; ad-hoc `sql()` errors roll back and
+  are capped at 10k rows; transaction-control detection now covers string
+  literals (dynamic SQL) and flags opaque `EXEC` calls; `autocommit=True`
+  echoes a persistence warning; `APP=tsql-fabric-debugger` + `LoginTimeout`
+  on the connection string.
+- **Observability**: `rows_affected` is `None` when not measured (no more
+  stale values); `post_rollback` column marks steps after a rollback;
+  `show_detail()` prints untruncated changed variables and the raw driver
+  error; `last_results()` DataFrames carry `attrs["truncated"]`;
+  multi-message SQL errors are joined instead of truncated; loose scripts
+  run inside a transaction with ROLLBACK by default and split via the
+  library's scanner; CSV saving works without pandas and uses utf-8-sig.
+
+- `TSQLDebugger`: interactive procedure debugging without touching the
+  `.sql` — `step()`, `step_into()` (IF/WHILE statement by statement, with
+  the condition evaluated server-side), `run_until()`, `jump_to()`,
+  `run_step()`, `set_var()`, `show_vars()`, `sql()`, `show_detail()`,
+  `last_results()`, `set_log_level()`.
+- State preserved between steps (DECLARE + re-injection through pyodbc
+  parameters + capture); `@@ROWCOUNT` and `ERROR_MESSAGE()` keep their
+  cross-batch semantics.
+- `BEGIN CATCH` emulated; DECLARE inside blocks stays visible (batch scope).
+- Transaction with ROLLBACK by default; `close(commit=True)` is explicit.
+- Entra ID authentication: Fabric notebook (notebookutils) or `az login`
+  (AzureCliCredential).
+- Batch mode (`run_procedure`), loose scripts (`run_script`) and a CLI
+  (`tsql-debug`).
+- Mutation testing with mutmut plus a snapshot/invariant hardening suite.
+
+Semantics fixes from the pre-release gap analysis
+(internal gap analysis):
+
+- `RETURN` ends the debug — including when it runs inside an atomic block
+  (detected by the missing capture).
+- One CATCH block per `BEGIN TRY` (`catch_id` per step); after emulating the
+  CATCH, the debug skips the rest of that TRY and continues after
+  `END CATCH`, like T-SQL does.
+- Table variables: declared in every batch, excluded from re-injection and
+  capture, with a warning that their content does not survive across steps.
+- `BEGIN TRAN` is no longer treated as a `BEGIN...END` block opener
+  (procedures with explicit transactions used to break the parse) and inner
+  `COMMIT`/`ROLLBACK`/`BEGIN TRAN`/`SAVE TRAN` raise a warning.
+- Result sets produced by the procedure itself are captured
+  (`last_results()`, `result_sets` column in the log) instead of discarded.
+- `step_timeout` (seconds per step) in the constructor.

tsql_fabric_debugger-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RedRex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tsql_fabric_debugger-0.3.2/PKG-INFO

@@ -0,0 +1,358 @@
+Metadata-Version: 2.5
+Name: tsql-fabric-debugger
+Version: 0.3.2
+Summary: Step-by-step debugger for T-SQL stored procedures on the Microsoft Fabric Warehouse
+Project-URL: Homepage, https://github.com/redrex-tech/tsql_fabric_debugger
+Project-URL: Repository, https://github.com/redrex-tech/tsql_fabric_debugger
+Project-URL: Documentation, https://github.com/redrex-tech/tsql_fabric_debugger/blob/main/docs/DOCUMENTATION.md
+Project-URL: Changelog, https://github.com/redrex-tech/tsql_fabric_debugger/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/redrex-tech/tsql_fabric_debugger/issues
+Author: RedRex
+License-Expression: MIT
+License-File: LICENSE
+Keywords: debugger,fabric,microsoft-fabric,sql-server,tsql,warehouse
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyodbc>=5.0
+Provides-Extra: all
+Requires-Dist: azure-identity>=1.15; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Requires-Dist: sqlparse>=0.5; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: azure-identity>=1.15; extra == 'dev'
+Requires-Dist: mutmut>=3.2; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: azure-identity>=1.15; extra == 'local'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# tsql-fabric-debugger
+
+Step-by-step debugger for T-SQL stored procedures on the **Microsoft Fabric
+Warehouse** — without changing a single line of your `.sql`.
+
+> This README is the quick tour. The deep dive — why Fabric has no native
+> debugger, how the state engine works inside, the full API reference, and
+> usage from a local machine, a Fabric notebook or AI agents/MCP — lives in
+> [`docs/DOCUMENTATION.md`](docs/DOCUMENTATION.md).
+
+## Why
+
+The Fabric Warehouse has no T-SQL debugger: no breakpoints, no watch, no way
+to run half a procedure. A whole procedure is a single statement to any SQL
+client, and `DECLARE` variables die at the end of each batch — so "run one
+piece at a time" doesn't work naively.
+
+This library solves that by parsing the procedure **in memory**: it slices
+the body into steps and preserves variable state between them. Each step runs
+as one batch on the same session:
+
+```sql
+DECLARE <all variables>;
+SELECT @a = ?, @b = ?, ...;        -- state re-injection (pyodbc parameters)
+<original statement, untouched>;
+SELECT '__hcap__', @@ROWCOUNT, @a, @b, ...;   -- capture of the new state
+```
+
+`@@ROWCOUNT` and `ERROR_MESSAGE()` are rewritten to preserve cross-batch
+semantics, and the procedure's `BEGIN CATCH` is emulated when a step fails.
+Everything runs inside a transaction with **ROLLBACK at the end by
+default** — nothing persists in the Warehouse unless you ask for it.
+
+## Installation
+
+```bash
+pip install tsql-fabric-debugger            # Fabric notebook
+pip install "tsql-fabric-debugger[local]"   # local machine (az login)
+pip install "tsql-fabric-debugger[all]"     # + pandas and sqlparse
+```
+
+Outside Fabric you need the **ODBC Driver 18 for SQL Server** installed and
+a valid `az login`.
+
+## IDE debugging (DAP)
+
+`tsql-fabric-dap` speaks the Debug Adapter Protocol over stdio: point any DAP
+client (VS Code, nvim-dap, ...) at it and debug the `.sql` visually — gutter
+breakpoints, step over/into/out, variables pane, hover evaluation. Never
+commits; disconnect rolls back.
+
+Rows a step returns are surfaced two ways: printed as a text table to the
+Debug Console, and emitted as a `tsqlFabricResultSet` custom DAP event
+(`{line, sets: [{columns, rows, truncated}]}` — one event per step, carrying
+all of that step's result sets) so a client can render them in a grid — the
+VS Code extension shows a **Result Set** panel beside the editor.
+
+A **VS Code extension** that wires this up (F5 on a `.sql`, no launch.json
+needed) lives in [`editors/vscode/`](editors/vscode/) — preview/MVP.
+
+## Interactive usage
+
+```python
+from tsql_fabric_debugger import TSQLDebugger
+
+dbg = TSQLDebugger(
+    "prd_load.sql",                        # the original .sql, untouched
+    params={"@year": 2015},                # test values
+    server="<endpoint>.datawarehouse.fabric.microsoft.com",
+    database="my_warehouse",
+)
+```
+
+No local `.sql`? Debug the **deployed** procedure by name — the source is
+fetched straight from the warehouse (`OBJECT_DEFINITION`):
+
+```python
+dbg = TSQLDebugger(proc_name="dbo.load_sales",
+                   params={"@year": 2015}, server=..., database=...)
+```
+
+Prefer the context-manager form — it guarantees ROLLBACK + close even when an
+exception interrupts the session, so no orphan transaction is left holding
+locks on the warehouse:
+
+```python
+with TSQLDebugger("prd_load.sql", params={"@year": 2015},
+                  server=..., database=...) as dbg:
+    dbg.run_all()
+```
+
+```python
+
+dbg.list_steps()      # list the numbered steps, without executing
+dbg.step()            # run the next step ("step over": whole IF/WHILE)
+dbg.step_into()       # step into an IF/WHILE: evaluates the condition
+                      #   server-side, picks the branch, yields sub-steps
+dbg.step_out()        # finish the current block/child and stop one level up
+dbg.run_all(into=True)   # run to the end the step_into() way: every IF/WHILE
+                         #   expanded, each loop iteration its own logged step
+child = dbg.step_into()   # on an `EXEC dbo.child ...` step: fetches the child's
+                          #   source from the warehouse and returns a CHILD
+                          #   debugger sharing this session; debug it, then the
+                          #   parent's next step() collects the OUTPUT values
+                          #   (an unhandled child error reaches the parent CATCH)
+dbg.run_until(15)     # run up to step 15 (breakpoint)
+dbg.run_until("MAX(SEQREC)")   # ...or up to the step whose command has that text
+dbg.jump_to(line=40)  # ...or position by file line; find_step() returns the number
+dbg.show_vars()       # state of every variable (OUTPUT params included)
+dbg.eval("@a * @b")   # evaluate one T-SQL expression with the CURRENT variables
+dbg.stack()           # where am I? procedures + expanded blocks + iteration
+dbg.sql("SELECT COUNT(*) FROM dbo.movements")   # query on the SAME session
+dbg.jump_to(17)       # move the cursor without running earlier steps
+dbg.set_var("@sqlSrc", "...")                   # build state by hand
+dbg.run_step(17)      # run ONLY step 17 (does not move the cursor)
+dbg.set_log_level("full")   # full command + SQL batch on errors
+dbg.show_detail()     # last step in full (command + error + batch)
+dbg.show_error()      # the step that FAILED, in full — the one-call idiom
+                      #   after a failed run_all() (last_error() for the dict)
+dbg.last_results()    # result sets the procedure itself produced
+dbg.watch("(SELECT COUNT(*) FROM stg.movements)", "stg")   # tracked every step
+dbg.log_at(8, "@fat")               # logpoint: print the value there, never stop
+dbg.clear_logpoints()               # remove one logpoint (by line) or all
+dbg.break_at(42, "@code = 31000")   # run_all() stops there when it's true
+dbg.break_at(8, hits=4)             # ...or from the 4th pass on (once=True: fire once)
+dbg.save_state("st.json")           # variables snapshot (JSON) ...
+dbg.load_state("st.json")           # ... resume tomorrow with jump_to()
+dbg.reset()           # rollback + replay from step 1 on a fresh session
+dbg.close()           # ROLLBACK and close (commit=True to persist)
+
+from tsql_fabric_debugger import diff_logs
+diff_logs(log_2015, log_2016)       # divergences between two runs
+```
+
+Each step shows the line in the original file, the variables that changed
+and, on errors, the clean SQL Server message:
+
+```
+[  5] line   19 | ok   | SELECT @offset = ISNULL(MAX(id), 0) FROM dbo.movements
+      -> @offset = 184230
+[  6] line   21 | ok   | condition: @year < 2018
+      -> condition = True
+```
+
+## Batch mode and CLI
+
+```python
+from tsql_fabric_debugger import run_procedure, summarize
+
+log = run_procedure("prd_load.sql", params={"@year": 2015},
+                    server=..., database=..., save_csv="log.csv")
+summarize(log)   # "OK — all N steps ran" or "FAILED at step X (line Y): <msg>"
+```
+
+`summarize(log)` is the "just tell me what happened" verdict — it prints one
+line and returns the facts (`ok`, `error_step`, `error_line`, `error`,
+`handled`), so you rarely need the step-by-step API for a quick check.
+
+```bash
+tsql-debug prd_load.sql --param @year=2015 \
+    --server <endpoint> --database my_warehouse --csv log.csv
+```
+
+Server and database can also come from the `FABRIC_TSQL_SERVER` and
+`FABRIC_TSQL_DATABASE` environment variables. Files without a
+`CREATE PROCEDURE` go through `run_script()` — split on `GO` lines when
+present, otherwise per statement via the library's own scanner (a `;` inside
+a string never splits) — also inside a transaction with ROLLBACK by default.
+On the CLI, `--param` values can be quoted (`--param @code='00123'`) to force
+a string and keep leading zeros; unquoted values infer int/float strictly
+(no scientific notation, no `nan`/`inf`). Exit codes: 0 = clean, 1 = at
+least one step recorded an ERROR (even if the procedure's CATCH handled it),
+2 = usage/file error. `.sql` files may be UTF-8 (with or without BOM),
+UTF-16 with BOM (SSMS default) or cp1252.
+
+### Constructor parameters
+
+| Parameter | Default | Purpose |
+|---|---|---|
+| `params` | `{}` | test values for procedure parameters (`{"@year": 2015}`) |
+| `autocommit` | `False` | `True` = every step persists immediately (a warning is echoed; `close()` undoes nothing) |
+| `log_level` | `"simple"` | `"full"` prints whole commands, untruncated variables and the SQL batch on errors |
+| `stop_on_error` | `True` | stop the sequential run on an unhandled error (`False`: continue past errors; `"any"`: also pause on CATCH-handled errors) |
+| `step_timeout` | `None` | per-step query timeout in seconds (`None` = unlimited) |
+| `lock_timeout` | `None` | seconds to wait for a lock before failing (error 1222) instead of hanging behind another session — the anti-hang for orphaned-transaction locks; does not prevent the orphan, only bounds the wait |
+| `max_result_rows` | `50` | rows captured per result set the procedure produces |
+| `max_loop_iterations` | `1000` | guard for `step_into()` on WHILE loops |
+| `preview_chars` | `500` | command truncation in the log's `command` column |
+| `offload_threshold` | `200_000` | strings above this length are kept in a server-side session table and hydrated per batch (uploaded once per change) instead of re-sent on every step |
+| `history_batches` | `None` | keep the heavy per-step payloads (batch text, result sets) only for the last N entries — ERROR entries always keep everything |
+| `echo` | `print` | console output sink |
+
+### Log columns
+
+`log_df()` / `--csv` (procedure mode): `step`, `line` (file line), `kind`
+(`stmt`/`declare`/`if_block`/`while_block`/`cond`/`exec`/`eval`/`return`/`throw`/`params`),
+`status` (`SUCCESS`/`ERROR`/`REGISTERED`), `rows_affected` (only for captured
+steps; `None` otherwise), `duration_s`, `command` (truncated preview),
+`changed_vars` (truncated — `show_detail()` has the full values),
+`result_sets`, `post_rollback` (True for steps that ran after an
+error-triggered rollback), `error`. The script mode (`run_script`) logs a
+smaller schema: `step`, `status`, `rows_affected`, `duration_s`, `command`,
+`error`.
+
+## Security
+
+- **Entra ID** authentication only: the notebook token on Fabric,
+  `AzureCliCredential` elsewhere. No passwords, ever.
+- Execution inside a transaction with ROLLBACK by default;
+  `close(commit=True)` is an explicit decision.
+- Variable re-injection through pyodbc parameters — no value concatenation
+  into SQL.
+- Only debug files you trust: the `.sql` **is** code executed under your
+  identity, and rollback-by-default is a convenience, not a security
+  boundary (a `COMMIT` hidden in dynamic SQL persists — the parser warns
+  about literal and string-embedded transaction control, and flags `EXEC`
+  calls it cannot see into).
+- Console output and CSV logs contain **real data** from the warehouse
+  (variable values, result-set rows) — treat them like the data itself.
+
+## Operational notes (read before debugging a shared warehouse)
+
+- **Required permissions**: the debugger does NOT `EXECUTE` the procedure —
+  it runs the body's statements directly under your identity. You need
+  SELECT/INSERT/UPDATE/DELETE on every object the procedure touches
+  (ownership chaining does not apply), and row-level security/column masks
+  apply to *you*, which can make results diverge from a real execution.
+- **Long transactions hold locks**: the debug session keeps one transaction
+  open from the first step until `close()`. Locks from completed steps are
+  retained the whole time — an interactive session parked for an hour blocks
+  concurrent writers and DDL on the touched tables. Debug in a dev
+  warehouse/schema, use the `with` form, and `close()` as soon as you are
+  done. `step_timeout` bounds a *running* statement only.
+- The session identifies itself as `tsql-fabric-debugger` in
+  `sys.dm_exec_sessions.program_name`.
+- Instances are **not thread-safe** (one session, one shared environment).
+- Memory: the full text of every executed batch is kept for `show_detail()`;
+  very long sessions over procedures with multi-MB dynamic SQL grow
+  accordingly.
+
+## Semantics preserved
+
+- `RETURN` ends the debug wherever it appears — top level, guard clause
+  inside an `IF`, or inside the emulated `CATCH` — just as it would end the
+  real execution.
+- Each `BEGIN TRY` gets **its own** emulated `CATCH`; after the CATCH handles
+  the error, the debug skips the rest of that TRY (nested TRY blocks
+  included) and continues after `END CATCH` — the same T-SQL semantics. A
+  `THROW` inside the CATCH aborts the debug like the real re-raise would.
+- The full `ERROR_*()` family works in the emulated CATCH: `ERROR_MESSAGE()`,
+  `ERROR_NUMBER()`, `ERROR_PROCEDURE()`, `ERROR_LINE()` (the file line of the
+  failing step), plus `ERROR_SEVERITY()`/`ERROR_STATE()` as RAISERROR-style
+  defaults (16/1) — the driver does not expose the real ones.
+- `DECLARE` inside the CATCH (the classic `DECLARE @msg = ERROR_MESSAGE();`)
+  is emulated correctly.
+- `IF x SET a = 1 ELSE SET a = 2` — no `;` before the `ELSE` — parses and
+  steps correctly.
+- Bodies without an outer `BEGIN...END` (bare statements, or starting
+  straight at `BEGIN TRY`) are supported.
+- Session `SET` options (`NOCOUNT`, `XACT_ABORT`, ...) run unparameterized so
+  they persist for the following steps, as they would in a real execution.
+- `SELECT`s produced by the procedure itself (diagnostics, samples) are
+  captured and displayed (`last_results()`), not discarded — including the
+  ones produced before a step failed.
+- Procedures with inner `COMMIT`/`BEGIN TRAN` raise a parse-time warning —
+  including transaction keywords spotted **inside string literals** (dynamic
+  SQL); `EXEC` calls are flagged as opaque.
+- After an error-triggered rollback, the debug warns that following steps run
+  against post-rollback data, and marks them with `post_rollback=True` in the
+  log.
+- `step_timeout=<seconds>` in the constructor bounds every step; Ctrl+C
+  cancels the running statement server-side and rolls back.
+
+## Practical limits
+
+- **Table variables**: `DECLARE @t TABLE (...)` is declared in every batch
+  (references compile) and triggers a warning, but its **content does not
+  survive across steps** — step over the block that fills and consumes it,
+  or use `#temp`.
+- `step_into` on a `WHILE` with `BREAK`/`CONTINUE` falls back to atomic mode
+  (with a warning).
+- `GOTO`, cursors and `WAITFOR` are out of scope.
+- A single failing statement keeps the previous variable values (same T-SQL
+  semantics); when an atomic block fails, use `jump_to(n)` + `step_into()`
+  to pinpoint the exact statement. After an error, the ROLLBACK undoes the
+  data effects of earlier steps, but the captured variables remain.
+
+## Tests
+
+```bash
+pytest                       # unit (offline, no warehouse)
+FABRIC_TSQL_SERVER=... FABRIC_TSQL_DATABASE=... pytest -m integration
+```
+
+### Mutation testing
+
+Suite quality is measured with [mutmut](https://mutmut.readthedocs.io/):
+
+```bash
+pip install "tsql-fabric-debugger[dev]"
+mutmut run        # ~1,700 mutants over scanner.py and parser.py
+mutmut results    # survivors; `mutmut show <id>` prints the diff
+```
+
+The scope covers `scanner`, `parser` **and `engine`** — the engine is
+exercised offline through a programmable fake pyodbc session
+(`tests/conftest.py`), so its logic (state capture, error routing, CATCH
+emulation, breakpoints, nested EXEC, offload) is mutation-tested without a
+warehouse. `connection`/`runner`/`cli` stay out (thin driver/warehouse
+glue). `tests/test_mutation_hardening.py` pins exact parser/scanner behavior
+and `tests/test_engine_offline.py` drives the engine; the remaining
+survivors are dominated by equivalent mutants.
+
+## License
+
+MIT © RedRex