sourcecode 5.8.6__tar.gz → 5.8.7__tar.gz

{sourcecode-5.8.6 → sourcecode-5.8.7}/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 ## [Unreleased]
 
+## [5.8.7] — 2026-08-18
+
+*An ASK polish pass, and then the recommended-feature queue emptied. The theme
+of the fixes is again the one the field keeps teaching: **three of the seven
+closed by finding the premise wrong**. E-9's caveat was not dropped between two
+commands — on that shape nothing ever produced it. E-14's row said "either the
+limit is not enforced or it is enforced and unreported"; it was neither, two
+authorities disagreed about the same number. And `C3-84`'s confident falsehood
+turned out to be **our own qualifier**, added a release earlier to close a
+silence, refuted by our own measurement.*
+
+### Fixed
+- **A partially resolved route path is unresolved, and its id stays readable**
+  (E-9). `@Path("/{accountId:" + UUID_PATTERN + "}")` contains string literals,
+  so every reader concluded the path was known and published the first literal —
+  `/{accountId:` — as the route, silently. A partial resolution is not a
+  resolution. The caveat is now a field of `CanonicalEndpoint`, so `endpoints`,
+  `impact-chain` and `impact` publish it from one authority; and `make_id`
+  percent-escapes the separator, so an endpoint id has four fields for every
+  route rather than five.
+- **The re-export hop budget is enforced, and running out of it is declared**
+  (E-14). Two authorities disagreed: the test said a three-level chain must not
+  resolve, the walk said "depth=2 total" and resolved it. The walk wins — two
+  hops land on the module where the symbol is declared. What was missing is the
+  other side, plus two defects found while adjudicating: a chain still going
+  when the budget ran out was published as if it had ended, and a chain that
+  simply ends inside a package reported a limit it never reached.
+- **`impact-chain`'s sentence names the unit its number is in** (C1-16, witness
+  a). It printed the entry count under the words "22 direct callers" while the
+  field beside it said 14. `impact` had closed this half already.
+- **`--jobs` states the measured cost split, not the estimate** (C3-84). The
+  4.15.0 wording called the rule pass *"where a repository-wide audit spends
+  most of its time"*. Instrumented: the CIR build is 88 % of the clock and every
+  rule together 8 %. All three surfaces carry the measurement now, and the
+  correction reverses what the flag implies — it covers the phase with the cost.
+- **A run cannot exit 0 without producing the file it promised** (C3-122). One
+  field report: 444 s, exit 0, no output, no file. Fixed as the shape rather
+  than the occurrence — the promise is noted from the argument vector, so all 65
+  commands that publish `--output` are covered including one that returns before
+  its emit seam, and a file write is never silent.
+- **SEC-001 reports an absence it measured, not a verdict it did not** (C1-43).
+  It told the reader *"any caller can reach this endpoint without
+  authentication"* from the absence of the two chain shapes it knows how to look
+  for, at `confidence: high`. It now states what was looked for and not found,
+  publishes the premise as evidence, and binds the coverage answer to the
+  authority that owns it.
+- **DEAD-001 keeps `high`, and the reason is on the record** (C3-101 c). The
+  severity was never the defect; the precision was, and it shipped.
+
+### Added
+- **`spring-audit --since <ref> --fail-on-new`** (F-BL) — the gate a repository
+  with existing debt can actually turn on. Joins two audits on the content-stable
+  `defect_id` and fails only on what the change introduced. Both sides are asked
+  the same question and the payload says which; a renamed symbol reads as one
+  resolved plus one new and says so; a comparison that could not be made exits
+  non-zero, never 0.
+- **`ask explain-endpoint '<VERB> <path>'`** (F-BN) — show your work for one
+  route: match, declaration, handler, chain, profiles, verdict, each naming the
+  authority that produced it and the file it can be checked against. A step that
+  could not be derived is `undetermined` **with the reason** — none of the six is
+  ever absent in silence.
+- **`spring-audit --remediation-diff`** (F-BK) — the findings as patches `git
+  apply` takes, for the defects whose repair is the lexical inverse of the
+  defect. Not `--recipe` with a different encoding: a recipe is run, a diff is
+  decided, and every patch carries what applying it decides.
+- **`spring-audit --clusters`** (F-BM) — 386 rows as the handful of things
+  somebody has to do, keyed on `(defect_kind, repair_shape, locus)` with the axis
+  declared. The effort figure is an assumption with its arithmetic exposed; an
+  owner comes from CODEOWNERS or is absent.
+- **A deprecation channel for published payload keys** (F-BQ, BC-003). A key on
+  its way out is published beside its replacement with the release that removes
+  it. `auth status` moves onto it, so it ships with a real population.
+- **The base URL a client centralises is resolved from its own declaration**
+  (F-BO). 115 of 135 client calls were unresolved for one reason: the head is a
+  constant written a few lines up. A name bound twice — `environment.ts` and
+  `environment.prod.ts` — is still not resolved.
+- **A declaration split across lines is still a declaration** (F-BP). A wrapped
+  generic return type published the member with *no annotations at all*, so the
+  route left the census and its guard left with it. `endpoints` on
+  BroadleafCommerce and spring-boot-admin is byte-identical: recall on the broken
+  shapes and nothing else.
+- **A cost fixture for the composition family** (F-BR, second half) — counted,
+  not timed, so it means the same thing on any machine.
+
 ## [5.8.6] — 2026-08-18
 
 *The queue the two 5.8.5 re-audits left, worked in their own order, and the
