ostrict 0.3.0__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.
ostrict/__init__.py ADDED
@@ -0,0 +1,22 @@
1
+ """ostrict: strict semantic views, linted at load time and compiled
2
+ deterministically to SQL. The view is a blueprint only — never materialized."""
3
+
4
+ from .models.ast import SemanticView
5
+ from .models.errors import CompilerError, LintFinding, Severity
6
+ from .models.query import CompiledQuery, Filter, QueryResult, SemanticQueryRequest
7
+ from .parsers import load_view, load_views
8
+
9
+ __version__ = "0.3.0"
10
+ __all__ = [
11
+ "CompiledQuery",
12
+ "CompilerError",
13
+ "Filter",
14
+ "LintFinding",
15
+ "QueryResult",
16
+ "SemanticQueryRequest",
17
+ "SemanticView",
18
+ "Severity",
19
+ "load_view",
20
+ "load_views",
21
+ "__version__",
22
+ ]
ostrict/cli.py ADDED
@@ -0,0 +1,155 @@
1
+ """Command line: `ostrict lint|compile|eval|export|import`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import sys
8
+ from pathlib import Path
9
+
10
+ import yaml
11
+
12
+ from .linter import LintConfig, lint
13
+ from .models.errors import CompilerError
14
+ from .parsers import load_view, load_views
15
+
16
+
17
+ def _lint_config(path: str | None) -> LintConfig | None:
18
+ if not path:
19
+ return None
20
+ cfg = (yaml.safe_load(Path(path).read_text()) or {}).get("lint") or {}
21
+ return LintConfig(
22
+ security_allowlist=tuple(cfg.get("security_allowlist") or ()),
23
+ no_pk_tables=tuple(cfg.get("no_pk_tables") or ()),
24
+ no_primary_date_tables=tuple(cfg.get("no_primary_date_tables") or ()),
25
+ )
26
+
27
+
28
+ def _views_from(paths: list[str]):
29
+ for path in paths:
30
+ p = Path(path)
31
+ if p.is_dir():
32
+ yield from load_views(p).values()
33
+ else:
34
+ yield load_view(p)
35
+
36
+
37
+ def cmd_lint(args) -> int:
38
+ worst = 0
39
+ for view in _views_from(args.paths):
40
+ report = lint(view, _lint_config(args.config))
41
+ print(report.render())
42
+ if not report.ok:
43
+ worst = 1
44
+ return worst
45
+
46
+
47
+ def cmd_compile(args) -> int:
48
+ from .compiler import compile_semantic_query
49
+ from .models.query import SemanticQueryRequest
50
+
51
+ view = load_view(args.view)
52
+ request = SemanticQueryRequest(
53
+ metrics=args.metric,
54
+ dimensions=args.dimension,
55
+ filters=[json.loads(f) for f in args.filter],
56
+ order_by=args.order_by,
57
+ limit=args.limit,
58
+ )
59
+ compiled = compile_semantic_query(view, request, dialect=args.dialect, lint_config=_lint_config(args.config))
60
+ print(compiled.sql)
61
+ return 0
62
+
63
+
64
+ def cmd_eval(args) -> int:
65
+ from .eval.runner import run_eval
66
+
67
+ report = run_eval(args.cases, seed=args.seed)
68
+ print(report.render())
69
+ return 0 if report.ok else 1
70
+
71
+
72
+ def cmd_export(args) -> int:
73
+ from .interchange import export_osi
74
+
75
+ out = export_osi(load_view(args.view), fmt=args.format, strip_extensions=args.strip_extensions)
76
+ for w in out.warnings:
77
+ print(f"warning: {w}", file=sys.stderr)
78
+ if args.output:
79
+ Path(args.output).write_text(out.text)
80
+ else:
81
+ print(out.text, end="")
82
+ return 0
83
+
84
+
85
+ def cmd_import(args) -> int:
86
+ from .interchange import import_osi, to_native_yaml
87
+
88
+ view = import_osi(Path(args.file), validate=False)
89
+ if not args.no_lint:
90
+ report = lint(view, _lint_config(args.config))
91
+ if report.findings:
92
+ print(report.render(), file=sys.stderr)
93
+ if not report.ok:
94
+ return 1 # ERROR findings refuse the conversion; --no-lint writes it for inspection
95
+ text = to_native_yaml(view)
96
+ if args.output:
97
+ Path(args.output).write_text(text)
98
+ else:
99
+ print(text, end="")
100
+ return 0
101
+
102
+
103
+ def main(argv: list[str] | None = None) -> int:
104
+ p = argparse.ArgumentParser(prog="ostrict")
105
+ sub = p.add_subparsers(dest="cmd", required=True)
106
+
107
+ sp = sub.add_parser("lint", help="lint semantic view files or folders (SV-R1..R10)")
108
+ sp.add_argument("paths", nargs="+")
109
+ sp.add_argument("--config", default=None, help="strict_semantic.yml whose lint: section to apply")
110
+ sp.set_defaults(fn=cmd_lint)
111
+
112
+ sp = sub.add_parser("compile", help="compile a structured request to SQL (no execution)")
113
+ sp.add_argument("view")
114
+ sp.add_argument("-m", "--metric", action="append", default=[])
115
+ sp.add_argument("-d", "--dimension", action="append", default=[])
116
+ sp.add_argument("-f", "--filter", action="append", default=[], help='JSON filter object')
117
+ sp.add_argument("-o", "--order-by", action="append", default=[])
118
+ sp.add_argument("-l", "--limit", type=int)
119
+ sp.add_argument("--dialect", default=None, help="bigquery | duckdb | snowflake | postgres")
120
+ sp.add_argument("--config", default=None, help="strict_semantic.yml whose lint: section to apply")
121
+ sp.set_defaults(fn=cmd_compile)
122
+
123
+ sp = sub.add_parser("eval", help="run a Golden Questions YAML deterministically (SV-R10.2)")
124
+ sp.add_argument("cases", help="golden questions YAML file")
125
+ sp.add_argument("--seed", default=None, help="SQL file to seed the DuckDB fixture database")
126
+ sp.set_defaults(fn=cmd_eval)
127
+
128
+ sp = sub.add_parser("export", help="export a .sql/.yaml view as an OSI (Open Semantic Interchange) document")
129
+ sp.add_argument("view")
130
+ sp.add_argument("--format", choices=("yaml", "json"), default="yaml")
131
+ sp.add_argument("-o", "--output", default=None, help="output file (stdout if omitted)")
132
+ sp.add_argument(
133
+ "--strip-extensions",
134
+ action="store_true",
135
+ help="emit vanilla OSI without custom_extensions; stripped guardrails are warned to stderr",
136
+ )
137
+ sp.set_defaults(fn=cmd_export)
138
+
139
+ sp = sub.add_parser("import", help="convert an OSI YAML/JSON file to the native spec (linted by default)")
140
+ sp.add_argument("file")
141
+ sp.add_argument("-o", "--output", default=None, help="output file (stdout if omitted)")
142
+ sp.add_argument("--no-lint", action="store_true", help="skip the SV-R1..R10 gate, for inspection only")
143
+ sp.add_argument("--config", default=None, help="strict_semantic.yml whose lint: section to apply")
144
+ sp.set_defaults(fn=cmd_import)
145
+
146
+ args = p.parse_args(argv)
147
+ try:
148
+ return args.fn(args)
149
+ except CompilerError as e:
150
+ print(f"error [{e.code}]: {e}" + (f"\nhint: {e.hint}" if e.hint else ""), file=sys.stderr)
151
+ return 2
152
+
153
+
154
+ if __name__ == "__main__":
155
+ sys.exit(main())
@@ -0,0 +1,123 @@
1
+ """Compile/execute pipeline with lint enforcement and plugin hooks."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import weakref
6
+ from collections.abc import Iterable
7
+ from typing import TYPE_CHECKING
8
+
9
+ from ..models.ast import SemanticView
10
+ from ..models.query import CompiledQuery, Filter, QueryResult, SemanticQueryRequest
11
+ from ..plugins.base import CompilerPlugin
12
+ from .guardrails import CompileConfig
13
+ from .resolver import Graph, build_graph
14
+ from .sql_builder import build_dimension_values_query, build_query
15
+
16
+ if TYPE_CHECKING:
17
+ from ..linter import LintConfig
18
+
19
+
20
+ def _ensure_valid(view, lint_config):
21
+ from ..linter import ensure_valid # deferred: the linter itself uses compiler.resolver
22
+
23
+ return ensure_valid(view, lint_config)
24
+
25
+
26
+ def _notify_model_loaded(view: SemanticView, plugins: Iterable[CompilerPlugin]) -> None:
27
+ """Fire on_model_loaded once per (plugin instance, view object).
28
+
29
+ A reloaded spec is a new object, so it fires again — matching "model
30
+ loaded". Views are unhashable, so the memo is id-keyed with a weakref
31
+ guard against id reuse."""
32
+ for p in plugins:
33
+ seen: dict[int, weakref.ref] = p.__dict__.setdefault("_ss_models_seen", {})
34
+ ref = seen.get(id(view))
35
+ if ref is not None and ref() is view:
36
+ continue
37
+ if len(seen) > 64: # prune refs whose views were garbage-collected
38
+ for k in [k for k, r in seen.items() if r() is None]:
39
+ del seen[k]
40
+ seen[id(view)] = weakref.ref(view)
41
+ p.on_model_loaded(view)
42
+
43
+ __all__ = [
44
+ "CompileConfig",
45
+ "Graph",
46
+ "build_graph",
47
+ "compile_dimension_values",
48
+ "compile_semantic_query",
49
+ "execute_semantic_query",
50
+ ]
51
+
52
+
53
+ def compile_semantic_query(
54
+ view: SemanticView,
55
+ request: SemanticQueryRequest | dict,
56
+ dialect: str | None = None,
57
+ plugins: Iterable[CompilerPlugin] = (),
58
+ config: CompileConfig | None = None,
59
+ lint_config: LintConfig | None = None,
60
+ ) -> CompiledQuery:
61
+ if isinstance(request, dict):
62
+ request = SemanticQueryRequest.model_validate(request)
63
+ _ensure_valid(view, lint_config) # ERROR findings block compilation
64
+ _notify_model_loaded(view, plugins)
65
+ for p in plugins:
66
+ request = p.before_compile(view, request) or request
67
+ compiled = build_query(view, request, dialect or view.dialect, config or CompileConfig())
68
+ for p in plugins:
69
+ compiled = p.after_compile(view, request, compiled) or compiled
70
+ return compiled
71
+
72
+
73
+ def compile_dimension_values(
74
+ view: SemanticView,
75
+ dimension: str,
76
+ search: str | None = None,
77
+ filters: Iterable[Filter | dict] = (),
78
+ limit: int = 50,
79
+ dialect: str | None = None,
80
+ plugins: Iterable[CompilerPlugin] = (),
81
+ config: CompileConfig | None = None,
82
+ lint_config: LintConfig | None = None,
83
+ ) -> CompiledQuery:
84
+ _ensure_valid(view, lint_config)
85
+ flts = [f if isinstance(f, Filter) else Filter.model_validate(f) for f in filters]
86
+ # Plugins see value lookups too, or RBAC filters injected in before_compile
87
+ # would not gate get_dimension_values. Hooks run on a synthetic request.
88
+ _notify_model_loaded(view, plugins)
89
+ request = SemanticQueryRequest(dimensions=[dimension], filters=flts, limit=limit)
90
+ for p in plugins:
91
+ request = p.before_compile(view, request) or request
92
+ return build_dimension_values_query(
93
+ view, dimension, search, list(request.filters),
94
+ request.limit if request.limit is not None else limit,
95
+ dialect or view.dialect, config or CompileConfig(),
96
+ )
97
+
98
+
99
+ def execute_semantic_query(
100
+ view: SemanticView,
101
+ request: SemanticQueryRequest | dict,
102
+ connector,
103
+ plugins: Iterable[CompilerPlugin] = (),
104
+ config: CompileConfig | None = None,
105
+ lint_config: LintConfig | None = None,
106
+ ) -> QueryResult:
107
+ if isinstance(request, dict):
108
+ request = SemanticQueryRequest.model_validate(request)
109
+ plugins = list(plugins)
110
+ compiled = compile_semantic_query(
111
+ view, request, dialect=connector.dialect, plugins=plugins, config=config, lint_config=lint_config
112
+ )
113
+ rows = connector.execute(compiled.sql)
114
+ cfg = config or CompileConfig()
115
+ result = QueryResult(
116
+ columns=compiled.columns,
117
+ rows=rows,
118
+ truncated=len(rows) >= (request.limit or cfg.default_limit),
119
+ sql=compiled.sql,
120
+ )
121
+ for p in plugins:
122
+ p.on_query_executed(view, request, compiled, result)
123
+ return result
@@ -0,0 +1,153 @@
1
+ """FinOps and correctness guardrails applied at compile time.
2
+
3
+ - SV-R10.7 metric-required (no raw-row dumps)
4
+ - SV-R7 snapshot tables need a point-in-time binding
5
+ - partition filter requirement + pruning bounds
6
+ - LIMIT injection and cap
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import datetime as dt
12
+ from dataclasses import dataclass
13
+ from typing import Any
14
+
15
+ from sqlglot import exp
16
+
17
+ from ..models.ast import Dimension, LogicalTable, SemanticView
18
+ from ..models.errors import (
19
+ ERR_EXCESSIVE_LIMIT,
20
+ ERR_METRIC_REQUIRED,
21
+ ERR_MISSING_PARTITION_FILTER,
22
+ ERR_SNAPSHOT_AGGREGATION_VIOLATION,
23
+ CompilerError,
24
+ )
25
+ from ..models.query import Filter
26
+
27
+ # upper-bound slack per grain: pruning windows must be a superset of the data asked for
28
+ _GRAIN_DAYS = {"hour": 1, "day": 1, "week": 7, "month": 31, "quarter": 92, "year": 366}
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class CompileConfig:
33
+ default_limit: int = 1000
34
+ max_limit: int = 10000
35
+ allow_full_scan: bool = False # authorized admins only: waives the partition requirement
36
+
37
+
38
+ def require_metrics(metrics: list) -> None:
39
+ if not metrics:
40
+ raise CompilerError(
41
+ ERR_METRIC_REQUIRED,
42
+ "a semantic query needs at least one metric; raw-row dumps are not served",
43
+ hint="to discover filter values, use get_dimension_values(dimension, search, limit)",
44
+ )
45
+
46
+
47
+ def resolve_limit(limit: int | None, config: CompileConfig) -> int:
48
+ if limit is None:
49
+ return config.default_limit
50
+ if not isinstance(limit, int) or limit < 1:
51
+ raise CompilerError(ERR_EXCESSIVE_LIMIT, f"limit must be a positive integer, got {limit!r}")
52
+ if limit > config.max_limit:
53
+ raise CompilerError(
54
+ ERR_EXCESSIVE_LIMIT, f"limit {limit} exceeds the configured cap of {config.max_limit}"
55
+ )
56
+ return limit
57
+
58
+
59
+ def _parse_iso(value: Any) -> dt.datetime | None:
60
+ if not isinstance(value, str):
61
+ return None
62
+ try:
63
+ return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
64
+ except ValueError:
65
+ return None
66
+
67
+
68
+ def _shift(value: str, days: int) -> str:
69
+ t = _parse_iso(value) + dt.timedelta(days=days)
70
+ return t.date().isoformat() if len(value) == 10 else t.isoformat(sep=" ")
71
+
72
+
73
+ def _bounds_from(filters: list[tuple[Dimension, str | None, Filter]], dimension: str):
74
+ """(lower, upper) ISO-string bound lists implied by filters on `dimension`."""
75
+ lowers: list[str] = []
76
+ uppers: list[str] = []
77
+ for dim, grain, flt in filters:
78
+ if dim.name != dimension:
79
+ continue
80
+ op, v = flt.op.lower(), flt.value
81
+ slack = _GRAIN_DAYS.get(grain, 0)
82
+ if op == "between" and isinstance(v, (list, tuple)) and len(v) == 2:
83
+ lo, hi = v
84
+ if _parse_iso(lo):
85
+ lowers.append(str(lo))
86
+ if _parse_iso(hi):
87
+ uppers.append(_shift(str(hi), slack))
88
+ elif op in ("=", ">=", ">") and _parse_iso(v):
89
+ lowers.append(str(v))
90
+ if op == "=":
91
+ uppers.append(_shift(str(v), slack))
92
+ elif op in ("<", "<=") and _parse_iso(v):
93
+ uppers.append(str(v))
94
+ elif op == "in" and isinstance(v, (list, tuple)) and v and all(_parse_iso(x) for x in v):
95
+ vals = sorted((str(x) for x in v), key=_parse_iso)
96
+ lowers.append(vals[0])
97
+ uppers.append(_shift(vals[-1], slack))
98
+ return lowers, uppers
99
+
100
+
101
+ def snapshot_binding(
102
+ view: SemanticView, table: LogicalTable, dims: list[tuple[Dimension, str | None]],
103
+ dim_filters: list[tuple[Dimension, str | None, Filter]],
104
+ ) -> None:
105
+ """SV-R7: a snapshot table is queried at a point in time, or per snapshot date."""
106
+ date_dim = next(
107
+ (d for d in view.dimensions if d.table == table.name and d.expr == table.primary_date), None
108
+ )
109
+ if date_dim is None: # the linter already demands this; defensive
110
+ raise CompilerError(
111
+ ERR_SNAPSHOT_AGGREGATION_VIOLATION,
112
+ f"snapshot table '{table.name}' exposes no dimension on '{table.primary_date}'",
113
+ )
114
+ pinned = any(
115
+ d.name == date_dim.name and f.op == "=" and grain in (None, "day")
116
+ for d, grain, f in dim_filters
117
+ )
118
+ per_date = any(d.name == date_dim.name and grain in (None, "day") for d, grain in dims)
119
+ if not (pinned or per_date):
120
+ raise CompilerError(
121
+ ERR_SNAPSHOT_AGGREGATION_VIOLATION,
122
+ f"metrics on snapshot table '{table.name}' must be pinned to one date "
123
+ f"(filter {date_dim.name} = 'YYYY-MM-DD') or grouped by '{date_dim.name}'; "
124
+ "summing snapshots across dates double-counts",
125
+ )
126
+
127
+
128
+ def partition_predicates(
129
+ view: SemanticView, table: LogicalTable,
130
+ dim_filters: list[tuple[Dimension, str | None, Filter]],
131
+ config: CompileConfig,
132
+ ) -> list[exp.Expression]:
133
+ """Require a bounding filter on the partition dimension and derive pruning
134
+ predicates on the physical partition column (pushed into the table subquery,
135
+ which is the only placement BigQuery honors for joined tables)."""
136
+ p = table.partition
137
+ if p is None:
138
+ return []
139
+ lowers, uppers = _bounds_from(dim_filters, p.dimension)
140
+ if not lowers and not config.allow_full_scan:
141
+ raise CompilerError(
142
+ ERR_MISSING_PARTITION_FILTER,
143
+ f"table '{table.name}' is partitioned; add a bounding filter on '{p.dimension}' "
144
+ "(=, >=, >, between or in with date values)",
145
+ hint=f"e.g. {{\"field\": \"{p.dimension}\", \"op\": \">=\", \"value\": \"2026-01-01\"}}",
146
+ )
147
+ col = exp.column(p.column, table=table.name)
148
+ out: list[exp.Expression] = []
149
+ for v in lowers:
150
+ out.append(exp.GTE(this=col.copy(), expression=exp.convert(_shift(v, -p.lookback_days))))
151
+ for v in uppers:
152
+ out.append(exp.LTE(this=col.copy(), expression=exp.convert(_shift(v, p.lookahead_days))))
153
+ return out
@@ -0,0 +1,90 @@
1
+ """Directed child->parent join graph: reachability, unique paths, structural findings.
2
+
3
+ The graph rules are what make every compiled query safe:
4
+ - edges only go child (many) -> parent (one) (SV-R3.1)
5
+ - at most one path between any two tables (SV-R3.5)
6
+ - queries only ever walk upward along these paths (SV-R3.4, enforced in sql_builder)
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass, field
12
+
13
+ from ..models.ast import Relationship, SemanticView
14
+ from ..models.errors import (
15
+ ERR_AMBIGUOUS_MULTI_PATH,
16
+ ERR_CYCLIC_RELATIONSHIP,
17
+ LintFinding,
18
+ Severity,
19
+ )
20
+
21
+ Path = tuple[Relationship, ...]
22
+
23
+
24
+ @dataclass
25
+ class Graph:
26
+ # reach[t][u] = the unique child->parent path from t up to ancestor u
27
+ reach: dict[str, dict[str, Path]]
28
+ findings: list[LintFinding] = field(default_factory=list)
29
+
30
+ def path_names(self, start: str, target: str) -> list[str]:
31
+ return [r.name for r in self.reach[start].get(target, ())]
32
+
33
+
34
+ def build_graph(view: SemanticView) -> Graph:
35
+ edges: dict[str, list[Relationship]] = {t: [] for t in view.tables}
36
+ findings: list[LintFinding] = []
37
+
38
+ for r in view.relationships:
39
+ if r.child == r.parent:
40
+ findings.append(
41
+ LintFinding(
42
+ rule="SV-R3.1",
43
+ code=ERR_CYCLIC_RELATIONSHIP,
44
+ severity=Severity.ERROR,
45
+ message=f"relationship '{r.name}' references its own table '{r.child}'; "
46
+ "model a role-playing alias table instead",
47
+ where=f"relationship {r.name}",
48
+ )
49
+ )
50
+ continue
51
+ edges[r.child].append(r)
52
+
53
+ def walk(start: str, paths: dict[str, Path], node: str, path: Path, seen: tuple[str, ...]) -> None:
54
+ for r in edges[node]:
55
+ if r.parent in seen:
56
+ chain = " -> ".join((*seen, r.parent))
57
+ findings.append(
58
+ LintFinding(
59
+ rule="SV-R3.1",
60
+ code=ERR_CYCLIC_RELATIONSHIP,
61
+ severity=Severity.ERROR,
62
+ message=f"relationships form a cycle: {chain}",
63
+ where=f"relationship {r.name}",
64
+ )
65
+ )
66
+ continue
67
+ if r.parent in paths:
68
+ a = " -> ".join((start, *(x.parent for x in paths[r.parent])))
69
+ b = " -> ".join((start, *(x.parent for x in (*path, r))))
70
+ findings.append(
71
+ LintFinding(
72
+ rule="SV-R3.5",
73
+ code=ERR_AMBIGUOUS_MULTI_PATH,
74
+ severity=Severity.ERROR,
75
+ message=f"two join paths from '{start}' to '{r.parent}' ({a} | {b}); "
76
+ "keep one relationship or introduce a role-playing alias table",
77
+ where=f"table {start}",
78
+ )
79
+ )
80
+ continue
81
+ paths[r.parent] = (*path, r)
82
+ walk(start, paths, r.parent, (*path, r), (*seen, r.parent))
83
+
84
+ reach: dict[str, dict[str, Path]] = {}
85
+ for start in view.tables:
86
+ paths: dict[str, Path] = {}
87
+ walk(start, paths, start, (), (start,))
88
+ reach[start] = paths
89
+
90
+ return Graph(reach=reach, findings=list(dict.fromkeys(findings)))