sourcecode 5.4.2__tar.gz → 5.5.0__tar.gz

{sourcecode-5.4.2 → sourcecode-5.5.0}/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [5.5.0] — 2026-08-12
+
+**Audit backlog resolved and performance signals made explicit.**
+This release folds in the latest external audit queue: programmatic Spring
+validation now contributes to `validation` gaps and confidence, servlet and
+endpoint publishing preserve extension mappings and `ANY` methods, reference
+classification distinguishes class literals from config wires, and the cache
+model now warns about large repositories against the correct scale. The roadmap
+also records the audit backlog, including the command-execution timing
+regression called out in the report.
+
+### Fixed
+- **Programmatic validation is now surfaced.** `Validator` and `@InitBinder`
+  evidence now affect `validation` gaps and overall confidence, and the payload
+  carries the non-coverage note for that limit.
+- **Servlet extension mappings stay visible.** Patterns such as `*.ftl` and
+  `*.vm` are preserved in the servlet surface instead of being dropped.
+- **Methodless request mappings publish as `ANY`.** `@RequestMapping` without a
+  declared method is no longer narrowed to `GET`.
+- **Class literals count as references.** `Foo.class` hits now promote the
+  type to `referenced` instead of `unknown_framework_dispatch`.
+- **Large-repository cache advice compares against the right scale.** The size
+  warning now tells the operator when the repository exceeds the measured
+  reference population.
+
+### Documentation
+- Added the external 2026-08-12 audit queue and its performance backlog to the
+  roadmap.
+
 ## [5.4.2] — 2026-08-12
 
 **External audit fixes and roadmap alignment.**

