whycode-cli 0.2.0__py3-none-any.whl

whycode/risk_card.py

@@ -0,0 +1,192 @@
+"""Render a Risk Card for a single file.
+
+Two output modes:
+- ``render_text`` returns a rich-renderable Group suitable for terminals.
+- ``to_dict`` returns a JSON-friendly dict (used by --json and the MCP server).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from rich.console import Group
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from whycode import git_facts as gf
+from whycode import signals as sig
+from whycode.scorer import Band, Score, score
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass(frozen=True)
+class RiskCard:
+    path: str
+    score: Score
+    signals: tuple[sig.Signal, ...]
+    commit_count: int
+    most_recent_sha: str | None
+    most_recent_subject: str | None
+    most_recent_author: str | None
+    most_recent_at: str | None
+    as_of_sha: str | None = None
+    """When set, the card was computed *as of* this commit (historical view)."""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "score": self.score.value,
+            "band": self.score.band.value,
+            "commit_count": self.commit_count,
+            "as_of": self.as_of_sha,
+            "most_recent": (
+                {
+                    "sha": self.most_recent_sha,
+                    "subject": self.most_recent_subject,
+                    "author": self.most_recent_author,
+                    "authored_at": self.most_recent_at,
+                }
+                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
+            ],
+        }
+
+
+def build(
+    repo_root: Path,
+    path: str,
+    *,
+    max_commits: int | None = None,
+    ref: str | None = None,
+) -> RiskCard:
+    facts = gf.gather(repo_root, path, max_commits=max_commits, ref=ref)
+    signals = sig.all_signals(facts)
+    s = score(signals)
+    head = facts.commits[0] if facts.commits else None
+    return RiskCard(
+        path=path,
+        score=s,
+        signals=tuple(signals),
+        commit_count=len(facts.commits),
+        most_recent_sha=head.sha[:12] if head else None,
+        most_recent_subject=head.subject if head else None,
+        most_recent_author=head.author_name if head else None,
+        most_recent_at=head.authored_at.isoformat() if head else None,
+        as_of_sha=ref[:12] if ref else None,
+    )
+
+
+# ----- rendering ------------------------------------------------------------
+
+_BAND_STYLE: dict[Band, str] = {
+    Band.HANDLE_WITH_CARE: "bold white on red",
+    Band.READ_HISTORY_FIRST: "bold black on yellow",
+    Band.WORTH_A_LOOK: "bold black on cyan",
+    Band.NO_FLAGS: "bold black on green",
+}
+
+
+def _severity_badge(severity: int) -> Text:
+    """Replace cryptic glyphs with a labelled, colour-coded severity tag."""
+    if severity >= 4:
+        return Text(" HIGH ", style="bold white on red")
+    if severity == 3:
+        return Text(" MED  ", style="bold black on yellow")
+    return Text(" LOW  ", style="bold black on cyan")
+
+
+def _header(card: RiskCard) -> Panel:
+    style = _BAND_STYLE[card.score.band]
+    title = Text()
+    title.append(" ")
+    title.append(card.score.band.value, style=style)
+    title.append("  ")
+    title.append(f"score {card.score.value}/100", style="bold")
+    if card.as_of_sha:
+        title.append(f"   as of {card.as_of_sha}", style="dim")
+    body = Text()
+    body.append(card.path, style="bold")
+    body.append(f"   ({card.commit_count} commits)\n", style="dim")
+    if card.most_recent_subject:
+        # Subject must fit on one line inside an 80-col Panel: 80 minus borders,
+        # padding, and the 8-char "Latest: " prefix leaves ~64 chars usable.
+        subj = card.most_recent_subject
+        if len(subj) > 64:
+            subj = subj[:63] + "…"
+        body.append("Latest: ", style="dim")
+        body.append(subj + "\n", style="")
+        body.append(
+            f"        {card.most_recent_sha}  {card.most_recent_author}  "
+            f"{(card.most_recent_at or '')[:10]}",
+            style="dim",
+        )
+    return Panel(body, title=title, title_align="left", border_style="grey50")
+
+
+def _evidence_redundant(evidence: tuple[str, ...], detail: str) -> bool:
+    """True if every evidence token already appears verbatim in the detail."""
+    if not evidence:
+        return True
+    return all(token in detail for token in evidence)
+
+
+def _signals_table(signals: tuple[sig.Signal, ...]) -> Table | Text:
+    if not signals:
+        return Text(
+            "No flags fired. The history is quiet — this is information, "
+            "not safety. Read the diff anyway.",
+            style="italic dim",
+        )
+    table = Table(show_header=False, box=None, padding=(0, 1, 1, 1), expand=True)
+    table.add_column(width=7, no_wrap=True)
+    table.add_column(ratio=1)
+    for s in signals:
+        block = Text()
+        block.append(s.headline + "\n", style="bold")
+        block.append(s.detail, style="")
+        if s.evidence and not _evidence_redundant(s.evidence, s.detail):
+            block.append("\nevidence: " + ", ".join(s.evidence), style="dim")
+        table.add_row(_severity_badge(s.severity), block)
+    return table
+
+
+def _next_step_hint(signals: tuple[sig.Signal, ...]) -> Text | None:
+    """Suggest a single concrete next action if a SHA-shaped evidence exists."""
+    for s in signals:
+        for token in s.evidence:
+            if 7 <= len(token) <= 12 and all(c in "0123456789abcdef" for c in token):
+                hint = Text()
+                hint.append("→ ", style="bold")
+                hint.append(f"git show {token}", style="bold cyan")
+                hint.append("   to read the most relevant commit in full", style="dim")
+                return hint
+    return None
+
+
+def render_text(card: RiskCard) -> Group:
+    pieces: list[Any] = [
+        _header(card),
+        Padding(_signals_table(card.signals), (0, 1, 0, 1)),
+    ]
+    hint = _next_step_hint(card.signals)
+    if hint is not None:
+        pieces.append(Padding(hint, (0, 1, 1, 2)))
+    return Group(*pieces)
+
+
+__all__ = ["RiskCard", "build", "render_text"]

whycode/scorer.py

@@ -0,0 +1,55 @@
+"""Risk scoring: signals -> a single 0..100 score and a human-readable band."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+
+from whycode.signals import Signal, SignalKind
+
+# Per-signal contribution at severity 1. Severity multiplies linearly up to 5.
+_BASE_WEIGHT: dict[SignalKind, int] = {
+    SignalKind.REVERT_CHAIN: 9,
+    SignalKind.INCIDENT_HISTORY: 8,
+    SignalKind.GHOST_KEEPER: 6,
+    SignalKind.INVARIANT_QUOTE: 6,
+    SignalKind.COUPLING: 5,
+    SignalKind.HIGH_CHURN: 5,
+    SignalKind.SILENCE: 3,
+    SignalKind.NEWBORN: 1,
+}
+
+_BAND_THRESHOLDS = (
+    (75, "HANDLE WITH CARE"),
+    (50, "READ HISTORY FIRST"),
+    (25, "WORTH A LOOK"),
+    (0, "NO FLAGS"),
+)
+
+
+class Band(StrEnum):
+    HANDLE_WITH_CARE = "HANDLE WITH CARE"
+    READ_HISTORY_FIRST = "READ HISTORY FIRST"
+    WORTH_A_LOOK = "WORTH A LOOK"
+    NO_FLAGS = "NO FLAGS"
+
+
+@dataclass(frozen=True)
+class Score:
+    value: int
+    band: Band
+
+
+def score(signals: Sequence[Signal]) -> Score:
+    """Combine signals into a 0..100 risk score with a band label."""
+    raw = 0
+    for s in signals:
+        weight = _BASE_WEIGHT.get(s.kind, 1)
+        raw += weight * s.severity
+    bounded = max(0, min(100, raw))
+    label = next(label for thresh, label in _BAND_THRESHOLDS if bounded >= thresh)
+    return Score(value=bounded, band=Band(label))
+
+
+__all__ = ["Band", "Score", "score"]

