Context:
Identified in the architectural review of #12.
This is a watch item with an explicit trigger, not work to schedule now.
Description:
internal/docscheck holds four checks that split cleanly into two structural families:
| Family |
Checks |
Shared machinery |
| Markdown-claim |
CheckLinks, CheckNamedPaths, CheckChangelog |
all read through readDocument → blankFencedCode → blankHTMLComments → codeSpanAt |
| Cross-file structural drift |
CheckSelfCheckCommands |
none of the above; hand-parses workflow YAML as indented text |
CheckSelfCheckCommands shares no parser with the three it sits beside, matches workflow structure rather than Markdown structure, and is the most fragile check in the file — its correctness depends on an exact formatting convention in two files the package does not own.
Related: internal/docscheck sits among internal/'s CLI-domain packages (check, matrix, threats, render, ...) despite being the only one nothing in cmd/ imports. The package comment discloses this in its first three lines, but ls internal/ gives no signal that one of eleven entries is categorically different. Note that go test ./... reaches any package under the module root, so internal/ is not actually required — a top-level repotest/ or tools/selfcheck/ would communicate the status at the filesystem level.
Trigger:
Split when a third structural/config-drift check appears — for example "docs/config.md keys match internal/policy/config.go fields", which #10 gestures at. At that point, move the structural checks to a sibling package and relocate out of internal/ in the same change.
Rationale:
Explicitly not worth doing today. One structural check behind a four-line CheckAll aggregator is easy to read in one sitting, and splitting for a single check is premature decomposition. Relocating now and possibly again later is worse than relocating once for a clearer reason. But waiting past a third check risks the package becoming a junk drawer of "things that check the repo somehow".
Reference:
Acceptance Criteria (when triggered):
Context:
Identified in the architectural review of #12.
This is a watch item with an explicit trigger, not work to schedule now.
Description:
internal/docscheckholds four checks that split cleanly into two structural families:CheckLinks,CheckNamedPaths,CheckChangelogreadDocument→blankFencedCode→blankHTMLComments→codeSpanAtCheckSelfCheckCommandsCheckSelfCheckCommandsshares no parser with the three it sits beside, matches workflow structure rather than Markdown structure, and is the most fragile check in the file — its correctness depends on an exact formatting convention in two files the package does not own.Related:
internal/docschecksits amonginternal/'s CLI-domain packages (check,matrix,threats,render, ...) despite being the only one nothing incmd/imports. The package comment discloses this in its first three lines, butls internal/gives no signal that one of eleven entries is categorically different. Note thatgo test ./...reaches any package under the module root, sointernal/is not actually required — a top-levelrepotest/ortools/selfcheck/would communicate the status at the filesystem level.Trigger:
Split when a third structural/config-drift check appears — for example "
docs/config.mdkeys matchinternal/policy/config.gofields", which #10 gestures at. At that point, move the structural checks to a sibling package and relocate out ofinternal/in the same change.Rationale:
Explicitly not worth doing today. One structural check behind a four-line
CheckAllaggregator is easy to read in one sitting, and splitting for a single check is premature decomposition. Relocating now and possibly again later is worse than relocating once for a clearer reason. But waiting past a third check risks the package becoming a junk drawer of "things that check the repo somehow".Reference:
internal/docscheck/docscheck.go—CheckAll,CheckSelfCheckCommands,workflowSelfCheckCommandsAcceptance Criteria (when triggered):
check.Errorsordering contract (by check, then by location) is preserved across the splitgo test ./...still reaches every check