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

sourcecode/cli.py

@@ -4084,7 +4084,11 @@ def impact_cmd(
       - direct_callers     — classes that directly call or depend on the target
       - indirect_callers   — transitive callers (BFS, bounded by --depth)
       - endpoints_affected — HTTP endpoints that transitively depend on the target
-      - transactional_boundaries_touched — @Transactional classes in the call chain
+      - transactional_boundaries_touched — @Transactional declarations on the target
+                             and on everything that calls it
+      - transactional_boundaries_reaching — the callers-only subset: what would run
+                             this change inside a transaction (the figure
+                             `ask retrieve transactions-reaching` reports)
       - risk_score / risk_level — quantified change risk
 
     \b
@@ -4714,7 +4718,10 @@ def export_cmd(
     ),
     integrations: bool = typer.Option(
         False, "--integrations",
-        help="Detect outbound integrations (HTTP/LDAP/JMS clients) with file:line evidence.",
+        help=(
+            "Detect outbound integrations (HTTP/LDAP/JMS clients) with file:line "
+            "evidence, plus the client libraries the build declares."
+        ),
     ),
     c4: bool = typer.Option(
         False, "--c4",
@@ -4742,6 +4749,11 @@ def export_cmd(
                      rolled up from class-level relation edges.
     --integrations   Outbound integrations (RestTemplate/WebClient/Feign/LDAP/JMS)
                      with file:line evidence — external-system dependency arrows.
+                     Also lists the client libraries the BUILD declares
+                     (declared_clients) and which of those no source construct
+                     uses — a config-wired client has no construct to find, so a
+                     count of 0 is never left standing alone against a client
+                     library named in the stack block.
     --c4             Unified architecture document mapped onto the open C4 model
                      (context/containers/components/code) + an API surface and a
                      per-directory content-hash manifest for incremental consumers.
@@ -4792,9 +4804,12 @@ def export_cmd(
         graph = ir.get("graph", {})
         _ep_data = extract_java_endpoints(root)
         endpoints = _ep_data.get("endpoints", [])
+        from sourcecode.integration_coordinates import declared_integration_coordinates
         _integrations = SemanticIntegrationEngine(
             ContextGraph.build(file_list, root)
-        ).as_report(len(file_list))
+        ).as_report(
+            len(file_list), declared=declared_integration_coordinates(root),
+        )
         data = _build_c4_export(
             root,
             file_list,
@@ -4831,9 +4846,12 @@ def export_cmd(
     if integrations:
         from sourcecode.context_graph import ContextGraph
         from sourcecode.semantic_integration_engine import SemanticIntegrationEngine
+        from sourcecode.integration_coordinates import declared_integration_coordinates
         data["integrations"] = SemanticIntegrationEngine(
             ContextGraph.build(file_list, root)
-        ).as_report(len(file_list))
+        ).as_report(
+            len(file_list), declared=declared_integration_coordinates(root),
+        )
 
     _prog.finish()
     output = _serialize_dict(data, format)
@@ -5684,19 +5702,35 @@ def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  #
     gc = (result.security_posture or {}).get("gate_coverage")
     if not gc:
         return []
-    not_covered = gc.get("not_carrying_gate", 0)
+    not_covered = gc.get("endpoints_not_carrying_gate", gc.get("not_carrying_gate", 0))
     gates = ", ".join(f"`{g}`" for g in gc.get("gate_annotations", [])) or "the detected gate"
-    total = gc.get("total_controller_handlers", 0)
+    # One unit, named: these are endpoints, not handler methods. The two counts differ
+    # (one method can serve several mappings) and must never be summed together.
+    total = gc.get("endpoints_total", gc.get("total_controller_handlers", 0))
     lines: list[str] = ["", "---", ""]
     if not_covered == 0:
-        lines.append(f"✅ **Gate coverage** — all {total} controller handlers carry {gates}.")
+        _gated = gc.get("endpoints_carrying_gate", total)
+        _std = gc.get("endpoints_standard_guarded", 0)
+        if _std:
+            lines.append(
+                f"✅ **Gate coverage** — all {total} endpoints are guarded: {_gated} carry "
+                f"{gates}, {_std} rely on a standard guard."
+            )
+        else:
+            lines.append(f"✅ **Gate coverage** — all {total} endpoints carry {gates}.")
         return lines
 
     covered = gc.get("possibly_filter_covered", 0)
+    _standard = gc.get("endpoints_standard_guarded", 0)
     lines.append(
-        f"🔓 **Gate coverage** — {not_covered} of {total} controller handlers do not carry "
+        f"🔓 **Gate coverage** — {not_covered} of {total} endpoints do not carry "
         f"{gates}."
     )
+    if _standard:
+        lines.append(
+            f"_{gc.get('endpoints_carrying_gate', 0)} carry the gate, {_standard} rely on a "
+            f"standard guard, {not_covered} on neither — the three sum to {total}._"
+        )
     if gc.get("reconstructed_filter_patterns"):
         lines.append(
             f"_{covered} of those match a reconstructed servlet filter pattern "
@@ -6201,6 +6235,65 @@ def posture_cmd(
 # ── Spring Boot Migration Check ───────────────────────────────────────────────
 
 
+def _migration_blast_radius(
+    target: Path,
+    file_list: list[str],
+    report: "object",
+    depth: int,
+) -> dict:
+    """Resolve the regression scope behind the migration findings (--blast-radius).
+
+    Reuses the shared context-cache CIR — the same one `impact-chain`, `explain` and
+    `cache warm` use — so a warmed repository skips the Java parse. Every failure mode
+    degrades to a block that says what could not be computed; it never fabricates reach
+    and never breaks the scan that already succeeded.
+    """
+    from sourcecode.migration_blast import compute_migration_blast, SCHEMA_VERSION
+
+    _depth = max(1, min(int(depth), 8))
+    findings = list(getattr(report, "findings", []) or [])
+
+    def _degraded(reason: str) -> dict:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "depth": _depth,
+            "status": "unavailable",
+            "endpoints_in_repo": 0,
+            "endpoints_reached": 0,
+            "request_surface_share": None,
+            "files_analyzed": 0,
+            "files_on_request_path": 0,
+            "files_off_request_path": 0,
+            "files_unresolved": [],
+            "files": [],
+            "files_omitted": 0,
+            "notes": [reason],
+        }
+
+    if not file_list:
+        return _degraded(
+            "No Java sources in this repository — there is no call graph to traverse, "
+            "so no regression scope can be attributed."
+        )
+
+    try:
+        from sourcecode import context_cache as _ctxcache
+        from sourcecode.context_graph import ContextGraph
+        from sourcecode.spring_model import SpringSemanticModel
+
+        try:
+            cir, _ = _ctxcache.get_or_build_cir(_resolve_repo_root(target), target, file_list)
+        except Exception:
+            cir = ContextGraph.build(file_list, target).cir
+        model = SpringSemanticModel.build(cir)
+        return compute_migration_blast(cir, model, findings, depth=_depth)
+    except Exception as exc:  # pragma: no cover - defensive
+        return _degraded(
+            f"Blast radius unavailable: {type(exc).__name__} while building the "
+            "repository IR. The migration findings above are unaffected."
+        )
+
+
 @app.command("migrate-check")
 def migrate_check_cmd(
     path: Path = typer.Argument(
@@ -6265,6 +6358,18 @@ def migrate_check_cmd(
         False, "--force",
         help="Emit to stdout even when the report exceeds the output-size guard.",
     ),
+    blast_radius: bool = typer.Option(
+        False, "--blast-radius",
+        help=(
+            "Rank affected product files by the HTTP endpoints whose call path runs "
+            "through them (regression scope), using the same caller traversal as "
+            "impact-chain. Builds the repository IR — slower than a plain scan."
+        ),
+    ),
+    depth: int = typer.Option(
+        4, "--depth",
+        help="Caller BFS depth for --blast-radius (1-8, default: 4).",
+    ),
 ) -> None:
     """Spring Boot 2→3 migration readiness: detect javax→jakarta namespace blockers.
 
@@ -6298,6 +6403,16 @@ def migrate_check_cmd(
       ask migrate-check . --output migration.json
       ask migrate-check . --snapshot --ref sprint-12   persist a readiness point
       ask migrate-check . --trend                      days-remaining over time
+      ask migrate-check . --blast-radius               endpoints behind each blocker
+
+    \b
+    Blast radius (--blast-radius):
+      Ranks the affected product files by the HTTP endpoints whose call path runs
+      through them — the re-test plan, ordered by regression scope. Reach is never
+      build breakage: a javax→jakarta finding fails compilation whether or not an
+      endpoint reaches it. A file whose types the IR could not resolve is reported
+      unresolved (reach unknown, never zero), and a repository with no endpoints in
+      the IR gets a null share with the reason stated instead of a 0.0.
 
     \b
     Readiness time series:
@@ -6366,6 +6481,9 @@ def migrate_check_cmd(
     if _file_limitations:
         report.limitations.extend(_file_limitations)
 
+    if blast_radius:
+        report.blast_radius = _migration_blast_radius(target, file_list, report, depth)
+
     if format == "text":
         output = report.to_text(min_severity=min_severity)
     else:
@@ -6513,7 +6631,8 @@ def impact_chain_cmd(
       - indirect_callers    — transitive callers (BFS up to --depth hops)
       - endpoints_affected  — HTTP endpoints reachable through the call chain
       - transaction_boundary — @Transactional semantics on the target (if any)
-      - security_surfaces   — per-endpoint security policy + SEC findings
+      - security_surfaces   — per-endpoint security verdict + confidence
+                              (security_posture authority) + declared policy + SEC findings
       - impact_findings     — TX/SEC audit findings touching the call chain
       - risk_level          — critical | high | medium | low
 

sourcecode/detectors/java.py

@@ -15,6 +15,7 @@ from sourcecode.detectors.parsers import (
     substitute_maven_properties as _resolve_maven_property,
     unique_strings,
 )
+from sourcecode.integration_coordinates import coordinates_for_kind
 from sourcecode.schema import FrameworkDetection
 from sourcecode.tree_utils import flatten_file_tree
 
@@ -488,11 +489,15 @@ class JavaDetector(AbstractDetector):
         if "spring-boot-starter-data-jpa" in text or "spring-data-jpa" in text:
             frameworks.append(FrameworkDetection(name="Spring Data JPA", source=source))
         # The Boot starter names neither of the module coordinates, so a Boot app
-        # wiring LDAP the standard way declared no LDAP framework at all.
-        if (
-            "spring-ldap-core" in text
-            or "spring-security-ldap" in text
-            or "spring-boot-starter-data-ldap" in text
+        # wiring LDAP the standard way declared no LDAP framework at all. The coordinate
+        # list lives in `integration_coordinates` — the same set `export --integrations`
+        # reads, so this stack block and that report can never recognize different
+        # libraries for the same external system (ADR-0008 R12).
+        # Only the Spring-family coordinates may carry the "Spring LDAP" label — the
+        # authority also knows non-Spring directory clients, and naming the wrong library
+        # would trade one incoherence for another.
+        if any(
+            c in text for c in coordinates_for_kind("ldap") if c.startswith("spring-")
         ):
             frameworks.append(FrameworkDetection(name="Spring LDAP", source=source))
         if "spring-aspects" in text or "spring-aop" in text:

sourcecode/integration_coordinates.py

@@ -0,0 +1,175 @@
+"""integration_coordinates.py — the declared-client signal for outbound integrations.
+
+THE authority for one question: *which outbound-integration client libraries does this
+repository's build declare?* (ADR-0008 R1). It is a different question from "which client
+constructs does the source contain" — that one belongs to
+:mod:`sourcecode.semantic_integration_engine` — and the two answers only conflict when a
+document reports one and stays silent about the other.
+
+That is exactly what the field reported, twice, two majors apart: `export --integrations`
+answered `count: 0` on a repository whose stack block listed **Spring LDAP**. Reproduced on
+a Boot app that declares `spring-boot-starter-data-ldap` and configures
+`spring.ldap.urls` in YAML: the directory is wired entirely by properties, so no LDAP
+client type is ever imported and the construct scan is *right* to find nothing — but the
+document as a whole then said the system has no outbound integrations while its own stack
+block said it talks to a directory.
+
+A declared coordinate is **evidence of a declared client, never an observed integration**
+(the same discipline that stopped a `org.mybatis` coordinate from being reported as MyBatis
+usage in `detectors/java.py`). This module answers what the build declares; the engine
+answers what the code does; the payload states both and says which is which.
+
+VAI (see `security_posture` §0.5): the table below lists **published open-source artifact
+coordinates** — the identity of a library, matched literally, the same basis as the engine's
+published client-type table. No proprietary, client or convention name appears here, and no
+predicate branches on a repository's own naming.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional
+
+# Build-manifest artifact coordinate → the outbound-integration kind it declares.
+# Kinds are exactly the engine's kinds, so declared and observed answers are comparable.
+# Only coordinates whose sole purpose is to talk to an external system are listed: a
+# driver-or-anything coordinate that a repository might carry for unrelated reasons has no
+# place here, because a declaration nobody can act on is noise, not evidence.
+_COORDINATE_KIND: "dict[str, str]" = {
+    # Directory (LDAP)
+    "spring-ldap-core": "ldap",
+    "spring-security-ldap": "ldap",
+    "spring-boot-starter-data-ldap": "ldap",
+    "spring-boot-starter-ldap": "ldap",
+    "unboundid-ldapsdk": "ldap",
+    # Kafka
+    "spring-kafka": "kafka",
+    "kafka-clients": "kafka",
+    "spring-cloud-stream-binder-kafka": "kafka",
+    # RabbitMQ / AMQP
+    "spring-boot-starter-amqp": "rabbitmq",
+    "spring-rabbit": "rabbitmq",
+    "amqp-client": "rabbitmq",
+    # JMS brokers
+    "spring-boot-starter-activemq": "jms",
+    "spring-boot-starter-artemis": "jms",
+    "activemq-client": "jms",
+    "activemq-broker": "jms",
+    "artemis-jms-client": "jms",
+    "spring-jms": "jms",
+    # Redis
+    "spring-boot-starter-data-redis": "redis",
+    "spring-data-redis": "redis",
+    "lettuce-core": "redis",
+    "jedis": "redis",
+    # Elasticsearch
+    "spring-boot-starter-data-elasticsearch": "elasticsearch",
+    "elasticsearch-rest-high-level-client": "elasticsearch",
+    "elasticsearch-java": "elasticsearch",
+    # Mail (SMTP)
+    "spring-boot-starter-mail": "smtp",
+    # Declarative HTTP clients
+    "spring-cloud-starter-openfeign": "http",
+    "feign-core": "http",
+    "okhttp": "http",
+    # SOAP
+    "spring-ws-core": "soap",
+    "spring-boot-starter-web-services": "soap",
+    "cxf-rt-frontend-jaxws": "soap",
+}
+
+# Build manifests scanned. Text-level, like the framework-coordinate scan in
+# `detectors/java.py` — a build file is configuration, not source.
+_MANIFEST_NAMES: frozenset[str] = frozenset({
+    "pom.xml", "build.gradle", "build.gradle.kts",
+})
+
+# Directories that never hold a production build manifest.
+_SKIP_DIRS: frozenset[str] = frozenset({
+    ".git", ".idea", "target", "build", "node_modules", ".sourcecode-cache",
+    ".gradle", "out", "dist",
+})
+
+# A repository with thousands of modules is real (OFBiz, Broadleaf); an unbounded walk is
+# not. The cap is stated in the payload when it bites, never applied silently.
+_MAX_MANIFESTS = 400
+
+_TEST_SCOPE_WINDOW = 4          # lines after a Maven coordinate that may carry its <scope>
+_TEST_SCOPE = re.compile(r"<scope>\s*(test|provided)\s*</scope>", re.IGNORECASE)
+_GRADLE_TEST_CONF = re.compile(r"^\s*(test|androidTest)[A-Za-z]*\s*[(\s'\"]", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class DeclaredClient:
+    """A client library the build declares, with the line that declares it."""
+
+    kind: str
+    coordinate: str
+    evidence: str               # "relpath:line" — same shape as an Integration's evidence
+
+    def to_dict(self) -> dict:
+        return {"kind": self.kind, "coordinate": self.coordinate, "evidence": self.evidence}
+
+
+def coordinates_for_kind(kind: str) -> tuple[str, ...]:
+    """Published coordinates that declare ``kind``. One home for the list, so a consumer
+    that recognizes a library recognizes the same set this authority does."""
+    return tuple(sorted(c for c, k in _COORDINATE_KIND.items() if k == kind))
+
+
+def _manifest_paths(root: Path) -> list[Path]:
+    found: list[Path] = []
+    for name in sorted(_MANIFEST_NAMES):
+        for path in sorted(root.rglob(name)):
+            if len(found) >= _MAX_MANIFESTS:
+                return found
+            if any(part in _SKIP_DIRS for part in path.parts):
+                continue
+            if path.is_file():
+                found.append(path)
+    return found
+
+
+def _is_test_scoped(lines: list[str], idx: int, manifest: str) -> bool:
+    """True when the declaration is a test/provided dependency — a build-time coordinate
+    is not a statement that the running system talks to that external party."""
+    if manifest == "pom.xml":
+        for line in lines[idx: idx + _TEST_SCOPE_WINDOW + 1]:
+            if _TEST_SCOPE.search(line):
+                return True
+        return False
+    return bool(_GRADLE_TEST_CONF.match(lines[idx]))
+
+
+def declared_integration_coordinates(
+    root: Optional[Path], *, manifests: Optional[Iterable[Path]] = None,
+) -> list[DeclaredClient]:
+    """Client libraries the build declares, deterministically ordered, deduplicated by
+    (kind, coordinate). Never raises: an unreadable manifest contributes nothing.
+    """
+    if root is None:
+        return []
+    root = Path(root)
+    paths = list(manifests) if manifests is not None else _manifest_paths(root)
+
+    seen: dict[tuple[str, str], DeclaredClient] = {}
+    for path in paths:
+        try:
+            lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
+        except OSError:
+            continue
+        try:
+            rel = str(path.relative_to(root)).replace("\\", "/")
+        except ValueError:
+            rel = path.name
+        for idx, line in enumerate(lines):
+            for coordinate, kind in _COORDINATE_KIND.items():
+                if coordinate not in line:
+                    continue
+                if _is_test_scoped(lines, idx, path.name):
+                    continue
+                key = (kind, coordinate)
+                if key not in seen:
+                    seen[key] = DeclaredClient(kind, coordinate, f"{rel}:{idx + 1}")
+    return [seen[k] for k in sorted(seen)]

sourcecode/mcp/registry.py

@@ -781,7 +781,9 @@ Blast-radius analysis: who calls a class and what breaks if it changes? Java onl
 
 Maps to: ask impact <target> <repo_path> [--depth <depth>]
 Returns: direct_callers, indirect_callers, endpoints_affected,
-         transactional_boundaries_touched, risk_score, risk_level, stats.
+         transactional_boundaries_touched (target + callers),
+         transactional_boundaries_reaching (callers only), risk_score,
+         risk_level, stats.
 
 Use this when:
 - Planning a refactor: understand the full call chain before changing a class

sourcecode/mcp/server.py

@@ -890,7 +890,8 @@ def get_impact_chain(repo_path: str = ".", symbol: str = "", depth: int = 4) ->
     Returns: ImpactChainResult with schema_version, symbol, resolution,
              direct_callers, indirect_callers, endpoints_affected,
              transaction_boundary (propagation/isolation/read_only),
-             security_surfaces (per-endpoint policy + finding IDs),
+             security_surfaces (per-endpoint verdict/confidence from the
+             security_posture authority + declared policy + finding IDs),
              impact_findings (TX-001..005 + SEC-001..003 findings in call chain),
              analysis_warnings, risk_level, confidence, metadata.
 
@@ -1320,7 +1321,9 @@ def get_impact_context(repo_path: str = ".", target: str = "", depth: int = 4) -
 
     Maps to: ask impact <target> <repo_path> [--depth <depth>]
     Returns: direct_callers, indirect_callers, endpoints_affected,
-             transactional_boundaries_touched, risk_score, risk_level, stats.
+             transactional_boundaries_touched (target + callers),
+             transactional_boundaries_reaching (callers only), risk_score,
+             risk_level, stats.
 
     Use this when:
     - Planning a refactor: understand the full call chain before changing a class

sourcecode/migrate_check.py

@@ -1402,6 +1402,11 @@ class MigrationReport:
     # exposure map, call-chain detection, upgrade-vs-rewrite verdict). Attached
     # by run_migrate_check; None when not computed.
     hibernate: Optional["HibernateStratification"] = None
+    # Regression scope behind the findings: the endpoints whose call path runs
+    # through each affected file (migration_blast.compute_migration_blast).
+    # Opt-in — attached by the CLI under --blast-radius; None when not computed,
+    # and then absent from the payload so the default report stays byte-identical.
+    blast_radius: Optional[dict] = None
 
     def finalize(self) -> "MigrationReport":
         if not self.generated_at:
@@ -1682,7 +1687,7 @@ class MigrationReport:
         return self
 
     def to_dict(self) -> dict:
-        return {
+        d: dict = {
             "schema_version": self.schema_version,
             "generated_at": self.generated_at,
             "repo_id": self.repo_id,
@@ -1718,6 +1723,11 @@ class MigrationReport:
             "limitations": self.limitations,
             "metadata": self.metadata,
         }
+        # Additive and opt-in: the key appears only when --blast-radius computed it,
+        # so a default run emits exactly the payload it emitted before.
+        if self.blast_radius is not None:
+            d["blast_radius"] = self.blast_radius
+        return d
 
     def to_compact_dict(self, top_n: int = _COMPACT_TOP_N) -> dict:
         """Bounded, decision-grade projection of `to_dict()`.
@@ -1754,6 +1764,11 @@ class MigrationReport:
                 if isinstance(h.get(_col), list):
                     h[_col] = _cap_collection(h[_col], top_n)
             compact["hibernate"] = h
+        blast = full.get("blast_radius")
+        if isinstance(blast, dict) and isinstance(blast.get("files"), list):
+            b = dict(blast)
+            b["files"] = _cap_collection(b["files"], top_n)
+            compact["blast_radius"] = b
         return compact
 
     def to_text(self, min_severity: str = "low") -> str:
@@ -1802,6 +1817,12 @@ class MigrationReport:
             lines.append(self.hibernate.to_text())
             lines.append("")
 
+        if self.blast_radius is not None:
+            from sourcecode.migration_blast import render_blast_text
+
+            lines.append(render_blast_text(self.blast_radius))
+            lines.append("")
+
         if not visible:
             lines.append("No findings at or above selected severity.")
             return "\n".join(lines)