whycode/signals.py

@@ -0,0 +1,389 @@
+"""Layer 2: heuristic signal extraction.
+
+Each signal answers one specific question. Signals never invent evidence —
+every one carries the SHAs that produced it, so a careful reader can verify.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from whycode import git_facts as gf
+
+if TYPE_CHECKING:
+    from whycode.git_facts import RepoFacts
+
+
+class SignalKind(StrEnum):
+    REVERT_CHAIN = "revert_chain"
+    INCIDENT_HISTORY = "incident_history"
+    HIGH_CHURN = "high_churn"
+    COUPLING = "coupling"
+    SILENCE = "silence"
+    GHOST_KEEPER = "ghost_keeper"
+    INVARIANT_QUOTE = "invariant_quote"
+    NEWBORN = "newborn"
+
+
+@dataclass(frozen=True)
+class Signal:
+    kind: SignalKind
+    severity: int  # 1..5; 5 is loudest.
+    headline: str
+    detail: str
+    evidence: tuple[str, ...] = field(default_factory=tuple)
+    """Commit SHAs (or other identifiers) backing this signal."""
+
+
+# ----- thresholds -----------------------------------------------------------
+COUPLING_MIN_COCHANGES = 3
+SILENCE_DAYS = 180
+GHOST_KEEPER_DAYS = 365
+HIGH_CHURN_WINDOW_DAYS = 90
+HIGH_CHURN_MIN_COMMITS = 6
+NEWBORN_DAYS = 14
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _days_since(when: datetime) -> int:
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max(0, (_now() - when).days)
+
+
+def _short(sha: str) -> str:
+    return sha[:7]
+
+
+def _age_phrase(days: int) -> str:
+    """Render a days count as a human phrase used in headlines."""
+    if days < 14:
+        return f"{days} day{'s' if days != 1 else ''} ago"
+    if days < 90:
+        return f"{days // 7} weeks ago"
+    if days < 730:
+        return f"{days // 30} months ago"
+    years = days // 365
+    return f"{years} year{'s' if years != 1 else ''} ago"
+
+
+def _decay_severity(severity: int, days_since_most_recent: int) -> int:
+    """Reduce severity for older signals; never below 1.
+
+    Buckets chosen for legibility:
+      - < 2 years: full weight (the team likely still remembers this)
+      - 2-5 years: drop one severity step (memory is fading)
+      - > 5 years: drop two steps, but keep at least 1 (still real evidence)
+    """
+    if days_since_most_recent > 1825:
+        return max(1, severity - 2)
+    if days_since_most_recent > 730:
+        return max(1, severity - 1)
+    return severity
+
+
+def detect_revert_chain(facts: RepoFacts) -> Signal | None:
+    if not facts.revert_pairs:
+        return None
+    n = len(facts.revert_pairs)
+    severity = min(5, 2 + n)
+    revert_shas = {sha for sha, _ in facts.revert_pairs}
+    revert_commits = [c for c in facts.commits if c.sha in revert_shas]
+    age_phrase = ""
+    if revert_commits:
+        days = _days_since(max(c.authored_at for c in revert_commits))
+        severity = _decay_severity(severity, days)
+        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)
+    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,
+    )
+
+
+def detect_incident_history(facts: RepoFacts) -> Signal | None:
+    if not facts.incident_commits:
+        return None
+    most_recent = max(facts.incident_commits, key=lambda c: c.authored_at)
+    days = _days_since(most_recent.authored_at)
+    n = len(facts.incident_commits)
+    severity = 4 if (days < 90 and n >= 2) else 3 if days < 365 else 2
+    detail = (
+        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]}')."
+    )
+    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]),
+    )
+
+
+def detect_high_churn(facts: RepoFacts) -> Signal | None:
+    cutoff_days = HIGH_CHURN_WINDOW_DAYS
+    recent = [c for c in facts.commits if _days_since(c.authored_at) <= cutoff_days]
+    if len(recent) < HIGH_CHURN_MIN_COMMITS:
+        return None
+    severity = 3 if len(recent) < 12 else 4
+    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]),
+    )
+
+
+def detect_coupling(facts: RepoFacts) -> Signal | None:
+    paired = [(p, n) for p, n in facts.co_changed_files.items() if n >= COUPLING_MIN_COCHANGES]
+    if not paired:
+        return None
+    paired.sort(key=lambda x: (-x[1], x[0]))
+    top = paired[:5]
+    severity = 3 if top[0][1] < 6 else 4
+    listed = "; ".join(f"{p} (x{n})" for p, n in top)
+    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),
+    )
+
+
+def detect_silence(facts: RepoFacts) -> Signal | None:
+    if not facts.commits:
+        return None
+    most_recent = facts.commits[0]
+    days = _days_since(most_recent.authored_at)
+    if days < SILENCE_DAYS:
+        return None
+    severity = 2 if days < 365 else 3
+    return Signal(
+        kind=SignalKind.SILENCE,
+        severity=severity,
+        headline=f"Untouched for {days} days",
+        detail=(
+            "Long-quiet code is often load-bearing. Verify it is still exercised "
+            "before assuming the silence means stability."
+        ),
+        evidence=(_short(most_recent.sha),),
+    )
+
+
+def detect_newborn(facts: RepoFacts) -> Signal | None:
+    if not facts.commits:
+        return None
+    oldest = facts.commits[-1]
+    days = _days_since(oldest.authored_at)
+    if days > NEWBORN_DAYS:
+        return None
+    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),),
+    )
+
+
+def detect_ghost_keeper(facts: RepoFacts) -> Signal | None:
+    """Has the file's primary author left the project?
+
+    Ownership is measured by ``git blame`` lines on HEAD (so a single big
+    initial commit by Alice still names Alice as primary even if Bob has 20
+    small fixes after). When blame is unavailable, fall back to commit count.
+
+    The signal fires only if the primary owner's last commit anywhere in the
+    repo is older than ``GHOST_KEEPER_DAYS``. Severity scales with both how
+    long they have been gone and how much of the current file they own.
+    """
+    if not facts.commits:
+        return None
+
+    blame = gf.line_ownership(facts.repo_root, facts.path)
+    ownership_share: float | None = None
+    if blame:
+        total_lines = sum(blame.values())
+        if total_lines == 0:
+            return None
+        primary_email = max(blame, key=lambda e: blame[e])
+        ownership_share = blame[primary_email] / total_lines
+    else:
+        counts: dict[str, int] = {}
+        for commit in facts.commits:
+            counts[commit.author_email] = counts.get(commit.author_email, 0) + 1
+        primary_email = max(counts, key=lambda e: counts[e])
+
+    primary_last_seen = gf.author_last_activity(facts.repo_root, primary_email)
+    if primary_last_seen is None or _days_since(primary_last_seen) < GHOST_KEEPER_DAYS:
+        return None
+    days_since_seen = _days_since(primary_last_seen)
+
+    primary_commit: gf.Commit | None = None
+    for commit in facts.commits:
+        if commit.author_email == primary_email:
+            primary_commit = commit
+            break
+    if primary_commit is None:
+        primary_commit = facts.commits[0]
+
+    severity = 3
+    if days_since_seen > 730 or (ownership_share is not None and ownership_share >= 0.7):
+        severity = 4
+    if days_since_seen > 1825 and (ownership_share is None or ownership_share >= 0.5):
+        severity = 5
+
+    if ownership_share is not None:
+        ownership_phrase = f"wrote {ownership_share:.0%} of current lines"
+    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"
+
+    return Signal(
+        kind=SignalKind.GHOST_KEEPER,
+        severity=severity,
+        headline=f"Primary author last active {days_since_seen} days ago",
+        detail=(
+            f"{primary_commit.author_name} {ownership_phrase}, but has not "
+            f"committed anywhere in this repo for {days_since_seen} days. "
+            f"Knowledge may have left the team."
+        ),
+        evidence=(_short(primary_commit.sha),),
+    )
+
+
+_INVARIANT_BULLETS = 3
+_INVARIANT_BULLET_LEN = 110
+
+
+_SENTENCE_MIN = 25
+
+
+def _first_sentence(line: str, limit: int) -> str:
+    """Return the first complete clause from ``line``, capped at ``limit``.
+
+    A separator only counts as a clause-break once the prefix is at least
+    ``_SENTENCE_MIN`` characters long — otherwise short tokens like "1." or
+    "e.g." would split off into useless one-token bullets.
+    """
+    candidates = []
+    for sep in (". ", "; ", " — ", " - "):
+        idx = line.find(sep, _SENTENCE_MIN)
+        if idx > 0:
+            candidates.append(idx + (1 if sep.startswith(".") else 0))
+    if candidates:
+        cut = min(candidates)
+        sliced = line[:cut].rstrip()
+        if len(sliced) <= limit:
+            return sliced
+    if len(line) <= limit:
+        return line
+    return line[: limit - 1].rstrip() + "…"
+
+
+def detect_invariant_quotes(facts: RepoFacts) -> Signal | None:
+    if not facts.invariant_quotes:
+        return None
+    # Dedupe by line, preserving the first SHA.
+    seen: dict[str, str] = {}
+    for sha, line in facts.invariant_quotes:
+        if line not in seen:
+            seen[line] = sha
+    total = len(seen)
+    quotes = list(seen.items())[:_INVARIANT_BULLETS]
+    bullets = [
+        f"  > {_first_sentence(line, _INVARIANT_BULLET_LEN)}  ({_short(sha)})"
+        for line, sha in quotes
+    ]
+    if total > _INVARIANT_BULLETS:
+        bullets.append(f"  > …and {total - _INVARIANT_BULLETS} more in this file's history.")
+    rendered = "\n".join(bullets)
+    severity = 3 if total >= 2 else 2
+    # Look up the most recent invariant-bearing commit and decay severity by age.
+    quote_shas = {sha for _, sha in seen.items()}
+    quote_commits = [c for c in facts.commits if c.sha in quote_shas]
+    age_phrase = ""
+    if quote_commits:
+        days = _days_since(max(c.authored_at for c in quote_commits))
+        severity = _decay_severity(severity, days)
+        age_phrase = f" (most recent: {_age_phrase(days)})"
+    evidence_shas: list[str] = []
+    seen_shas: set[str] = set()
+    for _, sha in quotes:
+        short = _short(sha)
+        if short not in seen_shas:
+            seen_shas.add(short)
+            evidence_shas.append(short)
+    return Signal(
+        kind=SignalKind.INVARIANT_QUOTE,
+        severity=severity,
+        headline=(
+            f"{total} invariant{'s' if total != 1 else ''} stated by past authors"
+            + age_phrase
+        ),
+        detail="Past authors used cautionary language in commit messages:\n" + rendered,
+        evidence=tuple(evidence_shas),
+    )
+
+
+_DETECTORS = (
+    detect_revert_chain,
+    detect_incident_history,
+    detect_invariant_quotes,
+    detect_ghost_keeper,
+    detect_coupling,
+    detect_high_churn,
+    detect_silence,
+    detect_newborn,
+)
+
+
+def all_signals(facts: RepoFacts) -> list[Signal]:
+    """Run every detector and return signals sorted by severity (loudest first).
+
+    NEWBORN is suppressed when any other signal fires: it's a "we don't have
+    enough history" hedge that becomes contradictory when the file has already
+    surfaced real flags.
+    """
+    out: list[Signal] = []
+    for detector in _DETECTORS:
+        signal = detector(facts)
+        if signal is not None:
+            out.append(signal)
+    if any(s.kind is not SignalKind.NEWBORN for s in out):
+        out = [s for s in out if s.kind is not SignalKind.NEWBORN]
+    out.sort(key=lambda s: (-s.severity, s.kind.value))
+    return out
+
+
+__all__ = [
+    "Signal",
+    "SignalKind",
+    "all_signals",
+    "detect_coupling",
+    "detect_ghost_keeper",
+    "detect_high_churn",
+    "detect_incident_history",
+    "detect_invariant_quotes",
+    "detect_newborn",
+    "detect_revert_chain",
+    "detect_silence",
+]
+
+
+def __dir__() -> Sequence[str]:
+    return __all__

whycode/templates/github-workflow.yml

@@ -0,0 +1,42 @@
+# Risk-gates pull requests with WhyCode.
+#
+# On every PR this workflow computes the Risk Card for each changed file
+# (vs the PR base) and:
+#   - prints a risk-ranked table to the job log
+#   - exits non-zero if any file reaches the band you choose, blocking merge
+#
+# Tune `--fail-on` to taste:
+#   handle   block PRs touching files >= HANDLE WITH CARE (>= 75)
+#   history  block PRs touching files >= READ HISTORY FIRST (>= 50)
+#   look     stricter; block at >= 25 (probably too noisy)
+#
+# Remove `--fail-on` entirely to make WhyCode advisory only.
+name: WhyCode
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  whycode:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out PR
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # WhyCode needs full history
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install WhyCode
+        run: pip install git+https://github.com/fangshuor/WhyCode.git
+
+      - name: Risk-rank files in this PR
+        run: whycode diff --base origin/${{ github.base_ref }} --fail-on history

whycode/templates/pre-commit

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# WhyCode pre-commit risk gate.
+# Blocks commits that touch HANDLE WITH CARE files (score >= 75) without
+# acknowledging them. Tune `--fail-on` if this is too strict for you.
+#
+# Bypass (rare): commit with `git commit --no-verify` — but think twice.
+exec whycode diff --staged --fail-on handle