ReleaseKit/docs/internal/validation.md

Shared validation mechanics

internal/validation owns reusable checks for one captured candidate. internal/candidate captures the clean source revision and keeps the validation sequence shared by local checking and publication. It calls the shared executor, runs product-specific AdditionalChecks once, and owns the post-validation build callback and local-state recheck. internal/publish adds its endpoint guards, tag creation, push, and recovery around that same candidate path.

The executor runs one offline Go suite, optionally with the race detector when selected. When full vet is selected, it disables test-time vet for that suite and runs native go vet -mod=readonly ./... after the suite succeeds. It then runs go build -mod=readonly -o <os.DevNull> ./... in static mode for each selected package-compilation target, preserving target order and stopping on the first failure. This compiles source without producing an artifact or executing a target binary. Test, vet, and package-compilation failures retain their go-test, go-vet, and package-compile identities, selected target where applicable, and underlying causes. Its request carries the captured repository directory and commit, output writer, and internal settings. When selected, the Go-format check loads the candidate tree once, reads regular Go blobs from the captured commit, and compares them with go/format output. It includes vendor and nested-module files, skips symlink blobs, reports all unformatted paths, and stops with a contextual cause on parse or inspection errors. It runs before product checks and build callbacks. Request.ReadCandidateTree lets selected file checks request candidate contents; the Go-only path does not enumerate the tree.

The workspace-file check uses that same candidate inventory and reports blob entries named go.work or go.work.sum, including nested paths and symlink blobs. It does not read workspace contents or depend on the workspace selected for Go commands. The local-replacement check parses every committed go.mod blob with golang.org/x/mod/modfile, including nested modules and vendor declarations. It follows committed symlink declarations through the captured tree and fails with an inspection cause when their selected contents are unavailable. A replacement with no parsed version is reported with its go.mod path, line, directive, and target; versioned replacements are allowed. It runs after the workspace-file check using the same candidate inventory. CandidateTree gets metadata and bytes from Git objects, reads blob bytes lazily, and resolves destinations without consulting the worktree or neighboring files.

Committed-tree metadata and blob reads disable lazy fetching and Git transports for those child commands. Missing local objects produce inspection errors; source preparation retains its separate network-capable operations. See Git's lazy-fetch controls for the command mechanism.

Public validation errors convert their diagnostic fields to the internal failure model for shared formatting. Converted failures retain their original contextual cause and reuse its rendering when it already contains the same diagnostics. The CLI presents the complete error chain, including candidate context around callback-supplied diagnostics.

Adding a shared check

When an optional check is accepted for implementation:

1. Define its typed Go setting in the root facade and its equivalent CLI-owned JSON field. Specify zero-value and omitted-profile behavior in GoDoc and the configuration reference. Keep future settings in the roadmap until their check is implemented.
2. Add the corresponding internal setting and explicit conversions. Use the same root request conversion for Check and Publish, and the shared CLI request conversion for profile-based candidate commands.
3. Implement a plain check function owned by internal/validation. Keep its rule semantics in the capability owner and pass only the captured candidate inputs it needs. A file-oriented check can call Request.ReadCandidateTree and read only the blobs it inspects.
4. Return an internal *Failure with the check identity, repository-relative findings, useful locations where available, and the underlying cause. Let the root facade convert those records to its own diagnostic types. Preserve cancellation and process errors through Unwrap.
5. Add the check to the shared executor at the ordering point selected by its capability. Stop on failure. Keep product assertions in AdditionalChecks and profile checks; keep artifact building in internal/build.
6. Cover observable behavior through both the Go facade and profile path when both are supported. Check default behavior, useful findings, cause preservation, cancellation where relevant, and failure stopping. Reuse the existing local Git and CLI fixtures.
7. Update only the canonical owners for behavior that has landed: GoDoc for the API, configuration and CLI references for profile behavior, and this inventory for internal ownership. Keep later feature contracts in the product roadmap.

Do not add a public validator registration interface. The public specification selects ReleaseKit-owned checks; AdditionalChecks remains the extension point for product behavior.

Go command environment reuse

The current executor uses the shared Go command environment for its offline suite, vet pass, and selected-target package compilation. The implementation roadmap records the shared ordering across validation and later file checks.

Reuse internal/gotool for native and static environments and target handling. Keep toolchain and module-cache discovery in gotool; do not reproduce its environment logic in a checker. Artifact output names, version injection, native smoke checks, and artifact digests remain owned by internal/build.

File-check coordination

File checks consume the captured tree and return findings to the shared error model. They do not read sibling worktrees or follow live symlink targets. CandidateTree.ResolveDestination returns data describing entries, directories, missing paths, checkout boundaries, submodule paths, and symlink cycles; the caller selects which observations fail validation or are reported as out of scope.

Resolution walks committed components and symlink targets in order. Active symlink expansion detects cycles, and traversal honors cancellation. Absolute destinations and symlink targets within the repository directory map back to candidate-relative paths; existence still comes from committed entries.

The Markdown roadmap owns proposed link syntax, anchors, diagnostics, and boundary policy. This foundation provides committed-file and destination-resolution primitives.