sqlassert 0.1.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

sqlassert/__init__.py

@@ -1,13 +1,38 @@
-from sqlassert.unique import (
-    UniqueJoinCheckResult,
-    UniqueJoinValidationResult,
-    unique_assertions,
-    validate_unique_joins,
+from sqlassert.main import analyze, analyze_database
+from sqlassert.diagnostics import Diagnostic
+from sqlassert.properties import (
+    EnumeratedDomain, ExactlyOneJoin, ExhaustiveCase, FunctionalDependency, ManyToOneJoin, NonNullColumn, NonNullColumns, NonNullElements, NonNullUniqueSet, OneToManyJoin,
+    OneToOneJoin, Property, UniqueJoin, UniqueSet,
 )
+from sqlassert.provenance import AttachmentSite, Origin
+from sqlassert.reporting import AssertionReport, Outcome, RelationFacts, Report
+from sqlassert.suggest import Suggestion, SuggestionReport, suggest
 
 __all__ = [
-    "UniqueJoinCheckResult",
-    "UniqueJoinValidationResult",
-    "unique_assertions",
-    "validate_unique_joins",
+    "AssertionReport",
+    "AttachmentSite",
+    "Diagnostic",
+    "EnumeratedDomain",
+    "ExactlyOneJoin",
+    "ExhaustiveCase",
+    "FunctionalDependency",
+    "ManyToOneJoin",
+    "NonNullColumn",
+    "NonNullColumns",
+    "NonNullElements",
+    "NonNullUniqueSet",
+    "OneToManyJoin",
+    "OneToOneJoin",
+    "Origin",
+    "Outcome",
+    "Property",
+    "RelationFacts",
+    "Report",
+    "Suggestion",
+    "SuggestionReport",
+    "UniqueSet",
+    "UniqueJoin",
+    "analyze",
+    "analyze_database",
+    "suggest",
 ]

sqlassert/__main__.py

@@ -0,0 +1,138 @@
+"""Command line: `sqlassert check PATH...` checks the assertions in SQL Programs for CI (`check.py`);
+`sqlassert suggest FILE` prints the improvements and markers sqlassert can prove.
+dbt projects are checked by the separate `sqlassert-dbt` package (`integrations/dbt/`)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+from sqlassert import check
+from sqlassert.main import DEFAULT_DIALECT
+from sqlassert.suggest import DEFAULT_MAX_SIZE, suggest
+
+# How each suggested Property reads in the listing.
+_KINDS = {
+    "ExactlyOneJoin": "Exactly One Join",
+    "OneToOneJoin": "One To One Join",
+    "ManyToOneJoin": "Many To One Join",
+    "OneToManyJoin": "One To Many Join",
+    "UniqueJoin": "Unique Join",
+    "UniqueSet": "Unique Set",
+    "NonNullUniqueSet": "Non-Null Unique Set",
+    "NonNullColumns": "Not Null",
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sqlassert")
+    commands = parser.add_subparsers(dest="command", required=True)
+    suggest_command = commands.add_parser(
+        "suggest", help="list the improvements and markers sqlassert can prove for a SQL Program"
+    )
+    suggest_command.add_argument("file", help="SQL Program to read, or - for stdin")
+    suggest_command.add_argument("--dialect", default=DEFAULT_DIALECT)
+    suggest_command.add_argument(
+        "--max-size", type=int, default=DEFAULT_MAX_SIZE, help="widest Unique Set searched exhaustively"
+    )
+    suggest_command.add_argument("--explain", action="store_true", help="print each suggestion's evidence")
+    suggest_command.add_argument(
+        "--annotate", action="store_true",
+        help="paste every suggested marker into FILE (for -, print the annotated SQL instead of the list)",
+    )
+    check_command = commands.add_parser(
+        "check",
+        help="analyze SQL Programs and fail when an assertion is UNKNOWN or a Diagnostic is reported",
+        description="Analyze each SQL Program from its SQL alone. Exit status: "
+        f"{check.EXIT_OK} every assertion PROVED (warnings allowed), {check.EXIT_FINDINGS} an assertion UNKNOWN "
+        f"or a Diagnostic reported, {check.EXIT_USAGE} bad arguments, configuration, or unreadable SQL. "
+        "Defaults come from [tool.sqlassert] in the nearest pyproject.toml; flags replace them, except --ignore, which adds to them.",
+    )
+    check_command.add_argument(
+        "paths", nargs="*", metavar="PATH",
+        help="SQL files, directories (every *.sql under them), or globs; - for stdin (default: [tool.sqlassert] paths)",
+    )
+    check_command.add_argument("--dialect", help=f"SQL dialect (default: [tool.sqlassert] dialect, else {DEFAULT_DIALECT})")
+    ignoring = check_command.add_mutually_exclusive_group()
+    ignoring.add_argument(
+        "--ignore", action="append", metavar="CODE",
+        help="also drop Findings with this code, e.g. undeclared-table, besides [tool.sqlassert] ignore; "
+        "repeatable or comma-separated",
+    )
+    ignoring.add_argument(
+        "--only-ignore", action="append", metavar="CODE",
+        help="drop Findings with these codes instead of [tool.sqlassert] ignore; repeatable or comma-separated "
+        "(--only-ignore '' ignores nothing)",
+    )
+    check_command.add_argument("--format", choices=sorted(check.FORMATS), default="text")
+    check_command.add_argument("--explain", action="store_true", help="print each UNKNOWN assertion's evidence")
+    arguments = parser.parse_args(argv)
+    if arguments.command == "check":
+        return _check(arguments)
+
+    try:
+        sql = check.read_sql(Path(arguments.file))
+    except check.UsageError as error:
+        print(f"sqlassert suggest: {error}", file=sys.stderr)
+        return check.EXIT_USAGE
+    report = suggest(sql, dialect=arguments.dialect, max_size=arguments.max_size)
+    for diagnostic in report.diagnostics:
+        print(f"{diagnostic.code}: {diagnostic.message}", file=sys.stderr)
+    for warning in report.warnings:
+        print(f"warning: {warning.code}: {warning.message}", file=sys.stderr)
+    if arguments.annotate and arguments.file == "-":
+        sys.stdout.write(report.annotated())
+        return 1 if report.diagnostics else 0
+    if arguments.annotate and report.suggestions:
+        Path(arguments.file).write_text(report.annotated())
+    # Improvements (High) first, then markers (Mid), then smells (Low).
+    items = (*report.improvements, *report.suggestions, *report.smells)
+    rows = [
+        (i.level.value, f"line {i.site.line}", i.site.label, i.rewrite.value, i.message) for i in report.improvements
+    ] + [
+        (s.level.value, f"line {s.site.line}", s.site.label, _KINDS[type(s.property).__name__], s.marker)
+        for s in report.suggestions
+    ] + [
+        (s.level.value, f"line {s.site.line}", s.site.label, s.concern.value, s.message) for s in report.smells
+    ]
+    widths = [max((len(row[i]) for row in rows), default=0) for i in range(4)]
+    for row, item in zip(rows, items):
+        print("  ".join(cell.ljust(width) for cell, width in zip(row[:4], widths)) + "  " + row[4])
+        if arguments.explain:
+            print(check.indented(item.evidence.explain()))
+    return 1 if report.diagnostics else 0
+
+
+def _check(arguments: argparse.Namespace) -> int:
+    try:
+        config = check.load_config(Path.cwd())
+        dialect = arguments.dialect or config.dialect
+        ignore = (
+            _codes(arguments.only_ignore) if arguments.only_ignore is not None
+            else config.ignore | _codes(arguments.ignore or ())
+        )
+        check.validate(dialect, ignore)
+        if arguments.paths:
+            paths = check.expand(arguments.paths, Path.cwd())
+        elif config.paths:
+            paths = check.expand(config.paths, config.root)
+        else:
+            raise check.UsageError("no SQL to check: name files, directories or globs, or set paths in [tool.sqlassert]")
+        programs = [(check.display(path), check.read_sql(path)) for path in paths]
+    except check.UsageError as error:
+        print(f"sqlassert check: {error}", file=sys.stderr)
+        return check.EXIT_USAGE
+    checked = [check.check(path, sql, dialect=dialect, ignore=ignore) for path, sql in programs]
+    sys.stdout.write(check.FORMATS[arguments.format](checked, explain=arguments.explain))
+    return check.exit_code(checked)
+
+
+def _codes(values: Iterable[str]) -> frozenset[str]:
+    """The codes of repeated, comma-separated flag values."""
+    return frozenset(code.strip() for value in values for code in value.split(",") if code.strip())
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sqlassert/check.py

@@ -0,0 +1,444 @@
+"""`sqlassert check`: analyze SQL Programs for CI, and render what they find.
+
+Each file is one SQL Program, analyzed from its SQL alone (`analyze`). Every
+`UNKNOWN` assertion and every Diagnostic becomes a Finding; a Connection
+Warning is a warning-level Finding and never fails the check, as it never fails
+a `Report`. The exit codes, Findings and formatters are this module's
+interface for any command that checks SQL (the CLI, the `sqlassert-dbt` plugin);
+`__main__.py` only parses arguments.
+
+Configuration comes from `[tool.sqlassert]` in the nearest `pyproject.toml`
+that has one, searched from the working directory upwards; command-line flags
+replace its values.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import sys
+import tomllib
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass, field
+from enum import Enum
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from urllib.parse import quote
+
+from sqlglot.dialects.dialect import Dialect
+
+from sqlassert import diagnostics as diag
+from sqlassert.diagnostics import Diagnostic
+from sqlassert.main import DEFAULT_DIALECT, analyze
+from sqlassert.provenance import Origin, Span
+from sqlassert.reporting import ASSERTED_KINDS, Outcome, Report
+
+# Exit codes, shared by every command that checks SQL.
+EXIT_OK = 0  # every assertion PROVED and no Diagnostic (warnings allowed)
+EXIT_FINDINGS = 1  # an assertion UNKNOWN or a Diagnostic reported
+EXIT_USAGE = 2  # bad arguments or configuration, or SQL that could not be read
+
+
+def unproved(kind: str) -> str:
+    """The code of the Finding an `UNKNOWN` assertion of this marker kind
+    produces: it names what was asserted and not proved, e.g. `unproved-unique`."""
+    return f"unproved-{kind}"
+
+
+# Every code a Finding can carry, so a mistyped ignored code is reported rather than ignored.
+UNPROVED_CODES = frozenset(unproved(kind) for kind in ASSERTED_KINDS.values())
+CODES = frozenset(
+    UNPROVED_CODES | {value for name, value in vars(diag).items() if name.isupper() and isinstance(value, str)}
+)
+
+STDIN = "-"
+
+
+class Severity(Enum):
+    """An `error` fails the check; a `warning` (a Connection Warning) never does."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One thing a check reports: an `UNKNOWN` assertion or a Diagnostic.
+
+    `path` is the file as shown to the user. `evidence` is an `UNKNOWN`
+    assertion's explained Evidence, printed only when asked for.
+    """
+
+    path: str
+    severity: Severity
+    code: str
+    message: str
+    origin: Origin | None = None
+    evidence: str | None = None
+
+
+@dataclass(frozen=True)
+class Checked:
+    """One SQL Program's Report and the Findings it produced, ignored codes removed."""
+
+    path: str
+    report: Report
+    findings: tuple[Finding, ...]
+
+
+class UsageError(Exception):
+    """Arguments, configuration, or files that leave nothing to check: exit `EXIT_USAGE`."""
+
+
+# Checking ------------------------------------------------------------------
+
+
+def findings(path: str, sql: str, report: Report, *, ignore: Iterable[str] = ()) -> tuple[Finding, ...]:
+    """The Findings of one Report, in source order within each kind, codes in `ignore` left out."""
+    ignored = frozenset(ignore)
+    unknown = [
+        Finding(
+            path, Severity.ERROR, unproved(assertion.kind), f"{_written(sql, assertion.origin)} is not proved (UNKNOWN)",
+            assertion.origin, assertion.evidence.explain() if assertion.evidence is not None else None,
+        )
+        for assertion in report.assertions
+        if assertion.outcome is Outcome.UNKNOWN
+    ]
+    reported = [_diagnostic(path, diagnostic, Severity.ERROR) for diagnostic in report.diagnostics]
+    warned = [_diagnostic(path, warning, Severity.WARNING) for warning in report.warnings]
+    return tuple(
+        finding for finding in sorted((*unknown, *reported, *warned), key=_source_order)
+        if finding.code not in ignored
+    )
+
+
+def check(path: str, sql: str, *, dialect: str = DEFAULT_DIALECT, ignore: Iterable[str] = ()) -> Checked:
+    """Analyze one SQL Program from its SQL alone."""
+    report = analyze(sql, dialect=dialect)
+    return Checked(path, report, findings(path, sql, report, ignore=ignore))
+
+
+def exit_code(checked: Iterable[Checked]) -> int:
+    """`EXIT_FINDINGS` when any error-level Finding remains, else `EXIT_OK`."""
+    failed = any(finding.severity is Severity.ERROR for result in checked for finding in result.findings)
+    return EXIT_FINDINGS if failed else EXIT_OK
+
+
+def _diagnostic(path: str, diagnostic: Diagnostic, severity: Severity) -> Finding:
+    return Finding(path, severity, diagnostic.code, diagnostic.message, diagnostic.origin)
+
+
+def _source_order(finding: Finding) -> tuple[int, int]:
+    """Findings without a line first, then by line and column."""
+    origin = finding.origin
+    if origin is None or origin.line is None:
+        return 0, 0
+    return origin.line, origin.span.column if origin.span is not None else 0
+
+
+def _written(sql: str, origin: Origin) -> str:
+    """The marker as written at `origin`, whitespace collapsed; its detail when it has no span."""
+    if origin.span is None:
+        return origin.detail
+    return " ".join(_text(sql, origin.span).split())
+
+
+def _text(sql: str, span: Span) -> str:
+    return sql[_offset(sql, span.line, span.column):_offset(sql, span.end_line, span.end_column)]
+
+
+def _offset(sql: str, line: int, column: int) -> int:
+    """The inverse of `Span.of`: lines end at `\\n` only."""
+    start = 0
+    for _ in range(line - 1):
+        start = sql.index("\n", start) + 1
+    return start + column - 1
+
+
+# Configuration ---------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Config:
+    """`[tool.sqlassert]`: `dialect`, `paths` (files, directories, globs;
+    relative to `root`), and `ignore` (codes whose Findings are dropped)."""
+
+    root: Path
+    dialect: str = DEFAULT_DIALECT
+    paths: tuple[str, ...] = ()
+    ignore: frozenset[str] = field(default_factory=frozenset)
+
+
+_CONFIG_KEYS = {"dialect": str, "paths": list, "ignore": list}
+
+
+def load_config(start: Path) -> Config:
+    """The `[tool.sqlassert]` table of the nearest `pyproject.toml` that has
+    one, from `start` upwards; defaults rooted at `start` when none does."""
+    for directory in (start, *start.parents):
+        pyproject = directory / "pyproject.toml"
+        if not pyproject.is_file():
+            continue
+        try:
+            table = tomllib.loads(pyproject.read_text()).get("tool", {}).get("sqlassert")
+        except (OSError, tomllib.TOMLDecodeError) as error:
+            raise UsageError(f"{pyproject}: {error}") from error
+        if table is not None:
+            return _config(pyproject, table)
+    return Config(start)
+
+
+def _config(pyproject: Path, table: object) -> Config:
+    if not isinstance(table, dict):
+        raise UsageError(f"{pyproject}: [tool.sqlassert] must be a table")
+    for key, value in table.items():
+        expected = _CONFIG_KEYS.get(key)
+        if expected is None:
+            raise UsageError(f"{pyproject}: unknown key {key!r} in [tool.sqlassert]; the keys are {', '.join(_CONFIG_KEYS)}")
+        if not isinstance(value, expected) or (expected is list and not all(isinstance(item, str) for item in value)):
+            shape = "a string" if expected is str else "a list of strings"
+            raise UsageError(f"{pyproject}: [tool.sqlassert] {key} must be {shape}")
+    return Config(
+        pyproject.parent,
+        dialect=table.get("dialect", DEFAULT_DIALECT),
+        paths=tuple(table.get("paths", ())),
+        ignore=frozenset(table.get("ignore", ())),
+    )
+
+
+def validate(dialect: str, ignore: Iterable[str]) -> None:
+    """Reject a dialect SQLGlot does not know, and an ignored code no Finding carries."""
+    try:
+        Dialect.get_or_raise(dialect)
+    except ValueError as error:
+        raise UsageError(str(error)) from error
+    unknown = sorted(set(ignore) - CODES)
+    if unknown:
+        raise UsageError(f"unknown code(s) to ignore: {', '.join(unknown)}; the codes are {', '.join(sorted(CODES))}")
+
+
+def expand(patterns: Sequence[str], root: Path) -> list[Path]:
+    """The SQL files `patterns` name, relative to `root`, in order and without repeats.
+
+    A file is itself; a directory is every `*.sql` under it; anything with a
+    glob character is a recursive glob (`**` crosses directories). A pattern
+    that names no file is a usage error: a check that silently checks nothing
+    would pass.
+    """
+    found: dict[Path, None] = {}
+    for pattern in patterns:
+        if pattern == STDIN:
+            found[Path(STDIN)] = None
+            continue
+        path = root / pattern
+        if glob.has_magic(pattern):
+            matches = sorted(Path(match) for match in glob.glob(str(path), recursive=True) if Path(match).is_file())
+        elif path.is_dir():
+            matches = sorted(path.rglob("*.sql"))
+        elif path.is_file():
+            matches = [path]
+        else:
+            raise UsageError(f"{pattern}: no such file or directory")
+        if not matches:
+            raise UsageError(f"{pattern} matches no SQL files")
+        found.update(dict.fromkeys(matches))
+    return list(found)
+
+
+def display(path: Path) -> str:
+    """How a checked file is named in output: relative to the working directory when inside it."""
+    if path == Path(STDIN):
+        return "<stdin>"
+    try:
+        return path.resolve().relative_to(Path.cwd().resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def read_sql(path: Path) -> str:
+    """A SQL Program's text; `-` reads stdin."""
+    if path == Path(STDIN):
+        return sys.stdin.read()
+    try:
+        return path.read_text()
+    except (OSError, UnicodeDecodeError) as error:
+        raise UsageError(f"{path}: {error}") from error
+
+
+# Output --------------------------------------------------------------------
+
+
+def indented(text: str, prefix: str = "    ") -> str:
+    """Explained Evidence, set under the line it explains."""
+    return "\n".join(prefix + line for line in text.splitlines())
+
+
+def render_text(checked: Sequence[Checked], *, explain: bool = False) -> str:
+    """`path:line:column: severity code: message`, then a summary line."""
+    lines = []
+    for result in checked:
+        for finding in result.findings:
+            lines.append(f"{_place(finding)}: {finding.severity.value} {finding.code}: {finding.message}")
+            if explain and finding.evidence is not None:
+                lines.append(indented(finding.evidence))
+    lines.append(_summary_line(checked))
+    return "\n".join(lines) + "\n"
+
+
+def render_json(checked: Sequence[Checked], *, explain: bool = False) -> str:
+    """Every assertion's outcome and every Finding, as one JSON document."""
+    def finding(item: Finding) -> dict:
+        shown = {
+            "path": item.path, "severity": item.severity.value, "code": item.code, "message": item.message,
+            "location": _location(item.origin),
+        }
+        if explain and item.evidence is not None:
+            shown["evidence"] = item.evidence
+        return shown
+
+    document = {
+        "assertions": [
+            {"path": result.path, "id": assertion.assertion_id, "outcome": assertion.outcome.value, "location": _location(assertion.origin)}
+            for result in checked for assertion in result.report.assertions
+        ],
+        "findings": [finding(item) for result in checked for item in result.findings],
+        "summary": _summary(checked),
+    }
+    return json.dumps(document, indent=2) + "\n"
+
+
+def render_sarif(checked: Sequence[Checked], *, explain: bool = False) -> str:
+    """A SARIF 2.1.0 log, as GitHub code scanning reads it. Columns count characters."""
+    found = [finding for result in checked for finding in result.findings]
+    codes = sorted({finding.code for finding in found})
+    driver: dict = {"name": "sqlassert", "informationUri": "https://github.com/polvoazul/sqlassert", "rules": [
+        {"id": code, "shortDescription": {"text": _RULE_DESCRIPTIONS.get(code, code.replace("-", " "))}}
+        for code in codes
+    ]}
+    try:
+        driver["version"] = version("sqlassert")
+    except PackageNotFoundError:
+        pass
+
+    def result(finding: Finding) -> dict:
+        message = finding.message
+        if explain and finding.evidence is not None:
+            message += "\n\n" + finding.evidence
+        location: dict = {"artifactLocation": {"uri": _uri(finding.path)}}
+        origin = finding.origin
+        if origin is not None and origin.line is not None:
+            region: dict = {"startLine": origin.line}
+            if origin.span is not None:
+                region.update(
+                    startColumn=origin.span.column, endLine=origin.span.end_line, endColumn=origin.span.end_column
+                )
+            location["region"] = region
+        return {
+            "ruleId": finding.code,
+            "ruleIndex": codes.index(finding.code),
+            "level": finding.severity.value,
+            "message": {"text": message},
+            "locations": [{"physicalLocation": location}],
+        }
+
+    log = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{"tool": {"driver": driver}, "columnKind": "unicodeCodePoints", "results": [result(f) for f in found]}],
+    }
+    return json.dumps(log, indent=2) + "\n"
+
+
+def render_github(checked: Sequence[Checked], *, explain: bool = False) -> str:
+    """GitHub Actions workflow commands: one `::error` or `::warning` annotation per Finding."""
+    lines = []
+    for result in checked:
+        for finding in result.findings:
+            properties = {"file": finding.path}
+            origin = finding.origin
+            if origin is not None and origin.line is not None:
+                properties["line"] = str(origin.line)
+                span = origin.span
+                if span is not None:
+                    properties["endLine"] = str(span.end_line)
+                    # GitHub honours columns only within one line.
+                    if span.end_line == span.line:
+                        properties.update(col=str(span.column), endColumn=str(span.end_column))
+            properties["title"] = f"sqlassert {finding.code}"
+            message = finding.message
+            if explain and finding.evidence is not None:
+                message += "\n" + finding.evidence
+            shown = ",".join(f"{key}={_escape_property(value)}" for key, value in properties.items())
+            lines.append(f"::{finding.severity.value} {shown}::{_escape_data(message)}")
+    return "".join(line + "\n" for line in lines)
+
+
+FORMATS: dict[str, Callable[..., str]] = {
+    "text": render_text,
+    "json": render_json,
+    "sarif": render_sarif,
+    "github": render_github,
+}
+
+_RULE_DESCRIPTIONS = {
+    unproved(kind): f"An asserted {kind.replace('-', ' ')} Property is not proved (UNKNOWN)" for kind in ASSERTED_KINDS.values()
+}
+
+
+def _place(finding: Finding) -> str:
+    origin = finding.origin
+    if origin is None or origin.line is None:
+        return finding.path
+    if origin.span is None:
+        return f"{finding.path}:{origin.line}"
+    return f"{finding.path}:{origin.line}:{origin.span.column}"
+
+
+def _location(origin: Origin | None) -> dict | None:
+    if origin is None or origin.line is None:
+        return None
+    if origin.span is None:
+        return {"line": origin.line}
+    span = origin.span
+    return {"line": span.line, "column": span.column, "end_line": span.end_line, "end_column": span.end_column}
+
+
+def _summary(checked: Sequence[Checked]) -> dict:
+    assertions = [assertion for result in checked for assertion in result.report.assertions]
+    found = [finding for result in checked for finding in result.findings]
+    return {
+        "files": len(checked),
+        "assertions": len(assertions),
+        "proved": sum(assertion.outcome is Outcome.PROVED for assertion in assertions),
+        "unknown": sum(assertion.outcome is Outcome.UNKNOWN for assertion in assertions),
+        "errors": sum(finding.severity is Severity.ERROR for finding in found),
+        "warnings": sum(finding.severity is Severity.WARNING for finding in found),
+    }
+
+
+def _summary_line(checked: Sequence[Checked]) -> str:
+    counts = _summary(checked)
+
+    def plural(count: int, noun: str) -> str:
+        return f"{count} {noun}{'' if count == 1 else 's'}"
+
+    return (
+        f"{plural(counts['files'], 'file')} checked: {plural(counts['assertions'], 'assertion')} "
+        f"({counts['proved']} PROVED, {counts['unknown']} UNKNOWN), "
+        f"{plural(counts['errors'], 'error')}, {plural(counts['warnings'], 'warning')}"
+    )
+
+
+def _uri(path: str) -> str:
+    if os.path.isabs(path):
+        return Path(path).as_uri()
+    return quote(path)
+
+
+def _escape_data(text: str) -> str:
+    return text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _escape_property(text: str) -> str:
+    return _escape_data(text).replace(":", "%3A").replace(",", "%2C")

