Documentation

Everything the CLI accepts, everything it emits, and how to wire it into an autonomous coding agent's loop. SlopGuard is alpha (v0.2). The JSON schemas are 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)

The mutate subcommand checks the tests themselves. It makes one small change to the source at a time, runs the tests against each change, and reports every change that no test catches. See How mutation testing works.

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

# Mutation testing: change the code, run the tests, list the changes no test caught
slopguard-swift mutate --path Sources/MyLib/Store.swift

# 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

# Mutation testing: change the code, run the tests, list the changes no test caught
slopguard-ts mutate --path src/store.ts

# 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

# Mutation testing: change the code, run the tests, list the changes no test caught
slopguard-go mutate --path ./internal/auth

# 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

# Mutation testing: change the code, run the tests, list the changes no test caught
slopguard-kotlin mutate --path src/main/kotlin/com/example/Store.kt

# 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

# Mutation testing: change the code, run the tests, list the changes no test caught
slopguard-python mutate --path src/pkg/store.py

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

Subcommands

analyze: all flags

mutate: all flags

Flags that only analyze uses, such as --threshold and --fail-over, are rejected as unknown flags. Each mutant costs one run of the test suite, so start with one file or one package. --dry-run shows how many mutants a path yields.

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, and so does mutate --json | jq .summary.

JSON report schema

Stable, versioned, and shared as one schema across slopguard-swift, slopguard-ts, slopguard-go, slopguard-kotlin, and slopguard-python. The same downstream tooling reads all five. 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
}

Mutation report schema

mutate --json emits its own report, separate from the analyze report. Its reportType is "mutation" and its schemaVersion is "1". Every port emits the same shape, with keys in alphabetical order at every level.

Top-level fields

projectRoot, runner and timeoutSeconds are null when no test ran. That happens in a dry run, and when no mutant is left to run because none was generated or all are ignored.

mutants[]

summary

notes[]

Each note is a plain sentence. The standard notes are:

• When at least one mutant ran and none was killed or timed out: Every tested mutant survived. Check that the tests import the source under --path.
• When some mutants did not compile: <n> mutant(s) did not compile and are excluded from the score.
• When coverage was requested but the coverage baseline produced no usable data: The baseline test run produced no coverage data, so every mutant was run.
• When the coverage baseline exited with an error but its data was still usable: The coverage run exited with code <n>; its coverage data was still used.
• When a file changed while the run was in progress: <absolute path> changed while mutate was running, so its remaining mutants were not run.
• When a new run recovers a file that an interrupted run left mutated: Restored <path>, which an interrupted mutate run left mutated. If the file has changed since, the note gives the path of the backup instead. If the backup is missing, the note is An interrupted mutate run left <path> mutated and its backup is missing. Restore the file from version control.
• When that recovery cannot write the original back: An interrupted mutate run left <path> mutated, and writing the original back failed. The original is at <backup path>.

slopguard-go never writes to the source tree, so it never adds the last two notes.

Errors

On failure, mutate exits with code 1 and writes the same error envelope as analyze to stderr: JSON with --json, text without it. The argument parser reports some errors itself, such as an unknown flag. Those errors are plain text, even with --json, and exit with code 64. An unknown flag also exits with code 1, but the argument parser reports it as plain text, even with --json. An unknown flag also exits with code 1, but Go's flag parser reports it as plain text, followed by the usage, even with --json. An unknown flag is an invalid_argument error in the same envelope. An unknown flag or an invalid --runner choice also exits with code 1, but Python's argparse reports it as plain text, after the usage, even with --json. These codes are new:

slopguard-go never writes to the source tree, so it never returns mutation_in_progress or restore_failed.

Existing codes are reused where they fit, such as invalid_argument for a bad flag value like an unknown operator id. mutate also returns runner_unavailable, the code that analyze already uses when the test runner cannot be launched. mutate also returns runner_unavailable, the code that analyze already uses when the test runner cannot be launched.

An excerpt from a run on the sample app, with the other top-level keys and mutants left out:

{
  "mutants" : [
    {
      "column" : 59,
      "file" : "Sources/TodoList/TodoStore.swift",
      "id" : "Sources/TodoList/TodoStore.swift:19:59:negate_conditional",
      "line" : 19,
      "method" : "TodoStore.toggle(id:)",
      "operator" : "negate_conditional",
      "original" : "==",
      "replacement" : "!=",
      "status" : "killed"
    }
  ],
  "summary" : {
    "compileErrors" : 0,
    "fileCount" : 3,
    "ignored" : 0,
    "killed" : 11,
    "mutantCount" : 11,
    "mutationScore" : 100,
    "noCoverage" : 0,
    "pending" : 0,
    "survived" : 0,
    "timedOut" : 0
  }
}

