111 lines
5.6 KiB
Markdown
111 lines
5.6 KiB
Markdown
# ADR 0007: Use native YAML and ordered documents for inspection reports
|
|
|
|
## Status
|
|
|
|
Proposed
|
|
|
|
## Date
|
|
|
|
2026-10-06
|
|
|
|
## Context
|
|
|
|
ConfigKit and PromptKit provide native YAML configuration inspection. Reusing
|
|
their writers preserves captured value semantics, ordering, and redaction. YAML
|
|
also supports automated consumption of structured reports.
|
|
|
|
The agreed initial direction is YAML-based structured inspection with JSON
|
|
deferred, and separate native documents for `config show --scope all`. The
|
|
remaining choices concern report defaults, document framing, and when output
|
|
begins relative to configuration loading.
|
|
|
|
## Decision
|
|
|
|
The initial standard uses text for concise operator reports and YAML for
|
|
structured consumption. JSON retains deferred status; a future format extension
|
|
is evaluated against a concrete consumer need.
|
|
|
|
| Operation | Default report | Available initial formats |
|
|
| --- | --- | --- |
|
|
| `help` | Text | Text |
|
|
| `version` | Text | Text, YAML |
|
|
| `config scopes`, `validate`, `sources`, `explain`, `diff` | Text | Text, YAML |
|
|
| `config show` | Native YAML | YAML |
|
|
| `promptkit list/show` | Text | Text, YAML |
|
|
|
|
These format choices govern initial configuration and PromptKit reports and
|
|
version reporting. Additional families select formats appropriate to their own
|
|
resources through their command contracts. Custom handler formats remain
|
|
application-owned. Version format selection preserves the selected subject under
|
|
[ADR 0004](0004-standard-inspection-surface.md).
|
|
|
|
Operations with a format choice use `--format text|yaml`. Format names are
|
|
lowercase. YAML-only display uses its native writer directly. Help presents its
|
|
registered text form. Format validation follows the usage outcome policy in
|
|
[ADR 0005](0005-invocation-outcomes.md).
|
|
|
|
A single-scope `config show` writes the owning library's complete native redacted
|
|
YAML. Its output consists of the inspection document itself. The native writer
|
|
preserves effective presence, null and container distinctions, stable mapping
|
|
order, and sequence order according to its public contract.
|
|
|
|
`config show --scope all` emits one native document per registered scope in the
|
|
order defined by [ADR 0009](0009-configuration-scopes.md): application first,
|
|
PromptKit next when registered, followed by additional scopes in identifier order.
|
|
Each document begins with `---` and a `# scope: NAME` comment. A one-scope `all`
|
|
selection uses the same labeled document form.
|
|
|
|
CommandKit writes the separators and comments around the native writer output.
|
|
Comments label scopes for operators; document order follows the registered scope
|
|
inventory. That framing offers callers an association between documents and
|
|
scopes. Each scope retains its own value namespace and native rendering.
|
|
The combined stream is an inspection report whose documents can be decoded
|
|
individually.
|
|
|
|
CommandKit checks operation availability for selected scopes before acquisition.
|
|
It acquires their views and completes validation required by those provider
|
|
contracts before report output begins. A failure returns its diagnostic outcome
|
|
before report writing. After writing begins, a writer failure may leave partial
|
|
bytes and returns operational failure under ADR 0005.
|
|
|
|
Other structured reports use operation-specific YAML schemas and selection
|
|
metadata. They contain one document and a trailing newline. Native explanation
|
|
snapshots retain their safe YAML text and presence/redaction metadata when
|
|
projected into structured reports. The CLI reference owns exact schemas and
|
|
field names after implementation.
|
|
|
|
Report confidentiality follows the owning libraries' sensitivity classifications.
|
|
Their safe writers and records supply redacted content. CommandKit preserves
|
|
those confidentiality semantics; arbitrary caller content retains the caller's
|
|
disclosure policy.
|
|
Report delivery uses the supplied streams and the channel policy in ADR 0005.
|
|
Configuration path syntax follows ConfigKit's JSON Pointer contract independently
|
|
of serialization format.
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| A scope-keyed YAML wrapper | Carries scope identity as parsed mapping keys. Rendering needs an additional wrapper representation and indentation of native documents. |
|
|
| JSON alongside YAML initially | Serves JSON-specific tools. The library maintains another serializer and representation contract. |
|
|
| YAML as every report's default | Provides uniform structured output. Interactive help, tables, and explanation workflows use structured documents for routine discovery. |
|
|
| Output each scope as acquisition finishes | Starts reporting earlier. A later acquisition failure can leave a successful prefix representing only part of the selection. |
|
|
| Marshal application runtime structs | Reuses application data types. Presence, captured resolution, ordering, and safe historical inspection need a separate rendering lifecycle. |
|
|
|
|
## Consequences
|
|
|
|
Native display preserves owning-library behavior and keeps rendering focused.
|
|
Combined inspection requires multi-document YAML consumption and an ordered scope
|
|
contract. The comments label documents, and the ordered inventory supports
|
|
identification.
|
|
|
|
Loading all scopes before output adds preparation time and allows a failure in
|
|
one selected scope to prevent combined output. Explicit single-scope inspection
|
|
remains available for a narrower view. Writer failures remain visible through
|
|
outcomes and may leave partial output.
|
|
|
|
Additional structured schemas are compatibility contracts owned by CommandKit.
|
|
Native concatenation can use existing writers; semantic comparison separately
|
|
requires the safe structured data described in
|
|
[ADR 0011](0011-semantic-configuration-diff.md).
|