execsql2 2.29.0__py3-none-any.whl → 2.31.1__py3-none-any.whl

execsql/lsp/code_actions.py

@@ -18,14 +18,14 @@ from collections.abc import Iterator, Sequence
 
 from lsprotocol import types
 
-from execsql.cli.lint import _dispatch_table, _with_placeholders, lint_source
+from execsql.cli.lint import _dispatch_table, lint_source
 from execsql.format import open_dollar_quote
 from execsql.lsp.document import ScriptIndex
 from execsql.metacommands import reference
+from execsql.lsp._util import RX_METACOMMAND, span
 
 __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
@@ -53,10 +53,6 @@ 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,
@@ -81,7 +77,7 @@ def _clears(lines: list[str], path: str | None, code: str, before: tuple[int, in
 
 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)
+    m = RX_METACOMMAND.match(text)
     if not m:
         return
     vocabulary = _vocabulary()
@@ -93,7 +89,7 @@ def _metacommand_fixes(text: str, row: int) -> Iterator[tuple[str, int, int, str
             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:
+            if table.get_match(fixed) is not None:
                 yield candidate, offset + word.start(), offset + word.end(), word.group()
 
 
@@ -104,7 +100,7 @@ def _p003(uri: str, lines: list[str], diagnostic: types.Diagnostic) -> list[type
             f"Change {written} to {_cased_like(candidate, written)}",
             uri,
             diagnostic,
-            [types.TextEdit(range=_range(row, start, end), new_text=_cased_like(candidate, written))],
+            [types.TextEdit(range=span(row, start, end), new_text=_cased_like(candidate, written))],
         )
         for candidate, start, end, written in _metacommand_fixes(lines[row], row)
     ]
@@ -113,7 +109,7 @@ def _p003(uri: str, lines: list[str], diagnostic: types.Diagnostic) -> list[type
 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)
+    m = RX_METACOMMAND.match(text)
     if not m:
         return []
     names = {c.name for c in reference.conditions() if c.name not in ("NOT", "OR")}
@@ -126,7 +122,7 @@ def _p004(uri: str, path: str | None, lines: list[str], diagnostic: types.Diagno
         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)
+                edit = types.TextEdit(range=span(row, word.start(), word.end()), new_text=new)
                 actions.append(_fix(f"Change {word.group()} to {new}", uri, diagnostic, [edit]))
     return actions
 
@@ -151,7 +147,7 @@ def _v001(index: ScriptIndex, uri: str, diagnostic: types.Diagnostic) -> list[ty
             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)
+            edit = types.TextEdit(range=span(row, loc.start, loc.end), new_text=new)
             actions.append(_fix(f"Change !!{ref.name}!! to !!{new}!!", uri, diagnostic, [edit]))
         break
     return actions
@@ -183,8 +179,8 @@ def _p002(uri: str, path: str | None, lines: list[str], diagnostic: types.Diagno
     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"),
+        types.TextEdit(range=span(row, 0, 0), new_text=f"{indent}-- !x! BEGIN SQL\n"),
+        types.TextEdit(range=span(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)]
 

execsql/lsp/completion.py

@@ -14,6 +14,7 @@ from lsprotocol import types
 
 from execsql.lsp.document import ScriptIndex
 from execsql.metacommands import reference
+from execsql.lsp._util import markdown, span
 
 __all__ = ["completions"]
 
@@ -27,17 +28,9 @@ _RX_EXPORT_FORMAT = re.compile(r"^\s*--\s*!x!\s*EXPORT\b.*\bAS\s+(?P<partial>\w*
 _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})")
+    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]:
@@ -59,7 +52,7 @@ def _keyword_items(line: int, start: int, end: int, typed: str, snippets: bool)
                     filter_text=entry.keyword,
                     sort_text=f"{entry.keyword}\x00{n:03d}",
                     text_edit=types.TextEdit(
-                        range=_range(line, start, end),
+                        range=span(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,
@@ -78,9 +71,9 @@ def _condition_items(line: int, start: int, end: int, snippets: bool) -> list[ty
                 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})"),
+                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),
+                    range=span(line, start, end),
                     new_text=entry.snippet if snippets else entry.name,
                 ),
                 insert_text_format=types.InsertTextFormat.Snippet if snippets else types.InsertTextFormat.PlainText,
