whygit 0.1.0__py3-none-any.whl

whygit/findings.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+SEVERITIES = ("blocking", "warning", "info")
+SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
+
+DOCS = "https://git-scm.com/docs/"
+BOOK = "https://git-scm.com/book/en/v2/"
+
+
+@dataclass
+class Step:
+    """One thing for the person to do. command is None for manual steps
+    such as editing a file."""
+
+    does: str
+    command: str | None = None
+    destructive: bool = False
+    warning: str | None = None
+
+    def to_dict(self) -> dict:
+        d: dict = {"does": self.does}
+        if self.command:
+            d["command"] = self.command
+        if self.destructive:
+            d["destructive"] = True
+        if self.warning:
+            d["warning"] = self.warning
+        return d
+
+
+@dataclass
+class FixOption:
+    title: str
+    steps: list[Step]
+
+    def to_dict(self) -> dict:
+        return {"title": self.title, "steps": [s.to_dict() for s in self.steps]}
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    severity: str
+    title: str
+    explanation: str
+    fix: list[FixOption] = field(default_factory=list)
+    learn_more: str = ""
+    details: list[str] = field(default_factory=list)
+    details_label: str = ""
+    note: str = ""
+
+    def to_dict(self, max_details: int = 10) -> dict:
+        d: dict = {
+            "rule": self.rule_id,
+            "severity": self.severity,
+            "title": self.title,
+            "explanation": self.explanation,
+        }
+        if self.details:
+            shown = self.details[:max_details]
+            if len(self.details) > max_details:
+                shown = shown + [f"... and {len(self.details) - max_details} more"]
+            d["details"] = {"label": self.details_label or "Files", "items": shown}
+        if self.note:
+            d["note"] = self.note
+        if self.fix:
+            d["fix"] = [f.to_dict() for f in self.fix]
+            first = d["fix"][0]
+            if first["title"].startswith("Or "):
+                first["title"] = first["title"][3].upper() + first["title"][4:]
+        if self.learn_more:
+            d["learn_more"] = self.learn_more
+        return d
+
+
+def sort_findings(findings: list[Finding], order: dict[str, int] | None = None) -> list[Finding]:
+    order = order or {}
+    return sorted(findings, key=lambda f: (SEVERITY_RANK.get(f.severity, 9), order.get(f.rule_id, 999)))
+
+
+def q(path: str) -> str:
+    """Quote a path for a shell command when it needs it. Double quotes work in
+    bash, zsh, PowerShell and cmd for ordinary file names."""
+    if path and all(c.isalnum() or c in "._-/+@:" for c in path):
+        return path
+    return '"' + path.replace('"', '\\"') + '"'

whygit/gitcmd.py

