sourcecode 5.5.2__tar.gz → 5.5.4__tar.gz

{sourcecode-5.5.2 → sourcecode-5.5.4}/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [5.5.4] — 2026-08-13
+
+**Re-audit performance and HTTP contract corrections.**
+
+### Fixed
+- Consolidated repeated XML and configuration traversals in `endpoints`; servlet
+  discovery now uses a pruned walk or the inventories already computed by the
+  endpoint analysis.
+- Parsed braced Spring `RequestMethod` declarations and expose complete
+  `methods` lists while retaining the backwards-compatible primary `method`.
+- Verified that atomic `--output` replacement produced the requested destination
+  before recording the run as successful.
+
+### Documentation
+- Documented `ANY` semantics and synchronized the defect ledger, roadmap, and
+  atomic audit-fix commits. The reported CLI alias discrepancy was not
+  reproducible against the public command signatures.
+
+## [5.5.3] — 2026-08-13
+
+**Audit regression fixes and diagnostic output.**
+
+### Fixed
+- Restored bounded default `spring-audit` stdout while preserving complete
+  reports through `--output`.
+- Added depth, provenance, unit declarations, and hub-excluded reach to
+  `impact` for service-locator architectures.
+- Hardened `web.xml` mapping extraction for legacy descriptors and consecutive
+  mappings, without activating commented mappings.
+- Published root timing metadata and reused content-addressed manifest analysis.
+- Made excluded test-source route counts explicit in endpoint output.
+
+### Documentation
+- Updated the roadmap with the 5.5.2 audit follow-up, deduplicated against
+  previous defect entries and linked to atomic fix commits.
+
 ## [5.5.2] — 2026-08-13
 
 **Follow-up audit corrections and performance visibility.**

{sourcecode-5.5.2 → sourcecode-5.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.5.2
+Version: 5.5.4
 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.5.2-blue)
