sourcecode 4.11.0__py3-none-any.whl → 4.14.0__py3-none-any.whl

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.11.0"
+__version__ = "4.14.0"

sourcecode/architectural_baseline.py

@@ -30,12 +30,14 @@ the perf baselines do.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from sourcecode import __version__ as TOOL_VERSION
+from sourcecode import readonly as _readonly
 from sourcecode.architectural_delta import ArchMetrics, diff_metrics, extract_metrics
 from sourcecode.perf import collect_env
 
@@ -365,21 +367,40 @@ def _baseline_filename(baseline: dict) -> str:
 #: a 14 587-entry structural inventory of the code. A self-confined
 #: `.ask/.gitignore` is the honest form: it never touches the user's own
 #: `.gitignore`, and it stops applying the moment they delete the directory.
+#: C3-74 corrected the last line. It used to read *"Delete this file to version
+#: them deliberately"*, and deleting it is the one action that would commit a
+#: baseline carrying `env.hostname_hash`, `cpu` and `cores` — an invitation to do
+#: the thing the file exists to prevent. It now states the consequence instead.
 _ASK_DIR_GITIGNORE = (
     "# Written by `ask` the first time it created this directory.\n"
     "# These are local analysis artefacts: a structural inventory of your code\n"
     "# and, if you asked for it, the machine that measured it. Nothing here\n"
-    "# belongs in a commit. Delete this file to version them deliberately.\n"
+    "# belongs in a commit.\n"
+    "#\n"
+    "# Removing this file makes everything here committable, including any\n"
+    "# recorded machine fingerprint (`--record-env`: hostname hash, CPU, cores).\n"
+    "# Version these deliberately only if you intend to publish that.\n"
     "*\n"
 )
 
 
-def protect_ask_dir(out_dir: Path) -> None:
+def protect_ask_dir(out_dir: Path, *, announce: bool = True) -> None:
     """Give a freshly created `.ask/` its own `.gitignore` (C3-68).
 
     Best-effort and never overwriting: a user who edited it decided something,
     and a tool that re-imposes its default on every run is worse than one that
     never wrote it.
+
+    **Call this where the write happens, never where the path is computed.** This
+    function *creates* the directory in order to protect it, so calling it
+    speculatively is a write — which is how `migrate-check` came to leave a
+    `.ask/.gitignore` inside a repository it had only read (C3-74).
+
+    `announce` puts one line on stderr the first time the directory is created,
+    with its path. A side effect inside somebody else's repository is exactly what
+    I-8 says must be declared, and this one hides from the check an auditor makes:
+    `git status --porcelain` is clean because the ignore file ignores itself, and
+    only `--ignored` reveals `!! <scope>/.ask/`.
     """
     try:
         ask_dir = Path(out_dir)
@@ -391,14 +412,41 @@ def protect_ask_dir(out_dir: Path) -> None:
             return
         marker = ask_dir / ".gitignore"
         if not marker.exists():
+            created = not ask_dir.exists()
+            # F-AS: the guard raises an OSError, which the `except OSError` below
+            # turns into "did not write" — the mode's promise, no new branch.
+            _readonly.guard(ask_dir, what="this tool's own directory")
             ask_dir.mkdir(parents=True, exist_ok=True)
             marker.write_text(_ASK_DIR_GITIGNORE, encoding="utf-8")
+            if announce and created:
+                _announce_ask_dir(ask_dir)
     except OSError:
         return
 
 
