sourcecode 5.8.20__tar.gz → 5.8.22__tar.gz

{sourcecode-5.8.20 → sourcecode-5.8.22}/.gitignore

@@ -12,6 +12,8 @@ build/
 .mypy_cache/
 .ruff_cache/
 .pytest_cache/
+.testmondata
+.testmondata-*
 src/*.egg-info/
 
 # Editor / IDE

{sourcecode-5.8.20 → sourcecode-5.8.22}/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## [5.8.22] — 2026-08-22
+
+*The eleventh audit-pass queue is closed entire: all fourteen open rows shipped
+as separate commits, regressions first, with the full suite green at 12 176
+tests. Four reported mechanisms are corrected against measurement and one half
+of one row is refused with its price on the record.*
+
+### Fixed — the two regressions the pass led with
+
+- **Root help (`AUD-597-R01`)** — `ask --help` went to 177.4 s in the field
+  because the page is *recursive* through the Typer→Click conversion: one
+  `--help` rebuilt the whole command tree 249 times. The tree is built once per
+  process. Measured here: **13.3 s → 0.45 s**.
+- **Self-check encoding and exit (`AUD-597-R02`)** — `selftest` decoded its
+  children with the host locale, so on a `cp1252` host three checks died with
+  tracebacks and the command still exited 0. Children are read as UTF-8, an
+  unreadable stream is no longer a traceback, and `summary.error > 0` exits 75.
+  The battery now asserts its own exit contract as a ledger row.
+
+### Fixed — bounding, identity and determinism
+
+- **Bounded is never larger (`AUD-597-R03`)** — `--compact` could grow a payload,
+  because a cut's disclosure outweighed the rows it replaced. The trade is
+  measured at each cut; a bounded answer is never the larger one, asserted over
+  the whole bounded-flag population. `--limit N` is still answered literally.
+- **Build provenance (`AUD-597-X01`)** — the generated commit stamp is declared a
+  wheel artifact, so an installed build can name the tree it came from. Proved
+  from the built wheel, not from a checkout.
+- **Front page (`AUD-597-A01`)** — every recommended line carries the bounding
+  flag its own command declares, typed with a value where the flag needs one, and
+  the comment column is padded after the substitution.
+- **Smaller answers (`AUD-597-A02`)** — the output ceiling learns that a smaller
+  answer can be a *mode*, so `export --c4` offers its three sections; and
+  `rename-class --dry-run` prints its plan without the diffs, so the most
+  destructive command in the product can be previewed.
+- **Bean population (`AUD-597-A03`)** — a class's stereotype was picked out of a
+  Python set, so the bean population moved with the per-process hash seed. The
+  choice takes a declared rank; every Spring stereotype outranks every JPA one.
+
+### Fixed — contracts, grammar and disclosure
+
+- **Ledger coherence (`AUD-597-A04`)** — a row declared closed in this document's
+  own prose can no longer ship reading `open`, and a closure declaration must
+  name its rows unambiguously.
+- **Analysis budget (`AUD-597-D01`)** — the help names the commands the budget
+  *stops* and the commands it only *advises*, instead of calling all eight a
+  deadline. The gating flags are asserted over the population that can gate.
+- **Mutually exclusive hints (`AUD-597-D02`)** — `delta` and `contract-diff` no
+  longer answer "not both" with a hint containing both.
+- **Partial timings (`AUD-597-D04`)** — a phase the run declares complete is
+  charged for its own duration, so `unaccounted_pct` on a partial answer means
+  what it means on a full one.
+- **Option suggestions (`AUD-597-D05`)** — suggestions come from this product's
+  guarded matcher rather than the parser's, and the guard measures a real edit
+  distance; where nothing is plausible, the hint names what the command takes.
+- **One repository grammar (`AUD-597-D06`)** — `--path`, `--repo` and `--dir` are
+  accepted everywhere as aliases for the positional repository argument, with no
+  payload change and without overriding a command that declares one already.
+- **Query sink scope (`AUD-597-D07`)** — the vocabulary states that it composes an
+  existing finding and does not originate one, so an absent row is not published
+  as safety.
+- **Exit-code contract (`AUD-596-D11`, residual)** — the rule that closed that row
+  shipped without the batteries that assert it, leaving 23 tests red against the
+  build that fixed them. `error_schema.EXIT_CODE_FOR` publishes the table.
+
+## [5.8.21] — 2026-08-22
+
+*The tenth audit-pass queue is closed: seven remaining P3 fixes shipped as
+separate commits, with the release documentation synchronized to the shipped
+contracts.*
+
+### Fixed — answer contracts and operational safety
+
+- **Repository identity (`AUD-596-D01`)** — the common response envelope now
+  publishes `repo_id` and `git_head` for repository-scoped JSON answers.
+- **Validation figures (`AUD-596-D03`)** — route constraint figures publish their
+  unit and counted population instead of relying on ambiguous field names.
+- **Compare candidates (`AUD-596-D08`)** — directory candidates are rejected
+  before model construction, and comparison results publish resolved counts.
+- **Grammar errors (`AUD-596-D11`)** — invalid command usage is now
+  `INVALID_USAGE`; semantic input failures remain `INVALID_INPUT`.
+- **Actionable hints (`AUD-596-D12`)** — rename, endpoint explanation and
+  regression inputs validate their shapes and provide next steps that can work.
+- **Schema pinning (`AUD-596-D14`)** — ambiguous identifiers such as `1.0`
+  publish `pinnable: false` and the canonical names to pin instead.
+- **Peak memory (`AUD-596-D10`)** — JSON answers publish `_meta.memory` with
+  peak RSS, and costly analyses enforce `ASK_MAX_RSS_MB` with a structured
+  `MEMORY_TOO_LARGE` refusal. Unset or `0` leaves the ceiling disabled.
+
+### Documentation
+
+- Updated the README, English and Spanish user guides, release metadata and
+  roadmap status to 5.8.21.
+- The generated `ask --help` remains the authority for command options and
+  now reports the installed 5.8.21 version.
+
 ## [5.8.20] — 2026-08-21
 
 *`C1-36` is closed on all four remedies. The row was opened by two field

{sourcecode-5.8.20 → sourcecode-5.8.22}/CONTRIBUTING.md

@@ -48,6 +48,18 @@ ask . prepare-context explain
 pytest tests/
 ```
 
+For the normal edit loop, use the incremental runner. The first run builds a
+local dependency map; later runs execute only tests affected by changed code:
+
+```bash
+scripts/test_fast.sh
+```
+
+Pass normal pytest arguments through when needed, for example
+`scripts/test_fast.sh tests/test_cli.py -x`. Run `pytest tests/` before merging
+or when changing shared infrastructure, because the incremental selection is a
+feedback optimization and the full suite remains the final regression gate.
+
 Run a single file:
 ```bash
 pytest tests/test_detector_nodejs.py -v

{sourcecode-5.8.20 → sourcecode-5.8.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.20
+Version: 5.8.22
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -36,8 +36,11 @@ Provides-Extra: dev
 Requires-Dist: jsonschema>=4.18; extra == 'dev'
 Requires-Dist: mcp<2,>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-testmon<2.2,>=2.1.4; (python_version < '3.10') and extra == 'dev'
+Requires-Dist: pytest-testmon>=2.2; (python_version >= '3.10') and extra == 'dev'
 Requires-Dist: pytest-xdist>=3.8; extra == 'dev'
-Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pytest<9,>=8; (python_version < '3.10') and extra == 'dev'
+Requires-Dist: pytest>=8; (python_version >= '3.10') and extra == 'dev'
 Requires-Dist: ruff>=0.15; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
@@ -55,7 +58,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.8.20-blue)
+![Version](https://img.shields.io/badge/version-5.8.22-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -75,6 +78,20 @@ Every time an AI coding agent starts a new session, it has to re-parse the repos
 
 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.
 
+## Product route: individual commands and packs
+
+ASK Engine keeps individual commands for precise, scriptable questions and adds
+workflow-shaped packs for users who want one consumable result:
+
+```bash
+ask pack assessment . --profile prod --output-dir .ask/packs/assessment
+ask pack gate . --since origin/main --output-dir .ask/packs/gate
+```
+
+The [Product Route](docs/PRODUCT-ROUTE.md) is normative: ASK focuses on
+deterministic evidence for Java/Spring modernization and safe change. Packs
+compose existing commands; they do not hide or replace them.
+
 **The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
 
 ---
@@ -125,7 +142,13 @@ stops at 1 408 files and ends at 5.1s. Commands outside that phase-runner set
 must not be gated on this variable; their budget applicability remains visible in
 the [defect ledger](docs/DEFECT-LEDGER.md).
 
-**Current performance status.** Release 5.8.20 retains the shared Canonical IR
+**Memory is measurable and bounded.** Repository-scoped JSON answers publish
+`_meta.memory.peak_rss_mb` and the configured ceiling. For a supervised deep run,
+set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
+answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
+unset, or set it to `0`, to disable the ceiling explicitly.
+
+**Current performance status.** Release 5.8.22 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
 runs; the no-label path remains parse-free. The one-model-per-declared-label path is
 also retained. These are implementation properties, not duration promises:
@@ -159,7 +182,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.20 — and, on a build that has aged,
+ask version                    # ask 5.8.22 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -480,7 +503,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. “Known” is a published list — `risk` prints it as `query_sink_vocabulary`, with the calls it deliberately leaves out and why — so a concatenation into a call outside that list is not a miss to be discovered, it is a stated boundary. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
@@ -640,6 +663,8 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 
 ## Documentation
 
+- [Product Route](docs/PRODUCT-ROUTE.md) — individual commands, packs, evidence contract and boundaries
+
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |

{sourcecode-5.8.20 → sourcecode-5.8.22}/README.md

@@ -10,7 +10,7 @@
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.8.20-blue)
+![Version](https://img.shields.io/badge/version-5.8.22-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -30,6 +30,20 @@ Every time an AI coding agent starts a new session, it has to re-parse the repos
 
 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.
 
+## Product route: individual commands and packs
+
+ASK Engine keeps individual commands for precise, scriptable questions and adds
+workflow-shaped packs for users who want one consumable result:
+
+```bash
+ask pack assessment . --profile prod --output-dir .ask/packs/assessment
+ask pack gate . --since origin/main --output-dir .ask/packs/gate
+```
+
+The [Product Route](docs/PRODUCT-ROUTE.md) is normative: ASK focuses on
+deterministic evidence for Java/Spring modernization and safe change. Packs
+compose existing commands; they do not hide or replace them.
+
 **The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
 
 ---
@@ -80,7 +94,13 @@ stops at 1 408 files and ends at 5.1s. Commands outside that phase-runner set
 must not be gated on this variable; their budget applicability remains visible in
 the [defect ledger](docs/DEFECT-LEDGER.md).
 
-**Current performance status.** Release 5.8.20 retains the shared Canonical IR
+**Memory is measurable and bounded.** Repository-scoped JSON answers publish
+`_meta.memory.peak_rss_mb` and the configured ceiling. For a supervised deep run,
+set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
+answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
+unset, or set it to `0`, to disable the ceiling explicitly.
+
+**Current performance status.** Release 5.8.22 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
 runs; the no-label path remains parse-free. The one-model-per-declared-label path is
 also retained. These are implementation properties, not duration promises:
@@ -114,7 +134,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.20 — and, on a build that has aged,
+ask version                    # ask 5.8.22 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -435,7 +455,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. “Known” is a published list — `risk` prints it as `query_sink_vocabulary`, with the calls it deliberately leaves out and why — so a concatenation into a call outside that list is not a miss to be discovered, it is a stated boundary. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
@@ -595,6 +615,8 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 
 ## Documentation
 
+- [Product Route](docs/PRODUCT-ROUTE.md) — individual commands, packs, evidence contract and boundaries
+
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |

{sourcecode-5.8.20 → sourcecode-5.8.22}/docs/CACHE.md

@@ -141,6 +141,7 @@ The second anchor is the field one, and it carries its own build for the same re
 | `mcp` | the shared work | not timed | yes | `snapshot`, `ris`, `cir`, `parse` | Serves the same commands over MCP, with the same layers. |
 | `schema` | nothing | not timed | no | — | Prints registries; reads no repository. |
 | `telemetry` | nothing | not timed | no | — | Not an analysis. |
+| `pack` | the shared work | not timed | no | `cir`, `parse` | Composes existing analyses; the pack adds no separate parser. |
 | `version` | nothing | not timed | no | — | Not an analysis. |
 <!-- END GENERATED -->
 

{sourcecode-5.8.20 → sourcecode-5.8.22}/docs/COMMERCIAL-OFFER.md

@@ -11,6 +11,12 @@ and [`MODERNIZATION.md`](MODERNIZATION.md) (the flagship product narrative). CLI
 > deterministically, with the source to prove it. Free on normal repos; Pro when the
 > work gets enterprise-scale or automated.**
 
+The commercial route is delivered through two packs while preserving every
+individual command: `ask pack assessment` for modernization and risk discovery,
+and `ask pack gate` for recurring change safety in CI. See
+[`PRODUCT-ROUTE.md`](PRODUCT-ROUTE.md) for the normative scope and evidence
+contract.
+
 The gating axis is **size + automation**, never capability. Nothing is crippled on Free;
 you pay exactly when the tool is replacing the most engineering time — a monolith above
 **500 Java source files**, or CI/CD automation. **€19/mo · €190/yr, per developer.**