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. Resolved module bodies are parsed once per blob object ID; only owned filesystem-replacement targets and line numbers remain cached. Each declaration path receives findings from that summary in its own path context. The optional file-size check uses each blob's captured Git size, including symlink link-text bytes, and skips entries without a blob size such as gitlinks. It applies normalized literal file/directory exclusions with path-boundary matching, then returns the first oversized path with FileSizeMeasurement. The optional Markdown check follows file-size inspection and uses the same candidate tree. It parses regular Markdown blobs, resolves local destinations, and checks supported anchors; outside-checkout and submodule observations are written to the shared output writer. A nil writer keeps library use quiet. CandidateTree gets metadata and bytes from Git objects, reads blob bytes lazily, and resolves destinations without consulting the worktree or neighboring files. Each tree owns one lazy Git blob reader; direct tree users must close it when finished. The shared validation executor closes its tree on every return before product checks or build callbacks run. A metadata-only selection never starts the reader. Per-read contexts cancel an in-flight blob exchange. The context supplied when creating the tree governs the reader lifetime, including shutdown and child reaping. Regular-file reads return independent caller-owned byte slices and are not retained by the tree. Symlink targets are retained as immutable owned strings by blob object ID; explicitly reading a symlink still returns independent bytes. The Go-format check caches only whether each successfully inspected object is formatted, then reports every unformatted path that refers to it.

The internal Markdown parser uses Goldmark to record inline, reference, and autolinks, images, titles, and their source use sites, and to build heading anchors from visible AST text. It supports ATX and Setext headings, decodes Markdown text through the parser, and assigns collision-free numeric suffixes to repeated anchors. Link locations use one-based line and byte-column values. The Markdown cache shares parsed records and anchors by regular blob object ID, with a path lookup for callers. Retained destinations and titles own their string storage, and parsed records contain content-relative locations only.

checkMarkdownLinks examines regular .md blobs from the captured tree. It skips schemed and protocol-relative URIs, strips query components, and decodes percent escapes once in local paths and fragments. It resolves destinations through CandidateTree.ResolveDestination relative to the current source path; decoded fragments are compared in lowercase against anchors from the resolved regular Markdown document. Missing paths, symlink cycles, and missing anchors produce markdown-links findings at the source use site. Outside-checkout links produce out-of-scope observations by default and findings when boundary enforcement is selected. Submodule-content observations remain out of scope under either setting. Observations go to the provided writer; a nil writer keeps library use quiet. Public selection is defined in the configuration reference and GoDoc.

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. Record proposed checks under docs/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.

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 public selection is owned by the facade and profile; the internal checker uses the committed-file and destination-resolution primitives described here.