sourcecode 3.8.0__py3-none-any.whl → 4.0.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.8.0"
+__version__ = "4.0.1"

sourcecode/cache.py

@@ -354,6 +354,7 @@ def status(repo_root: Path) -> dict[str, Any]:
             "cores": 0, "snapshots": 0, "views": 0, "cas_blobs": 0,
             "total_size_bytes": 0, "total_size_mb": 0.0,
             "current_git_head": current_head,
+            "stores": _store_breakdown(repo_root, 0),
             **ris_fields,
         }
     cores = list(cache_d.glob("core-*.json.gz"))
@@ -371,10 +372,57 @@ def status(repo_root: Path) -> dict[str, Any]:
         "total_size_bytes": total_bytes,
         "total_size_mb": round(total_bytes / (1024 * 1024), 2),
         "current_git_head": current_head,
+        # C3-36: `CAS blobs: 0`, `Total size: 0.1 MB` immediately after an 89-second
+        # warm of 3 342 files. Every figure above was true and described one store
+        # of three — the warm's output mostly lands in the shared CIR and the parse
+        # cache, which this command never counted. A status that reports a third of
+        # the state reads as a warm that did nothing.
+        "stores": _store_breakdown(repo_root, total_bytes),
         **ris_fields,
     }
 
 
+def _store_breakdown(repo_root: Path, core_bytes: int) -> "dict[str, Any]":
+    """What a warm actually populated, by store. Best-effort per store: a store
+    that cannot be inspected is reported as unavailable, never as empty."""
+    out: "dict[str, Any]" = {
+        "core": {
+            "cache_dir": str(cache_dir(repo_root)),
+            "bytes": core_bytes,
+            "scope": "this repository",
+            "holds": "core snapshots, rendered views and their CAS blobs",
+        },
+    }
+    try:
+        from sourcecode.context_cache import ContextCache  # noqa: PLC0415
+
+        ctx = ContextCache.for_repo(repo_root).stats()
+        out["shared_cir"] = {
+            "cache_dir": ctx["cache_dir"],
+            "entries": ctx["contexts"],
+            "bytes": ctx["bytes_stored"],
+            "scope": "this repository",
+            "holds": "the shared Canonical IR that explain/impact/posture reuse",
+        }
+    except Exception:
+        out["shared_cir"] = {"available": False}
+    try:
+        from sourcecode import parse_cache as _pc  # noqa: PLC0415
+
+        out["parse"] = {
+            **_pc.store_stats(),
+            "holds": "per-file parses, content-addressed across every repository",
+        }
+    except Exception:
+        out["parse"] = {"available": False}
+    out["note"] = (
+        "`cache warm` populates all of these; the core store alone is a third of "
+        "the answer, and reading it as the whole is how a completed warm looks like "
+        "an empty cache."
+    )
+    return out
+
+
 def clear(repo_root: Path, *, clear_ris: bool = False) -> int:
     """Delete cache files for *repo_root*.  Returns the number of files removed.
 

sourcecode/cache_model.py

@@ -131,6 +131,13 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "builds — the parse it used to repeat for itself. `--diff` compares two profile "
                  "sets over that one IR, so the second side costs the resolution only.",
                  "10.1 s → 1.6 s"),
+    CommandCache("risk", ("cir", "parse"), "shared", False,
+                 "Composes what the audit, impact-chain and the posture already answer, so it "
+                 "pays each of their costs once over the shared CIR a warm builds — one parse "
+                 "for the whole composition, and the reachability query is cached per symbol "
+                 "within the run.",
+                 "not measured on the battery yet — the composition is bounded by the "
+                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis"),
     CommandCache("endpoints", ("ris", "parse"), "shared", False,
                  "Recomputes the endpoint surface on every run, over a parse a warm has already "
                  "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "

sourcecode/cli.py

@@ -183,7 +183,7 @@ COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
         "cache", "auth", "mcp", "telemetry",
     )),
     ("experimental", "shape may change in a minor — do not gate CI on it", (
-        "posture", "archetype",
+        "risk", "posture", "archetype",
     )),
     # `retrieve` publishes 15+ intents whose answers the other commands already
     # give better: measured on the battery, `security-surface` merely re-states
@@ -297,6 +297,27 @@ def _group_help_block() -> str:
     return "\n".join(lines)
 
 
+def _remedy_help_block() -> str:
+    """The front page names the answers the field asked for as missing features.
+
+    C4-8 was closed in the payload: a limitation now carries the invocation that
+    resolves it. But the evaluator who wrote `ask posture --provenance` and `ask
+    contracts init` by hand was reading `--help` first, and neither shipped flag
+    was on it. The block is rendered from `remedies.REMEDIES`, so the pointer and
+    the capability cannot drift — `tests/test_remedies.py` already refuses a
+    remedy whose option the CLI does not accept.
+    """
+    from sourcecode.remedies import headlines
+
+    lines = ["[bold]Questions the repository alone does not answer:[/bold]"]
+    for invocation, headline in headlines():
+        # Bare invocation, like every other block on this page: the header panels
+        # print without the `ask ` prefix (C3-16).
+        bare = invocation.removeprefix("ask ")
+        lines.append(f"  {bare:<33}[dim]# {headline}[/dim]")
+    return "\n".join(lines)
+
+
 def _build_help_text() -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -323,6 +344,9 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
   endpoints .                  [dim]# endpoints + effective path + policy[/dim]
   spring-audit .               [dim]# TX anomalies + security surface[/dim]
   migrate-check . --compact    [dim]# Boot 2→3: located blockers + effort[/dim]
+  risk .                       [dim]# defects ranked by reach × access (exp.)[/dim]
+
+{_remedy_help_block()}
 
 [bold]Agent context:[/bold]
   ask --compact                [dim]# high-signal summary (~2,500–4,000 tokens)[/dim]
@@ -5475,11 +5499,21 @@ def validation_cmd(
     # The payload carries the same note, so a pipeline loses nothing.
     if _note:
         _notice(f"Note: {_note}")
+    # C2-15: the console said "0 body endpoints, 1179 gaps" over a payload carrying
+    # `body_endpoints_in_code: 1201` — it printed the *declared-constraint* count
+    # under the *code-surface* name, so the one line most readers see stated the
+    # opposite of the answer. Both axes are named, in their own units.
+    _declared = _summary.get("endpoints_with_body", 0)
+    _in_code = _summary.get("body_endpoints_in_code")
+    _bodies = (
+        f"{_in_code} body endpoints in code, {_declared} with a declared constraint "
+        f"surface" if _in_code is not None
+        else f"{_declared} routes with a declared constraint surface"
+    )
     _emit_command_output(
         output, output_path, copy,
         success_msg=f"Validation surface written to {output_path} "
-        f"({_summary.get('endpoints_with_body', 0)} body endpoints, "
-        f"{_summary.get('gaps', 0)} gaps)",
+        f"({_bodies}, {_summary.get('gaps', 0)} gaps)",
     )
 
     from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
@@ -6308,11 +6342,13 @@ 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("endpoints_not_carrying_gate", gc.get("not_carrying_gate", 0))
+    not_covered = gc.get("endpoints_not_carrying_gate", 0)
     gates = ", ".join(f"`{g}`" for g in gc.get("gate_annotations", [])) or "the detected gate"
     # 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))
+    # C2-14: read only the explicit keys — falling back to the retired aliases is how
+    # a name that lies about its unit survives its own removal.
+    total = gc.get("endpoints_total", 0)
     lines: list[str] = ["", "---", ""]
     if not_covered == 0:
         _gated = gc.get("endpoints_carrying_gate", total)
@@ -6326,7 +6362,6 @@ def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  #
             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} endpoints do not carry "
@@ -6338,9 +6373,18 @@ def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  #
             f"standard guard, {not_covered} on neither — the three sum to {total}._"
         )
     if gc.get("reconstructed_filter_patterns"):
+        # C1-20: the split, not the total. "N match a filter pattern" is the sentence
+        # a reader turns into "N are covered", and in the field the filters doing the
+        # matching were CORS, headers and logging.
+        _auth = gc.get("filter_covered_authenticating", 0)
+        _gap = gc.get("filter_gap_non_authenticating", 0)
+        _unknown = gc.get("filter_authentication_unknown", 0)
         lines.append(
-            f"_{covered} of those match a reconstructed servlet filter pattern "
-            f"(possibly filter-covered); {gc.get('no_matching_filter_pattern', 0)} match none._"
+            f"_{_auth} are covered by a servlet filter that authenticates; {_gap} match "
+            f"only filters that do not check the caller (CORS, headers, logging and the "
+            f"like); {_unknown} match a filter whose implementation is not in this "
+            f"repository; {gc.get('no_matching_filter_pattern', 0)} match no pattern at "
+            f"all. Filter-chain order is not reconstructed._"
         )
     lines += ["", "<details>", "<summary>Handlers without the gate</summary>", ""]
     lines += [
@@ -6418,19 +6462,11 @@ def spring_audit_cmd(
         help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
-    """Spring semantic audit: TX anomalies (TX-001..006) + security surface (SEC-001..003).
+    """Spring semantic audit: {{RULE_SUMMARY}}.
 
     \b
     Detects:
-      TX-001  @Transactional on private/final method (CGLIB proxy bypass)
-      TX-002  REQUIRES_NEW nested in REQUIRED call chain
-      TX-003  readOnly=true boundary propagating to write operation
-      TX-004  NOT_SUPPORTED/NEVER within active TX chain
-      TX-005  Exception swallowing inside @Transactional
-      TX-006  Self-invocation of @Transactional sibling (proxy bypass)
-      SEC-001 Unsecured endpoint in annotation_based security model
-      SEC-002 CVE-2025-41248: @PreAuthorize on inherited method from generic supertype
-      SEC-003 @Transactional on @Controller/@RestController (TX in wrong layer)
+{{RULE_LIST}}
 
     \b
     Findings and defects are two counts, both published. A rule fires per
@@ -6462,10 +6498,7 @@ def spring_audit_cmd(
     \b
     What it does not look at (the whole list is in the payload's `non_coverage`,
     and in the README):
-      NC-001  whether request input reaches a sink — no dataflow or taint
-      NC-002  secrets outside Java and Spring configuration
-      NC-003  filter-chain ORDER — a custom filter's presence is structural only
-      NC-004  known vulnerabilities in dependencies — no CVE matching
+{{NON_COVERAGE}}
     Silence about those is not evidence that there is nothing to find.
 """
     import json as _json
