parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/preview.py

@@ -0,0 +1,588 @@
+"""In-process preview of a generated SDK module — used by the agent's
+compile-check tool to validate an example before `complete()`.
+
+Pipeline:
+  1. Agent emits a draft spec.
+  2. Dispatcher calls ``render_preview(schema)`` — codegen runs, the
+     result is written under one per-process temp dir (a per-slug
+     subdir, overwritten on re-render) and imported via importlib.
+     No ``sys.path`` mutation.
+  3. Dispatcher calls ``check_example(module, example_src)`` — AST-walks
+     the example, resolves every reference (imports, attributes, method
+     calls + kwargs) against the live module. Returns a structured
+     report.
+
+No subprocess, no executor round-trip, no live HTTP. The example is
+NOT executed — purely static. That's the whole point: catch the
+ergonomic surface bugs (wrong method name, missing kwarg, dropped
+enum) without needing an API key or a target site.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import inspect
+import itertools
+import re
+import sys
+import tempfile
+import threading
+import textwrap
+import types
+import typing
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Dict, List, Optional, Tuple
+
+from .codegen_v2 import CodegenError, render_module
+
+
+@dataclass
+class CheckViolation:
+    """One ergonomics finding from the AST walk over an example."""
+
+    kind: str  # "import", "attribute", "method", "kwarg", "syntax"
+    location: str  # "<file>:<line>" or "line N"
+    message: str
+
+    def __str__(self) -> str:
+        return f"[{self.kind}] {self.location}: {self.message}"
+
+
+@dataclass
+class CheckReport:
+    """Result of running ``check_example`` on a draft."""
+
+    ok: bool
+    # Always "" from check_example — callers that need the generated source
+    # already hold it from render_preview. (Field kept: the dataclass shape
+    # is a stable public contract — changing its verdict is a breaking change.)
+    module_source: str
+    public_symbols: List[str] = field(default_factory=list)
+    violations: List[CheckViolation] = field(default_factory=list)
+
+    def summary(self) -> str:
+        """Human-readable summary for the agent to act on."""
+        if self.ok:
+            return f"OK — example compiles against the generated SDK ({len(self.public_symbols)} public symbols)."
+        lines = [f"FAIL — {len(self.violations)} violation(s):"]
+        for v in self.violations:
+            lines.append(f"  • {v}")
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Preview module renderer
+# ---------------------------------------------------------------------------
+
+
+def render_preview(
+    schema: Dict[str, Any],
+    *,
+    base_url: str = "http://preview.local",
+) -> Tuple[Optional[ModuleType], str]:
+    """Render ``schema`` to a real ``parse_sdk._preview.<slug>`` module
+    and import it. Returns ``(module, source)``. ``module`` is None when
+    the schema has no resources block or codegen rejects it outright
+    (``CodegenError`` — e.g. a hostile scraper id / endpoint name, or a
+    list op with no pagination block). The authoring tool must report
+    "no module" for a bad draft, never crash with a traceback — `parse
+    sync` already degrades the same way (skip + warn).
+    """
+    try:
+        source = render_module(schema, base_url=base_url)
+    except CodegenError:
+        return None, ""
+    if source is None:
+        return None, ""
+
+    slug = schema.get("slug") or schema.get("id") or "preview"
+    # The module is loaded under a hidden ``_preview`` namespace so it can
+    # coexist with whatever the user's already imported. We don't want
+    # ``parse_sdk.reddit`` and ``parse_sdk._preview.reddit`` to collide.
+    mod_name = f"parse_sdk._preview.{slug}"
+
+    # One per-process temp dir (removed at interpreter exit by the stdlib
+    # finalizer) with a unique subdir per render — a fresh path every time,
+    # so a stale bytecode-cache hit (pyc is keyed on mtime+size, and a fast
+    # re-render of a changed draft at a REUSED path can collide on both) is
+    # unrepresentable, and nothing survives the process the way the old
+    # one-mkdtemp-per-call dirs did. importlib needs an on-disk location for
+    # the spec because the generated module's ``__all__`` and relative
+    # imports expect a real path.
+    safe_slug = re.sub(r"[^A-Za-z0-9_.-]", "_", str(slug))
+    tmpdir = _preview_root() / f"{safe_slug}-{next(_PREVIEW_SEQ)}"
+    tmpdir.mkdir(parents=True, exist_ok=True)
+    init_path = tmpdir / "__init__.py"
+    init_path.write_text(source)
+
+    spec = importlib.util.spec_from_file_location(mod_name, init_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"importlib could not build a spec for {init_path}")
+    module = importlib.util.module_from_spec(spec)
+    # Same-name registration is load-bearing: get_type_hints resolution in
+    # the walker and Resource._field_hints resolve via cls.__module__, and a
+    # re-render of the same slug REPLACES (frees) the prior module.
+    sys.modules[mod_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except SyntaxError:
+        # A non-compiling generated module is a bad draft, not a crash: mirror the
+        # CodegenError path (return None) so render_preview never leaks a traceback
+        # — the documented contract above. Narrow to SyntaxError (covers
+        # IndentationError); a genuine runtime error in generated code must still
+        # propagate via the BaseException arm below.
+        sys.modules.pop(mod_name, None)
+        return None, ""
+    except BaseException:
+        # Never leave a half-initialized module registered — a later import
+        # of the same name would silently see the broken partial.
+        sys.modules.pop(mod_name, None)
+        raise
+    return module, source
+
+
+_PREVIEW_TMP: Optional[tempfile.TemporaryDirectory] = None
+_PREVIEW_LOCK = threading.Lock()
+_PREVIEW_SEQ = itertools.count()
+
+
+def _preview_root() -> Path:
+    """The per-process preview staging dir, created lazily. The stdlib
+    finalizer removes it (and every per-render subdir) at interpreter exit."""
+    global _PREVIEW_TMP
+    if _PREVIEW_TMP is None:
+        with _PREVIEW_LOCK:
+            if _PREVIEW_TMP is None:
+                _PREVIEW_TMP = tempfile.TemporaryDirectory(prefix="parse_sdk_preview_")
+    return Path(_PREVIEW_TMP.name)
+
+
+def public_symbols(module: ModuleType) -> List[str]:
+    """The codegen-emitted ``__all__`` (root class + resources + enums + errors)."""
+    return list(getattr(module, "__all__", []))
+
+
+# ---------------------------------------------------------------------------
+# AST walker — validate an example against the preview module
+# ---------------------------------------------------------------------------
+
+
+def _build_symbol_index(module: ModuleType) -> Dict[str, Any]:
+    """Top-level callables / classes / enums users might import."""
+    out: Dict[str, Any] = {}
+    for name in public_symbols(module):
+        if hasattr(module, name):
+            out[name] = getattr(module, name)
+    return out
+
+
+def check_example(module: ModuleType, example_src: str) -> CheckReport:
+    """Static-check an example against a preview module.
+
+    Catches:
+      * Syntax errors.
+      * Imports from ``parse_apis.<slug>`` of names that don't exist (and flags
+        the dead ``parse_sdk.<slug>`` form).
+      * Method calls referencing methods that don't exist on the resource /
+        collection / root client.
+      * Method calls passing kwargs the method doesn't accept.
+
+    Does NOT catch:
+      * Wrong types on positional args (no type inference).
+      * Whether the example actually returns data (no execution).
+    """
+    source = textwrap.dedent(example_src).strip()
+    public = _build_symbol_index(module)
+
+    # 1) Syntax
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return CheckReport(
+            ok=False,
+            module_source="",
+            public_symbols=public_symbols(module),
+            violations=[CheckViolation("syntax", f"line {e.lineno}", e.msg or "syntax error")],
+        )
+
+    violations: List[CheckViolation] = []
+
+    # 2) Imports
+    slug = module.__name__.rsplit('.', 1)[-1]
+    imported_names: Dict[str, Any] = dict(public)  # built-ins from this module pre-resolved
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if not node.module:
+                continue
+            # The dead generated path: parse_sdk.<slug> resolution was removed.
+            # Flag it explicitly so the agent rewrites to parse_apis.<slug>.
+            if node.module.startswith("parse_sdk.") and node.module not in (
+                "parse_sdk._runtime",
+            ):
+                violations.append(
+                    CheckViolation(
+                        "import",
+                        f"line {node.lineno}",
+                        f"`from {node.module} import …` is no longer importable — generated "
+                        f"clients live in `parse_apis.{slug}`. Use `from parse_apis.{slug} import …`.",
+                    )
+                )
+                continue
+            if node.module.startswith("parse_apis."):
+                for alias in node.names:
+                    name = alias.name
+                    if name not in public:
+                        violations.append(
+                            CheckViolation(
+                                "import",
+                                f"line {node.lineno}",
+                                f"`from {node.module} import {name}`: {name!r} is not exported by the generated SDK. "
+                                f"Available: {sorted(public)}",
+                            )
+                        )
+                    else:
+                        local = alias.asname or name
+                        imported_names[local] = public[name]
+
+    # 3) Method calls — best-effort attribute resolution
+    name_bindings: Dict[str, Any] = dict(imported_names)
+
+    _UNRESOLVED = object()  # sentinel: a callable hop whose return type can't
+    # be determined — the caller must IGNORE the chain (fail-open), never walk
+    # attribute lookups against the bare method object (that false-flags the
+    # next REAL member: paginator.first().details).
+
+    def _class_origin(tp: Any) -> Optional[type]:
+        """The origin CLASS of a parameterized generic alias
+        (``_Paginator[Thing]`` → ``Paginator``, ``Dict[str, X]`` → ``dict``),
+        or None when ``tp`` isn't one. Unions are explicitly excluded: on
+        3.14 ``typing.Union`` itself became a class, so a bare
+        ``inspect.isclass(get_origin(tp))`` misclassifies ``X | None`` as a
+        class-origin generic and derails the Optional/Union unwrap."""
+        origin = typing.get_origin(tp)
+        if origin is None or not inspect.isclass(origin):
+            return None
+        if origin is getattr(types, "UnionType", None) or origin is typing.Union:
+            return None
+        return origin
+
+    def _step_through_return(obj: Any, typevar_map: Dict[Any, Any]) -> Any:
+        """The class — or parameterized runtime generic alias like
+        ``_Paginator[Thing]`` — a property/method returns. Resolution EVALUATES
+        the annotation (``typing.get_type_hints``), first in the module's own
+        namespace, then in the function's defining module (runtime methods
+        reference runtime-private names like ``_PaginatorItem``) — the
+        emitter's vocabulary IS the resolver, so a prefix-spelling drift (the
+        old ``'Paginator['`` strip vs the emitted ``'_Paginator['``) is
+        unrepresentable. TypeVar returns (``Paginator.first -> _PaginatorItem``)
+        substitute through ``typevar_map`` (bound by the caller from the
+        enclosing generic alias), so the paginator's ELEMENT type survives the
+        hop. Non-callables pass through; anything unresolvable yields
+        ``_UNRESOLVED``."""
+        if _class_origin(obj) is not None:
+            # A parameterized runtime generic (``_Paginator[Thing]``) arriving
+            # as a chain ROOT — e.g. a name bound to a paginator-returning
+            # call result. Pass it through untouched; the caller's
+            # origin/TypeVar-binding path owns it. (Without this, the alias
+            # falls into the callable arm, get_type_hints fails, and the
+            # whole chain silently fails open.)
+            return obj
+        fn = None
+        if isinstance(obj, property) and obj.fget is not None:
+            fn = obj.fget
+        elif callable(obj) and not inspect.isclass(obj):
+            fn = obj
+        else:
+            return obj
+        try:
+            hints = typing.get_type_hints(fn, globalns=vars(module))
+        except Exception:
+            try:
+                hints = typing.get_type_hints(fn)  # fn's own module namespace
+            except Exception:
+                return _UNRESOLVED
+        tp = hints.get("return")
+        # Unwrap typing containers (List/Optional/Union) down to the element,
+        # substituting TypeVars from the enclosing generic as they surface.
+        for _ in range(6):
+            if isinstance(tp, typing.TypeVar):
+                if tp not in typevar_map:
+                    return _UNRESOLVED
+                tp = typevar_map[tp]
+                continue
+            origin = typing.get_origin(tp)
+            if origin is None:
+                break
+            if _class_origin(tp) is not None:
+                # A runtime generic (``_Paginator[Thing]``): keep the ALIAS so
+                # the element TypeVar stays bound for later hops — ``.list()``/
+                # ``.first()`` live on Paginator, their returns are the element.
+                return tp
+            args = [a for a in typing.get_args(tp) if a is not type(None)]
+            if not args:
+                return _UNRESOLVED
+            tp = args[0]
+        # Resolve runtime bases (Resource/Paginator/BaseAPI) by their module
+        # ORIGIN, prefix-tolerant so a future ``_runtime`` package split (where a
+        # base's __module__ becomes ``parse_sdk._runtime._core`` etc.) keeps the
+        # frozen check_example VERDICT identical instead of degrading the type to
+        # _UNRESOLVED. Behaviour-identical today (the flat module is the exact
+        # match); pinned by test_lockstep_contracts.
+        if inspect.isclass(tp) and (
+            tp.__module__ == module.__name__
+            or tp.__module__ == "parse_sdk._runtime"
+            or tp.__module__.startswith("parse_sdk._runtime.")
+        ):
+            return tp
+        return _UNRESOLVED
+
+    def _declared_field_type(cls: type, attr: str) -> Any:
+        """The (unwrapped) annotation type of a PEP-526 declared field.
+
+        Bare annotations (``title: str`` on a generated resource) create NO
+        class attribute, so ``hasattr`` alone false-flags every valid field
+        hop (``…first().title.upper()``). Returns the class / class-origin
+        generic alias to keep walking; the ``_UNRESOLVED`` sentinel when the
+        field exists but can't be usefully typed (``Any``, unresolvable —
+        fail open); ``None`` when ``attr`` is not a declared field at all
+        (a real violation)."""
+        if not any(attr in getattr(c, "__annotations__", {}) for c in cls.__mro__):
+            return None
+        try:
+            hints = typing.get_type_hints(cls, globalns=vars(module))
+        except Exception:
+            try:
+                hints = typing.get_type_hints(cls)
+            except Exception:
+                return _UNRESOLVED
+        tp = hints.get(attr)
+        for _ in range(6):
+            # Unwrap Optional/Union to the first real arm; keep class-origin
+            # aliases (Dict[str, X]) intact for the origin walk.
+            origin = typing.get_origin(tp)
+            if origin is None or _class_origin(tp) is not None:
+                break
+            args = [a for a in typing.get_args(tp) if a is not type(None)]
+            if not args:
+                return _UNRESOLVED
+            tp = args[0]
+        if tp is None or tp is typing.Any:
+            return _UNRESOLVED
+        if inspect.isclass(tp) or _class_origin(tp) is not None:
+            return tp
+        return _UNRESOLVED
+
+    def _resolve_attribute(
+        node: ast.AST,
+    ) -> Tuple[Optional[Any], Optional[str], Dict[Any, Any]]:
+        """Walk an Attribute chain back to a known root binding.
+
+        Returns ``(resolved_obj, failed_attr, typevar_map)`` — the map holds
+        the TypeVar bindings accumulated through generic hops so a caller
+        binding the LEAF's call result can substitute the element type
+        (``res.first()`` → ``Thing``). ``(resolved_obj, failed_attr)``:
+          * ``(obj, None)`` — fully resolved, ``obj`` is the leaf.
+          * ``(None, attr)`` — chain broke at ``attr``; the parent resolved
+            to a known class/object but ``attr`` is not on it. Caller can
+            report this as a violation.
+          * ``(None, None)`` — couldn't even find the root binding, or hit a
+            hop we cannot type; ignore (fail-open, never a false violation).
+        """
+        chain: List[str] = []
+        cur = node
+        while True:
+            if isinstance(cur, ast.Attribute):
+                chain.append(cur.attr)
+                cur = cur.value
+            elif isinstance(cur, ast.Call):
+                # Step INTO the call result: descend to the callee — the walk
+                # below steps through its return annotation at this hop, so
+                # chains THROUGH calls (`api.things.search(q).bogus()`) are
+                # finally validated instead of silently dropped.
+                cur = cur.func
+            else:
+                break
+        if not isinstance(cur, ast.Name):
+            return None, None, {}
+        root = name_bindings.get(cur.id)
+        if root is None:
+            return None, None, {}
+        chain.reverse()
+        obj: Any = root
+        typevar_map: Dict[Any, Any] = {}
+        for i, attr in enumerate(chain):
+            # Step through property/method return types so subsequent attrs
+            # resolve against the class they return.
+            obj = _step_through_return(obj, typevar_map)
+            if obj is _UNRESOLVED:
+                # Fail-open: a hop we cannot type ends VALIDATION of this
+                # chain — it must never end at a false violation.
+                return None, None, typevar_map
+            origin = _class_origin(obj)
+            if origin is not None:
+                # Parameterized runtime generic: bind its TypeVars (element
+                # type), then walk the origin class's real attributes.
+                # (3.14: ``__parameters__`` on a plain builtin origin like
+                # ``dict`` resolves to a non-iterable descriptor — only a
+                # real tuple carries TypeVars to bind.)
+                params = getattr(origin, "__parameters__", ())
+                if not isinstance(params, tuple):
+                    params = ()
+                typevar_map = dict(zip(params, typing.get_args(obj)))
+                obj = origin
+            if inspect.isclass(obj):
+                if hasattr(obj, attr):
+                    obj = getattr(obj, attr)
+                    continue
+                ftp = _declared_field_type(obj, attr)
+                if ftp is None:
+                    return None, attr, typevar_map
+                if ftp is _UNRESOLVED:
+                    return None, None, typevar_map
+                if i == len(chain) - 1:
+                    # The leaf is a field VALUE (an instance of ftp). Our only
+                    # callers are about to treat the leaf as a call target —
+                    # modelling instance callability is out of scope, so fail
+                    # open rather than validate against the class's ctor.
+                    return None, None, typevar_map
+                obj = ftp
+                continue
+            if hasattr(obj, attr):
+                obj = getattr(obj, attr)
+            else:
+                return None, attr, typevar_map
+        return obj, None, typevar_map
+
+    def _bind_value(value: ast.expr) -> Optional[Any]:
+        """What a bound name should resolve to, or None to leave it unbound
+        (fail-open). A Name passes its existing binding through (aliases,
+        ``with client as c``); a Name-constructor call binds the class itself
+        (instances walk attrs via the class — the original semantics); an
+        attribute-chain call binds the call's RESULT type by stepping through
+        the resolved callee's return annotation, so
+        ``res = c.things.search(q)`` binds ``res`` to ``_Paginator[Thing]``."""
+        if isinstance(value, ast.Name):
+            return name_bindings.get(value.id)
+        if not isinstance(value, ast.Call):
+            return None
+        fn = value.func
+        if isinstance(fn, ast.Name):
+            return name_bindings.get(fn.id)
+        if isinstance(fn, ast.Attribute):
+            resolved, _failed, tv = _resolve_attribute(fn)
+            if resolved is None:
+                return None
+            stepped = _step_through_return(resolved, tv)
+            return None if stepped is _UNRESOLVED else stepped
+        return None
+
+    def _validate_call_kwargs(target: Any, node: ast.Call) -> None:
+        """Flag kwargs the resolved callable does not accept."""
+        try:
+            sig = inspect.signature(target)
+        except (TypeError, ValueError):
+            return  # C-implemented callables without introspectable signatures
+        accepted = set(sig.parameters.keys())
+        # Chains resolve methods on the CLASS (plain functions), so inspect
+        # keeps the 'self' slot — never a real keyword for the caller:
+        # `search(self=1, …)` must flag, and the Accepted list must not
+        # advertise it.
+        accepted.discard("self")
+        has_var_kw = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+        for kw in node.keywords:
+            if kw.arg is None:
+                continue  # **kwargs splat — can't statically check
+            if kw.arg not in accepted and not has_var_kw:
+                violations.append(
+                    CheckViolation(
+                        "kwarg",
+                        f"line {node.lineno}",
+                        f"{ast.unparse(node.func)}(...) does not accept keyword '{kw.arg}'. "
+                        f"Accepted: {sorted(accepted)}",
+                    )
+                )
+
+    def _iter_source_order(t: ast.AST):
+        """Pre-order DFS = source order for statements. ``ast.walk`` is
+        BREADTH-first: a module-level rebinding on line 25 would be processed
+        before a call on line 20 inside a line-18 loop body, so the late
+        binding would pollute validation of earlier, deeper code (a measured
+        false positive on the corpus). Flow-insensitive bindings are only
+        sound when they apply to code at-or-after their own line."""
+        for child in ast.iter_child_nodes(t):
+            yield child
+            yield from _iter_source_order(child)
+
+    for node in _iter_source_order(tree):
+        # Track bindings so subsequent attribute walks have a starting class:
+        # plain assigns, annotated assigns (`c: Shop = Shop()` is an
+        # ast.AnnAssign, NOT an Assign), and with-items (`with Shop() as c:`
+        # — BaseAPI.__enter__ returns self, so the context class is exact).
+        # Each previously fell open silently, skipping ALL validation of the
+        # bound name's chains.
+        if isinstance(node, ast.Assign) and isinstance(node.value, (ast.Call, ast.Name)):
+            bound = _bind_value(node.value)
+            if bound is not None:
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        name_bindings[target.id] = bound
+        elif (
+            isinstance(node, ast.AnnAssign)
+            and node.value is not None
+            and isinstance(node.target, ast.Name)
+        ):
+            bound = _bind_value(node.value)
+            if bound is not None:
+                name_bindings[node.target.id] = bound
+        elif isinstance(node, (ast.With, ast.AsyncWith)):
+            for item in node.items:
+                if isinstance(item.optional_vars, ast.Name):
+                    bound = _bind_value(item.context_expr)
+                    if bound is not None:
+                        name_bindings[item.optional_vars.id] = bound
+
+        # Validate method calls + kwargs against resolved targets.
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            resolved, failed_attr, _tv = _resolve_attribute(node.func)
+            if resolved is None:
+                if failed_attr is not None:
+                    # Chain resolved partway but the final method isn't on
+                    # the resolved class — that's a real ergonomics bug.
+                    violations.append(
+                        CheckViolation(
+                            "method",
+                            f"line {node.lineno}",
+                            f"{ast.unparse(node.func)}: no method/attribute {failed_attr!r} on the resolved type.",
+                        )
+                    )
+                # else: couldn't resolve root — ignore (runtime-only binding).
+                continue
+            if not callable(resolved):
+                violations.append(
+                    CheckViolation(
+                        "method",
+                        f"line {node.lineno}",
+                        f"{ast.unparse(node.func)} is not callable (resolved to {type(resolved).__name__}).",
+                    )
+                )
+                continue
+            _validate_call_kwargs(resolved, node)
+        elif isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+            # Constructor / factory calls (`Reddit(api_keyy='x')`) were never
+            # kwarg-validated. inspect.signature on a class binds through
+            # __init__ with 'self' already excluded.
+            target = name_bindings.get(node.func.id)
+            if inspect.isclass(target):
+                _validate_call_kwargs(target, node)
+
+    return CheckReport(
+        ok=not violations,
+        module_source="",  # caller can fetch source separately
+        public_symbols=public_symbols(module),
+        violations=violations,
+    )