execsql2 2.26.0__py3-none-any.whl → 2.27.0__py3-none-any.whl

execsql/cli/commands/__init__.py

@@ -11,3 +11,4 @@ from execsql.cli.commands import lint  # noqa: F401
 from execsql.cli.commands import config  # noqa: F401
 from execsql.cli.commands import listing  # noqa: F401
 from execsql.cli.commands import init  # noqa: F401
+from execsql.cli.commands import lsp  # noqa: F401

execsql/cli/commands/listing.py

@@ -9,17 +9,21 @@ from __future__ import annotations
 
 import json
 import sys
+from typing import Annotated
 
 import typer
 
 from execsql.cli.application import ExecsqlCommand, ExecsqlSubGroup, app
 from execsql.cli.help import (
+    _err_console,
     _encoding_names,
-    _metacommand_rows,
+    _metacommand_entries,
+    _metacommand_json,
     _plugins_data,
     _print_encodings,
     _print_keywords_json,
     _print_keywords_text,
+    _print_metacommand,
     _print_metacommands,
     _print_plugins,
 )
@@ -43,10 +47,33 @@ def _json(data: object) -> None:
 
 
 @list_app.command(cls=ExecsqlCommand, name="metacommands")
-def metacommands_cmd(output_format: OutputFormatOpt = OutputFormat.text) -> None:
-    """Every metacommand and its syntax."""
-    if output_format is OutputFormat.json:
-        _json([{"name": name, "syntax": syntax} for name, syntax in _metacommand_rows()])
+def metacommands_cmd(
+    keyword: Annotated[
+        list[str] | None,
+        typer.Argument(metavar="[KEYWORD]", help="Show one metacommand's syntax, e.g. EXPORT or export query."),
+    ] = None,
+    output_format: OutputFormatOpt = OutputFormat.text,
+) -> None:
+    """Every metacommand with a one-line summary, or the syntax of one."""
+    if keyword:
+        from execsql.metacommands.reference import metacommand
+
+        wanted = " ".join(keyword)
+        entry = metacommand(wanted)
+        if entry is None:
+            import difflib
+
+            names = [m.keyword for m in _metacommand_entries()]
+            close = difflib.get_close_matches(wanted.upper(), names, n=3)
+            hint = f" Did you mean {', '.join(close)}?" if close else ""
+            _err_console.print(f"[bold red]Error:[/bold red] No metacommand {wanted!r}.{hint}", highlight=False)
+            raise typer.Exit(code=2)
+        if output_format is OutputFormat.json:
+            _json(_metacommand_json(entry))
+        else:
+            _print_metacommand(entry)
+    elif output_format is OutputFormat.json:
+        _json([_metacommand_json(m) for m in _metacommand_entries()])
     else:
         _print_metacommands()
 

execsql/cli/commands/lsp.py

@@ -0,0 +1,40 @@
+"""The ``lsp`` command: the language server editors start for ``.sql`` files."""
+
+from __future__ import annotations
+
+import typer
+
+from execsql.cli.application import ExecsqlCommand, app
+from execsql.cli.help import _err_console
+
+__all__ = ["lsp_cmd"]
+
+
+@app.command(
+    cls=ExecsqlCommand,
+    name="lsp",
+    help=(
+        "Run the execsql language server on stdin/stdout, for an editor to start. "
+        "Shows execsql lint findings as you type, completes metacommands, "
+        "conditional tests and variables, explains them on hover, and finds where variables, "
+        "SCRIPTs and included files are defined, offers quick fixes, and formats documents. Needs the lsp extra "
+        "(installed with any extras you already have, e.g. execsql2[postgres,lsp])."
+    ),
+)
+def lsp_cmd(
+    # Editors' language clients pass --stdio (VS Code always does); stdio is the only transport.
+    stdio: bool = typer.Option(False, "--stdio", hidden=True),
+) -> None:
+    """The ``lsp`` command; its user-facing help is the decorator's ``help``."""
+    try:
+        from execsql.lsp.server import create_server
+    except ImportError as exc:
+        _err_console.print(
+            "[bold red]Error:[/bold red] execsql lsp needs the lsp extra. Install it with the "
+            'extras you already have, e.g. uv tool install "execsql2\\[postgres,lsp]" or '
+            'pipx install --force "execsql2\\[postgres,lsp]". '
+            "See https://execsql2.readthedocs.io/en/latest/getting-started/installation/#adding-an-extra-later",
+            highlight=False,
+        )
+        raise typer.Exit(code=1) from exc
+    create_server().start_io()

