diff --git a/docs/convention-drift-audit-2026-03-23.md b/docs/convention-drift-audit-2026-03-23.md new file mode 100644 index 0000000..71ad4a4 --- /dev/null +++ b/docs/convention-drift-audit-2026-03-23.md @@ -0,0 +1,184 @@ +# Convention Drift Audit + +Date: 2026-03-23 + +Baseline: +- Audited at `e177418c90469c702eabef797a002f55c618fc66`. +- `CLAUDE.md:51` requires command code to use `pkg/cli/output.go` helpers instead of raw `fmt.Print*`. +- `CLAUDE.md:93` requires `_Good`, `_Bad`, `_Ugly` test suffixes. +- `CODEX.md` was not present under `/workspace` or `/root`, so no repo-local Codex conventions were available to apply beyond `CLAUDE.md` and in-repo docs. + +## `stdlib` -> `core.*` + +No literal `stdlib` namespace references or obvious pre-`core.*` import-path leftovers were found. + +Actionable drift, based on `CLAUDE.md:51`: command code still writes directly with `fmt.Print*` instead of going through `pkg/cli/output.go` helpers. + +- `cmd/core/config/cmd_get.go:23` +- `cmd/core/config/cmd_list.go:29` +- `cmd/core/config/cmd_path.go:16` +- `cmd/core/doctor/cmd_doctor.go:35` +- `cmd/core/doctor/cmd_environment.go:49` +- `cmd/core/doctor/cmd_install.go:14` +- `cmd/core/help/cmd.go:22` +- `cmd/core/pkgcmd/cmd_install.go:81` +- `cmd/core/pkgcmd/cmd_manage.go:51` +- `cmd/core/pkgcmd/cmd_remove.go:73` +- `cmd/core/pkgcmd/cmd_search.go:92` + +Notes: +- The first line above is the first direct `fmt.Print*` hit in each file; several of these files contain multiple direct output calls. +- Low-level output primitives such as `pkg/cli/output.go`, `pkg/cli/prompt.go`, `pkg/cli/stream.go`, `pkg/cli/tracker.go`, `pkg/cli/render.go`, and `pkg/cli/tree.go` were excluded from this list because they implement the output layer themselves. + +## UK English + +Mixed US and UK spellings remain in code comments, public API names, and user-facing docs. + +- `CONTRIBUTING.md:34` +- `README.md:125` +- `cmd/core/pkgcmd/cmd_search.go:72` +- `docs/cmd/ci/index.md:11` +- `docs/cmd/ci/init/index.md:3` +- `docs/cmd/dev/work/index.md:3` +- `docs/cmd/go/work/index.md:10` +- `docs/cmd/go/work/index.md:17` +- `docs/cmd/go/work/init/index.md:3` +- `docs/cmd/go/work/init/index.md:22` +- `docs/cmd/go/work/sync/index.md:34` +- `docs/cmd/go/work/use/index.md:45` +- `docs/cmd/pkg/search/index.md:18` +- `pkg/cli/ansi.go:39` +- `pkg/cli/ansi.go:46` +- `pkg/cli/ansi.go:94` +- `pkg/cli/ansi.go:100` +- `pkg/cli/ansi.go:107` +- `pkg/cli/ansi.go:140` +- `pkg/cli/ansi.go:146` +- `pkg/cli/glyph.go:28` +- `docs/pkg/cli/output.md:263` + +Notes: +- `pkg/cli/ansi.go` and its related docs are the clearest persistent drift point because the public API is `ColorEnabled` / `SetColorEnabled` while `CLAUDE.md:56` and several docs already use `colour` / `colours`. +- Legal text and schema keys that happen to use `license` were not counted unless they are repo-authored headings or prose. + +## Missing tests + +Packages with no tests in the package at all: + +- `cmd/core/config/cmd.go:9` +- `cmd/core/config/cmd_get.go:9` +- `cmd/core/config/cmd_list.go:11` +- `cmd/core/config/cmd_path.go:9` +- `cmd/core/config/cmd_set.go:7` +- `cmd/core/doctor/cmd_checks.go:20` +- `cmd/core/doctor/cmd_commands.go:19` +- `cmd/core/doctor/cmd_doctor.go:34` +- `cmd/core/doctor/cmd_environment.go:16` +- `cmd/core/doctor/cmd_install.go:11` +- `cmd/core/help/cmd.go:10` +- `cmd/core/main.go:26` + +Partially tested package surfaces with no dedicated coverage: + +- `cmd/core/pkgcmd/cmd_install.go:26` +- `cmd/core/pkgcmd/cmd_manage.go:17` +- `cmd/core/pkgcmd/cmd_pkg.go:21` +- `cmd/core/pkgcmd/cmd_search.go:31` + +Existing coverage in `cmd/core/pkgcmd` is narrow and only exercises `checkRepoSafety`: + +- `cmd/core/pkgcmd/cmd_remove_test.go:33` +- `cmd/core/pkgcmd/cmd_remove_test.go:42` +- `cmd/core/pkgcmd/cmd_remove_test.go:54` + +## SPDX headers + +`rg -n 'SPDX-License-Identifier|SPDX-FileCopyrightText' /workspace` returned no matches. + +In source/bootstrap scope, SPDX headers are missing at line 1 in all 61 tracked files below. + +Root and bootstrap files: + +- `Dockerfile:1` +- `install.bat:1` +- `install.sh:1` + +`cmd/` Go files: + +- `cmd/core/config/cmd.go:1` +- `cmd/core/config/cmd_get.go:1` +- `cmd/core/config/cmd_list.go:1` +- `cmd/core/config/cmd_path.go:1` +- `cmd/core/config/cmd_set.go:1` +- `cmd/core/doctor/cmd_checks.go:1` +- `cmd/core/doctor/cmd_commands.go:1` +- `cmd/core/doctor/cmd_doctor.go:1` +- `cmd/core/doctor/cmd_environment.go:1` +- `cmd/core/doctor/cmd_install.go:1` +- `cmd/core/help/cmd.go:1` +- `cmd/core/main.go:1` +- `cmd/core/pkgcmd/cmd_commands.go:1` +- `cmd/core/pkgcmd/cmd_install.go:1` +- `cmd/core/pkgcmd/cmd_manage.go:1` +- `cmd/core/pkgcmd/cmd_pkg.go:1` +- `cmd/core/pkgcmd/cmd_remove.go:1` +- `cmd/core/pkgcmd/cmd_remove_test.go:1` +- `cmd/core/pkgcmd/cmd_search.go:1` + +`pkg/` Go files: + +- `pkg/cli/ansi.go:1` +- `pkg/cli/ansi_test.go:1` +- `pkg/cli/app.go:1` +- `pkg/cli/app_test.go:1` +- `pkg/cli/check.go:1` +- `pkg/cli/check_test.go:1` +- `pkg/cli/command.go:1` +- `pkg/cli/commands.go:1` +- `pkg/cli/commands_test.go:1` +- `pkg/cli/daemon.go:1` +- `pkg/cli/daemon_test.go:1` +- `pkg/cli/errors.go:1` +- `pkg/cli/frame.go:1` +- `pkg/cli/frame_components.go:1` +- `pkg/cli/frame_model.go:1` +- `pkg/cli/frame_test.go:1` +- `pkg/cli/glyph.go:1` +- `pkg/cli/glyph_maps.go:1` +- `pkg/cli/glyph_test.go:1` +- `pkg/cli/i18n.go:1` +- `pkg/cli/layout.go:1` +- `pkg/cli/layout_test.go:1` +- `pkg/cli/log.go:1` +- `pkg/cli/output.go:1` +- `pkg/cli/output_test.go:1` +- `pkg/cli/prompt.go:1` +- `pkg/cli/prompt_test.go:1` +- `pkg/cli/render.go:1` +- `pkg/cli/runtime.go:1` +- `pkg/cli/stream.go:1` +- `pkg/cli/stream_test.go:1` +- `pkg/cli/strings.go:1` +- `pkg/cli/styles.go:1` +- `pkg/cli/styles_test.go:1` +- `pkg/cli/tracker.go:1` +- `pkg/cli/tracker_test.go:1` +- `pkg/cli/tree.go:1` +- `pkg/cli/tree_test.go:1` +- `pkg/cli/utils.go:1` + +## Supplemental: CLAUDE Test Naming Drift + +Tests not following the `_Good`, `_Bad`, `_Ugly` suffix convention from `CLAUDE.md:93`: + +- `cmd/core/pkgcmd/cmd_remove_test.go:33` +- `cmd/core/pkgcmd/cmd_remove_test.go:42` +- `cmd/core/pkgcmd/cmd_remove_test.go:54` +- `pkg/cli/ansi_test.go:8` +- `pkg/cli/app_test.go:129` +- `pkg/cli/check_test.go:5` +- `pkg/cli/daemon_test.go:9` +- `pkg/cli/glyph_test.go:5` +- `pkg/cli/glyph_test.go:17` +- `pkg/cli/layout_test.go:5` +- `pkg/cli/output_test.go:28`