From e2120a433b3562ec10d95d5b77def0e4bc6ce0a2 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sat, 12 Sep 2026 11:12:18 -0700 Subject: [PATCH 1/2] docs: record the two declined modernizer analyzers No guidance file existed in this repository, so the decision to decline embedlit and omitzero lived only in a commit message and a PR body. An unqualified `go fix ./...` would silently re-propose both. embedlit is not hypothetical here: across the plugin fleet it proposed rewrites in five of fourteen repositories, and in bomly-plugin-template it was the only thing the modernizer found -- an unqualified run there would have propagated flattened Coordinates into every plugin created from it. AGENTS.md and CLAUDE.md are identical copies, matching bomly-sdk's convention. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9521801 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# AGENTS.md + +Guidance for coding agents working in this repository. `CLAUDE.md` is an +identical copy; keep the two files in sync. + +This repository is a Bomly plugin. It compiles against +`github.com/bomly-dev/bomly-sdk` and is consumed by `bomly-dev/bomly-cli` as a +pinned module. The release order is **SDK tags first, plugins adopt, then the +CLI pins** — so a stale pin here stalls the CLI behind it. + +## The modernizer, and the analyzers we decline + +`go fix ./...` is the Go 1.27 modernizer. It **applies** its rewrites in place; +`go fix -diff ./...` prints them instead, which is how to look first. + +Two of its analyzers are declined across every Bomly repository. Run it as: + +```sh +go fix -embedlit=false -omitzero=false ./... +``` + +- **`embedlit`** flattens `Coordinates: sdk.Coordinates{...}` into the bare + promoted fields at construction sites. `Coordinates` is a named identity + concept (ADR-0041 in bomly-cli), and the wrapper is what keeps the identity + visible where a package is built. This is not hypothetical here: when the + modernizer was first run across the plugin fleet, `embedlit` proposed + rewrites in five of fourteen repositories, and in `bomly-plugin-template` it + was the *only* thing the modernizer found — an unqualified run there would + have propagated flattened coordinates into every plugin created from the + template. +- **`omitzero`** drops `omitempty` from struct-valued JSON fields. The encoded + bytes do not move — `encoding/json` never omits a struct — so no test and no + linter objects. But the tag *is* the wire schema for `bomly.plugin.v1`, and a + consumer generating a schema by reflection then reads the field as required. + `bomly-sdk` took that rewrite once and spent four review rounds undoing it. + +Neither is caught by a test, a linter, or CI. That is exactly why the decision +is written down here rather than left in a commit message. + +## Conventions + +- The SDK owns shared domain meaning: package URLs (`purlkit`), SPDX + expressions (`spdxkit`), digest algorithms, ecosystem joins. If you find + yourself writing a table that maps one vocabulary to another, check the SDK + first — several drifted copies of exactly that have been found and deleted + across these repositories. +- Do not commit build output. Binaries belong in `bin/` or `dist/`, both + ignored. From 217cb2e31fd613628857be50522300510173dc40 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sat, 12 Sep 2026 11:12:19 -0700 Subject: [PATCH 2/2] docs: keep CLAUDE.md identical to AGENTS.md Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..61e4a66 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,48 @@ +# CLAUDE.md + +Guidance for coding agents working in this repository. `CLAUDE.md` is an +identical copy; keep the two files in sync. + +This repository is a Bomly plugin. It compiles against +`github.com/bomly-dev/bomly-sdk` and is consumed by `bomly-dev/bomly-cli` as a +pinned module. The release order is **SDK tags first, plugins adopt, then the +CLI pins** — so a stale pin here stalls the CLI behind it. + +## The modernizer, and the analyzers we decline + +`go fix ./...` is the Go 1.27 modernizer. It **applies** its rewrites in place; +`go fix -diff ./...` prints them instead, which is how to look first. + +Two of its analyzers are declined across every Bomly repository. Run it as: + +```sh +go fix -embedlit=false -omitzero=false ./... +``` + +- **`embedlit`** flattens `Coordinates: sdk.Coordinates{...}` into the bare + promoted fields at construction sites. `Coordinates` is a named identity + concept (ADR-0041 in bomly-cli), and the wrapper is what keeps the identity + visible where a package is built. This is not hypothetical here: when the + modernizer was first run across the plugin fleet, `embedlit` proposed + rewrites in five of fourteen repositories, and in `bomly-plugin-template` it + was the *only* thing the modernizer found — an unqualified run there would + have propagated flattened coordinates into every plugin created from the + template. +- **`omitzero`** drops `omitempty` from struct-valued JSON fields. The encoded + bytes do not move — `encoding/json` never omits a struct — so no test and no + linter objects. But the tag *is* the wire schema for `bomly.plugin.v1`, and a + consumer generating a schema by reflection then reads the field as required. + `bomly-sdk` took that rewrite once and spent four review rounds undoing it. + +Neither is caught by a test, a linter, or CI. That is exactly why the decision +is written down here rather than left in a commit message. + +## Conventions + +- The SDK owns shared domain meaning: package URLs (`purlkit`), SPDX + expressions (`spdxkit`), digest algorithms, ecosystem joins. If you find + yourself writing a table that maps one vocabulary to another, check the SDK + first — several drifted copies of exactly that have been found and deleted + across these repositories. +- Do not commit build output. Binaries belong in `bin/` or `dist/`, both + ignored.