Documentation

Everything the CLI accepts, everything it emits, and how to wire it into an autonomous coding agent's loop. SlopGuard is alpha (v0.1). The JSON schema is versioned and stable (shared across languages), but flags may still move before v1.0.

Overview

wCRAP(m) = (cyc × cog) × (1 − cov/100)³ + sqrt(cyc × cog)

wCRAP(m) = (cyc × cog) × (1 − cov/100)³ + sqrt(cyc × cog)

wCRAP(m) = (cyc × cog) × (1 − cov/100)³ + sqrt(cyc × cog)

wCRAP(m) = (cyc × cog) × (1 − cov/100)³ + sqrt(cyc × cog)

wCRAP(m) = (cyc × cog) × (1 − cov/100)³ + sqrt(cyc × cog)

Install

git clone https://github.com/JeevanThandi/SlopGuard-Swift.git
cd SlopGuard-Swift
swift build -c release
cp .build/release/slopguard-swift /usr/local/bin

git clone https://github.com/JeevanThandi/slopguard-typescript.git
cd slopguard-typescript
npm install && npm run build
npm link        # exposes slopguard-ts on your PATH

go install github.com/JeevanThandi/slopguard-go/cmd/slopguard-go@latest

git clone https://github.com/JeevanThandi/slopguard-go.git
cd slopguard-go
go build -o slopguard-go ./cmd/slopguard-go
cp slopguard-go /usr/local/bin

git clone https://github.com/JeevanThandi/slopguard-kotlin.git
cd slopguard-kotlin
./gradlew :app:installDist
# launcher: app/build/install/slopguard-kotlin/bin/slopguard-kotlin
export PATH="$PWD/app/build/install/slopguard-kotlin/bin:$PATH"

pip install slopguard-python

git clone https://github.com/JeevanThandi/slopguard-python.git
cd slopguard-python
pip install .

Quickstart

# Zero-config: analyze the current directory (drives xcodebuild test for coverage)
slopguard-swift

# Scan a specific directory and print the top crappy methods
slopguard-swift analyze --path Sources --threshold 30

# iOS app: pick a scheme and destination
slopguard-swift analyze --path . --scheme MyApp --destination 'platform=iOS Simulator,name=iPhone 16'

# CocoaPods-style project: point xcodebuild at the workspace explicitly
slopguard-swift analyze --path . --workspace MyApp.xcworkspace --scheme MyApp

# Full JSON for CI / downstream tooling
slopguard-swift analyze --path Sources --json | jq '.methods | sort_by(-.crap)[:10]'

# Fail CI when any method's CRAP exceeds 50
slopguard-swift analyze --path Sources --fail-over 50

# Complexity only (skip the test build; every method shows 0% coverage)
slopguard-swift analyze --path Sources --no-coverage

# Zero-config: analyze the current directory (detects vitest/jest, runs it for coverage)
slopguard-ts

# Scan a specific directory and print the top crappy methods
slopguard-ts analyze --path src --threshold 30

# Skip runner auto-detection: name the framework to drive
slopguard-ts analyze --path src --runner vitest
slopguard-ts analyze --path src --runner jest

# Monorepo: run the tests of a specific package
slopguard-ts analyze --path packages/core/src --project-dir packages/core

# Full JSON for CI / downstream tooling
slopguard-ts analyze --path src --json | jq '.methods | sort_by(-.crap)[:10]'

# Fail CI when any method's CRAP exceeds 50
slopguard-ts analyze --path src --fail-over 50

# Complexity only (skip the test run; every method shows 0% coverage)
slopguard-ts analyze --path src --no-coverage

# Join coverage CI already produced (nyc, c8, mocha, or a prior run)
slopguard-ts analyze --path src --coverage-file coverage/coverage-final.json

# Zero-config: analyze the current module (drives go test for coverage)
slopguard-go

# Scan a specific directory and print the top crappy methods
slopguard-go analyze --path ./internal --threshold 30

# Scope the test run to specific packages (anything they miss reads 0%)
slopguard-go analyze --path ./internal/auth --packages ./internal/auth/...

# Full JSON for CI / downstream tooling
slopguard-go analyze --path . --json | jq '.methods | sort_by(-.crap)[:10]'

# Fail CI when any method's CRAP exceeds 50
slopguard-go analyze --path . --fail-over 50

# Complexity only (skip the test run; every method shows 0% coverage)
slopguard-go analyze --path ./pkg --no-coverage

# Join coverage CI already produced (a go test -coverprofile file)
slopguard-go analyze --path . --coverage-file cover.out

