crap-gate

Files (20)

• SKILL.md
• crap.py
• crap_config.py
• crap_coverage.py
• crap_git.py
• crap_model.py
• crap_python.py
• crap_report.py
• crap_score.py
• crap_typescript.mjs
• crap_typescript.py
• run.sh
• test_cli.py
• test_config.py
• test_coverage.py
• test_git.py
• test_launcher.py
• test_python.py
• test_score.py
• test_typescript.py

SKILL.md (first lines)

# crap-gate — untested complexity is the thing you may not add

`CRAP(f) = CC(f)² · (1 − cov(f))³ + CC(f)`. One number per function: how much
complexity did this change add that tests do not verify. A CC-2 helper passes
untested; a CC-9 function needs 100 % coverage; a CC-40 function fails even
when fully tested (CRAP ≥ CC always). Thresholds come from the project's
`.crap-gate.json` (defaults: existing changed function > 15 fails, new
function > 9 fails). There are no pragmas and no allow-lists — the only bypass
is the human approval gate at push time.

## Running the engine

Use the bundled launcher on macOS or Linux (x86_64/ARM64; Windows via WSL).
It downloads checksum-verified uv 0.12.13 and provisions private Python 3.13.7
on first use, then reuses them across repositories. No global Python, uv,
virtualenv activation, or pip installation is needed. The engine uses only
Python's standard library and supports Python source syntax through 3.13.
Run from anywhere inside the repo — it walks up to `.crap-gate.json`:

```bash
sh "<skill-dir>/run.sh"            # human table, exit 1 on violations
sh "<skill-dir>/run.sh" --json     # same data for a subagent prompt
sh "<skill-dir>/run.sh" --no-run   # reuse the last coverage reports
sh "<skill-dir>/run.sh" --all      # whole-repo baseline (exploration only)
sh "<skill-dir>/run.sh" --base main --threshold-new 7   # local what-ifs
```

`<skill-dir>` is wherever this skill is installed (`.agents/skills/crap-gate`,
`~/.my-skills/crap-gate`, …). Projects usually
wrap it (`make crap`); prefer the wrapper when one exists.

When you point a wrapper at an agent symlink, that symlink only exists after
`skills-cli sync` if the matching agent is declared for the skill in
`.my-skills.json` — `claude` → `.claude/skills/crap-gate`, `opencode` →
`.agents/skills/crap-gate`. A wrapper that runs `.agents/skills/crap-gate/run.sh`
therefore needs `"agents": ["opencode"]` (or `["claude", "opencode"]`) on the
`crap-gate` entry, or a fresh checkout/worktree will lack that path after `sync`.
The store copy `.my-skills/crap-gate/run.sh` is always materialized regardless
of declared agents, so wrapping against it avoids the agent/path coupling
entirely.

Existing `make crap` / `make crap-gate` wrappers must replace `python3 .../crap.py`
with `sh .../run.sh` (quote the path). Prefer the store path, for example:

```makefile
crap crap-gate:
	sh "$(CURDIR)/.my-skills/crap-gate/run.sh"
```

The launcher needs standard shell utilities, `curl`, `tar`, and `sha256sum`
or `shasum`. Its cache defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/crap-gate`;
set `CRAP_GATE_CACHE_DIR` to an absolute path to relocate it. To pre-provision,
run the launcher with `--help` while online. `CRAP_GATE_OFFLINE=1` then requires
that populated cache and prevents runtime downloads. Runtime setup messages go
to stderr; `--json` returns a structured error on setup failure, with exit 2.
Do not bypass the gate or repair global Python when setup fails; resolve the
reported download/cache problem and rerun the launcher.

TypeScript targets still need `node` and the project's own `typescript` package.
Coverage commands still need the project's test dependencies; configure them
with its normal runner (for example, `cd backend && pipenv run pytest ...`).
The launcher preserves PATH and the caller's environment for these commands;
its private Python is only for the gate engine. One exception: when no
virtualenv is active and the repo root has `.venv/bin`, that directory goes
first on PATH, so a bare `python -m coverage` reaches the project's
interpreter. It does not install project dependencies or edit project
environments. When a command writes no report, the error ends with the last
lines of its log.

By default the engine runs each target's coverage command only when that
target has changed files, so a backend-only change never runs the frontend
suite. Coverage command output goes to `.crap/<target>.log`.

Reading a line:

```
FAIL  backend/routers/stock.py:120  get_pe_history  CC 22  cov 0%  CRAP 506.0  limit 15 (existing)  → split to CC ≤ 3
```

The hint is the cheapest way out: `cover ≥ N%` when tests alone can fix it,
`split to CC ≤ k` when the function is too complex to pass at its current
coverage, both when both work. `Not measured:` lists changed code files that
no target covers (never a failure, never silent).

## Project setup (once per repository)

Create `.crap-gate.json` at the repo root:

```json
{
  "thresholds": { "existing": 15, "new": 9 },
  "base": "origin/main",
  "targets": [
    {
      "name": "backend",
      "paths": ["backend/**/*.py"],
      "exclude": ["backend/tests/**"],
      "complexity": { "tool": "python" },
      "coverage": {
        "format": "coverage.py",
        "root": "backend",
        "report": "backend/.crap/coverage.json",
        "command": "cd backend && pytest --cov=src --cov-report=json:.crap/coverage.json -q"
      }
    },
    {
      "name": "frontend",
      "paths": ["frontend/src/**/*.ts", "frontend/src/**/*.tsx"],
      "exclude": ["frontend/src/**/*.test.*"],
      "complexity": { "tool": "typescript", "cwd": "frontend" },
      "coverage": {
        "format": "istanbul",
        "report": "frontend/coverage/coverage-final.json",
        "command": "cd frontend && vitest run --coverage --coverage.reportOnFailure=true"
      }
    }
  ]
}
```

From jesdi/general-skills, MIT.

More from jesdi/general-skills