parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/checks.py

@@ -0,0 +1,601 @@
+"""Staged-artifact promotion gates.
+
+`parse sync` builds the next `parse_apis` tree in a staging directory and must
+prove three invariants before it overwrites the user's live tree, because a bad
+promotion is hard to undo and ships straight into the user's repo:
+
+  1. ``scan_secrets`` — no vendor key / JWT / high-entropy blob leaked into a
+     generated file (the agent writes free-text docstrings + examples, so a
+     leaked credential lands in prose, not a quoted literal).
+  2. ``check_generated_client_imports`` — generated code imports ONLY the
+     runtime (``parse_sdk._runtime`` / bare ``from parse_sdk import ...``), never
+     ``parse_sdk.config`` (resolution is internal to ``_runtime.BaseAPI``) and
+     never a generated client from ``parse_sdk.<slug>`` (the deleted v1
+     dynamic-model vestige, C-1).
+  3. ``check_docs_import_model`` — generated prose teaches the installed-package
+     model (``from parse_apis.<slug> import`` + "installed editable package"),
+     not the stale flat on-disk model (C-4).
+
+Each gate returns a flat ``list[tuple[Path, str]]`` of findings; an empty list
+means the tree passed. The caller (sync promotion) treats any non-empty list as
+a hard block. Functions are pure: they read the tree and return findings, they
+never mutate it.
+
+The secret detectors here are the SINGLE SOURCE of the pattern families —
+``tests/_secret_patterns.py`` re-exports them (the shipped package must not
+depend on its own test tree, so tests → package is the only legal direction;
+the prior hand-mirrored copy drifted once and the name-only parity test
+could not see regex-body drift). The families are DERIVED from
+``parse_core.security.code_sanitizer._SUSPICIOUS_PATTERNS`` and reshaped for
+generated-output scanning; family coverage against that backend upstream is
+pinned by ``test_no_secrets_codegen.py::test_covers_known_secret_families``.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+# --- secret-shape detectors ------------------------------------------------
+#
+# SINGLE SOURCE (tests/_secret_patterns.py re-exports these). PREFIXED are
+# re.search'd over the whole file text — de-anchored so a token in docstring
+# PROSE still matches; ENTROPY are re.fullmatch'd against string-literal
+# VALUES only so CamelCase forward-refs like 'PostCommentsCollection' on
+# every generated module do not false-positive.
+
+_PREFIXED_SIGNATURES: List[Tuple[str, "re.Pattern[str]"]] = [
+    ("jwt", re.compile(r"eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+")),
+    ("bearer_token", re.compile(r"Bearer\s+[A-Za-z0-9._\-+/=]{20,}")),
+    ("vendor_key", re.compile(r"(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,}")),
+    ("github_pat", re.compile(r"ghp_[A-Za-z0-9]{30,}")),
+    ("github_oauth", re.compile(r"gho_[A-Za-z0-9]{30,}")),
+    ("aws_access_key", re.compile(r"AKIA[A-Z0-9]{12,}")),
+    ("slack_token", re.compile(r"xox[bpsa]-[A-Za-z0-9\-]{10,}")),
+    ("credential_assignment", re.compile(r'(?:password|passwd|secret|token|api_key)\s*=\s*["\']([^"\']{6,})["\']', re.IGNORECASE)),
+    ("session_cookie", re.compile(r'(?:cookie|session_id|csrf|xsrf)\s*[:=]\s*["\']([^"\']{10,})["\']', re.IGNORECASE)),
+]
+
+# Placeholder shapes a credential-assignment VALUE may take BY CONSTRUCTION:
+# an angle-bracket template (`<paste-token-here>`) or an UPPERCASE_UNDERSCORE
+# name (`YOUR_API_KEY`). Letters + underscores only, at least one underscore —
+# NO digit class: admitting digits would exempt real key alphabets (AWS access
+# keys, base32 TOTP seeds, uppercase-alnum vendor keys), and on `.md` surfaces
+# this family is the only net (the entropy scan is `.py`-gated).
+_PLACEHOLDER_VALUE_RE = re.compile(r"^(?:<[^<>]{1,40}>|[A-Z][A-Z_]*_[A-Z_]{1,38})$")
+
+
+def is_placeholder_value(value: str) -> bool:
+    """Whether a ``credential_assignment`` VALUE is placeholder-shaped —
+    ``api_key="YOUR_API_KEY"`` teaches, it doesn't leak. Applies ONLY to that
+    family's value position; every other family scans unconditionally."""
+    return _PLACEHOLDER_VALUE_RE.fullmatch(value) is not None
+
+
+_ENTROPY_PATTERNS: List[Tuple[str, "re.Pattern[str]"]] = [
+    ("long_base64", re.compile(r"[A-Za-z0-9+/=]{30,}")),
+    ("long_hex", re.compile(r"[a-fA-F0-9]{32,}")),
+    ("short_base64", re.compile(r"[A-Za-z0-9+/=]{20,29}")),
+]
+
+
+def _iter_text_files(tree: Path, *, recursive: bool = True):
+    """Yield ``(path, text)`` for every readable UTF-8 file under ``tree``.
+
+    Binary / non-UTF-8 files (a stray ``.png``, a corrupt artifact) are SKIPPED
+    rather than crashing the gate: a promotion check must survive whatever the
+    codegen wrote, and a non-text file cannot carry a text-shaped secret or a
+    Python/Markdown import we care about. Directories and unreadable entries are
+    skipped for the same reason.
+
+    ``recursive=False`` scans only the entries directly in ``tree`` (not its
+    subdirectories) — used by the sync engine's whole-tree pre-promotion pass,
+    which gates only the top-level artifacts because each slug dir was already
+    gated individually (see ``_sync.stage_check_swap`` step 4).
+    """
+    entries = tree.rglob("*") if recursive else tree.iterdir()
+    for path in sorted(entries):
+        if not path.is_file():
+            continue
+        try:
+            yield path, path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+
+
+# Structural codegen literal sinks, split by HOW MUCH of the node is
+# name-position by construction. An alphanumeric-only schema name of 20+ chars
+# full-matches the entropy band (the same false-positive class that once
+# blocked every module's sync on the re-exported 'PaginationLimitError', and
+# again on long camelCase `_FIELD_ALIASES` values) — but only NAME positions
+# may be exempted: a request dict's VALUES are agent/user data (a pin literal,
+# `_params = {"api_key": "<blob>"}` in an agent-authored example) and must
+# stay scanned.
+_STRUCTURAL_SUBSCRIPT_TARGETS = frozenset({
+    "_params", "_p",            # request dicts: only the SUBSCRIPT KEY is a wire name
+})
+_STRUCTURAL_MAP_TARGETS = frozenset({
+    "_CARRY_PARAMS",            # error carry map: {attr ident: wire param}
+    "_FIELD_ALIASES",           # resource alias map: {field ident: wire field}
+    "_KEY_FIELD",               # resource key field ident (plain string)
+    "_ERROR_CLASSES",           # {wire kind: class}
+    "_RESOURCE_CLASSES",        # {label: class}
+})
+# Receiver roots of the codegen-emitted `.get(...)` / `in` shapes whose first
+# arg / left operand is a response-path or field NAME (`_resp.get(...)`,
+# `items[-1].get(...)`, `_last._FIELD_ALIASES.get(...)`, `'<items_path>' not
+# in _resp`). Constrained to these roots so `anything.get('<blob>')` in an
+# agent-authored example stays scanned; the all-name-slots invariant test
+# proves the set covers every emission shape.
+_STRUCTURAL_RECEIVER_ROOTS = frozenset({"_resp", "items", "_last", "_coerced"})
+
+
+def _is_emitted_str_enum(node: "ast.ClassDef") -> bool:
+    """Whether a class statement is codegen's exact enum emission shape —
+    ``class X(str, enum.Enum)``. Both bases are required: the closed shape
+    keeps a hand-written ``class X(Enum)`` in an agent-authored example
+    outside the exemption."""
+    has_str = any(isinstance(b, ast.Name) and b.id == "str" for b in node.bases)
+    has_enum = any(
+        isinstance(b, ast.Attribute) and b.attr == "Enum"
+        and isinstance(b.value, ast.Name) and b.value.id == "enum"
+        for b in node.bases
+    )
+    return has_str and has_enum
+
+
+def _expr_root_name(expr: ast.expr) -> Optional[str]:
+    """The root ``Name`` of an attribute/subscript/call chain (``items[-1]`` →
+    ``items``; ``_last._FIELD_ALIASES`` → ``_last``), or None."""
+    node = expr
+    while isinstance(node, (ast.Attribute, ast.Subscript, ast.Call)):
+        node = node.func if isinstance(node, ast.Call) else node.value
+    return node.id if isinstance(node, ast.Name) else None
+
+
+def _is_structural_receiver(expr: ast.expr) -> bool:
+    """The two receiver shapes codegen emits as the 1st positional arg of an
+    items-extraction call: a bare structural receiver (``_resp``), or the
+    ``_walk(_resp, '<parent>')`` wrapper of a DOTTED ``items_path`` (whose own
+    receiver is structural). The wrapper case lets the entropy exemption reach
+    the LEAF arg of ``_extract_items(_walk(_resp, '<parent>'), '<leaf>')``.
+    A CLOSED set — codegen never nests ``_walk`` deeper, so this does NOT
+    recurse: a genuinely new shape stays scanned (fails closed) rather than
+    being silently exempt."""
+    if isinstance(expr, ast.Name):
+        return expr.id in _STRUCTURAL_RECEIVER_ROOTS
+    return (
+        isinstance(expr, ast.Call)
+        and isinstance(expr.func, ast.Name)
+        and expr.func.id == "_walk"
+        and len(expr.args) >= 1
+        and isinstance(expr.args[0], ast.Name)
+        and expr.args[0].id in _STRUCTURAL_RECEIVER_ROOTS
+    )
+
+
+@dataclass
+class _ModuleFacts:
+    """Everything the secret/import gates need from a parsed module, collected
+    in ONE ``ast.walk``. ``_emitted_names`` / ``_structural_literal_values`` /
+    ``_string_literal_values`` and the import gate were four independent walks
+    over the same tree (the dominant cost of a fleet sync's gate pass); this
+    fuses them. Each field carries exactly what the corresponding old walk
+    produced — moved verbatim, not "simplified" — so the gate verdicts are
+    byte-identical (proven on the corpus). ``literals`` is UNFILTERED and in
+    ``ast.walk`` order (first-entropy-hit-per-family depends on that order);
+    ``import_modules`` is in walk order so import findings keep their sequence.
+    """
+    names: set[str]                  # identifiers BOUND in the module
+    structural: set[str]             # schema-derived codegen-emission literals
+    literals: List[Tuple[str, int]]  # (value, lineno) per str Constant, unfiltered
+    import_modules: List[str]        # absolute dotted import names (level==0)
+
+
+def _module_facts(module: ast.AST) -> _ModuleFacts:
+    """Single-pass collector — see :class:`_ModuleFacts`. One ``ast.walk``
+    produces four fact sets used by the staged-promotion gates: bound
+    identifiers (``names``), schema-derived structural literals (``structural``),
+    every string literal in walk order (``literals``), and absolute import
+    module names (``import_modules``).
+
+    ``names`` and ``structural`` are exempted from the ENTROPY secret families
+    ONLY (prefixed signatures still search raw text), and only NAME positions are
+    exempt. ``names`` covers a generated module's bound identifiers — class/func
+    names AND re-exported runtime errors (``PaginationLimitError``'s 20-char
+    spelling would otherwise full-match the entropy band and block every sync).
+    ``structural`` covers the schema NAMES quoted in codegen's closed emission
+    shapes: request subscript keys, ``_STRUCTURAL_MAP_TARGETS`` / ``_DISPLAYS_*``
+    map entries, ``str``-enum member values, ``Literal[...]`` codes, and the
+    ``_request`` / ``.get`` / membership-test name slots. A pin's literal VALUE,
+    request-dict values, and param defaults all stay scanned. The closed
+    shape-set is pinned from both sides in ``tests/test_staging_checks.py``
+    (all-name-slots invariant + recall fixtures); ``test_no_secrets_codegen.py``
+    drives the same path via ``_string_literal_values`` so the gate is
+    single-source.
+
+    The nested ``ast.walk`` calls in the structural block walk a SUBTREE (an
+    assigned value / a ``Literal[...]`` slice), not the module, so they are not
+    extra module passes."""
+    names: set[str] = set()
+    structural: set[str] = set()
+    literals: List[Tuple[str, int]] = []
+    import_modules: List[str] = []
+    for node in ast.walk(module):
+        # 1) bound identifiers: class/func names, assign targets, imports
+        if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            names.add(node.name)
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    names.add(target.id)
+        elif isinstance(node, ast.AnnAssign):
+            if isinstance(node.target, ast.Name):
+                names.add(node.target.id)
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                names.add(alias.asname or alias.name)
+
+        # 2) schema-derived structural literals (closed codegen emission shapes)
+        targets: List[ast.expr] = []
+        if isinstance(node, ast.Assign):
+            targets = list(node.targets)
+        elif isinstance(node, ast.AnnAssign):
+            targets = [node.target]
+        for target in targets:
+            if (
+                isinstance(target, ast.Subscript)
+                and isinstance(target.value, ast.Name)
+                and target.value.id in _STRUCTURAL_SUBSCRIPT_TARGETS
+                and isinstance(target.slice, ast.Constant)
+                and isinstance(target.slice.value, str)
+            ):
+                structural.add(target.slice.value)
+            elif (
+                isinstance(target, ast.Name)
+                and (target.id in _STRUCTURAL_MAP_TARGETS
+                     or target.id.startswith("_DISPLAYS_"))
+                and getattr(node, "value", None) is not None
+            ):
+                for sub in ast.walk(node.value):  # type: ignore[union-attr]
+                    if isinstance(sub, ast.Constant) and isinstance(sub.value, str):
+                        structural.add(sub.value)
+        if isinstance(node, ast.ClassDef) and _is_emitted_str_enum(node):
+            for stmt in node.body:
+                if (
+                    isinstance(stmt, ast.Assign)
+                    and isinstance(stmt.value, ast.Constant)
+                    and isinstance(stmt.value.value, str)
+                ):
+                    structural.add(stmt.value.value)
+        if (
+            isinstance(node, ast.Subscript)
+            and isinstance(node.value, ast.Name)
+            and node.value.id == "Literal"
+        ):
+            for sub in ast.walk(node.slice):
+                if isinstance(sub, ast.Constant) and isinstance(sub.value, str):
+                    structural.add(sub.value)
+        # The items-extraction helper ``_extract_items(_resp, '<items_path>')``
+        # and the dotted-path resolver ``_walk(_resp, '<a.b>')`` — bare-Name calls
+        # (not attribute calls). The 2nd positional arg is a declared wire path /
+        # NAME by construction (the same wire name the legacy
+        # ``_resp.get('<items_path>')`` / ``'<items_path>' not in _resp`` shapes
+        # already exempt). The 1st arg is a structural receiver: ``_resp``, OR —
+        # for a DOTTED items_path — the ``_walk(_resp, '<parent>')`` wrapper of
+        # ``_extract_items(_walk(_resp, '<parent>'), '<leaf>')``, so the LEAF wire
+        # name is exempt too. Exempt the wire-name arg from the entropy families.
+        if (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Name)
+            and node.func.id in ("_extract_items", "_walk")
+            and len(node.args) >= 2
+            and _is_structural_receiver(node.args[0])
+        ):
+            second = node.args[1]
+            if isinstance(second, ast.Constant) and isinstance(second.value, str):
+                structural.add(second.value)
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            if node.func.attr == "_request":
+                for arg in node.args[:2]:
+                    if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+                        structural.add(arg.value)
+            elif (
+                node.func.attr == "get"
+                and node.args
+                and _expr_root_name(node.func.value) in _STRUCTURAL_RECEIVER_ROOTS
+            ):
+                first = node.args[0]
+                if isinstance(first, ast.Constant) and isinstance(first.value, str):
+                    structural.add(first.value)
+        if isinstance(node, ast.Compare):
+            if (
+                isinstance(node.left, ast.Constant)
+                and isinstance(node.left.value, str)
+                and any(isinstance(op, (ast.In, ast.NotIn)) for op in node.ops)
+                and len(node.comparators) == 1
+                and _expr_root_name(node.comparators[0]) in _STRUCTURAL_RECEIVER_ROOTS
+            ):
+                structural.add(node.left.value)
+
+        # 3) every string literal, unfiltered + in walk order (was the final
+        #    loop in _string_literal_values; the caller filters by excluded set)
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            literals.append((node.value, node.lineno))
+
+        # 4) absolute import module names (was check_generated_client_imports'
+        #    walk); relative imports (level>0) and module-less forms are skipped,
+        #    exactly as the gate does, so the caller's allow-check is unchanged.
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                import_modules.append(alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            if not node.level and node.module is not None:
+                import_modules.append(node.module)
+
+    return _ModuleFacts(names, structural, literals, import_modules)
+
+
+def _string_literal_values(
+    text: str, *, structural_exempt: bool = True
+) -> List[Tuple[str, int]]:
+    """Extract entropy-eligible ``(value, lineno)`` string-literal pairs from
+    Python source.
+
+    Entropy families would false-positive on long identifiers (class names,
+    dotted module paths) if matched over raw text, so we restrict them to actual
+    string-literal values via ``ast`` AND drop any value that equals an
+    identifier defined in this module (a forward-ref annotation / ``__all__``
+    entry — the documented CamelCase false-positive class) or — when
+    ``structural_exempt`` is on — a schema-derived structural literal from the
+    known codegen sinks (the ``structural`` set computed by :func:`_module_facts`).
+
+    ``structural_exempt`` is the provenance gate: the structural shapes are
+    things CODEGEN emits, so only the file class codegen emits (the generated
+    client module) gets their exemption — an agent-authored ``example.py``
+    re-creating one of those shapes (a ``Literal['<blob>']`` annotation, a
+    ``_DISPLAYS_*`` map) stays fully scanned. Exclusion is by value equality
+    over the file: inside an emitted module a literal equal to an emitted
+    name/code is that name by construction (e.g. a closed param's default is
+    one of its codes).
+
+    Non-parseable text yields no literals — the prefixed group still scans the
+    raw text, so prefixed secrets in a syntax-broken file are not missed. The
+    lineno rides along so a finding can point at the offending line.
+
+    Parses once and reads :func:`_module_facts` (one walk) for the names,
+    structural literals, and unfiltered literal list; the filter (drop any value
+    equal to a bound name, plus structural literals when ``structural_exempt``)
+    is applied here. ``scan_tree`` does not route through this function — it
+    holds the parsed module already and reads ``_module_facts`` directly — so a
+    staged ``.py`` file is parsed exactly once per scan. This standalone form
+    exists for direct test consumers (``tests/test_no_secrets_codegen.py``).
+    """
+    try:
+        module = ast.parse(text)
+    except (SyntaxError, ValueError):
+        return []
+    facts = _module_facts(module)
+    excluded = facts.names | (facts.structural if structural_exempt else set())
+    return [(v, ln) for v, ln in facts.literals if v not in excluded]
+
+
+def _mask(value: str) -> str:
+    """A finding's value hint: first 4 chars + length — never more of the
+    value (the gate's whole point is that it might be a real secret)."""
+    return f"'{value[:4]}…', {len(value)} chars"
+
+
+@dataclass
+class TreeFindings:
+    """All gate findings from ONE pass over a staged tree — read each file once,
+    parse each ``.py`` once, run every check off the cached text/AST. The three
+    public gates are thin projections of this; ``_sync``'s promotion gate reads
+    all four lists. ``syntax_errors`` is engine-internal (the public
+    ``scan_secrets`` never compiled) — only the sync gate consumes it, replacing
+    its old separate ``rglob('__init__.py')`` compile loop."""
+    secrets: List[Tuple[Path, str, int, str]]
+    forbidden_imports: List[Tuple[Path, str]]
+    stale_docs: List[Tuple[Path, str]]
+    syntax_errors: List[Tuple[Path, str]]
+
+
+def scan_tree(tree: Path, *, recursive: bool = True) -> TreeFindings:
+    """Single-pass promotion scanner: read each file once and run every gate.
+
+    Per file: the prefixed secret signatures over raw text; for ``.py`` files
+    one ``ast.parse`` feeding :func:`_module_facts` (entropy families + the
+    generated-client import allow-check); a ``compile`` syntax gate on each
+    ``__init__.py``; the stale-doc needle scan on doc files. Findings are
+    appended in ``_iter_text_files`` (sorted-path) order, so each list matches
+    exactly what the old per-gate functions produced — verdicts are unchanged
+    (pinned by the equivalence test in ``tests/test_staging_checks.py``). This
+    replaces three independent ``_iter_text_files`` walks + up to three parses
+    per ``.py`` with one read and one parse per file."""
+    secrets: List[Tuple[Path, str, int, str]] = []
+    forbidden_imports: List[Tuple[Path, str]] = []
+    stale_docs: List[Tuple[Path, str]] = []
+    syntax_errors: List[Tuple[Path, str]] = []
+    for path, text in _iter_text_files(tree, recursive=recursive):
+        seen: set[str] = set()
+        # Prefixed signatures — raw text (catches tokens in docstring prose).
+        for family, pattern in _PREFIXED_SIGNATURES:
+            if family in seen:
+                continue
+            if family == "credential_assignment":
+                # Placeholder carve-out: flag only when some matched VALUE is
+                # not placeholder-shaped (group 1 is the quoted value).
+                m = next((m for m in pattern.finditer(text)
+                          if not is_placeholder_value(m.group(1))), None)
+            else:
+                m = pattern.search(text)
+            if m is not None:
+                lineno = text.count("\n", 0, m.start()) + 1
+                # Mask the captured VALUE when the family has one
+                # (credential_assignment/session_cookie); else the whole match.
+                masked_src = m.group(1) if m.groups() else m.group(0)
+                secrets.append((path, family, lineno, _mask(masked_src)))
+                seen.add(family)
+        if path.suffix == ".py":
+            try:
+                module: Optional[ast.AST] = ast.parse(text)
+            except (SyntaxError, ValueError):
+                module = None
+            if module is not None:
+                facts = _module_facts(module)
+                # Entropy families — string-literal values only. The structural
+                # (emission-shape) exemption applies ONLY to the generated
+                # client module (codegen emits exactly ``__init__.py``); an
+                # agent-authored example re-creating an emission shape stays
+                # scanned.
+                excluded = facts.names | (
+                    facts.structural if path.name == "__init__.py" else set())
+                literals = [(v, ln) for v, ln in facts.literals if v not in excluded]
+                for family, pattern in _ENTROPY_PATTERNS:
+                    if family in seen:
+                        continue
+                    hit = next(((v, ln) for v, ln in literals
+                                if pattern.fullmatch(v)), None)
+                    if hit is not None:
+                        value, lineno = hit
+                        secrets.append((path, family, lineno, _mask(value)))
+                        seen.add(family)
+                # Generated-client import allow-check (every .py, incl.
+                # example.py — a forbidden import there must not slip through).
+                for mod in facts.import_modules:
+                    offending = _is_offending_parse_sdk_module(mod)
+                    if offending is not None:
+                        forbidden_imports.append((path, offending))
+            # Syntax gate: compile() catches post-AST errors ast.parse accepts
+            # (return/yield outside a function, duplicate args); run on every
+            # __init__.py even when ast.parse above failed.
+            if path.name == "__init__.py":
+                try:
+                    compile(module if module is not None else text, str(path), "exec")
+                except SyntaxError as e:
+                    syntax_errors.append((path, str(e)))
+        if _is_doc_file(path):
+            for needle in _STALE_DOC_NEEDLES:
+                if needle in text:
+                    stale_docs.append((path, needle))
+    return TreeFindings(secrets, forbidden_imports, stale_docs, syntax_errors)
+
+
+def scan_secrets(tree: Path, *, recursive: bool = True) -> List[Tuple[Path, str, int, str]]:
+    """Flag secret-shaped content in every text file under ``tree``.
+
+    Returns ``(path, family, lineno, masked)`` per finding — ``masked`` shows
+    the first 4 chars and the length, never more of the value, so a finding is
+    actionable (which literal, on which line) without re-leaking what the gate
+    just caught. Prefixed signatures are searched over the whole file text
+    (catching tokens that land in docstring prose, where they are not their
+    own quoted literal). Entropy families are full-matched against Python
+    string-literal values only, so generated CamelCase forward-refs
+    (``PostCommentsCollection``) never trip them.
+
+    A file with multiple distinct families flagged yields one finding per
+    family; the same family is reported once per file, pointing at its first
+    occurrence (the caller blocks on any finding, so per-occurrence noise adds
+    nothing). A thin projection of :func:`scan_tree`."""
+    return scan_tree(tree, recursive=recursive).secrets
+
+
+# --- generated-client import gate (C-1) ------------------------------------
+
+# A generated module may import the runtime surface and re-export from the
+# package root, nothing else under ``parse_sdk``. The allow-list is exactly
+# ``parse_sdk._runtime``: credential resolution is an INTERNAL detail
+# of ``_runtime.BaseAPI`` (which delegates to ``parse_sdk.config``), so generated
+# code never imports ``parse_sdk.config`` directly and the gate does not whitelist
+# it — keeping ``config`` (which exposes ``save_credentials``) off generated
+# code's import surface. A bare ``from parse_sdk import X`` pulls package-level
+# names (``__version__``, errors) and is allowed. Anything else —
+# ``parse_sdk.config``, ``parse_sdk.<slug>``, ``parse_sdk.codegen_v2``, etc. — is
+# flagged.
+_ALLOWED_PARSE_SDK_SUBMODULES = frozenset({"_runtime"})
+
+
+def _is_offending_parse_sdk_module(module: str) -> str | None:
+    """Return the offending dotted module if ``module`` is a banned parse_sdk import.
+
+    ``module`` is a fully-qualified module name (``parse_sdk``,
+    ``parse_sdk._runtime``, ``parse_sdk.reddit``, …). Bare ``parse_sdk`` and the
+    runtime submodules are allowed; any other ``parse_sdk.<x>`` is offending and
+    returned verbatim so the caller can surface exactly what to fix.
+
+    A slug literally named like a runtime module (e.g. a ``parse_sdk._runtime``
+    import) is allowed by membership — the allow-set is checked on the FIRST
+    path segment after ``parse_sdk``, so deeper paths like
+    ``parse_sdk._runtime.foo`` are still allowed (they resolve into the runtime).
+    """
+    if module == "parse_sdk":
+        return None
+    if not module.startswith("parse_sdk."):
+        return None
+    first_segment = module[len("parse_sdk."):].split(".", 1)[0]
+    if first_segment in _ALLOWED_PARSE_SDK_SUBMODULES:
+        return None
+    return module
+
+
+def check_generated_client_imports(tree: Path, *, recursive: bool = True) -> List[Tuple[Path, str]]:
+    """Flag generated ``.py`` files that import a non-runtime ``parse_sdk`` module.
+
+    Uses ``ast`` (not regex) so aliased (``import parse_sdk.reddit as r``),
+    parenthesized, multiline, and whitespace-padded imports are all normalized
+    to their dotted module name before the allow-check. Relative imports
+    (``from . import x``) are ignored — they are package-internal and cannot
+    name ``parse_sdk.<slug>``. Returns ``(path, offending_module)``.
+
+    A file that fails to parse is skipped (a broken generated module is a codegen
+    bug surfaced elsewhere; this gate concerns only well-formed import shapes).
+
+    A thin projection of :func:`scan_tree` (the import allow-check runs off the
+    same single per-file parse as the secret scan)."""
+    return scan_tree(tree, recursive=recursive).forbidden_imports
+
+
+# --- docs import-model gate (C-4) ------------------------------------------
+
+# Stale import-model prose to flag in generated docs (.md / .py). Each needle is
+# a removed/old teaching: the deleted dynamic-model client import
+# (``parse_sdk.<slug>``, ``parse.api(``) or the flat on-disk model
+# (run-from-root + "no import magic" + project-local-package prose). The
+# current, correct teaching is the installed editable package, which contains
+# none of these needles, so it passes cleanly.
+_STALE_DOC_NEEDLES: Tuple[str, ...] = (
+    "parse_sdk.",          # generated-client import from parse_sdk.<slug>
+    "parse.api(",          # deleted dynamic-model call spelling
+    "no import magic",     # flat on-disk model prose
+    "from the project root",  # "Run scripts from the project root" prose
+    "project-local package",  # flat on-disk path prose
+)
+
+
+def _is_doc_file(path: Path) -> bool:
+    """A human/agent-facing DOC: any ``.md`` (README + AGENTS/CLAUDE index) or the
+    generated ``example.py``. The generated client module (``__init__.py``)
+    is NOT a doc — it legitimately imports ``parse_sdk._runtime`` (substring
+    ``parse_sdk.``), so scanning it here would false-positive on every module;
+    its imports are gated by :func:`check_generated_client_imports` instead.
+    """
+    return path.suffix == ".md" or path.name == "example.py"
+
+
+def check_docs_import_model(tree: Path, *, recursive: bool = True) -> List[Tuple[Path, str]]:
+    """Flag generated docs that teach a removed/stale SDK import model.
+
+    Scans doc files (``.md`` + ``example.py``) for any stale-needle substring and
+    returns ``(path, needle)`` per hit. The installed-package model
+    (``from parse_apis.<slug> import`` + "installed editable package") contains
+    none of the needles, so a correct doc returns no findings.
+
+    Substring matching is intentional — prose can wrap or reflow, but the stale
+    teachings ("no import magic", "from the project root") are stable phrases,
+    and ``parse_sdk.`` / ``parse.api(`` are exact code spellings that must never
+    reappear in shipped docs.
+
+    A thin projection of :func:`scan_tree`."""
+    return scan_tree(tree, recursive=recursive).stale_docs