docs: add convention drift audit
This commit is contained in:
Virgil
parent
e177418c90
commit
77b76e9541
1 changed files with 184 additions and 0 deletions
184
docs/convention-drift-audit-2026-03-23.md
Normal file
184
docs/convention-drift-audit-2026-03-23.md
Normal file
|
|
@ -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`
|
||||
Loading…
Add table
Reference in a new issue