slopscore 0.1.0__py3-none-any.whl

slopscore/__init__.py

@@ -0,0 +1,3 @@
+"""slopscore - heuristic slop linter for your own PRs and code."""
+
+__version__ = "0.1.0"

slopscore/cli.py

@@ -0,0 +1,283 @@
+"""Command-line entry point for slopscore.
+
+Reads a PR/issue document (JSON ``{title, body, commits[]}`` or, with --text,
+raw body text), runs the triage engine, and prints the report. The exit code
+doubles as a CI / git-hook gate:
+
+    0  below threshold (PASS)
+    1  at or above threshold (FLAG)
+    2  usage or input error
+
+Flags craft, not authorship: it reports fixable residue with evidence, never a claim about who or what wrote the text.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from slopscore.config import default_config, load_config
+from slopscore.ingest import MAX_INPUT_CHARS, files_from_diff, files_from_paths
+from slopscore.signals import SIGNALS, CodeFile, Document
+from slopscore.triage import DEFAULT_THRESHOLD, triage
+
+
+def _document_from_json(raw: str, files: tuple[CodeFile, ...] = ()) -> Document:
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("expected a JSON object with title/body/commits")
+    title = data.get("title", "")
+    body = data.get("body", "")
+    commits = data.get("commits", [])
+    # Validate rather than str()-coerce: a dict/number smuggled into a field
+    # would silently poison the scored text and PASS a malformed input.
+    if not isinstance(title, str) or not isinstance(body, str):
+        raise ValueError("'title' and 'body' must be strings")
+    if not isinstance(commits, list) or not all(isinstance(c, str) for c in commits):
+        raise ValueError("'commits' must be a list of strings")
+    return Document(
+        title=title, body=body, commits=tuple(commits), files=files, structured=True
+    )
+
+
+def _read_input(path: str | None) -> str:
+    # Capped read: a multi-MB body must not exhaust the scanner. Decode with
+    # errors="replace": a stray non-UTF-8 byte (legacy latin-1 file in a diff)
+    # must degrade to a replacement character, never raise - an unhandled
+    # decode error exits 1, which the hooks read as FLAG (false accusation).
+    if path and path != "-":
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read(MAX_INPUT_CHARS)
+    return sys.stdin.buffer.read(MAX_INPUT_CHARS).decode("utf-8", errors="replace")
+
+
+def _version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("slopscore")
+    except PackageNotFoundError:  # running from a bare checkout
+        return "0.0.0-dev"
+
+
+def _use_color(mode: str) -> bool:
+    if mode == "always":
+        return True
+    if mode == "never":
+        return False
+    # auto: a real terminal, and the user hasn't asked for no colour
+    # (https://no-color.org - any non-empty value disables).
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="slopscore",
+        description="Score a commit, PR or text for AI residue and low-craft\n"
+        "slop (0-100, itemised findings). Flags craft, not authorship - never\n"
+        "a claim about who or what wrote it.",
+        epilog=(
+            "examples:\n"
+            "  slopscore pr.json                     score a PR described as JSON\n"
+            "  echo 'Certainly!' | slopscore --text -    score raw text from stdin\n"
+            "  slopscore --text msg.txt --diff changes.diff\n"
+            "                                        score a message plus a diff's added lines\n"
+            "  slopscore --files src/*.py            scan code files for leftovers\n"
+            "\n"
+            "exit codes: 0 pass, 1 flag (score at/above threshold), 2 usage error.\n"
+            "\n"
+            "subcommands:\n"
+            "  slopscore install-hooks               install the commit-msg + pre-push hooks here\n"
+            "  slopscore hook commit-msg|pre-push    what those installed hooks invoke\n"
+            "\n"
+            "The score, bands and signals are explained in the README."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        help="input file (JSON, or text with --text); '-' or omitted reads stdin",
+    )
+    parser.add_argument(
+        "--text",
+        action="store_true",
+        help="treat the input as raw body text rather than JSON",
+    )
+    parser.add_argument(
+        "--json",
+        dest="as_json",
+        action="store_true",
+        help="emit a machine-readable JSON report",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="thorough tier: enable every signal, including the opt-in folklore "
+        "(higher recall, higher false-positive - read the score, do not gate on it)",
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=None,
+        help=f"0-100 slop score at/above which the verdict is FLAG "
+        f"(default {DEFAULT_THRESHOLD}, or the config's value)",
+    )
+    parser.add_argument(
+        "--config",
+        help="path to a TOML config file (per-signal on/off, weight overrides, threshold)",
+    )
+    parser.add_argument(
+        "--files",
+        nargs="*",
+        metavar="PATH",
+        help="code files to scan whole (go wide on your working tree)",
+    )
+    parser.add_argument(
+        "--diff",
+        metavar="PATH",
+        help="read a unified diff and scan its added lines only; '-' for stdin",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"slopscore {_version()}",
+    )
+    parser.add_argument(
+        "--color",
+        choices=("auto", "always", "never"),
+        default="auto",
+        help="colour the report (auto: only when stdout is a terminal; "
+        "the NO_COLOR convention is respected)",
+    )
+    parser.add_argument(
+        "--root",
+        metavar="DIR",
+        help="project root for manifest/import resolution (default: current directory)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Exit-code contract: 0 PASS, 1 FLAG, 2 anything else. A crash must come
+    # out as 2, not 1 - the hooks treat 1 as a verdict and would block on it.
+    args = sys.argv[1:] if argv is None else argv
+    if args and args[0] == "hook":
+        from slopscore.githooks import hook_main
+
+        return hook_main(args[1:])
+    if args and args[0] == "install-hooks":
+        from slopscore.githooks import install_hooks
+
+        return install_hooks()
+    try:
+        return _main(argv)
+    except Exception as exc:  # noqa: BLE001
+        print(f"slopscore: internal error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.config:
+        try:
+            with open(args.config, encoding="utf-8") as fh:
+                config = load_config(fh.read())
+        except OSError as exc:
+            print(f"slopscore: cannot read config: {exc}", file=sys.stderr)
+            return 2
+        except ValueError as exc:
+            print(f"slopscore: invalid config: {exc}", file=sys.stderr)
+            return 2
+    else:
+        config = default_config()
+
+    threshold = args.threshold if args.threshold is not None else config.threshold
+    if not 0.0 <= threshold <= 100.0:
+        print(
+            f"slopscore: threshold must be between 0 and 100 (got {threshold})",
+            file=sys.stderr,
+        )
+        return 2
+
+    files: tuple[CodeFile, ...] = ()
+    if args.files:
+        files += files_from_paths(args.files)
+    if args.diff:
+        try:
+            files += files_from_diff(_read_input(args.diff))
+        except OSError as exc:
+            print(f"slopscore: cannot read diff: {exc}", file=sys.stderr)
+            return 2
+
+    # Read prose input unless this is a code-only run (--files/--diff given, no
+    # positional path): then there is no prose to wait on stdin for.
+    code_only = bool(args.files or args.diff) and not args.path
+    if not code_only and not args.path and sys.stdin.isatty():
+        # A bare `slopscore` on a terminal would silently block on stdin -
+        # exactly a new user's first command. Greet instead.
+        print(
+            "slopscore - lint your own slop before you ship it.\n"
+            "\n"
+            "Watch every commit and push (recommended - run inside each repo):\n"
+            "  slopscore install-hooks\n"
+            "\n"
+            "Or score something now:\n"
+            '  echo "Certainly! ..." | slopscore --text -\n'
+            "  slopscore pr.json\n"
+            "\n"
+            "Full options: slopscore --help"
+        )
+        return 0
+    if not code_only:
+        try:
+            raw = _read_input(args.path)
+        except OSError as exc:
+            print(f"slopscore: cannot read input: {exc}", file=sys.stderr)
+            return 2
+        try:
+            doc = (
+                Document(body=raw, files=files)
+                if args.text
+                else _document_from_json(raw, files)
+            )
+        except (ValueError, json.JSONDecodeError) as exc:
+            hint = ""
+            if not args.text and not raw.lstrip().startswith(("{", "[")):
+                hint = " - input is not JSON; did you mean --text?"
+            print(f"slopscore: invalid input: {exc}{hint}", file=sys.stderr)
+            return 2
+    else:
+        doc = Document(files=files)
+
+    enabled = frozenset(s.name for s in SIGNALS) if args.strict else config.enabled
+    report = triage(
+        doc,
+        threshold=threshold,
+        enabled=enabled,
+        weights=config.weights,
+        root=args.root or ".",
+    )
+    if args.as_json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        use_color = _use_color(args.color)
+        print(report.to_text(color=use_color))
+        dim, reset = ("\x1b[2m", "\x1b[0m") if use_color else ("", "")
+        if args.strict:
+            print(f"{dim}Running thorough tier - every signal on (higher recall; "
+                  f"read the score, don't gate on it).{reset}")
+        else:
+            print(f"{dim}Running default tier. Use --strict to additionally flag "
+                  f"the opt-in signals (section scaffolding, marketing prose, "
+                  f"rhetorical questions, hallucinated imports...).{reset}")
+    return 1 if report.verdict == "FLAG" else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

slopscore/config.py

@@ -0,0 +1,76 @@
+"""Configuration: per-signal on/off, weight overrides, and the flag threshold.
+
+Parsed from TOML via the stdlib ``tomllib`` - no third-party dependency. The
+default config keeps the distinctive LLM tells plus the keyboard-character
+folklore (em-dash, emoji - additive-only, D-12) and disables the prose-style
+folklore (high human overlap); everything is overridable. Example::
+
+    threshold = 40
+
+    [signals]
+    promotional_adjectives = true   # opt a prose-folklore signal in
+    emoji_density = false           # opt a default signal out
+
+    [weights]
+    ai_self_reference = 6.0
+"""
+
+from __future__ import annotations
+
+import math
+import tomllib
+from dataclasses import dataclass, field
+
+from slopscore.signals import SIGNALS
+from slopscore.triage import DEFAULT_THRESHOLD
+
+_NAMES = frozenset(s.name for s in SIGNALS)
+
+
+def _default_enabled() -> frozenset[str]:
+    return frozenset(s.name for s in SIGNALS if s.default_enabled)
+
+
+@dataclass(frozen=True)
+class Config:
+    threshold: float = DEFAULT_THRESHOLD
+    enabled: frozenset[str] = field(default_factory=_default_enabled)
+    weights: dict[str, float] = field(default_factory=dict)
+
+
+def default_config() -> Config:
+    """The product default: distinctive tells + keyboard-character folklore
+    on (the latter additive-only); prose-style folklore off (D-12)."""
+    return Config()
+
+
+def _check_name(name: str) -> None:
+    if name not in _NAMES:
+        raise ValueError(f"unknown signal in config: {name!r}")
+
+
+def load_config(text: str) -> Config:
+    """Parse a TOML config, layered over the defaults. Raises ValueError on bad
+    TOML or an unknown signal name."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"invalid TOML: {exc}") from exc
+
+    enabled = set(_default_enabled())
+    for name, on in data.get("signals", {}).items():
+        _check_name(name)
+        enabled.add(name) if on else enabled.discard(name)
+
+    weights: dict[str, float] = {}
+    for name, weight in data.get("weights", {}).items():
+        _check_name(name)
+        value = float(weight)
+        if not math.isfinite(value) or value < 0:
+            raise ValueError(f"weight for {name!r} must be a finite number >= 0")
+        weights[name] = value
+
+    threshold = float(data.get("threshold", DEFAULT_THRESHOLD))
+    if not math.isfinite(threshold):
+        raise ValueError("threshold must be a finite number")
+    return Config(threshold=threshold, enabled=frozenset(enabled), weights=weights)

