sourcecode 1.57.0__py3-none-any.whl → 1.58.0__py3-none-any.whl

sourcecode/__init__.py

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

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

{sourcecode-1.57.0.dist-info → sourcecode-1.58.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.57.0
+Version: 1.58.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.58.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.58.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.dist-info → sourcecode-1.58.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=TrDqUl3QPap22po5ZZVSMV_lWRZibeQ0Vv3MgrCN2Wk,103
+sourcecode/__init__.py,sha256=zPgb29z23K85U3nCKBwXfaqA7j0bV7r7tMzxrVDP-9w,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=liCwQmLgb5vplohy8arjYxs_HOIv5C9MjLh_gY6bc5Q,44115
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
@@ -55,14 +55,14 @@ sourcecode/semantic_analyzer.py,sha256=4OdG6tTSnTvq3_dSWMbQu8Ad1ndSCKeG-b9qM4hIx
 sourcecode/serializer.py,sha256=TGzftrSKitZrtl6Hh-R05s4KdTOxwTmph_lGDbo2Wzg,125015
 sourcecode/spring_event_topology.py,sha256=5_ON_21Le5zbG-1GRc5GLIi5HJfy_QjcXLVPC5WeUGQ,18055
 sourcecode/spring_findings.py,sha256=G7Or2lKBUQbcTDqudLvSs9XvNg_YoAa-_lBOG_ULs8E,5457
-sourcecode/spring_impact.py,sha256=f8XJtOG41f7EHQCs64BBZ0mdMTwU40DRcMoQ59SVprg,53296
+sourcecode/spring_impact.py,sha256=qLwLfItX_o9LU-k_qjhD2hFpTX3PpEQ85TsYTAArzvg,56016
 sourcecode/spring_model.py,sha256=zOAgFmrRbG4a6KLm1TJl55aWMyPNsz3OS3FSczqPG6A,16594
 sourcecode/spring_security_audit.py,sha256=XtPJ1SXlZJ8k6VYmaWuAp7Bbir4UmreAL7doIGQ5I7o,20595
 sourcecode/spring_semantic.py,sha256=O1nKSGVzlukuxLHQVuCPxc-XrcrMFxwlHA20_dmEGgM,13307
 sourcecode/spring_tx_analyzer.py,sha256=FdFcyqPp3aT9oJ-PKrnXcTA6s69wdvzG-NBm0GMGPTU,30717
 sourcecode/summarizer.py,sha256=zgdps7yS2IktAbWe7IWz0oUcr3QIuNPRGrsScbZ4R1g,21797
 sourcecode/tree_utils.py,sha256=8GAkIfQAsvtEudIeW1l4ooH_oRtrWR8cpJQJsEa_Pfw,2093
-sourcecode/validation_surface.py,sha256=_HiKeUuN8wk8V2pWp1TRcwB_BwxsxyFWTqzCKGx1B8M,12747
+sourcecode/validation_surface.py,sha256=2Ojfzhw9R4XpemAFqb9RXf4FKyI3DYjGo4Dp0AHZMQo,22600
 sourcecode/version_check.py,sha256=CHp6ZxTIfo8kyHPCBgJA1uFC0xQCoXMuuOfrW8QTL8o,4942
 sourcecode/workspace.py,sha256=X_6NmNnitvT3_38V-JDChydo_sR68s249hLFlrQskU0,8271
 sourcecode/detectors/__init__.py,sha256=A0AACJFF6HWf_RgatNtWu3PUzstcKtIGM9f1PoFcJug,1987
@@ -102,8 +102,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
 sourcecode/telemetry/filters.py,sha256=NHa5T-6DaZduQPFuC34jOqHWQgSizM-Ygq8aZ4j19ng,5834
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-1.57.0.dist-info/METADATA,sha256=MllfgzFIxub5-5P1bTKKkF0ifSPQVoCD3XNMqS5V4-U,38704
-sourcecode-1.57.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.57.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.57.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.57.0.dist-info/RECORD,,
+sourcecode-1.58.0.dist-info/METADATA,sha256=hmIYx5s3UECwA6NNlKD6HEetY1pl-6t76_KF0YKZysA,38831
+sourcecode-1.58.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.58.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.58.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.58.0.dist-info/RECORD,,