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:
|
||||
|
||||
Reference in New Issue
Block a user