execsql2 2.13.0__tar.gz → 2.13.2__tar.gz

{execsql2-2.13.0 → execsql2-2.13.2}/CHANGELOG.md

@@ -13,6 +13,31 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.13.2] - 2026-04-06
+
+### Changed
+
+- `--lint` static analysis improvements:
+    - Track `SUB_EMPTY`, `SUB_ADD`, `SUB_APPEND`, and `SUBDATA` as variable definitions, eliminating false undefined-variable warnings.
+    - Descend into named script blocks via `EXECUTE SCRIPT` / `EXEC SCRIPT` / `RUN SCRIPT` so variables defined inside are visible to the caller.
+    - Two-pass variable collection: definition order no longer matters. Variables can be referenced before their SUB definition without false warnings.
+    - Read `SUB_INI` INI files at lint time and register section keys as defined variables.
+    - Auto-discover built-in system variables by scanning installed source instead of a hand-maintained list.
+    - Exclude `$COUNTER_N` variables from undefined-variable warnings.
+    - Warn when `EXECUTE SCRIPT` targets a non-existent script block (respects `IF EXISTS`).
+    - Eliminate duplicate warnings for script blocks reached via multiple execution paths.
+    - Sort errors before warnings, both by line number. Pad location columns for alignment.
+
+______________________________________________________________________
+
+## [2.13.1] - 2026-04-04
+
+### Changed
+
+- Bump pg-upsert minimum to >=1.20.0.
+
+______________________________________________________________________
+
 ## [2.13.0] - 2026-04-04
 
 ### Added