{sourcecode-5.4.2 → sourcecode-5.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.4.2
+Version: 5.5.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
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.4.2-blue)
+![Version](https://img.shields.io/badge/version-5.5.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.4.2 — and, on a build that has aged,
+ask version                    # ask 5.5.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.4.2 → sourcecode-5.5.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.4.2-blue)
+![Version](https://img.shields.io/badge/version-5.5.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.4.2 — and, on a build that has aged,
+ask version                    # ask 5.5.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.4.2 → sourcecode-5.5.0}/docs/USER_GUIDE.md

@@ -136,7 +136,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.4.2
+# ask 5.5.0
 ```
 
 Requires Python 3.9+.

{sourcecode-5.4.2 → sourcecode-5.5.0}/pyproject.toml

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

{sourcecode-5.4.2 → sourcecode-5.5.0}/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__ = "5.4.2"
+__version__ = "5.5.0"

{sourcecode-5.4.2 → sourcecode-5.5.0}/src/sourcecode/cache_model.py

@@ -492,6 +492,7 @@ class Conditioning:
     scope: str                              # "3 342 Java files, cache cold"
     transfers: "Optional[bool]"             # do the reference figures apply here?
     per_command: "dict[str, str]"           # command → how it can be run here
+    java_files: "Optional[int]" = None      # measured scope size, if available
 
     def statement(self) -> str:
         """One sentence about whether the figures below transfer to this scope."""
@@ -500,6 +501,14 @@ class Conditioning:
                 f"This repository ({self.scope}) was not measured, so nothing below "
                 f"is claimed about it: the figures are the reference repository's."
             )
+        if self.java_files is not None and self.java_files > REFERENCE_JAVA_FILES:
+            return (
+                f"This repository ({self.scope}) is larger than the repository the "
+                f"figures below were measured on ({REFERENCE_JAVA_FILES} Java files), "
+                f"and what cost tracks here is the build rather than the file count: "
+                f"{FIELD_ANCHOR}. Read each figure as the reference's, not as yours; "
+                f"the `here:` lines say how each command can be run on this one."
+            )
         if self.transfers:
             return (
                 f"This repository ({self.scope}) is within the size the figures "

{sourcecode-5.4.2 → sourcecode-5.5.0}/src/sourcecode/cli.py

@@ -27,6 +27,7 @@ from sourcecode.phased_run import PhasedRun
 from sourcecode.partial_contract import PARTIAL_EXIT_CODE as _PARTIAL_EXIT
 from sourcecode.partial_contract import read_count as _read_count
 from sourcecode import perf
+from sourcecode.non_coverage import block as _non_coverage_block
 from sourcecode.caller_metrics import (
     CALLER_METRIC_RECONCILIATION,
     CYCLE_METRIC_RECONCILIATION,
@@ -7287,6 +7288,23 @@ def validation_cmd(
     except Exception:
         pass
 
+    if data.get("programmatic_validation", {}).get("detected"):
+        data.setdefault("non_coverage", _non_coverage_block("validation"))
+        _vc = data.get("validation_confidence")
+        if isinstance(_vc, dict):
+            _vc["overall"] = "Likely"
+            _vc["claim"] = (
+                "Declared constraints are present, but programmatic Spring "
+                "Validator wiring was detected outside this surface's model"
+            )
+            limits = _vc.setdefault("known_precision_limits", [])
+            note = (
+                "Programmatic Spring Validator / @InitBinder wiring is outside the "
+                "declared-constraint surface."
+            )
+            if note not in limits:
+                limits.append(note)
+
     if path_prefix:
         data["endpoints"] = [
             e for e in data.get("endpoints", [])
@@ -14387,7 +14405,8 @@ def _cache_model_conditioning(path: Path) -> Any:
                 line += f" ({found.reference})"
             per_command[row.command] = line
         return _cmodel.Conditioning(
-            scope=scope.describe(), transfers=transfers, per_command=per_command
+            scope=scope.describe(), transfers=transfers, per_command=per_command,
+            java_files=scope.java_files,
         )
     except Exception:
         # A cost note is never worth failing a command that answers.

{sourcecode-5.4.2 → sourcecode-5.5.0}/src/sourcecode/non_coverage.py

@@ -321,6 +321,27 @@ NON_COVERAGE: tuple[NonCoverage, ...] = (
             "routes) is a measurement this command does not yet make."
         ),
     ),
+    NonCoverage(
+        id="NC-011",
+        surface="validation",
+        not_covered=(
+            "Programmatic Spring request-body validation wired with "
+            "`org.springframework.validation.Validator` or `@InitBinder`."
+        ),
+        why=(
+            "This surface reads declared bean-validation constraints recovered from "
+            "OpenAPI or DTO annotations. A validator registered in controller code "
+            "can enforce body rules without any declarative constraint on the "
+            "payload, so treating the result as fully verified would overstate what "
+            "the declared-constraint scan proves."
+        ),
+        instead=(
+            "`@InitBinder` / `setValidator(...)` wiring, or a Spring `Validator` "
+            "implementation, which this surface reports only as a coverage "
+            "boundary. `validation` still shows the declared rules; the programmatic "
+            "validator remains outside that model."
+        ),
+    ),
 )
 
 

{sourcecode-5.4.2 → sourcecode-5.5.0}/src/sourcecode/reference_facts.py

@@ -162,7 +162,7 @@ _QUALIFIED_TYPE_RE = re.compile(r"\b[A-Z][A-Za-z0-9_$]*\.[A-Z][A-Za-z0-9_$]*")
 
 def _scan_repository(
     root: Path, simple_names: "set[str]", nested: "dict[str, tuple[str, str]]"
-) -> "tuple[dict[str, str], dict[str, str]]":
+) -> "tuple[dict[str, str], dict[str, str], dict[str, str]]":
     """One walk, two questions — `(config-wired names, nested types other code names)`.
 
     Both scans need the whole tree, and walking it twice doubled the cost of the
@@ -175,6 +175,7 @@ def _scan_repository(
     """
     config_hits: dict[str, str] = {}
     nested_hits: dict[str, str] = {}
+    literal_hits: dict[str, str] = {}
     pending = set(simple_names)
     by_qualified: dict[str, list[str]] = {}
     for fqn, (qualified, _own) in nested.items():
@@ -183,7 +184,7 @@ def _scan_repository(
     scan_config = bool(pending)
     scan_java = bool(by_qualified)
     if not scan_config and not scan_java:
-        return config_hits, nested_hits
+        return config_hits, nested_hits, literal_hits
 
     scanned = 0
     for dirpath, dirnames, filenames in os.walk(root):
@@ -191,7 +192,7 @@ def _scan_repository(
         for filename in filenames:
             is_java = filename.endswith(".java")
             is_config = os.path.splitext(filename)[1].lower() in _CONFIG_REF_EXTS
-            if not ((is_java and scan_java) or (is_config and scan_config)):
+            if not ((is_java and (scan_java or scan_config)) or (is_config and scan_config)):
                 continue
             if scanned >= _SCAN_MAX_FILES:
                 break
@@ -206,6 +207,17 @@ def _scan_repository(
                     pending.discard(hit)
                     config_hits[hit] = rel
                 scan_config = bool(pending)
+            if is_java and scan_config:
+                # A `Foo.class` literal is a real static reference, and the
+                # field audit found one of these on the annotation-dispatch path.
+                class_hits = {
+                    hit for hit in pending
+                    if f"{hit}.class" in text
+                }
+                for hit in class_hits:
+                    pending.discard(hit)
+                    literal_hits[hit] = rel
+                scan_config = bool(pending)
             if is_java and scan_java:
                 for hit in set(_QUALIFIED_TYPE_RE.findall(text)) & set(by_qualified):
                     for fqn in by_qualified[hit]:
@@ -213,10 +225,10 @@ def _scan_repository(
                             nested_hits[fqn] = rel
                 scan_java = len(nested_hits) < len(nested)
             if not scan_config and not scan_java:
-                return config_hits, nested_hits
+                return config_hits, nested_hits, literal_hits
         if scanned >= _SCAN_MAX_FILES:
             break
-    return config_hits, nested_hits
+    return config_hits, nested_hits, literal_hits
 
 
 def analyze_type_references(nodes: "list[dict]", root: Path) -> ReferenceFacts:
@@ -226,7 +238,15 @@ def analyze_type_references(nodes: "list[dict]", root: Path) -> ReferenceFacts:
     examined, because a method with no callers is a different question.
     """
     root = Path(root)
-    types = [n for n in nodes or [] if n.get("type") in ("class", "interface") and n.get("fqn")]
+    def _node_kind(node: dict) -> str:
+        kind = str(node.get("symbol_kind") or node.get("kind") or node.get("type") or "")
+        if kind in ("class", "interface", "enum", "annotation", "record"):
+            return kind
+        if kind == "@interface":
+            return "annotation"
+        return str(node.get("type") or "")
+
+    types = [n for n in nodes or [] if _node_kind(n) in ("class", "interface", "enum", "annotation", "record") and n.get("fqn")]
     if not types:
         return ReferenceFacts(0, {s: 0 for s in STATUSES}, ())
 
@@ -237,7 +257,7 @@ def analyze_type_references(nodes: "list[dict]", root: Path) -> ReferenceFacts:
             entries.append(TypeReference(
                 fqn=str(node["fqn"]), status=REFERENCED,
                 basis="incoming edge in the call-graph",
-                type=str(node.get("type") or ""), role=str(node.get("role") or "other"),
+                type=_node_kind(node), role=str(node.get("role") or "other"),
             ))
         else:
             candidates.append(node)
@@ -271,22 +291,30 @@ def analyze_type_references(nodes: "list[dict]", root: Path) -> ReferenceFacts:
                 f"{parts[-2]}.{parts[-1]}",
                 str(node.get("source_file") or "").replace("\\", "/"),
             )
-    config_hits, nested_hits = _scan_repository(root, set(by_simple), nested_candidates)
+    config_hits, nested_hits, literal_hits = _scan_repository(root, set(by_simple), nested_candidates)
+    literal_refs: dict[str, str] = {}
     for simple, config_file in config_hits.items():
         for node in by_simple.get(simple, []):
             dispatch_basis[str(node["fqn"])] = f"named in {config_file}"
+    for simple, literal_file in literal_hits.items():
+        for node in by_simple.get(simple, []):
+            literal_refs[str(node["fqn"])] = literal_file
 
     for node in candidates:
         fqn = str(node["fqn"])
         common = {
             "fqn": fqn,
-            "type": str(node.get("type") or ""),
+            "type": _node_kind(node),
             "role": str(node.get("role") or "other"),
         }
-        if fqn in nested_hits:
+        if fqn in nested_hits or fqn in literal_refs:
             entries.append(TypeReference(
                 status=REFERENCED,
-                basis=f"named as a qualified nested type in {nested_hits[fqn]}",
+                basis=(
+                    f"named as a qualified nested type in {nested_hits[fqn]}"
+                    if fqn in nested_hits
+                    else f"referenced by a class literal in {literal_refs[fqn]}"
+                ),
                 **common,
             ))
         elif fqn in dispatch_basis:

{sourcecode-5.4.2 → sourcecode-5.5.0}/src/sourcecode/repository_ir.py

@@ -3778,7 +3778,11 @@ def _parse_route_http_method(ann_name: str, args_str: str) -> str:
     if explicit:
         return explicit
     m = re.search(r'method\s*=\s*(?:RequestMethod\.)?(\w+)', args_str or "")
-    return m.group(1).upper() if m else ""
+    if m:
+        return m.group(1).upper()
+    if ann_name == "@RequestMapping":
+        return "ANY"
+    return ""
 
 
 def _parse_route_extras(args_str: str) -> dict:

{sourcecode-5.4.2 → sourcecode-5.5.0}/src/sourcecode/validation_surface.py

@@ -34,6 +34,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Optional
 
 from sourcecode.path_filters import is_test_path
+from sourcecode.non_coverage import block as non_coverage_block
 
 if TYPE_CHECKING:
     from sourcecode.context_graph import ContextGraph
@@ -471,6 +472,47 @@ def _is_body_endpoint(ep: "dict[str, Any]") -> bool:
     return method in ("POST", "PUT", "PATCH")
 
 
+def _programmatic_validation_signals(graph: "ContextGraph") -> "list[str]":
+    """Presence-only evidence for Spring Validator / InitBinder wiring.
+
+    The validation surface does not model these flows, but the command still
+    needs to say when a repo is using them so the declared-constraint summary is
+    not read as a full proof."""
+    evidence: list[str] = []
+
+    for t in graph.types():
+        if _is_excluded(t.source_file):
+            continue
+        sig = (t.signature or "")
+        if "org.springframework.validation.Validator" not in sig:
+            continue
+        if "ConstraintValidator" in sig:
+            continue
+        evidence.append(f"{t.fqn} implements org.springframework.validation.Validator")
+
+    for m in graph.symbols(kind="method"):
+        if _is_excluded(m.source_file):
+            continue
+        if m.has_annotation("InitBinder"):
+            evidence.append(f"{m.fqn} is annotated with @InitBinder")
+
+    if evidence:
+        return sorted(dict.fromkeys(evidence))
+
+    try:
+        for edge in graph.cir.call_graph:
+            target = str(edge.get("to") or edge.get("to_symbol") or "")
+            if target.endswith("setValidator"):
+                source = str(edge.get("from") or edge.get("from_symbol") or "")
+                if source:
+                    evidence.append(f"{source} calls {target}")
+                    break
+    except Exception:
+        pass
+
+    return sorted(dict.fromkeys(evidence))
+
+
 def build_validation_surface(
     root: Path,
     endpoints_data: "Optional[dict[str, Any]]" = None,
@@ -494,6 +536,7 @@ def build_validation_surface(
         graph = _build_graph(root)
 
     catalog = discover_custom_validators(root, graph)
+    programmatic_evidence = _programmatic_validation_signals(graph)
 
     out_endpoints: "list[dict[str, Any]]" = []
     gaps: "list[dict[str, Any]]" = []
@@ -579,6 +622,11 @@ def build_validation_surface(
             "gaps": len(gaps),
         },
     }
+    if programmatic_evidence:
+        result["programmatic_validation"] = {
+            "detected": True,
+            "evidence": programmatic_evidence,
+        }
     spec_path = endpoints_data.get("openapi_spec")
     if spec_path:
         result["openapi_spec"] = spec_path
@@ -661,7 +709,48 @@ def build_validation_surface(
                 "expected for such repos, not a missing-validation finding."
             )
 
+    if programmatic_evidence:
+        result["non_coverage"] = non_coverage_block("validation")
+        result["note"] = (
+            result.get("note", "")
+            + " Programmatic Spring Validator wiring was detected, which is "
+            "outside the declared-constraint surface this command models."
+        ).strip()
+        if not result.get("gaps"):
+            result["gaps"] = [
+                {
+                    "method": "",
+                    "path": "",
+                    "controller": "",
+                    "reason": "programmatic_validator_wiring_unmodeled",
+                    "basis": "programmatic_validation",
+                    "confidence": "Likely",
+                }
+            ]
+            result["summary"]["gaps"] = 1
+
     _reconcile_with_code_axis(result, graph, root)
+    if programmatic_evidence:
+        result["non_coverage"] = non_coverage_block("validation")
+        note = result.get("note", "")
+        programmatic_note = (
+            " Programmatic Spring Validator wiring was detected, which is "
+            "outside the declared-constraint surface this command models."
+        )
+        if programmatic_note.strip() not in note:
+            result["note"] = (note + programmatic_note).strip()
+        if not result.get("gaps"):
+            result["gaps"] = [
+                {
+                    "method": "",
+                    "path": "",
+                    "controller": "",
+                    "reason": "programmatic_validator_wiring_unmodeled",
+                    "basis": "programmatic_validation",
+                    "confidence": "Likely",
+                }
+            ]
+            result["summary"]["gaps"] = 1
     return result