{
  "mutants": [
    {
      "column": 37,
      "file": "todoStore.ts",
      "id": "todoStore.ts:27:37:remove_not",
      "line": 27,
      "method": "TodoStore.remaining.get",
      "operator": "remove_not",
      "original": "!",
      "replacement": "",
      "status": "survived"
    }
  ],
  "summary": {
    "compileErrors": 0,
    "fileCount": 3,
    "ignored": 0,
    "killed": 6,
    "mutantCount": 7,
    "mutationScore": 85.71428571428571,
    "noCoverage": 0,
    "pending": 0,
    "survived": 1,
    "timedOut": 0
  }
}

{
  "mutants": [
    {
      "column": 32,
      "file": "store.go",
      "id": "store.go:55:32:increment",
      "line": 55,
      "method": "Store.All",
      "operator": "increment",
      "original": "++",
      "replacement": "--",
      "status": "timeout"
    }
  ],
  "summary": {
    "compileErrors": 0,
    "fileCount": 3,
    "ignored": 1,
    "killed": 15,
    "mutantCount": 17,
    "mutationScore": 100,
    "noCoverage": 0,
    "pending": 0,
    "survived": 0,
    "timedOut": 1
  }
}

{
  "mutants": [
    {
      "column": 19,
      "file": "com/example/todo/TodoStore.kt",
      "id": "com/example/todo/TodoStore.kt:19:19:boundary",
      "line": 19,
      "method": "TodoStore.toggle",
      "operator": "boundary",
      "original": "<",
      "replacement": "<=",
      "status": "survived"
    }
  ],
  "summary": {
    "compileErrors": 0,
    "fileCount": 2,
    "ignored": 0,
    "killed": 13,
    "mutantCount": 15,
    "mutationScore": 86.66666666666667,
    "noCoverage": 0,
    "pending": 0,
    "survived": 2,
    "timedOut": 0
  }
}

{
  "mutants": [
    {
      "column": 23,
      "file": "store.py",
      "id": "store.py:14:23:arithmetic",
      "line": 14,
      "method": "TodoStore.add",
      "operator": "arithmetic",
      "original": "+=",
      "replacement": "-=",
      "status": "survived"
    }
  ],
  "summary": {
    "compileErrors": 0,
    "fileCount": 4,
    "ignored": 0,
    "killed": 11,
    "mutantCount": 12,
    "mutationScore": 91.66666666666666,
    "noCoverage": 0,
    "pending": 0,
    "survived": 1,
    "timedOut": 0
  }
}

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

How mutation testing works

Coverage shows that a line ran during a test. It does not show that a test would fail if the line were wrong. mutate checks that. It makes one small change to the source, called a mutant: > becomes >=, + becomes -, or a call statement is deleted. Then it runs the tests against the mutant.

A mutant that makes a test fail is killed: a test checks that behaviour. A mutant that every test passes with has survived: no test checks that behaviour. The report lists each survivor with its file, line, column, original text, replacement text and enclosing method, so a developer or an agent can write the test that kills it.

analyze and mutate find different gaps. analyze finds complex code that the tests do not run. mutate finds code that the tests run but do not check.

What a run does

1. Walk --path with the same include and exclude rules as analyze, so test files are not mutated by default. Parse each file, generate its mutants, and name the enclosing method of each one. Apply the ignore markers and --operators, then sort the mutants by file, line, column and operator. A dry run stops here, and so does a run with no mutant left to run.
2. Run the plain baseline: the exact command used for mutants, once, with no mutation and no timeout. It must pass, or the run stops with baseline_failed. A broken command would otherwise fail every mutant and fake a perfect score. The run time of this baseline sets the default timeout.
3. Run the coverage baseline, the same coverage run that analyze uses. The swift test runner is the exception: it runs swift test --enable-code-coverage and reads the line counts with llvm-cov. A mutant on a line that no test executes gets no_coverage and does not run. This step never stops the run: without usable coverage data, every mutant runs and a note says so. --no-coverage skips it.
4. For each remaining mutant, in order: write it into the file, build and test with the timeout, write the original back, and classify the result.
5. For each remaining mutant, in order: write it into the file, run the tests with the timeout, write the original back, and classify the result.
6. For each remaining mutant, in order: write the mutated file to a temporary directory, run go test with an overlay that swaps it in, and classify the result. The source tree is never written.
7. For each remaining mutant, in order: write it into the file, run the Gradle tests with the timeout, write the original back, and classify the result.
8. For each remaining mutant, in order: write it into the file, run the tests with the timeout, write the original back, and classify the result.

