parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/resource_surface.py

@@ -0,0 +1,196 @@
+"""The ONE named, stable SDK reachability/entity predicate.
+
+This module is the single source of truth for "what is the emitted client surface
+of a resource". It is imported by THREE consumers that previously each computed
+reachability independently and could silently desync:
+
+  1. **codegen** (``codegen_v2._ModuleNames``) — gates the ``client.<plural>``
+     collection ``@property`` (``emits_client_accessor``);
+  2. an external consumer — asserts the
+     exact complement (a resource it flags unreachable must NOT emit an accessor),
+     and pins lockstep tests against THIS named API so a future SDK refactor can't
+     silently break backend validation;
+  3. **docgen** (``docgen._reachability_warnings``) — warns on a resource that
+     ships as dead code (``not is_class_reachable``).
+
+Because consumer 2 lives in a different repository, this is a **stable named
+API** — ``parse_sdk.resource_surface.resource_surface_facts`` — NOT an
+SDK-internal helper. It is additive (a NEW module / the cut's only NEW exported
+symbol); it does not rename or remove any existing symbol.
+
+Per-resource facts (each a SEPARATE, independently-meaningful signal):
+
+  * ``has_root_collection`` — a pinless op with a string endpoint routes to a
+    root collection (``_root_collection_emit_ops``). The synthesized
+    ``fetched_by`` ``.get`` is folded in by ``_normalize_schema``, so this single
+    fact already covers the "root-collection emit-ops OR fetched_by" entity arm.
+  * ``has_safe_factory`` — ``constructible`` AND an instance-navigable surface (a
+    ``$self``-pinned op OR a sub-resource) AND a ``str`` ``keyed_by`` AND every
+    ``$self`` pin uses the key (``_constructible_unsafe_pin`` clean) — the SAME
+    gate codegen's factory pass uses. This is the safe-``constructible`` entity arm.
+  * ``is_type_referenced`` — the resource's emitted class name is named by some op
+    ``returns`` (excluding its OWN ops — a resource can't bootstrap itself), a
+    field type, a sub-resource ``of``, or a sub-resource op ``returns``.
+  * ``is_class_reachable`` = ``has_root_collection or has_safe_factory or
+    is_type_referenced`` — the resource's class is genuinely handed to the user
+    SOMEHOW; its negation is docgen's "ships as dead code" warning.
+  * ``emits_client_accessor`` = ``has_root_collection`` — whether codegen emits a
+    ``client.<plural>`` collection ``@property`` for this resource. A safe-factory
+    resource is reachable but its client surface is the no-network factory
+    ``@property`` (``_factory_rows``), NOT a ``client.<plural>`` collection; a pure
+    value-object (type-referenced only) emits NEITHER. So this fact is the
+    collection-accessor gate specifically, and ``is_class_reachable`` is the
+    broader "not dead code" question — keeping them SEPARATE is what lets codegen
+    suppress dead ``client.<plural>`` while docgen still credits factory/type
+    reachability.
+
+The facts mirror existing codegen/docgen behavior EXACTLY (this is a
+centralization, not a behavior change): emitting bytes are unchanged — it
+removes the parallel computations so the three consumers can never drift.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, NamedTuple, Optional, Set
+
+
+class ResourceFacts(NamedTuple):
+    """The reachability/entity surface of a single resource. Field names are the
+    a stable public contract — external lockstep tests read them by name."""
+
+    has_root_collection: bool
+    has_safe_factory: bool
+    is_type_referenced: bool
+    is_class_reachable: bool
+    emits_client_accessor: bool
+
+
+def resource_surface_facts(schema: Dict[str, Any]) -> Dict[str, ResourceFacts]:
+    """``{resource_spec_key -> ResourceFacts}`` for every resource in ``schema``.
+
+    Computed on the NORMALIZED schema (so a ``fetched_by``-synthesized ``.get``
+    counts as a root collection and a normalized-vs-raw caller agree). The key is
+    the resource's spec key in the normalized schema; type-reference matching is
+    against the ``_camel``-canonical resource universe, mirroring codegen's
+    ``_allocate_returns`` resolution and the field-resolvability gate.
+
+    Accepts a raw OR already-normalized schema (it normalizes internally and is
+    idempotent under re-normalization), so a cross-repo caller need not import the
+    SDK's private normalizer. Returns ``{}`` when the schema declares no resources.
+    """
+    # Imported lazily so this module has no import-time cycle with codegen_v2
+    # (which is the heavier module and may import this in turn).
+    from parse_sdk.codegen_v2 import (
+        _camel,
+        _is_safe_factory,
+        _normalize_schema,
+        _referenced_resource_names,
+        _root_collection_emit_ops,
+    )
+
+    norm = _normalize_schema(schema)
+    resources = norm.get("resources")
+    if not isinstance(resources, dict) or not resources:
+        return {}
+
+    # Codegen resolves a return/field leaf to a resource by ``_camel`` identity
+    # (``_allocate_returns``), so the resource-name universe is the canonical
+    # ``_camel`` form of every resource key.
+    camel_names: Set[str] = {
+        _camel(rk) for rk, rv in resources.items() if isinstance(rv, dict)
+    }
+    # Under a ``_camel`` collision (e.g. ``Post`` + ``post``) codegen allocates
+    # the FIRST resource the un-suffixed class (``Post``) and the collider a
+    # suffix (``Post_`` — see ``_allocate_ident``); a bare-name reference
+    # (``featured: "Post"``) resolves to the un-suffixed class only. So a
+    # ``_camel`` reference credits ONLY the canonical (first-allocated) resource
+    # for that name — else the dead collider inherits the canonical's
+    # reachability and the fact API lies to its consumers (codegen/docgen/the
+    # external lockstep). ``has_root_collection``/``has_safe_factory`` are
+    # per-resource and unaffected; only the type-reference credit needs gating.
+    _canonical_rk_for_camel: Dict[str, str] = {}
+    for rk, rv in resources.items():
+        if isinstance(rv, dict):
+            _canonical_rk_for_camel.setdefault(_camel(rk), rk)
+
+    # --- gather every type label that could name a resource, ONCE -------------
+    # (op returns, field types, sub-resource ``of`` + sub-op returns). An own
+    # op's ``returns`` must NOT self-credit the owner (a resource can't bootstrap
+    # itself; the legit "collection op returns self" case is clause 1's job).
+    referenced_names: Set[str] = set()
+
+    def _credit(label: Any, *, exclude: Optional[str] = None) -> None:
+        if not isinstance(label, str):
+            return
+        names = _referenced_resource_names(label, camel_names)
+        if exclude is not None:
+            names = names - {exclude}
+        referenced_names.update(names)
+
+    for rk, rspec in resources.items():
+        if not isinstance(rspec, dict):
+            continue
+        own_name = _camel(rk)
+        ops = rspec.get("operations")
+        ops = ops if isinstance(ops, dict) else {}
+        fields = rspec.get("fields")
+        fields = fields if isinstance(fields, dict) else {}
+        subs = rspec.get("sub_resources")
+        subs = subs if isinstance(subs, dict) else {}
+        for op in ops.values():
+            if isinstance(op, dict):
+                _credit(op.get("returns"), exclude=own_name)
+        for fval in fields.values():
+            if isinstance(fval, str):
+                _credit(fval)
+            elif isinstance(fval, dict):
+                _credit(fval.get("type"))
+        for sspec in subs.values():
+            if not isinstance(sspec, dict):
+                continue
+            _credit(sspec.get("of"))
+            sops = sspec.get("operations")
+            sops = sops if isinstance(sops, dict) else {}
+            for sop in sops.values():
+                if isinstance(sop, dict):
+                    _credit(sop.get("returns"))
+
+    out: Dict[str, ResourceFacts] = {}
+    for rk, rspec in resources.items():
+        if not isinstance(rspec, dict):
+            continue
+        ops = rspec.get("operations")
+        ops = ops if isinstance(ops, dict) else {}
+        subs = rspec.get("sub_resources")
+        subs = subs if isinstance(subs, dict) else {}
+
+        # 1. Root collection (== the client.<plural> collection-accessor gate).
+        has_root_collection = bool(_root_collection_emit_ops(ops))
+
+        # 2. Safe factory — codegen's _factory_gate is the single source (so this
+        #    reachability fact can never drift from the emitter's factory pass).
+        has_safe_factory = _is_safe_factory(rspec, ops, subs)
+
+        # 3. Referenced as a type (its emitted class is genuinely returned).
+        #    Only the canonical resource for a colliding ``_camel`` is the target
+        #    of a bare-name reference (the collider gets a suffixed class no
+        #    bare label names) — so a non-canonical collider is NOT type-referenced.
+        _rk_camel = _camel(rk)
+        is_type_referenced = (
+            _rk_camel in referenced_names
+            and _canonical_rk_for_camel.get(_rk_camel) == rk
+        )
+
+        is_class_reachable = has_root_collection or has_safe_factory or is_type_referenced
+
+        out[rk] = ResourceFacts(
+            has_root_collection=has_root_collection,
+            has_safe_factory=has_safe_factory,
+            is_type_referenced=is_type_referenced,
+            is_class_reachable=is_class_reachable,
+            # The client.<plural> collection accessor is gated by the
+            # root-collection fact alone (factory/value-object resources do not
+            # get a collection accessor) — so codegen suppresses dead client.<plural>.
+            emits_client_accessor=has_root_collection,
+        )
+    return out

parse_sdk/sample_gate.py

@@ -0,0 +1,245 @@
+"""Deterministic field-type ⟷ sample reconciliation.
+
+The generated SDKs faithfully try to coerce whatever field type the LLM author
+wrote. When that type is wrong (``release_date: Dict[str, str]`` over a real
+``{"date": str, "coming_soon": bool}`` payload), the SDK can still type-check
+while exposing raw or best-effort-coerced values at runtime. This module is the
+deterministic verifier that catches the mismatch against the captured
+``return_schema.sample``.
+
+``gate_field(declared_label, samples, *, is_key=False) -> Verdict`` is pure: it
+reads value-types only, never emits the sample into output, and floors a
+contradicted ``Dict[str, SCALAR]`` / ``List[Dict[str, SCALAR]]`` / ``List[SCALAR]``
+field to the Any-form of the OBSERVED outer shape (``Any`` is sound — raw
+passthrough at runtime). The repair label is always one ``_field_annotation``
+emits verbatim (the resolvability invariant).
+
+``samples`` is the list of OBSERVED VALUES for ONE field, already projected by
+The projection (``resource → operation → endpoint → return_schema.sample`` with envelope
+descent). The gate never extracts a wire key itself.
+
+Built-in invariants:
+  * a declared ``Optional`` is preserved on repair independent of
+    whether the sample showed null (dropping it makes ``x = None`` a type error).
+  * the ``_KEY_FIELD`` is never rewritten (``is_key=True`` →
+    ``CONFIRMED``); widening a key to ``Any`` breaks ``__eq__``/``__hash__``/dedup.
+  * ``samples`` is guarded: ``None → []``; a non-list (a bare dict/str
+    would silently iterate keys/chars) → ``UNDECIDABLE``.
+  * an inner null in a ``List``/``Dict`` re-wraps the inner ``Optional``.
+  * Repair floors to the **observed** outer shape (fixes outer-container flip:
+    ``List[str]`` over a dict payload → ``Dict[str, Any]``, not ``List[Any]``).
+  * Sanitized placeholder leaves (``REDACTED_*`` etc.) are treated as
+    ``UNDECIDABLE`` evidence — residual serving-time defense, not the guarantee.
+
+Scalar-declared fields (``str``/``int``/...) get a verdict but are never
+repaired here (``repaired_label is None``); scalar mistypes route to the
+runtime backstop. Everything else (``X | str`` open unions, ``Dict[int, X]``,
+nesting beyond one level, resources, ``datetime``/``Decimal``/``Any``) is
+out-of-scope → the declared label is kept (``CONFIRMED``, never touched).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Optional, Tuple
+
+from parse_sdk._labels import split_top as _split_top
+from parse_sdk._labels import strip_wrapper as _inner
+
+_SCALARS = ("str", "int", "float", "bool")
+
+# Sanitizer placeholder leaves — a fixed allow-list is residual defense only
+# (an LLM sanitizer can emit any string; the build-time persisted repair is the
+# real guarantee). A leaf equal to one of these is "no evidence", not proof.
+_PLACEHOLDER_EXACT = frozenset({
+    "CRITICAL_PII_REDACTED", "John Doe", "Jane Doe",
+    "user@example.com", "+1 (555) 012-3456", "123 Main St",
+})
+
+
+@dataclass(frozen=True)
+class Verdict:
+    status: str                     # "CONFIRMED" | "CONTRADICTED" | "UNDECIDABLE"
+    repaired_label: Optional[str]   # non-None only when a rewrite is warranted
+
+
+@dataclass(frozen=True)
+class _Parsed:
+    kind: str          # "scalar" | "dict_scalar" | "list_scalar" | "list_dict_scalar" | "opaque"
+    scalar: Optional[str]
+    optional: bool
+
+
+def _is_placeholder(v: Any) -> bool:
+    if not isinstance(v, str):
+        return False
+    return v.startswith("REDACTED_") or v in _PLACEHOLDER_EXACT
+
+
+# Depth-0 comma split — single source in parse_sdk._labels (the hand-rolled
+# copies here, in codegen_reconcile, and in the runtime drifted historically);
+# imported at the top as ``_split_top``.
+
+
+def _parse_label(label: Any) -> _Parsed:
+    """Classify a declared field label into its reconciliation kind. A non-string
+    label (a malformed FieldSpec like ``{"type": 123}``) is out-of-scope/opaque —
+    never reconciled, never raised on (the downstream codegen path handles it
+    leniently)."""
+    if not isinstance(label, str):
+        return _Parsed("opaque", None, False)
+    s = label.strip()
+    optional = False
+    inner = _inner(s, "Optional[")
+    if inner is not None:
+        optional, s = True, inner
+    # A top-level union (``X | str``) is an open-enum/leaf form — never touched.
+    if "|" in s:
+        return _Parsed("opaque", None, optional)
+    if s in _SCALARS:
+        return _Parsed("scalar", s, optional)
+    d = _inner(s, "Dict[")
+    if d is not None:
+        parts = _split_top(d)
+        if len(parts) == 2 and parts[0] == "str" and parts[1] in _SCALARS:
+            return _Parsed("dict_scalar", parts[1], optional)
+        return _Parsed("opaque", None, optional)
+    li = _inner(s, "List[")
+    if li is not None:
+        if li in _SCALARS:
+            return _Parsed("list_scalar", li, optional)
+        dd = _inner(li, "Dict[")
+        if dd is not None:
+            parts = _split_top(dd)
+            if len(parts) == 2 and parts[0] == "str" and parts[1] in _SCALARS:
+                return _Parsed("list_dict_scalar", parts[1], optional)
+        return _Parsed("opaque", None, optional)
+    return _Parsed("opaque", None, optional)
+
+
+def _is_scalar_instance(v: Any, scalar: "Optional[str]") -> bool:
+    # ``scalar`` is Optional because ``_Parsed.scalar`` is — a scalar-kinded
+    # parse always sets it (invariant by construction), and the str fallthrough
+    # is total either way.
+    # ``bool`` subclasses ``int`` — check bool first, and exclude bool from
+    # int/float so a wire ``True`` never satisfies an ``int``/``float`` field.
+    if scalar == "bool":
+        return isinstance(v, bool)
+    if scalar == "int":
+        return isinstance(v, int) and not isinstance(v, bool)
+    if scalar == "float":
+        return isinstance(v, float) and not isinstance(v, bool)
+    return isinstance(v, str)
+
+
+def _wrap(base: str, optional: bool) -> str:
+    return f"Optional[{base}]" if optional else base
+
+
+def _observed_floor(non_null: List[Any], optional: bool) -> str:
+    """Floor to the Any-form of the OBSERVED outer shape across all samples."""
+    saw_dict = any(isinstance(v, dict) for v in non_null)
+    lists = [v for v in non_null if isinstance(v, list)]
+    saw_list = bool(lists)
+    if saw_dict and not saw_list:
+        return _wrap("Dict[str, Any]", optional)
+    if saw_list and not saw_dict:
+        elems = [e for lst in lists for e in lst]
+        if elems and all(isinstance(e, dict) for e in elems):
+            return _wrap("List[Dict[str, Any]]", optional)
+        return _wrap("List[Any]", optional)
+    # Scalars-only, or a mixed dict+list across samples — the honest floor is
+    # bare Any.
+    return _wrap("Any", optional)
+
+
+def _real_leaves(values: List[Any]) -> Tuple[List[Any], bool]:
+    """Drop nulls + sanitized placeholders; report whether a null was present."""
+    saw_null = any(v is None for v in values)
+    leaves = [v for v in values if v is not None and not _is_placeholder(v)]
+    return leaves, saw_null
+
+
+def gate_field(declared_label: str, samples: Any, *, is_key: bool = False) -> Verdict:
+    # Never rewrite a key field (owned by the original coercer).
+    if is_key:
+        return Verdict("CONFIRMED", None)
+
+    parsed = _parse_label(declared_label)
+    if parsed.kind == "opaque":
+        return Verdict("CONFIRMED", None)   # keep the declared label, untouched
+
+    # Guard the samples arg.
+    if samples is None:
+        samples = []
+    if not isinstance(samples, list):
+        return Verdict("UNDECIDABLE", None)
+
+    non_null = [s for s in samples if s is not None]
+
+    if parsed.kind == "scalar":
+        leaves, _ = _real_leaves(samples)
+        if not leaves:
+            return Verdict("UNDECIDABLE", None)
+        if all(_is_scalar_instance(v, parsed.scalar) for v in leaves):
+            return Verdict("CONFIRMED", None)
+        # A scalar mismatch is DETECTED but deliberately NOT repaired here
+        # (deferred). Runtime coercion is best-effort and keeps
+        # unparseable values raw; to close a mismatch deterministically at
+        # codegen time, floor to ``Any`` here.
+        return Verdict("CONTRADICTED", None)
+
+    # Repairable container kinds: dict_scalar / list_scalar / list_dict_scalar.
+    declared_outer = "dict" if parsed.kind == "dict_scalar" else "list"
+
+    def _outer(v: Any) -> str:
+        if isinstance(v, dict):
+            return "dict"
+        if isinstance(v, list):
+            return "list"
+        return "scalar"
+
+    if non_null and any(_outer(v) != declared_outer for v in non_null):
+        # Outer-container flip — floor to the OBSERVED shape, not the declared.
+        return Verdict("CONTRADICTED", _observed_floor(non_null, parsed.optional))
+
+    # Outer shape matches the declaration → inspect inner leaf value-types.
+    leaf_values: List[Any] = []
+    saw_inner_null = False
+    if parsed.kind == "dict_scalar":
+        for v in non_null:
+            vals = list(v.values())
+            leaves, snull = _real_leaves(vals)
+            leaf_values.extend(leaves); saw_inner_null |= snull
+    elif parsed.kind == "list_scalar":
+        for v in non_null:
+            leaves, snull = _real_leaves(v)
+            leaf_values.extend(leaves); saw_inner_null |= snull
+    else:  # list_dict_scalar
+        for v in non_null:
+            for d in v:
+                if isinstance(d, dict):
+                    leaves, snull = _real_leaves(list(d.values()))
+                    leaf_values.extend(leaves); saw_inner_null |= snull
+                elif d is not None:
+                    # A non-dict element flips the inner shape (the element
+                    # should be a record, not a scalar) — an outer-shape
+                    # contradiction; floor to the OBSERVED shape. Do NOT fold it
+                    # into the scalar leaf check (a str element would falsely
+                    # CONFIRM a List[Dict[str,str]] over a wire List[str]).
+                    return Verdict("CONTRADICTED", _observed_floor(non_null, parsed.optional))
+
+    if not leaf_values and not saw_inner_null:
+        return Verdict("UNDECIDABLE", None)
+
+    contradicted = any(not _is_scalar_instance(v, parsed.scalar) for v in leaf_values)
+    if contradicted:
+        return Verdict("CONTRADICTED", _observed_floor(non_null, parsed.optional))
+
+    # Inner nulls observed on an otherwise-CONFIRMED List[SCALAR] re-wrap
+    # the inner Optional (latent, non-corrupting).
+    if saw_inner_null and parsed.kind == "list_scalar":
+        return Verdict("CONTRADICTED",
+                       _wrap(f"List[Optional[{parsed.scalar}]]", parsed.optional))
+    if not leaf_values:
+        return Verdict("UNDECIDABLE", None)
+    return Verdict("CONFIRMED", None)