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

sourcecode/audit_report.py

@@ -39,13 +39,19 @@ def build_audit_report(
     profiles: Optional[set[str]] = None,
     sign_key: Optional[bytes] = None,
     risk_limit: int = 10,
+    risk_payload: Optional[dict[str, Any]] = None,
 ) -> dict[str, Any]:
     """Build the buyer-readable audit bundle from existing command payloads."""
     from sourcecode.posture import build_posture
-    from sourcecode.risk import build_risk
 
     root = Path(root).resolve()
-    risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+    if risk_payload is None:
+        from sourcecode.risk import build_risk
+        risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+        risk_source = "computed"
+    else:
+        risk = risk_payload
+        risk_source = "from-risk"
     posture = build_posture(root, profiles or set())
     top_risks = risk.get("risks", [])[:risk_limit]
     access = ((posture.get("endpoints") or {}).get("effective_access") or {})
@@ -58,6 +64,7 @@ def build_audit_report(
         **({"profile_set": sorted(profiles)} if profiles else {}),
         "summary": {
             "risk_model": risk.get("model"),
+            "risk_source": risk_source,
             "total_defects": risk.get("total_defects"),
             "total_findings": risk.get("total_findings"),
             "risk_bands": risk.get("by_band", {}),
@@ -78,6 +85,18 @@ def build_audit_report(
             "non_coverage": (risk.get("non_coverage") or {}).get("items", []),
         },
     }
+    from sourcecode.provenance import build_evidence_manifest
+    unsigned["evidence_manifest"] = build_evidence_manifest(
+        unsigned,
+        command="audit-report",
+        root=root,
+        inputs={
+            "profiles": sorted(profiles) if profiles else None,
+            "risk_limit": risk_limit,
+            "risk_source": risk_source,
+            "signed": bool(sign_key),
+        },
+    )
     # Sign and publish the same JSON-normalized material. Some embedded evidence
     # may contain tuples or other JSON-coercible values; normalizing before signing
     # avoids a signature over an in-memory shape the user never receives.

sourcecode/cache_model.py

@@ -144,6 +144,12 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "repository side, so what it buys is what it buys `risk`.",
                  "not measured on the battery yet — bounded by the `risk` composition, plus "
                  "reading one JSON file"),
