{
  "markdown": "# claude-crap\n\n[![npm version](https://img.shields.io/npm/v/claude-crap.svg)](https://www.npmjs.com/package/claude-crap)\n[![CI](https://github.com/ahernandez-developer/claude-crap/actions/workflows/ci.yml/badge.svg)](https://github.com/ahernandez-developer/claude-crap/actions/workflows/ci.yml)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)\n[![Bun](https://img.shields.io/badge/bun-%3E%3D1-black.svg)](https://bun.sh/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n> **Deterministic Quality Assurance plugin for Claude Code.**\n> Forces the agent through mathematical hooks, CRAP / TDR thresholds,\n> and SARIF 2.1.0 reports before a single line of code is allowed to\n> ship.\n\n`claude-crap` turns Claude Code into a disciplined QA engineer. It\nwraps every `Write`, `Edit`, and `Bash` call with a synchronous\n**PreToolUse gatekeeper**, a retrospective **PostToolUse verifier**,\nand a final **Stop quality gate** that refuses to close a task until\nmaintainability, reliability, and security ratings pass policy.\n\nEvery decision that touches source code must be backed by a result\nfrom the deterministic MCP engines — `compute_crap`, `compute_tdr`,\n`analyze_file_ast`, `ingest_sarif`, `score_project`, and others.\nThis is the **Fat Platform / Thin Agent** thesis: the LLM is an\nefficient worker, but the rails are mathematical and outside the\nmodel's reach.\n\n> **CRAP** stands for **Change Risk Anti-Patterns** — a metric\n> originally developed by Alberto Savoia and Bob Evans at Google (2007).\n> [Read the original post.](https://testing.googleblog.com/2011/02/this-code-is-crap.html)\n\n[Quick Start](#quick-start) · [Configuration](#configuration) · [How It Works](#how-it-works) · [MCP Tools](#mcp-tools) · [Documentation](#documentation) · [Contributing](#contributing)\n\n---\n\n## Quick Start\n\n```bash\nnpx claude-crap install\n```\n\nThis downloads the package, compiles `dist/` from source, creates\n`.claude-crap/reports/` in your project, and prints the Claude Code\ncommand to register the plugin:\n\n```\n  Next steps — pick ONE of the following:\n\n  1. Native install:\n       /plugin install /.../claude-crap\n\n  2. Marketplace install:\n       /plugin marketplace add https://github.com/ahernandez-developer/claude-crap\n       /plugin install claude-crap@herz\n```\n\nOnce registered, open any new session. The **SessionStart** hook\nprints a briefing with thresholds and the dashboard URL. From that\npoint the PreToolUse gatekeeper and Stop quality gate run\nautomatically — no further setup required.\n\n---\n\n## Configuration\n\n> **Default: `warn`.** No config file needed. The Stop gate\n> shows all violations but lets tasks close. Teams that want\n> hard enforcement can set `\"strict\"` in `.claude-crap.json`.\n\nThe `strictness` value controls how the Stop gate reacts to failures:\n\n| Mode       | Stop exit | Effect                                                         |\n| :--------- | :-------: | :------------------------------------------------------------- |\n| `strict`   |    `2`    | Task cannot close until rules pass.                            |\n| `warn`     |    `0`    | Full verdict visible to agent, but task closes. **Default.**   |\n| `advisory` |    `0`    | Single-line nudge only.                                        |\n\nOverride per workspace:\n\n```jsonc\n// .claude-crap.json — commit to git for team-wide policy\n{\n  \"strictness\": \"strict\"\n}\n```\n\nOr per session: `CLAUDE_CRAP_STRICTNESS=strict claude`\n\n**Precedence:** env var > `.claude-crap.json` > hardcoded `warn`.\n\nSee [docs/quality-gate.md](./docs/quality-gate.md) for the full\nCRAP formula, TDR formula, letter ratings, and adoption strategy.\n\n---\n\n## How It Works\n\n| Component | File | Role |\n| :-------- | :--- | :--- |\n| **PreToolUse gatekeeper** | `plugin/hooks/pre-tool-use.mjs` | Blocks sensitive paths, destructive Bash, hardcoded secrets, path traversal — `exit 2` injects the corrective message into the agent's context. |\n| **PostToolUse verifier** | `plugin/hooks/post-tool-use.mjs` | Warns on missing test harness, suppression markers (`eslint-disable`, `@ts-ignore`, `# nosec`), and TODO/FIXME/HACK. |\n| **Stop quality gate** | `plugin/hooks/stop-quality-gate.mjs` | Reads the SARIF store, computes CRAP / TDR / reliability / security ratings, and blocks task close if any metric is outside policy. |\n| **MCP server** | `src/index.ts` | Stdio-transport server exposing CRAP, TDR, tree-sitter AST, and SARIF engines as deterministic tools. |\n| **SARIF store** | `src/sarif/sarif-store.ts` | On-disk consolidated report with finding deduplication. Tolerates malformed entries so a tampered file can't DoS the boot. |\n| **Scanner adapters** | `src/adapters/` | ESLint, Semgrep, Bandit, Stryker, `dart analyze`, `dotnet format` — each stamps `effortMinutes` for uniform TDR computation. |\n| **Project map** | `src/monorepo/project-map.ts` | Auto-discovers monorepo sub-projects at boot, persists to `.claude-crap/projects.json`. |\n| **Dashboard** | `src/dashboard/server.ts` | Fastify on `127.0.0.1:5117` serving a Vue 3 SPA. Offline-capable (vendored runtime). PID-based port management. |\n\nAll findings are normalized to **SARIF 2.1.0** — one vocabulary,\nexact coordinates, no grep walls in the context window.\n\nSee [docs/architecture-overview.md](./docs/architecture-overview.md)\nfor the boot sequence, data flow, and design decisions.\n\n---\n\n## MCP Tools\n\nTen deterministic tools and two resources, all with strict JSON Schema validation.\n\n| Tool | Purpose |\n| :--- | :------ |\n| `compute_crap` | CRAP index for a single function + block verdict against threshold. |\n| `compute_tdr` | Technical Debt Ratio and A..E maintainability rating. |\n| `analyze_file_ast` | Tree-sitter AST metrics: LOC + per-function cyclomatic complexity. TypeScript, JavaScript, Python, Java, C#. |\n| `ingest_sarif` | Merge a raw SARIF 2.1.0 document into the store with deduplication. |\n| `ingest_scanner_output` | Route native scanner output through adapter, enrich with `effortMinutes`, persist as SARIF. Supports ESLint, Semgrep, Bandit, Stryker, `dart_analyze`, and `dotnet_format`. |\n| `require_test_harness` | Check whether a source file has an accompanying test file. |\n| `score_project` | Aggregate workspace into A..E grades. Optional `scope` parameter to score a single monorepo sub-project. |\n| `auto_scan` | Auto-detect scanners (including monorepo subdirectories), run them, ingest findings. |\n| `bootstrap_scanner` | Detect project type, install the right scanner, configure, and verify. |\n| `list_projects` | List all discovered monorepo sub-projects with type, scanner, and availability. |\n\n| Resource | Description |\n| :------- | :---------- |\n| `sonar://metrics/current` | Live CRAP / TDR / rating snapshot. |\n| `sonar://reports/latest.sarif` | Consolidated SARIF document. |\n\nFull schemas, inputs, outputs, and examples in\n[docs/mcp-tools.md](./docs/mcp-tools.md).\n\n---\n\n## System Requirements\n\n- **Node.js >= 20** — the only runtime. No .NET, JDK, or Python.\n- **Bun >= 1.0** also works (`bun run build`, `bun test`).\n- **Claude Code** with local plugin support.\n- **Zero native deps** — WASM-backed tree-sitter, no C compiler needed.\n\nWindows: requires a POSIX shell (Git Bash or WSL).\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for Windows setup details.\n\n---\n\n## Supported Languages & Scanners\n\n| Language | Extensions | AST analysis | Scanner | Setup |\n| :------- | :--------- | :----------: | :------ | :---- |\n| TypeScript | `.ts` `.tsx` `.mts` `.cts` | Cyclomatic complexity | ESLint | **Auto-installed** via npm |\n| JavaScript | `.js` `.jsx` `.mjs` `.cjs` | Cyclomatic complexity | ESLint | **Auto-installed** via npm |\n| Python | `.py` `.pyi` | Cyclomatic complexity | Bandit | `pip install bandit` |\n| Java | `.java` | Cyclomatic complexity | Semgrep | `brew install semgrep` |\n| C# / .NET | `.cs` | Cyclomatic complexity | `dotnet format` | **Included in .NET SDK** |\n| Dart / Flutter | `.dart` | LOC only | `dart analyze` | **Included in Dart/Flutter SDK** |\n| Vue | `.vue` | LOC only | ESLint (via root config) | Auto with TypeScript |\n| Go | `.go` | LOC only | — | — |\n| Rust | `.rs` | LOC only | — | — |\n| Ruby | `.rb` | LOC only | — | — |\n| PHP | `.php` | LOC only | — | — |\n| Swift | `.swift` | LOC only | — | — |\n| Kotlin | `.kt` | LOC only | — | — |\n| Scala | `.scala` | LOC only | — | — |\n\n**AST analysis** = tree-sitter cyclomatic complexity per function.\n**LOC only** = counted toward workspace metrics but no per-function analysis.\n\n### Monorepo auto-discovery\n\nIn monorepos, claude-crap automatically discovers sub-projects at\nsession startup — no per-project configuration needed. The plugin\nprobes npm workspaces and common directories (`apps/`, `packages/`,\n`libs/`, `modules/`, `services/`) to build a **project map**:\n\n```\nSession start\n  → discover project map\n  → detect sub-projects by type (TypeScript, Dart, C#, Python, etc.)\n  → install missing scanners (ESLint auto-installed via npm)\n  → run each scanner from its project directory\n  → aggregate all findings into one SARIF store\n  → score_project ready with real data\n```\n\nThe project map is persisted to `.claude-crap/projects.json` and\nexposed via the `list_projects` MCP tool. Use `score_project` with\nthe optional `scope` parameter to score a single sub-project:\n\n```ts\n// Score only one sub-project\nscore_project({ format: \"both\", scope: \"frontend\" })\n```\n\nSee [docs/supported-languages.md](./docs/supported-languages.md) for\ndetailed per-language setup and behavior.\n\n**File exclusions** are centralized and cover all major frameworks\nout of the box: `dist/`, `build/`, `bundle/`, `vendor/`,\n`.next`, `.nuxt`, `.astro`, `.svelte-kit`, `.dart_tool`,\n`.expo`, `.angular`, `.turbo`, and more. Custom exclusions can be\nadded via `.claude-crap.json`:\n\n```jsonc\n{\n  \"strictness\": \"strict\",\n  \"exclude\": [\"apps/legacy/\", \"generated/\", \"*.proto.ts\"]\n}\n```\n\n---\n\n## Documentation\n\n| Section | Link |\n| :------ | :--- |\n| Supported languages & scanners | [docs/supported-languages.md](./docs/supported-languages.md) |\n| Architecture & boot sequence | [docs/architecture-overview.md](./docs/architecture-overview.md) |\n| Quality gate math (CRAP, TDR, ratings) | [docs/quality-gate.md](./docs/quality-gate.md) |\n| Project score aggregation | [docs/scoring.md](./docs/scoring.md) |\n| Hooks reference | [docs/hooks.md](./docs/hooks.md) |\n| MCP tools & resources | [docs/mcp-tools.md](./docs/mcp-tools.md) |\n| Scanner adapters | [docs/scanner-adapters.md](./docs/scanner-adapters.md) |\n| SDK reference | [docs/sdk.md](./docs/sdk.md) |\n| Contributing & dev loop | [CONTRIBUTING.md](./CONTRIBUTING.md) |\n| Agent contract | [plugin/CLAUDE.md](./plugin/CLAUDE.md) |\n| Changelog | [CHANGELOG.md](./CHANGELOG.md) |\n\n---\n\n## Bug Reports\n\n```bash\nnpx claude-crap bug-report    # writes claude-crap-bug-report-<ts>.md\nnpx claude-crap bug-report --stdout\n```\n\nCollects plugin version, Node/npm/platform info, doctor output,\nSARIF summary, and resolved env vars (secrets auto-redacted).\nReview the output, then open an issue at\n[github.com/ahernandez-developer/claude-crap/issues](https://github.com/ahernandez-developer/claude-crap/issues).\n\n---\n\n## Contributing\n\nclaude-crap welcomes PRs — **including AI-assisted ones.** The plugin is built\nfor AI-assisted development and dog-foods its own quality gate, so Codex /\nClaude Code / Cursor / Copilot diffs are first-class contributions. All we ask\nis transparency and the Golden Rule: **no production code without a test.**\n\nQuick version:\n\n1. Fork and branch off `main`.\n2. **Write the test first** — the Golden Rule forbids code before a safety net.\n3. Run `npm test` — full suite must stay green.\n4. Open a PR using the [rigid deduction format](./plugin/CLAUDE.md) and\n   describe the user-visible change in the PR body.\n5. If AI-assisted, mark the PR and include the agent/model + testing level.\n\n**Do not** bump the `package.json` version or edit `CHANGELOG.md` — version\nbumps, release notes, and npm publishes are handled by the maintainer\n([@ahernandez-developer](https://github.com/ahernandez-developer)) at release\ntime.\n\nFull dev loop, test layout, coding conventions, release process, the\nAI-assisted PR checklist, and security reporting are all in\n[CONTRIBUTING.md](./CONTRIBUTING.md).\n\n---\n\n## License\n\nMIT. See [LICENSE](./LICENSE). Copyright (c) 2026 Alan Hernandez.\n",
  "bytes": 12357,
  "sha": "d9124f0a90851b50df2b5a1ffe53a3ef9d8fb1001d59c6433b7d8b366e4890fc",
  "repo_slug": "ahernandez-developer/claude-crap",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ahernandez_developer_claude_crap_claude__00bab5ad/readme"
}