Ratchet

Security scanner for AI-generated code. The public Ratchet CLI scans and scores code locally across six production-readiness categories.

Self-audit gate: CI requires an overall score of at least 95 and Security at 15/15 (we run Ratchet on itself).

$ ratchet scan

  🔧 Production Readiness: 89/100

  🧪 Testing         ████████████████       23/25
  🔒 Security        ███████████████████    15/15
  📝 Type Safety      ███████████████████    15/15
  ⚠️  Error Handling  ████████████          16/20
  ⚡ Performance      ████████               8/10
  📖 Code Quality     ████████              12/15

---

Quick Start

npm install -g ratchet-run
ratchet init        # Set up your project
ratchet scan        # Score your codebase
ratchet scan --explain-deductions   # See what cost you points

Installs the ratchet CLI. The npm package is named ratchet-run because ratchet was already taken on the registry.

More commands

Command	Description
ratchet scan	Score your codebase (free)
ratchet scan --explain-deductions	See exact files/lines costing points
ratchet map	Interactive quality and dependency map
ratchet graph	Dependency graph queries
ratchet report	Generate PDF/Markdown/JSON report
ratchet init	Initialize config
ratchet status	Check current run status
ratchet log	View run logs

---

What It Catches

Category	Weight	What It Finds
🔒 Security	15 pts	Hardcoded secrets, missing auth, unvalidated inputs, rate limiting gaps
🧪 Testing	25 pts	Coverage gaps, missing edge cases, weak assertions
📝 Type Safety	15 pts	any types, missing strict config, type escape hatches
⚠️ Error Handling	20 pts	Empty catches, missing try/catch, no structured logging
⚡ Performance	10 pts	await-in-loop, console.log in production, import bloat
📖 Code Quality	15 pts	Duplicated code, long functions, dead code, TODOs

---

How Pro Auto-Fix Works

Mutation commands are not included in the public/free CLI. They require the separately installed ratchet-pro package, which registers the Pro commands.

A ratchet wrench only turns one way. So does Ratchet:

1. Scan — Score your codebase across all 6 categories
2. Fix — AI identifies the highest-impact issue and writes a fix
3. Test — Runs your full test suite before committing
4. Commit — Only improvements that pass tests get kept
5. Repeat — Each "click" moves the score up. Failed fixes are reported and reverted.

$ ratchet improve --clicks 7

  ✓ Click 1 — removed hardcoded API key     [a3f9b21] — Score: 68 → 72 (+4)
  ✗ Click 2 — tests failed · rolled back
  ✓ Click 3 — added input validation        [7bc1d44] — Score: 72 → 76 (+4)
  ✓ Click 4 — replaced empty catch          [2e8f053] — Score: 76 → 79 (+3)
  ✗ Click 5 — tests failed · rolled back
  ✓ Click 6 — structured error logging      [9da3c17] — Score: 79 → 81 (+2)
  ✓ Click 7 — added rate limiting           [f81b44a] — Score: 81 → 82 (+1)

  Done. 5 landed · 2 rolled back · Score: 68 → 82/100 (+14)

---

Comparison

Feature	Ratchet	Semgrep	SonarQube	CodeQL	Biome
Local-first (no cloud upload)	✅	✅	❌	❌	✅
Auto-fix with test gate	Pro	❌	❌	❌	✅ (lint only)
AI-powered semantic analysis	Pro	❌	❌	❌	❌
Zero-config first run	✅	❌	❌	❌	✅
Open source core	✅	✅ (OSS edition)	❌	❌	✅
Self-audit CI gate (dogfood)	≥95/100	N/A	N/A	N/A	N/A
Node.js native	✅	❌ (Python)	❌ (Java)	❌ (OCaml)	✅

---

Privacy & Security

• Local-first. The public ratchet scan command runs entirely on your machine with no model-provider calls.
• Pro AI features are separate and opt-in. When ratchet-pro is installed, its AI commands use your configured provider and can send selected code context for analysis or mutation.
• No telemetry, ever. Ratchet itself has no servers that see your code.
• Open source core. MIT licensed. Audit the source at github.com/kcemate/ratchet.
• Self-auditing. CI runs Ratchet on Ratchet and fails below the documented score and Security gates.

---

Pricing

	Free	Pro
ratchet scan	✅	✅
AST autofix	—	✅
AI-powered fixes	—	✅
Deep scan	—	✅
ratchet improve	—	✅
GitHub Action	✅ (scan only)	✅ (scan only)

See ratchetcli.com for Pro pricing.

---

GitHub Action

The public Action performs one deterministic scan and can fail CI on total or per-category gates. It does not apply fixes or open pull requests.

name: Ratchet
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kcemate/ratchet@v1
        with:
          threshold: "90"
          category-thresholds: "Security=15,Testing=18"
          working-directory: "."
          version: "1.2.0"

Inputs include threshold, category-thresholds, explain, working-directory, version, and an optional prior baseline JSON path. Outputs include score, score-delta, json, and badge-url.

---

Architecture

Ratchet is a Commander CLI with a deterministic public scanner and an optional Pro plugin boundary:

• Public Classic engine (src/core/engines/classic.ts) — deterministic, local analysis scoring 0–100 across six weighted categories.
• Public GitHub Action (action.yml) — scan-only quality gates; it never applies fixes or opens pull requests.
• Pro plugin — deep analysis and mutation commands are registered only by a separately installed ratchet-pro package.

See docs/ARCHITECTURE.md for the full subsystem breakdown and data flow.

---

Development

git clone https://github.com/kcemate/ratchet.git
cd ratchet
npm ci
npm run build
npm link
npm test
npm run lint
npm run typecheck

See CONTRIBUTING.md for branching strategy, commit style, and how to add new scanners.

---

Links

• npm: ratchet-run
• GitHub: kcemate/ratchet
• License: MIT