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

execsql/lsp/completion.py

@@ -0,0 +1,203 @@
+"""Completion: metacommands after ``-- !x!``, conditional tests inside a condition, variables after ``!!``.
+
+Everything shown comes from :mod:`execsql.metacommands.reference` (syntax in
+the docs' notation, never the dispatch regexes) and from the script's own
+index.  A metacommand with several syntax lines offers one item per line, each
+inserting a fill-in template.
+"""
+
+from __future__ import annotations
+
+import re
+
+from lsprotocol import types
+
+from execsql.lsp.document import ScriptIndex
+from execsql.metacommands import reference
+
+__all__ = ["completions"]
+
+_RX_KEYWORD = re.compile(r"^(?P<lead>\s*--\s*!x!\s*)(?P<partial>[A-Za-z_][A-Za-z_ ]*)?$", re.I)
+_RX_VARIABLE = re.compile(r"""(?P<open>!(?P<q>['"]?)!|!\{)(?P<partial>[$&@~#+]?\w*)$""")
+_RX_CONDITION = re.compile(
+    r"(?:\b(?:IF|ELSEIF|ANDIF|ORIF|WHILE|UNTIL)\s*\(|\b(?:ASSERT|WAIT_UNTIL)\s+|\b(?:AND|OR|NOT)\s+|\()\s*(?P<partial>\w*)$",
+    re.I,
+)
+_RX_EXPORT_FORMAT = re.compile(r"^\s*--\s*!x!\s*EXPORT\b.*\bAS\s+(?P<partial>\w*)$", re.I)
+_RX_IS_METACOMMAND = re.compile(r"^\s*--\s*!x!", re.I)
+
+
+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 _markdown(text: str) -> types.MarkupContent:
+    return types.MarkupContent(kind=types.MarkupKind.Markdown, value=text)
+
+
+def _metacommand_doc(entry: reference.Metacommand) -> types.MarkupContent:
+    forms = "\n".join(entry.forms)
+    return _markdown(f"{entry.summary}\n\n```\n{forms}\n```\n\n[Reference]({entry.url})")
+
+
+def _keyword_items(line: int, start: int, end: int, typed: str, snippets: bool) -> list[types.CompletionItem]:
+    """One item per syntax line.  After a space, only keywords that continue what was typed."""
+    items = []
+    words = " ".join(typed.upper().split())
+    for entry in reference.metacommands():
+        if typed.endswith(" ") and not entry.keyword.startswith(words + " "):
+            continue
+        for n, form in enumerate(entry.forms):
+            rest = form[len(entry.keyword) :].strip() if form.upper().startswith(entry.keyword) else form
+            items.append(
+                types.CompletionItem(
+                    label=entry.keyword,
+                    label_details=types.CompletionItemLabelDetails(detail=f" {rest}"[:70] if rest else None),
+                    kind=types.CompletionItemKind.Keyword,
+                    detail=form,
+                    documentation=_metacommand_doc(entry),
+                    filter_text=entry.keyword,
+                    sort_text=f"{entry.keyword}\x00{n:03d}",
+                    text_edit=types.TextEdit(
+                        range=_range(line, start, end),
+                        new_text=reference.to_snippet(form) if snippets else entry.keyword,
+                    ),
+                    insert_text_format=types.InsertTextFormat.Snippet if snippets else types.InsertTextFormat.PlainText,
+                ),
+            )
+    return items
+
+
+def _condition_items(line: int, start: int, end: int, snippets: bool) -> list[types.CompletionItem]:
+    items = []
+    for entry in reference.conditions():
+        if entry.name in ("NOT", "OR"):
+            continue
+        items.append(
+            types.CompletionItem(
+                label=entry.name,
+                kind=types.CompletionItemKind.Function,
+                detail=entry.forms[0],
+                documentation=_markdown(f"{entry.summary}\n\n```\n{entry.forms[0]}\n```\n\n[Reference]({entry.url})"),
+                text_edit=types.TextEdit(
+                    range=_range(line, start, end),
+                    new_text=entry.snippet if snippets else entry.name,
+                ),
+                insert_text_format=types.InsertTextFormat.Snippet if snippets else types.InsertTextFormat.PlainText,
+            ),
+        )
+    return items
+
+
+def _variable_items(
+    index: ScriptIndex,
+    line: int,
+    start: int,
+    end: int,
+    closing: str,
+    partial: str,
+    snippets: bool,
+) -> list[types.CompletionItem]:
+    items: list[types.CompletionItem] = []
+
+    def add(name: str, detail: str, doc: str, kind: types.CompletionItemKind, snippet: str | None = None) -> None:
+        use_snippet = snippets and snippet is not None
+        items.append(
+            types.CompletionItem(
+                label=name,
+                kind=kind,
+                detail=detail,
+                documentation=_markdown(doc) if doc else None,
+                text_edit=types.TextEdit(
+                    range=_range(line, start, end),
+                    new_text=(snippet if use_snippet and snippet is not None else name) + closing,
+                ),
+                insert_text_format=types.InsertTextFormat.Snippet if use_snippet else types.InsertTextFormat.PlainText,
+            ),
+        )
+
+    sigil = partial[:1] if partial[:1] in "$&@#~+" else ""
+    if sigil in ("", "~", "+"):
+        for key, locations in sorted(index.definitions.items()):
+            first = locations[0]
+            where = f"line {first.line + 1}" if first.path == index.path else f"{first.path}, line {first.line + 1}"
+            add(sigil + index.spellings[key], f"defined at {where}", "", types.CompletionItemKind.Variable)
+    if sigil in ("", "#"):
+        for script, params in sorted(index.script_params.items()):
+            for param in params:
+                add(f"#{param}", f"parameter of SCRIPT {script}", "", types.CompletionItemKind.Variable)
+    if sigil in ("", "$"):
+        for var in reference.system_variables():
+            name = var.name
+            snippet = None
+            if name.endswith("_x"):  # $ARG_x, $COUNTER_x: the number is filled in
+                snippet = name[:-1].replace("$", "\\$") + "${1:1}"
+                name = name[:-1] + "n"
+            add(
+                name,
+                "system variable",
+                f"{var.summary}\n\n[Reference]({var.url})",
+                types.CompletionItemKind.Constant,
+                snippet,
+            )
+    return items
+
+
+def completions(
+    index: ScriptIndex,
+    source: str,
+    line: int,
+    character: int,
+    snippets: bool = True,
+) -> types.CompletionList:
+    """What to offer at (*line*, *character*) of *source*, zero-based."""
+    lines = source.splitlines()
+    text = lines[line] if 0 <= line < len(lines) else ""
+    before, after = text[:character], text[character:]
+    empty = types.CompletionList(is_incomplete=False, items=[])
+
+    m = _RX_VARIABLE.search(before)
+    if m:
+        closing = {"!!": "!!", "!'!": "!'!", '!"!': '!"!', "!{": "}!"}[m.group("open")]
+        rest = re.match(r"[$&@~#+]?\w*", after)
+        tail = after[rest.end() :] if rest else after
+        if tail.startswith(closing):
+            closing = ""
+        end = character + (rest.end() if rest else 0)
+        items = _variable_items(index, line, m.start("partial"), end, closing, m.group("partial"), snippets)
+        return types.CompletionList(is_incomplete=False, items=items)
+
+    if not _RX_IS_METACOMMAND.match(before):
+        return empty
+
+    m = _RX_EXPORT_FORMAT.match(before)
+    if m:
+        from execsql.metacommands import ALL_EXPORT_FORMATS
+
+        start = m.start("partial")
+        return types.CompletionList(
+            is_incomplete=False,
+            items=[
+                types.CompletionItem(
+                    label=fmt.upper(),
+                    kind=types.CompletionItemKind.EnumMember,
+                    detail="export format",
+                    text_edit=types.TextEdit(range=_range(line, start, character), new_text=fmt.upper()),
+                )
+                for fmt in sorted(ALL_EXPORT_FORMATS)
+            ],
+        )
+
+    m = _RX_CONDITION.search(before)
+    if m:
+        return types.CompletionList(
+            is_incomplete=False,
+            items=_condition_items(line, m.start("partial"), character, snippets),
+        )
+
+    m = _RX_KEYWORD.match(before)
+    if m:
+        start = m.end("lead")
+        items = _keyword_items(line, start, character, m.group("partial") or "", snippets)
+        return types.CompletionList(is_incomplete=False, items=items)
+    return empty

