sqlakit 0.22.3__tar.gz → 0.22.5__tar.gz

{sqlakit-0.22.3 → sqlakit-0.22.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.22.3
+Version: 0.22.5
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov

{sqlakit-0.22.3 → sqlakit-0.22.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.22.3"
+version = "0.22.5"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.22.3 → sqlakit-0.22.5}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.22.3"
+version = "0.22.5"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.22.3 → sqlakit-0.22.5}/sqlakit/_cli.py

@@ -5,18 +5,20 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import shutil
 import sys
 from pathlib import Path
 
 from . import _sql_formatter
-from ._linters import LINTERS, settings, stale
+from ._linters import LINTERS, dialect_of, settings, stale
 from ._project import Problem, Project, load_project
 from ._pycharm import DIALECTS, ddl, dialects
+from ._render import import_macros, rendered, unparsed
 from ._sql import NAMESPACE, registered, signature_of
 from .exceptions import MacroDefinitionError, ProjectConfigError, UnknownImportPathError
 
 
-def main(argv: list[str] | None = None) -> int:
+def main(argv: list[str] | None = None) -> int:  # noqa: PLR0911 - one return a command
     """Run a command, and return what the shell should make of it."""
     parser = argparse.ArgumentParser(prog="sqlakit", description="SQLAKit.")
     commands = parser.add_subparsers(dest="command", required=True)
@@ -52,6 +54,31 @@ def main(argv: list[str] | None = None) -> int:
         help="a directory in the project, the current one by default",
     )
     check.add_argument("--format", choices=("text", "json"), default="text")
