sourcecode 5.0.1__tar.gz → 5.1.0__tar.gz

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

@@ -60,7 +60,7 @@ jobs:
           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 "modes=$(python3 -c "import json;print(' '.join(json.load(open('gate-config.json'))['modes']))")" >> "$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"
 
@@ -79,7 +79,7 @@ jobs:
           python3 scripts/perf_harness.py \
             --repos "${{ steps.cfg.outputs.repo }}" \
             --commands ${{ steps.cfg.outputs.commands }} \
-            --modes "${{ steps.cfg.outputs.mode }}" \
+            --modes ${{ steps.cfg.outputs.modes }} \
             --runs "${{ steps.cfg.outputs.runs }}" \
             --fleet-root fleet \
             --out perf-run

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

@@ -2,6 +2,101 @@
 
 ## [Unreleased]
 
+## [5.1.0] — 2026-08-11
+
+**The operational queue field evaluation #25 left open, and the one row it opened
+that this project can act on.** No analysis changes: `endpoints`, `validation`,
+`posture`, `spring-audit` and `migrate-check` were re-run on spring-petclinic,
+jobrunr and BroadleafCommerce against 5.0.1 from a purged cache, and every
+payload matches byte for byte except the fields that are clocks by definition
+(`generated_at`, `analysis_time_ms`). What moves is what the product does when
+you clear a cache, compare a tree with itself, ask it whether you have edited
+anything, or read what a command costs — and `delta` / `contract-diff` gain one
+declared key, `comparison.identical_states`.
+
+### Fixed
+
+- **A confirmation prompt that cannot be answered is diagnosed, not raised
+  (C3-106).** v1.45.0 guarded the case it knew about — stdin that is not a
+  terminal — and the field found the one it does not cover: a PowerShell 5.1
+  session driven by a harness where `isatty()` answers true and the read hits
+  end-of-input at once, producing a Python traceback under a half-printed prompt.
+  All four prompts (`cache clear`, `cache context-clear`, `mcp init`,
+  `mcp remove` — the last two had no guard at all) now emit the product's own
+  envelope: `INVALID_INPUT`, the command that asked, `reason:
+  unanswerable_prompt`, and the `--yes` flag that removes the question. Exit 2,
+  because nothing was done. A plain "no" is still an answer: exit 1.
+- **The shared parse store can be cleared, and says so (C3-104).** `cache status`
+  publishes three layers and `cache clear` emptied two; the third — the per-file
+  parse store — had no eviction surface at all, so a from-scratch audit meant
+  `rm -rf ~/.sourcecode/parse-cache-v1`, a path the field had to learn from our
+  documentation. `ask cache clear --global` empties it and reports what it
+  removed; the default run names the layer, its size and the flag. Global on
+  purpose: the store is content-addressed across repositories, so "this
+  repository's entries" is not a set it can produce.
+- **One tree state is read once (C3-107).** `delta` and `contract-diff` built both
+  sides and then asked whether they differ. Identity is decided first — the
+  commit on the ref path, `cache.worktree_signature` on the checkout path, and
+  only when both sides produced a signature — so identical refs are materialised
+  once and the head IR is the base one. `comparison.identical_states` is always
+  present, with its basis, so a consumer can tell a degenerate comparison from a
+  real one. Wall time does not move on macOS (9,28 → 9,21 s on BroadleafCommerce):
+  the caches already served the second side, and what this removes is work whose
+  result the product already held.
+- **A clean tree is not checked out a second time (C3-102).** `verify-edit` reads
+  the shared entry instead of materialising HEAD in a throwaway worktree when git
+  reports the tree unmodified, and writes what it builds into both the shared and
+  the HEAD-sha lanes, so the first edit after a clean run is still warm. The
+  measured gain is small (10,32 → 10,03 s cold on BroadleafCommerce): the field's
+  76,6 s is one build of a 3 342-file repository, not a duplicated one. What
+  changes is that the build is no longer written where only `verify-edit` can
+  read it, and a clean-tree run no longer writes `.git/worktrees` in your
+  repository.
+- **The `repo-ir` size band contains the largest repository ever measured
+  (C3-105).** The band was 10,8-27,9 KB/file and the field measured 30,3
+  (101 254 852 B over 3 342 files) — the one number offered for planning excluded
+  the measurement a reader would take. The fifth sample is admitted, and the band
+  now publishes its sample size and its direction: the top under-states, because
+  the sample that set it counted tests among its files and the estimate does not.
+
+### Added
+
+- **A cached core richer than the requested view now serves it (C3-103).** The
+  overlay lookup already reused a *poorer* base and re-attached what it flipped;
+  the reverse was never tried, so asking for less than what was on disk paid for
+  a full analysis. The candidate set is symmetric now, with the dropped blocks
+  removed from the view so a caller never receives something it did not ask for.
+  On jobrunr: `--compact --git-context` then `--compact`, 1,15 s → **0,32 s**,
+  payload equal to a cold run block for block.
+- **Every build carries an in-house measurement of itself (C3-109).** The field
+  anchors are the field's, on their repository and their machine, so this project
+  can never refresh them — which is why B17 reopened one release after it closed:
+  labelling a figure does not re-measure it. `ask cache model` now prints the
+  release gate's own figure beside the field's (`gate:`, `gate_measurement`,
+  `gate_currency()`), with its scale, cache state, host class and build. Beside,
+  never instead — and when the in-house one is behind there is a command to fix
+  it rather than an evaluation to wait for. Generated from the committed baseline
+  by `scripts/sync_gate_anchors.py`; the suite fails if the two disagree.
+- **The gate measures the cold regime (C3-108).** Four consecutive in-house A/Bs
+  have failed to reproduce a field-reported regression, and the gate measured
+  warm only — while every field round since #23 purges every layer first. Cold
+  cells are captured and published (`observed_not_gated`, `decides: false` per
+  cell) and still may not block a release, because a cold median on an ephemeral
+  runner carries a cold page cache as well as a cold parse store.
+
+### Not fixed, and why
+
+- **The 2-2,6x regression across sixteen commands reported between 4.18.0 and
+  5.0.1 (C3-108) is open and unattributed.** Measured here on the field's own
+  method — every layer purged before each run — three builds on BroadleafCommerce
+  land within 2 % (`endpoints` 4,96 / 4,19 / 4,19 s · `spring-audit` 9,87 / 9,76 /
+  9,75 s · `repo-ir` 4,20 / 4,12 / 4,21 s · `validation` 9,39 / 9,26 / 9,33 s for
+  5.0.0 / 4.18.0 / 5.0.1), and the ADR-0006 harness on openmrs-core lands between
+  -0,6 % and +1,8 %, inside the ±5 % noise floor. The 4.18.0→5.0.1 diff is 13
+  files and 702 insertions, two of them on an analysis path and neither adding a
+  pass. A 2x a customer can measure is high whatever its cause, so the row stays
+  open: what it needs is a same-session A/B on the machine that sees it.
+
 ## [5.0.1] — 2026-08-11
 
 **A patch on the release that made the product's own cost figures honest, for the

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.0.1
+Version: 5.1.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-5.0.1-blue)
+![Version](https://img.shields.io/badge/version-5.1.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`**
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.0.1 — and, on a build that has aged,
+ask version                    # ask 5.1.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

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

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.0.1-blue)
+![Version](https://img.shields.io/badge/version-5.1.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`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.0.1 — and, on a build that has aged,
+ask version                    # ask 5.1.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

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

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

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

@@ -108,6 +108,10 @@ def _print_config() -> int:
         "fleet_subdir": FLEET.get(perf.RELEASE_GATE_REPO, perf.RELEASE_GATE_REPO),
         "repository_scale": perf.RELEASE_GATE_REPO_SCALE,
         "mode": perf.RELEASE_GATE_MODE,
+        # C3-108: what is measured and what decides are two lists now. The
+        # workflow reads `modes` for the harness; the gate reads the other.
+        "modes": list(perf.RELEASE_GATE_MEASURED_MODES),
+        "deciding_modes": list(perf.RELEASE_GATE_DECIDING_MODES),
         "min_runs": perf.RELEASE_GATE_MIN_RUNS,
         "commands": list(perf.RELEASE_GATE_COMMANDS),
         "exclusions": [

sourcecode-5.1.0/scripts/sync_gate_anchors.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Regenerate `sourcecode.gate_anchors` from the committed gate baseline (C3-109).
+
+The field anchors in `cache_model` are the **field's** measurements, taken on a
+private repository and a Windows machine. This repository can never refresh
+them, which is why B17 reopened one release after it closed: the mechanism that
+labels an anchor with its build works, and nothing can re-measure the number it
+labels.
+
+What this repository *can* measure every release is the gate — `perf-gate.yml`
+runs a declared command population on a 2 985-file repository under a declared
+host class, and commits the cells. This script copies those cells into the
+package, so a build can publish an in-house figure for **itself** beside a field
+anchor that belongs to an older one.
+
+One authority: the baseline JSON. The module is a derived artifact and
+`tests/test_gate_anchor_currency.py` fails when the two disagree, so a refreshed
+baseline that never reached the package is a red suite rather than a silent
+lie — which is the failure mode the whole row is about.
+
+Usage:
+    python3 scripts/sync_gate_anchors.py            # rewrite the module
+    python3 scripts/sync_gate_anchors.py --check    # exit 1 if it is out of date
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+BASELINE_DIR = REPO_ROOT / "docs" / "perf" / "baselines" / "gate-latest"
+MODULE_PATH = REPO_ROOT / "src" / "sourcecode" / "gate_anchors.py"
+
+_HEADER = '''"""gate_anchors.py — what the release gate measured, on the build that ran it.
+
+**Generated by `scripts/sync_gate_anchors.py` from `docs/perf/baselines/gate-latest/`.
+Do not edit by hand.** The baseline is the authority; this module is how a build
+carries it.
+
+C3-109. `cache_model`'s field anchors are the field's own measurements, on their
+repository and their machine — the reason they are trustworthy is the reason they
+cannot be refreshed here, and B17 reopened one release after closing because a
+refreshed anchor expires the moment the next release ships. This is the figure
+this project *can* re-measure every release: the gate's own population on a
+2 985-file repository, under a declared host class, with the build that produced
+it recorded beside it.
+
+It does not replace a field anchor and never overrides one. It is the second
+figure a reader gets — one measured at field scale on another build, one measured
+on this build on a repository we control — and the pair is honest in a way
+neither is alone.
+"""
+from __future__ import annotations
+
+'''
+
+
+def _cells() -> "dict[str, dict]":
+    out: "dict[str, dict]" = {}
+    for path in sorted(BASELINE_DIR.glob("*.json")):
+        cell = json.loads(path.read_text(encoding="utf-8"))
+        command = cell.get("command") or "ask"
+        out[command] = {
+            "seconds": round(float(cell["wall_ms"]["p50"]) / 1000.0, 2),
+            "mode": cell.get("mode", "unknown"),
+            "runs": int(cell.get("runs", 0) or 0),
+        }
+    return out
+
+
+def _meta() -> dict:
+    first = next(iter(sorted(BASELINE_DIR.glob("*.json"))), None)
+    if first is None:
+        return {}
+    cell = json.loads(first.read_text(encoding="utf-8"))
+    return {
+        "version": cell.get("tool_version", ""),
+        "captured_at": cell.get("captured_at", ""),
+        "repository": (cell.get("repo") or {}).get("name", ""),
+        "java_files": int((cell.get("repo") or {}).get("files", 0) or 0),
+        "host_class": (cell.get("env") or {}).get("host_id", "") or "github-ubuntu-latest",
+    }
+
+
+def render() -> str:
+    meta = _meta()
+    cells = _cells()
+    lines = [_HEADER]
+    lines.append("#: The build the gate cells below were captured on.\n")
+    lines.append(f'GATE_MEASURED_VERSION = {meta.get("version", "")!r}\n')
+    lines.append("#: When, so a reader can tell a stale capture from a missing one.\n")
+    lines.append(f'GATE_CAPTURED_AT = {meta.get("captured_at", "")!r}\n')
+    lines.append("#: The repository the gate measures, and its size axis.\n")
+    lines.append(f'GATE_REPOSITORY = {meta.get("repository", "")!r}\n')
+    lines.append(f'GATE_JAVA_FILES = {meta.get("java_files", 0)!r}\n')
+    lines.append(
+        "#: The host class the runs are comparable within. Cross-machine numbers\n"
+        "#: are recorded, never diffed (ADR-0006).\n"
+    )
+    lines.append(f'GATE_HOST_CLASS = {meta.get("host_class", "")!r}\n')
+    lines.append(
+        "\n#: command → measured wall time (p50 seconds), the cache mode it was\n"
+        "#: taken in, and how many runs the median is over.\n"
+    )
+    lines.append("GATE_ANCHORS: \"dict[str, dict]\" = {\n")
+    for command, cell in cells.items():
+        lines.append(
+            f"    {command!r}: {{\"seconds\": {cell['seconds']!r}, "
+            f"\"mode\": {cell['mode']!r}, \"runs\": {cell['runs']!r}}},\n"
+        )
+    lines.append("}\n")
+    return "".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--check", action="store_true",
+                    help="Do not write; exit 1 when the module is out of date.")
+    args = ap.parse_args()
+
+    if not BASELINE_DIR.exists():
+        print(f"no baseline directory at {BASELINE_DIR}", file=sys.stderr)
+        return 1
+    rendered = render()
+    current = MODULE_PATH.read_text(encoding="utf-8") if MODULE_PATH.exists() else ""
+    if args.check:
+        if current != rendered:
+            print(
+                "sourcecode/gate_anchors.py is out of date with "
+                "docs/perf/baselines/gate-latest — run scripts/sync_gate_anchors.py",
+                file=sys.stderr,
+            )
+            return 1
+        print("gate anchors are in sync")
+        return 0
+    MODULE_PATH.write_text(rendered, encoding="utf-8")
+    print(f"wrote {MODULE_PATH.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{sourcecode-5.0.1 → sourcecode-5.1.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__ = "5.0.1"
+__version__ = "5.1.0"

{sourcecode-5.0.1 → sourcecode-5.1.0}/src/sourcecode/cache_model.py

@@ -616,6 +616,103 @@ def field_currency() -> dict:
     }
 
 
+def gate_anchor(command: str) -> "Optional[dict]":
+    """What the release gate measured for *command*, or ``None`` (C3-109).
+
+    The third figure in this module, and the only one this repository can refresh
+    by itself. `REFERENCE_*` is a 3.2.2 measurement on a 2 000-file tree;
+    `field_seconds` is the field's, at 3 342 files, on their machine and their
+    build. Both age, and neither can be re-measured from here — which is exactly
+    how B17 reopened one release after it was closed: the labelling worked and
+    the number still expired.
+
+    The gate measures a 2 985-file repository under a declared host class every
+    release and commits its cells, so this figure carries the build that produced
+    it and can be brought current by running the gate. It never overrides a field
+    anchor — a measurement at field scale outranks one at gate scale — it is
+    published *beside* it, so an anchor from an older build is no longer the only
+    number a reader has.
+    """
+    try:
+        from sourcecode.gate_anchors import (
+            GATE_ANCHORS,
+            GATE_HOST_CLASS,
+            GATE_JAVA_FILES,
+            GATE_MEASURED_VERSION,
+            GATE_REPOSITORY,
+        )
+    except Exception:
+        return None
+    cell = GATE_ANCHORS.get(command)
+    if not cell:
+        return None
+    return {
+        "seconds": cell["seconds"],
+        "cache_state": cell["mode"],
+        "runs": cell["runs"],
+        "measured_on_version": GATE_MEASURED_VERSION,
+        "repository": GATE_REPOSITORY,
+        "java_files": GATE_JAVA_FILES,
+        "host_class": GATE_HOST_CLASS,
+    }
+
+
+def gate_currency() -> dict:
+    """Whether the in-house gate figures describe the build in hand (C3-109).
+
+    Same shape and same purpose as `field_currency`, for the anchor set that can
+    actually be refreshed. When this says `current: false`, the remedy is a
+    command rather than a hope: re-run the gate on the tag and commit the cells.
+    """
+    from sourcecode import __version__
+
+    current = __version__
+    try:
+        from sourcecode.gate_anchors import (
+            GATE_ANCHORS,
+            GATE_CAPTURED_AT,
+            GATE_HOST_CLASS,
+            GATE_JAVA_FILES,
+            GATE_MEASURED_VERSION,
+            GATE_REPOSITORY,
+        )
+    except Exception:
+        return {
+            "available": False,
+            "running_version": current,
+            "statement": (
+                "This build carries no gate measurement of its own. The gate "
+                "publishes one per release (docs/perf/REGRESSION-GATE.md); until "
+                "it runs, the field anchors are the only measured figures here."
+            ),
+        }
+    return {
+        "available": True,
+        "measured_on_version": GATE_MEASURED_VERSION,
+        "running_version": current,
+        "current": GATE_MEASURED_VERSION == current,
+        "captured_at": GATE_CAPTURED_AT,
+        "repository": GATE_REPOSITORY,
+        "java_files": GATE_JAVA_FILES,
+        "host_class": GATE_HOST_CLASS,
+        "commands": sorted(GATE_ANCHORS),
+        "statement": (
+            f"The release gate measured {len(GATE_ANCHORS)} commands on "
+            f"{GATE_REPOSITORY} ({GATE_JAVA_FILES} Java files, {GATE_HOST_CLASS}) "
+            + (
+                f"on {current}, the build you are running."
+                if GATE_MEASURED_VERSION == current
+                else (
+                    f"on {GATE_MEASURED_VERSION}; you are running {current}, which "
+                    f"the gate has not measured. Re-run it on this build "
+                    f"(docs/perf/REGRESSION-GATE.md) — unlike the field anchors, "
+                    f"this is a figure this project can refresh."
+                )
+            )
+        ),
+    }
+
+
 def reference_currency() -> dict:
     """How old the reference figures are, in releases the reader can name (F-AP).
 
@@ -680,6 +777,11 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
         # measured 2 351 s and 8,4 s on two of our own builds (C4-19, C3-97).
         "field_anchor": FIELD_ANCHOR,
         "field_currency": field_currency(),
+        # C3-109: and the figure this project can refresh by itself. A field
+        # anchor belongs to the build the field ran; this one belongs to the
+        # build the gate ran, which is a release away at worst instead of
+        # unreachable. Published beside, never instead.
+        "gate_currency": gate_currency(),
         "commands": [
             {
                 "command": cmd.command,
@@ -716,6 +818,12 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
                         "note": field_anchor_note(cmd),
                     }
                 ),
+                # C3-109: the in-house measurement of this command, on the build
+                # the gate last ran. Absent for commands the gate does not cover —
+                # its population is declared in `sourcecode.perf`, with the
+                # exclusions and their reasons, and an axis nobody measured is
+                # never a number here.
+                "gate_measurement": gate_anchor(cmd.command),
             }
             for cmd in COMMANDS
         ],
@@ -827,6 +935,7 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
     lines.append(f"  Timings: {REFERENCE_REPOSITORY}, each command measured in isolation.")
     lines.append(f"  {reference_currency()['statement']}")
     lines.append(f"  {field_currency()['statement']}")
+    lines.append(f"  {gate_currency()['statement']}")
     width = max(len(c.command) for c in COMMANDS)
     for cmd in COMMANDS:
         repeat = "repeat cached" if cmd.repeat else "recomputes"
@@ -848,6 +957,17 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
                 f"  {' ' * width}    field:    {shown} at "
                 f"{_thousands(FIELD_ANCHOR_JAVA_FILES)} Java files{suffix}"
             )
+        _gate = gate_anchor(cmd.command)
+        if _gate:
+            # C3-109: the in-house figure, beside the field's rather than instead
+            # of it — one is at field scale on another build, one is on a build
+            # this project can bring current.
+            lines.append(
+                f"  {' ' * width}    gate:     {_gate['seconds']:g} s at "
+                f"{_thousands(_gate['java_files'])} Java files "
+                f"({_gate['cache_state']} cache, on {_gate['measured_on_version']}, "
+                f"{_gate['host_class']})"
+            )
         if cmd.note:
             lines.append(f"  {' ' * width}    {cmd.note}")
         if here is not None and cmd.command in here.per_command: