sourcecode 4.9.0__tar.gz → 4.10.0__tar.gz

{sourcecode-4.9.0 → sourcecode-4.10.0}/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [4.10.0] — 2026-08-05
+
+### Fixed
+
+- **Canonical endpoint projection rejects parser-corrupt Java handler names.**
+  Reserved Java keywords such as `if` can no longer reach CIR/risk as synthetic
+  handler symbols.
+- **`DEAD-001` reports commented Java security annotations.** Java comments that
+  contain Spring/Jakarta/custom security annotations are now treated as disabled
+  controls, while active annotations stay out of dead-code findings.
+- **`SEC-007` reports JavaMelody descriptor credentials.** `authorized-users`
+  values in deployment descriptors are detected and redacted even when they are
+  not written as `{SHA-*}` digest literals.
+- **`audit-report` can reuse existing risk evidence.** `--from-risk risk.json`
+  packages a previous `ask risk` payload instead of recomputing repo-wide risk.
+- **Long analysis observability improved.** `ASK_PROGRESS=1` enables non-TTY
+  heartbeat lines, long commands write durable `.ask/runs` records, and file
+  outputs are written atomically.
+- **Large-repo CI budgets are explicit.** `ASK_MAX_ANALYSIS_SECONDS` can fail a
+  repo-wide/deep command before work starts when the configured budget is below
+  the command's safe floor.
+
+### Documentation
+
+- README, user guide and root `ask --help` now distinguish per-symbol,
+  inventory and repo-wide/deep command costs instead of treating cache
+  benchmarks as universal runtime promises.
+
+## [4.9.1] — 2026-08-04
+
+### Added
+
+- **Java LTS/licensing inventory in `migrate-check`.** Reports Java 8/11/17/21/25
+  evidence from Maven/Gradle, local runtime hints and container files, target-LTS
+  blockers via `--target-jdk`, and explicit Oracle JDK licensing-review signals
+  without changing migration readiness scoring.
+- **Claim provenance ledger.** `risk`, `enrich`, `migrate-check`, `audit-report`
+  and `prepare-context` now emit `evidence_manifest` with stable claim IDs,
+  source paths/lines, command inputs, ASK version, git HEAD and freshness metadata.
+
 ## [4.9.0] — 2026-08-04
 
 ### Added

