crapkit 0.2.0__py3-none-any.whl

crapkit/cli/analyses.py

@@ -0,0 +1,144 @@
+"""The standalone analyses that read a snapshot or the working tree rather than
+producing one: `coupling` (files that co-change), `mutate` (diff-scoped mutation
+testing), `duplication` (near-duplicate functions) and `mcp` (the stdio server
+that exposes the read-side tools)."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ..churn_log import log_lines
+from ..errors import ConfigError, CrapkitError
+from ._shared import _load_repo_config, _load_sources, _open_store, _print_json
+
+
+def cmd_coupling(args: argparse.Namespace) -> int:
+    from ..coupling import change_coupling_lines
+
+    root = Path(args.repo).resolve()
+    cfg = _load_repo_config(root)
+    pairs = change_coupling_lines(log_lines(root, cfg.churn_window_months),
+                                  min_support=args.min_support, min_confidence=args.min_confidence,
+                                  top=args.top)
+    if args.json:
+        _print_json({"pairs": pairs, "window_months": cfg.churn_window_months})
+        return 0
+    if not pairs:
+        print(f"no coupled pairs at support>={args.min_support} "
+              f"confidence>={args.min_confidence} in {cfg.churn_window_months}mo")
+        return 0
+    for p in pairs:
+        print(f"  {p['support']:>4}x  {p['confidence']:.0%}  {p['files'][0]}  <->  {p['files'][1]}")
+    return 0
+
+
+def _range_lines(ranges: list) -> set[int]:
+    return {line for start, end in ranges for line in range(start, end + 1)}
+
+
+def _mutation_targets(root: Path, files: list | None) -> dict:
+    """path -> changed line set (None = whole file). Default is diff-scoped:
+    only the working tree's changes vs HEAD grow mutants."""
+    from ..diffparse import changed_ranges
+    from ..gitio import diff_since
+
+    if files:
+        return {f.replace("\\", "/"): None for f in files}
+    targets = {p: _range_lines(rs) for p, rs in changed_ranges(diff_since(root, "HEAD")).items()}
+    if not targets:
+        raise CrapkitError("no changes vs HEAD to mutate — name files with --files")
+    return targets
+
+
+def _collect_mutants(root: Path, targets: dict, max_mutants: int) -> list:
+    from ..mutate import file_mutants
+
+    out = []
+    for rel, lines in sorted(targets.items()):
+        p = root / rel
+        if not p.is_file():
+            continue
+        language = "python" if rel.endswith(".py") else "typescript"
+        for m in file_mutants(p.read_text(encoding="utf-8", errors="replace"), lines, language):
+            out.append(m._replace(path=rel))
+    if len(out) > max_mutants:
+        print(f"crapkit: capping at {max_mutants} of {len(out)} mutants "
+              f"(raise --max-mutants to run them all)", file=sys.stderr)
+        out = out[:max_mutants]
+    return out
+
+
+def _print_mutation(as_json: bool, survivors: list, total: int) -> None:
+    killed = total - len(survivors)
+    if as_json:
+        _print_json({"mutants": total, "killed": killed, "survived": len(survivors),
+                          "survivors": [m._asdict() for m in survivors]})
+        return
+    rate = f"{killed / total:.0%}" if total else "n/a"
+    print(f"mutation: {killed}/{total} killed ({rate})")
+    for m in survivors:
+        print(f"  SURVIVED  {m.path}:{m.line}  [{m.op}]  {m.mutated.strip()}")
+
+
+def cmd_mcp(args: argparse.Namespace) -> int:
+    """Serve stdio from `--repo`, or from the directory the client started in.
+
+    A client registered globally opens the server in every project, most of
+    which have no crapkit.toml. Refusing to start there gave the client a server
+    that never answered `initialize`; the tools answer that per call instead.
+    A config that EXISTS and is broken still fails fast, before any client
+    connects, because every tool would fail the same way anyway.
+    """
+    from ..mcp_server import serve
+
+    root = Path(args.repo).resolve()
+    if (root / "crapkit.toml").is_file():
+        _load_repo_config(root)
+    return serve(root)
+
+
+def cmd_mutate(args: argparse.Namespace) -> int:
+    from ..mutate_pool import reporter, run_mutants
+
+    root = Path(args.repo).resolve()
+    cfg = _load_repo_config(root)
+    if not cfg.mutation_command:
+        raise ConfigError("mutate needs [crapkit] mutation_command — the suite run once per mutant")
+    mutants = _collect_mutants(root, _mutation_targets(root, args.files), args.max_mutants)
+    verdicts = run_mutants(root, cfg, mutants, reporter(len(mutants), sys.stderr))
+    survivors = [m for m, killed in zip(mutants, verdicts) if not killed]
+    _print_mutation(args.json, survivors, len(mutants))
+    return 0
+
+
+def _print_duplication(as_json: bool, pairs, latest: dict) -> None:
+    if as_json:
+        _print_json({"run_id": latest["id"], "pairs": pairs})
+        return
+    if not pairs:
+        print("no near-duplicate functions found")
+        return
+    for p in pairs:
+        a, b = p["functions"]
+        print(f"  {p['similarity']:.0%}  {a['path']}:{a['start']} {a['long_name']}  ==  "
+              f"{b['path']}:{b['start']} {b['long_name']}")
+
+
+def cmd_duplication(args: argparse.Namespace) -> int:
+    from ..dup import find_duplicates
+
+    root = Path(args.repo).resolve()
+    _load_repo_config(root)  # config errors first, like every command
+    store = _open_store(root, first_command="inventory")
+    runs = [r for r in store.list_runs() if r["kind"] != "hook"]
+    if not runs:
+        raise CrapkitError(f"no snapshot in {root} — run `crapkit inventory` first")
+    rows = store.read_rows(runs[-1]["id"])
+    # A loader, never a bound dict: whoever names those texts pins every byte of
+    # them across the pair counting (146 MB of peak on a 104 MB repo).
+    pairs = find_duplicates(rows, lambda: _load_sources(root, {r.path for r in rows}),
+                            min_lines=args.min_lines,
+                            similarity=args.similarity, top=args.top)
+    _print_duplication(args.json, pairs, runs[-1])
+    return 0

