sourcecode 3.1.0__py3-none-any.whl → 3.1.1__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.1.1"

sourcecode/cli.py

@@ -6201,6 +6201,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 +6324,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.
 
@@ -6366,6 +6437,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:

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)

sourcecode/migration_blast.py

@@ -0,0 +1,232 @@
+"""Migration blast radius — which request surface a migration finding sits under.
+
+`migrate-check` answers *what must change*: the files whose `javax.*` imports, XML
+descriptors and build coordinates block a Spring Boot 2→3 upgrade. It does not answer
+*what has to be re-tested when that change lands*, which is the question a migration
+plan is actually built around.
+
+This module answers it as a rule over the existing IR — no new detector, no second
+traversal engine. Each affected file resolves to the types it declares, those types are
+run through the same caller BFS `impact-chain` uses (`spring_impact._bfs_callers` +
+`_collect_endpoints`), and the reachable HTTP endpoints become that file's re-test set.
+
+Honesty contract:
+  * A `javax→jakarta` finding breaks compilation whether or not an endpoint reaches it.
+    `endpoints_reached` ranks *regression scope*, never "what fails to build".
+  * A file whose declared types the IR never resolved is reported in `files_unresolved`
+    with reach `unknown` — never folded into the zero-reach bucket.
+  * A repository the IR sees no endpoints in gets `request_surface_share: null` and a
+    note saying ranking fell back to caller counts, never a manufactured 0.0.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from sourcecode.spring_impact import _bfs_callers, _collect_endpoints
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+    from sourcecode.migrate_check import MigrationFinding
+    from sourcecode.spring_model import SpringSemanticModel
+
+SCHEMA_VERSION = "1.0"
+
+DEFAULT_DEPTH = 4
+DEFAULT_TOP_N = 25
+_ENDPOINTS_PER_FILE = 10
+
+_SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+_TYPE_KINDS = ("class", "interface", "enum", "annotation")
+
+_REACH_NOTE = (
+    "endpoints_reached ranks REGRESSION SCOPE — the requests whose call path runs "
+    "through the file — not what fails to build. A javax→jakarta finding breaks "
+    "compilation whether or not any endpoint reaches it."
+)
+
+
+def _types_by_file(cir: "CanonicalRepositoryIR") -> dict[str, list[str]]:
+    """Map source file → the type FQNs declared in it, from the IR's graph nodes."""
+    raw = getattr(cir, "_raw_ir", None) or {}
+    nodes = (raw.get("graph") or {}).get("nodes") or []
+    out: dict[str, list[str]] = {}
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        src = node.get("source_file") or ""
+        fqn = node.get("fqn") or ""
+        if not src or not fqn or "#" in fqn:
+            continue
+        if (node.get("symbol_kind") or node.get("type")) not in _TYPE_KINDS:
+            continue
+        out.setdefault(src, []).append(fqn)
+    for src in out:
+        out[src] = sorted(set(out[src]))
+    return out
+
+
+def _max_severity(findings: list["MigrationFinding"]) -> str:
+    return min(
+        (f.severity for f in findings),
+        key=lambda s: _SEVERITY_ORDER.get(s, 3),
+        default="low",
+    )
+
+
+def compute_migration_blast(
+    cir: "CanonicalRepositoryIR",
+    model: "SpringSemanticModel",
+    findings: list["MigrationFinding"],
+    *,
+    depth: int = DEFAULT_DEPTH,
+    top_n: int = DEFAULT_TOP_N,
+) -> dict:
+    """Resolve the request surface behind each migration finding.
+
+    Args:
+        cir:      CanonicalRepositoryIR for the same repository that was scanned.
+        model:    SpringSemanticModel built from that CIR (endpoint index).
+        findings: MigrationFinding list from `run_migrate_check`.
+        depth:    Caller BFS depth, the same knob `impact-chain --depth` exposes.
+        top_n:    Files retained in `files`; the rest are counted in `files_omitted`.
+
+    Returns a JSON-serializable dict. Never raises on a partial IR: anything it
+    could not resolve is reported as unresolved rather than dropped.
+    """
+    by_file: dict[str, list["MigrationFinding"]] = {}
+    non_source = 0
+    non_product = 0
+    for f in findings:
+        src = getattr(f, "source_file", "") or ""
+        if not src.endswith(".java"):
+            # XML descriptors and build coordinates carry no type the call graph
+            # can reach; they are counted, never ranked.
+            non_source += 1
+            continue
+        if getattr(f, "code_context", "main") != "main":
+            # Test and generated sources are outside the product blast radius, the
+            # same boundary blocking_count draws.
+            non_product += 1
+            continue
+        by_file.setdefault(src, []).append(f)
+
+    declared = _types_by_file(cir)
+    impl_graph = getattr(cir, "implementation_graph", None)
+    reverse_graph = getattr(cir, "reverse_graph", None) or {}
+    endpoints_in_repo = len(getattr(cir, "endpoints", None) or [])
+
+    rows: list[dict[str, Any]] = []
+    unresolved: list[str] = []
+    reached_ids: set[str] = set()
+
+    for src in sorted(by_file):
+        seeds = declared.get(src) or []
+        if not seeds:
+            unresolved.append(src)
+            continue
+        direct, indirect, truncated, *_rest = _bfs_callers(
+            seeds, reverse_graph, depth, impl_graph=impl_graph,
+        )
+        endpoints = _collect_endpoints(list(direct) + list(indirect), seeds, model)
+        for ep in endpoints:
+            reached_ids.add(ep.endpoint_id)
+        file_findings = by_file[src]
+        shown = sorted(
+            (e.to_dict() for e in endpoints),
+            key=lambda e: (e["path"], e["method"], e["endpoint_id"]),
+        )
+        rows.append({
+            "file": src,
+            "max_severity": _max_severity(file_findings),
+            "finding_count": len(file_findings),
+            "rule_ids": sorted({f.rule_id for f in file_findings}),
+            "types": seeds,
+            "direct_callers": len(direct),
+            "indirect_callers": len(indirect),
+            "traversal_truncated": bool(truncated),
+            "endpoints_reached": len(endpoints),
+            "endpoints": shown[:_ENDPOINTS_PER_FILE],
+            "endpoints_omitted": max(0, len(shown) - _ENDPOINTS_PER_FILE),
+        })
+
+    rows.sort(key=lambda r: (
+        -r["endpoints_reached"],
+        -(r["direct_callers"] + r["indirect_callers"]),
+        _SEVERITY_ORDER.get(r["max_severity"], 3),
+        r["file"],
+    ))
+
+    on_path = sum(1 for r in rows if r["endpoints_reached"] > 0)
+    notes: list[str] = [_REACH_NOTE]
+    if endpoints_in_repo:
+        share = round(len(reached_ids) / endpoints_in_repo, 4)
+    else:
+        share = None
+        notes.append(
+            "The IR resolved no HTTP endpoints in this repository, so no request "
+            "surface can be attributed — files are ranked by caller count alone."
+        )
+    if unresolved:
+        notes.append(
+            f"{len(unresolved)} file(s) carry a finding but declare no type the IR "
+            "resolved (parse gap or non-type source); their reach is unknown, not zero."
+        )
+    if any(r["traversal_truncated"] for r in rows):
+        notes.append(
+            "At least one traversal hit the hub-class guard and was capped — those "
+            "files' reach is a lower bound."
+        )
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "depth": depth,
+        "endpoints_in_repo": endpoints_in_repo,
+        "endpoints_reached": len(reached_ids),
+        "request_surface_share": share,
+        "files_analyzed": len(rows),
+        "files_on_request_path": on_path,
+        "files_off_request_path": len(rows) - on_path,
+        "files_unresolved": sorted(unresolved),
+        "findings_not_source": non_source,
+        "findings_not_product": non_product,
+        "files": rows[:top_n],
+        "files_omitted": max(0, len(rows) - top_n),
+        "notes": notes,
+    }
+
+
+def render_blast_text(blast: Optional[dict], *, top_n: int = 10) -> str:
+    """Render the blast-radius block as the text-format section."""
+    if not blast:
+        return ""
+    lines: list[str] = ["Migration blast radius (regression scope)"]
+    share = blast.get("request_surface_share")
+    if share is None:
+        lines.append(
+            f"  {blast.get('endpoints_in_repo', 0)} endpoints in IR — "
+            "no request surface attributable; ranked by callers."
+        )
+    else:
+        lines.append(
+            f"  {blast.get('endpoints_reached', 0)}/{blast.get('endpoints_in_repo', 0)} "
+            f"endpoints reached ({share * 100:.1f}% of the request surface)"
+        )
+    lines.append(
+        f"  Files on a request path: {blast.get('files_on_request_path', 0)}"
+        f" of {blast.get('files_analyzed', 0)} analyzed"
+        + (f"   [{len(blast.get('files_unresolved') or [])} unresolved]"
+           if blast.get("files_unresolved") else "")
+    )
+    for row in (blast.get("files") or [])[:top_n]:
+        lines.append(
+            f"  {row['endpoints_reached']:>4} endpoints  "
+            f"[{row['max_severity'].upper()}] {row['file']}  "
+            f"({row['direct_callers']}+{row['indirect_callers']} callers)"
+        )
+    omitted = blast.get("files_omitted", 0) + max(0, len(blast.get("files") or []) - top_n)
+    if omitted:
+        lines.append(f"  +{omitted} more file(s)")
+    for note in blast.get("notes") or []:
+        lines.append(f"  note: {note}")
+    return "\n".join(lines)

