sourcecode 4.17.0__tar.gz → 5.0.0__tar.gz

{sourcecode-4.17.0 → sourcecode-5.0.0}/.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.17.0 → sourcecode-5.0.0}/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 ## [Unreleased]
 
+## [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
+at where the time goes.** Three defects, all found by measuring rather than by
+reading: one answer that was silently about the wrong repository, and two scans
+that could not finish. `risk` on BroadleafCommerce (2 985 files) did not return in
+twenty minutes and now returns a complete answer in **68 s**.
+
+**Fixed in this release:**
+
+- **A run bounded to a subdirectory answered for the whole repository (C3-94).**
+  The shared Java parse was keyed on the worktree alone, so a run over a
+  subdirectory stored its subset under the repository-wide key and the next
+  repository-wide command read it. Measured on openmrs-core: `explain WebUtil
+  <repo>/web` left a **42-file / 382-symbol** CIR where the repository has 861 and
+  11 605, and `impact-chain` then answered from it — reporting 861 files beside
+  382 symbols, and dropping from `confidence: high` to `low` with no input change.
+  The analysed set is now part of the key; a repository-wide run owns the shared
+  entry and a bounded run keys on its own, so bounded runs are **cached** instead
+  of being exempt. The rule lived in one call site and four others wrote the key
+  unguarded; it now lives in the cache, behind one door.
+- **Naming the enclosing type backtracked exponentially (C3-95).** Two scanners
+  carried the same ambiguous pattern — a whitespace branch inside a starred group,
+  followed by another starred whitespace group. Measured: **13 ms** for 200 leading
+  spaces on one line, 1,17 s for 800, **10,1 s for 1 600**. Now linear: 0,06 ms at
+  1 600 and 0,76 ms at 20 000. `scan_security_configuration` on BroadleafCommerce
+  **3,34 s → 1,53 s**, same findings.
+- **`risk` could not finish, inside a regex no budget can interrupt (C3-96).**
+  `_java_methods` runs a method pattern over every source, and that pattern let the
+  same whitespace be consumed in three places at once. A catastrophic match runs in
+  CPython's C regex engine, which never returns to the interpreter — so the
+  deadline C3-87 installed is not read, and neither is a Ctrl-C. Rewritten so every
+  separator is consumed once, with the matches asserted **identical** over 1 771
+  files: eureka **142,35 s → 2,10 s**, jobrunr 29,38 s → 1,75 s, openmrs-core
+  35,25 s → 11,11 s, and `risk` on BroadleafCommerce **>20 min (killed) → 68 s**,
+  15 of 15 defects composed.
+
+**Not claimed by this release:** routing `spring-audit` and `risk` onto the shared
+parse is a correctness change, not a measured speed-up — the per-file parse cache
+already absorbed most of it, and the A/B on openmrs-core and BroadleafCommerce
+came out inside the noise. The residual cost of the method scan is polynomial, not
+linear, and `migrate-check` and `endpoints` still gain nothing from a warm; both
+are open in `.planning/ROADMAP-FIELD-BATTERY-2026-08-10.md`.
+
 ## [4.17.0] — 2026-08-10
 
 **The Part 1 queues of field evaluations #20 and #21, and the first three

{sourcecode-4.17.0 → sourcecode-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.17.0
+Version: 5.0.0
 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.17.0-blue)
+![Version](https://img.shields.io/badge/version-5.0.0-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.17.0 — and, on a build that has aged,
+ask version                    # ask 5.0.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.17.0 → sourcecode-5.0.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.17.0-blue)
+![Version](https://img.shields.io/badge/version-5.0.0-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.17.0 — and, on a build that has aged,
+ask version                    # ask 5.0.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.17.0 → sourcecode-5.0.0}/pyproject.toml

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

{sourcecode-4.17.0 → sourcecode-5.0.0}/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.17.0 → sourcecode-5.0.0}/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.17.0"
+__version__ = "5.0.0"