@@ -387,6 +471,27 @@ changes a **published value** while every exit code stays 0. Declared in
 for the exit-code kind — named in the `--help` of every command it can fire on,
 so an upgrade can be planned instead of discovered by a red pipeline.*
 
+### BC-003 — deprecated payload keys are removed (announced 5.8.7, takes effect 6.0.0)
+
+**Who is affected.** Any consumer reading a key that `field_deprecations` lists.
+**No exit code moves**: the key stops being emitted, and a consumer that reads it
+gets nothing rather than a wrong value.
+
+A published key that has been replaced is emitted **beside** its replacement for
+the whole window, listed in the payload's own `deprecated_fields`, and described
+in `field_deprecations` with the release that removes it — `alias_of` where the
+key was renamed and is copied from its replacement, `replaced_by` where the
+value is derived differently and the command still produces it. In 6.0.0 those
+keys stop being emitted, and nothing is removed that was not declared here
+first. C3-124 is the reason the channel exists rather than the schedule: an
+experimental tier is permission to change shape, not permission to change it in
+silence.
+
+The population is read from `sourcecode.field_deprecations` rather than copied
+here. Today it is the four `pro*` keys on `ask auth status`, which that payload
+publishes side by side with the entitlement block that replaced them — so the
+migration is checkable against one run.
+
 ### BC-002 — `schema_version` values are renamed to their canonical names (announced 5.8.5, takes effect 6.0.0)
 
 **Who is affected.** Any consumer that dispatches on the emitted

