Skip to content

[Tech Debt] Split docscheck's structural checks when a third one arrives #17

Description

@charles-fineman

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 readDocumentblankFencedCodeblankHTMLCommentscodeSpanAt
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):

  • Markdown-claim checks and cross-file structural checks live in separate packages
  • The check.Errors ordering contract (by check, then by location) is preserved across the split
  • The package's location communicates that it is repository tooling, not part of the CLI
  • go test ./... still reaches every check

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions