Findings and exceptions

A Rule finding identifies an exact code, project-relative path, line, column, message, and remediation. Error findings make compilation fail and prevent artifact completion.

Exact exceptions

Use an exact exception for one known finding. Exceptions require a reason and are stale-checked:

[[rules.rule_exceptions]]
rule = "SQBRSQL004"
path = "models/examples/sample_orders.sql"
reason = "This example intentionally demonstrates one sampled row."

An exception refers to one exact Rule code and path. If the finding disappears, SQLBuild reports the stale exception so obsolete configuration does not accumulate silently.

Path- and resource-scoped ignores

Use a path ignore when a documented project area intentionally follows a different convention:

[[rules.rule_ignores]]
rules = ["SQBRSQL"]
paths = ["models/examples/**"]
reason = "Examples retain intentionally minimal SQL."

Path ignores accept exact codes and family prefixes. Keep their scope narrow and explain why the project differs from the selected requirement.

Use selectors when the exception follows graph-resource identities or lineage rather than files:

[[rules.rule_ignores]]
rules = ["SQBRSQL021"]
selectors = ["intermediate_*"]
reason = "These intermediate interfaces intentionally preserve upstream columns."

Selectors use the same grammar as SQLBuild commands, including exact names, name globs, tags, resource paths, and graph expansion such as +intermediate_*. Use paths for authored-file glob matching, including SQL tests and audits that are not graph resources:

[[rules.rule_ignores]]
rules = ["SQBRSQL021"]
paths = ["models/**/intermediate_*.sql"]
reason = "These intermediate SQL files intentionally preserve upstream columns."

paths and selectors may be combined in one scoped ignore. Both forms require a reason.

Mandatory correctness

Mandatory compiler correctness is not configurable and cannot be suppressed. A project must first compile into a trustworthy representation before any selected Rule can run.

Machine-readable findings

Use JSON when another tool consumes findings:

sqb compile --json
sqb rules --json run SQBRSQL

Machine-readable output remains on stdout. Lifecycle progress and terminal status are written to stderr.