whycode-cli 0.2.4__tar.gz → 0.2.6__tar.gz

{whycode_cli-0.2.4/src/whycode_cli.egg-info → whycode_cli-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.2.4
+Version: 0.2.6
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT
@@ -87,8 +87,9 @@ Requires Python 3.11+.
 ```bash
 cd /path/to/your/repo
 
+whycode tour                        # the one command to run first
 whycode init                        # one-command setup: CI workflow + pre-commit gate
-whycode highlights                  # first-run treasure map: top decisions + incidents
+whycode highlights                  # repo-wide 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>     # risk as of a past commit

{whycode_cli-0.2.4 → whycode_cli-0.2.6}/README.md

@@ -59,8 +59,9 @@ Requires Python 3.11+.
 ```bash
 cd /path/to/your/repo
 
+whycode tour                        # the one command to run first
 whycode init                        # one-command setup: CI workflow + pre-commit gate
-whycode highlights                  # first-run treasure map: top decisions + incidents
+whycode highlights                  # repo-wide 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>     # risk as of a past commit

{whycode_cli-0.2.4 → whycode_cli-0.2.6}/pyproject.toml

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

{whycode_cli-0.2.4 → whycode_cli-0.2.6}/src/whycode/__init__.py

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

{whycode_cli-0.2.4 → whycode_cli-0.2.6}/src/whycode/cli.py

@@ -2,6 +2,7 @@
 
 Commands
 --------
+- ``whycode tour``              — first-run walkthrough: highlights + top risk + MCP setup.
 - ``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.
@@ -238,6 +239,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",
@@ -305,6 +314,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:
@@ -806,6 +846,131 @@ def _install_template(
     return f"[green]wrote:[/green]   {rel_label}"
 
 
+_MCP_SNIPPET = '''    {
+      "mcpServers": {
+        "whycode": {"command": "whycode", "args": ["mcp"]}
+      }
+    }'''
+
+
+@app.command()
+def tour(
+    repo: Path = typer.Option(Path("."), "--repo", help="Path inside the repo."),
+) -> None:
+    """First-run walkthrough: highlights + top risky files + MCP setup snippet.
+
+    The single command to run after installing WhyCode. Skips straight to
+    the most concrete things in the repo (verbatim invariants and
+    incident-flagged commits) and ends with the one snippet you'll need to
+    wire WhyCode into an MCP-aware editor.
+    """
+    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
+
+    console.print("[bold]Welcome to WhyCode.[/bold]")
+    console.print(f"[dim]Reading the history of {repo_root.name}…[/dim]\n")
+
+    # Section 1 — invariants and incidents (cheap; one git log call).
+    with console.status("Looking for stated decisions…", spinner="dots"):
+        commits = gf.all_commits(repo_root, max_count=2000)
+    if not commits:
+        console.print("[yellow]This repo has no commits yet — nothing to learn from.[/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)
+    invariants_top = [
+        (line, sha_to_commit[sha])
+        for line, sha in seen_lines.items()
+        if sha in sha_to_commit
+    ][:3]
+    incidents_top = gf.find_incidents(commits)[:3]
+
+    if invariants_top or incidents_top:
+        console.print("[bold yellow]Decisions and incidents[/bold yellow]")
+        for line, c in invariants_top:
+            console.print(f"  [italic]{line}[/italic]")
+            console.print(
+                f"  [dim]{c.sha[:7]}  {c.authored_at.date()}  {c.author_name}[/dim]\n"
+            )
+        for c in incidents_top:
+            subj = c.subject if len(c.subject) <= 70 else c.subject[:69] + "…"
+            console.print(f"  [red]{subj}[/red]")
+            console.print(
+                f"  [dim]{c.sha[:7]}  {c.authored_at.date()}  {c.author_name}[/dim]\n"
+            )
+    else:
+        console.print(
+            "[dim]No headline decisions or incidents in recent history.[/dim]"
+        )
+        console.print(
+            "[dim]Commit messages may be too terse — describing 'why' in commit "
+            "bodies (or using `hotfix:` / `BREAKING CHANGE:` prefixes) makes WhyCode "
+            "much more useful.[/dim]\n"
+        )
+
+    # Section 2 — top risky files. Slimmer scan: 100 files, depth 50 commits.
+    raw = gf.run_git(repo_root, "ls-files")
+    patterns = ign.effective_patterns(repo_root)
+    paths = [p for p in raw.splitlines() if p.strip() and not ign.is_ignored(p, patterns)][
+        :100
+    ]
+    cards: list[rc.RiskCard] = []
+    if paths:
+        with console.status(
+            f"Risk-ranking {len(paths)} files (slim scan)…", spinner="dots"
+        ):
+            for p in paths:
+                try:
+                    card = rc.build(repo_root, p, max_commits=50)
+                except gf.GitError:
+                    continue
+                useful = [s for s in card.signals if s.kind is not sig.SignalKind.NEWBORN]
+                if useful:
+                    cards.append(card)
+        cards.sort(key=lambda c: -c.score.value)
+
+    if cards:
+        console.print("[bold red]Top 3 risky files[/bold red]")
+        for top in cards[:3]:
+            console.print(
+                f"  [bold]{top.score.value:>3}[/bold]  "
+                f"{top.score.band.value:<20}  [cyan]{top.path}[/cyan]"
+            )
+            console.print(f"       [dim]{top.signals[0].headline}[/dim]")
+        console.print()
+
+    # Section 3 — MCP setup snippet (vendor-neutral phrasing).
+    console.print("[bold magenta]Wire WhyCode into your AI editor[/bold magenta]")
+    console.print(
+        "  WhyCode ships an MCP server. Any MCP-aware editor or assistant\n"
+        "  can call it — just add this snippet to your editor's MCP config:\n"
+    )
+    console.print(_MCP_SNIPPET)
+    console.print(
+        "\n  [dim](See your editor's docs for the exact config-file location.)[/dim]\n"
+    )
+
+    # Section 4 — what to do next.
+    console.print("[bold]Next:[/bold]")
+    if cards:
+        console.print(
+            f"  [dim]·[/dim] [bold]whycode why {cards[0].path}[/bold]   the full Risk Card"
+        )
+    console.print(
+        "  [dim]·[/dim] [bold]whycode init[/bold]                     install CI + pre-commit"
+    )
+    console.print(
+        "  [dim]·[/dim] [bold]whycode highlights[/bold]                more invariants and incidents"
+    )
+
+
 @app.command()
 def init(
     force: bool = typer.Option(

whycode_cli-0.2.6/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.4 → whycode_cli-0.2.6/src/whycode_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whycode-cli
-Version: 0.2.4
+Version: 0.2.6
 Summary: Tells you what to be afraid of before you touch a file.
 Author: Kevin
 License-Expression: MIT
@@ -87,8 +87,9 @@ Requires Python 3.11+.
 ```bash
 cd /path/to/your/repo
 
+whycode tour                        # the one command to run first
 whycode init                        # one-command setup: CI workflow + pre-commit gate
-whycode highlights                  # first-run treasure map: top decisions + incidents
+whycode highlights                  # repo-wide 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>     # risk as of a past commit

{whycode_cli-0.2.4 → whycode_cli-0.2.6}/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(
@@ -556,3 +589,51 @@ def test_scan_lists_top_files(repo, days_ago) -> None:  # type: ignore[no-untype
     result = _invoke(repo.root, "scan", "--top", "3")
     assert result.exit_code == 0
     assert "a.py" in result.output
+
+
+def test_tour_runs_and_emits_all_sections(repo, days_ago) -> None:  # type: ignore[no-untyped-def]
+    repo.commit(
+        "compat: keep sync path",
+        {"a.py": "1"},
+        body="Do not switch to async — v1 clients break.",
+        when=days_ago(60),
+    )
+    repo.commit(
+        "hotfix: refund regression",
+        {"b.py": "1"},
+        body="See INC-447.",
+        when=days_ago(20),
+    )
+    sha = repo.commit("feat: A", {"a.py": "2"}, when=days_ago(40))
+    repo.revert(sha, when=days_ago(15))
+    result = _invoke(repo.root, "tour")
+    assert result.exit_code == 0
+    out = result.output
+    assert "Welcome to WhyCode" in out
+    assert "Decisions and incidents" in out
+    assert "Do not switch to async" in out
+    assert "hotfix: refund regression" in out
+    assert "Wire WhyCode into your AI editor" in out
+    # MCP snippet appears verbatim so users can copy-paste.
+    assert '"command": "whycode"' in out
+
+
+def test_tour_quiet_repo_explains_why(repo) -> None:  # type: ignore[no-untyped-def]
+    repo.commit("init", {"a.py": "1"})
+    result = _invoke(repo.root, "tour")
+    assert result.exit_code == 0
+    out = result.output
+    # MCP section appears regardless — most useful next step.
+    assert "Wire WhyCode into your AI editor" in out
+    # And the empty-state explanation should mention why nothing fires.
+    assert "terse" in out.lower() or "no headline" in out.lower()
+
+
+def test_tour_outside_repo_errors(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    cwd = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        result = runner.invoke(app, ["tour"], catch_exceptions=False)
+    finally:
+        os.chdir(cwd)
+    assert result.exit_code != 0

whycode_cli-0.2.4/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 }}