+    check.add_argument(
+        "--lint",
+        choices=tuple(LINTERS),
+        help="also render every template, running the project's macros, and "
+        "fail where the linter cannot parse the SQL",
+    )
+    check.add_argument(
+        "--dialect", help="the dialect to render for, in place of the project's"
+    )
+
+    render = commands.add_parser(
+        "render",
+        help="write every template as the SQL it renders, for a linter to read",
+    )
+    render.add_argument(
+        "--out", required=True, help="the directory to write the rendered SQL into"
+    )
+    render.add_argument(
+        "--project",
+        default=".",
+        help="a directory in the project, the current one by default",
+    )
+    render.add_argument(
+        "--dialect", help="the dialect to render for, in place of the project's"
+    )
 
     export = commands.add_parser(
         "export", help="write what another tool needs to read the templates"
@@ -73,7 +100,16 @@ def main(argv: list[str] | None = None) -> int:
 
     arguments = parser.parse_args(argv)
     if arguments.command == "check":
-        return _check(Path(arguments.project), json_output=arguments.format == "json")
+        return _check(
+            Path(arguments.project),
+            json_output=arguments.format == "json",
+            lint=arguments.lint,
+            dialect=arguments.dialect,
+        )
+    if arguments.command == "render":
+        return _render(
+            Path(arguments.project), Path(arguments.out), dialect=arguments.dialect
+        )
     if arguments.command == "export":
         if arguments.tool == "sql-formatter":
             return _export_sql_formatter(
@@ -148,11 +184,14 @@ def _load(directory: Path, *, json_output: bool = False) -> Project | None:
         return None
 
 
-def _check(directory: Path, *, json_output: bool) -> int:
+def _check(
+    directory: Path, *, json_output: bool, lint: str | None, dialect: str | None
+) -> int:
     """Print what is wrong with the project's templates, and fail if anything is.
 
-    The exit is 1 for problems in the templates, and 2 for a project that cannot
-    be read, or holds no template to check.
+    With a linter, every template is rendered too, and what it cannot parse is
+    a problem. The exit is 1 for problems in the templates, and 2 for a project
+    that cannot be read, holds no template to check, or cannot be linted.
     """
     project = _load(directory, json_output=json_output)
     if project is None:
@@ -163,6 +202,12 @@ def _check(directory: Path, *, json_output: bool) -> int:
         _say(json.dumps({"error": message}) if json_output else message)
         return 2
     problems = list(project.problems())
+    if lint is not None:
+        try:
+            problems.extend(_lint(project, lint, dialect))
+        except _CannotRenderError as error:
+            _say(json.dumps({"error": str(error)}) if json_output else str(error))
+            return 2
     if json_output:
         _say(json.dumps([_as_json(problem) for problem in problems], indent=2))
     else:
@@ -180,6 +225,114 @@ def _check(directory: Path, *, json_output: bool) -> int:
     return 1 if problems else 0
 
 
+_WRITTEN = {"given": "every parameter given", "not_given": "no parameter given"}
+
+
+class _CannotRenderError(Exception):
+    """Why the templates cannot be rendered, or the rendering linted."""
+
+
+def _lint(project: Project, name: str, given: str | None) -> list[Problem]:
+    """Return where the linter cannot parse what the templates render.
+
+    Raises:
+        _CannotRenderError: if the linter cannot read the templates as the
+            project is set up.
+
+    """
+    linter = LINTERS[name]
+    if shutil.which(name) is None:
+        problem = f"`{name}` is not installed, so the rendered SQL cannot be linted"
+        raise _CannotRenderError(problem)
+    pyproject = project.root / "pyproject.toml"
+    text = pyproject.read_text(encoding="utf-8") if pyproject.exists() else ""
+    if stale(linter, project, text):
+        problem = (
+            f"the `{name}` settings do not read the templates: run "
+            f"`sqlakit export {name}` first"
+        )
+        raise _CannotRenderError(problem)
+    configured = dialect_of(linter, text)
+    chosen = _dialect_to_render(project, given, configured)
+    if configured is not None and configured != chosen:
+        problem = (
+            f"the templates render on {chosen}, and `{name}` reads {configured}: "
+            f"pass --dialect {configured}, or set the dialect in `[tool.{name}.core]`"
+        )
+        raise _CannotRenderError(problem)
+    try:
+        import_macros(project)
+    except Exception as error:
+        problem = (
+            f"the project's macros cannot be imported: {type(error).__name__}: {error}"
+        )
+        raise _CannotRenderError(problem) from error
+    return unparsed(project, linter, chosen)
+
+
+def _dialect_to_render(
+    project: Project, given: str | None, configured: str | None = None
+) -> str:
+    """Return the dialect to render the templates on.
+
+    `--dialect` wins, then the one the project's database URL names, then the
+    one a linter's settings read in. A macro writes by `ctx.dialect`, so a
+    guess would render SQL the database never gets.
+
+    Raises:
+        _CannotRenderError: if nothing names one.
+
+    """
+    chosen = given or project.dialect or configured
+    if chosen is None:
+        problem = (
+            "the code names no database URL to take the dialect from: pass --dialect"
+        )
+        raise _CannotRenderError(problem)
+    return chosen.lower()
+
+
+def _render(directory: Path, out: Path, *, dialect: str | None) -> int:
+    """Write each template twice, rendered with its parameters given and not.
+
+    The project's Python macros are imported and run, so what they write is
+    in the SQL. Exit 1 when a template cannot be rendered.
+    """
+    project = _load(directory)
+    if project is None:
+        return 2
+    try:
+        import_macros(project)
+    except Exception as error:  # noqa: BLE001 - the project's code raises anything
+        _say(
+            f"the project's macros cannot be imported: {type(error).__name__}: {error}"
+        )
+        return 2
+    try:
+        chosen = _dialect_to_render(project, dialect)
+    except _CannotRenderError as error:
+        _say(str(error))
+        return 2
+    problems = 0
+    count = 0
+    for one in rendered(project, chosen):
+        if one.sql is None:
+            problems += 1
+            _say(f"{one.name} ({one.variant}): {one.problem}")
+            continue
+        target = out / f"{one.name.removesuffix('.sql')}.{one.variant}.sql"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        header = [f"-- {one.name} on {chosen}, {_WRITTEN[one.variant]}"]
+        if one.kept:
+            header.append(
+                f"-- {', '.join(one.kept)} could not be made, and stays a call"
+            )
+        target.write_text("\n".join(header) + "\n" + one.sql, encoding="utf-8")
+        count += 1
+    _say(f"wrote {count} files to {_relative(out)}")
+    return 1 if problems else 0
+
+
 def _export_linter(
     name: str, directory: Path, *, dialect: str | None, check: bool
 ) -> int:

{sqlakit-0.22.3 → sqlakit-0.22.5}/sqlakit/_linters.py

@@ -27,7 +27,7 @@ if TYPE_CHECKING:
 
     from ._project import Project
 
-__all__ = ["LINTERS", "Linter", "settings", "stale"]
+__all__ = ["LINTERS", "Linter", "dialect_of", "parse_errors", "settings", "stale"]
 
 _NEXT_TABLE = re.compile(r"^\[", re.MULTILINE)
 
@@ -47,6 +47,9 @@ class Linter:
     kept: Callable[[str, list[str], str | None], set[int]]
     """Given the executable, the names and the dialect, the index of each name it
     cannot read as a column."""
+    unparsed: Callable[[str, Path, Path], dict[Path, list[tuple[int, int]]]]
+    """Given the executable, a directory of SQL and the project's root, where in
+    each file it could not parse: the line and the column, from one."""
 
     @property
     def placeholder(self) -> str:
@@ -130,6 +133,118 @@ def settings(
     return written_out
 
 
+def dialect_of(linter: Linter, pyproject: str) -> str | None:
+    """Return the dialect the linter's settings read in, by SQLAlchemy's name."""
+    tables = tomllib.loads(pyproject).get("tool", {}).get(linter.name, {})
+    written = tables.get("core", {}).get("dialect")
+    if not isinstance(written, str):
+        return None
+    named = {theirs: ours for ours, theirs in linter.dialects.items()}
+    return named.get(written, written)
+
+
+def parse_errors(
+    linter: Linter, folder: Path, root: Path
+) -> dict[Path, list[tuple[int, int]]]:
+    """Return where the linter could not parse each file of a directory.
+
+    It runs in the project's root, so it reads the project's settings, and an
+    empty result says the linter is not installed.
+    """
+    binary = shutil.which(linter.name)
+    if binary is None:
+        return {}
+    return linter.unparsed(binary, folder, root)
+
+
+_CHEAP_RULE = "LT12"
+"""The one rule a run for parse errors keeps: it reads only a file's end, and a
+linter parses the whole file whatever rules it runs."""
+
+
+def _sqruff_unparsed(
+    binary: str, folder: Path, root: Path
+) -> dict[Path, list[tuple[int, int]]]:
+    pyproject = root / "pyproject.toml"
+    text = pyproject.read_text(encoding="utf-8") if pyproject.exists() else ""
+    tables = tomllib.loads(text).get("tool", {}).get("sqruff", {})
+    core = tables.get("core", {})
+    placeholder = tables.get("templater", {}).get("placeholder", {})
+    # The project's reading of the templates, and none of its rules: sqruff
+    # takes no rules on its command line, so a file of settings of its own.
+    settings = [
+        "[sqruff]",
+        *([f"dialect = {core['dialect']}"] if "dialect" in core else []),
+        f"templater = {core.get('templater', 'placeholder')}",
+        f"rules = {_CHEAP_RULE}",
+        "",
+        "[sqruff:templater:placeholder]",
+        *(f"{name} = {value}" for name, value in placeholder.items()),
+    ]
+    with tempfile.TemporaryDirectory() as scratch:
+        config = Path(scratch, ".sqruff")
+        config.write_text("\n".join(settings) + "\n", encoding="utf-8")
+        found = subprocess.run(  # noqa: S603 - sqruff, found on the PATH
+            [
+                binary,
+                "lint",
+                "--config",
+                str(config),
+                "--parsing-errors",
+                "--format",
+                "json",
+                str(folder),
+            ],
+            capture_output=True,
+            text=True,
+            cwd=root,
+            check=False,
+        )
+    return {
+        Path(path).resolve(): [
+            (problem["range"]["start"]["line"], problem["range"]["start"]["character"])
+            for problem in problems
+            # A problem of parsing has no rule, and so no code.
+            if problem.get("code") is None
+        ]
+        for path, problems in _report(found.stdout, found.stderr, shape=dict).items()
+    }
+
+
+def _sqlfluff_unparsed(
+    binary: str, folder: Path, root: Path
+) -> dict[Path, list[tuple[int, int]]]:
+    found = subprocess.run(  # noqa: S603 - sqlfluff, found on the PATH
+        # A file outside the project reads no setting of it unless told where.
+        [
+            binary,
+            "lint",
+            "--config",
+            str(root / "pyproject.toml"),
+            # Only parse errors count: one cheap rule, run on every core.
+            "--rules",
+            _CHEAP_RULE,
+            "--processes",
+            "-1",
+            "--format",
+            "json",
+            str(folder),
+        ],
+        capture_output=True,
+        text=True,
+        cwd=root,
+        check=False,
+    )
+    return {
+        Path(report["filepath"]).resolve(): [
+            (problem["start_line_no"], problem["start_line_pos"])
+            for problem in report.get("violations", ())
+            if problem.get("code") == "PRS"
+        ]
+        for report in _report(found.stdout, found.stderr, shape=list)
+    }
+
+
 def _dialect(
     linter: Linter, tables: dict, given: str | None, project: Project
 ) -> str | None:
@@ -242,6 +357,7 @@ SQRUFF = Linter(
     # sqruff reads settings without a dialect as ANSI.
     default_dialect=None,
     kept=_sqruff_kept,
+    unparsed=_sqruff_unparsed,
 )
 
 SQLFLUFF = Linter(
@@ -252,6 +368,7 @@ SQLFLUFF = Linter(
     # sqlfluff reads no template without a dialect.
     default_dialect="ansi",
     kept=_sqlfluff_kept,
+    unparsed=_sqlfluff_unparsed,
 )
 
 LINTERS = {linter.name: linter for linter in (SQRUFF, SQLFLUFF)}

sqlakit-0.22.5/sqlakit/_render.py

@@ -0,0 +1,379 @@
+"""Every template of a project, rendered, for a linter to read.
+
+A macro written in Python is SQL only once it runs, so a linter reading the
+templates reads its call and never what it writes. `rendered` runs the macros:
+each template is written twice, once with every parameter given a made-up
+value and once with none, as a macro decides its SQL by what it is given.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import sqlalchemy as sa
+import sqlalchemy.engine.default
+import sqlalchemy.exc
+
+from ._linters import parse_errors
+from ._project import Problem
+from ._sql import _rendered, calls_kept, registered
+from ._static import StaticMacro
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+    from ._linters import Linter
+    from ._project import Project
+
+__all__ = ["Rendered", "import_macros", "rendered", "unparsed"]
+
+VARIANTS = ("given", "not_given")
+"""The two ways each template is written: every parameter given, and none."""
+
+
+class Example:
+    """A made-up value: any path read off it is another, and it writes `x`.
+
+    `:criteria.teams` and `:filters["kind"]` both read one, so a template
+    renders whatever shape its values have.
+    """
+
+    def __getattr__(self, _: str) -> Example:
+        return self
+
+    def __getitem__(self, _: object) -> Example:
+        return self
+
+    def __iter__(self) -> Iterator[Example]:
+        return iter((self,))
+
+    def __len__(self) -> int:
+        return 1
+
+    def __str__(self) -> str:
+        return "x"
+
+
+@dataclass(frozen=True, slots=True)
+class Piece:
+    """The stretch of rendered SQL a macro call wrote, and where the call is."""
+
+    start: int
+    end: int
+    call: str
+    """The call's name under its namespace: `tpl.owned_by`."""
+    span: tuple[int, int]
+    """Where the call is written in the template."""
+
+
+@dataclass(frozen=True, slots=True)
+class Rendered:
+    """A template written one way, or why it could not be."""
+
+    name: str
+    variant: str
+    sql: str | None
+    problem: str | None = None
+    kept: tuple[str, ...] = ()
+    """The macro calls that could not be made, and stay calls in the SQL."""
+    pieces: tuple[Piece, ...] = ()
+    """What each call of the template itself wrote, in order."""
+    read: bool = True
+    """Whether the template could be read: `sqlakit check` says why not."""
+
+    def written_by(self, offset: int) -> Piece | None:
+        """Return the call that wrote the SQL at an offset, if a call did."""
+        return next(
+            (piece for piece in self.pieces if piece.start <= offset < piece.end), None
+        )
+
+
+def import_macros(project: Project) -> None:
+    """Import the modules of the project's Python macros, in place of their reading.
+
+    `load_project` reads the macros from their source, so a call to one is
+    checked and never made. The modules are imported the way the code names
+    them, from the directory above their package.
+
+    Raises:
+        Exception: whatever importing the project's code raises.
+
+    """
+    macros = project.templates.macros
+    modules = {
+        macro.path for macro in macros.values() if isinstance(macro, StaticMacro)
+    }
+    for path in sorted(modules):
+        folder, name = _module(path)
+        if str(folder) not in sys.path:
+            sys.path.insert(0, str(folder))
+        found = registered([name])
+        macros.update(
+            (key, macro)
+            for key, macro in found.items()
+            if isinstance(macros.get(key), StaticMacro)
+        )
+
+
+def rendered(project: Project, dialect: str) -> Iterator[Rendered]:
+    """Yield each template of the project, written each way."""
+    preparer = _preparer(dialect)
+    namespace = project.templates.namespace
+    for name in project.templates.names():
+        path = project.path_of(name)
+        if path is None:
+            continue
+        source = path.read_text(encoding="utf-8")
+        try:
+            template = project.load(name, source)
+        except Exception as error:  # noqa: BLE001 - `sqlakit check` says more
+            for variant in VARIANTS:
+                yield Rendered(name, variant, None, str(error), read=False)
+            continue
+        calls = list(_calls(template.parts))
+        refused = _refused(project, name, source, calls, preparer)
+        for variant in VARIANTS:
+            given = variant == "given"
+            values: dict[str, Any] = {
+                param: Example() if given and param not in refused else None
+                for param in template.parameters()
+            }
+            try:
+                with calls_kept():
+                    sql, _ = _rendered(
+                        template, {"dialect": dialect, **values}, preparer
+                    )
+            except Exception as error:  # noqa: BLE001 - the project's macros raise anything
+                yield Rendered(name, variant, None, f"{type(error).__name__}: {error}")
+                continue
+            kept = tuple(
+                sorted(
+                    {
+                        f"{namespace}.{call.name}"
+                        for call in calls
+                        if re.search(
+                            rf"(?<![\w.]){re.escape(namespace)}\.{re.escape(call.name)}\s*\(",
+                            sql,
+                            re.IGNORECASE,
+                        )
+                    }
+                )
+            )
+            sql = sql.strip() + "\n"
+            pieces = _pieces(
+                project,
+                name,
+                source,
+                parts=template.parts,
+                values=values,
+                preparer=preparer,
+                sql=sql,
+            )
+            yield Rendered(name, variant, sql, kept=kept, pieces=pieces)
+
+
+def _pieces(  # noqa: PLR0913 - the template, and what it was rendered with
+    project: Project,
+    name: str,
+    source: str,
+    *,
+    parts: Sequence[Any],
+    values: dict[str, Any],
+    preparer: Any,  # noqa: ANN401
+    sql: str,
+) -> tuple[Piece, ...]:
+    """Return what each call of the template wrote, found in the whole SQL.
+
+    Each call is rendered alone with the same values, and looked for after the
+    one before it.
+    """
+    namespace = project.templates.namespace
+    dialect = getattr(preparer.dialect, "name", "")
+    found = []
+    after = 0
+    for call in parts:
+        if isinstance(call, str):
+            continue
+        try:
+            alone = project.load(name, source[call.span[0] : call.span[1]])
+            with calls_kept():
+                text, _ = _rendered(
+                    alone,
+                    {
+                        "dialect": dialect,
+                        **{param: values.get(param) for param in alone.parameters()},
+                    },
+                    preparer,
+                )
+        except Exception:  # noqa: BLE001, S112 - a call that fails alone has no piece
+            continue
+        text = text.strip()
+        start = sql.find(text, after) if text else -1
+        if start < 0:
+            continue
+        after = start + len(text)
+        found.append(Piece(start, after, f"{namespace}.{call.name}", call.span))
+    return tuple(found)
+
+
+_WAYS = {"given": "with every parameter given", "not_given": "with none given"}
+
+
+def unparsed(project: Project, linter: Linter, dialect: str) -> list[Problem]:
+    """Return where the linter cannot parse what the templates render.
+
+    Each template is rendered each way, and the SQL the linter cannot parse is
+    put on the call that wrote it. SQL the template writes itself is put on
+    its line, found by its text. A template that cannot be rendered is a
+    problem too.
+    """
+    written = list(rendered(project, dialect))
+    with tempfile.TemporaryDirectory() as folder:
+        # The two ways often write the same SQL, which is read once.
+        files: dict[Path, list[Rendered]] = {}
+        by_text: dict[tuple[str, str], Path] = {}
+        for one in written:
+            if one.sql is None:
+                continue
+            file = by_text.get((one.name, one.sql))
+            if file is None:
+                file = Path(folder, f"{len(by_text)}.sql").resolve()
+                file.write_text(one.sql, encoding="utf-8")
+                by_text[one.name, one.sql] = file
+            files.setdefault(file, []).append(one)
+        errors = parse_errors(linter, Path(folder).resolve(), project.root)
+    found: dict[tuple[Path, int, int, str], list[str]] = {}
+    for one in written:
+        path = project.path_of(one.name)
+        if path is None or one.sql is not None or not one.read:
+            continue
+        key = (path, 0, 0, f"cannot be rendered {{}}: {one.problem}")
+        found.setdefault(key, []).append(_WAYS[one.variant])
+    for file, places in errors.items():
+        for one in files.get(file, ()):
+            _place(project, linter, one, places, found)
+    return [
+        Problem(path, start, end, message.format(" and ".join(ways)))
+        for (path, start, end, message), ways in found.items()
+    ]
+
+
+def _place(
+    project: Project,
+    linter: Linter,
+    one: Rendered,
+    places: list[tuple[int, int]],
+    found: dict[tuple[Path, int, int, str], list[str]],
+) -> None:
+    """Put each place the linter could not parse on the call that wrote it."""
+    path = project.path_of(one.name)
+    if path is None or one.sql is None:
+        return
+    source = path.read_text(encoding="utf-8")
+    starts = [0, *(index + 1 for index, char in enumerate(one.sql) if char == "\n")]
+    for line, column in places:
+        offset = starts[min(line, len(starts)) - 1] + column - 1
+        written = one.sql[starts[line - 1] :].split("\n", 1)[0]
+        text = written.strip()
+        # The line the linter stopped on, and a caret under where it stopped.
+        indent = len(written) - len(written.lstrip())
+        shown = f"\n    {text}\n    {' ' * max(column - 1 - indent, 0)}^"
+        piece = one.written_by(offset)
+        if piece is not None:
+            message = f"{piece.call} writes SQL {linter.name} cannot parse, {{}}{shown}"
+            key = (path, *piece.span, message)
+        else:
+            at = source.find(text) if text else -1
+            start = max(at, 0)
+            message = f"{linter.name} cannot parse the rendered SQL, {{}}{shown}"
+            key = (path, start, start + len(text), message)
+        ways = found.setdefault(key, [])
+        if _WAYS[one.variant] not in ways:
+            ways.append(_WAYS[one.variant])
+
+
+def _refused(
+    project: Project,
+    name: str,
+    source: str,
+    calls: Sequence[Any],
+    preparer: Any,  # noqa: ANN401
+) -> set[str]:
+    """Return the parameters a macro refuses made up, and takes when not given.
+
+    `tpl.order_by` takes a sort that names one of its columns, and nothing
+    made up does, so `:sort` counts as not given when the rest are.
+    """
+    found: set[str] = set()
+    namespace = project.templates.namespace
+    dialect = getattr(preparer.dialect, "name", "")
+    for call in calls:
+        text = source[call.span[0] : call.span[1]]
+        try:
+            alone = project.load(name, text)
+        except Exception:  # noqa: BLE001, S112 - the whole template says what is wrong
+            continue
+        names = alone.parameters()
+        if not names:
+            continue
+        written = []
+        for value in (Example(), None):
+            try:
+                with calls_kept():
+                    sql, _ = _rendered(
+                        alone,
+                        {"dialect": dialect, **dict.fromkeys(names, value)},
+                        preparer,
+                    )
+            except Exception:  # noqa: BLE001 - a macro may refuse either
+                sql = None
+            written.append(sql)
+        made_up, missing = (
+            sql is None
+            or bool(
+                re.match(
+                    rf"{re.escape(namespace)}\.{re.escape(call.name)}\s*\(",
+                    sql.strip(),
+                    re.IGNORECASE,
+                )
+            )
+            for sql in written
+        )
+        if made_up and not missing:
+            found.update(names)
+    return found
+
+
+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 _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 - SQLAlchemy's IdentifierPreparer
+    """Return how a dialect quotes names, loaded without a driver or a server."""
+    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