sqlassert/diagnostics.py

@@ -0,0 +1,57 @@
+"""Explicit statements about what analysis could not do.
+
+A diagnostic reports a program the engine does not support. It is never a
+Disproof and never an inference: it says that analysis stopped short, and why.
+
+A warning is a Diagnostic too, reported apart (`Report.warnings`): the program
+is supported, but a fact a connection would supply is missing, so analysis
+treats it as unknown (ADR 0005). So are a constraint the dialect does not
+enforce, and, about the SQL itself (`SQL_WARNINGS`), an operator whose
+meaning a setting decides, a comparison that depends on something the
+values do not show, like a zoned timestamp's zone (`dialects.py`), and a
+comparison of composites whose elements may be NULL.
+Warnings never make a Report fail.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlassert.provenance import Origin
+
+CATALOG_METADATA_UNAVAILABLE = "catalog-metadata-unavailable"
+AMBIGUOUS_COLUMN = "ambiguous-column"
+AMBIGUOUS_OPERATOR = "ambiguous-operator"
+CARDINALITY_ON_FILTERING_JOIN = "cardinality-on-filtering-join"
+CATALOG_RELATION_NOT_FOUND = "catalog-relation-not-found"
+COMPOSITE_COMPARISON = "composite-comparison"
+CONSTRAINT_WITHOUT_TABLE = "constraint-without-table"
+DUPLICATE_DECLARATION = "duplicate-declaration"
+INCOMPLETE_CATALOG_METADATA = "incomplete-catalog-metadata"
+INVALID_FOREIGN_KEY_CONSTRAINT = "invalid-foreign-key-constraint"
+MULTIPLE_ROOT_SELECTS = "multiple-root-selects"
+RECURSIVE_VIEW_DEFINITION = "recursive-view-definition"
+SQL_PARSE_FAILED = "sql-parse-failed"
+UNANALYZED_ASSERTION = "unanalyzed-assertion"
+UNATTACHED_MARKER = "unattached-marker"
+UNDECLARED_TABLE = "undeclared-table"
+UNENFORCED_CONSTRAINT = "unenforced-constraint"
+UNKNOWN_ASSERTED_COLUMN = "unknown-asserted-column"
+UNRESOLVED_ASSERTED_COLUMN = "unresolved-asserted-column"
+UNKNOWN_REFERENCED_COLUMN = "unknown-referenced-column"
+UNRECOGNIZED_MARKER = "unrecognized-marker"
+UNSUPPORTED_CREATE_STATEMENT = "unsupported-create-statement"
+UNSUPPORTED_NATURAL_JOIN = "unsupported-natural-join"
+UNSUPPORTED_STATEMENT = "unsupported-statement"
+ZONED_TIMESTAMP_CAST = "zoned-timestamp-cast"
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    code: str
+    message: str
+    origin: Origin | None = None
+
+
+# Warnings about the SQL itself, which no connection answers: `analyze_database` keeps them.
+SQL_WARNINGS = frozenset({AMBIGUOUS_OPERATOR, COMPOSITE_COMPARISON, ZONED_TIMESTAMP_CAST})