feat(decorator): add auto error discovery to with_errors

with_errors(router, auto=True) fills responses by statically walking each
endpoint and its whole dependency tree at registration (the same walk as
check_raises), merged with any explicit Raises[...]. The Dependant tree is
rebuilt via public get_dependant/get_parameterless_sub_dependant with a lazy
import + endpoint-only fallback; _dependency_calls/_is_security_scheme move to
decorator.wrapper as the shared layer the checker imports from.

Author: feodor-ra

CLAUDE.md

@@ -6,15 +6,15 @@ Public PyPI package: typed HTTP errors for FastAPI — exact `Literal` error cod
 
 ## Status
 
-Draft. The `core` and `decorator` layers plus the layer-3 CI checker are implemented (the analysis `auto`-fill mode is not yet). Linters/type checker and pytest are configured (see Conventions); the whole package is at 100% branch coverage. Licensed under MIT (`LICENSE` + PEP 639 metadata in `pyproject.toml`).
+Draft. All three layers are implemented — `core`, the `with_errors` decorator (with `auto`-fill), and the layer-3 analysis (CI checker `check_raises` + CLI). Linters/type checker and pytest are configured (see Conventions); the whole package is at 100% branch coverage. Licensed under MIT (`LICENSE` + PEP 639 metadata in `pyproject.toml`).
 
 ## Architecture — three independent layers
 
 Each layer is usable without the next one:
 
 1. **`core`** (done) — `BaseError`, the `BaseErrorMeta` metaclass, `ErrorResponse`, `error_models()`, `handle_base_error`.
 2. **`decorator`** (done) — `with_errors(router)` + `Raises[...]` in the return annotation (Annotated syntax). An instance patch of `add_api_route` as the single interception point; subclassing `APIRouter` AND a wrapper object were both rejected (see decorator-layer decisions).
-3. **`analysis`** (CI checker done; `auto` planned) — AST walk over `raise` statements. `check_raises()` compares declared `Raises[...]` against errors actually raised (endpoint + helpers + dependency tree); a typer CLI (`cli` extra) wraps it. `auto=True` (auto-populating `responses` from the same walk) is the remaining piece. Design inspired by fastapi-docx (MIT), whose flaws are deliberately not inherited (see analysis-layer decisions).
+3. **`analysis`** (done) — AST walk over `raise` statements. `check_raises()` compares declared `Raises[...]` against errors actually raised (endpoint + helpers + dependency tree); a typer CLI (`cli` extra) wraps it. `with_errors(router, auto=True)` reuses the same walk to auto-populate `responses` at registration. Design inspired by fastapi-docx (MIT), whose flaws are deliberately not inherited (see analysis-layer decisions).
 
 ## Layout
 
@@ -70,7 +70,9 @@ src-layout, package `src/fastapi_typed_errors/`:
 - `_BodyVisitor` descends into statement bodies only (skips annotations/decorators/defaults), so a route's own `Raises[...]` return annotation is not counted, and local nested `def`s ARE walked. Catches `raise X`, `raise X(...)`, `raise ... from e`. **Argument heuristic**: an error class passed as a call argument counts as potentially raised (the `get_or_404(error=X)` pattern) — carve-out for `isinstance`/`issubclass`. Over-approximation is safe for CI (surfaces as `undeclared`); documented false-negatives (locals, `self.*`, dynamic dispatch, bare streams) keep `overdeclared` a failure by default.
 - Two discrepancy buckets, reported separately: `undeclared` (always a failure), `overdeclared` (failure by default; `allow_overdeclared=True` strips it at report-build time). `RaisesReport.ok` = `not routes`; no `__bool__` (ambiguous).
 - CLI split: `cli.py::main()` is the console-script entry with **no top-level `typer` import** (degrades to exit 2 + install hint without the `cli` extra); `_cli.py` holds the typer app (module-level `typer.Typer()`, needs the extra). A `@cli.callback()` forces `check` to be a named subcommand (a single typer command would otherwise collapse and swallow the app-path argument). Exit codes: 0 ok, 1 discrepancies, 2 usage/loading.
