sourcecode 5.8.0__tar.gz → 5.8.1__tar.gz

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

@@ -2,6 +2,143 @@
 
 ## [Unreleased]
 
+## [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.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.0
+Version: 5.8.1
 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.1-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.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.8.0 → sourcecode-5.8.1}/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.1-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.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.8.0 → sourcecode-5.8.1}/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.