crapkit 0.2.0__py3-none-any.whl

crapkit/cli/__init__.py

@@ -0,0 +1,316 @@
+"""The CLI, split by command family. This module is the seam every other file
+still imports through: `crapkit.cli:main` is the console script and `python -m
+crapkit`, and the test suite reaches dozens of the helpers below by name. Every
+top-level name the single-file cli.py exposed is re-exported here, so nothing
+outside the package has to know which family a helper landed in. No logic lives
+here: each name is defined in the module its family owns.
+
+The re-export is by name, not by import. Eight `from .family import ...` lines
+loaded all eight families before anything read one of their names, which put the
+cost of every subcommand on every invocation. `_OWNER` says which module owns
+each name and `__getattr__` fetches it the first time it is read.
+"""
+
+from __future__ import annotations
+
+_OWNER = {
+    "SCHEMA_VERSION": "_shared",
+    "_AMBIGUOUS_TEST": "verifying",
+    "_BriefLoader": "queue",
+    "_Corpus": "scoring",
+    "_Handles": "queue",
+    "_SCRIPT_SUFFIXES": "admin",
+    "_VersionAction": "parser",
+    "_actionable": "queue",
+    "_analysis_tools": "_shared",
+    "_analysis_workers": "scoring",
+    "_analyzed_corpus": "scoring",
+    "_apply_verify_override": "verifying",
+    "_at_level": "admin",
+    "_baseline_behind": "verifying",
+    "_baseline_failures": "verifying",
+    "_batch_json": "queue",
+    "_batch_rows": "queue",
+    "_brief_batch": "queue",
+    "_brief_churn": "queue",
+    "_brief_coupling": "queue",
+    "_brief_lines_text": "queue",
+    "_brief_mark": "queue",
+    "_brief_packet": "queue",
+    "_brief_payload": "queue",
+    "_brief_target": "queue",
+    "_brief_twins": "queue",
+    "_brief_versions": "queue",
+    "_build_inventory": "scoring",
+    "_by_scope": "scoring",
+    "_ceiling_breaches": "scoring",
+    "_churn_text": "queue",
+    "_claim_matches": "queue",
+    "_claimable": "queue",
+    "_claims_summary": "queue",
+    "_claims_to_release": "queue",
+    "_collect_lanes": "scoring",
+    "_collect_mutants": "analyses",
+    "_contexts_for_span": "reports",
+    "_coverage_summary": "scoring",
+    "_covered_scope_names": "admin",
+    "_diff_cover_breach": "verifying",
+    "_digest_pair": "reports",
+    "_dirty_tag": "_shared",
+    "_doctor_findings": "admin",
+    "_doctor_hook_modes": "admin",
+    "_doctor_keys": "admin",
+    "_doctor_lane_summary": "admin",
+    "_doctor_lanes": "admin",
+    "_doctor_oversized": "admin",
+    "_doctor_report": "admin",
+    "_doctor_scope_files": "admin",
+    "_doctor_scopes": "admin",
+    "_doctor_tools": "admin",
+    "_doctor_tune": "admin",
+    "_doctor_unclaimed": "admin",
+    "_doctor_uncovered": "admin",
+    "_doctor_unmeasured": "admin",
+    "_emit_baseline": "verifying",
+    "_emit_coverage_findings": "scoring",
+    "_emit_doctor": "admin",
+    "_emit_findings": "_shared",
+    "_emit_next": "queue",
+    "_emit_verify_findings": "verifying",
+    "_empty_reasons": "queue",
+    "_entry_json": "queue",
+    "_excluded_item": "queue",
+    "_execute_lanes": "scoring",
+    "_execute_parallel": "scoring",
+    "_explain_commits": "reports",
+    "_explain_extras": "reports",
+    "_explain_tests": "reports",
+    "_export_scored": "scoring",
+    "_extend_gitignore": "admin",
+    "_file_sizer": "_shared",
+    "_flag_counts": "scoring",
+    "_flake_retry": "verifying",
+    "_gate_candidates": "scoring",
+    "_gate_line": "_shared",
+    "_grant_env_override": "verifying",
+    "_group_files_by_scope": "verifying",
+    "_guard_ratchet_stamp": "verifying",
+    "_handle": "queue",
+    "_hook_modes": "admin",
+    "_interpreter": "admin",
+    "_is_test_path": "verifying",
+    "_junit_seconds": "admin",
+    "_lane_command_problems": "admin",
+    "_lane_durations": "admin",
+    "_lane_problem": "admin",
+    "_lane_problems": "admin",
+    "_lane_report": "admin",
+    "_lane_reports": "admin",
+    "_lane_reuse": "scoring",
+    "_lane_seconds": "admin",
+    "_latest_full_run": "ratchet_cmds",
+    "_latest_scored": "_shared",
+    "_latest_span": "reports",
+    "_listed_files": "admin",
+    "_lizard_version": "admin",
+    "_load_ratchet_or_die": "_shared",
+    "_load_repo_config": "_shared",
+    "_load_sources": "_shared",
+    "_mark_text": "queue",
+    "_matching_rows": "queue",
+    "_maybe_claim": "queue",
+    "_maybe_flake_retry": "verifying",
+    "_merge_stamp": "ratchet_cmds",
+    "_missing_named_script": "admin",
+    "_mutation_targets": "analyses",
+    "_name_matches": "queue",
+    "_name_prefix": "queue",
+    "_named_baseline": "verifying",
+    "_named_claims": "queue",
+    "_newest_coverage_run": "admin",
+    "_newest_run_report": "admin",
+    "_next_head": "queue",
+    "_next_item_payload": "queue",
+    "_next_ranked": "queue",
+    "_next_reasons": "queue",
+    "_no_baseline": "verifying",
+    "_no_handle_message": "queue",
+    "_no_lane_debt": "queue",
+    "_no_lane_gap": "queue",
+    "_no_line_message": "queue",
+    "_no_match_message": "queue",
+    "_no_scopes_reason": "admin",
+    "_note_stale_staged": "verifying",
+    "_open_store": "_shared",
+    "_owning_scope": "verifying",
+    "_package_json": "admin",
+    "_packet_commands": "queue",
+    "_packet_context": "queue",
+    "_packet_gate": "queue",
+    "_packet_scope": "queue",
+    "_pick_baseline": "verifying",
+    "_pick_function": "queue",
+    "_policy_findings": "ratchet_cmds",
+    "_present_markers": "admin",
+    "_present_on_disk": "scoring",
+    "_print_batches": "queue",
+    "_print_brief": "queue",
+    "_print_brief_context": "queue",
+    "_print_brief_neighbours": "queue",
+    "_print_claims": "queue",
+    "_print_coverage": "scoring",
+    "_print_duplication": "analyses",
+    "_print_finding_split": "verifying",
+    "_print_findings": "admin",
+    "_print_history": "reports",
+    "_print_init_summary": "admin",
+    "_print_json": "_shared",
+    "_print_mutation": "analyses",
+    "_print_prune": "reports",
+    "_print_ratchet_report": "ratchet_cmds",
+    "_print_released": "queue",
+    "_print_rescore_table": "scoring",
+    "_print_trend": "reports",
+    "_print_uncovered": "reports",
+    "_print_verify_findings": "verifying",
+    "_progress": "scoring",
+    "_prune_renames": "ratchet_cmds",
+    "_pruned": "ratchet_cmds",
+    "_pushdown_floor": "queue",
+    "_range_lines": "analyses",
+    "_rankable": "queue",
+    "_ratchet_entries": "_shared",
+    "_ratchet_mark": "reports",
+    "_ratchet_merge": "ratchet_cmds",
+    "_ratchet_move": "ratchet_cmds",
+    "_ratchet_report": "ratchet_cmds",
+    "_ratchet_sha256": "verifying",
+    "_records_by_scope": "scoring",
+    "_release_claims": "verifying",
+    "_release_target": "queue",
+    "_report_verify": "verifying",
+    "_require_ancestor": "verifying",
+    "_rescore_analyze": "scoring",
+    "_rescore_gate": "scoring",
+    "_rescore_json": "scoring",
+    "_rescore_overlay": "scoring",
+    "_rescored_records": "scoring",
+    "_resolve_batch": "queue",
+    "_resolve_batches": "queue",
+    "_resolve_top": "queue",
+    "_route_unowned": "verifying",
+    "_row_at_line": "queue",
+    "_row_by_handle": "queue",
+    "_row_ceiling": "queue",
+    "_row_marker": "queue",
+    "_run_kind": "scoring",
+    "_run_lanes": "scoring",
+    "_run_line": "reports",
+    "_run_one_lane": "scoring",
+    "_runs_list": "reports",
+    "_runs_prune": "reports",
+    "_scope_config": "queue",
+    "_scope_rollup_from_agg": "reports",
+    "_scoped_command": "verifying",
+    "_scored_run": "scoring",
+    "_scored_store": "queue",
+    "_select_lanes": "scoring",
+    "_send_digest_alert": "reports",
+    "_settle_verify": "verifying",
+    "_skip_reason": "queue",
+    "_split_worklist": "queue",
+    "_stale_warning": "queue",
+    "_store_if_any": "admin",
+    "_store_path": "admin",
+    "_store_report": "admin",
+    "_taint_note": "verifying",
+    "_traced_lane": "scoring",
+    "_tracked_files": "scoring",
+    "_trend_row": "reports",
+    "_tsv_baseline": "verifying",
+    "_unclaimed": "queue",
+    "_uncovered_fields": "queue",
+    "_uncovered_scopes": "admin",
+    "_uncovered_text": "reports",
+    "_under_scope_path": "verifying",
+    "_unknown_key_text": "admin",
+    "_unmarked_breaches": "scoring",
+    "_untracked_of": "scoring",
+    "_verify_attribution": "verifying",
+    "_verify_baseline": "verifying",
+    "_verify_basis": "verifying",
+    "_verify_exit_code": "verifying",
+    "_verify_result": "verifying",
+    "_verify_store": "verifying",
+    "_version_line": "parser",
+    "_version_report": "admin",
+    "_warn_diff_uncovered": "verifying",
+    "_warn_suite_shrink": "verifying",
+    "_warn_untracked": "scoring",
+    "_watch_banner": "admin",
+    "_watch_cycle": "admin",
+    "_watch_cycles": "admin",
+    "_watch_rescore": "admin",
+    "_watched_files": "admin",
+    "_working_marks": "ratchet_cmds",
+    "_worklist_batches": "queue",
+    "_worklist_marks": "queue",
+    "_worklist_payload": "queue",
+    "_worklist_print": "queue",
+    "_write_tsv": "_shared",
+    "build_parser": "parser",
+    "cmd_brief": "queue",
+    "cmd_claims": "queue",
+    "cmd_coupling": "analyses",
+    "cmd_coverage": "scoring",
+    "cmd_digest": "reports",
+    "cmd_doctor": "admin",
+    "cmd_duplication": "analyses",
+    "cmd_explain": "reports",
+    "cmd_hook_precommit": "verifying",
+    "cmd_init": "admin",
+    "cmd_inventory": "scoring",
+    "cmd_mcp": "analyses",
+    "cmd_mutate": "analyses",
+    "cmd_next_item": "queue",
+    "cmd_overrides": "reports",
+    "cmd_ratchet": "ratchet_cmds",
+    "cmd_rescore": "scoring",
+    "cmd_runs": "reports",
+    "cmd_test_scoped": "verifying",
+    "cmd_trend": "reports",
+    "cmd_verify": "verifying",
+    "cmd_watch": "admin",
+    "cmd_worklist": "queue",
+    "main": "parser",
+}
+
+_MODULES = frozenset(_OWNER.values())
+
+__all__ = sorted(_OWNER)
+
+
+def __getattr__(name):
+    """Re-export on demand: reading a name loads the one family that defines it."""
+    family = _OWNER.get(name)
+    if family is None:
+        return _submodule(name)
+    from importlib import import_module
+
+    value = getattr(import_module(f"{__name__}.{family}"), name)
+    globals()[name] = value
+    return value
+
+
+def _submodule(name: str):
+    """`crapkit.cli.admin` after a bare `import crapkit.cli`: the family modules
+    were attributes here because __init__ imported every one of them."""
+    if name not in _MODULES:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    return import_module(f"{__name__}.{name}")
+
+
+def __dir__():
+    return sorted(set(_OWNER) | _MODULES | set(globals()))

