83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# 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.
|
|
|
|
## 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.
|
|
|
|
## Prospective Go command recipe
|
|
|
|
The complete planned procedure uses one test invocation. Race selection
|
|
modifies that command. When a separate full vet pass is selected, run tests with
|
|
vet disabled and then run native `go vet`. Selected package-compilation targets
|
|
run after test and vet with the static Go environment, including
|
|
`CGO_ENABLED=0`. Keep these compatibility checks independent of executable
|
|
artifact declarations. These selections become operational as their checkers
|
|
are implemented.
|
|
|
|
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.
|
|
|
|
The Markdown capability will use PromptKit's current parser and anchor
|
|
conventions as its starting evidence. Supported link syntax, anchors,
|
|
diagnostics, and boundary policy belong to that feature's roadmap and
|
|
implementation prompt. This foundation provides only the committed-file and
|
|
destination-resolution primitives.
|