whygit 0.1.0__py3-none-any.whl

whygit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

whygit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

whygit/cli.py

@@ -0,0 +1,109 @@
+"""Command line front end: whygit, whygit status, whygit explain, whygit mcp."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .engine import PathNotFound, diagnose, explain_error, explain_state
+from .render import Style, render_diagnosis, render_explanation, render_state, want_color
+
+EPILOG = """examples:
+  whygit                          explain what's going on in this repository
+  whygit status                   plain summary: branch, upstream, changes
+  whygit explain "fatal: refusing to merge unrelated histories"
+  git push 2>&1 | whygit explain -
+  whygit mcp                      run as an MCP server (for Claude Code, Cursor, Claude Desktop)
+
+whygit only reads your repository. It never runs the fixes it suggests."""
+
+
+def _common(p: argparse.ArgumentParser, suppress: bool) -> None:
+    d = argparse.SUPPRESS if suppress else None
+    p.add_argument(
+        "--path", "-C", default=d if suppress else ".", help="repository folder to look at (default: current folder)"
+    )
+    p.add_argument("--json", action="store_true", default=d if suppress else False, help="print JSON instead of text")
+    p.add_argument("--no-color", action="store_true", default=d if suppress else False, help="never use colour")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="whygit",
+        description="Explains what state your Git repository is in and how to fix it, in plain English.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"whygit {__version__}")
+    _common(parser, suppress=False)
+    sub = parser.add_subparsers(dest="command", metavar="command")
+    p = sub.add_parser("diagnose", help="list problems, most urgent first (the default)")
+    _common(p, suppress=True)
+    p = sub.add_parser("status", help="plain summary of the repository")
+    _common(p, suppress=True)
+    p = sub.add_parser("explain", help="explain a git error message ('-' reads it from stdin)")
+    p.add_argument("text", nargs="*", help="the error text, or - to read from stdin")
+    _common(p, suppress=True)
+    sub.add_parser("mcp", help="run the MCP server over stdio")
+    return parser
+
+
+def _setup_stdout() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    _setup_stdout()
+    args = build_parser().parse_args(argv)
+    if args.command == "mcp":
+        from .server import main as server_main
+
+        server_main()
+        return 0
+    style = Style(want_color(force_off=args.no_color or args.json))
+    try:
+        if args.command == "status":
+            res = explain_state(args.path)
+            _emit(res, args.json, lambda r: render_state(r, style))
+            return 0
+        if args.command == "explain":
+            text = " ".join(args.text)
+            if text.strip() in ("", "-"):
+                if sys.stdin is not None and sys.stdin.isatty():
+                    print(
+                        "Paste the error text, then press Ctrl-D (macOS/Linux) or Ctrl-Z then Enter (Windows):",
+                        file=sys.stderr,
+                    )
+                text = sys.stdin.read() if sys.stdin is not None else ""
+            if not text.strip():
+                print("whygit explain: no error text given.", file=sys.stderr)
+                return 2
+            res = explain_error(text, args.path)
+            _emit(res, args.json, lambda r: render_explanation(r, style))
+            return 0 if res.get("recognised") else 3
+        res = diagnose(args.path)
+        _emit(res, args.json, lambda r: render_diagnosis(r, style))
+        return 1 if any(f["severity"] == "blocking" for f in res["findings"]) else 0
+    except PathNotFound as exc:
+        print(
+            f"whygit: the folder {exc} does not exist. Use --path with your project folder, or cd into it first.",
+            file=sys.stderr,
+        )
+        return 2
+
+
+def _emit(res: dict, as_json: bool, render) -> None:
+    if as_json:
+        print(json.dumps(res, indent=2, ensure_ascii=False))
+    else:
+        print(render(res))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

whygit/engine.py

@@ -0,0 +1,179 @@
+"""Public entry points shared by the CLI and the MCP server. Everything returned
+here is plain data (dicts, lists, strings) with credentials redacted."""
+
+from __future__ import annotations
+
+import os
+
+from .errors import match_errors
+from .findings import Finding, sort_findings
+from .gitcmd import redact, redact_obj
+from .rules import RULES, rule_order
+from .state import PathNotFound, RepoState, ago, collect
+
+__all__ = ["diagnose", "explain_state", "explain_error", "findings_for", "PathNotFound"]
+
+
+def findings_for(st: RepoState) -> list[Finding]:
+    found = []
+    quiet = set()
+    for r in RULES:
+        f = r.detect(st)
+        if f is not None:
+            found.append(f)
+            if r.quiet:
+                quiet.add(r.id)
+    if any(f.rule_id == "home_repo" and f.severity == "blocking" for f in found):
+        # Everything else is noise (and some advice, like `git add .`, would be harmful).
+        found = [f for f in found if f.rule_id in ("home_repo", "index_lock")]
+    if any(f.severity in ("blocking", "warning") for f in found):
+        found = [f for f in found if f.rule_id not in quiet]
+    return sort_findings(found, rule_order())
+
+
+def _summary_counts(findings: list[Finding]) -> str:
+    if not findings:
+        return "No problems found."
+    parts = []
+    for sev in ("blocking", "warning", "info"):
+        n = sum(1 for f in findings if f.severity == sev)
+        if n:
+            parts.append(f"{n} {sev}")
+    return ", ".join(parts)
+
+
+def _where(st: RepoState) -> dict:
+    d: dict = {"path": str(st.path)}
+    if st.toplevel is not None:
+        d["repo_root"] = str(st.toplevel)
+    if st.is_repo:
+        if st.detached:
+            d["branch"] = None
+            d["head"] = f"detached at {(st.head_oid or '')[:7]}"
+        else:
+            d["branch"] = st.branch
+    return d
+
+
+def diagnose(path: str | os.PathLike | None = None) -> dict:
+    st = collect(path)
+    findings = findings_for(st)
+    out = _where(st)
+    out["summary"] = _summary_counts(findings)
+    out["findings"] = [f.to_dict() for f in findings]
+    return redact_obj(out)
+
+
+def _names(entries, limit=8) -> list[str]:
+    names = [e.path for e in entries]
+    if len(names) > limit:
+        return names[:limit] + [f"... and {len(names) - limit} more"]
+    return names
+
+
+def explain_state(path: str | os.PathLike | None = None) -> dict:
+    st = collect(path)
+    out = _where(st)
+    lines: list[str] = []
+    if not st.git_available:
+        out["is_repo"] = False
+        out["summary"] = ["Git is not installed or not on PATH."]
+        return out
+    if not st.is_repo:
+        out["is_repo"] = False
+        reason = {
+            "not_found": "This folder is not inside a Git repository.",
+            "dubious": "Git refuses to read this repository because another user owns the folder.",
+            "inside_git_dir": "You are inside the hidden .git folder.",
+            "bare": "This is a bare repository (history only, no working files).",
+        }.get(st.not_repo_reason, "Git could not read this folder: " + st.error_text)
+        out["summary"] = [reason]
+        return redact_obj(out)
+    out["is_repo"] = True
+    if "rebase" in st.in_progress:
+        name = f"branch '{st.rebase_head_name}'" if st.rebase_head_name else "a branch"
+        step = f" (step {st.rebase_step})" if st.rebase_step else ""
+        lines.append(f"Rebasing {name}{step}; HEAD is detached until the rebase finishes.")
+    elif st.detached:
+        lines.append(f"Not on a branch: HEAD is detached at commit {(st.head_oid or '')[:7]}.")
+    elif st.unborn:
+        lines.append(f"On branch '{st.branch}', which has no commits yet.")
+    else:
+        lines.append(f"On branch '{st.branch}'.")
+    if st.last_commit:
+        lines.append(f"Last commit: {st.last_commit}.")
+        out["last_commit"] = st.last_commit
+    if st.upstream:
+        out["upstream"] = st.upstream
+        if st.upstream_gone:
+            lines.append(f"It tracks {st.upstream}, which no longer exists on the remote.")
+        else:
+            out["ahead"], out["behind"] = st.ahead, st.behind
+            if st.ahead == 0 and st.behind == 0:
+                rel = "up to date with"
+            elif st.ahead and st.behind:
+                rel = f"{st.ahead} ahead and {st.behind} behind"
+            elif st.ahead:
+                rel = f"{st.ahead} ahead of"
+            else:
+                rel = f"{st.behind} behind"
+            lines.append(f"It is {rel} {st.upstream}. {st.fetch_note()}")
+        out["last_fetch"] = ago(st.last_fetch) if st.last_fetch else "never (only cloned)"
+    elif not st.detached:
+        lines.append("It is not linked to a remote branch (no upstream).")
+    out["remotes"] = dict(st.remotes)
+    if not st.remotes:
+        lines.append("No remote is set, so nothing is connected to GitHub.")
+    op = [o for o in st.in_progress]
+    if op:
+        out["in_progress"] = op
+        lines.append("In progress: " + ", ".join(op) + ".")
+    changes = {
+        "conflicted": _names(st.unmerged),
+        "staged": _names(st.staged),
+        "modified_not_staged": _names(st.unstaged),
+        "untracked": _names(st.untracked),
+    }
+    out["changes"] = {k: v for k, v in changes.items() if v}
+    counts = [
+        (len(st.unmerged), "conflicted"),
+        (len(st.staged), "staged for the next commit"),
+        (len(st.unstaged), "changed but not staged"),
+        (len(st.untracked), "new and untracked"),
+    ]
+    bits = [f"{n} {label}" for n, label in counts if n]
+    lines.append(("Files: " + ", ".join(bits) + ".") if bits else "No uncommitted changes.")
+    if st.stash_count:
+        out["stashes"] = st.stash_count
+        lines.append(
+            f"{st.stash_count} stash entr{'y' if st.stash_count == 1 else 'ies'} saved (see `git stash list`)."
+        )
+    out["summary"] = lines
+    return redact_obj(out)
+
+
+def explain_error(error_text: str, path: str | os.PathLike | None = None) -> dict:
+    text = error_text or ""
+    st = collect(path) if path not in (None, "") else None
+    matches = match_errors(text, st)
+    out: dict = {"recognised": bool(matches)}
+    if st is not None:
+        out.update(_where(st))
+    if matches:
+        out["matches"] = [dict(f.to_dict(), matched_line=line) for f, line in matches]
+        # Add anything else urgent in the repository that the error didn't mention.
+        if st is not None and st.is_repo:
+            seen = {f.rule_id for f, _ in matches}
+            extra = [f.to_dict() for f in findings_for(st) if f.severity == "blocking" and f.rule_id not in seen]
+            if extra:
+                out["also_in_this_repo"] = extra
+    else:
+        out["message"] = (
+            "whygit doesn't recognise this message. Here is what it can see in the repository instead."
+            if st is not None
+            else "whygit doesn't recognise this message. Pass the repository path to get a diagnosis of its current state."
+        )
+        if st is not None:
+            out["diagnosis"] = [f.to_dict() for f in findings_for(st)]
+        out["error_excerpt"] = redact(text.strip())[:500]
+    return redact_obj(out)