# Zero-config: analyze the current module (drives gradle test + Kover for coverage)
slopguard-kotlin analyze --path src/main/kotlin

# Scan a directory and print the top crappy methods
slopguard-kotlin analyze --path src/main/kotlin --threshold 30

# Android with Kover (the default): scope to a variant report task
slopguard-kotlin analyze --path app/src/main/kotlin \
  --gradle-test-task testDebugUnitTest --gradle-report-task koverXmlReportDebug

# Prefer JaCoCo? Opt in with --coverage-tool jacoco
slopguard-kotlin analyze --path src/main/kotlin --coverage-tool jacoco

# Multi-module: point at the module whose tests should run
slopguard-kotlin analyze --path feature/login/src/main/kotlin --project-dir feature/login

# Full JSON for CI / downstream tooling
slopguard-kotlin analyze --path src/main/kotlin --json | jq '.methods | sort_by(-.crap)[:10]'

# Fail CI when any method's CRAP exceeds 50
slopguard-kotlin analyze --path src/main/kotlin --fail-over 50

# Complexity only (skip the test run; every method shows 0% coverage)
slopguard-kotlin analyze --path src/main/kotlin --no-coverage

# Join a Kover/JaCoCo report CI already produced
slopguard-kotlin analyze --path src/main/kotlin \
  --coverage-file build/reports/kover/report.xml

# Zero-config: analyze the current project (auto-finds and runs its tests for coverage)
slopguard-python

# Scan a specific directory and print the top crappy methods
slopguard-python analyze --path ./src --threshold 30

# Name the test runner instead of auto-detecting it
slopguard-python analyze --path ./src --runner pytest

# Full JSON for CI / downstream tooling
slopguard-python analyze --path . --json | jq '.methods | sort_by(-.crap)[:10]'

# Fail CI when any method's CRAP exceeds 50
slopguard-python analyze --path . --fail-over 50

# Complexity only (skip the test run; every method shows 0% coverage)
slopguard-python analyze --path ./src --no-coverage

# Join coverage CI already produced (a coverage json report)
slopguard-python analyze --path . --coverage-file coverage.json

# Or run it as a module
python -m slopguard analyze --path ./src

Subcommands

analyze: all flags

Exit codes & streams

Stream discipline: the report (text or JSON) goes to stdout; progress markers (slopguard: running tests…) go to stderr. Piped stdout is always clean; analyze --json | jq .summary just works.

JSON report schema

Stable, versioned, and shared byte-for-byte across slopguard-swift, slopguard-ts, slopguard-go, and slopguard-kotlin. The same downstream tooling reads all four. Three top-level sections:

summary

• files, types, methods: counts, plus crappy counts.
• avgCrap, maxCrap: distribution of wCRAP across all methods.
• weighted coverage across analyzed methods, when coverage was gathered.
• coverageAvailable: false under --no-coverage or when no coverage data was found.

methods[]

Every analyzed function, method, constructor, and accessor:

types[]

• aggregatedCrap: the formula applied to the type's totals (total burden, comparable across types).
• maxCrap: the worst single-method offender in the type (the "biggest fire" metric).
• isCrappy, weighted coverage, method counts.

Example output from SlopGuard analyzing its own sources:

{
  "qualifiedName": "CrapAggregator.aggregate(fileReports:sourceRootURL:…)",
  "file": "slopguard-core/Aggregation/CrapAggregator.swift",
  "line": 19,
  "kind": "function",
  "complexity": 17,
  "cognitiveComplexity": 15,
  "weightedComplexity": 15.97,
  "coverage": 0,
  "crap": 270.97,
  "isCrappy": true
}

{
  "qualifiedName": "CrapAggregator.aggregate",
  "file": "core/aggregation/crapAggregator.ts",
  "line": 48,
  "kind": "method",
  "complexity": 20,
  "cognitiveComplexity": 16,
  "weightedComplexity": 17.89,
  "coverage": 0,
  "crap": 337.89,
  "isCrappy": true
}

{
  "qualifiedName": "enumerate",
  "file": "core/diranalyzer.go",
  "line": 95,
  "kind": "function",
  "complexity": 10,
  "cognitiveComplexity": 26,
  "weightedComplexity": 16.12,
  "coverage": 0,
  "crap": 276.12,
  "isCrappy": true
}

{
  "qualifiedName": "ComplexityCalculator.walk",
  "file": "core/src/main/kotlin/.../ComplexityVisitor.kt",
  "line": 81,
  "kind": "method",
  "complexity": 19,
  "cognitiveComplexity": 12,
  "weightedComplexity": 15.10,
  "coverage": 0,
  "crap": 243.10,
  "isCrappy": true
}

