sourcecode 1.38.0__tar.gz → 1.39.0__tar.gz

{sourcecode-1.38.0 → sourcecode-1.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.38.0
+Version: 1.39.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.38.0-blue)
+![Version](https://img.shields.io/badge/version-1.39.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 ---
@@ -114,7 +114,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.38.0
+# sourcecode 1.39.0
 ```
 
 ---
@@ -149,6 +149,9 @@ sourcecode impact-chain OrderPlacedEvent /path/to/repo --type events
 # REST endpoint surface
 sourcecode endpoints /path/to/repo
 
+# Request-body validation per endpoint: constraints + custom validators (free)
+sourcecode validation /path/to/repo
+
 # Onboard to an unfamiliar codebase
 sourcecode onboard /path/to/repo
 

{sourcecode-1.38.0 → sourcecode-1.39.0}/README.md

@@ -2,7 +2,7 @@
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.38.0-blue)
+![Version](https://img.shields.io/badge/version-1.39.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 ---
@@ -76,7 +76,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.38.0
+# sourcecode 1.39.0
 ```
 
 ---
@@ -111,6 +111,9 @@ sourcecode impact-chain OrderPlacedEvent /path/to/repo --type events
 # REST endpoint surface
 sourcecode endpoints /path/to/repo
 
+# Request-body validation per endpoint: constraints + custom validators (free)
+sourcecode validation /path/to/repo
+
 # Onboard to an unfamiliar codebase
 sourcecode onboard /path/to/repo
 

{sourcecode-1.38.0 → sourcecode-1.39.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.38.0"
+version = "1.39.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.38.0 → sourcecode-1.39.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.38.0"
+__version__ = "1.39.0"

{sourcecode-1.38.0 → sourcecode-1.39.0}/src/sourcecode/cli.py

@@ -230,6 +230,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "cold-start",
         # Spring semantic audit
         "spring-audit",
+        # Request-body validation surface
+        "validation",
         # Spring impact chain
         "impact-chain",
         # PR blast-radius report
@@ -3915,6 +3917,105 @@ def endpoints_cmd(
     _nudge()
 
 
+@app.command("validation")
+def validation_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path to scan for request-body validation (default: current directory)",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json",
+        "--format",
+        "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False,
+        "--copy",
+        "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+    path_prefix: Optional[str] = typer.Option(
+        None, "--path-prefix", "-p",
+        help="Filter endpoints whose URL path starts with this prefix.",
+    ),
+    gaps_only: bool = typer.Option(
+        False, "--gaps-only",
+        help="Report only endpoints/fields with no declared validation (the gaps section).",
+    ),
+) -> None:
+    """Map request-body validation per endpoint (constraints + custom validators).
+
+    \b
+    Aggregates two sources of bean-validation truth so an agent knows exactly
+    what a request body must satisfy before touching it:
+      * declarative constraints on the DTOs (@Pattern/@Size/@NotNull, min/max,
+        enum), recovered from the OpenAPI spec even when the DTOs are generated
+        under target/generated-sources (not scanned);
+      * hand-written custom validators (@Constraint + ConstraintValidator, e.g.
+        PetAgeValidator), linked to fields via x-field-extra-annotation.
+
+    \b
+    Output (JSON): per-endpoint validatedFields with their rules + custom
+    validators, the discovered custom-validator catalog, and the set of body
+    endpoints with no declared validation (gaps).
+
+    \b
+    Examples:
+      sourcecode validation .
+      sourcecode validation . --gaps-only
+      sourcecode validation . --path-prefix /owners
+      sourcecode validation . --format yaml
+    """
+    _enforce_format("validation", format)
+
+    target = path.resolve()
+    if not target.exists() or not target.is_dir():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+            hint="Pass an existing repository directory.",
+            expected="A directory path.",
+        )
+        raise typer.Exit(code=1)
+
+    from sourcecode.validation_surface import build_validation_surface
+    data = build_validation_surface(target)
+
+    if path_prefix:
+        data["endpoints"] = [
+            e for e in data.get("endpoints", [])
+            if str(e.get("path", "")).startswith(path_prefix)
+        ]
+        data["gaps"] = [
+            g for g in data.get("gaps", [])
+            if str(g.get("path", "")).startswith(path_prefix)
+        ]
+    if gaps_only:
+        data = {
+            "gaps": data.get("gaps", []),
+            "summary": data.get("summary", {}),
+        }
+
+    output = _serialize_dict(data, format)
+    _summary = data.get("summary", {})
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=f"Validation surface written to {output_path} "
+        f"({_summary.get('endpoints_with_body', 0)} body endpoints, "
+        f"{_summary.get('gaps', 0)} gaps)",
+    )
+
+    from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+    _nudge()
+
+
 # ── Spring Semantic Audit ─────────────────────────────────────────────────────
 
 

