sqlbuild 0.51.0__tar.gz → 0.52.0__tar.gz

sqlbuild-0.52.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.52.0"
+}

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.52.0](https://github.com/chio-labs/sqlbuild/compare/v0.51.0...v0.52.0) (2026-08-21)
+
+
+### Features
+
+* **compiler:** add expansion span models and offset mapping ([9bfbd7b](https://github.com/chio-labs/sqlbuild/commit/9bfbd7b09e986de42b3a0b1dfd29890a58d0e3dc))
+* **compiler:** emit substitution spans from every expansion pass ([1ce9d32](https://github.com/chio-labs/sqlbuild/commit/1ce9d322faf17542fc72c938d78c2851d7f8f25b))
+* **lint:** add sqb lint and sqb format with sqruff and native header rules ([c4e47cd](https://github.com/chio-labs/sqlbuild/commit/c4e47cda9b1e6f6a49eb66be03437633710cb615))
+* **lint:** lint the SQL the project actually produces ([1833273](https://github.com/chio-labs/sqlbuild/commit/18332735d5825a29c3f23e14c442bff9f7f2568f))
+* **lint:** neutralize sqlbuild interpolation with unique sentinels ([e99a4be](https://github.com/chio-labs/sqlbuild/commit/e99a4befbc8e32671d4857f5eccba68d1d3d4bf0))
+* **lint:** reject unsupported sqruff dialects instead of linting silently ([a09157b](https://github.com/chio-labs/sqlbuild/commit/a09157b570aa4978083be85df866f524b60d0ca2))
+* **lint:** translate adapter dialect and scaffold .sqruff on lint/format ([504c425](https://github.com/chio-labs/sqlbuild/commit/504c425c630cda1f7e946f86984a535c9fe464a1))
+
+
+### Bug Fixes
+
+* **lint:** handle scoped declarations and formatting edge cases ([f367ed9](https://github.com/chio-labs/sqlbuild/commit/f367ed98cde77652250a7962af6376c68ba231dc))
+* **lint:** satisfy policy checks for formatting fixes ([76cc7cd](https://github.com/chio-labs/sqlbuild/commit/76cc7cd3269fe9eed3751c51a6ed6c36162f9559))
+* **plan:** render all model change diffs ([f57ac80](https://github.com/chio-labs/sqlbuild/commit/f57ac80d8fe210ae0fa4b0af5ab676ae26adc97c))
+* **plan:** render all model change diffs ([b8ae726](https://github.com/chio-labs/sqlbuild/commit/b8ae726b259005bdbcdb80ddb70ca72a0f2e68bf))
+
 ## [0.51.0](https://github.com/chio-labs/sqlbuild/compare/v0.50.0...v0.51.0) (2026-08-18)
 
 

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlbuild
-Version: 0.51.0
+Version: 0.52.0
 Summary: Typed, test-first SQL pipelines with local E2E testing
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -9,6 +9,7 @@ Requires-Dist: polyglot-sql>=0.5.10
 Requires-Dist: pydantic-settings<3,>=2
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: rich>=15.0.0
+Requires-Dist: sqruff>=0.40.0
 Provides-Extra: bigquery
 Requires-Dist: google-cloud-bigquery>=3.37.0; extra == 'bigquery'
 Provides-Extra: dagster

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/fensu.toml

@@ -189,3 +189,8 @@ reason = "Fensu does not classify tooling rules/ as a role for sibling _helpers
 rule = "FFL101"
 path = "scripts/fensu_policy/rules/orchestration_dataflow.py"
 reason = "Fensu does not classify tooling rules/ as a role for sibling _helpers imports, despite FFR704 requiring that layout."
+
+[[rule_exceptions]]
+rule = "FFL102"
+path = "src/sqlbuild/lint/_helpers/native.py"
+reason = "The lint layer reuses the compiler's MODEL() header parser; the compiler exposes no public facade for it."

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlbuild"
-version = "0.51.0"
+version = "0.52.0"
 description = "Typed, test-first SQL pipelines with local E2E testing"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -14,6 +14,7 @@ dependencies = [
   "pydantic-settings>=2,<3",
   "PyYAML>=6.0.2",
   "rich>=15.0.0",
+  "sqruff>=0.40.0",
 ]
 
 [project.optional-dependencies]

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/cli/commands/_helpers/entry/dispatch.py

@@ -55,19 +55,7 @@ def dispatch_cli_command(*, args: CliNamespace, handlers: CliEntrypointHandlers)
 
     project_dir: Path | None = None if args.project_dir is None else Path(args.project_dir)
     effective_project_dir: Path = project_dir if project_dir is not None else Path.cwd()
-    if args.command is not None and not (
-        args.command == CliCommand.DBT
-        and args.dbt_command != DBT_INIT_COMMAND
-        and not (effective_project_dir / PROJECT_CONFIG_FILENAME).exists()
-    ):
-        _ = configure_diagnostics(
-            target_dir=effective_project_dir / "target",
-            debug=args.debug,
-            use_color=(not args.no_color) and supports_color(),
-        )
-        logging.getLogger("sqlbuild.cli").debug(
-            "command=%s project_dir=%s", args.command, effective_project_dir
-        )
+    _configure_diagnostics(args=args, effective_project_dir=effective_project_dir)
     select: tuple[str, ...] = (*tuple(args.select), *read_selector_files(args.select_file))
     if args.command == CliCommand.COMPILE:
         return handlers.run_compile(
@@ -436,9 +424,44 @@ def dispatch_cli_command(*, args: CliNamespace, handlers: CliEntrypointHandlers)
             project_dir=project_dir,
             select=select,
         )
+    if args.command == CliCommand.LINT or args.command == CliCommand.FORMAT:
+        return _dispatch_lint_format_command(args=args, handlers=handlers, project_dir=project_dir)
     return 0
 
 
+def _configure_diagnostics(*, args: CliNamespace, effective_project_dir: Path) -> None:
+    """Configure diagnostics for commands that run inside a project."""
+
+    if args.command is None or (
+        args.command == CliCommand.DBT
+        and args.dbt_command != DBT_INIT_COMMAND
+        and not (effective_project_dir / PROJECT_CONFIG_FILENAME).exists()
+    ):
+        return
+    _ = configure_diagnostics(
+        target_dir=effective_project_dir / "target",
+        debug=args.debug,
+        use_color=(not args.no_color) and supports_color(),
+    )
+    logging.getLogger("sqlbuild.cli").debug(
+        "command=%s project_dir=%s", args.command, effective_project_dir
+    )
+
+
+def _dispatch_lint_format_command(
+    *,
+    args: CliNamespace,
+    handlers: CliEntrypointHandlers,
+    project_dir: Path | None,
+) -> int:
+    """Route lint and format commands to their handlers."""
+
+    no_sqruff: bool = getattr(args, "no_sqruff", False)
+    if args.command == CliCommand.LINT:
+        return handlers.run_lint(project_dir, no_sqruff=no_sqruff)
+    return handlers.run_format(project_dir, no_sqruff=no_sqruff)
+
+
 def _dispatch_dbt_command(
     *,
     args: CliNamespace,

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/cli/commands/_helpers/entry/parser.py

@@ -209,6 +209,12 @@ def _add_quality_parsers(
     _ = add_vars_args(audit_parser)
     _ = add_dbt_config_args(parser=audit_parser)
 
+    lint_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.LINT)
+    lint_parser.add_argument("--no-sqruff", dest="no_sqruff", action="store_true", default=False)
+
+    format_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.FORMAT)
+    format_parser.add_argument("--no-sqruff", dest="no_sqruff", action="store_true", default=False)
+
 
 def _add_data_parsers(
     subparsers: argparse._SubParsersAction[argparse.ArgumentParser],

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/cli/commands/_helpers/init/scaffold.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from pathlib import Path
 
+from sqlbuild.lint.constants import DEFAULT_SQRUFF_CONFIG_CONTENT
+
 
 def scaffold_blank_project(*, base_dir: Path, project_name: str) -> None:
     """Create the default blank SQLBuild project structure."""
@@ -30,6 +32,10 @@ def scaffold_blank_project(*, base_dir: Path, project_name: str) -> None:
 
     (base_dir / "sqlbuild_project.toml").write_text(_build_project_toml(project_name=project_name))
 
+    sqruff_config: Path = base_dir / ".sqruff"
+    if not sqruff_config.exists():
+        sqruff_config.write_text(DEFAULT_SQRUFF_CONFIG_CONTENT)
+
     for directory in directories:
         gitkeep: Path = base_dir / directory / ".gitkeep"
         if not any((base_dir / directory).iterdir()):

sqlbuild-0.52.0/src/sqlbuild/cli/commands/_helpers/lint/__init__.py

@@ -0,0 +1 @@
+"""Helpers for the lint and format CLI commands."""

sqlbuild-0.52.0/src/sqlbuild/cli/commands/_helpers/lint/runs.py

@@ -0,0 +1,116 @@
+"""Shared helpers for the lint and format CLI commands."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from sqlbuild.lint.constants import (
+    DEFAULT_MAX_DESCRIPTION_LINES,
+    DEFAULT_SQRUFF_CONFIG_PATH,
+    LINT_SECTION_KEY,
+    MAX_DESCRIPTION_LINES_KEY,
+    PROJECT_CONFIG_FILENAME_KEY,
+    SQRUFF_CONFIG_PATH_KEY,
+    SQRUFF_ENABLED_KEY,
+)
+from sqlbuild.lint.main.ensure_config import ensure_sqruff_config
+from sqlbuild.lint.models import LintConfig, LintRunResult
+
+
+def resolve_lint_config(*, project_dir: Path, no_sqruff: bool) -> LintConfig:
+    """Resolve the effective lint config from project settings and CLI flags."""
+
+    sqruff_enabled: bool = not no_sqruff
+    sqruff_config_path: str = DEFAULT_SQRUFF_CONFIG_PATH
+    max_description_lines: int = DEFAULT_MAX_DESCRIPTION_LINES
+    config_file: Path = project_dir / PROJECT_CONFIG_FILENAME_KEY
+    if config_file.is_file():
+        with config_file.open("rb") as handle:
+            payload: dict[str, object] = tomllib.load(handle)
+        lint_section: object = payload.get(LINT_SECTION_KEY)
+        if isinstance(lint_section, dict):
+            sqruff_enabled = _resolve_bool(
+                section=lint_section,
+                key=SQRUFF_ENABLED_KEY,
+                current=sqruff_enabled,
+            )
+            sqruff_config_path = _resolve_str(
+                section=lint_section,
+                key=SQRUFF_CONFIG_PATH_KEY,
+                current=sqruff_config_path,
+            )
+            max_description_lines = _resolve_int(
+                section=lint_section,
+                key=MAX_DESCRIPTION_LINES_KEY,
+                current=max_description_lines,
+            )
+    return LintConfig(
+        sqruff_enabled=sqruff_enabled,
+        sqruff_config_path=sqruff_config_path,
+        max_description_lines=max_description_lines,
+    )
+
+
+def prepare_lint_run(*, project_dir: Path, no_sqruff: bool) -> tuple[LintConfig, str | None]:
+    """Resolve config, scaffold a missing sqruff config, and return any drift warning."""
+
+    config: LintConfig = resolve_lint_config(project_dir=project_dir, no_sqruff=no_sqruff)
+    warning: str | None = ensure_sqruff_config(
+        project_dir=project_dir,
+        config_path=config.sqruff_config_path,
+        sqruff_enabled=config.sqruff_enabled,
+    )
+    return config, warning
+
+
+def render_lint_result(*, result: LintRunResult, show_formatted: bool) -> None:
+    """Print a lint or format run result to stdout."""
+
+    if show_formatted and result.formatted_files:
+        print("Formatted files:")
+        formatted_path: Path
+        for formatted_path in result.formatted_files:
+            print(f"  {formatted_path}")
+        print()
+    if result.violations:
+        _print_violations(result=result)
+    print(
+        f"Completed.  FAULT={len(result.faults)}  WARN={len(result.warnings)}  "
+        f"FILES={result.files_checked}"
+    )
+
+
+def _print_violations(*, result: LintRunResult) -> None:
+    current_file: Path | None = None
+    violation: object
+    for violation in result.violations:
+        if violation.file_path != current_file:
+            current_file = violation.file_path
+            print(f"{current_file}")
+        print(
+            f"  {violation.line}:{violation.column}  "
+            f"{violation.engine}  {violation.code}  {violation.message}"
+        )
+    print()
+
+
+def _resolve_bool(*, section: dict[str, object], key: str, current: bool) -> bool:
+    raw_value: object = section.get(key)
+    if isinstance(raw_value, bool):
+        return current and raw_value
+    return current
+
+
+def _resolve_str(*, section: dict[str, object], key: str, current: str) -> str:
+    raw_value: object = section.get(key)
+    if isinstance(raw_value, str) and raw_value:
+        return raw_value
+    return current
+
+
+def _resolve_int(*, section: dict[str, object], key: str, current: int) -> int:
+    raw_value: object = section.get(key)
+    if isinstance(raw_value, int) and raw_value > 0:
+        return raw_value
+    return current

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/cli/commands/main/entrypoint/entry.py

@@ -21,6 +21,7 @@ from sqlbuild.cli.commands.models import (
 )
 from sqlbuild.compiler.discovery.exceptions import DiscoveryError
 from sqlbuild.integrations.dbt.types import DbtInteropCommand
+from sqlbuild.lint.exceptions import LintError
 from sqlbuild.presentation.main.supports_color import supports_color
 from sqlbuild.virtual.state.exceptions import StateBackendError
 
@@ -46,6 +47,8 @@ def main(argv: Sequence[str] | None = None) -> int:
     from sqlbuild.cli.commands.main.inspection._query import run_query
     from sqlbuild.cli.commands.main.project._compile import run_compile
     from sqlbuild.cli.commands.main.project._dag import run_dag
+    from sqlbuild.cli.commands.main.project._format import run_format_command
+    from sqlbuild.cli.commands.main.project._lint import run_lint_command
     from sqlbuild.cli.commands.main.project._plan import run_plan
     from sqlbuild.cli.commands.main.state._janitor import run_janitor
     from sqlbuild.cli.commands.main.state._promote import run_promote
@@ -169,6 +172,14 @@ def main(argv: Sequence[str] | None = None) -> int:
             targets=targets,
             force=force,
         ),
+        run_lint=lambda project_dir, no_sqruff: run_lint_command(
+            project_dir=project_dir,
+            no_sqruff=no_sqruff,
+        ),
+        run_format=lambda project_dir, no_sqruff: run_format_command(
+            project_dir=project_dir,
+            no_sqruff=no_sqruff,
+        ),
         run_scenario=run_scenario,
         run_scenario_capture=run_scenario_capture,
     )
@@ -200,6 +211,13 @@ def _main_with_dependencies(
             file=sys.stderr,
         )
         return 1
+    except LintError as error:
+        logging.getLogger("sqlbuild.cli").exception("lint failed")
+        print(
+            format_expected_error(error=error, fallback_code="L001", use_color=use_color),
+            file=sys.stderr,
+        )
+        return 1
     except (DiscoveryError, StateBackendError, ValueError) as error:
         logging.getLogger("sqlbuild.cli").exception("command failed")
         print(

sqlbuild-0.52.0/src/sqlbuild/cli/commands/main/project/_format.py

@@ -0,0 +1,23 @@
+"""Run the format command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlbuild.cli.commands._helpers.lint.runs import prepare_lint_run, render_lint_result
+from sqlbuild.lint.main.run_format import run_format
+from sqlbuild.lint.models import LintConfig, LintRunResult
+
+
+def run_format_command(*, project_dir: Path | None, no_sqruff: bool = False) -> int:
+    """Apply autofixes in place; non-zero when faults remain after formatting."""
+
+    base_dir: Path = project_dir if project_dir is not None else Path.cwd()
+    prepared: tuple[LintConfig, str | None] = prepare_lint_run(
+        project_dir=base_dir, no_sqruff=no_sqruff
+    )
+    if prepared[1] is not None:
+        print(f"WARN  {prepared[1]}")
+    result: LintRunResult = run_format(project_dir=base_dir, config=prepared[0])
+    _ = render_lint_result(result=result, show_formatted=True)
+    return 1 if result.violations else 0

sqlbuild-0.52.0/src/sqlbuild/cli/commands/main/project/_lint.py

@@ -0,0 +1,23 @@
+"""Run the lint command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlbuild.cli.commands._helpers.lint.runs import prepare_lint_run, render_lint_result
+from sqlbuild.lint.main.run_lint import run_lint
+from sqlbuild.lint.models import LintConfig, LintRunResult
+
+
+def run_lint_command(*, project_dir: Path | None, no_sqruff: bool = False) -> int:
+    """Report lint violations without modifying authored files; non-zero on violations."""
+
+    base_dir: Path = project_dir if project_dir is not None else Path.cwd()
+    prepared: tuple[LintConfig, str | None] = prepare_lint_run(
+        project_dir=base_dir, no_sqruff=no_sqruff
+    )
+    if prepared[1] is not None:
+        print(f"WARN  {prepared[1]}")
+    result: LintRunResult = run_lint(project_dir=base_dir, config=prepared[0])
+    _ = render_lint_result(result=result, show_formatted=False)
+    return 1 if result.violations else 0

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/cli/commands/models.py

@@ -19,6 +19,7 @@ from sqlbuild.cli.commands.types import (
     DebugCommandHandler,
     FreshnessSourceStatus,
     LineageCommandHandler,
+    LintCommandHandler,
     PlaygroundTemplate,
     QueryCommandHandler,
     ReconcileCommandHandler,
@@ -1235,6 +1236,8 @@ class CliEntrypointHandlers:
     run_init: Callable[[Path | None], int]
     run_playground: Callable[[PlaygroundCommandRequest], int]
     run_skills_update: SkillsUpdateCommandHandler
+    run_lint: LintCommandHandler
+    run_format: LintCommandHandler
     run_scenario: Callable[[ScenarioTestCommandRequest], int]
     run_scenario_capture: Callable[[ScenarioCaptureCommandRequest], int]
 

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/cli/commands/types.py

@@ -50,6 +50,8 @@ class CliCommand(StrEnum):
     SCENARIO = "scenario"
     DBT = "dbt"
     SKILLS = "skills"
+    LINT = "lint"
+    FORMAT = "format"
 
 
 class DagCommandHandler(Protocol):
@@ -148,6 +150,15 @@ class SkillsUpdateCommandHandler(Protocol):
     ) -> int: ...
 
 
+class LintCommandHandler(Protocol):
+    def __call__(
+        self,
+        project_dir: Path | None,
+        *,
+        no_sqruff: bool,
+    ) -> int: ...
+
+
 class FreshnessSourceStatus(StrEnum):
     """Command status for one source freshness observation."""
 

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/cli/output/_helpers/plan_text.py

@@ -1044,7 +1044,7 @@ def _append_query_diff(*, lines: list[str], entry: ModelPlanEntry) -> list[str]:
 
     if entry.previous_query_sql is None:
         return lines
-    if entry.reason != PlanReason.QUERY_CHANGED:
+    if not entry.query_changed:
         return lines
     style: CliStyle = CliStyle(use_color=True)
     lines.append(style.label("    query diff:"))
@@ -1057,7 +1057,7 @@ def _append_query_diff(*, lines: list[str], entry: ModelPlanEntry) -> list[str]:
 def _append_config_diff(*, lines: list[str], entry: ModelPlanEntry) -> list[str]:
     """Append version-identity config diff lines if metadata changed."""
 
-    if entry.reason != PlanReason.CONFIG_CHANGED:
+    if not entry.config_changed:
         return lines
     if entry.previous_metadata_json is None or entry.fingerprint_metadata_json is None:
         return lines

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/compiler/compile/_helpers/render/declarations.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 from sqlbuild.compiler.compile.constants import MACRO_TOKEN, SQL_QUOTE_TOKENS
 from sqlbuild.compiler.compile.exceptions import CompileInputError
+from sqlbuild.compiler.compile.models import ExpansionSpan
 from sqlbuild.compiler.discovery.models import (
     ConstantDeclaration,
     DiscoveredConstantFile,
@@ -85,14 +86,34 @@ def expand_declaration_references(
 ) -> str:
     """Resolve enum-member and constant references to SQL scalar literals."""
 
+    rendered_sql: str
+    rendered_sql, _spans = expand_declaration_references_with_spans(
+        sql=sql, file_path=file_path, enums=enums, constants=constants
+    )
+    return rendered_sql
+
+
+def expand_declaration_references_with_spans(
+    *,
+    sql: str,
+    file_path: Path,
+    enums: dict[str, EnumDeclaration],
+    constants: dict[str, ConstantDeclaration],
+) -> tuple[str, tuple[ExpansionSpan, ...]]:
+    """Resolve declaration references, returning the span of every substitution."""
+
     rendered_parts: list[str] = []
+    spans: list[ExpansionSpan] = []
+    output_length: int = 0
     cursor: int = 0
     while cursor < len(sql):
         reference_start: int | None = _find_next_reference_start(sql=sql, start=cursor)
         if reference_start is None:
             rendered_parts.append(sql[cursor:])
             break
-        rendered_parts.append(sql[cursor:reference_start])
+        leading_literal: str = sql[cursor:reference_start]
+        rendered_parts.append(leading_literal)
+        output_length += len(leading_literal)
         start_match: re.Match[str] | None = _DECLARATION_REFERENCE_START_PATTERN.match(
             sql, reference_start
         )
@@ -116,8 +137,17 @@ def expand_declaration_references(
                 constants=constants,
             )
         rendered_parts.append(replacement)
+        spans.append(
+            ExpansionSpan(
+                source_start=reference_start,
+                source_end=next_cursor,
+                output_start=output_length,
+                output_end=output_length + len(replacement),
+            )
+        )
+        output_length += len(replacement)
         cursor = next_cursor
-    return "".join(rendered_parts)
+    return "".join(rendered_parts), tuple(spans)
 
 
 def resolve_enum_contract_columns(

{sqlbuild-0.51.0 → sqlbuild-0.52.0}/src/sqlbuild/compiler/compile/_helpers/render/macros.py

@@ -21,6 +21,7 @@ from sqlbuild.compiler.compile.constants import (
 )
 from sqlbuild.compiler.compile.exceptions import CompileInputError
 from sqlbuild.compiler.compile.models import (
+    ExpansionSpan,
     LoadedMacro,
     MacroContext,
 )
@@ -79,17 +80,42 @@ def expand_sql_macros(
 ) -> str:
     """Expand authored Python macros in one executable SQL string."""
 
+    expanded_sql: str
+    expanded_sql, _spans = expand_sql_macros_with_spans(
+        sql=sql,
+        file_path=file_path,
+        loaded_macros=loaded_macros,
+        macro_overrides=macro_overrides,
+        macro_context=macro_context,
+    )
+    return expanded_sql
+
+
+def expand_sql_macros_with_spans(
+    *,
+    sql: str,
+    file_path: Path,
+    loaded_macros: dict[str, LoadedMacro],
+    macro_overrides: dict[str, str] | None = None,
+    macro_context: MacroContext,
+) -> tuple[str, tuple[ExpansionSpan, ...]]:
+    """Expand authored Python macros, returning the span of every substitution."""
+
     if MACRO_TOKEN not in sql:
-        return sql
+        return sql, ()
 
     rendered_sql_parts: list[str] = []
+    spans: list[ExpansionSpan] = []
+    output_length: int = 0
     cursor: int = 0
     while cursor < len(sql):
         macro_start_index: int | None = _find_next_macro_start(sql=sql, start_index=cursor)
         if macro_start_index is None:
             rendered_sql_parts.append(sql[cursor:])
             break
-        rendered_sql_parts.append(sql[cursor:macro_start_index])
+        leading_literal: str = sql[cursor:macro_start_index]
+        rendered_sql_parts.append(leading_literal)
+        output_length += len(leading_literal)
         macro_result: object
         next_index: int
         macro_result, next_index = _evaluate_macro_call(
@@ -113,8 +139,17 @@ def expand_sql_macros(
                 f"call '{matched_call.group(0).rstrip()}'. Compose macros in Python instead."
             )
         rendered_sql_parts.append(macro_result)
+        spans.append(
+            ExpansionSpan(
+                source_start=macro_start_index,
+                source_end=next_index,
+                output_start=output_length,
+                output_end=output_length + len(macro_result),
+            )
+        )
+        output_length += len(macro_result)
         cursor = next_index
-    return "".join(rendered_sql_parts)
+    return "".join(rendered_sql_parts), tuple(spans)
 
 
 def find_macro_call_names(sql: str) -> tuple[str, ...]:

sqlbuild-0.52.0/src/sqlbuild/compiler/compile/_helpers/render/spans.py

@@ -0,0 +1,34 @@
+"""Map offsets in rendered SQL back onto the authored text that produced them."""
+
+from __future__ import annotations
+
+from sqlbuild.compiler.compile.models import ExpansionSpan, MappedOffset
+
+
+def map_output_offset(*, offset: int, spans: tuple[ExpansionSpan, ...]) -> MappedOffset:
+    """Resolve one rendered offset through a single expansion pass."""
+
+    mapped: int = offset
+    span: ExpansionSpan
+    for span in spans:
+        if offset < span.output_start:
+            break
+        if offset < span.output_end:
+            return MappedOffset(offset=span.source_start, generated=True)
+        mapped += (span.source_end - span.source_start) - (span.output_end - span.output_start)
+    return MappedOffset(offset=mapped, generated=False)
+
+
+def map_through_passes(
+    *, offset: int, passes: tuple[tuple[ExpansionSpan, ...], ...]
+) -> MappedOffset:
+    """Resolve one rendered offset back through every expansion pass in order."""
+
+    current: int = offset
+    generated: bool = False
+    spans: tuple[ExpansionSpan, ...]
+    for spans in reversed(passes):
+        resolved: MappedOffset = map_output_offset(offset=current, spans=spans)
+        current = resolved.offset
+        generated = generated or resolved.generated
+    return MappedOffset(offset=current, generated=generated)