{sourcecode-4.9.0 → sourcecode-4.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.9.0
+Version: 4.10.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.9.0-blue)
+![Version](https://img.shields.io/badge/version-4.10.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -54,9 +54,9 @@ Description-Content-Type: text/markdown
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. For a large Java or TypeScript monolith, that means 5–15 seconds per invocation. Multiply by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
-ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, every subsequent invocation returns pre-built context in milliseconds. The repo doesn't change? The cache doesn't expire.
+ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, later invocations reuse pre-built context whenever their command can consume the warmed layers. The repo doesn't change? The cache doesn't expire.
 
 **The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
 
@@ -69,9 +69,11 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-Cache keyed on content hashes — invalidated only when source changes. On repeated agent sessions against the same codebase, nearly every invocation is a cache hit.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
 
-At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
+With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
+
+**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY supervised runs. Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep command whose configured budget is below its safe floor. Use `ask audit-report --from-risk risk.json` to package an existing risk run instead of recomputing it.
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
 shared structural layers (L1/L2 + the Repository Intelligence Snapshot + the shared Canonical
@@ -97,7 +99,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.9.0 — and, on a build that has aged,
+ask version                    # ask 4.10.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -137,8 +139,9 @@ ask endpoints /path/to/repo
 # CGLIB no-op), security surface, request-body validation.
 ask spring-audit /path/to/repo
 
-# Spring Boot 2→3 readiness: located blockers, per-dimension score, effort estimate.
+# Spring Boot 2→3 readiness plus Java LTS/licensing inventory.
 ask migrate-check /path/to/repo --compact
+# Add --target-jdk 25 to make the LTS route explicit.
 ```
 
 **Then the three that finish the sentence the four above start.** A profile-set answer stays
@@ -308,12 +311,12 @@ from it.
 | `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
 | `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
 | `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
-| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
+| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
 | `migrate-recipe` | experimental | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
 | `data-exposure` | experimental | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls |
 | `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
-| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
+| `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
 | `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
@@ -401,6 +404,16 @@ and that gap is the honest description, not a defect to argue with. `migrate-che
 the OpenRewrite recipe each finding carries so the executor that does apply changes has its
 input.
 
+**Java LTS/licensing inventory.** `migrate-check` emits `java_lts_inventory` beside the migration
+scores. It reads Maven/Gradle, local runtime hints and container files for Java 8/11/17/21/25
+evidence, reports target-LTS blockers with `--target-jdk`, and marks explicit Oracle JDK evidence
+as `licensing_review_needed`. This is inventory evidence, not legal advice.
+
+**Claim provenance ledger.** JSON outputs from `risk`, `enrich`, `migrate-check`,
+`audit-report` and `prepare-context` include `evidence_manifest`: stable claim IDs mapped to
+source paths/lines, command inputs, ASK version, git HEAD and freshness metadata. The manifest
+indexes claims already in the payload; it does not add analysis or certify compliance.
+
 
 ---
 

{sourcecode-4.9.0 → sourcecode-4.10.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.9.0-blue)
+![Version](https://img.shields.io/badge/version-4.10.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -16,9 +16,9 @@
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. For a large Java or TypeScript monolith, that means 5–15 seconds per invocation. Multiply by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
-ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, every subsequent invocation returns pre-built context in milliseconds. The repo doesn't change? The cache doesn't expire.
+ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, later invocations reuse pre-built context whenever their command can consume the warmed layers. The repo doesn't change? The cache doesn't expire.
 
 **The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
 
@@ -31,9 +31,11 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-Cache keyed on content hashes — invalidated only when source changes. On repeated agent sessions against the same codebase, nearly every invocation is a cache hit.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
 
-At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
+With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
+
+**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY supervised runs. Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep command whose configured budget is below its safe floor. Use `ask audit-report --from-risk risk.json` to package an existing risk run instead of recomputing it.
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
 shared structural layers (L1/L2 + the Repository Intelligence Snapshot + the shared Canonical
@@ -59,7 +61,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.9.0 — and, on a build that has aged,
+ask version                    # ask 4.10.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -99,8 +101,9 @@ ask endpoints /path/to/repo
 # CGLIB no-op), security surface, request-body validation.
 ask spring-audit /path/to/repo
 
-# Spring Boot 2→3 readiness: located blockers, per-dimension score, effort estimate.
+# Spring Boot 2→3 readiness plus Java LTS/licensing inventory.
 ask migrate-check /path/to/repo --compact
+# Add --target-jdk 25 to make the LTS route explicit.
 ```
 
 **Then the three that finish the sentence the four above start.** A profile-set answer stays
@@ -270,12 +273,12 @@ from it.
 | `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
 | `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
 | `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
-| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
+| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
 | `migrate-recipe` | experimental | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
 | `data-exposure` | experimental | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls |
 | `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
-| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
+| `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
 | `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
@@ -363,6 +366,16 @@ and that gap is the honest description, not a defect to argue with. `migrate-che
 the OpenRewrite recipe each finding carries so the executor that does apply changes has its
 input.
 
+**Java LTS/licensing inventory.** `migrate-check` emits `java_lts_inventory` beside the migration
+scores. It reads Maven/Gradle, local runtime hints and container files for Java 8/11/17/21/25
+evidence, reports target-LTS blockers with `--target-jdk`, and marks explicit Oracle JDK evidence
+as `licensing_review_needed`. This is inventory evidence, not legal advice.
+
+**Claim provenance ledger.** JSON outputs from `risk`, `enrich`, `migrate-check`,
+`audit-report` and `prepare-context` include `evidence_manifest`: stable claim IDs mapped to
+source paths/lines, command inputs, ASK version, git HEAD and freshness metadata. The manifest
+indexes claims already in the payload; it does not add analysis or certify compliance.
+
 
 ---
 

{sourcecode-4.9.0 → sourcecode-4.10.0}/pyproject.toml

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

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

{sourcecode-4.9.0 → sourcecode-4.10.0}/src/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-4.9.0 → sourcecode-4.10.0}/src/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-4.9.0 → sourcecode-4.10.0}/src/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-4.9.0 → sourcecode-4.10.0}/src/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