sourcecode 5.8.0__tar.gz → 5.8.2__tar.gz

{sourcecode-5.8.0 → sourcecode-5.8.2}/CHANGELOG.md

@@ -2,6 +2,251 @@
 
 ## [Unreleased]
 
+## [5.8.2] — 2026-08-17
+
+*The five rows the 5.8.0 re-audits left in the queue, closed one commit at a
+time, in the order the roadmap itself recommended. Four of the five are about
+what the product can **say** rather than what it can compute — a boolean without
+its unit, a count without its cap, an incompatible change without a way to find
+out, forty version identifiers that nothing could look up — which is the same
+theme 5.8.1 found and did not exhaust. The fifth adds the detector that a ratio
+gate structurally cannot be: an absolute cost axis.*
+
+*Three defects were found while fixing others and are recorded with their rows:
+`version` and `schema` disagreeing about which registries this release
+publishes; `Scope.large` answering `False` from a saturated count while the
+class's own docstring said it must not; and a scan cap that could drift from the
+cap the message names.*
+
+### Added
+- **The release gate measures cost, not only change** (P1 / F-BR). Every
+  comparison it made was a ratio, and a ratio cannot see a cost that was always
+  too high: `validation` went 13,8 → 34,1 → 39,5 s across three releases with no
+  step over 20 %, so the gate was green at every step and a staircase shipped.
+  `absolute_cost` adds a declared ceiling per command — each published beside
+  the mark it was calibrated against, because a limit nobody can audit against a
+  measurement is just a number — and the anchored assertion the field validated,
+  `max(sample) < 8 × posture_warm`, with the anchor measured in the same run so
+  a slower runner moves the limit with it. The two formulations prescribed
+  before it are refuted with measurement and are carried in the source with the
+  counter-example that killed each: one reads only the ends of the series, the
+  other scores shape rather than cost and hands the worst release of the six a
+  perfect mark. `--self-test` gains two reds, because a green gate is evidence
+  only when a red one is reachable.
+- **`ask schema` resolves every `schema_version` this release can emit** (B6) —
+  50 entries over 44 identifiers, each with what it versions, which module
+  defines it, which commands carry it, and whether a JSON Schema document exists
+  behind it. `endpoints` gains `endpoints-v1`, the version it never had. The
+  registry is checked against the source by AST, so a new identifier cannot
+  arrive unlisted. `1.0` is published as **ambiguous**: seven unrelated shapes
+  spell their version that way, and resolving it to one of them would be a
+  confident falsehood.
+- **An `## Upgrading` section, and `ask schema breaking-changes-v1`** (ASK-11).
+  A change that turns `exit 0` into `exit 1` is now declared before it fires,
+  named in the `--help` of every command it can fire on, and carried with the
+  invocations that change and the sizes at which they change.
+
+### Fixed
+- **A boolean about the working tree names the unit it was measured in** (B11).
+  `has_uncommitted_changes: false` was published in the same terminal where
+  `git status` had just printed `?? .claude/settings.json`. The rule is right and
+  stays — no analyser opens an editor or agent state directory — but with no
+  basis, "no changes" and "changes I did not count" are the same three
+  characters. The boolean now travels with a census that reconciles against the
+  reader's own `git status`: `counted + excluded` is exactly what git printed,
+  and each exclusion carries its reason. A non-git directory says "not a git
+  worktree" instead of a confident `false`.
+- **A count that stops early says what stopped it** (ASK-13). `cache warm`
+  reported "at least 8 418 Java files" about a repository holding 24 073,
+  because the walk stops after 25 000 *directory entries*, not 25 000 Java
+  files. The cap stays — this runs while somebody waits for `--help` to render —
+  and now names itself with its unit. `Scope.large` also answered `False` from a
+  saturated count, so a repository whose first entries held few sources was
+  advised as small; below the threshold a capped count now decides nothing and
+  the cost verdict answers `unknown` with its reason.
+- **`version` and `schema` publish the same registries.** They carried a comment
+  promising they could not disagree while one held a literal and the other
+  derived its list; the second registry made them disagree. Both read one
+  authority now.
+
+## Upgrading — incompatible changes
+
+*A change that turns `exit 0` into `exit 1` is a breaking change, and it belongs
+here rather than in a line of a release section. Declared in
+`sourcecode.breaking_changes`, printed by `ask schema breaking-changes-v1`, and
+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-001 — stdout over the output ceiling exits 1 (since 5.7.0)
+
+**Who is affected.** Any script, pipeline or agent that reads a large payload
+from stdout. Before 5.7.0 the ~50K-estimated-token ceiling existed on
+`migrate-check` and `repo-ir` only, so the same size was refused by one command
+and printed in silence by another (AS-09). It is now one policy at the single
+emit seam.
+
+**The trigger is repository size, not a flag** — so an invocation that fits
+today can stop fitting on a larger repository, or after a release that detects
+more. Measured by the field on the 5.6.1 → 5.7.x upgrade:
+
+| Invocation | Payload in 5.6.1 (`exit 0`) |
+|---|---|
+| `ask endpoints tutorials` | 987 141 B — ~247 K estimated tokens |
+| `ask endpoints thingsboard` | 318 380 B |
+| `ask posture spring-boot` | 355 032 B on 8 667 Java files |
+
+**Restore the old behaviour now:** `ASK_MAX_OUTPUT_TOKENS=0` (or
+`--max-output-tokens 0`) switches the guard off and prints the whole payload,
+exactly as before 5.7.0. Any other value moves the ceiling rather than removing
+it.
+
+**The remedy, when there is time:** a bounding flag keeps the answer where the
+reader is — `--compact`, `--limit N`, `--top-n N` or `--min-severity`, whichever
+the command declares — and `--output FILE` writes the whole payload to disk
+without the stdout ceiling applying at all. The error message names the ones the
+failing invocation has not already used.
+
+The decision itself is not being revisited: 247 K tokens printed into an agent's
+context window was worse than a refusal. What was missing was the ability to
+find that out before it fired.
+
+## [5.8.1] — 2026-08-17
+
+*Ten rows from the two 5.8.0 re-audits, closed one commit at a time. The theme
+is not the engine: of the ten, **three were analysis defects and seven were the
+payload failing to say what the analysis already knew** — a population that
+moved with no field to explain it, two empty lists beside two full builds, a
+census naming production trees as excluded, a compact view that dropped its own
+identity, a tier that read as a severity. Two reported causes were **refuted by
+measurement** and are recorded as such rather than "fixed": the claimed
+5.7.3 → 5.8.0 slowdown (±2 % over 10 repo×command pairs) and the ceiling hint
+said to name no smaller variant when one exists.*
+
+### Added
+- `posture` and `validation` take `--limit N` and `--compact` (ASK-10). Both
+  could exceed the output ceiling and declared no flag that could get under it,
+  so the only ways out were `--output FILE` — which puts the answer outside the
+  agent that asked for it — and `ASK_MAX_OUTPUT_TOKENS=0`, which switches the
+  guard off. `posture` exited 1 on 2 of 8 corpus repositories, and what pushed
+  it over was a *better* answer: conditional beans now name
+  `@ConditionalOnExpression` instead of a generic reason (`unresolved`
+  64 120 → 184 864 B). Bounding lives in one authority, reaches every depth of
+  the payload (a `--diff` is bounded on both sides), touches lists and never
+  counts, and every cut publishes `{total, shown, omitted}` with the registered
+  effect. Nothing is bounded unless you ask. Measured: `posture` on
+  keycloak-config-cli 53 115 → 4 605 B under `--compact`, summary unchanged.
+  A registry-derived battery now fails when a command that can exceed the
+  ceiling declares no way under it.
+
+### Fixed
+- A risk tier is not a rule severity, and no longer reads like one (B2). The
+  band and the severity shared a vocabulary while measuring different things,
+  and disagreed on 34 of 50 rows — both correct, since a severity is what the
+  rule says about a defect and a band is what the composition says about it in
+  this repository. `audit-report` announced 14 critical over bands while
+  `--min-severity critical` filtered severities and returned 0. Every risk row
+  and census now also carries `risk_tier` (R1…R5) beside `band`, with one
+  crosswalk sentence that names both axes, says they disagree by construction,
+  and points at `--min-band` as the flag that filters tiers.
+- `--compact` makes an answer smaller, never unattributable (B14).
+  `cold-start --compact` dropped 11 of 19 keys — `schema_version`, `repo_id`,
+  `current_git_head`, and a 331-character `hotspots` section — from a document
+  whose weight was 97,7 % endpoints, and cut the endpoint list to 30 with
+  nothing to say it had. There is now an immutable minimum no compact view may
+  remove, every cut collection declares `{total, shown, omitted}` (on
+  BroadleafCommerce: 272 total, 30 shown, 242 omitted), and trimming goes by
+  weight rather than by a fixed key list, with every removed section named and
+  measured in `compact_omitted`.
+- An excluded *pattern* is a directory whose files are all excluded (ASK-12).
+  `spring-audit` published `core/`, `module/` and `cli/` — three production
+  trees, 5 955 files between them — as excluded patterns, because the
+  constructor fell back to naming the first path segment. The exclusion itself
+  was conservative and correct; the field describing it was not, and an auditor
+  filed and withdrew an over-exclusion report over it. The same field also had
+  two constructors with two shapes. Both surfaces now call one producer beside
+  the authority that decides what a test source is: `patterns_matched` holds
+  only declared test roots, and per-file rules are published as a
+  `rules_matched` census with a sentence explaining each rule.
+- One authority writes every output-ceiling hint (ASK-09). `repo-ir` carried two
+  hand-written hints — one for stdout, one for the separate megabyte guard on a
+  written file — and `migrate-check` a third that reimplemented `build_hint`
+  line for line. A hand-written escape list cannot know which flags the caller
+  already passed, which is the defect the field reported from the other side.
+  `output_ceiling` now expresses what those commands needed: `--force` as a
+  bypass, offered only where it is declared; `--gzip` as a file-only bound; a
+  `destination="file"` view where `--output FILE` is not an escape and the token
+  env var does not apply; and the "no smaller inline variant" prefix decided by
+  counting the bounding escapes rather than the sentence. The reported half —
+  `endpoints` and `cold-start` claiming nothing smaller exists while `--compact`
+  fits — does not reproduce against the unified emit seam.
+- `verify-edit` names the change that bought its model (B4). A clean worktree
+  already short-circuits — measured 0,47 s with `model_built: false` on a
+  2 985-file repository — but a single changed path that is neither `.java`
+  nor a build descriptor (a stray `.yml`, an unclassified extension) forces two
+  repository-wide builds while appearing in **neither** published list. The
+  payload therefore read `changed_files: []`, `changed_build_files: []`,
+  `model_built: true` and 16,3 s of work with nothing to explain it, which is
+  how it was reported as a broken short circuit. `analysis.model_forced_by:
+  {count, paths, reason}` now names those paths, and `basis` says the model was
+  forced rather than implying nothing changed.
+- A write that cannot finish leaves the filesystem as it found it (B15). The
+  payload was written to a temporary beside the destination and renamed onto it
+  — atomic, and correct — but a failed rename left the temporary behind: a field
+  matrix of five bad destinations left **13,9 MB of untracked files inside the
+  repository**, which is the premise "read-only analysis" being false. The
+  write now lives in one authority (`sourcecode.output_sink`) and removes its
+  temporary in a `finally`. Three edges came with it: a discard sink (`nul`,
+  `NUL`, `CON` on Windows, `/dev/null` on POSIX) is a destination, not an I/O
+  error — `written: false`, `sink: "null-device"`, `exit 0`, matched only on the
+  platform that reserves the name; the operating system's message no longer
+  enters our English sentence but travels in `os_error: {raw, errno, errno_name,
+  locale}`, beside a `cleaned_up` list of what the run took back with it; and
+  `-o reports/today/out.json` creates the parent directories, deliberately, with
+  a hint that says so instead of telling you to check for a directory we would
+  have made.
+- The parse store publishes the ceiling its policy can hold, not only its budget
+  (ASK-15 / AS-18). The resting excess over the 512 MB budget was measured going
+  5,45 → 44,35 MB and, followed across three further commands, **not
+  converging** — because the policy is "swept every 32 MB written" and with no
+  writes there is no sweep. Nothing was lying; the figure to size a disk by was
+  simply not published. `cache status` now carries `effective_ceiling_mb`
+  (`budget + sweep_interval × concurrent writers`, the writer count read from
+  the authority the parse pool resolves `--jobs` against) with a basis that
+  names both terms and says why the excess *rests*: the last interval before a
+  process exits is never swept. `over_budget` — normal, bounded, expected — is
+  separated from `over_ceiling`, the only state that contradicts what we
+  publish. `cache model` and `docs/CACHE.md` corrected from the same fact.
+- Retiring a stale parse-cache generation is a rename, not a walk of the store
+  (ASK-14 / AS-17). The first run after an upgrade is the one run that finds a
+  whole unreachable generation, and it unlinked every file of it *inside* the
+  analysis, before its own first write — so a cold run's cost scaled with what
+  the store already held, which is the exact condition the field measured its
+  worst cold number under. The generation is now renamed out of reach in one
+  directory operation and unlinked on a daemon thread behind the run: **990 ms →
+  10,9 ms** on the analysis path over 20 000 entries / 153 MB. A filesystem that
+  refuses the rename still gets the inline delete, and a deletion cut short by
+  process exit is finished by the next run. `cache status` keeps counting those
+  bytes, named `retired (deleting)` — they are on the disk until they are not.
+  The other half of the report, a claimed 5.7.3 → 5.8.0 slowdown in the analysis
+  path itself, **did not reproduce**: 10 repo×command pairs A/B'd against
+  `0900336` with an isolated cache per cell put every delta inside ±2 %.
+- An analysed population does not move between releases without a field that
+  explains the move (B17-sv / AS-16). 5.8.0's E-35 fix removed symbols that were
+  never declarations — `return unknownHelper("x");` parsed as one — and
+  `metadata.symbols_analyzed` fell with them (`saint-server` 43 642 → 43 003,
+  −1,46 %, after five constant versions). The correction was right and the
+  release said nothing, so the next field re-audit read it as lost coverage and
+  filed it P0. Every command that publishes `symbols_analyzed` now publishes
+  `symbols_excluded: {count, reason, basis}` beside it — `repo-ir`'s
+  `analysis_meta`, the CIR metadata and `spring-audit`'s metadata, from one
+  authority — **always present, `count: 0` included**, because a field that
+  appears only when it is non-zero says nothing by its absence. The count is
+  carried in the parse-cache entry, so a warm run reports the same number as a
+  cold one and a file prepared by a worker reports the same as one parsed in
+  sequence. `reason` names the phantom and the release that removed it; `basis`
+  names the discriminator (`statement_head_in_return_type_slot`), which is
+  checkable against the source.
+
 ## [5.8.0] — 2026-08-16
 
 *The field queue from the two 5.7.3 validations, closed end to end: the blast