@@ -6567,6 +6600,30 @@ def spring_audit_cmd(
         raise typer.Exit(code=1)
 
 
+def _render_audit_help(doc: str) -> str:
+    """Fill the rule and non-coverage blocks from the tables that own them.
+
+    The rules this command detects were written out by hand in its own help, and
+    stayed at `SEC-001..003` for two releases after CL-9 shipped three more — the
+    C4-1 shape, where a curated list beside a generated one drifts and the
+    curated one is what the reader gets. Both blocks are rendered now, so adding
+    a rule updates the help by construction.
+    """
+    from sourcecode import non_coverage, rule_catalog
+
+    nc_lines = [
+        f"      {line}" for line in non_coverage.render_help_lines("security_surface", width=68)
+    ]
+    return (
+        doc.replace("{{RULE_SUMMARY}}", rule_catalog.summary_line())
+        .replace("{{RULE_LIST}}", rule_catalog.render_help_block())
+        .replace("{{NON_COVERAGE}}", "\n".join(nc_lines))
+    )
+
+
+spring_audit_cmd.__doc__ = _render_audit_help(spring_audit_cmd.__doc__ or "")
+
+
 # ── verify-edit: in-loop semantic diff gate ───────────────────────────────────
 
 
@@ -6840,6 +6897,74 @@ def verify_cmd(
         raise typer.Exit(code=report.exit_code)
 
 
+@app.command("risk")
+def risk_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory).",
+    ),
+    limit: int = typer.Option(
+        50, "--limit", help="How many composed risks to publish (highest first)."
+    ),
+    min_band: str = typer.Option(
+        "low",
+        "--min-band",
+        help="Floor on the composed band: critical | high | medium | low.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the report to a file instead of stdout."
+    ),
+    format: str = typer.Option("json", "--format", "-f", help="Output format: json or yaml."),
+) -> None:
+    """[EXPERIMENTAL] What each defect actually costs, once reach and access are in it.
+
+    \b
+    The other commands answer one axis each, correctly, and leave the composition
+    to the reader. In the field, one class was `medium` in `spring-audit`,
+    `medium/5.0` in `impact-chain`, `coverage_unknown → permit_all` in `posture`,
+    and executed a stored procedure that mutates the database. Composed, that is
+    unauthenticated write access under the release build; separately, it was two
+    commands saying "medium".
+
+    \b
+      severity_effective = defect_severity × reachability × auth_verdict × write_effect
+
+    \b
+    No new analysis: every factor is read from the command that already publishes
+    it, and every row publishes its four factors with the authority each came
+    from, so a reader can disagree with one and keep the rest. An axis that could
+    not be measured is `unknown`, multiplies by 1.0, and is named in `blind_axes`.
+
+    \b
+    Examples:
+      ask risk .
+      ask risk . --min-band high
+      ask risk . --limit 10 -o risk.json
+    """
+    from sourcecode.risk import build_risk
+
+    path = _admit_path(path)
+    if min_band not in ("critical", "high", "medium", "low"):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"--min-band expects critical | high | medium | low (got {min_band!r}).",
+            hint="Example: --min-band high",
+            expected="critical|high|medium|low",
+        )
+        raise typer.Exit(code=1)
+
+    data = build_risk(path, limit=limit, min_band=min_band)
+    _emit_command_output(
+        _serialize_dict(data, format),
+        output_path,
+        False,
+        success_msg=(
+            f"risk written to {output_path} ({data['shown']} of "
+            f"{data['total_defects']} defects composed)"
+        ),
+    )
+
+
 @app.command("posture")
 def posture_cmd(
     path: Path = typer.Argument(
@@ -9969,6 +10094,20 @@ def cache_status_cmd(
         typer.echo(f"Views:       {stats['views']}")
         typer.echo(f"CAS blobs:   {stats['cas_blobs']}")
         typer.echo(f"Total size:  {stats['total_size_mb']} MB")
+        # C3-36: the three lines above describe ONE of the three stores a warm
+        # fills. Printed alone after an 89 s warm they read as "nothing was
+        # cached", which is the opposite of what happened.
+        _stores = stats.get("stores") or {}
+        for _label, _key in (("Shared CIR", "shared_cir"), ("Parse cache", "parse")):
+            _store = _stores.get(_key) or {}
+            if not _store or _store.get("available") is False:
+                typer.echo(f"{_label + ':':<13}unavailable")
+                continue
+            _mb = round(_store.get("bytes", 0) / (1024 * 1024), 2)
+            _scope = " (shared across repositories)" if _store.get("scope") == "shared" else ""
+            typer.echo(
+                f"{_label + ':':<13}{_store.get('entries', 0)} entries, {_mb} MB{_scope}"
+            )
         # RIS section
         if stats.get("ris_exists"):
             _stale_tag = " [STALE]" if stats.get("ris_is_stale") else ""
@@ -10326,7 +10465,7 @@ HELP_PANELS: "tuple[tuple[str, tuple[str, ...]], ...]" = (
         "cache", "auth", "mcp", "telemetry", "baseline",
     )),
     ("Experimental — shape may change", (
-        "archetype", "retrieve",
+        "risk", "archetype", "retrieve",
     )),
 )
 

sourcecode/confidence_analyzer.py

@@ -343,9 +343,14 @@ class ConfidenceAnalyzer:
                 gaps.append(AnalysisGap(
                     area="testing",
                     reason=(
+                        # C1-19: "Java files" here has always meant the non-test ones
+                        # — the denominator of a test ratio cannot include the tests.
+                        # Unqualified, it read as a third file count contradicting
+                        # `migrate-check.java_files_scanned` (which counts them all).
                         f"Backend test coverage critical: {len(_java_tests)} test files "
-                        f"for {len(_java_prod)} Java files "
-                        f"({_ratio:.1%}) — {_java_test_facts.basis}"
+                        f"for {len(_java_prod)} non-test Java files "
+                        f"(of {len(_java_all)} Java files, {_ratio:.1%}) — "
+                        f"{_java_test_facts.basis}"
                     ),
                     impact="high",
                 ))

sourcecode/defect_identity.py

@@ -93,6 +93,25 @@ def assign_defect_ids(findings: "Iterable[SpringFinding]") -> None:
         finding.defect_id = make_defect_id(category, kind, symbol)
 
 
+def _witness_sites(witnesses: "list[SpringFinding]") -> "dict[str, Any]":
+    """The distinct places this defect was observed, when the witnesses record one."""
+    sites: "list[dict[str, Any]]" = []
+    seen: "set[tuple[str, Any]]" = set()
+    for finding in witnesses:
+        site = (finding.evidence or {}).get("call_site")
+        if not isinstance(site, dict):
+            continue
+        key = (str(site.get("source_file") or ""), site.get("line"))
+        if key in seen:
+            continue
+        seen.add(key)
+        sites.append(site)
+    if not sites:
+        return {}
+    sites.sort(key=lambda s: (str(s.get("source_file") or ""), s.get("line") or 0))
+    return {"witness_sites": sites, "distinct_site_count": len(sites)}
+
+
 def group_by_defect(findings: "list[SpringFinding]") -> list[dict[str, Any]]:
     """One row per defect, most severe first, each naming its witnesses.
 
@@ -137,6 +156,11 @@ def group_by_defect(findings: "list[SpringFinding]") -> list[dict[str, Any]]:
             "rule_ids": sorted({f.pattern_id for f in witnesses}),
             "witness_count": len(witnesses),
             "witnesses": [f.id for f in witnesses],
+            # C2-16: witnesses of one defect are all located at the symbol that
+            # carries the remedy, so several of them print the same line and read
+            # as duplicates. Where each was actually observed is listed here, and
+            # a count of distinct sites so "N witnesses" can be checked against it.
+            **_witness_sites(witnesses),
         })
     rows.sort(key=lambda r: (SEVERITY_RANK.get(r["severity"], 9), r["symbol"]))
     return rows

sourcecode/environment_resolution.py

@@ -209,7 +209,7 @@ def collect_signals(root: Path) -> list[Signal]:
         if _PROPERTY_KEY not in text and _ENV_KEY not in text:
             continue
         try:
-            rel = str(path.relative_to(root))
+            rel = path.relative_to(root).as_posix()
         except ValueError:
             rel = str(path)
         lines = text.splitlines()