slopscore/githooks.py

@@ -0,0 +1,319 @@
+"""Git hook implementations and the hook installer.
+
+The shell files in ``hooks/`` are thin shims that exec ``slopscore hook
+commit-msg``/``pre-push``; all behaviour lives here so a pip-installed
+package is self-contained (``slopscore install-hooks``). Hooks fail OPEN:
+any internal error warns and allows the operation - a broken linter must
+never block a commit.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+import subprocess
+import sys
+
+from slopscore.config import Config, default_config, load_config
+from slopscore.ingest import MAX_INPUT_CHARS, files_from_diff
+from slopscore.signals import SIGNALS, Document
+from slopscore.triage import triage
+
+_ZERO = "0" * 40
+_OBJECT_ID = re.compile(r"[0-9a-f]{7,64}")  # git sha-1/sha-256 abbreviations
+
+COMMIT_MSG_SHIM = """\
+#!/bin/sh
+# slopscore commit-msg shim - the logic lives in `slopscore hook commit-msg`.
+# Install: `slopscore install-hooks` (writes this shim into .git/hooks; from a
+# checkout). Bypass any time with `git commit --no-verify`.
+if command -v slopscore >/dev/null 2>&1; then
+  exec slopscore hook commit-msg "$1"
+fi
+# -P (isolated sys.path, Python 3.11+) is load-bearing: without it this would
+# import a slopscore/ package from the repo being scored - code execution on
+# commit in a hostile clone. On 3.10 the probe fails and the hook skips.
+if command -v python3 >/dev/null 2>&1 && python3 -P -c "import slopscore" 2>/dev/null; then
+  exec python3 -P -m slopscore.cli hook commit-msg "$1"
+fi
+exit 0  # slopscore not available - skip rather than block a commit
+"""
+
+PRE_PUSH_SHIM = """\
+#!/bin/sh
+# slopscore pre-push shim - the logic lives in `slopscore hook pre-push`.
+# Install: `slopscore install-hooks` (writes this shim into .git/hooks; from a
+# checkout). Bypass any time with `git push --no-verify`.
+if command -v slopscore >/dev/null 2>&1; then
+  exec slopscore hook pre-push "$@"
+fi
+# -P (isolated sys.path, Python 3.11+) is load-bearing: without it this would
+# import a slopscore/ package from the repo being scored - code execution on
+# push in a hostile clone. On 3.10 the probe fails and the hook skips.
+if command -v python3 >/dev/null 2>&1 && python3 -P -c "import slopscore" 2>/dev/null; then
+  exec python3 -P -m slopscore.cli hook pre-push "$@"
+fi
+exit 0  # slopscore not available - skip rather than block a push
+"""
+
+SHIMS = {"commit-msg": COMMIT_MSG_SHIM, "pre-push": PRE_PUSH_SHIM}
+
+
+def _git(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], capture_output=True, text=True)
+
+
+def _git_config(key: str, type_flag: str | None = None) -> str:
+    cmd = ["config"]
+    if type_flag:
+        cmd.append(f"--type={type_flag}")
+    cmd += ["--get", key]
+    result = _git(*cmd)
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+class _Settings:
+    """Per-repo hook settings from git config plus the SLOPSCORE_BLOCK env."""
+
+    def __init__(self) -> None:
+        self.block = _git_config("slopscore.block", "bool") == "true"
+        env = os.environ.get("SLOPSCORE_BLOCK", "")
+        if env == "1":
+            self.block = True
+        elif env == "0":
+            self.block = False
+        elif env:
+            print(
+                f"slopscore: SLOPSCORE_BLOCK must be 1 or 0 (got '{env}'); ignoring it.",
+                file=sys.stderr,
+            )
+        self.threshold_raw = _git_config("slopscore.threshold")
+        self.strict = _git_config("slopscore.strict", "bool") == "true"
+        self.config = default_config()
+        self.broken: str | None = None  # error text when settings are unusable
+        config_path = _git_config("slopscore.config", "path")
+        if config_path:
+            if os.path.isfile(config_path):
+                try:
+                    with open(config_path, encoding="utf-8") as fh:
+                        self.config = load_config(fh.read())
+                except (OSError, ValueError) as exc:
+                    self.broken = f"slopscore: invalid config: {exc}"
+            else:
+                print(
+                    f"slopscore: git config slopscore.config points at "
+                    f"'{config_path}' which does not exist; ignoring it.",
+                    file=sys.stderr,
+                )
+        self.threshold = self.config.threshold
+        if self.threshold_raw:
+            try:
+                self.threshold = float(self.threshold_raw)
+            except ValueError:
+                self.broken = (
+                    f"slopscore: threshold must be a number 0-100 "
+                    f"(got '{self.threshold_raw}')"
+                )
+            else:
+                if not 0.0 <= self.threshold <= 100.0:
+                    self.broken = (
+                        f"slopscore: threshold must be between 0 and 100 "
+                        f"(got {self.threshold})"
+                    )
+
+    @property
+    def threshold_display(self) -> str:
+        return self.threshold_raw or "30"
+
+
+def _footer(settings: _Settings) -> None:
+    """Config status footer so the knobs are discoverable from the report."""
+    if sys.stdout.isatty():
+        b, d, c, r = "\x1b[1m", "\x1b[2m", "\x1b[36m", "\x1b[0m"
+    else:
+        b = d = c = r = ""
+    thr = settings.threshold_display
+    print()
+    if settings.strict:
+        print(f"{b}Running thorough tier{r}{d} - every signal on (higher recall; "
+              f"read the score, don't gate on it). Off:{r} {c}git config slopscore.strict false{r}")
+    else:
+        print(f"{b}Running default tier.{r}{d} Run{r} {c}git config slopscore.strict true{r}"
+              f"{d} to additionally flag the opt-in signals (section scaffolding, "
+              f"marketing prose, rhetorical questions, hallucinated imports...).{r}")
+    if settings.block:
+        print(f"{b}Blocking: ON{r}{d} - commits and pushes scoring {thr}+ are refused.{r}")
+        print(f"{d}To turn off run:{r} {c}git config slopscore.block false{r}")
+    else:
+        print(f"{b}Blocking: off{r}{d} - commits and pushes only get this advisory.{r}")
+        print(
+            f"{d}To turn on run:{r} {c}git config slopscore.block true{r}"
+            f"{d} (refuses at score {thr}+){r}"
+        )
+    print()
+
+
+def _score(msg: str, diff: str, settings: _Settings, label: str | None, badge: str):
+    cfg: Config = settings.config
+    enabled = frozenset(s.name for s in SIGNALS) if settings.strict else cfg.enabled
+    doc = Document(
+        body=msg[:MAX_INPUT_CHARS], files=files_from_diff(diff[:MAX_INPUT_CHARS])
+    )
+    report = triage(
+        doc, threshold=settings.threshold, enabled=enabled, weights=cfg.weights
+    )
+    text = report.to_text(color=sys.stdout.isatty(), label=label, badge=badge)
+    return report, text
+
+
+def commit_msg(args: list[str]) -> int:
+    if not args:
+        print("slopscore: hook commit-msg needs the message file path", file=sys.stderr)
+        return 0
+    settings = _Settings()
+    if settings.broken:
+        print(settings.broken, file=sys.stderr)
+        print("slopscore: scoring failed (see above) - commit allowed.", file=sys.stderr)
+        return 0
+    try:
+        with open(args[0], encoding="utf-8", errors="replace") as fh:
+            msg = fh.read(MAX_INPUT_CHARS)
+    except OSError as exc:
+        print(f"slopscore: cannot read commit message: {exc}", file=sys.stderr)
+        return 0
+    diff = _git("diff", "--cached", "--diff-filter=ACMR").stdout
+    report, text = _score(msg, diff, settings, None, "SLOPSCORE COMMIT CHECK")
+    print(text)
+    _footer(settings)
+    if settings.block and report.verdict == "FLAG":
+        print(
+            "slopscore: score at/above threshold; commit blocked (slopscore.block). "
+            "Use --no-verify to bypass.",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+def _outgoing_pairs() -> list[tuple[str, str]]:
+    """(local_sha, remote_sha) pairs from the pre-push stdin protocol, or from
+    PRE_COMMIT_FROM_REF/TO_REF when run under the pre-commit framework
+    (which consumes stdin itself)."""
+    pairs = []
+    if not sys.stdin.isatty():
+        for line in sys.stdin.read().splitlines():
+            parts = line.split()
+            if len(parts) == 4:
+                pairs.append((parts[1], parts[3]))
+    if not pairs and os.environ.get("PRE_COMMIT_TO_REF"):
+        local = _git("rev-parse", os.environ["PRE_COMMIT_TO_REF"]).stdout.strip()
+        remote = _git(
+            "rev-parse", os.environ.get("PRE_COMMIT_FROM_REF", _ZERO)
+        ).stdout.strip()
+        if local:
+            pairs.append((local, remote or _ZERO))
+    return pairs
+
+
+def pre_push(args: list[str]) -> int:
+    settings = _Settings()
+    if settings.broken:
+        print(settings.broken, file=sys.stderr)
+        print("slopscore: scoring failed (see above) - push allowed.", file=sys.stderr)
+        return 0
+    flagged = 0
+    scanned = 0
+    for local_sha, remote_sha in _outgoing_pairs():
+        if local_sha == _ZERO:
+            continue  # ref delete - nothing outgoing
+        if remote_sha == _ZERO:
+            # New remote ref: score only what no remote has seen yet.
+            rev_args = ["rev-list", local_sha, "--not", "--remotes"]
+        else:
+            rev_args = ["rev-list", f"{remote_sha}..{local_sha}"]
+        for sha in _git(*rev_args).stdout.split():
+            # Defence-in-depth: only ever interpolate a real object id into the
+            # git calls below, so a future change can't let a dash-prefixed
+            # token reach git as an option (review, security Low).
+            if not _OBJECT_ID.fullmatch(sha):
+                continue
+            scanned += 1
+            msg = _git("log", "-1", "--format=%B", sha).stdout
+            # First-parent diff so a merge scores what it introduced.
+            diff = _git(
+                "show", sha, "--diff-merges=first-parent", "--diff-filter=ACMR",
+                "--format=",
+            ).stdout
+            label = _git("log", "-1", "--format=[%h] %s", sha).stdout.strip()
+            report, text = _score(msg, diff, settings, label, "SLOPSCORE PUSH CHECK")
+            if report.verdict == "FLAG":
+                flagged += 1
+                print(text)
+    if flagged:
+        print(f"slopscore: {flagged} of {scanned} outgoing commits at/above threshold.")
+        _footer(settings)
+        if settings.block:
+            print(
+                "slopscore: push blocked (slopscore.block). Use --no-verify to bypass.",
+                file=sys.stderr,
+            )
+            return 1
+    return 0
+
+
+def install_hooks() -> int:
+    hook_dir = _git("rev-parse", "--git-path", "hooks").stdout.strip()
+    if not hook_dir:
+        print("slopscore: not inside a git repository", file=sys.stderr)
+        return 1
+    os.makedirs(hook_dir, exist_ok=True)
+    installed = []
+    for name, shim in SHIMS.items():
+        dst = os.path.join(hook_dir, name)
+        if os.path.exists(dst):
+            with open(dst, encoding="utf-8", errors="replace") as fh:
+                if "slopscore" not in fh.read():
+                    print(
+                        f"Skipped {name}: a non-slopscore hook already exists at "
+                        f"{dst} (remove it and re-run to replace).",
+                        file=sys.stderr,
+                    )
+                    continue
+            os.remove(dst)  # never write through a pre-existing symlink
+        with open(dst, "w", encoding="utf-8") as fh:
+            fh.write(shim)
+        os.chmod(dst, os.stat(dst).st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        installed.append(name)
+    if not installed:
+        return 1
+    print(f"Installed slopscore hooks ({', '.join(installed)}) -> {hook_dir}")
+    print(
+        "Advisory by default (never blocks). Opt in: git config slopscore.block true; "
+        "set the bar with git config slopscore.threshold 50. "
+        "SLOPSCORE_BLOCK=1/0 overrides; --no-verify bypasses."
+    )
+    print(
+        "Config: slopscore.toml in the repo root (threshold, signals, weights) - "
+        "see the README."
+    )
+    return 0
+
+
+def hook_main(args: list[str]) -> int:
+    """Dispatch for `slopscore hook <name> ...`. Fails OPEN on any crash."""
+    try:
+        if args and args[0] == "commit-msg":
+            return commit_msg(args[1:])
+        if args and args[0] == "pre-push":
+            return pre_push(args[1:])
+        print(
+            "slopscore: unknown hook (expected commit-msg or pre-push)", file=sys.stderr
+        )
+        return 0
+    except Exception as exc:  # noqa: BLE001 - a broken linter must not block
+        print(
+            f"slopscore: internal hook error: {exc} - operation allowed.",
+            file=sys.stderr,
+        )
+        return 0