+def _announce_ask_dir(ask_dir: Path) -> None:
+    """One line, on stderr, naming what was created and how to move it (C3-74)."""
+    import sys
+
+    try:
+        # No flag is named here on purpose: the commands that write under `.ask/`
+        # spell the override differently (`baseline capture --dir`,
+        # `migrate-check --history-dir`), and a message that names the wrong one
+        # is the class of defect this ledger is about.
+        sys.stderr.write(
+            f"[ask] created {ask_dir}{os.sep} for this run's local artefacts — "
+            f"git-ignored by its own .gitignore, so `git status` will not show it "
+            f"(`git status --ignored` will). The command's directory option takes a "
+            f"path outside the repository if you want them elsewhere.\n"
+        )
+        sys.stderr.flush()
+    except Exception:
+        pass
+
+
 def write_baseline(baseline: dict, out_dir: Path) -> Path:
     """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
+    _readonly.guard(out_dir, what="baseline history directory")
     out_dir.mkdir(parents=True, exist_ok=True)
     protect_ask_dir(out_dir)
     path = out_dir / _baseline_filename(baseline)

sourcecode/cache_model.py

@@ -75,10 +75,17 @@ class CommandCache:
     warm_seconds: "Optional[float]" = None
     #: The other measured point: this command on the field repository
     #: (3 342 Java files, Windows 11 / PowerShell 5.1 / pipx, cold), from field
-    #: evaluations #13 and #14. Seconds where a run finished; `field_blocked`
+    #: evaluations #13, #14 and #16. Seconds where a run finished; `field_blocked`
     #: where it did not — the harness promoted the process and the session died,
     #: which is a measurement of a different kind and is never written as a
     #: duration. Rows with neither were not attempted there.
+    #:
+    #: C3-72: where two evaluations of the same command at this size disagree, the
+    #: figure here is the **most recent** one, because it describes the build a
+    #: reader is about to run — and the previous figure is kept in the comment
+    #: beside it rather than dropped, since a cost that moved by 5,8× between two
+    #: releases (spring-audit, 408 s in #13 against 2 351 s in #16) is itself the
+    #: measurement C3-76 exists for.
     field_seconds: "Optional[float]" = None
     field_blocked: bool = False
 
@@ -92,20 +99,36 @@ REFERENCE_REPOSITORY = (
 #: figures are relative to.
 REFERENCE_JAVA_FILES = 2000
 
+#: The build the reference figures were measured on. F-AP's second rider: C3-60
+#: conditioned these figures on the repository in hand; this is the other half —
+#: **keeping them current**, or, when they are not current, saying so. A table
+#: measured nine releases ago and printed without its provenance is a prediction
+#: presented as a measurement, which is the one thing this product does not do.
+#: The nightly gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them; this
+#: constant is what makes the gap visible until it does.
+REFERENCE_MEASURED_VERSION = "3.2.2"
+
 #: The other end of the measured range, and the reason this module publishes a
-#: *class* rather than a projected duration (C4-19). Field evaluation #13, on
+#: *class* rather than a projected duration (C4-19). Field evaluation #16, on
 #: Windows 11 / PowerShell 5.1 / pipx / Python 3.10: `spring-audit` on a
-#: 3 342-file repository ran **408 s** — 46× the 8.8 s the same command takes on
-#: the 2 000-file reference. Cost does not scale with file count in any way this
-#: product has measured, so a projected "~15 s on your repository" would be a
-#: confident falsehood of exactly the kind the ledger exists to prevent. What can
-#: be said honestly is the class, the two measured anchors, and how to run it.
+#: 3 342-file repository ran **2 351 s** — 267× the 8.8 s the same command takes
+#: on the 2 000-file reference, for a repository 1,7× the size. Cost does not
+#: scale with file count in any way this product has measured, so a projected
+#: "~15 s on your repository" would be a confident falsehood of exactly the kind
+#: the ledger exists to prevent. What can be said honestly is the class, the two
+#: measured anchors, and how to run it.
+#:
+#: C3-72 replaced evaluation #13's 408 s with #16's 2 351 s here: the same command
+#: on the same repository at the same commit, measured three releases later
+#: (2 557 s in 4.10.6, 2 398 s in 4.10.7, 2 351 s in 4.11.0). The older figure was
+#: the one a budget message quoted as "~600s" for three releases while the
+#: measurement stood four times higher.
 FIELD_ANCHOR = (
-    "field evaluation #13: spring-audit on 3 342 Java files took 408 s "
-    "(Windows, pipx, cold) against 8.8 s on the 2 000-file reference"
+    "field evaluation #16: spring-audit on 3 342 Java files took 2 351 s "
+    "(Windows, pipx, warm cache) against 8.8 s on the 2 000-file reference"
 )
 FIELD_ANCHOR_JAVA_FILES = 3342
-FIELD_ANCHOR_SECONDS = 408.0
+FIELD_ANCHOR_SECONDS = 2351.4
 
 
 #: Every layer keys on `cache.worktree_signature` — the exact tree state (C1-9).
@@ -150,7 +173,9 @@ LAYERS: tuple[Layer, ...] = (
         location="~/.sourcecode/parse-cache-v1/",
         invalidated_by=(
             "the file's own bytes and the extractor's source — content-addressed, "
-            "so it is never stale and never needs invalidating"
+            "so it is never stale and never needs invalidating. Bounded by "
+            "`ASK_PARSE_CACHE_MAX_MB` (default 512 MB, least-recently-used, "
+            "enforced on write) and reported in `cache status` (F-AR)"
         ),
         warmed="filled for every Java file the warm parses",
     ),
@@ -176,14 +201,15 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Resolves the conditional bean graph on every run, over the shared CIR a warm "
                  "builds — the parse it used to repeat for itself. `--diff` compares two profile "
                  "sets over that one IR, so the second side costs the resolution only.",
-                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_blocked=True),
+                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_seconds=38.0),
     CommandCache("risk", ("cir", "parse"), "shared", False,
                  "Composes what the audit, impact-chain and the posture already answer, so it "
                  "pays each of their costs once over the shared CIR a warm builds — one parse "
                  "for the whole composition, and the reachability query is cached per symbol "
                  "within the run.",
                  "not measured on the battery yet — the composition is bounded by the "
-                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis", analysis_class="deep"),
+                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis",
+                 analysis_class="deep", field_seconds=3232.2),
     CommandCache("enrich", ("cir", "parse"), "shared", False,
                  "Runs the same composition as `risk` over the repository, then joins a SARIF "
                  "log to it. Reading the log is negligible; everything a warm helps with is the "
@@ -213,14 +239,14 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Recomputes the endpoint surface on every run, over a parse a warm has already "
                  "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "
                  "the shared parse cache, and a warm measurably bought it nothing (C3-6).",
-                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=4.2),
+                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=5.0),
     CommandCache("spring-audit", ("ris", "parse"), "shared", False,
                  "Recomputes every run, but over a parse a warm has already paid for.",
-                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=408.0),
+                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=2351.4),
     CommandCache("migrate-check", ("cir",), "none", False,
                  "Computes its own inventory and shares nothing a warm builds. Only `--blast-radius` "
                  "reuses the shared CIR.",
-                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_blocked=True),
+                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_seconds=26.7),
     CommandCache("impact-chain", ("cir", "parse"), "shared", False,
                  "The CIR is the expensive half — this is where a warm pays most.",
                  "9.9 s → 1.7 s", analysis_class="core", cold_seconds=9.9, warm_seconds=1.7),
@@ -343,6 +369,34 @@ class Conditioning:
         )
 
 
+def reference_currency() -> dict:
+    """How old the reference figures are, in releases the reader can name (F-AP).
+
+    Returns the build the figures were measured on, the build running now, and
+    whether they are the same. The gap is not converted into a count of releases:
+    versions are not a distance and this module does not invent one. Naming both
+    builds is enough for a reader to see that a figure was measured on a different
+    one — which is the whole defect: *"no predice nada a 3 342 ficheros"* applies
+    to the size axis, and this is the same failure on the time axis.
+    """
+    from sourcecode import __version__
+
+    current = __version__
+    return {
+        "measured_on_version": REFERENCE_MEASURED_VERSION,
+        "running_version": current,
+        "current": REFERENCE_MEASURED_VERSION == current,
+        "statement": (
+            f"Measured on {REFERENCE_MEASURED_VERSION}; you are running {current}. "
+            f"The figures are that build's on that repository — they are not a "
+            f"prediction for this one, and the nightly performance gate "
+            f"(docs/perf/REGRESSION-GATE.md) is what re-measures them."
+            if REFERENCE_MEASURED_VERSION != current
+            else f"Measured on {current}, the build you are running."
+        ),
+    }
+
+
 def as_dict(here: "Optional[Conditioning]" = None) -> dict:
     """The whole model as data — what `ask cache model --json` emits."""
     conditioned: dict = {}
@@ -371,6 +425,9 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
         ],
         "reference_repository": REFERENCE_REPOSITORY,
         "reference_java_files": REFERENCE_JAVA_FILES,
+        # F-AP rider: the figures carry the build they were measured on, so a
+        # table nine releases old cannot read as this build's measurement.
+        "reference_currency": reference_currency(),
         # Published beside the reference so no consumer reads the figures as a
         # law: the same command has been measured 46× slower on a repository 1.7×
         # the size, on a different platform (C4-19).
@@ -412,6 +469,15 @@ def render_markdown() -> str:
     out.append("")
     out.append(f"Measured on {REFERENCE_REPOSITORY}, each command in isolation.")
     out.append("")
+    # The build, not the gap: this block is a checked-in document, so naming the
+    # *running* version here would make the doc drift on every release. `cache
+    # model` names both, because there a reader has a running build to compare to.
+    out.append(
+        f"Measured on release {REFERENCE_MEASURED_VERSION}. Figures are that "
+        f"build's on that repository, not a prediction for yours; the nightly "
+        f"performance gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them."
+    )
+    out.append("")
     out.append("| Command | A warm gives it | Measured (nothing cached → after a warm) | Repeat run cached | Layers | Notes |")
     out.append("|---|---|---|---|---|---|")
     for cmd in COMMANDS:
@@ -489,6 +555,7 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
     lines.append("")
     lines.append("What a warm gives each command")
     lines.append(f"  Timings: {REFERENCE_REPOSITORY}, each command measured in isolation.")
+    lines.append(f"  {reference_currency()['statement']}")
     width = max(len(c.command) for c in COMMANDS)
     for cmd in COMMANDS:
         repeat = "repeat cached" if cmd.repeat else "recomputes"