execsql2 2.24.0__py3-none-any.whl → 2.25.1__py3-none-any.whl

execsql/cli/lint.py

@@ -7,10 +7,10 @@ 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.
+1. **Parse errors** — :func:`lint_source` parses with error recovery, so
+   every unmatched or unclosed IF / LOOP / BATCH / SCRIPT / SQL block is a
+   ``P001`` at its own line and the remaining checks run on the recovered
+   tree.
 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
@@ -22,6 +22,12 @@ Checks performed:
 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).
+6. **Unknown metacommands** — reports a metacommand that no entry in the
+   dispatch table ``execsql run`` uses (plus installed plugins) matches,
+   skipping commands that contain a substitution variable.
+7. **Unknown conditions** — parses (never evaluates) every IF, ELSEIF,
+   ANDIF, ORIF, LOOP and EXECUTE SCRIPT ... WHILE/UNTIL condition, and the
+   condition in ASSERT and WAIT_UNTIL, against the conditional-test table.
 
 Every check has a rule code (:data:`RULES`), so a caller can select or
 ignore rules and machine-readable output can name them.
@@ -31,6 +37,8 @@ Public surface:
 - :func:`lint` — entry point; returns a list of :class:`Issue`.
 - :data:`RULES` / :class:`Rule` — the rule registry: code, name, severity.
 - :func:`parse_error` — the :class:`Issue` for a script that fails to parse.
+- :func:`lint_source` — parse script text and lint it: every block-structure
+  error as a ``P001``, plus every other rule on the recovered tree.
 - :func:`resolve_selectors` / :func:`filter_issues` — ``--select`` and
   ``--ignore`` handling.
 - :func:`print_text`, :func:`print_concise`, :func:`print_statistics`,
@@ -45,7 +53,7 @@ import re
 from collections import Counter
 from collections.abc import Iterable
 from pathlib import Path