{execsql2-2.13.0 → execsql2-2.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.13.0
+Version: 2.13.2
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql
@@ -51,7 +51,7 @@ Requires-Dist: keyring; extra == 'all'
 Requires-Dist: odfpy; extra == 'all'
 Requires-Dist: openpyxl; extra == 'all'
 Requires-Dist: oracledb; extra == 'all'
-Requires-Dist: pg-upsert>=1.18.2; extra == 'all'
+Requires-Dist: pg-upsert>=1.20.0; extra == 'all'
 Requires-Dist: polars; extra == 'all'
 Requires-Dist: psycopg2-binary; extra == 'all'
 Requires-Dist: pymysql; extra == 'all'
@@ -109,7 +109,7 @@ Requires-Dist: oracledb; extra == 'oracle'
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary; extra == 'postgres'
 Provides-Extra: upsert
-Requires-Dist: pg-upsert>=1.18.2; extra == 'upsert'
+Requires-Dist: pg-upsert>=1.20.0; extra == 'upsert'
 Description-Content-Type: text/markdown
 
 > [!NOTE]

{execsql2-2.13.0 → execsql2-2.13.2}/docs/about/divergence.md

@@ -13,21 +13,21 @@ ______________________________________________________________________
 
 ### CLI Options
 
-| Flag                            | Description                                                                                                                                                                                                                                                                                                                             |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--version`                     | Print version and exit (Rich-formatted).                                                                                                                                                                                                                                                                                                |
-| `-c` / `--command`              | Execute an inline SQL or metacommand string instead of a script file.                                                                                                                                                                                                                                                                   |
-| `--dsn` / `--connection-string` | Accept a standard database URL (e.g. `postgresql://user:pass@host/db`). Supports `postgresql`, `mysql`, `mssql`, `oracle`, `firebird`, `sqlite`, and `duckdb` schemes.                                                                                                                                                                  |
-| `--output-dir`                  | Set a default base directory for export output files.                                                                                                                                                                                                                                                                                   |
-| `--progress`                    | Show a Rich progress bar during long-running IMPORT operations.                                                                                                                                                                                                                                                                         |
-| `--dump-keywords`               | Emit all metacommand keywords, conditionals, config options, and export formats as structured JSON.                                                                                                                                                                                                                                     |
-| `--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.                                                                                          |
-| `--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.                      |
+| Flag                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--version`                     | Print version and exit (Rich-formatted).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `-c` / `--command`              | Execute an inline SQL or metacommand string instead of a script file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--dsn` / `--connection-string` | Accept a standard database URL (e.g. `postgresql://user:pass@host/db`). Supports `postgresql`, `mysql`, `mssql`, `oracle`, `firebird`, `sqlite`, and `duckdb` schemes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--output-dir`                  | Set a default base directory for export output files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--progress`                    | Show a Rich progress bar during long-running IMPORT operations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--dump-keywords`               | Emit all metacommand keywords, conditionals, config options, and export formats as structured JSON.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `--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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `--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); missing INCLUDE file targets (warnings); and unknown `EXECUTE SCRIPT` targets (warnings). Variable analysis uses two passes so definition order does not matter. The linter descends into named script blocks reached via `EXECUTE SCRIPT` / `EXEC SCRIPT` / `RUN SCRIPT`, reads `SUB_INI` INI files at lint time, recognizes `SUB_EMPTY` / `SUB_ADD` / `SUB_APPEND` / `SUBDATA` as definitions, suppresses false warnings for `$COUNTER_N`, and auto-discovers built-in system variables from the installed source. Exits 0 if no errors, 1 if errors found. |
 
 ### Export Formats
 

{execsql2-2.13.0 → execsql2-2.13.2}/docs/getting-started/syntax.md

@@ -205,10 +205,15 @@ Valid encoding names can be displayed with the `-y` option. See also [Character
     - **Unmatched IF / ENDIF** — open IF blocks with no closing ENDIF, or orphan ENDIF with no IF (error).
     - **Unmatched LOOP / END LOOP** — open LOOP with no END LOOP, or orphan END LOOP (error).
     - **Unmatched BEGIN BATCH / END BATCH** — open batch with no close, or orphan END BATCH (error).
-    - **Potentially undefined variables** — `!!$VAR!!` references where `$VAR` is not a built-in variable, not `$ARG_N`, and was not defined by a preceding `SUB` metacommand in the same script (warning — may be a false-positive if the variable is set in a config file or via `-a`).
+    - **Potentially undefined variables** — `!!$VAR!!` references where `$VAR` is not a built-in system variable, not `$ARG_N`, not `$COUNTER_N`, and was not defined by a `SUB`, `SUB_EMPTY`, `SUB_ADD`, `SUB_APPEND`, `SUBDATA`, or `SUB_INI` metacommand anywhere in the script (warning — may be a false-positive if the variable is set in a config file or via `-a`).
     - **Missing INCLUDE files** — `INCLUDE` targets that do not exist on disk relative to the script's directory (warning; `INCLUDE IF EXISTS` targets are never checked).
+    - **Unknown EXECUTE SCRIPT target** — `EXECUTE SCRIPT` names a script block that was not defined in the file (warning; `EXECUTE SCRIPT IF EXISTS` targets are never warned about).
     - **Empty script** — no commands found (warning).
 
+    Variable analysis uses two passes: the first collects every variable definition across the entire script and all named script blocks; the second performs the checks. Variables may be referenced before their definition point without producing false warnings. The linter also descends into named script blocks (`BEGIN SCRIPT … END SCRIPT`) reached via `EXECUTE SCRIPT`, `EXEC SCRIPT`, or `RUN SCRIPT`, so variables defined inside a block are visible to the caller. `SUB_INI` INI files are read at lint time to register their section keys as defined variables.
+
+    Built-in system variables are discovered automatically from the installed execsql source, so new variables added in future releases are recognized without any linter changes.
+
     Exits 0 when no errors are found (warnings alone do not affect the exit code). Exits 1 when any errors are found.
 
     ```bash

{execsql2-2.13.0 → execsql2-2.13.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.13.0"
+version = "2.13.2"
 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" }
@@ -58,7 +58,7 @@ odbc = ["pyodbc"]
 # Feature bundles
 formats = ["odfpy", "xlrd", "openpyxl", "Jinja2", "polars", "tables", "PyYAML"]
 auth = ["keyring"]
-upsert = ["pg-upsert>=1.18.2"]
+upsert = ["pg-upsert>=1.20.0"]
 # Convenience groups
 all-db = [
     "psycopg2-binary",
@@ -161,7 +161,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.13.0"
+current_version = "2.13.2"
 commit = true
 commit_args = "--no-verify"
 tag = true

{execsql2-2.13.0 → execsql2-2.13.2}/src/execsql/cli/lint.py

@@ -10,11 +10,18 @@ Checks performed
 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
+   ``SUB`` (or ``SUB_EMPTY``, ``SUB_ADD``, ``SUB_APPEND``, ``SUBDATA``)
+   metacommand in the same parsed command list and not in the set of built-in
+   variables (warning).  Note: ``SUB_INI`` and ``SELECT_SUB`` define variables
+   whose names are not statically knowable — those may produce false-positive
+   warnings.
+5. **EXECUTE SCRIPT flow analysis** — when an ``EXECUTE SCRIPT <name>``
+   metacommand is encountered, the linter descends into the named script
+   block (if found in ``_state.savedscripts``) and merges any variables it
+   defines back into the caller's scope.
+6. **Missing INCLUDE files** — INCLUDE target does not exist on disk relative
    to the script directory (warning).
-6. **Empty script** — no commands found (warning).
+7. **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
@@ -67,6 +74,31 @@ _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)
 
+# SUB_EMPTY <varname> — defines a variable with empty string
+_RX_SUB_EMPTY = re.compile(r"^\s*SUB_EMPTY\s+(?P<name>[+~]?\w+)\s*$", re.I)
+
+# SUB_ADD <varname> <expr> — increments a variable (implies it exists)
+_RX_SUB_ADD = re.compile(r"^\s*SUB_ADD\s+(?P<name>[+~]?\w+)\s+", re.I)
+
+# SUB_APPEND <varname> <text> — appends to a variable (implies it exists)
+_RX_SUB_APPEND = re.compile(r"^\s*SUB_APPEND\s+(?P<name>[+~]?\w+)\s", re.I)
+
+# SUBDATA <varname> <datasource> — defines a variable from a query result
+_RX_SUBDATA = re.compile(r"^\s*SUBDATA\s+(?P<name>[+~]?\w+)\s+", re.I)
+
+# SUB_INI [FILE] <filename> [SECTION] <section> — bulk-defines variables from INI file
+_RX_SUB_INI = re.compile(
+    r'^\s*SUB_INI\s+(?:FILE\s+)?(?:"(?P<qfile>[^"]+)"|(?P<file>\S+))'
+    r"(?:\s+SECTION)?\s+(?P<section>\w+)\s*$",
+    re.I,
+)
+
+# EXECUTE SCRIPT / EXEC SCRIPT / RUN SCRIPT
+_RX_EXEC_SCRIPT = re.compile(
+    r"^\s*(?:EXEC(?:UTE)?|RUN)\s+SCRIPT(?:\s+IF\s+EXISTS)?\s+(?P<script_id>\w+)",
+    re.I,
+)
+
 # INCLUDE <file>
 _RX_INCLUDE = re.compile(
     r"^\s*INCLUDE(?:\s+IF\s+EXISTS?)?\s+(?P<path>\S+.*?)\s*$",
@@ -76,67 +108,41 @@ _RX_INCLUDE = re.compile(
 # 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
-    },
-)
+# Built-in system variables — extracted automatically from the installed
+# ``execsql`` source by scanning for ``add_substitution("$NAME", ...)`` and
+# ``register_lazy("$NAME", ...)`` calls.  This avoids maintaining a hand-
+# curated list that drifts out of sync when new system variables are added.
+# Variable names are stored upper-case without the leading ``$``.
+
+
+def _discover_builtin_vars() -> frozenset[str]:
+    """Scan the execsql package source for ``$VARNAME`` system variables."""
+    import importlib.util
+
+    _rx_add_sub = re.compile(r'(?:(?<!\w)add_substitution|(?<!\w)sv)\s*\(\s*["\'](\$\w+)["\']')
+    _rx_lazy = re.compile(r'register_lazy\s*\(\s*["\'](\$\w+)["\']')
+
+    names: set[str] = set()
+
+    spec = importlib.util.find_spec("execsql")
+    if spec is None or spec.submodule_search_locations is None:
+        return frozenset(names)
+
+    pkg_dir = Path(spec.submodule_search_locations[0])
+    for src_file in pkg_dir.rglob("*.py"):
+        try:
+            text = src_file.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        for m in _rx_add_sub.finditer(text):
+            names.add(m.group(1).lstrip("$").upper())
+        for m in _rx_lazy.finditer(text):
+            names.add(m.group(1).lstrip("$").upper())
+
+    return frozenset(names)
+
+
+_BUILTIN_VARS: frozenset[str] = _discover_builtin_vars()
 
 
 # ---------------------------------------------------------------------------
@@ -159,23 +165,90 @@ def _warning(source: str, line_no: int, message: str) -> _Issue:
 # ---------------------------------------------------------------------------
 
 
+def _collect_defined_vars(
+    cmdlist: CommandList,
+    script_dir: Path | None,
+    defined_vars: set[str],
+    *,
+    _savedscripts: dict | None = None,
+    _visited_scripts: set[str] | None = None,
+) -> None:
+    """Pass 1: walk *cmdlist* and collect all variable definitions into *defined_vars*.
+
+    This populates the set with every variable name that could be defined at
+    runtime — ``SUB``, ``SUB_EMPTY``, ``SUB_ADD``, ``SUB_APPEND``,
+    ``SUBDATA``, and ``SUB_INI`` (by reading the INI file on disk).  It also
+    descends into ``EXECUTE SCRIPT`` targets to collect their definitions.
+
+    No issues are reported; structural checks and variable-reference validation
+    happen in pass 2 (:func:`_lint_cmdlist`).
+    """
+    visited = _visited_scripts if _visited_scripts is not None else set()
+
+    for cmd in cmdlist.cmdlist:
+        if cmd.command_type == "sql":
+            continue
+        stmt = cmd.command.statement
+
+        # SUB <name> <value>
+        sub_m = _RX_SUB.match(stmt)
+        if sub_m:
+            defined_vars.add(sub_m.group("name").lstrip("+~").upper())
+
+        # SUB_EMPTY / SUB_ADD / SUB_APPEND / SUBDATA
+        for rx in (_RX_SUB_EMPTY, _RX_SUB_ADD, _RX_SUB_APPEND, _RX_SUBDATA):
+            m = rx.match(stmt)
+            if m:
+                defined_vars.add(m.group("name").lstrip("+~").upper())
+                break
+
+        # SUB_INI — read INI file keys
+        ini_m = _RX_SUB_INI.match(stmt)
+        if ini_m:
+            ini_file = ini_m.group("qfile") or ini_m.group("file")
+            ini_section = ini_m.group("section")
+            if ini_file and not _RX_VAR_REF.search(ini_file):
+                _read_ini_vars(ini_file, ini_section, script_dir, defined_vars)
+
+        # EXECUTE SCRIPT — descend into named script block
+        exec_m = _RX_EXEC_SCRIPT.match(stmt)
+        if exec_m and _savedscripts is not None:
+            script_id = exec_m.group("script_id").lower()
+            if script_id in _savedscripts and script_id not in visited:
+                visited.add(script_id)
+                _collect_defined_vars(
+                    _savedscripts[script_id],
+                    script_dir,
+                    defined_vars,
+                    _savedscripts=_savedscripts,
+                    _visited_scripts=visited,
+                )
+
+
 def _lint_cmdlist(
     cmdlist: CommandList,
     script_dir: Path | None,
     defined_vars: set[str],
+    *,
+    _savedscripts: dict | None = None,
+    _visited_scripts: set[str] | None = None,
 ) -> list[_Issue]:
-    """Lint a single :class:`CommandList` and return any issues found.
+    """Pass 2: lint a :class:`CommandList` for structural and variable issues.
 
     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.
+        defined_vars: Set of variable names (without sigil) that have been
+            pre-collected by :func:`_collect_defined_vars`.  This includes
+            *all* top-level and script-block definitions so that ordering
+            does not matter.
+        _savedscripts: Dictionary of named script blocks (from
+            ``_state.savedscripts``).  Passed explicitly so the function can
+            descend into EXECUTE SCRIPT targets.
+        _visited_scripts: Set of script IDs already descended into, shared
+            across recursive calls to prevent infinite recursion from circular
+            EXECUTE SCRIPT references.
 
     Returns:
         List of ``(severity, source, line_no, message)`` issue tuples.
@@ -191,6 +264,10 @@ def _lint_cmdlist(
     batch_depth = 0
     batch_open_locs: list[tuple[str, int]] = []
 
+    # Track which EXECUTE SCRIPT targets we've already descended into to
+    # prevent infinite recursion from circular script references.
+    visited_scripts: set[str] = _visited_scripts if _visited_scripts is not None else set()
+
     for cmd in cmdlist.cmdlist:
         src = cmd.source
         lno = cmd.line_no
@@ -202,7 +279,7 @@ def _lint_cmdlist(
                 _check_var_ref(m.group(1), src, lno, defined_vars, issues)
             continue
 
-        # Metacommand checks
+        # Metacommand checks — variable references
         for m in _RX_VAR_REF.finditer(stmt):
             _check_var_ref(m.group(1), src, lno, defined_vars, issues)
 
@@ -247,11 +324,27 @@ def _lint_cmdlist(
                 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())
+        # -- EXECUTE SCRIPT — descend into named script block --
+        exec_m = _RX_EXEC_SCRIPT.match(stmt)
+        if exec_m and _savedscripts is not None:
+            script_id = exec_m.group("script_id").lower()
+            if script_id not in _savedscripts:
+                # Warn unless it's EXECUTE SCRIPT IF EXISTS
+                if not re.search(r"\bIF\s+EXISTS\b", stmt, re.I):
+                    issues.append(
+                        _warning(src, lno, f"EXECUTE SCRIPT target not found: '{script_id}'"),
+                    )
+            elif script_id not in visited_scripts:
+                visited_scripts.add(script_id)
+                sub_issues = _lint_cmdlist(
+                    _savedscripts[script_id],
+                    script_dir,
+                    defined_vars,
+                    _savedscripts=_savedscripts,
+                    _visited_scripts=visited_scripts,
+                )
+                for sev, ssrc, slno, msg in sub_issues:
+                    issues.append((sev, ssrc, slno, f"[script '{script_id}'] {msg}"))
 
         # -- INCLUDE file existence --
         inc_m = _RX_INCLUDE.match(stmt)
@@ -307,6 +400,10 @@ def _check_var_ref(
     if re.match(r"^ARG_\d+$", name, re.I):
         return
 
+    # $COUNTER_N is managed by CounterVars (@@counter metacommands)
+    if re.match(r"^COUNTER_\d+$", name, re.I):
+        return
+
     # Built-in system variables
     if name.upper() in _BUILTIN_VARS:
         return
@@ -325,6 +422,35 @@ def _check_var_ref(
     )
 
 
+def _read_ini_vars(
+    ini_file: str,
+    section: str,
+    script_dir: Path | None,
+    defined_vars: set[str],
+) -> None:
+    """Read an INI file and register its section keys as defined variables.
+
+    Mirrors what ``SUB_INI`` does at runtime: reads a
+    :class:`~configparser.ConfigParser` section and defines each key as a
+    substitution variable.  If the file does not exist or the section is
+    missing, silently does nothing (the runtime handler behaves the same way).
+    """
+    from configparser import ConfigParser
+
+    p = Path(ini_file)
+    if not p.is_absolute() and script_dir is not None:
+        p = script_dir / p
+
+    if not p.exists():
+        return
+
+    cp = ConfigParser()
+    cp.read(p)
+    if cp.has_section(section):
+        for key, _value in cp.items(section):
+            defined_vars.add(key.upper())
+
+
 def _check_include_path(
     raw_path: str,
     script_dir: Path | None,
@@ -393,19 +519,68 @@ def _lint_script(
         return issues
 
     script_dir = Path(script_path).resolve().parent if script_path else None
+    savedscripts: dict = getattr(_state, "savedscripts", {})
+
+    # ------------------------------------------------------------------
+    # Pass 1: collect all variable definitions from the top-level script
+    # and all reachable script blocks.  This ensures definition order does
+    # not matter — a script block executed early can reference variables
+    # defined later in the top-level script.
+    # ------------------------------------------------------------------
+    all_defined: set[str] = set()
+    collect_visited: set[str] = set()
+    _collect_defined_vars(
+        cmdlist,
+        script_dir,
+        all_defined,
+        _savedscripts=savedscripts,
+        _visited_scripts=collect_visited,
+    )
+    # Also collect from every saved script block (they may define vars
+    # referenced by other blocks).  Share the visited set so each block
+    # is only traversed once (O(N) instead of O(N²)).
+    for saved_cl in savedscripts.values():
+        _collect_defined_vars(
+            saved_cl,
+            script_dir,
+            all_defined,
+            _savedscripts=savedscripts,
+            _visited_scripts=collect_visited,
+        )
 
-    # 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))
+    # ------------------------------------------------------------------
+    # Pass 2: lint for structural issues and undefined-variable warnings
+    # using the complete variable set from pass 1.
+    # ------------------------------------------------------------------
+    # Shared visited-scripts tracker — prevents duplicate lint warnings
+    # when the same script block is reached via multiple paths.
+    visited: set[str] = set()
+
+    issues.extend(
+        _lint_cmdlist(
+            cmdlist,
+            script_dir,
+            all_defined,
+            _savedscripts=savedscripts,
+            _visited_scripts=visited,
+        ),
+    )
 
-    # 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))
+    # Analyse each named SCRIPT block that was NOT already visited via
+    # EXECUTE SCRIPT (standalone analysis catches structural issues like
+    # unmatched IF/ENDIF in script blocks that are never executed).
+    for script_name, saved_cl in savedscripts.items():
+        if script_name in visited:
+            continue
+        visited.add(script_name)
+        saved_issues = _lint_cmdlist(
+            saved_cl,
+            script_dir,
+            set(all_defined),
+            _savedscripts=savedscripts,
+            _visited_scripts=visited,
+        )
         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
@@ -440,12 +615,22 @@ def _print_lint_results(issues: list[_Issue], script_label: str) -> int:
         _console.print()
         return 0
 
-    for severity, source, line_no, message in issues:
-        loc = f"{source}:{line_no}" if line_no else source
+    # Sort: errors first, then warnings; within each group sort by line number.
+    _sev_order = {"error": 0, "warning": 1}
+    sorted_issues = sorted(issues, key=lambda i: (_sev_order.get(i[0], 9), i[2]))
+
+    # Compute the widest location string so columns align.
+    locs: list[str] = []
+    for _, source, line_no, _ in sorted_issues:
+        locs.append(f"{source}:{line_no}" if line_no else source)
+    loc_width = max(len(loc) for loc in locs) if locs else 0
+
+    for (severity, _source, _line_no, message), loc in zip(sorted_issues, locs):
+        pad = " " * (loc_width - len(loc))
         if severity == "error":
-            _console.print(f"  [bold red]ERROR  [/bold red]  [dim]{loc}[/dim]  {message}")
+            _console.print(f"  [bold red]ERROR  [/bold red]  [dim]{loc}[/dim]{pad}  {message}")
         else:
-            _console.print(f"  [bold yellow]WARNING[/bold yellow]  [dim]{loc}[/dim]  {message}")
+            _console.print(f"  [bold yellow]WARNING[/bold yellow]  [dim]{loc}[/dim]{pad}  {message}")
 
     _console.print()
     parts = []