sourcecode 5.5.0__py3-none-any.whl → 5.5.2__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__ = "5.5.0"
+__version__ = "5.5.2"

sourcecode/_docs/USER_GUIDE.md

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

sourcecode/cli.py

@@ -3125,6 +3125,7 @@ def main(
         raise typer.Exit()
 
     _t0 = time.monotonic()
+    _root_timing: dict[str, float] = {}
     no_tree: bool = False  # set True by --agent; --no-tree flag removed
 
     # Validate new flag choices
@@ -3457,6 +3458,9 @@ def main(
     _core_hash = ""
     _core_flags_str = ""
     _view_flags_str = ""
+    # Reuse the freshness decision for cache metadata; otherwise the root
+    # command repeats a full Git status walk after the analysis completes.
+    _tree_is_dirty: Optional[bool] = None
 
     if not no_cache:
         try:
@@ -3506,6 +3510,8 @@ def main(
                 Path(_git_root_str) if _git_root_str else target,
                 scope=target,
             )
+            if _tree_sig and _git_sha:
+                _tree_is_dirty = _tree_sig != _git_sha
             if _tree_sig:
                 _core_key = f"{_tree_sig}-{_core_h}"
             else:
@@ -3821,7 +3827,11 @@ def main(
             if format == "json":
                 try:
                     from sourcecode.ris import _has_uncommitted_changes as _huc
-                    _uncommitted = _huc(target)
+                    _uncommitted = (
+                        _tree_is_dirty
+                        if _tree_is_dirty is not None
+                        else _huc(target)
+                    )
                 except Exception:
                     _uncommitted = False
                 _data_scope = "COMPACT" if compact else ("AGENT" if agent else "FULL")
@@ -3938,6 +3948,7 @@ def main(
         if _advisory:
             typer.echo(_advisory, err=True)
 
+    _manifest_t0 = time.perf_counter()
     _perf_detection = perf.start()
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
@@ -3998,6 +4009,7 @@ def main(
         root_dependencies, root_summary = dependency_analyzer.analyze(target)
         dependency_records.extend(root_dependencies)
         dependency_summaries.append(root_summary)
+    _root_timing["manifests_ms"] = round((time.perf_counter() - _manifest_t0) * 1000, 2)
     module_graphs = []
     if graph_analyzer is not None:
         root_graph_tree = (
@@ -4643,6 +4655,13 @@ def main(
                 )
 
     perf.stop("analysis", _perf_analysis)
+    # Root timings are deliberately a small diagnostic envelope. They make cold
+    # manifest cost visible even when the optional perf recorder is disabled.
+    _root_timing.setdefault("context_ms", round((time.monotonic() - _t0) * 1000, 2))
+    _root_timing.setdefault("parse_ms", 0.0)
+    _root_timing.setdefault("cir_ms", 0.0)
+    _root_timing.setdefault("ris_ms", 0.0)
+    _root_timing.setdefault("snapshot_ms", 0.0)
     # 4. Serialize
     _progress.update("serializing output")
     _perf_serialize = perf.start()
@@ -4688,8 +4707,16 @@ def main(
         raw_dict = standard_view(sm, include_tree=tree and not no_tree)
         if not no_redact:
             raw_dict = redact_dict(raw_dict)
+        data = raw_dict
         content = _serialize_dict(raw_dict, format)
 
+    if isinstance(data, dict):
+        data.setdefault("_meta", {})["timing_ms"] = {
+            **_root_timing,
+            "total_ms": round((time.monotonic() - _t0) * 1000, 2),
+        }
+        content = _serialize_dict(data, format)
+
     perf.stop("serialize", _perf_serialize)
     perf.flush_recorder()
 
@@ -4717,7 +4744,11 @@ def main(
     if format == "json":
         try:
             from sourcecode.ris import _has_uncommitted_changes as _huc_fresh
-            _uncommitted_fresh = _huc_fresh(target)
+            _uncommitted_fresh = (
+                _tree_is_dirty
+                if _tree_is_dirty is not None
+                else _huc_fresh(target)
+            )
             # _huc_fresh uses --untracked-files=no — it misses repos where all
             # files are untracked (no staged/unstaged changes to tracked files).
             # Promote to True when _allowed_changed_files contains untracked files.
@@ -6503,6 +6534,10 @@ def endpoints_cmd(
              "the endpoint count, and the endpoint total is carried across as one "
              "number rather than 3 500 rows.",
     ),
+    include_tests: bool = typer.Option(
+        False, "--include-tests",
+        help="Include endpoints from test source and test-fixture modules; excluded by default.",
+    ),
     client_usage: bool = typer.Option(
         False, "--client-usage",
         help="Join the routes against the HTTP calls written in the TypeScript/"
@@ -6563,7 +6598,7 @@ def endpoints_cmd(
     _prog = Progress()
     _prog.start("scanning endpoints")
     try:
-        data = _extract_java_endpoints(target)
+        data = _extract_java_endpoints(target, include_tests=include_tests)
     finally:
         _prog.finish()
 
@@ -8989,9 +9024,26 @@ def spring_audit_cmd(
             # 9,53 s on a 1 303-file repository) and it is the same parse the other
             # knowledge commands share, so it is fetched rather than rebuilt — which
             # is what makes a warm worth anything here (cold == warm before C3-94).
-            cir = _ctxcache.shared_cir(
-                target, file_list, progress=_work_sink(_prog)
+            _repo_root = _ctxcache.repo_root_of(target)
+            cir, _cir_lookup = _ctxcache.get_or_build_cir(
+                _repo_root, target, file_list, progress=_work_sink(_prog)
             )
+            _cache_state = {
+                "context": "warm" if _cir_lookup.hit else "cold",
+                "parse": "warm" if _cir_lookup.hit else "cold",
+            }
+            try:
+                from sourcecode import cache as _cache_state_mod
+                _cache_status = _cache_state_mod.status(target)
+                _cache_state["snapshot"] = (
+                    "warm" if _cache_status.get("cached_cores") else "cold"
+                )
+                _cache_state["ris"] = (
+                    "warm" if _cache_status.get("ris_exists") else "cold"
+                )
+            except Exception:
+                _cache_state["snapshot"] = "unknown"
+                _cache_state["ris"] = "unknown"
             # C3-85: the stretch between the last `linking` tick and the first rule
             # tick reports nothing, and what stays on the line is `n/n` — a counter
             # that finished, reading as a stage still running. Measured on keycloak
@@ -9142,7 +9194,18 @@ def spring_audit_cmd(
                         "phase that never ran is not evidence there is none."
                     )
 
-            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"
+            data.setdefault("metadata", {})["cache_layers"] = _cache_state
             if _stopped_early:
                 # C3-87: the block is composed by `PhasedRun.status`, which is the
                 # authority `risk` is now bound to as well — one vocabulary for
@@ -9176,6 +9239,7 @@ 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()
         output = _serialize_dict(data, format)
 
     # F-AV: our own readers ask for the count under either spelling — the break
@@ -9763,6 +9827,9 @@ def risk_cmd(
             data, rule_filter=rule_filter, band_filter=band_filter, top_n=top_n
         )
     else:
+        if output_path is None:
+            from sourcecode.risk import compact_risk_output
+            data = compact_risk_output(data)
         output = _serialize_dict(data, format)
     _emit_command_output(
         output,

sourcecode/dependency_analyzer.py

@@ -162,6 +162,15 @@ class DependencyAnalyzer:
         *,
         workspace: str | None = None,
     ) -> tuple[list[DependencyRecord], DependencySummary]:
+        from sourcecode import manifest_cache
+
+        cached = manifest_cache.load(root)
+        if cached is not None:
+            records, summary = cached
+            if workspace is not None:
+                records = [replace(record, workspace=workspace) for record in records]
+                summary = replace(summary, dependencies=records)
+            return records, summary
         records: list[DependencyRecord] = []
         limitations: list[str] = []
 
@@ -185,7 +194,12 @@ class DependencyAnalyzer:
             replace(r, role=_infer_role(r.name, r.ecosystem, r.scope))
             for r in deduped
         ]
-        return deduped, self._build_summary(deduped, limitations)
+        summary = self._build_summary(deduped, limitations)
+        manifest_cache.save(root, deduped, summary)
+        if workspace is not None:
+            deduped = [replace(record, workspace=workspace) for record in deduped]
+            summary = replace(summary, dependencies=deduped)
+        return deduped, summary
 
     def merge_summaries(self, summaries: Iterable[DependencySummary]) -> DependencySummary:
         result = DependencySummary(requested=True)

sourcecode/manifest_cache.py

@@ -0,0 +1,62 @@
+"""Content-addressed cache for manifest dependency analysis."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+
+from sourcecode.schema import DependencyRecord, DependencySummary
+
+
+def _base() -> Path:
+    configured = os.environ.get("SOURCECODE_CACHE_DIR", "")
+    return Path(configured) if configured else Path.home() / ".sourcecode" / "cache"
+
+
+def _key(root: Path) -> str:
+    digest = hashlib.sha256()
+    analyzer = Path(__file__).with_name("dependency_analyzer.py")
+    digest.update(analyzer.read_bytes())
+    names = {
+        "pom.xml", "build.gradle", "build.gradle.kts", "package.json",
+        "package-lock.json", "pyproject.toml", "Cargo.toml", "go.mod",
+        "composer.json", "Gemfile",
+    }
+    paths: set[Path] = set()
+    for name in names:
+        paths.update(root.rglob(name))
+    for path in sorted(paths):
+        if not path.is_file():
+            continue
+        try:
+            digest.update(path.relative_to(root).as_posix().encode())
+            digest.update(path.read_bytes())
+        except OSError:
+            continue
+    return digest.hexdigest()
+
+
+def load(root: Path) -> tuple[list[DependencyRecord], DependencySummary] | None:
+    try:
+        path = _base() / "manifest-cache-v1" / f"{_key(root)}.json"
+        data = json.loads(path.read_text(encoding="utf-8"))
+        records = [DependencyRecord(**row) for row in data["records"]]
+        summary = DependencySummary(**data["summary"])
+        summary.dependencies = records
+        return records, summary
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def save(root: Path, records: list[DependencyRecord], summary: DependencySummary) -> None:
+    try:
+        path = _base() / "manifest-cache-v1" / f"{_key(root)}.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"records": [asdict(row) for row in records], "summary": asdict(summary)}
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(payload, sort_keys=True), encoding="utf-8")
+        tmp.replace(path)
+    except OSError:
+        return

sourcecode/migrate_check.py

@@ -2375,6 +2375,26 @@ class MigrationReport:
             compact, "findings", top_n,
             key=lambda f: SEVERITY_ORDER.get(f.get("severity"), 3),
         )
+        # Keep invariant rule prose once; each finding carries only location and
+        # rule identity. Full prose remains available in the non-compact report.
+        _rule_catalog: dict[str, dict] = {}
+        _lean_findings: list[dict] = []
+        for _finding in compact.get("findings", []):
+            _rule_id = _finding.get("rule_id", "unknown")
+            _rule_catalog.setdefault(_rule_id, {
+                "title": _finding.get("title", ""),
+                "explanation": _finding.get("explanation", ""),
+                "fix_hint": _finding.get("fix_hint", ""),
+            })
+            _lean_findings.append({
+                key: _finding[key]
+                for key in (
+                    "id", "rule_id", "severity", "source_file", "first_line",
+                    "migration_target", "imports_found", "code_context",
+                ) if key in _finding
+            })
+        compact["rule_catalog"] = _rule_catalog
+        compact["findings"] = _lean_findings
         hib = full.get("hibernate")
         if isinstance(hib, dict):
             h = dict(hib)

sourcecode/reference_facts.py

@@ -223,6 +223,18 @@ def _scan_repository(
                     for fqn in by_qualified[hit]:
                         if fqn not in nested_hits and nested[fqn][1] != rel:
                             nested_hits[fqn] = rel
+                # Nested types are often used unqualified by their enclosing
+                # class (`private Operation operation` or `Map<String, DATATYPE>`).
+                # The declaration is not a reference; a second occurrence is.
+                for fqn, (qualified, owner_file) in nested.items():
+                    if owner_file != rel or fqn in nested_hits:
+                        continue
+                    nested_name = qualified.rsplit(".", 1)[-1]
+                    unqualified = re.findall(
+                        rf"(?<!\.)\b{re.escape(nested_name)}\b", text
+                    )
+                    if len(unqualified) > 1:
+                        nested_hits[fqn] = rel
                 scan_java = len(nested_hits) < len(nested)
             if not scan_config and not scan_java:
                 return config_hits, nested_hits, literal_hits
@@ -311,7 +323,7 @@ def analyze_type_references(nodes: "list[dict]", root: Path) -> ReferenceFacts:
             entries.append(TypeReference(
                 status=REFERENCED,
                 basis=(
-                    f"named as a qualified nested type in {nested_hits[fqn]}"
+                    f"referenced by its enclosing source in {nested_hits[fqn]}"
                     if fqn in nested_hits
                     else f"referenced by a class literal in {literal_refs[fqn]}"
                 ),

sourcecode/release_info.py

@@ -27,7 +27,7 @@ from typing import Any, Optional
 #: The date `__version__` was released, from that version's CHANGELOG entry.
 #: `tests/test_release_info.py` fails the build if the two disagree, so this is
 #: a copy of a fact rather than a second authority for it.
-RELEASE_DATE = "2026-08-12"
+RELEASE_DATE = "2026-08-13"
 
 #: Releases per day, measured over the 30 releases before this one (the same
 #: computation the test re-runs against the CHANGELOG). Stable across window

sourcecode/repository_ir.py

@@ -6362,10 +6362,13 @@ def is_test_source_file(rel_path: str) -> bool:
 # Convenience: find Java files in a repo
 # ---------------------------------------------------------------------------
 
-def extract_java_endpoints(root: Path) -> "dict[str, Any]":
+def extract_java_endpoints(
+    root: Path, *, include_tests: bool = False
+) -> "dict[str, Any]":
     """Extract REST endpoint surface from Java source files.
 
     Canonical endpoint extractor — uses IR symbol extraction + _build_route_surface().
+    Test-fixture modules remain auditable by default and can be included explicitly.
     Security extraction delegated to _route_security_from_sym (single source of truth);
     results stored in route["security_annotations"] by _build_route_surface.
 
@@ -6408,7 +6411,7 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
 
     java_files = sorted(
         p for p in root.rglob("*.java")
-        if not is_test_source_file(_rel(p))
+        if (include_tests or not is_test_source_file(_rel(p)))
         and "target/" not in str(p).replace("\\", "/")
         and not any(f in str(p).replace("\\", "/") for f in _CLIENT_PATH_FRAGMENTS)
     )
@@ -6674,7 +6677,8 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     # counted with, the real API surface — but they are preserved in their own bucket
     # so nothing is silently dropped and the exclusion is auditable.
     _test_util_endpoints = [e for e in endpoints if e.get("scope") == "test_util"]
-    endpoints = [e for e in endpoints if e.get("scope") != "test_util"]
+    if not include_tests:
+        endpoints = [e for e in endpoints if e.get("scope") != "test_util"]
 
     # "no_security_signal" = no recognized security annotation at method OR class level.
     # Note: repos may use framework-level security (e.g. Keycloak itself) with no
@@ -6898,7 +6902,7 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
         pass
     # Surface test-fixture endpoints excluded from the production surface above.
     # Reported separately (not hidden) so the exclusion is transparent and auditable.
-    if _test_util_endpoints:
+    if _test_util_endpoints and not include_tests:
         result["test_util_endpoints"] = _test_util_endpoints
         result["test_util_excluded"] = len(_test_util_endpoints)
         result.setdefault("notes", []).append(
@@ -6906,6 +6910,8 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
             f"module(s) under src/main were excluded from the production surface "
             f"(see test_util_endpoints)."
         )
+    elif _test_util_endpoints:
+        result["test_util_included"] = len(_test_util_endpoints)
     # Surface incomplete-endpoint warnings (interface-defined controllers) only when
     # present, to keep output backward-compatible for the common case.
     if endpoint_warnings:
@@ -6964,6 +6970,17 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     if any(r.get("framework") == "jax_rs" for r in routes):
         _nonspring.pop("jax_rs", None)
 
+    # Servlet mappings are a URL declaration population, not a count of
+    # HttpServlet classes. Reuse the servlet extractor so `endpoints` and
+    # `endpoints --servlets` publish the same authoritative census.
+    try:
+        from sourcecode.servlet_surface import build_servlet_surface
+
+        _nonspring["servlets"] = int(
+            build_servlet_surface(root).get("declarations", 0)
+        )
+    except Exception:
+        pass
     _nonspring_total = sum(_nonspring.values())
     if _nonspring_total:
         _frameworks = [k for k, v in _nonspring.items() if v]
@@ -7264,6 +7281,23 @@ def compute_blast_radius(
     # class-level node traversable at all (C1-16), and rebuilding it per node
     # would make the walk quadratic in the graph.
     _rg_index = _class_method_index(reverse_graph)
+
+    def _walk_callers(_node: str) -> list[str]:
+        """Expand method frontiers through their owning class as well.
+
+        Service-locator accessors enter the frontier as ``Class#accessor`` while
+        callers of the class are indexed under its method keys. Keeping the
+        exact lookup preserves method-level reach; adding the enclosing class
+        lookup prevents that frontier from becoming a false terminal node.
+        """
+        candidates = list(_all_callers_from_rg(
+            _node, reverse_graph, _rg_index, _impl_graph
+        ))
+        if "#" in _node:
+            candidates.extend(_all_callers_from_rg(
+                _enclosing_class(_node), reverse_graph, _rg_index, _impl_graph
+            ))
+        return list(dict.fromkeys(candidates))
     # Callers inject the interface, not the implementation, so a walk that does not
     # know the implements relation stops one hop short of every DI consumer. Without
     # it this traversal reached 200 classes and **no controller at all** for
@@ -7298,14 +7332,14 @@ def compute_blast_radius(
                     _expanded.add(_sym)
         matched_fqns = _expanded
     for seed in matched_fqns:
-        _seed_callers = _all_callers_from_rg(seed, reverse_graph, _rg_index, _impl_graph)
+        _seed_callers = _walk_callers(seed)
         if len(_seed_callers) > _HUB_CALLER_THRESHOLD and max_depth > 1:
             _effective_depth = 1
             _hub_class_guard = True
             break
 
     for seed in matched_fqns:
-        callers = _all_callers_from_rg(seed, reverse_graph, _rg_index, _impl_graph)
+        callers = _walk_callers(seed)
         for c in callers:
             if c not in all_affected:
                 all_affected[c] = 1
@@ -7385,16 +7419,22 @@ def compute_blast_radius(
 
     # BFS for indirect callers
     indirect_callers: list[str] = []
+    _indirect_parent: dict[str, str] = {}
+    _hub_frontier_nodes: set[str] = set()
     visited: set[str] = set(matched_fqns) | set(direct_callers)
 
     while queue:
         node, depth = queue.pop(0)
         if depth >= _effective_depth:
             continue
-        for caller in _all_callers_from_rg(node, reverse_graph, _rg_index, _impl_graph):
+        _node_callers = _walk_callers(node)
+        if len(_node_callers) > _HUB_CALLER_THRESHOLD:
+            _hub_frontier_nodes.add(node)
+        for caller in _node_callers:
             if caller not in visited:
                 visited.add(caller)
                 all_affected[caller] = depth + 1
+                _indirect_parent[caller] = node
                 indirect_callers.append(caller)
                 queue.append((caller, depth + 1))
 
@@ -7414,7 +7454,7 @@ def compute_blast_radius(
             _snode, _sdepth = _sample_queue.pop(0)
             if _sdepth >= _HUB_SAMPLE_DEPTH:
                 continue
-            for _scaller in _all_callers_from_rg(_snode, reverse_graph, _rg_index, _impl_graph):
+            for _scaller in _walk_callers(_snode):
                 if _scaller not in _sample_visited:
                     _sample_visited.add(_scaller)
                     all_affected[_scaller] = _sdepth + 1
@@ -7615,10 +7655,38 @@ def compute_blast_radius(
     _direct_caller_classes = sorted(
         caller_classes(direct_callers, exclude=matched_fqns)
     )
-    n_direct_symbols = len(direct_callers)
+    _direct_class_set = set(_direct_caller_classes)
+    _direct_caller_symbols = sorted(
+        symbol for symbol in direct_callers
+        if _enclosing_class(symbol) in _direct_class_set
+    )
+    n_direct_symbols = len(_direct_caller_symbols)
     n_direct_classes = len(_direct_caller_classes)
     n_direct   = n_direct_symbols
     n_indirect = len(indirect_callers)
+
+    # The complete reverse walk is useful as a measured upper reach, but a
+    # service-locator hub can make it collapse to "the whole repository". Publish
+    # a second, conservative axis that stops at hub frontiers instead of forcing
+    # consumers to guess from a flat list of symbols.
+    _without_hubs: list[str] = []
+    _without_hubs_seen = set(matched_fqns) | set(direct_callers)
+    _without_hubs_queue: list[tuple[str, int]] = [
+        (c, 1) for c in direct_callers
+    ]
+    while _without_hubs_queue:
+        _node, _depth = _without_hubs_queue.pop(0)
+        if _depth >= _effective_depth:
+            continue
+        _next = _walk_callers(_node)
+        if len(_next) > _HUB_CALLER_THRESHOLD:
+            continue
+        for _caller in _next:
+            if _caller not in _without_hubs_seen:
+                _without_hubs_seen.add(_caller)
+                _without_hubs.append(_caller)
+                _without_hubs_queue.append((_caller, _depth + 1))
+
     n_ep       = len(endpoints_affected)
     n_txn      = len(txn_nodes)
     n_mappers  = len(mappers_affected)
@@ -7785,6 +7853,20 @@ def compute_blast_radius(
     _indirect_summary = (
         _indirect_ordered if _indirect_cap is None else _indirect_ordered[:_indirect_cap]
     )
+    def _via_hub(_node: str) -> bool:
+        _seen_path: set[str] = set()
+        _cursor = _node
+        while _cursor in _indirect_parent and _cursor not in _seen_path:
+            _seen_path.add(_cursor)
+            _cursor = _indirect_parent[_cursor]
+            if _cursor in _hub_frontier_nodes:
+                return True
+        return False
+
+    _indirect_details = [
+        {"fqn": _node, "depth": all_affected.get(_node), "via_hub": _via_hub(_node)}
+        for _node in _indirect_summary
+    ]
 
     out: dict = {
         "target": target,
@@ -7827,10 +7909,11 @@ def compute_blast_radius(
             else _direct_caller_classes[:_direct_cap]
         ),
         "direct_caller_symbols": (
-            sorted(direct_callers) if _direct_cap is None
-            else sorted(direct_callers)[:_direct_cap]
+            _direct_caller_symbols if _direct_cap is None
+            else _direct_caller_symbols[:_direct_cap]
         ),
         "indirect_callers": _indirect_summary,
+        "indirect_caller_details": _indirect_details,
         "container_wired": [w.to_dict() for w in _container_wired],
         "endpoints_affected": endpoints_affected,
         "mappers_affected": mappers_affected,
@@ -7850,6 +7933,10 @@ def compute_blast_radius(
             "indirect_caller_count": n_indirect,
             "indirect_callers_computed": not _bfs_truncated or _indirect_sampled,
             "indirect_callers_sampled": _indirect_sampled,
+            "indirect_caller_count_unit": "reference symbols (methods or classes)",
+            "indirect_callers_without_hubs_count": len(_without_hubs),
+            "indirect_callers_without_hubs_unit": "reference symbols (hub frontiers excluded)",
+            "hub_frontier_count": len(_hub_frontier_nodes),
             "endpoints_affected_count": n_ep,
             # C1-37: four figures called "endpoints" at one commit (3 364 /
             # 3 382 / 3 382 / 3 574). Each one now says which population it

sourcecode/risk.py

@@ -47,6 +47,31 @@ if TYPE_CHECKING:
 
 RISK_SCHEMA = "risk-v1"
 
+
+def compact_risk_output(data: dict) -> dict:
+    """Project stdout to stable rule prose plus small per-defect evidence."""
+    compact = dict(data)
+    rows = data.get("risks") or []
+    rules: dict[str, dict] = {}
+    lean: list[dict] = []
+    for row in rows:
+        rule_ids = row.get("rule_ids") or [row.get("rule_id", "unknown")]
+        for rule_id in rule_ids:
+            rules.setdefault(rule_id, {
+                "title": row.get("title", ""),
+                "statement": row.get("statement", ""),
+            })
+        lean.append({
+            key: row[key] for key in (
+                "defect_id", "symbol", "source_file", "first_line", "band",
+                "score", "rule_ids", "factors",
+            ) if key in row
+        })
+    compact["rules"] = rules
+    compact["risks"] = lean
+    compact["default_output"] = "bounded"
+    return compact
+
 #: The composition, in one place. The payload publishes it, `--help` renders it and
 #: the battery holds both to it: a hand-copied model line in the help screen went on
 #: advertising four factors for as long as it took someone to read it, which is the

sourcecode/servlet_surface.py

@@ -168,9 +168,16 @@ def build_servlet_surface(root: Path, *, limit: Optional[int] = None) -> dict:
         elif path.suffix == ".java":
             mappings.extend(_from_registration_beans(path, relative))
 
-    # One URL pattern declared twice is two declarations of one reachable path; the
-    # census counts patterns, the rows keep every declaration.
-    patterns = sorted({m.url_pattern for m in mappings})
+    # A URL pattern is the observable HTTP surface. Multiple descriptors can
+    # repeat it, but publishing every duplicate made `declarations` disagree with
+    # the pattern census and with endpoint-side reconciliation. Keep the first
+    # deterministic declaration as provenance and expose one row per reachable
+    # pattern.
+    _unique: dict[str, ServletMapping] = {}
+    for mapping in sorted(mappings, key=lambda m: (m.url_pattern, m.source_file, m.source)):
+        _unique.setdefault(mapping.url_pattern, mapping)
+    mappings = list(_unique.values())
+    patterns = sorted(_unique)
     by_source: "dict[str, int]" = {}
     for mapping in mappings:
         by_source[mapping.source] = by_source.get(mapping.source, 0) + 1

sourcecode/validation_surface.py

@@ -484,18 +484,15 @@ def _programmatic_validation_signals(graph: "ContextGraph") -> "list[str]":
         if _is_excluded(t.source_file):
             continue
         sig = (t.signature or "")
-        if "org.springframework.validation.Validator" not in sig:
+        if (
+            "org.springframework.validation.Validator" not in sig
+            and not re.search(r"\bimplements\s+Validator\b", 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))
 
@@ -627,6 +624,7 @@ def build_validation_surface(
             "detected": True,
             "evidence": programmatic_evidence,
         }
+        result["programmatic_validation_gaps"] = []
     spec_path = endpoints_data.get("openapi_spec")
     if spec_path:
         result["openapi_spec"] = spec_path
@@ -717,7 +715,7 @@ def build_validation_surface(
             "outside the declared-constraint surface this command models."
         ).strip()
         if not result.get("gaps"):
-            result["gaps"] = [
+            result["programmatic_validation_gaps"] = [
                 {
                     "method": "",
                     "path": "",
@@ -727,7 +725,6 @@ def build_validation_surface(
                     "confidence": "Likely",
                 }
             ]
-            result["summary"]["gaps"] = 1
 
     _reconcile_with_code_axis(result, graph, root)
     if programmatic_evidence:
@@ -740,7 +737,7 @@ def build_validation_surface(
         if programmatic_note.strip() not in note:
             result["note"] = (note + programmatic_note).strip()
         if not result.get("gaps"):
-            result["gaps"] = [
+            result["programmatic_validation_gaps"] = [
                 {
                     "method": "",
                     "path": "",
@@ -750,7 +747,6 @@ def build_validation_surface(
                     "confidence": "Likely",
                 }
             ]
-            result["summary"]["gaps"] = 1
     return result
 
 

{sourcecode-5.5.0.dist-info → sourcecode-5.5.2.dist-info}/METADATA

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

{sourcecode-5.5.0.dist-info → sourcecode-5.5.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=kIpmlxwOoXC5aa6kJcz5s9dCm4R4SN2RiXVFk3uxLJQ,308
+sourcecode/__init__.py,sha256=N8caEJv8V-c5M8fb_R3zr9u-Fd7axm-yB4yw-d_rbf0,308
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=CZvRLpkHot_D8D3JFQVorr-EHDJyh0BbS7RnSTqBigM,40499
 sourcecode/architectural_baseline.py,sha256=4GiMVBLJVHvRKSWQGf2ZVurI1-R0qk5pmaevgvGSgVA,26325
@@ -19,7 +19,7 @@ sourcecode/chain_rules.py,sha256=Bi6UHfgd-GxWswmnHRcPz5jdbAuqka3Zkz_P-MTvqhw,127
 sourcecode/change_plan.py,sha256=aX1mp2XnlDN-8R2BcTiu8HlkDwQ_4fN1ZLckj0VMXHM,9945
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=JBzPwSSrDG-tUHAbcKB678HRbjLpD-ohzbzzO62mgpo,20114
-sourcecode/cli.py,sha256=vV53BEtmpl97Kz2a00Sk88_SKgdbd17B5mA52tMLcas,645928
+sourcecode/cli.py,sha256=hJukwL8ZTc1ZHVkkZWau9J0LFYtAfyHvVdp4HKIRWIY,648972
 sourcecode/client_calls.py,sha256=5_sBfFVXi6RgGiyWrlJKH4x4EF21do6gKlAOuFCKAoA,17709
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/compare.py,sha256=2GdDy0qkDSgmkkpgvoCHitoLj3mt30EeFgJ8PGEXJng,14712
@@ -41,7 +41,7 @@ sourcecode/data_labels.py,sha256=c_hmgudTE68cVRdywfbfonr7nUWIL-JH2HOXB8Pplv0,845
 sourcecode/declarations.py,sha256=Jr7oJDg004sFw0TvJySNVggXFT2jB6hQgbeQK2qreVo,7000
 sourcecode/defect_identity.py,sha256=XS2VFDImg9NLaRImybKTeyk-CoDSsXmchldg0dwvM7c,7028
 sourcecode/degradation.py,sha256=BtuGUKFgkzI3Z6fwmUdxEUEaLFAcPQ_bHhU2w9ItDxw,18376
-sourcecode/dependency_analyzer.py,sha256=fQCaWQ7_BNcVgZv8gweJCwJ1CGlXsz8nw_tqN3aHJNE,63952
+sourcecode/dependency_analyzer.py,sha256=MRv6eh1TG5E9Y5Db-bNdZHDIJ3gWvvL3bBU1-9_QSZI,64593
 sourcecode/deployment_prefix.py,sha256=g0_4bE_m9svjhnapRpOp8BJkj6Ul94Ij_iVezygMZ0I,11956
 sourcecode/detach.py,sha256=PvkCcbIuTaDKKt5TGqtQLahmsmCkflui33jLnMEWkvg,8006
 sourcecode/doc_analyzer.py,sha256=05bjTUbDbmnbajD_cgRnACzS8T7xxBKVX4CjkJlhZg8,24411
@@ -71,9 +71,10 @@ sourcecode/identity_fallback.py,sha256=uRC_j_80uaI4Ue4tf-OhKX4h472dmufYcjEFGSxY2
 sourcecode/integration_coordinates.py,sha256=7vGFxN4tCn_KTisYFJuixa8XkyHBoasEFB3fqM62OBI,7407
 sourcecode/jdk_exports.py,sha256=fCrlwNAXUT9gge_joq6kMnY3zJxYB2pxqy-0w3o3MJI,874
 sourcecode/license.py,sha256=vvgE1vBUWh8ozWI7USYuteh6noxntnjuzDQIPF-l4rA,27795
+sourcecode/manifest_cache.py,sha256=NkVtg0T5YfHdIiM63jStvcLcsznM6_bnTHib4t8_FW8,2158
 sourcecode/mcp_nudge.py,sha256=lKemOqK_wny2u7Ymcr2Idi5Kx8pXY02jCi-_nJYLGMg,2992
 sourcecode/metrics_analyzer.py,sha256=gLoRWKygF18jLgwsqmGXSWopw-f5iO1VbM7Jjdif6ag,22809
-sourcecode/migrate_check.py,sha256=8KKgsiiWu21XwCXgFV1bB8AVsB-pl6KNBTmMW6NYGB8,149028
+sourcecode/migrate_check.py,sha256=vdJ_2hOR9XOIQsz4czzamQMKKzHnNErg8vPdzzYqfMY,150019
 sourcecode/migration_blast.py,sha256=OPryWkM6-PbvcG3eJFdcWUnlpXBje41nu2BkrZnE2hg,9359
 sourcecode/non_coverage.py,sha256=sKp0J4_hKzKb_HMoXtdP91D0lMfEAPrOx44sqdQc18Y,23520
 sourcecode/openapi_surface.py,sha256=BTt0K-woZbkbWTN77IkqeBm_Okag9owR0848fmot8sk,16207
@@ -99,15 +100,15 @@ sourcecode/readiness_timeline.py,sha256=KjghC1MWH7Tzto97TBR3N0F8FkR87w5z7lZ1QsWv
 sourcecode/readonly.py,sha256=dqGiNVvpfi4Ww8VzwUs6E3SdbqcHL1LFHItIK7IjrM0,5830
 sourcecode/reconciliation.py,sha256=GU-1PTcVr8zcbtC7BASfpHcZndP9AdboXPNQiBc0fzo,34251
 sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
-sourcecode/reference_facts.py,sha256=3r8EnbKewOAls3FOggDWnTr84eogJoQ8fVVdvyXSpfE,14801
-sourcecode/release_info.py,sha256=IQdMsFrQM4IVHNmwXWS7TbtRu80_oWugvNrYnpQ0bao,5895
+sourcecode/reference_facts.py,sha256=mx7H-Ax5y8sKAQHrnJCXlgjkUzqZtQTByv9Zy2lxKQQ,15500
+sourcecode/release_info.py,sha256=lCzjRkPWDmOZQxPujpY5FwPU8a87G358ectkhNU8cX8,5895
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/remedies.py,sha256=V2_cD4pLq8bKRkzF-3RGFoiu1xWYZS384WDVp1MrlZw,10225
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
-sourcecode/repository_ir.py,sha256=AAX2OCLNIBcTicuHH-WydIJStBVPjbdkBbYCwOhFYWs,380428
+sourcecode/repository_ir.py,sha256=tV0Uu7qWw_gDUG9WldYxmbNLZnbQljxHYZznWP4cdlA,384071
 sourcecode/ris.py,sha256=Xbx34dkJI_uXil9xsgw-fA_Apcm4nbnTjQgFm66dP1g,27489
-sourcecode/risk.py,sha256=432XEiL9xp8JBaxidwQInZBN4F98QJLAsqgZrh3CKow,81790
+sourcecode/risk.py,sha256=u2V7nG5yGW8VV4sFDSgFkZqdI6ltmilWhlQwlIH7d2o,82660
 sourcecode/rule_catalog.py,sha256=pTkgkQZ1u7atB3fkQJ9BPWo8lNiamvEuRN7MtRgle0c,5263
 sourcecode/rule_pass.py,sha256=DTNxD-nAecMJhIzI1LCd9FyRumInQSZjitacNh4Zoc8,14671
 sourcecode/runs.py,sha256=o4oXkB3WFJGScbK_C10OAWzsE18B9Zc55u_IE8_yl4M,6291
@@ -124,7 +125,7 @@ sourcecode/semantic_impact_engine.py,sha256=t09IirGC3JjQDy33JZd1_WKzQVKXkoNl3-XE
 sourcecode/semantic_integration_engine.py,sha256=7a0WqAInOv39f0Yr_94TYo_JP_8QpeI9KGaknpzAyQU,18899
 sourcecode/semantic_services.py,sha256=nbUuPv-F01USTt_9CHT8iy_ucCIw3fz4W3Aquea_pd4,10782
 sourcecode/serializer.py,sha256=cK4I3WzX0H-oBPbqzBsUBRux5GcYmH_yPDQwxvkf8yQ,141598
-sourcecode/servlet_surface.py,sha256=aOeRne07man8DwHsbog4FTOyF3sYV-oP_N1e4gt3Uvk,9115
+sourcecode/servlet_surface.py,sha256=QY3QPw6pZJ4CQK4yS8q7uDd3f2PDyUUsQ8TS_BkbGs8,9506
 sourcecode/source_text.py,sha256=R52gmSljz7L6YVPbixv5W-LOZ5eKUVvSUP3S-QH_IWc,9047
 sourcecode/spring_event_topology.py,sha256=5_ON_21Le5zbG-1GRc5GLIi5HJfy_QjcXLVPC5WeUGQ,18055
 sourcecode/spring_findings.py,sha256=cW6NiQAFUM9mDYPitJr6MrQg--YBI41LxrSEMI9aeIQ,25272
@@ -146,7 +147,7 @@ sourcecode/token_estimate.py,sha256=G-ivzIJfVq5TLQN04dC0WK4LZJjWVYL54Ebcxe4fJ7M,
 sourcecode/tree_utils.py,sha256=8GAkIfQAsvtEudIeW1l4ooH_oRtrWR8cpJQJsEa_Pfw,2093
 sourcecode/type_usage_surface.py,sha256=51IrKRQoIoRnlsiDjHnqpJBn2rc6E59aRhgS0HTzAF0,4428
 sourcecode/validation_inference.py,sha256=-oWJqE6PqkqcZbCFDJeWCQHgI9Dbuv5ggJWD3LE_2IU,20817
-sourcecode/validation_surface.py,sha256=2wQAEfzWKAymsptGLaIlN-xw2C7ozE4zO-WR8a7qr20,34857
+sourcecode/validation_surface.py,sha256=06muCMxymQEQSqmNgTMdsguC7XQ22tqcZmYJOmvWFHY,34745
 sourcecode/verify_edit.py,sha256=SUaJeH5Icc54mutQx3-gh7i8U6d50cb_oxYc9SDUnHs,42757
 sourcecode/verify_repo.py,sha256=aHlNIUfoVVUxTXTNtSFryP4dOFBOvCfdyC31fFRXU6s,15346
 sourcecode/verify_rules.py,sha256=R3l6nLT6WQzUNBzxtmnxyGZcKj9qMDW38Y0c0gNdCGk,19973
@@ -213,9 +214,9 @@ sourcecode/telemetry/events.py,sha256=4_yeO58U-Cwc1Qb27VB0_EjhmroY0k91n3_VGxeALB
 sourcecode/telemetry/filters.py,sha256=RzxauTz8HliO4BllQnXEXc7zTeqdCZi5MgqGEDuW7OQ,6570
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
 sourcecode/_docs/DEFECT-LEDGER.md,sha256=sTFPEV2xx-L9n4mrG8UO4LxeETMJpGKHXyKQBZlqNog,497112
-sourcecode/_docs/USER_GUIDE.md,sha256=yRFIp4sx38X4KSxIf1RjwCiWsvKSmJ-IoPkzHOOsMI4,79546
-sourcecode-5.5.0.dist-info/METADATA,sha256=jg3OolyQqoitfNoZCkPqc8nQm20P8TZogBj2pyC8ljA,47104
-sourcecode-5.5.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-5.5.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-5.5.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-5.5.0.dist-info/RECORD,,
+sourcecode/_docs/USER_GUIDE.md,sha256=IOYL9rI9tLViNMICXma_uRSiztjMaW92V5sDAYlPkfo,79546
+sourcecode-5.5.2.dist-info/METADATA,sha256=VjdCWsZA1Bm_mhWsXA-yr6JT1zTSKcLVJA8lejltoug,47104
+sourcecode-5.5.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-5.5.2.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-5.5.2.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-5.5.2.dist-info/RECORD,,