With the swift test runner, each mutant runs swift build --build-tests and then swift test --skip-build --disable-code-coverage. Its coverage baseline reads per-line counts through xcrun llvm-cov export. With the xcodebuild runner, each mutant runs build-for-testing and then test-without-building, both with -enableCodeCoverage NO. xccov reports coverage per function, so under the xcodebuild runner a mutant is no_coverage when its enclosing method never ran.

The mutant command is vitest run --bail=1 --coverage.enabled=false --reporter=dot or jest --bail=1 --coverage=false --watchAll=false --ci. Coverage stays off in mutant runs, so a coverage threshold in your config cannot fail a run and fake a kill.

The mutant command is go test -overlay=<json> -vet=off -failfast <packages>, run in the module root. The test cache is keyed on the compiled binary, so packages that a mutant does not change come back (cached). Go records coverage per block of statements, so a mutant in a case expression can get no_coverage even though the expression was evaluated.

The mutant command is ./gradlew <test-task> --fail-fast --console=plain with an init script. The script switches off every Kover and JaCoCo report and verification task and the JaCoCo agent, so a coverage threshold in your build cannot fail a mutant run and fake a kill.

The mutant command is python -m pytest -x -q -p no:cacheprovider (plus --no-cov when pytest-cov is installed) or python -m unittest discover -f. Coverage stays off in mutant runs, so a coverage threshold in your config cannot fail a run and fake a kill.

The text report

The text report opens with a summary. Then it lists the mutants that survived, the mutants on lines that no test runs, and the mutants that timed out. Each line gives the location, the operator, the original and replacement text, and the enclosing method.

This dry run of the sample app lists every mutant without running a test:

slopguard-swift 0.2.0 — mutation report (schema 1)
source:    /work/TodoList
project:   (not run)
runner:    (not run)
timeout:   (not run)

Summary
  files:          3
  mutants:        11
  killed:         0
  timed out:      0
  survived:       0
  no coverage:    0
  compile errors: 0
  ignored:        0
  pending:        11
  score:          n/a

Mutants (11, not run)
  Sources/TodoList/Todo.swift:12:29  boolean_literal  `false` → `true`  Todo.init(id:title:isCompleted:createdAt:)
  Sources/TodoList/TodoFilter.swift:10:33  boolean_literal  `true` → `false`  TodoFilter.matches(_:)
  Sources/TodoList/TodoFilter.swift:11:33  remove_not  `!` → ``  TodoFilter.matches(_:)
  Sources/TodoList/TodoStore.swift:11:9  remove_call  `todos.append(todo)` → ``  TodoStore.add(_:)
  Sources/TodoList/TodoStore.swift:15:9  remove_call  `todos.removeAll { $0.id == id }` → ``  TodoStore.remove(id:)
  Sources/TodoList/TodoStore.swift:15:33  negate_conditional  `==` → `!=`  TodoStore.remove(id:)
  Sources/TodoList/TodoStore.swift:19:59  negate_conditional  `==` → `!=`  TodoStore.toggle(id:)
  Sources/TodoList/TodoStore.swift:20:9  remove_call  `todos[index].isCompleted.toggle()` → ``  TodoStore.toggle(id:)
  Sources/TodoList/TodoStore.swift:24:59  negate_conditional  `==` → `!=`  TodoStore.rename(id:to:)
  Sources/TodoList/TodoStore.swift:33:29  remove_not  `!` → ``  TodoStore.activeCount.get
  Sources/TodoList/TodoStore.swift:41:9  remove_call  `todos.removeAll(where: \.isCompleted)` → ``  TodoStore.clearCompleted()

This run is on the sample app, before its tests were strengthened. One mutant survives:

slopguard-typescript 0.2.0 — mutation report (schema 1)
source:    /work/todo-list/src
project:   /work/todo-list
runner:    vitest
timeout:   21s per mutant

Summary
  files:          3
  mutants:        7
  killed:         6
  timed out:      0
  survived:       1
  no coverage:    0
  compile errors: 0
  ignored:        0
  score:          85.71%

Survived (1) — tests still pass with these changes
  todoStore.ts:27:37  remove_not  `!` → ``  TodoStore.remaining.get

This run is on the sample app. One mutant timed out, which counts as killed, and an ignore marker switched off another:

slopguard-go 0.2.0 — mutation report (schema 1)
source:    /work/todolist
project:   /work/todolist
runner:    go test
timeout:   35s per mutant

Summary
  files:          3
  mutants:        17
  killed:         15
  timed out:      1
  survived:       0
  no coverage:    0
  compile errors: 0
  ignored:        1
  score:          100.00%