-from typing import NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
 
 from execsql.exceptions import ErrInfo
 from execsql.script.ast import (
@@ -62,6 +70,10 @@ from execsql.script.ast import (
     SqlStatement,
 )
 
+if TYPE_CHECKING:
+    from execsql.script.engine import MetaCommandList
+    from execsql.script.ast import ConditionModifier
+
 __all__ = [
     "RULES",
     "Issue",
@@ -69,6 +81,7 @@ __all__ = [
     "exit_code",
     "filter_issues",
     "lint",
+    "lint_source",
     "parse_error",
     "print_concise",
     "print_statistics",
@@ -109,6 +122,24 @@ RULES: dict[str, Rule] = {
             "error",
             "The script cannot be parsed, for example an IF, LOOP, BATCH or SCRIPT block that is never closed.",
         ),
+        Rule(
+            "P002",
+            "split-dollar-quote",
+            "error",
+            "A dollar-quoted body ($$ ... $$) is split into separate statements at a line ending in ';'.",
+        ),
+        Rule(
+            "P003",
+            "unknown-metacommand",
+            "error",
+            "A metacommand is misspelled or malformed: no form of any metacommand matches it.",
+        ),
+        Rule(
+            "P004",
+            "unknown-condition",
+            "error",
+            "A condition (IF, ELSEIF, ANDIF, ORIF, LOOP, ASSERT, ...) uses an unknown test or cannot be parsed.",
+        ),
         Rule("S001", "empty-script", "warning", "The script contains no statements."),
         Rule(
             "V001",
@@ -194,12 +225,30 @@ _RX_SUB_INI = re.compile(
 )
 _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)
+_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<qstr>.+?)\s*$", re.I)
+# The prompts that store the answer in a variable.
+_RX_ASK_SUB = re.compile(r"""^\s*(?:PROMPT\s+)?ASK\s+(?:'.*'|".*")\s+SUB\s+(?P<name>~?\w+)(?:\s|$)""", re.I)
+_RX_PROMPT_ENTER_SUB = re.compile(r"^\s*PROMPT\s+ENTER_SUB\s+(?P<name>~?\w+)\s", re.I)
+_RX_PROMPT_DIRECTORY = re.compile(r"^\s*PROMPT\s+DIRECTORY\s+SUB\s+(?P<name>~?\w+)(?:\s|$)", re.I)
+_RX_PROMPT_FILE = re.compile(
+    r"^\s*PROMPT\s+(?:OPENFILE|SAVEFILE)\s+SUB\s+(?P<names>~?\w+(?:\s+~?\w+){0,4})(?=\s+FROM\s|\s*$)",
+    re.I,
+)
+_RX_PROMPT_CREDENTIALS = re.compile(
+    r'^\s*PROMPT(?:\s+MESSAGE)?(?:\s+"[^"]*")?\s+CREDENTIALS\s+(?P<user>\w+)\s+(?P<pw>\w+)\s*$',
+    re.I,
+)
 
 _RX_VAR_REF = re.compile(r"!!([$@&~#+]?\w+)!!", re.I)
+# Every candidate reference, including one nested in another's name
+# (``!!N_!!GROUP!!_CHECKS!!``), which _RX_VAR_REF's left-to-right scan skips.
+_RX_VAR_REF_ANY = re.compile(r"(?=!!([$@&~#+]?\w+)!!)")
+# Stands for a substituted value in _unresolved_var_refs: a word character
+# (so an enclosing name still matches) that no script name contains.
+_SUBSTITUTED = "ª"
 
 
 # ---------------------------------------------------------------------------
@@ -245,6 +294,39 @@ def _get_builtin_vars() -> frozenset[str]:
     return _BUILTIN_VARS
 
 
+_DISPATCH_TABLE: MetaCommandList | None = None
+
+
+def _dispatch_table() -> MetaCommandList:
+    """Return the metacommand table ``execsql run`` dispatches from, built on first call.
+
+    A private copy, with installed metacommand plugins registered, so that
+    linting never adds entries to the table a run in this process uses.
+    """
+    global _DISPATCH_TABLE
+    if _DISPATCH_TABLE is None:
+        from execsql.metacommands.dispatch import build_dispatch_table
+        from execsql.plugins import discover_metacommand_plugins
+
+        table = build_dispatch_table()
+        discover_metacommand_plugins(table)
+        _DISPATCH_TABLE = table
+    return _DISPATCH_TABLE
+
+
+_CONDITIONAL_TABLE: MetaCommandList | None = None
+
+
+def _conditional_table() -> MetaCommandList:
+    """Return the table of conditional tests ``execsql run`` evaluates with, built on first call."""
+    global _CONDITIONAL_TABLE
+    if _CONDITIONAL_TABLE is None:
+        from execsql.metacommands.conditions import build_conditional_table
+
+        _CONDITIONAL_TABLE = build_conditional_table()
+    return _CONDITIONAL_TABLE
+
+
 # ---------------------------------------------------------------------------
 # AST walker helpers
 # ---------------------------------------------------------------------------
@@ -302,7 +384,7 @@ def _extract_var_definition(
     script_dir: Path | None,
     defined: set[str],
 ) -> None:
-    """Extract variable name from a SUB-family metacommand into *defined*."""
+    """Add the variable(s) a metacommand defines to *defined*: the SUB family and the prompts that store an answer."""
     for rx in (
         _RX_SUB,
         _RX_SUB_EMPTY,
@@ -313,13 +395,32 @@ def _extract_var_definition(
         _RX_SUB_TEMPFILE,
         _RX_SUB_DECRYPT,
         _RX_SUB_ENCRYPT,
-        _RX_SUB_QUERYSTRING,
+        _RX_ASK_SUB,
+        _RX_PROMPT_ENTER_SUB,
+        _RX_PROMPT_DIRECTORY,
     ):
         m = rx.match(command)
         if m:
             defined.add(m.group("name").lstrip("+~").upper())
             return
 
+    m = _RX_PROMPT_FILE.match(command)
+    if m:
+        defined.update(name.lstrip("~").upper() for name in m.group("names").split())
+        return
+
+    m = _RX_PROMPT_CREDENTIALS.match(command)
+    if m:
+        defined.update((m.group("user").upper(), m.group("pw").upper()))
+        return
+
+    m = _RX_SUB_QUERYSTRING.match(command)
+    if m:
+        from urllib.parse import parse_qsl
+
+        defined.update(key.upper() for key, _value in parse_qsl(m.group("qstr")))
+        return
+
     # SUB_INI bulk-defines from INI file — read keys at lint time
     ini_m = _RX_SUB_INI.match(command)
     if ini_m:
@@ -329,29 +430,99 @@ def _extract_var_definition(
             _read_ini_vars(ini_file, ini_section, script_dir, defined)
 
 
+# Larger than any real SUB_INI file; lint reads no more than this.
+_MAX_INI_BYTES = 1024 * 1024
+
+
 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."""
+    """Read an INI file and register its section keys as defined variables.
+
+    Only a regular file up to :data:`_MAX_INI_BYTES` is read, so a script
+    naming a FIFO or a device (``/dev/zero``) cannot hang lint or the
+    language server; a file that is unreadable or not valid INI defines
+    nothing.
+    """
     from configparser import ConfigParser
+    from configparser import Error as ConfigError
 
     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)
+    try:
+        if not p.is_file() or p.stat().st_size > _MAX_INI_BYTES:
+            return
+        cp.read_string(p.read_text(encoding="utf-8"), source=str(p))
+    except (OSError, UnicodeDecodeError, ConfigError):
+        return
     if cp.has_section(section):
         for key, _value in cp.items(section):
             defined_vars.add(key.upper())
 
 
+def _is_known_var(raw_name: str, defined_vars: set[str]) -> bool:
+    """Whether execsql may substitute *raw_name* (as written, with its sigil) at run time."""
+    sigil = raw_name[0] if raw_name[0] in ("$", "@", "&", "~", "#", "+") else ""
+    name = raw_name[len(sigil) :]
+
+    # Skip non-$ sigil prefixes — resolved at runtime
+    if sigil in ("@", "&", "~", "#", "+"):
+        return True
+
+    if sigil == "$":
+        # System variables: $ARG_N is set with -a/--assign-arg, $COUNTER_N by
+        # CounterVars, the rest by execsql itself.  A SUB cannot define one.
+        return bool(re.match(r"^(?:ARG|COUNTER)_\d+$", name, re.I)) or name.upper() in _get_builtin_vars()
+    # User variables, defined by a SUB-family metacommand or a prompt.
+    return name.upper() in defined_vars
+
+
+def _unresolved_var_refs(text: str, defined_vars: set[str]) -> list[str]:
+    """The variable names in *text* that execsql would leave unsubstituted, as written.
+
+    execsql substitutes a known variable wherever ``!!name!!`` appears and
+    repeats until nothing changes, so a variable written inside another's
+    name (``!!N_!!GROUP!!_CHECKS!!``) is replaced first, and the outer name
+    is only known at run time: it is not checked.  Here each known variable
+    is replaced by a placeholder character, a name holding one counts as
+    known, and that repeats until nothing is replaced.
+
+    In a run of unknown candidates that share delimiters, the inner ones
+    (every second, from the second) are reported: with ``GROUP`` undefined,
+    ``!!N_!!GROUP!!_CHECKS!!`` reports ``GROUP``, not the fragments ``N_``
+    and ``_CHECKS``.
+    """
+    while True:
+        parts: list[str] = []
+        end = 0
+        for m in _RX_VAR_REF_ANY.finditer(text):
+            name = m.group(1)
+            if m.start() >= end and (_SUBSTITUTED in name or _is_known_var(name, defined_vars)):
+                parts += [text[end : m.start()], _SUBSTITUTED]
+                end = m.start() + len(name) + 4
+        if not parts:
+            break
+        text = "".join([*parts, text[end:]])
+
+    unresolved: list[str] = []
+    run: list[str] = []
+    end = -1
+    for m in _RX_VAR_REF_ANY.finditer(text):
+        if run and m.start() != end - 2:  # not sharing the previous candidate's closing !!
+            unresolved.extend(run if len(run) == 1 else run[1::2])
+            run = []
+        run.append(m.group(1))
+        end = m.start() + len(m.group(1)) + 4
+    unresolved.extend(run if len(run) == 1 else run[1::2])
+    return unresolved
+
+
 def _check_var_ref(
     raw_name: str,
     source: str,
@@ -360,30 +531,7 @@ def _check_var_ref(
     issues: list[_Issue],
 ) -> None:
     """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 — 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
-
-    # $COUNTER_N is managed by CounterVars
-    if re.match(r"^COUNTER_\d+$", name, re.I):
-        return
-
-    # Built-in system variables
-    if name.upper() in _get_builtin_vars():
-        return
-
-    # User-defined via SUB
-    if name.upper() in defined_vars:
+    if not raw_name or _is_known_var(raw_name, defined_vars):
         return
 
     issues.append(
@@ -427,8 +575,8 @@ def _check_include_path(
 #: Conditions whose value is fixed at parse time.  ``IF(True)`` is a real and
 #: reasonable thing to write while developing; leaving it in is what makes
 #: every other branch dead code.
-_RX_CONST_TRUE = re.compile(r"^\s*\(?\s*(?:true|1\s*=\s*1|yes)\s*\)?\s*$", re.I)
-_RX_CONST_FALSE = re.compile(r"^\s*\(?\s*(?:false|0\s*=\s*1|1\s*=\s*0|no)\s*\)?\s*$", re.I)
+_RX_CONST_TRUE = re.compile(r"^\s*\(?\s*(?:true|yes)\s*\)?\s*$", re.I)
+_RX_CONST_FALSE = re.compile(r"^\s*\(?\s*(?:false|no)\s*\)?\s*$", re.I)
 
 #: Metacommands after which nothing in the same block can run.
 _RX_TERMINAL = re.compile(r"^\s*HALT\b(?!\s+DISPLAY)", re.I)
@@ -482,6 +630,138 @@ def _check_constant_condition(node: IfBlock, issues: list[_Issue]) -> None:
         )
 
 
+def _check_split_dollar_quotes(nodes: list[Node], issues: list[_Issue]) -> None:
+    """Report a dollar-quoted body that the script splits into several statements.
+
+    A statement ends at any line ending in ``;``, even inside ``$$ ... $$``,
+    so a function body is sent to the database in pieces: the first piece
+    fails, and with ERROR_HALT OFF the statements inside the body then run
+    on their own.  One issue is reported where the body opens; the pieces
+    that follow until it closes are part of the same problem.
+    """
+    from execsql.format import open_dollar_quote
+
+    open_tag: str | None = None
+    for node in nodes:
+        if not isinstance(node, SqlStatement):
+            continue
+        was_open = open_tag
+        open_tag = open_dollar_quote(node.text, open_tag)
+        if was_open is None and open_tag is not None:
+            issues.append(
+                _issue(
+                    "P002",
+                    node.span.file,
+                    node.span.start_line,
+                    f"dollar-quoted body {open_tag} is split at the first line ending in ';'; "
+                    "put the statement between BEGIN SQL and END SQL",
+                ),
+            )
+
+
+# A command holding a variable (!!v!!, !'!v!'!, !"!v!"! or deferred !{v}!) is
+# only known after substitution at run time.
+_RX_ANY_VAR = re.compile(r"!(['\"]?)![$&@~#+]?\w+!\1!|!\{[$&@~#+]?\w+\}!")
+
+
+#: Values a variable is tried as: a boolean (a whole condition), a number
+#: (``ROW_COUNT_EQ(t, !!n!!)``) and a name (a table or column).  Between them
+#: they fit wherever a variable can stand in a condition or a metacommand.
+_PLACEHOLDERS = ("TRUE", "1", "x")
+
+
+def _with_placeholders(text: str, value: str = "TRUE") -> str:
+    """Replace each substitution variable with the literal *value*."""
+    return _RX_ANY_VAR.sub(value, text)
+
+
+def _placeholder_forms(text: str) -> list[str]:
+    """*text* with its variables replaced by each of :data:`_PLACEHOLDERS` in turn.
+
+    What none of them makes valid is not valid with any value, such as
+    ``!!flag!! = TRUE`` (there is no ``=`` comparison).
+    """
+    return [_with_placeholders(text, value) for value in _PLACEHOLDERS]
+
+
+# Named groups that capture a condition in a metacommand's pattern: ASSERT,
+# WAIT_UNTIL, and the WHILE / UNTIL of ON ... EXECUTE SCRIPT.
+_CONDITION_GROUPS = ("condtest", "condition", "loopcond")
+
+
+def _check_metacommand(node: MetaCommandStatement, issues: list[_Issue]) -> None:
+    """Report a metacommand that no dispatch-table entry matches, or whose condition does not parse.
+
+    ``execsql run`` halts on such a command with "Unknown metacommand",
+    whether the keyword is misspelled or the arguments don't fit any form.
+    """
+    match = _dispatch_table().get_match(node.command)
+    if match is None and _RX_ANY_VAR.search(node.command):
+        # A variable can stand for a keyword or a whole clause: try the
+        # command with placeholders, and judge it only if one matches.
+        match = next(
+            (m for form in _placeholder_forms(node.command) if (m := _dispatch_table().get_match(form)) is not None),
+            None,
+        )
+        if match is None:
+            return
+    if match is None:
+        issues.append(
+            _issue(
+                "P003",
+                node.span.file,
+                node.span.start_line,
+                f"unknown or malformed metacommand: {node.command.strip()}",
+            ),
+        )
+        return
+    groups = match[1].groupdict()
+    for name in _CONDITION_GROUPS:
+        if groups.get(name):
+            _check_condition(groups[name], node.span.file, node.span.start_line, issues)
+
+
+def _check_condition(condition: str, source: str, line_no: int, issues: list[_Issue]) -> None:
+    """Report a condition that the conditional-expression parser rejects.
+
+    Only parses: no test is evaluated, so nothing touches a database.  A
+    condition with variables is reported only when it parses with none of
+    the placeholder values (:func:`_placeholder_forms`).
+    """
+    from execsql.exceptions import CondParserError
+    from execsql.parser import CondParser
+
+    forms = _placeholder_forms(condition) if _RX_ANY_VAR.search(condition) else [condition]
+    for form in forms:
+        try:
+            CondParser(form, _conditional_table()).parse()
+        except (CondParserError, RecursionError):  # RecursionError: nested past the parser's depth
+            continue
+        return
+    issues.append(
+        _issue("P004", source, line_no, f"unknown or malformed condition: {condition.strip()}"),
+    )
+
+
+def _check_modifiers(modifiers: list[ConditionModifier], issues: list[_Issue]) -> None:
+    for mod in modifiers:
+        _check_condition(mod.condition, mod.span.file, mod.span.start_line, issues)
+
+
+def _check_block_conditions(node: Node, issues: list[_Issue]) -> None:
+    """Check the conditions an IF (with its ANDIF / ORIF / ELSEIF), LOOP or EXECUTE SCRIPT carries."""
+    if isinstance(node, IfBlock):
+        _check_condition(node.condition, node.span.file, node.span.start_line, issues)
+        _check_modifiers(node.condition_modifiers, issues)
+        for clause in node.elseif_clauses:
+            _check_condition(clause.condition, clause.span.file, clause.span.start_line, issues)
+            _check_modifiers(clause.condition_modifiers, issues)
+    elif isinstance(node, LoopBlock):
+        _check_condition(node.condition, node.span.file, node.span.start_line, issues)
+    elif isinstance(node, IncludeDirective) and node.loop_condition:
+        _check_condition(node.loop_condition, node.span.file, node.span.start_line, issues)
+
+
 def _check_unreachable_after_halt(nodes: list[Node], issues: list[_Issue]) -> None:
     """Report statements that follow an unconditional HALT in the same block.
 
@@ -507,11 +787,17 @@ def _check_unreachable_after_halt(nodes: list[Node], issues: list[_Issue]) -> No
         return
 
 
+# The conditional tests that read a variable by its bare name.
+_RX_VAR_TEST = re.compile(r"\bSUB_(?:DEFINED|EMPTY)\s*\(\s*([$&@~#]?\w+)\s*\)", re.I)
+
+
 def _collect_var_references(nodes: list[Node], seen: set[str]) -> None:
-    """Record every ``!!var!!`` reference anywhere beneath *nodes*."""
+    """Record every variable read anywhere beneath *nodes*: ``!!var!!``, or ``sub_defined(var)`` / ``sub_empty(var)``."""
     for node in nodes:
         for text in _referencing_text(node):
-            for m in _RX_VAR_REF.finditer(text):
+            for m in _RX_VAR_REF_ANY.finditer(text):
+                seen.add(m.group(1).lstrip("$@&~#+").upper())
+            for m in _RX_VAR_TEST.finditer(text):
                 seen.add(m.group(1).lstrip("$@&~#+").upper())
         for child in node.children():
             _collect_var_references([child], seen)
@@ -591,20 +877,23 @@ def _lint_nodes(
         visited_scripts = set()
 
     _check_unreachable_after_halt(nodes, issues)
+    _check_split_dollar_quotes(nodes, issues)
 
     for node in nodes:
         src = node.span.file
         lno = node.span.start_line
+        _check_block_conditions(node, issues)
 
         # -- 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)
+            for name in _unresolved_var_refs(node.text, defined_vars):
+                _check_var_ref(name, src, lno, defined_vars, issues)
 
         # -- 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)
+            _check_metacommand(node, issues)
+            for name in _unresolved_var_refs(node.command, defined_vars):
+                _check_var_ref(name, src, lno, defined_vars, issues)
 
         # -- IncludeDirective checks --
         elif isinstance(node, IncludeDirective):
@@ -711,6 +1000,20 @@ def lint(
     return issues
 
 
+def lint_source(source: str, label: str, script_path: str | None = None) -> list[_Issue]:
+    """Parse *source* and lint it, unfiltered.
+
+    Each block-structure error (an IF without ENDIF, a stray END LOOP, ...)
+    is a ``P001`` at its own line.  The parser recovers from them, so every
+    other rule still runs on the rest of the script.
+    """
+    from execsql.script.parser import parse_string
+
+    errors: list[ErrInfo] = []
+    tree = parse_string(source, label, errors=errors)
+    return [parse_error(label, exc) for exc in errors] + lint(tree, script_path=script_path)
+
+
 # ---------------------------------------------------------------------------
 # Selecting rules
 # ---------------------------------------------------------------------------

execsql/cli/options.py

@@ -50,7 +50,7 @@ DsnOpt = Annotated[
         metavar="URL",
         help=(
             "Database connection URL, e.g. postgresql://user:pass@host:5432/db. "
-            "Supported schemes: postgresql, mysql, mssql, oracle, firebird, sqlite, duckdb. "
+            "Supported schemes: postgresql (postgres), mysql (mariadb), mssql (sqlserver), oracle, firebird, sqlite, duckdb. "
             "Overrides -t/-u/-p and positional server/db args."
         ),
     ),