base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expand reporting categories and define failure-bound errors

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-23 18:08:13 +00:00
parent 09d4d7992a
commit fa0aeace36
1 changed files with 70 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/roadmap/reporting.md
View File

@@ -1,15 +1,16 @@
# Output policy and invocation reporting # Output policy and invocation reporting
Status: initial planning. The three output modes and uniform treatment of help Status: initial planning. Message categories, the quiet/default/verbose output
and version are selected. Consumer API, flag details, and delivery mechanics policy, and uniform treatment of help and version are selected. A debug mode
remain open. Implementation has not started. extends the proposed hierarchy. Consumer API, flag details, and delivery
mechanics remain open. Implementation has not started.
## Purpose ## Purpose
Provide consistent handling of `--quiet` and `--verbose` across application Provide consistent handling of `--quiet`, `--verbose`, and the proposed
commands and optional integrations. Reduce repeated output classification, `--debug` mode across application commands and optional integrations. Reduce
diagnostic presentation, and delivery bookkeeping where CommandKit can provide repeated output classification, diagnostic presentation, and delivery bookkeeping
a meaningful benefit. where CommandKit can provide a meaningful benefit.
Ordinary Go writers and formatting functions already make application output Ordinary Go writers and formatting functions already make application output
straightforward. Design reporting conveniences around the shared output policy straightforward. Design reporting conveniences around the shared output policy
@@ -36,22 +37,42 @@ CommandKit diagnostics while preserving native rendering and source context.
Some adapters wrap multiple records in one diagnostic writer and classify the Some adapters wrap multiple records in one diagnostic writer and classify the
batch by its highest severity. This matters when designing selective visibility. batch by its highest severity. This matters when designing selective visibility.
There is currently no shared quiet/verbose policy or invocation reporter API. There is currently no shared verbosity policy or invocation reporter API.
## Selected output policy ## Selected output policy
The operator chooses among quiet, ordinary, and verbose presentation: Distinguish substantive application output from diagnostic message categories:
| Output category | `--quiet` | No flag | `--verbose` | - **Substantive output (Normal):** The requested report or command result.
| --- | --- | --- | --- | - **Error:** The invocation failed and will return a non-zero status code.
| Substantive application output | Suppressed | Shown | Shown | - **Warning:** Something went wrong or deserves attention, but the invocation
| Warnings and informational messages | Suppressed | Suppressed | Shown | can still succeed. A recovered problem is a warning.
| Error diagnostics for a failed run | Shown | Shown | Shown | - **Info:** Progress or useful explanation, including completion messages.
- **Debug:** Troubleshooting detail, including intermediate decisions and
execution-path information.
Substantive output includes requested reports and command results. Progress and Quiet, ordinary, and verbose presentation follow the selected policy. The
completion chatter are informational messages. The category of a message proposed debug mode adds troubleshooting detail to verbose output:
determines its visibility; stream destination alone cannot distinguish a
warning from an error. | Output category | `--quiet` | No flag | `--verbose` | `--debug` (proposed) |
| --- | --- | --- | --- | --- |
| Substantive application output | Suppressed | Shown | Shown | Shown |
| Error | Shown | Shown | Shown | Shown |
| Warning | Suppressed | Suppressed | Shown | Shown |
| Info | Suppressed | Suppressed | Shown | Shown |
| Debug | Suppressed | Suppressed | Suppressed | Shown |
Info belongs in verbose mode; debug includes verbose messages. Normal output
remains a substantive result category, separate from diagnostic severity.
The category of a message determines its visibility; stream destination alone
cannot distinguish a warning from an error.
Error presentation is tied to invocation failure. Prefer deriving error
diagnostics from a failed outcome, which may carry detailed explanations. Avoid
an unrestricted `Error(...)` reporting method that permits an error message
followed by a successful outcome. The application still controls process exit
under the existing outcome contract; the returned outcome must consistently
represent the failure and its non-zero status.
Apply the same policy to help and version. There are no command-specific Apply the same policy to help and version. There are no command-specific
exceptions for successful output: exceptions for successful output:
@@ -69,10 +90,10 @@ diagnostic delivery.
### Flag and invocation behavior ### Flag and invocation behavior
Model quiet, ordinary, and verbose as mutually exclusive presentation modes. Model quiet, ordinary, verbose, and debug as mutually exclusive presentation
The proposed rule when both flags occur is last occurrence wins, consistent modes. The proposed rule when multiple mode flags occur is last occurrence wins,
with existing repetition conventions. Exact boolean forms, resets, short consistent with existing repetition conventions. Exact boolean forms, resets,
spellings, placement, and collision handling remain to be specified. short spellings, placement, and collision handling remain to be specified.
Keep verbosity a presentation choice: a quiet invocation still performs its Keep verbosity a presentation choice: a quiet invocation still performs its
requested operation and returns the ordinary outcome. Apply the policy through requested operation and returns the ordinary outcome. Apply the policy through
@@ -81,9 +102,9 @@ streams or external destinations remains application-owned.
### Streaming and failure diagnostics ### Streaming and failure diagnostics
The proposed approach applies visibility when output is emitted. A verbose run The proposed approach applies visibility when output is emitted. A verbose or
may show progress before subsequently failing, and an ordinary run may write debug run may show progress before subsequently failing, and an ordinary run may
part of its substantive output before failing. Previously written bytes cannot write part of its substantive output before failing. Previously written bytes cannot
be withdrawn. Whole-run buffering solely to make failed runs contain only error be withdrawn. Whole-run buffering solely to make failed runs contain only error
output is not part of the proposed direction. output is not part of the proposed direction.
@@ -99,7 +120,9 @@ An invocation-scoped facility could classify messages, coordinate immediate and
end-of-handler presentation, and retain delivery failures. Earlier illustrative end-of-handler presentation, and retain delivery failures. Earlier illustrative
API shapes included `inv.Reporter()`, `Info`, `Warn`, `Diagnostic`, and an API shapes included `inv.Reporter()`, `Info`, `Warn`, `Diagnostic`, and an
`AtEnd()` view. These names and shapes are exploratory, not selected contracts. `AtEnd()` view. These names and shapes are exploratory, not selected contracts.
Reassess the necessary API around the output modes before adopting them. Reassess the necessary API around the output modes and expanded message
categories before adopting them. Debug messages need a corresponding
classification; its exact API remains open.
Continue to support standard `io.Writer` usage for report bodies and native Continue to support standard `io.Writer` usage for report bodies and native
report writers. Reuse existing diagnostic and outcome concepts where practical. report writers. Reuse existing diagnostic and outcome concepts where practical.
@@ -107,9 +130,9 @@ Any reporting facility should coordinate with returned `Outcome.Diagnostics`
and operation causes so already-presented messages are not repeated. and operation causes so already-presented messages are not repeated.
Whether reporting methods return write errors, retain them for finalization, Whether reporting methods return write errors, retain them for finalization,
or expose an explicit delivery-error accessor remains open. Emitting an or expose an explicit delivery-error accessor remains open. The API must enforce
error-severity message and deciding the operation's outcome need clearly the selected relationship between Error diagnostics and failed outcomes,
defined responsibilities. including diagnostics supplied through generic or existing entry points.
### Upstream diagnostic ownership ### Upstream diagnostic ownership
@@ -123,6 +146,10 @@ already exists or prescribe its upstream shape. Preserve useful native
diagnostic detail and supported error identity, and coordinate returned errors diagnostic detail and supported error identity, and coordinate returned errors
with diagnostics that already explain them. with diagnostics that already explain them.
Debug output follows the same upstream disclosure and safe-rendering contracts.
Enabling debug does not authorize secret disclosure or bypass owning-library
rules.
## Work needed ## Work needed
1. Settle the open decisions with examples covering ordinary application output, 1. Settle the open decisions with examples covering ordinary application output,
@@ -136,8 +163,9 @@ with diagnostics that already explain them.
4. Implement the selected behavior across core and the integrations. Preserve 4. Implement the selected behavior across core and the integrations. Preserve
upstream rendering and semantics while applying the chosen visibility policy. upstream rendering and semantics while applying the chosen visibility policy.
5. Verify classification, flag selection, suppression, retained diagnostics, 5. Verify classification, flag selection, suppression, retained diagnostics,
ordering, duplicate prevention, and write-failure handling with focused ordering, duplicate prevention, Error/non-zero-outcome consistency, debug
behavioral tests and maintained consumer examples. visibility, and write-failure handling with focused behavioral tests and
maintained consumer examples.
6. Update GoDoc, the CLI reference, consumer guidance, and release documentation 6. Update GoDoc, the CLI reference, consumer guidance, and release documentation
when implemented. Review whether any resulting architectural change needs an when implemented. Review whether any resulting architectural change needs an
ADR; exact reporting APIs and flag syntax remain API/CLI contracts. ADR; exact reporting APIs and flag syntax remain API/CLI contracts.
@@ -146,23 +174,26 @@ with diagnostics that already explain them.
### OD-1: Flag grammar and scope ### OD-1: Flag grammar and scope
How are quiet and verbose selected, repeated, combined, or explicitly reset? How are quiet, verbose, and debug selected, repeated, combined, or explicitly
Are short spellings built in? Where may the flags appear, including on help reset? Are short spellings built in? Where may the flags appear, including on help
requests? How are canonical and alias spelling collisions handled, and how is requests? How are canonical and alias spelling collisions handled, and how is
the mode determined for invocations that fail during routing or parsing? the mode determined for invocations that fail during routing or parsing?
### OD-2: Consumer API and output classification ### OD-2: Consumer API and output classification
What is the smallest API for substantive output, informational messages, What is the smallest API for substantive output, debug and informational
warnings, and errors? How do direct writes through `Invocation.Streams` interact messages, warnings, and failure diagnostics? How do direct writes through
with it? How can helpers report through the same invocation? Is a dedicated `Invocation.Streams` interact with it? How can helpers report through the same
immediate/deferred reporter needed, and how does it compose with existing invocation? Is a dedicated immediate/deferred reporter needed, and how does it compose with existing
outcome diagnostics? outcome diagnostics?
### OD-3: Failure presentation and diagnostic retention ### OD-3: Failure presentation and diagnostic retention
What identifies an error that must be shown, particularly for application domain How does the API enforce that Error diagnostics accompany a failed invocation
outcomes and error-severity diagnostics accompanying a successful outcome? with a non-zero status, including application domain outcomes? How should
inconsistent caller-supplied combinations be handled through existing diagnostic
and outcome APIs? How are recovered upstream problems represented as warnings
while preserving their native context?
Which contextual records belong to an error explanation? How are mixed upstream Which contextual records belong to an error explanation? How are mixed upstream
diagnostic batches filtered while preserving useful native rendering? What is diagnostic batches filtered while preserving useful native rendering? What is
retained when presentation is suppressed, and how is duplicate presentation retained when presentation is suppressed, and how is duplicate presentation