Document configuration comparison behavior
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
# Adopt ConfigKit v0.7.1 and expose native configuration comparison
|
||||
|
||||
Status: end-state decisions selected; dependency adoption and `config diff` are
|
||||
not implemented. This roadmap defines the selected target and remaining gap;
|
||||
the [implementation plan](implementation.md) owns stages and execution order.
|
||||
Status: ConfigKit v0.7.1 adoption and ConfigKit-backed `config diff` are
|
||||
implemented. Distribution reconciliation and final validation remain in the
|
||||
[implementation plan](implementation.md), which records the evidence and order.
|
||||
|
||||
## Purpose and authority
|
||||
|
||||
@@ -34,14 +34,15 @@ disclosure; CommandKit owns selection, coordination, adaptation, and presentatio
|
||||
| Owner | Current state |
|
||||
| --- | --- |
|
||||
| Core module | Go 1.26.0; captured commands, typed bindings, dispatch, outcomes, help, and version. No ConfigKit dependency. ReleaseKit v0.4.0 is the declared maintainer tool. |
|
||||
| `integrations/ckconfig` | Requires ConfigKit v0.5.0. `Scope`, `Suite`, `FromConfigKit`, and `AppCommand` expose scopes/validate/show/sources/explain. No comparison operation or provider exists. |
|
||||
| `integrations/ckprompt` | Directly requires ConfigKit v0.5.0 and PromptKit v0.12.0. Depends on ckconfig's public scope contracts and adapts engine configuration plus named definitions. |
|
||||
| Deferred comparison | [DIFF-01](deferred.md#diff-01-semantic-configuration-comparison) records the target. Native semantics, selection syntax, provider representation, and the YAML-only report are selected; implementation remains pending. |
|
||||
| `integrations/ckconfig` | Requires ConfigKit v0.7.1. `Scope`, `Suite`, `FromConfigKit`, and `AppCommand` expose independently declared validate/show/sources/explain/diff capabilities. |
|
||||
| `integrations/ckprompt` | Requires ConfigKit v0.7.1 and PromptKit v0.12.0. It depends on ckconfig's public scope contracts and adapts engine configuration plus named definitions; its ConfigKit scope does not declare comparison. |
|
||||
| Comparison status | ConfigKit-backed `config diff` is implemented. The [CLI reference](../cli.md#compare-configuration-selections), integration GoDoc, and [implementation record](implementation.md) own current contracts and evidence. PromptKit comparison remains deferred. |
|
||||
|
||||
The existing ConfigKit adapter acquires a typed `*configkit.Result[T]` and exposes
|
||||
its effective, source, and explanation facets through `View`. That generic
|
||||
adapter is a useful place to retain typed results for comparison. `View` alone
|
||||
does not supply two results of the same `T` to `configkit.Diff`.
|
||||
The ConfigKit adapter acquires typed `*configkit.Result[T]` values and exposes
|
||||
effective, source, and explanation facets through `View` for ordinary operations.
|
||||
Its separate comparison callback retains `T`, loads both prepared selections,
|
||||
and returns the native records from `configkit.Diff` without routing through
|
||||
`View`.
|
||||
|
||||
ConfigKit v0.7.1 identifies source commit
|
||||
`6fffde4af8f31f99d3ee295c426eb3234cb0fb77`. Relative to the selected v0.5.0:
|
||||
@@ -53,15 +54,14 @@ ConfigKit v0.7.1 identifies source commit
|
||||
runtime/API change from v0.7.0.
|
||||
|
||||
The YAML dependency remains `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Existing public
|
||||
loading and inspection signatures are unchanged. The review found no apparent
|
||||
adapter migration requirement for existing operations; that is static review
|
||||
evidence, not a completed upgrade validation. See the pinned
|
||||
loading and inspection signatures are unchanged, and the integration suites pass
|
||||
with the adopted dependency. See the pinned
|
||||
[release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/6fffde4af8f31f99d3ee295c426eb3234cb0fb77/docs/releases/v0.7.1.md)
|
||||
and [comparison contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/6fffde4af8f31f99d3ee295c426eb3234cb0fb77/docs/config.md#effective-configuration-diffs).
|
||||
|
||||
## Dependency adoption and ownership
|
||||
|
||||
Both integration modules select ConfigKit v0.7.1 and carry normal dependency
|
||||
Both integration modules now select ConfigKit v0.7.1 and carry normal dependency
|
||||
metadata for their actual graphs. Consumer Go minimums remain 1.26.0, the selected
|
||||
release toolchain remains 1.26.8, and PromptKit remains v0.12.0 for this work.
|
||||
Core continues to have no ConfigKit or optional-integration dependency.
|
||||
@@ -115,7 +115,7 @@ empty diff without an invented requirement that an override be supplied. Do not
|
||||
short-circuit acquisition merely because the selections are equal: caller-owned
|
||||
loading may produce different effective results.
|
||||
|
||||
For example, these show the accepted target syntax, not current commands:
|
||||
For example, these are current invocations:
|
||||
|
||||
```text
|
||||
app config diff --config before.yml --against-config after.yml
|
||||
@@ -255,12 +255,12 @@ boundaries; do not promise interruption inside a synchronous upstream call.
|
||||
|
||||
### Comparison provider and ConfigKit adapters
|
||||
|
||||
Add a narrow optional comparison callback to `ckconfig.Scope[I, S]`. Its request
|
||||
`ckconfig.Scope[I, S]` exposes a narrow optional comparison callback. Its request
|
||||
groups each side's selection with its separately prepared typed input and supplies
|
||||
one shared state value separately. Return
|
||||
`commandkit.Acquired[[]configkit.Difference]` plus an error, following the existing
|
||||
acquisition convention. Reuse upstream public record types rather than duplicate
|
||||
them solely to rename fields. The selected target shape in ckconfig is:
|
||||
acquisition convention. It reuses upstream public record types rather than
|
||||
duplicating them solely to rename fields. The current API shape is:
|
||||
|
||||
```go
|
||||
type ComparisonSide[I any] struct {
|
||||
@@ -273,13 +273,13 @@ type ComparisonRequest[I any] struct {
|
||||
Right ComparisonSide[I]
|
||||
}
|
||||
|
||||
// Accepted target field on Scope[I, S]:
|
||||
// Current field on Scope[I, S]:
|
||||
// Compare func(context.Context, ComparisonRequest[I], S) (commandkit.Acquired[[]configkit.Difference], error)
|
||||
```
|
||||
|
||||
These names and the callback shape are selected for implementation; they are not
|
||||
implemented exports. ADR 0012 records paired provider ownership and input/state
|
||||
lifetimes; this roadmap owns the target declarations until the Go API is implemented.
|
||||
These are the implemented exports in `integrations/ckconfig/contracts.go`.
|
||||
ADR 0012 records paired provider ownership and input/state lifetimes; GoDoc owns
|
||||
the exact public declarations.
|
||||
|
||||
`AppCommand` and `FromConfigKit` provide native comparison alongside their existing
|
||||
supported operations, with ordinary capability narrowing available. They use the
|
||||
@@ -306,19 +306,18 @@ or loads need not run after failure. Declaration construction, installation, hel
|
||||
version, and scope discovery leave input/state factories and acquisition/comparison
|
||||
callbacks uninvoked.
|
||||
ADR 0012 records this two-selection specialization of ADR 0011's suite lifecycle,
|
||||
and the architecture policy reflects it. Document the exact implemented API
|
||||
contract in Go declarations and GoDoc when it lands.
|
||||
and the architecture policy reflects it. The exact API contract is in the Go
|
||||
declarations and GoDoc.
|
||||
|
||||
### Application-owned state and caches
|
||||
|
||||
Generic result handling stays inside the owning adapter, without reflection,
|
||||
private-core access, or result type assertions. Shared state supports consumer
|
||||
caches whose keys distinguish the effective selections and any typed-input values
|
||||
that affect loading. A cache
|
||||
that stores only one configuration can incorrectly reuse the left result for the
|
||||
right and report equality. Demonstrate correct keys in the maintained example;
|
||||
CommandKit neither supplies nor repairs application caches. Cache policy and
|
||||
factory objects remain caller-owned.
|
||||
that affect loading. A cache that stores only one configuration can incorrectly
|
||||
reuse the left result for the right and report equality. The composed example
|
||||
demonstrates selection- and input-aware keys; CommandKit neither supplies nor
|
||||
repairs application caches. Cache policy and factory objects remain caller-owned.
|
||||
|
||||
## Design tradeoffs
|
||||
|
||||
@@ -340,46 +339,15 @@ values while representing removals explicitly. Omitting empty categories would
|
||||
shorten output but require missing-key handling; a separate text renderer adds no
|
||||
needed operator value for this delivery.
|
||||
|
||||
## Work needed from the baseline
|
||||
## Implementation record
|
||||
|
||||
These work areas close the gap from the current implementation to the selected
|
||||
end state above. The [implementation plan](implementation.md) defines their
|
||||
execution order and completion evidence.
|
||||
|
||||
- **Dependency adoption:** upgrade both integration requirements, reconcile sums
|
||||
and indirect/tool dependencies, and assess PromptKit v0.12.0 against the newly
|
||||
selected ConfigKit version. Preserve distributed manifests without sibling
|
||||
replacements or committed workspace files.
|
||||
- **Capability and provider API:** extend ckconfig's operation/capture/validation
|
||||
model for the selected comparison provider. Preserve retained adapter errors,
|
||||
capability narrowing, metadata-only scopes, and validation only of bindings
|
||||
used by generated commands. Do not require an ordinary acquisition provider
|
||||
for a comparison-only scope if its selected pair provider is sufficient.
|
||||
- **Typed preparation:** capture comparison selection metadata and applicable
|
||||
selector lists once. Prepare/check the selected pair through core bindings,
|
||||
with state and callback timing from the chosen lifecycle. Keep caller-owned
|
||||
objects and aliases under existing ownership rules.
|
||||
- **Native adaptation:** extend the typed ConfigKit adapter/convenience factory
|
||||
to load the selected pair and call `configkit.Diff`. Reuse diagnostic adaptation
|
||||
and ordinary error handling without introducing a generic provider framework,
|
||||
global cache, or untyped result transport.
|
||||
- **Command and reports:** generate the conditional `config diff` declaration,
|
||||
integrate it with discovery/help, and render the chosen report contract using
|
||||
native safe values. Preserve existing operation/report behavior.
|
||||
- **Documentation and distribution:** update GoDoc, CLI/consumer guidance,
|
||||
maintained examples, affected module notices and pinned ConfigKit links, and
|
||||
relevant release notes as implementation lands. Include a maintained comparison
|
||||
example that loads genuinely different selections through shared state, with
|
||||
cache keys accounting for the selection and typed-input values used by its
|
||||
loader. Review transitive tool notices for the actual graph. Move DIFF-01's
|
||||
implemented portion out of deferred work; retain unresolved future PromptKit
|
||||
comparison and unrelated proposals.
|
||||
- **Validation evidence:** run each affected module's deterministic offline suite
|
||||
and representative consumers. Check module/package boundaries independently
|
||||
with workspace mode off. If CommandKit prerequisite versions remain unpublished,
|
||||
use disposable alternate module files for local-source wiring evidence, as
|
||||
described in the [development guide](../development.md#documentation-validation).
|
||||
Do not fabricate future checksums or turn migration checks into permanent gates.
|
||||
Dependency adoption, capability and typed-pair preparation, native adaptation,
|
||||
YAML reporting, end-to-end execution, and both maintained comparison examples
|
||||
are implemented. Current API and operator contracts belong to GoDoc, the
|
||||
[CLI reference](../cli.md#compare-configuration-selections), the
|
||||
[consumer guide](../consumers/guide.md#configkit-scopes), and the example
|
||||
READMEs. The [implementation plan](implementation.md) records stage-by-stage
|
||||
changes and validation; distribution reconciliation and final validation remain.
|
||||
|
||||
### Focused behavioral evidence
|
||||
|
||||
|
||||
@@ -18,29 +18,20 @@ an idea here does not select its syntax, API, priority, or delivery date.
|
||||
|
||||
## Deferred capability targets
|
||||
|
||||
### DIFF-01: semantic configuration comparison
|
||||
### PromptKit configuration comparison
|
||||
|
||||
Expose comparison of two independently resolved selections of one scope using
|
||||
owning-library public comparison APIs. [ADR 0008](../adr/0008-semantic-configuration-diff.md)
|
||||
owns native comparison, paired safe disclosure, and the reduced default report.
|
||||
The target includes a YAML-only report of safe changed regions; completed
|
||||
comparisons succeed whether or not they find differences.
|
||||
ConfigKit-backed `config diff` is implemented by `ckconfig` for scopes that
|
||||
declare that capability. `ckprompt.ConfigScope` does not declare comparison.
|
||||
Reassess PromptKit's supported public comparison capabilities before planning a
|
||||
PromptKit comparison. Do not reach into ConfigKit internals or infer comparison
|
||||
semantics from rendered YAML.
|
||||
|
||||
The initial review of ConfigKit v0.5.0 and PromptKit v0.12.0 did not find the
|
||||
public comparison support needed for that target. ConfigKit v0.7.0 introduced
|
||||
`configkit.Diff`, retained in v0.7.1, which supplies native comparison and paired
|
||||
safe changed-region snapshots. CommandKit still uses ConfigKit v0.5.0; dependency
|
||||
adoption and comparison delivery are targeted by the
|
||||
[ConfigKit roadmap](configkit.md). Assess PromptKit's supported
|
||||
public comparison capabilities separately. Rendered YAML and sibling internals
|
||||
are not substitutes for the owning library's public comparison contract.
|
||||
### Comparison extensions
|
||||
|
||||
The ConfigKit roadmap records accepted selection syntax and the paired provider
|
||||
API, with lifecycle recorded in
|
||||
[ADR 0012](../adr/0012-typed-configuration-comparison-pairs.md). The selected report
|
||||
shape is recorded in that roadmap. Independent per-side domain selectors and
|
||||
an optional assertion mode remain outside that delivery. Add public types and
|
||||
handlers with their implementation rather than exposing placeholders.
|
||||
Independent per-side domain selectors and an optional assertion mode remain
|
||||
unselected extensions to the delivered ConfigKit comparison. Consider them only
|
||||
for a concrete consumer need and a deliberate API/behavior decision under the
|
||||
relevant ADRs.
|
||||
|
||||
### CAT-01: PromptKit catalogs
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Implement ConfigKit adoption and configuration comparison
|
||||
|
||||
Status: implementation in progress; Stages 1–10 are complete.
|
||||
Status: implementation in progress; Stages 1–11 are complete.
|
||||
|
||||
## Scope and authority
|
||||
|
||||
@@ -545,9 +545,20 @@ canonical owners, while future/deferred work stays clearly separate.
|
||||
symbols. Keep accepted ADR decision text unchanged; presentation details
|
||||
remain in CLI/API owners rather than returning to ADRs.
|
||||
|
||||
**Completion evidence:** current operator/API/consumer owners agree with the
|
||||
implemented behavior; no stale four-operation convenience claims, text-diff
|
||||
promises, or deferred markers for delivered ConfigKit comparison.
|
||||
**Completion evidence — complete:** ckconfig GoDoc now describes all five
|
||||
operations, paired input lifetimes, shared state, native records, diagnostics,
|
||||
and supported error identity. The ckconfig README, CLI reference, consumer guide,
|
||||
internal overview, development examples, and maintained example READMEs describe
|
||||
current ConfigKit comparison behavior. The CLI owner covers independent right
|
||||
inheritance and supplied presence, native effective-value semantics, reduced
|
||||
safe YAML categories, null/deletion, concealed regions, empty output, root
|
||||
ambiguity, diagnostics, and outcome delivery. The ConfigKit feature roadmap now
|
||||
records implementation status; the deferred record no longer carries ConfigKit
|
||||
comparison as pending work and retains PromptKit comparison, independent per-side
|
||||
domain selectors, catalogs, and other unselected ideas. The accepted ADRs were
|
||||
left unchanged. Local Markdown targets/fragments and copied commands were
|
||||
reviewed; a local link check and `git diff --check -- '*.md'` passed. `go doc`
|
||||
was inspected for the exported comparison API.
|
||||
|
||||
## Stage 12: Reconcile manifests, notices, and pending integration release notes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user