whycode-cli 0.4.2__py3-none-any.whl → 0.5.2__py3-none-any.whl

whycode/__init__.py

@@ -1,3 +1,3 @@
 """WhyCode — tells you what to be afraid of before touching a file."""
 
-__version__ = "0.4.2"
+__version__ = "0.5.2"

whycode/cli.py

@@ -20,10 +20,11 @@ Commands
 
 from __future__ import annotations
 
+import contextlib
 import functools
 import json
 import sys
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
 from pathlib import Path
 from typing import Any, TypeVar
 
@@ -126,6 +127,42 @@ def _require_tracked(path_arg: str) -> tuple[Path, str]:
     return repo_root, rel
 
 
+@contextlib.contextmanager
+def _memoised_is_ignored(repo_root: Path) -> Iterator[None]:
+    """Memoise ``ign.is_ignored`` for the duration of the ``with`` block.
+
+    The diff command's evaluation re-applies the same ``is_ignored`` test
+    against thousands of co-change candidates per file. Each call resolves
+    fnmatch over ~83 patterns; uncached, that is ~100 CPU-seconds across
+    a 1,927-file diff on django.
+
+    A path's verdict is fully determined by the path string and the
+    repo's effective ignore-pattern tuple, so we cache by ``(path,
+    patterns)`` for the duration of the diff and restore the original
+    function on exit. The cache is process-local; the rest of the CLI
+    (``why``, ``scan``, …) sees the un-memoised function. ``ign`` itself
+    is unchanged.
+    """
+    patterns = ign.effective_patterns(repo_root)
+    cache: dict[str, bool] = {}
+    original = ign.is_ignored
+
+    def memoised(path: str, patterns_arg: object = patterns) -> bool:
+        if patterns_arg is patterns:
+            cached = cache.get(path)
+            if cached is None:
+                cached = original(path, patterns)
+                cache[path] = cached
+            return cached
+        return original(path, patterns_arg)  # type: ignore[arg-type]
+
+    ign.is_ignored = memoised  # type: ignore[assignment]
+    try:
+        yield
+    finally:
+        ign.is_ignored = original
+
+
 _F = TypeVar("_F", bound=Callable[..., Any])
 
 
@@ -240,6 +277,15 @@ def why(
         "--no-cache",
         help="Bypass the local SQLite cache at .whycode/cache.db.",
     ),
+    explain: bool = typer.Option(
+        False,
+        "--explain",
+        help=(
+            "Below each signal, print the precise rule that fired: the literal "
+            "matched tokens, threshold values, and the source location of the "
+            "ladder branch. L1+L2 only — L3 (--llm) decisions are not annotated."
+        ),
+    ),
 ) -> None:
     """Print the Risk Card for ``path``."""
     repo_root, rel = _require_tracked(path)
