scan¶

The scan command is the main entry point. It analyzes Go modules, computes CRAP scores, and outputs the results.

Usage¶

go-crap scan [path] [flags]

Arguments:

Argument	Description	Default
`path`	Directory or package pattern to scan	`.` (current directory)

Flags¶

Flag	Short	Description	Default
`--threshold`	`-t`	Score above which a function is marked as problematic	`30.0`
`--fail-above`		Exit with code 1 if any function exceeds the threshold	`false`
`--format`	`-f`	Output format: `table`, `json`, `github`, `sarif`, or `pr-comment`	`table`
`--top`		Show only the N worst offenders (0 = all). `CoverageUntrusted` entries always survive, even when `N` is small	`0`
`--min`		Hide entries below this score. `CoverageUntrusted` entries are never hidden, regardless of their score	`0`
`--missing`		Policy for functions without coverage: `pessimistic`, `optimistic`, or `skip`	`pessimistic`
`--exclude`		Exclude files matching this regex pattern (repeatable). Use `.` to match any path depth. e.g. `._test\.go` to exclude all test files, `pb/.*\.go` to exclude protobuf files	none
`--verbose`		Enable verbose (debug-level) logging	`false`
`--output`	`-o`	Output file path (default: stdout)	stdout
`--mutation-report`		Path to gremlins JSON mutation report to validate coverage reliability	`""` (disabled)
`--detailed`		Include mutation failure details (original/replacement code, line, type) in report output	`false`

CoverageUntrusted has meaning only if --mutation-report was used.

Coverage Unavailable Warning¶

When a Go module fails to build or run tests (go test ./... errors), coverage data is lost for all functions in that module. go-crap detects this and surfaces the error in all output formats:

table — coverage column shows N/A ‼, footer lists unavailable modules with error messages
json — coverage is null, coverage_warning contains the error
github — ::warning annotation with module error
sarif — result with RuleID: "go-crap/coverage-unavailable"
pr-comment — "Coverage Unavailable" section

This is distinct from the --missing policy, which handles functions that have no coverage data because they were not exercised by tests. Coverage unavailable means the entire module's test run failed.

Examples¶

Scan all packages¶

go-crap scan

Scan a project somewhere else¶

go-crap scan ~/go/src/github.com/padiazg/go-crap

Show only the top 20 worst offenders¶

go-crap scan --top 20

CI integration - fail on high CRAP scores¶

go-crap scan --fail-above --threshold 30 --format github

Filter by minimum score¶

go-crap scan --min 10

Exclude generated or test files¶

go-crap scan --exclude '.*_test\.go' --exclude 'testdata/.*\.go'

Exclude protobuf and mock files at any depth¶

go-crap scan --exclude '\.pb\.go$' --exclude 'mock_'

Machine-readable JSON output¶

go-crap scan --format json > report.json

SARIF output¶

go-crap scan --format sarif > report.sarif

Outputs SARIF 2.1.0 compliant JSON for integration with code scanning tools, IDEs, and CI platforms that support SARIF.

Pull request comment output¶

go-crap scan --format pr-comment > pr-comment.md

Generates a markdown table with status symbols, CRAP scores, complexity, coverage, and file locations — formatted for pasting into pull request comments.

Write to file¶

go-crap scan --output report.json
go-crap scan -o report.json

Uses the --output / -o flag to write results to a file instead of stdout. Works with any format.

Verbose / debug logging¶

go-crap scan --verbose

Enables debug-level logging to help diagnose issues with module discovery, coverage parsing, or path matching.

Mutation report validation¶

go-crap scan --mutation-report gremlins-report.json

Validates coverage reliability by comparing mutation testing results against go-crap's coverage data. When a function has lived mutants (mutations that survived because tests didn't catch them), go-crap marks the coverage as unreliable and recalculates the CRAP score assuming 0% coverage.

Unreliable coverage is indicated by:

A ⚠ warning next to the coverage percentage in table and pr-comment output
An additional coverage-untrusted SARIF result in sarif format
A mutation score in json output (mutation_score field)
A ::warning annotation in github format, emitted even when the CRAP score is below threshold
An "Unreliable Coverage" section in pr-comment output listing all affected functions (always rendered when mutation report is provided)

This is useful when you use gremlins or similar mutation testing tools to catch functions that appear well-tested but have blind spots.

Detailed mutation output¶

go-crap scan --mutation-report gremlins-report.json --format json --detailed

The --detailed flag includes full mutation failure details in the report output:

JSON: mutation_details array per entry with type, mutator_name, file, line, status, original_text, replacement_text
SARIF: survived mutations appended to warning messages with type, line, and code diff (e.g. "a < b" → "a >= b")
PR Comment: Survived Mutants column in the Unreliable Coverage section, with code snippets inline
Table: no change — still shows ⚠ for untrusted coverage

This is useful for debugging which specific mutants survived and what code transformations they represented.