execsql2 2.8.0__py3-none-any.whl → 2.9.0__py3-none-any.whl

execsql/cli/__init__.py

@@ -223,6 +223,25 @@ def main(
         "--dry-run",
         help=("Parse the script and print the command list without connecting to a database or executing anything."),
     ),
+    lint: bool = typer.Option(
+        False,
+        "--lint",
+        help=(
+            "Parse the script and perform static analysis without connecting to a database or executing anything. "
+            "Reports unmatched IF/ENDIF/LOOP/BATCH blocks (errors), potentially undefined variables, "
+            "and missing INCLUDE files (warnings). Exits 0 if no errors, 1 if errors found."
+        ),
+    ),
+    ping: bool = typer.Option(
+        False,
+        "--ping",
+        help=(
+            "Test database connectivity and exit. "
+            "Prints connection details and the server version on success (exit 0), "
+            "or the error message on failure (exit 1). "
+            "No script file is required."
+        ),
+    ),
     dsn: str | None = typer.Option(
         None,
         "--dsn",
@@ -350,6 +369,10 @@ def main(
     positional = args or []
     if command is not None:
         script_name = None  # inline mode — no script file
+    elif ping:
+        # --ping does not require a script file; positional args are still
+        # available for server/db arguments if --dsn is not used.
+        script_name = None
     else:
         if not positional:
             _err_console.print(
@@ -421,6 +444,8 @@ def main(
         output_dir=output_dir,
         progress=progress,
         profile=profile,
+        ping=ping,
+        lint=lint,
     )
 
 

execsql/cli/lint.py

@@ -0,0 +1,459 @@
+"""Static analysis (lint) for execsql scripts.
+
+:func:`_lint_script` inspects a parsed :class:`~execsql.script.CommandList`
+for common structural problems without connecting to a database or executing
+any commands.
+
+Checks performed
+----------------
+1. **Unmatched IF / ENDIF** — mismatched nesting depth (error).
+2. **Unmatched LOOP / END LOOP** — mismatched nesting depth (error).
+3. **Unmatched BEGIN BATCH / END BATCH** — mismatched nesting depth (error).
+4. **Potentially undefined variables** — ``!!$VAR!!`` tokens not preceded by a
+   ``SUB`` metacommand in the same parsed command list and not in the set of
+   built-in variables (warning).
+5. **Missing INCLUDE files** — INCLUDE target does not exist on disk relative
+   to the script directory (warning).
+6. **Empty script** — no commands found (warning).
+
+The function walks ``CommandList.cmdlist`` and also descends into any
+``CommandList`` objects stored in ``_state.savedscripts`` (i.e. named scripts
+defined with ``BEGIN SCRIPT … END SCRIPT`` in the same file).  SCRIPT blocks
+are analysed in isolation; nesting counters reset for each block.
+
+Exit-code contract
+------------------
+- Returns ``1`` when at least one **error**-severity issue is found.
+- Returns ``0`` when only warnings (or nothing) are found.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from execsql.script.engine import CommandList
+
+__all__ = ["_lint_script"]
+
+
+# ---------------------------------------------------------------------------
+# Compiled patterns for metacommand recognition
+# ---------------------------------------------------------------------------
+
+# IF block — "IF(...)" block form (single-command, no ENDIF needed)
+_RX_IF_INLINE = re.compile(
+    r"^\s*IF\s*\(\s*.+\s*\)\s*\{.+\}\s*$",
+    re.I,
+)
+# IF block form that opens a block requiring ENDIF
+_RX_IF_BLOCK = re.compile(r"^\s*IF\s*\(\s*.+\s*\)\s*$", re.I)
+_RX_ENDIF = re.compile(r"^\s*ENDIF\s*$", re.I)
+_RX_ELSE = re.compile(r"^\s*ELSE\s*$", re.I)
+_RX_ELSEIF = re.compile(r"^\s*ELSEIF\s*\(\s*.+\s*\)\s*$", re.I)
+_RX_ANDIF = re.compile(r"^\s*ANDIF\s*\(\s*.+\s*\)\s*$", re.I)
+_RX_ORIF = re.compile(r"^\s*ORIF\s*\(\s*.+\s*\)\s*$", re.I)
+
+# LOOP … END LOOP
+_RX_LOOP = re.compile(r"^\s*LOOP\s+(?:WHILE|UNTIL)\s*\(", re.I)
+_RX_END_LOOP = re.compile(r"^\s*END\s+LOOP\s*$", re.I)
+
+# BEGIN BATCH … END BATCH
+_RX_BEGIN_BATCH = re.compile(r"^\s*BEGIN\s+BATCH\s*$", re.I)
+_RX_END_BATCH = re.compile(r"^\s*END\s+BATCH\s*$", re.I)
+
+# SUB <varname> <value> — defines a substitution variable
+_RX_SUB = re.compile(r"^\s*SUB\s+(?P<name>[+~]?\w+)\s+", re.I)
+
+# INCLUDE <file>
+_RX_INCLUDE = re.compile(
+    r"^\s*INCLUDE(?:\s+IF\s+EXISTS?)?\s+(?P<path>\S+.*?)\s*$",
+    re.I,
+)
+
+# Variable reference — !!name!! where name may start with $, @, &, ~, #, +
+_RX_VAR_REF = re.compile(r"!!([$@&~#+]?\w+)!!", re.I)
+
+# Built-in system variables that are always defined (populated by _run before
+# any script commands execute).  Variable names are stored without the leading
+# ``$`` for case-insensitive set membership tests.
+_BUILTIN_VARS: frozenset[str] = frozenset(
+    {
+        # Start-time / environment
+        "SCRIPT_START_TIME",
+        "SCRIPT_START_TIME_UTC",
+        "DATE_TAG",
+        "DATETIME_TAG",
+        "DATETIME_UTC_TAG",
+        "LAST_ROWCOUNT",
+        "LAST_SQL",
+        "LAST_ERROR",
+        "ERROR_MESSAGE",
+        "USER",
+        "STARTING_PATH",
+        "PATHSEP",
+        "OS",
+        "PYTHON_EXECUTABLE",
+        "STARTING_SCRIPT",
+        "STARTING_SCRIPT_NAME",
+        "STARTING_SCRIPT_REVTIME",
+        "RUN_ID",
+        # Execution-time (set during runscripts — not available in --dry-run
+        # but always defined before any script command can reference them)
+        "CURRENT_TIME",
+        "CURRENT_TIME_UTC",
+        "CURRENT_SCRIPT",
+        "CURRENT_SCRIPT_PATH",
+        "CURRENT_SCRIPT_NAME",
+        "CURRENT_SCRIPT_LINE",
+        "SCRIPT_LINE",
+        "CURRENT_DIR",
+        "CURRENT_PATH",
+        "CURRENT_ALIAS",
+        "AUTOCOMMIT_STATE",
+        "TIMER",
+        "DB_USER",
+        "DB_SERVER",
+        "DB_NAME",
+        "DB_NEED_PWD",
+        "RANDOM",
+        "UUID",
+        "VERSION1",
+        "VERSION2",
+        "VERSION3",
+        "CANCEL_HALT_STATE",
+        "ERROR_HALT_STATE",
+        "METACOMMAND_ERROR_HALT_STATE",
+        "CONSOLE_WAIT_WHEN_ERROR_HALT_STATE",
+        "CONSOLE_WAIT_WHEN_DONE_STATE",
+        "CURRENT_DBMS",
+        "CURRENT_DATABASE",
+        "SYSTEM_CMD_EXIT_STATUS",
+        # Connection-populated
+        "DB_FILE",
+        "DB_PORT",
+        # Counter variables (@@name) are always valid — skip validation
+    },
+)
+
+
+# ---------------------------------------------------------------------------
+# 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)
+
+
+# ---------------------------------------------------------------------------
+# Core lint implementation
+# ---------------------------------------------------------------------------
+
+
+def _lint_cmdlist(
+    cmdlist: CommandList,
+    script_dir: Path | None,
+    defined_vars: set[str],
+) -> list[_Issue]:
+    """Lint a single :class:`CommandList` and return any issues found.
+
+    Args:
+        cmdlist: The parsed command list to analyse.
+        script_dir: Directory of the top-level script file, used for resolving
+            relative INCLUDE paths.  ``None`` for inline (``-c``) scripts.
+        defined_vars: Mutable set of variable names (without sigil) that have
+            been defined by preceding ``SUB`` metacommands.  The caller passes
+            in the set from the outer scope so that variables defined before an
+            EXECUTE SCRIPT call are visible inside the script block when
+            analysing top-level scripts.  For named-script analysis the caller
+            passes a *copy* so that local definitions don't leak.
+
+    Returns:
+        List of ``(severity, source, line_no, message)`` issue tuples.
+    """
+    issues: list[_Issue] = []
+
+    if_depth = 0
+    if_open_locs: list[tuple[str, int]] = []  # (source, line_no) of unmatched IF
+
+    loop_depth = 0
+    loop_open_locs: list[tuple[str, int]] = []
+
+    batch_depth = 0
+    batch_open_locs: list[tuple[str, int]] = []
+
+    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
+
+        if cmd.command_type == "sql":
+            # SQL statements: check for variable references only
+            for m in _RX_VAR_REF.finditer(stmt):
+                _check_var_ref(m.group(1), src, lno, defined_vars, issues)
+            continue
+
+        # Metacommand checks
+        for m in _RX_VAR_REF.finditer(stmt):
+            _check_var_ref(m.group(1), src, lno, defined_vars, issues)
+
+        # -- IF block (opens a block requiring ENDIF) --
+        if _RX_IF_BLOCK.match(stmt) and not _RX_IF_INLINE.match(stmt):
+            if_depth += 1
+            if_open_locs.append((src, lno))
+
+        elif _RX_ENDIF.match(stmt):
+            if if_depth == 0:
+                issues.append(_error(src, lno, "ENDIF without a matching preceding IF"))
+            else:
+                if_depth -= 1
+                if_open_locs.pop()
+
+        elif _RX_ELSEIF.match(stmt) or _RX_ELSE.match(stmt) or _RX_ANDIF.match(stmt) or _RX_ORIF.match(stmt):
+            if if_depth == 0:
+                kw = stmt.strip().split(None, 1)[0].upper()
+                issues.append(_error(src, lno, f"{kw} without a matching preceding IF"))
+
+        # -- LOOP --
+        elif _RX_LOOP.match(stmt):
+            loop_depth += 1
+            loop_open_locs.append((src, lno))
+
+        elif _RX_END_LOOP.match(stmt):
+            if loop_depth == 0:
+                issues.append(_error(src, lno, "END LOOP without a matching preceding LOOP"))
+            else:
+                loop_depth -= 1
+                loop_open_locs.pop()
+
+        # -- BATCH --
+        elif _RX_BEGIN_BATCH.match(stmt):
+            batch_depth += 1
+            batch_open_locs.append((src, lno))
+
+        elif _RX_END_BATCH.match(stmt):
+            if batch_depth == 0:
+                issues.append(_error(src, lno, "END BATCH without a matching preceding BEGIN BATCH"))
+            else:
+                batch_depth -= 1
+                batch_open_locs.pop()
+
+        # -- SUB variable definition --
+        sub_m = _RX_SUB.match(stmt)
+        if sub_m:
+            varname = sub_m.group("name").lstrip("+~")
+            defined_vars.add(varname.upper())
+
+        # -- INCLUDE file existence --
+        inc_m = _RX_INCLUDE.match(stmt)
+        if inc_m:
+            raw_path = inc_m.group("path").strip().strip("\"'")
+            # Only check if no substitution variables are in the path
+            if not _RX_VAR_REF.search(raw_path):
+                _check_include_path(raw_path, script_dir, src, lno, stmt, issues)
+
+    # Report unclosed blocks at end of command list
+    for osrc, olno in if_open_locs:
+        issues.append(_error(osrc, olno, "IF without a matching ENDIF"))
+    for osrc, olno in loop_open_locs:
+        issues.append(_error(osrc, olno, "LOOP without a matching END LOOP"))
+    for osrc, olno in batch_open_locs:
+        issues.append(_error(osrc, olno, "BEGIN BATCH without a matching END BATCH"))
+
+    return issues
+
+
+def _check_var_ref(
+    raw_name: str,
+    source: str,
+    line_no: int,
+    defined_vars: set[str],
+    issues: list[_Issue],
+) -> None:
+    """Emit a warning if *raw_name* looks like an undefined user variable.
+
+    Built-in system variables, environment-variable references (``&``-prefix),
+    column variables (``@``-prefix), counter variables (``@@``), parameter
+    variables (``#``-prefix), and ``$ARG_N`` are excluded from the check.
+
+    Args:
+        raw_name: Variable name token as captured from ``!!name!!`` (with sigil).
+        source: Source file name for the issue location.
+        line_no: Line number of the command containing the reference.
+        defined_vars: Set of variable names (upper-case, no sigil) that have
+            been defined by preceding SUB metacommands.
+        issues: Issue list to append to.
+    """
+    if not raw_name:
+        return
+
+    sigil = raw_name[0] if raw_name[0] in ("$", "@", "&", "~", "#", "+") else ""
+    name = raw_name[len(sigil) :]
+
+    # Skip non-$ sigil prefixes — these are always resolved at runtime
+    if sigil in ("@", "&", "~", "#", "+"):
+        return
+
+    # $ARG_N is set via -a/--assign-arg at invocation time
+    if re.match(r"^ARG_\d+$", name, re.I):
+        return
+
+    # Built-in system variables
+    if name.upper() in _BUILTIN_VARS:
+        return
+
+    # User-defined via SUB
+    if name.upper() in defined_vars:
+        return
+
+    issues.append(
+        _warning(
+            source,
+            line_no,
+            f"Potentially undefined variable: !!{raw_name}!! "
+            "(not defined by a preceding SUB; may be set by a config file or -a arg)",
+        ),
+    )
+
+
+def _check_include_path(
+    raw_path: str,
+    script_dir: Path | None,
+    source: str,
+    line_no: int,
+    stmt: str,
+    issues: list[_Issue],
+) -> None:
+    """Warn if the INCLUDE target does not exist on disk.
+
+    Args:
+        raw_path: Unquoted file path string from the INCLUDE metacommand.
+        script_dir: Directory of the top-level script file; used for relative
+            path resolution.  ``None`` for inline scripts.
+        source: Source file name for issue location.
+        line_no: Line number of the INCLUDE command.
+        stmt: Full metacommand statement text (for the IF EXISTS variant).
+        issues: Issue list to append to.
+    """
+    # IF EXISTS variant — missing file is intentional; skip
+    if re.match(r"^\s*INCLUDE\s+IF\s+EXISTS?", stmt, re.I):
+        return
+
+    p = Path(raw_path)
+    if not p.is_absolute() and script_dir is not None:
+        p = script_dir / p
+
+    if not p.exists():
+        issues.append(
+            _warning(
+                source,
+                line_no,
+                f"INCLUDE target does not exist: {raw_path!r}",
+            ),
+        )
+
+
+def _lint_script(
+    cmdlist: CommandList | None,
+    script_path: str | None = None,
+) -> list[_Issue]:
+    """Perform static analysis on a parsed command list.
+
+    Walks every :class:`~execsql.script.ScriptCmd` in *cmdlist* and any named
+    scripts accumulated in ``_state.savedscripts`` (those defined with
+    ``BEGIN SCRIPT … END SCRIPT`` in the same source file).
+
+    Args:
+        cmdlist: The top-level :class:`~execsql.script.CommandList` returned by
+            ``read_sqlfile()`` / ``read_sqlstring()``.  If ``None`` or empty,
+            a single "empty script" warning is returned.
+        script_path: Absolute or relative path to the SQL script file.  Used
+            to resolve relative INCLUDE paths.  Pass ``None`` for inline
+            (``-c``) scripts.
+
+    Returns:
+        List of ``(severity, source, line_no, message)`` tuples, one per issue
+        found.  An empty list means the script is clean.
+    """
+    import execsql.state as _state
+
+    issues: list[_Issue] = []
+
+    if cmdlist is None or not cmdlist.cmdlist:
+        issues.append(_warning("<script>", 0, "Script is empty — no commands found"))
+        return issues
+
+    script_dir = Path(script_path).resolve().parent if script_path else None
+
+    # Shared set of variables defined in the top-level script via SUB.
+    # Named scripts get a fresh copy so their internal definitions don't bleed
+    # back into the top-level analysis.
+    top_defined: set[str] = set()
+
+    issues.extend(_lint_cmdlist(cmdlist, script_dir, top_defined))
+
+    # Analyse each named SCRIPT block collected during parsing
+    for script_name, saved_cl in getattr(_state, "savedscripts", {}).items():
+        saved_issues = _lint_cmdlist(saved_cl, script_dir, set(top_defined))
+        for sev, src, lno, msg in saved_issues:
+            # Annotate with the script name if the source is the same file
+            issues.append((sev, src, lno, f"[script '{script_name}'] {msg}"))
+
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Rich output helper
+# ---------------------------------------------------------------------------
+
+
+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
+
+    for severity, source, line_no, message in issues:
+        loc = f"{source}:{line_no}" if line_no else source
+        if severity == "error":
+            _console.print(f"  [bold red]ERROR  [/bold red]  [dim]{loc}[/dim]  {message}")
+        else:
+            _console.print(f"  [bold yellow]WARNING[/bold yellow]  [dim]{loc}[/dim]  {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

execsql/cli/run.py

@@ -24,7 +24,11 @@ from execsql.script import SubVarSet, current_script_line, read_sqlfile, read_sq
 from execsql.utils.fileio import FileWriter, Logger, filewriter_end
 from execsql.utils.gui import gui_connect, gui_console_isrunning, gui_console_off, gui_console_on, gui_console_wait_user
 
-__all__ = ["_connect_initial_db", "_print_dry_run", "_print_profile", "_run"]
+__all__ = ["_connect_initial_db", "_ping_db", "_print_dry_run", "_print_profile", "_run"]
+
+# Lint helper — imported lazily inside _run() to keep start-up cost low, but
+# re-exported here so that tests and callers can reach it via cli.run.
+from execsql.cli.lint import _lint_script, _print_lint_results  # noqa: F401 — re-export
 
 
 # ---------------------------------------------------------------------------
@@ -119,6 +123,64 @@ def _print_profile(profile_data: list[tuple]) -> None:
     _console.print()
 
 
+# ---------------------------------------------------------------------------
+# --ping helper
+# ---------------------------------------------------------------------------
+
+
+def _ping_db(db) -> None:
+    """Test connectivity for *db*, print connection details, and exit.
+
+    Attempts to execute ``SELECT version()`` (or ``SELECT sqlite_version()``
+    for SQLite) to retrieve the server version string.  If the query fails the
+    connection is still reported as successful — only the version line is
+    omitted.  On success the function raises :class:`SystemExit` with code 0.
+
+    Args:
+        db: An open :class:`~execsql.db.base.Database` instance.
+    """
+    dbms_id: str = db.type.dbms_id if db.type else "unknown"
+
+    # Try to fetch a human-readable server version string.
+    version_str: str | None = None
+    _version_queries = [
+        "SELECT version()",
+        "SELECT sqlite_version()",
+        "SELECT @@VERSION",
+    ]
+    for sql in _version_queries:
+        try:
+            curs = db.cursor()
+            curs.execute(sql)
+            row = curs.fetchone()
+            curs.close()
+            if row and row[0]:
+                version_str = str(row[0]).split("\n")[0].strip()
+            break
+        except Exception:
+            continue
+
+    # Build the connection descriptor.
+    if db.server_name:
+        port_part = f":{db.port}" if db.port else ""
+        location = f"{db.server_name}{port_part}/{db.db_name or ''}"
+    else:
+        location = db.db_name or "<in-memory>"
+
+    if version_str:
+        _console.print(
+            f"[bold green]Connected[/bold green] to [bold]{dbms_id}[/bold] "
+            f"[dim]{version_str}[/dim] at [cyan]{location}[/cyan]",
+        )
+    else:
+        _console.print(
+            f"[bold green]Connected[/bold green] to [bold]{dbms_id}[/bold] at [cyan]{location}[/cyan]",
+        )
+
+    db.close()
+    raise SystemExit(0)
+
+
 # ---------------------------------------------------------------------------
 # Core execution (split from argument parsing for testability)
 # ---------------------------------------------------------------------------
@@ -150,6 +212,8 @@ def _run(
     output_dir: str | None = None,
     progress: bool = False,
     profile: bool = False,
+    ping: bool = False,
+    lint: bool = False,
 ) -> None:
     """Initialise state, connect to the database, load the script, and run it.
 
@@ -157,6 +221,17 @@ def _run(
     without going through the Typer CLI layer. All parameters mirror the
     corresponding CLI options; see [Syntax & Options](../syntax.md) for
     descriptions.
+
+    When *ping* is ``True``, the function connects to the database, prints
+    connection details (DBMS name, server version, and location), and calls
+    :func:`_ping_db` which raises ``SystemExit(0)``.  No script is loaded or
+    executed.  *script_name* and *command* may both be ``None`` in ping mode.
+
+    When *lint* is ``True``, the script is parsed and statically analysed for
+    structural issues (unmatched IF/ENDIF/LOOP/BATCH blocks, potentially
+    undefined variables, missing INCLUDE files, empty scripts) without
+    connecting to a database or executing anything.  Exits with code 0 if no
+    errors were found, or code 1 if errors were found.
     """
     import execsql.state as _state
 
@@ -286,10 +361,10 @@ def _run(
     if progress:
         conf.show_progress = True
 
-    # Positional arguments after the script name (or all positionals in inline mode)
+    # Positional arguments after the script name (or all positionals in inline/ping mode)
     # off=1: script file occupies positional[0]; connection args start at [1]
-    # off=0: no script file; all positionals are connection args
-    off = 0 if command is not None else 1
+    # off=0: no script file; all positionals are connection args (inline -c or --ping)
+    off = 0 if (command is not None or ping) else 1
     if len(positional) == off + 1:
         if conf.db_type in ("a", "l", "k"):
             conf.db_file = positional[off]
@@ -403,12 +478,13 @@ def _run(
             )
 
     # ------------------------------------------------------------------
-    # Load the SQL script
+    # Load the SQL script (skipped in --ping and --dry-run with no script)
     # ------------------------------------------------------------------
-    if command is not None:
-        read_sqlstring(command.replace("\\n", "\n").replace("\\t", "\t"), "<inline>")
-    else:
-        read_sqlfile(script_name)
+    if not ping:
+        if command is not None:
+            read_sqlstring(command.replace("\\n", "\n").replace("\\t", "\t"), "<inline>")
+        else:
+            read_sqlfile(script_name)
 
     # ------------------------------------------------------------------
     # Dry-run: print command list and exit without connecting to DB
@@ -417,6 +493,16 @@ def _run(
         _print_dry_run(_state.commandliststack[-1] if _state.commandliststack else None)
         raise SystemExit(0)
 
+    # ------------------------------------------------------------------
+    # Lint: static analysis without connecting to DB
+    # ------------------------------------------------------------------
+    if lint:
+        cmdlist = _state.commandliststack[-1] if _state.commandliststack else None
+        issues = _lint_script(cmdlist, script_name)
+        label = script_name or "<inline>"
+        exit_code = _print_lint_results(issues, label)
+        raise SystemExit(exit_code)
+
     # ------------------------------------------------------------------
     # Start GUI console if requested
     # ------------------------------------------------------------------
@@ -446,6 +532,12 @@ def _run(
     _state.subvars.add_substitution("$DB_SERVER", db.server_name)
     _state.subvars.add_substitution("$SYSTEM_CMD_EXIT_STATUS", "0")
 
+    # ------------------------------------------------------------------
+    # --ping: report connection details and exit (no script executed)
+    # ------------------------------------------------------------------
+    if ping:
+        _ping_db(db)  # raises SystemExit(0) on success
+
     # ------------------------------------------------------------------
     # Execute the script
     # ------------------------------------------------------------------

{execsql2-2.8.0.dist-info → execsql2-2.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.8.0
+Version: 2.9.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
@@ -221,6 +221,7 @@ execsql script.sql                          # read connection from config file
 | `-w`                                | Skip password prompt when a username is supplied                |
 | `--dsn URL`                         | Connection string (e.g. `postgresql://user:pass@host/db`)       |
 | `--dry-run`                         | Parse the script and report commands without executing          |
+| `--lint`                            | Static analysis: check structure and warn on issues (no DB)     |
 | `--progress`                        | Show a progress bar for long-running IMPORT operations          |
 | `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
 | `--gui-framework {tkinter,textual}` | GUI framework for interactive prompts                           |

{execsql2-2.8.0.dist-info → execsql2-2.9.0.dist-info}/RECORD

@@ -9,10 +9,11 @@ execsql/parser.py,sha256=mbNSMiAMR1NvNvFtQAZq6nxBOupMGJZXSimLWLtZeNs,15537
 execsql/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 execsql/state.py,sha256=BodGWiLD7I3s7LFd8Mb6SHMp3I1BhVE4rYcR0UZWAoM,14799
 execsql/types.py,sha256=HVWb4umIB9lpxCGgqk3xy1hoGYPfN39xci5mHF0Izq4,31882
-execsql/cli/__init__.py,sha256=KewdhCBL8iRa_iPZZ7RKeRl90pGCXg3_lsMaVZph-kY,15118
+execsql/cli/__init__.py,sha256=Y4lFKvKWyjtMgSLsmACHYG33DFpeAQxddIVrlKURwpg,16081
 execsql/cli/dsn.py,sha256=svaZtrUXFRL2W5G6FRRiKtR6kehOp7urrVhIx_642Z8,2820
 execsql/cli/help.py,sha256=Sn_TgSJiQeBx-xZH0fuP5OvR_wasSTumjWF9UHfIX5k,5414
-execsql/cli/run.py,sha256=pkUIcWtzDSYfoIlM418cZdLix7NI45HKRIBxgZfFtHg,26405
+execsql/cli/lint.py,sha256=KluYROdjGJNUrVbO3cJym-H296zbih4no-F10HF0P4U,16165
+execsql/cli/run.py,sha256=i0ip8tm21Sm4EFbfBdcekETmiABzrRfeP84SqA4IF68,30158
 execsql/db/__init__.py,sha256=jTbuafuKOqYtXFR1wvCOoKK5Lr3l1uErfaIbIr6UywI,1063
 execsql/db/access.py,sha256=L79gUnAnnM9EJ_f4k42jr7DI0qGcKtLOnJTlBC7uPm0,17879
 execsql/db/base.py,sha256=hfMFj8fXY0T1aXLvWJHqb0aU4EQUDFOc-YrS29HH8U4,30405
@@ -89,24 +90,24 @@ execsql/utils/numeric.py,sha256=xh02ANSRk3nUpQ-rtm66ILoMqoi7HtzCoRMIOT9U8QI,1570
 execsql/utils/regex.py,sha256=diEzTZqU_HHwVMadPAvN1Vgzhl7I03eVaEFGCXyGGL8,3770
 execsql/utils/strings.py,sha256=5Dvzrk-9SIw2lpxXZQkiJbNyo1sy7iXXAtSULlZ0KG8,8488
 execsql/utils/timer.py,sha256=eDYf5VzCNFk7oo90InJucUm3XcBdhYMogjZMqeg9xzc,1899
-execsql2-2.8.0.data/data/execsql2_extras/README.md,sha256=sxwVyU0ZahCfANv56LahkyuM505kFjrMhe-1SvWE69E,4845
-execsql2-2.8.0.data/data/execsql2_extras/config_settings.sqlite,sha256=aY5cxR7Q7J6zJ4bC9lu5mHUrhy211Cq3MNKPQVCt02E,20480
-execsql2-2.8.0.data/data/execsql2_extras/example_config_prompt.sql,sha256=SY3Jxn1qcVm4kPW9xmmTfknHfvURXmeEYTbRjYrjGSw,7487
-execsql2-2.8.0.data/data/execsql2_extras/execsql.conf,sha256=_45iJ-KWZnB8uMW_gEg067MM5pmGJ-dVl7VbAZMunAE,9530
-execsql2-2.8.0.data/data/execsql2_extras/make_config_db.sql,sha256=WwyC6dK-Eh5CAVppiBCDHqiI1_wEI9U95Ytpr4lsZkg,8726
-execsql2-2.8.0.data/data/execsql2_extras/md_compare.sql,sha256=B8Wd7LZ0vnMY2qvA139JIEBkPObgRH2i5xj6PejTQt8,24092
-execsql2-2.8.0.data/data/execsql2_extras/md_glossary.sql,sha256=DJRHcU5NbFpxTTX-IwH3yRlsboj1q6BBGrUAHKn4Cuo,10796
-execsql2-2.8.0.data/data/execsql2_extras/md_upsert.sql,sha256=v_7GbWh_N1mBTmw3gvTrkagOVp2q0KmXvM8hE-DlFxY,112524
-execsql2-2.8.0.data/data/execsql2_extras/pg_compare.sql,sha256=9dWa8hnfy5dVJI-z2iGpd9JzQmI4j2ziMlEdpnr66ro,24352
-execsql2-2.8.0.data/data/execsql2_extras/pg_glossary.sql,sha256=pKjIIDsROAgJq2H-1qNEcRMAWManivcZ_AEVHzUUlic,9908
-execsql2-2.8.0.data/data/execsql2_extras/pg_upsert.sql,sha256=k7AFiGTLBy3nf-qO5QIaZrEYTAKvdxxU3JDLx9jqkzs,108315
-execsql2-2.8.0.data/data/execsql2_extras/script_template.sql,sha256=1Estacb_vm1FgK41k_G9nuduP1yiA-fQ1Kn4Z4mv5Ao,11153
-execsql2-2.8.0.data/data/execsql2_extras/ss_compare.sql,sha256=TsVxWm3cEpR5-EiMYXNhtaY0arSNeKZhsJdHdLA7xeI,24833
-execsql2-2.8.0.data/data/execsql2_extras/ss_glossary.sql,sha256=cLM7nN8JOIu9ZVP9oY9qdSK3hrnWJiDcX6nZmQQbQWI,13065
-execsql2-2.8.0.data/data/execsql2_extras/ss_upsert.sql,sha256=BCqmBykXBF-BpCgOFeG1qhf2XfScKsxPD17wd1hYfHw,120647
-execsql2-2.8.0.dist-info/METADATA,sha256=fGxvlbidjAgVeGg51ZWXNPcblzQrR3UWbgfF60yGpuA,16849
-execsql2-2.8.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-execsql2-2.8.0.dist-info/entry_points.txt,sha256=sUOxkM-dN1eBGGpSpDLsAaE0yNXYQKWZAfxPOlMkQyk,90
-execsql2-2.8.0.dist-info/licenses/LICENSE.txt,sha256=LBdhuxejF8_bLCHZ2kWfmDXpDGUu914Gbd6_3JjCRe0,676
-execsql2-2.8.0.dist-info/licenses/NOTICE,sha256=sqVrM73Ys9zfvWC_P797lHfTnoPW_ETeBSrUTFaob0A,339
-execsql2-2.8.0.dist-info/RECORD,,
+execsql2-2.9.0.data/data/execsql2_extras/README.md,sha256=sxwVyU0ZahCfANv56LahkyuM505kFjrMhe-1SvWE69E,4845
+execsql2-2.9.0.data/data/execsql2_extras/config_settings.sqlite,sha256=aY5cxR7Q7J6zJ4bC9lu5mHUrhy211Cq3MNKPQVCt02E,20480
+execsql2-2.9.0.data/data/execsql2_extras/example_config_prompt.sql,sha256=SY3Jxn1qcVm4kPW9xmmTfknHfvURXmeEYTbRjYrjGSw,7487
+execsql2-2.9.0.data/data/execsql2_extras/execsql.conf,sha256=_45iJ-KWZnB8uMW_gEg067MM5pmGJ-dVl7VbAZMunAE,9530
+execsql2-2.9.0.data/data/execsql2_extras/make_config_db.sql,sha256=WwyC6dK-Eh5CAVppiBCDHqiI1_wEI9U95Ytpr4lsZkg,8726
+execsql2-2.9.0.data/data/execsql2_extras/md_compare.sql,sha256=B8Wd7LZ0vnMY2qvA139JIEBkPObgRH2i5xj6PejTQt8,24092
+execsql2-2.9.0.data/data/execsql2_extras/md_glossary.sql,sha256=DJRHcU5NbFpxTTX-IwH3yRlsboj1q6BBGrUAHKn4Cuo,10796
+execsql2-2.9.0.data/data/execsql2_extras/md_upsert.sql,sha256=v_7GbWh_N1mBTmw3gvTrkagOVp2q0KmXvM8hE-DlFxY,112524
+execsql2-2.9.0.data/data/execsql2_extras/pg_compare.sql,sha256=9dWa8hnfy5dVJI-z2iGpd9JzQmI4j2ziMlEdpnr66ro,24352
+execsql2-2.9.0.data/data/execsql2_extras/pg_glossary.sql,sha256=pKjIIDsROAgJq2H-1qNEcRMAWManivcZ_AEVHzUUlic,9908
+execsql2-2.9.0.data/data/execsql2_extras/pg_upsert.sql,sha256=k7AFiGTLBy3nf-qO5QIaZrEYTAKvdxxU3JDLx9jqkzs,108315
+execsql2-2.9.0.data/data/execsql2_extras/script_template.sql,sha256=1Estacb_vm1FgK41k_G9nuduP1yiA-fQ1Kn4Z4mv5Ao,11153
+execsql2-2.9.0.data/data/execsql2_extras/ss_compare.sql,sha256=TsVxWm3cEpR5-EiMYXNhtaY0arSNeKZhsJdHdLA7xeI,24833
+execsql2-2.9.0.data/data/execsql2_extras/ss_glossary.sql,sha256=cLM7nN8JOIu9ZVP9oY9qdSK3hrnWJiDcX6nZmQQbQWI,13065
+execsql2-2.9.0.data/data/execsql2_extras/ss_upsert.sql,sha256=BCqmBykXBF-BpCgOFeG1qhf2XfScKsxPD17wd1hYfHw,120647
+execsql2-2.9.0.dist-info/METADATA,sha256=9IJPnmBiSv11eTc7x9Xswfv0KiAwzwizxJX_umIXaSo,16955
+execsql2-2.9.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+execsql2-2.9.0.dist-info/entry_points.txt,sha256=sUOxkM-dN1eBGGpSpDLsAaE0yNXYQKWZAfxPOlMkQyk,90
+execsql2-2.9.0.dist-info/licenses/LICENSE.txt,sha256=LBdhuxejF8_bLCHZ2kWfmDXpDGUu914Gbd6_3JjCRe0,676
+execsql2-2.9.0.dist-info/licenses/NOTICE,sha256=sqVrM73Ys9zfvWC_P797lHfTnoPW_ETeBSrUTFaob0A,339
+execsql2-2.9.0.dist-info/RECORD,,