74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# 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](0009-configuration-scopes.md). 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](0005-invocation-outcomes.md).
|
|
|
|
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](../cli.md) 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](0008-semantic-configuration-diff.md).
|