sqlbuild 0.121.0__tar.gz → 0.122.0__tar.gz

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/Cargo.lock

@@ -599,7 +599,7 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "sqlbuild-rules-native"
-version = "0.121.0"
+version = "0.122.0"
 dependencies = [
  "fensu-policy",
  "globset",

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.121.0
+Version: 0.122.0
 Requires-Dist: duckdb>=1.3.2
 Requires-Dist: filelock>=3.20.3
 Requires-Dist: orjson>=3.10.0
@@ -49,10 +49,10 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
   <a href="https://sqlbuild.com/docs/roadmap/">Roadmap</a>
 </p>
 
-Change your warehouse as often as your code. SQLBuild brings compile-time checks, tests and diffs to
-your SQL, so change is safe. It is a free, open-source framework for SQL and Python data pipelines,
-and it keeps its state in append-only tables in your own warehouse: no external state database, no
-manifest files and no paid tier.
+Change your warehouse as often as your code. SQLBuild brings compile-time checks, tests and safe
+renames to your SQL, so change stops being risky. It is a free, open-source framework for SQL and
+Python data pipelines, and it keeps its state in append-only tables in your own warehouse: no
+external state database, no manifest files and no paid tier.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/chio-labs/sqlbuild/main/.github/demos/rename.gif" alt="Moving and renaming an incremental model: sqb plan migrates the existing table instead of rebuilding it" width="100%">

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/README.md

@@ -13,10 +13,10 @@
   <a href="https://sqlbuild.com/docs/roadmap/">Roadmap</a>
 </p>
 
-Change your warehouse as often as your code. SQLBuild brings compile-time checks, tests and diffs to
-your SQL, so change is safe. It is a free, open-source framework for SQL and Python data pipelines,
-and it keeps its state in append-only tables in your own warehouse: no external state database, no
-manifest files and no paid tier.
+Change your warehouse as often as your code. SQLBuild brings compile-time checks, tests and safe
+renames to your SQL, so change stops being risky. It is a free, open-source framework for SQL and
+Python data pipelines, and it keeps its state in append-only tables in your own warehouse: no
+external state database, no manifest files and no paid tier.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/chio-labs/sqlbuild/main/.github/demos/rename.gif" alt="Moving and renaming an incremental model: sqb plan migrates the existing table instead of rebuilding it" width="100%">

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/crates/sqlbuild-rules-native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlbuild-rules-native"
-version = "0.121.0"
+version = "0.122.0"
 edition.workspace = true
 license.workspace = true
 publish.workspace = true

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/crates/sqlbuild-rules-native/src/constants.rs

@@ -1,5 +1,5 @@
 pub(crate) const API_VERSION: u32 = 1;
-pub(crate) const SCOPE_METADATA_SCHEMA_VERSION: u32 = 2;
+pub(crate) const SCOPE_METADATA_SCHEMA_VERSION: u32 = 3;
 pub(crate) const BUILT_IN_RULE_NAMESPACE: &str = "SQBR";
 pub(crate) const PIPELINE_SUBJECT: &str = "pipeline";
 pub(crate) const GENERIC_TEST_NAME: &str = "test";

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/crates/sqlbuild-rules-native/src/engine/tests/helpers.rs

@@ -116,7 +116,7 @@ pub(crate) fn threshold_request(
 
 pub(crate) fn scope_index() -> Value {
     json!({
-        "schema_version": 2,
+        "schema_version": 3,
         "ownership_roots": [{"path": "models", "resource_kind": "model"}],
         "resources": [{
             "identity": "model:orders",

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/crates/sqlbuild-rules-native/src/models.rs

@@ -259,10 +259,9 @@ pub(crate) enum ResourceKind {
     Model,
     Test,
     Scenario,
-    Hook,
     Function,
-    Audit,
     Source,
+    Seed,
 }
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
@@ -271,6 +270,11 @@ pub(crate) enum DeclarationKind {
     Macro,
     Enum,
     Constant,
+    Audit,
+    SingularAudit,
+    Schema,
+    SqlHook,
+    PythonHook,
 }
 
 #[derive(Clone, Debug, Deserialize, Serialize)]

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/crates/sqlbuild-rules-native/src/rules/_helpers/domain_layout.rs

@@ -595,6 +595,11 @@ fn container_limit(evaluation: &ProjectEvaluationRequest<'_>, kind: &Declaration
         DeclarationKind::Macro => "max_macro_container_files",
         DeclarationKind::Constant => "max_constant_container_files",
         DeclarationKind::Enum => "max_enum_container_files",
+        DeclarationKind::Audit
+        | DeclarationKind::SingularAudit
+        | DeclarationKind::Schema
+        | DeclarationKind::SqlHook
+        | DeclarationKind::PythonHook => return DEFAULT_MAX_CONTAINER_FILES,
     };
     threshold(evaluation, name, DEFAULT_MAX_CONTAINER_FILES)
 }

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlbuild"
-version = "0.121.0"
+version = "0.122.0"
 description = "Typed, test-first SQL pipelines with local E2E testing"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/src/sqlbuild/cli/commands/_helpers/entry/parser.py

@@ -26,6 +26,7 @@ from sqlbuild.cli.commands.constants import (
 from sqlbuild.cli.commands.types import CliCommand, CompileLineageMode
 from sqlbuild.compiler.contract_adoption.types import ContractAction
 from sqlbuild.compiler.lineage.types import ColumnLineageMode
+from sqlbuild.compiler.scopes.types import DeclarationKind
 
 
 def _installed_version() -> str:
@@ -441,7 +442,7 @@ def _add_inspection_parsers(
         "--kind",
         dest="scope_kind",
         action="append",
-        choices=("macro", "enum", "constant"),
+        choices=tuple(kind.value for kind in DeclarationKind),
         default=[],
     )
     scope_parser.add_argument("--match", dest="scope_match", default=None, metavar="GLOB")

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/src/sqlbuild/cli/commands/_helpers/playground/templates/waffle_shop/seeds/lookups.yml

@@ -4,6 +4,9 @@ seeds:
     columns:
       - name: waffle_type_id
         type: INTEGER
+        audits:
+          - not_null
+          - unique
       - name: waffle_name
         type: VARCHAR
       - name: category

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/src/sqlbuild/cli/commands/classes/build_progress_callbacks.py

@@ -1134,6 +1134,39 @@ def _format_failure_details(*, result: BuildExecutionResult, style: CliStyle) ->
             )
         lines.append("")
 
+    lines.extend(_format_audit_error_details(result=result, style=style, has_failures=has_failures))
+    return lines
+
+
+def _format_audit_error_details(
+    *, result: BuildExecutionResult, style: CliStyle, has_failures: bool
+) -> list[str]:
+    lines: list[str] = []
+    audit_result: AuditExecutionResult
+    for audit_result in (*result.source_audit_results, *result.end_audit_results):
+        if audit_result.execution_error is None:
+            continue
+        if not has_failures:
+            lines.append("")
+            lines.append(style.error_strong("Failures:"))
+            lines.append("")
+            has_failures = True
+        target: str = (
+            f" on {audit_result.attached_target_name}"
+            if audit_result.attached_target_name is not None
+            else ""
+        )
+        lines.append(f"  {audit_result.audit_name}{target}  (audit)")
+        lines.extend(
+            _format_failure_error_block(
+                error_code=None,
+                error_message=audit_result.execution_error,
+                error_help=None,
+                style=style,
+            )
+        )
+        lines.append("")
+
     return lines
 
 

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/src/sqlbuild/cli/output/_helpers/execution_result_document.py

@@ -987,6 +987,7 @@ def _format_audit_checks(
                     if result.evaluation_mode == AuditEvaluationMode.MEASUREMENT
                     else None
                 ),
+                "execution_error": result.execution_error,
             }
         )
         for result in results

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/src/sqlbuild/compiler/auditing/types.py

@@ -17,6 +17,7 @@ class AuditRunScope(StrEnum):
 
 class AuditAttachmentKind(StrEnum):
     SOURCE = "source"
+    SEED = "seed"
     MODEL = "model"
     END = "end"
 

sqlbuild-0.122.0/src/sqlbuild/compiler/compile/_helpers/assembly/audit_gates.py

@@ -0,0 +1,42 @@
+"""Compile validation for attached audits that gate their target."""
+
+from __future__ import annotations
+
+from sqlbuild.compiler.compile.constants import ATTACHED_AUDIT_READS_OWN_DEPENDANT_CODE
+from sqlbuild.compiler.compile.exceptions import CompileInputError
+from sqlbuild.compiler.compile.models import CompiledObjectKey, CompiledProject
+from sqlbuild.compiler.compile.types import CompiledResourceType
+from sqlbuild.compiler.graph.main._attached_audit_gate_cycle import attached_audit_gate_cycle
+from sqlbuild.compiler.graph.models import AttachedAuditGateEdge
+
+_RESOURCE_LABELS: dict[CompiledResourceType, str] = {
+    CompiledResourceType.MODEL: "model",
+    CompiledResourceType.SOURCE: "source",
+    CompiledResourceType.SEED: "seed",
+    CompiledResourceType.UDF: "function",
+    CompiledResourceType.TABLE_FN: "table function",
+}
+
+
+def validate_attached_audit_gates(*, project: CompiledProject) -> None:
+    """Reject attached audits that would wait for a resource built from their own target."""
+
+    cycle: AttachedAuditGateEdge | None = attached_audit_gate_cycle(project=project)
+    if cycle is None:
+        return
+    target: str = _describe(cycle.target)
+    read: str = _describe(cycle.read)
+    raise CompileInputError(
+        f"Audit '{cycle.audit_name}' on {target} reads {read}, which depends on "
+        f"'{cycle.target.name}'; an attached audit gates its target, so it cannot wait for a "
+        "resource built from that target",
+        code=ATTACHED_AUDIT_READS_OWN_DEPENDANT_CODE,
+        help=(
+            f"write a singular audit under audits/singular/ that references both "
+            f"'{cycle.target.name}' and '{cycle.read.name}'; it runs once both are built"
+        ),
+    )
+
+
+def _describe(key: CompiledObjectKey) -> str:
+    return f"{_RESOURCE_LABELS[CompiledResourceType(key.resource_type)]} '{key.name}'"

{sqlbuild-0.121.0 → sqlbuild-0.122.0}/src/sqlbuild/compiler/compile/_helpers/attachment/audits.py

@@ -21,24 +21,25 @@ from sqlbuild.compiler.compile._helpers.attachment.references import (
     build_known_source_names,
     validate_audit_references,
 )
+from sqlbuild.compiler.compile._helpers.named_declarations.core import (
+    declaration_file_expansion,
+    named_declaration_usages,
+)
 from sqlbuild.compiler.compile._helpers.refs.references import extract_sql_references
 from sqlbuild.compiler.compile._helpers.render.arguments import (
     render_parameterized_sql,
 )
 from sqlbuild.compiler.compile._helpers.render.cursor_intrinsics import reject_cursor_intrinsics
-from sqlbuild.compiler.compile._helpers.render.declarations import resolve_declaration_expansion
 from sqlbuild.compiler.compile._helpers.render.sql_vars import (
     expand_authored_sql_result,
 )
-from sqlbuild.compiler.compile.constants import (
-    AUDIT_DIRECTORY_NAME,
-    GENERIC_AUDIT_DIRECTORY_NAME,
-)
+from sqlbuild.compiler.compile.constants import SINGULAR_AUDIT_NOT_CROSS_RESOURCE_CODE
 from sqlbuild.compiler.compile.exceptions import CompileInputError
 from sqlbuild.compiler.compile.models import (
     AuthoredSqlExpansionResult,
     CompileAuditInput,
     CompileModelInput,
+    CompileSeedInput,
     CompileSourceInput,
     CompileSqlReference,
     DeclarationExpansionContext,
@@ -54,8 +55,12 @@ from sqlbuild.compiler.discovery.models import (
     DiscoveredProjectInputs,
 )
 from sqlbuild.compiler.references.types import SqlReferenceKind
-from sqlbuild.compiler.scopes.models import ResourceIdentity
-from sqlbuild.compiler.scopes.types import ResourceKind
+from sqlbuild.compiler.scopes.models import (
+    DeclarationIdentity,
+    ResourceIdentity,
+    UsageRecord,
+)
+from sqlbuild.compiler.scopes.types import DeclarationKind, ResourceKind
 from sqlbuild.spec.contracts.models import (
     SchemaAuditInstance,
     SchemaColumn,
@@ -63,6 +68,16 @@ from sqlbuild.spec.contracts.models import (
     SourceColumnEntry,
 )
 
+_CROSS_MODEL_MINIMUM: int = 2
+
+
+@dataclass(frozen=True)
+class _AuditConsumer:
+    """The resource that attaches a generic audit, used for scope visibility and placement."""
+
+    identity: ResourceIdentity
+    path: Path
+
 
 @dataclass(frozen=True)
 class _AuditAttachmentContext:
@@ -78,14 +93,14 @@ class _AuditAttachmentContext:
     effective_vars: dict[str, object]
     macro_context: MacroContext
     declaration_expansion: DeclarationExpansionContext
-    scoped_declarations: dict[tuple[Path, ResourceIdentity], DeclarationExpansionContext] = field(
-        default_factory=dict, compare=False, repr=False
+    scoped_declarations: dict[tuple[Path, DeclarationIdentity], DeclarationExpansionContext] = (
+        field(default_factory=dict, compare=False, repr=False)
     )
 
     def remember_scoped_declarations(
         self,
         *,
-        key: tuple[Path, ResourceIdentity],
+        key: tuple[Path, DeclarationIdentity],
         declarations: DeclarationExpansionContext,
     ) -> None:
         """Retain one resolved audit scope for reuse in this compile invocation."""
@@ -105,6 +120,7 @@ def build_audit_inputs(
     declaration_expansion: DeclarationExpansionContext,
     generic_audit_definitions: dict[str, tuple[DiscoveredAuditFile, DiscoveredAuditBlock]]
     | None = None,
+    seed_inputs: tuple[CompileSeedInput, ...] = (),
 ) -> tuple[CompileAuditInput, ...]:
     """Build compile-time audit inputs from discovered SQL audit blocks."""
 
@@ -134,14 +150,14 @@ def build_audit_inputs(
             continue
         audit_block: DiscoveredAuditBlock
         for audit_block in audit_file.blocks:
-            audit_resource: ResourceIdentity = ResourceIdentity(
-                ResourceKind.AUDIT,
+            audit_identity: DeclarationIdentity = DeclarationIdentity(
+                DeclarationKind.SINGULAR_AUDIT,
                 audit_block.name or audit_file.relative_path.stem,
             )
             scoped_declarations: DeclarationExpansionContext = _scoped_audit_declarations(
                 context=attachment_context,
                 file_path=audit_file.file_path,
-                resource=audit_resource,
+                consumer=audit_identity,
             )
             expansion: AuthoredSqlExpansionResult = expand_authored_sql_result(
                 sql=audit_block.sql_body,
@@ -189,6 +205,11 @@ def build_audit_inputs(
                 known_seed_names=known_seed_names,
                 known_source_names=known_source_names,
             )
+            referenced_resources: tuple[ResourceIdentity, ...] = singular_audit_resources(
+                references=references,
+                audit_file=audit_file,
+                audit_name=audit_identity.name,
+            )
             header_severity: str | None = _str_from_dict(
                 values=audit_block.header_values, key="severity"
             )
@@ -254,6 +275,10 @@ def build_audit_inputs(
                     declaration_usages=(
                         expansion.usages
                         + (() if evidence_expansion is None else evidence_expansion.usages)
+                        + tuple(
+                            UsageRecord(consumer=resource, declaration=audit_identity)
+                            for resource in referenced_resources
+                        )
                     ),
                 )
             )
@@ -275,6 +300,11 @@ def build_audit_inputs(
                 context=attachment_context,
             )
         )
+    seed_input: CompileSeedInput
+    for seed_input in seed_inputs:
+        audit_inputs.extend(
+            build_seed_attached_audit_inputs(seed_input=seed_input, context=attachment_context)
+        )
     return tuple(audit_inputs)
 
 
@@ -295,6 +325,10 @@ def build_model_attached_audit_inputs(
         if model_input.schema_file is not None
         else model_input.model_file.relative_path
     )
+    model_consumer: _AuditConsumer = _AuditConsumer(
+        identity=ResourceIdentity(ResourceKind.MODEL, model_input.model_file.file_path.stem),
+        path=model_input.model_file.relative_path,
+    )
     attached_audit_inputs: list[CompileAuditInput] = []
     audit_instance: SchemaAuditInstance
     for audit_instance in model_input.schema_entry.audits:
@@ -316,6 +350,7 @@ def build_model_attached_audit_inputs(
                 attached_target_name=model_input.model_file.file_path.stem,
                 attached_column_name=attached_column_name,
                 context=context,
+                consumer=model_consumer,
             )
         )
     column_entry: SchemaColumn
@@ -345,6 +380,7 @@ def build_model_attached_audit_inputs(
                     attached_target_name=model_input.model_file.file_path.stem,
                     attached_column_name=column_entry.name,
                     context=context,
+                    consumer=model_consumer,
                 )
             )
     return tuple(attached_audit_inputs)
@@ -357,6 +393,10 @@ def build_source_attached_audit_inputs(
 ) -> tuple[CompileAuditInput, ...]:
     """Render source-attached audits into compile audit inputs."""
 
+    source_consumer: _AuditConsumer = _AuditConsumer(
+        identity=ResourceIdentity(ResourceKind.SOURCE, source_input.source_entry.name),
+        path=source_input.source_file.relative_path,
+    )
     attached_audit_inputs: list[CompileAuditInput] = []
     audit_instance: SchemaAuditInstance
     for audit_instance in source_input.source_entry.audits:
@@ -375,6 +415,7 @@ def build_source_attached_audit_inputs(
                 attached_target_name=source_input.source_entry.name,
                 attached_column_name=None,
                 context=context,
+                consumer=source_consumer,
             )
         )
     column_entry: SourceColumnEntry
@@ -396,11 +437,59 @@ def build_source_attached_audit_inputs(
                     attached_target_name=source_input.source_entry.name,
                     attached_column_name=column_entry.name,
                     context=context,
+                    consumer=source_consumer,
                 )
             )
     return tuple(attached_audit_inputs)
 
 
+def build_seed_attached_audit_inputs(
+    *,
+    seed_input: CompileSeedInput,
+    context: _AuditAttachmentContext,
+) -> tuple[CompileAuditInput, ...]:
+    """Render seed-attached table and column audits into compile audit inputs."""
+
+    seed_name: str = seed_input.schema_entry.name
+    seed_consumer: _AuditConsumer = _AuditConsumer(
+        identity=ResourceIdentity(ResourceKind.SEED, seed_name),
+        path=seed_input.seed_file.relative_path,
+    )
+    implicit_arguments: dict[str, object] = {
+        "seed": seed_name,
+        "relation": SqlReferenceKind.SEED.example_call(seed_name, quote='"'),
+    }
+    attached_audit_inputs: list[CompileAuditInput] = [
+        build_attached_audit_input(
+            audit_instance=audit_instance,
+            owner_file=seed_input.schema_file.relative_path,
+            implicit_arguments=implicit_arguments,
+            attached_target_kind=AttachedAuditTargetKind.SEED,
+            attached_target_name=seed_name,
+            attached_column_name=_explicit_audit_column_name(audit_instance=audit_instance),
+            context=context,
+            consumer=seed_consumer,
+        )
+        for audit_instance in seed_input.schema_entry.audits
+    ]
+    column_entry: SchemaColumn
+    for column_entry in seed_input.schema_entry.columns:
+        attached_audit_inputs.extend(
+            build_attached_audit_input(
+                audit_instance=audit_instance,
+                owner_file=seed_input.schema_file.relative_path,
+                implicit_arguments={**implicit_arguments, "column": column_entry.name},
+                attached_target_kind=AttachedAuditTargetKind.SEED,
+                attached_target_name=seed_name,
+                attached_column_name=column_entry.name,
+                context=context,
+                consumer=seed_consumer,
+            )
+            for audit_instance in column_entry.audits
+        )
+    return tuple(attached_audit_inputs)
+
+
 def _explicit_audit_column_name(
     *,
     audit_instance: SchemaAuditInstance,
@@ -410,16 +499,16 @@ def _explicit_audit_column_name(
 
 
 def _scoped_audit_declarations(
-    *, context: _AuditAttachmentContext, file_path: Path, resource: ResourceIdentity
+    *, context: _AuditAttachmentContext, file_path: Path, consumer: DeclarationIdentity
 ) -> DeclarationExpansionContext:
-    key: tuple[Path, ResourceIdentity] = (file_path, resource)
+    key: tuple[Path, DeclarationIdentity] = (file_path, consumer)
     cached: DeclarationExpansionContext | None = context.scoped_declarations.get(key)
     if cached is not None:
         return cached
-    resolved: DeclarationExpansionContext = resolve_declaration_expansion(
+    resolved: DeclarationExpansionContext = declaration_file_expansion(
         context=context.declaration_expansion,
         file_path=file_path,
-        resource=resource,
+        consumer=consumer,
     )
     context.remember_scoped_declarations(key=key, declarations=resolved)
     return resolved
@@ -434,6 +523,7 @@ def build_attached_audit_input(
     attached_target_name: str,
     attached_column_name: str | None,
     context: _AuditAttachmentContext,
+    consumer: _AuditConsumer,
 ) -> CompileAuditInput:
     """Render one attached generic audit instance into a compile audit input."""
 
@@ -444,6 +534,13 @@ def build_attached_audit_input(
         raise CompileInputError(
             f"{owner_file} references unknown generic audit '{audit_instance.definition_name}'"
         )
+    attachment_usages: tuple[UsageRecord, ...] = named_declaration_usages(
+        resolver=context.declaration_expansion.resolver,
+        kind=DeclarationKind.AUDIT,
+        name=audit_instance.definition_name,
+        consumer=consumer.identity,
+        consumer_path=consumer.path,
+    )
     evaluation_mode: AuditEvaluationMode = definition[1].evaluation_mode
     if evaluation_mode == AuditEvaluationMode.MEASUREMENT:
         if audit_instance.severity is not None:
@@ -481,14 +578,10 @@ def build_attached_audit_input(
             owner_file=owner_file,
             definition_name=audit_instance.definition_name,
         )
-    audit_resource: ResourceIdentity = ResourceIdentity(
-        ResourceKind.AUDIT,
-        definition[1].name or definition[0].relative_path.stem,
-    )
     scoped_declarations: DeclarationExpansionContext = _scoped_audit_declarations(
         context=context,
         file_path=definition[0].file_path,
-        resource=audit_resource,
+        consumer=DeclarationIdentity(DeclarationKind.AUDIT, audit_instance.definition_name),
     )
     expansion: AuthoredSqlExpansionResult = expand_authored_sql_result(
         sql=rendered_sql_body,
@@ -579,7 +672,9 @@ def build_attached_audit_input(
         run_scope=resolved_run_scope,
         always_run=audit_instance.always_run,
         declaration_usages=(
-            expansion.usages + (() if evidence_expansion is None else evidence_expansion.usages)
+            attachment_usages
+            + expansion.usages
+            + (() if evidence_expansion is None else evidence_expansion.usages)
         ),
     )
 
@@ -587,7 +682,7 @@ def build_attached_audit_input(
 def index_generic_audit_definitions(
     audit_files: tuple[DiscoveredAuditFile, ...],
 ) -> dict[str, tuple[DiscoveredAuditFile, DiscoveredAuditBlock]]:
-    """Index generic audit definitions discovered under audits/generic/."""
+    """Index project-wide and scoped generic audit definitions by name."""
 
     definitions: dict[str, tuple[DiscoveredAuditFile, DiscoveredAuditBlock]] = {}
     audit_file: DiscoveredAuditFile
@@ -611,7 +706,8 @@ def index_generic_audit_definitions(
         definition_name: str = audit_file.file_path.stem
         if definition_name in definitions:
             raise CompileInputError(
-                f"Duplicate generic audit definition found for '{definition_name}'"
+                f"Duplicate generic audit definition found for '{definition_name}' in "
+                f"{definitions[definition_name][0].relative_path} and {audit_file.relative_path}"
             )
         definitions[definition_name] = (audit_file, audit_file.blocks[0])
     return definitions
@@ -620,9 +716,68 @@ def index_generic_audit_definitions(
 def is_generic_audit_file(audit_file: DiscoveredAuditFile) -> bool:
     """Return whether a discovered audit file is a generic definition."""
 
-    return audit_file.relative_path.parts[:2] == (
-        AUDIT_DIRECTORY_NAME,
-        GENERIC_AUDIT_DIRECTORY_NAME,
+    return audit_file.declaration_kind is DeclarationKind.AUDIT
+
+
+def singular_audit_resources(
+    *,
+    references: tuple[CompileSqlReference, ...],
+    audit_file: DiscoveredAuditFile,
+    audit_name: str,
+) -> tuple[ResourceIdentity, ...]:
+    """Require a singular audit to check more than one resource and return what it references."""
+
+    model_names: frozenset[str] = frozenset(
+        reference.ref_name for reference in references if reference.ref_kind == SqlReferenceKind.REF
+    )
+    companion_kinds: dict[SqlReferenceKind, ResourceKind] = {
+        SqlReferenceKind.SOURCE: ResourceKind.SOURCE,
+        SqlReferenceKind.SEED: ResourceKind.SEED,
+        SqlReferenceKind.TABLE_FUNCTION: ResourceKind.FUNCTION,
+    }
+    companions: frozenset[ResourceIdentity] = frozenset(
+        ResourceIdentity(companion_kinds[SqlReferenceKind(reference.ref_kind)], reference.ref_name)
+        for reference in references
+        if reference.ref_kind in companion_kinds
+    )
+    label: str = f"Singular audit '{audit_name}' in {audit_file.relative_path}"
+    if len(model_names) >= _CROSS_MODEL_MINIMUM or (model_names and companions):
+        return tuple(
+            sorted(
+                {
+                    *(ResourceIdentity(ResourceKind.MODEL, name) for name in model_names),
+                    *companions,
+                }
+            )
+        )
+    if len(model_names) == 1:
+        model_name: str = next(iter(model_names))
+        raise CompileInputError(
+            f"{label} checks only model '{model_name}'; singular audits must be cross-resource",
+            code=SINGULAR_AUDIT_NOT_CROSS_RESOURCE_CODE,
+            help=(
+                f"attach a generic audit to '{model_name}' instead: write it in an "
+                "audits/generic/ role and select FROM @relation, joining @relation to itself for "
+                "self-join checks"
+            ),
+        )
+    if companions:
+        raise CompileInputError(
+            f"{label} checks only sources or seeds; singular audits must reference at least one "
+            "model",
+            code=SINGULAR_AUDIT_NOT_CROSS_RESOURCE_CODE,
+            help="attach YAML audits to the source or seed instead",
+        )
+    raise CompileInputError(
+        f"{label} references no SQLBuild resource; singular audits must reference two or more "
+        f"models, or a model plus a source, seed, or table function via "
+        f"{SqlReferenceKind.REF.placeholder_call()}, {SqlReferenceKind.SOURCE.placeholder_call()}, "
+        f"or {SqlReferenceKind.SEED.placeholder_call()}",
+        code=SINGULAR_AUDIT_NOT_CROSS_RESOURCE_CODE,
+        help=(
+            "reference resources through SQLBuild calls instead of hard-coded relation names, or "
+            "attach a generic audit to the resource being checked"
+        ),
     )