sourcecode 4.10.7__tar.gz → 4.11.0__tar.gz

{sourcecode-4.10.7 → sourcecode-4.11.0}/CHANGELOG.md

@@ -2,6 +2,124 @@
 
 ## [Unreleased]
 
+## [4.11.0] — 2026-08-07
+
+**The queue behind Tier D: five ledger rows, and three batteries that were red in
+the release before this one.** C3-59 · C3-56 (second half) · C3-52 · C3-60 (second
+half) · CL-15 close here, one commit each. Two of them were bigger than the row
+said, and both in the same direction — a flag that parses and does not check, a
+message that promises output nobody writes:
+
+- **`--format` was published by eleven commands that validated nothing**, so
+  `ask risk . --format bogus` answered with JSON as if the value had counted
+  (C3-59);
+- **`--detach` told the operator "progress and errors go to `log`"** and the log
+  held one line, because a detached worker has no terminal and the heartbeat
+  switched itself off exactly where it is the only way to tell work from a hang
+  (C3-52).
+
+⚠ **Behaviour changes to read before upgrading a pipeline:**
+
+- **An unsupported `--format` now exits 2** with the values that are valid, on
+  the eleven commands that used to accept anything and answer JSON. A script
+  passing a value that was never supported fails where it used to appear to work.
+- **`--format/-f` is accepted after 34 more commands**, including the 29
+  `retrieve` intents, `modernize`, `schema`, `onboard` and `fix-bug`.
+- **`ask config <path>` refuses a path that does not exist** (exit 1, the standard
+  envelope) instead of reporting "nothing is declared" about it.
+- **A detached run writes heartbeat lines into its own log** unless `--progress`
+  or `ASK_PROGRESS` says otherwise. Nothing changes for a foreground, piped or CI
+  run that does not ask.
+
+Three tests were **already red in 4.10.7** — each a battery that derives its
+population from the CLI, so C4-17's and C4-20's own changes tripped them — and
+they are fixed here. One of the three was not a test defect: it found `ask config`
+answering about a repository that does not exist.
+
+### Changed
+
+- **The `spring-audit` security section says what it is before it says what it
+  found** (CL-15). A field evaluation found the repository's critical SQL
+  injection by hand and ASK did not report it — correctly and by declaration
+  (NC-001: no dataflow) — but the section is announced as a *security surface*,
+  which invites reading it as a defect finder. The surface now states, from one
+  table rendered into both `--help` and the payload, that it reads the security
+  **configuration and exposure** (declared chain rules, open endpoints, disabled
+  controls, bypassable gates, each with file and line), that it is **not** a
+  vulnerability scanner, and where it is strongest: given a defect somebody else
+  found, `ask impact` and `ask risk` quantify what it reaches. The rule-family
+  label follows (`security surface` → `security configuration and exposure`). No
+  rule and no finding changed — this was always a naming defect.
+
+### Fixed
+
+- **`ask config <path>` refuses a repository nobody could read** instead of
+  reporting on it (C4-21 follow-up). The command gained a repository argument in
+  4.10.7 without the admission gate every other path-taking command uses, so
+  `ask config /nonexistent` answered *"Declaration: none at
+  /nonexistent/sourcecode.config.json"* with exit 0 — and *"nothing is declared
+  here"* is indistinguishable from *"nobody could look"*, which is the reading
+  ADR-0008 exists to prevent.
+
+- **`ask cache model` states which repository its figures were measured on, and
+  what that means for yours** (C3-60, second half). It published `verify-edit` as
+  *14,6 s → 9,6 s → 5,6 s* and called it *"built for the edit loop"* while the
+  same command had not answered at 495 s on the field repository — both
+  measurements, one printed. The command now measures the scope it is run in
+  (same authority as `--help` and the remedies), says whether the published
+  figures transfer to it, and gives each command a `here:` line saying how it can
+  be run on *this* repository. No figure changed and nothing is projected: an
+  unmeasurable scope gets the reference figures unqualified, as before.
+
+- **`--progress off | stderr | file:<path>` on every command that can make you
+  wait** (C3-52). The heartbeat existed and the watcher model everybody uses
+  could not see it: a supervisor reading the standard streams got nothing for
+  703 seconds unless it knew to set `ASK_PROGRESS=1` or to poll the run record —
+  knowledge that appeared in no `--help` and in no payload. The choice is now
+  published on the command being typed (62 commands, population from the
+  registry), `ASK_PROGRESS` still sets the same thing in the environment, and an
+  unrecognised value is refused with exit 2 rather than silently falling back to
+  the default. Nothing changes for a piped or CI run that does not ask.
+- **A detached run's log carries the progress its own envelope promises**
+  (C3-52). `--detach` printed *"Progress and errors go to `log`"* and the log
+  held one line, because a detached worker has no terminal and the heartbeat
+  disabled itself exactly where it is the only way to tell work from a hang. A
+  detached run now enables the heartbeat into its own log unless `--progress` or
+  `ASK_PROGRESS` says otherwise; no shell reads those bytes, so the PowerShell
+  `$?` problem (C3-66) cannot be reached from a detached run.
+
+- **The progress heartbeat carries a denominator and an ETA** (C3-56, second
+  half). `phase=auditing 3342 Java files elapsed=6.8m` said the run was alive and
+  nothing about whether it was worth waiting for; the field's only way to tell
+  work from a hang was reading the worker's CPU time. The line now reads
+  `phase=auditing 2766 Java files stage=parsing 1458/2766 files elapsed=2.0s
+  eta=1.8s eta_covers=parsing`, with the counts coming from the loops that read
+  the files rather than from the spinner. The ETA **names what it covers**
+  (nothing here knows the cost of the stages after the counted one), is withheld
+  until it can be measured, and is dropped when the phase changes rather than
+  freezing at `2766/2766`. A run with no heartbeat enabled is not asked to count.
+
+- **`-f` means `--format` on every command that publishes it, and every command
+  that answers with a payload document publishes it** (C3-59). `-f json` was
+  accepted by `endpoints` and `spring-audit` and refused by `modernize`, whose
+  error called `-f` a global flag *"as `ask -f <path>`"* — so the message taught
+  the collision it was meant to remove. The population is now the C4-17 rule one
+  level along (a payload command publishes `--format/-f`; a command that answers
+  in lines is exempt on the record in `cli.COMMANDS_WITHOUT_FORMAT`), and 34
+  commands gained the flag: `modernize`, `archetype`, `cold-start`, `schema`,
+  `onboard`, `fix-bug` and the 29 `retrieve` intents. One conversion in the emit
+  seam serves all of them, on the *stamped* document, so a YAML answer carries
+  the same `_meta` as the JSON one.
+- **An unsupported `--format` is refused instead of silently ignored** (C3-59).
+  Eleven commands published the flag and validated nothing — `ask risk .
+  --format bogus` answered with JSON as if the value had counted. Validation
+  moved into the shared option factory, keyed off the command being run, so a
+  command cannot publish the flag and skip the check;
+  `sourcecode.format_contract.FORMAT_REGISTRY` is the one authority for what
+  each command accepts, and an invalid value exits 2 with the values that are
+  valid. `rename-class` keeps `-f` for `--from` (on the record in
+  `COMMANDS_WITHOUT_FORMAT_SHORTHAND`); its long `--format` is unchanged.
+
 ## [4.10.7] — 2026-08-07
 
 **Tier D, and with it the M13 bug queue.** Five ledger rows close (C4-17 · C4-18 ·

{sourcecode-4.10.7 → sourcecode-4.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.10.7
+Version: 4.11.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.10.7-blue)
+![Version](https://img.shields.io/badge/version-4.11.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`**
@@ -73,8 +73,10 @@ These numbers are cache-layer benchmarks, not a promise for every command. Per-s
 
 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. Long repo-wide/deep runs also write durable records under
+**Large-repo controls.** Pass `--progress stderr` (or `--progress file:run.log`)
+for line heartbeats in a non-TTY supervised run — with the file being read so
+far and an ETA for the stage being measured. `ASK_PROGRESS` sets the same thing
+in the environment. Long repo-wide/deep runs also write durable records under
 `~/.sourcecode/runs/<repo-hash>/` by default, not inside the audited repository;
 set `ASK_RUNS_IN_REPO=1` only when repo-local `.ask/runs` records are intentional.
 Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep
@@ -106,7 +108,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.7 — and, on a build that has aged,
+ask version                    # ask 4.11.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -322,7 +324,7 @@ from it.
 | `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 |
+| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
 | `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 |
@@ -359,7 +361,21 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
-### What the security surface does not answer
+### What the security section is, and what it does not answer
+
+**What it reads:** the security *configuration and exposure* of a repository — which
+rules the request chain declares, which endpoints they leave open, which controls are
+present but disabled, and which custom gates can be bypassed, each with the file and
+line that says so.
+
+**What it is not:** a vulnerability scanner. No value flows through a program here, so
+an injection, a deserialization sink or a logic flaw inside a method body is not looked
+for, and its absence from the report is not evidence (NC-001, below).
+
+**Where it is strongest:** given a defect somebody else found — a scanner finding, a
+line from a review — `ask impact <symbol>` and `ask risk` quantify what it reaches: the
+endpoints, the transactional boundaries and the modules downstream of it, with the
+confidence of each hop. That is the question a taint scanner does not answer.
 
 Published because a product that states its limits is not compared on breadth — it is
 compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent

{sourcecode-4.10.7 → sourcecode-4.11.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.10.7-blue)
+![Version](https://img.shields.io/badge/version-4.11.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`**
@@ -35,8 +35,10 @@ These numbers are cache-layer benchmarks, not a promise for every command. Per-s
 
 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. Long repo-wide/deep runs also write durable records under
+**Large-repo controls.** Pass `--progress stderr` (or `--progress file:run.log`)
+for line heartbeats in a non-TTY supervised run — with the file being read so
+far and an ETA for the stage being measured. `ASK_PROGRESS` sets the same thing
+in the environment. Long repo-wide/deep runs also write durable records under
 `~/.sourcecode/runs/<repo-hash>/` by default, not inside the audited repository;
 set `ASK_RUNS_IN_REPO=1` only when repo-local `.ask/runs` records are intentional.
 Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep
@@ -68,7 +70,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.7 — and, on a build that has aged,
+ask version                    # ask 4.11.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -284,7 +286,7 @@ from it.
 | `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 |
+| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
 | `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 |
@@ -321,7 +323,21 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
-### What the security surface does not answer
+### What the security section is, and what it does not answer
+
+**What it reads:** the security *configuration and exposure* of a repository — which
+rules the request chain declares, which endpoints they leave open, which controls are
+present but disabled, and which custom gates can be bypassed, each with the file and
+line that says so.
+
+**What it is not:** a vulnerability scanner. No value flows through a program here, so
+an injection, a deserialization sink or a logic flaw inside a method body is not looked
+for, and its absence from the report is not evidence (NC-001, below).
+
+**Where it is strongest:** given a defect somebody else found — a scanner finding, a
+line from a review — `ask impact <symbol>` and `ask risk` quantify what it reaches: the
+endpoints, the transactional boundaries and the modules downstream of it, with the
+confidence of each hop. That is the question a taint scanner does not answer.
 
 Published because a product that states its limits is not compared on breadth — it is
 compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent

{sourcecode-4.10.7 → sourcecode-4.11.0}/pyproject.toml

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

{sourcecode-4.10.7 → sourcecode-4.11.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.10.7"
+__version__ = "4.11.0"