sourcecode 2.5.17__py3-none-any.whl → 2.5.19__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.5.17"
+__version__ = "2.5.19"

sourcecode/repository_ir.py

@@ -2475,10 +2475,20 @@ def _scan_guard_clauses(body: str) -> list[dict]:
 
 
 def _extract_guard_facts(symbols: list[SymbolRecord], source: str) -> dict[str, list[dict]]:
-    """Ordered `guard_clause` atoms per method/constructor FQN. Reuses the SAME
-    `_method_body` extraction as the other body facts; the scanner keeps only the
-    structural guard shape (β), on its own occurrence axis."""
-    callers = [s for s in symbols if s.symbol_kind in ("method", "constructor") and s.line]
+    """Ordered `guard_clause` atoms per method/constructor/endpoint FQN. Reuses the
+    SAME `_method_body` extraction as the other body facts; the scanner keeps only
+    the structural guard shape (β), on its own occurrence axis.
+
+    Endpoint-kind bodies are included (F2): an annotation-classified handler
+    (`@PostMapping …`, symbol_kind="endpoint") is still a method body, and a guard
+    that throws on a bad request parameter (`if (x == null || x.isBlank()) throw`)
+    is exactly the manual-validation shape the validation surface must see. The
+    scope was previously method/constructor only, which silently dropped every
+    guard living in a handler body — the atom exists, the coverage did not."""
+    callers = [
+        s for s in symbols
+        if s.symbol_kind in ("method", "constructor", "endpoint") and s.line
+    ]
     if not callers:
         return {}
     raw_lines = source.splitlines()

sourcecode/validation_inference.py

@@ -15,20 +15,23 @@ VAI note (§0.5): the only names this module keys on are **published open
 standards** (`jakarta.validation`, `javax.validation`, the bean-validation
 annotation vocabulary). No client / convention name enters a predicate.
 
-ARCHITECTURAL DIVERGENCE — manual_validation (design §2, deferred)
------------------------------------------------------------------
-Design §2 also asks for a `manual_validation` class detected by the **β
-GuardClause** shape on handler bodies (a guard that throws on a bad parameter).
-That path assumes guard atoms cover handlers. They do NOT: `_extract_guard_facts`
-(repository_ir.py) scans only `symbol_kind in {"method", "constructor"}`, and a
-mapped handler surfaces as kind `"endpoint"` — so `guard_facts` is empty for
-every handler body. Design §8 classifies §2 as *Incremental / no new primitive*;
-against the current architecture that is false. Rather than smuggle in an IR
-change under an "Incremental" increment, `manual_validation` is deferred and the
-conflict is documented in the design doc (EPV / INV-2: build the endpoint-scoped
-guard capability only when this consumer is ratified). The three classes that ARE
-reuse-only (active / available-unused / none) ship here and already resolve the
-field defect.
+manual_validation (design §2) — RESOLVED (F2, roadmap Engineering Decision Support)
+-----------------------------------------------------------------------------------
+Design §2 asks for a `manual_validation` class detected by the **β GuardClause**
+shape on handler bodies (a guard that throws/returns on a bad parameter). This was
+previously deferred because `_extract_guard_facts` scanned only
+`symbol_kind in {"method","constructor"}` and a mapped handler surfaces as kind
+`"endpoint"`, so `guard_facts` was empty for every handler body (EPV/INV-2: build
+the endpoint-scoped guard capability only when this consumer is ratified).
+
+Roadmap F2 ratifies the consumer. `_extract_guard_facts` now includes endpoint-kind
+bodies (repository_ir.py) — the SAME β scan widened to a symbol_kind it silently
+skipped, no new atom type — so a handler's entry guards are visible here. This
+module now classifies `manual_validation` from those atoms, scoped to
+null/empty-check guards (β's `other` test_kind lumps range checks with
+non-validation guards like memoization/preconditions, so counting it would inflate
+false positives; range validation is therefore not separately claimed — an honest
+under-report, labelled Likely never Verified).
 """
 from __future__ import annotations
 
@@ -64,6 +67,30 @@ _VALIDATE_MARKERS: frozenset[str] = frozenset({"Valid", "Validated"})
 # Body-carrying HTTP verbs — the surface where request-body validation applies.
 _BODY_VERBS: frozenset[str] = frozenset({"POST", "PUT", "PATCH"})
 
+# β GuardClause test kinds that read as manual input validation (F2). `other`
+# is excluded on purpose: at β it lumps range checks with non-validation guards
+# (memoization, preconditions), so it cannot be claimed as validation.
+_MANUAL_GUARD_TESTS: frozenset[str] = frozenset({"null_check", "empty_check"})
+
+
+def _manual_guarded_handlers(
+    cir: "CanonicalRepositoryIR", handler_symbols: "set[str]"
+) -> set[str]:
+    """Handler symbols carrying ≥1 null/empty β GuardClause that early-exits.
+
+    Every β atom already early-exits (return/throw — `_scan_guard_clauses` records
+    no other shape), so presence of a null/empty atom on a handler body IS the
+    manual-validation signal. Scoped to the handlers actually on the body surface
+    so a guard in an unrelated method never counts."""
+    gf = cir.guard_facts
+    out: set[str] = set()
+    for h in handler_symbols:
+        for atom in gf.get(h, ()) or ():
+            if atom.get("test_kind") in _MANUAL_GUARD_TESTS:
+                out.add(h)
+                break
+    return out
+
 
 def _validation_available(cir: "CanonicalRepositoryIR") -> tuple[bool, list[str]]:
     """True when a published bean-validation framework is on the classpath,
