slop-doctor

slop-doctor scans a repository and scores the kinds of decay that agents tend to amplify: dead artifacts, duplicate truth, toxic context, architecture drift, and design-system bypass.

Install

npx -y slop-doctor@latest .

Usage

slop-doctor .
slop-doctor . --json
slop-doctor . --score
slop-doctor . --diff main
slop-doctor . --project @acme/web
slop-doctor . --fail-on critical
slop-doctor . --progress plain
slop-doctor explain js/design-system-bypass

Runtime Contract

• Advisory-first by default: findings do not cause a non-zero exit unless --fail-on is set.
• Runtime or tooling failures do cause a non-zero exit.
• Node.js 20+ is supported.
• When tool-backed rules degrade, the CLI reports degraded coverage instead of pretending the repo is clean.
• Progress rendering stays on stderr; use --progress plain or SLOP_DOCTOR_PROGRESS=plain for agent/CI-friendly step logs.
• --diff and --project focus the report and score on the selected changed files or workspace paths while preserving full-repo detector context.

GitHub Actions

- uses: actions/checkout@v5
  with:
    fetch-depth: 0
- uses: noahphan/slop-doctor@main
  with:
    diff: main
    fail-on: high
    github-token: ${{ secrets.GITHUB_TOKEN }}

The action outputs a score and can update a pull request comment when github-token is provided.

Node.js API

import { scanRepository } from "slop-doctor/api";

const result = await scanRepository({
  repoPath: ".",
  includeRuleIds: null,
  excludeRuleIds: new Set(),
  enableDocs: true,
  enableJs: true,
});

What It Flags

• Orphaned JS/TS artifacts
• Duplicate code and duplicated visual primitives
• Circular dependencies and oversized files
• Oversized or contradictory root docs
• Pages that bypass shared design primitives or tokens

Limitations

• No autofix or rewrite engine
• No hosted service
• No interactive workspace picker yet