156 lines
8.1 KiB
Markdown
156 lines
8.1 KiB
Markdown
# Validation API and profile model
|
|
|
|
Status: Agreed direction for v0.2.0; detailed API design and implementation
|
|
planning remain to be completed.
|
|
|
|
This roadmap describes the shared model that enables the optional validation
|
|
capabilities in the [v0.2.0 roadmap](v0.2.0.md). It owns their common API,
|
|
configuration, execution, and diagnostic design. The release roadmap owns each
|
|
capability's purpose and scope. A staged implementation plan will follow the
|
|
finalized release scope.
|
|
|
|
## 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](../adr/0002-routine-releases.md):
|
|
shared capabilities should reduce application code and routine developer
|
|
decisions. The facade boundaries in [ADR 0001](../adr/0001-public-facade.md)
|
|
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](v0.2.0.md), 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. Exact field names and representations
|
|
will be settled together during implementation planning.
|
|
|
|
### 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](v0.2.0.md) 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 will be selected for the agreed capabilities during API
|
|
design.
|
|
|
|
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.
|
|
|
|
## Work needed
|
|
|
|
- Design the Go validation specification and profile representation together,
|
|
covering defaults, related selections, and their mapping to shared execution.
|
|
- Consolidate request conversion and validation coordination where needed so
|
|
`Check`, `Publish`, and their CLI forms use the same decisions.
|
|
- Define shared candidate-file inspection and compact settings for related
|
|
rules, limits, and exclusions, preserving each capability's declared scope.
|
|
- Define check identity, useful diagnostic detail, error wrapping, and CLI
|
|
presentation as one small model for the accepted capabilities.
|
|
- Preserve the additional-check extension point and the separate publication,
|
|
build, and delivery responsibilities while integrating the new specification.
|
|
- Update GoDoc, configuration and CLI references, consumer examples, and
|
|
internal guidance as the model is implemented. Explain any migration needed
|
|
for existing additional commands that become shared selections.
|
|
- Verify unchanged default behavior, equivalent API/profile selections, one
|
|
base suite execution, coordinated test/vet behavior, and failure/cancellation
|
|
propagation. Individual feature work supplies its own behavioral coverage.
|
|
|
|
## 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.
|