execsql/lsp/diagnostics.py

@@ -0,0 +1,66 @@
+"""``execsql lint`` findings as LSP diagnostics."""
+
+from __future__ import annotations
+
+from lsprotocol import types
+
+from execsql.cli.lint import Issue, filter_issues, lint_source
+
+__all__ = ["LINT_DOCS_URL", "diagnostics", "to_diagnostic", "too_deep_diagnostic"]
+
+LINT_DOCS_URL = "https://execsql2.readthedocs.io/en/latest/reference/lint/"
+
+_SEVERITY = {
+    "error": types.DiagnosticSeverity.Error,
+    "warning": types.DiagnosticSeverity.Warning,
+}
+
+
+def to_diagnostic(issue: Issue, lines: list[str]) -> types.Diagnostic:
+    """One lint issue as a diagnostic that underlines its line.
+
+    Lint reports lines, not columns: the range covers the line's text from
+    its first non-blank character.  An issue with no single line (line 0)
+    is placed at the top of the document.
+    """
+    row = max(issue.line - 1, 0)
+    text = lines[row] if row < len(lines) else ""
+    start = len(text) - len(text.lstrip())
+    return types.Diagnostic(
+        range=types.Range(
+            start=types.Position(line=row, character=start),
+            end=types.Position(line=row, character=len(text.rstrip("\r\n"))),
+        ),
+        message=issue.message,
+        severity=_SEVERITY.get(issue.severity, types.DiagnosticSeverity.Warning),
+        code=issue.code,
+        code_description=types.CodeDescription(href=f"{LINT_DOCS_URL}#{issue.code.lower()}"),
+        source="execsql",
+    )
+
+
+def diagnostics(
+    source: str,
+    path: str | None,
+    select: tuple[str, ...] = (),
+    ignore: tuple[str, ...] = (),
+) -> list[types.Diagnostic]:
+    """Lint *source* (the editor's current text of the file at *path*).
+
+    *path* lets lint resolve ``INCLUDE`` targets relative to the file;
+    *select* and *ignore* are rule-code prefixes, as ``execsql lint`` takes
+    them from ``--select`` / ``--ignore`` or a config file's ``[lint]``.
+    """
+    issues = filter_issues(lint_source(source, path or "<untitled>", path), select, ignore)
+    lines = source.splitlines()
+    return [to_diagnostic(issue, lines) for issue in sorted(issues, key=lambda i: (i.line, i.code))]
+
+
+def too_deep_diagnostic() -> types.Diagnostic:
+    """Stands in for lint's findings on a script nested too deeply to parse."""
+    return types.Diagnostic(
+        range=types.Range(start=types.Position(line=0, character=0), end=types.Position(line=0, character=0)),
+        message="The script nests blocks or conditions too deeply to check.",
+        severity=types.DiagnosticSeverity.Error,
+        source="execsql",
+    )

