sql-sp-harness 1.0.0__py3-none-any.whl

sql_sp_harness/__init__.py

@@ -0,0 +1,4 @@
+"""T-SQL stored procedure debug harness — safe SQL test-harness generator."""
+
+__version__ = "1.0.0"
+__pypi_name__ = "sql-sp-harness"

sql_sp_harness/__main__.py

@@ -0,0 +1,4 @@
+from sql_sp_harness.cli import main
+
+if __name__ == "__main__":
+    main()

sql_sp_harness/cli.py

@@ -0,0 +1,297 @@
+"""CLI for sql-sp-harness."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from sql_sp_harness import __version__
+from sql_sp_harness.console import supports_color
+from sql_sp_harness.inventory import inventory_from_sql
+from sql_sp_harness.transform import transform_sql
+
+APP_HELP = """
+Turn T-SQL stored procedures into safe, runnable debug scripts.
+
+\b
+Commands:
+  analyze    See what a procedure does (DML, TRY/CATCH, loops, variables)
+  generate   Create a debug harness script safe to run on a dev database
+
+\b
+Quick start:
+  sql-sp-harness analyze -i MyProc.sql
+  sql-sp-harness generate -i MyProc.sql -o MyProc_debug.sql
+
+\b
+More help:
+  sql-sp-harness analyze --help
+  sql-sp-harness generate --help
+"""
+
+app = typer.Typer(
+    name="sql-sp-harness",
+    help=APP_HELP,
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.command("version")
+def cmd_version() -> None:
+    """Print package version."""
+    typer.echo(__version__)
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("sql-sp-harness")
+    except Exception:
+        return __version__
+
+
+@app.callback()
+def _root_callback(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    """T-SQL stored procedure debug harness generator."""
+    if version:
+        typer.echo(f"sql-sp-harness {_version()}")
+        raise typer.Exit()
+
+
+def _read_input(path: Optional[Path]) -> str:
+    if path is None or str(path) == "-":
+        return sys.stdin.read()
+    return path.read_text(encoding="utf-8")
+
+
+def _write_output(path: Optional[Path], content: str) -> None:
+    if path is None or str(path) == "-":
+        sys.stdout.write(content)
+        return
+    path.write_text(content, encoding="utf-8")
+
+
+def _run_analyze(
+    input: Path,
+    report: Optional[Path],
+    plain: bool,
+    full: bool,
+) -> None:
+    sql = _read_input(input)
+    inv = inventory_from_sql(sql)
+    colorize = supports_color() and not plain and report is None
+    text = inv.to_text(colorize=colorize, non_zero_only=not full)
+    if report:
+        report.write_text(text + "\n", encoding="utf-8")
+        typer.echo(f"Report written to {report}")
+    else:
+        typer.echo(text)
+
+
+@app.command("analyze")
+def analyze_cmd(
+    input: Path = typer.Option(
+        ...,
+        "--input",
+        "-i",
+        help="Input .sql file (use - for stdin).",
+    ),
+    report: Optional[Path] = typer.Option(
+        None,
+        "--report",
+        "-r",
+        help="Write plain-text report to file (no ANSI colors).",
+    ),
+    plain: bool = typer.Option(
+        False,
+        "--plain",
+        help="Disable ANSI colors on terminal output.",
+    ),
+    full: bool = typer.Option(
+        False,
+        "--full",
+        help="Show all sections, including zero counts.",
+    ),
+) -> None:
+    """
+    Analyze a stored procedure and show what it does.
+
+    Summarizes DML against real tables, TRY/CATCH blocks, loops, SET statements,
+    and other structural detail — useful before generating a debug harness.
+    """
+    _run_analyze(input, report, plain, full)
+
+
+@app.command("inventory", hidden=True)
+def inventory_cmd(
+    input: Path = typer.Option(
+        ...,
+        "--input",
+        "-i",
+        help="Input .sql file (use - for stdin).",
+    ),
+    report: Optional[Path] = typer.Option(
+        None,
+        "--report",
+        "-r",
+        help="Write plain-text report to file (no ANSI colors).",
+    ),
+    plain: bool = typer.Option(
+        False,
+        "--plain",
+        help="Disable ANSI colors on terminal output.",
+    ),
+    full: bool = typer.Option(
+        False,
+        "--full",
+        help="Show all sections, including zero counts.",
+    ),
+) -> None:
+    """Deprecated alias for analyze."""
+    _run_analyze(input, report, plain, full)
+
+
+def _run_generate(
+    input: Path,
+    output: Optional[Path],
+    trace_style: str,
+    no_stub_dml: bool,
+    block_markers: bool,
+    quiet: bool,
+) -> None:
+    if trace_style not in ("raiserror", "print"):
+        typer.echo("trace-style must be 'raiserror' or 'print'", err=True)
+        raise typer.Exit(1)
+
+    sql = _read_input(input)
+    progress = None if quiet else lambda msg: typer.echo(msg, err=True)
+
+    result = transform_sql(
+        sql,
+        trace_style=trace_style,
+        stub_dml=not no_stub_dml,
+        add_block_markers=block_markers,
+        on_progress=progress,
+    )
+
+    out_path = output
+    if out_path is None and str(input) != "-":
+        out_path = input.with_name(f"{input.stem}_debug{input.suffix}")
+
+    _write_output(out_path, result.sql)
+
+    summary = (
+        f"Done: {result.stats.dml_stubbed} DML stubbed, "
+        f"{result.stats.traces_added} traces added."
+    )
+    if out_path and str(out_path) != "-":
+        typer.echo(f"{summary} Written to {out_path}")
+    else:
+        typer.echo(summary)
+
+    if result.parse_errors:
+        typer.echo("Parse warnings present — review banner in output.", err=True)
+        raise typer.Exit(2)
+
+
+@app.command("generate")
+def generate_cmd(
+    input: Path = typer.Option(
+        ...,
+        "--input",
+        "-i",
+        help="Input .sql file (use - for stdin).",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output path (default: <input>_debug.sql).",
+    ),
+    trace_style: str = typer.Option(
+        "print",
+        "--trace-style",
+        help="Trace style: print (default) or raiserror (NOWAIT).",
+    ),
+    no_stub_dml: bool = typer.Option(
+        False, "--no-stub-dml", help="Skip DML stubbing; only add traces."
+    ),
+    block_markers: bool = typer.Option(
+        False,
+        "--block-markers",
+        help="Insert -- [DBG] Step N markers before IF/WHILE.",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress progress messages on stderr.",
+    ),
+) -> None:
+    """
+    Generate a debug harness script from a stored procedure.
+
+    Replaces writes to real tables with SELECT previews and adds PRINT traces on
+    variables so you can run the script on a dev database without side effects.
+    """
+    _run_generate(input, output, trace_style, no_stub_dml, block_markers, quiet)
+
+
+@app.command("transform", hidden=True)
+def transform_cmd(
+    input: Path = typer.Option(
+        ...,
+        "--input",
+        "-i",
+        help="Input .sql file (use - for stdin).",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output path (default: <input>_debug.sql).",
+    ),
+    trace_style: str = typer.Option(
+        "print",
+        "--trace-style",
+        help="Trace style: print (default) or raiserror (NOWAIT).",
+    ),
+    no_stub_dml: bool = typer.Option(
+        False, "--no-stub-dml", help="Skip DML stubbing; only add traces."
+    ),
+    block_markers: bool = typer.Option(
+        False,
+        "--block-markers",
+        help="Insert -- [DBG] Step N markers before IF/WHILE.",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress progress messages on stderr.",
+    ),
+) -> None:
+    """Deprecated alias for generate."""
+    _run_generate(input, output, trace_style, no_stub_dml, block_markers, quiet)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

sql_sp_harness/console.py

@@ -0,0 +1,45 @@
+"""Terminal styling helpers for CLI output."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+RESET = "\033[0m"
+GREEN = "\033[32m"
+RED = "\033[31m"
+YELLOW = "\033[33m"
+CYAN = "\033[36m"
+BOLD = "\033[1m"
+ITALIC = "\033[3m"
+DIM = "\033[2m"
+
+
+def supports_color() -> bool:
+    return sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+
+def style(text: str, color: str, *, enabled: bool = True) -> str:
+    if not enabled:
+        return text
+    return f"{color}{text}{RESET}"
+
+
+def success(text: str, *, enabled: bool = True) -> str:
+    return style(text, GREEN, enabled=enabled)
+
+
+def failure(text: str, *, enabled: bool = True) -> str:
+    return style(text, RED, enabled=enabled)
+
+
+def warning(text: str, *, enabled: bool = True) -> str:
+    return style(text, YELLOW, enabled=enabled)
+
+
+def heading(text: str, *, enabled: bool = True) -> str:
+    return style(text, CYAN + BOLD, enabled=enabled)
+
+
+def dim(text: str, *, enabled: bool = True) -> str:
+    return style(text, DIM, enabled=enabled)

sql_sp_harness/dml_preview.py

@@ -0,0 +1,277 @@
+"""Convert DML statements into safe SELECT previews for debug harness scripts."""
+
+from __future__ import annotations
+
+import re
+
+CLAUSE_FROM = re.compile(r"\bFROM\b", re.IGNORECASE)
+CLAUSE_WHERE = re.compile(r"\bWHERE\b", re.IGNORECASE)
+CLAUSE_SET = re.compile(r"\bSET\b", re.IGNORECASE)
+INSERT_INTO = re.compile(r"^\s*INSERT\s+INTO\s+(\S+)", re.IGNORECASE)
+DELETE_FROM = re.compile(
+    r"^\s*DELETE\s+FROM\s+(\S+)(?:\s+WHERE\s+(.+))?\s*;?\s*$",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def _extract_paren_content(text: str, open_index: int) -> tuple[str, int] | None:
+    if open_index >= len(text) or text[open_index] != "(":
+        return None
+    depth = 0
+    for i in range(open_index, len(text)):
+        ch = text[i]
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+            if depth == 0:
+                return text[open_index + 1 : i], i + 1
+    return None
+
+
+def _block_sql(block_lines: list[str]) -> str:
+    parts = [ln.strip() for ln in block_lines if ln.strip()]
+    return re.sub(r"\s+", " ", " ".join(parts)).strip()
+
+
+def _find_clause(text: str, pattern: re.Pattern[str]) -> int | None:
+    match = pattern.search(text)
+    return match.start() if match else None
+
+
+def _split_expressions(text: str) -> list[str]:
+    parts: list[str] = []
+    depth = 0
+    current: list[str] = []
+    for ch in text:
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            part = "".join(current).strip()
+            if part:
+                parts.append(part)
+            current = []
+            continue
+        current.append(ch)
+    tail = "".join(current).strip()
+    if tail:
+        parts.append(tail)
+    return parts
+
+
+def _parse_assignments(set_clause: str) -> list[tuple[str, str]]:
+    assignments: list[tuple[str, str]] = []
+    for part in _split_expressions(set_clause):
+        if "=" not in part:
+            continue
+        lhs, rhs = part.split("=", 1)
+        assignments.append((lhs.strip(), rhs.strip()))
+    return assignments
+
+
+def _column_alias(name: str) -> str:
+    base = name.split(".")[-1].strip("[]")
+    return f"[{base}]"
+
+
+_BARE_VAR = re.compile(r"^@\w+$", re.IGNORECASE)
+_QUOTED_LITERAL = re.compile(r"^(N?'([^']|'')*'|\d+(\.\d+)?)$", re.IGNORECASE)
+
+
+def _lhs_column_name(lhs: str) -> str:
+    return lhs.split(".")[-1].strip("[]")
+
+
+def _is_calculation(expr: str) -> bool:
+    """True when RHS is an expression, not a bare variable or simple literal."""
+    text = expr.strip()
+    if _BARE_VAR.match(text):
+        return False
+    if _QUOTED_LITERAL.match(text):
+        return False
+    if re.search(r"[\+\-\*/%]|^\w+\(", text, re.IGNORECASE):
+        return True
+    return False
+
+
+def _preview_column_alias(lhs: str, rhs: str) -> str:
+    """Choose preview column alias based on SET/VALUES expression shape."""
+    rhs = rhs.strip()
+    if _BARE_VAR.match(rhs):
+        return f"[{rhs}]"
+    col = _lhs_column_name(lhs)
+    if _is_calculation(rhs):
+        return f"[calculated-{col}]"
+    return f"[{col}]"
+
+
+def _parse_update(sql: str) -> dict[str, str | list[tuple[str, str]]] | None:
+    text = sql.strip().rstrip(";")
+    if not re.match(r"UPDATE\b", text, re.I):
+        return None
+
+    rest = re.sub(r"^UPDATE\s+", "", text, flags=re.I).strip()
+    set_match = CLAUSE_SET.search(rest)
+    if not set_match:
+        return None
+
+    target = rest[: set_match.start()].strip()
+    after_set = rest[set_match.end() :].strip()
+    from_pos = _find_clause(after_set, CLAUSE_FROM)
+    where_pos = _find_clause(after_set, CLAUSE_WHERE)
+    stops = [pos for pos in (from_pos, where_pos) if pos is not None]
+    assign_end = min(stops) if stops else len(after_set)
+
+    assignments = _parse_assignments(after_set[:assign_end])
+    if not assignments:
+        return None
+
+    from_clause = ""
+    if from_pos is not None:
+        from_end = where_pos if where_pos is not None and where_pos > from_pos else len(after_set)
+        from_clause = after_set[from_pos:from_end].strip()
+
+    where_clause = ""
+    if where_pos is not None:
+        where_clause = after_set[where_pos:].strip()
+
+    return {
+        "kind": "UPDATE",
+        "target": target,
+        "assignments": assignments,
+        "from_clause": from_clause,
+        "where_clause": where_clause,
+    }
+
+
+def _parse_insert(sql: str) -> dict[str, str | list[str]] | None:
+    one_line = re.sub(r"\s+", " ", sql.strip().rstrip(";"))
+    head = INSERT_INTO.match(one_line)
+    if not head:
+        return None
+
+    table = head.group(1)
+    pos = head.end()
+    while pos < len(one_line) and one_line[pos].isspace():
+        pos += 1
+    columns: list[str] = []
+
+    if pos < len(one_line) and one_line[pos] == "(":
+        col_content, pos = _extract_paren_content(one_line, pos) or ("", pos)
+        columns = [c.strip() for c in col_content.split(",") if c.strip()]
+
+    values_match = re.search(r"\bVALUES\b", one_line[pos:], re.I)
+    if not values_match:
+        return None
+    pos += values_match.end()
+    while pos < len(one_line) and one_line[pos].isspace():
+        pos += 1
+
+    values_content, _end = _extract_paren_content(one_line, pos) or ("", pos)
+    values = _split_expressions(values_content)
+    if not values:
+        return None
+    if columns and len(columns) != len(values):
+        return None
+    if not columns:
+        columns = [f"col{i + 1}" for i in range(len(values))]
+
+    return {
+        "kind": "INSERT",
+        "target": table,
+        "columns": columns,
+        "values": values,
+    }
+
+
+def _parse_delete(sql: str) -> dict[str, str] | None:
+    one_line = re.sub(r"\s+", " ", sql.strip().rstrip(";"))
+    match = DELETE_FROM.match(one_line)
+    if not match:
+        return None
+    return {
+        "kind": "DELETE",
+        "target": match.group(1),
+        "where_clause": (match.group(2) or "").strip(),
+    }
+
+
+def _format_multiline(indent: str, sql: str) -> list[str]:
+    return [f"{indent}{line}" if line else "" for line in sql.splitlines()]
+
+
+def build_dml_preview(block_lines: list[str], indent: str) -> list[str] | None:
+    """Return SELECT preview lines replacing a DML block, or None if unsupported."""
+    sql = _block_sql(block_lines)
+    first = block_lines[0].strip().split()[0].upper()
+
+    if first == "UPDATE":
+        parsed = _parse_update(sql)
+        if parsed is None:
+            return None
+        target = str(parsed["target"])
+        assignments = parsed["assignments"]
+        assert isinstance(assignments, list)
+
+        select_cols = [f"N'UPDATE to table {target}' AS [DBG_Action]"]
+        for lhs, rhs in assignments:
+            select_cols.append(f"{rhs} AS {_preview_column_alias(str(lhs), str(rhs))}")
+
+        from_clause = str(parsed.get("from_clause") or "")
+        if from_clause:
+            from_sql = from_clause
+        else:
+            from_sql = f"FROM {target}"
+
+        where_clause = str(parsed.get("where_clause") or "").strip()
+        preview = (
+            f"SELECT {', '.join(select_cols)}\n"
+            f"{from_sql}"
+            + (f"\n{where_clause}" if where_clause else "")
+            + ";"
+        )
+        return [
+            f"{indent}-- [DBG-PREVIEW] Would have executed:",
+            *_format_multiline(indent, preview),
+        ]
+
+    if first == "INSERT":
+        parsed = _parse_insert(sql)
+        if parsed is None:
+            return None
+        target = str(parsed["target"])
+        columns = parsed["columns"]
+        values = parsed["values"]
+        assert isinstance(columns, list) and isinstance(values, list)
+
+        select_cols = [f"N'INSERT to table {target}' AS [DBG_Action]"]
+        for col, val in zip(columns, values, strict=True):
+            select_cols.append(f"{val} AS {_preview_column_alias(str(col), str(val))}")
+
+        preview = f"SELECT {', '.join(select_cols)};"
+        return [
+            f"{indent}-- [DBG-PREVIEW] Would have executed:",
+            *_format_multiline(indent, preview),
+        ]
+
+    if first == "DELETE":
+        parsed = _parse_delete(sql)
+        if parsed is None:
+            return None
+        target = str(parsed["target"])
+        where_clause = str(parsed.get("where_clause") or "").strip()
+        select_cols = [f"N'DELETE from table {target}' AS [DBG_Action]", "*"]
+        preview = (
+            f"SELECT {', '.join(select_cols)}\n"
+            f"FROM {target}"
+            + (f"\nWHERE {where_clause}" if where_clause else "")
+            + ";"
+        )
+        return [
+            f"{indent}-- [DBG-PREVIEW] Would have executed:",
+            *_format_multiline(indent, preview),
+        ]
+
+    return None

sql_sp_harness/emit.py

@@ -0,0 +1,25 @@
+"""Format output files with safety banners and summaries."""
+
+from __future__ import annotations
+
+from sql_sp_harness.transform import TransformStats
+
+
+def debug_banner(parse_errors: list[str], stats: TransformStats) -> str:
+    lines = [
+        "-- ============================================================================",
+        "-- DEBUG HARNESS — DO NOT RUN ON PRODUCTION",
+        "-- Generated by sql-sp-harness. DML replaced with SELECT previews; variable traces injected.",
+        "-- ============================================================================",
+        f"-- DML statements stubbed: {stats.dml_stubbed}",
+        f"-- Trace lines added: {stats.traces_added}",
+    ]
+    if parse_errors:
+        lines.append("-- PARSE WARNINGS (review manually):")
+        for err in parse_errors:
+            lines.append(f"--   {err}")
+    for w in stats.warnings:
+        lines.append(f"--   {w}")
+    lines.append("-- ============================================================================")
+    lines.append("")
+    return "\n".join(lines) + "\n"