Timed out (1) — counted as killed
  store.go:55:32  increment  `++` → `--`  Store.All

This run is on the sample app, before its tests were strengthened. Two mutants survive:

slopguard-kotlin 0.2.0 — mutation report (schema 1)
source:    /work/todolist/src/main/kotlin
project:   /work/todolist
runner:    gradle
timeout:   70s per mutant

Summary
  files:          2
  mutants:        15
  killed:         13
  timed out:      0
  survived:       2
  no coverage:    0
  compile errors: 0
  ignored:        0
  score:          86.67%

Survived (2) — tests still pass with these changes
  com/example/todo/TodoStore.kt:19:19  boundary  `<` → `<=`  TodoStore.toggle
  com/example/todo/TodoStore.kt:29:23  arithmetic  `-` → `+`  TodoStore.clearCompleted

This run is on the sample app, before its tests were strengthened. One mutant survives:

slopguard-python 0.2.0 — mutation report (schema 1)
source:    /work/todolist/todolist
project:   /work/todolist
runner:    unittest
timeout:   11s per mutant

Summary
  files:          4
  mutants:        12
  killed:         11
  timed out:      0
  survived:       1
  no coverage:    0
  compile errors: 0
  ignored:        0
  score:          91.67%

Survived (1) — tests still pass with these changes
  store.py:14:23  arithmetic  `+=` → `-=`  TodoStore.add

Statuses and score

mutationScore = (killed + timedOut) / (killed + timedOut + survived + noCoverage) × 100

Detected mutants count for the score and missed mutants count against it. Excluded mutants do not count at all. The JSON report gives the score unrounded, and the text report rounds it to two decimals. The score is null (n/a in text) when no mutant counts, which is always the case in a dry run.

Operators

The operator ids are the same in every port, and --operators takes any of them. Each mutant replaces one span of the source: an operator token, a literal, or a whole call statement for remove_call. A double arrow (↔) means the change goes both ways.

Equivalent mutants and the ignore marker

Some mutants change nothing that a test can observe, so no test can kill them. These are equivalent mutants. For example, when code keeps the largest value seen so far, > and >= give the same result, because assigning an equal value changes nothing. Switch such a mutant off with a comment on its line, or on a comment line directly above it:

if m.complexity > maxComplexity { // slopguard-ignore-mutant(boundary): equal values assign the same max

if (s > max) max = s; // slopguard-ignore-mutant(boundary): assigning an equal max changes nothing

if m.Complexity > maxComplexity { // slopguard-ignore-mutant(boundary): equal values assign the same max

if (value > max) max = value // slopguard-ignore-mutant(boundary): equal values give the same max

// slopguard-ignore-mutant
val limit = retries * 2

if score > best:  # slopguard-ignore-mutant(boundary): assigning an equal best changes nothing
    best = score

• slopguard-ignore-mutant ignores every mutant on its line.
• slopguard-ignore-mutant(boundary,negate_conditional) ignores only the listed operators. Unknown ids are dropped.
• A marker on a line that holds only a comment applies to the next line.
• Ignored mutants never run and do not count toward the score.

Write the reason after the marker, so a reviewer can check that the mutant really is equivalent.

Workspace safety

Each mutant runs your tests, so a run executes your code once per mutant. This is the same trust boundary as analyze.

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).

mutate uses the same rules, so by default it never mutates test code.

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.
- For each file you changed, run
  `slopguard-swift mutate --path <file> --json --quiet`. For every
  `.mutants[]` entry with status `survived` or `no_coverage`, add a test
  that passes on the real code and fails with that mutant in place.
  If no test can kill a mutant because the change has no observable
  effect, add `// slopguard-ignore-mutant(<operator>): <reason>`
  on its line instead. Re-run until none are left.
- 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.
- For each file you changed, run
  `slopguard-ts mutate --path <file> --json --quiet`. For every
  `.mutants[]` entry with status `survived` or `no_coverage`, add a test
  that passes on the real code and fails with that mutant in place.
  If no test can kill a mutant because the change has no observable
  effect, add `// slopguard-ignore-mutant(<operator>): <reason>`
  on its line instead. Re-run until none are left.
- 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.
- For each package you changed, run
  `slopguard-go mutate --path <package> --json --quiet`. For every
  `.mutants[]` entry with status `survived` or `no_coverage`, add a test
  that passes on the real code and fails with that mutant in place.
  If no test can kill a mutant because the change has no observable
  effect, add `// slopguard-ignore-mutant(<operator>): <reason>`
  on its line instead. Re-run until none are left.
- 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.
- For each file you changed, run
  `slopguard-kotlin mutate --path <file> --json --quiet`. For every
  `.mutants[]` entry with status `survived` or `no_coverage`, add a test
  that passes on the real code and fails with that mutant in place.
  If no test can kill a mutant because the change has no observable
  effect, add `// slopguard-ignore-mutant(<operator>): <reason>`
  on its line instead. Re-run until none are left.
- 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.
- For each file you changed, run
  `slopguard-python mutate --path <file> --json --quiet`. For every
  `.mutants[]` entry with status `survived` or `no_coverage`, add a test
  that passes on the real code and fails with that mutant in place.
  If no test can kill a mutant because the change has no observable
  effect, add `# slopguard-ignore-mutant(<operator>): <reason>`
  on its line instead. Re-run until none are left.
- 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

Mutation testing recipe

Coverage alone lets an agent write tests that run code without checking it. mutate closes that gap. Its JSON report works as a queue: each mutant carries its exact location, its original and replacement text, and its enclosing method.

1. Run mutate --json on the code the agent changed.
2. For each mutant with status survived or no_coverage, the agent writes a test that passes on the real code and fails with that mutant in place.
3. Re-run mutate until no such mutant is left. A mutant that no test can kill gets the ignore marker and a reason.

# 1. The work queue: every mutant no test catches, with what to test
slopguard-swift mutate --path Sources/MyLib/Store.swift --json --quiet \
  | jq '[.mutants[] | select(.status == "survived" or .status == "no_coverage")
         | {id, method, original, replacement}]'

