sourcecode 4.10.7__py3-none-any.whl → 4.12.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.10.7"
+__version__ = "4.12.0"

sourcecode/architectural_baseline.py

@@ -30,6 +30,7 @@ the perf baselines do.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
@@ -365,21 +366,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,12 +411,35 @@ def protect_ask_dir(out_dir: Path) -> None:
             return
         marker = ask_dir / ".gitignore"
         if not marker.exists():
+            created = not ask_dir.exists()
             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."""
     out_dir.mkdir(parents=True, exist_ok=True)

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
 
@@ -93,19 +100,26 @@ REFERENCE_REPOSITORY = (
 REFERENCE_JAVA_FILES = 2000
 
 #: 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).
@@ -176,14 +190,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 +228,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),
@@ -301,9 +316,59 @@ def layer(layer_id: str) -> Layer:
     raise KeyError(layer_id)
 
 
-def as_dict() -> dict:
+@dataclass(frozen=True)
+class Conditioning:
+    """The reader's repository, so the figures below are read against it (C3-60).
+
+    `verify-edit` is published here as *14,6 s → 9,6 s → 5,6 s* and described as
+    *"built for the edit loop"*; on the field repository the same command had not
+    answered at 495 s. Both are true, and printing only the first is what made
+    the second read as a defect in the reader's setup rather than as the scale
+    the figure was never measured at. The numbers do not change — what changes is
+    that they arrive with the repository they belong to, and with what is known
+    about the one in hand.
+
+    Built by the caller (`cli`) from `execution_plan`, which owns the scope
+    measurement; this module stays free of that dependency because
+    `execution_plan` already reads *it*.
+    """
+
+    scope: str                              # "3 342 Java files, cache cold"
+    transfers: "Optional[bool]"             # do the reference figures apply here?
+    per_command: "dict[str, str]"           # command → how it can be run here
+
+    def statement(self) -> str:
+        """One sentence about whether the figures below transfer to this scope."""
+        if self.transfers is None:
+            return (
+                f"This repository ({self.scope}) was not measured, so nothing below "
+                f"is claimed about it: the figures are the reference repository's."
+            )
+        if self.transfers:
+            return (
+                f"This repository ({self.scope}) is within the size the figures "
+                f"below were measured at ({REFERENCE_JAVA_FILES} Java files)."
+            )
+        return (
+            f"This repository ({self.scope}) is larger than the repository the "
+            f"figures below were measured on ({REFERENCE_JAVA_FILES} Java files), "
+            f"and cost has not been observed to scale with file count: "
+            f"{FIELD_ANCHOR}. Read each figure as the reference's, not as yours; "
+            f"the `here:` lines say how each command can be run on this one."
+        )
+
+
+def as_dict(here: "Optional[Conditioning]" = None) -> dict:
     """The whole model as data — what `ask cache model --json` emits."""
+    conditioned: dict = {}
+    if here is not None:
+        conditioned = {
+            "scope_measured": here.scope,
+            "reference_figures_transfer": here.transfers,
+            "conditioning": here.statement(),
+        }
     return {
+        **conditioned,
         "invalidation": (
             "Every layer keys on the exact tree state: any change to the analysed files "
             "invalidates it, committed or not. A clean tree keys on the commit, so a repeat "
@@ -334,6 +399,13 @@ def as_dict() -> dict:
                 "note": cmd.note,
                 "measured": cmd.measured or None,
                 "analysis_class": cmd.analysis_class,
+                # How this command can be run on the repository in hand, when one
+                # was measured. Absent rather than guessed otherwise (C3-60).
+                **(
+                    {"here": here.per_command[cmd.command]}
+                    if here is not None and cmd.command in here.per_command
+                    else {}
+                ),
                 "reference_seconds": (
                     None
                     if cmd.cold_seconds is None
@@ -366,7 +438,7 @@ def render_markdown() -> str:
     return "\n".join(out)
 
 
-def render_summary() -> str:
+def render_summary(here: "Optional[Conditioning]" = None) -> str:
     """The model as `ask cache model` prints it by default (C3-63).
 
     One line per layer and one line per command — every command named (nothing
@@ -376,6 +448,9 @@ def render_summary() -> str:
     own selling argument is token economy. That detail is still one flag away.
     """
     lines: list[str] = []
+    if here is not None:
+        lines.append(here.statement())
+        lines.append("")
     lines.append(
         "Invalidation: every layer keys on the exact tree state — any change to the "
         "analysed files invalidates it, committed or not."
@@ -396,6 +471,8 @@ def render_summary() -> str:
             f"  {cmd.command.ljust(cmd_width)}  {_WARM_LABEL[cmd.warm].ljust(warm_width)} "
             f"({repeat})  [{layers}]"
         )
+        if here is not None and cmd.command in here.per_command:
+            lines.append(f"  {' ' * cmd_width}  here: {here.per_command[cmd.command]}")
     lines.append("")
     lines.append(
         "Full detail (measured timings, per-command notes): ask cache model --full"
@@ -404,11 +481,14 @@ def render_summary() -> str:
     return "\n".join(lines)
 
 
-def render_text() -> str:
+def render_text(here: "Optional[Conditioning]" = None) -> str:
     """The model in full: every layer and command with its measured timing and note.
 
     `ask cache model --full`. See `render_summary` for the default."""
     lines: list[str] = []
+    if here is not None:
+        lines.append(here.statement())
+        lines.append("")
     lines.append("Invalidation — one rule for every layer")
     lines.append("  Every layer keys on the exact tree state. Any change to the analysed files")
     lines.append("  invalidates it, committed or not, tracked or not. A clean tree keys on the")
@@ -432,4 +512,6 @@ def render_text() -> str:
             lines.append(f"  {' ' * width}    measured: {cmd.measured}")
         if cmd.note:
             lines.append(f"  {' ' * width}    {cmd.note}")
+        if here is not None and cmd.command in here.per_command:
+            lines.append(f"  {' ' * width}    here: {here.per_command[cmd.command]}")
     return "\n".join(lines)

sourcecode/canonical_ir.py

@@ -19,7 +19,7 @@ import json
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Callable, Optional
 
 from sourcecode.cir_graphs import ImplementationGraph, InjectionGraph
 from sourcecode.repository_ir import (
@@ -526,6 +526,7 @@ def build_canonical_ir(
     root: Path,
     *,
     since: Optional[str] = None,
+    progress: "Optional[Callable[[int, int, str], None]]" = None,
 ) -> CanonicalRepositoryIR:
     """Build CanonicalRepositoryIR from Java files.
 
@@ -537,8 +538,13 @@ def build_canonical_ir(
         file_paths: Relative paths to Java files (from find_java_files).
         root:       Absolute repo root.
         since:      Git ref for symbol diff (e.g. "HEAD~1", "main").
+        progress:   Optional (done, total, stage) sink passed straight through to
+                    the builder — the only place that knows how much of the work
+                    is left (C3-56).
     """
-    ir = build_repo_ir(file_paths, root, since=since, emit_body_facts=True)
+    ir = build_repo_ir(
+        file_paths, root, since=since, emit_body_facts=True, progress=progress
+    )
     return ir_dict_to_canonical(ir, file_paths=file_paths)