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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. sqlassert/__init__.py +34 -9
  2. sqlassert/__main__.py +138 -0
  3. sqlassert/check.py +444 -0
  4. sqlassert/diagnostics.py +57 -0
  5. sqlassert/dialects.py +211 -0
  6. sqlassert/discovery/__init__.py +30 -0
  7. sqlassert/discovery/bigquery.py +71 -0
  8. sqlassert/discovery/databricks.py +18 -0
  9. sqlassert/discovery/duckdb.py +163 -0
  10. sqlassert/discovery/fetcher.py +402 -0
  11. sqlassert/discovery/information_schema.py +326 -0
  12. sqlassert/discovery/mysql.py +70 -0
  13. sqlassert/discovery/postgres.py +143 -0
  14. sqlassert/discovery/redshift.py +36 -0
  15. sqlassert/discovery/snowflake.py +63 -0
  16. sqlassert/discovery/trino.py +37 -0
  17. sqlassert/improvements.py +528 -0
  18. sqlassert/ir/__init__.py +56 -0
  19. sqlassert/ir/convert.py +2377 -0
  20. sqlassert/ir/model.py +676 -0
  21. sqlassert/main.py +57 -0
  22. sqlassert/properties.py +121 -0
  23. sqlassert/provenance.py +73 -0
  24. sqlassert/python_engine.py +299 -0
  25. sqlassert/reporting.py +102 -0
  26. sqlassert/rules/STYLEGUIDE.md +19 -0
  27. sqlassert/rules/__init__.py +11 -0
  28. sqlassert/rules/column_set.py +34 -0
  29. sqlassert/rules/domain.py +376 -0
  30. sqlassert/rules/equality.py +233 -0
  31. sqlassert/rules/exactly_one.py +75 -0
  32. sqlassert/rules/foreign_key.py +316 -0
  33. sqlassert/rules/join_cardinality.py +94 -0
  34. sqlassert/rules/nullability.py +418 -0
  35. sqlassert/rules/uniqueness.py +601 -0
  36. sqlassert/smells.py +306 -0
  37. sqlassert/sql_parse.py +974 -0
  38. sqlassert/suggest.py +339 -0
  39. sqlassert-0.3.1.dist-info/METADATA +725 -0
  40. sqlassert-0.3.1.dist-info/RECORD +44 -0
  41. {sqlassert-0.1.2.dist-info → sqlassert-0.3.1.dist-info}/WHEEL +1 -1
  42. sqlassert-0.3.1.dist-info/entry_points.txt +2 -0
  43. sqlassert-0.3.1.dist-info/licenses/LICENSE +21 -0
  44. sqlassert/unique.py +0 -605
  45. sqlassert-0.1.2.dist-info/METADATA +0 -173
  46. sqlassert-0.1.2.dist-info/RECORD +0 -6
  47. {sqlassert-0.1.2.dist-info → sqlassert-0.3.1.dist-info}/top_level.txt +0 -0