{sourcecode-5.8.0 → sourcecode-5.8.2}/CLAUDE.md

@@ -70,5 +70,13 @@ the same command runs on a 3 300-file monolith.
   `unknown`, never `0` and never "not reachable".
 - **Vendor-agnostic inference.** Logic never branches on a proprietary name;
   names are evidence, never the rule.
-- Run the suite with `-o addopts=""` to see the summary line; the entry point for
-  local runs is `run_cli.py`, not `python -m sourcecode.cli`.
+- **The suite runs in parallel by default.** `addopts = "-q -n auto"`, so plain
+  `pytest` runs the whole battery and prints the summary line — 70 s on 8 cores,
+  not 246 s. `-o addopts=""` is no longer the way to see the count; it now
+  *removes* the parallelism. Override the worker count with `-n <k>`, not by
+  clearing `addopts`.
+- **Run one file while you work, the suite before you commit.** Naming the file
+  is ~2 s; the full run is 70 s. `-k <pattern>` is not the shortcut — it
+  deselects but still collects all ~9 000 tests, so it floors at 16 s. After a
+  red run, `--lf` re-runs only what failed.
+- The entry point for local runs is `run_cli.py`, not `python -m sourcecode.cli`.

{sourcecode-5.8.0 → sourcecode-5.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.0
+Version: 5.8.2
 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
@@ -35,6 +35,7 @@ Requires-Dist: tree-sitter>=0.21; extra == 'ast'
 Provides-Extra: dev
 Requires-Dist: mcp<2,>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.15; extra == 'dev'
 Provides-Extra: mcp
@@ -47,7 +48,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.0-blue)
+![Version](https://img.shields.io/badge/version-5.8.2-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
@@ -135,7 +136,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.0 — and, on a build that has aged,
+ask version                    # ask 5.8.2 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.8.0 → sourcecode-5.8.2}/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.0-blue)
+![Version](https://img.shields.io/badge/version-5.8.2-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
@@ -92,7 +92,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.0 — and, on a build that has aged,
+ask version                    # ask 5.8.2 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.8.0 → sourcecode-5.8.2}/docs/CACHE.md

@@ -59,7 +59,7 @@ the enclosing monorepo, and `cache status` / `cache clear` resolve to that same
 | `ris` | the Repository Intelligence Snapshot — structural index, endpoint index, summaries | tree state (the snapshot records the tree it describes) | rebuilt on every warm |
 | `cir` | the shared Canonical IR — the Java parse every knowledge command reuses | tree state · analyzer fingerprint · schema version | built |
 | `task` | one `prepare-context` task answer, per task and per option set | tree state · task · --symptom / --all / --include-config / --format | never — a warm does not run any task |
-| `parse` | the symbol extraction of one file, keyed by its bytes | the file's own bytes and the extractor's source — content-addressed, so it is never stale and never needs invalidating. Bounded by `ASK_PARSE_CACHE_MAX_MB` (default 512 MB, least-recently-used, swept every 32 MB written rather than on every write, so the size can sit one sweep interval per running process above the budget) and reported in `cache status` (F-AR) | filled for every Java file the warm parses |
+| `parse` | the symbol extraction of one file, keyed by its bytes | the file's own bytes and the extractor's source — content-addressed, so it is never stale and never needs invalidating. Bounded by `ASK_PARSE_CACHE_MAX_MB` (default 512 MB, least-recently-used, swept every 32 MB written rather than on every write, and the last interval before a process exits is never swept — so the store rests up to one interval per writing process above its budget, and the figure to size a disk by is the ceiling `cache status` publishes beside it, not the budget itself (ASK-15)) and reported in `cache status` (F-AR) | filled for every Java file the warm parses |
 
 Measured on BroadleafCommerce (2 000+ Java files, dirty tree), warm machine, 3.2.2, each command in isolation.