svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/api/fastapi/openapi/mutators.py

@@ -47,6 +47,218 @@ def conventions_mutator():
     return m
 
 
+def pagination_components_mutator(
+    *,
+    default_limit: int = 50,
+    max_limit: int = 200,
+) -> callable:
+    """
+    Adds reusable pagination/filtering parameters & paginated envelope schemas.
+    - Cursor: cursor/limit
+    - Page: page/page_size
+    - Common filters: q, sort, created_[after|before], updated_[after|before]
+    - Envelope: PaginatedList<T>
+    """
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        comps = schema.setdefault("components", {})
+        params = comps.setdefault("parameters", {})
+        schemas = comps.setdefault("schemas", {})
+
+        # ---- Parameters (reusable) ----
+        params.setdefault(
+            "cursor",
+            {
+                "name": "cursor",
+                "in": "query",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": "Opaque cursor for forward pagination.",
+            },
+        )
+        params.setdefault(
+            "limit",
+            {
+                "name": "limit",
+                "in": "query",
+                "required": False,
+                "schema": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": max_limit,
+                    "default": default_limit,
+                },
+                "description": f"Max items to return (1..{max_limit}).",
+            },
+        )
+        params.setdefault(
+            "page",
+            {
+                "name": "page",
+                "in": "query",
+                "required": False,
+                "schema": {"type": "integer", "minimum": 1, "default": 1},
+                "description": "1-based page index (alternative to cursor).",
+            },
+        )
+        params.setdefault(
+            "page_size",
+            {
+                "name": "page_size",
+                "in": "query",
+                "required": False,
+                "schema": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": max_limit,
+                    "default": default_limit,
+                },
+                "description": f"Number of items per page (1..{max_limit}).",
+            },
+        )
+        params.setdefault(
+            "q",
+            {
+                "name": "q",
+                "in": "query",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": "Free-text filter query.",
+            },
+        )
+        params.setdefault(
+            "sort",
+            {
+                "name": "sort",
+                "in": "query",
+                "required": False,
+                "schema": {
+                    "type": "string",
+                    "examples": ["created_at", "-created_at", "name", "-name"],
+                },
+                "description": "Sort field, prefix '-' for descending.",
+            },
+        )
+        for fld in ("created", "updated"):
+            params.setdefault(
+                f"{fld}_after",
+                {
+                    "name": f"{fld}_after",
+                    "in": "query",
+                    "required": False,
+                    "schema": {"type": "string"},
+                    "description": f"Only items with {fld}_at strictly after this HTTP-date (RFC 9110).",
+                },
+            )
+            params.setdefault(
+                f"{fld}_before",
+                {
+                    "name": f"{fld}_before",
+                    "in": "query",
+                    "required": False,
+                    "schema": {"type": "string"},
+                    "description": f"Only items with {fld}_at strictly before this HTTP-date (RFC 9110).",
+                },
+            )
+
+        # ---- Envelope schema (generic pattern) ----
+        # This is a non-generic "template" envelope; concrete versions are produced per endpoint, if desired.
+        schemas.setdefault(
+            "PaginatedList",
+            {
+                "type": "object",
+                "properties": {
+                    "items": {"type": "array", "items": {"type": "object"}},
+                    "next_cursor": {
+                        "type": "string",
+                        "nullable": True,
+                        "description": "Opaque cursor for next page (null when no more).",
+                    },
+                    "total": {
+                        "type": "integer",
+                        "nullable": True,
+                        "description": "Total items (may be null if not computed).",
+                    },
+                },
+                "required": ["items"],
+            },
+        )
+
+        return schema
+
+    return m
+
+
+def auto_attach_pagination_params_mutator(
+    *,
+    mode: str = "cursor_or_page",
+    attach_filters: bool = True,
+    apply_when: str = "array_200",
+    flag_disable: str = "x_no_auto_pagination",
+) -> callable:
+    """
+    Attaches reusable pagination/filter parameters to GET "listy" operations.
+
+    - mode:
+        "cursor_or_page" -> attach cursor+limit and page+page_size (clients use either)
+        "cursor_only"    -> attach cursor+limit
+        "page_only"      -> attach page+page_size
+    - apply_when:
+        "array_200" -> only when response 200 schema is an array
+        "all_get"   -> for every GET op
+    - Per-op opt-out: set operation's openapi_extra[flag_disable] = True
+    """
+
+    def _should_apply(op: dict) -> bool:
+        if op.get(flag_disable) is True:
+            return False
+        if apply_when == "all_get":
+            return True
+        # array_200: inspect 200->application/json->schema
+        resps = op.get("responses") or {}
+        r200 = resps.get("200")
+        if not isinstance(r200, dict):
+            return False
+        content = r200.get("content") or {}
+        mt = content.get("application/json")
+        if not isinstance(mt, dict):
+            return False
+        sch = mt.get("schema") or {}
+        return isinstance(sch, dict) and sch.get("type") == "array"
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for _, method, op in _iter_ops(schema):
+            if method != "get":
+                continue
+            if not _should_apply(op):
+                continue
+
+            params = op.setdefault("parameters", [])
+
+            def _add_ref(name: str):
+                params.append({"$ref": f"#/components/parameters/{name}"})
+
+            if mode in ("cursor_only", "cursor_or_page"):
+                _add_ref("cursor")
+                _add_ref("limit")
+            if mode in ("page_only", "cursor_or_page"):
+                _add_ref("page")
+                _add_ref("page_size")
+            if attach_filters:
+                _add_ref("q")
+                _add_ref("sort")
+                _add_ref("created_after")
+                _add_ref("created_before")
+                _add_ref("updated_after")
+                _add_ref("updated_before")
+
+        return schema
+
+    return m
+
+
 def normalize_problem_and_examples_mutator():
     """
     1) Force components.schemas.Problem.properties.instance.format = "uri-reference".
@@ -155,6 +367,18 @@ def auth_mutator(include_api_key: bool):
 
     def _m(schema: dict) -> dict:
         schema = dict(schema)
+
+        # Detect if any operation already references APIKeyHeader
+        any_op_wants_api_key = False
+        for _, _, op in _iter_ops(schema):
+            for sec in op.get("security") or []:
+                if isinstance(sec, dict) and "APIKeyHeader" in sec:
+                    any_op_wants_api_key = True
+                    break
+            if any_op_wants_api_key:
+                break
+
+        # Add OAuth2 (always)
         comps = schema.setdefault("components", {}).setdefault("securitySchemes", {})
         comps.setdefault(
             "OAuth2PasswordBearer",
@@ -163,11 +387,21 @@ def auth_mutator(include_api_key: bool):
                 "flows": {"password": {"tokenUrl": auth_login_path, "scopes": {}}},
             },
         )
-        if include_api_key:
+
+        # Add API key scheme only if:
+        #  - include_api_key flag is True (from spec/root), OR
+        #  - at least one operation already references APIKeyHeader.
+        if include_api_key or any_op_wants_api_key:
             comps.setdefault(
-                "APIKeyHeader", {"type": "apiKey", "name": "X-API-Key", "in": "header"}
+                "APIKeyHeader",
+                {
+                    "type": "apiKey",
+                    "name": "X-API-Key",
+                    "in": "header",
+                },
             )
 
+        # Normalize operation security (drop only 'SessionCookie')
         drop = {"SessionCookie"}
         for _, _, op in _iter_ops(schema):
             op["security"] = _normalize_security_list(op.get("security"), drop)
@@ -421,7 +655,9 @@ def ensure_request_body_descriptions_mutator(default_template="Request body for
 
 
 def ensure_parameter_metadata_mutator(param_desc_template="{name} parameter."):
-    """Add missing descriptions; enforce required for path params; ensure schema exists."""
+    """Add missing descriptions; enforce required for path params; ensure schema exists.
+    NOTE: Never touch $ref parameters here.
+    """
 
     def m(schema: dict) -> dict:
         schema = dict(schema)
@@ -432,6 +668,9 @@ def ensure_parameter_metadata_mutator(param_desc_template="{name} parameter."):
             for p in params:
                 if not isinstance(p, dict):
                     continue
+                if "$ref" in p:
+                    # leave component parameters untouched
+                    continue
                 name = p.get("name", "")
                 where = p.get("in", "")
                 # description
@@ -451,8 +690,123 @@ def ensure_parameter_metadata_mutator(param_desc_template="{name} parameter."):
     return m
 
 
+def strip_ref_siblings_in_parameters_mutator():
+    """Normalize parameters: if an item has $ref, remove all other keys."""
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for _, _, op in _iter_ops(schema):
+            params = op.get("parameters")
+            if not isinstance(params, list):
+                continue
+            for p in params:
+                if isinstance(p, dict) and "$ref" in p and len(p) > 1:
+                    ref = p["$ref"]
+                    p.clear()
+                    p["$ref"] = ref
+        return schema
+
+    return m
+
+
+def dedupe_parameters_mutator():
+    """
+    Deduplicate operation.parameters by actual (name, in):
+      - Prefer **inline** params over $ref so per-op 'required: true' (e.g., Idempotency-Key) wins.
+      - Collapse duplicate $refs.
+      - If a $ref and an inline share the same (name, in), keep the inline and drop the $ref.
+    """
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        comps = schema.get("components") or {}
+        comp_params = (comps.get("parameters") or {}).copy()
+
+        def _resolve_ref(ref: str) -> tuple[str, str] | None:
+            # '#/components/parameters/<Key>' -> ('Idempotency-Key','header'), etc.
+            try:
+                key = ref.rsplit("/", 1)[-1]
+                p = comp_params.get(key) or {}
+                name = p.get("name")
+                where = p.get("in")
+                if isinstance(name, str) and isinstance(where, str):
+                    return (name, where)
+            except Exception:
+                pass
+            return None
+
+        for _, _, op in _iter_ops(schema):
+            params = op.get("parameters")
+            if not isinstance(params, list) or not params:
+                continue
+
+            # First pass: collect inline params by (name, in)
+            inline_by_key: dict[tuple[str, str], dict] = {}
+            for p in params:
+                if isinstance(p, dict) and "$ref" not in p:
+                    name = p.get("name")
+                    where = p.get("in")
+                    if isinstance(name, str) and isinstance(where, str):
+                        # Prefer the first inline; later duplicates ignored
+                        inline_by_key.setdefault((name, where), p)
+
+            seen_ref_targets: set[str] = set()
+            seen_keys: set[tuple[str, str]] = set()
+            result: list[dict] = []
+
+            for p in params:
+                if not isinstance(p, dict):
+                    continue
+
+                if "$ref" in p:
+                    ref = p.get("$ref")
+                    if not isinstance(ref, str):
+                        continue
+                    # de-dup exact same $ref
+                    if ref in seen_ref_targets:
+                        continue
+                    seen_ref_targets.add(ref)
+
+                    tup = _resolve_ref(ref)
+                    if tup is None:
+                        # keep unresolved ref (unlikely)
+                        result.append({"$ref": ref})
+                        continue
+
+                    # If an inline with same (name, in) exists, prefer inline, skip this $ref
+                    if tup in inline_by_key:
+                        continue
+
+                    # Else, keep this $ref if we didn't already keep a param for that key
+                    if tup in seen_keys:
+                        continue
+                    seen_keys.add(tup)
+                    # Ensure no siblings remain
+                    result.append({"$ref": ref})
+                    continue
+
+                # inline param
+                name = p.get("name")
+                where = p.get("in")
+                if not (isinstance(name, str) and isinstance(where, str)):
+                    result.append(p)
+                    continue
+                key = (name, where)
+                if key in seen_keys:
+                    # already kept an inline with same (name, in)
+                    continue
+                seen_keys.add(key)
+                result.append(p)
+
+            op["parameters"] = result
+
+        return schema
+
+    return m
+
+
 def normalize_no_content_204_mutator():
-    """Ensure 204 responses have description and no content."""
+    """Ensure 204 responses have 'No Content' description and no content."""
 
     def m(schema: dict) -> dict:
         schema = dict(schema)
@@ -462,8 +816,9 @@ def normalize_no_content_204_mutator():
                 continue
             r204 = resps.get("204")
             if isinstance(r204, dict):
-                r204.setdefault("description", "No Content")
-                # many validators prefer no 'content' for 204
+                # Always normalize text to the conventional phrasing
+                r204["description"] = "No Content"
+                # Many validators prefer no 'content' for 204
                 if "content" in r204:
                     r204.pop("content", None)
         return schema
@@ -471,6 +826,53 @@ def normalize_no_content_204_mutator():
     return m
 
 
+def inject_safe_examples_mutator():
+    """
+    Inject a couple of specific, schema-safe examples:
+      - If a 2xx application/json response uses #/components/schemas/SendEmailCodeOut
+        and has no example(s), set {"sent": true, "cooldown_seconds": 60}.
+      - For GET/any 2xx on /ping, add {"status": "ok"} if example(s) are missing.
+    Never overwrites existing example/examples.
+    """
+
+    def _has_examples(mt_obj: dict) -> bool:
+        return isinstance(mt_obj, dict) and ("example" in mt_obj or "examples" in mt_obj)
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for path, method, op in _iter_ops(schema):
+            resps = op.get("responses") or {}
+            for code, resp in resps.items():
+                if not isinstance(resp, dict):
+                    continue
+                try:
+                    ic = int(code)
+                except Exception:
+                    continue
+                if not (200 <= ic < 300):
+                    continue
+
+                content = resp.get("content") or {}
+                mt_obj = content.get("application/json")
+                if not isinstance(mt_obj, dict) or _has_examples(mt_obj):
+                    continue
+
+                # Special-case: SendEmailCodeOut by $ref
+                sch = mt_obj.get("schema") or {}
+                ref = sch.get("$ref") if isinstance(sch, dict) else None
+                if isinstance(ref, str) and ref.endswith("/SendEmailCodeOut"):
+                    mt_obj["example"] = {"sent": True, "cooldown_seconds": 60}
+                    continue
+
+                # Special-case: /ping success body
+                if path == "/ping":
+                    mt_obj["example"] = {"status": "ok"}
+
+        return schema
+
+    return m
+
+
 def prune_invalid_responses_keys_mutator():
     """In an operation's responses object, only status codes or 'default' are allowed."""
 
