strictspec 0.1.0__py3-none-any.whl

strictspec/__init__.py

@@ -0,0 +1,437 @@
+"""strictspec -- the public Python runtime.
+
+The stable surface that generated strictspec validator code imports. It
+re-exports the diagnostics model, document loading for the three syntaxes, the
+version-pairing guard, the tagged document value (the second entry point) with
+its coercers, and the constraint-engine entry (validation is driven by the
+shared emitter IR, so a generated Python validator runs the identical checks as
+the reference interpreter and the Go runtime).
+
+Invariants: no lenient modes; loading and validation are inseparable; unknown
+keys are always a hard error; there is no severity -- every diagnostic is an
+error; raw untagged dicts are never a validation input (tagged values only).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+from . import _diag as _diag
+from . import _doc as _doc
+from . import _ir as _ir
+from . import _jsondoc as _jsondoc
+from . import _render as _render
+from . import _schema as _schema
+from . import _strdecode as _strdecode
+from . import _tomldoc as _tomldoc
+
+# Version is the strictspec release this runtime was built at. Generated code is
+# paired to it exactly (see require_runtime_version). rlsbl bumps this
+# __version__ in source on release (Python pypi target); the version-pairing
+# test asserts it matches pyproject, so drift is impossible.
+__version__ = "0.1.0"
+Version = __version__
+
+__all__ = [
+    "Version",
+    "__version__",
+    "Diagnostic",
+    "Result",
+    "Program",
+    "Value",
+    "KV",
+    "Kind",
+    "compile_embedded",
+    "load_value",
+    "load_values",
+    "check_runtime_version",
+    "require_runtime_version",
+    "PairingError",
+    "version_gate",
+    "GateResult",
+]
+
+
+class PairingError(Exception):
+    """Raised by require_runtime_version on a version-pairing mismatch."""
+
+
+def check_runtime_version(generated_by: str) -> str | None:
+    """Return a structured remediation message if generated code pinned to
+    generated_by is not paired with this runtime, else None. Under the
+    always-latest dependency rule this is the INTENDED surfacing of skew: the
+    remediation is regeneration, never pinning.
+    """
+    if generated_by == Version:
+        return None
+    return (
+        "strictspec version pairing mismatch:\n"
+        f"  generated by: {generated_by}\n"
+        f"  runtime:      {Version}\n"
+        "  remediation:  regenerate with `strictspec gen` against the current runtime "
+        "(do not pin -- the always-latest rule surfaces skew so it gets fixed)"
+    )
+
+
+def require_runtime_version(generated_by: str) -> None:
+    """Hard-error form used in generated init: raise PairingError when
+    generated_by does not exactly match this runtime version.
+    """
+    msg = check_runtime_version(generated_by)
+    if msg is not None:
+        raise PairingError(msg)
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One validation error: a stable STRICTSPEC_* code, the rendered path, and
+    the pinned message text. There is no severity field: every diagnostic is an
+    error.
+    """
+
+    code: str
+    path: str
+    message: str
+
+
+@dataclass(frozen=True)
+class Result:
+    """A validation outcome: whether the document validated, and the ordered
+    diagnostics (empty iff valid). Diagnostics are in emission order.
+    """
+
+    valid: bool
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+
+class Kind(IntEnum):
+    """The lexeme class of a tagged document value (the public projection)."""
+
+    RECORD = 0
+    ARRAY = 1
+    STRING = 2
+    INTEGER = 3
+    FLOAT = 4
+    BOOL = 5
+    NULL = 6
+    DATETIME = 7
+    DATE = 8
+    TIME = 9
+
+
+class Program:
+    """A compiled strictspec schema. Generated code builds one at import from
+    its embedded schema (compile_embedded) and calls validate.
+    """
+
+    __slots__ = ("_prog",)
+
+    def __init__(self, prog: _ir.Program) -> None:
+        self._prog = prog
+
+    def validate(self, input: bytes, syntax: str) -> Result:
+        """RAW-BYTES entry point: lossless parse of input in the given syntax
+        ("json" | "toml" | "jsonl"), then validate. Loading and validation are
+        inseparable. For JSONL every line is validated with per-line anchors.
+        """
+        return self.validate_with_evidence(input, syntax, None)
+
+    def validate_with_evidence(
+        self, input: bytes, syntax: str, evidence: dict | None
+    ) -> Result:
+        if syntax == "jsonl":
+            diags = self._validate_jsonl(input, evidence)
+        elif syntax == "toml":
+            try:
+                d = _tomldoc.parse(input)
+            except _doc.ParseError as pe:
+                diags = [_parse_diag(pe)]
+            else:
+                diags = _ir.execute(
+                    self._prog, d.root, _ir.ExecOptions(format=_doc.FORMAT_TOML, evidence=evidence)
+                )
+        else:  # json
+            try:
+                d = _jsondoc.parse(input)
+            except _doc.ParseError as pe:
+                diags = [_parse_diag(pe)]
+            else:
+                diags = _ir.execute(
+                    self._prog, d.root, _ir.ExecOptions(format=_doc.FORMAT_JSON, evidence=evidence)
+                )
+        return _render_result(diags)
+
+    def validate_value(self, v: "Value") -> Result:
+        """TAGGED-VALUE entry point: validate an already-parsed tagged document
+        value (from load_value or a generated typed constructor). Raw untagged
+        dicts are never accepted.
+        """
+        return self.validate_value_with_evidence(v, None)
+
+    def validate_value_with_evidence(self, v: "Value", evidence: dict | None) -> Result:
+        diags = _ir.execute(
+            self._prog, v._node, _ir.ExecOptions(format=v._format, evidence=evidence)
+        )
+        return _render_result(diags)
+
+    def _validate_jsonl(self, src: bytes, evidence: dict | None) -> list:
+        try:
+            docs = _jsondoc.parse_lines(src)
+        except _doc.ParseError as pe:
+            return [_parse_diag(pe)]
+        starts = _line_starts(src)
+        out: list = []
+        for i, d in enumerate(docs):
+            ls = starts[i] if i < len(starts) else 0
+            out.extend(
+                _ir.execute(
+                    self._prog,
+                    d.root,
+                    _ir.ExecOptions(
+                        format=_doc.FORMAT_JSONL,
+                        evidence=evidence,
+                        jsonl=True,
+                        line=i + 1,
+                        line_start=ls,
+                    ),
+                )
+            )
+        return out
+
+
+def compile_embedded(files: dict[str, str], main_file: str) -> Program:
+    """Compile a schema carried IN MEMORY by generated code: files maps each
+    referenced file name (the schema, imported type-definition files, and the
+    scalar manifest) to its exact text, and main_file names the entry point.
+    Import resolution and custom-scalar binding happen against the FileSet,
+    never disk. A schema-authoring problem surfaces as ValueError.
+    """
+    s, sdiags = _schema.parse_from(files, main_file)
+    sdiags = list(sdiags) + _schema.resolve_imports_from(s, files)
+    if sdiags:
+        raise ValueError(_embedded_schema_error(sdiags))
+    scalars = _schema.load_manifest_scalars_from(files)
+    return Program(_ir.compile_program(s, scalars))
+
+
+@dataclass(frozen=True)
+class KV:
+    """One ordered key/value binding of a record or map."""
+
+    key: str
+    value: "Value"
+
+
+class Value:
+    """A TAGGED, lexeme-retaining document value: the second entry point's input
+    and what generated typed constructors bind from. It comes from a lossless
+    parse (load_value) or from generated typed constructors. Raw untagged dicts
+    are never Values -- ambiguity never enters the model.
+    """
+
+    __slots__ = ("_node", "_format")
+
+    def __init__(self, node: _doc.Node | None, fmt: str) -> None:
+        self._node = node
+        self._format = fmt
+
+    def kind(self) -> Kind:
+        if self._node is None:
+            return Kind.NULL
+        k = self._node.kind
+        return {
+            _doc.Kind.RECORD: Kind.RECORD,
+            _doc.Kind.ARRAY: Kind.ARRAY,
+            _doc.Kind.STRING: Kind.STRING,
+            _doc.Kind.INTEGER: Kind.INTEGER,
+            _doc.Kind.FLOAT: Kind.FLOAT,
+            _doc.Kind.BOOL: Kind.BOOL,
+            _doc.Kind.NULL: Kind.NULL,
+            _doc.Kind.DATETIME_OFFSET: Kind.DATETIME,
+            _doc.Kind.DATETIME_LOCAL: Kind.DATETIME,
+            _doc.Kind.DATE_LOCAL: Kind.DATE,
+            _doc.Kind.TIME_LOCAL: Kind.TIME,
+        }.get(k, Kind.NULL)
+
+    def field(self, name: str) -> "tuple[Value, bool]":
+        if self._node is None or self._node.kind != _doc.Kind.RECORD:
+            return Value(None, self._format), False
+        for e in self._node.entries:
+            if e.key == name:
+                return Value(e.value, self._format), True
+        return Value(None, self._format), False
+
+    def entries(self) -> list[KV]:
+        if self._node is None or self._node.kind != _doc.Kind.RECORD:
+            return []
+        return [KV(e.key, Value(e.value, self._format)) for e in self._node.entries]
+
+    def items(self) -> list["Value"]:
+        if self._node is None or self._node.kind != _doc.Kind.ARRAY:
+            return []
+        return [Value(it, self._format) for it in self._node.items]
+
+    # --- coercers ------------------------------------------------------------
+
+    def string(self) -> tuple[str, bool]:
+        if self._node is None or self._node.kind != _doc.Kind.STRING:
+            return "", False
+        return self._decode_string(), True
+
+    def int(self) -> tuple[int, bool]:
+        if self._node is None or self._node.kind != _doc.Kind.INTEGER:
+            return 0, False
+        v = _schema._go_parse_int(self._node.lexeme)
+        if v is None:
+            return 0, False
+        return v, True
+
+    def float(self) -> tuple[float, bool]:
+        if self._node is None or self._node.kind != _doc.Kind.FLOAT:
+            return 0.0, False
+        f = _schema._go_parse_float(self._node.lexeme)
+        if f is None:
+            return 0.0, False
+        return f, True
+
+    def number(self) -> tuple[float, bool]:
+        if self._node is None or self._node.kind not in (_doc.Kind.INTEGER, _doc.Kind.FLOAT):
+            return 0.0, False
+        f = _schema._go_parse_float(self._node.lexeme)
+        if f is None:
+            return 0.0, False
+        return f, True
+
+    def bool(self) -> tuple[bool, bool]:
+        if self._node is None or self._node.kind != _doc.Kind.BOOL:
+            return False, False
+        return self._node.lexeme == "true", True
+
+    def datetime(self) -> tuple[str, bool]:
+        if self._node is None:
+            return "", False
+        k = self._node.kind
+        if k in (
+            _doc.Kind.DATETIME_OFFSET,
+            _doc.Kind.DATETIME_LOCAL,
+            _doc.Kind.DATE_LOCAL,
+            _doc.Kind.TIME_LOCAL,
+        ):
+            return self._node.lexeme, True
+        if k == _doc.Kind.STRING:
+            return self._decode_string(), True
+        return "", False
+
+    def is_null(self) -> bool:
+        return self._node is None or self._node.kind == _doc.Kind.NULL
+
+    def _decode_string(self) -> str:
+        if self._node is None:
+            return ""
+        if self._format == _doc.FORMAT_TOML:
+            return _strdecode.decode_toml(self._node.lexeme)
+        return _strdecode.decode_json(self._node.lexeme)
+
+
+def load_value(input: bytes, syntax: str) -> Value:
+    """Losslessly parse raw bytes in the given syntax into a tagged Value. For
+    "jsonl" it parses the FIRST line (use load_values for a stream). A parse
+    failure raises -- there is no lenient mode.
+    """
+    if syntax == "toml":
+        d = _tomldoc.parse(input)
+        return Value(d.root, _doc.FORMAT_TOML)
+    if syntax == "jsonl":
+        docs = _jsondoc.parse_lines(input)
+        if not docs:
+            raise ValueError("strictspec: empty JSONL stream")
+        return Value(docs[0].root, _doc.FORMAT_JSONL)
+    d = _jsondoc.parse(input)
+    return Value(d.root, _doc.FORMAT_JSON)
+
+
+def load_values(input: bytes) -> list[Value]:
+    """Losslessly parse a JSONL stream into one Value per line."""
+    docs = _jsondoc.parse_lines(input)
+    return [Value(d.root, _doc.FORMAT_JSONL) for d in docs]
+
+
+# --- version gate helper -----------------------------------------------------
+
+
+@dataclass(frozen=True)
+class GateResult:
+    """The structured outcome of the inline version gate: whether the document's
+    format_version is accepted, plus the remediation payload on failure.
+    """
+
+    ok: bool
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+
+def version_gate(program: Program, input: bytes, syntax: str) -> GateResult:
+    """Run ONLY the version gate against the document, returning its structured
+    result (the three-message pattern + remediation payload). A convenience for
+    consumers that want to surface the gate verdict before full validation.
+    """
+    try:
+        if syntax == "toml":
+            d = _tomldoc.parse(input)
+            root = d.root
+            fmt = _doc.FORMAT_TOML
+        elif syntax == "jsonl":
+            docs = _jsondoc.parse_lines(input)
+            root = docs[0].root if docs else None
+            fmt = _doc.FORMAT_JSONL
+        else:
+            d = _jsondoc.parse(input)
+            root = d.root
+            fmt = _doc.FORMAT_JSON
+    except _doc.ParseError as pe:
+        r = _render_result([_parse_diag(pe)])
+        return GateResult(ok=False, diagnostics=r.diagnostics)
+    v = _ir._Exec(program._prog, root, _ir.ExecOptions(format=fmt))
+    ok = v.gate(root)
+    r = _render_result(v.diags.all())
+    return GateResult(ok=ok, diagnostics=r.diagnostics)
+
+
+# --- internal helpers --------------------------------------------------------
+
+
+def _render_result(diags: list) -> Result:
+    out = tuple(
+        Diagnostic(code=d.code, path=d.path.render(), message=_render.render(d)) for d in diags
+    )
+    return Result(valid=len(out) == 0, diagnostics=out)
+
+
+def _parse_diag(pe: _doc.ParseError) -> _diag.Diagnostic:
+    code = "STRICTSPEC_PARSE_JSON_SYNTAX"
+    if pe.format == _doc.FORMAT_TOML:
+        code = "STRICTSPEC_PARSE_TOML_SYNTAX"
+    elif pe.format == _doc.FORMAT_JSONL:
+        code = "STRICTSPEC_PARSE_JSONL_LINE_SYNTAX"
+    slots = {"detail": _diag.SlotString(pe.message)}
+    # Only the JSONL line-syntax template carries a {line} placeholder; binding
+    # it for JSON/TOML (as the Go code literally does) would be an unknown-slot
+    # render error. The JSON/TOML templates take only {path} and {detail}.
+    if code == "STRICTSPEC_PARSE_JSONL_LINE_SYNTAX":
+        slots["line"] = _diag.SlotInt(pe.position.line)
+    return _diag.Diagnostic(code=code, path=_diag.new_path(), slots=slots)
+
+
+def _line_starts(src: bytes) -> list[int]:
+    starts = [0]
+    for i, b in enumerate(src):
+        if b == 0x0A:
+            starts.append(i + 1)
+    return starts
+
+
+def _embedded_schema_error(diags: list) -> str:
+    parts = ["strictspec: embedded schema failed meta-schema validation (regenerate):"]
+    for d in diags:
+        parts.append("\n  " + d.code + " at " + d.path.render())
+    return "".join(parts)