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

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

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,206 @@
+"""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
+
+
+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)
+    return index
+
+
+def _index_into(
+    index: ScriptIndex,
+    source: str,
+    path: str | None,
+    seen: set[str],
+    read: Callable[[Path], str | None],
+    *,
+    top: bool,
+) -> 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:
+                    _index_into(index, included, str(resolved), seen, read, top=False)
+
+    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