"""How a featured list is chosen, as the site reads it: `GET /api/featured/method` (Stream AW2).

Sources of truth: `services/process_doc.py` (`read_doc("FEATURED")`), `docs/FEATURED.md` (the
authority), `services/featured.py` (`VERSION`, the constants the doc mirrors),
`tests/test_featured_api.py`. Read-only: the doc is read per request and nothing is written or
cached. An absent or unversioned document is `DOC_MISSING` (404) rather than an empty page: a
document without a version line is not an authority, and the page that reads it 404s the same.
"""

from __future__ import annotations

from fastapi import APIRouter, HTTPException

from app.models.schemas import FeaturedMethodOut
from app.services import process_doc

router = APIRouter(prefix="/api/featured", tags=["featured"])


@router.get("/method", response_model=FeaturedMethodOut)
def read_method() -> dict:
    out = process_doc.featured_method()
    if out is None:
        raise HTTPException(status_code=404, detail={"error_code": "DOC_MISSING",
                                                     "summary": "docs/FEATURED.md is absent or carries no version line"})
    return out