whycode-cli 0.2.1__py3-none-any.whl → 0.2.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.2.1"
+__version__ = "0.2.2"

whycode/cli.py

@@ -4,6 +4,8 @@ Commands
 --------
 - ``whycode why <path>``        — print the Risk Card for a single file.
 - ``whycode why <path> --at SHA`` — risk card as of a past commit.
+- ``whycode why <path> --mute KIND`` — locally suppress a noisy signal kind.
+- ``whycode highlights``        — repo-wide treasure map of decisions and incidents.
 - ``whycode diff [--base REF]`` — risk-rank files changed against a base ref.
 - ``whycode show <sha>``        — risk-flavored summary for one commit.
 - ``whycode timeline <path>``   — risk score evolution across the file's history.
@@ -29,6 +31,7 @@ from whycode import __version__
 from whycode import git_facts as gf
 from whycode import risk_card as rc
 from whycode import signals as sig
+from whycode import suppressions as supp
 
 app = typer.Typer(
     add_completion=False,
@@ -119,6 +122,20 @@ def why(
         "--at",
         help="Show the Risk Card as of this commit / ref (postmortem queries).",
     ),
+    mute: list[str] = typer.Option(
+        [],
+        "--mute",
+        help=(
+            "Suppress a signal kind for this path going forward "
+            "(stored in .whycode/suppressed.json). Accepts kind name or "
+            "unique prefix: incident, revert, ghost, coupling, silence, …"
+        ),
+    ),
+    no_mutes: bool = typer.Option(
+        False,
+        "--no-mutes",
+        help="Bypass the local suppression list — show all signals.",
+    ),
     max_commits: int | None = typer.Option(
         None, "--max-commits", help="Cap the number of commits scanned (debug)."
     ),
@@ -140,7 +157,31 @@ def why(
         except gf.GitError:
             err.print(f"[red]error:[/red] unknown commit / ref: {at!r}")
             raise typer.Exit(2) from None
-    card = rc.build(repo_root, rel, max_commits=max_commits, ref=resolved_ref)
+    if mute:
+        sl = supp.load(repo_root)
+        added: list[str] = []
+        for token in mute:
+            try:
+                kind = supp.resolve_kind(token)
+            except ValueError as exc:
+                err.print(f"[red]error:[/red] {exc}")
+                raise typer.Exit(2) from None
+            if sl.add(rel, kind):
+                added.append(kind.value)
+        if added:
+            supp.save(repo_root, sl)
+            if not json_out:
+                err.print(
+                    f"[dim]muted on {rel}: {', '.join(added)}  "
+                    f"(stored in .whycode/suppressed.json — edit to undo)[/dim]"
+                )
+    card = rc.build(
+        repo_root,
+        rel,
+        max_commits=max_commits,
+        ref=resolved_ref,
+        apply_suppressions=not no_mutes,
+    )
     if json_out:
         console.print_json(json.dumps(card.to_dict()))
         return
@@ -286,6 +327,136 @@ def diff(
             raise typer.Exit(1)
 
 
+@app.command()
+def highlights(
+    invariants: int = typer.Option(
+        5, "--invariants", help="How many invariant lines to surface."
+    ),
+    incidents: int = typer.Option(
+        5, "--incidents", help="How many incident commits to surface."
+    ),
+    max_commits: int | None = typer.Option(
+        None,
+        "--max-commits",
+        help="Cap on commits scanned (defaults to no cap; tune for very large repos).",
+    ),
+    repo: Path = typer.Option(Path("."), "--repo", help="Path inside the repo."),
+    json_out: bool = typer.Option(
+        False, "--json", help="Emit machine-readable JSON instead of a card."
+    ),
+) -> None:
+    """The first-run treasure map: top decisions and incidents across the repo.
+
+    Surfaces the highest-value commit-message lines (invariants stated by past
+    authors) and the most recent incident-flavoured commits — the things a
+    reader most wants to know about the codebase before touching anything.
+    """
+    try:
+        repo_root = gf.discover_repo_root(repo.resolve())
+    except gf.GitError as exc:
+        err.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(2) from exc
+
+    with console.status("Reading repo history…", spinner="dots"):
+        commits = gf.all_commits(repo_root, max_count=max_commits)
+    if not commits:
+        console.print("[yellow]no commits in this repo[/yellow]")
+        return
+
+    inv_pairs = gf.extract_invariant_quotes(commits)
+    sha_to_commit = {c.sha: c for c in commits}
+    seen_lines: dict[str, str] = {}
+    for sha, line in inv_pairs:
+        seen_lines.setdefault(line, sha)
+    inv_records: list[tuple[str, str, gf.Commit]] = []
+    for line, sha in seen_lines.items():
+        commit = sha_to_commit.get(sha)
+        if commit is None:
+            continue
+        inv_records.append((line, sha, commit))
+    inv_records.sort(key=lambda t: t[2].authored_at, reverse=True)
+    inv_records = inv_records[:invariants]
+
+    incident_records = gf.find_incidents(commits)[:incidents]
+
+    if json_out:
+        console.print_json(
+            json.dumps(
+                {
+                    "repo": str(repo_root),
+                    "scanned_commits": len(commits),
+                    "invariants": [
+                        {
+                            "sha": c.sha[:12],
+                            "subject": c.subject,
+                            "author": c.author_name,
+                            "authored_at": c.authored_at.isoformat(),
+                            "line": line,
+                        }
+                        for line, _, c in inv_records
+                    ],
+                    "incidents": [
+                        {
+                            "sha": c.sha[:12],
+                            "subject": c.subject,
+                            "author": c.author_name,
+                            "authored_at": c.authored_at.isoformat(),
+                        }
+                        for c in incident_records
+                    ],
+                }
+            )
+        )
+        return
+
+    console.print(
+        f"[bold]WhyCode highlights[/bold]   "
+        f"[dim]{len(commits)} commits scanned in this repo[/dim]\n"
+    )
+    if inv_records:
+        console.print(
+            f"[bold yellow]INVARIANTS[/bold yellow] "
+            f"[dim]({len(inv_records)} most recent stated by past authors)[/dim]"
+        )
+        for i, (line, sha, commit) in enumerate(inv_records, 1):
+            short = sha[:7]
+            date = str(commit.authored_at.date())
+            console.print(
+                f"  {i}. [dim]{short}  {date}  {commit.author_name}[/dim]"
+            )
+            console.print(f"     [italic]{line}[/italic]")
+        console.print()
+    else:
+        console.print(
+            "[dim]INVARIANTS: none found. The repo's commit bodies don't use "
+            "cautionary language like 'do not', 'must not', 'warning:', etc.[/dim]\n"
+        )
+
+    if incident_records:
+        console.print(
+            f"[bold red]INCIDENTS[/bold red] "
+            f"[dim]({len(incident_records)} most recent incident-flavoured commits)[/dim]"
+        )
+        for i, c in enumerate(incident_records, 1):
+            short = c.sha[:7]
+            date = str(c.authored_at.date())
+            subj = c.subject if len(c.subject) <= 70 else c.subject[:69] + "…"
+            console.print(
+                f"  {i}. [dim]{short}  {date}  {c.author_name}[/dim]\n"
+                f"     {subj}"
+            )
+        console.print()
+    else:
+        console.print(
+            "[dim]INCIDENTS: none found. No commit subject contains 'hotfix', "
+            "'incident', 'regression', etc.[/dim]\n"
+        )
+
+    console.print(
+        "[dim]→ whycode why <path>   to dig into the file behind any of these.[/dim]"
+    )
+
+
 def _sample_indices(total: int, max_samples: int) -> list[int]:
     """Pick at most ``max_samples`` indices spread across [0, total).
 

whycode/risk_card.py

@@ -18,6 +18,7 @@ from rich.text import Text
 
 from whycode import git_facts as gf
 from whycode import signals as sig
+from whycode import suppressions as supp
 from whycode.scorer import Band, Score, score
 
 if TYPE_CHECKING:
@@ -73,9 +74,20 @@ def build(
     *,
     max_commits: int | None = None,
     ref: str | None = None,
+    apply_suppressions: bool = True,
 ) -> RiskCard:
+    """Build a Risk Card.
+
+    By default, signals matching the local ``.whycode/suppressed.json`` list
+    are dropped — that file is the user's "this signal is wrong, hide it"
+    feedback. Pass ``apply_suppressions=False`` to bypass it (useful for
+    debug or auditing what was hidden).
+    """
     facts = gf.gather(repo_root, path, max_commits=max_commits, ref=ref)
     signals = sig.all_signals(facts)
+    if apply_suppressions:
+        suppressions = supp.load(repo_root)
+        signals = supp.filter_signals(signals, suppressions, path)
     s = score(signals)
     head = facts.commits[0] if facts.commits else None
     return RiskCard(

whycode/suppressions.py

@@ -0,0 +1,123 @@
+"""Local suppression list — the "this signal is wrong, hide it" feedback loop.
+
+Stored at ``<repo>/.whycode/suppressed.json``.  ``.whycode/`` is gitignored,
+so the list is per-developer and never travels with the repo.  This honours
+the privacy contract: no central DB, no telemetry, no cross-team sharing of
+"these signals are bogus" data.
+
+Schema (intentionally tiny — easy to hand-edit):
+
+    {
+      "suppressed": [
+        ["src/foo.py", "incident_history"],
+        ["src/bar.py", "ghost_keeper"]
+      ]
+    }
+
+Match is exact ``(path, kind)`` — no globs.  We can add patterns if real
+users ask for them; for now precision beats convenience.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from whycode.signals import SignalKind
+
+if TYPE_CHECKING:
+    from whycode.signals import Signal
+
+_FILENAME = "suppressed.json"
+_DIRNAME = ".whycode"
+
+
+@dataclass
+class SuppressionList:
+    entries: list[tuple[str, str]] = field(default_factory=list)
+
+    def is_suppressed(self, path: str, kind: SignalKind) -> bool:
+        return (path, kind.value) in self.entries
+
+    def add(self, path: str, kind: SignalKind) -> bool:
+        """Idempotent. Returns True if a new entry was added."""
+        pair = (path, kind.value)
+        if pair in self.entries:
+            return False
+        self.entries.append(pair)
+        return True
+
+    def __iter__(self) -> Iterator[tuple[str, str]]:
+        return iter(self.entries)
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+
+def _path(repo_root: Path) -> Path:
+    return repo_root / _DIRNAME / _FILENAME
+
+
+def load(repo_root: Path) -> SuppressionList:
+    """Return the suppression list for ``repo_root``. Empty if no file exists."""
+    target = _path(repo_root)
+    if not target.exists():
+        return SuppressionList()
+    try:
+        raw = json.loads(target.read_text())
+    except (OSError, json.JSONDecodeError):
+        # A corrupt file should not stop ``whycode why`` from running.
+        # Treat as empty and let the user see what happened on next save.
+        return SuppressionList()
+    items = raw.get("suppressed", [])
+    out: list[tuple[str, str]] = []
+    for item in items:
+        if isinstance(item, list) and len(item) == 2:
+            out.append((str(item[0]), str(item[1])))
+    return SuppressionList(entries=out)
+
+
+def save(repo_root: Path, sl: SuppressionList) -> None:
+    target = _path(repo_root)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"suppressed": [list(pair) for pair in sl.entries]}
+    target.write_text(json.dumps(payload, indent=2) + "\n")
+
+
+def resolve_kind(token: str) -> SignalKind:
+    """Resolve a user-supplied kind name (or unique prefix) to a SignalKind.
+
+    Raises ValueError when the token is unknown or matches multiple kinds.
+    """
+    needle = token.lower().replace("-", "_").strip()
+    if not needle:
+        raise ValueError("empty signal kind")
+    matches = [k for k in SignalKind if needle in k.value]
+    if not matches:
+        raise ValueError(
+            f"unknown signal kind: {token!r}. "
+            f"Known: {', '.join(k.value for k in SignalKind)}"
+        )
+    if len(matches) > 1:
+        names = ", ".join(k.value for k in matches)
+        raise ValueError(f"ambiguous: {token!r} matches multiple kinds: {names}")
+    return matches[0]
+
+
+def filter_signals(
+    signals: Iterable[Signal], suppressions: SuppressionList, path: str
+) -> list[Signal]:
+    """Drop signals whose ``(path, kind)`` is in the suppression list."""
+    return [s for s in signals if not suppressions.is_suppressed(path, s.kind)]
+
+
+__all__ = [
+    "SuppressionList",
+    "filter_signals",
+    "load",
+    "resolve_kind",
+    "save",
+]

{whycode_cli-0.2.1.dist-info → whycode_cli-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.2.1
+Version: 0.2.2
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT
@@ -88,9 +88,11 @@ Requires Python 3.11+.
 cd /path/to/your/repo
 
 whycode init                        # one-command setup: CI workflow + pre-commit gate
+whycode highlights                  # first-run treasure map: top decisions + incidents
 whycode why src/some/file.py        # the Risk Card for one file
 whycode why src/some/file.py -b     # one-line summary (for triage / scripts)
-whycode why src/some/file.py --at <sha>  # what did this file's risk look like as of <sha>?
+whycode why src/some/file.py --at <sha>     # risk as of a past commit
+whycode why src/some/file.py --mute <kind>  # local "this signal is wrong, hide it" feedback
 whycode diff                        # rank everything you changed vs origin/main
 whycode diff --staged               # ditto, for files staged for commit
 whycode diff --fail-on history      # CI gate: exit 1 if any file is ≥ READ HISTORY FIRST

{whycode_cli-0.2.1.dist-info → whycode_cli-0.2.2.dist-info}/RECORD

@@ -1,17 +1,18 @@
-whycode/__init__.py,sha256=jJnNmctGBHLWNIpQ6nSfkbHd9x-7trhSglEmlsrULME,96
+whycode/__init__.py,sha256=jKEx86xuF42y5emGUY2ejvZ2Ro2LMyRzCr1520lsWKo,96
 whycode/__main__.py,sha256=dqAk6746YpuM-FTIH4TBOULegGc5WweojiZjce0VYgQ,105
-whycode/cli.py,sha256=9e2lUpAFamzmwS1ixtk8TxW49gDpXlBq0oQ5r9I5mR4,24391
+whycode/cli.py,sha256=vs1O8riLYKbW3qGKOLx_bZuJi8pN_t5P6Xx0l8r-drc,30600
 whycode/git_facts.py,sha256=qn4ctE6RkkGa5sFq9ZYjT7UlKIcZnmjSQkOE8NkgvcY,15177
 whycode/mcp_server.py,sha256=56csOHSP90Zk59-_Puvk4WTSlCJ6xQAm-K10b_qmyAQ,7105
-whycode/risk_card.py,sha256=IuQTfSeKwjC6RCmbXXT012xEODESonRBmZKcfvDwAOY,6479
+whycode/risk_card.py,sha256=iIk4MkQQrlnj782dxdfoogUcByunI5j6y8vUnuhByAA,6996
 whycode/scorer.py,sha256=4pBejunfxzYhGUzMeL8uGEMQzC6DWiqwcTeMdo3eras,1444
 whycode/signals.py,sha256=14KziRolXvhmOnMnluXpPPInoBRO5uDu0tm024EYik0,13066
+whycode/suppressions.py,sha256=1lKSs-kCgpnJbcxozcgiSP8ZAfjEDMHXuM3sw4FaY78,3836
 whycode/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 whycode/templates/github-workflow.yml,sha256=yy87tbYKCexNYFso4e4OxGAdIIYOLn2cVxEt-FzP2oo,1095
 whycode/templates/pre-commit,sha256=IhU11CvoDwqRAAsvHwUo-BwaNbdgy1cpXc54Z_phrmQ,316
-whycode_cli-0.2.1.dist-info/licenses/LICENSE,sha256=U6LN5qg5kJXSJf7KFPm9KJhmiGn3qK_GsTVWXdt1DFA,1062
-whycode_cli-0.2.1.dist-info/METADATA,sha256=W9iwebvjq96Ry9P-6I3NDwA1TPOcu403hDVxwVT1-aM,9100
-whycode_cli-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-whycode_cli-0.2.1.dist-info/entry_points.txt,sha256=xrNWc4CQn3ZhQFJxsGIPiTqpN19K4pRpgaj6qGaEzSQ,44
-whycode_cli-0.2.1.dist-info/top_level.txt,sha256=6yIL5rxW-4DbARHQYrPlGQVqKddZ88sjvmNosDh1w3A,8
-whycode_cli-0.2.1.dist-info/RECORD,,
+whycode_cli-0.2.2.dist-info/licenses/LICENSE,sha256=U6LN5qg5kJXSJf7KFPm9KJhmiGn3qK_GsTVWXdt1DFA,1062
+whycode_cli-0.2.2.dist-info/METADATA,sha256=ghJkHcW2uJmn8Jb1SoEo9zBlY7slOmPx4fEO_Pl7mm0,9260
+whycode_cli-0.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+whycode_cli-0.2.2.dist-info/entry_points.txt,sha256=xrNWc4CQn3ZhQFJxsGIPiTqpN19K4pRpgaj6qGaEzSQ,44
+whycode_cli-0.2.2.dist-info/top_level.txt,sha256=6yIL5rxW-4DbARHQYrPlGQVqKddZ88sjvmNosDh1w3A,8
+whycode_cli-0.2.2.dist-info/RECORD,,