execsql2 2.17.3__py3-none-any.whl → 2.18.1__py3-none-any.whl

execsql/cli/lint.py

@@ -1,114 +1,103 @@
-"""Legacy flat-CommandList linter and shared result printer for execsql.
-
-The active ``--lint`` implementation is in :mod:`execsql.cli.lint_ast`,
-which works against the AST produced by
-:func:`execsql.script.parser.parse_script`. The CLI reaches that
-linter directly; the ``_lint_cmdlist`` walker in this module is
-unreached from the CLI now and is retained for reference / potential
-reuse only.
-
-What's still used from this module:
-
-- :func:`_print_lint_results` — shared Rich-formatted output for both
-  the AST linter and any code that still constructs lint issues
-  manually. Called from ``cli/__init__.py`` and re-exported via
-  ``cli/run.py``.
-- :class:`_Issue` and the ``_error()`` / ``_warning()`` constructors
-  — used by both linters.
-
-The flat-CommandList ``_lint_cmdlist``, ``_collect_defined_vars``, and
-``_discover_builtin_vars`` helpers below covered the same checks the
-AST linter now performs (unmatched IF/LOOP/BATCH, undefined ``!!$VAR!!``
-references, missing INCLUDE files, EXECUTE SCRIPT flow analysis, empty
-script). They operate on the legacy
-:class:`~execsql.script.engine.CommandList`; no CLI path constructs
-that representation any more.
-
-Exit-code contract (still honoured by the AST linter):
-
-- ``1`` when at least one error-severity issue is found.
-- ``0`` when only warnings (or nothing) are found.
+"""AST-based static analysis (``--lint``) for execsql scripts.
+
+Operates on the :class:`~execsql.script.ast.Script` tree produced by
+:func:`execsql.script.parser.parse_script` / ``parse_string``. Runs as
+an early CLI exit — no DB connection and no ``_state`` initialisation
+required.
+
+Checks performed:
+
+1. **Parse errors** — the AST parser rejects unmatched IF / LOOP /
+   BATCH / SCRIPT blocks at parse time with precise source spans;
+   ``cli/__init__.py`` reports any parse failure as a lint error before
+   :func:`lint` is even called.
+2. **Empty scripts** — warns when no nodes were parsed.
+3. **Potentially undefined variables** — flags ``!!$VAR!!`` references
+   with no preceding ``SUB``-family definition, ignoring built-in
+   ``$VAR`` names discovered from the package source and the
+   non-``$`` sigils (``~``, ``#``, ``+``, ``@``, ``&``) that resolve at
+   runtime.
+4. **Missing INCLUDE files** — warns when the resolved target does not
+   exist on disk (skipped when ``IF EXISTS`` is present).
+5. **EXECUTE SCRIPT target resolution** — warns when a target name does
+   not correspond to a :class:`ScriptBlock` in the same file (skipped
+   when ``IF EXISTS`` is present).
+
+Public surface:
+
+- :func:`lint` — entry point; returns a list of
+  ``(severity, source, line_no, message)`` tuples.
+- :func:`_print_lint_results` — Rich console formatter for those
+  tuples; returns the ``--lint`` process exit code (``1`` when any
+  error-severity issue is present, ``0`` otherwise).
+- :data:`_Issue`, :func:`_error`, :func:`_warning` — tuple type alias
+  and constructors used by the walker and the formatter.
 """
 
 from __future__ import annotations
 
 import re
 from pathlib import Path
-from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:
-    from execsql.script.engine import CommandList
+from execsql.script.ast import (
+    BatchBlock,
+    IfBlock,
+    IncludeDirective,
+    LoopBlock,
+    MetaCommandStatement,
+    Node,
+    Script,
+    ScriptBlock,
+    SqlBlock,
+    SqlStatement,
+)
 
-__all__ = ["_lint_script"]
+__all__ = ["_Issue", "_error", "_print_lint_results", "_warning", "lint"]
 
 
 # ---------------------------------------------------------------------------
-# Compiled patterns for metacommand recognition
+# Issue tuple type and constructors
 # ---------------------------------------------------------------------------
 
-# 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)
 
-# 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)
+_Issue = tuple[str, str, int, str]  # (severity, source, line_no, message)
 
-# 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)
+def _error(source: str, line_no: int, message: str) -> _Issue:
+    return ("error", source, line_no, message)
 
-# 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
+def _warning(source: str, line_no: int, message: str) -> _Issue:
+    return ("warning", source, line_no, message)
+
+
+# ---------------------------------------------------------------------------
+# Variable-related patterns
+# ---------------------------------------------------------------------------
+
+_RX_SUB = re.compile(r"^\s*SUB\s+(?P<name>[+~]?\w+)\s+", re.I)
+_RX_SUB_EMPTY = re.compile(r"^\s*SUB_EMPTY\s+(?P<name>[+~]?\w+)\s*$", re.I)
+_RX_SUB_ADD = re.compile(r"^\s*SUB_ADD\s+(?P<name>[+~]?\w+)\s+", re.I)
+_RX_SUB_APPEND = re.compile(r"^\s*SUB_APPEND\s+(?P<name>[+~]?\w+)\s", re.I)
+_RX_SUBDATA = re.compile(r"^\s*SUBDATA\s+(?P<name>[+~]?\w+)\s+", re.I)
 _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,
 )
+_RX_SELECTSUB = re.compile(r"^\s*(?:SELECT_?SUB|PROMPT\s+SELECT_?SUB)\s+", re.I)
+_RX_SUB_LOCAL = re.compile(r"^\s*SUB_LOCAL\s+(?P<name>\w+)\s+", re.I)
+_RX_SUB_TEMPFILE = re.compile(r"^\s*SUB_TEMPFILE\s+(?P<name>\w+)\s", re.I)
+_RX_SUB_DECRYPT = re.compile(r"^\s*SUB_DECRYPT\s+(?P<name>\w+)\s+", re.I)
+_RX_SUB_ENCRYPT = re.compile(r"^\s*SUB_ENCRYPT\s+(?P<name>\w+)\s+", re.I)
+_RX_SUB_QUERYSTRING = re.compile(r"^\s*SUB_QUERYSTRING\s+(?P<name>\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*$",
-    re.I,
-)
-
-# Variable reference — !!name!! where name may start with $, @, &, ~, #, +
 _RX_VAR_REF = re.compile(r"!!([$@&~#+]?\w+)!!", re.I)
 
-# 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 ``$``.
+
+# ---------------------------------------------------------------------------
+# Built-in variable discovery
+# ---------------------------------------------------------------------------
 
 
 def _discover_builtin_vars() -> frozenset[str]:
@@ -138,227 +127,122 @@ def _discover_builtin_vars() -> frozenset[str]:
     return frozenset(names)
 
 
-_BUILTIN_VARS: frozenset[str] = _discover_builtin_vars()
-
-
-# ---------------------------------------------------------------------------
-# Issue tuple helpers
-# ---------------------------------------------------------------------------
-
-_Issue = tuple[str, str, int, str]  # (severity, source, line_no, message)
+_BUILTIN_VARS: frozenset[str] | None = None
 
 
-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)
+def _get_builtin_vars() -> frozenset[str]:
+    """Return the cached set of built-in variable names, discovering on first call."""
+    global _BUILTIN_VARS
+    if _BUILTIN_VARS is None:
+        _BUILTIN_VARS = _discover_builtin_vars()
+    return _BUILTIN_VARS
 
 
 # ---------------------------------------------------------------------------
-# Core lint implementation
+# AST walker helpers
 # ---------------------------------------------------------------------------
 
 
-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.
+def _collect_script_blocks(script: Script) -> dict[str, ScriptBlock]:
+    """Build a name → ScriptBlock lookup from all ScriptBlock nodes in the tree."""
+    blocks: dict[str, ScriptBlock] = {}
+    for node in script.walk():
+        if isinstance(node, ScriptBlock):
+            blocks[node.name] = node
+    return blocks
 
-    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],
+def _collect_defined_vars_from_nodes(
+    nodes: list[Node],
+    script_blocks: dict[str, ScriptBlock],
+    script_dir: Path | None,
+    defined: set[str],
+    visited: set[str] | None = None,
+) -> None:
+    """Walk nodes and collect variable definitions into *defined*."""
+    if visited is None:
+        visited = set()
+
+    for node in nodes:
+        if isinstance(node, MetaCommandStatement):
+            _extract_var_definition(node.command, script_dir, defined)
+
+        elif isinstance(node, IncludeDirective) and node.is_execute_script:
+            target = node.target.lower()
+            if target in script_blocks and target not in visited:
+                visited.add(target)
+                _collect_defined_vars_from_nodes(
+                    script_blocks[target].body,
+                    script_blocks,
                     script_dir,
-                    defined_vars,
-                    _savedscripts=_savedscripts,
-                    _visited_scripts=visited,
+                    defined,
+                    visited,
                 )
 
+        # Recurse into block children
+        if isinstance(node, (IfBlock, LoopBlock, BatchBlock, ScriptBlock, SqlBlock)):
+            _collect_defined_vars_from_nodes(
+                list(node.children()),
+                script_blocks,
+                script_dir,
+                defined,
+                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]:
-    """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: 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.
-    """
-    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]] = []
-
-    # 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
-        stmt = 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 — variable references
-        for m in _RX_VAR_REF.finditer(stmt):
-            _check_var_ref(m.group(1), src, lno, defined_vars, issues)
+def _extract_var_definition(
+    command: str,
+    script_dir: Path | None,
+    defined: set[str],
+) -> None:
+    """Extract variable name from a SUB-family metacommand into *defined*."""
+    for rx in (
+        _RX_SUB,
+        _RX_SUB_EMPTY,
+        _RX_SUB_ADD,
+        _RX_SUB_APPEND,
+        _RX_SUBDATA,
+        _RX_SUB_LOCAL,
+        _RX_SUB_TEMPFILE,
+        _RX_SUB_DECRYPT,
+        _RX_SUB_ENCRYPT,
+        _RX_SUB_QUERYSTRING,
+    ):
+        m = rx.match(command)
+        if m:
+            defined.add(m.group("name").lstrip("+~").upper())
+            return
+
+    # SUB_INI bulk-defines from INI file — read keys at lint time
+    ini_m = _RX_SUB_INI.match(command)
+    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)
 
-        # -- 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()
+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."""
+    from configparser import ConfigParser
 
-        # -- BATCH --
-        elif _RX_BEGIN_BATCH.match(stmt):
-            batch_depth += 1
-            batch_open_locs.append((src, lno))
+    p = Path(ini_file)
+    if not p.is_absolute() and script_dir is not None:
+        p = script_dir / p
 
-        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()
-
-        # -- 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)
-        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"))
+    if not p.exists():
+        return
 
-    return issues
+    cp = ConfigParser()
+    cp.read(p)
+    if cp.has_section(section):
+        for key, _value in cp.items(section):
+            defined_vars.add(key.upper())
 
 
 def _check_var_ref(
@@ -368,27 +252,14 @@ def _check_var_ref(
     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.
-    """
+    """Emit a warning if *raw_name* looks like an undefined user variable."""
     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
+    # Skip non-$ sigil prefixes — resolved at runtime
     if sigil in ("@", "&", "~", "#", "+"):
         return
 
@@ -396,12 +267,12 @@ def _check_var_ref(
     if re.match(r"^ARG_\d+$", name, re.I):
         return
 
-    # $COUNTER_N is managed by CounterVars (@@counter metacommands)
+    # $COUNTER_N is managed by CounterVars
     if re.match(r"^COUNTER_\d+$", name, re.I):
         return
 
     # Built-in system variables
-    if name.upper() in _BUILTIN_VARS:
+    if name.upper() in _get_builtin_vars():
         return
 
     # User-defined via SUB
@@ -418,172 +289,167 @@ def _check_var_ref(
     )
 
 
-def _read_ini_vars(
-    ini_file: str,
-    section: str,
+def _check_include_path(
+    raw_path: str,
     script_dir: Path | None,
-    defined_vars: set[str],
+    source: str,
+    line_no: int,
+    issues: list[_Issue],
 ) -> 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)
+    """Warn if the INCLUDE target does not exist on disk."""
+    p = Path(raw_path)
     if not p.is_absolute() and script_dir is not None:
         p = script_dir / p
 
     if not p.exists():
-        return
+        issues.append(
+            _warning(source, line_no, f"INCLUDE target does not exist: {raw_path!r}"),
+        )
 
-    cp = ConfigParser()
-    cp.read(p)
-    if cp.has_section(section):
-        for key, _value in cp.items(section):
-            defined_vars.add(key.upper())
 
+# ---------------------------------------------------------------------------
+# Core lint walk
+# ---------------------------------------------------------------------------
 
-def _check_include_path(
-    raw_path: str,
+
+def _lint_nodes(
+    nodes: list[Node],
     script_dir: Path | None,
-    source: str,
-    line_no: int,
-    stmt: str,
+    defined_vars: set[str],
+    script_blocks: dict[str, ScriptBlock],
     issues: list[_Issue],
+    *,
+    visited_scripts: set[str] | None = None,
 ) -> None:
-    """Warn if the INCLUDE target does not exist on disk.
+    """Walk a list of AST nodes and collect lint issues."""
+    if visited_scripts is None:
+        visited_scripts = set()
 
-    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
+    for node in nodes:
+        src = node.span.file
+        lno = node.span.start_line
 
-    p = Path(raw_path)
-    if not p.is_absolute() and script_dir is not None:
-        p = script_dir / p
+        # -- Variable references in SQL --
+        if isinstance(node, SqlStatement):
+            for m in _RX_VAR_REF.finditer(node.text):
+                _check_var_ref(m.group(1), src, lno, defined_vars, issues)
 
-    if not p.exists():
-        issues.append(
-            _warning(
-                source,
-                line_no,
-                f"INCLUDE target does not exist: {raw_path!r}",
-            ),
-        )
+        # -- Metacommand checks --
+        elif isinstance(node, MetaCommandStatement):
+            for m in _RX_VAR_REF.finditer(node.command):
+                _check_var_ref(m.group(1), src, lno, defined_vars, issues)
+
+        # -- IncludeDirective checks --
+        elif isinstance(node, IncludeDirective):
+            if node.is_execute_script:
+                target = node.target.lower()
+                if target not in script_blocks:
+                    if not node.if_exists:
+                        issues.append(
+                            _warning(src, lno, f"EXECUTE SCRIPT target not found: '{target}'"),
+                        )
+                elif target not in visited_scripts:
+                    visited_scripts.add(target)
+                    _lint_nodes(
+                        script_blocks[target].body,
+                        script_dir,
+                        defined_vars,
+                        script_blocks,
+                        issues,
+                        visited_scripts=visited_scripts,
+                    )
+            else:
+                # INCLUDE file existence check
+                if not node.if_exists:
+                    raw_path = node.target.strip().strip("\"'")
+                    if not _RX_VAR_REF.search(raw_path):
+                        _check_include_path(raw_path, script_dir, src, lno, issues)
+
+        # -- Recurse into block children --
+        if isinstance(node, IfBlock):
+            _lint_nodes(node.body, script_dir, defined_vars, script_blocks, issues, visited_scripts=visited_scripts)
+            for clause in node.elseif_clauses:
+                _lint_nodes(
+                    clause.body,
+                    script_dir,
+                    defined_vars,
+                    script_blocks,
+                    issues,
+                    visited_scripts=visited_scripts,
+                )
+            _lint_nodes(
+                node.else_body,
+                script_dir,
+                defined_vars,
+                script_blocks,
+                issues,
+                visited_scripts=visited_scripts,
+            )
+        elif isinstance(node, (LoopBlock, BatchBlock, SqlBlock)):
+            _lint_nodes(node.body, script_dir, defined_vars, script_blocks, issues, visited_scripts=visited_scripts)
+        elif isinstance(node, ScriptBlock):
+            # Lint script block body (structural errors already caught by parser)
+            if node.name not in visited_scripts:
+                visited_scripts.add(node.name)
+                sub_issues: list[_Issue] = []
+                _lint_nodes(
+                    node.body,
+                    script_dir,
+                    defined_vars,
+                    script_blocks,
+                    sub_issues,
+                    visited_scripts=visited_scripts,
+                )
+                for sev, ssrc, slno, msg in sub_issues:
+                    issues.append((sev, ssrc, slno, f"[script '{node.name}'] {msg}"))
 
 
-def _lint_script(
-    cmdlist: CommandList | None,
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def lint(
+    script: Script,
     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).
+    """Perform static analysis on an AST-parsed script.
 
     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.
+        script: The parsed :class:`Script` tree.
+        script_path: Path to the source file (for resolving relative
+            INCLUDE paths).  ``None`` for inline scripts.
 
     Returns:
-        List of ``(severity, source, line_no, message)`` tuples, one per issue
-        found.  An empty list means the script is clean.
+        List of ``(severity, source, line_no, message)`` issue tuples.
     """
-    import execsql.state as _state
-
     issues: list[_Issue] = []
 
-    if cmdlist is None or not cmdlist.cmdlist:
+    if not script.body:
         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
-    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.
-    # ------------------------------------------------------------------
+    script_blocks = _collect_script_blocks(script)
+
+    # Pass 1: collect all variable definitions
     all_defined: set[str] = set()
-    collect_visited: set[str] = set()
-    _collect_defined_vars(
-        cmdlist,
+    _collect_defined_vars_from_nodes(script.body, script_blocks, script_dir, all_defined)
+
+    # Pass 2: lint for variable and include issues
+    _lint_nodes(
+        script.body,
         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,
-        )
-
-    # ------------------------------------------------------------------
-    # 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,
-        ),
+        script_blocks,
+        issues,
     )
 
-    # 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:
-            issues.append((sev, src, lno, f"[script '{script_name}'] {msg}"))
-
     return issues
 
 
 # ---------------------------------------------------------------------------
-# Rich output helper
+# Result printing
 # ---------------------------------------------------------------------------