# SlopGuard

> SlopGuard is a CRAP (Change Risk Anti-Patterns) guardrail for coding agents. It scores every
> method by how complex AND how untested it is, via wCRAP(m) = (cyc × cog) × (1 − cov/100)³ + sqrt(cyc × cog),
> and emits a CI-gateable report. Thesis: code quality + test coverage decide the outcomes of
> autonomous/background coding agents; SlopGuard measures and enforces both. Five implementations
> ship today, sharing one formula and one JSON schema (schemaVersion "2"):
> - slopguard-swift: Swift / iOS (parses with SwiftSyntax, coverage via `xcodebuild test`).
> - slopguard-ts: TypeScript / JavaScript (parses with the TypeScript compiler API, coverage by
>   driving vitest or jest).
> - slopguard-go: Go (parses with the `go/ast` standard library, coverage by driving `go test`).
> - slopguard-kotlin: Kotlin / Android (parses with the Kotlin compiler PSI, coverage by driving
>   Gradle with Kover or JaCoCo).
> - slopguard-python: Python (parses with the `ast` standard library, coverage by driving pytest or
>   unittest under coverage.py).

Key facts:
- CLIs: `slopguard-swift`, `slopguard-ts`, `slopguard-go`, `slopguard-kotlin`, and `slopguard-python`
  (default subcommand `analyze`; also `version`). Alpha, v0.1.
- Coverage is gathered by the tool itself, never user-supplied, and cannot be faked. Swift drives
  `xcodebuild test`; TypeScript drives the project's own vitest/jest and reads the istanbul map; Go
  drives `go test -coverprofile`; Kotlin drives Gradle with Kover or JaCoCo (both emit JaCoCo-format
  XML); Python drives pytest/unittest under coverage.py and reads `coverage json`.
- Output: pretty text or stable versioned JSON (schemaVersion "2", shared across languages) on stdout;
  progress on stderr.
- Exit codes: 0 ok, 1 analysis error, 2 quality gate tripped (`--fail-over`).
- Default crappy threshold: 30. MIT.
- Swift requires Xcode 16 / Swift 6.0+ on macOS 13+. TypeScript requires Node 18.17+. Go requires
  Go 1.23+. Kotlin requires JDK 17+. Python requires Python 3.9+.

## Docs

- [Swift interface reference (markdown)](https://www.slopguard.dev/llms-full.txt): every flag, the JSON schema, exit codes, formula semantics, and agent integration recipes for slopguard-swift
- [TypeScript interface reference (markdown)](https://www.slopguard.dev/llms-full.ts.txt): the same, for slopguard-ts
- [Go interface reference (markdown)](https://www.slopguard.dev/llms-full.go.txt): the same, for slopguard-go
- [Kotlin interface reference (markdown)](https://www.slopguard.dev/llms-full.kotlin.txt): the same, for slopguard-kotlin
- [Python interface reference (markdown)](https://www.slopguard.dev/llms-full.python.txt): the same, for slopguard-python
- [Human docs](https://www.slopguard.dev/docs/): same content, rendered, with a Swift / TypeScript / Go / Kotlin / Python language switch
- [Swift source repository](https://github.com/JeevanThandi/SlopGuard-Swift): MIT, two dependencies (swift-syntax, swift-argument-parser), no network, no telemetry
- [TypeScript source repository](https://github.com/JeevanThandi/slopguard-typescript): MIT, two dependencies (typescript, commander), no network, no telemetry
- [Go source repository](https://github.com/JeevanThandi/slopguard-go): MIT, zero third-party dependencies (Go standard library only), no network, no telemetry
- [Kotlin source repository](https://github.com/JeevanThandi/slopguard-kotlin): MIT, one runtime dependency (kotlin-compiler-embeddable), no network, no telemetry
- [Python source repository](https://github.com/JeevanThandi/slopguard-python): MIT, zero runtime dependencies (Python standard library only), no network, no telemetry

## Optional

- [Landing page](https://www.slopguard.dev/): the agentic-engineering thesis and an interactive formula explorer