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

execsql/lsp/hover.py

@@ -0,0 +1,119 @@
+"""Hover: what the metacommand, conditional test or variable under the cursor is.
+
+Metacommands and conditional tests are explained from
+:mod:`execsql.metacommands.reference`; a variable by where the script defines
+it, or by its reference entry for system variables.
+"""
+
+from __future__ import annotations
+
+import re
+
+from lsprotocol import types
+
+from execsql.lsp.document import Reference, ScriptIndex, variable_at
+from execsql.metacommands import reference
+
+__all__ = ["hover", "metacommand_for"]
+
+_RX_METACOMMAND = re.compile(r"^(?P<lead>\s*--\s*!x!\s*)(?P<command>.*?)\s*$", re.I)
+_RX_WORD = re.compile(r"[A-Za-z_]+")
+
+
+def metacommand_for(command: str) -> reference.Metacommand | None:
+    """The reference entry for a metacommand's text (what follows ``-- !x!``).
+
+    The dispatch entry that would run it names its keyword when it has one
+    (``PROMPT MESSAGE "..." MAP ...`` is PROMPT MAP); otherwise the longest
+    keyword the text starts with (``AUTOCOMMIT ON`` is AUTOCOMMIT,
+    ``CONFIG BOOLEAN_INT YES`` is CONFIG).
+    """
+    from execsql.cli.lint import _dispatch_table
+
+    match = _dispatch_table().get_match(command)
+    if match is not None and match[0].description:
+        entry = reference.metacommand(match[0].description)
+        if entry is not None:
+            return entry
+    best = None
+    for entry in reference.metacommands():
+        if re.match(rf"{re.escape(entry.keyword)}S?\b", command.strip(), re.I) and (
+            best is None or len(entry.keyword) > len(best.keyword)
+        ):
+            best = entry
+    return best
+
+
+def _markdown(text: str) -> types.MarkupContent:
+    return types.MarkupContent(kind=types.MarkupKind.Markdown, value=text)
+
+
+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 _syntax_block(forms: tuple[str, ...]) -> str:
+    return "```\n" + "\n".join(forms) + "\n```"
+
+
+def _variable_hover(index: ScriptIndex, ref: Reference, lines: list[str]) -> str | None:
+    name = ref.name
+    if name.startswith("$"):
+        var = reference.system_variable(name)
+        if var is None:
+            return f"**{name}**: not a system variable execsql defines."
+        return f"**{name}** — system variable\n\n{var.summary}\n\n[Reference]({var.url})"
+    if name.startswith("&"):
+        return f"**{name}** — the environment variable `{name[1:]}`."
+    if name.startswith("@"):
+        return f"**{name}** — a column value assigned by SELECT_SUB or PROMPT SELECT_SUB."
+    if name.startswith("#"):
+        owners = [s for s, params in index.script_params.items() if name[1:].lower() in (p.lower() for p in params)]
+        if owners:
+            return f"**{name}** — parameter of SCRIPT {', '.join(owners)}."
+        return f"**{name}** — a SCRIPT parameter, but no SCRIPT here declares `{name[1:]}`."
+    locations = index.definitions.get(ref.key)
+    if not locations:
+        return f"**{name}** is not defined in this script or the files it includes (lint rule V001)."
+    parts = [f"**{name}** — substitution variable"]
+    for loc in locations[:5]:
+        where = f"line {loc.line + 1}" if loc.path == index.path else f"{loc.path}, line {loc.line + 1}"
+        text = lines[loc.line].strip() if loc.path == index.path and loc.line < len(lines) else ""
+        parts.append(f"Defined at {where}" + (f":\n```\n{text}\n```" if text else "."))
+    if len(locations) > 5:
+        parts.append(f"… and {len(locations) - 5} more.")
+    return "\n\n".join(parts)
+
+
+def hover(index: ScriptIndex, source: str, line: int, character: int) -> types.Hover | None:
+    """What to show for the cursor at (*line*, *character*), zero-based."""
+    lines = source.splitlines()
+    text = lines[line] if 0 <= line < len(lines) else ""
+
+    ref = variable_at(index, line, character)
+    if ref is not None:
+        content = _variable_hover(index, ref, lines)
+        loc = ref.location
+        return types.Hover(contents=_markdown(content), range=_range(line, loc.start, loc.end)) if content else None
+
+    m = _RX_METACOMMAND.match(text)
+    if not m or character < m.end("lead"):
+        return None
+
+    # A conditional test under the cursor: a word followed by "(".
+    for word in _RX_WORD.finditer(text):
+        if word.start() <= character <= word.end() and text[word.end() :].lstrip().startswith("("):
+            cond = reference.condition(word.group())
+            if cond is not None and cond.name not in ("NOT", "OR"):
+                body = f"**{cond.name}** — conditional test\n\n{cond.summary}\n\n{_syntax_block(cond.forms)}\n\n[Reference]({cond.url})"
+                return types.Hover(contents=_markdown(body), range=_range(line, word.start(), word.end()))
+
+    entry = metacommand_for(m.group("command"))
+    if entry is None:
+        return None
+    start = m.end("lead")
+    written = re.match(r"\s*".join(map(re.escape, entry.keyword.split())), text[start:], re.I)
+    first_word = re.match(r"[A-Za-z_]+", text[start:])
+    keyword_end = start + (written.end() if written else first_word.end() if first_word else 0)
+    body = f"**{entry.keyword}** — {entry.category} metacommand\n\n{entry.summary}\n\n{_syntax_block(entry.forms)}\n\n[Reference]({entry.url})"
+    return types.Hover(contents=_markdown(body), range=_range(line, start, keyword_end))

