26 Commits

Author SHA1 Message Date
4a7ae664a6 Remove retired roadmap references from development guide 2026-11-21 12:36:10 +00:00
eaace5bd10 Retire completed result inspection roadmaps 2026-11-21 12:33:28 +00:00
174e030dad Write ConfigKit v1.4.0 release notes 2026-11-21 12:32:27 +00:00
1305f2b9e9 Avoid metadata copies during scoped path enumeration 2026-11-21 12:01:47 +00:00
d6fcfc62d9 Clarify result value lookup semantics 2026-11-21 12:01:02 +00:00
ed5d57d061 Preserve terminal values during result lookup 2026-11-21 12:00:29 +00:00
bcee3f866f Record scoped enumeration efficiency finding 2026-11-21 04:33:34 +00:00
a57afc7d69 Record result access review findings 2026-11-21 04:21:25 +00:00
7a9ce01064 Document value access and focused inspection 2026-11-21 04:16:46 +00:00
37f38f3e54 Demonstrate composing two component consumers 2026-11-21 04:13:27 +00:00
ace9f98072 Demonstrate component result handoff 2026-11-21 04:12:15 +00:00
51e15753eb Verify scoped inspection history and provenance 2026-11-21 04:10:56 +00:00
b5e1c11c4a Compare focused inspection views 2026-11-21 04:09:41 +00:00
db743a4b3d Render focused inspection values safely 2026-11-21 04:07:57 +00:00
68a6da2388 Add scoped inspection views 2026-11-21 04:06:45 +00:00
f514936c9c Expose current configuration values 2026-11-21 04:05:27 +00:00
654fe9d306 Add current configuration value navigation 2026-11-21 04:03:37 +00:00
b3799be2fa Remove superseded consumer request 2026-11-21 04:00:27 +00:00
229ad5bfe7 Plan typed result access and focused inspection 2026-11-21 03:54:39 +00:00
afe83a6fd2 Record inspection comparison across application types 2026-11-21 03:37:15 +00:00
86a9060418 Settle canonical reporting scope identity 2026-11-21 03:20:20 +00:00
d11e749428 Settle inspection APIs and review roadmap consistency 2026-11-21 03:17:32 +00:00
4c2620c68b Settle dynamic value traversal using existing type rules 2026-11-21 03:12:59 +00:00
41622c54e0 Settle value access for manually constructed results 2026-11-21 03:07:14 +00:00
48e7f943d9 Add focused inspection to the result access roadmap 2026-11-21 03:00:57 +00:00
472ac551c2 Plan typed value access from configuration results 2026-11-21 02:26:31 +00:00
25 changed files with 1454 additions and 180 deletions

View File

