deep-slop

Deep AI Slop Detection — 25 AST-Powered Engines, 211+ Rules

Detect AI-generated slop, dead code, security vulnerabilities, import problems, and architectural decay in your codebase. Tree-sitter AST analysis for 8 languages, density-aware scoring, SARIF 2.1.0 output, MCP server, 16 AI agent providers, and multi-language linting across 14 languages.

---

Why deep-slop?

AI coding assistants are fast — but they leave fingerprints: narrative comments, empty catch blocks, hallucinated imports, as any casts, copy-paste patterns, and silently swallowed errors. Traditional linters miss these because they weren't designed to detect AI-authored code quality decay.

deep-slop is purpose-built to find and fix AI slop with real AST analysis (tree-sitter), not regex hacks. It goes beyond AI-slop detection to cover security, dead code, type safety, architecture, performance, i18n, formatting, framework anti-patterns, and markup quality — 18 specialized engines, 181+ rules, one unified quality gate.

---

Quick Start

# Scan your project immediately — no install needed
npx deep-slop scan .

# SARIF output for GitHub Code Scanning
npx deep-slop scan . --sarif

# Scan only specific paths
npx deep-slop scan . --include "src/**/*.ts"

# Or install globally
npm install -g deep-slop
deep-slop scan .

Output includes a density-aware quality score (0–100), per-engine diagnostics, top findings, and actionable suggestions:

  deep-slop scanning: /home/user/my-project

  ⏳ ast-slop.............. ✅ 14 issues (120ms)
  ⏳ import-intelligence... ✅ 6 issues (85ms)
  ⏳ dead-flow............. ✅ 3 issues (45ms)
  ⏳ type-safety........... ✅ 2 issues (30ms)
  ⏳ syntax-deep........... ✅ 0 issues (20ms)
  ⏳ security-deep......... ✅ 1 issues (60ms)
  ⏳ arch-constraints...... ✅ 2 issues (35ms)
  ⏳ dup-detect............ ⏭️ skipped
  ⏳ perf-hints............ ✅ 1 issues (25ms)
  ⏳ i18n-lint............. ⏭️ skipped
  ⏳ config-lint........... ✅ 0 issues (10ms)
  ⏳ meta-quality.......... ✅ 1 issues (5ms)
  ⏳ knip................... ✅ 4 issues (150ms)
  ⏳ arch-rules............ ⏭️ no rules.yml
  ⏳ lint-external......... ⏭️ skipped
  ⏳ format-lint........... ✅ 3 issues (15ms)
  ⏳ framework-lint........ ✅ 5 issues (40ms)
  ⏳ markup-lint........... ✅ 2 issues (30ms)

  ▸ Top findings:
    1. ast-slop/narrative-comment   — src/utils.ts:42
    2. security-deep/hardcoded-secret — src/config.ts:12
    3. dead-flow/unreachable-after-terminator — src/handler.ts:88

  Score: 72/100 (Needs Work) | Errors: 3 | Warnings: 11 | Info: 16 | Suggestions: 0

---

Install

# npm
npm install -g deep-slop

# pnpm
pnpm add -g deep-slop

# yarn
yarn global add deep-slop

# One-off (no install)
npx deep-slop scan .

Requirements: Node.js >= 20

---

CLI Commands

Command	Description
scan [path]	Scan project for AI slop and quality issues
fix [path]	Auto-fix detected issues with AST-based safe transforms
ci [path]	CI mode — structured output with quality gate
rules	List, search, or show details for all 181+ rules
init [path]	Scaffold configuration and CI workflow
doctor [path]	Check environment for deep-slop compatibility
trend [path]	Show score trend across recent scans
watch [path]	Watch for file changes and auto-scan
hook	Manage hooks for AI coding tools (install/uninstall/status/baseline/audit/sentinel)
agent	AI agent-powered repair commands (repair/plan/use/sessions)
badge [path]	Generate a shields.io quality score badge
update	Check for and install deep-slop updates

deep-slop scan [path]

Scan a project directory for issues.

deep-slop scan .                                    # Full scan
deep-slop scan ./src                                # Scan specific directory
deep-slop scan . --json                             # JSON output
deep-slop scan . --sarif                            # SARIF 2.1.0 output (GitHub Code Scanning)
deep-slop scan . --include "src/**/*.ts"            # Include only matching files
deep-slop scan . --engine ast-slop type-safety      # Run specific engines
deep-slop scan . --exclude "**/*.test.ts"           # Exclude patterns
deep-slop scan . --severity warning                 # Only warnings and above
deep-slop scan . --changes                          # Only git-changed files
deep-slop scan . --staged                           # Only git-staged files
deep-slop scan . --base main                        # Compare against branch
deep-slop scan . --verbose                          # Verbose output with rule details

