sourcecode 4.18.0__tar.gz → 5.0.1__tar.gz

{sourcecode-4.18.0 → sourcecode-5.0.1}/.github/workflows/perf-gate.yml

@@ -59,14 +59,18 @@ jobs:
           python3 scripts/perf_gate.py --print-config | tee gate-config.json
           echo "repo_url=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository_url'])")" >> "$GITHUB_OUTPUT"
           echo "repo=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository'])")" >> "$GITHUB_OUTPUT"
+          echo "fleet_subdir=$(python3 -c "import json;print(json.load(open('gate-config.json'))['fleet_subdir'])")" >> "$GITHUB_OUTPUT"
           echo "mode=$(python3 -c "import json;print(json.load(open('gate-config.json'))['mode'])")" >> "$GITHUB_OUTPUT"
           echo "runs=$(python3 -c "import json;print(json.load(open('gate-config.json'))['min_runs'])")" >> "$GITHUB_OUTPUT"
           echo "commands=$(python3 -c "import json;print(' '.join(repr(c) for c in json.load(open('gate-config.json'))['commands']))")" >> "$GITHUB_OUTPUT"
 
       - name: Clone the gate repository
+        # Into the directory the harness resolves the gate repository to, which
+        # `--print-config` publishes. Naming it here instead cost three nightlies
+        # that measured nothing.
         run: |
           mkdir -p fleet
-          git clone --depth 1 "${{ steps.cfg.outputs.repo_url }}" "fleet/${{ steps.cfg.outputs.repo }}"
+          git clone --depth 1 "${{ steps.cfg.outputs.repo_url }}" "fleet/${{ steps.cfg.outputs.fleet_subdir }}"
 
       - name: Measure
         env:
@@ -84,6 +88,7 @@ jobs:
         run: |
           python3 scripts/perf_gate.py \
             --baseline "$BASELINE_DIR" \
+            --require-baseline \
             --current perf-run \
             --report perf-run/gate.json \
             --table perf-run/RELEASE-TABLE.md

{sourcecode-4.18.0 → sourcecode-5.0.1}/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 ## [Unreleased]
 
