From f4a32dae736de26876daea9b6e00fa681cb6f567 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 7 Oct 2026 16:46:18 +0000 Subject: [PATCH] Expand optional candidate checks for v0.2.0 --- docs/roadmap/model.md | 40 +++++++++++++++----- docs/roadmap/v0.2.0.md | 86 ++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 113 insertions(+), 13 deletions(-) diff --git a/docs/roadmap/model.md b/docs/roadmap/model.md index 8c211c3..5d010a2 100644 --- a/docs/roadmap/model.md +++ b/docs/roadmap/model.md @@ -19,8 +19,8 @@ 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, and -Markdown checks need a coherent home as they are added. +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): @@ -28,6 +28,10 @@ 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 @@ -37,10 +41,11 @@ Add a facade-owned `ValidationSpec` to `ReleaseRequest`, with a corresponding 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 race, full-vet, package-compilation, -Go-formatting, and Markdown-link capabilities. Its zero value and an omitted -profile object preserve current default validation. Consumers enable optional -checks according to their product needs. +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; @@ -64,11 +69,25 @@ 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. 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, package compilation, formatting, and Markdown links | Shared validation specification | +| 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 | @@ -87,8 +106,9 @@ remain separate from offline candidate validation. Shared validation failures identify the check and expose useful details to Go callers. File-oriented checks provide source locations and actionable findings -where applicable. The CLI presents those details consistently through the -ordinary candidate-check and publication commands. +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` @@ -107,6 +127,8 @@ failure-stopping behavior of the candidate workflow. 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, diff --git a/docs/roadmap/v0.2.0.md b/docs/roadmap/v0.2.0.md index 533b411..e4854aa 100644 --- a/docs/roadmap/v0.2.0.md +++ b/docs/roadmap/v0.2.0.md @@ -272,6 +272,8 @@ ReleaseKit currently leaves these mechanics to consumer-owned additional checks. Sharing the check would remove a locally maintained parser and give consumers one documented convention for validating navigation within their documentation. +Consumers that require documentation to remain within the checkout also need +a shared option to enforce that boundary. ### Target end state @@ -286,9 +288,10 @@ can follow. The supported behavior accounts for common inline and reference links, code examples, escaped destinations, and duplicate headings. External website availability is outside the check's scope. -Links outside the checkout are classified and reported as outside the shared -check's scope. Validation remains independent of neighboring checkouts; -consumer-specific restrictions on those links remain additional product checks. +By default, links outside the checkout are classified and reported as outside +the shared check's scope. An optional setting makes local destinations outside +the checkout a validation failure, using the same parser and diagnostics. +Boundary validation remains independent of neighboring checkout contents. Existing validation defaults remain unchanged when the option is unset. ### Work needed @@ -297,11 +300,86 @@ Existing validation defaults remain unchanged when the option is unset. including destination resolution and diagnostics for out-of-scope links. - Add shared parsing and local destination/fragment validation behind the public validation API and profile selection. +- Add the optional checkout-boundary rule to the shared Markdown settings, + with diagnostics that identify the source location and destination. - Document supported behavior and verify valid and broken links, heading fragments, representative Markdown syntax, and handling of code examples - and links outside the checkout. + and links outside the checkout with the boundary rule enabled and disabled. - Verify that checking is offline, preserves files, and behaves consistently through candidate checking and publication. Completion should let PromptKit replace its local Markdown checker with a profile selection and rely on shared parsing rules and diagnostics. + +## 9. Offer module-distribution checks + +### Rationale and current baseline + +PromptKit checks that released source is independent of neighboring checkouts +by excluding committed workspace files and local filesystem module replacements. +ReleaseKit's offline Go environment controls validation execution; inspecting +the distributed candidate requires separate checks that consumers currently own. + +Shared inspection would remove these local checks and provide consistent +diagnostics for consumers with the same distribution requirements. + +### Target end state + +The public API and profile offer independently selectable rules for committed +workspace files (`go.work` and `go.work.sum`) and local filesystem replacements +in committed module declarations. Each selected rule reports offending paths +and, where applicable, module directives through shared candidate validation. + +The replacement rule permits versioned module replacements. Workspace use and +vendoring retain their existing behavior unless affected by a selected rule. +The checks inspect candidate contents independently of the Go test environment. +`Check` and `Publish`, including their CLI forms, apply the same offline, +read-only checks. Omitted selections preserve current defaults. + +### Work needed + +- Add independent distribution-rule selections to the validation API and profile. +- Implement shared candidate-file inspection and module-declaration parsing, + distinguishing local filesystem replacements from versioned replacements. +- Document the inspection scope and diagnostics, and verify workspace files, + local and versioned replacements, and independent rule selection. +- Verify equivalent API/CLI behavior, unchanged defaults, and inspection of + distributed files regardless of workspace discovery settings during testing. + +Completion should let PromptKit declare its distribution requirements and +remove the corresponding consumer-owned checks. + +## 10. Offer an individual-file-size check + +### Rationale and current baseline + +Unintentionally committed binaries and large assets can increase the size of +released source. ReleaseKit currently leaves file-size inspection to consumers. +A shared check would catch oversized files while allowing each consumer to +declare its intended size limit and exceptions. + +### Target end state + +An optional public API and profile selection checks individual tracked files +in the current candidate. When enabled, the default limit is 1 MB (1,000,000 +bytes); consumers can configure the limit and explicit repository-relative +path exclusions for intentional large files. A file exceeding the limit fails +validation with its path, observed size, and configured limit. + +The check measures file size. Small binaries remain subject to ordinary review. +Its scope is the current candidate's files; historical objects and aggregate +repository size remain separate concerns. `Check` and `Publish`, including +their CLI forms, use the same offline, read-only inspection. The check is +disabled by default. + +### Work needed + +- Add file-size selection, a configurable byte limit, and path exclusions to + the shared validation API and profile. +- Implement candidate-file size inspection with actionable diagnostics. +- Document units, threshold behavior, exclusions, and the scope of inspection. +- Verify files below, at, and above the limit; configured limits and exclusions; + and equivalent API/CLI behavior with the check enabled and disabled. + +Completion should let consumers catch oversized candidate files through a +small declaration and remove any corresponding local inspection code.