From 7b96ceac4deb0805cb45e2d9b785bbb08b5c25d3 Mon Sep 17 00:00:00 2001 From: Alex Dunmow Date: Thu, 18 Jun 2026 16:46:53 +0800 Subject: [PATCH] Link CLAUDE.md to AGENTS.md --- AGENTS.md | 36 ++++++++++++++++++++++++++++++++++++ CLAUDE.md | 37 +------------------------------------ 2 files changed, 37 insertions(+), 36 deletions(-) create mode 100644 AGENTS.md mode change 100644 => 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8d0b0ff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,36 @@ +# check-safety + +Standalone Go module: BlockNinja static safety/lint runner. ~25 checks across the consolidated tree. + +## Layout + +``` +check-safety/ +├── main.go # CLI entry, orders all checks +├── check_*.go # one per check, wires its rule to the runner +├── .go # rule implementation (errleak.go, colors.go, ...) +├── *_test.go # unit tests per rule +├── golden_test.go # snapshot test that runs the whole binary on fixtures +├── testdata/golden/ # snapshot fixtures + expected stdout/exit +├── internal/helpers/ # vendored from cms/backend/internal/helpers (LogDeferredError) +└── internal/theme/ # vendored from cms/backend/internal/theme (Theme struct + helpers) +``` + +## Invariants when editing + +- This is **standalone** — no imports from sibling repos (CMS, orchestrator, plugins). The two vendored packages above are the only CMS surfaces it depends on, and they are intentional copies. +- `blockNinjaRepoRoot()` and `orchestratorRepoRoot()` in `lint_pipeline.go` hardcode the consolidated layout (`~/src/blockninja/{cms,orchestrator}`). Update them if the tree layout changes. +- Golden tests are characterisation tests — if you intentionally change a check's output, run `make test-update` and commit the new fixture. +- The CMS Makefile's `safety-check` and `install-safety-checker` targets shell out into this directory (`cd ../check-safety`). Keep the CLI contract stable: `check-safety [--flags]`. + +## Adding a check + +1. New `check_.go` with a `runCheck(rep *reporter, ...)` func. +2. New `.go` for the actual rule logic. +3. Add `_test.go` for unit coverage. +4. Wire into `main.go`'s ordered check list. Numbered comments at the top of `main.go` should stay in sync. +5. If the check is deterministic, add a fixture under `testdata/golden//` and `make test-update`. + +## Why vendored, not imported + +`internal/helpers` and `internal/theme` are inside CMS's `internal/` tree. Go's internal-package rule blocks cross-module imports of `internal/...`. Options were: refactor CMS to make them public (large blast radius), use a `replace` directive (still blocked by internal rule), or vendor (chosen). Drift between CMS and the vendored copies is the whole point of check 21 (preset validation against `theme.Theme`) — it surfaces schema changes. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 8d0b0ff..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,36 +0,0 @@ -# check-safety - -Standalone Go module: BlockNinja static safety/lint runner. ~25 checks across the consolidated tree. - -## Layout - -``` -check-safety/ -├── main.go # CLI entry, orders all checks -├── check_*.go # one per check, wires its rule to the runner -├── .go # rule implementation (errleak.go, colors.go, ...) -├── *_test.go # unit tests per rule -├── golden_test.go # snapshot test that runs the whole binary on fixtures -├── testdata/golden/ # snapshot fixtures + expected stdout/exit -├── internal/helpers/ # vendored from cms/backend/internal/helpers (LogDeferredError) -└── internal/theme/ # vendored from cms/backend/internal/theme (Theme struct + helpers) -``` - -## Invariants when editing - -- This is **standalone** — no imports from sibling repos (CMS, orchestrator, plugins). The two vendored packages above are the only CMS surfaces it depends on, and they are intentional copies. -- `blockNinjaRepoRoot()` and `orchestratorRepoRoot()` in `lint_pipeline.go` hardcode the consolidated layout (`~/src/blockninja/{cms,orchestrator}`). Update them if the tree layout changes. -- Golden tests are characterisation tests — if you intentionally change a check's output, run `make test-update` and commit the new fixture. -- The CMS Makefile's `safety-check` and `install-safety-checker` targets shell out into this directory (`cd ../check-safety`). Keep the CLI contract stable: `check-safety [--flags]`. - -## Adding a check - -1. New `check_.go` with a `runCheck(rep *reporter, ...)` func. -2. New `.go` for the actual rule logic. -3. Add `_test.go` for unit coverage. -4. Wire into `main.go`'s ordered check list. Numbered comments at the top of `main.go` should stay in sync. -5. If the check is deterministic, add a fixture under `testdata/golden//` and `make test-update`. - -## Why vendored, not imported - -`internal/helpers` and `internal/theme` are inside CMS's `internal/` tree. Go's internal-package rule blocks cross-module imports of `internal/...`. Options were: refactor CMS to make them public (large blast radius), use a `replace` directive (still blocked by internal rule), or vendor (chosen). Drift between CMS and the vendored copies is the whole point of check 21 (preset validation against `theme.Theme`) — it surfaces schema changes. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file