sqlassert/main.py ADDED
@@ -0,0 +1,57 @@
1
+ """Compose parsing, IR conversion, and property analysis into a Report."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import replace
6
+ from typing import TYPE_CHECKING
7
+
8
+ from sqlassert import diagnostics as diag
9
+ from sqlassert.ir.convert import IrParser
10
+ from sqlassert.python_engine import Engine
11
+ from sqlassert.reporting import Report
12
+ from sqlassert.sql_parse import SqlParser
13
+
14
+ if TYPE_CHECKING:
15
+ from sqlassert.discovery import DatabaseKnowledgeFetcher
16
+
17
+ DEFAULT_DIALECT = "duckdb"
18
+
19
+
20
+ def analyze(sql: str, *, dialect: str = DEFAULT_DIALECT, trust_unenforced_keys: bool = True) -> Report:
21
+ """Prove the Unique Join Assertions and Unique Set Assertions in one SQL Program.
22
+
23
+ Pure: the Program is the only source of Knowledge. `analyze_database`
24
+ adds a database catalog. Where a catalog would have helped (a table with
25
+ no `CREATE`, a column only a catalog can resolve), the Report warns.
26
+ `trust_unenforced_keys` (on by default) makes the keys the dialect does
27
+ not enforce Property Declarations, as `RELY` does; off, they are ignored
28
+ with an `unenforced-constraint` warning (`docs/dialects.md`).
29
+ """
30
+ sql_parser = SqlParser(dialect)
31
+ ir_parser = IrParser(dialect, trust_unenforced_keys)
32
+
33
+ ast = sql_parser.parse(sql)
34
+ conversion = ir_parser.parse(ast)
35
+ diagnostics = ast.diagnostics + conversion.diagnostics
36
+ return Engine().run(conversion.program, conversion.knowledge, diagnostics, conversion.warnings)
37
+
38
+
39
+ def analyze_database(
40
+ sql: str, fetcher: DatabaseKnowledgeFetcher, *, dialect: str = DEFAULT_DIALECT, trust_unenforced_keys: bool = True,
41
+ ) -> Report:
42
+ """`analyze`, with the external Relations the Program reaches hydrated from a catalog.
43
+
44
+ The fetcher reads catalog metadata only, never rows, and binds it to the
45
+ final IR before the engine runs once. No connection warnings: a relation
46
+ the catalog lacks is already a diagnostic. A catalog key the dialect does
47
+ not enforce warns, unless `trust_unenforced_keys` declares it, and so do
48
+ the SQL's own warnings (`diagnostics.SQL_WARNINGS`).
49
+ """
50
+ ast = SqlParser(dialect).parse(sql)
51
+ hydration = fetcher.hydrate(ast, dialect=dialect, trust_unenforced_keys=trust_unenforced_keys)
52
+ conversion = hydration.conversion
53
+ facts = fetcher.bind(conversion.program, hydration)
54
+ program = replace(conversion.program, declarations=conversion.program.declarations + facts.declarations)
55
+ diagnostics = ast.diagnostics + hydration.diagnostics + conversion.diagnostics
56
+ warnings = (*facts.warnings, *(warning for warning in conversion.warnings if warning.code in diag.SQL_WARNINGS))
57
+ return Engine().run(program, conversion.knowledge + facts.knowledge, diagnostics, warnings)
@@ -0,0 +1,121 @@
1
+ """Structural properties over the relational IR."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from sqlassert.ir.model import Join, LiteralValue, NodeMeta, OutputColumn, SimpleCase
6
+
7
+
8
+ class Property(metaclass=NodeMeta, abstract=True):
9
+ """One semantic statement, independent of how it enters reasoning."""
10
+
11
+
12
+ class NonNullColumn(Property):
13
+ column: OutputColumn
14
+
15
+
16
+ class NonNullColumns(Property):
17
+ """Every listed column is non-null: one assertion for a whole column list."""
18
+
19
+ columns: frozenset[OutputColumn]
20
+
21
+
22
+ class NonNullElements(Property):
23
+ """No listed column's value has a NULL element: an ARRAY's elements, a
24
+ ROW's fields, a MAP's values, nested ones included (`NOT NULL ELEMENTS`).
25
+ Says nothing of the value itself, which may be NULL. No catalog states it,
26
+ so it is only asserted or declared."""
27
+
28
+ columns: frozenset[OutputColumn]
29
+
30
+
31
+ class UniqueSet(Property):
32
+ columns: frozenset[OutputColumn]
33
+
34
+
35
+ class NonNullUniqueSet(UniqueSet):
36
+ """A Unique Set whose columns are all non-null."""
37
+
38
+
39
+ class FunctionalDependency(Property):
40
+ """Rows agreeing on every `determinant` column, all non-null, agree on
41
+ every `dependent` column (`DETERMINES`). Lax: NULL in the determinant
42
+ exempts a row, as it does for a Unique Set."""
43
+
44
+ determinant: frozenset[OutputColumn]
45
+ dependent: frozenset[OutputColumn]
46
+
47
+
48
+ class EnumeratedDomain(Property):
49
+ """Every non-null value of `column` is one of `values`.
50
+
51
+ NULL is outside every domain (`NOT NULL` governs it), and a domain does
52
+ not claim that each of its values occurs.
53
+ """
54
+
55
+ column: OutputColumn
56
+ values: frozenset[LiteralValue]
57
+
58
+
59
+ class ExhaustiveCase(Property):
60
+ """Every member of `case`'s operand's Enumerated Domain has a WHEN arm
61
+ that is exactly that literal, so no non-null operand value reaches ELSE.
62
+
63
+ ELSE never substitutes for an arm, and a NULL operand, which matches no
64
+ arm, is left to `NOT NULL`.
65
+ """
66
+
67
+ case: SimpleCase
68
+
69
+
70
+ class ManyToOneJoin(Property):
71
+ """A join that cannot repeat a row of its left input: each left row
72
+ matches at most one right row (`MANY TO ONE`)."""
73
+
74
+ join: Join
75
+
76
+
77
+ class OneToManyJoin(Property):
78
+ """A join that cannot repeat a row of its right input: each right row
79
+ matches at most one left row (`ONE TO MANY`)."""
80
+
81
+ join: Join
82
+
83
+
84
+ class OneToOneJoin(Property):
85
+ """A join that repeats a row of neither input (`ONE TO ONE`)."""
86
+
87
+ join: Join
88
+
89
+
90
+ class UniqueJoin(Property):
91
+ """A join that repeats rows of at most one input: it is not many to many
92
+ (`UNIQUE`, `NOT MANY TO MANY`)."""
93
+
94
+ join: Join
95
+
96
+
97
+ class ExactlyOneJoin(Property):
98
+ """A join in which every row of its left input matches exactly one right row.
99
+
100
+ The join neither multiplies nor removes left rows, and a left join
101
+ null-extends none of them.
102
+ """
103
+
104
+ join: Join
105
+
106
+
107
+ class ReferentialCoverage(Property):
108
+ """Every row whose referencing columns are all non-null has a row of the
109
+ referenced relation equal to it on the paired referenced columns.
110
+
111
+ Columns pair by position. A row with a null referencing component is exempt
112
+ (`MATCH SIMPLE`). This is the part of a Foreign Key that Knowledge supplies:
113
+ `REFERENCES` constraints, catalog foreign keys, and declarations.
114
+ """
115
+
116
+ columns: tuple[OutputColumn, ...]
117
+ referenced_columns: tuple[OutputColumn, ...]
118
+
119
+
120
+ class ForeignKey(ReferentialCoverage):
121
+ """Referential Coverage onto a Unique Set of the referenced relation."""
@@ -0,0 +1,73 @@
1
+ """Source locations for semantic elements and diagnostics.
2
+
3
+ Origins hold plain values so that no SQLGlot node or connection can escape
4
+ through reporting.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass
10
+
11
+
12
+ SQL = "sql"
13
+
14
+
15
+ @dataclass(frozen=True, order=True)
16
+ class Span:
17
+ """A region of SQL text: where a Property Marker is written. Spans order by position.
18
+
19
+ Lines and columns count from 1, columns in characters; `end_column` is
20
+ one past the region's last character, as SARIF's `endColumn`.
21
+ """
22
+
23
+ line: int
24
+ column: int
25
+ end_line: int
26
+ end_column: int
27
+
28
+ @classmethod
29
+ def of(cls, sql: str, start: int, end: int) -> Span:
30
+ """The region of `sql[start:end]`."""
31
+ line, column = _position(sql, start)
32
+ end_line, end_column = _position(sql, end)
33
+ return cls(line, column, end_line, end_column)
34
+
35
+
36
+ def _position(sql: str, offset: int) -> tuple[int, int]:
37
+ return sql.count("\n", 0, offset) + 1, offset - sql.rfind("\n", 0, offset)
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class Origin:
42
+ """A SQL source span or catalog fact that a semantic element arose from.
43
+
44
+ `line` is the first source line, when known; `span` the exact region,
45
+ when the element is a Property Marker (its `line` is then `line`).
46
+ """
47
+
48
+ kind: str
49
+ detail: str
50
+ line: int | None = None
51
+ span: Span | None = None
52
+
53
+ @classmethod
54
+ def marked(cls, detail: str, span: Span) -> Origin:
55
+ """The Origin of something a Property Marker at `span` asserts or reports."""
56
+ return cls(SQL, detail, span.line, span)
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class AttachmentSite:
61
+ """Where a Property Marker for one JOIN or Select Expression is written.
62
+
63
+ `offset` indexes the SQL text: a join marker is inserted there, before the
64
+ join's first keyword; a trailing column marker is appended there, after
65
+ the Select Expression's last token. `label` names what the site marks
66
+ (`JOIN users AS u`, `view v`, `CTE c`, `subquery s`, `Root Select`);
67
+ anonymous Select Expressions share a label and are told apart by `line`.
68
+ """
69
+
70
+ label: str
71
+ line: int
72
+ offset: int
73
+ trailing: bool
@@ -0,0 +1,299 @@
1
+ """Analysis-scoped memoization and evidence for Python property functions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Generator, Iterable, Iterator
6
+ from contextlib import contextmanager
7
+ from contextvars import ContextVar
8
+ from dataclasses import dataclass, field, fields
9
+ from enum import IntEnum
10
+ from functools import wraps
11
+ from inspect import signature
12
+
13
+ from case_conversion import snake
14
+
15
+ from sqlassert import ir
16
+ from sqlassert.diagnostics import DUPLICATE_DECLARATION, Diagnostic
17
+ from sqlassert.properties import Property
18
+ from sqlassert.reporting import ASSERTED_KINDS, AssertionReport, Outcome, RelationFacts, Report
19
+
20
+
21
+ @dataclass(eq=False)
22
+ class Result[T]:
23
+ """A property function's value and evidence, including collection members."""
24
+
25
+ value: T
26
+ reason: str
27
+ subjects: tuple[object, ...] = ()
28
+ premises: list[Result] = field(default_factory=list)
29
+ kind: str = "structural"
30
+ members: dict = field(default_factory=dict)
31
+
32
+ def __bool__(self) -> bool:
33
+ raise TypeError("Use .value to inspect a result, or & and | to compose Boolean evidence")
34
+
35
+ def __and__(self: Result[bool], other: Result[bool]) -> Result[bool]:
36
+ return all_of((self, other))
37
+
38
+ def __or__(self: Result[bool], other: Result[bool]) -> Result[bool]:
39
+ return any_of((self, other))
40
+
41
+ def explain(self) -> str:
42
+ """Render the evidence, referring back to shared premises by number."""
43
+ lines: list[str] = []
44
+ seen: dict[Result, int] = {}
45
+
46
+ def visit(result: Result, depth: int) -> None:
47
+ indent = " " * depth
48
+ if result in seen:
49
+ lines.append(f"{indent}see #{seen[result]}")
50
+ return
51
+ seen[result] = len(seen) + 1
52
+ match result.value:
53
+ case True:
54
+ state = "PROVED"
55
+ case False:
56
+ state = "UNKNOWN"
57
+ case _:
58
+ state = "VALUE"
59
+ locations = []
60
+ for subject in result.subjects:
61
+ match subject:
62
+ case ir.Node(origin=origin):
63
+ locations.append(origin)
64
+ case _:
65
+ pass # Property arguments may also be sets and other plain values.
66
+ sources = "; ".join(
67
+ f"{origin.detail}" + (f" (line {origin.line})" if origin.line is not None else "")
68
+ for origin in dict.fromkeys(locations)
69
+ )
70
+ suffix = f" — {sources}" if sources else ""
71
+ lines.append(f"{indent}#{seen[result]} {state}: {result.reason}{suffix}")
72
+ for premise in result.premises:
73
+ visit(premise, depth + 1)
74
+
75
+ visit(self, 0)
76
+ return "\n".join(lines)
77
+
78
+
79
+ def unknown(reason: str, *subjects: object) -> Result[bool]:
80
+ return Result(False, reason, subjects, kind="unknown")
81
+
82
+
83
+ def all_of(results: Iterable[Result[bool]]) -> Result[bool]:
84
+ premises = list(results)
85
+ return Result(all(_boolean_values(premises)), "All premises required", premises=premises, kind="all")
86
+
87
+
88
+ def any_of(results: Iterable[Result[bool]]) -> Result[bool]:
89
+ premises = list(results)
90
+ return Result(any(_boolean_values(premises)), "Any alternative suffices", premises=premises, kind="any")
91
+
92
+
93
+ def _boolean_values(results):
94
+ values = []
95
+ for result in results:
96
+ match result.value:
97
+ case True | False:
98
+ values.append(result.value)
99
+ case _:
100
+ raise TypeError("Boolean composition requires Result[bool]")
101
+ return values
102
+
103
+
104
+ _active: ContextVar[Arena] = ContextVar("property_analysis")
105
+ analysis_functions = []
106
+
107
+
108
+ def cache(function):
109
+ """Memoize only within the active analysis, using normalized arguments."""
110
+ parameters = signature(function)
111
+
112
+ @wraps(function)
113
+ def cached(*args, **kwargs):
114
+ arena = current_arena()
115
+ bound = parameters.bind(*args, **kwargs)
116
+ bound.apply_defaults()
117
+ key = (function, tuple(bound.arguments.values()))
118
+ if key in arena.cache:
119
+ return arena.cache[key]
120
+ if key in arena.evaluating:
121
+ raise RuntimeError(
122
+ f"cyclic property dependency: {cached.__name__}. This is an internal sqlassert bug, "
123
+ "not a problem with the analyzed SQL: an analysis broke the Stratum order"
124
+ )
125
+ arena.evaluating.add(key)
126
+ try:
127
+ result = function(*args, **kwargs)
128
+ arena.cache[key] = result
129
+ return result
130
+ finally:
131
+ arena.evaluating.remove(key)
132
+
133
+ return cached
134
+
135
+
136
+ class Stratum(IntEnum):
137
+ """The order in which facts about one relation may use each other.
138
+
139
+ An analysis about relation R may use any fact about R's inputs, but facts
140
+ about R itself only at its own or a lower stratum. The IR's relations form a
141
+ DAG, so this keeps the whole call graph acyclic: the memoized engine cannot
142
+ compute mutually recursive facts, which would need a fixpoint.
143
+
144
+ Equality groups come first: they read only the relation's own conjuncts
145
+ and its inputs' groups. Unique Joins (and Exactly One Joins) follow, so a
146
+ relation's Null Sources may use them; dependencies use Null Sources (a padded side's
147
+ dependencies hold only when the join cannot pad an agreeing row) and Unique
148
+ Joins; closure uses dependencies and non-nullness; Unique Sets and
149
+ Functional Dependency assertions are closure questions; Foreign Keys use
150
+ Unique Sets. Enumerated Domains come last: they read equality groups and,
151
+ for a CASE's unreachable ELSE, non-nullness. A cycle is an internal sqlassert bug, not a problem
152
+ with the analyzed SQL.
153
+ """
154
+
155
+ EQUALITY_GROUP = 5
156
+ UNIQUE_JOIN = 10
157
+ NON_NULL = 20
158
+ FUNCTIONAL_DEPENDENCY = 30
159
+ CLOSURE = 40
160
+ UNIQUE_SET = 50
161
+ FOREIGN_KEY = 60
162
+ DOMAIN = 70
163
+
164
+
165
+ def analysis(stratum: Stratum):
166
+ """Cache and name an analysis function; public ones match Property names and fields."""
167
+
168
+ def decorate(function):
169
+ parameters = signature(function)
170
+
171
+ @cache
172
+ @wraps(function)
173
+ def evaluate(*args, **kwargs):
174
+ bound = parameters.bind(*args, **kwargs)
175
+ bound.apply_defaults()
176
+ arena = current_arena()
177
+ relation = _subject_relation(arena.program, bound.arguments.values())
178
+ if relation is not None:
179
+ for active, active_stratum, name in arena.active:
180
+ assert active is not relation or stratum <= active_stratum, (
181
+ f"{function.__name__} ({stratum.name}) called from {name} ({active_stratum.name}) "
182
+ "about the same relation: a fact may only use facts at its own or a lower stratum"
183
+ )
184
+ arena.active.append((relation, stratum, function.__name__))
185
+ try:
186
+ arguments = tuple(sorted(bound.arguments.items()))
187
+ accepted = arena.accepted.get((function.__name__, arguments), ())
188
+ result = any_of(accepted) if accepted else function(*args, **kwargs)
189
+ finally:
190
+ arena.active.pop()
191
+ return Result(result.value, function.__name__, tuple(bound.arguments.values()), [result], "claim", result.members)
192
+
193
+ evaluate.stratum = stratum
194
+ analysis_functions.append(evaluate)
195
+ return evaluate
196
+
197
+ return decorate
198
+
199
+
200
+ def _subject_relation(program: ir.Program, arguments: Iterable[object]) -> ir.RelationExpr | None:
201
+ """The relation an analysis call is about: its first argument that names one."""
202
+ for argument in arguments:
203
+ match argument:
204
+ case ir.RelationExpr():
205
+ return argument
206
+ case ir.OutputColumn():
207
+ return program.column_to_parent_relation_index.get(argument)
208
+ case frozenset() | tuple():
209
+ return program.relation_of(frozenset(argument))
210
+ case Result(value=value) if isinstance(getattr(value, "relation", None), ir.RelationExpr):
211
+ return value.relation
212
+ case _:
213
+ pass # Scalar expressions and plain values are not about one relation.
214
+ return None
215
+
216
+
217
+ def current_arena() -> Arena:
218
+ return _active.get()
219
+
220
+
221
+ class Arena:
222
+ """One immutable program's knowledge, memoized values, and evidence graph."""
223
+
224
+ def __init__(self, program: ir.Program, knowledge: tuple[Property, ...]):
225
+ self.cache: dict[tuple, object] = {}
226
+ self.evaluating: set[tuple] = set()
227
+ self.active: list[tuple[ir.RelationExpr | None, Stratum, str]] = []
228
+ self.accepted: dict[tuple, tuple[Result[bool], ...]] = {}
229
+ self.program = program
230
+ self.knowledge = (*knowledge, *program.declarations)
231
+ # Schema Knowledge is accepted; Property Declarations are the author's trusted claims.
232
+ sources = [("Accepted", item) for item in knowledge] + [("Declared", item) for item in program.declarations]
233
+ for label, item in sources:
234
+ values = tuple(getattr(item, field.name) for field in fields(item))
235
+ subjects = []
236
+ for value in values:
237
+ match value:
238
+ case frozenset() | set() | list() | tuple():
239
+ subjects.extend(value)
240
+ case _:
241
+ subjects.append(value)
242
+ evidence = Result(True, f"{label} {type(item).__name__}", (item, *subjects), kind="accepted")
243
+ for cls in Property._subclasses:
244
+ if cls not in type(item).__mro__:
245
+ continue
246
+ key = _accepted_key(cls, item)
247
+ self.accepted[key] = (*self.accepted.get(key, ()), evidence)
248
+
249
+ def accepted_evidence(self, item: Property) -> tuple[Result[bool], ...]:
250
+ """The evidence accepting `item` as Knowledge, empty when it is not."""
251
+ return self.accepted.get(_accepted_key(type(item), item), ())
252
+
253
+ def prove(self, property: Property) -> Result[bool]:
254
+ values = {field.name: getattr(property, field.name) for field in fields(property)}
255
+ evaluator, = (function for function in analysis_functions if function.__name__ == snake(type(property).__name__))
256
+ return evaluator(**values)
257
+
258
+
259
+ def _accepted_key(cls: type[Property], item: Property) -> tuple:
260
+ """How `item`, as an instance of `cls`, is looked up among accepted results."""
261
+ return (snake(cls.__name__), tuple(sorted((field.name, getattr(item, field.name)) for field in fields(cls))))
262
+
263
+
264
+ class Engine:
265
+ @contextmanager
266
+ def session(self, program: ir.Program, knowledge: tuple[Property, ...] = ()) -> Generator[Arena]:
267
+ assert _active.get(None) is None, "An analysis arena is already active"
268
+ # Importing registers analysis functions; inference remains in rules/.
269
+ from sqlassert.rules import domain, equality, exactly_one, foreign_key, join_cardinality, nullability, uniqueness # noqa: F401
270
+
271
+ arena = Arena(program, knowledge)
272
+ token = _active.set(arena)
273
+ try:
274
+ yield arena
275
+ finally:
276
+ _active.reset(token)
277
+
278
+ def run(
279
+ self, program: ir.Program, knowledge: tuple[Property, ...] = (), diagnostics: tuple[Diagnostic, ...] = (),
280
+ warnings: tuple[Diagnostic, ...] = (),
281
+ ) -> Report:
282
+ from sqlassert.rules.uniqueness import minimal_keys
283
+
284
+ with self.session(program, knowledge) as arena:
285
+ assertions = []
286
+ for index, assertion in enumerate(program.assertions, 1):
287
+ evidence = arena.prove(assertion.property)
288
+ if any(diagnostic.code == DUPLICATE_DECLARATION for diagnostic in diagnostics):
289
+ evidence = evidence & unknown("Duplicate declarations prevent accepting a proof", assertion)
290
+ assertions.append(AssertionReport(
291
+ f"assert_{index}", Outcome.PROVED if evidence.value else Outcome.UNKNOWN, assertion.origin,
292
+ ASSERTED_KINDS[type(assertion.property)], evidence,
293
+ ))
294
+ facts = {}
295
+ for relation in program.named_relations:
296
+ facts[relation.report_name.lower()] = tuple(
297
+ tuple(column.name for column in key) for key in minimal_keys(relation)
298
+ )
299
+ return Report(tuple(assertions), tuple(diagnostics), RelationFacts(facts), tuple(warnings))
sqlassert/reporting.py ADDED
@@ -0,0 +1,102 @@
1
+ """The durable Report an analysis returns: assertion outcomes, diagnostics, and relation facts.
2
+
3
+ The Report holds plain values only, plus each assertion's evidence. It never prints.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Sequence
9
+ from dataclasses import dataclass, field
10
+ from enum import Enum
11
+ from typing import TYPE_CHECKING
12
+
13
+ from sqlassert import properties as props
14
+ from sqlassert.diagnostics import Diagnostic
15
+ from sqlassert.provenance import Origin
16
+
17
+ if TYPE_CHECKING:
18
+ from sqlassert.python_engine import Result
19
+
20
+
21
+ class Outcome(Enum):
22
+ """PROVED or UNKNOWN. UNKNOWN fails an assertion but is not a Disproof."""
23
+
24
+ PROVED = "proved"
25
+ UNKNOWN = "unknown"
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class AssertionReport:
30
+ """One assertion's outcome. `kind` is the marker that states it
31
+ (`ASSERTED_KINDS`), so a failure names what was not proved."""
32
+
33
+ assertion_id: str
34
+ outcome: Outcome
35
+ origin: Origin
36
+ kind: str
37
+ evidence: Result[bool] | None = field(default=None, compare=False)
38
+
39
+
40
+ # The marker each assertable Property is written as, in the words of its `/**ASSERT ...**/`.
41
+ ASSERTED_KINDS: dict[type[props.Property], str] = {
42
+ props.NonNullColumns: "not-null",
43
+ props.NonNullElements: "not-null-elements",
44
+ props.UniqueSet: "unique",
45
+ props.NonNullUniqueSet: "not-null-unique", # also written PRIMARY KEY
46
+ props.FunctionalDependency: "determines",
47
+ props.EnumeratedDomain: "enum",
48
+ props.ReferentialCoverage: "foreign-key",
49
+ props.ForeignKey: "foreign-key",
50
+ props.ExhaustiveCase: "exhaustive",
51
+ props.UniqueJoin: "unique-join",
52
+ props.ManyToOneJoin: "many-to-one-join",
53
+ props.OneToManyJoin: "one-to-many-join",
54
+ props.OneToOneJoin: "one-to-one-join",
55
+ props.ExactlyOneJoin: "exactly-one-join",
56
+ }
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class RelationFacts:
61
+ """What was proved about every Named Relation in one analysis.
62
+
63
+ Tables and views use their declared name; CTEs use a ``CTE_``-prefixed
64
+ report label. Anonymous Relation Expressions are omitted: ask about the
65
+ assertion they feed into instead.
66
+
67
+ Holds only Unique Sets for now; further properties join it as typed
68
+ methods, the same way, rather than as a generic ask-anything query.
69
+ """
70
+
71
+ _unique_sets: dict[str, tuple[tuple[str, ...], ...]] = field(default_factory=dict)
72
+
73
+ def unique_sets(self, relation: str) -> tuple[tuple[str, ...], ...]:
74
+ """The minimal Unique Sets proved for `relation`, smallest first.
75
+
76
+ Every minimal set of up to three columns; when none is that small,
77
+ one minimal set. A superset of any of them is unique too."""
78
+ return self._unique_sets.get(relation.lower(), ())
79
+
80
+ def is_unique(self, relation: str, columns: Sequence[str]) -> bool:
81
+ """Whether `columns` is guaranteed unique on `relation`: some proved
82
+ Unique Set's members are all among `columns`."""
83
+ candidate = {column.lower() for column in columns}
84
+ return any(set(unique_set) <= candidate for unique_set in self.unique_sets(relation))
85
+
86
+
87
+ @dataclass(frozen=True)
88
+ class Report:
89
+ assertions: tuple[AssertionReport, ...] = ()
90
+ diagnostics: tuple[Diagnostic, ...] = ()
91
+ facts: RelationFacts = field(default_factory=RelationFacts)
92
+ warnings: tuple[Diagnostic, ...] = ()
93
+
94
+ @property
95
+ def proved(self) -> bool:
96
+ """Every assertion proved, and nothing about the program was unsupported.
97
+
98
+ Warnings do not count: they explain UNKNOWN outcomes, never cause them."""
99
+ return not self.diagnostics and all(
100
+ assertion.outcome is Outcome.PROVED for assertion in self.assertions
101
+ )
102
+
@@ -0,0 +1,19 @@
1
+ # Rule Style Guide
2
+
3
+ Rules are analysis functions. Each returns `Result[Value]`: `.value`
4
+ is the computed Value and the remaining fields directly represent its evidence.
5
+ `@analysis(stratum)` provides declaration lookup and analysis-scoped caching for public and
6
+ internal analysis functions. Its `Stratum` orders facts about one relation: an analysis may
7
+ use facts about the same relation only at its own or a lower stratum, which keeps the
8
+ call graph acyclic; the decorator asserts this on every call. Every concrete public `Property` class has one
9
+ snake-case public analysis function whose parameters match its fields. Internal
10
+ analysis functions start with `_`. `ColumnSet`, `Closure`, and `RowIdentity` are
11
+ ordinary derived values defined in these rules. Uniqueness is a closure question:
12
+ derive dependencies a relation introduces in `_functional_dependencies`, and let
13
+ `_closure` reach into inputs; never copy an input's facts up to its consumer.
14
+ Use explicit matches for semantic dispatch, and fail on unhandled node types. Keep IR traversal and set operations in small helpers so analysis
15
+ functions state their semantic rule directly. Use `&` / `|` or `all_of` /
16
+ `any_of` to preserve evidence; Python's `and` / `or` deliberately reject
17
+ `Result` values. Use `.value` for every result, including Boolean results
18
+ (false means unproved). `&` / `|` and `all_of` / `any_of` compose only
19
+ `Result[bool]` values and retain their evidence.
@@ -0,0 +1,11 @@
1
+ """Python analysis functions establish public relational properties.
2
+
3
+ Equality groups say which columns carry one value (equality), for facts
4
+ about values.
5
+
6
+ Null sources say why a column may be NULL (nullability). Functional
7
+ dependencies and their closure decide uniqueness: a column set is a Unique
8
+ Set when its closure reaches the relation's Row Identity, and a join is
9
+ many to one when the right columns ON binds reach the right input's
10
+ (uniqueness, join_cardinality). Foreign Keys and Exactly One Joins build on both.
11
+ """