Metadata-Version: 2.4
Name: brokk-slopcop
Version: 0.0.5
Summary: Static analysis for coding agents and CI: check a change through the hosted SlopCop API
License-Expression: Apache-2.0
License-File: LICENSE
Description-Content-Type: text/markdown
Requires-Python: >=3.9
Keywords: agents,ai-agent,ci,cli,code-review,coding-agent,git,sarif,static-analysis
Project-URL: Homepage, https://github.com/BrokkAi/slopcop
Project-URL: Repository, https://github.com/BrokkAi/slopcop
Project-URL: Issues, https://github.com/BrokkAi/slopcop/issues
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Go
Classifier: Topic :: Software Development :: Quality Assurance

# SlopCop

**Static analysis deep enough for CI, fast enough to run on every edit.**

[![CI](https://github.com/BrokkAi/slopcop/actions/workflows/ci.yml/badge.svg)](https://github.com/BrokkAi/slopcop/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/BrokkAi/slopcop)](https://github.com/BrokkAi/slopcop/releases/latest)
[![npm](https://img.shields.io/npm/v/@brokkai/slopcop)](https://www.npmjs.com/package/@brokkai/slopcop)
[![PyPI](https://img.shields.io/pypi/v/brokk-slopcop)](https://pypi.org/project/brokk-slopcop/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Go](https://img.shields.io/badge/Go-1.25%2B-blue.svg)](https://go.dev/)

`slopcop` sends one git patch, from the base commit to the working tree, to the
hosted check API at <https://slopcop.com>. The service applies it, runs the
hosted policy catalog plus the repository rules you selected, and returns the
report: every finding with its severity, the file and line that triggered it,
and the certainty behind it. The analysis is
[Bifrost](https://github.com/BrokkAi/bifrost), an open-source static analysis
engine rather than a language model, so a finding traces back to a rule instead
of to a guess.

There is no local analyzer and nothing to install per language: the CLI ships
the change and prints what comes back, and it never decides on its own that
there is nothing to check. The command is built for agents and one-shot CI: no
prompts, one request, and the analyzer's exit contract.

## Install

npm, PyPI, the release archive, and the PowerShell installer all install the
same release binary for macOS, Linux, and Windows on x64 and arm64, so
`slopcop version` reports which release it came from. The Go toolchain can
build that binary from source instead.

| Channel | Platforms | Needs |
| --- | --- | --- |
| [npm](#npm) | macOS, Linux, Windows | Node 22 or newer |
| [PyPI](#pypi) | macOS, Linux, Windows | Python 3.9 or newer |
| [Release archive](#release-archive) | macOS, Linux, Windows | nothing |
| [PowerShell installer](#powershell-installer) | Windows | PowerShell |
| [Go](#go) | built from source | Go 1.25 or newer |

### npm

```console
npm install --global @brokkai/slopcop
slopcop --help
```

The tarball carries the release binary for every supported platform, so it
needs no Go toolchain. `npx @brokkai/slopcop` runs it without installing it.

### PyPI

```console
pip install brokk-slopcop
```

`pipx install brokk-slopcop` or `uv tool install brokk-slopcop` puts it in an
environment of its own. The wheels carry the release binary, so no Go toolchain
is needed either. The package is `brokk-slopcop` because PyPI already has an
unrelated project named `slopcop`; the command it installs is still `slopcop`,
and `python -m brokk_slopcop` runs the same binary.

### Release archive

Each release publishes `slopcop_v<version>_<os>_<arch>.tar.gz` (`.zip` on
Windows) holding the binary, `README.md`, and `LICENSE`, plus a `checksums.txt`
covering every archive. Download them from
<https://github.com/BrokkAi/slopcop/releases/latest> and check the sha256
before unpacking:

```console
ver=0.0.3; os=linux; arch=amd64   # darwin/arm64 on Apple silicon
base=https://github.com/BrokkAi/slopcop/releases/download/v$ver
curl -fsSLO "$base/slopcop_v${ver}_${os}_${arch}.tar.gz"
curl -fsSLO "$base/checksums.txt"
grep "${os}_${arch}" checksums.txt | sha256sum -c -   # shasum -a 256 -c - on macOS
tar -xzf "slopcop_v${ver}_${os}_${arch}.tar.gz" slopcop
sudo install -m 755 slopcop /usr/local/bin/slopcop
```

### PowerShell installer

```powershell
irm https://raw.githubusercontent.com/BrokkAi/slopcop/master/install.ps1 | iex
```

It takes the latest release, verifies the archive against `checksums.txt`,
installs `slopcop.exe` to `%LOCALAPPDATA%\Programs\slopcop`, and adds that
directory to the user `Path`. `SLOPCOP_VERSION`, `SLOPCOP_INSTALL_DIR`, and
`SLOPCOP_NO_MODIFY_PATH` override its defaults.

### Go

```console
go install github.com/BrokkAi/slopcop/cmd/slopcop@latest
```

Go 1.25 or newer is required to build. A plain `go install` reports `dev` as
its version; in a clone, `make install` stamps the version from `git describe`.

## Enable it in an agent

The binary carries the agent skill that teaches a coding agent how to run
slopcop. `slopcop init` installs it into each well-known skills directory whose
harness is present, and names what it did:

| Location | Harness |
| --- | --- |
| `~/.agents/skills/slopcop/` | Codex, opencode |
| `~/.claude/skills/slopcop/` | Claude Code, opencode |
| `$CODEX_HOME/skills/slopcop/`, or `~/.codex/skills/slopcop/` | Codex home |

A skill that is already there is left alone by init, so running it again is
safe. `slopcop login` and every check also install the skill in those
directories, rewriting one that differs from the skill bundled into the binary,
so an agent follows the instructions of the slopcop version it runs; local
edits to an installed skill do not survive them. `slopcop init --no-skill`
skips the install and any update of it.

## Sign in

```console
slopcop login                           # browser device flow
slopcop login --token "$SLOPCOP_TOKEN"  # existing credential, for CI and agents
```

The browser flow prints a URL and a code and stores the token once the login is
approved. The service URL defaults to `https://slopcop.com`; `--service`,
`$SLOPCOP_SERVICE`, or a stored value override it.

The credential lives in `slopcop/config.json` under the user config directory
and is written owner-only. `slopcop logout` clears it.

Precedence:

| Value | Order |
| --- | --- |
| Service URL | `--service`, `$SLOPCOP_SERVICE`, stored by `slopcop login`, `https://slopcop.com` |
| Token | `$SLOPCOP_TOKEN`, stored value |

## Check

```console
slopcop                          # check the change in the current checkout
slopcop check --format json      # same, machine-readable
slopcop --root ../repo --base HEAD~1
```

The base commit defaults to the merge base with the branch upstream, then the
merge base with `origin/HEAD`, then `HEAD`. The service must already have the
base commit in its clone; a missing one comes back as the service's
`base_not_found` message and remedy.

Every run sends one check request, even when the working tree matches the base
and the patch is empty. A clean result or a failure always comes from the
service.

Flags:

| Flag | Meaning |
| --- | --- |
| `--root PATH` | repository to check (default `.`) |
| `--base REV` | base commit or revision for the change |
| `--format human\|json\|sarif` | report format (default `human`) |
| `--fail-on never\|finding\|note\|warning\|error` | exit-1 threshold for new findings (default `finding`) |
| `--show-existing` | also list the findings that were already in the code |
| `--policy PATH` | repository-relative `.rqlp` file to evaluate (repeatable) |
| `--no-policy-discovery` | skip `.slopcop/policies` rules |
| `--timeout DURATION` | how long to wait for the result (default `10m`) |
| `--verbose` | print the resolved request to stderr |

### What is sent

One git patch from the base commit to the working tree. An empty change is
sent as an empty patch, not filtered out. The patch carries committed but
unpushed work, unstaged edits, untracked files, deletions, renames, mode
changes, and binary content. Git-ignored files stay out, except selected
`.slopcop/policies` rules, which must travel because the service evaluates them
from the patched checkout.

The service owns the limits on what a check accepts. When a change is too
large or touches too many files, the service's `payload_too_large` response is
printed verbatim; the CLI does not impose its own limits.

Every check also runs the hosted catalog. Rules under
`.slopcop/policies/**/*.rqlp` are added automatically unless
`--no-policy-discovery` is set.

### New and pre-existing findings

A check fails only on findings the change introduced or touched: the service
marks a finding new when it is in a file the change writes and its lines meet a
line the change added, or the line beside one it removed. Findings that were
already in the code are counted, never fail the check, and are listed only with
`--show-existing`. A change that introduces nothing exits `0`, however many
findings the repository already holds.

### Ignore a false positive

Each finding a check reports carries an `id`. When a finding is a false
positive, ignore it:

```console
slopcop ignore 0f8fad5b-d9cb-469f-a165-70867728950e
```

That finding is not reported again for this repository. Ignoring covers that
one finding, its rule plus its place in the code, in its repository for your
workspace; the rule keeps reporting everything else. Ignoring a finding twice
is fine. `ignore` uses the same login and service URL as a check, exits `0`
with a one-line confirmation, and otherwise exits `2` with the service's
message and remedy; `finding_not_found` means the id is unknown or comes from a
check outside your workspace.

### Output and exit codes

The service answers structured data; the CLI renders it. `human` prints one
block per new finding, with an `ID:` line when the service names one, then the
pre-existing ones with `--show-existing`, a
summary line such as `1 new finding across 1 file(s); 72 already in the code
(--show-existing lists them) | Analysis complete`, and any omitted or
incomplete checks. `json` prints `status`, `baseCommit`, `summary`
(`newFindings` and `existingFindings` count the split), `findings` (each with
`new` and its `id`), `incomplete`, and `failure` when the analysis did not
complete. `sarif` prints a SARIF 2.1.0 log whose results carry `baselineState`
`new` or `unchanged` and the finding id in `properties["slopcop.findingId"]`. `--format` and `--show-existing` only change the rendering, never
the request, so the service answers the same check whichever is used.

| Exit | Meaning |
| --- | --- |
| `0` | Check completed; no new finding crossed the `--fail-on` level |
| `1` | A new finding crossed `--fail-on` |
| `2` | No new finding crossed `--fail-on`, but a check was incomplete; or the CLI or service failed |
| `3` | The check was still running when `--timeout` ran out |

An inconclusive check fails the check only when it concerns a file the
change writes. One about other files is listed on an `Inconclusive outside
the change` line (`inconclusiveElsewhere` in `json`, a `note` notification in
`sarif`) and never changes the exit code. A check that timed out counts
wherever it is. The service can place an inconclusive check only once Bifrost
reports which files it concerns; until then every one counts as in the change.

The service applies `--fail-on` and sets the status; the exit code follows it.
The CLI always sends `--fail-on`, defaulting to `finding`: a check fails only
on findings the change introduced, so any of them, a note or an unrated one
included, is worth fixing before the change lands. The service's own default
for a request without `failOn` is Bifrost's `warning`; pass `--fail-on warning`
to match it.
New findings that cross `--fail-on` exit `1` even when some check did not
complete.

While the service answers `check_running`, the CLI waits the `Retry-After` it
names and asks again until `--timeout` runs out; every ask attaches to the same
running check. If it is still running then, the CLI exits `3`, prints the
service's message and remedy on stderr, and in `json` prints
`{"status": "pending", "retryAfter": 5, "message": …, "remedy": …}` on stdout
(`sarif` prints a run with `slopcop.status` `pending`). Running the same check
again picks up the same analysis.

Service failures print the closed contract exactly: message, remedy, and any
install URL. The codes, messages, and remedies are defined by the service in
`server/src/check.rs` of `BrokkAi/bifrost-service`; the CLI does not
rewrite them. The remedies name no client, so when one says to sign in the CLI
adds the `slopcop login` command after it. A failed request prints no report
on stdout.

## API

The CLI calls `POST <service>/v1/check` with a bearer token:

```json
{
  "repoUrl": "https://github.com/owner/name",
  "baseCommit": "0123456789abcdef0123456789abcdef01234567",
  "change": "<base64 git patch>",
  "selection": {"files": [".slopcop/policies/rule.rqlp"]},
  "failOn": "finding"
}
```

The service rejects any other field. The response carries `status`,
`baseCommit`, `applied`, `summary`, `findings`, `incomplete`, and `failure`
when the analysis did not complete. Against a service from before findings
were marked `new`, the CLI treats every finding as new, as that service gated
on all of them. Non-2xx responses carry `code`, `message`,
`remedy`, `retryable`, and an optional `installUrl`.

Each finding in the response carries an `id`; a service from before findings
could be ignored omits it.

`slopcop ignore <id>` calls `POST <service>/v1/ignore` with the same bearer
token and `{"findingId": "<id>"}`, and gets back
`{"findingId": "<id>", "status": "ignored"}`. Failures use the same closed
contract, including `finding_not_found`.

`slopcop login` uses the device flow: `POST /api/device` returns a
`deviceCode`, `userCode`, `verificationUri`, `expiresIn`, and `interval`, and
`POST /api/token` returns `202` while pending or `200` with a `token` once
approved. The polling codes are `authorization_pending`, `slow_down`,
`expired_token`, and `access_denied`.

## Development

```console
make test        # go test ./...
make vet         # go vet ./...
make build       # bin/slopcop-<goos>-<goarch>
make cross-check # linux, darwin, and windows on amd64 and arm64
make npm-test    # node --test npm/test
make wheels      # pypi-dist/, one wheel per release target
```

Releases are tag-driven. Pushing a `v*.*.*` tag runs GoReleaser, which builds
linux, darwin, and windows for amd64 and arm64, packages `tar.gz` archives
(`zip` on Windows) with `checksums.txt`, and publishes the GitHub release.
`.goreleaser.yaml` is the single source of truth; CI runs `goreleaser check`
and a snapshot build on every change, and `make release-check` runs the same
locally when GoReleaser is installed. The same tag push then packs
`@brokkai/slopcop` from those release archives and publishes it to npm with
[trusted publishing](docs/npm-publishing.md), so the package needs no npm
token.

The same tag also packs a wheel per release target from the binaries GoReleaser
just built, installs the wheel for every platform GitHub can run, and
publishes `brokk-slopcop` to PyPI with
[trusted publishing](docs/pypi-publishing.md), so that package needs no PyPI
token either.

Layout:

| Path | Purpose |
| --- | --- |
| `cmd/slopcop` | process entry point |
| `internal/cli` | cobra commands, selection, exit codes |
| `internal/gitx` | remote canonicalization, base resolution, patch building |
| `internal/service` | `/v1/check` client and the wire contract |
| `internal/report` | human, JSON, and SARIF rendering from the structured response |
| `internal/config` | stored service URL and token |
| `npm` | launcher, packer, and tests of the `@brokkai/slopcop` package |
| `packaging/pypi` | wheel packer and launcher of the `brokk-slopcop` package |
| `skills/slopcop` | the agent skill the binary embeds and installs |
| `docs/npm-publishing.md` | npm release flow and trusted publisher setup |
| `docs/pypi-publishing.md` | PyPI release flow and trusted publisher setup |
| `.goreleaser.yaml` | tag release build, archives, and checksums |
