check-safety/README.md

# check-safety

Static safety checker for the BlockNinja codebase. Walks a target tree, runs 31 invariant
checks across Go and frontend sources, and exits non-zero on any violation.

Lives at `~/src/blockninja/check-safety/` as a standalone Go module, alongside `cms/`,
`orchestrator/`, `core/`, the plugins, and the sites. It is intentionally standalone — no
imports from sibling repos except two vendored packages (see [Vendored packages](#how-it-stays-in-sync-with-cms)).

## Run

```bash
# Scan CMS (default target)
make run

# Scan a different repo
make run TARGET=../orchestrator

# Direct invocation — first positional arg is the target dir (default ".")
go run . ../sites/bidbuddy
go run . ~/src/blockninja/cms
```

If you run it against the top of the consolidated BlockNinja repo, it prints a hint to pass
`--plugin-dir <path>` (or run inside the plugin directory) so plugin-specific checks fire.

### CLI flags

| Flag | Meaning |
|------|---------|
| `<target-dir>` (positional) | Repo/subtree to scan. Defaults to `.`. If it contains `plugin.mod`, it is auto-registered as a plugin root so plugin checks run. |
| `--orchestrator` | Scan the orchestrator backend only (resolved from the hardcoded consolidated layout), regardless of the positional target. |
| `--plugin-dir <path> [more…]` | Register one or more plugin roots (dirs with `plugin.mod`). Alias: `--plugin-dirs`. Consumes args until the next `--flag`. |
| `--plugin-pages <dir> [more…]` | Register frontend source dirs directly as plugin page targets (for the frontend checks). Consumes args until the next `--flag`. |
| `--verbose` / `-v` | Print every check (including `OK`/`SKIP`), not just failures and warnings. |
| `--all-any` | The `any`-usage check (2e) defaults to only the **unstaged working-tree diff** (newly introduced `any`); `--all-any` scans every source file instead. |

The CLI contract (`check-safety <target-dir> [--flags]`) is stable — the CMS `Makefile`
`safety-check` / `install-safety-checker` targets shell into this directory and depend on it.

### Output

Output is concise by design (it is usually fed back into an agent's context). Passing and
skipped checks print nothing; only `FAIL`/`WARN`/`ERR` checks print a `<STATUS> <id> <summary>`
line with their findings indented beneath, followed by one tally line. A clean run is two lines:

```
check-safety /home/alex/src/blockninja/cms
32 checks: 20 ok 12 skip -> OK
```

A run with problems:

```
check-safety /home/alex/src/blockninja/cms
FAIL 15 1 err.Error() leak(s) to HTTP clients — log via slog.Error() and return a user-friendly message
  internal/service/handler.go:27 http.Error(w, err.Error(), ...) — leaks internal error
WARN 2e 1 any usage in changed lines (showing 1, --all-any to scan all)
  web/src/api.ts:12 [go] data: any

32 checks: 27 ok 3 skip 1 warn 1 fail -> FAIL
```

Pass `--verbose` to see every check's status. Exit code is `1` on any `FAIL`, `2` on a hard
`ERR`, `0` otherwise (warnings do not fail the run).

## Install globally

```bash
make install   # go install . → $GOPATH/bin/check-safety
check-safety ~/src/blockninja/cms
```

## Test

```bash
make test         # go test -count=1 ./... (some tests shell out to npm/tsc/golangci-lint and skip if absent)
make test-short   # go test -short — skip the slow ones
make test-update  # regenerate the golden snapshots after intentional output changes
make tidy         # go mod tidy
make build        # go build -o check-safety .
make clean        # remove the built binary
```

`golden_test.go` is a characterisation snapshot test: it runs the whole binary against the
fixtures under `testdata/golden/` and diffs stdout + exit code. If you intentionally change a
check's output, run `make test-update` and commit the regenerated fixture.

## What it checks

Checks self-register via `init()` and run in `Seq` order. The full set (the `ID` is what the
tool prints in each check header):

| ID | Check | What it enforces |
|----|-------|------------------|
| 1 | Secret env var reads | Secret env vars (`JWT_SECRET`, `VAULT_*`, encryption keys, …) are read only inside `config.Load()` (`config/config.go`) or `_test.go` files. |
| 2 | RBAC registration | Every RPC method is registered in the RBAC interceptor. Internal / plugin-managed services (e.g. `ManagementService`, Symposium's `WikiService`) are exempted. |
| 2b | Plugin proto ownership | Plugins own their proto/RBAC definitions correctly (no poaching of core proto packages). |
| 2c | Plugin SDK boundaries | Standalone plugins import only the published `block/core` SDK boundary — verified via imports, `go.mod`, and version. |
| 2d | sqlc UUID overrides | sqlc UUID overrides in standalone plugins and `cmd` configs must use `github.com/google/uuid`. |
| 2e | `any` usage | Warns on `any` usage in Go and TypeScript (capped at 120 printed warnings). |
| 2f | Codegen freshness | `sqlc compile` and `buf generate` must succeed for every scanned root that defines them (generated code is up to date). |
| 3 | Go lint | Go code compiles and passes `go fix`, `golangci-lint --fix`, `go vet`, and the strict lint checks. |
| 3b | Orchestrator tests | Orchestrator backend tests must pass when checking the core BlockNinja repo. |
| 4 | Frontend lint | Frontend code is auto-formatted, lint-clean, and typecheck-clean. |
| 5 | ConnectRPC hooks | Frontend uses the generated ConnectRPC hooks — no hand-crafted API clients. |
| 6 | No hardcoded colors | No hardcoded colors in the frontend — use theme tokens. |
| 7 | Tab state in URL | No `useState` for tab state in route files — use URL `?tab=` params. |
| 8 | API subpath imports | Import `@block-ninja/api` from subpaths only, never the package root. |
| 9 | pnpm only | No npm/yarn lockfiles — pnpm is the only package manager. |
| 10 | Button automation | Interactive buttons carry the required automation attributes. |
| 10b | No eslint-disable | No `eslint-disable-next-line` comments (fix the lint, don't suppress it). |
| 10disc | Plugin discovery | Plugin frontend pages are discoverable by the loader. |
| 11 | No placeholder code | No placeholder / stub code — only shipped features. |
| 12 | No reinvented utils | No reinvented utilities — use the shared helpers. |
| 13 | RPC error handling | RPC query/mutation error handling is present and correct. |
| 14 | No raw SQL | No raw SQL outside sqlc / Bob. |
| 15 | No leaked errors | No `err.Error()` leaked to HTTP clients. |
| 16 | Directory structure | Services and handlers live in their correct directories. |
| 17 | No TODO markers | No TODO markers in production code. |
| 18 | Plugin segmentation | Plugin segmentation is respected (`safety-rules.yml`). |
| 19 | Auth precedence | Bearer token takes precedence over cookies in the auth middleware. |
| 20 | Tailwind v4 | Tailwind v4 configuration is correct (PostCSS plugin, CSS directives, `@config`). |
| 21 | Preset validation | Plugin `presets.json` type-safe-unmarshals against `theme.Theme`. |
| 22 | HTML sanitization | No hand-rolled HTML sanitization — use bluemonday. |
| 28 | Admin toolbar | Public page handlers inject the admin toolbar data. |

> The canonical numbered list also lives in the comment block at the top of `main.go`; keep
> the two in sync when adding or renumbering a check.

## How it stays in sync with CMS

`internal/helpers/deferlog.go` and `internal/theme/*.go` are **vendored copies** from CMS
(`cms/backend/internal/{helpers,theme}/`). Go's `internal/` rule blocks direct imports across
modules, so they are copied in rather than imported. When CMS changes the theme schema or
`LogDeferredError`, re-copy them — that drift is precisely what the preset-validation check
(21) surfaces.

`blockNinjaRepoRoot()` and `orchestratorRepoRoot()` in `lint_pipeline.go` hardcode the
consolidated layout (`~/src/blockninja/{cms,orchestrator}`). Update them if the tree layout
changes.

## Adding a new check

1. Add a `check_<name>.go` file with a `runCheck<Name>` func and an `init()` that calls
   `register(Check{Seq, ID, Title, Run})`.
2. Add the rule logic in a `<rule>.go` file, plus a `<rule>_test.go` for unit coverage.
3. Pick a `Seq` value that slots it into the desired run order.
4. Update the numbered comment block at the top of `main.go` and the table above.
5. If the output is deterministic, add a fixture under `testdata/golden/<case>/` and run
   `make test-update` to regenerate the snapshot.
</content>
</invoke>