Plan the shared validation foundation

This commit is contained in:
2026-10-07 17:14:26 +00:00
parent 7afc0de092
commit 8c742cd11d
2 changed files with 406 additions and 25 deletions

View File

@@ -1,13 +1,13 @@
# Validation API and profile model
Status: Agreed direction for v0.2.0; detailed API design and implementation
planning remain to be completed.
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](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.
capability's purpose and scope. The [implementation plan](implementation.md)
owns the stages and the remaining API rollout question.
## Rationale and current baseline
@@ -49,8 +49,8 @@ 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.
internal implementation owns execution. The [implementation plan](implementation.md)
records the proposed field names, representations, and rollout.
### Shared coordination
@@ -115,32 +115,20 @@ 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.
and diagnostic fields are proposed in the [implementation plan](implementation.md).
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
## Implementation
- 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.
The [implementation plan](implementation.md) 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