{sourcecode-5.8.6 → sourcecode-5.8.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.6
+Version: 5.8.7
 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
@@ -49,7 +49,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.8.6-blue)
+![Version](https://img.shields.io/badge/version-5.8.7-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
@@ -91,9 +91,11 @@ in the environment, and the heartbeat is emitted by the analysis itself, not onl
 by a timer thread, so a CPU-bound stretch is never silent. `--jobs N` / `-j`
 (env `ASK_JOBS`) sets the worker processes that parse files — default CPU count
 − 1; parallelism only warms the content-addressed parse cache, so the answer is
-byte-identical at any value. It does **not** parallelise the rule pass, which is
-where a repository-wide audit spends most of its time, and a warm cache leaves it
-nothing to parse — so raising it there buys nothing. Long repo-wide/deep runs also write durable records
+byte-identical at any value. It does **not** parallelise the rule pass —
+measured with `metadata.timings` on a 2 766-file repository, the CIR build is
+88 % of a repository-wide audit's clock and every rule together 8 %, so the flag
+covers the phase that holds the cost; a warm cache leaves it nothing to parse, so
+raising it there buys nothing. 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. Use `ask audit-report --from-risk risk.json` to package an existing
@@ -137,7 +139,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.6 — and, on a build that has aged,
+ask version                    # ask 5.8.7 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -410,6 +412,7 @@ from it.
 | `retrieve` | parked | typed knowledge queries over the model | |
 | `timeline` | experimental | since when a number moved, and in which commit window | walks the commit series and re-runs the shipped analyses (`posture`, `data-exposure`, `endpoints`, `spring-audit`) on a read-only materialisation of each sampled tree; publishes transitions, not a per-commit dump. A sample that could not be analysed is `null` with a reason, never 0, and a transition under sampling carries the window it could have happened in |
 | `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
+| `explain-endpoint` | supported | the derivation behind one route's verdict | six steps — match, declaration, handler, chain, profiles, verdict — each naming the authority that produced it and the file it can be checked against; a step that could not be derived is `undetermined` with the reason, never absent |
 | `selftest` | supported | this product's own defect ledger, run against your repository | each ledger row's acceptance criterion as an executable assertion, with the subject (repository, size, platform, entry point) beside every verdict; a row whose precondition the repository does not meet is `not_applicable` with the reason, never a pass |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |

{sourcecode-5.8.6 → sourcecode-5.8.7}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.8.6-blue)
+![Version](https://img.shields.io/badge/version-5.8.7-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
@@ -46,9 +46,11 @@ in the environment, and the heartbeat is emitted by the analysis itself, not onl
 by a timer thread, so a CPU-bound stretch is never silent. `--jobs N` / `-j`
 (env `ASK_JOBS`) sets the worker processes that parse files — default CPU count
 − 1; parallelism only warms the content-addressed parse cache, so the answer is
-byte-identical at any value. It does **not** parallelise the rule pass, which is
-where a repository-wide audit spends most of its time, and a warm cache leaves it
-nothing to parse — so raising it there buys nothing. Long repo-wide/deep runs also write durable records
+byte-identical at any value. It does **not** parallelise the rule pass —
+measured with `metadata.timings` on a 2 766-file repository, the CIR build is
+88 % of a repository-wide audit's clock and every rule together 8 %, so the flag
+covers the phase that holds the cost; a warm cache leaves it nothing to parse, so
+raising it there buys nothing. 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. Use `ask audit-report --from-risk risk.json` to package an existing
@@ -92,7 +94,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.6 — and, on a build that has aged,
+ask version                    # ask 5.8.7 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -365,6 +367,7 @@ from it.
 | `retrieve` | parked | typed knowledge queries over the model | |
 | `timeline` | experimental | since when a number moved, and in which commit window | walks the commit series and re-runs the shipped analyses (`posture`, `data-exposure`, `endpoints`, `spring-audit`) on a read-only materialisation of each sampled tree; publishes transitions, not a per-commit dump. A sample that could not be analysed is `null` with a reason, never 0, and a transition under sampling carries the window it could have happened in |
 | `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
+| `explain-endpoint` | supported | the derivation behind one route's verdict | six steps — match, declaration, handler, chain, profiles, verdict — each naming the authority that produced it and the file it can be checked against; a step that could not be derived is `undetermined` with the reason, never absent |
 | `selftest` | supported | this product's own defect ledger, run against your repository | each ledger row's acceptance criterion as an executable assertion, with the subject (repository, size, platform, entry point) beside every verdict; a row whose precondition the repository does not meet is `not_applicable` with the reason, never a pass |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |

{sourcecode-5.8.6 → sourcecode-5.8.7}/docs/CACHE.md

@@ -108,6 +108,7 @@ The second anchor is the field one, and it carries its own build for the same re
 | `chunk-file` | nothing | not timed | no | — | Reads one file; nothing to cache. |
 | `cold-start` | the answer | 0.2 s either way | yes | `ris` | Reads the RIS a warm rebuilds — that is all it does. Without one it answers `no_ris` instead of a snapshot. |
 | `timeline` | nothing | not timed | yes | `timeline-samples` | Two commits are two trees, so nothing is shared *within* a run — but a metric at a commit is a pure function of that tree, and the tree at a sha never changes, so a sample an earlier run of this analyser already measured is read from the store instead of being measured again (C3-129). A warm builds nothing for it: a warm analyses the working tree, not history. `--no-cache` measures every sample again, and the payload publishes the hits. |
+| `explain-endpoint` | the shared work | not measured on the battery yet — bounded by `endpoints` on the same repository | yes | `cir`, `parse` | Builds the repository IR to answer about ONE route, so the warm it shares with `endpoints` and `posture` is the whole difference between a question you ask once and a question you ask twenty times. |
 | `selftest` | the shared work | not timed | no | `cir`, `parse` | Runs the ledger's acceptance criteria by invoking other commands against this repository, so it inherits their layers — a warm makes those runs warm. It holds no cache of its own and stores nothing. |
 | `regress` | nothing | not timed | no | — | Diffs two payload files this CLI already wrote; analyses no source, so no cache layer applies. What it reads about caching is the `cache_layers` field inside those payloads — to refuse a comparison taken under different cache states, not to use one. |
 | `trend` | nothing | not timed | no | — | Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`. |