+    CommandCache("audit-report", ("cir", "parse"), "shared", False,
+                 "Packages `risk` and `posture` evidence. A warm helps the repository side; "
+                 "`--from-risk risk.json` skips risk recomputation entirely and only builds "
+                 "the posture/report projection.",
+                 "not measured on the battery yet — bounded by `risk` + `posture`, or by "
+                 "`posture` when `--from-risk` is supplied"),
     CommandCache("migrate-recipe", ("parse",), "shared", False,
                  "Runs the same scan as `migrate-check` and projects its findings into an "
                  "OpenRewrite recipe, so it buys exactly what a warm buys `migrate-check`: "

sourcecode/canonical_ir.py

@@ -43,6 +43,23 @@ _REVERSE_EXCLUDE: frozenset[str] = frozenset({"annotated_with", "mapped_to"})
 # the CIR endpoint count reconciles with the `endpoints` command). See BUG #7.
 _FQN_PATH_RE: re.Pattern = re.compile(r"/(org|com|net|io|edu)\.[a-z][a-z0-9]*\.[a-zA-Z]")
 
+_JAVA_RESERVED_HANDLER_NAMES: frozenset[str] = frozenset({
+    "if", "else", "for", "while", "do", "switch", "case", "break", "continue",
+    "return", "new", "throw", "try", "catch", "finally", "instanceof",
+    "this", "super", "void", "class", "interface", "enum", "extends", "implements",
+    "import", "package", "static", "final", "abstract", "synchronized", "native",
+    "true", "false", "null",
+})
+
+
+def _route_has_reserved_handler(route: dict) -> bool:
+    """Reject parser-corrupt endpoint symbols such as ``pkg.Controller#if``."""
+    symbol = str(route.get("symbol") or "")
+    if "#" not in symbol:
+        return False
+    handler = symbol.rsplit("#", 1)[1].split("(", 1)[0].strip()
+    return handler in _JAVA_RESERVED_HANDLER_NAMES
+
 
 # ---------------------------------------------------------------------------
 # CanonicalSecurity
@@ -438,6 +455,8 @@ def ir_dict_to_canonical(
     for r in route_surface:
         if r.get("scope") == "test_util":
             continue
+        if _route_has_reserved_handler(r):
+            continue
         if _FQN_PATH_RE.search(r.get("path", "") or ""):
             continue
         ep = _route_to_canonical_endpoint(r)

sourcecode/cli.py

@@ -338,14 +338,16 @@ def _build_help_text() -> str:
 Deterministic Java/Spring semantics and reusable structural context for AI coding agents.
 
 Cache warms on first scan; later calls reuse pre-built context instead of rescanning.
-Scan and warm time scale with repo size — small repos in seconds, large repos (thousands
-of files) in minutes. Semantic analysis itself is sub-second; repo indexing dominates.
+Performance depends on command class and repo size: per-symbol queries are the fast path,
+inventory commands scale with files, and repo-wide/deep compositions can take
+minutes on multi-thousand-endpoint repositories. Use deep jobs nightly or with
+ASK_MAX_ANALYSIS_SECONDS/ASK_PROGRESS when CI needs an explicit budget.
 
 [bold]Start here — Java/Spring analysis:[/bold]
   posture . --diff dev:prod    [dim]# effective access, two profile sets (exp.)[/dim]
   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]
+  migrate-check . --compact    [dim]# Boot 2→3 + Java LTS/licensing inventory[/dim]
   risk .                       [dim]# defects ranked by reach × access (exp.)[/dim]
 
 {_remedy_help_block()}
@@ -881,9 +883,24 @@ def _enforce_format(command: str, fmt: str) -> None:
 
 
 def _safe_write_file(path: "Path", content: str) -> None:
-    """Write content to path, emitting a clean JSON error on I/O failure."""
+    """Atomically write content to path, emitting a clean JSON error on I/O failure."""
     try:
-        path.write_text(content, encoding="utf-8")
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(f".{path.name}.tmp-{os.getpid()}-{time.time_ns()}")
+        tmp.write_text(content, encoding="utf-8")
+        tmp.replace(path)
+        try:
+            from sourcecode.runs import active_run
+            run = active_run()
+            if run is not None:
+                run.write(
+                    status="running",
+                    output_path=path,
+                    output_size=path.stat().st_size,
+                )
+        except Exception:
+            pass
     except OSError as _exc:
         _emit_error_json(
             INVALID_INPUT_CODE,
@@ -968,6 +985,50 @@ def _active_command_context() -> "tuple[str, Optional[Path]]":
 
 
 _EXPENSIVE_ANALYSIS_TTL_SECONDS = 6 * 60 * 60
+_ANALYSIS_CLASSES: dict[str, tuple[str, int, str]] = {
+    "spring-audit": ("repo-wide", 600, "use nightly/deep tier on large repositories"),
+    "risk": ("deep", 1200, "run `ask spring-audit` or a saved `risk.json` first"),
+    "audit-report": ("deep", 1200, "reuse `--from-risk risk.json` or schedule nightly"),
+    "verify --init": ("repo-wide", 600, "derive contracts outside pre-commit"),
+    "verify": ("core", 60, "run with a larger CI budget or narrow the contract set"),
+    "migrate-check": ("repo-wide", 600, "run inventory in CI and deep migration checks nightly"),
+}
+
+
+def _analysis_budget(command: str) -> dict[str, Any]:
+    cls, recommended, fallback = _ANALYSIS_CLASSES.get(
+        command, ("repo-wide", 600, "run this command in a supervised or nightly job")
+    )
+    configured: Optional[float] = None
+    raw = os.environ.get("ASK_MAX_ANALYSIS_SECONDS")
+    if raw:
+        try:
+            configured = float(raw)
+        except ValueError:
+            configured = None
+    return {
+        "class": cls,
+        "recommended_min_seconds": recommended,
+        "configured_max_seconds": configured,
+        "fallback": fallback,
+    }
+
+
+def _enforce_analysis_budget(command: str, budget: dict[str, Any]) -> None:
+    configured = budget.get("configured_max_seconds")
+    recommended = float(budget.get("recommended_min_seconds") or 0)
+    if configured is None or float(configured) >= recommended:
+        return
+    _emit_error_json(
+        INVALID_INPUT_CODE,
+        (
+            f"{command} is a {budget.get('class')} analysis and the configured "
+            f"budget ({configured:g}s) is below its safe floor ({recommended:g}s)."
+        ),
+        hint=str(budget.get("fallback") or "raise ASK_MAX_ANALYSIS_SECONDS"),
+        expected=f"ASK_MAX_ANALYSIS_SECONDS >= {recommended:g}",
+    )
+    raise typer.Exit(code=2)
 
 
 def _analysis_lock_path(path: Path) -> Path:
@@ -1051,8 +1112,14 @@ def _emit_analysis_contention_warning(command: str, path: Path, phase: str) -> N
 @contextlib.contextmanager
 def _expensive_analysis_scope(command: str, path: Path, phase: str):
     """Register a long repository-wide analysis and warn on concurrent runs."""
+    from sourcecode.runs import RunRecord, reset_active_run, set_active_run
+
     lock_path = _analysis_lock_path(path)
     _emit_analysis_contention_warning(command, path, phase)
+    budget = _analysis_budget(command)
+    _enforce_analysis_budget(command, budget)
+    run_record = RunRecord.start(path, command, phase, budget=budget)
+    run_token = set_active_run(run_record)
     token = f"{os.getpid()}:{time.time_ns()}"
     owns_lock = False
     if _active_analysis_record(lock_path) is None:
@@ -1077,6 +1144,12 @@ def _expensive_analysis_scope(command: str, path: Path, phase: str):
             owns_lock = False
     try:
         yield
+        if run_record is not None:
+            run_record.write(status="complete", exit_code=0)
+    except BaseException as exc:
+        if run_record is not None:
+            run_record.write(status="failed", exit_code=1, error=str(exc))
+        raise
     finally:
         if owns_lock:
             try:
@@ -1088,6 +1161,7 @@ def _expensive_analysis_scope(command: str, path: Path, phase: str):
                     lock_path.unlink()
                 except OSError:
                     pass
+        reset_active_run(run_token)
 
 
 def _emit_command_output(
@@ -3875,6 +3949,11 @@ def prepare_context_cmd(
       ask prepare-context review-pr . --since main --output review.json
       ask prepare-context onboard --llm-prompt
       ask prepare-context --task-help
+
+    \b
+    Provenance:
+      JSON output includes evidence_manifest: claim IDs for context files and
+      source-backed rows, plus command inputs, ASK version, git HEAD and freshness.
     """
     from sourcecode.prepare_context import TASKS, TaskContextBuilder
 
@@ -4419,6 +4498,20 @@ def prepare_context_cmd(
             _skipped.append("test_gap_discovery")
         out["skipped_analyzers"] = _skipped
 
+    from sourcecode.provenance import build_evidence_manifest as _build_evidence_manifest
+    out["evidence_manifest"] = _build_evidence_manifest(
+        out,
+        command="prepare-context",
+        root=target,
+        inputs={
+            "task": task,
+            "since": since,
+            "format": format or "json",
+            "fast": fast,
+            "llm_prompt": llm_prompt,
+        },
+    )
+
     # P0-1: Apply output budget per task — safety net for large repos.
     _pc_budget = _prepare_context_budget(task)
 
@@ -8007,6 +8100,11 @@ def audit_report_cmd(
     format: str = typer.Option(
         "json", "--format", "-f", help="Output format: json, yaml or markdown."
     ),
+    from_risk: Optional[Path] = typer.Option(
+        None,
+        "--from-risk",
+        help="Reuse an existing `ask risk -o risk.json` payload instead of recomputing risk.",
+    ),
     copy: bool = _copy_option(),
 ) -> None:
     """[EXPERIMENTAL] Human audit bundle over existing ASK evidence, optionally signed.
@@ -8015,7 +8113,8 @@ def audit_report_cmd(
     This packages the same evidence `risk` and `posture` already publish into a
     report a buyer can read: top risks, effective runtime posture, source-linked
     evidence and non-coverage. It does not certify compliance, choose fixes or
-    assign ROI.
+    assign ROI. JSON includes evidence_manifest: claim IDs mapped to source spans,
+    command inputs, ASK version and freshness.
 
     \b
     `--sign-key` adds an HMAC-SHA256 signature over the canonical JSON payload.
@@ -8024,6 +8123,7 @@ def audit_report_cmd(
     \b
     Examples:
       ask audit-report .
+      ask risk . -o risk.json && ask audit-report . --from-risk risk.json
       ask audit-report . --profile prod --format markdown
       ask audit-report . --sign-key audit.key -o audit-report.json
     """
@@ -8059,12 +8159,42 @@ def audit_report_cmd(
                 expected="a non-empty key file",
             )
             raise typer.Exit(code=1)
+    risk_payload = None
+    if from_risk is not None:
+        risk_path = Path(from_risk).expanduser()
+        if not risk_path.is_file():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--from-risk must name a readable risk JSON file (got {str(from_risk)!r}).",
+                hint="Example: ask risk . -o risk.json && ask audit-report . --from-risk risk.json",
+                expected="an existing JSON file produced by `ask risk`",
+            )
+            raise typer.Exit(code=1)
+        try:
+            risk_payload = json.loads(risk_path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--from-risk is not valid JSON: {exc}",
+                hint="Regenerate it with: ask risk . -o risk.json",
+                expected="a JSON object produced by `ask risk`",
+            )
+            raise typer.Exit(code=1)
+        if not isinstance(risk_payload, dict) or "risks" not in risk_payload:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                "--from-risk does not look like an `ask risk` payload.",
+                hint="Regenerate it with: ask risk . -o risk.json",
+                expected="a JSON object with a `risks` array",
+            )
+            raise typer.Exit(code=1)
 
     _prog = Progress()
     _prog.start("packaging audit evidence")
     try:
         data = build_audit_report(
             path, profiles=_profile_set(profile), sign_key=key_bytes,
+            risk_payload=risk_payload,
         )
     finally:
         _prog.stop()
@@ -8724,9 +8854,9 @@ def migrate_check_cmd(
         None,
         "--target-jdk",
         help=(
-            "The JDK you are actually moving to (e.g. 11, 17, 21). Rules for a "
-            "later JDK are not your blockers and are not reported. Without it, "
-            "every JDK axis is reported at once."
+            "The JDK you are actually moving to (e.g. 11, 17, 21, 25). Rules "
+            "for a later JDK are not your blockers and are not reported. Also "
+            "sets java_lts_inventory.target_lts."
         ),
     ),
     keep_boot: bool = typer.Option(
@@ -8786,7 +8916,7 @@ def migrate_check_cmd(
         help="Caller BFS depth for --blast-radius (1-8, default: 4).",
     ),
 ) -> None:
-    """Spring Boot 2→3 migration readiness: detect javax→jakarta namespace blockers.
+    """Spring Boot 2→3 migration readiness + Java LTS/licensing inventory.
 
     \b
     Detects:
@@ -8815,6 +8945,7 @@ def migrate_check_cmd(
       ask migrate-check . --compact          bounded decision summary
       ask migrate-check /path/to/repo --format text
       ask migrate-check . --min-severity high
+      ask migrate-check . --target-jdk 25       Java LTS target inventory
       ask migrate-check . --table --rule MIG-001 --band critical --top-n 20
       ask migrate-check . --output migration.json
       ask migrate-check . --snapshot --ref sprint-12   persist a readiness point
@@ -8837,6 +8968,13 @@ def migrate_check_cmd(
       <repo>/.ask/readiness-history). --trend reads that series and reports
       first→last movement — no improving/degrading label, and readiness_score is
       flagged not-comparable when the applicable dimension set changed.
+
+    \b
+    Java LTS/licensing inventory:
+      The JSON report includes java_lts_inventory: Java 8/11/17/21/25 evidence
+      from Maven/Gradle, local runtime hints and container files; target-LTS
+      blockers; and explicit Oracle JDK/licensing-review signals. This is
+      inventory evidence, not legal advice, and it never changes readiness_score.
     """
     from sourcecode.repository_ir import find_java_files
     from sourcecode.migrate_check import run_migrate_check