commithygiene 0.1.0__py3-none-any.whl

commithygiene-0.1.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: commithygiene
+Version: 0.1.0
+Summary: Read-only linter for noisy, AI-generated git commit history
+Author: commithygiene contributors
+License: MIT
+Keywords: git,commits,linter,ai,agent,cli,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# commithygiene
+
+<div align="center">
+
+**The read-only linter for AI-mangled git history.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#-zero-dependencies)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-13%2F13%20passing-success.svg)](tests/)
+
+*AI agents write a lot of commits. Some of them deserve to be squashed before anyone sees them.*
+
+</div>
+
+---
+
+## What problem does this solve?
+
+Your AI coding agent (or you, at 2 a.m.) just produced this history:
+
+```
+a1b2c3d  Update LoginForm.tsx
+d4e5f6  Fix TypeScript error
+g7h8i9  Revert LoginForm.tsx
+j0k1l2  Update LoginForm.tsx again
+m3n4o5  Fix import
+p6q7r8  wip
+s9t0u1  LoginForm complete
+```
+
+Seven commits. One component. **History that is useless for bisect, hostile to review, and embarrassing to merge.**
+
+`commithygiene` finds these commits — *before* they hit your branch. It's read-only: it never rewrites history, never stages files, never touches your reflog. It just **reads** and **reports**. You decide what to do.
+
+> **AI wrote the code. You're still responsible for the history.**
+
+## Why commithygiene?
+
+Every other tool in this space wants to *rewrite* your history:
+
+| Tool | Approach | Needs | Can it gate CI? |
+|---|---|---|---|
+| Claude `git-squash` skill | Interactive squash | Claude Code runtime | ❌ Lives in a chat session |
+| `commit-tidy` / `squash-commits` skills | LLM-guided rebase | Claude + context | ❌ |
+| `yawn` | AI *writes new* commit messages | API key | ❌ |
+| `git-shrink` | Group + squash by similarity | Node.js + npm | ⚠️ Rewrites history |
+| **commithygiene** | **Read-only linter with exit codes** | **Just Python 3.10+** | ✅ **Made for CI** |
+
+The ecosystem had `prettier` but no `eslint`. `git-cliff` but no `shellcheck`. **commithygiene is the linter** — the thing you put in your pipeline to *catch* noise, not the thing you run interactively to fix it.
+
+## Features
+
+- 🔒 **Read-only by design** — `git log` and `git show` only. Zero risk of destroying history.
+- 🪶 **Zero dependencies** — one file, pure Python standard library. No npm, no Rust toolchain, no API key.
+- 🤖 **Knows AI fingerprints** — detects `wip`, `fix typo again`, `revert the revert`, `actually works now`, and other agent churn patterns.
+- 🚦 **CI-ready exit codes** — `0` clean, `1` noise found, `2` error. `--strict` promotes warnings to errors.
+- 📊 **JSON output** — machine-readable for scripts, bots, and dashboards.
+- 📈 **Health reports** — `report` gives you a project-wide noise ratio and verdict.
+- 🐍 **Python 3.10+** — runs anywhere Python runs. Windows, macOS, Linux.
+
+## Quick start
+
+### 1. Drop it in
+
+```bash
+# No install needed — it's a single file.
+curl -O https://raw.githubusercontent.com/DEL8108/commit-hygiene-checker/main/commithygiene.py
+python commithygiene.py check
+```
+
+Or install properly:
+
+```bash
+pip install git+https://github.com/DEL8108/commit-hygiene-checker.git
+commithygiene check
+```
+
+### 2. Run it on your current branch
+
+```bash
+$ commithygiene check
+
+  commithygiene — scanned 8 commit(s)
+
+  ✗ noise-subject     650b5e8c43  noise commit: 'wip'
+  ✗ noise-subject     9743088c03  noise commit: 'wip'
+  ! churn-subject     562493cd3e  possible churn commit: 'fix typo again'
+  ! churn-subject     5871f1d5c1  possible churn commit: 'actually works now'
+  ! churn-subject     a4590d7b47  possible churn commit: 'revert the revert'
+  ! trivial-only      4ffd15159e  tiny diff touching only trivial files (README.md)
+```
+
+Exit code `1` — your CI just found noise before your reviewer did.
+
+### 3. Gate your PRs
+
+```yaml
+# .github/workflows/hygiene.yml
+name: Commit Hygiene
+on: [pull_request]
+jobs:
+  hygiene:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # need full history
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check commit hygiene
+        run: |
+          curl -O https://raw.githubusercontent.com/DEL8108/commit-hygiene-checker/main/commithygiene.py
+          python commithygiene.py check "${{ github.event.pull_request.base.sha }}..HEAD" --strict
+```
+
+Now every PR with a `wip` or an `actually works now` in it gets flagged **before merge**.
+
+## Usage
+
+### `check` — find noisy commits
+
+```bash
+commithygiene check                    # scan all of HEAD
+commithygiene check HEAD~20..HEAD      # scan the last 20 commits
+commithygiene check main..HEAD         # only commits on this branch
+commithygiene check --strict           # warnings become errors (exit 1)
+commithygiene check --format json      # machine-readable output
+```
+
+### `report` — project-wide health
+
+```bash
+$ commithygiene report
+
+  commit hygiene report — HEAD
+
+    commits        : 128
+    noise commits  : 31 (24%)
+    churn commits  : 12 (9%)
+    verdict        : very noisy
+```
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean — no noise, or only warnings (without `--strict`) |
+| `1` | Noise found — errors, or warnings under `--strict` |
+| `2` | Usage / I/O error (not a git repo, bad range, git missing) |
+
+## What gets flagged
+
+| Rule | Severity | Example |
+|---|---|---|
+| `noise-subject` | error | `wip`, `tmp`, `fixup!`, `???`, `initial commit`, `checkpoint` |
+| `churn-subject` | warning | `fix typo again`, `revert the revert`, `actually works now`, `for real this time` |
+| `trivial-only` | warning | a 1-file commit touching only `README.md`, lockfiles, `.gitignore` |
+
+Warnings stay warnings unless you pass `--strict` — because sometimes a `revert` is a legitimate, deliberate decision. `commithygiene` errs on the side of *showing* you, not *blocking* you.
+
+## How it works
+
+```
+git log --format=%H <range>          # list commits, oldest first
+        │
+        ▼
+git show --numstat --format=%s <h>   # subject + per-file stats per commit
+        │
+        ▼
+heuristic engine                     # noise patterns, churn tokens, trivial paths
+        │
+        ▼
+findings ──► table / json ──► exit code 0/1/2
+```
+
+No git history is modified at any step. The only commands executed are `git log`, `git show`, and `git rev-parse`. You can audit the entire tool in one sitting — it's ~500 lines.
+
+## Why "hygiene"?
+
+Because that's what it is. Like flossing, nobody *wants* to think about commit hygiene, but the alternative is worse. The name also means the tool is easily discoverable apart from the squash/rewrite crowd — this is the *prevention* layer, not the *surgery* layer.
+
+## Limitations
+
+Being read-only and heuristic-driven means some things are out of scope, on purpose:
+
+- **It never rewrites history.** For that, use `git rebase -i`, `git-squash`, or `git-shrink`.
+- **It judges by signals, not semantics.** A `wip` with a giant meaningful diff is still flagged — you know your repo better than the heuristic does.
+- **It doesn't verify build state.** Two commits both labeled `fix` could each be perfectly fine.
+- **No AI, no LLM calls, no telemetry.** It's deterministic. The same input always produces the same output. That's a feature.
+
+## Contributing
+
+Found a noise pattern the tool missed? A false positive? Contributions are welcome:
+
+1. Fork and clone the repo.
+2. Run the tests: `python -m unittest discover -s tests -v`
+3. Add a test for your pattern in `tests/test_commithygiene.py`.
+4. Open a PR with a clear description.
+
+The whole philosophy is "small, conservative, zero false-positive pressure." New rules need example commits that prove the signal is real.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Do whatever you want with it; attribution appreciated.
+
+---
+
+<div align="center">
+
+**Star it if your agent's commit history has ever made you say "what is this?"** ⭐
+
+</div>