@@ -50,6 +50,8 @@ Start with one file. Optional features use the same loading and inspection model
references and choose which configuration fields to hide in inspection output. references and choose which configuration fields to hide in inspection output.
- [Inspect a load](docs/config.md#layered-metadata): examine sources, presence, - [Inspect a load](docs/config.md#layered-metadata): examine sources, presence,
history, safe YAML output, or [changes between two loads](docs/config.md#effective-configuration-diffs). history, safe YAML output, or [changes between two loads](docs/config.md#effective-configuration-diffs).
- [Hand settings to libraries](docs/consumers/README.md#component-handoff): share
one result and let each consumer select its own settings and reporting scope.
The [consumer guide](docs/consumers/README.md) walks through these tasks and links The [consumer guide](docs/consumers/README.md) walks through these tasks and links
to maintained examples. The [configuration reference](docs/config.md) defines the to maintained examples. The [configuration reference](docs/config.md) defines the

View File

@@ -40,6 +40,10 @@ func Diff[T any](left, right *Result[T]) ([]Difference, error) {
if err != nil { if err != nil {
return nil, err return nil, err
} }
return fromEngineDifferences(values), nil
}
func fromEngineDifferences(values []engine.Difference) []Difference {
differences := make([]Difference, len(values)) differences := make([]Difference, len(values))
for index, value := range values { for index, value := range values {
differences[index] = Difference{ differences[index] = Difference{
@@ -49,5 +53,5 @@ func Diff[T any](left, right *Result[T]) ([]Difference, error) {
HiddenChanged: value.HiddenChanged, HiddenChanged: value.HiddenChanged,
} }
} }
return differences, nil return differences
} }

View File

@@ -2,7 +2,10 @@
## Status ## Status
Accepted and implemented. The Accepted and implemented. Extended by
[ADR 0024](0024-compare-inspection-views-across-application-types.md) for inspection
view comparison across application Go types. The existing same-type comparison
API continues to follow this decision. The
[configuration contract](../config.md#effective-configuration-diffs) owns current [configuration contract](../config.md#effective-configuration-diffs) owns current
behavior. Completed planning and remediation records are preserved in Git behavior. Completed planning and remediation records are preserved in Git
history at `1c2610c` under `docs/roadmap/`. history at `1c2610c` under `docs/roadmap/`.

View File

@@ -0,0 +1,51 @@
# ADR 0024: Compare Inspection Views Across Application Types
## Status
Accepted.
## Date
2026-11-20
## Context
An application can load configuration once and share the result with libraries.
Each library needs to inspect its own section while the application chooses the
Go type that holds the complete configuration.
[ADR 0010](0010-effective-configuration-diff.md) provides comparison between
results with the same Go configuration type. A shared inspection view lets a
library compare configurations without knowing that application type.
## Decision
Provide inspection views that compare saved configuration values from successful
loads regardless of the original application Go types. Views being compared
select the same location within their respective configurations.
ConfigKit owns comparison and redaction. Use the saved load snapshots and the
equality, sequence comparison, and sensitive-value handling established by
ADR 0010. Report changes that overlap the selected location, retaining original
application paths and any containing changes.
This decision extends ADR 0010. The existing same-type comparison API continues
to follow that decision.
## Alternatives Considered
- **Require matching application Go types.** This follows the existing API's
restriction but adds type checks or application-specific adapters to a shared
inspection view.
- **Let libraries implement comparison.** This gives libraries control but
duplicates ConfigKit's comparison and redaction rules.
## Consequences
Libraries can offer configuration comparison through one inspection interface
across applications. Applications retain ownership of their Go configuration
types and presentation.
A reported change to a containing value may include configuration outside the
selected section. The view provides a reporting focus, with the existing
redaction rules applied to all returned values.

View File

@@ -226,6 +226,13 @@ describe the configuration as it was when the load finished. Returned source,
diagnostic, and metadata records are copies; changing them cannot change later diagnostic, and metadata records are copies; changing them cannot change later
queries. Separate loads return independently owned configuration and records. queries. Separate loads return independently owned configuration and records.
`Result.Value` selects trusted current Go values by configuration path, including
resolved secrets and zero values without input. It uses ordinary Go assignment:
maps, slices, and pointers can share state with `Config`. Availability does not
establish input presence; use metadata for that distinction. Capture owned
runtime settings before later mutations invalidate the relationship to saved
inspection evidence. A manually constructed result also supports value lookup.
Every source, options, schema, version, defaults, decode, resolution, or Every source, options, schema, version, defaults, decode, resolution, or
validation failure returns a nil result and a `*LoadError`. Successful results validation failure returns a nil result and a `*LoadError`. Successful results
contain caller-owned `Config`, detached `Metadata`, a defensive source list, contain caller-owned `Config`, detached `Metadata`, a defensive source list,
@@ -750,6 +757,7 @@ Use inspection to understand a completed load without reading the files again:
| Inspect earlier values as safe YAML | `Explain` or `WriteExplanation` | | Inspect earlier values as safe YAML | `Explain` or `WriteExplanation` |
| Show the saved final configuration as safe YAML | `WriteEffective` | | Show the saved final configuration as safe YAML | `WriteEffective` |
| Compare final values from two loads | `Diff` | | Compare final values from two loads | `Diff` |
| Focus reporting on one location | `InspectSubtree` |
For example, suppose a typed default sets `workers` to `2`, the main input For example, suppose a typed default sets `workers` to `2`, the main input
supplies `workers: 3`, and an overlay supplies `workers: 4`. The final value is supplies `workers: 3`, and an overlay supplies `workers: 4`. The final value is
@@ -758,6 +766,16 @@ earlier default and main contributions. `History` returns attribution records;
`Explain` adds their before/after values. Changing `result.Config.Workers` later `Explain` adds their before/after values. Changing `result.Config.Workers` later
does not change any of these saved inspection results. does not change any of these saved inspection results.
An `Inspection` view focuses reporting on a canonical JSON Pointer location.
Its `HistoricalPaths` includes observed paths at or below that location and
`WriteEffective` renders the selected frozen value with original sensitivity.
An absent scope can be selected, but has no effective output. Explicit metadata
and explanation queries keep native application paths and may address values
outside the focus; source catalogs and resource contexts remain available for
the whole load. This is a reporting focus, not a confidentiality boundary. Numeric
key and index spellings with the same pointer select the same focus, while
explicit queries preserve their normal path intent.
#### Presence, origins, and historical paths #### Presence, origins, and historical paths
`Result.Metadata()` describes every final configuration path. Queries retain explicit `Result.Metadata()` describes every final configuration path. Queries retain explicit
@@ -1011,6 +1029,14 @@ uninitialized results return an error with no records. A failed `Load` retains
its normal nil-result/`LoadError` behavior, which callers handle before invoking its normal nil-result/`LoadError` behavior, which callers handle before invoking
`Diff`. `Diff`.
`Inspection.Diff` compares focused views at the same canonical location, even
when their application root Go types differ. It compares the complete frozen
snapshots with the same paired redaction and retains records at, below, or above
the focus. Because sequences and structural replacements can be atomic, an
ancestor record may reflect a change outside the selected value. Different
scopes or unavailable views return an error and no records. Whole-result
`Diff[T]` remains restricted to results of the same Go type.
## Typed secret references ## Typed secret references
There are three separate tasks when working with credentials: There are three separate tasks when working with credentials:

View File

@@ -28,8 +28,24 @@ Start with one file, then choose the tasks your application needs:
| Reuse settings or combine record lists | [Inheritance](#named-sibling-inheritance) and [identified sequences](#identified-prompt-sequences) | | Reuse settings or combine record lists | [Inheritance](#named-sibling-inheritance) and [identified sequences](#identified-prompt-sequences) |
| Handle credentials | [Typed-secret reference](../config.md#typed-secret-references), [configured startup](#configured-secrets-startup), and the [direct-directory example](../../examples/consumers/consumers_test.go) | | Handle credentials | [Typed-secret reference](../config.md#typed-secret-references), [configured startup](#configured-secrets-startup), and the [direct-directory example](../../examples/consumers/consumers_test.go) |
| Inspect sources, earlier values, or changes | [Inspect a completed load](#inspect-a-completed-load) and [diffs](#effective-configuration-diffs) | | Inspect sources, earlier values, or changes | [Inspect a completed load](#inspect-a-completed-load) and [diffs](#effective-configuration-diffs) |
| Hand one result to library consumers | [Component handoff](#component-handoff) |
| Upgrade an existing consumer | [Migration guidance](#intentional-migration-changes) | | Upgrade an existing consumer | [Migration guidance](#intentional-migration-changes) |
## Component handoff
Register application and library rules in one definition, then load once and
pass the whole result to each consumer. A consumer can select its named settings
with `Value`, assert its own type, and follow effective field origins through
`Metadata` and `SourceContext` to capture resources. It owns any runtime copy it
needs. The maintained [one-library example](../../examples/consumers/result_component.go)
shows registration, underlay defaults, handoff, and a focused inspection facade;
the [two-library example](../../examples/consumers/result_composition.go) composes
callbacks and identity registrations for two consumers.
Views focus reports while explicit metadata and explanation queries retain native
application-root paths. See the [configuration contract](../config.md#layered-metadata)
for ownership, scope, and frozen inspection behavior.
## Choosing a loading entry point ## Choosing a loading entry point
- Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration. - Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration.

View File

@@ -58,6 +58,7 @@ Accepted decisions:
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md) - [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
- [Keep the public facade root-owned](adr/0006-public-facade.md) - [Keep the public facade root-owned](adr/0006-public-facade.md)
- [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md) - [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md)
- [Compare inspection views across application types](adr/0024-compare-inspection-views-across-application-types.md)
- [Place inputs at literal application mapping paths](adr/0011-input-destinations.md) - [Place inputs at literal application mapping paths](adr/0011-input-destinations.md)
- [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md) - [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md)
- [Separate import selection controls](adr/0016-independent-import-controls.md) - [Separate import selection controls](adr/0016-independent-import-controls.md)
@@ -68,186 +69,16 @@ Accepted decisions:
- [Match registered records during resolution inspection](adr/0021-sequence-resolution-correspondence.md) - [Match registered records during resolution inspection](adr/0021-sequence-resolution-correspondence.md)
- [Bind companion contexts after main selection](adr/0022-main-relative-context.md) - [Bind companion contexts after main selection](adr/0022-main-relative-context.md)
For cross-cutting changes, follow every applicable row. Completed implementation For cross-cutting changes, follow every applicable row. Use current contracts
and remediation plans are preserved in Git history at `cb5b435`; use current and the component overview for ongoing work.
contracts and the component overview for ongoing work. For example:
```sh
git show cb5b435:docs/roadmap/remediation.md
```
Release-candidate, publication, and verification work follows the operational Release-candidate, publication, and verification work follows the operational
[release procedure](release.md). Its module-selected ReleaseKit `publish` [release procedure](release.md). Its module-selected ReleaseKit `publish`
invocation validates the committed candidate and publishes only the intended invocation validates the committed candidate and publishes only the intended
tag; those release checks remain distinct from the everyday development check. tag; those release checks remain distinct from the everyday development check.
The completed string-and-integer schema-version implementation and remediation
records are preserved in Git history at `244104f`. The
[configuration contract](config.md#application-schema-versions) owns current behavior.
The completed source-origins and public-facade roadmaps, implementation plan, and
resolved review findings are preserved in Git history at `5760614`, for example
`git show 5760614:docs/roadmap/remediation.md`. The earlier source-origins staged
plan remains at `28e7fc5:docs/roadmap/implementation.md`. Current resolution
behavior belongs to the [configuration contract](config.md#recorded-application-resolution),
and current facade ownership belongs to the [component overview](internal/overview.md).
## Baseline validation ## Baseline validation
The completed main-relative companion roadmap, Audita request, implementation
plan, and remediation report are preserved in Git history at `47547bc` under
`docs/roadmap/`. The [layered loading contract](config.md#layered-loading)
describes current behavior, and [ADR 0022](adr/0022-main-relative-context.md)
records the context binding decision.
The completed field-level sequence resolution roadmap, implementation plan, and
resolved audit findings are preserved in Git history at `7e53863` under
`docs/roadmap/`. For example:
```sh
git show 7e53863:docs/roadmap/implementation.md
git show 7e53863:docs/roadmap/remediation.md
```
The [configuration contract](config.md#recorded-application-resolution) owns
current resolution behavior, and [ADR 0021](adr/0021-sequence-resolution-correspondence.md)
records the correspondence decision.
The completed filesystem-source and underlay roadmap, original feature request,
implementation plan, and resolved remediation record are preserved in Git history
at `b604aa1` under `docs/roadmap/`. Current behavior belongs to the
[configuration contract](config.md#layered-loading). Built-in sibling
inheritance is now part of the [configuration contract](config.md#sibling-inheritance).
The completed request, roadmap, plan, and resolved review findings are preserved
in Git history at `83c59ea` under `docs/roadmap/`.
The completed overlay rename plan and release-workflow simplification record are
preserved in Git history at `73ce6e9` under `docs/roadmap/`. Current overlay
behavior belongs to the [configuration contract](config.md#selected-overlays),
and release operations belong to the [release procedure](release.md).
The completed ReleaseKit adoption, startup performance request and experiments,
benchmark evidence, performance audit, implementation plan, and remediation
record are preserved in Git history at `8e91a2b` under `docs/roadmap/`. For example:
```sh
git show 8e91a2b:docs/roadmap/startup-benchmark.md
```
Remaining optimization candidates belong to
[future performance experiments](roadmap/future.md#3-performance-experiments).
The completed effective-configuration diff roadmap, implementation plan, and
resolved review findings are preserved in Git history at `1c2610c` under
`docs/roadmap/`. The
[configuration contract](config.md#effective-configuration-diffs) owns current
comparison and disclosure behavior, and
[ADR 0010](adr/0010-effective-configuration-diff.md) records the decision.
The completed input-destination, relative-import-destination, and shared
source-version roadmaps, associated consumer request, implementation plan, and
resolved review findings are preserved in Git history at `e4270c9` under
`docs/roadmap/`. For example:
```sh
git show e4270c9:docs/roadmap/implementation.md
git show e4270c9:docs/roadmap/remediation.md
```
Current behavior belongs to the configuration contract's
[input destinations](config.md#input-destinations),
[imports](config.md#explicit-imports), and
[shared source-version checks](config.md#shared-source-version-checks) sections.
Explicit sequence-item placement, collection operations, identity registration,
and final registered-identity validation are owned by the
[strict composition](config.md#strict-document-composition) section;
[imports](config.md#explicit-imports) owns acquisition and scheduling. The
[maintained sequence catalog](consumers/README.md#identified-prompt-sequences)
shows the consumer boundary, and [ADR 0017](adr/0017-collection-sequence-policy.md)
records the collection decision.
The completed sequence-composition roadmap, implementation plan, and resolved
remediation record are preserved in Git history at `008d2ba` under
`docs/roadmap/`. For example:
```sh
git show 008d2ba:docs/roadmap/sequence-composition.md
git show 008d2ba:docs/roadmap/implementation.md
git show 008d2ba:docs/roadmap/remediation.md
```
The completed import-discovery roadmap, implementation plan, and resolved
remediation record are preserved in Git history at `5747ec4` under
`docs/roadmap/`. For example:
```sh
git show 5747ec4:docs/roadmap/imports.md
git show 5747ec4:docs/roadmap/implementation.md
git show 5747ec4:docs/roadmap/remediation.md
```
The subsequent import-integration audit and completed remediation record are
preserved at `6903c9e:docs/roadmap/remediation.md`; retrieve them with
`git show 6903c9e:docs/roadmap/remediation.md`.
The completed sequence-identity/collection-policy roadmap and implementation
plan are preserved in Git history at `d0a605a`:
```sh
git show d0a605a:docs/roadmap/sequences.md
git show d0a605a:docs/roadmap/implementation.md
```
Current behavior belongs to the configuration contract's
[strict composition](config.md#strict-document-composition),
[sibling inheritance](config.md#sibling-inheritance), and
[CLI overrides](config.md#explicit-cli-overrides) sections.
The completed remediation record, including the algorithm-audit findings, is
preserved at `ea46001:docs/roadmap/remediation.md`.
The completed configuration-discovery roadmap, implementation plan, and
remediation record are preserved in Git history at `0369111`, for example
`git show 0369111:docs/roadmap/remediation.md`. Current behavior belongs to
[configuration discovery](config.md#configuration-discovery); the public
[discovery declarations](../discovery.go) own the Go API.
The completed consolidation proposal, implementation plan, and resolved audit
findings are preserved in Git history at `34cbc0d` under `docs/roadmap/`. For
example:
```sh
git show 34cbc0d:docs/roadmap/implementation.md
git show 34cbc0d:docs/roadmap/remediation.md
```
Potential enhancements are tracked in [future features](roadmap/future.md).
The completed audit-remediation, internal-boundary simplification, shared-history,
and public API cleanup roadmaps, reviews, and resolved findings are preserved at
`68400ff` under `docs/roadmap/`. For example:
```sh
git show 68400ff:docs/roadmap/api.md
git show 68400ff:docs/roadmap/remediation.md
```
Their earlier completed implementation plans are preserved at
`bb5540b:docs/roadmap/implementation.md` (audit remediation),
`f6d54a0:docs/roadmap/implementation.md` (internal-boundary simplification), and
`07e4ae5:docs/roadmap/implementation.md` (shared history). The plan at
`68400ff:docs/roadmap/implementation.md` records the public API cleanup.
Current behavior and migration information belong to the
[configuration contract](config.md), public declaration comments, and
[consumer guide](consumers/README.md#pre-v1-public-api-cleanup).
The consolidated audit, including
findings, evidence, and settled scope decisions, is preserved at
`453da68:docs/roadmap/audit.md`; the original nine reports are preserved at
`ecd5d5d` under `docs/roadmap/`. Retrieve the consolidated record with:
```sh
git show 453da68:docs/roadmap/audit.md
```
Install the Go version required by `go.mod` or a compatible newer toolchain. Install the Go version required by `go.mod` or a compatible newer toolchain.
Acquire declared dependencies explicitly before entering an offline Acquire declared dependencies explicitly before entering an offline
development or validation environment: development or validation environment:
@@ -309,6 +140,7 @@ code changes. Use the component overview to find the corresponding implementatio
| Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination\|Import\|Glob\|Mounted'`, `go test . -run 'Destination\|Import\|SourceContext\|FacadeMounted'`, and `go test ./examples/consumers` | | Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination\|Import\|Glob\|Mounted'`, `go test . -run 'Destination\|Import\|SourceContext\|FacadeMounted'`, and `go test ./examples/consumers` |
| Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` | | Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` |
| Schema, defaults, projection, cloning | [Implementation flow](internal/overview.md#implementation-flow), [schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection and typed cloning](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` | | Schema, defaults, projection, cloning | [Implementation flow](internal/overview.md#implementation-flow), [schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection and typed cloning](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
| Current values and focused inspection | [Value tests](../facade_result_value_test.go), [view tests](../facade_inspection_view_test.go), [comparison tests](../facade_inspection_diff_test.go), and [history integration](../facade_inspection_history_test.go) | `go test . -run 'TestResultValue\|TestInspectionView'` and `go test ./internal/engine -run 'TestResultValue\|Diff\|History'` |
| Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` | | Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
| Resolution sequence matching and inspection | [Correspondence](../internal/engine/resolution_correspondence_test.go), [auditing and history](../internal/engine/resolution_compare_test.go), [public integration](../facade_resolution_sequences_test.go) | `go test ./internal/engine -run 'Resolution\|History\|Explain\|Sensitivity'` and `go test . -run 'Resolution\|SequenceIdentity\|Diff'` | | Resolution sequence matching and inspection | [Correspondence](../internal/engine/resolution_correspondence_test.go), [auditing and history](../internal/engine/resolution_compare_test.go), [public integration](../facade_resolution_sequences_test.go) | `go test ./internal/engine -run 'Resolution\|History\|Explain\|Sensitivity'` and `go test . -run 'Resolution\|SequenceIdentity\|Diff'` |
| Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` | | Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |

View File

@@ -45,6 +45,10 @@ Implemented component owners:
- Root `Diff` and `Difference` provide the public comparison boundary and - Root `Diff` and `Difference` provide the public comparison boundary and
convert detached engine records to root-owned paths and snapshots; consumer convert detached engine records to root-owned paths and snapshots; consumer
examples own presentation of the safe changed regions. examples own presentation of the safe changed regions.
- `Result.Value` delegates current Go-value navigation to an operation-local
engine schema builder and existing field/path bindings. Root `Inspection`
wraps an engine view borrowing the frozen inspection and canonical scope;
it reuses history enumeration, document redaction, and whole-result diff.
- `internal/document` owns the parser-independent ordered tree and cloning. - `internal/document` owns the parser-independent ordered tree and cloning.
`internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary. `internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
- Engine mechanism tests own source, composition, inheritance, decoding, - Engine mechanism tests own source, composition, inheritance, decoding,

View File

@@ -316,12 +316,14 @@ See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
Detailed syntax and operation tables belong to the Detailed syntax and operation tables belong to the
[current configuration contract](../config.md). [current configuration contract](../config.md).
The frozen inspection boundary also supports comparing completed same-type The frozen inspection boundary supports comparing completed same-type results
results without reopening sources or rerunning the load lifecycle. The and focused views across application root types without reopening sources or
rerunning the load lifecycle. The
[configuration contract](../config.md#effective-configuration-diffs) owns [configuration contract](../config.md#effective-configuration-diffs) owns
comparison and disclosure behavior, the [component overview](../internal/overview.md) comparison and disclosure behavior, the [component overview](../internal/overview.md)
owns implementation responsibility, and [ADR 0010](../adr/0010-effective-configuration-diff.md) owns implementation responsibility, and [ADR 0010](../adr/0010-effective-configuration-diff.md)
records the accepted decision. and [ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md)
record the accepted decisions.
## Collection Identity And Combination ## Collection Identity And Combination

58
docs/releases/v1.4.0.md Normal file
View File

@@ -0,0 +1,58 @@
# ConfigKit v1.4.0
Applications can now load configuration once and pass the complete result to
libraries that select their own typed settings and reporting scope. The new APIs
reuse the original load's provenance, resource contexts, and frozen inspection
state.
## Current typed values
`Result.Value(path)` selects a current Go value without requiring the consumer
to know the application's root configuration type. It uses ConfigKit's existing
field bindings and semantic paths, preserving named types, terminal pointers,
and resolved `Secret` values. A present nil value succeeds; unavailable paths
return false. Lookup also works with manually constructed results and returns
terminal values without conversion or revalidation.
This is trusted access with ordinary Go assignment semantics: maps, slices, and
pointers can share state with `Result.Config`. Later caller changes are visible
to lookup, while inspection continues to describe the completed load. Consumers
remain responsible for capturing any owned runtime settings they need.
[Value API](../../result_value.go) · [Ownership contract](../config.md#completion-and-resource-lifetime)
## Focused inspection
`Result.InspectSubtree(path)` returns a non-generic `Inspection` view. It renders
the selected frozen value with existing redaction, enumerates observed paths
within the scope, and forwards explanations, metadata, source records, and
resource contexts using native application paths.
A valid absent scope can be selected for history and comparison. Rendering an
absent effective value returns an error without output; explicit null renders
normally. Numeric key and index spellings with the same canonical JSON Pointer
select the same reporting location. Explicit queries retain their normal path
intent and can address values outside the focus. Source catalogs and ancestor
evidence remain available: the view is a reporting focus, not an isolation
boundary. Scoped path enumeration avoids copying unrelated effective metadata.
[Inspection API](../../inspection_view.go) · [Inspection contract](../config.md#layered-metadata)
`Inspection.Diff` compares views selecting the same location, including views
from different application root Go types. It uses the existing whole-snapshot
comparison and paired redaction, then retains differences at, below, or above
the focus. Sequences remain atomic: a retained ancestor difference can reflect
changes outside the selected descendant. Uninitialized views and mismatched
scopes return an error without records. Existing same-type `Diff[T]` is unchanged.
[Comparison contract](../config.md#effective-configuration-diffs)
The maintained [one-library](../../examples/consumers/result_component.go) and
[two-library](../../examples/consumers/result_composition.go) examples demonstrate
registration, one-load handoff, owned settings capture, and resource lookup from
effective source origins. [Consumer guidance](../consumers/README.md#component-handoff)
## Compatibility
These APIs are additive. Existing loading, composition, inspection, and shared
source-version behavior remains unchanged; existing callers need no migration.
The Go consumer minimum remains 1.27.0.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/oss/attribution.md)

View File

@@ -0,0 +1,122 @@
package consumers
import (
"errors"
"io"
"io/fs"
"path"
"slices"
"strings"
configkit "go.maximumdirect.net/configkit"
)
// ComponentSettings is a library-owned configuration type embedded by an application.
type ComponentSettings struct {
Name string `yaml:"name"`
Resource string `yaml:"resource"`
Token string `yaml:"token"`
Entries []ComponentItem `yaml:"entries"`
}
// ComponentItem is one identified library setting.
type ComponentItem struct {
ID string `yaml:"id"`
Resource string `yaml:"resource"`
}
// ComponentApplication is the application-owned root for this example.
type ComponentApplication struct {
Component ComponentSettings `yaml:"component"`
}
// ComponentResult is the small interface required by the library at handoff.
type ComponentResult interface {
Value(configkit.Path) (any, bool)
Metadata() configkit.Metadata
SourceContext(string) (configkit.ResourceContext, bool)
}
// ComponentRuntime contains settings and captured resource data owned by the library.
type ComponentRuntime struct {
Settings ComponentSettings
Resource []byte
}
// ComponentDefinition registers library behavior through an application field selector.
func ComponentDefinition[T any](selectSettings func(*T) *ComponentSettings) configkit.Definition[T] {
component := configkit.Keys("component")
return configkit.Definition[T]{
SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(component.Key("entries"), "id")},
Resolve: func(root *T, resolution *configkit.Resolution) error {
settings := selectSettings(root)
configkit.Default(resolution, component.Key("name"), &settings.Name, "default component", "use component default")
configkit.Normalize(resolution, component.Key("name"), &settings.Name, strings.TrimSpace(settings.Name), "trim component name")
return nil
},
Validate: func(root *T, validation *configkit.Validation) {
if selectSettings(root).Name == "" {
validation.Error(component.Key("name"), "component name is required")
}
},
Sensitive: func(path configkit.Path) bool { return path.String() == "/component/token" },
}
}
// LoadComponentApplication assembles one application load with bundled underlay defaults.
func LoadComponentApplication(source configkit.Source) (*configkit.Result[ComponentApplication], error) {
return configkit.LoadLayered(configkit.Input{Source: source}, configkit.LayeredOptions[ComponentApplication]{
Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("component defaults", []byte("component: {entries: [{id: default}]}\n"))}}}},
Definition: ComponentDefinition(func(root *ComponentApplication) *ComponentSettings { return &root.Component }),
})
}
// NewComponent accepts the entire result, selects library settings, and captures
// a resource relative to the effective field's original source.
func NewComponent(result ComponentResult) (ComponentRuntime, error) {
value, ok := result.Value(configkit.Keys("component"))
settings, typed := value.(ComponentSettings)
if !ok || !typed {
return ComponentRuntime{}, errors.New("component settings unavailable")
}
settings.Entries = slices.Clone(settings.Entries)
info, ok := result.Metadata().Lookup(configkit.Keys("component", "resource"))
if !ok || len(info.Origin.Locations) != 1 {
return ComponentRuntime{}, errors.New("component resource origin unavailable")
}
context, ok := result.SourceContext(info.Origin.Locations[0].SourceID)
if !ok {
return ComponentRuntime{}, errors.New("component resource context unavailable")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, settings.Resource))
if err != nil {
return ComponentRuntime{}, err
}
return ComponentRuntime{Settings: settings, Resource: data}, nil
}
// ComponentInspection is a library-owned facade over one selected reporting view.
type ComponentInspection struct{ view configkit.Inspection }
// InspectComponent selects the library's conventional reporting scope once.
func InspectComponent(result interface {
InspectSubtree(configkit.Path) (configkit.Inspection, bool)
}) (ComponentInspection, bool) {
view, ok := result.InspectSubtree(configkit.Keys("component"))
return ComponentInspection{view: view}, ok
}
// WriteEffective renders the frozen component safely.
func (i ComponentInspection) WriteEffective(output io.Writer) error {
return i.view.WriteEffective(output)
}
// Explain forwards native application paths without changing their meaning.
func (i ComponentInspection) Explain(path configkit.Path) (configkit.Explanation, bool) {
return i.view.Explain(path)
}
// Diff compares two frozen component views.
func (i ComponentInspection) Diff(other ComponentInspection) ([]configkit.Difference, error) {
return i.view.Diff(other.view)
}

View File

@@ -0,0 +1,57 @@
package consumers
import (
"bytes"
"strings"
"testing"
"testing/fstest"
configkit "go.maximumdirect.net/configkit"
)
func TestComponentHandoff(t *testing.T) {
filesystem := configkit.NewFilesystem("application", fstest.MapFS{
"config/main.yml": &fstest.MapFile{Data: []byte("component: {name: ' example ', resource: asset.txt, token: disposable-canary}\n")},
"config/asset.txt": &fstest.MapFile{Data: []byte("resource data")},
})
result, err := LoadComponentApplication(filesystem.File("config/main.yml"))
if err != nil {
t.Fatal(err)
}
runtime, err := NewComponent(result)
if err != nil {
t.Fatal(err)
}
if runtime.Settings.Name != "example" || len(runtime.Settings.Entries) != 1 || runtime.Settings.Entries[0].ID != "default" || string(runtime.Resource) != "resource data" {
t.Fatalf("component runtime = %#v", runtime)
}
runtime.Settings.Entries[0].ID = "runtime change"
if result.Config.Component.Entries[0].ID != "default" {
t.Fatal("runtime settings share the result's slice")
}
entries, found := result.Metadata().Lookup(configkit.Keys("component", "entries"))
if !result.Metadata().IsExplicit(configkit.Keys("component", "resource")) || !found || entries.Origin.Layer != configkit.LayerUnderlay {
t.Fatal("presence did not retain source distinction")
}
view, ok := InspectComponent(result)
if !ok {
t.Fatal("component view unavailable")
}
var output bytes.Buffer
if err := view.WriteEffective(&output); err != nil {
t.Fatal(err)
}
if strings.Contains(output.String(), "disposable-canary") || !strings.Contains(output.String(), "example") {
t.Fatalf("unsafe report: %s", output.String())
}
if _, ok := view.Explain(configkit.Keys("component", "resource")); !ok {
t.Fatal("resource explanation unavailable")
}
if diff, err := view.Diff(view); err != nil || len(diff) != 0 {
t.Fatalf("view diff = %#v, %v", diff, err)
}
_, err = LoadComponentApplication(configkit.Bytes("invalid.yml", []byte("component: {name: ' '}\n")))
if err == nil {
t.Fatal("component validation did not fail")
}
}

View File

@@ -0,0 +1,86 @@
package consumers
import (
"errors"
"strings"
configkit "go.maximumdirect.net/configkit"
)
// AuditSettings is a second library's independent configuration type.
type AuditSettings struct {
Enabled bool `yaml:"enabled"`
Rules []AuditRule `yaml:"rules"`
}
// AuditRule has an identity used by the application's assembly policy.
type AuditRule struct {
ID string `yaml:"id"`
}
// ComposedApplication combines application and two library settings.
type ComposedApplication struct {
Label string `yaml:"label"`
Component ComponentSettings `yaml:"component"`
Audit AuditSettings `yaml:"audit"`
}
// AuditResult is the smaller interface needed by the audit consumer.
type AuditResult interface {
Value(configkit.Path) (any, bool)
}
// NewAuditSettings takes a copy of the second library's settings.
func NewAuditSettings(result AuditResult) (AuditSettings, error) {
value, ok := result.Value(configkit.Keys("audit"))
settings, typed := value.(AuditSettings)
if !ok || !typed {
return AuditSettings{}, errors.New("audit settings unavailable")
}
settings.Rules = append([]AuditRule(nil), settings.Rules...)
return settings, nil
}
func auditDefinition[T any](selectSettings func(*T) *AuditSettings) configkit.Definition[T] {
audit := configkit.Keys("audit")
return configkit.Definition[T]{
SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(audit.Key("rules"), "id")},
Resolve: func(root *T, resolution *configkit.Resolution) error {
configkit.Default(resolution, audit.Key("enabled"), &selectSettings(root).Enabled, true, "enable audit by default")
return nil
},
Validate: func(root *T, validation *configkit.Validation) {
if selectSettings(root).Enabled && len(selectSettings(root).Rules) == 0 {
validation.Error(audit.Key("rules"), "enabled audit requires a rule")
}
},
}
}
// LoadComposedApplication applies application and library callbacks in order in
// one load. A placed component input remains an ordinary underlay.
func LoadComposedApplication(main, component configkit.Input) (*configkit.Result[ComposedApplication], error) {
componentRules := ComponentDefinition(func(root *ComposedApplication) *ComponentSettings { return &root.Component })
auditRules := auditDefinition(func(root *ComposedApplication) *AuditSettings { return &root.Audit })
identities := append(componentRules.SequenceIdentities, auditRules.SequenceIdentities...)
definition := configkit.Definition[ComposedApplication]{
SequenceIdentities: identities,
Sensitive: componentRules.Sensitive,
Resolve: func(root *ComposedApplication, resolution *configkit.Resolution) error {
configkit.Normalize(resolution, configkit.Keys("label"), &root.Label, strings.TrimSpace(root.Label), "trim application label")
if err := componentRules.Resolve(root, resolution); err != nil {
return err
}
return auditRules.Resolve(root, resolution)
},
Validate: func(root *ComposedApplication, validation *configkit.Validation) {
if root.Label == "" {
validation.Error(configkit.Keys("label"), "application label is required")
}
componentRules.Validate(root, validation)
auditRules.Validate(root, validation)
},
}
component.Destination = configkit.Keys("component")
return configkit.LoadLayered(main, configkit.LayeredOptions[ComposedApplication]{Underlays: []configkit.Underlay{{Inputs: []configkit.Input{component}}}, Definition: definition})
}

View File

@@ -0,0 +1,69 @@
package consumers
import (
"io/fs"
"path"
"testing"
"testing/fstest"
configkit "go.maximumdirect.net/configkit"
)
func TestComposedConsumersShareOneLoad(t *testing.T) {
filesystem := configkit.NewFilesystem("components", fstest.MapFS{
"config/component.yml": &fstest.MapFile{Data: []byte("name: ' component '\nresource: asset.txt\nentries:\n - {id: parent, resource: asset.txt}\n - {id: child, extends: {id: parent}}\n")},
"config/asset.txt": &fstest.MapFile{Data: []byte("shared asset")},
})
component := configkit.Input{Source: filesystem.File("config/component.yml")}
load := func(main string) *configkit.Result[ComposedApplication] {
t.Helper()
result, err := LoadComposedApplication(configkit.Input{Source: configkit.Bytes("app.yml", []byte(main))}, component)
if err != nil {
t.Fatal(err)
}
return result
}
first := load("label: ' app '\naudit: {enabled: false, rules: [{id: first}]}\n")
second := load("label: second\naudit: {rules: [{id: second}]}\n")
componentRuntime, err := NewComponent(first)
if err != nil {
t.Fatal(err)
}
audit, err := NewAuditSettings(first)
if err != nil {
t.Fatal(err)
}
if first.Config.Label != "app" || componentRuntime.Settings.Name != "component" || string(componentRuntime.Resource) != "shared asset" || audit.Enabled || audit.Rules[0].ID != "first" {
t.Fatalf("first result = %#v %#v", componentRuntime, audit)
}
secondAudit, err := NewAuditSettings(second)
if err != nil || !secondAudit.Enabled || secondAudit.Rules[0].ID != "second" || audit.Enabled {
t.Fatalf("second audit = %#v, %v", secondAudit, err)
}
resource := configkit.Keys("component", "entries").Index(1).Key("resource")
info, ok := first.Metadata().Lookup(resource)
if !ok || len(info.Origin.Inheritance) == 0 || len(info.Origin.Locations) == 0 {
t.Fatalf("inherited origin = %#v, %v", info, ok)
}
context, ok := first.SourceContext(info.Origin.Locations[0].SourceID)
if !ok {
t.Fatal("resource context unavailable")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, first.Config.Component.Entries[1].Resource))
if err != nil || string(data) != "shared asset" {
t.Fatalf("inherited resource = %q, %v", data, err)
}
_, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("invalid.yml", []byte("label: app\naudit: {rules: [{id: same}, {id: same}]}\n"))}, component)
if err == nil {
t.Fatal("duplicate audit identities accepted")
}
badComponent := configkit.Input{Source: configkit.Bytes("bad-component.yml", []byte("name: good\nentries: [{id: duplicate}, {id: duplicate}]\n"))}
_, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("app.yml", []byte("label: app\naudit: {rules: [{id: valid}]}\n"))}, badComponent)
if err == nil {
t.Fatal("duplicate component identities accepted")
}
_, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("invalid.yml", []byte("label: ' '\naudit: {rules: [{id: valid}]}\n"))}, component)
if err == nil {
t.Fatal("application validation did not run")
}
}

View File

@@ -0,0 +1,96 @@
package configkit_test
import (
"strings"
"testing"
configkit "go.maximumdirect.net/configkit"
)
func TestInspectionViewDiff(t *testing.T) {
type first struct {
Component map[string]any `yaml:"component"`
Sibling string `yaml:"sibling"`
Items []string `yaml:"items"`
}
type second struct {
Component map[string]any `yaml:"component"`
Sibling string `yaml:"sibling"`
Items []string `yaml:"items"`
}
left, err := configkit.Load[first](configkit.Bytes("left.yml", []byte("component: {name: before, gone: null}\nsibling: old\nitems: [a, b]\n")))
if err != nil {
t.Fatal(err)
}
right, err := configkit.Load[second](configkit.Bytes("right.yml", []byte("component: {name: after, added: null}\nsibling: new\nitems: [a, c]\n")))
if err != nil {
t.Fatal(err)
}
lv, _ := left.InspectSubtree(configkit.Keys("component"))
rv, _ := right.InspectSubtree(configkit.Keys("component"))
diff, err := lv.Diff(rv)
if err != nil || len(diff) != 3 || diff[0].Path.String() != "/component/added" || diff[1].Path.String() != "/component/gone" || diff[2].Path.String() != "/component/name" {
t.Fatalf("component diff = %#v, %v", diff, err)
}
if diff[0].Left.Present || !diff[0].Right.Present || !diff[1].Left.Present || diff[1].Right.Present {
t.Fatalf("null and absence = %#v", diff)
}
sequenceLeft, _ := left.InspectSubtree(configkit.Keys("items").Index(0))
sequenceRight, _ := right.InspectSubtree(configkit.Keys("items", "0"))
diff, err = sequenceLeft.Diff(sequenceRight)
if err != nil || len(diff) != 1 || diff[0].Path.String() != "/items" {
t.Fatalf("sequence ancestor = %#v, %v", diff, err)
}
missingLeft, _ := left.InspectSubtree(configkit.Keys("absent"))
missingRight, _ := right.InspectSubtree(configkit.Keys("absent"))
if diff, err = missingLeft.Diff(missingRight); err != nil || len(diff) != 0 {
t.Fatalf("absent diff = %#v, %v", diff, err)
}
if diff, err = lv.Diff(missingRight); err == nil || diff != nil {
t.Fatalf("mismatched diff = %#v, %v", diff, err)
}
if diff, err = (configkit.Inspection{}).Diff(lv); err == nil || diff != nil {
t.Fatalf("zero diff = %#v, %v", diff, err)
}
rootLeft, _ := left.InspectSubtree(configkit.Path{})
rootRight, _ := right.InspectSubtree(configkit.Path{})
if diff, err = rootLeft.Diff(rootRight); err != nil || len(diff) != 5 {
t.Fatalf("root diff = %#v, %v", diff, err)
}
if diff, err = lv.Diff(lv); err != nil || len(diff) != 0 {
t.Fatalf("equal diff = %#v, %v", diff, err)
}
}
func TestInspectionViewDiffRedactionAndShape(t *testing.T) {
load := func(input string, sensitive bool) *configkit.Result[map[string]any] {
t.Helper()
result, err := configkit.Load(configkit.Bytes("view.yml", []byte(input)), configkit.Options[map[string]any]{Definition: configkit.Definition[map[string]any]{Sensitive: func(path configkit.Path) bool { return sensitive && path.String() == "/component" }}})
if err != nil {
t.Fatal(err)
}
return result
}
left := load("component: {token: disposable-canary-left}\n", true)
right := load("component: {token: disposable-canary-right}\n", false)
lv, _ := left.InspectSubtree(configkit.Keys("component", "token"))
rv, _ := right.InspectSubtree(configkit.Keys("component", "token"))
diff, err := lv.Diff(rv)
if err != nil || len(diff) != 1 || !diff[0].Left.Redacted || !diff[0].Right.Redacted || !diff[0].HiddenChanged || strings.Contains(diff[0].Left.YAML+diff[0].Right.YAML, "disposable-canary") {
t.Fatalf("sensitive diff = %#v, %v", diff, err)
}
removed := load("other: public\n", false)
removedView, _ := removed.InspectSubtree(configkit.Keys("component", "token"))
diff, err = lv.Diff(removedView)
if err != nil || len(diff) != 1 || diff[0].Right.Present || !diff[0].Left.Redacted || strings.Contains(diff[0].Left.YAML, "disposable-canary") {
t.Fatalf("sensitive removal = %#v, %v", diff, err)
}
left = load("component: {'0': old}\n", false)
right = load("component: [new]\n", false)
lv, _ = left.InspectSubtree(configkit.Keys("component", "0"))
rv, _ = right.InspectSubtree(configkit.Keys("component").Index(0))
diff, err = lv.Diff(rv)
if err != nil || len(diff) != 1 || diff[0].Path.String() != "/component" {
t.Fatalf("shape diff = %#v, %v", diff, err)
}
}

View File

@@ -0,0 +1,134 @@
package configkit_test
import (
"bytes"
"io/fs"
"path"
"reflect"
"strings"
"testing"
"testing/fstest"
configkit "go.maximumdirect.net/configkit"
)
func TestInspectionViewHistoryAndResourceOwnership(t *testing.T) {
filesystem := configkit.NewFilesystem("component", fstest.MapFS{
"config/settings.yml": &fstest.MapFile{Data: []byte("entries:\n parent: {resource: asset.txt, removed: old}\n child: {extends: parent}\nsibling: retained\n")},
"config/asset.txt": &fstest.MapFile{Data: []byte("asset contents")},
})
load := func() *configkit.Result[map[string]any] {
t.Helper()
result, err := configkit.LoadLayered(configkit.Input{Source: filesystem.File("config/settings.yml"), Destination: configkit.Keys("component")}, configkit.LayeredOptions[map[string]any]{Definition: configkit.Definition[map[string]any]{
Resolve: func(current *map[string]any, resolution *configkit.Resolution) error {
child := (*current)["component"].(map[string]any)["entries"].(map[string]any)["child"].(map[string]any)
delete(child, "removed")
resolution.RecordNormalization(configkit.Keys("component", "entries", "child", "removed"), "remove old setting")
return nil
},
}})
if err != nil {
t.Fatal(err)
}
return result
}
result, other := load(), load()
scope := configkit.Keys("component", "entries", "child")
view, ok := result.InspectSubtree(scope)
if !ok {
t.Fatal("view unavailable")
}
removed := scope.Key("removed")
resource := scope.Key("resource")
paths := []string{}
for _, p := range view.HistoricalPaths() {
paths = append(paths, p.String())
}
if !strings.Contains(strings.Join(paths, ","), removed.String()) {
t.Fatalf("removed history missing: %v", paths)
}
if _, ok := view.Metadata().Lookup(removed); ok {
t.Fatal("removed value is effective")
}
explanation, ok := view.Explain(removed)
if !ok || explanation.Effective.Present || len(explanation.History) == 0 {
t.Fatalf("removed explanation = %#v, %v", explanation, ok)
}
if len(view.Metadata().History(removed)) == 0 {
t.Fatal("removed history missing")
}
info, ok := view.Metadata().Lookup(resource)
if !ok || len(info.Origin.Locations) == 0 || len(info.Origin.Inheritance) == 0 {
t.Fatalf("inherited origin = %#v, %v", info, ok)
}
id := info.Origin.Locations[0].SourceID
context, ok := view.SourceContext(id)
if !ok {
t.Fatal("source context missing")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, "asset.txt"))
if err != nil || string(data) != "asset contents" {
t.Fatalf("resource = %q, %v", data, err)
}
if _, ok := view.Source(id); !ok {
t.Fatal("source containing sibling missing")
}
before := bytes.Buffer{}
if err := view.WriteEffective(&before); err != nil {
t.Fatal(err)
}
otherView, _ := other.InspectSubtree(scope)
child := result.Config["component"].(map[string]any)["entries"].(map[string]any)["child"].(map[string]any)
child["resource"] = "changed"
if value, _ := result.Value(resource); value != "changed" {
t.Fatalf("current value = %v", value)
}
after := bytes.Buffer{}
if err := view.WriteEffective(&after); err != nil || !bytes.Equal(before.Bytes(), after.Bytes()) {
t.Fatalf("view changed = %q, %v", after.String(), err)
}
if diff, err := view.Diff(otherView); err != nil || len(diff) != 0 {
t.Fatalf("frozen diff = %#v, %v", diff, err)
}
info.Origin.Locations[0].SourceID = "changed"
again, _ := view.Metadata().Lookup(resource)
if again.Origin.Locations[0].SourceID != id {
t.Fatal("metadata was not detached")
}
explanation.Effective.YAML = "changed"
againExplanation, _ := view.Explain(removed)
if reflect.DeepEqual(explanation, againExplanation) {
t.Fatal("explanation was not detached")
}
}
func TestInspectionViewHistoricalNumericScope(t *testing.T) {
result, err := configkit.Load(configkit.Bytes("shape.yml", []byte("component: {'0': {old: value}}\n")), configkit.Options[map[string]any]{Definition: configkit.Definition[map[string]any]{
Resolve: func(current *map[string]any, resolution *configkit.Resolution) error {
(*current)["component"] = []any{map[string]any{"new": "value"}}
resolution.RecordNormalization(configkit.Keys("component"), "change shape")
return nil
},
}})
if err != nil {
t.Fatal(err)
}
key, _ := result.InspectSubtree(configkit.Keys("component", "0"))
index, _ := result.InspectSubtree(configkit.Keys("component").Index(0))
if !reflect.DeepEqual(key.HistoricalPaths(), index.HistoricalPaths()) {
t.Fatal("numeric reporting scopes differ")
}
var paths []string
for _, p := range key.HistoricalPaths() {
paths = append(paths, p.String())
}
if !strings.Contains(strings.Join(paths, ","), "/component/0/old") || !strings.Contains(strings.Join(paths, ","), "/component/0/new") {
t.Fatalf("shape history = %v", paths)
}
if _, ok := key.Metadata().Lookup(configkit.Keys("component", "0", "new")); ok {
t.Fatal("explicit key query changed intent")
}
if _, ok := key.Metadata().Lookup(configkit.Keys("component").Index(0).Key("new")); !ok {
t.Fatal("index query failed")
}
}

View File

@@ -0,0 +1,153 @@
package configkit_test
import (
"bytes"
"errors"
"reflect"
"strings"
"testing"
configkit "go.maximumdirect.net/configkit"
)
func TestInspectionViewScopeAndQueries(t *testing.T) {
result, err := configkit.Load[map[string]any](configkit.Bytes("view.yml", []byte("a: {child: one}\nab: two\nitems: [{name: first}]\n'a/b': {'': value}\n")))
if err != nil {
t.Fatal(err)
}
view, ok := result.InspectSubtree(configkit.Keys("a"))
if !ok {
t.Fatal("view unavailable")
}
var paths []string
for _, path := range view.HistoricalPaths() {
paths = append(paths, path.String())
}
if !reflect.DeepEqual(paths, []string{"/a", "/a/child"}) {
t.Fatalf("scope paths = %#v", paths)
}
if _, ok := view.Metadata().Lookup(configkit.Keys("ab")); !ok {
t.Fatal("metadata filtered")
}
if _, ok := view.Explain(configkit.Keys("ab")); !ok {
t.Fatal("native query filtered")
}
var output bytes.Buffer
if err := view.WriteExplanation(&output, configkit.Keys("ab")); err != nil {
t.Fatal(err)
}
if len(view.Sources()) != len(result.Sources()) || len(view.Sources()) == 0 {
t.Fatal("sources filtered")
}
if _, ok := view.Source(view.Sources()[0].ID); !ok {
t.Fatal("source unavailable")
}
if _, ok := result.InspectSubtree(configkit.Keys("absent")); !ok {
t.Fatal("absent scope rejected")
}
if _, ok := result.InspectSubtree(configkit.Path{}.Index(-1)); ok {
t.Fatal("invalid scope accepted")
}
keyScope, _ := result.InspectSubtree(configkit.Keys("items", "0"))
indexScope, _ := result.InspectSubtree(configkit.Keys("items").Index(0))
if !reflect.DeepEqual(keyScope.HistoricalPaths(), indexScope.HistoricalPaths()) {
t.Fatal("numeric scope differs")
}
escaped, _ := result.InspectSubtree(configkit.Keys("a/b", ""))
if got := escaped.HistoricalPaths(); len(got) != 1 || got[0].String() != "/a~1b/" {
t.Fatalf("escaped scope = %#v", got)
}
root, _ := result.InspectSubtree(configkit.Path{})
if !reflect.DeepEqual(root.HistoricalPaths(), result.Metadata().HistoricalPaths()) {
t.Fatal("root scope filtered")
}
}
type viewFailWriter struct{}
func (viewFailWriter) Write([]byte) (int, error) { return 0, errors.New("write failed") }
func TestInspectionViewWriteEffective(t *testing.T) {
options := configkit.Options[map[string]any]{Definition: configkit.Definition[map[string]any]{
Sensitive: func(path configkit.Path) bool { return path.String() == "/private" || path.String() == "/nested/token" },
Resolve: func(current *map[string]any, resolution *configkit.Resolution) error {
delete(*current, "removed")
resolution.RecordNormalization(configkit.Keys("removed"), "remove")
return nil
},
}}
result, err := configkit.Load(configkit.Bytes("view.yml", []byte("private: {child: canary-private}\nnested: {token: canary-token, name: public}\nitems: [zero, one]\n'0': numeric\n'null': null\nremoved: earlier\n")), options)
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
path configkit.Path
contains string
absent string
fails bool
}{
{configkit.Path{}, "public", "canary-token", false},
{configkit.Keys("nested"), "public", "canary-token", false},
{configkit.Keys("private", "child"), "REDACTED", "canary-private", false},
{configkit.Keys("items"), "one", "", false},
{configkit.Keys("items").Index(1), "one", "", false},
{configkit.Path{}.Index(0), "numeric", "", false},
{configkit.Keys("null"), "null", "", false},
{configkit.Keys("removed"), "", "", true},
{configkit.Keys("missing"), "", "", true},
} {
view, ok := result.InspectSubtree(tc.path)
if !ok {
t.Fatal("view unavailable")
}
var out bytes.Buffer
err := view.WriteEffective(&out)
if (err != nil) != tc.fails || (tc.fails && out.Len() != 0) || (tc.contains != "" && !strings.Contains(out.String(), tc.contains)) || (tc.absent != "" && strings.Contains(out.String(), tc.absent)) {
t.Errorf("%s: %q, %v", tc.path.String(), out.String(), err)
}
}
view, _ := result.InspectSubtree(configkit.Keys("nested"))
result.Config["nested"] = "changed"
var out bytes.Buffer
if err := view.WriteEffective(&out); err != nil || !strings.Contains(out.String(), "public") {
t.Fatalf("frozen output = %q, %v", out.String(), err)
}
if err := view.WriteEffective(viewFailWriter{}); err == nil {
t.Fatal("writer error lost")
}
if err := view.WriteEffective(nil); err == nil {
t.Fatal("nil writer accepted")
}
if err := (configkit.Inspection{}).WriteEffective(&bytes.Buffer{}); err == nil {
t.Fatal("zero view accepted")
}
}
func TestInspectionViewUnavailable(t *testing.T) {
var result *configkit.Result[map[string]any]
if _, ok := result.InspectSubtree(configkit.Path{}); ok {
t.Fatal("nil result accepted")
}
if _, ok := (&configkit.Result[map[string]any]{}).InspectSubtree(configkit.Path{}); ok {
t.Fatal("manual result accepted")
}
var view configkit.Inspection
if len(view.HistoricalPaths()) != 0 || view.Sources() != nil {
t.Fatal("zero view returned records")
}
if _, ok := view.Metadata().Lookup(configkit.Path{}); ok {
t.Fatal("zero metadata")
}
if _, ok := view.Source("source-1"); ok {
t.Fatal("zero source")
}
if _, ok := view.SourceContext("source-1"); ok {
t.Fatal("zero source context")
}
if _, ok := view.Explain(configkit.Path{}); ok {
t.Fatal("zero explanation")
}
if err := view.WriteExplanation(&bytes.Buffer{}, configkit.Path{}); err == nil {
t.Fatal("zero explanation rendering")
}
}

187
facade_result_value_test.go Normal file
View File

@@ -0,0 +1,187 @@
package configkit_test
import (
"bytes"
"reflect"
"strings"
"testing"
configkit "go.maximumdirect.net/configkit"
)
type valueName string
type valueKey string
type valueEmbedded struct{ Label valueName }
type valueCodec struct{ Text string }
func (valueCodec) MarshalText() ([]byte, error) { panic("codec called during lookup") }
func (*valueCodec) UnmarshalText([]byte) error { panic("codec called during lookup") }
type valueConfig struct {
Embedded *valueEmbedded `yaml:",inline"`
Extra map[valueKey]any `yaml:",inline"`
List []string `yaml:"list"`
Array [2]int `yaml:"array"`
Dynamic any `yaml:"dynamic"`
Codec valueCodec `yaml:"codec"`
Pointer *valueEmbedded `yaml:"pointer"`
Nil *valueEmbedded `yaml:"nil"`
Ignored string `yaml:"-"`
private string
}
func TestResultValueCurrentNavigation(t *testing.T) {
var missing *configkit.Result[valueConfig]
if _, ok := missing.Value(configkit.Path{}); ok {
t.Fatal("nil result")
}
var nilMap map[string]int
result := &configkit.Result[valueConfig]{Config: valueConfig{
Embedded: &valueEmbedded{Label: "named"}, Extra: map[valueKey]any{"a/b": nil, "": nilMap, "0": 7},
List: []string{"first"}, Array: [2]int{1, 2}, Dynamic: map[string]any{"list": []any{valueEmbedded{Label: "dynamic"}}}, Pointer: &valueEmbedded{Label: "pointer"},
}}
parsed, _ := configkit.ParsePath("/dynamic/list/0/label")
parsedKey, _ := configkit.ParsePath("/0")
if got, ok := result.Value(configkit.Path{}); !ok || !reflect.DeepEqual(got, result.Config) {
t.Fatalf("root = %#v, %v", got, ok)
}
pointer, ok := result.Value(configkit.Keys("dynamic", "list").Index(0))
if !ok || pointer.(valueEmbedded).Label != "dynamic" {
t.Fatalf("struct terminal = %#v, %v", pointer, ok)
}
for _, tc := range []struct {
path configkit.Path
want any
ok bool
}{
{configkit.Keys("label"), valueName("named"), true},
{configkit.Keys("a/b"), nil, true}, {configkit.Keys(""), nilMap, true},
{parsedKey, 7, true}, {configkit.Path{}.Index(0), nil, false},
{configkit.Keys("list").Index(0), "first", true}, {configkit.Keys("list", "0"), nil, false},
{configkit.Keys("list").Index(1), nil, false}, {configkit.Keys("list").Index(-1), nil, false},
{parsed, valueName("dynamic"), true}, {configkit.Keys("ignored"), nil, false}, {configkit.Keys("private"), nil, false},
{configkit.Keys("codec"), valueCodec{}, true}, {configkit.Keys("codec", "text"), nil, false},
{configkit.Keys("nil"), (*valueEmbedded)(nil), true}, {configkit.Keys("nil", "label"), nil, false},
{configkit.Keys("pointer", "label"), valueName("pointer"), true},
} {
got, ok := result.Value(tc.path)
if ok != tc.ok || !reflect.DeepEqual(got, tc.want) {
t.Errorf("%s: got %#v, %v; want %#v, %v", tc.path.String(), got, ok, tc.want, tc.ok)
}
}
copyValue, _ := result.Value(configkit.Keys("array"))
array := copyValue.([2]int)
array[0] = 9
listValue, _ := result.Value(configkit.Keys("list"))
listValue.([]string)[0] = "changed"
mapValue, _ := result.Value(configkit.Keys("dynamic"))
mapValue.(map[string]any)["added"] = true
pointerValue, _ := result.Value(configkit.Keys("pointer"))
pointerValue.(*valueEmbedded).Label = "changed"
if result.Config.Array[0] != 1 || result.Config.List[0] != "changed" {
t.Fatal("assignment ownership differs")
}
if result.Config.Dynamic.(map[string]any)["added"] != true {
t.Fatal("map assignment did not preserve alias")
}
if result.Config.Pointer.Label != "changed" {
t.Fatal("pointer assignment did not preserve alias")
}
result.Config.Embedded = nil
if _, ok := result.Value(configkit.Keys("label")); ok {
t.Fatal("nil inline pointer")
}
result.Config.Dynamic = make(chan int)
if _, ok := result.Value(configkit.Keys("dynamic")); !ok {
t.Fatal("unsupported terminal unavailable")
}
if _, ok := result.Value(configkit.Keys("dynamic", "x")); ok {
t.Fatal("unsupported value traversed")
}
}
func TestResultValueFrozenInspectionAndSecret(t *testing.T) {
t.Setenv("CONFIGKIT_VALUE_TEST_SECRET", "disposable-value-canary")
type settings struct {
Name string `yaml:"name"`
Count int `yaml:"count"`
Token configkit.Secret `yaml:"token"`
}
result, err := configkit.Load[settings](configkit.Bytes("settings.yml", []byte("name: before\ntoken: CONFIGKIT_VALUE_TEST_SECRET\n")))
if err != nil {
t.Fatal(err)
}
if got, ok := result.Value(configkit.Keys("count")); !ok || got != 0 || result.Metadata().IsExplicit(configkit.Keys("count")) {
t.Fatalf("default = %#v, %v", got, ok)
}
secret, ok := result.Value(configkit.Keys("token"))
if !ok || secret.(configkit.Secret).Value() != "disposable-value-canary" {
t.Fatal("resolved secret unavailable")
}
result.Config.Name = "after"
if got, _ := result.Value(configkit.Keys("name")); got != "after" {
t.Fatalf("current value = %v", got)
}
var output bytes.Buffer
if err := result.WriteEffective(&output); err != nil {
t.Fatal(err)
}
if !strings.Contains(output.String(), "before") || strings.Contains(output.String(), "after") || strings.Contains(output.String(), "disposable-value-canary") {
t.Fatalf("frozen output = %s", output.String())
}
}
func TestResultValueReturnsTerminalsWithoutSchemaValidation(t *testing.T) {
type terminal struct {
A int `yaml:"same"`
B int `yaml:"same"`
}
want := terminal{A: 1, B: 2}
cases := []struct {
name string
lookup func(configkit.Path) (any, bool)
path configkit.Path
}{
{"map", (&configkit.Result[map[string]terminal]{Config: map[string]terminal{"item": want}}).Value, configkit.Keys("item")},
{"slice", (&configkit.Result[[]terminal]{Config: []terminal{want}}).Value, configkit.Path{}.Index(0)},
{"array", (&configkit.Result[[1]terminal]{Config: [1]terminal{want}}).Value, configkit.Path{}.Index(0)},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got, ok := tc.lookup(tc.path)
if !ok || got != want {
t.Fatalf("terminal = %#v, %v", got, ok)
}
if _, ok := tc.lookup(tc.path.Key("same")); ok {
t.Fatal("ambiguous containing bindings accepted")
}
})
}
// A post-load replacement need not itself satisfy the load-time schema.
result, err := configkit.Load[map[string]any](configkit.Bytes("dynamic.yml", []byte("{}")))
if err != nil {
t.Fatal(err)
}
result.Config["dynamic"] = struct {
Child terminal `yaml:"child"`
Good int `yaml:"good"`
}{Child: want, Good: 3}
for _, tc := range []struct {
path configkit.Path
want any
}{
{configkit.Keys("dynamic", "child"), want},
{configkit.Keys("dynamic", "good"), 3},
} {
got, ok := result.Value(tc.path)
if !ok || got != tc.want {
t.Fatalf("%s = %#v, %v", tc.path.String(), got, ok)
}
}
if _, ok := result.Value(configkit.Keys("dynamic", "child", "same")); ok {
t.Fatal("ambiguous dynamic child accepted navigation")
}
if _, err := configkit.Load[map[string]terminal](configkit.NoSource()); err == nil {
t.Fatal("Load accepted an invalid element schema")
}
}

88
inspection_view.go Normal file
View File

@@ -0,0 +1,88 @@
package configkit
import (
"io"
"go.maximumdirect.net/configkit/internal/engine"
)
// Inspection is a reporting view of a completed load. Its scope filters
// enumeration; explicit queries and source records retain their native paths.
type Inspection struct{ view engine.InspectionView }
// InspectSubtree selects a canonical JSON Pointer reporting location, including
// an absent location. Equivalent key and index spellings select the same scope.
// Nil, manually constructed results and invalid paths cannot produce a view.
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool) {
if r == nil {
return Inspection{}, false
}
view, ok := engine.NewInspectionView(r.inspection, toEnginePath(path))
return Inspection{view: view}, ok
}
// Metadata returns the unfiltered metadata of the completed load.
func (i Inspection) Metadata() Metadata { return Metadata{value: i.view.Inspection().Metadata()} }
// HistoricalPaths returns observed paths at or beneath the reporting scope.
func (i Inspection) HistoricalPaths() []Path {
values := i.view.HistoricalPaths()
paths := make([]Path, len(values))
for index := range values {
paths[index] = fromEnginePath(values[index])
}
return paths
}
// WriteEffective renders the saved value at the reporting scope with its
// original sensitivity. Unavailable values and nil writers return an error;
// writer errors can leave partial output.
func (i Inspection) WriteEffective(output io.Writer) error { return i.view.WriteEffective(output) }
// Diff compares frozen views at the same canonical scope, including differences
// at an ancestor when the existing comparison treats that ancestor atomically.
// Views may come from different root Go types. Unavailable or mismatched views
// return an error without records.
func (i Inspection) Diff(other Inspection) ([]Difference, error) {
values, err := i.view.Diff(other.view)
if err != nil {
return nil, err
}
return fromEngineDifferences(values), nil
}
// Sources returns the full detached source catalog.
func (i Inspection) Sources() []SourceInfo {
values := i.view.Inspection().Sources()
if values == nil {
return nil
}
result := make([]SourceInfo, len(values))
for index := range values {
result[index] = fromEngineSourceInfo(values[index])
}
return result
}
// Source returns a detached record from the full source catalog.
func (i Inspection) Source(id string) (SourceInfo, bool) {
value, ok := i.view.Inspection().Source(id)
return fromEngineSourceInfo(value), ok
}
// SourceContext returns the borrowed resource context for an acquired source.
func (i Inspection) SourceContext(id string) (ResourceContext, bool) {
value, ok := i.view.Inspection().SourceContext(id)
return ResourceContext{FS: value.FS, BaseDir: value.BaseDir}, ok
}
// Explain queries a native path, whether or not it lies within the scope.
func (i Inspection) Explain(path Path) (Explanation, bool) {
value, ok := i.view.Inspection().Explain(toEnginePath(path))
return fromEngineExplanation(value), ok
}
// WriteExplanation renders an explicit native path using the frozen load.
func (i Inspection) WriteExplanation(output io.Writer, path Path) error {
return i.view.Inspection().WriteExplanation(output, toEnginePath(path))
}

View File

@@ -0,0 +1,68 @@
package engine
import (
"errors"
"io"
yamladapter "go.maximumdirect.net/configkit/internal/yaml"
)
// InspectionView borrows an inspection and selects a canonical reporting scope.
type InspectionView struct {
inspection *Inspection
scope Path
}
func NewInspectionView(inspection *Inspection, scope Path) (InspectionView, bool) {
if inspection == nil || !scope.valid() {
return InspectionView{}, false
}
normalized, err := ParsePath(scope.String())
if err != nil {
return InspectionView{}, false
}
return InspectionView{inspection: inspection, scope: normalized}, true
}
func (v InspectionView) Inspection() *Inspection { return v.inspection }
func (v InspectionView) Diff(other InspectionView) ([]Difference, error) {
if v.inspection == nil || other.inspection == nil || v.scope.String() != other.scope.String() {
return nil, errors.New("configkit: diff inspection scope unavailable or mismatched")
}
values, err := Diff(v.inspection, other.inspection)
if err != nil {
return nil, err
}
var result []Difference
for _, value := range values {
if pathContains(v.scope, value.Path) || pathContains(value.Path, v.scope) {
result = append(result, value)
}
}
return result, nil
}
func (v InspectionView) WriteEffective(output io.Writer) error {
if v.inspection == nil || v.inspection.final == nil || output == nil {
return errEffectiveUnavailable
}
node, ok := documentAtPathWithLookup(v.inspection.final, v.scope, v.inspection.documentLookup())
if !ok {
return errEffectiveUnavailable
}
return yamladapter.Write(output, redactedDocument(node, v.inspection.secrets, v.scope))
}
func (v InspectionView) HistoricalPaths() []Path {
if v.inspection == nil {
return nil
}
var paths []Path
for _, path := range v.inspection.metadata.HistoricalPaths() {
if pathContains(v.scope, path) {
paths = append(paths, path)
}
}
return paths
}

View File

@@ -0,0 +1,99 @@
package engine
import "reflect"
// ResultValue navigates the current Go value without projecting or copying it.
func ResultValue(root any, path Path, secrets SecretBinding) (any, bool) {
if !path.valid() {
return nil, false
}
current := reflect.ValueOf(root)
if len(path.segments) == 0 {
return root, true
}
builder := schemaBuilder{cache: make(map[reflect.Type]*typeDescriptor), building: make(map[reflect.Type]bool), secrets: secrets, lookup: true}
for _, segment := range path.segments {
seen := make(map[valueVisit]bool)
for current.IsValid() && (current.Kind() == reflect.Pointer || current.Kind() == reflect.Interface) {
if current.IsNil() {
return nil, false
}
if current.Kind() == reflect.Pointer {
visit := valueVisit{typeOf: current.Type(), kind: current.Kind(), ptr: current.Pointer()}
if seen[visit] {
return nil, false
}
seen[visit] = true
}
current = current.Elem()
}
if !current.IsValid() {
return nil, false
}
descriptor, issue := builder.describe(current.Type(), Path{})
if issue != nil {
return nil, false
}
switch descriptor.kind {
case descriptorStruct:
if segment.kind == pathSegmentIndex {
return nil, false
}
if position, ok := descriptor.fieldByName[segment.key]; ok {
current = resultField(current, descriptor.fields[position].index)
} else if descriptor.inlineMap != nil {
current = resultMapEntry(resultField(current, descriptor.inlineMap.index), segment.key)
} else {
return nil, false
}
case descriptorMap:
if segment.kind == pathSegmentIndex {
return nil, false
}
current = resultMapEntry(current, segment.key)
case descriptorSlice, descriptorArray:
index, ok := schemaIndex(segment)
if !ok || index >= current.Len() {
return nil, false
}
current = current.Index(index)
default:
return nil, false
}
if !current.IsValid() {
return nil, false
}
}
if !current.CanInterface() {
return nil, false
}
return current.Interface(), true
}
func resultField(root reflect.Value, index []int) reflect.Value {
current := root
for position, field := range index {
if current.Kind() != reflect.Struct {
return reflect.Value{}
}
current = current.Field(field)
if position < len(index)-1 {
for current.Kind() == reflect.Pointer {
if current.IsNil() {
return reflect.Value{}
}
current = current.Elem()
}
}
}
return current
}
func resultMapEntry(value reflect.Value, name string) reflect.Value {
if !value.IsValid() || value.Kind() != reflect.Map {
return reflect.Value{}
}
key := reflect.New(value.Type().Key()).Elem()
key.SetString(name)
return value.MapIndex(key)
}

View File

@@ -0,0 +1,67 @@
package engine
import (
"reflect"
"testing"
)
func TestResultValueNavigation(t *testing.T) {
type key string
type embedded struct{ Name string }
type root struct {
Embedded *embedded `yaml:",inline"`
Extra map[key]any `yaml:",inline"`
List []int `yaml:"list"`
Any any `yaml:"any"`
}
value := root{Embedded: &embedded{Name: "named"}, Extra: map[key]any{"a/b": nil}, List: []int{3}, Any: map[string]any{"n": []any{"ok"}}}
parsed, _ := ParsePath("/any/n/0")
for _, tc := range []struct {
path Path
want any
ok bool
}{
{Keys("name"), "named", true},
{Keys("a/b"), nil, true},
{Keys("missing"), nil, false},
{Keys("list").Index(0), 3, true},
{Keys("list").Key("0"), nil, false},
{parsed, "ok", true},
{Keys("list").Index(2), nil, false},
{Path{}.Index(-1), nil, false},
} {
got, ok := ResultValue(value, tc.path, SecretBinding{})
if ok != tc.ok || !reflect.DeepEqual(got, tc.want) {
t.Errorf("%s: got %#v, %v; want %#v, %v", tc.path.String(), got, ok, tc.want, tc.ok)
}
}
value.Embedded = nil
if _, ok := ResultValue(value, Keys("name"), SecretBinding{}); ok {
t.Fatal("nil inline pointer was traversed")
}
}
func TestResultValueTerminalAndPointerCycle(t *testing.T) {
type pointer *pointer
var cycle pointer
cycle = &cycle
var nilSlice []string
for _, value := range []any{nil, nilSlice, make(chan int), cycle} {
got, ok := ResultValue(value, Path{}, SecretBinding{})
if !ok || reflect.TypeOf(got) != reflect.TypeOf(value) {
t.Fatalf("terminal %#v: got %#v, %v", value, got, ok)
}
}
if _, ok := ResultValue(cycle, Keys("x"), SecretBinding{}); ok {
t.Fatal("pointer cycle was traversed")
}
channel := make(chan int)
value := struct{ Channel chan int }{Channel: channel}
got, ok := ResultValue(value, Keys("channel"), SecretBinding{})
if !ok || got != channel {
t.Fatalf("unsupported terminal: got %#v, %v", got, ok)
}
if _, ok := ResultValue(value, Keys("channel", "x"), SecretBinding{}); ok {
t.Fatal("unsupported terminal accepted navigation")
}
}

View File

@@ -115,6 +115,9 @@ type schemaBuilder struct {
building map[reflect.Type]bool building map[reflect.Type]bool
journal []reflect.Type journal []reflect.Type
secrets SecretBinding secrets SecretBinding
// lookup describes only the current container and its flattened inline fields.
// Ordinary descendants are described only when navigation continues into them.
lookup bool
} }
func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescriptor, *schemaIssue) { func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescriptor, *schemaIssue) {
@@ -134,6 +137,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
if current.Kind() == reflect.Pointer { if current.Kind() == reflect.Pointer {
descriptor.kind = descriptorPointer descriptor.kind = descriptorPointer
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path) element, issue := b.describe(current.Elem(), path)
if issue != nil { if issue != nil {
return nil, issue return nil, issue
@@ -171,6 +177,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
return fail(CodeSchemaUnsupportedType, "configuration maps must have string keys") return fail(CodeSchemaUnsupportedType, "configuration maps must have string keys")
} }
descriptor.kind = descriptorMap descriptor.kind = descriptorMap
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path) element, issue := b.describe(current.Elem(), path)
if issue != nil { if issue != nil {
return nil, issue return nil, issue
@@ -178,6 +187,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
descriptor.element = element descriptor.element = element
case reflect.Slice: case reflect.Slice:
descriptor.kind = descriptorSlice descriptor.kind = descriptorSlice
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path.Index(0)) element, issue := b.describe(current.Elem(), path.Index(0))
if issue != nil { if issue != nil {
return nil, issue return nil, issue
@@ -186,6 +198,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
case reflect.Array: case reflect.Array:
descriptor.kind = descriptorArray descriptor.kind = descriptorArray
descriptor.length = current.Len() descriptor.length = current.Len()
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path.Index(0)) element, issue := b.describe(current.Elem(), path.Index(0))
if issue != nil { if issue != nil {
return nil, issue return nil, issue

View File

@@ -4,9 +4,13 @@ import "reflect"
func (b *schemaBuilder) describeOrdinaryField(owner *typeDescriptor, field reflect.StructField, index int, name string, secret bool, path Path) *schemaIssue { func (b *schemaBuilder) describeOrdinaryField(owner *typeDescriptor, field reflect.StructField, index int, name string, secret bool, path Path) *schemaIssue {
fieldPath := path.Key(name) fieldPath := path.Key(name)
fieldType, issue := b.describe(field.Type, fieldPath) var fieldType *typeDescriptor
if issue != nil { if !b.lookup {
return issue var issue *schemaIssue
fieldType, issue = b.describe(field.Type, fieldPath)
if issue != nil {
return issue
}
} }
if issue := addField(owner, fieldDescriptor{name: name, index: []int{index}, descriptor: fieldType, secret: secret}, path); issue != nil { if issue := addField(owner, fieldDescriptor{name: name, index: []int{index}, descriptor: fieldType, secret: secret}, path); issue != nil {
return issue return issue

31
result_value.go Normal file
View File

@@ -0,0 +1,31 @@
package configkit
import "go.maximumdirect.net/configkit/internal/engine"
// Value returns the current Config value at path. The root [Path] selects Config.
// A non-nil result supports lookup even when constructed manually without load
// or inspection state. Success means value availability, not input presence or
// validation; use Metadata to inspect presence in the completed load.
//
// Navigation follows the shared YAML field names, inline bindings and supported
// shapes described in docs/config.md#application-schema-binding, with [Path]'s
// key/index rules. It follows non-nil intermediate pointers and interfaces,
// checks map membership and sequence bounds, and never allocates missing values.
// Scalars, including text-codec types and Secret, remain leaves.
// A nil receiver, invalid path, missing value, or unavailable traversal returns
// (nil, false). A present nil succeeds: a nil interface returns (nil, true), while
// typed nil pointers, maps and slices retain their types in the returned any.
//
// The terminal retains its actual Go type, including named types and pointers;
// terminal pointers are not dereferenced. Lookup performs no conversion or
// revalidation of the terminal and does not invoke codecs or resolve secrets.
// Values are trusted application data and may include resolved Secret values.
// Ordinary Go assignment applies: structs and arrays are copied, while maps,
// slices and pointers can alias Config. Inspection methods continue to report
// the frozen completed load, not later caller mutations.
func (r *Result[T]) Value(path Path) (any, bool) {
if r == nil {
return nil, false
}
return engine.ResultValue(r.Config, toEnginePath(path), secretBinding())
}