sourcecode 2.5.17__tar.gz → 2.5.18__tar.gz

{sourcecode-2.5.17 → sourcecode-2.5.18}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [2.5.18] — 2026-07-20
+
+**Engineering Decision Support — Part A, F1: standalone OpenAPI specs now reach the
+validation surface.** First correctness-foundation fix of the capability milestone
+(`docs/DEVELOPMENT-ROADMAP.md`): trust-critical, stability-permitted (consumer-wiring
+over an existing producer, no new inference). A repo shipping a plain `openapi.yml`
+with no openapi-generator interface-controller was reported "No OpenAPI spec found" —
+a confirmed false negative that would launder into any downstream decision. Full suite
+(3538 passed, 5 skipped) confirms confinement.
+
+### Fixed
+
+- **F1 — standalone-spec discovery reaches the validation surface.** `extract_java_endpoints`
+  only links a spec when an `@RestController implements XxxApi` interface-controller
+  matches it; a repo with a plain `openapi.yml` and no such controller fell through to
+  "No OpenAPI spec found". The validation surface now consults the existing
+  `openapi_surface.build_openapi_surface` producer directly in that branch: a discovered
+  spec's body operations (POST/PUT/PATCH) contribute their declared constraints as
+  `source="openapi-spec"` routes (deduped against source-annotated routes by
+  method+path), the `openapi_spec` claim flips from `null` to the spec path, and the
+  note explains the standalone discovery. Genuinely absent specs are unchanged — the
+  `null` claim and source-DTO recovery path stand. New `TestStandaloneSpecRecovery`
+  regression class (4 tests).
+- **F1 — `zero_result_reason` on genuine absence.** When no spec is on disk and no
+  in-repo DTO constraints are recoverable, the validation surface now carries a
+  machine-readable `zero_result_reason = "no_openapi_spec_and_no_source_dto_constraints"`
+  beside the prose note, so a consumer can distinguish an attested negative ("looked,
+  found nothing") from an un-run analysis. Absent on any positive result.
+
+### Notes
+
+- **Reconciliation rule deliberately NOT added for F1.** The roadmap's F1 strategy
+  suggested a "spec-present vs spec-absent" reconciliation rule as the honesty guard.
+  The flip was instead achieved at the true source (the validation surface now reads
+  the spec), and the two sibling surfaces that also report spec presence
+  (`serializer` arch_reasons, `confidence_analyzer` api_contract gap) were verified to
+  already detect a standalone `openapi.yml` via their filename check — so **no surface
+  makes the false "no spec" claim**, leaving the reconciliation layer no provable
+  contradiction to fire on. Adding a rule that never fires on any real repo violates
+  the layer's own contract (fire only on contradiction, EPV). Recorded here so the
+  roadmap item is closed by decision, not oversight.
+
 ## [2.5.17] — 2026-07-19
 
 **Semantic Stability cleanup: dead code removed and a scanner fork collapsed, with

{sourcecode-2.5.17 → sourcecode-2.5.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.17
+Version: 2.5.18
 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 → sourcecode-2.5.18}/pyproject.toml

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

{sourcecode-2.5.17 → sourcecode-2.5.18}/src/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.18"

{sourcecode-2.5.17 → sourcecode-2.5.18}/src/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 "