crapkit/cli/parser.py

@@ -0,0 +1,384 @@
+"""The argument parser and the process entry point: every subcommand's flags in
+one place, the lazy --version action, and main()'s stream reconfiguration and
+CrapkitError-to-exit-code mapping."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .. import __version__
+from ..errors import CrapkitError
+
+
+class _Handler:
+    """A subcommand's handler, named at parser-build time and imported when it runs.
+
+    argparse holds this where the function used to sit, and main() still calls
+    args.func(args). Naming eight families to build the parser imported all
+    eight, so `crapkit runs list` paid for the mutation engine and the verifier,
+    and `hook-precommit` paid for them at every git commit.
+    """
+
+    __slots__ = ("_family", "_name")
+
+    def __init__(self, family: str, name: str) -> None:
+        self._family = family
+        self._name = name
+
+    def __call__(self, args):
+        from importlib import import_module
+
+        return getattr(import_module(f"{__package__}.{self._family}"), self._name)(args)
+
+    def __repr__(self) -> str:
+        return f"<{__package__}.{self._family}.{self._name}>"
+
+
+def _version_line() -> str:
+    """`crapkit <version>` — the program AND the number, so a pasted bug report
+    says what produced it.
+
+    The installed distribution answers, because pyproject.toml is where the
+    number is published. `__version__` is the fallback for a source tree with
+    nothing installed, which is where the git merge driver runs.
+
+    importlib.metadata reads that number out of the installed METADATA file,
+    dragging in email, csv, typing and importlib.resources to do it. Reading the
+    same header straight costs a directory listing, so when it produces the
+    number the package already carries, both sources say the same thing and
+    neither import is worth making. A disagreement, or a distribution this scan
+    cannot see, goes to importlib.metadata and takes its answer.
+    """
+    if _published_version() == __version__:
+        return f"crapkit {__version__}"
+    return f"crapkit {_metadata_version()}"
+
+
+def _metadata_version() -> str:
+    """The authority, for what reading a header cannot settle."""
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("crapkit")
+    except PackageNotFoundError:
+        return __version__
+
+
+def _published_version() -> str | None:
+    """The Version: header of the first crapkit dist-info on sys.path — the same
+    file, found the same way, that importlib.metadata would answer from."""
+    for entry in sys.path:
+        metadata = _dist_info_metadata(entry)
+        if metadata:
+            return _version_field(metadata)
+    return None
+
+
+def _dist_info_metadata(entry: str) -> str | None:
+    """<entry>/crapkit-*.dist-info/METADATA, when this path entry holds one."""
+    try:
+        names = os.listdir(entry or ".")
+    except OSError:
+        return None  # a zip, a stale path entry, an unreadable directory
+    for name in names:
+        if _is_crapkit_dist_info(name):
+            return os.path.join(entry, name, "METADATA")
+    return None
+
+
+def _is_crapkit_dist_info(name: str) -> bool:
+    low = name.lower()
+    return low.startswith("crapkit-") and low.endswith(".dist-info")
+
+
+def _version_field(path: str) -> str | None:
+    """METADATA's Version: header. Headers stop at the first blank line; the
+    long description below it is free to contain anything."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as handle:
+            return _version_header(handle)
+    except OSError:
+        return None
+
+
+def _version_header(lines) -> str | None:
+    for line in lines:
+        if not line.strip():
+            return None
+        if line.startswith("Version:"):
+            return line.partition(":")[2].strip()
+    return None
+
+
+class _VersionAction(argparse.Action):
+    """`--version`, resolved when it is asked for.
+
+    argparse's own version action wants the finished string at parser-build
+    time, and reading the installed distribution costs ~30ms. build_parser()
+    runs on every invocation, `crapkit hook-precommit` included, and the hook is
+    measured in what a developer waits for at every `git commit`.
+    """
+
+    def __init__(self, option_strings, dest, **kwargs):
+        super().__init__(option_strings, dest, nargs=0, **kwargs)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        print(_version_line())
+        parser.exit()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The whole CLI surface, assembled without parsing anything. README's
+    Subcommands table is checked against this parser's own subcommand set."""
+    parser = argparse.ArgumentParser(prog="crapkit")
+    parser.add_argument("--version", action=_VersionAction, default=argparse.SUPPRESS,
+                        help="print the program name and its version")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inv = sub.add_parser("inventory", help="build the per-function complexity inventory snapshot")
+    inv.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    inv.add_argument("--db", default=None, help="snapshot database path (default: <repo>/.crapkit/crap.sqlite)")
+    inv.add_argument("--export", default=None, help="also write a canonical TSV export, relative to the repo")
+    inv.add_argument("--json", action="store_true", help="print the run summary as JSON")
+    inv.set_defaults(func=_Handler("scoring", "cmd_inventory"))
+
+    cov = sub.add_parser("coverage", help="run coverage lanes, join onto a fresh inventory, write a scored run")
+    cov.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    cov.add_argument("--lane", default=None, help="run only this lane (default: all)")
+    cov.add_argument("--reuse-artifacts", action="store_true", help="skip lane commands, parse existing artifacts")
+    cov.add_argument("--reuse-unchanged", action="store_true",
+                     help="rerun only lanes whose scope files changed since their artifact; reuse the rest")
+    cov.add_argument("--export", default=None, help="write scored TSV export, relative to the repo")
+    cov.add_argument("--sarif", default=None, metavar="PATH",
+                     help="write over-target findings as SARIF 2.1.0, relative to the repo")
+    cov.add_argument("--github", action="store_true",
+                     help="print findings as GitHub workflow-command annotations")
+    cov.add_argument("--json", action="store_true", help="print the run summary as JSON")
+    cov.set_defaults(func=_Handler("scoring", "cmd_coverage"))
+
+    nxt = sub.add_parser("next-item", help="the actionable queue as JSON, ranked by crap "
+                                           "descending: what a refactor session takes next")
+    nxt.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    nxt.add_argument("--top", type=int, default=1, help="return the next N items instead of one")
+    nxt.add_argument("--exclude", action="append", default=[],
+                     help="skip items whose path or function name contains this (repeatable)")
+    nxt.add_argument("--scope", action="append", default=[], metavar="NAME",
+                     help="restrict to this configured scope (repeatable); exact, not substring")
+    nxt.add_argument("--claim", action="store_true",
+                     help="hold the items handed out so another session skips them; "
+                          "verify releases a claim once the function is at its ceiling, "
+                          "and `crapkit claims release PATH NAME` hands one back by hand")
+    nxt.set_defaults(func=_Handler("queue", "cmd_next_item"))
+
+    clm = sub.add_parser("claims", help="the claims sessions hold, and the release that hands one back")
+    clm.add_argument("action", nargs="?", default="list", choices=("list", "release"),
+                     help="list (default): every open claim; release: close one (PATH NAME) "
+                          "or, with --all, every one")
+    clm.add_argument("target", nargs="*", metavar="ARG",
+                     help="release: PATH NAME, taking either the bare identifier or the "
+                          "long_name next-item printed")
+    clm.add_argument("--all", action="store_true", help="release: close every open claim")
+    clm.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    clm.add_argument("--json", action="store_true", help="machine output")
+    clm.set_defaults(func=_Handler("queue", "cmd_claims"))
+
+    runs_p = sub.add_parser("runs", help="run history, and the retention command that trims it")
+    runs_p.add_argument("action", nargs="?", default="list", choices=("list", "prune"),
+                        help="list (default): id, kind, verdict, commit, lane set, and "
+                             "`baseline` on the run verify compares against (verdict=- is "
+                             "a run that renders no verdict); prune: delete runs outside "
+                             "the keep-set, then VACUUM")
+    runs_p.add_argument("--keep", type=int, default=5,
+                        help="prune: newest trusted runs to keep (default 5). A floor, not "
+                             "a cap — the digest pair, passing verify baselines, runs an "
+                             "override names and the newest non-hook run are kept too")
+    runs_p.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    runs_p.add_argument("--json", action="store_true", help="machine output")
+    runs_p.set_defaults(func=_Handler("reports", "cmd_runs"))
+
+    ovr = sub.add_parser("overrides", help="the override audit trail")
+    ovr.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    ovr.add_argument("--json", action="store_true", help="machine output")
+    ovr.set_defaults(func=_Handler("reports", "cmd_overrides"))
+
+    expl = sub.add_parser("explain", help="a function's trajectory across runs, plus its ratchet mark")
+    expl.add_argument("path", help="repo-relative source file")
+    expl.add_argument("name", help="function name or fragment")
+    expl.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    expl.add_argument("--history", action="store_true",
+                      help="also list the commits that touched this function (git log -L)")
+    expl.add_argument("--tests", action="store_true",
+                      help="also list the tests covering this function (coverage.py contexts)")
+    expl.add_argument("--json", action="store_true", help="machine output")
+    expl.set_defaults(func=_Handler("reports", "cmd_explain"))
+
+    brf = sub.add_parser("brief", help="one function's whole start-editing packet: score, "
+                                       "source, the rest of its file, gate rule, lane, mark, "
+                                       "dark lines, twins, churn, coupling, commands")
+    brf.add_argument("path", nargs="?", help="repo-relative source file")
+    brf.add_argument("name", nargs="?",
+                     help="function name: the bare identifier, the whole long_name "
+                          "next-item printed, or the line it starts on")
+    brf.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    brf.add_argument("--batch", type=int, default=None, metavar="N",
+                     help="skip PATH NAME and emit a packet for each of the top N "
+                          "queue items, assembled in one process; always JSON")
+    brf.add_argument("--json", action="store_true", help="machine output (default: a short summary)")
+    brf.set_defaults(func=_Handler("queue", "cmd_brief"))
+
+    rsc = sub.add_parser("rescore", help="fresh complexity for named files overlaid on the latest run's coverage")
+    rsc.add_argument("files", nargs="+", help="repo-relative source files to re-analyze")
+    rsc.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    rsc.add_argument("--json", action="store_true", help="machine output (default: table)")
+    rsc.add_argument("--gate", action="store_true",
+                     help="exit 6 when a function this tree changed since HEAD is over its "
+                          "scope ceiling: the pre-commit hook's ccn-only policy on the hook's "
+                          "own selection, minus functions a ratchet mark already covers")
+    rsc.set_defaults(func=_Handler("scoring", "cmd_rescore"))
+
+    dig = sub.add_parser("digest", help="delta between the last two scored runs; silent when unchanged")
+    dig.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    dig.add_argument("--alert", action="store_true", help="pipe a non-quiet digest through alert_command")
+    dig.set_defaults(func=_Handler("reports", "cmd_digest"))
+
+    trd = sub.add_parser("trend", help="totals per scored run: over-target count, CRAP load, average")
+    trd.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    trd.add_argument("--json", action="store_true", help="print as JSON")
+    trd.set_defaults(func=_Handler("reports", "cmd_trend"))
+
+    tsc = sub.add_parser("test-scoped", help="run the configured isolated test command for the files' scope")
+    tsc.add_argument("files", nargs="+", help="repo-relative test files")
+    tsc.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    tsc.set_defaults(func=_Handler("verifying", "cmd_test_scoped"))
+
+    ver = sub.add_parser("verify", help="full verdict vs the baseline snapshot: gate, ratchet, new failures")
+    ver.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    # one baseline, named one way: two of these would leave the losing flag
+    # silently ignored, and which one lost would be argument order
+    picked = ver.add_mutually_exclusive_group()
+    picked.add_argument("--baseline", type=int, default=None, help="baseline run id (default: latest scored run)")
+    picked.add_argument("--base", default=None, metavar="REF",
+                        help="measure the diff from merge-base(REF, HEAD); the baseline run must "
+                             "then sit at or behind that fork point")
+    picked.add_argument("--baseline-tsv", default=None, metavar="PATH",
+                        help="read the baseline from a TSV written by --emit-baseline, not the store")
+    ver.add_argument("--emit-baseline", default=None, metavar="PATH",
+                     help="also write the baseline run as a portable TSV, relative to the repo")
+    ver.add_argument("--reuse-artifacts", action="store_true", help="skip lane commands, parse existing artifacts")
+    ver.add_argument("--reuse-unchanged", action="store_true",
+                     help="rerun only lanes whose scope files changed since their artifact; reuse the rest")
+    ver.add_argument("--override", default=None, metavar="REASON",
+                     help="audited exemption for gate violations: alert + ratchet debt + snapshot record")
+    ver.add_argument("--sarif", default=None, metavar="PATH",
+                     help="write gate/ratchet findings as SARIF 2.1.0, relative to the repo")
+    ver.add_argument("--github", action="store_true",
+                     help="print findings as GitHub workflow-command annotations")
+    ver.add_argument("--json", action="store_true", help="print the verdict as JSON")
+    ver.set_defaults(func=_Handler("verifying", "cmd_verify"))
+
+    hook = sub.add_parser("hook-precommit", help="gate staged functions at min-CCN <= target; exit 6 on violation")
+    hook.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    hook.set_defaults(func=_Handler("verifying", "cmd_hook_precommit"))
+
+    wl = sub.add_parser("worklist", help="ranked risk map: every admitted function, "
+                                         "finished and no-lane rows included, so it never empties")
+    wl.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    wl.add_argument("--top", type=int, default=None, help="cap the active list (default: config worklist_top)")
+    wl.add_argument("--scope", action="append", default=[], metavar="NAME",
+                    help="restrict to this configured scope (repeatable); exact, not substring")
+    wl.add_argument("--batches", type=int, default=None, metavar="N",
+                    help="split the active list into at most N batches with no shared "
+                         "files, co-changing files kept together: one per agent session")
+    wl.add_argument("--json", action="store_true", help="print as JSON")
+    wl.set_defaults(func=_Handler("queue", "cmd_worklist"))
+
+    ini = sub.add_parser("init", help="sniff the repo and write a starter crapkit.toml")
+    ini.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    ini.set_defaults(func=_Handler("admin", "cmd_init"))
+
+    doc = sub.add_parser("doctor", help="check that crapkit.toml still describes this repo")
+    doc.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    doc.add_argument("--show-files", action="store_true", help="list every file each scope matched")
+    doc.add_argument("--json", action="store_true",
+                     help="one machine-readable report instead of lines: versions, store, "
+                          "newest run, per-lane artifact stamps, problems, warnings")
+    doc.add_argument("--tune", action="store_true",
+                     help="print suggested [crapkit] parallelism knobs for this machine from "
+                          "cpu count and recorded lane durations; writes nothing")
+    doc.set_defaults(func=_Handler("admin", "cmd_doctor"))
+
+    rat = sub.add_parser("ratchet", help="manage the committed marks file: seed new debt, prune gone code")
+    rat.add_argument("action", choices=("seed", "prune", "merge", "move", "report"),
+                     help="seed: mark over-target functions from the latest run; "
+                          "prune: drop marks whose functions left the codebase "
+                          "(a mark whose file git renamed follows it instead); "
+                          "merge: 3-way git merge driver (BASE OURS THEIRS); "
+                          "move: re-path marks at their recorded values (OLD NEW); "
+                          "report: burn-down from the marks file's git history")
+    rat.add_argument("files", nargs="*", metavar="FILE",
+                     help="for merge: the three files git passes as %%O %%A %%B; "
+                          "for move: OLD NEW, where a trailing '/' on OLD moves a directory")
+    rat.add_argument("--json", action="store_true", help="machine output (report)")
+    rat.add_argument("--enforce", action="store_true",
+                     help="report: exit 1 on debt policy violations (age, repayment quota)")
+    rat.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    rat.set_defaults(func=_Handler("ratchet_cmds", "cmd_ratchet"))
+
+    wat = sub.add_parser("watch", help="rescore files as they change (polls tracked files from start)")
+    wat.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    wat.add_argument("--interval", type=float, default=2.0, help="poll seconds (default 2)")
+    wat.add_argument("--cycles", type=int, default=None,
+                     help="stop after N polls (default: poll until ctrl-c)")
+    wat.set_defaults(func=_Handler("admin", "cmd_watch"))
+
+    srv = sub.add_parser("mcp", help="stdio MCP server exposing the read-side tools (JSON-RPC, no deps)")
+    srv.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    srv.set_defaults(func=_Handler("analyses", "cmd_mcp"))
+
+    mut = sub.add_parser("mutate", help="diff-scoped mutation testing: flip operators on changed lines, run the suite per mutant")
+    mut.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    mut.add_argument("--files", nargs="*", default=None,
+                     help="mutate these whole files instead of the working-tree diff vs HEAD")
+    mut.add_argument("--max-mutants", type=int, default=100, help="hard cap per run (default 100)")
+    mut.add_argument("--json", action="store_true", help="machine output")
+    mut.set_defaults(func=_Handler("analyses", "cmd_mutate"))
+
+    dup = sub.add_parser("duplication", help="near-duplicate functions by normalized line shingles")
+    dup.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    dup.add_argument("--min-lines", type=int, default=8, help="smallest function considered (default 8)")
+    dup.add_argument("--similarity", type=float, default=0.8,
+                     help="containment threshold, shared/smaller (default 0.8)")
+    dup.add_argument("--top", type=int, default=50, help="cap the pair list (default 50)")
+    dup.add_argument("--json", action="store_true", help="machine output")
+    dup.set_defaults(func=_Handler("analyses", "cmd_duplication"))
+
+    cpl = sub.add_parser("coupling", help="files that co-change in the churn window: hidden dependencies")
+    cpl.add_argument("--repo", default=".", help="consuming repo root (default: cwd)")
+    cpl.add_argument("--min-support", type=int, default=5, help="minimum shared commits (default 5)")
+    cpl.add_argument("--min-confidence", type=float, default=0.5,
+                     help="minimum max-direction co-change ratio (default 0.5)")
+    cpl.add_argument("--top", type=int, default=50, help="cap the pair list (default 50)")
+    cpl.add_argument("--json", action="store_true", help="machine output")
+    cpl.set_defaults(func=_Handler("analyses", "cmd_coupling"))
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Piped output (git hooks, CI, agents) reads as UTF-8 everywhere modern;
+    # Windows hands pipes the legacy codepage instead, which renders as mojibake.
+    # A tty keeps its native encoding. Either way errors degrade to '?' — an
+    # exotic console must never turn an exit code into a traceback.
+    for stream in (sys.stdout, sys.stderr):
+        if not hasattr(stream, "reconfigure"):
+            continue
+        if stream.isatty():
+            stream.reconfigure(errors="replace")
+        else:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except CrapkitError as exc:
+        print(f"crapkit: {exc}", file=sys.stderr)
+        return exc.exit_code