execsql/cli/dispatch.py

@@ -29,7 +29,7 @@ from __future__ import annotations
 __all__ = ["COMMANDS", "GLOBAL_FLAGS", "dispatch", "normalize"]
 
 #: Tokens that name a command.
-COMMANDS = ("run", "format", "lint", "config", "list", "init")
+COMMANDS = ("run", "format", "lint", "config", "list", "init", "lsp")
 
 #: Options declared on the app rather than on a command, which must reach
 #: the parser without ``run`` in front of them. ``-m``, ``--encodings`` and

execsql/cli/help.py

@@ -19,7 +19,9 @@ __all__ = [
     "_init_config",
     "_init_config_text",
     "_keywords_data",
-    "_metacommand_rows",
+    "_metacommand_entries",
+    "_metacommand_json",
+    "_print_metacommand",
     "_plugins_data",
     "_print_encodings",
     "_print_keywords_json",
@@ -31,66 +33,6 @@ __all__ = [
 _console = Console()
 _err_console = Console(stderr=True)
 
-# ---------------------------------------------------------------------------
-# Metacommand syntax hints — paired with keywords from the dispatch table.
-# Keys must match the ``description`` values used in mcl.add() calls.
-# Entries here are validated by tests/test_registry.py.
-# ---------------------------------------------------------------------------
-
-_SYNTAX: dict[str, tuple[str, str]] = {
-    # (display_name, syntax_hint)
-    "ASK": ("ASK", '"<question>" SUB <match_string>'),
-    "AUTOCOMMIT": ("AUTOCOMMIT", "ON|OFF"),
-    "BEGIN BATCH": ("BEGIN BATCH / END BATCH / ROLLBACK BATCH", ""),
-    "BEGIN SCRIPT": ("BEGIN SCRIPT / END SCRIPT", ""),
-    "BEGIN SQL": ("BEGIN SQL / END SQL", ""),
-    "CANCEL_HALT": ("CANCEL_HALT", "ON|OFF"),
-    "CD": ("CD", "<directory>"),
-    "CONNECT": ("CONNECT", "<alias> [AS <alias_name>]"),
-    "COPY": ("COPY", "<source_file> TO <dest_file>"),
-    "DEBUG": ("DEBUG", "ON|OFF"),
-    "SUB": ("DEFINE SUB", "<variable> [AS] <value>"),
-    "EXPORT QUERY": ("EXPORT QUERY", "<queryname> [AS <alias>] ..."),
-    "EXPORT": ("EXPORT", "<queryname> TO <format> <filename> ..."),
-    "HALT": ("HALT [ON]", "ERROR|CANCEL"),
-    "IF": ("IF <condition>", "/ ELSE / ENDIF"),
-    "IMPORT_FILE": ("IMPORT FILE", "<filename> [OPTIONS ...]"),
-    "IMPORT": ("IMPORT TABLE", "<tablename> FROM FILE <filename> [OPTIONS ...]"),
-    "LOOP": ("LOOP <n> TIMES | WHILE | UNTIL", "/ END LOOP"),
-    "CONFIG": ("CONFIG", "<option> <value>"),
-    "ON CANCEL_HALT": ("ON CANCEL_HALT", "..."),
-    "ON ERROR_HALT": ("ON ERROR_HALT", "..."),
-    "PAUSE": ("PAUSE", "[<text>]"),
-    "PROMPT ACTION": ("PROMPT ACTION", "..."),
-    "PROMPT ENTRY_FORM": ("PROMPT ENTRY_FORM", "..."),
-    "PROMPT OPENFILE": ("PROMPT OPENFILE", "..."),
-    "PROMPT SAVEFILE": ("PROMPT SAVEFILE", "..."),
-    "PROMPT DIRECTORY": ("PROMPT DIRECTORY", "..."),
-    "PROMPT MAP": ("PROMPT MAP", "..."),
-    "ROLLBACK BATCH": ("ROLLBACK", ""),
-    "SERVE": ("SERVE", "<queryname> ..."),
-    "SYSTEM_CMD": ("SYSTEM_CMD", "(<operating system command line>)"),
-    "TIMER": ("TIMER", "ON|OFF"),
-    "USE": ("USE", "<alias_name>"),
-    "WAIT_UNTIL": ("WAIT_UNTIL", "<Boolean_expression> <HALT|CONTINUE> AFTER <n> SECONDS"),
-    "WRITE": ("WRITE", '"<text>" [[TEE] TO <output>]'),
-    "WRITE CREATE_TABLE": ("WRITE CREATE_TABLE FROM", "<filename> [TO <output>]"),
-    "WRITE SCRIPT": ("WRITE SCRIPT", "<script_name> [[APPEND] TO <output_file>]"),
-    "ZIP": ("ZIP", "<filename> [APPEND] TO ZIPFILE <zipfilename>"),
-    "SUB_TEMPFILE": ("SUB_TEMPFILE", "<variable>"),
-}
-
-# Keys from _SYNTAX that should be skipped when auto-generating from dispatch
-# table (they're variants covered by another entry).
-_SKIP_FROM_DISPATCH = {
-    "END BATCH",
-    "END SCRIPT",
-    "END SQL",
-    "ROLLBACK BATCH",
-    "BEGIN SCRIPT",
-    "BEGIN SQL",
-}
-
 
 def _init_config_text() -> str:
     """The default execsql.conf template, every option commented out and documented."""
@@ -106,56 +48,62 @@ def _init_config() -> None:
     sys.stdout.write(_init_config_text())
 
 
-def _metacommand_rows() -> list[tuple[str, str]]:
-    """``(name, syntax)`` for every metacommand, in the order they are listed.
+_CATEGORY_ORDER = ("control", "block", "action", "config", "prompt")
 
-    Keyword list is derived from the dispatch table; syntax hints come from
-    the ``_SYNTAX`` dict above.  Keywords not in ``_SYNTAX`` get an empty
-    syntax hint.
-    """
-    from execsql.metacommands import DISPATCH_TABLE
-
-    # Collect unique keyword names from the dispatch table.
-    seen: set[str] = set()
-    keywords: list[str] = []
-    for mc in DISPATCH_TABLE:
-        if mc.description and mc.description not in seen and mc.description not in _SKIP_FROM_DISPATCH:
-            seen.add(mc.description)
-            keywords.append(mc.description)
-    # Add parser-level keywords not in the dispatch table.
-    for extra in ("BEGIN BATCH", "BEGIN SCRIPT", "BEGIN SQL"):
-        if extra not in seen:
-            seen.add(extra)
-            keywords.append(extra)
-
-    rows: list[tuple[str, str]] = []
-    for kw in sorted(keywords):
-        if kw in _SYNTAX:
-            rows.append(_SYNTAX[kw])
-        elif kw.startswith("CONFIG ") or kw.startswith("CONSOLE_") or "_" in kw:
-            continue  # skip config options / internal entries
-        else:
-            rows.append((kw, ""))
-    return rows
+
+def _metacommand_entries() -> list[Any]:
+    """Every metacommand's readable entry, by category, then keyword."""
+    from execsql.metacommands.reference import metacommands
+
+    order = {c: i for i, c in enumerate(_CATEGORY_ORDER)}
+    return sorted(metacommands(), key=lambda m: (order.get(m.category, len(order)), m.keyword))
+
+
+def _metacommand_json(entry: Any) -> dict[str, Any]:
+    return {
+        "name": entry.keyword,
+        "category": entry.category,
+        "syntax": entry.forms[0],
+        "forms": list(entry.forms),
+        "summary": entry.summary,
+        "url": entry.url,
+    }
 
 
 def _print_metacommands() -> None:
-    """Print the metacommands table using Rich."""
+    """Print every metacommand with its category and one-line summary."""
     table = Table(
         title="execsql Metacommands",
-        caption="Embed in SQL comment lines following the [bold]!x![/bold] token.",
+        caption=(
+            "Write them in a SQL comment after [bold]-- !x![/bold].  "
+            "[bold]execsql list metacommands <KEYWORD>[/bold] shows the syntax of one."
+        ),
         show_header=True,
         header_style="bold cyan",
         border_style="dim",
         expand=False,
     )
     table.add_column("Metacommand", style="bold green", no_wrap=True)
-    table.add_column("Syntax", style="white")
-    for name, syntax in _metacommand_rows():
-        table.add_row(name, syntax)
+    table.add_column("Category", style="dim", no_wrap=True)
+    table.add_column("Summary", style="white")
+    for entry in _metacommand_entries():
+        table.add_row(entry.keyword, entry.category, entry.summary)
     _console.print(table)
 
 
+def _print_metacommand(entry: Any) -> None:
+    """Print one metacommand's syntax lines, summary and docs link."""
+    from rich.markup import escape
+
+    _console.print(f"[bold green]{escape(entry.keyword)}[/bold green]  [dim]{entry.category}[/dim]")
+    _console.print(escape(entry.summary))
+    _console.print()
+    for form in entry.forms:
+        _console.print(f"  -- !x! {escape(form)}", highlight=False)
+    _console.print()
+    _console.print(f"[dim]{entry.url}[/dim]", highlight=False)
+
+
 def _encoding_names() -> list[str]:
     """Every encoding name Python accepts, sorted."""
     return sorted(codec_dict.keys())

execsql/cli/lint.py

@@ -82,6 +82,7 @@ __all__ = [
     "filter_issues",
     "lint",
     "lint_source",
+    "variables_defined_by",
     "parse_error",
     "print_concise",
     "print_statistics",
@@ -430,6 +431,18 @@ def _extract_var_definition(
             _read_ini_vars(ini_file, ini_section, script_dir, defined)
 
 
+def variables_defined_by(command: str, script_dir: Path | None = None) -> set[str]:
+    """The variable names (upper case, without ``~``/``+``) a metacommand defines.
+
+    *command* is the text after ``-- !x!``.  Covers the SUB family, the
+    prompts that store an answer, SUB_QUERYSTRING and SUB_INI (whose INI file
+    is read, relative to *script_dir*).
+    """
+    defined: set[str] = set()
+    _extract_var_definition(command, script_dir, defined)
+    return defined
+
+
 # Larger than any real SUB_INI file; lint reads no more than this.
 _MAX_INI_BYTES = 1024 * 1024
 

execsql/lsp/__init__.py

@@ -0,0 +1,6 @@
+"""Language server for execsql scripts: ``execsql lsp``.
+
+Editors start it over stdio. The features are plain functions over a
+document's text, so they are tested without a client; :mod:`.server` wires
+them to the protocol with pygls (the ``lsp`` extra).
+"""

execsql/lsp/code_actions.py

@@ -0,0 +1,217 @@
+"""Quick fixes for lint findings.
+
+Each fix is checked before it is offered: a spelling fix must make the
+metacommand match a dispatch-table form (P003) or make lint's finding go away
+(P004, P002).  A fix that would not clear the finding is never shown.
+
+- P003 unknown metacommand: a misspelled keyword, e.g. ``EXPROT`` -> ``EXPORT``.
+- P004 unknown condition: a misspelled conditional test, e.g. ``HASROWZ`` -> ``HASROWS``.
+- V001 undefined variable: a near-miss of a variable the script defines (or of a system variable).
+- P002 split dollar quote: put the statement between ``BEGIN SQL`` and ``END SQL``.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from collections.abc import Iterator, Sequence
+
+from lsprotocol import types
+
+from execsql.cli.lint import _dispatch_table, _with_placeholders, lint_source
+from execsql.format import open_dollar_quote
+from execsql.lsp.document import ScriptIndex
+from execsql.metacommands import reference
+
+__all__ = ["code_actions"]
+
+_RX_METACOMMAND = re.compile(r"^(?P<lead>\s*--\s*!x!\s*)(?P<command>.*?)\s*$", re.I)
+_RX_WORD = re.compile(r"[A-Za-z_][A-Za-z_0-9]*")
+_RX_UNDEFINED = re.compile(r"!!(?P<name>[^!]+)!!")
+_SUGGESTIONS = 3  # per misspelled word
+_CUTOFF = 0.7
+
+
+def _vocabulary() -> set[str]:
+    """Every literal word of a metacommand's syntax: keywords and words such as TO, AS, WITH."""
+    words: set[str] = set()
+    for entry in reference.metacommands():
+        for form in entry.forms:
+            words.update(re.findall(r"\b[A-Z][A-Z_]+\b", re.sub(r"<[^>]*>", " ", form)))
+    return words
+
+
+def _cased_like(word: str, written: str) -> str:
+    return word.lower() if written.islower() else word
+
+
+def _close(word: str, choices: set[str] | list[str]) -> list[str]:
+    return difflib.get_close_matches(word.upper(), list(choices), n=_SUGGESTIONS, cutoff=_CUTOFF)
+
+
+def _replace(text: str, start: int, end: int, new: str) -> str:
+    return text[:start] + new + text[end:]
+
+
+def _range(line: int, start: int, end: int) -> types.Range:
+    return types.Range(start=types.Position(line=line, character=start), end=types.Position(line=line, character=end))
+
+
+def _fix(title: str, uri: str, diagnostic: types.Diagnostic, edits: list[types.TextEdit]) -> types.CodeAction:
+    return types.CodeAction(
+        title=title,
+        kind=types.CodeActionKind.QuickFix,
+        diagnostics=[diagnostic],
+        edit=types.WorkspaceEdit(changes={uri: edits}),
+    )
+
+
+def _count(source: str, path: str | None, code: str) -> int:
+    return sum(1 for issue in lint_source(source, path or "<untitled>", script_path=path) if issue.code == code)
+
+
+def _clears(lines: list[str], path: str | None, code: str, before: tuple[int, int], row: int, new_line: str) -> bool:
+    """Whether replacing line *row* with *new_line* removes a *code* finding without adding a parse error.
+
+    *before* is the (*code*, P001) count of the unchanged script.
+    """
+    fixed = "\n".join(lines[:row] + [new_line] + lines[row + 1 :]) + "\n"
+    return _count(fixed, path, code) < before[0] and _count(fixed, path, "P001") <= before[1]
+
+
+def _metacommand_fixes(text: str, row: int) -> Iterator[tuple[str, int, int, str]]:
+    """(suggestion, start, end, written) for each word whose replacement makes the metacommand match."""
+    m = _RX_METACOMMAND.match(text)
+    if not m:
+        return
+    vocabulary = _vocabulary()
+    offset = m.start("command")
+    command = m.group("command")
+    table = _dispatch_table()
+    for word in _RX_WORD.finditer(command):
+        if word.group().upper() in vocabulary:
+            continue
+        for candidate in _close(word.group(), vocabulary):
+            fixed = _replace(command, word.start(), word.end(), candidate)
+            if table.get_match(fixed) is not None or table.get_match(_with_placeholders(fixed)) is not None:
+                yield candidate, offset + word.start(), offset + word.end(), word.group()
+
+
+def _p003(uri: str, lines: list[str], diagnostic: types.Diagnostic) -> list[types.CodeAction]:
+    row = diagnostic.range.start.line
+    return [
+        _fix(
+            f"Change {written} to {_cased_like(candidate, written)}",
+            uri,
+            diagnostic,
+            [types.TextEdit(range=_range(row, start, end), new_text=_cased_like(candidate, written))],
+        )
+        for candidate, start, end, written in _metacommand_fixes(lines[row], row)
+    ]
+
+
+def _p004(uri: str, path: str | None, lines: list[str], diagnostic: types.Diagnostic) -> list[types.CodeAction]:
+    row = diagnostic.range.start.line
+    text = lines[row]
+    m = _RX_METACOMMAND.match(text)
+    if not m:
+        return []
+    names = {c.name for c in reference.conditions() if c.name not in ("NOT", "OR")}
+    source = "\n".join(lines) + "\n"
+    before = (_count(source, path, "P004"), _count(source, path, "P001"))
+    actions = []
+    for word in _RX_WORD.finditer(text, m.start("command")):
+        if word.group().upper() in names or not text[word.end() :].lstrip().startswith("("):
+            continue
+        for candidate in _close(word.group(), names):
+            new = _cased_like(candidate, word.group())
+            if _clears(lines, path, "P004", before, row, _replace(text, word.start(), word.end(), new)):
+                edit = types.TextEdit(range=_range(row, word.start(), word.end()), new_text=new)
+                actions.append(_fix(f"Change {word.group()} to {new}", uri, diagnostic, [edit]))
+    return actions
+
+
+def _v001(index: ScriptIndex, uri: str, diagnostic: types.Diagnostic) -> list[types.CodeAction]:
+    m = _RX_UNDEFINED.search(diagnostic.message)
+    if not m:
+        return []
+    row = diagnostic.range.start.line
+    written = m.group("name")
+    actions = []
+    for ref in index.references:
+        loc = ref.location
+        if loc.path != index.path or loc.line != row or ref.name.lower() != written.lower():
+            continue
+        prefix = ref.name[: len(ref.name) - len(ref.name.lstrip("~+"))]
+        bare = ref.name[len(prefix) :]
+        if bare.startswith("$"):
+            choices = {v.name for v in reference.system_variables() if not v.name.endswith("_x")}
+            spelled = {name: name for name in choices}
+        else:
+            spelled = {key: index.spellings[key] for key in index.definitions}
+        for candidate in _close(bare, set(spelled)):
+            new = prefix + spelled[candidate]
+            edit = types.TextEdit(range=_range(row, loc.start, loc.end), new_text=new)
+            actions.append(_fix(f"Change !!{ref.name}!! to !!{new}!!", uri, diagnostic, [edit]))
+        break
+    return actions
+
+
+def _statement_end(lines: list[str], row: int) -> int | None:
+    """The line that ends the statement whose dollar-quoted body opens on *row*."""
+    open_tag: str | None = None
+    for end in range(row, len(lines)):
+        open_tag = open_dollar_quote(lines[end] + "\n", open_tag)
+        if open_tag is None and end > row and lines[end].rstrip().endswith(";"):
+            return end
+    return None
+
+
+def _p002(uri: str, path: str | None, lines: list[str], diagnostic: types.Diagnostic) -> list[types.CodeAction]:
+    row = diagnostic.range.start.line
+    end = _statement_end(lines, row)
+    if end is None:
+        return []
+    indent = lines[row][: len(lines[row]) - len(lines[row].lstrip())]
+    fixed = (
+        lines[:row]
+        + [f"{indent}-- !x! BEGIN SQL"]
+        + lines[row : end + 1]
+        + [f"{indent}-- !x! END SQL"]
+        + lines[end + 1 :]
+    )
+    if _count("\n".join(fixed) + "\n", path, "P002") >= _count("\n".join(lines) + "\n", path, "P002"):
+        return []
+    edits = [
+        types.TextEdit(range=_range(row, 0, 0), new_text=f"{indent}-- !x! BEGIN SQL\n"),
+        types.TextEdit(range=_range(end, len(lines[end]), len(lines[end])), new_text=f"\n{indent}-- !x! END SQL"),
+    ]
+    return [_fix("Put the statement between BEGIN SQL and END SQL", uri, diagnostic, edits)]
+
+
+def code_actions(
+    index: ScriptIndex,
+    uri: str,
+    source: str,
+    diagnostics: Sequence[types.Diagnostic],
+) -> list[types.CodeAction]:
+    """The quick fixes for the execsql *diagnostics* the editor asks about."""
+    lines = source.splitlines()
+    actions: list[types.CodeAction] = []
+    for diagnostic in diagnostics:
+        if diagnostic.source != "execsql" or diagnostic.range.start.line >= len(lines):
+            continue
+        if diagnostic.code == "P003":
+            found = _p003(uri, lines, diagnostic)
+        elif diagnostic.code == "P004":
+            found = _p004(uri, index.path, lines, diagnostic)
+        elif diagnostic.code == "V001":
+            found = _v001(index, uri, diagnostic)
+        elif diagnostic.code == "P002":
+            found = _p002(uri, index.path, lines, diagnostic)
+        else:
+            continue
+        if len(found) == 1:
+            found[0].is_preferred = True
+        actions.extend(found)
+    return actions