sourcecode 4.1.0__py3-none-any.whl → 4.3.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.1.0"
+__version__ = "4.3.0"

sourcecode/architectural_baseline.py

@@ -312,6 +312,25 @@ def load_baseline(path: Path) -> dict:
     return data
 
 
+def latest_baseline_path(directory: Path) -> "Path | None":
+    """The most recently captured baseline in `directory`, or None if there is none.
+
+    Ordered exactly as `load_baselines_dir` orders its series (capture time, commit
+    as the tie-break), so "the last point in the trend" and "the base a diff uses by
+    default" can never disagree about which artifact that is.
+    """
+    dated: list[tuple[str, str, Path]] = []
+    for p in sorted(Path(directory).glob("*.json")):
+        try:
+            b = load_baseline(p)
+        except (OSError, ValueError, json.JSONDecodeError):
+            continue
+        dated.append((str(b.get("captured_at", "")), str(b.get("commit", "")), p))
+    if not dated:
+        return None
+    return max(dated, key=lambda t: (t[0], t[1]))[2]
+
+
 def load_baselines_dir(directory: Path) -> list[dict]:
     """Load every architectural baseline in `directory`, sorted by capture time."""
     out: list[dict] = []

sourcecode/baseline_autocapture.py

@@ -0,0 +1,375 @@
+"""baseline_autocapture.py — the half of the architectural history that is not a command.
+
+`ask baseline capture` has shipped since D5 and produces a history exactly as long as
+the number of times a human remembered to type it. Field audit #8 named that plainly:
+the artifact a competitor cannot backfill is *three years of a specific monolith's
+architectural baselines*, and **a history that depends on someone remembering to invoke
+it will not exist**. So capture has to be a by-product of a run that was going to happen
+anyway — the CI gate, which already builds the same IR the baseline is extracted from.
+
+This module is the single authority for the question *"should this run leave a baseline
+behind, and what happened when it tried?"*. It is deliberately small and conservative,
+because every branch here is a side effect inside somebody else's repository:
+
+* **It never starts a history nobody asked for.** A piggybacked run captures only where
+  a history already exists (`.ask/baselines/`) or where the operator opted in explicitly
+  (`--auto`, `ASK_BASELINE_AUTOCAPTURE=1`). The read-only complaint that `--dir` closed
+  is not going to be re-opened by a command that writes on its own initiative.
+* **One commit, one baseline.** The history is keyed by commit; re-capturing a commit
+  would silently relabel a point already in the series (and, after a tool upgrade, change
+  its metrics under the same key — the comparability contract exists precisely so that
+  cannot pass unnoticed). An already-captured commit is a skip, not an overwrite.
+* **A dirty tree is not a commit.** Writing `<commit>.json` from a modified working tree
+  attributes measurements to a state that commit never had. Skip and say so.
+* **It never fails the run it rode in on.** A read-only checkout, a full disk, a `.ask`
+  owned by another user: the host command's verdict is about the host command's question.
+  The capture reports what it could not do; it does not change an exit code.
+
+Every outcome is published (`action`, `reason`, `statement`) rather than being silent —
+I-8: a run declares the effect of what it did and did not do, and "no history was written"
+is exactly the kind of non-event that is invisible until someone needs the series.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterable, Optional
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+#: Where a history lives when nobody said otherwise — inside the repository, so it
+#: travels with the code (same default as `ask baseline capture`).
+HISTORY_DIRNAME: Path = Path(".ask") / "baselines"
+
+#: Explicit operator switch. "1"/"true"/"yes"/"on" enables piggybacked capture even
+#: without an existing history; "0"/"false"/"no"/"off" disables it even with one.
+ENV_FLAG: str = "ASK_BASELINE_AUTOCAPTURE"
+
+_TRUE = frozenset({"1", "true", "yes", "on"})
+_FALSE = frozenset({"0", "false", "no", "off"})
+
+# Actions.
+CAPTURED: str = "captured"
+SKIPPED: str = "skipped"
+
+# Reasons to capture.
+HISTORY_PRESENT: str = "history_present"
+EXPLICITLY_ENABLED: str = "explicitly_enabled"
+
+# Reasons to skip.
+NO_HISTORY: str = "no_history"
+DISABLED: str = "disabled"
+NO_COMMIT_IDENTITY: str = "no_commit_identity"
+WORKTREE_DIRTY: str = "worktree_dirty"
+WORKTREE_STATE_UNKNOWN: str = "worktree_state_unknown"
+COMMIT_ALREADY_CAPTURED: str = "commit_already_captured"
+WRITE_FAILED: str = "write_failed"
+NO_ANALYSIS: str = "no_analysis"
+
+_STATEMENTS: dict[str, str] = {
+    HISTORY_PRESENT: (
+        "This repository already keeps an architectural history, so this run added "
+        "the current commit to it."
+    ),
+    EXPLICITLY_ENABLED: (
+        "Automatic capture was requested, so this run added the current commit to the "
+        "architectural history."
+    ),
+    NO_HISTORY: (
+        "No architectural history exists here and none was requested, so nothing was "
+        "written. A series cannot be reconstructed later: start one with "
+        "`ask baseline capture <path>` (or `--auto` in the pipeline that already runs)."
+    ),
+    DISABLED: (
+        f"Automatic capture is switched off ({ENV_FLAG}), so this run added nothing to "
+        "the architectural history."
+    ),
+    NO_COMMIT_IDENTITY: (
+        "The path has no resolvable git commit, so a captured baseline could not be "
+        "joined to anything later. Nothing was written."
+    ),
+    WORKTREE_DIRTY: (
+        "The working tree carries uncommitted changes, so measurements taken now do not "
+        "describe the commit they would be filed under. Nothing was written."
+    ),
+    WORKTREE_STATE_UNKNOWN: (
+        "Whether the working tree is clean could not be determined, so the measurements "
+        "could not be attributed to the commit. Nothing was written."
+    ),
+    COMMIT_ALREADY_CAPTURED: (
+        "This commit is already in the architectural history; the stored baseline was "
+        "kept as captured (re-capturing would relabel a point in the series)."
+    ),
+    WRITE_FAILED: (
+        "The architectural history could not be written (see `error`). The verdict of "
+        "this run is unaffected — capture never changes what the command reports."
+    ),
+    NO_ANALYSIS: (
+        "This run did not analyse the repository, so there were no measurements to add "
+        "to the architectural history. Nothing was written."
+    ),
+}
+
+
+@dataclass(frozen=True)
+class CaptureDecision:
+    """What a run should do about the architectural history, and why."""
+
+    action: str  # CAPTURED (intent, before execution) | SKIPPED
+    reason: str
+    history_dir: Optional[str] = None
+    commit: Optional[str] = None
+    baseline_file: Optional[str] = None
+    history_size: Optional[int] = None
+    error: Optional[str] = None
+
+    @property
+    def statement(self) -> str:
+        return _STATEMENTS.get(self.reason, "")
+
+    def to_dict(self) -> dict:
+        out = {
+            "action": self.action,
+            "reason": self.reason,
+            "statement": self.statement,
+            "history_dir": self.history_dir,
+            "commit": self.commit,
+            "baseline_file": self.baseline_file,
+            "history_size": self.history_size,
+        }
+        if self.error is not None:
+            out["error"] = self.error
+        return out
+
+
+def env_opt_in(environ: "Optional[dict[str, str]]" = None) -> Optional[bool]:
+    """Tri-state read of the operator switch: True / False / None (never asked).
+
+    None is a distinct answer on purpose — the same rule the telemetry consent and
+    the fact registry follow. "Nobody configured this" is not "somebody said no".
+    """
+    raw = (environ if environ is not None else os.environ).get(ENV_FLAG)
+    if raw is None:
+        return None
+    value = raw.strip().lower()
+    if value in _TRUE:
+        return True
+    if value in _FALSE:
+        return False
+    return None
+
+
+def history_dir_for(root: Path, out_dir: "Optional[Path]" = None) -> Path:
+    """The directory a repository's baselines live in."""
+    return Path(out_dir).resolve() if out_dir is not None else Path(root) / HISTORY_DIRNAME
+
+
+def _porcelain_path(line: str) -> str:
+    """The path a `git status --porcelain` line refers to (the destination on renames)."""
+    body = line[3:] if len(line) > 3 else ""
+    if " -> " in body:  # rename/copy: `R  old -> new`
+        body = body.split(" -> ", 1)[1]
+    return body.strip().strip('"')
+
+
+def worktree_dirty(
+    root: Path, ignore: "Optional[Path | Iterable[Path]]" = None
+) -> Optional[bool]:
+    """True/False for a git worktree, None when the state could not be determined.
+
+    `git status --porcelain` honours `.gitignore`, so build output does not count as
+    a modification — but an untracked `.java` file does, because it is in the IR the
+    baseline measures.
+
+    `ignore` drops directories from the answer, and callers pass exactly one thing:
+    **this tool's own footprint** (`.ask/`, and the history directory when `--dir`
+    put it elsewhere). Two measured reasons, not a convenience:
+
+    * the first capture leaves an untracked file inside the repository, so without
+      this the history would report a dirty tree from its second run onward — a
+      series of exactly one;
+    * `.ask/contracts.yml` is what a gate run is *for*, and in a repository that has
+      not committed it yet, counting it as a modification of the code would mean the
+      history never starts.
+
+    Nothing else is excused, because everything else is what the baseline measures.
+    """
+    try:
+        out = subprocess.run(
+            # `-uall` because git collapses an untracked directory to one entry
+            # (`?? .ask/`), and the whole point here is to tell OUR untracked file
+            # apart from the source file next to it.
+            ["git", "-C", str(root), "status", "--porcelain", "-uall"],
+            capture_output=True, text=True, timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0:
+        return None
+    lines = [ln for ln in out.stdout.splitlines() if ln.strip()]
+    if ignore is None:
+        return bool(lines)
+    candidates = [ignore] if isinstance(ignore, (str, Path)) else list(ignore)
+    prefixes: list[str] = []
+    for candidate in candidates:
+        try:
+            rel = Path(candidate).resolve().relative_to(Path(root).resolve()).as_posix()
+        except ValueError:  # outside the repo (`--dir`): nothing of it to drop
+            continue
+        prefixes.append(rel.rstrip("/") + "/")
+    remaining = [
+        ln for ln in lines
+        if not any(
+            (_porcelain_path(ln).rstrip("/") + "/").startswith(p) for p in prefixes
+        )
+    ]
+    return bool(remaining)
+
+
+def history_size(history_dir: Path) -> Optional[int]:
+    """How many baselines the history holds, or None when there is no history."""
+    try:
+        if not history_dir.is_dir():
+            return None
+        return sum(1 for _ in history_dir.glob("*.json"))
+    except OSError:
+        return None
+
+
+def decide(
+    *,
+    history_dir: Path,
+    history_exists: bool,
+    opt_in: Optional[bool],
+    commit: Optional[str],
+    dirty: Optional[bool],
+    already_captured: Optional[Path],
+    size: Optional[int] = None,
+) -> CaptureDecision:
+    """Pure policy: given the facts, capture or skip — with the reason named.
+
+    Split from execution so the policy is testable without a repository, and so the
+    order of the checks is visible in one place: consent first, then identity, then
+    attribution, then idempotency.
+    """
+    common = {
+        "history_dir": str(history_dir),
+        "commit": commit,
+        "history_size": size,
+    }
+    if opt_in is False:
+        return CaptureDecision(SKIPPED, DISABLED, **common)
+    if opt_in is not True and not history_exists:
+        return CaptureDecision(SKIPPED, NO_HISTORY, **common)
+    if not commit:
+        return CaptureDecision(SKIPPED, NO_COMMIT_IDENTITY, **common)
+    if dirty is None:
+        return CaptureDecision(SKIPPED, WORKTREE_STATE_UNKNOWN, **common)
+    if dirty:
+        return CaptureDecision(SKIPPED, WORKTREE_DIRTY, **common)
+    if already_captured is not None:
+        return CaptureDecision(
+            SKIPPED, COMMIT_ALREADY_CAPTURED,
+            baseline_file=str(already_captured), **common
+        )
+    return CaptureDecision(
+        CAPTURED, HISTORY_PRESENT if history_exists else EXPLICITLY_ENABLED, **common
+    )
+
+
+def _existing_baseline(history_dir: Path, commit: str) -> Optional[Path]:
+    candidate = history_dir / f"{commit}.json"
+    try:
+        return candidate if candidate.is_file() else None
+    except OSError:
+        return None
+
+
+def plan(
+    root: Path,
+    *,
+    out_dir: "Optional[Path]" = None,
+    explicit: bool = False,
+    environ: "Optional[dict[str, str]]" = None,
+) -> CaptureDecision:
+    """Gather the repository facts and apply `decide` to them."""
+    root = Path(root)
+    from sourcecode.architectural_baseline import git_commit
+
+    hist = history_dir_for(root, out_dir)
+    exists = hist.is_dir()
+    opt_in = True if explicit else env_opt_in(environ)
+
+    # Consent is the cheapest question and the most common answer, so it is asked
+    # first: a command that piggybacks on every run must cost nothing at all in a
+    # repository that keeps no history. `git status -uall` on a monolith is not
+    # nothing.
+    if opt_in is False or (opt_in is not True and not exists):
+        return decide(
+            history_dir=hist, history_exists=exists, opt_in=opt_in,
+            commit=None, dirty=None, already_captured=None, size=history_size(hist),
+        )
+
+    commit = git_commit(root)
+    # The tool's own footprint, and only that.
+    own = (hist, Path(root) / HISTORY_DIRNAME.parts[0])
+    dirty = worktree_dirty(root, ignore=own) if commit else None
+    already = _existing_baseline(hist, commit) if commit else None
+    return decide(
+        history_dir=hist,
+        history_exists=exists,
+        opt_in=opt_in,
+        commit=commit,
+        dirty=dirty,
+        already_captured=already,
+        size=history_size(hist),
+    )
+
+
+def run(
+    root: Path,
+    cir: "Optional[CanonicalRepositoryIR]" = None,
+    *,
+    out_dir: "Optional[Path]" = None,
+    explicit: bool = False,
+    ref: "Optional[str]" = None,
+    environ: "Optional[dict[str, str]]" = None,
+    decision: "Optional[CaptureDecision]" = None,
+) -> CaptureDecision:
+    """Decide, and when the decision is to capture, write the baseline.
+
+    `cir` is the IR the host command already built — capture adds a metric extraction
+    and a file write, never a second analysis. Passing None with a capture decision is
+    a caller bug, reported as a skip rather than raised: this function's contract is
+    that it cannot fail the run that called it.
+    """
+    plan_ = decision if decision is not None else plan(
+        root, out_dir=out_dir, explicit=explicit, environ=environ
+    )
+    if plan_.action != CAPTURED:
+        return plan_
+
+    from sourcecode.architectural_baseline import build_baseline, write_baseline
+
+    hist = history_dir_for(Path(root), out_dir)
+    try:
+        if cir is None:
+            raise ValueError("no IR was available to capture from")
+        baseline = build_baseline(cir, ref=ref, commit=plan_.commit)
+        written = write_baseline(baseline, hist)
+    except Exception as exc:  # a side effect never decides the host command's verdict
+        return CaptureDecision(
+            SKIPPED, WRITE_FAILED,
+            history_dir=str(hist), commit=plan_.commit,
+            history_size=plan_.history_size, error=f"{type(exc).__name__}: {exc}",
+        )
+    return CaptureDecision(
+        CAPTURED, plan_.reason,
+        history_dir=str(hist), commit=plan_.commit,
+        baseline_file=str(written),
+        history_size=(plan_.history_size or 0) + 1,
+    )

sourcecode/cache_model.py

@@ -138,6 +138,25 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "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"),
+    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 "
+                 "repository side, so what it buys is what it buys `risk`.",
+                 "not measured on the battery yet — bounded by the `risk` composition, plus "
+                 "reading one JSON file"),
+    CommandCache("migrate-recipe", ("parse",), "shared", False,
+                 "Runs the same scan as `migrate-check` and projects its findings into an "
+                 "OpenRewrite recipe, so it buys exactly what a warm buys `migrate-check`: "
+                 "the parse, not the rule pass.",
+                 "not measured on the battery yet — bounded by `migrate-check` on the same "
+                 "repository (openmrs-core ~2 s)"),
+    CommandCache("data-exposure", ("cir", "parse"), "shared", False,
+                 "Walks the same call reach as `impact-chain` once per declared type and "
+                 "reads the endpoint security surface, both over the shared CIR a warm "
+                 "builds. Cost scales with the number of declared types, not with the "
+                 "size of the label.",
+                 "not measured on the battery yet — one `impact-chain` traversal per "
+                 "declared seed type over a CIR the warm already paid for"),
     CommandCache("endpoints", ("ris", "parse"), "shared", False,
                  "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 "

sourcecode/caller_reach.py

@@ -127,13 +127,21 @@ def bfs_callers(
     max_depth: int,
     impl_graph: object | None = None,
     method_scoped: bool = False,
-) -> tuple[list[str], list[str], bool, int]:
+) -> tuple[list[str], list[str], bool, int, int]:
     """Walk the reverse graph from *seed_fqns*.
 
-    Returns ``(direct, indirect, was_truncated, self_excluded)``. ``direct`` is
-    depth 1 — the callers of the seeds themselves; ``indirect`` is depth 2 and
-    beyond, up to *max_depth*. ``was_truncated`` says the hub-class guard capped
-    the walk, which makes the result a floor.
+    Returns ``(direct, indirect, was_truncated, self_excluded, guard_population)``.
+    ``direct`` is depth 1 — the callers of the seeds themselves; ``indirect`` is
+    depth 2 and beyond, up to *max_depth*. ``was_truncated`` says the hub-class
+    guard capped the walk, which makes the result a floor.
+
+    ``guard_population`` is the number the guard actually read: unique caller
+    **reference sites**, method-level keys included, before anything is
+    normalised to a class. It is returned rather than left implicit because the
+    figure the payload publishes is the class count, and a message that names
+    the cap without naming its own population contradicts the payload beside it —
+    measured on openmrs-core, *"symbol has > 500 direct callers"* printed next to
+    `direct_caller_count: 215` (C2-21).
 
     A class's own members are members, not external callers, so they are dropped
     and counted (BUG #2 — leaving them in inflated a blast radius ~12×). For a
@@ -170,7 +178,8 @@ def bfs_callers(
             if etype not in SKIP_EDGE_TYPES:
                 unique_direct.update(c for c in fqn_list if not _is_self_reference(c))
 
-    effective_depth = 1 if len(unique_direct) > CALLER_CAP else max_depth
+    guard_population = len(unique_direct)
+    effective_depth = 1 if guard_population > CALLER_CAP else max_depth
     if effective_depth < max_depth:
         was_truncated = True
 
@@ -202,4 +211,4 @@ def bfs_callers(
                 else:
                     _add_caller(caller, depth)
 
-    return direct, indirect, was_truncated, self_excluded
+    return direct, indirect, was_truncated, self_excluded, guard_population

sourcecode/canonical_ir.py

@@ -115,6 +115,30 @@ class CanonicalSecurity:
 # CanonicalEndpoint
 # ---------------------------------------------------------------------------
 
+def request_identity(method: str, path: str) -> str:
+    """The identity of the **request**, not of the handler that serves it.
+
+    An endpoint `id` identifies a handler: it carries the controller FQN and the
+    handler symbol, so moving a mapping to another class produces a different
+    `id` for the same URL. That is the right identity inside one tree and the
+    wrong one across two — a comparison keyed on it reports every refactored
+    handler as one endpoint removed and another added, and the reader asking
+    "did this change what a caller can reach" has to subtract the noise by hand.
+
+    Two states of one repository — `contract-diff` between refs, `posture
+    --diff-ref` — compare what a client can call, which is METHOD + path. One
+    authority for it, because two spellings of one identity is how two commands
+    come to disagree about the same endpoint (ADR-0008 R11).
+
+    Note what this deliberately does *not* do: it does not normalise path
+    variable names or inline regexes. `/{id:.*}` and `/{id:[^0-9].*}` are
+    different URLs to a client, and equating them would hide a real change in
+    the surface — measured on a fleet repository where exactly that edit moved
+    93 requests.
+    """
+    return f"{str(method).upper()} {path}"
+
+
 @dataclass
 class CanonicalEndpoint:
     """Canonical endpoint entity — single source of truth for REST endpoint data.
@@ -159,6 +183,11 @@ class CanonicalEndpoint:
         """Deterministic endpoint ID — stable across formatting/body changes."""
         return f"{method}:{path}:{controller_class}:{handler_symbol}"
 
+    @property
+    def request_key(self) -> str:
+        """This endpoint's request identity — see `request_identity`."""
+        return request_identity(self.method, self.path)
+
 
 # ---------------------------------------------------------------------------
 # CanonicalRepositoryIR