commithygiene-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+commithygiene.py,sha256=23A6sqHanmJsfD0RMgkLn-ce6LV2n56fXvk138rSNGg,15122
+commithygiene-0.1.0.dist-info/licenses/LICENSE,sha256=Iei147ZPSFkK0YZGXX_ULbzR4x6us61Bg3puaZvHW3E,1083
+commithygiene-0.1.0.dist-info/METADATA,sha256=lGbSOhJ_CjdGDNTxbSHoeRiGVb1Sf4FCerxbJ0PO4FY,9028
+commithygiene-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+commithygiene-0.1.0.dist-info/entry_points.txt,sha256=oUk57IZBudT7oV4meZwphxpQD7sjLhKhvRhFsUsOd6c,53
+commithygiene-0.1.0.dist-info/top_level.txt,sha256=fMa3c1cg-nrRoQA1rABkfKq_Ue5LUTKAK5WbaJeonbM,14
+commithygiene-0.1.0.dist-info/RECORD,,

commithygiene-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

commithygiene-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+commithygiene = commithygiene:main

commithygiene-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 commithygiene contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commithygiene-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+commithygiene

commithygiene.py

@@ -0,0 +1,492 @@
+#!/usr/bin/env python3
+"""commithygiene — a zero-dependency, read-only linter for AI-mangled git history.
+
+AI coding agents (and humans in a hurry) leave a recognizable trail of "noise
+commits": ``wip``, ``fix typo``, ``fix typo again``, ``revert`` followed by
+``revert the revert``, tiny diffs to the same file over and over. Individually
+harmless, together they bury meaningful change and break ``git bisect``.
+
+``commithygiene`` does ONE thing and does it read-only: it walks a range of git
+history, scores every commit against a set of heuristics, and reports the ones
+that should have been squashed before they hit the branch. It never rewrites
+history, never stages files, never touches your reflog — it only reads.
+
+Exit-code contract (CI friendly):
+    EXIT_OK    = 0   no noise, or only warnings (without --strict)
+    EXIT_DRIFT = 1   noise found (always, or warnings promoted via --strict)
+    EXIT_ERROR = 2   usage / I/O / unexpected error
+
+Only the Python standard library is used. Requires Python 3.10+.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field, asdict
+from typing import Iterable, Optional
+
+__version__ = "0.1.0"
+
+# ---------------------------------------------------------------------------
+# Exit codes
+# ---------------------------------------------------------------------------
+EXIT_OK = 0
+EXIT_DRIFT = 1
+EXIT_ERROR = 2
+
+
+class CliError(Exception):
+    """Raised for expected, user-facing failures (bad args, bad repo, ...)."""
+
+
+# ---------------------------------------------------------------------------
+# Heuristics
+# ---------------------------------------------------------------------------
+# Commits whose subject is pure noise. These are almost never meaningful
+# checkpoints and should always be flagged. The lists are deliberately small and
+# conservative: a false positive here is worse than a missed one.
+NOISE_PATTERNS: tuple[re.Pattern, ...] = tuple(
+    re.compile(p, re.IGNORECASE)
+    for p in (
+        r"^wip\b",
+        r"^work in progress\b",
+        r"^tmp\b",
+        r"^temp\b",
+        r"^fixup!",
+        r"^squash!",
+        r"^tweak\b",
+        r"^tweak(s|ing)?\b",
+        r"^minor\b",
+        r"^oops\b",
+        r"^cleanup\b",
+        r"^misc\b",
+        r"^save point\b",
+        r"^checkpoint\b",
+        r"^.\?{1,3}$",           # "?", "??", "???" etc.
+        r"^test commit\b",
+        r"^initial commit$",
+        r"^\d+$",                # bare numbers like "123"
+    )
+)
+
+# A subject containing these tokens is a strong signal of churn: an edit to an
+# edit, a revert, or a "real fix now" that implies a previous attempt was wrong.
+CHURN_TOKENS: tuple[str, ...] = (
+    "again",
+    "revert",
+    "actually",
+    "now it works",
+    "for real",
+    "final",
+    "final version",
+    "hopefully",
+    "try",
+    "attempt",
+    "redo",
+    "another",
+)
+
+# Files whose changes rarely constitute a meaningful checkpoint on their own.
+# A commit touching ONLY these is usually noise.
+TRIVIAL_ONLY_PATHS: tuple[str, ...] = (
+    ".gitignore",
+    ".editorconfig",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "poetry.lock",
+    "Pipfile.lock",
+)
+
+
+@dataclass
+class Finding:
+    """A single hygiene violation. ``severity`` is "error" or "warning"."""
+
+    severity: str
+    code: str
+    detail: str
+    commit: str
+    subject: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "severity": self.severity,
+            "code": self.code,
+            "detail": self.detail,
+            "commit": self.commit,
+            "subject": self.subject,
+        }
+
+
+@dataclass
+class CommitInfo:
+    """What we know about a single commit, assembled from ``git show`` output."""
+
+    hash: str
+    subject: str
+    files_changed: int = 0
+    insertions: int = 0
+    deletions: int = 0
+    paths: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Git plumbing
+# ---------------------------------------------------------------------------
+def _run(cmd: list[str]) -> str:
+    """Run a git command and return its trimmed stdout. Raises CliError."""
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError:
+        raise CliError("git executable not found on PATH")
+    if proc.returncode != 0:
+        err = (proc.stderr or "").strip()
+        raise CliError(err or f"git command failed: {' '.join(cmd)}")
+    return (proc.stdout or "").strip()
+
+
+def is_git_repo() -> bool:
+    try:
+        _run(["git", "rev-parse", "--is-inside-work-tree"])
+        return True
+    except CliError:
+        return False
+
+
+def list_commits(rng: Optional[str]) -> list[str]:
+    """Return commit hashes (oldest first) in the requested range."""
+    cmd = ["git", "log", "--format=%H"]
+    if rng:
+        cmd.append(rng)
+    try:
+        out = _run(cmd)
+    except CliError:
+        # An empty repository (no commits yet) makes `git log` fail; treat that
+        # as "nothing to scan" rather than leaking the raw git error.
+        return []
+    if not out:
+        return []
+    # oldest-first ordering so "again/revert" context reads naturally
+    return list(reversed(out.splitlines()))
+
+
+def show_commit(h: str) -> CommitInfo:
+    """Assemble a CommitInfo for one hash using a single ``git show`` call."""
+    # numstat gives us per-file add/del without loading the full patch.
+    numstat = _run(
+        ["git", "show", "--numstat", "--format=%s", "--no-color", h]
+    ).splitlines()
+
+    subject = ""
+    if numstat:
+        subject = numstat[0].strip()
+
+    info = CommitInfo(hash=h, subject=subject)
+    files = 0
+    ins = 0
+    dele = 0
+    paths: list[str] = []
+    for line in numstat[1:]:
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split("\t")
+        # valid numstat rows look like: "<add>\t<del>\t<path>"
+        if len(parts) < 3:
+            continue
+        add_s, del_s, path = parts[0], parts[1], parts[2]
+        # binary files are reported as "-"
+        a = 0 if add_s == "-" else int(add_s)
+        d = 0 if del_s == "-" else int(del_s)
+        files += 1
+        ins += a
+        dele += d
+        if path:
+            paths.append(path)
+
+    info.files_changed = files
+    info.insertions = ins
+    info.deletions = dele
+    info.paths = paths
+    return info
+
+
+# ---------------------------------------------------------------------------
+# Rule engine
+# ---------------------------------------------------------------------------
+def _is_noise(subject: str) -> bool:
+    return any(p.search(subject) for p in NOISE_PATTERNS)
+
+
+def _has_churn(subject: str) -> bool:
+    low = subject.lower()
+    return any(tok in low for tok in CHURN_TOKENS)
+
+
+def _only_trivial_paths(paths: list[str]) -> bool:
+    if not paths:
+        return False
+    return all(
+        p in TRIVIAL_ONLY_PATHS
+        or p.endswith(".lock")
+        for p in paths
+    )
+
+
+def analyze_commit(c: CommitInfo, strict: bool = False) -> list[Finding]:
+    """Score a single commit and return its findings (possibly empty)."""
+    findings: list[Finding] = []
+
+    if _is_noise(c.subject):
+        findings.append(
+            Finding(
+                severity="error",
+                code="noise-subject",
+                detail=f"noise commit: '{c.subject}'",
+                commit=c.hash,
+                subject=c.subject,
+            )
+        )
+
+    # "revert" + "again"/"actually" style churn is a warning (could be legit).
+    if _has_churn(c.subject):
+        findings.append(
+            Finding(
+                severity="warning",
+                code="churn-subject",
+                detail=f"possible churn commit: '{c.subject}'",
+                commit=c.hash,
+                subject=c.subject,
+            )
+        )
+
+    # A tiny diff touching only lockfiles/docs is rarely a checkpoint.
+    if (
+        c.files_changed == 1
+        and c.insertions + c.deletions <= 10
+        and _only_trivial_paths(c.paths)
+    ):
+        findings.append(
+            Finding(
+                severity="warning",
+                code="trivial-only",
+                detail=(
+                    "tiny diff touching only trivial files "
+                    f"({', '.join(c.paths[:2])})"
+                ),
+                commit=c.hash,
+                subject=c.subject,
+            )
+        )
+
+    if strict:
+        # Under --strict, promote warnings to errors so CI can hard-fail.
+        for f in findings:
+            if f.severity == "warning":
+                f.severity = "error"
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+def cmd_check(args: argparse.Namespace) -> int:
+    if not is_git_repo():
+        raise CliError("not a git repository (or git not on PATH)")
+
+    hashes = list_commits(args.range)
+    if not hashes:
+        raise CliError(f"no commits found in range: {args.range or 'HEAD'}")
+
+    all_findings: list[Finding] = []
+    for h in hashes:
+        info = show_commit(h)
+        all_findings.extend(analyze_commit(info, strict=args.strict))
+
+    _render(all_findings, args.format, args.strict, len(hashes))
+    return _exit_code(all_findings, args.strict)
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    """A project-wide health summary: noise ratio, churn, hot files."""
+    if not is_git_repo():
+        raise CliError("not a git repository (or git not on PATH)")
+
+    hashes = list_commits(args.range)
+    if not hashes:
+        raise CliError(f"no commits found in range: {args.range or 'HEAD'}")
+
+    commits = [show_commit(h) for h in hashes]
+    noisy = sum(1 for c in commits if _is_noise(c.subject))
+    churny = sum(1 for c in commits if _has_churn(c.subject))
+
+    report = {
+        "commits": len(commits),
+        "noise_commits": noisy,
+        "noise_ratio": round(noisy / len(commits), 3) if commits else 0.0,
+        "churn_commits": churny,
+        "churn_ratio": round(churny / len(commits), 3) if commits else 0.0,
+    }
+
+    if args.format == "json":
+        print(json.dumps(report, indent=2))
+    else:
+        _print(f"\n  commit hygiene report — {args.range or 'HEAD'}\n")
+        _print(f"    commits        : {report['commits']}")
+        _print(f"    noise commits  : {report['noise_commits']} "
+               f"({report['noise_ratio']:.0%})")
+        _print(f"    churn commits  : {report['churn_commits']} "
+               f"({report['churn_ratio']:.0%})")
+        verdict = (
+            "clean" if report["noise_ratio"] < 0.05
+            else "noisy" if report["noise_ratio"] < 0.2
+            else "very noisy"
+        )
+        _print(f"    verdict        : {verdict}\n")
+
+    return EXIT_OK
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+_USE_COLOR = False
+
+
+def _print(msg: str = "") -> None:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")  # py3.7+; Windows safety
+    except Exception:
+        pass
+    print(msg)
+
+
+def _color(code: str, s: str) -> str:
+    if not _USE_COLOR:
+        return s
+    return f"\033[{code}m{s}\033[0m"
+
+
+def _render(
+    findings: list[Finding],
+    fmt: str,
+    strict: bool,
+    total: int,
+) -> None:
+    if fmt == "json":
+        payload = {
+            "commits_scanned": total,
+            "findings": [f.to_dict() for f in findings],
+        }
+        _print(json.dumps(payload, indent=2))
+        return
+
+    _print(f"\n  commithygiene — scanned {total} commit(s)\n")
+
+    if not findings:
+        _print(_color("32", "  ✓ clean — no hygiene issues found\n"))
+        return
+
+    for f in findings:
+        mark = _color("31", "✗") if f.severity == "error" else _color("33", "!")
+        code = f"{f.code:<16}"
+        _print(f"  {mark} {code}  {f.commit[:10]}  {f.detail}")
+    _print("")
+
+
+def _exit_code(findings: list[Finding], strict: bool) -> int:
+    has_error = any(f.severity == "error" for f in findings)
+    has_warning = any(f.severity == "warning" for f in findings)
+
+    if has_error:
+        return EXIT_DRIFT
+    if has_warning and strict:
+        return EXIT_DRIFT
+    return EXIT_OK
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="commithygiene",
+        description=(
+            "Read-only linter for noisy / AI-generated git commit history. "
+            "Finds wip, churn, and trivial commits before they hit your branch."
+        ),
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    # Shared flags for both subcommands. argparse only allows parent-level
+    # options BEFORE the subcommand, so real CLI UX needs them on each sub.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--no-color", action="store_true",
+                        help="disable ANSI colors")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c_check = sub.add_parser("check", parents=[common],
+                             help="find noisy commits in a range")
+    c_check.add_argument("range", nargs="?", default=None,
+                         help="git range (default: HEAD)")
+    c_check.add_argument("--strict", action="store_true",
+                         help="treat warnings as errors (exit 1)")
+    c_check.add_argument("--format", choices=["table", "json"],
+                         default="table", help="output format")
+    c_check.set_defaults(func=cmd_check)
+
+    c_report = sub.add_parser("report", parents=[common],
+                              help="project-wide hygiene summary")
+    c_report.add_argument("range", nargs="?", default=None,
+                          help="git range (default: HEAD)")
+    c_report.add_argument("--format", choices=["table", "json"],
+                          default="table", help="output format")
+    c_report.set_defaults(func=cmd_report)
+
+    return p
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    global _USE_COLOR
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # Color only on a real TTY, never when asked not to, and honor NO_COLOR.
+    _USE_COLOR = (
+        hasattr(sys.stdout, "isatty")
+        and sys.stdout.isatty()
+        and not getattr(args, "no_color", False)
+        and "NO_COLOR" not in os.environ
+    )
+
+    try:
+        return args.func(args)
+    except CliError as e:
+        sys.stderr.write(f"error: {e}\n")
+        return EXIT_ERROR
+    except BrokenPipeError:
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())