3.6 KiB
ADR 0007: Use native YAML and ordered documents for inspection reports
Status
Accepted.
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.
Decision
The initial standard uses text for concise operator reports and YAML for structured consumption.
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. CommandKit supplies
document separators and scope-label comments around native writer output. Each
scope retains its own value namespace and native rendering; the documents can
be decoded individually.
For config show, CommandKit checks operation availability for selected scopes
before acquisition. It acquires all selected views and completes validation
required by those provider contracts before report output begins. A failure
returns its diagnostic outcome before report writing. Other inspection operations
define their own output timing. After writing begins, a writer failure may leave
partial bytes and returns operational failure under
ADR 0005.
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.
Additional families select formats appropriate to their resources. Custom handler formats remain application-owned. The CLI reference owns exact per-operation formats, framing syntax, and report shapes for implemented commands.
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. |
Write config show documents as each scope is acquired |
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.
Loading all selected scopes before config show output adds preparation time and
allows a failure in one scope to prevent combined display. Explicit single-scope
display remains available for a narrower view.
Additional structured schemas are compatibility contracts owned by CommandKit. Native concatenation can use existing writers; semantic comparison uses the owning library's supported comparison API under ADR 0008.