whycode-cli 0.2.3__tar.gz → 0.2.5__tar.gz

{whycode_cli-0.2.3/src/whycode_cli.egg-info → whycode_cli-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.2.3
+Version: 0.2.5
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT

{whycode_cli-0.2.3 → whycode_cli-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "whycode-cli"
-version = "0.2.3"
+version = "0.2.5"
 description = "Tells you what to be afraid of before you touch a file."
 readme = "README.md"
 license = "MIT"

{whycode_cli-0.2.3 → whycode_cli-0.2.5}/src/whycode/__init__.py

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

{whycode_cli-0.2.3 → whycode_cli-0.2.5}/src/whycode/cli.py

@@ -71,12 +71,29 @@ def _path_is_known_to_git(repo_root: Path, rel: str) -> bool:
     if gf.is_tracked(repo_root, rel):
         return True
     try:
-        out = gf._run_git(repo_root, "log", "--oneline", "-1", "--all", "--", rel)
+        out = gf.run_git(repo_root, "log", "--oneline", "-1", "--all", "--", rel)
     except gf.GitError:
         return False
     return bool(out.strip())
 
 
+def _require_tracked(path_arg: str) -> tuple[Path, str]:
+    """Resolve ``path_arg`` to ``(repo_root, rel)`` or exit with a friendly warning.
+
+    Used by every command that takes a path argument and needs git history
+    to be useful (``why``, ``timeline``, ``honest``). Combines the two earlier
+    helpers so callers don't repeat the warn-and-exit boilerplate.
+    """
+    repo_root, rel = _resolve_repo_and_path(path_arg)
+    if not _path_is_known_to_git(repo_root, rel):
+        err.print(
+            f"[yellow]warning:[/yellow] [bold]{rel}[/bold] is not tracked by git "
+            f"and has no history in this repo. Nothing to learn from."
+        )
+        raise typer.Exit(1)
+    return repo_root, rel
+
+
 # --- shared: band threshold parsing ----------------------------------------
 
 _BAND_THRESHOLDS_BY_KEY: dict[str, int] = {
@@ -142,17 +159,11 @@ def why(
     ),
 ) -> None:
     """Print the Risk Card for ``path``."""
-    repo_root, rel = _resolve_repo_and_path(path)
-    if not _path_is_known_to_git(repo_root, rel):
-        err.print(
-            f"[yellow]warning:[/yellow] [bold]{rel}[/bold] is not tracked by git "
-            f"and has no history in this repo. Nothing to learn from."
-        )
-        raise typer.Exit(1)
+    repo_root, rel = _require_tracked(path)
     resolved_ref: str | None = None
     if at is not None:
         try:
-            resolved_ref = gf._run_git(
+            resolved_ref = gf.run_git(
                 repo_root, "rev-parse", "--verify", f"{at}^{{commit}}"
             ).strip()
         except gf.GitError:
@@ -202,7 +213,7 @@ def _resolve_base_ref(repo_root: Path, requested: str | None) -> str:
     candidates = ("origin/main", "origin/master", "main", "master", "HEAD~1")
     for ref in candidates:
         try:
-            gf._run_git(repo_root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+            gf.run_git(repo_root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
             return ref
         except gf.GitError:
             continue
@@ -227,6 +238,14 @@ def diff(
     json_out: bool = typer.Option(
         False, "--json", help="Emit machine-readable JSON instead of a table."
     ),
+    markdown: bool = typer.Option(
+        False,
+        "--markdown",
+        help=(
+            "Emit GitHub-flavoured markdown suitable for posting as a PR comment. "
+            "Pipe into a workflow step that calls `gh pr comment`."
+        ),
+    ),
     fail_on: str | None = typer.Option(
         None,
         "--fail-on",
@@ -241,13 +260,13 @@ def diff(
     try:
         repo_root = gf.discover_repo_root(repo.resolve())
         if staged:
-            raw = gf._run_git(
+            raw = gf.run_git(
                 repo_root, "diff", "--cached", "--name-only", "--diff-filter=ACMR"
             )
             actual_base = "(staged changes)"
         else:
             actual_base = _resolve_base_ref(repo_root, base)
-            raw = gf._run_git(repo_root, "diff", "--name-only", f"{actual_base}...HEAD")
+            raw = gf.run_git(repo_root, "diff", "--name-only", f"{actual_base}...HEAD")
     except gf.GitError as exc:
         err.print(f"[red]error:[/red] {exc}")
         raise typer.Exit(2) from exc
@@ -294,6 +313,37 @@ def diff(
 
     flagged = [c for c in cards if _is_actionable(c)]
     quiet_n = len(cards) - len(flagged)
+    scope_md = "files staged for commit" if staged else f"files changed vs `{actual_base}`"
+    if markdown:
+        # Stable marker so a follow-up workflow step can find-and-update the
+        # same comment on subsequent pushes instead of stacking new ones.
+        print("<!-- whycode-comment -->")
+        print("## WhyCode risk briefing")
+        print()
+        print(f"**{len(files)} {scope_md}**")
+        print()
+        if not flagged:
+            print("Nothing flagged. Read the diff anyway.")
+        else:
+            print("| Score | Band | File | Top signal |")
+            print("| ----: | ---- | ---- | ---------- |")
+            for c in flagged:
+                top_signal = c.signals[0].headline.replace("|", "\\|")
+                print(
+                    f"| {c.score.value} | {c.score.band.value} | "
+                    f"`{c.path}` | {top_signal} |"
+                )
+            if quiet_n:
+                print()
+                print(f"_+ {quiet_n} file(s) changed with no flags._")
+            print()
+            print(
+                "_Run `whycode why <path>` for the full Risk Card on any of the above._"
+            )
+        if threshold is not None and any(c.score.value >= threshold for c in cards):
+            raise typer.Exit(1)
+        return
+
     scope = "staged for commit" if staged else f"changed vs {actual_base}"
     console.print(f"[bold]{len(files)} file(s) {scope}[/bold]")
     if not flagged:
@@ -483,13 +533,7 @@ def timeline(
     ),
 ) -> None:
     """Show how this file's risk score evolved over its history."""
-    repo_root, rel = _resolve_repo_and_path(path)
-    if not _path_is_known_to_git(repo_root, rel):
-        err.print(
-            f"[yellow]warning:[/yellow] [bold]{rel}[/bold] is not tracked by git "
-            f"and has no history in this repo."
-        )
-        raise typer.Exit(1)
+    repo_root, rel = _require_tracked(path)
 
     commits = gf.commits_for_path(repo_root, rel)
     if not commits:
@@ -588,7 +632,7 @@ def scan(
         err.print(f"[red]error:[/red] {exc}")
         raise typer.Exit(2) from exc
 
-    raw = gf._run_git(repo_root, "ls-files")
+    raw = gf.run_git(repo_root, "ls-files")
     all_paths = [line for line in raw.splitlines() if line.strip()]
     patterns = () if no_ignore else ign.effective_patterns(repo_root)
     paths = [p for p in all_paths if not ign.is_ignored(p, patterns)][:sample]
@@ -648,13 +692,7 @@ def honest(
     Use when the Risk Card's first-sentence truncation is hiding important
     context — e.g., a commit whose constraint is stated across two lines.
     """
-    repo_root, rel = _resolve_repo_and_path(path)
-    if not _path_is_known_to_git(repo_root, rel):
-        err.print(
-            f"[yellow]warning:[/yellow] [bold]{rel}[/bold] is not tracked by git "
-            f"and has no history in this repo."
-        )
-        raise typer.Exit(1)
+    repo_root, rel = _require_tracked(path)
     facts = gf.gather(repo_root, rel)
     if not facts.invariant_quotes:
         if json_out:
@@ -716,24 +754,18 @@ def show(
     """Risk-flavored summary for a single commit: classification + per-file risk."""
     try:
         repo_root = gf.discover_repo_root(repo.resolve())
-        full_sha = gf._run_git(repo_root, "rev-parse", "--verify", f"{sha}^{{commit}}").strip()
     except gf.GitError as exc:
         err.print(f"[red]error:[/red] {exc}")
         raise typer.Exit(2) from exc
 
-    raw = gf._run_git(
-        repo_root, "log", "-1", "--no-merges", f"--pretty=format:{gf._log_format()}", full_sha
-    )
-    commits = gf._parse_log_records(raw)
-    if not commits:
-        err.print(f"[red]error:[/red] could not read commit {full_sha}")
+    commit = gf.read_commit(repo_root, sha)
+    if commit is None:
+        err.print(f"[red]error:[/red] could not read commit {sha!r}")
         raise typer.Exit(2)
-    commit = commits[0]
+    full_sha = commit.sha
 
-    is_incident = bool(
-        gf._INCIDENT_RE.search(commit.subject + "\n" + commit.body)
-        or gf._BREAKING_CC_RE.search(commit.subject)
-    )
+    classification = gf.classify_commit(commit)
+    is_incident = classification.incident_flavoured
     invariants = gf.extract_invariant_quotes([commit])
     file_changes = gf.files_changed_in(repo_root, full_sha)
 
@@ -768,14 +800,14 @@ def show(
     )
     console.print(f"  {commit.subject}")
     console.print()
-    classification = []
+    badges: list[str] = []
     if is_incident:
-        classification.append("[bold red]incident-flavored[/bold red]")
+        badges.append("[bold red]incident-flavored[/bold red]")
     if invariants:
-        classification.append(f"[yellow]states {len(invariants)} invariant(s)[/yellow]")
-    if not classification:
-        classification.append("[dim]no special classification[/dim]")
-    console.print("  " + "   ".join(classification))
+        badges.append(f"[yellow]states {len(invariants)} invariant(s)[/yellow]")
+    if not badges:
+        badges.append("[dim]no special classification[/dim]")
+    console.print("  " + "   ".join(badges))
     console.print(f"  [dim]{len(file_changes)} files changed[/dim]")
 
     if not cards:

{whycode_cli-0.2.3 → whycode_cli-0.2.5}/src/whycode/git_facts.py

@@ -129,8 +129,13 @@ class GitError(RuntimeError):
     """Raised when a git invocation fails or produces unexpected output."""
 
 
-def _run_git(repo_root: Path, *args: str) -> str:
-    """Invoke git, return stdout. Raises GitError on non-zero exit."""
+def run_git(repo_root: Path, *args: str) -> str:
+    """Invoke ``git -C <repo_root> <args>`` and return stdout.
+
+    Public API: callers (CLI, MCP server) use this to run git commands
+    that aren't already wrapped in a higher-level helper here. Raises
+    :class:`GitError` on non-zero exit or when ``git`` itself is missing.
+    """
     cmd = ["git", "-C", str(repo_root), *args]
     try:
         proc = subprocess.run(
@@ -150,6 +155,10 @@ def _run_git(repo_root: Path, *args: str) -> str:
     return proc.stdout
 
 
+# Back-compat alias. Prefer ``run_git`` in new code.
+_run_git = run_git
+
+
 def discover_repo_root(start: Path) -> Path:
     """Find the enclosing git repo root for ``start``."""
     out = _run_git(start, "rev-parse", "--show-toplevel").strip()
@@ -240,6 +249,25 @@ def all_commits(repo_root: Path, *, max_count: int | None = None) -> list[Commit
     return _parse_log_records(raw)
 
 
+def read_commit(repo_root: Path, ref: str) -> Commit | None:
+    """Resolve ``ref`` (SHA, tag, branch, ``HEAD~3`` …) to a single ``Commit``.
+
+    Returns ``None`` when the ref doesn't exist or doesn't resolve to a
+    commit. Used by ``whycode show <sha>`` and similar single-commit views.
+    """
+    try:
+        full_sha = run_git(
+            repo_root, "rev-parse", "--verify", f"{ref}^{{commit}}"
+        ).strip()
+    except GitError:
+        return None
+    raw = run_git(
+        repo_root, "log", "-1", "--no-merges", f"--pretty=format:{_log_format()}", full_sha
+    )
+    parsed = _parse_log_records(raw)
+    return parsed[0] if parsed else None
+
+
 def files_changed_in(repo_root: Path, sha: str) -> list[FileChange]:
     """Return the list of files (with diffstat) changed in ``sha``."""
     raw = _run_git(
@@ -359,6 +387,26 @@ def find_incidents(commits: Sequence[Commit]) -> list[Commit]:
     return out
 
 
+@dataclass(frozen=True)
+class CommitClassification:
+    """Light-weight summary of what kind of work a single commit represents."""
+
+    incident_flavoured: bool
+    invariant_count: int
+
+
+def classify_commit(commit: Commit) -> CommitClassification:
+    """Classify a single commit by reusing the same rules ``find_incidents`` and
+    ``extract_invariant_quotes`` apply to a list. Public API for ``whycode show``
+    and any other surface that wants a single-commit verdict without
+    re-implementing the regex ladder.
+    """
+    return CommitClassification(
+        incident_flavoured=bool(find_incidents([commit])),
+        invariant_count=len(extract_invariant_quotes([commit])),
+    )
+
+
 # Straight, backtick, and the four common Unicode "smart" quote code points.
 # We build the string from chr() calls because ruff's RUF001 ambiguous-char
 # check rejects the literal Unicode quotes inline.

whycode_cli-0.2.5/src/whycode/templates/github-workflow.yml

@@ -0,0 +1,64 @@
+# Risk-rank pull requests with WhyCode.
+#
+# On every PR this workflow:
+#   1. Computes the Risk Card for each changed file (vs the PR base)
+#   2. Prints a risk-ranked table to the job log
+#   3. Posts (or updates) a single PR comment with the same table
+#
+# Advisory by default — humans decide. To turn it into a hard gate that
+# blocks merging, append `--fail-on <band>` to the diff line:
+#   handle    block at HANDLE WITH CARE   (score >= 75)
+#   history   block at READ HISTORY FIRST (score >= 50)
+#   look      stricter — block at >= 25
+name: WhyCode
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write  # required to post / update the PR comment
+
+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 whycode-cli
+
+      - name: Risk-rank files in this PR (job log)
+        run: whycode diff --base origin/${{ github.base_ref }}
+
+      - name: Build PR comment body
+        run: whycode diff --base origin/${{ github.base_ref }} --markdown > whycode-comment.md
+
+      - name: Post or update the PR comment
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          BODY=$(cat whycode-comment.md)
+          # Find any existing comment we previously posted (identified by the
+          # hidden HTML marker WhyCode emits at the top of the message).
+          EXISTING=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+            --jq 'map(select(.body | contains("<!-- whycode-comment -->"))) | .[0].id // empty')
+          if [ -n "$EXISTING" ]; then
+            gh api -X PATCH "repos/${REPO}/issues/comments/${EXISTING}" \
+              -f body="$BODY" > /dev/null
+          else
+            gh api -X POST "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+              -f body="$BODY" > /dev/null
+          fi

{whycode_cli-0.2.3 → whycode_cli-0.2.5/src/whycode_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.2.3
+Version: 0.2.5
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT

{whycode_cli-0.2.3 → whycode_cli-0.2.5}/tests/test_cli.py

@@ -508,6 +508,39 @@ def test_scan_no_ignore_brings_them_back(repo, days_ago) -> None:  # type: ignor
     assert "CHANGELOG" in permissive_run.output or "src/app.py" in permissive_run.output
 
 
+def test_diff_markdown_output(repo, days_ago) -> None:  # type: ignore[no-untyped-def]
+    repo.commit("init", {"refund.py": "0"}, when=days_ago(120))
+    sha = repo.commit("feat: refund flow", {"refund.py": "1"}, when=days_ago(60))
+    repo.revert(sha, when=days_ago(50))
+    repo.commit(
+        "hotfix: regression",
+        {"refund.py": "2"},
+        body="incident #INC-42",
+        when=days_ago(10),
+    )
+    result = _invoke(repo.root, "diff", "--base", "HEAD~3", "--markdown")
+    assert result.exit_code == 0
+    out = result.output
+    # Hidden marker so the workflow can find-and-update its prior comment.
+    assert "<!-- whycode-comment -->" in out
+    # Markdown table syntax.
+    assert "| Score | Band |" in out
+    assert "| ----: |" in out
+    # File path appears as inline code.
+    assert "`refund.py`" in out
+
+
+def test_diff_markdown_quiet_repo(repo, days_ago) -> None:  # type: ignore[no-untyped-def]
+    repo.commit("init", {"a.py": "1"}, when=days_ago(40))
+    repo.commit("docs: tweak", {"a.py": "2"}, when=days_ago(20))
+    result = _invoke(repo.root, "diff", "--base", "HEAD~1", "--markdown")
+    assert result.exit_code == 0
+    out = result.output
+    assert "<!-- whycode-comment -->" in out
+    # No flagged files → friendly note instead of an empty table.
+    assert "Nothing flagged" in out
+
+
 def test_scan_respects_user_whycodeignore(repo, days_ago) -> None:  # type: ignore[no-untyped-def]
     (repo.root / ".whycodeignore").write_text("internal/legacy.py\n")
     sha = repo.commit(

whycode_cli-0.2.3/src/whycode/templates/github-workflow.yml

@@ -1,40 +0,0 @@
-# Risk-rank 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.
-# Advisory by default — humans decide.
-#
-# To turn it into a hard gate that blocks merging, append `--fail-on <band>`
-# to the `whycode diff` line below:
-#   handle    block at HANDLE WITH CARE   (score >= 75)
-#   history   block at READ HISTORY FIRST (score >= 50)
-#   look      stricter — block at >= 25
-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 whycode-cli
-
-      - name: Risk-rank files in this PR
-        run: whycode diff --base origin/${{ github.base_ref }}