sourcecode 1.57.0__tar.gz → 1.59.0__tar.gz

{sourcecode-1.57.0 → sourcecode-1.59.0}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [1.59.0] — 2026-06-19
+
+### Fixed
+- **Event topology now recognizes generic-wrapper event publishers.**
+  `publishEvent(new SaveServiceEvent<>(obj))` and explicit forms like
+  `new SaveServiceEvent<Order>(obj)` were silently dropped: the publisher-edge
+  regex required the constructor `(` to immediately follow the class name, so any
+  diamond `<>` or type argument broke the match. `repo-ir` / event-topology then
+  reported no producers for the whole generic `*ServiceEvent` family (e.g. OpenMRS
+  `SaveServiceEvent`/`VoidServiceEvent`/`RetireServiceEvent`). The inline and
+  two-step publish scans now skip an optional (incl. nested) generic argument list.
+- **`impact-chain` now resolves intra-class method callers.** A query on a
+  private/helper method (e.g. `OrderServiceImpl#stopOrder`) found zero direct
+  callers and degraded to a wrong class-level expansion, because method-to-method
+  calls inside a single class produced no graph edge — only class-level `calls`
+  edges existed. The relation builder now emits method-level `calls` edges for
+  bare `m(...)` and `this.m(...)` invocations whose target is a sibling method of
+  the same class (string/comment-aware, overload-safe, no self-loops). The two
+  defects were found dogfooding the tool on OpenMRS issue #6197.
+
+## [1.58.0] — 2026-06-19
+
+### Added
+- **`validation` recovers DTO constraints from source when no OpenAPI spec is
+  present.** Previously `validated_fields` read `0` for any repo without a spec
+  on disk, even when DTOs carried bean-validation annotations. The command now
+  locates each body-shaped handler's `@Valid`/`@Validated` parameter, resolves
+  the DTO in-repo, and reads its field constraints (following one in-repo
+  supertype so inherited constraints are kept). Recovered routes are tagged
+  `source="source-derived"` at medium confidence with a `binding` hint
+  (body vs form). The core symbol/endpoint extractor is untouched, so the
+  OpenAPI-driven path is unchanged. Verified: spring-petclinic 0 → 13 validated
+  fields; repos with no `@Valid` usage correctly stay at 0 (no false positives).
+
+### Changed
+- **`impact-chain` output now matches the `impact` command's risk schema.**
+  `risk_score`, `confidence_score`, `confidence_level`, and `explanation` are
+  emitted at the top level (previously `risk_score` lived only in `metadata`
+  and there was no `explanation`). The legacy `confidence` string is retained
+  and equals `confidence_level`. Risk/confidence formulas are unchanged — only
+  the output contract was aligned so agents parse both commands with one shape.
+
 ## [1.57.0] — 2026-06-19
 
 ### Changed