@@ -133,10 +160,11 @@ def infer_validation_pattern(cir: "CanonicalRepositoryIR") -> ValidationInferenc
 
     Repo-level class (DESIGN §2):
       - ``bean_validation_active``            — @Valid present on body handlers.
+      - ``manual_validation``                 — no @Valid, but body handlers guard
+        their input with null/empty β guard clauses that early-exit (Likely).
       - ``bean_validation_available_unused``  — validation on the classpath and
         body endpoints exist, but no handler validates → risk (Likely).
       - ``no_validation_detected``            — none of the above (Unknown).
-        (``manual_validation`` deferred — see module docstring.)
 
     Never raises.
     """
@@ -145,15 +173,30 @@ def infer_validation_pattern(cir: "CanonicalRepositoryIR") -> ValidationInferenc
 
     body_eps = [ep for ep in cir.endpoints if str(ep.method).upper() in _BODY_VERBS]
     body_total = len(body_eps)
+    body_handlers = {ep.handler_symbol for ep in body_eps}
+    manual_handlers = _manual_guarded_handlers(cir, body_handlers)
     validated_body = sum(1 for ep in body_eps if ep.handler_symbol in validated_handlers)
+    # manual guards only "count" where bean validation is absent — a handler that
+    # both @Valid-s and hand-guards is bean-validated, not manual.
+    manual_body = sum(
+        1 for ep in body_eps
+        if ep.handler_symbol in manual_handlers
+        and ep.handler_symbol not in validated_handlers
+    )
     unvalidated_body = body_total - validated_body
 
     # per-endpoint findings (only the body surface — where a request body applies)
     endpoint_findings: list[dict] = []
-    rollup = {"validated": 0, "available_unused": 0, "unvalidated_unknown": 0}
+    rollup = {
+        "validated": 0, "manual_guard": 0,
+        "available_unused": 0, "unvalidated_unknown": 0,
+    }
     for ep in body_eps:
         if ep.handler_symbol in validated_handlers:
             klass, conf = "validated", Confidence.VERIFIED
+        elif ep.handler_symbol in manual_handlers:
+            # hand-written null/empty guard on the handler body → manual validation
+            klass, conf = "manual_guard", Confidence.LIKELY
         elif available:
             # @RequestBody-shaped verb, framework available, no @Valid → gap
             klass, conf = "available_unused", Confidence.LIKELY
@@ -175,11 +218,11 @@ def infer_validation_pattern(cir: "CanonicalRepositoryIR") -> ValidationInferenc
         "the exact @RequestBody parameter count is not captured (no IR atom "
         "exposes it), so 'available_unused' may include body-less handlers."
     )
-    manual_fn = (
-        "manual_validation (a handler that throws on a bad parameter) is not "
-        "detected — guard-clause atoms do not cover endpoint-kind handlers "
-        "(architectural defer, see module docstring); such a repo classifies "
-        "no_validation_detected here."
+    manual_range_fn = (
+        "manual_validation is detected from null/empty β guard clauses only; "
+        "range/other-shaped guards (e.g. `if (n < 0) throw`) are indistinguishable "
+        "at β from non-validation guards and are not counted, so a purely "
+        "range-guarded handler can under-report."
     )
 
     if validated_body > 0:
@@ -193,11 +236,38 @@ def infer_validation_pattern(cir: "CanonicalRepositoryIR") -> ValidationInferenc
                     "validated_body_endpoints": validated_body,
                     "body_endpoints": body_total,
                     "unvalidated_body_endpoints": unvalidated_body,
+                    "manual_guarded_body_endpoints": manual_body,
                     "validation_available": available,
                 },
             ),
             limitations=[common_limitation],
-            fn_causes=[manual_fn],
+            fn_causes=[manual_range_fn],
+        )
+    elif manual_body > 0:
+        pattern = "manual_validation"
+        verdict = Verdict(
+            claim="Request bodies validated by hand-written guard clauses (no bean validation)",
+            confidence=Confidence.LIKELY,
+            evidence=Evidence(
+                atoms_used=[f"null/empty guard: {h}" for h in sorted(manual_handlers)][:50],
+                details={
+                    "body_endpoints": body_total,
+                    "manual_guarded_body_endpoints": manual_body,
+                    "validated_body_endpoints": 0,
+                    "validation_available": available,
+                },
+            ),
+            limitations=[
+                common_limitation,
+                "A null/empty guard is a likely input-validation signal, not a "
+                "proof — it could defend an internal invariant unrelated to the "
+                "request contract.",
+            ],
+            fp_causes=[
+                "A null/empty guard may protect against an internal null rather "
+                "than validate the request body.",
+            ],
+            fn_causes=[manual_range_fn],
         )
     elif available and body_total > 0:
         pattern = "bean_validation_available_unused"
@@ -222,7 +292,7 @@ def infer_validation_pattern(cir: "CanonicalRepositoryIR") -> ValidationInferenc
                 "A body endpoint may be intentionally unvalidated (idempotent "
                 "echo, internal-only), or validated manually.",
             ],
-            fn_causes=[manual_fn],
+            fn_causes=[manual_range_fn],
         )
     else:
         pattern = "no_validation_detected"
@@ -238,7 +308,7 @@ def infer_validation_pattern(cir: "CanonicalRepositoryIR") -> ValidationInferenc
                 "validation import, and no body endpoints, or validation is done "
                 "by a mechanism this projection does not model.",
             ],
-            fn_causes=[manual_fn],
+            fn_causes=[manual_range_fn],
         )
 
     return ValidationInferenceResult(

sourcecode/validation_surface.py

@@ -363,6 +363,98 @@ def _recover_source_endpoints(
     return routes, total
 
 
+def _recover_spec_endpoints(
+    root: Path,
+    existing_keys: "set[tuple[Any, Any]]",
+    catalog: "dict[str, Any]",
+    custom_used: "set[str]",
+) -> "tuple[Optional[str], list[dict[str, Any]], int]":
+    """Recover validation routes from a standalone OpenAPI spec on disk.
+
+    F1: ``extract_java_endpoints`` only links a spec when an openapi-generator
+    interface-controller (``@RestController implements XxxApi``) matches it. A
+    repo that ships a plain ``openapi.yml`` with no such controller therefore
+    reported "No OpenAPI spec found" — a confirmed false negative. This consults
+    the existing :func:`build_openapi_surface` producer directly so a discovered
+    spec's body operations contribute their declared constraints and flip the
+    "no spec" claim.
+
+    Returns ``(spec_path, routes, validated_field_count)``; ``spec_path`` is None
+    when no parseable spec with operations is present.
+    """
+    from sourcecode.openapi_surface import build_openapi_surface
+
+    surface = build_openapi_surface(root)
+    if surface is None or not surface.operations:
+        return None, [], 0
+
+    routes: "list[dict[str, Any]]" = []
+    total = 0
+    for op in surface.operations:
+        if str(op.method).upper() not in ("POST", "PUT", "PATCH"):
+            continue
+        key = (op.method, op.path)
+        if key in existing_keys:
+            continue  # already surfaced from source — dedupe by method+path
+        schema = surface.schemas.get(op.request_body_schema) if op.request_body_schema else None
+        constraints = [f.to_dict() for f in schema.fields] if schema is not None else []
+        validated = _validated_fields_from_constraints(constraints, catalog, custom_used)
+        total += len(validated)
+        route: "dict[str, Any]" = {
+            "method": op.method,
+            "path": op.path,
+            "controller": None,
+            "handler": op.operation_id or "(operation)",
+            "schema": op.request_body_schema,
+            "source": "openapi-spec",
+            "confidence": "high",
+            "validatedFields": validated,
+        }
+        routes.append(route)
+        existing_keys.add(key)
+    return surface.spec_path, routes, total
+
+
+def _validated_fields_from_constraints(
+    constraints: "list[Any]",
+    catalog: "dict[str, Any]",
+    custom_used: "set[str]",
+) -> "list[dict[str, Any]]":
+    """Render a schema's constraint dicts into ``validatedFields`` entries.
+
+    Mirrors the built-in-rule + custom-validator linkage the main loop applies to
+    OpenAPI request bodies; shared so the standalone-spec path (F1) stays byte-
+    consistent with the interface-controller path."""
+    out: "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
+        out.append(field_entry)
+    return out
+
+
 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]]" = []
@@ -491,6 +583,36 @@ def build_validation_surface(
     if spec_path:
         result["openapi_spec"] = spec_path
     else:
+        # No spec linked by extract_java_endpoints (no openapi-generator
+        # interface-controller matched). F1: consult the standalone-spec
+        # producer directly — a plain openapi.yml shipped in the repo is a real
+        # spec, so its body operations contribute constraints and flip the
+        # "no spec found" claim instead of reporting a false negative.
+        existing_keys = {(r.get("method"), r.get("path")) for r in out_endpoints}
+        spec_path2, spec_routes, spec_fields = _recover_spec_endpoints(
+            root, existing_keys, catalog, custom_used
+        )
+        if spec_path2 is not None:
+            result["openapi_spec"] = spec_path2
+            out_endpoints.extend(spec_routes)
+            total_validated_fields += spec_fields
+            spec_keys = {(r.get("method"), r.get("path")) for r in spec_routes}
+            gaps = [g for g in gaps if (g.get("method"), g.get("path")) not in spec_keys]
+            result["endpoints"] = out_endpoints
+            result["gaps"] = gaps
+            result["custom_validators"] = [catalog[k].to_dict() for k in sorted(catalog)]
+            result["summary"]["endpoints_with_body"] = len(out_endpoints)
+            result["summary"]["validated_fields"] = total_validated_fields
+            result["summary"]["custom_validators_linked"] = len(custom_used)
+            result["summary"]["gaps"] = len(gaps)
+            result["summary"]["spec_derived_routes"] = len(spec_routes)
+            result["note"] = (
+                "OpenAPI spec discovered on disk (standalone, not linked to a "
+                "generated interface-controller); body operations contributed "
+                "their declared constraints. Response shapes and non-body "
+                "operations are not modeled here."
+            )
+            return result
         # No OpenAPI spec on disk / under target/generated-sources. Recover
         # declarative constraints from the graph's DTO field nodes (bean-
         # validation annotations on @Valid/@Validated handler bodies), so a
@@ -525,6 +647,12 @@ def build_validation_surface(
                 "partial; OpenAPI-carried constraints would be more complete."
             )
         else:
+            # Genuine absence — no spec on disk AND no in-repo DTO constraints.
+            # Emit a machine-readable zero_result_reason (F1) so a consumer can
+            # tell "we looked and found nothing" from "we did not look": an empty
+            # surface here is an attested negative, not a missing-validation
+            # finding.
+            result["zero_result_reason"] = "no_openapi_spec_and_no_source_dto_constraints"
             result["note"] = (
                 "No OpenAPI spec found and no source DTO constraints recovered "
                 "(no handler validates an in-repo DTO via @Valid/@Validated, or "

{sourcecode-2.5.17.dist-info → sourcecode-2.5.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.17
+Version: 2.5.19
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-2.5.17.dist-info → sourcecode-2.5.19.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=Ao5tzW0DQ-NV-o4Yno0H_QEOlx1oyQh_ih-rdREfXDs,309
+sourcecode/__init__.py,sha256=lv_mMr5Y5s1U1_CJa-6pkjbnlCz4lXMFrxs9SHb4qJs,309
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=d7yoN6Tj4OBj-VgSMPEKg4WF9H8FypnZ5A6AkUh5oIE,34484
 sourcecode/architecture_analyzer.py,sha256=GFc4ek-s1IHWM7pl-0L32WahZ93AmDgrAMcOuBKA5Dk,61463
@@ -57,7 +57,7 @@ sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
-sourcecode/repository_ir.py,sha256=Q2lMpm5x8ZAIY4MVKWEcLZ-BP26kUoP1dRfdER6gSbo,312316
+sourcecode/repository_ir.py,sha256=2Za5B4ar0iqPkdlHHttmhcHO4ErTXmg8TyOY3tAO2CA,312842
 sourcecode/ris.py,sha256=Hw8TakTQ6hku-Abf2k8954NwkrH_sP73_8wVH8x5khc,22079
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=z3CV0rcGunu0Y8mpNgp07wI7nxT0pxw1BkXRRtI0Rpo,9609
@@ -79,8 +79,8 @@ sourcecode/spring_tx_analyzer.py,sha256=7qXwQR9QbpVxbxJC-mawBMXM9xzydtZeq5L18cP_
 sourcecode/summarizer.py,sha256=sr0-tfecFKCr-fSkPPWbl-t9HC7SY2ZxkjnnXX8DB2A,26621
 sourcecode/tree_utils.py,sha256=8GAkIfQAsvtEudIeW1l4ooH_oRtrWR8cpJQJsEa_Pfw,2093
 sourcecode/type_usage_surface.py,sha256=51IrKRQoIoRnlsiDjHnqpJBn2rc6E59aRhgS0HTzAF0,4428
-sourcecode/validation_inference.py,sha256=UtmYv-d4TEzT1ihGEipAhtXDrwq0XtVtjMpb3i7NsNc,10815
-sourcecode/validation_surface.py,sha256=A7h0Z9xHjPrxUPkyoPKlhGb8tCF0w0PI_XT-tOj5sC4,21375
+sourcecode/validation_inference.py,sha256=cQaEJxCBDRWcD0On6PapoGb4qOTEPPlJ1eD4raFHWp0,14099
+sourcecode/validation_surface.py,sha256=A0-FVswL__XOcw92wvIwghwLq5AWtIm2kzO3RjEb1b4,27325
 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
@@ -138,8 +138,8 @@ sourcecode/telemetry/consent.py,sha256=LIAO9ohJZF8OuZwM4u1VWtALlYfTCCKq4wV3Vwc7i
 sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
 sourcecode/telemetry/filters.py,sha256=NHa5T-6DaZduQPFuC34jOqHWQgSizM-Ygq8aZ4j19ng,5834
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-2.5.17.dist-info/METADATA,sha256=Pp6k3FfuZdHiohzyuajk3p9MPq7gTCOecNy-m3iBI98,10852
-sourcecode-2.5.17.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-2.5.17.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-2.5.17.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-2.5.17.dist-info/RECORD,,
+sourcecode-2.5.19.dist-info/METADATA,sha256=m52i-fTO7exXgHCc5tUJyv2ne4dBOOAtKThagdx4dSo,10852
+sourcecode-2.5.19.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-2.5.19.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-2.5.19.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-2.5.19.dist-info/RECORD,,