+![Version](https://img.shields.io/badge/version-5.5.4-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.5.2 — and, on a build that has aged,
+ask version                    # ask 5.5.4 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.5.2 → sourcecode-5.5.4}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.5.2-blue)
+![Version](https://img.shields.io/badge/version-5.5.4-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.5.2 — and, on a build that has aged,
+ask version                    # ask 5.5.4 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.5.2 → sourcecode-5.5.4}/docs/DEFECT-LEDGER.md

@@ -16,6 +16,17 @@ The facts these rows are keyed to are published: `ask schema facts-v1` prints th
 
 ---
 
+## Audit synchronization
+
+| ID | Defect | Found | Severity | Status |
+|---|---|---|---|---|
+| AS-01 | `risk`/`enrich` could omit `sql_taint.bounded_interpolations`, making `sinks_total` impossible to audit against its bounded evidence. | 5.4.2 re-audit | Medium | **closed 5.4.2** — both projections preserve the bounded rows; the paired fixture asserts the sink total and the retained bounded interpolation. |
+| AS-02 | Route projection emitted declarations from abstract Spring controllers, creating phantom routes and inflating the unprotected census. | 5.4.2 re-audit | Low | **closed 5.4.2** — abstract declarers are excluded while concrete subtype projection remains admitted; the route-surface regression covers both sides. |
+| AS-03 | The distributed ledger could leave `C3-123` open after the 5.4.1 build already excluded static assets. | 5.4.2 re-audit | Informational | **closed 5.4.2** — the stale state was synchronized to the wheel it documents. |
+| AS-04 | An unconstrained `@RequestMapping` was described by consumers as GET although Spring admits every verb. | 5.5.1 audit | Medium | **closed 5.5.1** — primary `method` is `ANY`; 5.5.4 adds the concrete `methods` list so consumers do not need to infer its expansion. |
+
+---
+
 ## Class C1 — One fact, two authorities
 
 | ID | Defect | Found | Severity | Status |

{sourcecode-5.5.2 → sourcecode-5.5.4}/docs/USER_GUIDE.md

@@ -136,7 +136,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.5.2
+# ask 5.5.4
 ```
 
 Requires Python 3.9+.
@@ -261,7 +261,13 @@ ask endpoints /path/to/repo
 ask endpoints . --format yaml
 ```
 
-Output: list of `{method, path, controller, handler}`. Covers `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`, `@RequestMapping`, `@GET`, `@POST`, `@PUT`, `@DELETE`, `@PATCH` + `@Path`.
+Output: list of `{method, methods, path, controller, handler}`. `method` remains
+the backwards-compatible primary verb; `methods` is the complete declared set.
+An unconstrained `@RequestMapping` reports `method: "ANY"` and
+`methods: ["GET", "POST", "PUT", "DELETE", "PATCH"]`, because it accepts all
+of those verbs rather than defaulting to GET. Covers `@GetMapping`, `@PostMapping`,
+`@PutMapping`, `@DeleteMapping`, `@PatchMapping`, `@RequestMapping`, `@GET`,
+`@POST`, `@PUT`, `@DELETE`, `@PATCH` + `@Path`.
 
 Each endpoint carries a `security` policy. Standard annotations (`@PreAuthorize`, `@Secured`, `@RolesAllowed`, …) are recognized automatically; a custom authorization annotation reports `policy: "none_detected"` until declared in a `sourcecode.config.json` at the repo root:
 

{sourcecode-5.5.2 → sourcecode-5.5.4}/pyproject.toml

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

{sourcecode-5.5.2 → sourcecode-5.5.4}/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.5.2"
+__version__ = "5.5.4"

{sourcecode-5.5.2 → sourcecode-5.5.4}/src/sourcecode/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import contextlib
+import errno
 import hashlib
 import json
 import difflib
@@ -1196,6 +1197,15 @@ def _safe_write_file(path: "Path", content: str) -> None:
             fh.flush()
             os.fsync(fh.fileno())
         tmp.replace(path)
+        # Atomic replacement alone does not prove that the destination is the
+        # requested artifact. Verify the postcondition before reporting a run
+        # output path, especially for non-empty JSON reports.
+        if not path.is_file() or (content and path.stat().st_size == 0):
+            raise OSError(
+                errno.EIO,
+                "atomic output replacement did not produce the requested file",
+                str(path),
+            )
         try:
             dir_fd = os.open(str(path.parent), os.O_RDONLY)
             try:
@@ -9239,7 +9249,17 @@ def spring_audit_cmd(
     elif format == "github-comment":
         output = _render_spring_audit_github_comment(combined, min_severity)
     else:
-        data = combined.to_compact_dict() if compact else combined.to_dict()
+        _bounded_default = (
+            not compact and output_path is None and format == "json" and not table
+        )
+        data = (
+            combined.to_compact_dict()
+            if compact or _bounded_default
+            else combined.to_dict()
+        )
+        if _bounded_default:
+            data.pop("mode", None)
+            data["default_output"] = "bounded"
         output = _serialize_dict(data, format)
 
     # F-AV: our own readers ask for the count under either spelling — the break

{sourcecode-5.5.2 → sourcecode-5.5.4}/src/sourcecode/deployment_prefix.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Iterable, Optional
 
 # Published Spring Boot property keys (DATA — never a predicate on a repo name).
 _CONTEXT_PATH_KEYS: tuple[str, ...] = (
@@ -163,25 +163,31 @@ def _profile_of_document(flat: "dict[str, str]", file_profile: Optional[str]) ->
     return file_profile
 
 
-def _config_files(root: Path) -> "list[Path]":
+def _config_files(root: Path, files: Optional[Iterable[Path]] = None) -> "list[Path]":
     """Spring config files under conventional resource directories.
 
     Bounded and sorted for determinism; test resources are excluded because a
     prefix declared for tests is not the deployed one.
     """
+    candidates = files if files is not None else root.rglob("application*.*")
     found: list[Path] = []
-    for pattern in ("**/src/main/resources/**/application*.*", "**/config/application*.*"):
-        for path in root.glob(pattern):
-            name = path.name
-            if name in _CONFIG_BASENAMES or _PROFILE_FILE_RE.match(name):
-                text = str(path).replace("\\", "/")
-                if "/src/test/" in text or "/target/" in text:
-                    continue
-                found.append(path)
+    for path in candidates:
+        path = Path(path)
+        name = path.name
+        if name not in _CONFIG_BASENAMES and not _PROFILE_FILE_RE.match(name):
+            continue
+        text = str(path).replace("\\", "/")
+        in_resources = "/src/main/resources/" in text
+        in_config = "/config/" in text
+        if not (in_resources or in_config) or "/src/test/" in text or "/target/" in text:
+            continue
+        found.append(path)
     return sorted(set(found))[:60]
 
 
-def detect_deployment_prefix(root: Path) -> DeploymentPrefix:
+def detect_deployment_prefix(
+    root: Path, *, files: Optional[Iterable[Path]] = None
+) -> DeploymentPrefix:
     """Read the deployment prefix from the repo's Spring configuration.
 
     Best effort and never raises: an unreadable or malformed config yields an
@@ -190,7 +196,7 @@ def detect_deployment_prefix(root: Path) -> DeploymentPrefix:
     """
     result = DeploymentPrefix()
     try:
-        candidates = _config_files(Path(root))
+        candidates = _config_files(Path(root), files)
     except Exception:
         return result
 

{sourcecode-5.5.2 → sourcecode-5.5.4}/src/sourcecode/repository_ir.py

@@ -3772,17 +3772,40 @@ def _route_path_expression(args_str: str, constants: "Optional[dict[str, str]]")
     return args_str.strip()
 
 
-def _parse_route_http_method(ann_name: str, args_str: str) -> str:
-    """Derive HTTP method from annotation name or explicit method= arg."""
+_ANY_HTTP_METHODS = ("GET", "POST", "PUT", "DELETE", "PATCH")
+
+
+def _parse_route_http_methods(ann_name: str, args_str: str) -> tuple[str, ...]:
+    """Derive every declared HTTP method, preserving annotation order."""
     explicit = _HTTP_METHOD_MAP.get(ann_name)
     if explicit:
-        return explicit
-    m = re.search(r'method\s*=\s*(?:RequestMethod\.)?(\w+)', args_str or "")
+        return (explicit,)
+    # Spring accepts both `method=RequestMethod.GET` and the array spelling
+    # `method={RequestMethod.GET, RequestMethod.POST}`. The old expression
+    # expected the token immediately after `=`, so the braces form fell through
+    # to ANY and overstated the reachable verb surface.
+    m = re.search(
+        r'\bmethod\s*=\s*\{?\s*((?:RequestMethod\.)?\w+(?:\s*,\s*(?:RequestMethod\.)?\w+)*)',
+        args_str or "",
+    )
     if m:
-        return m.group(1).upper()
+        methods = re.findall(r'(?:RequestMethod\.)?(\w+)', m.group(1))
+        if methods:
+            return tuple(dict.fromkeys(method.upper() for method in methods))
     if ann_name == "@RequestMapping":
-        return "ANY"
-    return ""
+        return ("ANY",)
+    return ()
+
+
+def _parse_route_http_method(ann_name: str, args_str: str) -> str:
+    """Backward-compatible primary HTTP method for a route."""
+    methods = _parse_route_http_methods(ann_name, args_str)
+    return methods[0] if methods else ""
+
+
+def _published_http_methods(method: str) -> list[str]:
+    """Concrete verbs a consumer must consider for a route's method label."""
+    return list(_ANY_HTTP_METHODS if method == "ANY" else (method,))
 
 
 def _parse_route_extras(args_str: str) -> dict:
@@ -5014,7 +5037,8 @@ def _build_route_surface(
             _suffix_expr = _route_path_expression(args, constants)
             effective_prefixes = class_info.get(cls_simple, {}).get("prefixes", [""])
 
-        method = _parse_route_http_method(ann_name, args) or "GET"
+        route_methods = _parse_route_http_methods(ann_name, args) or ("GET",)
+        method = route_methods[0]
 
         if cls_simple in class_info:
             class_info[cls_simple]["own_endpoints"].append(
@@ -5070,6 +5094,7 @@ def _build_route_surface(
                     "effective_class": cls_fqn,
                     "path": full_path,
                     "method": method,
+                    "methods": _published_http_methods(method) if method == "ANY" else list(route_methods),
                     "return_type": (sym.return_type.strip() if sym.return_type else "void"),
                     "stable_id": sym.stable_id,
                     "inheritance_depth": 0,
@@ -5175,6 +5200,7 @@ def _build_route_surface(
                                     "effective_class": data["fqn"],
                                     "path": full_path,
                                     "method": verb,
+                                    "methods": _published_http_methods(verb),
                                     "return_type": _parent_rt_by_sym.get(declaring_sym, "void"),
                                     "stable_id": stable_id,
                                     "inheritance_depth": depth,
@@ -6415,6 +6441,27 @@ def extract_java_endpoints(
         and "target/" not in str(p).replace("\\", "/")
         and not any(f in str(p).replace("\\", "/") for f in _CLIENT_PATH_FRAGMENTS)
     )
+    # `endpoints` needs XML both for Spring Security and WebScript detection.
+    # One inventory avoids seven name-specific walks plus a later desc.xml walk.
+    _xml_files = sorted(root.rglob("*.xml"))
+    # Deployment-prefix resolution formerly ran two independent `root.glob()`
+    # calls. One candidate list keeps that work bounded and reusable below.
+    _config_files = sorted(root.rglob("application*.*"))
+    _excluded_test_source_routes = 0
+    if not include_tests:
+        _route_marker = _re.compile(
+            r"@(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|RequestMapping|GET|POST|PUT|DELETE|PATCH|Path)\b"
+        )
+        for _candidate in root.rglob("*.java"):
+            _candidate_rel = _rel(_candidate)
+            if not is_test_source_file(_candidate_rel):
+                continue
+            try:
+                _excluded_test_source_routes += len(
+                    _route_marker.findall(_candidate.read_text(encoding="utf-8", errors="replace"))
+                )
+            except OSError:
+                continue
 
     all_symbols: list[SymbolRecord] = []
     extends_map: dict[str, str] = {}
@@ -6620,6 +6667,7 @@ def extract_java_endpoints(
 
         entry: dict = {
             "method": route["method"],
+            "methods": route.get("methods", _published_http_methods(route["method"])),
             "path": route["path"],
             "controller": controller,
             # Two controllers can share a simple name across packages: keycloak
@@ -6776,23 +6824,23 @@ def extract_java_endpoints(
         re.IGNORECASE,
     )
     _xml_security_detected = False
-    _XML_GLOBS = (
-        "*security*.xml", "*Security*.xml",
-        "*applicationContext*.xml", "*-context.xml", "*Context.xml",
-        "*spring*.xml", "*Spring*.xml",
-    )
-    for _glob in _XML_GLOBS:
-        for _xf in root.rglob(_glob):
-            if "target/" in str(_xf).replace("\\", "/"):
-                continue
-            try:
-                _xt = _xf.read_text(encoding="utf-8", errors="replace")
-            except OSError:
-                continue
-            if _XML_SECURITY_RE.search(_xt):
-                _xml_security_detected = True
-                break
-        if _xml_security_detected:
+    for _xf in _xml_files:
+        _xml_name = _xf.name.lower()
+        if not (
+            "security" in _xml_name
+            or "spring" in _xml_name
+            or _xml_name.endswith("-context.xml")
+            or _xml_name.endswith("context.xml")
+        ):
+            continue
+        if "target/" in str(_xf).replace("\\", "/"):
+            continue
+        try:
+            _xt = _xf.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if _XML_SECURITY_RE.search(_xt):
+            _xml_security_detected = True
             break
 
     if _xml_security_detected:
@@ -6892,7 +6940,7 @@ def extract_java_endpoints(
     try:
         from sourcecode.deployment_prefix import detect_deployment_prefix
 
-        _prefix = detect_deployment_prefix(root)
+        _prefix = detect_deployment_prefix(root, files=_config_files)
         if _prefix.sources:
             result["deployment_prefix"] = _prefix.to_dict()
         if _prefix.prefix:
@@ -6912,6 +6960,12 @@ def extract_java_endpoints(
         )
     elif _test_util_endpoints:
         result["test_util_included"] = len(_test_util_endpoints)
+    if _excluded_test_source_routes:
+        result["test_source_excluded"] = _excluded_test_source_routes
+        result.setdefault("notes", []).append(
+            f"{_excluded_test_source_routes} route annotation(s) from test source trees "
+            "were excluded; use --include-tests to include them."
+        )
     # Surface incomplete-endpoint warnings (interface-defined controllers) only when
     # present, to keep output backward-compatible for the common case.
     if endpoint_warnings:
@@ -6949,7 +7003,9 @@ def extract_java_endpoints(
     # (*.desc.xml: <url>/<authentication>/<transaction>) in addition to the Java
     # signals gathered above.
     _webscript_descriptors = 0
-    for _df in root.rglob("*.desc.xml"):
+    for _df in _xml_files:
+        if not _df.name.endswith(".desc.xml"):
+            continue
         if "target/" in str(_df).replace("\\", "/"):
             continue
         try:
@@ -6977,7 +7033,7 @@ def extract_java_endpoints(
         from sourcecode.servlet_surface import build_servlet_surface
 
         _nonspring["servlets"] = int(
-            build_servlet_surface(root).get("declarations", 0)
+            build_servlet_surface(root, files=[*java_files, *_xml_files]).get("declarations", 0)
         )
     except Exception:
         pass
@@ -7853,6 +7909,10 @@ def compute_blast_radius(
     _indirect_summary = (
         _indirect_ordered if _indirect_cap is None else _indirect_ordered[:_indirect_cap]
     )
+    _indirect_by_depth: dict[str, int] = {}
+    for _node in indirect_callers:
+        _depth_key = str(all_affected.get(_node, 0))
+        _indirect_by_depth[_depth_key] = _indirect_by_depth.get(_depth_key, 0) + 1
     def _via_hub(_node: str) -> bool:
         _seen_path: set[str] = set()
         _cursor = _node
@@ -7914,6 +7974,9 @@ def compute_blast_radius(
         ),
         "indirect_callers": _indirect_summary,
         "indirect_caller_details": _indirect_details,
+        "indirect_callers_unit": "reference symbols (methods or classes)",
+        "indirect_callers_by_depth": _indirect_by_depth,
+        "indirect_callers_without_hubs": _without_hubs,
         "container_wired": [w.to_dict() for w in _container_wired],
         "endpoints_affected": endpoints_affected,
         "mappers_affected": mappers_affected,

{sourcecode-5.5.2 → sourcecode-5.5.4}/src/sourcecode/servlet_surface.py

@@ -20,10 +20,11 @@ So the answer is a second, named population beside the first, with its own total
 
 from __future__ import annotations
 
+import os
 import re
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
+from typing import Iterable, Optional
 from xml.etree import ElementTree as ET
 
 POPULATION = "servlet"
@@ -84,7 +85,8 @@ def _child_text(elem: "ET.Element", name: str) -> str:
 
 def _from_web_xml(xml_path: Path, relative: str) -> "list[ServletMapping]":
     try:
-        root = ET.parse(str(xml_path)).getroot()
+        text = xml_path.read_text(encoding="utf-8", errors="replace")
+        root = ET.fromstring(text)
     except Exception:
         return []
     classes: "dict[str, str]" = {}
@@ -110,6 +112,27 @@ def _from_web_xml(xml_path: Path, relative: str) -> "list[ServletMapping]":
                 source_file=relative,
                 source="web.xml",
             ))
+    # Keep a tolerant lexical fallback for descriptors containing legacy XML
+    # constructs that ElementTree rejects or partially normalizes. Comments are
+    # removed first so commented deployment examples never become live routes.
+    try:
+        active = re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+        for block in re.findall(r"<servlet-mapping\b[^>]*>(.*?)</servlet-mapping>", active, re.DOTALL | re.IGNORECASE):
+            name_match = re.search(r"<servlet-name\b[^>]*>\s*([^<]+?)\s*</servlet-name>", block, re.DOTALL | re.IGNORECASE)
+            pattern_match = re.search(r"<url-pattern\b[^>]*>\s*([^<]+?)\s*</url-pattern>", block, re.DOTALL | re.IGNORECASE)
+            if not pattern_match:
+                continue
+            candidate = ServletMapping(
+                url_pattern=pattern_match.group(1).strip(),
+                servlet_name=name_match.group(1).strip() if name_match else "",
+                servlet_class=classes.get(name_match.group(1).strip(), "") if name_match else "",
+                source_file=relative,
+                source="web.xml",
+            )
+            if candidate not in out:
+                out.append(candidate)
+    except Exception:
+        pass
     return out
 
 
@@ -144,14 +167,36 @@ def _from_registration_beans(java_path: Path, relative: str) -> "list[ServletMap
     return out
 
 
-def build_servlet_surface(root: Path, *, limit: Optional[int] = None) -> dict:
+def build_servlet_surface(
+    root: Path,
+    *,
+    limit: Optional[int] = None,
+    files: Optional[Iterable[Path]] = None,
+) -> dict:
     """Every servlet-mapped URL pattern under `root`, as a population of its own."""
     from sourcecode import non_coverage
 
     root = Path(root)
     mappings: "list[ServletMapping]" = []
-    for path in sorted(root.rglob("*")):
-        if any(part in _SKIP_DIRS for part in path.parts) or not path.is_file():
+    if files is None:
+        candidates: list[Path] = []
+        for directory, dirs, names in os.walk(root):
+            dirs[:] = sorted(name for name in dirs if name not in _SKIP_DIRS)
+            candidates.extend(
+                Path(directory) / name
+                for name in sorted(names)
+                if name == "web.xml" or name.endswith(".java")
+            )
+    else:
+        candidates = sorted(
+            {
+                Path(path)
+                for path in files
+                if Path(path).name == "web.xml" or Path(path).suffix == ".java"
+            }
+        )
+    for path in candidates:
+        if not path.is_file():
             continue
         try:
             # POSIX, like every other path this CLI publishes. C2-18 fixed this