+## [5.0.1] — 2026-08-11
+
+**A patch on the release that made the product's own cost figures honest, for the
+four cells that refresh did not reach.** No analysis changes: `onboard` payloads
+on spring-petclinic and jobrunr are byte-identical against 5.0.0. What moves is
+the operational advice on two commands — `repo-ir` and `baseline capture` are
+foreground work at field scale, where 5.0.0 still sent them to a nightly job on a
+4.10.4 outcome.
+
+### Fixed
+
+- **Four cost cells the 5.0.0 refresh did not reach, and two of them said the
+  field could not run a command it has since run twice (C3-100).** C3-97 gave
+  every field figure the build it was taken on and re-measured what evaluation
+  #22 had run; what #22 had not run kept its 4.10.4 cell. `ask` (root) published
+  115 s, `baseline` 11 s, and — worse, because the claim is categorical rather
+  than numeric — `repo-ir` and `verify-edit` published `field_blocked`, which the
+  model renders as *"did not finish in an interactive session"*. Evaluation #23
+  ran all four from a purged cache on the same repository: root **72,3 s**,
+  `repo-ir` **9,8 s**, `baseline capture` **2,2 s**, `verify-edit` **76,6 s**.
+  `repo-ir` and `baseline` are foreground work at field scale where the product
+  was sending them to a nightly job.
+- **An outcome is a measurement, so it expires like one.** `field_blocked` was the
+  strongest claim in the table and the only one that could be written without a
+  build behind it. It is dated now wherever it is published (*"did not finish in
+  an interactive session on 4.10.4 … and nothing has re-measured it since"*), and
+  the battery rejects an undated one.
+- **A figure now states the cache state it was taken in.** The root analysis is
+  72,3 s from a purged cache and 0,3 s from a warm one; publishing one number
+  without saying which invites a reader to compare two different facts. Every
+  field figure carries `warm`/`cold`/`mixed`, in the `here:` line, the `cache
+  model` rows and the JSON.
+- **The headline anchor is read off the table instead of copied beside it.**
+  `FIELD_ANCHOR`, `FIELD_ANCHOR_SECONDS` and `FIELD_ANCHOR_MEASURED_VERSION` are
+  derived from the `spring-audit` row — the missed copy is what C3-100 was — and
+  `field_currency()` now also names every row measured before the newest figure in
+  the same table (`rows_behind_the_newest_field_measurement`), which is the
+  staleness that hid for three releases: not *"older than the build you are
+  running"* but *"older than the refresh that reached the row next to it"*.
+- **The root row was invisible to the surface its measurement exists for.**
+  `cost_row("ask (root)")` resolved to no row, so `cache model`'s `here:` line for
+  the root analysis was published from the command's *class*, with no figure in
+  it, on every repository. Found while checking the refresh on a real one.
+
+## [5.0.0] — 2026-08-11
+
+**The engine got 280× faster in 4.18.0 and every number the product quoted about
+its own cost still described the build before it.** This release changes no
+analysis: it makes what ASK says about itself true again, and makes the way it
+went stale impossible to repeat silently. Field evaluation #22 — eighth
+measurement of the same 3 342-file repository at the same commit — scored the
+build **9,2/10** and named this as the one place the product states something
+false with confidence.
+
+**Why a major.** No API breaks. What changes is an answer thousands of readers
+act on: commands that were published as *"not a foreground run here — `--output
+<file> --detach`, or a nightly job"* are now published as foreground work, and
+the operational advice in `--help`, `cache model`, the budget warning and the
+remedies moves with them. A recommendation that reverses is a contract change
+whatever the surface, so it is versioned like one.
+
+**Fixed in this release:**
+
+- **The cost anchors described a build that no longer exists (C3-97).** `spring-audit`'s
+  field anchor was **2 351 s**, measured on 4.11.0; the same command, on the same
+  repository at the same commit, takes **8,4 s** on 4.18.0 — the two
+  catastrophic-backtracking patterns behind that figure were deleted in C3-95 and
+  C3-96. Four surfaces read the anchors and none could tell they were old:
+  `execution_plan`'s `here:` verdict, the budget warning, the `cache model`
+  header, and the front page. The product therefore recommended a nightly job for
+  an eight-second command, and an operator sizing `ASK_MAX_ANALYSIS_SECONDS` from
+  it would set the budget ~280× too high. Anchors refreshed from evaluation #22
+  (`spring-audit` 2 351 → 8,4 s · `risk` 3 232 → 73,3 s · `posture` 38 → 8,0 s ·
+  `migrate-check` 26,7 → 10,2 s · `endpoints` 5,0 → 3,8 s), first anchors recorded
+  for `impact-chain` 5,5 s, `validation` 17,4 s, `pr-impact` 12,5 s, `impact`
+  7,7 s and `explain` 4,4 s — and `modernize`, carried as *did not finish* since
+  4.10.4, is a measurement again at **9,1 s**.
+- **And they cannot go stale silently again.** Every field figure now carries
+  `field_measured_version`, the build it was taken on. A figure from an earlier
+  release is still published — a measurement at that size beats silence — but it
+  arrives labelled *"measured on 4.10.4, not re-measured on 5.0.0"* wherever it is
+  read, and `ask cache model --json` publishes `field_currency` naming every row
+  in that state. This is the mechanism `REFERENCE_MEASURED_VERSION` already gave
+  the reference figures; the field anchors, which are the ones that decide how a
+  command is offered, had none.
+- **The front page paraphrased the table instead of deriving it (CL-21).** *"Repo-wide/deep
+  compositions can take minutes … use deep jobs nightly"* was written in `cli`
+  beside the model it described, so it aged separately from the anchors it
+  paraphrased. It is generated from `cache_model.cost_sentence()` now: refreshing
+  a measurement refreshes the prose, and a battery asserts the front page contains
+  exactly what the model generates.
+- **The performance gate had no baseline to compare against (C3-98).** F-AP shipped
+  the detector in 4.13.0 and it has run nightly since, self-testing that a
+  synthetic 3× regression would fail — against `docs/perf/baselines/gate-latest`,
+  a directory that was never created. Every run ended in the gate refusing to
+  report green (*"a gate that cannot be red is not evidence"*), which is why eight
+  consecutive field evaluations found no evidence that any benchmark gates a
+  release. The baseline is committed: six cells on BroadleafCommerce, warm, five
+  runs each, captured on the runner at 4.18.0, with provenance and a refresh
+  procedure beside them. First real comparison passed with `regressions: []`, and
+  the observed runner noise floor — ±5 %, widest on the shortest cell — is
+  published next to the 20 % threshold it has to be read against.
+- **The gate's exclusion list quoted a deleted cost (C3-99).** `risk` was excluded
+  because it took *54 minutes* on the gate repository. Since C3-96 it takes
+  **68 s** there. The reason now says so, and names the only thing still keeping
+  it out: no baseline cell exists for it yet.
+- **Stale cost claims elsewhere in the documentation.** README (the proof table's
+  caveat and the problem statement), `USER_GUIDE` (the "Start here" framing and
+  the spinner paragraph), `docs/CACHE.md` (regenerated), `docs/perf/REGRESSION-GATE.md`
+  §3, and the module docstrings of `execution_plan`, `phased_run` and `detach`,
+  where a 408 s / 2 351 s cost was narrated in the present tense.
+
+**Deliberately not in this release:** the `chunk-file -c` remap. The guide says the
+short form moves from `--chunk` to `--copy` "at the next major"; this major
+changes no invocation, and breaking a working command line as a side effect of a
+documentation-truth release would be the wrong trade. It waits for a major that
+changes the command surface on purpose.
+
+**Not changed:** any analysis, any payload, any schema. Every rule, every count and
+every verdict this build produces is byte-identical to 4.18.0's.
+
 ## [4.18.0] — 2026-08-10
 
 **A field battery over the test repositories, run against 4.17.0 and aimed first

{sourcecode-4.18.0 → sourcecode-5.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.18.0
+Version: 5.0.1
 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.18.0-blue)
+![Version](https://img.shields.io/badge/version-5.0.1-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`**
@@ -54,7 +54,7 @@ Description-Content-Type: text/markdown
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On a large Java/Spring monolith that is thousands of files of parsing per turn, repeated for every question asked about the same unchanged tree. Multiply it by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
 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.
 
@@ -69,7 +69,7 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most, and inventory commands scale with file count. What a repository-wide analysis costs tracks the build more than the file count: on one 3,342-file monolith, at one commit, `spring-audit` measured 2,351s on 4.11.0 and **8.4s on 4.18.0** with a byte-identical payload — so ASK publishes measured anchors and the release each was taken on, and never projects a duration for your repository. `ask cache model` prints both anchors per command, and `risk` — the one composition still measured in the tens of seconds at that size — is the one to give a budget or a detached run.
 
 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.
 
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.18.0 — and, on a build that has aged,
+ask version                    # ask 5.0.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.18.0 → sourcecode-5.0.1}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.18.0-blue)
+![Version](https://img.shields.io/badge/version-5.0.1-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`**
@@ -16,7 +16,7 @@
 
 ## The problem
 
-Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On small and mid-sized repos that cost is seconds; on large Java/Spring monoliths, repo-wide semantic composition can be minutes. Multiply that by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. On a large Java/Spring monolith that is thousands of files of parsing per turn, repeated for every question asked about the same unchanged tree. Multiply it by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
 
 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.
 
@@ -31,7 +31,7 @@ ASK Engine solves this with a persistent structural cache keyed on file content
 | Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
 | BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
 
-These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most. Inventory commands scale with file count. Repo-wide/deep compositions such as `risk`, `audit-report` and large `spring-audit` runs can take minutes on multi-thousand-endpoint repositories and belong in a supervised or nightly job unless CI sets an explicit budget.
+These numbers are cache-layer benchmarks, not a promise for every command. Per-symbol queries and compact context benefit most, and inventory commands scale with file count. What a repository-wide analysis costs tracks the build more than the file count: on one 3,342-file monolith, at one commit, `spring-audit` measured 2,351s on 4.11.0 and **8.4s on 4.18.0** with a byte-identical payload — so ASK publishes measured anchors and the release each was taken on, and never projects a duration for your repository. `ask cache model` prints both anchors per command, and `risk` — the one composition still measured in the tens of seconds at that size — is the one to give a budget or a detached run.
 
 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.
 
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.18.0 — and, on a build that has aged,
+ask version                    # ask 5.0.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.18.0 → sourcecode-5.0.1}/pyproject.toml

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

{sourcecode-4.18.0 → sourcecode-5.0.1}/scripts/perf_gate.py

@@ -33,7 +33,13 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
 from sourcecode import perf  # noqa: E402
+# The directory a repository is checked out under is the harness's fact, not a
+# second one this script or a workflow may restate: CI cloned the gate repo into
+# `fleet/broadleaf` while the harness looked for `fleet/BroadleafCommerce`, so
+# every nightly measured zero cells. `--print-config` now publishes the one name.
+from perf_harness import FLEET  # noqa: E402
 
 
 def load_cells(directory: Path) -> dict[str, dict]:
@@ -98,6 +104,8 @@ def _print_config() -> int:
         "threshold": perf.RELEASE_GATE_THRESHOLD,
         "repository": perf.RELEASE_GATE_REPO,
         "repository_url": perf.RELEASE_GATE_REPO_URL,
+        # Where the harness will look for that checkout, under the fleet root.
+        "fleet_subdir": FLEET.get(perf.RELEASE_GATE_REPO, perf.RELEASE_GATE_REPO),
         "repository_scale": perf.RELEASE_GATE_REPO_SCALE,
         "mode": perf.RELEASE_GATE_MODE,
         "min_runs": perf.RELEASE_GATE_MIN_RUNS,
@@ -122,6 +130,11 @@ def main() -> int:
     ap.add_argument("--allow-incomparable", action="store_true",
                     help="Do not fail cells whose env/host differ. Off by default: "
                          "an incomparable cell is an unmeasured one.")
+    ap.add_argument("--require-baseline", action="store_true",
+                    help="Fail when the baseline holds no cells. A run with nothing "
+                         "to compare against records every cell as `new` and passes; "
+                         "that is a recording, not a gate, and CI must not read it "
+                         "as one.")
     ap.add_argument("--report", type=Path, help="Write the perf-gate-v1 report here.")
     ap.add_argument("--table", type=Path, help="Write the release-notes markdown table here.")
     ap.add_argument("--self-test", action="store_true",
@@ -143,6 +156,12 @@ def main() -> int:
               f"which the gate reads as a failure, not a pass.", file=sys.stderr)
         return 1
     baseline = load_cells(args.baseline) if args.baseline else {}
+    if args.require_baseline and not baseline:
+        where = args.baseline if args.baseline else "<no --baseline given>"
+        print(f"no baseline cells in {where} — every cell would be recorded as "
+              f"`new` and the run would pass without comparing anything. A gate "
+              f"that cannot be red is not evidence.", file=sys.stderr)
+        return 1
 
     report = perf.gate_report(
         baseline, current,

{sourcecode-4.18.0 → sourcecode-5.0.1}/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.18.0"
+__version__ = "5.0.1"