@@ -0,0 +1,183 @@
+"""The only place whygit starts a process. Every git call goes through run_git,
+which accepts read-only subcommands and refuses everything else."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+# Subcommands that only read. Some need their arguments checked as well,
+# because the same subcommand can also write (config, remote, symbolic-ref...).
+ALLOWED_SUBCOMMANDS = frozenset(
+    {
+        "status",
+        "rev-parse",
+        "symbolic-ref",
+        "for-each-ref",
+        "rev-list",
+        "config",
+        "ls-files",
+        "ls-tree",
+        "diff",
+        "log",
+        "remote",
+        "worktree",
+        "cat-file",
+        "show-ref",
+        "merge-base",
+        "version",
+    }
+)
+
+_CONFIG_READ_MODES = {"--get", "--get-all", "--get-regexp", "--list", "-l"}
+_CONFIG_OK_FLAGS = _CONFIG_READ_MODES | {
+    "--local",
+    "--global",
+    "--system",
+    "--show-origin",
+    "--show-scope",
+    "--null",
+    "-z",
+    "--name-only",
+    "--includes",
+    "--no-includes",
+    "--bool",
+    "--int",
+    "--path",
+}
+_FORBIDDEN_ANYWHERE = ("--output", "--ext-diff", "--exec", "--upload-pack", "--receive-pack")
+
+TIMEOUT_SECONDS = 20
+
+
+class GitRefused(Exception):
+    """Raised when a caller asks run_git for something that is not read-only."""
+
+
+class GitNotFound(Exception):
+    """Raised when no git executable can be started."""
+
+
+@dataclass
+class GitResult:
+    args: tuple[str, ...]
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+def check_allowed(args: tuple[str, ...]) -> None:
+    if not args:
+        raise GitRefused("no git subcommand given")
+    sub, rest = args[0], args[1:]
+    if sub.startswith("-"):
+        raise GitRefused(f"global git options are not accepted: {sub}")
+    if sub not in ALLOWED_SUBCOMMANDS:
+        raise GitRefused(f"'git {sub}' is not on the read-only allowlist")
+    for a in rest:
+        if a.split("=", 1)[0] in _FORBIDDEN_ANYWHERE:
+            raise GitRefused(f"option {a} is not allowed")
+    if sub == "config":
+        flags = [a for a in rest if a.startswith("-")]
+        if not any(f in _CONFIG_READ_MODES for f in flags):
+            raise GitRefused("git config is only allowed with --get, --get-all, --get-regexp or --list")
+        for f in flags:
+            if f.split("=", 1)[0] not in _CONFIG_OK_FLAGS and not f.startswith("--type="):
+                raise GitRefused(f"git config option {f} is not allowed")
+    elif sub == "remote":
+        if list(rest) not in ([], ["-v"], ["--verbose"]):
+            raise GitRefused("git remote is only allowed as 'git remote' or 'git remote -v'")
+    elif sub == "worktree":
+        if not rest or rest[0] != "list" or any(a not in ("--porcelain", "-z", "list") for a in rest):
+            raise GitRefused("git worktree is only allowed as 'git worktree list'")
+    elif sub == "symbolic-ref":
+        positional = [a for a in rest if not a.startswith("-")]
+        bad = [a for a in rest if a.startswith("-") and a not in ("-q", "--quiet", "--short")]
+        if len(positional) > 1 or bad:
+            raise GitRefused("git symbolic-ref is only allowed to read a ref")
+    elif sub == "cat-file":
+        if any(a in ("--filters", "--textconv") for a in rest):
+            raise GitRefused("cat-file filters are not allowed")
+
+
+def _env() -> dict[str, str]:
+    env = dict(os.environ)
+    # Never let an ambient repository setting redirect us somewhere else.
+    for k in ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_NAMESPACE"):
+        env.pop(k, None)
+    env["GIT_OPTIONAL_LOCKS"] = "0"
+    env["GIT_TERMINAL_PROMPT"] = "0"
+    env["GIT_PAGER"] = "cat"
+    env["LC_ALL"] = "C"
+    env["LANGUAGE"] = "C"
+    return env
+
+
+# Global options added to every call: no pager, and no fsmonitor hook, so a
+# repository's own config cannot make whygit run another program.
+_GLOBAL_OPTS = ("--no-pager", "-c", "core.fsmonitor=false", "-c", "core.quotePath=false")
+
+
+def run_git(cwd: str | Path, *args: str, input_text: str | None = None, timeout: float = TIMEOUT_SECONDS) -> GitResult:
+    check_allowed(tuple(args))
+    args = tuple(args)
+    if args[0] in ("diff", "log"):
+        # No external diff programs or text conversion filters.
+        args = (args[0], "--no-ext-diff", "--no-textconv", *args[1:])
+    cmd = ["git", *_GLOBAL_OPTS, *args]
+    kwargs: dict = {}
+    if os.name == "nt":
+        kwargs["creationflags"] = 0x08000000  # CREATE_NO_WINDOW
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            env=_env(),
+            input=input_text.encode("utf-8") if input_text is not None else None,
+            stdin=None if input_text is not None else subprocess.DEVNULL,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+            **kwargs,
+        )
+    except FileNotFoundError as exc:
+        raise GitNotFound(str(exc)) from exc
+    except subprocess.TimeoutExpired:
+        return GitResult(tuple(args), 124, "", "timed out")
+    return GitResult(
+        tuple(args),
+        proc.returncode,
+        proc.stdout.decode("utf-8", errors="replace"),
+        proc.stderr.decode("utf-8", errors="replace"),
+    )
+
+
+# Redaction of credentials in URLs and well-known token formats.
+_URL_USERINFO = re.compile(r"(?i)\b([a-z][a-z0-9+.\-]*://)[^/@\s'\"]+@")
+_TOKENS = re.compile(r"\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_\-]{20,})\b")
+
+
+def redact(text: str) -> str:
+    if not text:
+        return text
+    text = _URL_USERINFO.sub(r"\1***@", text)
+    return _TOKENS.sub("***", text)
+
+
+def redact_obj(obj):
+    if isinstance(obj, str):
+        return redact(obj)
+    if isinstance(obj, list):
+        return [redact_obj(x) for x in obj]
+    if isinstance(obj, tuple):
+        return tuple(redact_obj(x) for x in obj)
+    if isinstance(obj, dict):
+        return {k: redact_obj(v) for k, v in obj.items()}
+    return obj

whygit/render.py

@@ -0,0 +1,185 @@
+"""Plain-text rendering for the terminal."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import textwrap
+
+LABELS = {"blocking": "BLOCKING", "warning": "WARNING", "info": "INFO"}
+
+
+class Style:
+    def __init__(self, enabled: bool):
+        self.enabled = enabled
+
+    def _c(self, code: str, s: str) -> str:
+        return f"\033[{code}m{s}\033[0m" if self.enabled else s
+
+    def bold(self, s):
+        return self._c("1", s)
+
+    def dim(self, s):
+        return self._c("2", s)
+
+    def cmd(self, s):
+        return self._c("36", s)
+
+    def sev(self, sev, s):
+        return self._c({"blocking": "1;31", "warning": "1;33", "info": "1;34"}.get(sev, "1"), s)
+
+    def warn(self, s):
+        return self._c("1;31", s)
+
+
+def want_color(stream=None, force_off: bool = False) -> bool:
+    stream = stream or sys.stdout
+    if force_off or os.environ.get("NO_COLOR") or os.environ.get("TERM") == "dumb":
+        return False
+    if not hasattr(stream, "isatty") or not stream.isatty():
+        return False
+    if os.name == "nt":
+        return _enable_windows_vt()
+    return True
+
+
+def _enable_windows_vt() -> bool:
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.GetStdHandle(-11)
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        return bool(kernel32.SetConsoleMode(handle, mode.value | 0x0004))
+    except Exception:
+        return False
+
+
+def _width() -> int:
+    return max(60, min(100, shutil.get_terminal_size((88, 24)).columns - 2))
+
+
+def _wrap(text: str, indent: str, width: int) -> list[str]:
+    return textwrap.wrap(
+        text,
+        width=width,
+        initial_indent=indent,
+        subsequent_indent=indent,
+        break_on_hyphens=False,
+        break_long_words=False,
+    ) or [indent]
+
+
+def finding_lines(f: dict, s: Style, width: int) -> list[str]:
+    out = [s.sev(f["severity"], f"[{LABELS.get(f['severity'], f['severity'].upper())}]") + " " + s.bold(f["title"])]
+    out += _wrap(f["explanation"], "  ", width)
+    if f.get("details"):
+        out.append("  " + f["details"]["label"] + ":")
+        for item in f["details"]["items"]:
+            out.append("    - " + item)
+    if f.get("note"):
+        out += _wrap(f["note"], "  ", width)
+    fixes = f.get("fix") or []
+    if fixes:
+        out.append("  " + s.bold("How to fix:"))
+        for i, opt in enumerate(fixes):
+            title = opt["title"] if i == 0 else opt["title"]
+            out.append("    " + title + ":")
+            for n, step in enumerate(opt["steps"], 1):
+                num = f"{n}. "
+                pad = "      " + " " * len(num)
+                if step.get("command"):
+                    out.append("      " + num + s.cmd(step["command"]))
+                    out += _wrap(step["does"], pad, width)
+                else:
+                    wrapped = _wrap(step["does"], pad, width)
+                    wrapped[0] = "      " + num + wrapped[0].lstrip()
+                    out += wrapped
+                if step.get("warning"):
+                    out += [
+                        s.warn(x) if j == 0 else x
+                        for j, x in enumerate(_wrap("Warning: " + step["warning"], pad, width))
+                    ]
+    if f.get("learn_more"):
+        out.append("  " + s.dim("Learn more: " + f["learn_more"]))
+    return out
+
+
+def render_diagnosis(report: dict, s: Style) -> str:
+    width = _width()
+    head = "whygit: " + report.get("repo_root", report["path"])
+    if report.get("branch"):
+        head += f" (branch {report['branch']})"
+    elif report.get("head"):
+        head += f" ({report['head']})"
+    lines = [s.bold(head)]
+    if report.get("repo_root") and report["repo_root"] != report["path"]:
+        lines.append(s.dim("Run the commands below from the repository folder above; file paths are relative to it."))
+    lines.append("")
+    findings = report.get("findings", [])
+    if not findings:
+        lines.append("No problems found. Run `whygit status` for a plain summary of the repository.")
+        return "\n".join(lines)
+    for f in findings:
+        lines += finding_lines(f, s, width)
+        lines.append("")
+    lines.append(s.dim(report["summary"] + ". whygit never runs these commands for you; copy the ones you want."))
+    return "\n".join(lines)
+
+
+def render_state(state: dict, s: Style) -> str:
+    width = _width()
+    head = "whygit status: " + state.get("repo_root", state["path"])
+    lines = [s.bold(head), ""]
+    for line in state.get("summary", []):
+        lines += _wrap(line, "", width)
+    ch = state.get("changes") or {}
+    labels = {
+        "conflicted": "Conflicted",
+        "staged": "Staged",
+        "modified_not_staged": "Changed, not staged",
+        "untracked": "Untracked",
+    }
+    for key, label in labels.items():
+        if ch.get(key):
+            lines.append("")
+            lines.append(label + ":")
+            lines += ["  " + p for p in ch[key]]
+    if state.get("remotes"):
+        lines.append("")
+        lines.append("Remotes:")
+        lines += [f"  {k}  {v}" for k, v in state["remotes"].items()]
+    return "\n".join(lines)
+
+
+def render_explanation(res: dict, s: Style) -> str:
+    width = _width()
+    lines: list[str] = []
+    if res.get("recognised"):
+        for f in res["matches"]:
+            if f.get("matched_line"):
+                lines.append(s.dim("Matched: " + f["matched_line"]))
+            lines += finding_lines(f, s, width)
+            lines.append("")
+        extra = res.get("also_in_this_repo") or []
+        if extra:
+            lines.append(s.bold("Also found in this repository:"))
+            lines.append("")
+            for f in extra:
+                lines += finding_lines(f, s, width)
+                lines.append("")
+        lines.append(s.dim("whygit never runs these commands for you; copy the ones you want."))
+    else:
+        lines += _wrap(res.get("message", "Not recognised."), "", width)
+        lines.append("")
+        diag = res.get("diagnosis")
+        if diag:
+            for f in diag:
+                lines += finding_lines(f, s, width)
+                lines.append("")
+        elif diag is not None:
+            lines.append("No problems found in the repository either.")
+    return "\n".join(lines).rstrip() + "\n"