{sourcecode-3.1.0.dist-info → sourcecode-3.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.1.0
+Version: 3.1.1
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -139,7 +139,7 @@ The system map: module graph, dependency views, REST surface, per-class summarie
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 4 · Migration & Modernization
-Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, and an effort estimate.
+Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, an effort estimate, and — with `--blast-radius` — the endpoints whose call path runs through each blocker, so the re-test plan is ordered by regression scope.
 `ask migrate-check` · `ask modernize`
 → [migrate-check reference](docs/migrate-check.md) · [MODERNIZATION.md](docs/MODERNIZATION.md)
 
@@ -233,7 +233,7 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
 | [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml`, enforce them in the edit loop and in CI |
-| [posture.md](docs/posture.md) | What a profile set actually wires, and what could not be decided (experimental) |
+| [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — and what could not be decided (experimental) |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
 | [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |
 | [PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md) | Free vs Pro, pricing model |

{sourcecode-3.1.0.dist-info → sourcecode-3.1.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=RdGu3pDWTIDIExICX1CUTqllYPhYoeMc4ByyRDVrjIY,308
+sourcecode/__init__.py,sha256=gL2tqDxnoKJo0NZ97V-BftlhGDV-Hcty4joUrxJ6XF0,308
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=qWMCyL2UzSGXJhCIZj38JjS7wI15EE3eILsWiaoCZXQ,35779
 sourcecode/architectural_baseline.py,sha256=7QzJri4pbL3nzAn9gNutZW6mZR8HHD6H2C2H1EEwYPE,17904
@@ -14,7 +14,7 @@ sourcecode/chain_rules.py,sha256=1kLHv1t7g5rMmycIYSpm3az8SjCr01Xw7LtyV2tNhSA,106
 sourcecode/change_plan.py,sha256=MNgNyu4zrLGvBBaXPwyCh-T2ZGaUQX3Hm4W87uuhZ3w,7750
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=JBzPwSSrDG-tUHAbcKB678HRbjLpD-ohzbzzO62mgpo,20114
-sourcecode/cli.py,sha256=zLML0Qwsxa_DQICh9QZMxKk0SIxeRu80oGmW_NV6ulM,395225
+sourcecode/cli.py,sha256=d6ztendlmJIuXvXqb2uoaJmZnO_nisPmsChdJBgjycU,398039
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/compare.py,sha256=jdePg0dNCxFpysiTGMsROL5XABLjy_zVUgVeySvdb0o,7514
 sourcecode/confidence_analyzer.py,sha256=vnbPI-20FnHdjO6STxHW8fbaxmB4A7y58io63ibFZjc,21586
@@ -52,7 +52,8 @@ sourcecode/jdk_exports.py,sha256=fCrlwNAXUT9gge_joq6kMnY3zJxYB2pxqy-0w3o3MJI,874
 sourcecode/license.py,sha256=keFuwNxdAtvK2Ds91Wl79GMYxuxWYnN5Wbw1qBpaoUI,24896
 sourcecode/mcp_nudge.py,sha256=lKemOqK_wny2u7Ymcr2Idi5Kx8pXY02jCi-_nJYLGMg,2992
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
-sourcecode/migrate_check.py,sha256=07jZp8CY6GYybK67092ma_EomBsYbYt-O4jarW5HmKQ,109340
+sourcecode/migrate_check.py,sha256=TJvaShbglENOr8ikvCodnlXQy54TtT05N2ZVe02b3lc,110421
+sourcecode/migration_blast.py,sha256=5qUsUi4n0cwBKltdJYyvyfhBkGENAYjB-d_7LZtnVks,9282
 sourcecode/openapi_surface.py,sha256=BTt0K-woZbkbWTN77IkqeBm_Okag9owR0848fmot8sk,16207
 sourcecode/output_budget.py,sha256=Js9yUlfQtPhqBl9R6wn_9UHVjjJc3GtLcqyfjf5t50Q,9869
 sourcecode/parse_cache.py,sha256=IIsWhtMYpBLNyRCDVoiVpUZa62QIk1Q1sZBDNG4G4V0,6668
@@ -158,8 +159,8 @@ sourcecode/telemetry/consent.py,sha256=GuhCiA_x2n3LwGBkZnvyIwtFcf5Zwa8O0DdLqkATI
 sourcecode/telemetry/events.py,sha256=4_yeO58U-Cwc1Qb27VB0_EjhmroY0k91n3_VGxeALB8,2776
 sourcecode/telemetry/filters.py,sha256=RzxauTz8HliO4BllQnXEXc7zTeqdCZi5MgqGEDuW7OQ,6570
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-3.1.0.dist-info/METADATA,sha256=B4R07QBUVN2LdW8xLyj6ABp3wCpWDhJqCtXcv45F34s,11091
-sourcecode-3.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-3.1.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-3.1.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-3.1.0.dist-info/RECORD,,
+sourcecode-3.1.1.dist-info/METADATA,sha256=u9yY71cBQ2ZoUpQWoG78kSFzKV7LXTTuEyGIYVd3Ppk,11286
+sourcecode-3.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-3.1.1.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-3.1.1.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-3.1.1.dist-info/RECORD,,