crapkit/cli/_shared.py

@@ -0,0 +1,130 @@
+"""Helpers more than one command family needs: the JSON envelope and its schema
+version, repo config loading, the snapshot store openers, TSV/SARIF writers, the
+ratchet file reader, and the gate line every gate prints. Nothing here belongs to
+one command; anything that does lives with its family."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..config import load_config_text
+from ..errors import ConfigError, CrapkitError, ToolError
+from ..store import SnapshotStore
+
+
+SCHEMA_VERSION = 1  # bumped whenever a --json field is removed or retyped
+
+
+def _print_json(payload: dict) -> None:
+    """Every machine-readable payload leaves through here, so a wrapper can pin
+    the shape it parses and fail loudly when the shape moves."""
+    print(json.dumps({**payload, "schema": SCHEMA_VERSION}, sort_keys=True))
+
+
+def _analysis_tools():
+    """Import the analysis stack lazily so an absent tool maps to ToolError (exit 5).
+
+    Under deferred_pygments: lizard's Erlang reader binds pygments at module
+    scope, and crapkit analyzes no Erlang, so every process paid 26ms of import
+    for a reader it never reaches. The proxies come out again as lizard lands.
+    """
+    from .._pygdefer import deferred_pygments
+
+    try:
+        with deferred_pygments():
+            import lizard
+
+            from ..analyze import analyze_files, load_cache, save_cache
+    except ImportError as exc:
+        raise ToolError(f"required analysis tool unavailable: {exc}") from exc
+    return lizard, analyze_files, load_cache, save_cache
+
+
+def _load_repo_config(root: Path):
+    config_path = root / "crapkit.toml"
+    if not config_path.is_file():
+        raise ConfigError(f"no crapkit.toml at {root} — nothing to analyze")
+    return load_config_text(config_path.read_text(encoding="utf-8"))
+
+
+def _file_sizer(root: Path):
+    """Working-tree sizes for the max_file_bytes cut. A tracked path that is gone
+    reads as 0: absence is _present_on_disk's business, not the byte ceiling's."""
+    def size_of(path: str) -> int:
+        try:
+            return (root / path).stat().st_size
+        except OSError:
+            return 0
+    return size_of
+
+
+def _write_tsv(path: Path, lines) -> None:
+    """Stream an export to disk. newline="\\n" is the determinism contract: the
+    bytes must not pick up the host's line separator. Writing line by line keeps
+    the whole document from existing as a string next to the rows it came from."""
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.writelines(lines)
+
+
+def _emit_findings(root: Path, sarif_path: str | None, github: bool, results: list) -> None:
+    from ..sarif import github_annotation
+    from ..sarifio import write_sarif
+
+    if sarif_path:
+        write_sarif(root / sarif_path, results)
+    if github:
+        for r in results:
+            print(github_annotation(r))
+
+
+def _load_ratchet_or_die(ratchet_path: Path, name: str) -> list:
+    from ..ratchet import load_ratchet
+
+    if not ratchet_path.is_file():
+        return []
+    try:
+        return load_ratchet(ratchet_path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        raise ConfigError(f"unreadable ratchet file {name}: {exc}") from exc
+
+
+def _dirty_tag(dirty: bool) -> str:
+    return "  [dirty]" if dirty else ""
+
+
+def _gate_line(v) -> str:
+    """One gate violation, however it was decided; verify and `rescore --gate`
+    report the same finding, so they must read the same."""
+    return (f"  GATE  crap {v.crap:8.1f}  ccn {v.ccn:>3} cov {v.cov:.0%}  "
+            f"{v.path}:{v.start}  {v.long_name}  -> {v.remedy}{_dirty_tag(v.dirty)}")
+
+
+def _latest_scored(store: SnapshotStore):
+    from ..store import default_baseline
+    return default_baseline(store)
+
+
+def _open_store(root: Path, first_command: str = "coverage") -> SnapshotStore:
+    db_path = root / ".crapkit" / "crap.sqlite"
+    if not db_path.is_file():
+        raise CrapkitError(f"no snapshot in {root} — run `crapkit {first_command}` first")
+    return SnapshotStore(db_path)
+
+
+def _ratchet_entries(root: Path, cfg) -> list | None:
+    """The committed marks, or None when the repo carries no marks file yet."""
+    from ..ratchet import load_ratchet
+
+    ratchet_path = root / cfg.ratchet_file
+    if not ratchet_path.is_file():
+        return None
+    return load_ratchet(ratchet_path.read_text(encoding="utf-8"))
+
+
+def _load_sources(root: Path, paths: set) -> dict:
+    sources = {}
+    for rel in paths:
+        p = root / rel
+        if p.is_file():
+            sources[rel] = p.read_text(encoding="utf-8", errors="replace")
+    return sources