Add mounted collection consumer examples
This commit is contained in:
@@ -17,6 +17,7 @@ sanitized shapes using only ConfigKit and the Go standard library:
|
||||
| Seriatim-like | Independent strict ordered speaker and autocorrect rule files | First-match and ordered replacement algorithms; no central application configuration file |
|
||||
| Bundled file | Simple native `fs.FS` source through ordinary `Load` | Selection and lifetime of the application-owned embedded filesystem |
|
||||
| Layered catalog | Embedded defaults with an import, a mapping underlay, an independent host main file, explicit false/zero input, and source-relative resource access | Domain validation and opening/interpreting the template resource |
|
||||
| Mounted collections | Literal input destinations, peer prompt/profile fragments, local inheritance, imported collection metadata, and a version-only higher-tier override | Collection IDs, profile meaning, and opening/interpreting prompt resources |
|
||||
| Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
|
||||
| Effective configuration diff | Same-type frozen effective comparisons for two selected files or base-versus-overlay impact | Source/options selection and consumer-owned safe presentation |
|
||||
|
||||
@@ -108,6 +109,32 @@ and may fail independently of the completed configuration load. The
|
||||
[configuration contract](../config.md#source-resource-contexts) owns exact
|
||||
lifetime and precedence rules.
|
||||
|
||||
## Input destinations and mounted collections
|
||||
|
||||
The small [`Example_inputDestination`](../../examples/consumers/destinations_test.go)
|
||||
mounts one mapping source beneath literal collection/prompt keys and loads a
|
||||
second input without a destination to show that root placement remains the
|
||||
default. Consumers pass paths, not filenames or namespace strings for ConfigKit
|
||||
to interpret.
|
||||
|
||||
[`LoadCollectionBundle`](../../examples/consumers/destinations.go) assembles an
|
||||
embedded collection manifest with a source-root import, separate prompt and
|
||||
profile peers, and a higher-priority input that changes only one prompt's
|
||||
ordinary `version` field. The main document alone supplies the application
|
||||
schema version. A prompt's local `extends` relationship resolves after all
|
||||
tiers, so `custom` inherits the final `brief` content and fields while retaining
|
||||
its own profile selection.
|
||||
|
||||
The resolver follows each effective `content_file` origin to its declaring
|
||||
source context. This also works for `custom`'s inherited resource. The
|
||||
application-owned [`ReadCollectionPromptContent`](../../examples/consumers/destinations.go)
|
||||
demonstrates the same lookup after loading; ConfigKit does not open or interpret
|
||||
the resource. [`destinations_test.go`](../../examples/consumers/destinations_test.go)
|
||||
checks source destinations and authored coordinates, presence, inherited values,
|
||||
relative resources, and strict peer conflicts. The
|
||||
[configuration contract](../config.md#input-destinations) owns shared placement,
|
||||
import, source-location, and ownership behavior.
|
||||
|
||||
Known module catalogs should use canonical object entries with a module identifier
|
||||
and typed options. A small union struct is sufficient when the available option
|
||||
fields are known; validation selects which fields apply to each module. Runtime-
|
||||
@@ -187,6 +214,7 @@ focused behavioral owner:
|
||||
| Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
|
||||
| `LoadSecretsDir`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
|
||||
| Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
|
||||
| Literal input destinations, root-default compatibility, and mounted peer collections | `Example_inputDestination`, `LoadCollectionBundle`, and `destinations_test.go` |
|
||||
| Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
|
||||
| Effective configuration diffs and consumer-owned presentation | `ExampleDiff`, `ExampleCompareFiles`, and `ExampleCompareRolloutOverlay` |
|
||||
| Results, metadata, diagnostics, effective output, and writer failures | Focused root-package load, provenance, rendering, and explanation tests |
|
||||
|
||||
@@ -465,7 +465,7 @@ supported ConfigKit import path.
|
||||
|
||||
## Stage 11 — Add maintained simple and collection-style consumer examples
|
||||
|
||||
Status: planned. Scope: executable adoption examples with consumer-owned types.
|
||||
Status: complete. Scope: executable adoption examples with consumer-owned types.
|
||||
|
||||
1. Add a minimal mounted-fragment example using `Input.Destination` in an
|
||||
ordinary layered load. Show literal keys and root-default compatibility
|
||||
@@ -483,9 +483,24 @@ Status: planned. Scope: executable adoption examples with consumer-owned types.
|
||||
from the consumer guide; add a small executable root example if useful for
|
||||
discovery without duplicating the complete scenario.
|
||||
|
||||
Validate: `go test ./examples/consumers`, applicable `Example` tests, local links,
|
||||
and everyday check. Done: simple and representative consumers substantiate the
|
||||
same configuration model and need no compensating structural pass.
|
||||
Validated with `go test ./examples/consumers -count=1`,
|
||||
`go test . -run '^Example' -count=1`, and `./scripts/check.sh` (go1.26.8
|
||||
linux/amd64); all passed, including local documentation links.
|
||||
|
||||
`Example_inputDestination` demonstrates a literal mounted mapping path and an
|
||||
ordinary root input without consumer-side parsing or merging.
|
||||
`LoadCollectionBundle` and `TestCollectionBundleAssemblesMountedPeersAndResources`
|
||||
exercise prompt/profile peer sources, imported collection metadata with an
|
||||
ordinary version label, main-owned schema-version checking, local sibling
|
||||
inheritance, and a higher-tier prompt version-only change that retains the rest
|
||||
of its body. The resolver and `ReadCollectionPromptContent` follow direct and
|
||||
inherited `content_file` provenance to the declaring native-filesystem context.
|
||||
The test checks final values, explicit presence, source destinations and authored
|
||||
coordinates, relative resources, and the inherited field's origin.
|
||||
`TestCollectionPeerPromptConflictsRemainStrict` preserves expected conflict
|
||||
behavior. The examples are linked from the consumer adoption guide. Done: simple
|
||||
and representative consumers substantiate the same model without a compensating
|
||||
structural pass.
|
||||
|
||||
## Stage 12 — Reconcile documentation and audit the complete implementation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user