{
  "qualifiedName": "_run_analyze",
  "file": "src/slopguard/cli.py",
  "line": 116,
  "kind": "function",
  "complexity": 14,
  "cognitiveComplexity": 18,
  "weightedComplexity": 15.87,
  "coverage": 0,
  "crap": 267.87,
  "isCrappy": true
}

The wCRAP formula, precisely

wCRAP(m) = (cyc × cog) × (1 − cov/100)³ + sqrt(cyc × cog)

• cov = 100 → the risk term vanishes; the score collapses to sqrt(cyc × cog), complexity alone.
• cov = 0 → full quadratic penalty: (cyc × cog) + sqrt(cyc × cog).
• The cube sharply rewards even partial coverage: at 50% coverage the untested factor is 0.5³ = 0.125, so 87.5% of the risk term is gone.
• Inputs are clamped: negative complexity → 0; coverage → [0, 100]. The score is always ≥ 0.

The exact shipping implementation is Sources/slopguard-core/CRAP.swift: 18 lines, fully covered. Play with the curve in the interactive formula lab.

The exact shipping implementation is src/core/crap.ts: a handful of lines, fully covered, identical in behaviour to the Swift version. Play with the curve in the interactive formula lab.

The exact shipping implementation is core/crap.go: a handful of lines, fully covered, identical in behaviour to the other ports. Play with the curve in the interactive formula lab.

The exact shipping implementation is core/src/main/kotlin/dev/slopguard/core/Crap.kt: a handful of lines, fully covered, identical in behaviour to the other ports. Play with the curve in the interactive formula lab.

The exact shipping implementation is src/slopguard/crap.py: a handful of lines, fully covered, identical in behaviour to the other ports. Play with the curve in the interactive formula lab.

How coverage is gathered

Includes & excludes

By default SlopGuard skips build products and test code: .build, Pods, Carthage, Generated, *Tests, *Spec, and friends. Add your own with --exclude (combined with the defaults) or take full manual control with --no-default-excludes. Useful when you want to score the test suite itself.

By default SlopGuard skips build products and test code: node_modules, dist, build, out, coverage, *.d.ts, *.min.js, generated code, and test files (*.test.*, *.spec.*, __tests__/, test(s)/). Add your own with --exclude (combined with the defaults) or take full manual control with --no-default-excludes. Useful when you want to score the test suite itself.

What counts as a method: functions, class methods, constructors, get/set accessors, static blocks, and named arrow functions / function expressions (const handler = () => {}, object properties, class fields). Anonymous inline callbacks don't get their own entry; their branches count toward the enclosing method, with a cognitive nesting bump for the callback body, per the Sonar spec.

