7.4 KiB
Validation API and profile model
Status: Agreed direction for v0.2.0; a proposed staged plan records the API design and an open question about its rollout.
This roadmap describes the shared model that enables the optional validation capabilities in the v0.2.0 roadmap. It owns their common API, configuration, execution, and diagnostic design. The release roadmap owns each capability's purpose and scope. The implementation plan owns the stages and the remaining API rollout question.
Rationale and current baseline
ReleaseKit v0.1.0 exposes Check and Publish through the root facade. Both
accept ReleaseRequest and use shared candidate-validation machinery. Validation
runs the standard offline Go suite, followed by AdditionalChecks when supplied.
Selected executable builds follow validation. The CLI maps profile checks
commands to the additional-check callback.
This provides a common procedure and a product-specific extension point. The request and profile currently have no structured selection for shared optional validation. Race testing, full vet, package compilation, formatting, Markdown, module-distribution, and file-size checks need a coherent home as they are added.
The model should let consumers declare their choices once while ReleaseKit owns execution and coordination. This follows ADR 0002: shared capabilities should reduce application code and routine developer decisions. The facade boundaries in ADR 0001 provide the existing architectural foundation.
Optional capabilities can serve a small subset of consumers when they remove application-owned release mechanics and have clear scope, compact configuration, and proportionate maintenance costs.
Target end state
One validation specification
Add a facade-owned ValidationSpec to ReleaseRequest, with a corresponding
validation object in the release profile. Use typed Go fields and ordinary
JSON settings to express the same supported selections. Group related choices,
including base-test and vet settings, so their relationship is clear.
The specification accommodates the agreed capabilities in the release roadmap, including optional Markdown boundary enforcement, independent module-distribution rules, and file-size settings. Its zero value and an omitted profile object preserve current default validation. Consumers enable optional checks according to their product needs.
Go callers and CLI users receive equivalent validation behavior. The CLI owns profile parsing and presentation; the facade owns the public types and contracts; internal implementation owns execution. The implementation plan records the proposed field names, representations, and rollout.
Shared coordination
Check and Publish pass the same specification through one internal validation
path bound to the captured candidate. ReleaseKit constructs the selected Go
commands, manages its shared environment, determines execution order, and
propagates failures and cancellation.
Race selection changes the one base suite invocation. Selecting a separate full-vet pass automatically omits test-time vet. Package-compilation targets express compatibility checks independently of executable artifact selection. Consumers obtain this coordination through their declarations.
Keep the executor straightforward and internal, with ordinary functions for the selected capabilities. The public model expresses validation choices; ReleaseKit maintains their execution procedure. Existing candidate rechecks, offline validation, and source-publication outcomes retain their meaning.
Candidate-content inspection
File-oriented checks share candidate-file enumeration and inspection where useful. Their scope is the captured candidate, and inspection remains offline and read-only. Inspect committed candidate contents and define symlink and submodule handling explicitly in the shared inspection model. Module-distribution rules inspect the files being released independently of the environment used to run Go commands. Markdown boundary validation operates independently of neighboring checkout contents.
Keep each check's settings together: Markdown validation owns its optional boundary rule; module-distribution validation owns its independent rule selections; file-size validation owns its limit and path exclusions. The release roadmap defines the scope and defaults of each capability.
Clear responsibility boundaries
| Concern | Model owner |
|---|---|
| Base tests, full vet, and package compilation | Shared validation specification |
| Formatting, Markdown links, module distribution, and file size | Shared validation specification |
| Product-specific assertions and example checks | Existing AdditionalChecks callback and profile checks |
| Expected authoritative push destination | Publication settings and endpoint handling |
| Executable package, binary name, and artifact targets | Build declaration |
| Hosted destination and credentials | Delivery settings |
AdditionalChecks and profile checks remain available for substantive
consumer behavior. Shared capabilities use the validation specification.
Preserve the current behavior of existing declarations as the new options land.
The expected-endpoint feature remains a publication guard, and Check remains
local-only. Selecting package-compilation checks leaves a source-only consumer's
deliverable selection unchanged. Tool installation and dependency preparation
remain separate from offline candidate validation.
Consistent diagnostics
Shared validation failures identify the check and expose useful details to Go callers. File-oriented checks provide source locations and actionable findings where applicable, including relevant paths, directives, and measured values. The CLI presents those details consistently through the ordinary candidate-check and publication commands.
Use a small facade-owned error model with stable check identity and support for
underlying error causes and cancellation. Preserve errors.Is and errors.As
behavior across internal conversions and facade wrapping. Exact error types
and diagnostic fields are proposed in the implementation plan.
Validation failures and publication outcomes have distinct meanings. Existing publication states continue to describe whether publication was attempted, confirmed, conflicted, or remains uncertain. The model preserves the existing failure-stopping behavior of the candidate workflow.
Implementation
The implementation plan defines the enabling sequence, proposed declarations and diagnostics, inspection primitives, verification, and documentation work. Individual capabilities supply their behavioral coverage as they are implemented. The target state above describes the complete model across those capabilities.
Adoption evidence
Evaluate the design against all three known consumer shapes: Audita's default validation and executable builds; ConfigKit's selected test, vet, and library compilation checks; and PromptKit's shared validation plus substantive example assertions.
Completion should give each consumer a small declaration and the same routine release operation. The model should support the agreed v0.2.0 capabilities with shared execution and clear diagnostics while keeping product-specific work in the existing extension point.