sqlakit-lsp 0.2.0__tar.gz → 0.3.1__tar.gz

{sqlakit_lsp-0.2.0 → sqlakit_lsp-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit-lsp
-Version: 0.2.0
+Version: 0.3.1
 Summary: The language server for SQLAKit templates.
 Keywords: sqlalchemy,sqlakit,lsp,language-server,sql
 Author: Anton Ruhlov
@@ -36,10 +36,13 @@ templates. In a `.sql` template:
 - on hover, the SQL a call writes, above the macro's signature and docstring
 - go to definition, implementation and references of a macro or a template
 - rename of a macro or a template across the project
+- go to definition of a `:parameter`, to each call of Python that passes it,
+  and on hover, the value each call passes
 - the macros' calls and the parameters coloured
 - a parameter no call of the project passes, marked, with a quick fix for a
   name close to one the calls pass
-- **Show rendered SQL**, the whole template as the SQL it writes
+- **Show rendered SQL**, the whole template as the SQL it writes, with `:name`
+  or with `?` for each parameter
 - the outline of a template, and a search for a macro or a template
 
 In Python, the template name in `db.sql("...")` completes and links to its

{sqlakit_lsp-0.2.0 → sqlakit_lsp-0.3.1}/README.md

@@ -9,10 +9,13 @@ templates. In a `.sql` template:
 - on hover, the SQL a call writes, above the macro's signature and docstring
 - go to definition, implementation and references of a macro or a template
 - rename of a macro or a template across the project
+- go to definition of a `:parameter`, to each call of Python that passes it,
+  and on hover, the value each call passes
 - the macros' calls and the parameters coloured
 - a parameter no call of the project passes, marked, with a quick fix for a
   name close to one the calls pass
-- **Show rendered SQL**, the whole template as the SQL it writes
+- **Show rendered SQL**, the whole template as the SQL it writes, with `:name`
+  or with `?` for each parameter
 - the outline of a template, and a search for a macro or a template
 
 In Python, the template name in `db.sql("...")` completes and links to its

{sqlakit_lsp-0.2.0 → sqlakit_lsp-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit-lsp"
-version = "0.2.0"
+version = "0.3.1"
 description = "The language server for SQLAKit templates."
 readme = "README.md"
 license = "MIT"

{sqlakit_lsp-0.2.0 → sqlakit_lsp-0.3.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit-lsp"
-version = "0.2.0"
+version = "0.3.1"
 description = "The language server for SQLAKit templates."
 readme = "README.md"
 license = "MIT"

sqlakit_lsp-0.3.1/sqlakit_lsp/_live.py

@@ -0,0 +1,92 @@
+"""Render a template with the project's own macros, in the project's Python.
+
+The server reads the project's code and never runs it, so a macro written in
+Python stays a call when it renders a template. **Show rendered SQL** asks for
+more: the server runs this file with the project's interpreter, which imports
+the modules of those macros, and prints the SQL as JSON.
+
+It reads its request as JSON on stdin, and imports nothing of the server: the
+project's environment has `sqlakit`, and not the server.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+class _Example:
+    """A value to render a template with: any path reads another of it."""
+
+    def __getattr__(self, _: str) -> _Example:
+        return self
+
+    def __getitem__(self, _: object) -> _Example:
+        return self
+
+    def __iter__(self) -> Any:  # noqa: ANN401
+        return iter((self,))
+
+    def __len__(self) -> int:
+        return 1
+
+    def __str__(self) -> str:
+        return "x"
+
+
+def _module(path: Path) -> tuple[Path, str]:
+    """Return the directory a module is imported from, and its dotted name."""
+    parts = [path.stem]
+    folder = path.parent
+    while (folder / "__init__.py").is_file():
+        parts.append(folder.name)
+        folder = folder.parent
+    return folder, ".".join(reversed(parts))
+
+
+def _preparer(dialect: str) -> Any:  # noqa: ANN401
+    import sqlalchemy as sa  # noqa: PLC0415
+    import sqlalchemy.engine.default  # noqa: PLC0415
+    import sqlalchemy.exc  # noqa: PLC0415
+
+    try:
+        return sa.engine.make_url(f"{dialect}://").get_dialect()().identifier_preparer
+    except sa.exc.NoSuchModuleError:
+        default = sa.engine.default.DefaultDialect()
+        default.name = dialect
+        return default.identifier_preparer
+
+
+def main() -> None:
+    request = json.load(sys.stdin)
+    from sqlakit._project import load_project  # noqa: PLC0415
+    from sqlakit._sql import Context, calls_kept, registered  # noqa: PLC0415
+
+    project = load_project(Path(request["root"]))
+    for file in request["modules"]:
+        folder, name = _module(Path(file))
+        if str(folder) not in sys.path:
+            sys.path.insert(0, str(folder))
+        try:
+            found = registered([name])
+        except Exception as error:  # noqa: BLE001 - the project's code raises anything
+            sys.stdout.write(
+                json.dumps({"error": f"{name} cannot be imported: {error}"}) + "\n"
+            )
+            return
+        project.templates.macros.update(
+            (key, macro) for key, macro in found.items() if key in request["macros"]
+        )
+    template = project.load(request["name"], request["source"])
+    values: dict[str, Any] = dict.fromkeys(template.parameters(), _Example())
+    values.update(dict.fromkeys(request["not_given"]))
+    dialect = request["dialect"]
+    with calls_kept():
+        sql = template.render(Context(dialect, _preparer(dialect), values)).strip()
+    sys.stdout.write(json.dumps({"sql": sql}) + "\n")
+
+
+if __name__ == "__main__":
+    main()

{sqlakit_lsp-0.2.0 → sqlakit_lsp-0.3.1}/sqlakit_lsp/_server.py

@@ -23,8 +23,10 @@ import asyncio
 import bisect
 import difflib
 import inspect
+import json
 import os
 import re
+import subprocess
 import tempfile
 import uuid
 from collections import OrderedDict
@@ -141,6 +143,8 @@ class Target:
     path: Path
     line: int
     column: int = 0
+    length: int = 0
+    """How many characters of the line the place spans: a name to select."""
 
 
 def _innermost(parts: Sequence[Any], offset: int) -> Any:  # noqa: ANN401
@@ -155,6 +159,66 @@ def _innermost(parts: Sequence[Any], offset: int) -> Any:  # noqa: ANN401
     return None
 
 
+_BOUND = re.compile(
+    rf"{_LITERAL}|(?<![:\w\\]):(?P<bound>[A-Za-z_]\w*)(?![\w:])", re.DOTALL
+)
+"""A placeholder of rendered SQL, and the strings and comments to skip."""
+
+_LIVE = Path(__file__).with_name("_live.py")
+"""The script the project's interpreter renders a template with."""
+
+_LIVE_SECONDS = 20
+"""How long a render with the project's macros may take: it imports them."""
+
+
+def _interpreter(root: Path) -> Path | None:
+    """Return the Python of the project's `.venv`, if it has one."""
+    for found in (
+        root / ".venv" / "bin" / "python",
+        root / ".venv" / "Scripts" / "python.exe",
+    ):
+        if found.is_file():
+            return found
+    return None
+
+
+def _run_live(root: Path, request: dict[str, Any]) -> tuple[str | None, str]:
+    """Render a template in the project's interpreter: the SQL, or why not."""
+    python = _interpreter(root)
+    if python is None:
+        return None, "the project has no .venv to run its macros in."
+    try:
+        done = subprocess.run(  # noqa: S603 - the project's own interpreter
+            [str(python), str(_LIVE)],
+            input=json.dumps(request),
+            capture_output=True,
+            text=True,
+            cwd=root,
+            timeout=_LIVE_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        return None, f"running {_relative(python, root)} failed: {error}"
+    try:
+        answer = json.loads(done.stdout.strip().splitlines()[-1])
+    except (IndexError, ValueError):
+        last = (done.stderr.strip().splitlines() or ["no output"])[-1]
+        return None, f"{_relative(python, root)} failed: {last}"
+    if "sql" in answer:
+        return answer["sql"], ""
+    return None, str(answer.get("error", "no SQL came back"))
+
+
+def _calls(parts: Sequence[Any]) -> Iterator[Any]:
+    """Yield every macro call of a read template, the ones in arguments too."""
+    for part in parts:
+        if isinstance(part, str):
+            continue
+        yield part
+        for argument in part.args:
+            yield from _calls(argument.parts)
+
+
 def _rendered(template: Any, dialect: str, values: dict[str, Any]) -> str | None:  # noqa: ANN401
     """Return the SQL a read template writes for these values, if it can.
 
@@ -285,6 +349,22 @@ class Reference:
     end: int
 
 
+@dataclass(frozen=True, slots=True)
+class Passing:
+    """A call of Python that passes a template's parameter."""
+
+    path: Path
+    line: int
+    start: int
+    end: int
+    """Where the value is: its keyword, or the code that passes values the call
+    does not name, `values` in `**values`."""
+    code: str
+    """What the call writes, `page_size=limit` or `**values`."""
+    named: bool = True
+    """Whether the call names the parameter, and does not only may pass it."""
+
+
 def _read(path: Path) -> str:
     return path.read_text(encoding="utf-8", errors="replace")
 
@@ -309,6 +389,9 @@ _WORD = re.compile(r"\w+")
 SHOW = "Show rendered SQL"
 """The title of the action that shows a whole template as SQL."""
 
+SHOW_MARKED = "Show rendered SQL with ?"
+"""The title of the action that shows it with `?` for each parameter."""
+
 RENDER = "sqlakit.render"
 """The command that writes a whole template as SQL, for an editor to open."""
 
@@ -578,6 +661,21 @@ class _Assistant:
         """
         if name in self._passed:
             return self._passed[name]
+        calls = [call for _, call in self._calls_reading(name)]
+        passed = (
+            None
+            if not calls or any(call.open for call in calls)
+            else frozenset(keyword.name for call in calls for keyword in call.keywords)
+        )
+        self._passed[name] = passed
+        return passed
+
+    def _calls_reading(self, name: str) -> list[tuple[Path, _TemplateCall]]:
+        """Return the calls of Python that read a template, and their files.
+
+        A call that reads a template that includes it, however deep, reads it
+        too.
+        """
         included_by = self._included_by()
         readers, waiting = {name}, [name]
         while waiting:
@@ -585,19 +683,12 @@ class _Assistant:
                 if including not in readers:
                     readers.add(including)
                     waiting.append(including)
-        calls = [
-            call
+        return [
+            (path, call)
             for path in self._project_files()[1]
-            for reader in readers
+            for reader in sorted(readers)
             for call in self._scan(path, None).calls.get(reader, ())
         ]
-        passed = (
-            None
-            if not calls or any(call.open for call in calls)
-            else frozenset(keyword for call in calls for keyword, _, _ in call.keywords)
-        )
-        self._passed[name] = passed
-        return passed
 
     def _included_by(self) -> dict[str, set[str]]:
         """Return, for each template, the templates that include it."""
@@ -789,7 +880,13 @@ class _Assistant:
         """Return the whole template as the database gets it, on the project's dialect.
 
         Every parameter counts as given, so every optional part is there, and
-        stays a placeholder. A call that cannot be made so stays a call.
+        stays a placeholder. A parameter a built-in macro cannot take made up,
+        the column `tpl.order_by` sorts by, counts as not given.
+
+        The server reads the project's Python macros and does not run them, so
+        when the template calls one, it is rendered again by the project's own
+        interpreter, `.venv/bin/python`, which imports them. Without one, or
+        when that fails, the calls stay calls, and a comment on top says why.
         """
         name = self.project.name_of(path) or path.name
         dialect = self.project.dialect or "postgresql"
@@ -797,11 +894,90 @@ class _Assistant:
             template = self.compiled(name, source)
         except SQLAKitError as error:
             return f"-- {name} cannot be read: {error}\n"
-        values = dict.fromkeys(template.parameters(), _Example())
+        calls = list(_calls(template.parts))
+        values: dict[str, Any] = dict.fromkeys(template.parameters(), _Example())
+        values.update(dict.fromkeys(self._not_given(name, source, calls, dialect)))
         sql = _rendered(template, dialect, values)
         if sql is None:
             return f"-- {name} cannot be written with made-up values.\n"
-        return f"-- {name} on {dialect}\n{sql}\n"
+        namespace = self.project.templates.namespace
+        # A call of an included template is in the SQL too, and not in `calls`.
+        static = {
+            key: macro
+            for key, macro in self.project.templates.macros.items()
+            if isinstance(macro, StaticMacro)
+        }
+        kept = {
+            key: macro
+            for key, macro in static.items()
+            if re.search(rf"(?<![\w.]){namespace}\.{key}\s*\(", sql, re.IGNORECASE)
+        }
+        if not kept:
+            return f"-- {name} on {dialect}\n{sql}\n"
+        request = {
+            "root": str(self.project.root),
+            "name": name,
+            "source": source,
+            "dialect": dialect,
+            # Every one, as a macro may call another inside, as a file macro's SQL does.
+            "modules": sorted({str(macro.path) for macro in static.values()}),
+            "macros": sorted(static),
+            "not_given": sorted(key for key, value in values.items() if value is None),
+        }
+        run, problem = _run_live(self.project.root, request)
+        if run is not None:
+            return f"-- {name} on {dialect}\n{run}\n"
+        listed = ", ".join(f"{namespace}.{key}" for key in sorted(kept))
+        return f"-- {name} on {dialect}\n-- {listed} stays a call: {problem}\n{sql}\n"
+
+    def rendered_marked(self, path: Path, source: str) -> str:
+        """Return the rendered template with `?` for each parameter, in order.
+
+        A comment on top lists what each `?` stands for, as a driver that
+        takes `?` is given the values in that order.
+        """
+        text = self.rendered(path, source)
+        names: list[str] = []
+
+        def marked(found: re.Match[str]) -> str:
+            name = found.group("bound")
+            if name is None:
+                return found.group(0)
+            names.append(name)
+            return "?"
+
+        text = _BOUND.sub(marked, text)
+        if not names:
+            return text
+        first, _, rest = text.partition("\n")
+        listed = ", ".join(f":{name}" for name in names)
+        return f"{first}\n-- ? in order: {listed}\n{rest}"
+
+    def _not_given(
+        self, name: str, source: str, calls: Sequence[Any], dialect: str
+    ) -> set[str]:
+        """Return the parameters to render as not given.
+
+        They are those of a call of a built-in macro that cannot be made with a
+        made-up value, and can with none: `:sort` of `tpl.order_by`, whose value
+        must be a column it lists.
+        """
+        found: set[str] = set()
+        for call in calls:
+            if isinstance(self.project.templates.macros.get(call.name), StaticMacro):
+                continue
+            text = source[call.span[0] : call.span[1]]
+            try:
+                alone = self.compiled(name, text)
+            except SQLAKitError:
+                continue
+            names = alone.parameters()
+            given = _rendered(alone, dialect, dict.fromkeys(names, _Example()))
+            if names and given in (None, text.strip()):
+                missing = _rendered(alone, dialect, dict.fromkeys(names))
+                if missing not in (None, text.strip()):
+                    found.update(names)
+        return found
 
     def holds_macros(self, path: Path) -> bool:
         """Whether a file defines macros: SQL macros, or the SQL of a file macro."""
@@ -900,23 +1076,37 @@ class _Assistant:
 
     def passes(
         self, name: str, param: str
-    ) -> tuple[list[tuple[Path, int]], list[tuple[Path, int]]]:
+    ) -> tuple[list[Passing], list[tuple[Path, int]]]:
         """Return the calls of Python that pass a template's parameter, and not.
 
-        Each is a file and a line. A call that passes values it does not name,
-        `**values` or a context, counts as one that may pass it.
+        A call that does not pass it is a file and a line. A call that passes
+        values it does not name, `**values` or a context, counts as one that
+        may pass it. The calls of a template that includes this one count too.
         """
         passing, silent = [], []
-        for path in self._project_files()[1]:
-            for call in self._scan(path, None).calls.get(name, ()):
-                named = {keyword for keyword, _, _ in call.keywords}
-                where = (path, call.line)
-                (passing if call.open or param in named else silent).append(where)
+        for path, call in self._calls_reading(name):
+            keyword = next((one for one in call.keywords if one.name == param), None)
+            if keyword is not None:
+                code = f"{param}={keyword.value}"
+                passing.append(
+                    Passing(path, keyword.line, keyword.start, keyword.end, code)
+                )
+            elif call.open:
+                passing.extend(
+                    Passing(path, one.line, one.start, one.end, one.value, named=False)
+                    for one in call.unnamed
+                )
+            else:
+                silent.append((path, call.line))
         return passing, silent
 
-    def parameter_hover(self, path: Path, source: str, offset: int) -> str | None:
-        """Return which calls pass the parameter under the offset, and which not."""
+    def _parameter_at(
+        self, path: Path, source: str, offset: int
+    ) -> tuple[str, re.Match[str]] | None:
+        """Return the template and the `:parameter` under the offset."""
         name = self.project.name_of(path)
+        if name is None:
+            return None
         found = next(
             (
                 match
@@ -925,15 +1115,23 @@ class _Assistant:
             ),
             None,
         )
-        if name is None or found is None:
+        return None if found is None else (name, found)
+
+    def parameter_hover(self, path: Path, source: str, offset: int) -> str | None:
+        """Return which calls pass the parameter under the offset, what, and which not."""
+        at = self._parameter_at(path, source, offset)
+        if at is None:
             return None
+        name, found = at
         param = found.group(1)
         passing, silent = self.passes(name, param)
         root = self.project.root
 
-        def listed(places: list[tuple[Path, int]]) -> str:
+        def listed(places: Sequence[tuple[Path, int, str | None]]) -> str:
             shown = [
-                f"- `{_relative(path, root)}:{line}`" for path, line in places[:_LISTED]
+                f"- `{_relative(path, root)}:{line}`"
+                + ("" if code is None else f" `{code}`")
+                for path, line, code in places[:_LISTED]
             ]
             if len(places) > _LISTED:
                 shown.append(f"- and {len(places) - _LISTED} more")
@@ -941,13 +1139,41 @@ class _Assistant:
 
         parts = [f"`:{param}` of `{name}`"]
         if passing:
-            parts.append(f"Passed by {len(passing)}:\n\n{listed(passing)}")
+            given = [(one.path, one.line, one.code) for one in passing]
+            parts.append(f"Passed by {len(passing)}:\n\n{listed(given)}")
         if silent:
-            parts.append(f"Not passed by {len(silent)}:\n\n{listed(silent)}")
+            missing = [(path, line, None) for path, line in silent]
+            parts.append(f"Not passed by {len(silent)}:\n\n{listed(missing)}")
         if not passing and not silent:
             parts.append("No call in the project's Python reads this template.")
         return "\n\n".join(parts)
 
+    def parameter_definitions(
+        self, path: Path, source: str, offset: int
+    ) -> list[Target]:
+        """Return where the Python passes the parameter under the offset.
+
+        That is the keyword of each call that names it. Only when none does, it
+        is the code of the calls that pass values they do not name: `values` in
+        `**values`, or a context that is not written out.
+        """
+        at = self._parameter_at(path, source, offset)
+        if at is None:
+            return []
+        name, found = at
+        passing = self.passes(name, found.group(1))[0]
+        named = [one for one in passing if one.named]
+        texts: dict[Path, str] = {}
+        targets = []
+        for one in named or passing:
+            text = texts.get(one.path)
+            if text is None:
+                text = texts[one.path] = _read(one.path)
+            line = text.count("\n", 0, one.start)
+            column = one.start - (text.rfind("\n", 0, one.start) + 1)
+            targets.append(Target(one.path, line, column, one.end - one.start))
+        return targets
+
     def signature(self, source: str, offset: int) -> Signature | None:
         """Return the macro whose arguments the offset is in, and which one it is."""
         start = max(0, source.rfind("\n\n", 0, offset))
@@ -1064,6 +1290,9 @@ class _Assistant:
         for match in self._name_at.finditer(source, start, end):
             if match.start() <= offset <= match.end():
                 return match.span()
+        for match in _PARAMETERS.finditer(source, start, end):
+            if match.start() <= offset <= match.end():
+                return match.span()
         return defined
 
     def reads_python(self, path: Path) -> bool:
@@ -1098,12 +1327,13 @@ class _Assistant:
             listed = ", ".join(f"`{name}`" for name in sorted(reads)) or "nothing"
             found.extend(
                 Diagnostic(
-                    start,
-                    end,
-                    f"`{name}` is not a parameter of `{call.name}`, which reads {listed}.",
+                    keyword.start,
+                    keyword.end,
+                    f"`{keyword.name}` is not a parameter of `{call.name}`, "
+                    f"which reads {listed}.",
                 )
-                for name, start, end in call.keywords
-                if name not in reads
+                for keyword in call.keywords
+                if keyword.name not in reads
             )
         return found
 
@@ -1543,23 +1773,69 @@ _ARGUMENT_TYPED = re.compile(
 _PASSED = re.compile(r"(\w+)\s*=")
 
 
+_SHOWN = 60
+"""The most characters of a value's code a hover shows."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Keyword:
+    """A value a call passes by name, where the name is written, and its code."""
+
+    name: str
+    start: int
+    end: int
+    value: str
+    line: int
+
+
 @dataclass(frozen=True, slots=True)
 class _TemplateCall:
     """A call that reads a template, and the values it passes by name."""
 
     name: str
-    keywords: tuple[tuple[str, int, int], ...]
-    """Each keyword's name, and where it is written."""
+    keywords: tuple[_Keyword, ...]
+    """Each keyword, and where it is written."""
     open: bool
     """Whether it passes values the code does not name: `**values` or a context."""
     line: int = 1
     span: tuple[int, int] | None = None
     """Where the template's name is written, without its quotes."""
+    unnamed: tuple[_Keyword, ...] = ()
+    """The code that passes values it does not name: where `values` of
+    `**values` is, and all of it written, or a context's."""
+
+
+def _unnamed(node: ast.expr, written: str, source: str, starts: list[int]) -> _Keyword:
+    """Return code that passes values it does not name, as a keyword with no name."""
+    start = _char_offset(source, starts, node.lineno, node.col_offset)
+    end = _char_offset(
+        source,
+        starts,
+        node.end_lineno or node.lineno,
+        node.end_col_offset or node.col_offset,
+    )
+    code = _code(node, source, starts)
+    # The name the editor selects: the value, or the start of a long one.
+    end = end if source.count("\n", start, end) == 0 else source.find("\n", start)
+    return _Keyword("", start, end, written.format(code), node.lineno)
+
+
+def _code(node: ast.expr, source: str, starts: list[int]) -> str:
+    """Return the code of an expression on one line, cut short when it is long."""
+    start = _char_offset(source, starts, node.lineno, node.col_offset)
+    end = _char_offset(
+        source,
+        starts,
+        node.end_lineno or node.lineno,
+        node.end_col_offset or node.col_offset,
+    )
+    text = " ".join(source[start:end].split())
+    return text if len(text) <= _SHOWN else f"{text[: _SHOWN - 1]}…"
 
 
 def _named_keys(
     node: ast.expr, source: str, starts: list[int]
-) -> list[tuple[str, int, int]] | None:
+) -> list[_Keyword] | None:
     """Return the keys of a dict written out, and where each is, or None.
 
     None is a context the code does not write out: a name, a call, or a dict
@@ -1568,11 +1844,19 @@ def _named_keys(
     if not isinstance(node, ast.Dict) or any(key is None for key in node.keys):
         return None
     found = []
-    for key in node.keys:
+    for key, value in zip(node.keys, node.values, strict=True):
         if not (isinstance(key, ast.Constant) and isinstance(key.value, str)):
             return None
         start = _char_offset(source, starts, key.lineno, key.col_offset) + 1
-        found.append((key.value, start, start + len(key.value)))
+        found.append(
+            _Keyword(
+                key.value,
+                start,
+                start + len(key.value),
+                _code(value, source, starts),
+                key.lineno,
+            )
+        )
     return found
 
 
@@ -1611,7 +1895,15 @@ def _template_calls(source: str) -> list[_TemplateCall]:
             if keyword.arg is None or keyword.arg == "context":
                 continue
             start = _char_offset(source, starts, keyword.lineno, keyword.col_offset)
-            keywords.append((keyword.arg, start, start + len(keyword.arg)))
+            keywords.append(
+                _Keyword(
+                    keyword.arg,
+                    start,
+                    start + len(keyword.arg),
+                    _code(keyword.value, source, starts),
+                    keyword.lineno,
+                )
+            )
         # A context written out as a dict names its values as keywords do.
         contexts = [
             *node.args[1:2],
@@ -1620,6 +1912,28 @@ def _template_calls(source: str) -> list[_TemplateCall]:
         written = [_named_keys(context, source, starts) for context in contexts]
         for keys in written:
             keywords.extend(keys or ())
+        unnamed = [
+            *(
+                _unnamed(context, "{}", source, starts)
+                for context, keys in zip(node.args[1:2], written, strict=False)
+                if keys is None
+            ),
+            *(
+                _unnamed(keyword.value, "context={}", source, starts)
+                for keyword, keys in zip(
+                    [one for one in node.keywords if one.arg == "context"],
+                    written[len(node.args[1:2]) :],
+                    strict=True,
+                )
+                if keys is None
+            ),
+            *(_unnamed(one, "{}", source, starts) for one in node.args[2:]),
+            *(
+                _unnamed(keyword.value, "**{}", source, starts)
+                for keyword in node.keywords
+                if keyword.arg is None
+            ),
+        ]
         named = node.args[0]
         value = str(named.value) if isinstance(named, ast.Constant) else ""
         span = None
@@ -1630,13 +1944,7 @@ def _template_calls(source: str) -> list[_TemplateCall]:
             span = None if quote < 0 else (quote, quote + len(value))
         found.append(
             _TemplateCall(
-                value,
-                tuple(keywords),
-                any(keys is None for keys in written)
-                or len(node.args) > 2  # noqa: PLR2004 - the name and a context
-                or any(keyword.arg is None for keyword in node.keywords),
-                node.lineno,
-                span,
+                value, tuple(keywords), bool(unnamed), node.lineno, span, tuple(unnamed)
             )
         )
     return found
@@ -2113,26 +2421,40 @@ def _server() -> Any:  # noqa: ANN401, C901, PLR0915 - a handler for each reques
         if found is None:
             return None
         path = _path(params.text_document.uri)
-        target = (
-            found.helper.python_definition(found.source, found.offset, path)
+        if found.python:
+            target = found.helper.python_definition(found.source, found.offset, path)
+        else:
+            target = found.helper.definition(found.source, found.offset, path)
+        # A parameter is defined where the Python passes it, by each call.
+        targets = (
+            [target]
+            if target is not None
+            else []
             if found.python
-            else found.helper.definition(found.source, found.offset, path)
+            else found.helper.parameter_definitions(path, found.source, found.offset)
         )
-        if target is None:
+        if not targets:
             return None
-        start = types.Position(target.line, _utf16_column(target))
-        uri, place = target.path.resolve().as_uri(), types.Range(start, start)
+        places = []
+        for one in targets:
+            start, end = _utf16_columns(one)
+            place = types.Range(
+                types.Position(one.line, start), types.Position(one.line, end)
+            )
+            places.append((one.path.resolve().as_uri(), place))
         span = found.helper.origin(
             found.source, found.offset, python=found.python, path=path
         )
         if span is None or not links_supported(ls):
-            return types.Location(uri, place)
+            if len(places) == 1:
+                return types.Location(*places[0])
+            return [types.Location(uri, place) for uri, place in places]
         # A link carries the span it starts from, which the editor underlines.
         origin = types.Range(
             types.Position(*position_of(found.source, span[0])),
             types.Position(*position_of(found.source, span[1])),
         )
-        return [types.LocationLink(uri, place, place, origin)]
+        return [types.LocationLink(uri, place, place, origin) for uri, place in places]
 
     def links_supported(ls: LanguageServer) -> bool:
         """Whether the editor takes a definition as a link with the span it starts from."""
@@ -2282,21 +2604,30 @@ def _server() -> Any:  # noqa: ANN401, C901, PLR0915 - a handler for each reques
         support = None if action is None else action.resolve_support
         return bool(support is not None and "edit" in support.properties)
 
-    def rendered_file(ls: LanguageServer, uri: str) -> tuple[Path, str]:
+    def rendered_file(
+        ls: LanguageServer, uri: str, *, marked: bool = False
+    ) -> tuple[Path, str]:
         """Return a new file for the rendered template, and what goes in it."""
         helper = assistant()
         path = _path(uri)
         source = ls.workspace.get_text_document(uri).source
         name = helper.project.name_of(path) or path.name if helper else path.name
-        text = helper.rendered(path, source) if helper else ""
+        if helper is None:
+            text = ""
+        elif marked:
+            text = helper.rendered_marked(path, source)
+        else:
+            text = helper.rendered(path, source)
         # A new file each time: the editor may still hold the one before.
         written = _RENDERED / uuid.uuid4().hex[:8] / name
         written.parent.mkdir(parents=True, exist_ok=True)
         return written, text
 
-    def rendered_edit(ls: LanguageServer, uri: str) -> types.WorkspaceEdit:
+    def rendered_edit(
+        ls: LanguageServer, uri: str, *, marked: bool = False
+    ) -> types.WorkspaceEdit:
         """Return an edit that makes the file of the rendered template."""
-        written, text = rendered_file(ls, uri)
+        written, text = rendered_file(ls, uri, marked=marked)
         target = written.as_uri()
         start = types.Position(0, 0)
         return types.WorkspaceEdit(
@@ -2330,14 +2661,18 @@ def _server() -> Any:  # noqa: ANN401, C901, PLR0915 - a handler for each reques
             return actions or None
         if not path.name.endswith(".sql"):
             return actions or None
-        action = types.CodeAction(title=SHOW, kind=types.CodeActionKind.Empty)
-        if shows_documents(ls):
-            action.command = types.Command(title=SHOW, command=RENDER, arguments=[uri])
-        elif resolves_edits(ls):
-            action.data = {"uri": uri}
-        else:
-            action.edit = rendered_edit(ls, uri)
-        return [*actions, action]
+        for title, marked in ((SHOW, False), (SHOW_MARKED, True)):
+            action = types.CodeAction(title=title, kind=types.CodeActionKind.Empty)
+            if shows_documents(ls):
+                action.command = types.Command(
+                    title=title, command=RENDER, arguments=[uri, marked]
+                )
+            elif resolves_edits(ls):
+                action.data = {"uri": uri, "marked": marked}
+            else:
+                action.edit = rendered_edit(ls, uri, marked=marked)
+            actions.append(action)
+        return actions
 
     def fixes(ls: LanguageServer, params: Any) -> list[types.CodeAction]:  # noqa: ANN401
         """Return a quick fix for each problem of ours the editor sends along.
@@ -2380,13 +2715,15 @@ def _server() -> Any:  # noqa: ANN401, C901, PLR0915 - a handler for each reques
         """Work out the edit of an action once the editor has chosen it."""
         data = action.data or {}
         if "uri" in data:
-            action.edit = rendered_edit(ls, data["uri"])
+            action.edit = rendered_edit(
+                ls, data["uri"], marked=bool(data.get("marked"))
+            )
         return action
 
     @server.command(RENDER)
-    async def render(ls: LanguageServer, uri: str) -> None:
+    async def render(ls: LanguageServer, uri: str, marked: bool = False) -> None:  # noqa: FBT001, FBT002 - a command's arguments come in order
         """Write the rendered template to a file, and have the editor open it."""
-        written, text = rendered_file(ls, uri)
+        written, text = rendered_file(ls, uri, marked=marked)
         written.write_text(text, encoding="utf-8")
         await ls.window_show_document_async(
             types.ShowDocumentParams(written.as_uri(), take_focus=True)
@@ -2499,13 +2836,24 @@ def _server() -> Any:  # noqa: ANN401, C901, PLR0915 - a handler for each reques
 
 def _utf16_column(target: Target) -> int:
     """Return a target's column in the UTF-16 units the protocol counts in."""
-    if not target.column:
-        return 0
+    return _utf16_columns(target)[0]
+
+
+def _utf16_columns(target: Target) -> tuple[int, int]:
+    """Return where a target starts and ends on its line, in UTF-16 units."""
+    end = target.column + target.length
+    if not end:
+        return 0, 0
     try:
         line = _lines(target.path, target.path.stat().st_mtime_ns)[target.line]
     except (OSError, IndexError):
-        return target.column
-    return len(line[: target.column].encode("utf-16-le")) // 2
+        return target.column, end
+    if line.isascii():
+        return target.column, end
+    units = [
+        len(line[:column].encode("utf-16-le")) // 2 for column in (target.column, end)
+    ]
+    return units[0], units[1]
 
 
 @lru_cache(maxsize=64)