execsql/lsp/document.py

@@ -0,0 +1,210 @@
+"""What a script defines and refers to, with positions: the index the editor features read.
+
+Built from the recovering parser (a script with an unclosed block still
+indexes) and from the script's text for exact columns.  ``INCLUDE``d files
+are read from disk and indexed too, so a variable set in a shared setup
+script completes and resolves in the scripts that include it.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pygls.uris import from_fs_path
+
+from execsql.cli.lint import variables_defined_by
+from execsql.script.ast import IncludeDirective, MetaCommandStatement, ScriptBlock
+from execsql.script.parser import parse_string
+
+__all__ = [
+    "Location",
+    "Reference",
+    "ScriptIndex",
+    "file_uri",
+    "index_script",
+    "read_included",
+    "same_file_key",
+    "uri_for",
+    "variable_at",
+]
+
+# A substitution variable as written: !!name!!, !'!name!'!, !"!name!"! or the deferred !{name}!.
+# The lookahead also finds one written inside another's name: in !!N_!!GROUP!!_CHECKS!!,
+# execsql substitutes !!GROUP!! first, so GROUP is a use (N_ and _CHECKS are found too).
+_RX_VARIABLE = re.compile(r"""(?=!(['"]?)!(?P<name>[$&@~#+]?\w+)!\1!)|!\{(?P<deferred>[$&@~#+]?\w+)\}!""")
+_RX_METACOMMAND = re.compile(r"^\s*--\s*!x!\s*", re.I)
+
+
+@dataclass(frozen=True)
+class Location:
+    """A span on one line of a file: zero-based line, character offsets."""
+
+    path: str | None
+    line: int
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class Reference:
+    """A variable written in the script, e.g. ``!!report_dir!!``."""
+
+    name: str  # as written, with its prefix: "report_dir", "$CURRENT_DATE", "#param"
+    location: Location  # the name itself, inside the delimiters
+
+    @property
+    def key(self) -> str:
+        """The name a definition is filed under: user variables without ``~``/``+``, upper case."""
+        return self.name.lstrip("~+").upper()
+
+
+@dataclass
+class ScriptIndex:
+    """Definitions and uses in one script and the files it includes."""
+
+    path: str | None
+    definitions: dict[str, list[Location]] = field(default_factory=dict)  # by Reference.key
+    spellings: dict[str, str] = field(default_factory=dict)  # key -> name as first written
+    scripts: dict[str, Location] = field(default_factory=dict)  # BEGIN SCRIPT name (lower case) -> where
+    script_params: dict[str, list[str]] = field(default_factory=dict)  # script name -> its #parameters
+    includes: list[tuple[Location, str]] = field(default_factory=list)  # (where the target is written, resolved path)
+    script_calls: list[tuple[Location, str]] = field(default_factory=list)  # EXECUTE SCRIPT name, in this file
+    references: list[Reference] = field(default_factory=list)  # in this file and the files it includes
+    open_uris: dict[str, str] = field(default_factory=dict)  # same_file_key(path) -> URI of the editor's open copy
+
+    def define(self, name: str, location: Location) -> None:
+        key = name.lstrip("~+").upper()
+        self.definitions.setdefault(key, []).append(location)
+        self.spellings.setdefault(key, name.lstrip("~+"))
+
+
+# Limits on what INCLUDE indexing reads, so a script in an untrusted workspace
+# cannot make every request read a huge file or walk an endless include chain.
+MAX_INCLUDED_BYTES = 10 * 1024 * 1024
+MAX_INCLUDED_FILES = 200
+# The files an INCLUDE names, all together; past it indexing follows no more of them.
+MAX_INCLUDED_TOTAL_BYTES = 20 * 1024 * 1024
+
+
+def read_included(path: Path) -> str | None:
+    """The text of an ``INCLUDE``d file, or ``None`` if it is not one to index.
+
+    Only a regular file (not a FIFO or a device, whose read could block or
+    never end) of at most :data:`MAX_INCLUDED_BYTES` that decodes as UTF-8.
+    """
+    try:
+        if not path.is_file() or path.stat().st_size > MAX_INCLUDED_BYTES:
+            return None
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _span_of(word: str, line: str, start: int = 0) -> tuple[int, int]:
+    """Columns of *word* in *line* at or after *start* (any case); the whole line if absent."""
+    m = re.search(rf"(?<![\w$#@&]){re.escape(word)}(?!\w)", line[start:], re.I)  # after ~ or +: SUB ~name
+    if m is None:
+        return 0, len(line)
+    return start + m.start(), start + m.end()
+
+
+def index_script(
+    source: str,
+    path: str | None,
+    read: Callable[[Path], str | None] = read_included,
+) -> ScriptIndex:
+    """Index *source*, the text of the file at *path* (``None`` for an unsaved buffer).
+
+    *read* supplies an ``INCLUDE``d file's text; the server passes one that
+    prefers the editor's unsaved copy of a file that is open.
+    """
+    index = ScriptIndex(path=path)
+    _index_into(index, source, path, set(), read, top=True, budget=[MAX_INCLUDED_TOTAL_BYTES])
+    return index
+
+
+def _index_into(
+    index: ScriptIndex,
+    source: str,
+    path: str | None,
+    seen: set[str],
+    read: Callable[[Path], str | None],
+    *,
+    top: bool,
+    budget: list[int],
+) -> None:
+    if path is not None:
+        seen.add(str(Path(path).resolve()))
+    lines = source.splitlines()
+    script_dir = Path(path).parent if path else None
+    tree = parse_string(source, path or "<untitled>", errors=[])
+
+    for node in tree.walk():
+        row = node.span.start_line - 1
+        text = lines[row] if 0 <= row < len(lines) else ""
+        if isinstance(node, MetaCommandStatement):
+            prefix = _RX_METACOMMAND.match(text)
+            after = prefix.end() if prefix else 0
+            for name in sorted(variables_defined_by(node.command, script_dir)):
+                start, end = _span_of(name, text, after)
+                found = text[start:end] if text[start:end].upper() == name else name  # keep the script's spelling
+                index.define(found, Location(path, row, start, end))
+        elif isinstance(node, ScriptBlock):
+            start, end = _span_of(node.name, text)
+            index.scripts.setdefault(node.name.lower(), Location(path, row, start, end))
+            index.script_params[node.name.lower()] = [p.name for p in node.param_defs or []]
+        elif isinstance(node, IncludeDirective) and node.is_execute_script:
+            if top:
+                start, end = _span_of(node.target, text)
+                index.script_calls.append((Location(path, row, start, end), node.target.lower()))
+        elif isinstance(node, IncludeDirective):
+            target = node.target.strip().strip("\"'")
+            start, end = _span_of(target, text) if target else (0, len(text))
+            resolved = Path(target) if Path(target).is_absolute() or script_dir is None else script_dir / target
+            if top:
+                index.includes.append((Location(path, row, start, end), str(resolved)))
+            if "!" not in target and str(resolved.resolve()) not in seen and len(seen) < MAX_INCLUDED_FILES:
+                included = read(resolved)
+                if included is not None and len(included) <= budget[0]:
+                    budget[0] -= len(included)
+                    _index_into(index, included, str(resolved), seen, read, top=False, budget=budget)
+
+    for row, text in enumerate(lines):
+        for m in _RX_VARIABLE.finditer(text):
+            group = "deferred" if m.group("deferred") else "name"
+            index.references.append(Reference(m.group(group), Location(path, row, m.start(group), m.end(group))))
+
+
+def uri_for(path: str | None, index: ScriptIndex, uri: str) -> str:
+    """The URI to report for a location in *path*.
+
+    For the indexed file it is the request's *uri*, as the client spelled it:
+    one rebuilt from the path can differ (``file:///c:/`` and ``file:///C:/``
+    on Windows), and a client may not match the two.
+    """
+    if path is None or path == index.path:
+        return uri
+    return file_uri(path, index) or uri
+
+
+def file_uri(path: str, index: ScriptIndex) -> str | None:
+    """The URI for another file at *path*: as the client spelled it if the file is open, else one built from the path."""
+    return index.open_uris.get(same_file_key(path)) or from_fs_path(path)
+
+
+def same_file_key(path: str) -> str:
+    """*path* resolved and case-folded where the file system ignores case, for comparing files."""
+    return os.path.normcase(str(Path(path).resolve()))
+
+
+def variable_at(index: ScriptIndex, line: int, character: int) -> Reference | None:
+    """The variable reference under the cursor in the indexed file, if any."""
+    for ref in index.references:
+        loc = ref.location
+        if loc.path == index.path and loc.line == line and loc.start <= character <= loc.end:
+            return ref
+    return None

execsql/lsp/folding.py

@@ -0,0 +1,59 @@
+"""Folding ranges: metacommand blocks and their branches, multi-line SQL statements and comments.
+
+An editor that gets folding ranges from a server stops folding by
+indentation, so the ranges cover everything worth folding, not only the
+blocks execsql adds.
+"""
+
+from __future__ import annotations
+
+import re
+
+from lsprotocol import types
+
+from execsql.script.ast import BatchBlock, Comment, IfBlock, LoopBlock, ScriptBlock, SqlBlock, SqlStatement
+from execsql.script.parser import parse_string
+
+__all__ = ["folding_ranges"]
+
+_BLOCKS = (IfBlock, LoopBlock, BatchBlock, ScriptBlock, SqlBlock)
+# The line that closes a block, as the parser reads it: ENDIF, END LOOP, END SCRIPT, END BATCH, END SQL.
+_RX_BLOCK_END = re.compile(r"^\s*--\s*!x!\s*(?:ENDIF|END\s*LOOP|END\s+(?:SCRIPT|BATCH|SQL)\b)", re.I)
+
+
+def _range(start_line: int, end_line: int, kind: str | None = None) -> types.FoldingRange | None:
+    """A range over 1-based *start_line*..*end_line*, or ``None`` if that is a single line."""
+    if end_line <= start_line:
+        return None
+    return types.FoldingRange(start_line=start_line - 1, end_line=end_line - 1, kind=kind)
+
+
+def folding_ranges(source: str, path: str | None) -> list[types.FoldingRange]:
+    """The script's folding ranges, in document order.
+
+    A block folds up to the line before its closing metacommand, so
+    ``ENDIF`` / ``END LOOP`` / ``END SCRIPT`` stays visible (a block left
+    unclosed folds to its last line); an IF folds each branch separately, up
+    to the line before the next ``ELSEIF`` or ``ELSE``.
+    """
+    lines = source.splitlines()
+    tree = parse_string(source, path or "<untitled>", errors=[])
+    found: list[types.FoldingRange | None] = []
+    for node in tree.walk():
+        span = node.span
+        end = span.effective_end_line
+        if isinstance(node, _BLOCKS) and not (0 < end <= len(lines) and _RX_BLOCK_END.match(lines[end - 1])):
+            end += 1  # no closing line to keep visible
+        if isinstance(node, IfBlock):
+            starts = [span.start_line, *(c.span.start_line for c in node.elseif_clauses)]
+            if node.else_span is not None:
+                starts.append(node.else_span.start_line)
+            for start, following in zip(starts, [*starts[1:], end], strict=True):
+                found.append(_range(start, following - 1))
+        elif isinstance(node, _BLOCKS):
+            found.append(_range(span.start_line, end - 1))
+        elif isinstance(node, SqlStatement):
+            found.append(_range(span.start_line, end))
+        elif isinstance(node, Comment):
+            found.append(_range(span.start_line, end, types.FoldingRangeKind.Comment))
+    return sorted((r for r in found if r is not None), key=lambda r: (r.start_line, -r.end_line))

execsql/lsp/formatting.py

@@ -0,0 +1,37 @@
+"""Format Document: ``execsql format`` on the editor's text."""
+
+from __future__ import annotations
+
+from lsprotocol import types
+
+from execsql.format import format_file
+
+__all__ = ["format_document"]
+
+
+def format_document(
+    source: str,
+    indent: int = 4,
+    use_sql: bool = True,
+    leading_comma: bool = False,
+    rewrite_sql: bool = False,
+) -> list[types.TextEdit]:
+    """One edit replacing the whole document with its formatted text; none when it is already formatted.
+
+    The options are ``execsql format``'s, from the ``[format]`` config section.
+    """
+    formatted = format_file(
+        source,
+        indent=indent,
+        use_sql=use_sql,
+        leading_comma=leading_comma,
+        rewrite_sql=rewrite_sql,
+    )
+    if formatted == source:
+        return []
+    lines = source.splitlines(keepends=True)
+    end = types.Position(line=len(lines), character=0)
+    if lines and not lines[-1].endswith(("\n", "\r")):
+        # LSP counts characters in UTF-16 code units.
+        end = types.Position(line=len(lines) - 1, character=len(lines[-1].encode("utf-16-le")) // 2)
+    return [types.TextEdit(range=types.Range(start=types.Position(line=0, character=0), end=end), new_text=formatted)]