deep-slop fix [path]

Auto-fix detected issues with AST-based safe transforms.

deep-slop fix .                     # Fix all fixable issues
deep-slop fix . --engine ast-slop   # Fix only one engine's issues
deep-slop fix . --safe              # Only safe fixes (confidence >= 0.8)
deep-slop fix . --force             # Apply all fixes, including low-confidence
deep-slop fix . --dry-run           # Preview without modifying files

The fix pipeline: scan → collect fixable diagnostics → plan → apply → verify → re-scan. If verification fails, changes are rolled back automatically.

deep-slop ci [path]

CI mode — structured output with quality gate.

deep-slop ci .                      # Fail below default threshold (50)
deep-slop ci . --fail-below 70      # Custom threshold
deep-slop ci . --format sarif       # SARIF for GitHub Code Scanning
deep-slop ci . --format json        # JSON output
deep-slop ci . --changes            # Only changed files
deep-slop ci . --staged             # Only staged files

Exit code 1 if score is below threshold. Perfect for CI pipelines.

deep-slop rules

List and search all available rules.

deep-slop rules                     # List all rules
deep-slop rules --search unused     # Fuzzy search by name/description
deep-slop rules ast-slop/empty-catch # Show rule details with impact tier

deep-slop init [path]

Scaffold configuration and CI workflow.

deep-slop init .                    # Create .deep-slop/config.yml
deep-slop init . --preset typescript-strict   # From preset
deep-slop init . --strict           # Maximum strictness (enterprise preset)

deep-slop doctor [path]

Check which external tools are available (ruff, golangci-lint, clippy, knip, etc.).

deep-slop doctor .                  # Show toolchain coverage

deep-slop trend [path]

Show score history with sparklines.

deep-slop trend .                   # Show score trend
deep-slop trend . --limit 20        # Last 20 scans

deep-slop report [path]

Generate an HTML trend report with SVG charts, severity breakdown, and engine performance tables.

deep-slop report .                  # Generate report at ./deep-slop-report.html
deep-slop report . --output docs/report.html --limit 50

deep-slop watch [path]

Watch mode — re-scan on file changes.

deep-slop watch .                   # Watch and re-scan on changes

deep-slop hook

Manage git hooks and AI tool hooks for automated scanning.

deep-slop hook install              # Install pre-commit hook
deep-slop hook uninstall            # Remove pre-commit hook
deep-slop hook status               # Show hook status
deep-slop hook baseline             # Capture quality baseline
deep-slop hook audit                # Audit dependencies for vulnerabilities
deep-slop hook sentinel             # Run sentinel mode with auto-repair

Runtime hooks (full scan + fix): Claude, Cursor, Gemini, Pi Rules-only hooks (pass diagnostics as context): Codex, Windsurf, Cline, Kilo, Copilot, Antigravity

deep-slop agent

AI agent integration for automated repair.

deep-slop agent repair .                      # Start repair loop (default: Claude)
deep-slop agent repair . --provider codex     # Use Codex for repairs
deep-slop agent repair . --provider cursor    # Use Cursor for repairs
deep-slop agent repair . --target-score 80    # Target specific score
deep-slop agent plan .                        # Preview repair plan without applying
deep-slop agent use claude .                  # Set default provider for project
deep-slop agent sessions .                    # List all repair sessions

16 providers: claude, codex, cursor, opencode, aider, goose, windsurf, vscode, amp, gemini-cli, kimi, warp, pi, crush, deep-agents, antigravity

deep-slop badge [path]

Generate a shields.io quality score badge for your README.

deep-slop badge .                   # Output badge URL
deep-slop badge . --json            # JSON with URL + markdown
deep-slop badge . --owner Romanchello --repo deep-slop

deep-slop update

Self-update to the latest version.

deep-slop update                    # Check and install updates
deep-slop update --check            # Only check, do not install

---

The 25 Engines

1. ast-slop — AI Slop Pattern Detection (20+ rules)

Detects hallmarks of AI-authored code:

Rule	Severity	Description
empty-catch	strict	Empty catch blocks silently swallow errors
narrative-comment	strict	Comments that describe WHAT instead of WHY
hallucinated-import	standard	Imports from non-existent packages
as-any-cast	standard	as any casts disabling type safety
generic-naming	advisory	Variables like data, result, item, info
decorative-comment	style	Visual separator blocks (// ===, // ───)
console-leftover	style	Debug console.log/console.debug statements
trivial-comment	mechanical	Comments that restate the obvious
todo-leftover	mechanical	TODO comments with AI agent attribution
unnecessary-abstraction	maintainability	Overly ceremonial class/module patterns
silent-recovery	strict	Unnecessary try-catch wrapping that hides failures
hardcoded-config	standard	Configuration values baked into source
copy-paste-signature	mechanical	Copy-paste patterns differing only in identifiers
boilerplate-structure	mechanical	Overly ceremonial patterns (AI template signature)
ai-emoji-comment	style	Emoji in comments (common AI agent signature)
overly-defensive	advisory	Unnecessary null checks or defensive wrapping
todo-stub	mechanical	TODO/FIXME stubs left by AI agents
swallowed-exception	strict	Exceptions caught and silently discarded
...and more

2. import-intelligence — Import Path Optimization (7 rules)

Rule	Description
alternative-path	Suggest tree-shakeable imports (e.g., lodash/map instead of lodash)
barrel-optimization	Skip barrel files, import from source
circular-dependency	Detect import cycles in the dependency graph
unused-import	Imported but never referenced
duplicate-import	Multiple import statements from the same module
broken-alias	Path alias that doesn't map to an existing file
barrel-bypass	Direct import past barrel re-export

3. dead-flow — Unreachable & Unused Code (7 rules)

Rule	Description
unreachable-after-terminator	Code after return/throw/break
dead-conditional	Conditionals that always evaluate the same way
unused-export	Exported symbols with no consumers
unused-variable	Declared but never read (_-prefixed vars skipped)
empty-block	Empty if/for/while/try/catch blocks
dead-switch-case	Unreachable switch cases after default
dead-conditional	Logic errors or AI artifacts

4. type-safety — TypeScript Type Enforcement (6 rules)

Rule	Description
as-any-cast	as any casts with context-aware type suggestions
double-assertion	as unknown as X bypass patterns
ts-suppress	@ts-ignore and @ts-expect-error directives
non-null-assertion	! operator without null checks
generic-any	any used as generic parameter (Array<any>)
missing-return-type	Functions without explicit return types

5. syntax-deep — Syntax Anomaly Detection (12 rules)

BOM characters, CRLF line endings, mixed indentation, escape sequences, regex issues, floating-point precision loss, Unicode anomalies (zero-width spaces, RTL overrides, homoglyphs), trailing whitespace, NUL bytes, shebang mismatches, and leftover git merge conflict markers.

6. security-deep — Security Vulnerability Detection (10 rules)

Rule	Description
eval-usage	eval(), new Function(), vm.runInContext
innerhtml-usage	Direct innerHTML assignment (XSS risk)
sql-injection	String concatenation in SQL queries
shell-injection	Unsanitized exec()/spawn() arguments
ssrf-risk	Server-side request forgery patterns
prototype-pollution	Deep merge without prototype guard
hardcoded-secret	API keys, tokens, passwords in source
dependency-vulnerability	Known vulnerable dependencies
xss-risk	Cross-site scripting attack vectors
unsafe-html	Unsafe HTML operations

7. arch-constraints — Architecture Analysis (6 rules)

Rule	Description
circular-dependency	Module dependency cycles (via graphology)
high-coupling	High fan-in/fan-out modules
layer-violation	Imports that violate defined layer boundaries
god-file	Files concentrating too many responsibilities
deep-nesting	Excessive nesting depth (context-aware thresholds)
unstable-dependency	Fragile dependency patterns

8. dup-detect — Duplicate Code Detection (5 rules)

Identical AST subtrees, similar blocks (copy-paste with minor edits), duplicate imports across files, repeated constants, and copy-paste divergence patterns.

9. perf-hints — Performance Anti-Patterns (6 rules)

N+1 query patterns, missing React memoization (React.memo/useMemo/useCallback), synchronous operations in async context, large allocations in loops, unnecessary awaits, and string concatenation in loops.

10. i18n-lint — Internationalization Issues (4 rules)

Hardcoded strings in JSX/props, missing translation keys, locale mismatches across locale files, and untranslated strings.

11. config-lint — Configuration Validation (6 rules)

tsconfig issues, ESLint misconfig, package script problems, Prettier config, Vite config, and EditorConfig inconsistencies.

12. meta-quality — Scoring & Quality Gate (4 rules)

Score report quality, trend analysis/regression detection, quality gate enforcement, and config sanity checks.

13. knip — Unused Dependency/Export Detection

Integrates knip to find unused dependencies, unused exports, and dead code that the AST engines may miss.

14. arch-rules — Custom Architecture Rules

Load custom rules from .deep-slop/rules.yml:

rules:
  - id: forbid-lodash-default-import
    message: "Use specific lodash imports for tree-shaking"
    severity: warning
    pattern: "import _ from 'lodash'"
  - id: no-direct-api-from-ui
    message: "UI components must use service layer, not call API directly"
    severity: error
    forbid_import_from_path:
      from: "src/ui/**"
      import: "src/api/**"

15. lint-external — Multi-Language Linters

Wraps external linters for non-TypeScript code:

Language	Tool
Python	ruff
Go	golangci-lint
Rust	clippy

16. format-lint — Formatting Consistency (6 rules)

Detects formatting inconsistencies across all source files: mixed indentation, inconsistent quote style, max line length violations, inconsistent semicolons, blank line clusters, and trailing comma inconsistencies.

17. framework-lint — Framework-Specific Rules (15+ rules)

Framework-specific AI slop detection:

Next.js rules (8 rules): Misplaced use client, missing use client, Pages Router APIs in App Router, next/router vs next/navigation, missing Image dimensions, metadata in client components, hardcoded env vars, links without ARIA labels.

Tailwind CSS rules (7 rules): @apply anti-pattern, inline style conflicts, !important modifier, duplicate utilities, magic values, incomplete flex, overloaded className strings.

18. markup-lint — Markup & Config Quality (20+ rules)

Quality checks for non-source files:

JSON (4 rules): Trailing commas, duplicate keys, inconsistent spacing, deep nesting. YAML (4 rules): Tab indentation, duplicate keys, complex anchors, missing document separators. CSS (4 rules): Unused selectors, !important overuse, duplicate properties, universal selectors. HTML (4 rules): Missing alt on images, missing lang, deprecated tags, inline event handlers. Markdown (4 rules): Broken links, inconsistent heading styles, TODOs in docs, missing fenced language.

19. python-deep — Python-Specific Rules (11 rules)

Detects Python-specific anti-patterns using tree-sitter AST:

STRICT (2 rules): bare-except (bare except clause), mutable-default (mutable default argument). STANDARD (2 rules): global-variable (global keyword usage), star-import (from x import *). MAINTAINABILITY (3 rules): no-type-hint (parameter without type annotation), no-return-type (function without return type), broad-exception (except Exception/BaseException). MECHANICAL (3 rules): f-string-in-log (f-string in logging call), pass-stub (function with only pass), print-statement (print() in non-test code). ADVISORY (1 rule): missing-docstring (public function/class without docstring).

20. go-deep — Go-Specific Rules (9 rules)

Go idiomatic code analysis:

STRICT (2 rules): goto-usage (goto statement), package-cycle (circular imports). STANDARD (3 rules): unchecked-error (ignoring returned error), empty-interface (interface{} / any), defer-in-loop (defer inside loop). MAINTAINABILITY (2 rules): exported-no-doc (exported symbol without doc comment), context-missing (I/O function without context.Context). MECHANICAL (2 rules): deep-copy-missing (large struct by value), init-side-effect (init() with side effects).

21. rust-deep — Rust-Specific Rules (9 rules)

Rust safety and idiomatic analysis:

STANDARD (3 rules): unwrap-in-prod (.unwrap() in non-test code), todo-macro (todo!() left in code), unimplemented-macro (unimplemented!() left in code). MAINTAINABILITY (1 rule): large-enum-variant (disproportionately large enum variant). MECHANICAL (4 rules): clone-on-copy (.clone() on Copy type), wildcard-catch (catch-all _ in match), expect-in-prod (.expect() in non-test code), redundant-clone (clone before drop). ADVISORY (1 rule): unsafe-usage (unsafe block without safety comment).

22+. Plugin Engines

deep-slop supports custom plugin engines loaded from .deep-slop/plugins/. Plugins implement the same Engine interface as built-in engines and appear alongside them in scan output, scoring, and MCP tools.

See the Plugin API section for details.

---

Languages

deep-slop analyzes 14 languages with Tree-sitter AST support for 8:

Language	AST Analysis	Engines Active
TypeScript	✅ tree-sitter	All engines
JavaScript	✅ tree-sitter	All engines
TSX	✅ tree-sitter	All + framework-lint
JSX	✅ tree-sitter	All + framework-lint
Python	✅ tree-sitter	ast-slop, syntax-deep, security-deep, lint-external (ruff)
Go	✅ tree-sitter	ast-slop, syntax-deep, security-deep, lint-external (golangci-lint)
Rust	✅ tree-sitter	ast-slop, syntax-deep, lint-external (clippy)
PHP	✅ tree-sitter	ast-slop, syntax-deep, security-deep
C#	✅ tree-sitter	ast-slop, syntax-deep
Swift	✅ tree-sitter	ast-slop, syntax-deep
JSON	Text-based	markup-lint
YAML	Text-based	markup-lint, config-lint
CSS	Text-based	markup-lint, framework-lint (Tailwind)
HTML	Text-based	markup-lint
Markdown	Text-based	markup-lint

Score is withheld for projects where >80% of files are in unsupported languages.

---

Frameworks

Next.js

8 rules detecting common AI-authored Next.js anti-patterns:

• Misplaced or missing 'use client' directives
• Pages Router APIs in App Router projects
• next/router instead of next/navigation
• Missing <Image> dimensions causing layout shift
• Metadata exports in client components
• Hardcoded URLs instead of environment variables
• Links without accessible text

Tailwind CSS

7 rules catching AI-generated Tailwind slop:

• @apply negating utility-first approach
• Inline style conflicts with Tailwind classes
• !important modifier indicating specificity issues
• Duplicate/conflicting utilities in same className
• Arbitrary magic values instead of theme scale
• Bare flex without alignment (likely incomplete)
• Overloaded className strings needing extraction

---

Configuration

.deep-slop/config.yml

Create .deep-slop/config.yml in your project root:

# .deep-slop/config.yml

# ── Engine selection (all enabled by default) ──
engines:
  ast-slop: true
  import-intelligence: true
  dead-flow: true
  type-safety: true
  syntax-deep: true
  security-deep: true
  arch-constraints: true
  dup-detect: true
  perf-hints: true
  i18n-lint: false          # Disable for non-i18n projects
  config-lint: true
  meta-quality: true
  knip: true
  arch-rules: true
  lint-external: false      # Requires external tools installed
  format-lint: true
  framework-lint: true
  markup-lint: true

# ── Quality thresholds ──
quality:
  maxFunctionLoc: 50        # Max lines per function
  maxFileLoc: 300           # Max lines per file
  maxNesting: 4             # Max nesting depth
  maxParams: 5              # Max function parameters
  maxCyclomatic: 10         # Max cyclomatic complexity
  maxCoupling: 10           # Max fan-in/fan-out

# ── Context-aware complexity thresholds ──
# Rust: 2.5x, Go: 1.5x, TSX: 1.5x multiplier on maxCyclomatic

# ── Security settings ──
security:
  audit: true               # Run npm audit
  auditTimeout: 60          # Audit timeout in seconds
  owasp: true               # OWASP top-10 checks

# ── Import intelligence ──
imports:
  suggestAlternatives: true # Suggest tree-shakeable paths
  optimizeBarrels: true     # Flag barrel file imports
  validateAliases: true     # Check tsconfig path aliases
  buildGraph: true          # Build import dependency graph
  maxCircularDepth: 5       # Max circular dep depth

# ── Type safety ──
types:
  flagAsAny: true           # Flag `as any` casts
  suggestTypes: true        # Suggest concrete types
  flagDoubleAssertion: true # Flag `as unknown as X`

# ── Dead code ──
deadCode:
  unreachableBranches: true
  unusedExports: true
  unusedVariables: true     # _-prefixed vars skipped

# ── i18n ──
i18n:
  hardcodedStrings: true
  validateKeys: false       # Enable if you have locale files

# ── Scoring ──
scoring:
  mode: logarithmic         # logarithmic or linear
  failBelow: 50             # CI quality gate threshold

# ── Rule severity overrides ──
rules:
  ast-slop/generic-naming: off       # Turn off a rule
  security-deep/eval-usage: error    # Promote to error
  type-safety/missing-return-type: warning  # Demote to warning

# ── Exclude patterns ──
exclude:
  - node_modules
  - .git
  - dist
  - build
  - coverage
  - tmp-*

# ── CI quality gate ──
ci:
  failBelow: 50            # Fail if score below this threshold
  format: json             # Output format for CI
  failOnErrors: true       # Also fail on any error-level diagnostic

.deep-slopignore

Exclude files from scanning with a .deep-slopignore file (gitignore-style patterns):

# .deep-slopignore
node_modules/
dist/
*.min.js
*.d.ts
coverage/

Suppress Directives

Suppress specific rules inline in source files:

// deep-slop-ignore-next ast-slop/narrative-comment
// This comment explains WHY, not what — intentional
const result = compute(data);

// deep-slop-ignore-line ast-slop/generic-naming
const info = getData();

/* deep-slop-ignore-start ast-slop/console-leftover */
console.log('debug temp');
/* deep-slop-ignore-end ast-slop/console-leftover */

Directive forms: deep-slop-ignore-next, deep-slop-ignore-line, deep-slop-ignore-start / deep-slop-ignore-end

--include Option

Scan only specific file patterns:

deep-slop scan . --include "src/**/*.ts"
deep-slop scan . --include "src/**/*.ts" --include "lib/**/*.js"

Config Inheritance

Extend from presets or parent configs:

extends: typescript-strict   # Built-in preset name

# Override specific settings
quality:
  maxFileLoc: 400           # Relax from preset's 200

Custom Architecture Rules

Create .deep-slop/rules.yml:

rules:
  - id: no-business-logic-in-ui
    message: "Business logic must not live in UI components"
    severity: error
    forbid_import_from_path:
      from: "src/components/**"
      import: "src/services/**"

  - id: no-moment-js
    message: "Use date-fns instead of moment.js for tree-shaking"
    severity: warning
    forbid_import: "moment"

Presets

Preset	Description
typescript-strict	Strict scoring, all engines, error thresholds (failBelow: 80)
monorepo-relaxed	Relaxed for monorepos, excludes common monorepo paths (failBelow: 60)
python-go	Optimized for Python + Go — enables lint-external, disables config-lint
minimal	Only ast-slop + security-deep — lightweight scanning

deep-slop init . --preset typescript-strict
deep-slop init . --strict           # Enterprise preset (maximum strictness)

---

MCP Server

deep-slop ships a Model Context Protocol server for integration with AI coding agents (Claude Code, Cursor, Windsurf, Aider, etc.).

Setup

Add to your MCP client config (.cursor/mcp.json, .claude/settings.json, etc.):

{
  "mcpServers": {
    "deep-slop": {
      "command": "npx",
      "args": ["-y", "deep-slop-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "deep-slop": {
      "command": "deep-slop-mcp"
    }
  }
}

MCP Tools (7+ tools)

Tool	Description
deep_slop_scan	Full project scan with configurable engines, severity filtering, and assessment
deep_slop_fix	Auto-fix issues: scan → fix → verify → re-scan
deep_slop_why	Explain why a rule flagged specific code (impact tier, rationale, doc link)
deep_slop_engines	List all 18 engines and their rule counts
deep_slop_rules	List/search all 181+ rules with metadata (severity, tier, fixable)
deep_slop_score	Quick quality score check (fast, minimal output)
deep_slop_baseline	Check quality baseline before making changes

---

CI Integration

GitHub Actions Composite Action

Use deep-slop as a composite GitHub Action in your CI:

steps:
  - uses: DemumuMind/deep-slopDM@main
    with:
      directory: "."
      fail-below: "50"
      format: "sarif"
      node-version: "20"
      version: "latest"

Inputs:

Input	Default	Description
directory	.	Directory to scan
node-version	20	Node.js version
format	sarif	Output format (human, json, sarif)
fail-below	50	Fail if score below threshold (0–100)
version	latest	deep-slop CLI version

SARIF Upload to GitHub Code Scanning

- uses: DemumuMind/deep-slopDM@main
  with:
    format: sarif
    fail-below: "70"

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: deep-slop-results.sarif

SARIF 2.1.0 output integrates with GitHub code scanning.

init --strict Enterprise Preset

deep-slop init . --strict

Creates a strict configuration with failBelow: 80, all engines enabled, and error-level severity for security and architecture rules. Ideal for enterprise CI pipelines.

---

Agent Integration

deep-slop integrates with 16 AI agent providers for automated repair:

Provider	Flag	Type
Claude Code	--provider claude	Runtime (full scan + fix)
Codex	--provider codex	Runtime
Cursor	--provider cursor	Runtime
OpenCode	--provider opencode	Runtime
Aider	--provider aider	Runtime
Goose	--provider goose	Runtime
Windsurf	--provider windsurf	Runtime
VS Code	--provider vscode	Runtime
Amp	--provider amp	Runtime
Gemini CLI	--provider gemini-cli	Runtime
Kimi	--provider kimi	Runtime
Warp	--provider warp	Runtime
Pi	--provider pi	Runtime
Crush	--provider crush	Runtime
Deep Agents	--provider deep-agents	Runtime
Antigravity	--provider antigravity	Runtime

Repair Loop

deep-slop agent repair . --provider claude --target-score 80

The repair loop: scan → diagnose → prompt agent → apply fixes → re-scan → repeat until the target score is reached or max turns exhausted.

Agent Hooks

Runtime hooks (full scan + auto-fix): Claude, Cursor, Gemini, Pi Rules-only hooks (pass diagnostics as context to the agent): Codex, Windsurf, Cline, Kilo, Copilot, Antigravity

Auto PR with --pr

Create a pull request automatically after agent repair completes:

deep-slop agent repair . --provider claude --pr

---

Plugin API

deep-slop supports custom plugin engines loaded from .deep-slop/plugins/. Plugins implement the same Engine interface as built-in engines and appear alongside them in scan output, scoring, and MCP tools.

Plugin Structure

.deep-slop/
  plugins/
    my-engine/
      index.js      # Plugin entry point

Plugin Interface

interface Engine {
  name: string;                    // Unique engine identifier
  description: string;             // Human-readable description
  supportedLanguages: Language[];  // Languages this engine supports
  run(context: EngineContext): Promise<EngineResult>;
  fix?(diagnostics: Diagnostic[], context: EngineContext): Promise<FixResult>;
}

Creating a Plugin

// .deep-slop/plugins/my-engine/index.js
export const myEngine = {
  name: 'my-engine',
  description: 'Custom engine for project-specific checks',
  supportedLanguages: ['typescript', 'javascript'],
  async run(context) {
    const diagnostics = [];
    // Your analysis logic here
    return {
      engine: 'my-engine',
      diagnostics,
      elapsed: 0,
      skipped: false,
    };
  },
};

Plugins are auto-discovered and loaded after built-in engines. They can be enabled/disabled in .deep-slop/config.yml just like built-in engines:

engines:
  my-engine: true   # Enable custom plugin

---

---

Pre-commit Hook

Add deep-slop as a pre-commit hook:

repos:
  - repo: https://github.com/DemumuMind/deep-slopDM
    rev: v1.6.0
    hooks:
      - id: deep-slop

Or install via the CLI:

deep-slop hook install

---

Scoring System

deep-slop uses a density-aware logarithmic scoring system (0–100 scale):

score = 100 - (100 × log1p(scaledDeduction)) / log1p(100 + scaledDeduction)

Where:

• density = min(1, actionable_issues / (file_count + smoothing))
• scaledDeduction = totalDeduction × density
• totalDeduction = sum(severityWeight × ruleMultiplier × engineWeight)
• Per-rule caps prevent noisy rules from dominating the score
• Context-aware complexity thresholds: Rust 2.5×, Go 1.5×, TSX 1.5× on maxCyclomatic
• tsconfig path aliases are respected for import resolution
• _-prefixed unused variables are skipped

Impact Tiers

Each rule is classified into one of 6 tiers:

Tier	Multiplier	Cap	Example Rules
strict	1.0×	40	Empty catch, eval usage, hardcoded secrets, circular deps
standard	1.0×	30	Hallucinated imports, as-any casts, broken aliases
maintainability	0.75×	24	High coupling, layer violations, N+1 queries
mechanical	0.5×	16	Unused imports, trailing whitespace, BOM characters
style	0.5×	8	Decorative comments, console leftovers, precision loss
advisory	0.25×	8	Generic naming, missing React memo, hardcoded strings

Score Labels

Score	Label
>= 75	Healthy
>= 50	Needs Work
< 50	Critical

Severity Weights

Severity	Weight
error	10
warning	3
info	1
suggestion	0.25

---

Programmatic API

import { runScan, DEFAULT_CONFIG, type ScanResult } from "deep-slop";

const result: ScanResult = await runScan({
  rootDirectory: "/path/to/project",
  languages: ["typescript"],
  frameworks: ["react"],
  files: ["src/index.ts"],
  installedTools: {},
  config: DEFAULT_CONFIG,
});

console.log(`Score: ${result.score}/100 (${result.label})`);
console.log(`Errors: ${result.bySeverity.error}`);
console.log(`Warnings: ${result.bySeverity.warning}`);

---

deep-slop vs aislop

Feature	aislop	deep-slop
Detection engines	6	18
Analysis method	Regex-based	AST (tree-sitter)
Total rules	13	181+
AI slop rules	13	20+
Alternative import paths	No	Yes — tree-shakeable suggestions
Type safety analysis	No	Yes — as any, double assertions, @ts-ignore
Dead code flow	Via knip	AST-native — unreachable, unused exports/variables
Architecture analysis	Basic	Yes — circular deps, coupling, layer violations, god files
Duplicate code detection	No	Yes — structural + copy-paste patterns
Performance hints	No	Yes — N+1, memoization, sync-in-async
i18n linting	No	Yes — hardcoded strings, missing keys, locale mismatches
Config validation	No	Yes — tsconfig, ESLint, Vite, Prettier, EditorConfig
Framework rules	No	Yes — Next.js (8), Tailwind CSS (7)
Formatting consistency	No	Yes — indent, quotes, semicolons, trailing commas
Markup quality	No	Yes — JSON, YAML, CSS, HTML, Markdown
Custom architecture rules	Yes (rules.yml)	Yes (rules.yml with matchers)
Plugin API	No	Yes — custom engines from .deep-slop/plugins/
MCP Server	4 tools	7+ tools (scan, fix, why, engines, rules, score, baseline)
Scoring	Density-aware logarithmic	Density-aware logarithmic + per-rule caps
Impact tiers	6 tiers	6 tiers (strict → advisory)
Auto-fix pipeline	Plan → apply → verify	Plan → apply → verify → rollback
SARIF output	Yes	Yes — SARIF 2.1.0 for GitHub Code Scanning
Score withheld (unsupported lang)	No	Yes — null score when >80% unsupported
Editor extension	No	Yes — Problems panel + auto-scan
GitHub Action	Yes	Yes — composite action with SARIF upload
Pre-commit hook	Yes	Yes
Config presets	No	4 presets + --strict enterprise
Config inheritance	Yes (extends)	Yes (extends)
Rule severity overrides	Yes	Yes — per-rule error/warning/info/off
Suppress directives	No	Yes — next/line/start/end
Score badge	Yes	Yes
Score history	Yes (trend)	Yes (trend + sparklines)
Watch mode	No	Yes — re-scan on file changes
Multi-language linting	oxlint, ruff, golangci-lint, clippy, rubocop	ruff, golangci-lint, clippy
AI agent providers	16 flags	16 providers + repair loop + sessions
Agent --pr auto PR	No	Yes
Context-aware thresholds	No	Yes — Rust 2.5×, Go 1.5×, TSX 1.5×
tsconfig alias support	No	Yes — path aliases respected
_-prefixed unused vars	Not skipped	Skipped
Self-update	No	Yes — deep-slop update
Top findings section	No	Yes — most impactful issues highlighted
Pattern docs	No	Yes — bad/good examples per rule

---

Performance

Metric	Value
Self-scan time	~2s (18 engines, 100+ files)
Package size	282KB tarball
Memory usage	~45MB peak
Cold start	~300ms (with tree-sitter)
Test suite	197 tests, all passing
Type-check	0 TS errors

---

Self-Scan

deep-slop runs on itself. The self-scan score is captured by pnpm scan and written to the project's history. We practice what we preach — our own codebase is scanned and scored by deep-slop, and we use it to continuously improve code quality.

---

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Type-check
pnpm typecheck

# Run tests
pnpm test

# Scan the project itself
pnpm scan

# JSON output
pnpm scan:json

---

Contributing

See CONTRIBUTING.md for detailed guidelines, or:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes and add tests
4. Run the test suite (pnpm test)
5. Ensure the project type-checks (pnpm typecheck)
6. Scan for slop (pnpm scan) — we hold ourselves to the same standard
7. Commit with a descriptive message
8. Open a pull request

Adding a new rule:

1. Add the rule to the appropriate engine in src/engines/<engine>/index.ts
2. Add rule impact classification in src/scoring/rule-impact.ts
3. Add display label in src/output/rule-labels.ts
4. If fixable, add to FIXABLE_RULES in src/engines/catalog.ts
5. Add tests in src/engines/<engine>/index.test.ts

Adding a new engine:

1. Create src/engines/<name>/index.ts implementing the Engine interface
2. Register in src/engines/orchestrator.ts
3. Add to src/types/index.ts EngineName type
4. Add preset entries in src/config/presets.ts
5. Add engine info in the MCP deep_slop_engines tool

---

License

MIT © Romanchello 2026

---

Report Bug · Request Feature · npm · GitHub Action · Contributing