{sourcecode-1.38.0 → sourcecode-1.39.0}/src/sourcecode/format_contract.py

@@ -27,6 +27,7 @@ FORMAT_REGISTRY: "dict[str, tuple[str, ...]]" = {
     "repo-ir": ("json", "yaml"),
     "impact": ("json", "yaml"),
     "endpoints": ("json", "yaml"),
+    "validation": ("json", "yaml"),
     "impact-chain": ("json", "yaml"),
     "pr-impact": ("text", "json"),
     "migrate-check": ("json", "text"),

{sourcecode-1.38.0 → sourcecode-1.39.0}/src/sourcecode/mcp/registry.py

@@ -864,6 +864,31 @@ Returns: endpoints list with method, path, controller, handler fields;
          "unknown" (no security signals detected).
 Supports Spring MVC (@GetMapping etc.) and JAX-RS (@GET/@POST etc.).
 repo_path: absolute path to the Java repository (default: current working directory).
+"""
+
+    _GET_VALIDATION_DOC = """\
+Request-body validation surface per endpoint. JAVA/SPRING ONLY.
+
+Do NOT call this on non-Java repositories — it will return empty results.
+
+Combines two sources of bean-validation truth so you know what a request body
+must satisfy before generating a payload, a test, or reasoning about a 400:
+  * declarative constraints on the DTOs (@Pattern/@Size/@NotNull, minimum/maximum,
+    enum) — recovered from the OpenAPI spec even when DTOs are generated under
+    target/generated-sources (not scanned);
+  * hand-written custom validators (@Constraint + ConstraintValidator, e.g.
+    PetAgeValidator), linked to fields via x-field-extra-annotation.
+
+Maps to: sourcecode validation <repo_path>
+Returns: endpoints[] (method, path, controller, handler, schema, validatedFields[
+  {name, rules[{kind,value}], customValidators[{annotation,validators,message,resolved}]}]),
+  custom_validators[] (catalog: annotation, validators, message, validatedTypes, targets),
+  gaps[] (POST/PUT/PATCH endpoints with no declared validation),
+  summary, openapi_spec.
+An unresolved custom annotation (referenced in the spec, no validator in source)
+is reported with resolved=false.
+repo_path: absolute path to the Java repository (default: current working directory).
+gaps_only: when true, return only the gaps section (endpoints lacking validation).
 """
 
     _CACHE_STATUS_DOC = """\
@@ -1083,6 +1108,27 @@ repo_path: absolute path to the repository (default: current working directory).
             docstring_override=_GET_ENDPOINTS_DOC,
         ),
 