@@ -328,12 +374,12 @@ def why(
                 card = card.with_decisions(tuple(decisions))
 
         if json_out:
-            console.print_json(json.dumps(card.to_dict()))
+            console.print_json(json.dumps(card.to_dict(explain=explain)))
             return
         if brief:
             _print_brief(card)
             return
-        console.print(rc.render_text(card))
+        console.print(rc.render_text(card, explain=explain))
     finally:
         if cache is not None:
             cache.close()
@@ -428,16 +474,57 @@ def diff(
 
     cache = _open_cache(repo_root, no_cache)
     try:
-        cards: list[rc.RiskCard] = []
-        for f in files:
-            try:
-                cards.append(rc.build(repo_root, f, cache=cache))
-            except gf.GitError:
-                continue
-        # Stable tie-break: lex smallest path on identical scores so cache
-        # and --no-cache truncate the same files at --top N.
-        cards.sort(key=lambda c: (-c.score.value, c.path))
-        cards = cards[:top]
+        # One git log walk feeds every changed file's scoring. Without this
+        # batched load, diff against an old base on a large repo runs N
+        # `git log --follow` calls (one per changed file): on django at 1,927
+        # changed files the legacy path measured 6+ minutes, with the
+        # 12+ minute variant timing out outright. ``load_diff_facts`` parses
+        # one un-pathed walk into a path -> [Commit] map; per-file scoring
+        # then does dict lookups instead of re-shelling-out.
+        try:
+            diff_facts = gf.load_diff_facts(repo_root, cache=cache)
+        except gf.GitError as exc:
+            err.print(f"[red]error:[/red] {exc}")
+            raise typer.Exit(2) from exc
+        # Pre-compute the ignore-pattern set ONCE and a verdict-per-path
+        # memo. ``signals.detect_coupling`` (re-introduced in 0.4.1 as F10)
+        # filters every coupling candidate through ``ign.is_ignored`` —
+        # without memoisation that's 83 patterns x 700 candidates x 1,927
+        # files = ~100 CPU-seconds across the diff. The memo cache turns
+        # each path's verdict into a dict lookup after the first hit.
+        with _memoised_is_ignored(repo_root):
+            # First pass: every changed file is scored without the
+            # ghost-keeper detector, which would otherwise fire ``git
+            # blame`` per file. With 1,927 changed files on django this
+            # single deferral saves ~5 minutes. We then sort and
+            # re-evaluate only the top-N with full signals — at most
+            # ``top`` blame calls instead of ``len(files)``.
+            prelim: list[rc.RiskCard] = []
+            for f in files:
+                try:
+                    prelim.append(
+                        rc.build_from_diff_facts(diff_facts, f, skip_ghost_keeper=True)
+                    )
+                except gf.GitError:
+                    continue
+            # Stable tie-break (from 0.4.2): lex smallest path on identical
+            # scores so cache and --no-cache truncate the same files at --top N.
+            prelim.sort(key=lambda c: (-c.score.value, c.path))
+            # Second pass: re-score the top-N with the full detector ladder
+            # so the rendered table includes ghost-keeper findings where
+            # they apply. Files outside the top-N keep their first-pass
+            # score; they were not going to appear in the user's view
+            # anyway.
+            refined_top: list[rc.RiskCard] = []
+            for prelim_card in prelim[:top]:
+                try:
+                    refined_top.append(
+                        rc.build_from_diff_facts(diff_facts, prelim_card.path)
+                    )
+                except gf.GitError:
+                    refined_top.append(prelim_card)
+            cards = refined_top
+            cards.sort(key=lambda c: (-c.score.value, c.path))
     finally:
         if cache is not None:
             cache.close()

whycode/git_facts.py

@@ -735,6 +735,242 @@ def _populate_diffstat_cache(
         cache.upsert_commit_files(rows)
 
 
+# ---- batch loading for whycode diff ---------------------------------------
+
+
+@dataclass(frozen=True)
+class DiffFacts:
+    """A whole-repo snapshot built once for a single ``whycode diff`` evaluation.
+
+    The diff command scores N changed files; previously each file fired its
+    own ``git log --follow`` plus a co-change diffstat pass, so wall-clock
+    cost scaled with N. ``DiffFacts`` replaces N path-restricted log walks
+    with a single un-pathed walk: one ``git log --no-merges --numstat`` over
+    the repo, parsed once into ``commits_by_path`` (every commit that named
+    each path) and ``co_change_index`` (each commit's full file-set, used
+    for in-memory coupling counts). Per-file scoring then reads from this
+    map rather than re-shelling-out.
+
+    The map deliberately does NOT follow renames: the diff command only
+    scores files present in HEAD's working tree, so the tradeoff is "lose
+    rename-resolved history pre-rename" against "scoring 1,927 files in
+    seconds rather than minutes". Coupling against pre-rename names still
+    surfaces under those names in the map; the surface diff in practice is
+    a stable-tie-break difference, not a structural one.
+    """
+
+    repo_root: Path
+    commits_by_path: dict[str, list[Commit]]
+    """``path -> [Commit]``, newest-first, capped per path during load.
+
+    A missing key — i.e. ``commits_by_path.get(path)`` returns ``None`` —
+    means the loader walk did not see this path. ``gather_for_diff`` treats
+    that the same as an empty list: a path that the un-pathed walk did not
+    touch has no history to score from.
+    """
+
+    co_change_index: dict[str, tuple[str, ...]]
+    """``commit_sha -> tuple of paths touched by that commit``.
+
+    Snapshot of the same numstat parse used to build ``commits_by_path``.
+    Per-file ``co_changes`` reads this for in-memory coupling counts so
+    the diff pipeline never re-issues ``git log --no-walk`` per file.
+    """
+
+    cache: CacheStore | None = None
+    """Optional cache, threaded through so signal detectors (specifically
+    ``detect_ghost_keeper``) reuse it for ``git blame`` line ownership."""
+
+
+_NUMSTAT_LINE_RE = re.compile(r"^(\d+|-)\t(\d+|-)\t(.+)$")
+
+
+def load_diff_facts(
+    repo_root: Path,
+    *,
+    max_commits: int | None = None,
+    cache: CacheStore | None = None,
+) -> DiffFacts:
+    """Build a :class:`DiffFacts` snapshot from one ``git log`` invocation.
+
+    Strategy:
+      1. Walk HEAD with ``git log --no-merges --numstat --pretty=...`` once.
+      2. Parse each commit + its full file-set into a single in-memory map.
+      3. Return the snapshot for the diff command's per-file scorer to drive.
+
+    With a ``cache`` supplied, the walked commits are persisted to
+    ``commits``; per-file diffstat presence rows are persisted to
+    ``commit_files`` so a subsequent ``why`` / ``scan`` / ``diff`` invocation
+    on the same HEAD reuses what we just paid for.
+
+    The walk is intentionally un-pathed: the diff command scores files
+    that appear in ``git diff --name-only base...HEAD``, all of which exist
+    at HEAD by definition. A single un-pathed walk that captures every
+    commit's diffstat is strictly cheaper than N path-restricted walks
+    that each re-walk the full graph. ``max_commits`` is applied per-path
+    *after* the walk so callers can cap per-file depth without changing
+    the cost of the walk itself.
+    """
+    # Pretty format: RECORD_SEP starts each commit; metadata fields are
+    # UNIT_SEP-delimited; the body is the last metadata field. Numstat
+    # output git appends after the body needs no further separator —
+    # the next commit's leading RECORD_SEP marks the boundary.
+    pretty_format = (
+        f"{RECORD_SEP}%H{UNIT_SEP}%an{UNIT_SEP}%ae{UNIT_SEP}"
+        f"%aI{UNIT_SEP}%s{UNIT_SEP}%b"
+    )
+    raw = _run_git(
+        repo_root,
+        "log",
+        "--no-merges",
+        "--numstat",
+        f"--pretty=format:{pretty_format}",
+    )
+    all_commits, commits_by_path, co_change_index = _parse_log_with_files(raw)
+    if max_commits is not None:
+        commits_by_path = {p: cs[:max_commits] for p, cs in commits_by_path.items()}
+    if cache is not None and all_commits:
+        _store_commits(cache, all_commits)
+        # Persist diffstat presence rows so a subsequent `why` against the
+        # same HEAD does not re-shell-out per file. Insertion/deletion
+        # widths are not captured by this walk (the diff command's
+        # detectors only depend on the *path set* of each commit), so they
+        # are stored as zero — see the paragraph in ``DiffFacts``.
+        files_rows: list[tuple[str, str, int, int]] = []
+        for sha, paths in co_change_index.items():
+            for p in paths:
+                files_rows.append((sha, p, 0, 0))
+        if files_rows:
+            cache.upsert_commit_files(files_rows)
+        try:
+            head_sha = _run_git(repo_root, "rev-parse", "HEAD").strip()
+        except GitError:
+            head_sha = ""
+        if head_sha and not cache.head_sha:
+            cache.set_head_sha(head_sha)
+    return DiffFacts(
+        repo_root=repo_root,
+        commits_by_path=commits_by_path,
+        co_change_index=co_change_index,
+        cache=cache,
+    )
+
+
+def _parse_log_with_files(
+    raw: str,
+) -> tuple[list[Commit], dict[str, list[Commit]], dict[str, tuple[str, ...]]]:
+    """Parse ``git log --no-merges --numstat --pretty=<sep><commit>`` output.
+
+    Returns ``(all_commits, commits_by_path, co_change_index)``:
+      - ``all_commits`` is every parsed commit, newest first.
+      - ``commits_by_path[path]`` is the subset whose numstat block named
+        ``path``, preserving the newest-first order of the walk.
+      - ``co_change_index[sha]`` is the full path tuple from the same
+        numstat block, used by the diff command's in-memory coupling.
+
+    Within one record the format is
+    ``<sha>\\x1f<an>\\x1f<ae>\\x1f<aI>\\x1f<subject>\\x1f<body...>``
+    followed by zero or more numstat lines (``ins\\tdel\\tpath``). The body
+    is free-form prose; numstat is tab-delimited 3-column. We walk lines
+    forward, holding the first line as the metadata + start-of-body, and
+    accumulate further lines as either body (free-form) or numstat
+    (matches :data:`_NUMSTAT_LINE_RE`). Once a numstat line fires, the
+    remaining lines for that record are taken to be more numstat lines.
+    """
+    all_commits: list[Commit] = []
+    commits_by_path: dict[str, list[Commit]] = {}
+    co_change_index: dict[str, tuple[str, ...]] = {}
+    for record in raw.split(RECORD_SEP):
+        record = record.strip("\n")
+        if not record:
+            continue
+        lines = record.split("\n")
+        # The first line carries every metadata field plus the first body
+        # line (the body itself was emitted verbatim by ``%b``).
+        head_parts = lines[0].split(UNIT_SEP)
+        if len(head_parts) < 6:
+            continue
+        sha = head_parts[0].strip()
+        if not sha:
+            continue
+        author_name = head_parts[1]
+        author_email = head_parts[2]
+        authored_at = head_parts[3]
+        subject = head_parts[4]
+        first_body = UNIT_SEP.join(head_parts[5:])
+        body_lines: list[str] = [first_body] if first_body else []
+        files: list[str] = []
+        in_numstat = False
+        for line in lines[1:]:
+            m = _NUMSTAT_LINE_RE.match(line)
+            if in_numstat:
+                if m is not None:
+                    files.append(m.group(3))
+                continue
+            if m is not None:
+                in_numstat = True
+                files.append(m.group(3))
+                continue
+            body_lines.append(line)
+        try:
+            authored = _parse_iso(authored_at)
+        except ValueError:
+            # Bad timestamps from a single 15-year-old commit shouldn't kill
+            # the diff command. F1 (full timezone-tolerant parser) is owned
+            # by another branch; we degrade locally rather than crash.
+            continue
+        body = "\n".join(body_lines).strip("\n")
+        commit = Commit(
+            sha=sha,
+            author_name=author_name,
+            author_email=author_email,
+            authored_at=authored,
+            subject=subject,
+            body=body,
+            files=tuple(files),
+        )
+        all_commits.append(commit)
+        co_change_index[sha] = commit.files
+        for path in files:
+            commits_by_path.setdefault(path, []).append(commit)
+    return all_commits, commits_by_path, co_change_index
+
+
+def gather_for_diff(
+    diff_facts: DiffFacts,
+    path: str,
+    *,
+    max_commits: int | None = None,
+) -> RepoFacts:
+    """Build a :class:`RepoFacts` for ``path`` using only the in-memory map.
+
+    The diff command calls this once per changed file, replacing the per-file
+    ``gather()`` (and its embedded ``git log --follow`` + co-change shell-out)
+    with O(1) dict lookups. All higher-layer detectors run unchanged on the
+    returned ``RepoFacts``.
+    """
+    commits = diff_facts.commits_by_path.get(path, [])
+    if max_commits is not None:
+        commits = commits[:max_commits]
+    co_changed: Counter[str] = Counter()
+    for commit in commits:
+        touched = diff_facts.co_change_index.get(commit.sha, ())
+        for other in touched:
+            if other == path:
+                continue
+            co_changed[other] += 1
+    return RepoFacts(
+        repo_root=diff_facts.repo_root,
+        path=path,
+        commits=commits,
+        co_changed_files=co_changed,
+        revert_pairs=find_revert_pairs(commits),
+        incident_commits=find_incidents(commits),
+        invariant_quotes=extract_invariant_quotes(commits),
+        cache=diff_facts.cache,
+    )
+
+
 _REVERT_PREFIX = 'this reverts commit '
 
 

whycode/risk_card.py

@@ -50,7 +50,37 @@ class RiskCard:
 
         return replace(self, decisions=decisions)
 
-    def to_dict(self) -> dict[str, Any]:
+    def to_dict(self, *, explain: bool = False) -> dict[str, Any]:
+        """Render the card as a JSON-friendly dict.
+
+        With ``explain=True``, each signal entry grows an ``explanation``
+        key carrying the rule identifier, prose, evidence, and source
+        location populated by the detector. ``None`` is emitted when a
+        signal has no explanation attached (e.g. data ingested from an
+        older cache); the key is omitted entirely when ``explain`` is
+        off, so default consumers see no shape change.
+        """
+        signals_out: list[dict[str, Any]] = []
+        for s in self.signals:
+            entry: dict[str, Any] = {
+                "kind": s.kind.value,
+                "severity": s.severity,
+                "headline": s.headline,
+                "detail": s.detail,
+                "evidence": list(s.evidence),
+            }
+            if explain:
+                entry["explanation"] = (
+                    {
+                        "rule": s.explanation.rule,
+                        "why_it_fired": s.explanation.why_it_fired,
+                        "evidence": list(s.explanation.evidence),
+                        "source_ref": s.explanation.source_ref,
+                    }
+                    if s.explanation is not None
+                    else None
+                )
+            signals_out.append(entry)
         return {
             "path": self.path,
             "score": self.score.value,
@@ -67,16 +97,7 @@ class RiskCard:
                 if self.most_recent_sha
                 else None
             ),
-            "signals": [
-                {
-                    "kind": s.kind.value,
-                    "severity": s.severity,
-                    "headline": s.headline,
-                    "detail": s.detail,
-                    "evidence": list(s.evidence),
-                }
-                for s in self.signals
-            ],
+            "signals": signals_out,
             "decisions": [d.to_dict() for d in self.decisions],
         }
 
@@ -101,7 +122,63 @@ def build(
     the same repo (e.g. inside ``scan`` or ``diff``) share a warm cache.
     """
     facts = gf.gather(repo_root, path, max_commits=max_commits, ref=ref, cache=cache)
-    signals = sig.all_signals(facts)
+    return _from_facts(
+        path=path,
+        facts=facts,
+        repo_root=repo_root,
+        ref=ref,
+        apply_suppressions=apply_suppressions,
+    )
+
+
+def build_from_diff_facts(
+    diff_facts: gf.DiffFacts,
+    path: str,
+    *,
+    max_commits: int | None = None,
+    apply_suppressions: bool = True,
+    skip_ghost_keeper: bool = False,
+) -> RiskCard:
+    """Build a Risk Card from an in-memory :class:`DiffFacts` map.
+
+    The diff command pre-loads one ``DiffFacts`` for the whole evaluation
+    via :func:`whycode.git_facts.load_diff_facts`, then calls this helper
+    once per changed file. The card's signals, score, and ``most_recent_*``
+    fields all derive from the same in-memory map, so per-file cost is
+    O(1) rather than the per-file ``git log --follow`` it replaces.
+
+    With ``skip_ghost_keeper=True`` the per-file ``git blame`` call is
+    deferred — the diff command uses this for its first pass over every
+    changed file, then re-evaluates only the top-N with full signals.
+    Without this skip, scoring 1,927 files spends ~4-5 minutes inside
+    ``git blame`` even though > 95% of those files never reach the table
+    the user sees.
+    """
+    facts = gf.gather_for_diff(diff_facts, path, max_commits=max_commits)
+    return _from_facts(
+        path=path,
+        facts=facts,
+        repo_root=diff_facts.repo_root,
+        ref=None,
+        apply_suppressions=apply_suppressions,
+        skip_ghost_keeper=skip_ghost_keeper,
+    )
+
+
+def _from_facts(
+    *,
+    path: str,
+    facts: gf.RepoFacts,
+    repo_root: Path,
+    ref: str | None,
+    apply_suppressions: bool,
+    skip_ghost_keeper: bool = False,
+) -> RiskCard:
+    """Common tail of :func:`build` and :func:`build_from_diff_facts`."""
+    if skip_ghost_keeper:
+        signals = _all_signals_without_ghost_keeper(facts)
+    else:
+        signals = sig.all_signals(facts)
     if apply_suppressions:
         suppressions = supp.load(repo_root)
         signals = supp.filter_signals(signals, suppressions, path)
@@ -120,6 +197,40 @@ def build(
     )
 
 
+# Detectors whose evidence is already in :class:`RepoFacts` (no git blame, no
+# follow-up shell-out). The ghost-keeper detector is the only one missing
+# here — it calls ``git blame`` per-file, which is the diff command's
+# remaining bottleneck after the log walk is shared.
+_FAST_DETECTORS = (
+    sig.detect_revert_chain,
+    sig.detect_incident_history,
+    sig.detect_invariant_quotes,
+    sig.detect_coupling,
+    sig.detect_high_churn,
+    sig.detect_silence,
+    sig.detect_newborn,
+)
+
+
+def _all_signals_without_ghost_keeper(facts: gf.RepoFacts) -> list[sig.Signal]:
+    """Re-implement the public ``all_signals`` ladder, minus ghost-keeper.
+
+    Mirrors the NEWBORN-suppression rule that ``signals.all_signals`` uses
+    so that an empty signal list collapses cleanly to NEWBORN-only when the
+    other detectors are all silent. If any other detector fires, NEWBORN is
+    dropped, exactly as the canonical helper does.
+    """
+    out: list[sig.Signal] = []
+    for detector in _FAST_DETECTORS:
+        signal = detector(facts)
+        if signal is not None:
+            out.append(signal)
+    if any(s.kind is not sig.SignalKind.NEWBORN for s in out):
+        out = [s for s in out if s.kind is not sig.SignalKind.NEWBORN]
+    out.sort(key=lambda s: (-s.severity, s.kind.value))
+    return out
+
+
 # ----- rendering ------------------------------------------------------------
 
 _BAND_STYLE: dict[Band, str] = {
@@ -174,7 +285,7 @@ def _evidence_redundant(evidence: tuple[str, ...], detail: str) -> bool:
     return all(token in detail for token in evidence)
 
 
-def _signals_table(signals: tuple[sig.Signal, ...]) -> Table | Text:
+def _signals_table(signals: tuple[sig.Signal, ...], *, explain: bool = False) -> Table | Text:
     if not signals:
         return Text(
             "No flags fired. The history is quiet — this is information, "
@@ -190,6 +301,18 @@ def _signals_table(signals: tuple[sig.Signal, ...]) -> Table | Text:
         block.append(s.detail, style="")
         if s.evidence and not _evidence_redundant(s.evidence, s.detail):
             block.append("\nevidence: " + ", ".join(s.evidence), style="dim")
+        if explain and s.explanation is not None:
+            ex = s.explanation
+            block.append("\n", style="")
+            block.append("─ rule: ", style="dim")
+            block.append(ex.rule, style="dim bold")
+            if ex.source_ref:
+                block.append("  ", style="dim")
+                block.append(ex.source_ref, style="dim")
+            block.append("\n  fired because: ", style="dim")
+            block.append(ex.why_it_fired, style="dim")
+            if ex.evidence:
+                block.append("\n  evidence: " + ", ".join(ex.evidence), style="dim")
         table.add_row(_severity_badge(s.severity), block)
     return table
 
@@ -234,10 +357,10 @@ def _decisions_block(decisions: tuple[Decision, ...]) -> Padding:
     return Padding(panel, (1, 1, 0, 1))
 
 
-def render_text(card: RiskCard) -> Group:
+def render_text(card: RiskCard, *, explain: bool = False) -> Group:
     pieces: list[Any] = [
         _header(card),
-        Padding(_signals_table(card.signals), (0, 1, 0, 1)),
+        Padding(_signals_table(card.signals, explain=explain), (0, 1, 0, 1)),
     ]
     if card.decisions:
         pieces.append(_decisions_block(card.decisions))
@@ -247,4 +370,4 @@ def render_text(card: RiskCard) -> Group:
     return Group(*pieces)
 
 
-__all__ = ["RiskCard", "build", "render_text"]
+__all__ = ["RiskCard", "build", "build_from_diff_facts", "render_text"]

whycode/signals.py

@@ -16,7 +16,7 @@ from whycode import git_facts as gf
 from whycode import ignore as ign
 
 if TYPE_CHECKING:
-    from whycode.git_facts import RepoFacts
+    from whycode.git_facts import Commit, RepoFacts
 
 
 class SignalKind(StrEnum):
@@ -30,6 +30,29 @@ class SignalKind(StrEnum):
     NEWBORN = "newborn"
 
 
+@dataclass(frozen=True)
+class Explanation:
+    """Structured trace of why a single signal fired.
+
+    Each detector that produces a :class:`Signal` populates this with the
+    concrete rule branch that matched, the literal evidence (token, count,
+    threshold) the rule looked at, and a stable ``file:function`` reference
+    so a curious reader can open the source and audit the ladder.
+    """
+
+    rule: str
+    """Short stable identifier, e.g. ``"incident_subject_keyword"``."""
+
+    why_it_fired: str
+    """One-sentence prose describing the matching condition."""
+
+    evidence: tuple[str, ...] = field(default_factory=tuple)
+    """Literal matched substrings, threshold values, or counts."""
+
+    source_ref: str = ""
+    """``path:function`` pointer into the project source for the rule."""
+
+
 @dataclass(frozen=True)
 class Signal:
     kind: SignalKind
@@ -39,6 +62,9 @@ class Signal:
     evidence: tuple[str, ...] = field(default_factory=tuple)
     """Commit SHAs (or other identifiers) backing this signal."""
 
+    explanation: Explanation | None = None
+    """Per-rule trace populated when ``whycode why --explain`` is on."""
+
 
 # ----- thresholds -----------------------------------------------------------
 COUPLING_MIN_COCHANGES = 3
@@ -90,6 +116,84 @@ def _decay_severity(severity: int, days_since_most_recent: int) -> int:
     return severity
 
 
+def _classify_incident_commit(commit: Commit) -> tuple[str, str, tuple[str, ...]]:
+    """Return ``(rule, why, evidence_tokens)`` for the rule branch that fired.
+
+    Mirrors the acceptance ladder in :func:`whycode.git_facts.find_incidents`
+    so an :class:`Explanation` can name which clause matched on this specific
+    commit. Evaluation order matches the ladder; the first match wins.
+    """
+    subject = commit.subject
+    body = commit.body
+    cve = gf._CVE_RE.search(subject)
+    if cve:
+        return (
+            "incident_subject_security_advisory",
+            f"subject cites the security advisory {cve.group(0)!r}",
+            (cve.group(0),),
+        )
+    ghsa = gf._GHSA_RE.search(subject)
+    if ghsa:
+        return (
+            "incident_subject_security_advisory",
+            f"subject cites the security advisory {ghsa.group(0)!r}",
+            (ghsa.group(0),),
+        )
+    if gf._REVERTED_SUBJECT_RE.search(subject) or gf._REVERTS_SUBJECT_RE.search(subject):
+        return (
+            "incident_subject_revert_marker",
+            "subject is a default git revert pointer (Reverted/Reverts)",
+            ("Reverted",) if gf._REVERTED_SUBJECT_RE.search(subject) else ("Reverts",),
+        )
+    cc = gf._BREAKING_CC_RE.search(subject)
+    if cc:
+        return (
+            "incident_subject_conventional_commits_breaking",
+            f"subject carries the Conventional Commits breaking marker {cc.group(0).strip()!r}",
+            (cc.group(0).strip(),),
+        )
+    # Subject keyword path (regression handled with corroboration inside the helper).
+    if gf._is_subject_incident(subject, body):
+        # Find which keyword actually matched in subject.
+        match = gf._INCIDENT_RE.search(subject)
+        if match:
+            tok = match.group(0)
+            return (
+                "incident_subject_keyword",
+                f"subject {subject[:60]!r} matched the literal token {tok!r}",
+                (tok,),
+            )
+        # _is_subject_incident also accepts the regression+id corroboration
+        # path even when no other keyword is in the subject.
+        return (
+            "incident_subject_regression_corroborated",
+            "subject contains 'regression' and a corroborating issue id",
+            ("regression",),
+        )
+    if gf._BREAKING_FOOTER_RE.search(body):
+        return (
+            "incident_body_breaking_change_footer",
+            "body carries the structured 'BREAKING CHANGE:' footer",
+            ("BREAKING CHANGE:",),
+        )
+    body_kw = gf._INCIDENT_RE.search(body)
+    issue = gf._ISSUE_ID_RE.search(body)
+    if body_kw and issue:
+        return (
+            "incident_body_keyword_with_issue_id",
+            (
+                f"body keyword {body_kw.group(0)!r} corroborated by issue id "
+                f"{issue.group(0)!r}"
+            ),
+            (body_kw.group(0), issue.group(0)),
+        )
+    # Should not happen — find_incidents only returns commits that match one
+    # of the branches above. Falling through means the ladder grew without
+    # this helper. Return a neutral classification so the explanation surface
+    # never crashes.
+    return ("incident_unclassified", "matched the incident ladder", ())
+
+
 def detect_revert_chain(facts: RepoFacts) -> Signal | None:
     if not facts.revert_pairs:
         return None
@@ -104,12 +208,22 @@ def detect_revert_chain(facts: RepoFacts) -> Signal | None:
         age_phrase = f" (most recent: {_age_phrase(days)})"
     evidence = tuple(_short(rev) for rev, _ in facts.revert_pairs)
     pairs_text = ", ".join(f"{_short(rev)} reverts {_short(orig)}" for rev, orig in facts.revert_pairs)
+    explanation = Explanation(
+        rule="revert_pair_default_message",
+        why_it_fired=(
+            f"{n} commit{' body matches' if n == 1 else ' bodies match'} the default git "
+            "revert footer 'This reverts commit <sha>'"
+        ),
+        evidence=evidence,
+        source_ref="src/whycode/git_facts.py:find_revert_pairs",
+    )
     return Signal(
         kind=SignalKind.REVERT_CHAIN,
         severity=severity,
         headline=f"{n} revert{'s' if n != 1 else ''} touched this file{age_phrase}",
         detail=f"Reverts in this file's history: {pairs_text}.",
         evidence=evidence,
+        explanation=explanation,
     )
 
 
@@ -124,12 +238,20 @@ def detect_incident_history(facts: RepoFacts) -> Signal | None:
         f"{n} commit{'s' if n != 1 else ''} matched incident keywords "
         f"(latest {days} day{'s' if days != 1 else ''} ago: '{most_recent.subject[:80]}')."
     )
+    rule, why, tokens = _classify_incident_commit(most_recent)
+    explanation = Explanation(
+        rule=rule,
+        why_it_fired=why,
+        evidence=tokens,
+        source_ref="src/whycode/git_facts.py:find_incidents",
+    )
     return Signal(
         kind=SignalKind.INCIDENT_HISTORY,
         severity=severity,
         headline=f"{n} incident-flagged change{'s' if n != 1 else ''} in history",
         detail=detail,
         evidence=tuple(_short(c.sha) for c in facts.incident_commits[:5]),
+        explanation=explanation,
     )
 
 
@@ -139,12 +261,26 @@ def detect_high_churn(facts: RepoFacts) -> Signal | None:
     if len(recent) < HIGH_CHURN_MIN_COMMITS:
         return None
     severity = 3 if len(recent) < 12 else 4
+    explanation = Explanation(
+        rule="high_churn_recent_window",
+        why_it_fired=(
+            f"{len(recent)} commits within the last {cutoff_days} days crossed the "
+            f"threshold of {HIGH_CHURN_MIN_COMMITS}"
+        ),
+        evidence=(
+            f"recent_commits={len(recent)}",
+            f"window_days={cutoff_days}",
+            f"threshold={HIGH_CHURN_MIN_COMMITS}",
+        ),
+        source_ref="src/whycode/signals.py:detect_high_churn",
+    )
     return Signal(
         kind=SignalKind.HIGH_CHURN,
         severity=severity,
         headline=f"High churn: {len(recent)} commits in last {cutoff_days} days",
         detail="Code that changes this often is rarely settled — read recent diffs first.",
         evidence=tuple(_short(c.sha) for c in recent[:5]),
+        explanation=explanation,
     )
 
 
@@ -172,12 +308,27 @@ def detect_coupling(facts: RepoFacts) -> Signal | None:
     top = paired[:5]
     severity = 3 if top[0][1] < 6 else 4
     listed = "; ".join(f"{p} (x{n})" for p, n in top)
+    top_path, top_count = top[0]
+    explanation = Explanation(
+        rule="coupling_co_change_threshold",
+        why_it_fired=(
+            f"{top_path!r} changed together with this file {top_count} times "
+            f"(threshold {COUPLING_MIN_COCHANGES})"
+        ),
+        evidence=(
+            f"top_co_changer={top_path}",
+            f"co_changes={top_count}",
+            f"threshold={COUPLING_MIN_COCHANGES}",
+        ),
+        source_ref="src/whycode/signals.py:detect_coupling",
+    )
     return Signal(
         kind=SignalKind.COUPLING,
         severity=severity,
         headline=f"Tightly coupled to {len(top)} other file{'s' if len(top) != 1 else ''}",
         detail=f"Tends to change together with: {listed}.",
         evidence=tuple(p for p, _ in top),
+        explanation=explanation,
     )
 
 
@@ -189,6 +340,18 @@ def detect_silence(facts: RepoFacts) -> Signal | None:
     if days < SILENCE_DAYS:
         return None
     severity = 2 if days < 365 else 3
+    explanation = Explanation(
+        rule="silence_untouched_threshold",
+        why_it_fired=(
+            f"most recent commit on this file is {days} days old, exceeding the "
+            f"{SILENCE_DAYS}-day silence threshold"
+        ),
+        evidence=(
+            f"days_since_last_commit={days}",
+            f"threshold={SILENCE_DAYS}",
+        ),
+        source_ref="src/whycode/signals.py:detect_silence",
+    )
     return Signal(
         kind=SignalKind.SILENCE,
         severity=severity,
@@ -198,6 +361,7 @@ def detect_silence(facts: RepoFacts) -> Signal | None:
             "before assuming the silence means stability."
         ),
         evidence=(_short(most_recent.sha),),
+        explanation=explanation,
     )
 
 
@@ -208,12 +372,25 @@ def detect_newborn(facts: RepoFacts) -> Signal | None:
     days = _days_since(oldest.authored_at)
     if days > NEWBORN_DAYS:
         return None
+    explanation = Explanation(
+        rule="newborn_first_commit_window",
+        why_it_fired=(
+            f"oldest commit on this file is {days} day(s) old, within the "
+            f"{NEWBORN_DAYS}-day newborn window"
+        ),
+        evidence=(
+            f"days_since_first_commit={days}",
+            f"threshold={NEWBORN_DAYS}",
+        ),
+        source_ref="src/whycode/signals.py:detect_newborn",
+    )
     return Signal(
         kind=SignalKind.NEWBORN,
         severity=1,
         headline=f"New file (first commit {days} day{'s' if days != 1 else ''} ago)",
         detail="Limited history — the usual signals are not yet trustworthy.",
         evidence=(_short(oldest.sha),),
+        explanation=explanation,
     )
 
 
@@ -266,9 +443,27 @@ def detect_ghost_keeper(facts: RepoFacts) -> Signal | None:
 
     if ownership_share is not None:
         ownership_phrase = f"wrote {ownership_share:.0%} of current lines"
+        ownership_evidence = f"line_ownership_share={ownership_share:.2f}"
+        rule = "ghost_keeper_inactive_line_owner"
     else:
         share = sum(1 for c in facts.commits if c.author_email == primary_email)
         ownership_phrase = f"wrote {share} of {len(facts.commits)} commits here"
+        ownership_evidence = f"commits_by_primary={share}"
+        rule = "ghost_keeper_inactive_commit_owner"
+
+    explanation = Explanation(
+        rule=rule,
+        why_it_fired=(
+            f"primary author of this file has not committed anywhere for "
+            f"{days_since_seen} days (threshold {GHOST_KEEPER_DAYS})"
+        ),
+        evidence=(
+            f"days_since_active={days_since_seen}",
+            f"threshold={GHOST_KEEPER_DAYS}",
+            ownership_evidence,
+        ),
+        source_ref="src/whycode/signals.py:detect_ghost_keeper",
+    )
 
     return Signal(
         kind=SignalKind.GHOST_KEEPER,
@@ -280,6 +475,7 @@ def detect_ghost_keeper(facts: RepoFacts) -> Signal | None:
             f"Knowledge may have left the team."
         ),
         evidence=(_short(primary_commit.sha),),
+        explanation=explanation,
     )
 
 
@@ -345,6 +541,22 @@ def detect_invariant_quotes(facts: RepoFacts) -> Signal | None:
         if short not in seen_shas:
             seen_shas.add(short)
             evidence_shas.append(short)
+    matched_tokens: list[str] = []
+    seen_tokens: set[str] = set()
+    for line in seen:
+        m = gf._INVARIANT_RE.search(line)
+        if m and m.group(0).lower() not in seen_tokens:
+            seen_tokens.add(m.group(0).lower())
+            matched_tokens.append(m.group(0))
+    explanation = Explanation(
+        rule="invariant_token_match_in_body",
+        why_it_fired=(
+            f"{total} commit body line{'s' if total != 1 else ''} contained a known "
+            "invariant token (e.g. 'do not', 'must not', 'workaround', …)"
+        ),
+        evidence=tuple(matched_tokens) if matched_tokens else (f"matches={total}",),
+        source_ref="src/whycode/git_facts.py:extract_invariant_quotes",
+    )
     return Signal(
         kind=SignalKind.INVARIANT_QUOTE,
         severity=severity,
@@ -354,6 +566,7 @@ def detect_invariant_quotes(facts: RepoFacts) -> Signal | None:
         ),
         detail="Past authors used cautionary language in commit messages:\n" + rendered,
         evidence=tuple(evidence_shas),
+        explanation=explanation,
     )
 
 
@@ -388,6 +601,7 @@ def all_signals(facts: RepoFacts) -> list[Signal]:
 
 
 __all__ = [
+    "Explanation",
     "Signal",
     "SignalKind",
     "all_signals",

{whycode_cli-0.4.2.dist-info → whycode_cli-0.5.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.4.2
+Version: 0.5.2
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT
@@ -140,6 +140,32 @@ Score interpretation:
 | 25–49   | WORTH A LOOK        | One thing might bite you. Glance.       |
 | 0–24    | NO FLAGS            | Quiet history — but read the diff anyway. |
 
+### "But why exactly did this fire?" — `--explain`
+
+When a signal looks wrong (or you just want to understand the reasoning
+before trusting the tool), pass `--explain`. Each fired signal grows a
+small block naming the precise rule that produced it, the literal evidence
+the rule looked at, and the source location of the ladder branch:
+
+```
+$ whycode why src/payment/refund.py --explain
+
+   MED     1 incident-flagged change in history
+           1 commit matched incident keywords (latest 12 days ago:
+           'hotfix: idempotency token regression').
+           evidence: a3f4b2c
+           ─ rule: incident_subject_keyword  src/whycode/git_facts.py:find_incidents
+             fired because: subject 'hotfix: idempotency token regression'
+                            matched the literal token 'hotfix'
+             evidence: hotfix
+```
+
+Without `--explain`, output is exactly as before — this is purely an
+opt-in transparency surface. `--explain --json` adds an `explanation`
+key per signal in the JSON output, with the same fields. The flag covers
+L1+L2 detectors only; if you also pass `--llm`, the L3 decision block is
+unaffected.
+
 ## The killer use case: hand it to your AI editor
 
 WhyCode is also an MCP server. Configure it in any MCP-aware editor or

{whycode_cli-0.4.2.dist-info → whycode_cli-0.5.2.dist-info}/RECORD

@@ -1,22 +1,22 @@
-whycode/__init__.py,sha256=YXMeIO9f86OJ3_EonP3wlcLW6Qv9sIHQQZqr-Ja4HV8,96
+whycode/__init__.py,sha256=HkmUVIKP--eR8gyVbGEEEzJ1fogqXGGp-PTF9UIPdYw,96
 whycode/__main__.py,sha256=dqAk6746YpuM-FTIH4TBOULegGc5WweojiZjce0VYgQ,105
 whycode/cache.py,sha256=0cEPZHdolQbSiBLAOnMu20tobIrc7G0MNycpldHRpkk,18536
-whycode/cli.py,sha256=uRW5aysC2ufYvs_qPC1gzZcjQTFUZHdXxAmF25d4oY8,49328
+whycode/cli.py,sha256=CRDzVcZJur5DcYg1eoLfwZMSAqDJ8kwkSWg0U4ktmI4,53589
 whycode/decisions.py,sha256=oCVhEF7QfHeci0LAWNtEjV2mUAEBJloL1rT3I4XXbkw,7570
-whycode/git_facts.py,sha256=MLp8e4nGaam6lBGCHY5-sftHj71lyg_HmmBOBx3g-kg,41829
+whycode/git_facts.py,sha256=zevyDVZTIvWJrtaiufhOdFboltH5__pooWFBdO8AhBY,51567
 whycode/ignore.py,sha256=O_8bHIt0d1U-sYrBajBa7oEqpnHWU3f6Zf-8PU8CpO0,4748
 whycode/llm.py,sha256=leB94pBg8kUCq_BujZq5ixny0urGtKskjdaKoum_eCA,4092
 whycode/mcp_server.py,sha256=ht1tStAkOwmQzNIRkm1eA8Tnc59fzDRSGkgyIprft-0,18503
-whycode/risk_card.py,sha256=xOJkHwIkS_6yw_dSowsQ6LHfeD9Mwr2tymL7_wqxs0U,8855
+whycode/risk_card.py,sha256=gur_01ESKVhVQJrEQeVcOvJq5KDSIu8cZbaFZtVHBMQ,13718
 whycode/scorer.py,sha256=4pBejunfxzYhGUzMeL8uGEMQzC6DWiqwcTeMdo3eras,1444
-whycode/signals.py,sha256=z0kZfXR60nS-j56nchHd1V3aK8A5CGR1BAyHZZAff3s,13899
+whycode/signals.py,sha256=yHsNmo6fbUQS8vQwuhAPSgP7Tn3fD-Etio62upacIsQ,22176
 whycode/suppressions.py,sha256=1lKSs-kCgpnJbcxozcgiSP8ZAfjEDMHXuM3sw4FaY78,3836
 whycode/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 whycode/templates/github-workflow.yml,sha256=LAfHMDG2TkAwi4vCNinHk-4zOt-mCWErBpmpaqlW5oA,2251
 whycode/templates/pre-commit,sha256=IhU11CvoDwqRAAsvHwUo-BwaNbdgy1cpXc54Z_phrmQ,316
-whycode_cli-0.4.2.dist-info/licenses/LICENSE,sha256=U6LN5qg5kJXSJf7KFPm9KJhmiGn3qK_GsTVWXdt1DFA,1062
-whycode_cli-0.4.2.dist-info/METADATA,sha256=GD3cP18eEcHePHEXxroFuuZ-2pysLn51biNROQKDBXw,10218
-whycode_cli-0.4.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-whycode_cli-0.4.2.dist-info/entry_points.txt,sha256=xrNWc4CQn3ZhQFJxsGIPiTqpN19K4pRpgaj6qGaEzSQ,44
-whycode_cli-0.4.2.dist-info/top_level.txt,sha256=6yIL5rxW-4DbARHQYrPlGQVqKddZ88sjvmNosDh1w3A,8
-whycode_cli-0.4.2.dist-info/RECORD,,
+whycode_cli-0.5.2.dist-info/licenses/LICENSE,sha256=U6LN5qg5kJXSJf7KFPm9KJhmiGn3qK_GsTVWXdt1DFA,1062
+whycode_cli-0.5.2.dist-info/METADATA,sha256=dvNlR2ck9ZATEtphb69C98V3XDqjX1CLzgb1_iSFtKQ,11364
+whycode_cli-0.5.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+whycode_cli-0.5.2.dist-info/entry_points.txt,sha256=xrNWc4CQn3ZhQFJxsGIPiTqpN19K4pRpgaj6qGaEzSQ,44
+whycode_cli-0.5.2.dist-info/top_level.txt,sha256=6yIL5rxW-4DbARHQYrPlGQVqKddZ88sjvmNosDh1w3A,8
+whycode_cli-0.5.2.dist-info/RECORD,,