# 2. The agent writes one test per entry. Each test must fail with its mutant in place.

# 3. Re-run until the queue is empty (jq -e exits 1 while entries remain)
slopguard-swift mutate --path Sources/MyLib/Store.swift --json --quiet \
  | jq -e '.summary.survived + .summary.noCoverage == 0'

# CI: fail the PR when the mutation score drops below 80
slopguard-swift mutate --path Sources --quiet --fail-under 80

# 1. The work queue: every mutant no test catches, with what to test
slopguard-ts mutate --path src/store.ts --json --quiet \
  | jq '[.mutants[] | select(.status == "survived" or .status == "no_coverage")
         | {id, method, original, replacement}]'

# 2. The agent writes one test per entry. Each test must fail with its mutant in place.

# 3. Re-run until the queue is empty (jq -e exits 1 while entries remain)
slopguard-ts mutate --path src/store.ts --json --quiet \
  | jq -e '.summary.survived + .summary.noCoverage == 0'

# CI: fail the PR when the mutation score drops below 80
slopguard-ts mutate --path src --quiet --fail-under 80

# 1. The work queue: every mutant no test catches, with what to test
slopguard-go mutate --path ./internal/auth --json --quiet \
  | jq '[.mutants[] | select(.status == "survived" or .status == "no_coverage")
         | {id, method, original, replacement}]'

# 2. The agent writes one test per entry. Each test must fail with its mutant in place.

# 3. Re-run until the queue is empty (jq -e exits 1 while entries remain)
slopguard-go mutate --path ./internal/auth --json --quiet \
  | jq -e '.summary.survived + .summary.noCoverage == 0'

# CI: fail the PR when the mutation score drops below 80
slopguard-go mutate --path . --quiet --fail-under 80

# 1. The work queue: every mutant no test catches, with what to test
slopguard-kotlin mutate --path src/main/kotlin/com/example/Store.kt --json --quiet \
  | jq '[.mutants[] | select(.status == "survived" or .status == "no_coverage")
         | {id, method, original, replacement}]'

# 2. The agent writes one test per entry. Each test must fail with its mutant in place.

# 3. Re-run until the queue is empty (jq -e exits 1 while entries remain)
slopguard-kotlin mutate --path src/main/kotlin/com/example/Store.kt --json --quiet \
  | jq -e '.summary.survived + .summary.noCoverage == 0'

# CI: fail the PR when the mutation score drops below 80
slopguard-kotlin mutate --path src/main/kotlin --quiet --fail-under 80

# 1. The work queue: every mutant no test catches, with what to test
slopguard-python mutate --path src/pkg/store.py --json --quiet \
  | jq '[.mutants[] | select(.status == "survived" or .status == "no_coverage")
         | {id, method, original, replacement}]'

# 2. The agent writes one test per entry. Each test must fail with its mutant in place.

# 3. Re-run until the queue is empty (jq -e exits 1 while entries remain)
slopguard-python mutate --path src/pkg/store.py --json --quiet \
  | jq -e '.summary.survived + .summary.noCoverage == 0'

# CI: fail the PR when the mutation score drops below 80
slopguard-python mutate --path src --quiet --fail-under 80

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.