By default SlopGuard skips build products and test code: vendor, testdata, *_test.go, and generated code (*.pb.go, *_gen.go, mock_*.go, and anything carrying the // Code generated … DO NOT EDIT. header). Add your own with --exclude (combined with the defaults) or take full manual control with --no-default-excludes.

What counts as a method: top-level functions and methods (functions with a receiver). Anonymous function literals don't get their own entry; their branches count toward the enclosing function, with a cognitive nesting bump for the closure body, per the Sonar spec. Go attaches methods to a type by receiver, not lexical nesting, so a type's members are gathered package-wide.

By default SlopGuard skips build products and test code: build, .gradle, generated code, *Test.kt / *Tests.kt, the src/test and src/androidTest source sets, and testFixtures/. Add your own with --exclude (combined with the defaults) or take full manual control with --no-default-excludes.

What counts as a method: top-level and member functions (in classes, objects, interfaces, enums), secondary constructors, init blocks, and custom get/set accessors with a body. Lambdas and local functions don't get their own entry; their branches count toward the enclosing function, with a cognitive nesting bump, per the Sonar spec. Types are gathered by lexical nesting.

By default SlopGuard skips environments, caches, and test code: .venv, __pycache__, .mypy_cache, test files and dirs (test_*.py, *_test.py, tests/, conftest.py), generated stubs (*_pb2.py), and anything carrying an @generated / DO NOT EDIT header. Add your own with --exclude (combined with the defaults) or take full manual control with --no-default-excludes.

What counts as a method: top-level functions, methods, constructors (__init__), and property get/set accessors. Named nested defs get their own entry; anonymous lambdas don't — their branches count toward the enclosing method, with a cognitive nesting bump for the lambda body, per the Sonar spec. Methods attach to their lexically enclosing class, so nested classes get qualified names (Outer.Inner.method).

Using with agents

SlopGuard's core claim: code quality and coverage decide agentic outcomes. Agents iterate by changing code and running tests. Where coverage is missing they fly blind, and where complexity is high they hallucinate. wCRAP is one number that captures both, so you can use it in two directions:

• As a gate: agents can't merge new slop. Run --fail-over in CI; exit code 2 blocks the PR.
• As a work queue: feed the JSON to an agent and have it burn the leaderboard down: write tests for crappy methods, refactor the tangles, re-run to verify the score dropped.

CLAUDE.md / AGENTS.md drop-in

## Quality gate: SlopGuard

Before declaring any Swift task complete, run:

    slopguard-swift analyze --path Sources --json --quiet

- The report is JSON on stdout; `.methods[]` entries with `isCrappy: true`
  exceed the wCRAP threshold (30).
- If your change ADDED a crappy method, refactor it or cover it with tests
  until its `crap` score is below 30. Coverage is gathered by the tool
  itself via `xcodebuild test`. Write real tests; the number cannot be
  hand-fed.
- CI runs `--fail-over 50` and will reject the PR at exit code 2.
- Full interface reference: https://www.slopguard.dev/llms-full.txt

## Quality gate: SlopGuard

Before declaring any TypeScript task complete, run:

    slopguard-ts analyze --path src --json --quiet

- The report is JSON on stdout; `.methods[]` entries with `isCrappy: true`
  exceed the wCRAP threshold (30).
- If your change ADDED a crappy method, refactor it or cover it with tests
  until its `crap` score is below 30. Coverage is gathered by the tool
  itself by driving your test runner (vitest/jest). Write real tests; the
  number cannot be hand-fed.
- CI runs `--fail-over 50` and will reject the PR at exit code 2.
- Full interface reference: https://www.slopguard.dev/llms-full.ts.txt

## Quality gate: SlopGuard

Before declaring any Go task complete, run:

    slopguard-go analyze --path . --json --quiet

- The report is JSON on stdout; `.methods[]` entries with `isCrappy: true`
  exceed the wCRAP threshold (30).
- If your change ADDED a crappy method, refactor it or cover it with tests
  until its `crap` score is below 30. Coverage is gathered by the tool
  itself by driving `go test`. Write real tests; the number cannot be
  hand-fed.
- CI runs `--fail-over 50` and will reject the PR at exit code 2.
- Full interface reference: https://www.slopguard.dev/llms-full.go.txt

## Quality gate: SlopGuard

Before declaring any Kotlin task complete, run:

    slopguard-kotlin analyze --path src/main/kotlin --json --quiet

- The report is JSON on stdout; `.methods[]` entries with `isCrappy: true`
  exceed the wCRAP threshold (30).
- If your change ADDED a crappy method, refactor it or cover it with tests
  until its `crap` score is below 30. Coverage is gathered by the tool
  itself by driving your Gradle test run (Kover/JaCoCo). Write real tests;
  the number cannot be hand-fed.
- CI runs `--fail-over 50` and will reject the PR at exit code 2.
- Full interface reference: https://www.slopguard.dev/llms-full.kotlin.txt

## Quality gate: SlopGuard

Before declaring any Python task complete, run:

    slopguard-python analyze --path . --json --quiet

- The report is JSON on stdout; `.methods[]` entries with `isCrappy: true`
  exceed the wCRAP threshold (30).
- If your change ADDED a crappy method, refactor it or cover it with tests
  until its `crap` score is below 30. Coverage is gathered by the tool
  itself by driving your test suite (pytest/unittest under coverage.py).
  Write real tests; the number cannot be hand-fed.
- CI runs `--fail-over 50` and will reject the PR at exit code 2.
- Full interface reference: https://www.slopguard.dev/llms-full.python.txt

Agent recipes

# Build an agent work queue: worst methods first, stable IDs included
slopguard-swift analyze --json --quiet \
  | jq '[.methods[] | select(.isCrappy)] | sort_by(-.crap)
         | map({id, crap, coverage, file, line})'

# Coverage gaps only: complex code no test touches
slopguard-swift analyze --json --quiet \
  | jq '.methods[] | select(.complexity >= 5 and .coverage <= 50)'

# Diff-style check after an agent's change: did max crap go up?
before=$(slopguard-swift analyze --json --quiet | jq '.summary.maxCrap')
# … agent edits code …
after=$(slopguard-swift analyze --json --quiet | jq '.summary.maxCrap')
[ "$(echo "$after > $before" | bc)" = "0" ] || echo "quality regressed"

# Fast pre-commit sweep (no test build): catches new tangles instantly
slopguard-swift analyze --no-coverage --quiet --fail-over 200

# Build an agent work queue: worst methods first, stable IDs included
slopguard-ts analyze --json --quiet \
  | jq '[.methods[] | select(.isCrappy)] | sort_by(-.crap)
         | map({id, crap, coverage, file, line})'

# Coverage gaps only: complex code no test touches
slopguard-ts analyze --json --quiet \
  | jq '.methods[] | select(.complexity >= 5 and .coverage <= 50)'

# Diff-style check after an agent's change: did max crap go up?
before=$(slopguard-ts analyze --json --quiet | jq '.summary.maxCrap')
# … agent edits code …
after=$(slopguard-ts analyze --json --quiet | jq '.summary.maxCrap')
[ "$(echo "$after > $before" | bc)" = "0" ] || echo "quality regressed"

# Fast pre-commit sweep (no test run): catches new tangles instantly
slopguard-ts analyze --no-coverage --quiet --fail-over 200

# Build an agent work queue: worst methods first, stable IDs included
slopguard-go analyze --json --quiet \
  | jq '[.methods[] | select(.isCrappy)] | sort_by(-.crap)
         | map({id, crap, coverage, file, line})'

# Coverage gaps only: complex code no test touches
slopguard-go analyze --json --quiet \
  | jq '.methods[] | select(.complexity >= 5 and .coverage <= 50)'

# Diff-style check after an agent's change: did max crap go up?
before=$(slopguard-go analyze --json --quiet | jq '.summary.maxCrap')
# … agent edits code …
after=$(slopguard-go analyze --json --quiet | jq '.summary.maxCrap')
[ "$(echo "$after > $before" | bc)" = "0" ] || echo "quality regressed"

# Fast pre-commit sweep (no test run): catches new tangles instantly
slopguard-go analyze --no-coverage --quiet --fail-over 200

# Build an agent work queue: worst methods first, stable IDs included
slopguard-kotlin analyze --json --quiet \
  | jq '[.methods[] | select(.isCrappy)] | sort_by(-.crap)
         | map({id, crap, coverage, file, line})'

# Coverage gaps only: complex code no test touches
slopguard-kotlin analyze --json --quiet \
  | jq '.methods[] | select(.complexity >= 5 and .coverage <= 50)'

# Diff-style check after an agent's change: did max crap go up?
before=$(slopguard-kotlin analyze --json --quiet | jq '.summary.maxCrap')
# … agent edits code …
after=$(slopguard-kotlin analyze --json --quiet | jq '.summary.maxCrap')
[ "$(echo "$after > $before" | bc)" = "0" ] || echo "quality regressed"

# Fast pre-commit sweep (no test run): catches new tangles instantly
slopguard-kotlin analyze --no-coverage --quiet --fail-over 200

# Build an agent work queue: worst methods first, stable IDs included
slopguard-python analyze --json --quiet \
  | jq '[.methods[] | select(.isCrappy)] | sort_by(-.crap)
         | map({id, crap, coverage, file, line})'

# Coverage gaps only: complex code no test touches
slopguard-python analyze --json --quiet \
  | jq '.methods[] | select(.complexity >= 5 and .coverage <= 50)'

# Diff-style check after an agent's change: did max crap go up?
before=$(slopguard-python analyze --json --quiet | jq '.summary.maxCrap')
# … agent edits code …
after=$(slopguard-python analyze --json --quiet | jq '.summary.maxCrap')
[ "$(echo "$after > $before" | bc)" = "0" ] || echo "quality regressed"

# Fast pre-commit sweep (no test run): catches new tangles instantly
slopguard-python analyze --no-coverage --quiet --fail-over 200

Agent-ingestible docs

This site publishes its documentation in machine-friendly form, following the llms.txt convention:

Point your agent at https://www.slopguard.dev/llms-full.txt and it has the complete Swift interface. Both files are plain text/plain markdown with no markup to strip.

Point your agent at https://www.slopguard.dev/llms-full.ts.txt and it has the complete TypeScript interface. Both files are plain text/plain markdown with no markup to strip.

Point your agent at https://www.slopguard.dev/llms-full.go.txt and it has the complete Go interface. Both files are plain text/plain markdown with no markup to strip.

Point your agent at https://www.slopguard.dev/llms-full.kotlin.txt and it has the complete Kotlin interface. Both files are plain text/plain markdown with no markup to strip.

Point your agent at https://www.slopguard.dev/llms-full.python.txt and it has the complete Python interface. Both files are plain text/plain markdown with no markup to strip.