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 current executor runs the default offline Go suite. Its request carries the captured repository directory and commit, output writer, and internal settings. Request.ReadCandidateTree lets a selected file check request candidate contents; the default Go-only path does not enumerate the tree. 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. The roadmap coordination design owns the proposed test, vet, and package-compilation procedure.

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. Build 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.