@brokkai/slopcop 0.0.2 → 0.0.4

package/README.md

@@ -1,50 +1,102 @@
 # SlopCop
 
-SlopCop checks a change through the yet to be deployed hosted SlopCop check
-API. The CLI ships the working-tree change to the service, the service applies
-it to the base commit and runs the hosted policy catalog plus any repository
-rules selected, and the CLI prints the report. There is no local analyzer: a check never needs a
-Bifrost install, and the CLI 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.
+**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
-make install
+npm install --global @brokkai/slopcop
+slopcop --help
 ```
 
-or:
+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
-go install github.com/BrokkAi/slopcop/cmd/slopcop@latest
+pip install brokk-slopcop
 ```
 
-Go 1.25 or newer is required to build.
+`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.
 
-On Windows, the PowerShell installer takes the latest release instead of
-building:
+### 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 verifies the release checksum, 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.
+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.
 
-The npm package carries the release binary for macOS, Linux, and Windows on x64
-and arm64, so it needs no Go toolchain:
+### Go
 
 ```console
-npm install --global @brokkai/slopcop
-npx @brokkai/slopcop --help
+go install github.com/BrokkAi/slopcop/cmd/slopcop@latest
 ```
 
-Node 22 or newer is required to run that package.
+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
 
@@ -107,10 +159,11 @@ Flags:
 | `--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 (default `finding`) |
+| `--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` | one check request timeout (default `10m`) |
+| `--timeout DURATION` | how long to wait for the result (default `10m`) |
 | `--verbose` | print the resolved request to stderr |
 
 ### What is sent
@@ -130,21 +183,58 @@ 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.
+
 ### Output and exit codes
 
 The service answers structured data; the CLI renders it. `human` prints one
-block per finding, a summary line, and any omitted or incomplete checks. `json`
-prints `status`, `baseCommit`, `summary`, `findings`, `incomplete`, and
-`failure` when the analysis did not complete. `sarif` prints a SARIF 2.1.0
-log.
+block per new finding, 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`), `incomplete`, and `failure` when the analysis did not complete. `sarif`
+prints a SARIF 2.1.0 log whose results carry `baselineState` `new` or
+`unchanged`. `--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; nothing crossed the `--fail-on` level |
-| `1` | A finding crossed `--fail-on` |
-| `2` | The check was incomplete, or the CLI or service failed |
+| `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
@@ -173,7 +263,9 @@ The CLI calls `POST <service>/v1/check` with a bearer token:
 
 The service rejects any other field. The response carries `status`,
 `baseCommit`, `applied`, `summary`, `findings`, `incomplete`, and `failure`
-when the analysis did not complete. Non-2xx responses carry `code`, `message`,
+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`.
 
 `slopcop login` uses the device flow: `POST /api/device` returns a
@@ -190,6 +282,7 @@ 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
@@ -202,6 +295,12 @@ locally when GoReleaser is installed. The same tag push then packs
 [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 |
@@ -213,6 +312,8 @@ Layout:
 | `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 |

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@brokkai/slopcop",
-  "version": "0.0.2",
-  "description": "Check a change through the hosted SlopCop check API",
+  "version": "0.0.4",
+  "description": "Static analysis for coding agents and CI: check a change through the hosted SlopCop API",
+  "keywords": [
+    "agents",
+    "ai-agent",
+    "ci",
+    "cli",
+    "code-review",
+    "coding-agent",
+    "git",
+    "sarif",
+    "static-analysis"
+  ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",