@@ -664,12 +1066,11 @@ def improve_success_response_descriptions_mutator():
 
 
 def ensure_success_examples_mutator():
-    """Ensure 2xx application/json responses have an example."""
+    """Ensure 2xx application/json responses have an example (but only when safe)."""
 
     def m(schema: dict) -> dict:
         schema = dict(schema)
         for _, _, op in _iter_ops(schema):
-            summary = op.get("summary") or ""
             resps = op.get("responses") or {}
             for code, resp in resps.items():
                 if not isinstance(resp, dict):
@@ -680,29 +1081,133 @@ def ensure_success_examples_mutator():
                     continue
                 if not (200 <= ic < 300) or ic == 204:
                     continue
-                content = resp.get("content") or {}
-                mt_obj = content.get("application/json")
-                if not isinstance(mt_obj, dict):
-                    continue
-                if "example" in mt_obj or "examples" in mt_obj:
+                mt_obj = (resp.get("content") or {}).get("application/json")
+                if not isinstance(mt_obj, dict) or "example" in mt_obj or "examples" in mt_obj:
                     continue
                 sch = mt_obj.get("schema") or {}
-                # give minimal but deterministic examples
-                if sch.get("type") == "string":
+
+                # Only set examples for primitives/arrays. Never for object/$ref.
+                t = sch.get("type")
+                if t == "string":
                     mt_obj["example"] = "example"
