sourcecode 1.38.0__py3-none-any.whl → 1.41.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/cir_graphs.py

@@ -25,22 +25,67 @@ class ImplementationGraph:
 
     Built from implements edges where BOTH ends are known CIR symbols (internal
     interface/class pairs).  External framework interfaces are excluded.
+
+    Subtype indices (CH-001c): `extends` edges are also captured so that
+    interface-to-interface inheritance (`SubIface extends BaseIface`) and abstract
+    base classes (`SubClass extends BaseClass`) are modeled as descendants of the
+    supertype.  The `implements`-only indices (`_impl_of`/`_ifaces_of`) are kept
+    separate to preserve DI resolution semantics (primary_implementation).
     """
     _impl_of: dict[str, list[str]] = field(default_factory=dict)
     _ifaces_of: dict[str, list[str]] = field(default_factory=dict)
+    # CH-001c: union of implements + extends descendants (impl classes, sub-interfaces,
+    # subclasses) keyed by supertype FQN, and its reverse.
+    _subtype_of: dict[str, list[str]] = field(default_factory=dict)
+    _supertype_of: dict[str, list[str]] = field(default_factory=dict)
 
     # ---------------------------------------------------------------------------
     # Queries
     # ---------------------------------------------------------------------------
 
     def implementations_of(self, interface_fqn: str) -> list[str]:
-        """Return FQNs of classes that implement interface_fqn (in-repo only)."""
+        """Return FQNs of classes that implement interface_fqn (in-repo only).
+
+        Strictly `implements` edges — excludes sub-interfaces/subclasses. Use
+        subtypes_of()/all_subtypes_of() for the full impact-relevant descendant set.
+        """
         return self._impl_of.get(interface_fqn, [])
 
     def interfaces_of(self, class_fqn: str) -> list[str]:
         """Return FQNs of in-repo interfaces implemented by class_fqn."""
         return self._ifaces_of.get(class_fqn, [])
 
+    def subtypes_of(self, type_fqn: str) -> list[str]:
+        """Return direct in-repo subtypes of type_fqn.
+
+        Union of `implements` (concrete impls) and `extends` (sub-interfaces,
+        subclasses) children.  This is the impact-relevant descendant set: a change
+        to type_fqn's contract propagates to all of these.
+        """
+        return self._subtype_of.get(type_fqn, [])
+
+    def supertypes_of(self, type_fqn: str) -> list[str]:
+        """Return direct in-repo supertypes of type_fqn (implemented/extended)."""
+        return self._supertype_of.get(type_fqn, [])
+
+    def all_subtypes_of(self, type_fqn: str) -> list[str]:
+        """Return the transitive closure of in-repo subtypes (BFS, cycle-safe).
+
+        Covers multi-level hierarchies, e.g. a base interface → sub-interface →
+        concrete impl chain.  Order is breadth-first from type_fqn; deduplicated.
+        """
+        seen: set[str] = set()
+        out: list[str] = []
+        queue: list[str] = list(self._subtype_of.get(type_fqn, []))
+        while queue:
+            sub = queue.pop(0)
+            if sub in seen:
+                continue
+            seen.add(sub)
+            out.append(sub)
+            queue.extend(self._subtype_of.get(sub, []))
+        return out
+
     def primary_implementation(self, interface_fqn: str) -> str | None:
         """Return the single implementation if unambiguous, else None.
 
@@ -89,9 +134,14 @@ class ImplementationGraph:
 
         impl_of: dict[str, list[str]] = {}
         ifaces_of: dict[str, list[str]] = {}
+        subtype_of: dict[str, list[str]] = {}
+        supertype_of: dict[str, list[str]] = {}
 
         for edge in dependencies:
-            if edge.get("type") != "implements":
+            etype = edge.get("type")
+            # CH-001c: extends edges (sub-interface / subclass) are subtype relations
+            # too, even though they never feed the implements-only DI indices.
+            if etype not in ("implements", "extends"):
                 continue
             from_fqn = (edge.get("from") or "").strip()
             to_fqn = (edge.get("to") or "").strip()
@@ -110,12 +160,27 @@ class ImplementationGraph:
             if ">" in from_fqn or "<" in from_fqn:
                 continue
 
-            if from_fqn not in impl_of.get(to_fqn, []):
-                impl_of.setdefault(to_fqn, []).append(from_fqn)
-            if to_fqn not in ifaces_of.get(from_fqn, []):
-                ifaces_of.setdefault(from_fqn, []).append(to_fqn)
+            # Subtype indices — both implements and extends contribute descendants.
+            if from_fqn not in subtype_of.get(to_fqn, []):
+                subtype_of.setdefault(to_fqn, []).append(from_fqn)
+            if to_fqn not in supertype_of.get(from_fqn, []):
+                supertype_of.setdefault(from_fqn, []).append(to_fqn)
+
+            # Implements-only indices — preserve DI resolution semantics. Sub-interfaces
+            # and subclasses (extends) must NOT count as "implementations" for
+            # primary_implementation() bean resolution.
+            if etype == "implements":
+                if from_fqn not in impl_of.get(to_fqn, []):
+                    impl_of.setdefault(to_fqn, []).append(from_fqn)
+                if to_fqn not in ifaces_of.get(from_fqn, []):
+                    ifaces_of.setdefault(from_fqn, []).append(to_fqn)
 
-        return cls(_impl_of=impl_of, _ifaces_of=ifaces_of)
+        return cls(
+            _impl_of=impl_of,
+            _ifaces_of=ifaces_of,
+            _subtype_of=subtype_of,
+            _supertype_of=supertype_of,
+        )
 
 
 # ---------------------------------------------------------------------------

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/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/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/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):