execsql/lsp/navigation.py

@@ -0,0 +1,169 @@
+"""Navigation: go to definition, find references, the document outline and INCLUDE links."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from lsprotocol import types
+
+from execsql.lsp.document import Location, ScriptIndex, file_uri, uri_for, variable_at
+from execsql.script.ast import (
+    BatchBlock,
+    IfBlock,
+    IncludeDirective,
+    LoopBlock,
+    MetaCommandStatement,
+    Node,
+    ScriptBlock,
+    SqlBlock,
+)
+from execsql.script.parser import parse_string
+
+__all__ = ["definition", "document_links", "document_symbols", "references"]
+
+
+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 _lsp_location(loc: Location, index: ScriptIndex, uri: str) -> types.Location:
+    return types.Location(uri=uri_for(loc.path, index, uri), range=_range(loc.line, loc.start, loc.end))
+
+
+def _at(entries: list[tuple[Location, str]], line: int, character: int) -> str | None:
+    for loc, value in entries:
+        if loc.line == line and loc.start <= character <= loc.end:
+            return value
+    return None
+
+
+def definition(index: ScriptIndex, uri: str, line: int, character: int) -> list[types.Location]:
+    """Where the variable, SCRIPT or included file under the cursor is defined."""
+    ref = variable_at(index, line, character)
+    if ref is not None:
+        if ref.name.startswith("#"):
+            name = ref.name[1:].lower()
+            return [
+                _lsp_location(index.scripts[script], index, uri)
+                for script, params in index.script_params.items()
+                if name in (p.lower() for p in params) and script in index.scripts
+            ]
+        return [_lsp_location(loc, index, uri) for loc in index.definitions.get(ref.key, [])]
+
+    script = _at(index.script_calls, line, character)
+    if script is not None and script in index.scripts:
+        return [_lsp_location(index.scripts[script], index, uri)]
+
+    target = _at(index.includes, line, character)
+    if target is not None and Path(target).is_file():
+        uri_of_file = file_uri(target, index)
+        if uri_of_file:
+            return [types.Location(uri=uri_of_file, range=_range(0, 0, 0))]
+    return []
+
+
+def references(
+    index: ScriptIndex,
+    uri: str,
+    line: int,
+    character: int,
+    include_declaration: bool = True,
+) -> list[types.Location]:
+    """Every use of the variable under the cursor in this file and the files it includes (and its definitions)."""
+    ref = variable_at(index, line, character)
+    if ref is None:
+        return []
+    found = [_lsp_location(r.location, index, uri) for r in index.references if r.key == ref.key]
+    if include_declaration and not ref.name.startswith(("$", "&", "@", "#")):
+        found += [_lsp_location(loc, index, uri) for loc in index.definitions.get(ref.key, [])]
+    return found
+
+
+def document_links(index: ScriptIndex) -> list[types.DocumentLink]:
+    """Each INCLUDE target that exists, as a link to the file."""
+    links = []
+    for loc, target in index.includes:
+        path = Path(target)
+        if path.is_file():
+            uri = file_uri(target, index)
+            if uri:
+                links.append(types.DocumentLink(range=_range(loc.line, loc.start, loc.end), target=uri))
+    return links
+
+
+def _node_range(node: Node, lines: list[str]) -> types.Range:
+    start = node.span.start_line - 1
+    end = node.span.effective_end_line - 1
+    end_text = lines[end] if 0 <= end < len(lines) else ""
+    return types.Range(
+        start=types.Position(line=start, character=0),
+        end=types.Position(line=end, character=len(end_text)),
+    )
+
+
+def _symbol(
+    name: str,
+    kind: types.SymbolKind,
+    node: Node,
+    lines: list[str],
+    children: list[types.DocumentSymbol],
+) -> types.DocumentSymbol:
+    rng = _node_range(node, lines)
+    head = types.Range(
+        start=rng.start,
+        end=types.Position(
+            line=rng.start.line,
+            character=len(lines[rng.start.line]) if rng.start.line < len(lines) else 0,
+        ),
+    )
+    return types.DocumentSymbol(name=name, kind=kind, range=rng, selection_range=head, children=children or None)
+
+
+def _symbols(nodes: list[Node], lines: list[str], index: ScriptIndex) -> list[types.DocumentSymbol]:
+    out: list[types.DocumentSymbol] = []
+    for node in nodes:
+        children = _symbols(list(node.children()), lines, index)
+        if isinstance(node, ScriptBlock):
+            params = ", ".join(p.name for p in node.param_defs or [])
+            out.append(
+                _symbol(
+                    f"SCRIPT {node.name}({params})" if params else f"SCRIPT {node.name}",
+                    types.SymbolKind.Function,
+                    node,
+                    lines,
+                    children,
+                ),
+            )
+        elif isinstance(node, IfBlock):
+            out.append(_symbol(f"IF ({node.condition.strip()})", types.SymbolKind.Namespace, node, lines, children))
+        elif isinstance(node, LoopBlock):
+            out.append(
+                _symbol(
+                    f"LOOP {node.loop_type} ({node.condition.strip()})",
+                    types.SymbolKind.Namespace,
+                    node,
+                    lines,
+                    children,
+                ),
+            )
+        elif isinstance(node, BatchBlock):
+            out.append(_symbol("BATCH", types.SymbolKind.Namespace, node, lines, children))
+        elif isinstance(node, SqlBlock):
+            out.append(_symbol("SQL block", types.SymbolKind.Namespace, node, lines, children))
+        elif isinstance(node, IncludeDirective) and not node.is_execute_script:
+            out.append(_symbol(f"INCLUDE {node.target.strip()}", types.SymbolKind.File, node, lines, []))
+        elif isinstance(node, MetaCommandStatement):
+            row = node.span.start_line - 1
+            for key, locations in index.definitions.items():
+                for loc in locations:
+                    if loc.path == index.path and loc.line == row:
+                        out.append(_symbol(index.spellings[key], types.SymbolKind.Variable, node, lines, []))
+        else:
+            out.extend(children)
+    return out
+
+
+def document_symbols(index: ScriptIndex, source: str) -> list[types.DocumentSymbol]:
+    """The outline: SCRIPT blocks, IF / LOOP / BATCH blocks, INCLUDE directives and variable definitions, nested."""
+    tree = parse_string(source, index.path or "<untitled>", errors=[])
+    return _symbols(tree.body, source.splitlines(), index)

execsql/lsp/rename.py

@@ -0,0 +1,91 @@
+"""Rename a user variable everywhere the index sees it: the script and the files it includes.
+
+Scripts that ``INCLUDE`` this one are not known to the server, so their
+uses of the variable are not renamed.
+"""
+
+from __future__ import annotations
+
+import re
+
+from lsprotocol import types
+
+from execsql.lsp.document import Location, ScriptIndex, uri_for, variable_at
+
+__all__ = ["RenameError", "prepare_rename", "rename"]
+
+_RX_NAME = re.compile(r"^\w+$")
+
+
+class RenameError(ValueError):
+    """Why a rename cannot be done; the server shows the message."""
+
+
+def _target(index: ScriptIndex, line: int, character: int) -> tuple[str, Location] | None:
+    """The user variable under the cursor: its key and where its bare name is written."""
+    ref = variable_at(index, line, character)
+    if ref is not None:
+        bare = ref.name.lstrip("~+")
+        if not _RX_NAME.match(bare):  # $system, &environment, @column or #parameter
+            return None
+        loc = ref.location
+        return ref.key, Location(loc.path, loc.line, loc.end - len(bare), loc.end)
+    for key, locations in index.definitions.items():
+        for loc in locations:
+            if loc.path == index.path and loc.line == line and loc.start <= character <= loc.end:
+                return key, loc
+    return None
+
+
+def _range(loc: Location) -> types.Range:
+    return types.Range(
+        start=types.Position(line=loc.line, character=loc.start),
+        end=types.Position(line=loc.line, character=loc.end),
+    )
+
+
+def prepare_rename(index: ScriptIndex, line: int, character: int) -> types.Range | None:
+    """The name to rename at the cursor, or ``None`` if there is nothing renameable there."""
+    target = _target(index, line, character)
+    return _range(target[1]) if target else None
+
+
+def rename(index: ScriptIndex, uri: str, line: int, character: int, new_name: str) -> types.WorkspaceEdit | None:
+    """Edits renaming the variable under the cursor to *new_name*.
+
+    Raises :class:`RenameError` when the rename would not be correct: an
+    invalid name, one already defined, a name used both as a local
+    (``~name``) and a global variable (execsql keeps those apart; the index
+    does not), or a definition whose name cannot be located on its line.
+    """
+    target = _target(index, line, character)
+    if target is None:
+        return None
+    key = target[0]
+    if not _RX_NAME.match(new_name):
+        raise RenameError(f"{new_name!r} is not a variable name: use letters, digits and underscores.")
+    if new_name.upper() != key and new_name.upper() in index.definitions:
+        raise RenameError(f"{new_name} is already defined.")
+
+    uses = [r for r in index.references if r.key == key]
+    prefixes = {r.name[: len(r.name) - len(r.name.lstrip("~+"))] for r in uses}
+    if "~" in prefixes and len(prefixes) > 1:
+        raise RenameError(f"{key.lower()} is used both as a local (~) and a global variable; rename it by hand.")
+
+    spans: set[Location] = set()
+    for ref in uses:
+        bare = ref.name.lstrip("~+")
+        loc = ref.location
+        spans.add(Location(loc.path, loc.line, loc.end - len(bare), loc.end))
+    for loc in index.definitions.get(key, []):
+        if loc.end - loc.start != len(key):
+            where = f"{loc.path or 'this file'}, line {loc.line + 1}"
+            raise RenameError(f"Cannot find the name {key.lower()} in its definition ({where}); rename it by hand.")
+        spans.add(loc)
+
+    changes: dict[str, list[types.TextEdit]] = {}
+    for loc in sorted(spans, key=lambda s: (s.path or "", s.line, s.start)):
+        changes.setdefault(uri_for(loc.path, index, uri), []).append(
+            types.TextEdit(range=_range(loc), new_text=new_name),
+        )
+    return types.WorkspaceEdit(changes=changes)