@@ -107,9 +100,9 @@ def _variable_items(
                 label=name,
                 kind=kind,
                 detail=detail,
-                documentation=_markdown(doc) if doc else None,
+                documentation=markdown(doc) if doc else None,
                 text_edit=types.TextEdit(
-                    range=_range(line, start, end),
+                    range=span(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,
@@ -182,7 +175,7 @@ def completions(
                     label=fmt.upper(),
                     kind=types.CompletionItemKind.EnumMember,
                     detail="export format",
-                    text_edit=types.TextEdit(range=_range(line, start, character), new_text=fmt.upper()),
+                    text_edit=types.TextEdit(range=span(line, start, character), new_text=fmt.upper()),
                 )
                 for fmt in sorted(ALL_EXPORT_FORMATS)
             ],

execsql/lsp/diagnostics.py

@@ -8,7 +8,7 @@ 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/"
+LINT_DOCS_URL = "https://execsql2.readthedocs.io/en/stable/reference/lint/"
 
 _SEVERITY = {
     "error": types.DiagnosticSeverity.Error,
@@ -44,18 +44,30 @@ def diagnostics(
     path: str | None,
     select: tuple[str, ...] = (),
     ignore: tuple[str, ...] = (),
+    base_dir: str | None = None,
 ) -> 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;
+    *path* lets lint resolve ``INCLUDE`` targets relative to the file (an
+    unsaved buffer's, with no *path*, resolve against *base_dir*);
     *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)
+    issues = filter_issues(lint_source(source, path or "<untitled>", path, base_dir), select, ignore)
     lines = source.splitlines()
     return [to_diagnostic(issue, lines) for issue in sorted(issues, key=lambda i: (i.line, i.code))]
 
 
+def failure_diagnostic(exc: BaseException) -> types.Diagnostic:
+    """Stands in for lint's findings when checking the script raised an unexpected error."""
+    return types.Diagnostic(
+        range=types.Range(start=types.Position(line=0, character=0), end=types.Position(line=0, character=0)),
+        message=f"execsql could not check this script ({type(exc).__name__}: {exc}).",
+        severity=types.DiagnosticSeverity.Error,
+        source="execsql",
+    )
+
+
 def too_deep_diagnostic() -> types.Diagnostic:
     """Stands in for lint's findings on a script nested too deeply to parse."""
     return types.Diagnostic(

execsql/lsp/document.py

@@ -17,26 +17,30 @@ from pathlib import Path
 from pygls.uris import from_fs_path
 
 from execsql.cli.lint import variables_defined_by
+from execsql.lsp._util import RX_METACOMMAND
+from execsql.utils.paths import is_network_path
 from execsql.script.ast import IncludeDirective, MetaCommandStatement, ScriptBlock
 from execsql.script.parser import parse_string
 
 __all__ = [
+    "FileFacts",
     "Location",
     "Reference",
     "ScriptIndex",
+    "file_facts",
     "file_uri",
     "index_script",
     "read_included",
     "same_file_key",
     "uri_for",
     "variable_at",
+    "is_file",
 ]
 
 # 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)
@@ -100,7 +104,7 @@ def read_included(path: Path) -> str | None:
         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):
+    except (OSError, ValueError, UnicodeDecodeError):  # ValueError: a NUL in the name
         return None
 
 
@@ -112,71 +116,152 @@ def _span_of(word: str, line: str, start: int = 0) -> tuple[int, int]:
     return start + m.start(), start + m.end()
 
 
+@dataclass(frozen=True)
+class _Define:
+    name: str  # as the script spells it
+    location: Location
+
+
+@dataclass(frozen=True)
+class _ScriptDef:
+    name: str  # lower case
+    location: Location
+    params: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class _ScriptCall:
+    location: Location
+    name: str  # lower case
+
+
+@dataclass(frozen=True)
+class _Include:
+    location: Location
+    target: str  # as written, quotes removed
+    resolved: str  # relative to the including file
+
+
+@dataclass(frozen=True)
+class FileFacts:
+    """What one file adds to an index, in the order indexing meets it.
+
+    It depends on the file's text and path alone, not on the files it
+    includes, so a caller may keep it while the text is unchanged, unless
+    :attr:`reads_ini`: a ``SUB_INI`` reads an INI file that can change on its own.
+    """
+
+    steps: tuple[_Define | _ScriptDef | _ScriptCall | _Include, ...]
+    references: tuple[Reference, ...]
+    reads_ini: bool = False
+
+    @property
+    def includes(self) -> tuple[str, ...]:
+        """The path of each file an ``INCLUDE`` in this file names, relative to it."""
+        return tuple(step.resolved for step in self.steps if isinstance(step, _Include))
+
+
+_RX_SUB_INI = re.compile(r"\s*SUB_INI\b", re.I)
+
+
+def file_facts(source: str, path: str | None, base_dir: str | None = None) -> FileFacts:
+    """The definitions, script blocks, ``INCLUDE`` targets and variable uses written in *source*.
+
+    Relative paths in it resolve against *path*'s directory, or for an
+    unsaved buffer (no *path*) against *base_dir*, else the working directory.
+    """
+    steps: list[_Define | _ScriptDef | _ScriptCall | _Include] = []
+    reads_ini = False
+    lines = source.splitlines()
+    script_dir = Path(path).parent if path else (Path(base_dir) if base_dir 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):
+            reads_ini = reads_ini or _RX_SUB_INI.match(node.command) is not None
+            prefix = RX_METACOMMAND.match(text)
+            after = prefix.end("lead") 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
+                steps.append(_Define(found, Location(path, row, start, end)))
+        elif isinstance(node, ScriptBlock):
+            start, end = _span_of(node.name, text)
+            params = tuple(p.name for p in node.param_defs or [])
+            steps.append(_ScriptDef(node.name.lower(), Location(path, row, start, end), params))
+        elif isinstance(node, IncludeDirective) and node.is_execute_script:
+            start, end = _span_of(node.target, text)
+            steps.append(_ScriptCall(Location(path, row, start, end), node.target.lower()))
+        elif isinstance(node, IncludeDirective):
+            target = node.target.strip().strip("\"'")
+            if is_network_path(target):
+                continue  # never followed: checking it would contact the named host
+            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
+            steps.append(_Include(Location(path, row, start, end), target, str(resolved)))
+
+    references: list[Reference] = []
+    for row, text in enumerate(lines):
+        for m in _RX_VARIABLE.finditer(text):
+            group = "deferred" if m.group("deferred") else "name"
+            references.append(Reference(m.group(group), Location(path, row, m.start(group), m.end(group))))
+    return FileFacts(tuple(steps), tuple(references), reads_ini)
+
+
 def index_script(
     source: str,
     path: str | None,
     read: Callable[[Path], str | None] = read_included,
+    facts: Callable[[str, str | None, str | None], FileFacts] = file_facts,
+    base_dir: str | None = None,
 ) -> 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.
+    prefers the editor's unsaved copy of a file that is open.  *facts*
+    reads one file's text; the server passes one that remembers the answer.
+    An unsaved buffer's relative ``INCLUDE`` resolves against *base_dir*.
     """
     index = ScriptIndex(path=path)
-    _index_into(index, source, path, set(), read, top=True, budget=[MAX_INCLUDED_TOTAL_BYTES])
+    found = facts(source, path, None if path else base_dir)
+    _index_into(index, found, path, set(), read, facts, top=True, budget=[MAX_INCLUDED_TOTAL_BYTES])
     return index
 
 
 def _index_into(
     index: ScriptIndex,
-    source: str,
+    found: FileFacts,
     path: str | None,
     seen: set[str],
     read: Callable[[Path], str | None],
+    facts: Callable[[str, str | None, str | None], FileFacts],
     *,
     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:
+        seen.add(_resolved(path))
+    for step in found.steps:
+        if isinstance(step, _Define):
+            index.define(step.name, step.location)
+        elif isinstance(step, _ScriptDef):
+            index.scripts.setdefault(step.name, step.location)
+            index.script_params[step.name] = list(step.params)
+        elif isinstance(step, _ScriptCall):
             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
+                index.script_calls.append((step.location, step.name))
+        else:
             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)
+                index.includes.append((step.location, step.resolved))
+            if "!" not in step.target and _resolved(step.resolved) not in seen and len(seen) < MAX_INCLUDED_FILES:
+                included = read(Path(step.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))))
+                    included_facts = facts(included, step.resolved, None)
+                    _index_into(index, included_facts, step.resolved, seen, read, facts, top=False, budget=budget)
+    index.references.extend(found.references)
 
 
 def uri_for(path: str | None, index: ScriptIndex, uri: str) -> str:
@@ -196,9 +281,25 @@ def file_uri(path: str, index: ScriptIndex) -> str | None:
     return index.open_uris.get(same_file_key(path)) or from_fs_path(path)
 
 
+def _resolved(path: str) -> str:
+    """*path* made absolute with links resolved, or just made absolute when the OS rejects it (too long, a NUL)."""
+    try:
+        return str(Path(path).resolve())
+    except (OSError, ValueError):
+        return os.path.abspath(path)
+
+
+def is_file(path: str | Path) -> bool:
+    """Whether *path* names a regular file; ``False`` for a name the OS rejects (too long, a NUL)."""
+    try:
+        return Path(path).is_file()
+    except (OSError, ValueError):
+        return False
+
+
 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()))
+    return os.path.normcase(_resolved(path))
 
 
 def variable_at(index: ScriptIndex, line: int, character: int) -> Reference | None:

execsql/lsp/hover.py

@@ -13,10 +13,10 @@ from lsprotocol import types
 
 from execsql.lsp.document import Reference, ScriptIndex, variable_at
 from execsql.metacommands import reference
+from execsql.lsp._util import RX_METACOMMAND, markdown, span
 
 __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_]+")
 
 
@@ -44,14 +44,6 @@ def metacommand_for(command: str) -> reference.Metacommand | None:
     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```"
 
@@ -94,9 +86,9 @@ def hover(index: ScriptIndex, source: str, line: int, character: int) -> types.H
     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
+        return types.Hover(contents=markdown(content), range=span(line, loc.start, loc.end)) if content else None
 
-    m = _RX_METACOMMAND.match(text)
+    m = RX_METACOMMAND.match(text)
     if not m or character < m.end("lead"):
         return None
 
@@ -106,7 +98,7 @@ def hover(index: ScriptIndex, source: str, line: int, character: int) -> types.H
             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()))
+                return types.Hover(contents=markdown(body), range=span(line, word.start(), word.end()))
 
     entry = metacommand_for(m.group("command"))
     if entry is None:
@@ -116,4 +108,4 @@ def hover(index: ScriptIndex, source: str, line: int, character: int) -> types.H
     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))
+    return types.Hover(contents=markdown(body), range=span(line, start, keyword_end))

execsql/lsp/navigation.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 from lsprotocol import types
 
-from execsql.lsp.document import Location, ScriptIndex, file_uri, uri_for, variable_at
+from execsql.lsp.document import Location, ScriptIndex, file_uri, is_file, uri_for, variable_at
 from execsql.script.ast import (
     BatchBlock,
     IfBlock,
@@ -18,16 +18,13 @@ from execsql.script.ast import (
     SqlBlock,
 )
 from execsql.script.parser import parse_string
+from execsql.lsp._util import span
 
 __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))
+    return types.Location(uri=uri_for(loc.path, index, uri), range=span(loc.line, loc.start, loc.end))
 
 
 def _at(entries: list[tuple[Location, str]], line: int, character: int) -> str | None:
@@ -55,10 +52,10 @@ def definition(index: ScriptIndex, uri: str, line: int, character: int) -> list[
         return [_lsp_location(index.scripts[script], index, uri)]
 
     target = _at(index.includes, line, character)
-    if target is not None and Path(target).is_file():
+    if target is not None and is_file(target):
         uri_of_file = file_uri(target, index)
         if uri_of_file:
-            return [types.Location(uri=uri_of_file, range=_range(0, 0, 0))]
+            return [types.Location(uri=uri_of_file, range=span(0, 0, 0))]
     return []
 
 
@@ -84,10 +81,10 @@ def document_links(index: ScriptIndex) -> list[types.DocumentLink]:
     links = []
     for loc, target in index.includes:
         path = Path(target)
-        if path.is_file():
+        if is_file(path):
             uri = file_uri(target, index)
             if uri:
-                links.append(types.DocumentLink(range=_range(loc.line, loc.start, loc.end), target=uri))
+                links.append(types.DocumentLink(range=span(loc.line, loc.start, loc.end), target=uri))
     return links