-                elif sch.get("type") == "boolean":
+                elif t == "boolean":
                     mt_obj["example"] = True
-                elif sch.get("type") == "integer":
+                elif t == "integer":
                     mt_obj["example"] = 0
-                elif sch.get("type") == "array":
+                elif t == "array":
                     mt_obj["example"] = []
-                elif sch.get("type") == "object":
-                    # just put {} if no requireds
-                    if not sch.get("required"):
-                        mt_obj["example"] = {}
-                # fallback
-                if "example" not in mt_obj:
-                    mt_obj["example"] = {"status": "ok", "summary": summary}
+                # NOTE: no else/fallback for object/$ref
+        return schema
+
+    return m
+
+
+# --- NEW: attach minimal x-codeSamples for common operations ---
+def attach_code_samples_mutator():
+    """Attach minimal curl/httpie x-codeSamples for each operation if missing.
+
+    We avoid templating parameters; samples illustrate method and path only.
+    """
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        servers = schema.get("servers") or [{"url": ""}]
+        base = servers[0].get("url") or ""
+
+        for path, method, op in _iter_ops(schema):
+            # Don't override existing samples
+            if isinstance(op.get("x-codeSamples"), list) and op["x-codeSamples"]:
+                continue
+            url = f"{base}{path}"
+            method_up = method.upper()
+            samples = [
+                {
+                    "lang": "bash",
+                    "label": "curl",
+                    "source": f"curl -X {method_up} '{url}'",
+                },
+                {
+                    "lang": "bash",
+                    "label": "httpie",
+                    "source": f"http {method_up} '{url}'",
+                },
+            ]
+            op["x-codeSamples"] = samples
+        return schema
+
+    return m
+
+
+# --- NEW: ensure Problem+JSON examples exist for standard error responses ---
+def ensure_problem_examples_mutator():
+    """Add example objects for 4xx/5xx responses using Problem schema if absent."""
+
+    try:
+        # Internal helper with sensible defaults
+        from .conventions import _problem_example  # type: ignore
+    except Exception:  # pragma: no cover - fallback
+
+        def _problem_example(**kw):  # type: ignore
+            base = {
+                "type": "about:blank",
+                "title": "Error",
+                "status": 500,
+                "detail": "An error occurred.",
+                "instance": "/request/trace",
+                "code": "INTERNAL_ERROR",
+            }
+            base.update(kw)
+            return base
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for _, _, op in _iter_ops(schema):
+            resps = op.get("responses") or {}
+            for code, resp in resps.items():
+                if not isinstance(resp, dict):
+                    continue
+                try:
+                    ic = int(code)
+                except Exception:
+                    continue
+                if ic < 400:
+                    continue
+                # Do not add content if response is a $ref; avoid creating siblings
+                if "$ref" in resp:
+                    continue
+                content = resp.setdefault("content", {})
+                # prefer problem+json but also set application/json if present
+                for mt in ("application/problem+json", "application/json"):
+                    mt_obj = content.get(mt)
+                    if mt_obj is None:
+                        # Create a basic media type referencing Problem schema when appropriate
+                        if mt == "application/problem+json":
+                            mt_obj = {"schema": {"$ref": "#/components/schemas/Problem"}}
+                            content[mt] = mt_obj
+                        else:
+                            continue
+                    if not isinstance(mt_obj, dict):
+                        continue
+                    if "example" in mt_obj or "examples" in mt_obj:
+                        continue
+                    mt_obj["example"] = _problem_example(status=ic)
+        return schema
+
+    return m
+
+
+# --- NEW: attach default tags from first path segment when missing ---
+def attach_default_tags_mutator():
+    """If an operation has no tags, tag it by its first path segment."""
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for path, _method, op in _iter_ops(schema):
+            tags = op.get("tags")
+            if tags:
+                continue
+            seg = path.strip("/").split("/", 1)[0] or "root"
+            op["tags"] = [seg]
         return schema
 
     return m
