sourcecode 3.1.0__tar.gz → 3.1.1__tar.gz

{sourcecode-3.1.0 → sourcecode-3.1.1}/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- **`migrate-check --blast-radius` states the regression scope behind each blocker.** The
+  finding list says what must change; a migration plan is built around what has to be
+  re-tested when that change lands. Each affected product file now resolves to the types
+  it declares and runs through the same caller traversal `impact-chain` uses, so the
+  block reports the HTTP endpoints whose call path passes through it, ranked. Measured on
+  BroadleafCommerce: 62.3% of the request surface (137 of 220 endpoints) runs through a
+  file with a finding, and 52 of the 166 affected files carry all of it. Implemented as a
+  rule over the existing IR — no new detector, ~3 ms per affected file on top of an IR
+  build shared with `impact-chain` / `explain` through the context cache.
+  - Reach is regression scope, never build breakage: a `javax→jakarta` finding fails
+    compilation whether or not any endpoint reaches it, and the payload says so.
+  - Unresolved is not zero — a file whose declared types the IR never resolved is listed
+    in `files_unresolved` with reach *unknown*.
+  - A repository the IR resolves no endpoints in (alfresco's webscript framework,
+    openmrs-core) gets `request_surface_share: null` and a note that ranking fell back to
+    caller counts, never a manufactured `0.0`.
+  - Opt-in and additive: without the flag the report is byte-identical to before, and the
+    key is absent rather than `null`.
+
+## [3.1.1] — 2026-07-28
+
+Documentation only; no behaviour changed.
+
+- **`contracts.md` gains an enforcement-maturity section**: which contract kinds have been
+  run against real code and with what result, the one false block found and fixed (a
+  fully-qualified security annotation reading as no guard, 3.1.0), and what is still
+  unproven — the GitHub Actions workflow has never run in a hosted runner. Plus a
+  three-week rollout that starts advisory (`--fail-on never`), because a contract whose
+  first act is blocking a merge gets deleted.
+- **`migrate-check.md` documents the output-size guard** added in 3.1.0: the measured
+  sizes that motivated it, the emitted `OUTPUT_TOO_LARGE` payload, and the four ways past
+  it in the order worth trying.
+- Doc-accuracy tests cover the new claims: the rollout flags exist, every documented
+  contract kind is implemented, and the quoted guard hint is the one the code emits.
+
 ## [3.1.0] — 2026-07-28
 
 **Posture answers about requests, not only about beans.** Milestone M4 of the strategic

{sourcecode-3.1.0 → sourcecode-3.1.1}/PKG-INFO

@@ -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 → sourcecode-3.1.1}/README.md

@@ -101,7 +101,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)
 
@@ -195,7 +195,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 → sourcecode-3.1.1}/pyproject.toml

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

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

{sourcecode-3.1.0 → sourcecode-3.1.1}/src/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-3.1.0 → sourcecode-3.1.1}/src/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-3.1.1/src/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)