sourcecode 2.5.19__py3-none-any.whl → 2.6.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__ = "2.5.19"
+__version__ = "2.6.0"

sourcecode/architectural_baseline.py

@@ -0,0 +1,408 @@
+"""architectural_baseline.py — D5 Architectural knowledge persistence.
+
+Engineering Decision Support, Part B / D5. Turns ASK from a stateless per-run tool
+into one that REMEMBERS a repository's architecture over time. Generalizes the perf
+harness's frozen-schema + same-baseline-diff discipline (`perf-baseline-v1`,
+`docs/perf/baselines/<ver>/`) from timing to architectural metrics: a committed,
+versioned `architectural-baseline-v1` artifact per ref that persists the measured
+structural fingerprint (totals + fan-in hotspots + the full endpoint surface and
+fan-in map needed to diff faithfully).
+
+Three capabilities, one schema:
+  * capture — freeze the current CIR's measured metrics into a baseline artifact.
+  * diff    — diff the live working tree against a stored baseline (this is D1's
+              `diff_metrics` with the base snapshot loaded from disk instead of a
+              second checkout — "D1 auto-diffs against the stored baseline").
+  * trend   — a multi-ref series over N stored baselines (totals over time + per
+              hotspot fan-in trajectory).
+
+Moat line: every field is MEASURED and derived from the CIR alone (via D1's
+`extract_metrics`). Persistence adds no inference, no verdict, no ROI — it stores and
+replays measured facts. Trend reports movement; it never labels a trajectory
+"improving"/"degrading" (that reading is the engineer's).
+
+Determinism & comparability (carried from the perf harness): the metric content of a
+baseline is a pure function of the CIR — same repo state → identical totals/hotspots/
+surface (only `captured_at`/`commit`/env vary). An env fingerprint is recorded so a
+consumer can refuse to compare baselines captured on incomparable hosts, exactly as
+the perf baselines do.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sourcecode import __version__ as TOOL_VERSION
+from sourcecode.architectural_delta import ArchMetrics, diff_metrics, extract_metrics
+from sourcecode.perf import collect_env
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+# Frozen schema tags — versioned like perf-baseline-v1 / architectural-delta-v1.
+ARCH_BASELINE_SCHEMA: str = "architectural-baseline-v1"
+ARCH_TREND_SCHEMA: str = "architectural-trend-v1"
+# Emitted by `diff_baseline` when the two snapshots are not comparable and the
+# caller did NOT opt into an override — a refusal, not a delta.
+ARCH_NOT_COMPARABLE_SCHEMA: str = "architectural-not-comparable-v1"
+
+# Comparability verdicts.
+COMPARABLE: str = "COMPARABLE"
+NOT_COMPARABLE: str = "NOT_COMPARABLE"
+# `diff_baseline(..., allow_incomparable=True)` still emits a delta but stamps this
+# so the output can never be mistaken for a clean comparison.
+OVERRIDDEN: str = "OVERRIDDEN"
+
+# The axes that make two architectural baselines comparable. Architectural metrics
+# are a PURE FUNCTION OF SOURCE — they do not depend on CPU, cores, or host — so the
+# comparability contract is SEMANTIC, not hardware. Gating on hostname/cpu (as the
+# perf harness must, because timing IS hardware-sensitive) would be theater here and
+# would falsely refuse a valid cross-host architectural diff. What genuinely makes a
+# delta misleading is a change in the measurement itself: the baseline schema, the
+# analysis (tool) version that extracted the metrics, or the underlying IR schema.
+# A difference in any of these means a symbol/endpoint/fan-in delta could reflect the
+# extractor changing rather than the code changing — so ASK refuses.
+_COMPARABILITY_AXES: tuple[tuple[str, str], ...] = (
+    ("schema", "baseline schema"),
+    ("tool_version", "analysis (tool) version"),
+    ("ir_schema_version", "IR schema"),
+)
+
+# How many top fan-in symbols to record as named hotspots. The FULL fan-in map is
+# stored separately for faithful diffs; hotspots are the human-facing projection.
+_HOTSPOT_N: int = 20
+
+
+def _utc_now() -> str:
+    # Microsecond precision (DR-2): whole-second timestamps collided whenever two
+    # baselines were captured in the same second (common in CI / rapid capture), and
+    # the trend sort then tie-broke on the commit STRING — which carries no temporal
+    # order — scrambling the series. Sub-second resolution makes real captures
+    # distinct; lexicographic ISO order stays chronological.
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def git_commit(repo: Path) -> str | None:
+    """Best-effort short commit of `repo`'s HEAD, or None when not a git repo."""
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(repo), "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    commit = out.stdout.strip()
+    return commit or None
+
+
+def _hotspots(fan_in: dict[str, int], top_n: int) -> list[dict]:
+    """Top-N symbols by fan-in (desc), then FQN asc. Zero-fan-in symbols excluded."""
+    ranked = sorted(
+        ((s, c) for s, c in fan_in.items() if c > 0),
+        key=lambda kv: (-kv[1], kv[0]),
+    )
+    return [{"symbol": s, "fan_in": c} for s, c in ranked[:top_n]]
+
+
+def build_baseline(
+    cir: "CanonicalRepositoryIR",
+    *,
+    ref: str | None = None,
+    commit: str | None = None,
+    hotspot_n: int = _HOTSPOT_N,
+    captured_at: str | None = None,
+    env: dict | None = None,
+    tool_version: str | None = None,
+) -> dict:
+    """Freeze a CIR's measured architectural metrics into a baseline artifact.
+
+    Stores the full endpoint surface and fan-in map (not just hotspots) so a later
+    `diff_baseline` reproduces exactly what a two-checkout D1 delta would report.
+    Records the analysis provenance (`tool_version`, `ir_schema_version`) that the
+    comparability contract gates on — a delta is only trustworthy between baselines
+    that share them."""
+    m = extract_metrics(cir)
+    endpoints = sorted([meth, path] for (meth, path) in m.endpoints)
+    fan_in = dict(sorted(m.fan_in.items()))
+    cycles = sorted((sorted(c) for c in m.cycles), key=lambda mm: (len(mm), mm))
+    return {
+        "schema": ARCH_BASELINE_SCHEMA,
+        "tool_version": tool_version if tool_version is not None else TOOL_VERSION,
+        "ir_schema_version": str(getattr(cir, "schema_version", "")),
+        "ref": ref,
+        "commit": commit,
+        "captured_at": captured_at or _utc_now(),
+        "cir_hash": m.cir_hash,
+        "totals": {
+            "files": m.file_count,
+            "symbols": m.symbol_count,
+            "endpoints": m.endpoint_count,
+            "dependency_edges": m.dependency_edge_count,
+            "import_cycles": len(m.cycles),
+        },
+        "hotspots": _hotspots(m.fan_in, hotspot_n),
+        "endpoint_surface": endpoints,
+        "fan_in": fan_in,
+        "import_cycles": cycles,
+        "env": env if env is not None else collect_env(),
+        "provenance": (
+            "architectural_baseline (D5): a measured structural fingerprint of one "
+            "CIR, persisted per ref. Metric content is a pure function of the repo "
+            "state. No verdict, no ROI — stores and replays measured facts."
+        ),
+    }
+
+
+def _analysis_meta(source: dict) -> dict:
+    """Extract the comparability axes from a baseline (or a synthesized head meta)."""
+    return {axis: source.get(axis) for axis, _ in _COMPARABILITY_AXES}
+
+
+def _head_meta(head_cir: "CanonicalRepositoryIR") -> dict:
+    """The comparability meta for a live head CIR: current tool + its IR schema."""
+    return {
+        "schema": ARCH_BASELINE_SCHEMA,
+        "tool_version": TOOL_VERSION,
+        "ir_schema_version": str(getattr(head_cir, "schema_version", "")),
+    }
+
+
+def comparability(base: dict, head: dict) -> dict:
+    """Verdict on whether two snapshots' metrics are comparable.
+
+    Gates on the SEMANTIC axes only (schema / tool version / IR schema) — see
+    `_COMPARABILITY_AXES` for why hardware is deliberately excluded. Any mismatch
+    yields NOT_COMPARABLE with an itemized reason per differing axis."""
+    reasons: list[dict] = []
+    for axis, label in _COMPARABILITY_AXES:
+        bv, hv = base.get(axis), head.get(axis)
+        if bv != hv:
+            reasons.append({
+                "axis": axis,
+                "base": bv,
+                "head": hv,
+                "detail": f"{label} differs: {bv!r} (base) vs {hv!r} (head)",
+            })
+    return {
+        "status": COMPARABLE if not reasons else NOT_COMPARABLE,
+        "reasons": reasons,
+        "base": _analysis_meta(base),
+        "head": _analysis_meta(head),
+    }
+
+
+def baseline_to_metrics(baseline: dict) -> ArchMetrics:
+    """Reconstruct an `ArchMetrics` from a stored baseline for a faithful D1 diff."""
+    totals = baseline.get("totals", {})
+    endpoints = frozenset(
+        (str(pair[0]).upper(), str(pair[1]))
+        for pair in baseline.get("endpoint_surface", [])
+        if isinstance(pair, (list, tuple)) and len(pair) == 2
+    )
+    return ArchMetrics(
+        cir_hash=str(baseline.get("cir_hash", "")),
+        file_count=int(totals.get("files", 0)),
+        symbol_count=int(totals.get("symbols", 0)),
+        endpoint_count=int(totals.get("endpoints", 0)),
+        dependency_edge_count=int(totals.get("dependency_edges", 0)),
+        endpoints=endpoints,
+        fan_in={str(k): int(v) for k, v in (baseline.get("fan_in") or {}).items()},
+        cycles=frozenset(
+            frozenset(str(m) for m in members)
+            for members in baseline.get("import_cycles", [])
+            if isinstance(members, (list, tuple))
+        ),
+    )
+
+
+def _base_descriptor(baseline: dict) -> dict:
+    """Self-describing block naming the stored baseline the head was diffed against."""
+    return {
+        "ref": baseline.get("ref"),
+        "commit": baseline.get("commit"),
+        "captured_at": baseline.get("captured_at"),
+        "tool_version": baseline.get("tool_version"),
+        "ir_schema_version": baseline.get("ir_schema_version"),
+    }
+
+
+def diff_baseline(
+    baseline: dict,
+    head_cir: "CanonicalRepositoryIR",
+    *,
+    allow_incomparable: bool = False,
+) -> dict:
+    """Diff a live CIR against a stored baseline — D1's delta, base loaded from disk.
+
+    Comparability first: if the base and the live head disagree on the semantic axes
+    (baseline schema / analysis version / IR schema), a delta would conflate the
+    measurement change with the code change. ASK REFUSES by default, returning an
+    `architectural-not-comparable-v1` payload (status NOT_COMPARABLE) instead of a
+    misleading delta — an honest refusal is preferred over a plausible-looking lie.
+
+    Set `allow_incomparable=True` to override: the delta is still computed but stamped
+    `status=OVERRIDDEN` with the reasons, so it can never be read as a clean diff.
+
+    When comparable, the payload is the `architectural-delta-v1` schema (identical to
+    a two-checkout `ask delta`), stamped `status=COMPARABLE`, plus a `base` block."""
+    verdict = comparability(baseline, _head_meta(head_cir))
+
+    if verdict["status"] == NOT_COMPARABLE and not allow_incomparable:
+        return {
+            "schema": ARCH_NOT_COMPARABLE_SCHEMA,
+            "status": NOT_COMPARABLE,
+            "comparability": verdict,
+            "base": _base_descriptor(baseline),
+            "message": (
+                "Refusing to diff: base and head are not comparable "
+                f"({'; '.join(r['detail'] for r in verdict['reasons'])}). "
+                "A delta would conflate the analysis change with the code change. "
+                "Re-capture the base with the current tool (ask baseline capture) for "
+                "a clean diff, or pass --allow-incomparable to override."
+            ),
+            "provenance": (
+                "architectural_baseline (D5): comparability refusal. Architectural "
+                "metrics are a pure function of source; a delta is only trustworthy "
+                "when the baseline schema, analysis version, and IR schema all match."
+            ),
+        }
+
+    base = baseline_to_metrics(baseline)
+    head = extract_metrics(head_cir)
+    delta = diff_metrics(base, head)
+    delta["status"] = (
+        OVERRIDDEN if verdict["status"] == NOT_COMPARABLE else COMPARABLE
+    )
+    delta["comparability"] = verdict
+    delta["base"] = _base_descriptor(baseline)
+    return delta
+
+
+# ── Persistence I/O ───────────────────────────────────────────────────────────
+
+
+def _baseline_filename(baseline: dict) -> str:
+    """Stable filename for a baseline: commit if known, else the capture timestamp."""
+    stem = baseline.get("commit") or baseline.get("captured_at", "baseline")
+    safe = "".join(c if (c.isalnum() or c in "-_.") else "-" for c in str(stem))
+    return f"{safe}.json"
+
+
+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)
+    path = out_dir / _baseline_filename(baseline)
+    path.write_text(
+        json.dumps(baseline, sort_keys=True, indent=2) + "\n", encoding="utf-8"
+    )
+    return path
+
+
+def load_baseline(path: Path) -> dict:
+    """Load and validate one baseline artifact."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or data.get("schema") != ARCH_BASELINE_SCHEMA:
+        raise ValueError(
+            f"{path}: not an {ARCH_BASELINE_SCHEMA} artifact "
+            f"(schema={data.get('schema') if isinstance(data, dict) else type(data).__name__})."
+        )
+    return data
+
+
+def load_baselines_dir(directory: Path) -> list[dict]:
+    """Load every architectural baseline in `directory`, sorted by capture time."""
+    out: list[dict] = []
+    for p in sorted(Path(directory).glob("*.json")):
+        try:
+            out.append(load_baseline(p))
+        except (ValueError, json.JSONDecodeError):
+            continue  # skip foreign JSON; a baseline dir may hold unrelated files
+    # Order by capture time (DR-2). captured_at now carries microsecond resolution,
+    # so real captures are distinct and lexicographic ISO order == chronological.
+    # commit is only a deterministic fallback for the degenerate exact-timestamp tie
+    # (same instant → order is genuinely ambiguous); it never reorders distinct times.
+    out.sort(key=lambda b: (str(b.get("captured_at", "")), str(b.get("commit", ""))))
+    return out
+
+
+# ── Trend (multi-ref series) ──────────────────────────────────────────────────
+
+
+def build_trend(baselines: list[dict]) -> dict:
+    """A multi-ref series over N baselines: totals over time + hotspot fan-in tracks.
+
+    Deterministic projection: points ordered by capture time; hotspot tracks cover
+    the union of every baseline's named hotspots, each track a per-point fan-in
+    series (0 where the symbol is absent). Reports movement only — no trajectory
+    label, no verdict."""
+    points = [
+        {
+            "ref": b.get("ref"),
+            "commit": b.get("commit"),
+            "captured_at": b.get("captured_at"),
+            "tool_version": b.get("tool_version"),
+            "ir_schema_version": b.get("ir_schema_version"),
+            "totals": b.get("totals", {}),
+        }
+        for b in baselines
+    ]
+
+    # Comparability across the SERIES. A trend is not refused — cross-version history
+    # is still worth seeing — but every point-to-point transition that crosses an
+    # analysis-version boundary is flagged, because a metric jump there may be the
+    # extractor changing, not the code. The reader must attribute those with care.
+    boundaries: list[dict] = []
+    for i in range(1, len(baselines)):
+        v = comparability(baselines[i - 1], baselines[i])
+        if v["status"] == NOT_COMPARABLE:
+            boundaries.append({
+                "from_index": i - 1,
+                "to_index": i,
+                "reasons": v["reasons"],
+            })
+    distinct_versions = sorted(
+        {str(b.get("tool_version")) for b in baselines}
+    )
+    series_comparability = {
+        "status": COMPARABLE if not boundaries else NOT_COMPARABLE,
+        "distinct_tool_versions": distinct_versions,
+        "boundaries": boundaries,
+    }
+
+    tracked: set[str] = set()
+    for b in baselines:
+        for h in b.get("hotspots", []):
+            if isinstance(h, dict) and h.get("symbol"):
+                tracked.add(str(h["symbol"]))
+
+    hotspot_trends: list[dict] = []
+    for sym in sorted(tracked):
+        series = [int((b.get("fan_in") or {}).get(sym, 0)) for b in baselines]
+        first, last = series[0], series[-1]
+        hotspot_trends.append({
+            "symbol": sym,
+            "fan_in_series": series,
+            "first": first,
+            "last": last,
+            "delta": last - first,
+        })
+    # Largest absolute movement first, then symbol name — deterministic.
+    hotspot_trends.sort(key=lambda t: (-abs(t["delta"]), t["symbol"]))
+
+    return {
+        "schema": ARCH_TREND_SCHEMA,
+        "baseline_count": len(baselines),
+        "comparability": series_comparability,
+        "points": points,
+        "hotspot_trends": hotspot_trends,
+        "provenance": (
+            "architectural_trend (D5): a measured series over persisted baselines. "
+            "Reports totals and fan-in movement over time; assigns no "
+            "improving/degrading label — the reading is the engineer's. Transitions "
+            "that cross an analysis-version boundary are flagged in comparability: a "
+            "metric jump there may reflect the extractor changing, not the code."
+        ),
+    }