+        # --- get_validation: clean alias replacing raw canonical (6 CLI params) ---
+        _alias_spec(
+            "get_validation",
+            "Request-body validation surface per endpoint (constraints + custom validators). JAVA/SPRING ONLY.",
+            ("validation",),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+                ToolParamSpec("gaps_only", "option", bool, required=False, default=False,
+                              option_names=("--gaps-only",), is_flag=True,
+                              help="Return only endpoints/fields lacking validation."),
+            ),
+            lambda inputs: (
+                ["validation", str(inputs.get("repo_path", "."))]
+                + (["--gaps-only"] if bool(inputs.get("gaps_only")) else [])
+            ),
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_GET_VALIDATION_DOC,
+        ),
+
         # --- cache management: curated aliases stripping CLI noise params ---
         _alias_spec(
             "cache_status",
@@ -1214,6 +1260,7 @@ _MCP_HIDDEN_CANONICAL_TOOLS: frozenset[str] = frozenset({
     "modernize",          # duplicate of modernize_context
     # Raw CLI tools with output-format/noise params — clean alias with only repo_path exists
     "endpoints",          # 7 CLI params (output_path/format/copy/etc.); use get_endpoints
+    "validation",         # 6 CLI params (output_path/format/copy/path_prefix/gaps_only); use get_validation
     "cache_status",       # path + json_output flag; curated alias strips json_output, renames path→repo_path
     "cache_warm",         # path + compact/agent output flags; curated alias keeps only repo_path
     "cache_clear",        # path + yes/all_ destructive flags; curated alias keeps repo_path + include_ris only

{sourcecode-1.38.0 → sourcecode-1.39.0}/src/sourcecode/openapi_surface.py

@@ -68,6 +68,9 @@ class FieldConstraint:
     fmt: Optional[str] = None
     enum: Optional[list[Any]] = None
     ref: Optional[str] = None  # schema name when the field is an object/array ref
+    # Custom bean-validation annotations injected via openapi-generator's
+    # ``x-field-extra-annotation`` vendor extension (simple class names).
+    extra_annotations: "list[str]" = field(default_factory=list)
 
     def to_dict(self) -> "dict[str, Any]":
         out: "dict[str, Any]" = {"name": self.name, "required": self.required}
@@ -84,6 +87,8 @@ class FieldConstraint:
         ):
             if val is not None:
                 out[key] = val
+        if self.extra_annotations:
+            out["extraAnnotations"] = self.extra_annotations
         return out
 
 
@@ -255,6 +260,32 @@ def _ref_name(ref: Any) -> Optional[str]:
     return None
 
 
+def _extra_annotations(prop: "dict[str, Any]") -> "list[str]":
+    """Extract simple class names from ``x-field-extra-annotation``.
+
+    openapi-generator injects custom bean-validation annotations on generated DTO
+    fields via this vendor extension, e.g.
+    ``x-field-extra-annotation: "@com.x.PetAgeValidation"`` (string) or a list of
+    such entries. We keep the trailing simple name (``PetAgeValidation``).
+    """
+    import re as _re
+
+    raw = prop.get("x-field-extra-annotation")
+    if raw is None:
+        return []
+    items = raw if isinstance(raw, list) else [raw]
+    names: "list[str]" = []
+    for item in items:
+        if not isinstance(item, str):
+            continue
+        # Each entry may carry several annotations; grab every @Name token.
+        for m in _re.finditer(r"@\s*([\w.]+)", item):
+            simple = m.group(1).rsplit(".", 1)[-1]
+            if simple and simple not in names:
+                names.append(simple)
+    return names
+
+
 def _field_from_property(name: str, prop: Any, required: bool) -> FieldConstraint:
     fc = FieldConstraint(name=name, required=required)
     if not isinstance(prop, dict):
@@ -276,6 +307,7 @@ def _field_from_property(name: str, prop: Any, required: bool) -> FieldConstrain
     enum = prop.get("enum")
     if isinstance(enum, list):
         fc.enum = list(enum)
+    fc.extra_annotations = _extra_annotations(prop)
     if fc.type is None and prop.get("type") == "array":
         items = prop.get("items")
         if isinstance(items, dict):

sourcecode-1.39.0/src/sourcecode/validation_surface.py

@@ -0,0 +1,305 @@
+"""Validation surface extraction (Phase 20).
+
+Combines the two sources of bean-validation truth in a Spring repo into one
+per-endpoint view an agent can reason about before touching a request body:
+
+  1. **Declarative constraints** carried by the OpenAPI spec DTOs (``pattern``,
+     ``minLength``/``maxLength``, ``required``, ``minimum``/``maximum``, ``enum``)
+     — recovered by :mod:`sourcecode.openapi_surface` (Phase 18). These map to
+     ``@Pattern``/``@Size``/``@NotNull`` on the generated DTOs.
+  2. **Custom constraint validators** hand-written in ``src`` — a ``@Constraint``
+     meta-annotation plus its ``ConstraintValidator`` implementation (e.g.
+     ``PetAgeValidator``) — linked to DTO fields through openapi-generator's
+     ``x-field-extra-annotation`` vendor extension.
+
+The output is a per-endpoint validation surface (which body fields are validated
+and how), the custom-validator catalog discovered in source, and the set of
+validation gaps (body endpoints with no declared constraint at all).
+
+Design notes mirror :mod:`sourcecode.openapi_surface`: pure extraction (never a
+conformance check), defensive (malformed input yields a partial surface, never an
+exception), and deterministic ordering for stable JSON.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from sourcecode.path_filters import is_test_path
+
+# Built-in constraint keys (as emitted by FieldConstraint.to_dict) that count as
+# "this field is validated".
+_BUILTIN_CONSTRAINT_KEYS = (
+    "pattern",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "enum",
+)
+
+# How many java files to scan for custom validators, to stay fast on big repos.
+_SCAN_CAP = 5000
+
+_CONSTRAINT_RE = re.compile(
+    r"@Constraint\s*\(\s*validatedBy\s*=\s*\{?([^)}]*)\}?\s*\)", re.DOTALL
+)
+_INTERFACE_RE = re.compile(r"@interface\s+(\w+)")
+_MESSAGE_RE = re.compile(
+    r"String\s+message\s*\(\s*\)\s*default\s*\"([^\"]*)\"", re.DOTALL
+)
+_TARGET_RE = re.compile(r"@Target\s*\(\s*\{?([^)}]*)\}?\s*\)", re.DOTALL)
+_VALIDATOR_IMPL_RE = re.compile(
+    r"class\s+(\w+)\s+implements\s+ConstraintValidator\s*<\s*(\w+)\s*,\s*([\w.<>\[\] ]+?)\s*>",
+    re.DOTALL,
+)
+
+
+@dataclass
+class CustomConstraint:
+    """A hand-written bean-validation constraint discovered in source."""
+
+    name: str  # the @interface annotation, e.g. "PetAgeValidation"
+    validators: "list[str]" = field(default_factory=list)  # ConstraintValidator impls
+    message: Optional[str] = None  # default message template
+    validated_types: "list[str]" = field(default_factory=list)  # T in <A, T>
+    targets: "list[str]" = field(default_factory=list)  # @Target element types
+    source_file: Optional[str] = None
+
+    def to_dict(self) -> "dict[str, Any]":
+        out: "dict[str, Any]" = {"annotation": self.name}
+        if self.validators:
+            out["validators"] = self.validators
+        if self.message is not None:
+            out["message"] = self.message
+        if self.validated_types:
+            out["validatedTypes"] = self.validated_types
+        if self.targets:
+            out["targets"] = self.targets
+        if self.source_file:
+            out["sourceFile"] = self.source_file
+        return out
+
+
+def _simple(name: str) -> str:
+    return name.rsplit(".", 1)[-1].strip()
+
+
+def _split_class_list(raw: str) -> "list[str]":
+    """Parse ``A.class, B.class`` (or a single entry) into simple class names."""
+    out: "list[str]" = []
+    for tok in raw.split(","):
+        tok = tok.strip()
+        if not tok:
+            continue
+        tok = re.sub(r"\.class\b", "", tok)
+        simple = _simple(tok)
+        if simple and simple not in out:
+            out.append(simple)
+    return out
+
+
+def discover_custom_validators(root: Path) -> "dict[str, CustomConstraint]":
+    """Scan non-test Java source for custom ``@Constraint`` validators.
+
+    Returns a map keyed by the annotation's simple name. Never raises; an
+    unreadable or malformed file is skipped.
+    """
+    root = Path(root)
+    catalog: "dict[str, CustomConstraint]" = {}
+    # annotation name -> validated types, harvested from ConstraintValidator impls.
+    impl_types: "dict[str, list[str]]" = {}
+    impl_validators: "dict[str, list[str]]" = {}
+
+    scanned = 0
+    for p in sorted(root.rglob("*.java")):
+        if scanned >= _SCAN_CAP:
+            break
+        norm = str(p).replace("\\", "/")
+        if is_test_path(norm) or "/target/" in norm or "/build/" in norm:
+            continue
+        try:
+            text = p.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        scanned += 1
+
+        if "@Constraint" not in text and "ConstraintValidator" not in text:
+            continue
+        rel = norm[len(str(root).replace("\\", "/")) :].lstrip("/") or norm
+
+        # @interface declarations carrying @Constraint(validatedBy = ...).
+        for m in _CONSTRAINT_RE.finditer(text):
+            tail = text[m.end() :]
+            iface = _INTERFACE_RE.search(tail)
+            if not iface:
+                continue
+            ann_name = iface.group(1)
+            cc = catalog.setdefault(ann_name, CustomConstraint(name=ann_name))
+            cc.source_file = cc.source_file or rel
+            for v in _split_class_list(m.group(1)):
+                if v not in cc.validators:
+                    cc.validators.append(v)
+            # Default message + @Target sit within this @interface body.
+            body = tail[iface.end() :]
+            msg = _MESSAGE_RE.search(body)
+            if msg and cc.message is None:
+                cc.message = msg.group(1)
+            tgt = _TARGET_RE.search(text[: m.start()][-400:] + tail[: iface.end()])
+            if tgt:
+                for t in tgt.group(1).split(","):
+                    t = _simple(t)
+                    if t and t not in cc.targets:
+                        cc.targets.append(t)
+
+        # ConstraintValidator<Annotation, Type> implementations.
+        for m in _VALIDATOR_IMPL_RE.finditer(text):
+            validator_cls, ann_name, vtype = m.group(1), m.group(2), _simple(m.group(3))
+            impl_types.setdefault(ann_name, [])
+            if vtype and vtype not in impl_types[ann_name]:
+                impl_types[ann_name].append(vtype)
+            impl_validators.setdefault(ann_name, [])
+            if validator_cls not in impl_validators[ann_name]:
+                impl_validators[ann_name].append(validator_cls)
+
+    # Fold validator-impl findings back into the catalog (handles validators
+    # declared in a different file than the annotation).
+    for ann_name, types in impl_types.items():
+        cc = catalog.setdefault(ann_name, CustomConstraint(name=ann_name))
+        for t in types:
+            if t not in cc.validated_types:
+                cc.validated_types.append(t)
+    for ann_name, vals in impl_validators.items():
+        cc = catalog.setdefault(ann_name, CustomConstraint(name=ann_name))
+        for v in vals:
+            if v not in cc.validators:
+                cc.validators.append(v)
+    return catalog
+
+
+def _field_rules(fieldc: "dict[str, Any]") -> "list[dict[str, Any]]":
+    """Render a constraint dict's built-in rules as a list of {kind, value}."""
+    rules: "list[dict[str, Any]]" = []
+    if fieldc.get("required"):
+        rules.append({"kind": "required"})
+    for key in _BUILTIN_CONSTRAINT_KEYS:
+        if key in fieldc:
+            rules.append({"kind": key, "value": fieldc[key]})
+    return rules
+
+
+def _is_body_endpoint(ep: "dict[str, Any]") -> bool:
+    method = str(ep.get("method", "")).upper()
+    return method in ("POST", "PUT", "PATCH")
+
+
+def build_validation_surface(
+    root: Path,
+    endpoints_data: "Optional[dict[str, Any]]" = None,
+) -> "dict[str, Any]":
+    """Build the per-endpoint validation surface for a repo.
+
+    ``endpoints_data`` is the result of :func:`extract_java_endpoints`; when not
+    supplied it is computed (so the command can run standalone). Returns a JSON-
+    ready dict: ``endpoints`` (validated fields per route), ``custom_validators``
+    (catalog), ``gaps`` (body routes with no declared constraint), and ``summary``.
+    """
+    root = Path(root)
+    if endpoints_data is None:
+        from sourcecode.repository_ir import extract_java_endpoints
+
+        endpoints_data = extract_java_endpoints(root)
+
+    catalog = discover_custom_validators(root)
+
+    out_endpoints: "list[dict[str, Any]]" = []
+    gaps: "list[dict[str, Any]]" = []
+    custom_used: "set[str]" = set()
+    total_validated_fields = 0
+
+    for ep in endpoints_data.get("endpoints", []):
+        body = ep.get("request_body")
+        if not isinstance(body, dict):
+            # A body-shaped verb with no recovered request body is a blind spot
+            # worth flagging, but only when we resolved the route from the spec.
+            if _is_body_endpoint(ep) and ep.get("source") == "openapi-spec":
+                gaps.append(
+                    {
+                        "method": ep.get("method"),
+                        "path": ep.get("path"),
+                        "controller": ep.get("controller"),
+                        "reason": "no_request_body_constraints",
+                    }
+                )
+            continue
+
+        constraints = body.get("constraints") or []
+        validated_fields: "list[dict[str, Any]]" = []
+        for fc in constraints:
+            if not isinstance(fc, dict):
+                continue
+            rules = _field_rules(fc)
+            customs: "list[dict[str, Any]]" = []
+            for ann in fc.get("extraAnnotations", []) or []:
+                cc = catalog.get(ann)
+                entry: "dict[str, Any]" = {"annotation": ann}
+                if cc is not None:
+                    custom_used.add(ann)
+                    if cc.validators:
+                        entry["validators"] = cc.validators
+                    if cc.message is not None:
+                        entry["message"] = cc.message
+                    entry["resolved"] = True
+                else:
+                    entry["resolved"] = False
+                customs.append(entry)
+            if not rules and not customs:
+                continue
+            field_entry: "dict[str, Any]" = {"name": fc.get("name")}
+            if rules:
+                field_entry["rules"] = rules
+            if customs:
+                field_entry["customValidators"] = customs
+            validated_fields.append(field_entry)
+
+        total_validated_fields += len(validated_fields)
+        route = {
+            "method": ep.get("method"),
+            "path": ep.get("path"),
+            "controller": ep.get("controller"),
+            "handler": ep.get("handler"),
+            "schema": body.get("schema"),
+            "validatedFields": validated_fields,
+        }
+        out_endpoints.append(route)
+        if _is_body_endpoint(ep) and not validated_fields:
+            gaps.append(
+                {
+                    "method": ep.get("method"),
+                    "path": ep.get("path"),
+                    "controller": ep.get("controller"),
+                    "schema": body.get("schema"),
+                    "reason": "no_validated_fields",
+                }
+            )
+
+    custom_list = [catalog[k].to_dict() for k in sorted(catalog)]
+    result: "dict[str, Any]" = {
+        "endpoints": out_endpoints,
+        "custom_validators": custom_list,
+        "gaps": gaps,
+        "summary": {
+            "endpoints_with_body": len(out_endpoints),
+            "validated_fields": total_validated_fields,
+            "custom_validators_declared": len(custom_list),
+            "custom_validators_linked": len(custom_used),
+            "gaps": len(gaps),
+        },
+    }
+    spec_path = endpoints_data.get("openapi_spec")
+    if spec_path:
+        result["openapi_spec"] = spec_path
+    return result