-- `collect_raised`/`_scan` are the reuse point for the future `auto=True`.
+- `collect_raised`/`_scan` are the shared engine for both `check_raises` and `with_errors(auto=True)`.
+- **`auto=True`** (user decision 2026-07-23): scope = endpoint + full dependency tree (matches `check_raises`); the discovered set is **unioned** with any `Raises[...]` markers, and an explicit `responses={}` still wins per status. Injected in `wrapper` before delegating (mutating `route.responses` after build silently drops the schema — `response_fields` are frozen at build; verified). The dependency tree is rebuilt at registration (the route does not exist yet) via public `fastapi.dependencies.utils.get_dependant` + `get_parameterless_sub_dependant`, folding router-level + route-level `dependencies=[...]` (mirror `_build_dependant_with_parameterless_dependencies`); `path` is irrelevant (only path-param detection). `auto` is captured in the wrapper closure — first-`with_errors`-call wins (idempotent re-wrap does not change it).
+- Import layering for `auto`: `decorator.wrapper` cannot import `analysis` at module level (analysis already imports wrapper → cycle). So `collect_raised` is **lazy-imported** inside `_auto_raised`, and `get_dependant`/`get_parameterless_sub_dependant` are lazy-imported in a `try/except ImportError` → graceful degradation to endpoint-only if FastAPI moves them (tested by `delattr`-ing `get_parameterless_sub_dependant`, which fails only our combined import, not FastAPI's own bindings). `_dependency_calls`/`_is_security_scheme` live in `decorator.wrapper` (the shared lower layer both use) and are imported by `analysis.checker`.
 
 ## Conventions
 

README.md

@@ -2,7 +2,7 @@
 
 Typed error responses for FastAPI: `Literal` error codes in OpenAPI, discriminated `oneOf` unions, and a single source of truth — the error class itself.
 
-> **Status: draft.** Layers 1 (`core`), 2 (`decorator`) and the layer-3 CI checker are implemented; the analysis `auto`-fill mode is coming.
+> **Status: draft.** All three layers are implemented — `core`, the `with_errors` decorator (with `auto`-fill), and the layer-3 CI checker.
 
 ## Requirements
 
@@ -69,6 +69,21 @@ OpenAPI gets a `404` and a `403` entry with the **exact** `Literal` code each; s
 
 `with_errors(router)` returns the **same** `APIRouter` instance with its `add_api_route` patched on the instance, so object identity is preserved: `include_router`, websockets, imperative `add_api_route(...)` calls and app-level decorators all work natively. For an application, wrap its router: `with_errors(app.router)`.
 
+### Auto-fill
+
+Pass `with_errors(router, auto=True)` to drop the `Raises[...]` markers entirely: at registration each endpoint and its whole dependency tree are statically walked (the same walk the [CI checker](#ci-checker) uses), and the discovered errors fill `responses` automatically — merged with any markers you *do* write, and an explicit `responses={}` still wins per status.
+
+```python
+router = with_errors(APIRouter(), auto=True)
+
+
+@router.get("/items/{item_id}")
+def get_item(item_id: int, user: Annotated[User, Depends(current_user)]) -> Item:
+    if item_id == 0:
+        raise NotFoundError(f"No item {item_id}")  # auto -> 404
+    return Item(item_id=item_id)                    # + whatever current_user can raise
+```
+
 ## Core layer only
 
 The decorator layer is optional sugar — `responses={}` can always be filled by hand with `error_models()`:

src/fastapi_typed_errors/analysis/checker.py

@@ -1,7 +1,5 @@
 """CI checker: compare declared ``Raises`` against the errors found in code."""
 
-import functools
-import inspect
 from collections.abc import Callable, Iterator
 from dataclasses import dataclass
 from typing import Any, Protocol, cast
@@ -10,10 +8,14 @@
 from fastapi import APIRouter, FastAPI
 from fastapi.dependencies.models import Dependant
 from fastapi.routing import APIRoute
-from fastapi.security.base import SecurityBase
 
 from ..core.base import BaseError
-from ..decorator.wrapper import _find_raises, _return_annotation, _unwrap_endpoint
+from ..decorator.wrapper import (
+    _dependency_calls,
+    _find_raises,
+    _return_annotation,
+    _unwrap_endpoint,
+)
 from .visitor import _collect, _ScanCache
 
 
@@ -164,37 +166,6 @@ def _raised(route: _RouteLike, *, max_depth: int, cache: _ScanCache) -> frozense
     return frozenset(raised)
 
 
-def _dependency_calls(dependant: Dependant) -> Iterator[Callable[..., Any]]:
-    """Yield every dependency callable in the tree, skipping security schemes.
-
-    Args:
-        dependant: The route's dependency tree root.
-
-    Yields:
-        Callable[..., Any]: Each sub-dependency's callable.
-    """
-    for sub in dependant.dependencies:
-        if sub.call is not None and not _is_security_scheme(sub.call):
-            yield sub.call
-        yield from _dependency_calls(sub)
-
-
-def _is_security_scheme(call: Callable[..., Any]) -> bool:
-    """Report whether a dependency callable is a security scheme.
-
-    Args:
-        call: The dependency callable.
-
-    Returns:
-        bool: ``True`` for ``SecurityBase`` instances (they raise stock
-            ``HTTPException``, never ``BaseError``).
-    """
-    unwrapped = call
-    while isinstance(unwrapped, functools.partial):
-        unwrapped = unwrapped.func
-    return isinstance(inspect.unwrap(unwrapped), SecurityBase)
-
-
 def _sorted(errors: frozenset[type[BaseError[Any]]]) -> tuple[type[BaseError[Any]], ...]:
     """Order error classes by name for deterministic output.
 

src/fastapi_typed_errors/decorator/wrapper.py

@@ -2,13 +2,16 @@
 
 import functools
 import inspect
-from collections.abc import Callable
+from collections.abc import Callable, Iterator, Sequence
 from http import HTTPStatus
 from types import UnionType
 from typing import Annotated, Any, Final, TypeAliasType, Union, cast, get_args, get_origin, get_type_hints
 
 from fastapi import APIRouter, Response
 from fastapi.datastructures import DefaultPlaceholder
+from fastapi.dependencies.models import Dependant
+from fastapi.params import Depends
+from fastapi.security.base import SecurityBase
 
 from ..core.base import BaseError
 from ..core.models import error_models
@@ -17,7 +20,7 @@
 _ALREADY_WRAPPED: Final[str] = "_fastapi_typed_errors_wrapped"
 
 
-def with_errors[R: APIRouter](router: R, /) -> R:
+def with_errors[R: APIRouter](router: R, /, *, auto: bool = False) -> R:
     """Enable ``Raises`` handling on the router and return the same router.
 
     The router's ``add_api_route`` is replaced (on the instance) with a wrapper
@@ -30,28 +33,34 @@ def with_errors[R: APIRouter](router: R, /) -> R:
     patch. Idempotent: wrapping twice is a no-op.
 
     For an application, wrap its router: ``with_errors(app.router)``.
-    Future options will be keyword-only (e.g. ``with_errors(router, auto=...)``).
 
     Args:
         router: The router to enable ``Raises`` handling on.
+        auto: When ``True``, also fill ``responses`` from errors discovered by
+            statically walking each endpoint and its whole dependency tree — no
+            ``Raises[...]`` needed; discovered errors are merged with any that
+            are declared. Set it on the first ``with_errors`` call; because
+            wrapping is idempotent, a later call does not change it.
 
     Returns:
         R: The same router instance, for chaining and assignment.
     """
     if not getattr(router.add_api_route, _ALREADY_WRAPPED, False):
-        router.add_api_route = _wrap_add_api_route(router.add_api_route)  # ty: ignore[invalid-assignment]
+        router.add_api_route = _wrap_add_api_route(router.add_api_route, router, auto=auto)  # ty: ignore[invalid-assignment]
     return router
 
 
-def _wrap_add_api_route[**P, R](add_api_route: Callable[P, R], /) -> Callable[P, R]:
+def _wrap_add_api_route[**P, R](add_api_route: Callable[P, R], router: APIRouter, /, *, auto: bool) -> Callable[P, R]:
     """Build the ``add_api_route`` replacement enriching ``responses`` from ``Raises``.
 
     The wrapper only manipulates call arguments and delegates: without markers
-    the call passes through byte-for-byte, so FastAPI's ``DefaultPlaceholder``
-    sentinels and inference behavior stay intact.
+    (and without ``auto``) the call passes through byte-for-byte, so FastAPI's
+    ``DefaultPlaceholder`` sentinels and inference behavior stay intact.
 
     Args:
         add_api_route: The original bound ``APIRouter.add_api_route``.
+        router: The wrapped router (its ``dependencies`` feed the ``auto`` walk).
+        auto: Whether to also derive errors from the endpoint and dependencies.
 
     Returns:
         Callable[P, R]: The replacement, preserving the original signature.
@@ -65,13 +74,15 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             # Let the original signature produce the natural error.
             return add_api_route(*args, **kwargs)
         annotation = _return_annotation(_unwrap_endpoint(endpoint), path)
-        markers = _find_raises(annotation)
-        if markers:
+        errors = dict.fromkeys(error for marker in _find_raises(annotation) for error in marker.errors)
+        if auto:
+            route_dependencies = cast(Sequence[Depends] | None, kwargs.get("dependencies"))
+            errors = dict.fromkeys([*errors, *_auto_raised(endpoint, path, route_dependencies, router)])
+        if errors:
             # Mutating P.kwargs violates the ParamSpec guarantee formally, but the keys
             # belong to the wrapped signature — localize the lie in one cast alias.
             raw_kwargs = cast(dict[str, Any], kwargs)
-            errors = tuple(dict.fromkeys(error for marker in markers for error in marker.errors))
-            raw_kwargs["responses"] = {**_build_responses(errors), **(raw_kwargs.get("responses") or {})}
+            raw_kwargs["responses"] = {**_build_responses(tuple(errors)), **(raw_kwargs.get("responses") or {})}
             if (model := raw_kwargs.get("response_model")) is None or isinstance(model, DefaultPlaceholder):
                 base = _annotated_base(annotation)
                 if base is type(None) or (isinstance(base, type) and issubclass(base, Response)):
@@ -219,3 +230,79 @@ def _build_responses(errors: tuple[type[BaseError[Any]], ...]) -> dict[int | str
             "description": "; ".join(descriptions) or HTTPStatus(status).phrase,
         }
     return responses
+
+
+def _auto_raised(
+    endpoint: Callable[..., Any],
+    path: object,
+    route_dependencies: Sequence[Depends] | None,
+    router: APIRouter,
+) -> frozenset[type[BaseError[Any]]]:
+    """Discover the errors an endpoint and its dependency tree can raise.
+
+    Walks the endpoint's source with the analysis layer's ``collect_raised``
+    and does the same for every dependency callable, rebuilding the ``Dependant``
+    tree at registration time (the route does not exist yet). ``collect_raised``
+    is imported lazily to break the ``decorator`` ↔ ``analysis`` import cycle;
+    if FastAPI's dependency helpers move, the walk degrades to the endpoint only.
+
+    Args:
+        endpoint: The endpoint callable being registered.
+        path: The route path (only used for FastAPI's path-param detection,
+            irrelevant to which dependencies are found).
+        route_dependencies: The route-level ``dependencies=[Depends(...)]``.
+        router: The router (its router-level ``dependencies`` are folded in).
+
+    Returns:
+        frozenset[type[BaseError[Any]]]: Every ``BaseError`` subclass found.
+    """
+    from ..analysis.visitor import collect_raised  # ruff:ignore[import-outside-top-level] — breaks the import cycle
+
+    raised = set(collect_raised(endpoint))
+    try:
+        from fastapi.dependencies.utils import (  # ruff:ignore[import-outside-top-level] — enables the fallback below
+            get_dependant,
+            get_parameterless_sub_dependant,
+        )
+    except ImportError:
+        return frozenset(raised)
+    path_str = cast("str", path)
+    dependant = get_dependant(path=path_str, call=endpoint)
+    for depends in reversed([*router.dependencies, *(route_dependencies or [])]):
+        dependant.dependencies.insert(0, get_parameterless_sub_dependant(depends=depends, path=path_str))
+    for call in _dependency_calls(dependant):
+        raised |= collect_raised(call)
+    return frozenset(raised)
+
+
+def _dependency_calls(dependant: Dependant) -> Iterator[Callable[..., Any]]:
+    """Yield every dependency callable in the tree, skipping security schemes.
+
+    Shared with the analysis checker (which imports it from here).
+
+    Args:
+        dependant: The dependency tree root.
+
+    Yields:
+        Callable[..., Any]: Each sub-dependency's callable.
+    """
+    for sub in dependant.dependencies:
+        if sub.call is not None and not _is_security_scheme(sub.call):
+            yield sub.call
+        yield from _dependency_calls(sub)
+
+
+def _is_security_scheme(call: Callable[..., Any]) -> bool:
+    """Report whether a dependency callable is a security scheme.
+
+    Args:
+        call: The dependency callable.
+
+    Returns:
+        bool: ``True`` for ``SecurityBase`` instances (they raise stock
+            ``HTTPException``, never ``BaseError``).
+    """
+    unwrapped = call
+    while isinstance(unwrapped, functools.partial):
+        unwrapped = unwrapped.func
+    return isinstance(inspect.unwrap(unwrapped), SecurityBase)