execsql2 2.15.8__py3-none-any.whl → 2.16.0__py3-none-any.whl

execsql/cli/__init__.py

@@ -273,6 +273,11 @@ def main(
         "--dump-keywords",
         help="Dump all metacommand keywords as JSON and exit.",
     ),
+    list_plugins: bool = typer.Option(
+        False,
+        "--list-plugins",
+        help="List all discovered plugins (metacommands, exporters, importers) and exit.",
+    ),
     profile: bool = typer.Option(
         False,
         "--profile",
@@ -283,6 +288,24 @@ def main(
         "--profile-limit",
         help="Number of top statements to show in the --profile timing summary (default: 20).",
     ),
+    config_file: str | None = typer.Option(
+        None,
+        "--config",
+        metavar="FILE",
+        help=(
+            "Path to an execsql configuration file. "
+            "Loaded after the implicit search paths so its values take precedence. "
+            "The file may chain additional configs via its [cyan][config][/cyan] section."
+        ),
+    ),
+    parse_tree: bool = typer.Option(
+        False,
+        "--parse-tree",
+        help=(
+            "Parse the script into an abstract syntax tree and print the tree structure. "
+            "Does not connect to a database or execute anything."
+        ),
+    ),
     debug: bool = typer.Option(
         False,
         "--debug",
@@ -370,12 +393,56 @@ def main(
         _console.print_json(_json.dumps(data, indent=2))
         raise typer.Exit()
 
+    if list_plugins:
+        from execsql.plugins import (
+            EXPORTER_GROUP,
+            IMPORTER_GROUP,
+            METACOMMAND_GROUP,
+            _load_entry_points,
+        )
+
+        _console.print("\n[bold cyan]Installed plugins:[/bold cyan]\n")
+
+        mc_plugins = _load_entry_points(METACOMMAND_GROUP)
+        ex_plugins = _load_entry_points(EXPORTER_GROUP)
+        im_plugins = _load_entry_points(IMPORTER_GROUP)
+
+        if not mc_plugins and not ex_plugins and not im_plugins:
+            _console.print("  [dim]No plugins found.[/dim]")
+            _console.print()
+            _console.print(
+                "  Plugins are discovered via Python entry points.\n"
+                "  See the execsql documentation for how to create plugins.",
+            )
+        else:
+            if mc_plugins:
+                _console.print(f"  [bold]Metacommands[/bold] ({len(mc_plugins)}):")
+                for name, _ in mc_plugins:
+                    _console.print(f"    - {name}")
+            if ex_plugins:
+                _console.print(f"  [bold]Exporters[/bold] ({len(ex_plugins)}):")
+                for name, _ in ex_plugins:
+                    _console.print(f"    - {name}")
+            if im_plugins:
+                _console.print(f"  [bold]Importers[/bold] ({len(im_plugins)}):")
+                for name, _ in im_plugins:
+                    _console.print(f"    - {name}")
+
+        _console.print()
+        raise typer.Exit()
+
     if online_help:
         import webbrowser
 
         webbrowser.open("https://execsql2.readthedocs.io/en/latest/", new=2, autoraise=True)
         raise typer.Exit()
 
+    if config_file and not Path(config_file).is_file():
+        _err_console.print(
+            f"[bold red]Error:[/bold red] Config file [cyan]{config_file!r}[/cyan] does not exist.",
+        )
+        raise typer.Exit(code=2)
+
     positional = args or []
     if command is not None:
         script_name = None  # inline mode — no script file
@@ -425,6 +492,61 @@ def main(
         )
         raise typer.Exit(code=2)
 
+    # ------------------------------------------------------------------
+    # Parse tree: parse script into AST and print tree structure
+    # ------------------------------------------------------------------
+    if parse_tree:
+        from execsql.script.ast import format_tree
+        from execsql.script.parser import parse_script, parse_string
+
+        try:
+            if command is not None:
+                tree = parse_string(command.replace("\\n", "\n").replace("\\t", "\t"), "<inline>")
+            elif script_name is not None:
+                encoding = script_encoding or "utf-8"
+                tree = parse_script(script_name, encoding=encoding)
+            else:
+                _err_console.print(
+                    "[bold red]Error:[/bold red] --parse-tree requires a script file or -c command.",
+                )
+                raise typer.Exit(code=1)
+        except ErrInfo as exc:
+            _err_console.print(f"[bold red]Parse error:[/bold red] {exc.errmsg()}")
+            raise typer.Exit(code=1) from exc
+
+        _console.print(format_tree(tree))
+        raise typer.Exit()
+
+    # ------------------------------------------------------------------
+    # Lint: AST-based static analysis (no DB connection needed)
+    # ------------------------------------------------------------------
+    if lint:
+        from execsql.cli.lint import _print_lint_results
+        from execsql.cli.lint_ast import lint_ast
+        from execsql.script.parser import parse_script, parse_string
+
+        label = script_name or "<inline>"
+        try:
+            if command is not None:
+                tree = parse_string(command.replace("\\n", "\n").replace("\\t", "\t"), "<inline>")
+            elif script_name is not None:
+                encoding = script_encoding or "utf-8"
+                tree = parse_script(script_name, encoding=encoding)
+            else:
+                _err_console.print(
+                    "[bold red]Error:[/bold red] --lint requires a script file or -c command.",
+                )
+                raise typer.Exit(code=1)
+        except ErrInfo as exc:
+            # Parse failure IS a lint error — report it
+            issues = [("error", label, 0, f"Parse error: {exc.errmsg()}")]
+            exit_code = _print_lint_results(issues, label)
+            raise typer.Exit(code=exit_code) from exc
+
+        issues = lint_ast(tree, script_path=script_name)
+        exit_code = _print_lint_results(issues, label)
+        raise typer.Exit(code=exit_code)
+
     # ------------------------------------------------------------------
     # Delegate to the real main implementation
     # ------------------------------------------------------------------
@@ -458,6 +580,7 @@ def main(
         ping=ping,
         lint=lint,
         debug=debug,
+        config_file=config_file,
     )
 
 

execsql/cli/lint_ast.py

@@ -0,0 +1,439 @@
+"""AST-based static analysis (lint) for execsql scripts.
+
+Performs the same checks as :mod:`execsql.cli.lint` but operates on the
+:class:`~execsql.script.ast.Script` tree instead of a flat
+:class:`~execsql.script.engine.CommandList`.
+
+Advantages over the flat linter:
+
+- **No runtime state required** — works with the AST parser alone, so it
+  can run as an early exit in the CLI without initialising ``_state``.
+- **Structural validation is free** — the AST parser already rejects
+  unmatched IF/LOOP/BATCH/SCRIPT blocks at parse time with precise source
+  spans.  This linter only needs to report variable and INCLUDE issues.
+- **Script blocks are in the tree** — ``EXECUTE SCRIPT`` targets are
+  resolved by finding :class:`ScriptBlock` nodes, not by looking up
+  ``_state.savedscripts``.
+
+Checks performed
+----------------
+1. **Parse errors** — the AST parser rejects unmatched blocks, so any
+   parse failure is reported as an error with the parser's message.
+2. **Potentially undefined variables** — same heuristic as the flat linter.
+3. **EXECUTE SCRIPT target resolution** — warns when a target name does
+   not correspond to a :class:`ScriptBlock` in the same file.
+4. **Missing INCLUDE files** — warns when the file does not exist on disk.
+5. **Empty script** — warns when no nodes were parsed.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from execsql.script.ast import (
+    BatchBlock,
+    IfBlock,
+    IncludeDirective,
+    LoopBlock,
+    MetaCommandStatement,
+    Node,
+    Script,
+    ScriptBlock,
+    SqlBlock,
+    SqlStatement,
+)
+
+__all__ = ["lint_ast"]
+
+
+# ---------------------------------------------------------------------------
+# Variable-related patterns (shared with the flat linter)
+# ---------------------------------------------------------------------------
+
+_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)
+
+_RX_VAR_REF = re.compile(r"!!([$@&~#+]?\w+)!!", re.I)
+
+
+# ---------------------------------------------------------------------------
+# Issue tuple helpers
+# ---------------------------------------------------------------------------
+
+_Issue = tuple[str, str, int, str]  # (severity, source, line_no, message)
+
+
+def _error(source: str, line_no: int, message: str) -> _Issue:
+    return ("error", source, line_no, message)
+
+
+def _warning(source: str, line_no: int, message: str) -> _Issue:
+    return ("warning", source, line_no, message)
+
+
+# ---------------------------------------------------------------------------
+# Built-in variable discovery (reuse from flat linter)
+# ---------------------------------------------------------------------------
+
+
+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] | None = None
+
+
+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
+
+
+# ---------------------------------------------------------------------------
+# AST walker helpers
+# ---------------------------------------------------------------------------
+
+
+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
+
+
+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,
+                    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 _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)
+
+
+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
+
+    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_var_ref(
+    raw_name: str,
+    source: str,
+    line_no: int,
+    defined_vars: set[str],
+    issues: list[_Issue],
+) -> None:
+    """Emit a warning if *raw_name* looks like an undefined user variable."""
+    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:
+        return
+
+    issues.append(
+        _warning(
+            source,
+            line_no,
+            f"Potentially undefined variable: !!{raw_name}!! "
+            "(not defined by a preceding SUB; may be set by a config file or -a arg)",
+        ),
+    )
+
+
+def _check_include_path(
+    raw_path: str,
+    script_dir: Path | None,
+    source: str,
+    line_no: int,
+    issues: list[_Issue],
+) -> None:
+    """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():
+        issues.append(
+            _warning(source, line_no, f"INCLUDE target does not exist: {raw_path!r}"),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Core lint walk
+# ---------------------------------------------------------------------------
+
+
+def _lint_nodes(
+    nodes: list[Node],
+    script_dir: Path | None,
+    defined_vars: set[str],
+    script_blocks: dict[str, ScriptBlock],
+    issues: list[_Issue],
+    *,
+    visited_scripts: set[str] | None = None,
+) -> None:
+    """Walk a list of AST nodes and collect lint issues."""
+    if visited_scripts is None:
+        visited_scripts = set()
+
+    for node in nodes:
+        src = node.span.file
+        lno = node.span.start_line
+
+        # -- 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)
+
+        # -- 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}"))
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def lint_ast(
+    script: Script,
+    script_path: str | None = None,
+) -> list[_Issue]:
+    """Perform static analysis on an AST-parsed script.
+
+    Args:
+        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)`` issue tuples.
+    """
+    issues: list[_Issue] = []
+
+    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
+    script_blocks = _collect_script_blocks(script)
+
+    # Pass 1: collect all variable definitions
+    all_defined: set[str] = set()
+    _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,
+        script_blocks,
+        issues,
+    )
+
+    return issues