Document value access and focused inspection
This commit is contained in:
@@ -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
|
||||
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
|
||||
validation failure returns a nil result and a `*LoadError`. Successful results
|
||||
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` |
|
||||
| Show the saved final configuration as safe YAML | `WriteEffective` |
|
||||
| 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
|
||||
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
|
||||
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
|
||||
|
||||
`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
|
||||
`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
|
||||
|
||||
There are three separate tasks when working with credentials:
|
||||
|
||||
@@ -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) |
|
||||
| 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) |
|
||||
| Hand one result to library consumers | [Component handoff](#component-handoff) |
|
||||
| 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
|
||||
|
||||
- Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration.
|
||||
|
||||
@@ -58,6 +58,7 @@ Accepted decisions:
|
||||
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
|
||||
- [Keep the public facade root-owned](adr/0006-public-facade.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)
|
||||
- [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md)
|
||||
- [Separate import selection controls](adr/0016-independent-import-controls.md)
|
||||
@@ -309,6 +310,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` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
|
||||
@@ -45,6 +45,10 @@ Implemented component owners:
|
||||
- Root `Diff` and `Difference` provide the public comparison boundary and
|
||||
convert detached engine records to root-owned paths and snapshots; consumer
|
||||
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/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
|
||||
- Engine mechanism tests own source, composition, inheritance, decoding,
|
||||
|
||||
@@ -316,12 +316,14 @@ See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
|
||||
Detailed syntax and operation tables belong to the
|
||||
[current configuration contract](../config.md).
|
||||
|
||||
The frozen inspection boundary also supports comparing completed same-type
|
||||
results without reopening sources or rerunning the load lifecycle. The
|
||||
The frozen inspection boundary supports comparing completed same-type results
|
||||
and focused views across application root types without reopening sources or
|
||||
rerunning the load lifecycle. The
|
||||
[configuration contract](../config.md#effective-configuration-diffs) owns
|
||||
comparison and disclosure behavior, the [component overview](../internal/overview.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
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Implementation plan: typed result values and focused inspection
|
||||
|
||||
Status: implementation in progress; Stages 1–8 complete.
|
||||
Status: complete; all stages implemented and validated.
|
||||
|
||||
## Scope and working instructions
|
||||
|
||||
@@ -309,6 +309,8 @@ or claim completion of real PromptKit integration.
|
||||
|
||||
## Stage 9 — Document the implemented boundary and validate the sprint
|
||||
|
||||
**Complete.**
|
||||
|
||||
Update documentation only once the corresponding behavior exists:
|
||||
|
||||
- Declaration comments own signatures, nil/absence behavior, ordinary aliasing,
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Typed value access and focused inspection from a result
|
||||
|
||||
Status: agreed feature scope; OD-1 through OD-5 settled; not implemented.
|
||||
Status: implemented; OD-1 through OD-5 settled. See the current
|
||||
[configuration contract](../config.md) and declaration comments for behavior.
|
||||
Baseline: v1.3.0, commit `652ddb6`.
|
||||
|
||||
## Purpose and baseline
|
||||
@@ -11,12 +12,12 @@ checks its public settings type, and constructs its runtime objects. Libraries
|
||||
can also offer inspection focused on their section. Section names remain library
|
||||
conventions, not ConfigKit reserved keys.
|
||||
|
||||
Today, [Result.Config](../../lifecycle.go) supplies trusted typed values, but its
|
||||
generic root type prevents a library from selecting a field without knowing the
|
||||
At the baseline, [Result.Config](../../lifecycle.go) supplied trusted typed values, but its
|
||||
generic root type prevented a library from selecting a field without knowing the
|
||||
application type or adding its own traversal. Existing metadata and
|
||||
[source contexts](../../resource_context.go) already support field provenance and
|
||||
resource lookup. Existing inspection and comparison operate on completed-load
|
||||
snapshots, but there is no reusable subtree reporting view. Redacted inspection
|
||||
resource lookup. Baseline inspection and comparison operated on completed-load
|
||||
snapshots, but there was no reusable subtree reporting view. Redacted inspection
|
||||
snapshots are not execution inputs.
|
||||
|
||||
PromptKit has accepted the typed-value direction. The subsequently agreed
|
||||
|
||||
Reference in New Issue
Block a user