@@ -722,32 +1227,33 @@ def dedupe_tags_mutator():
 
 def scrub_invalid_object_examples_mutator():
     """
-    If a media example is an object but schema has required fields and the example
-    is {} (or not a dict), remove the example so the validator won't fail.
+    Remove media examples that are objects but don't satisfy required keys
+    (or when schema is a $ref/object). Keeps primitives/arrays.
     """
 
-    def patch_content(node: dict):
+    def _invalid_object_example(sch: dict, ex: dict) -> bool:
+        if not isinstance(sch, dict) or not isinstance(ex, dict):
+            return False
+        if "$ref" in sch:
+            return True  # can't validate here → drop
+        if sch.get("type") == "object" or "properties" in sch or "required" in sch:
+            req = set(sch.get("required") or [])
+            return bool(req) and not req.issubset(ex.keys())
+        return False
+
+    def _patch(node: dict):
         content = node.get("content")
         if not isinstance(content, dict):
             return
         for mt_obj in content.values():
             if not isinstance(mt_obj, dict):
                 continue
-            if "example" not in mt_obj:
-                continue
             sch = mt_obj.get("schema")
             ex = mt_obj.get("example")
-            if not isinstance(sch, dict):
-                continue
-            # Follow $ref if you want; simplest is: only act on obvious object cases.
-            if (
-                sch.get("type") == "object"
-                or "properties" in sch
-                or "required" in sch
-                or "$ref" in sch
+            if "example" in mt_obj and _invalid_object_example(
+                sch if isinstance(sch, dict) else {}, ex
             ):
-                if not isinstance(ex, dict) or ex == {}:
-                    mt_obj.pop("example", None)
+                mt_obj.pop("example", None)
 
     def m(schema: dict) -> dict:
         schema = dict(schema)
@@ -756,10 +1262,10 @@ def scrub_invalid_object_examples_mutator():
             if isinstance(resps, dict):
                 for resp in resps.values():
                     if isinstance(resp, dict):
-                        patch_content(resp)
+                        _patch(resp)
             rb = op.get("requestBody")
             if isinstance(rb, dict):
-                patch_content(rb)
+                _patch(rb)
         return schema
 
     return m
@@ -792,25 +1298,224 @@ def drop_unused_components_mutator_auto(keep_schemas: set[str] | None = None):
 
         # schemas
         sch = comps.get("schemas") or {}
-        to_drop = [
-            name
-            for name in sch.keys()
-            if name not in keep_schemas and name not in (used.get("schemas") or set())
-        ]
-        for name in to_drop:
-            sch.pop(name, None)
-
-        # responses (optional; usually all are used)
+        for name in list(sch.keys()):
+            if name not in keep_schemas and name not in (used.get("schemas") or set()):
+                sch.pop(name, None)
+
+        # responses
         resps = comps.get("responses") or {}
-        to_drop_r = [name for name in resps.keys() if name not in (used.get("responses") or set())]
-        for name in to_drop_r:
-            resps.pop(name, None)
+        for name in list(resps.keys()):
+            if name not in (used.get("responses") or set()):
+                resps.pop(name, None)
+
+        # NEW: headers
+        hdrs = comps.get("headers") or {}
+        for name in list(hdrs.keys()):
+            if name not in (used.get("headers") or set()):
+                hdrs.pop(name, None)
+
+        # (Optional: parameters/requestBodies/etc. same pattern)
 
         return schema
 
     return m
 
 
+def hardening_components_mutator():
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        comps = schema.setdefault("components", {})
+        params = comps.setdefault("parameters", {})
+        headers = comps.setdefault("headers", {})
+
+        params.setdefault(
+            "IdempotencyKey",
+            {
+                "name": "Idempotency-Key",
+                "in": "header",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": "Provide to make the request idempotent for 24h.",
+            },
+        )
+        params.setdefault(
+            "IfNoneMatch",
+            {
+                "name": "If-None-Match",
+                "in": "header",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": "Conditional GET (ETag).",
+            },
+        )
+        params.setdefault(
+            "IfModifiedSince",
+            {
+                "name": "If-Modified-Since",
+                "in": "header",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": "Conditional GET. HTTP-date per RFC 9110 (e.g. 'Wed, 01 Jan 2025 00:00:00 GMT').",
+            },
+        )
+        params.setdefault(
+            "IfMatch",
+            {
+                "name": "If-Match",
+                "in": "header",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": "Optimistic concurrency for updates.",
+            },
+        )
+
+        headers.setdefault(
+            "ETag", {"schema": {"type": "string"}, "description": "Opaque entity tag."}
+        )
+        headers.setdefault(
+            "LastModified",
+            {
+                "schema": {"type": "string"},  # HTTP-date string
+                "description": "Last modification time, HTTP-date per RFC 9110.",
+            },
+        )
+        headers.setdefault(
+            "XRateLimitLimit", {"schema": {"type": "integer"}, "description": "Tokens in window."}
+        )
+        headers.setdefault(
+            "XRateLimitRemaining",
+            {"schema": {"type": "integer"}, "description": "Remaining tokens."},
+        )
+        headers.setdefault(
+            "XRateLimitReset", {"schema": {"type": "integer"}, "description": "Unix reset time."}
+        )
+        headers.setdefault(
+            "XRequestId", {"schema": {"type": "string"}, "description": "Correlation id."}
+        )
+        headers.setdefault(
+            "Deprecation",
+            {
+                "schema": {"type": "string"},
+                "description": "Set to 'true' for deprecated endpoints.",
+            },
+        )
+        headers.setdefault(
+            "Sunset",
+            {"schema": {"type": "string"}, "description": "HTTP-date for deprecation sunset."},
+        )
+        return schema
+
+    return m
+
+
+def attach_header_params_mutator():
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        comps = schema.setdefault("components", {})
+        comp_params = comps.setdefault("parameters", {})
+
+        def _component_param_name(ref: str) -> tuple[str, str] | None:
+            try:
+                key = ref.rsplit("/", 1)[-1]
+                p = comp_params.get(key) or {}
+                name = p.get("name")
+                where = p.get("in")
+                if isinstance(name, str) and isinstance(where, str):
+                    return (name, where)
+            except Exception:
+                pass
+            return None
+
+        for _, method, op in _iter_ops(schema):
+            params = op.setdefault("parameters", [])
+
+            # What inline params (non-$ref) are already present?
+            inline_names = {
+                (p.get("name"), p.get("in"))
+                for p in params
+                if isinstance(p, dict) and "$ref" not in p and "name" in p and "in" in p
+            }
+
+            def add_ref_if_absent(name: str):
+                ref = {"$ref": f"#/components/parameters/{name}"}
+                tup = _component_param_name(ref["$ref"])
+                # If an inline with the same (name, in) exists (e.g., from a dependency),
+                # don't add the ref at all.
+                if tup and tup in inline_names:
+                    return
+                params.append(ref)
+
+            # ---- Write methods: Idempotency-Key fallback (optional via $ref) ----
+            # If the dependency added an inline required param, nothing to do;
+            # otherwise, add the optional component ref so callers can still send it.
+            if method in ("post", "patch", "delete"):
+                if ("Idempotency-Key", "header") not in inline_names:
+                    add_ref_if_absent("IdempotencyKey")
+                # Optional optimistic concurrency for updates
+                if method in ("patch", "put"):
+                    add_ref_if_absent("IfMatch")
+
+            # ---- Conditional GET headers (optional via $ref) ----
+            if method == "get":
+                add_ref_if_absent("IfNoneMatch")
+                add_ref_if_absent("IfModifiedSince")
+
+            # ---- Standard success/429 headers (unchanged) ----
+            resps = op.get("responses") or {}
+            for code, resp in resps.items():
+                try:
+                    ic = int(code)
+                except Exception:
+                    continue
+                if 200 <= ic < 300:
+                    hdrs = resp.setdefault("headers", {})
+                    hdrs.setdefault("ETag", {"$ref": "#/components/headers/ETag"})
+                    hdrs.setdefault("Last-Modified", {"$ref": "#/components/headers/LastModified"})
+                    hdrs.setdefault("X-Request-Id", {"$ref": "#/components/headers/XRequestId"})
+                    hdrs.setdefault(
+                        "X-RateLimit-Limit", {"$ref": "#/components/headers/XRateLimitLimit"}
+                    )
+                    hdrs.setdefault(
+                        "X-RateLimit-Remaining",
+                        {"$ref": "#/components/headers/XRateLimitRemaining"},
+                    )
+                    hdrs.setdefault(
+                        "X-RateLimit-Reset", {"$ref": "#/components/headers/XRateLimitReset"}
+                    )
+                if code == "429":
+                    resp.setdefault("headers", {})["Retry-After"] = {
+                        "schema": {"type": "integer"},
+                        "description": "Seconds until next allowed request.",
+                    }
+
+        return schema
+
+    return m
+
+
+def attach_conditional_get_304_mutator():
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for _, method, op in _iter_ops(schema):
+            if method != "get":
+                continue
+            resps = op.setdefault("responses", {})
+            resps.setdefault(
+                "304",
+                {
+                    "description": "Not Modified",
+                    "headers": {
+                        "ETag": {"$ref": "#/components/headers/ETag"},
+                        "Last-Modified": {"$ref": "#/components/headers/LastModified"},
+                        "X-Request-Id": {"$ref": "#/components/headers/XRequestId"},
+                    },
+                },
+            )
+        return schema
+
+    return m
+
+
 def setup_mutators(
     service: ServiceInfo,
     spec: APIVersionSpec | None,
@@ -819,22 +1524,31 @@ def setup_mutators(
 ) -> list:
     mutators = [
         conventions_mutator(),
+        hardening_components_mutator(),
+        attach_header_params_mutator(),
         normalize_problem_and_examples_mutator(),
         attach_standard_responses_mutator(),
+        attach_conditional_get_304_mutator(),
         auth_mutator(include_api_key),
         strip_ref_siblings_in_responses_mutator(),
         prune_invalid_responses_keys_mutator(),
+        strip_ref_siblings_in_parameters_mutator(),
+        dedupe_parameters_mutator(),
         ensure_operation_descriptions_mutator(),
         ensure_request_body_descriptions_mutator(),
         ensure_parameter_metadata_mutator(),
         ensure_media_type_schemas_mutator(),
         ensure_examples_for_json_mutator(),
         ensure_success_examples_mutator(),
+        attach_default_tags_mutator(),
+        attach_code_samples_mutator(),
+        ensure_problem_examples_mutator(),
         ensure_media_examples_mutator(),
         scrub_invalid_object_examples_mutator(),
         normalize_no_content_204_mutator(),
         ensure_response_descriptions_mutator(),
         improve_success_response_descriptions_mutator(),
+        inject_safe_examples_mutator(),
         dedupe_tags_mutator(),
         ensure_global_tags_mutator(),
         drop_unused_components_mutator_auto(),
@@ -842,5 +1556,4 @@ def setup_mutators(
     ]
     if server_url:
         mutators.append(servers_mutator(server_url))
-
     return mutators