{sourcecode-1.57.0 → sourcecode-1.59.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.57.0
+Version: 1.59.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.57.0-blue)
+![Version](https://img.shields.io/badge/version-1.59.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.53.0
+# sourcecode 1.59.0
 ```
 
 ---
@@ -150,6 +150,8 @@ sourcecode impact-chain OrderPlacedEvent /path/to/repo --type events
 sourcecode endpoints /path/to/repo
 
 # Request-body validation per endpoint: constraints + custom validators (free)
+# Recovers constraints from the OpenAPI spec, or directly from Java DTO
+# bean-validation annotations when no spec is present.
 sourcecode validation /path/to/repo
 
 # Onboard to an unfamiliar codebase

{sourcecode-1.57.0 → sourcecode-1.59.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.57.0-blue)
+![Version](https://img.shields.io/badge/version-1.59.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.53.0
+# sourcecode 1.59.0
 ```
 
 ---
@@ -112,6 +112,8 @@ sourcecode impact-chain OrderPlacedEvent /path/to/repo --type events
 sourcecode endpoints /path/to/repo
 
 # Request-body validation per endpoint: constraints + custom validators (free)
+# Recovers constraints from the OpenAPI spec, or directly from Java DTO
+# bean-validation annotations when no spec is present.
 sourcecode validation /path/to/repo
 
 # Onboard to an unfamiliar codebase

{sourcecode-1.57.0 → sourcecode-1.59.0}/pyproject.toml

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

{sourcecode-1.57.0 → sourcecode-1.59.0}/src/sourcecode/__init__.py

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

{sourcecode-1.57.0 → sourcecode-1.59.0}/src/sourcecode/repository_ir.py

@@ -347,12 +347,17 @@ _SPRING_OTHER: frozenset[str] = frozenset({
     "@MatrixParam", "@CookieParam", "@Context",
 })
 
-_PUBLISH_EVENT_RE = re.compile(r'\.publishEvent\s*\(\s*new\s+(\w+)\s*[(\{]')
+# Optional generic type args between the event class name and its constructor
+# parens — diamond `<>` or explicit `<Order>` / `<Map<String,Integer>>`.
+# Required so `publishEvent(new SaveServiceEvent<>(obj))` (generic event wrappers,
+# e.g. OpenMRS *ServiceEvent family) is recognised as a publisher edge.
+_GENERIC_ARGS = r'(?:<[^<>;{}()]*(?:<[^<>;{}()]*>[^<>;{}()]*)*>)?'
+_PUBLISH_EVENT_RE = re.compile(r'\.publishEvent\s*\(\s*new\s+(\w+)\s*' + _GENERIC_ARGS + r'\s*[(\{]')
 
 # Two-step publish: SomeEvent var = new SomeEvent(...); publisher.publishEvent(var)
 # Used when event is created before passing to publishEvent (common pattern).
 _PUBLISH_EVENT_CALL_RE = re.compile(r'\.publishEvent\s*\(')
-_NEW_EVENT_INSTANTIATION_RE = re.compile(r'\bnew\s+(\w+Event)\s*[\({]')
+_NEW_EVENT_INSTANTIATION_RE = re.compile(r'\bnew\s+(\w+Event)\s*' + _GENERIC_ARGS + r'\s*[\({]')
 
 # Keycloak SPI event fire pattern: XxxEvent.fire(session, ...)
 _FIRE_EVENT_RE = re.compile(r'\b(\w+Event)\.fire\s*\(')
@@ -1122,6 +1127,102 @@ def _build_same_package_map(symbols: list[SymbolRecord]) -> dict[str, dict[str,
     return result
 
 
+# Reserved words that read like calls (`if (`, `for (`, …). Can never be sibling
+# method names (Java reserves them), but guard the intra-class scan anyway.
+_CALL_KEYWORDS: frozenset[str] = frozenset({
+    "if", "for", "while", "switch", "catch", "return", "synchronized",
+    "new", "super", "this", "assert",
+})
+
+
+def _method_body(raw_lines: list[str], start_idx: int) -> str:
+    """Source text of the method/constructor declared at raw_lines[start_idx],
+    from its first '{' to the matching '}' (brace-matched, string/char aware).
+
+    The signature prefix before '{' is dropped so the method's own name is not
+    scanned as a call site. Returns "" for a bodyless declaration (abstract /
+    interface method terminated by ';' before any '{').
+    """
+    depth = 0
+    started = False
+    out: list[str] = []
+    for i in range(start_idx, len(raw_lines)):
+        line = raw_lines[i]
+        if not started:
+            if "{" in line:
+                started = True
+                line = line[line.index("{"):]
+            elif ";" in line:
+                return ""           # bodyless declaration
+            else:
+                continue            # multi-line signature continuation
+        out.append(line)
+        depth += _count_net_braces(line)
+        if depth <= 0:
+            break
+    return "\n".join(out)
+
+
+def _intra_class_call_edges(symbols: list[SymbolRecord], source: str) -> list[RelationEdge]:
+    """Method-level `calls` edges for intra-class invocations.
+
+    `discontinueOrder(){ stopOrder(...); }` →
+    OrderServiceImpl#discontinueOrder --calls--> OrderServiceImpl#stopOrder.
+
+    Class-level call scans miss method-to-method calls within a single class, so
+    impact-chain on a private/helper method (e.g. OrderServiceImpl#stopOrder) found
+    zero method-level callers and degraded to a wrong class-level expansion. Resolves
+    bare `m(...)` and `this.m(...)` calls whose target is a sibling METHOD of the same
+    class. Overloads link to all same-name siblings (arity not resolved by regex).
+    Deterministic, in-source only — no cross-file or runtime inference.
+    """
+    callers = [s for s in symbols if s.symbol_kind in ("method", "constructor") and s.line]
+    if not callers:
+        return []
+
+    # Per-class sibling index: simple method name → [method FQNs]. Constructors are
+    # not call targets (a `new X(...)` site is a different relation).
+    siblings: dict[str, dict[str, list[str]]] = {}
+    for s in symbols:
+        if s.symbol_kind == "method" and "#" in s.symbol:
+            cls = _enclosing_class(s.symbol)
+            name = s.symbol.rsplit("#", 1)[1]
+            siblings.setdefault(cls, {}).setdefault(name, []).append(s.symbol)
+    if not siblings:
+        return []
+
+    raw_lines = source.splitlines()
+    edges: list[RelationEdge] = []
+    for caller in callers:
+        cls = _enclosing_class(caller.symbol)
+        sib = siblings.get(cls)
+        if not sib:
+            continue
+        body = _method_body(raw_lines, caller.line - 1)
+        if not body:
+            continue
+        body = _STRING_LITERAL_RE.sub('', _strip_java_comments(body))
+        for name, fqns in sib.items():
+            if name in _CALL_KEYWORDS:
+                continue
+            # bare `name(` (not preceded by word char or '.') OR explicit `this.name(`
+            pat = (r'(?<![\w.])' + re.escape(name) + r'\s*\('
+                   + r'|\bthis\s*\.\s*' + re.escape(name) + r'\s*\(')
+            if not re.search(pat, body):
+                continue
+            for tgt in fqns:
+                if tgt == caller.symbol:
+                    continue        # skip self-recursion self-loop
+                edges.append(RelationEdge(
+                    from_symbol=caller.symbol,
+                    to_symbol=tgt,
+                    type="calls",
+                    confidence="medium",
+                    evidence={"type": "method_call", "value": f"{name}(...)"},
+                ))
+    return edges
+
+
 def _build_relations(
     symbols: list[SymbolRecord],
     raw_imports: list[str],
@@ -1557,6 +1658,9 @@ def _build_relations(
                         evidence={"type": "method_call", "value": f"{_tgt.split('.')[-1]}.…(…)"},
                     ))
 
+    # ── Intra-class method calls: EnclosingMethod -> calls -> SameClass#sibling ──
+    edges.extend(_intra_class_call_edges(symbols, source))
+
     seen: set[tuple[str, str, str]] = set()
     unique: list[RelationEdge] = []
     for e in edges:

{sourcecode-1.57.0 → sourcecode-1.59.0}/src/sourcecode/spring_impact.py

@@ -70,6 +70,17 @@ _SEVERITY_WEIGHT: dict[str, float] = {
     "low": 1.0,
 }
 
+# Maps the categorical confidence to a numeric score so impact-chain output
+# carries the same `confidence_score`/`confidence_level` pair as the `impact`
+# command. Deterministic — mirrors impact's confidence banding (high≥0.75,
+# medium≥0.45).
+_CONFIDENCE_SCORE: dict[str, float] = {
+    "high": 0.9,
+    "medium": 0.6,
+    "low": 0.3,
+    "unknown": 0.0,
+}
+
 
 # ---------------------------------------------------------------------------
 # Output model
@@ -117,10 +128,16 @@ class ImpactChainResult:
     impact_findings: list[dict] = field(default_factory=list)     # SpringFinding.to_dict() filtered
     analysis_warnings: list[str] = field(default_factory=list)
     risk_level: str = "unknown"                # "critical" | "high" | "medium" | "low" | "unknown"
-    confidence: str = "high"                   # "high" | "medium" | "low"
+    risk_score: float = 0.0                    # numeric score behind risk_level (parity with `impact`)
+    confidence: str = "high"                   # "high" | "medium" | "low" (legacy field, kept)
+    explanation: str = ""                      # human-readable rationale (parity with `impact`)
     metadata: dict = field(default_factory=dict)
 
     def to_dict(self) -> dict:
+        # `confidence_level`/`confidence_score` mirror the `impact` command's schema
+        # so AI agents parse both commands with one shape. `confidence` (string) is
+        # retained for backward compatibility — it equals `confidence_level`.
+        confidence_level = self.confidence
         d: dict = {
             "schema_version": self.schema_version,
             "symbol": self.symbol,
@@ -134,7 +151,11 @@ class ImpactChainResult:
             "impact_findings": self.impact_findings,
             "analysis_warnings": self.analysis_warnings,
             "risk_level": self.risk_level,
+            "risk_score": self.risk_score,
             "confidence": self.confidence,
+            "confidence_level": confidence_level,
+            "confidence_score": _CONFIDENCE_SCORE.get(confidence_level, 0.0),
+            "explanation": self.explanation,
             "metadata": self.metadata,
         }
         return d
@@ -680,6 +701,33 @@ def _compute_risk(
     return level, round(total, 2)
 
 
+def _build_chain_explanation(
+    risk_level: str,
+    direct_callers: int,
+    indirect_callers: int,
+    endpoints_affected: int,
+    findings: int,
+    confidence: str,
+) -> str:
+    """Human-readable rationale, phrased to match the `impact` command's
+    explanation so both surfaces read consistently."""
+    if not direct_callers and not indirect_callers and not endpoints_affected:
+        return "No callers or endpoints found in the impact chain. Low-risk isolated change."
+    parts: list[str] = []
+    if direct_callers:
+        parts.append(f"{direct_callers} direct caller{'s' if direct_callers != 1 else ''}")
+    if indirect_callers:
+        parts.append(f"{indirect_callers} indirect caller{'s' if indirect_callers != 1 else ''}")
+    if endpoints_affected:
+        parts.append(f"{endpoints_affected} endpoint{'s' if endpoints_affected != 1 else ''} exposed")
+    if findings:
+        parts.append(f"{findings} TX/SEC finding{'s' if findings != 1 else ''} in chain")
+    text = f"Risk={risk_level.upper()}: {'; '.join(parts)}."
+    if confidence != "high":
+        text += f" (confidence={confidence}: IR may be incomplete)"
+    return text
+
+
 # ---------------------------------------------------------------------------
 # Security surface aggregation
 # ---------------------------------------------------------------------------
@@ -762,6 +810,7 @@ class ImpactOrchestrator:
                 analysis_warnings=warnings or [f"Symbol '{symbol}' not found in CIR."],
                 risk_level="unknown",
                 confidence="low",
+                explanation=f"Symbol {symbol!r} not found in the IR.",
                 metadata={"analysis_depth": depth},
             )
 
@@ -1041,7 +1090,16 @@ class ImpactOrchestrator:
             impact_findings=impact_findings,
             analysis_warnings=warnings,
             risk_level=risk_level,
+            risk_score=risk_score,
             confidence=confidence,
+            explanation=_build_chain_explanation(
+                risk_level,
+                len(direct_callers),
+                len(indirect_callers),
+                len(endpoints_affected),
+                len(impact_findings),
+                confidence,
+            ),
             metadata={
                 "analysis_depth": depth,
                 "callers_total": len(direct_callers) + len(indirect_callers),
@@ -1132,4 +1190,5 @@ def run_impact_chain(
             analysis_warnings=[f"Internal error: {type(exc).__name__}: {exc}"],
             risk_level="unknown",
             confidence="low",
+            explanation=f"Internal error during analysis: {type(exc).__name__}.",
         )

{sourcecode-1.57.0 → sourcecode-1.59.0}/src/sourcecode/validation_surface.py

@@ -180,6 +180,226 @@ def discover_custom_validators(root: Path) -> "dict[str, CustomConstraint]":
     return catalog
 
 
+# ---------------------------------------------------------------------------
+# Source-derived constraints (no OpenAPI spec)
+#
+# When a repo ships no OpenAPI spec, declarative DTO constraints still live in
+# the Java source as bean-validation annotations. We recover them directly:
+# locate the handler's validated body parameter (@Valid/@Validated), resolve
+# that DTO class in-repo, and read its fields' constraint annotations. This is
+# pure extraction — it never fabricates constraints, and it is reported with
+# source="source-derived" + a lower confidence than spec-carried constraints.
+# ---------------------------------------------------------------------------
+
+# jakarta/javax bean-validation built-in constraints. @Valid marks nested
+# validation, which still means "this field is validated".
+_BEAN_CONSTRAINTS = frozenset({
+    "NotNull", "NotEmpty", "NotBlank", "Null", "AssertTrue", "AssertFalse",
+    "Min", "Max", "DecimalMin", "DecimalMax", "Digits", "Positive",
+    "PositiveOrZero", "Negative", "NegativeOrZero", "Size", "Pattern", "Email",
+    "Past", "PastOrPresent", "Future", "FutureOrPresent", "Valid",
+})
+_VALIDATE_MARKERS = frozenset({"Valid", "Validated"})
+# A class-typed identifier (starts uppercase) — heuristic for "a DTO type".
+_CLASS_TYPE_RE = re.compile(r"^[A-Z][\w]*$")
+_ANN_TOKEN_RE = re.compile(r"@(\w+)\s*(?:\(([^)]*)\))?")
+_FIELD_DECL_RE = re.compile(
+    r"^\s*(?:private|protected|public)\s+"
+    r"(?:final\s+|static\s+|transient\s+|volatile\s+)*"
+    r"[\w.$<>\[\], ]+?\s+(\w+)\s*[;=]"
+)
+_CLASS_EXTENDS_RE = re.compile(r"\bclass\s+\w+\s+extends\s+(\w+)")
+
+
+def _index_repo_classes(root: Path) -> "dict[str, Path]":
+    """Map a class's simple name → its source file (first non-test match)."""
+    index: "dict[str, Path]" = {}
+    count = 0
+    for jf in root.rglob("*.java"):
+        rel = str(jf).replace("\\", "/")
+        if is_test_path(rel) or "/target/" in rel:
+            continue
+        count += 1
+        if count > _SCAN_CAP:
+            break
+        index.setdefault(jf.stem, jf)
+    return index
+
+
+def _balanced_parens(src: str, open_idx: int) -> "Optional[str]":
+    """Given the index of a '(', return the inner text up to its matching ')'."""
+    depth = 0
+    for i in range(open_idx, len(src)):
+        c = src[i]
+        if c == "(":
+            depth += 1
+        elif c == ")":
+            depth -= 1
+            if depth == 0:
+                return src[open_idx + 1:i]
+    return None
+
+
+def _split_top_level(params: str) -> "list[str]":
+    """Split a parameter list on top-level commas (ignoring generics/parens)."""
+    out: "list[str]" = []
+    depth = 0
+    buf: "list[str]" = []
+    for c in params:
+        if c in "<(":
+            depth += 1
+        elif c in ">)":
+            depth -= 1
+        if c == "," and depth == 0:
+            out.append("".join(buf))
+            buf = []
+        else:
+            buf.append(c)
+    if buf:
+        out.append("".join(buf))
+    return out
+
+
+def _handler_body_dto(controller_src: str, handler: str) -> "Optional[tuple[str, str]]":
+    """Find ``handler``'s validated body parameter. Returns (dto_simple, binding)
+    where binding is 'body' (@RequestBody), 'form' (@ModelAttribute / implicit),
+    or None when the handler has no @Valid/@Validated DTO parameter."""
+    for m in re.finditer(r"\b" + re.escape(handler) + r"\s*\(", controller_src):
+        params = _balanced_parens(controller_src, m.end() - 1)
+        if params is None:
+            continue
+        for raw in _split_top_level(params):
+            raw = raw.strip()
+            if not raw:
+                continue
+            anns = {a.group(1) for a in _ANN_TOKEN_RE.finditer(raw)}
+            if not (anns & _VALIDATE_MARKERS):
+                continue
+            # Strip annotations, then read the parameter's declared type.
+            without_ann = _ANN_TOKEN_RE.sub("", raw).strip()
+            without_ann = re.sub(r"^final\s+", "", without_ann)
+            parts = without_ann.split()
+            if not parts:
+                continue
+            dto = re.sub(r"<.*", "", parts[0]).strip()
+            if not _CLASS_TYPE_RE.match(dto):
+                continue
+            binding = "body" if "RequestBody" in anns else "form"
+            return dto, binding
+    return None
+
+
+def _dto_field_constraints(
+    dto: str,
+    class_index: "dict[str, Path]",
+    catalog: "dict[str, CustomConstraint]",
+    _seen: "Optional[set[str]]" = None,
+) -> "list[dict[str, Any]]":
+    """Read a DTO's validated fields (own file + in-repo supertypes, depth-guarded)."""
+    if _seen is None:
+        _seen = set()
+    if dto in _seen or dto not in class_index:
+        return []
+    _seen.add(dto)
+    try:
+        src = class_index[dto].read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+
+    fields: "list[dict[str, Any]]" = []
+    pending: "list[tuple[str, str]]" = []  # (annotation, args)
+    for line in src.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("@"):
+            mt = _ANN_TOKEN_RE.match(stripped)
+            if mt:
+                pending.append((mt.group(1), (mt.group(2) or "").strip()))
+            continue
+        fm = _FIELD_DECL_RE.match(line)
+        if fm:
+            rules: "list[dict[str, Any]]" = []
+            customs: "list[dict[str, Any]]" = []
+            for ann, args in pending:
+                if ann in _BEAN_CONSTRAINTS:
+                    rule: "dict[str, Any]" = {"kind": ann}
+                    if args:
+                        rule["value"] = args
+                    rules.append(rule)
+                elif ann in catalog:
+                    customs.append({"annotation": ann, "resolved": True})
+            if rules or customs:
+                entry: "dict[str, Any]" = {"name": fm.group(1)}
+                if rules:
+                    entry["rules"] = rules
+                if customs:
+                    entry["customValidators"] = customs
+                fields.append(entry)
+            pending = []
+        elif stripped and not stripped.startswith("//") and not stripped.startswith("*"):
+            # Any other meaningful line breaks the annotation→field adjacency.
+            pending = []
+
+    # Follow a single in-repo supertype so inherited constraints are not lost.
+    ext = _CLASS_EXTENDS_RE.search(src)
+    if ext:
+        seen_names = {f["name"] for f in fields}
+        for inherited in _dto_field_constraints(ext.group(1), class_index, catalog, _seen):
+            if inherited["name"] not in seen_names:
+                fields.append(inherited)
+    return fields
+
+
+def _recover_source_endpoints(
+    root: Path,
+    endpoints: "list[dict[str, Any]]",
+    catalog: "dict[str, CustomConstraint]",
+) -> "tuple[list[dict[str, Any]], int]":
+    """Build validation routes for source endpoints whose handler validates a
+    DTO. Returns (routes, validated_field_count). Only body-shaped verbs are
+    considered, matching the OpenAPI path's scope."""
+    class_index = _index_repo_classes(root)
+    controller_cache: "dict[str, Optional[str]]" = {}
+    routes: "list[dict[str, Any]]" = []
+    total = 0
+    for ep in endpoints:
+        if not _is_body_endpoint(ep):
+            continue
+        controller = ep.get("controller")
+        handler = ep.get("handler")
+        if not controller or not handler or controller not in class_index:
+            continue
+        if controller not in controller_cache:
+            try:
+                controller_cache[controller] = class_index[controller].read_text(
+                    encoding="utf-8", errors="replace"
+                )
+            except OSError:
+                controller_cache[controller] = None
+        csrc = controller_cache[controller]
+        if csrc is None:
+            continue
+        dto_binding = _handler_body_dto(csrc, str(handler))
+        if dto_binding is None:
+            continue
+        dto, binding = dto_binding
+        validated = _dto_field_constraints(dto, class_index, catalog)
+        if not validated:
+            continue
+        total += len(validated)
+        routes.append({
+            "method": ep.get("method"),
+            "path": ep.get("path"),
+            "controller": controller,
+            "handler": handler,
+            "schema": dto,
+            "binding": binding,
+            "source": "source-derived",
+            "confidence": "medium",
+            "validatedFields": validated,
+        })
+    return routes, total
+
+
 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]]" = []
@@ -303,18 +523,44 @@ def build_validation_surface(
     if spec_path:
         result["openapi_spec"] = spec_path
     else:
-        # No OpenAPI spec on disk / under target/generated-sources. Declarative
-        # DTO constraints cannot be recovered, so a sea of zeros here is expected
-        # and NOT a sign the repo lacks validation — it just isn't OpenAPI-driven.
-        # Surface this explicitly so the result is not silently misread as
-        # "no validation anywhere".
+        # No OpenAPI spec on disk / under target/generated-sources. Recover
+        # declarative constraints directly from the Java DTOs that handlers
+        # validate (@Valid/@Validated body params), so a repo without a spec is
+        # no longer reported as a sea of zeros.
         result["openapi_spec"] = None
-        result["note"] = (
-            "No OpenAPI spec found (no spec on disk or under "
-            "target/generated-sources). Declarative DTO constraints cannot be "
-            "recovered; only source-declared custom validators are reported. "
-            "Body-endpoint and validated-field counts will read zero unless an "
-            "OpenAPI spec is present — this is expected, not a missing-validation "
-            "finding."
+        source_routes, source_fields = _recover_source_endpoints(
+            root, endpoints_data.get("endpoints", []), catalog
         )
+        if source_routes:
+            existing = {(r.get("method"), r.get("path")) for r in out_endpoints}
+            for r in source_routes:
+                if (r.get("method"), r.get("path")) not in existing:
+                    out_endpoints.append(r)
+            total_validated_fields += source_fields
+            # Recompute the gaps that depended on the now-recovered routes.
+            recovered = {(r.get("method"), r.get("path")) for r in source_routes}
+            gaps = [
+                g for g in gaps
+                if (g.get("method"), g.get("path")) not in recovered
+            ]
+            result["endpoints"] = out_endpoints
+            result["gaps"] = gaps
+            result["summary"]["endpoints_with_body"] = len(out_endpoints)
+            result["summary"]["validated_fields"] = total_validated_fields
+            result["summary"]["gaps"] = len(gaps)
+            result["summary"]["source_derived_routes"] = len(source_routes)
+            result["note"] = (
+                "No OpenAPI spec found; constraints were recovered from Java DTO "
+                "source (bean-validation annotations on @Valid/@Validated handler "
+                "bodies). Routes carry source=\"source-derived\" at medium "
+                "confidence. Custom-validator linkage and nested generics may be "
+                "partial; OpenAPI-carried constraints would be more complete."
+            )
+        else:
+            result["note"] = (
+                "No OpenAPI spec found and no source DTO constraints recovered "
+                "(no handler validates an in-repo DTO via @Valid/@Validated, or "
+                "the DTOs declare no bean-validation annotations). This is "
+                "expected for such repos, not a missing-validation finding."
+            )
     return result