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

Select unified invocation reporting API direction

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 01:01:48 +00:00
parent 810333e376
commit 0869b17b43
1 changed files with 52 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/roadmap/reporting.md
View File

@@ -3,7 +3,9 @@
Status: initial planning. Message categories, all four output modes, uniform
treatment of help and version, message prefixes, and OD-1's flag grammar and
scope (including independent Progress control) are selected.
Consumer API and delivery mechanics remain open. Implementation has not started.
OD-2's unified reporting direction is selected. Exact API signatures, failure
presentation, retention, and delivery mechanics remain open. Implementation has
not started.
## Purpose
@@ -268,28 +270,54 @@ remain subject to the selected mode. Retain suppressed diagnostics for
programmatic inspection rather than equating suppression with loss of evidence.
The exact representation of retained and delivered diagnostics remains open.
### Consumer reporting API
## Selected consumer reporting API direction
An invocation-scoped facility could classify messages, coordinate immediate and
end-of-handler presentation, and retain delivery failures. Earlier illustrative
API shapes included `inv.Reporter()`, `Info`, `Warn`, `Diagnostic`, and an
`AtEnd()` view. These names and shapes are exploratory, not selected contracts.
Reassess the necessary API around the output modes and expanded message
categories before adopting them. Debug and Progress messages need corresponding
classifications; their exact APIs remain open. Progress is a streaming category;
do not conflate it with deferred informational summaries.
Provide one reporting facility per invocation for substantive output, immediate
messages, and end-of-run diagnostics. The consumer API is chosen for its intended
long-term design; with no current consumers, preserving existing API shapes
carries no weight in this decision.
Continue to support standard `io.Writer` usage for report bodies and native
report writers. Reuse existing diagnostic and outcome concepts where practical.
Any reporting facility should coordinate with returned `Outcome.Diagnostics`
and operation causes so already-presented messages are not repeated.
The facility exposes interfaces appropriate to each need:
| Need | Selected direction | Illustrative shape |
| --- | --- | --- |
| Substantive results | An ordinary `io.Writer`, usable by encoders and native report writers. | `inv.Reporter().Output()` |
| Immediate messages | Categorized methods applying visibility and presentation automatically. | `Info`, `Warn`, `Debug`, `Progress` |
| End-of-run diagnostics | An explicit deferred view sharing the invocation's reporting state. | `report.AtEnd().Warn(message)` |
| Rich upstream diagnostics | Typed submission preserving severity, context, and native rendering. | Exact API remains open. |
These method names illustrate the selected direction; exact names and signatures
remain to be finalized. Progress is streaming output, distinct from deferred
informational summaries. Applications need not implement categories they do not
use or check verbosity before reporting.
The reporter owns presentation: output visibility, progress settings, prefixes,
ordering, and delivery bookkeeping. Its views share invocation state, allowing
already-emitted messages, deferred messages, suppression, and write failures to
be coordinated in one place. Helpers may receive the reporter or a narrow
application-defined interface. Domain libraries can continue returning
diagnostic data for the handler to submit, independently of CommandKit.
The returned outcome owns the operation result: success, failure, or an
application domain classification. CommandKit presents a failed outcome through
the same reporting facility. Error explanations must be explicitly associated
with the failure they describe; an unrestricted `Error(...)` method that permits
success afterward is outside this direction. Typed upstream diagnostic submission
must preserve that relationship as well.
Use the reporter as the common diagnostic submission path, replacing the earlier
proposal to split submission between a reporter and `Outcome.Diagnostics`.
Whether the execution result exposes retained diagnostic observations is an
OD-3 decision, separate from how handlers submit messages. Caller-selected
destinations belong at the execution boundary; the handler-facing API routes
output through the reporter instead of requiring a parallel raw-stream API.
Whether reporting methods return write errors, retain them for finalization,
or expose an explicit delivery-error accessor remains open. The API must enforce
the selected relationship between Error diagnostics and failed outcomes,
including diagnostics supplied through generic or existing entry points.
or expose an explicit delivery-error accessor remains open under OD-4. Standard
writer operations remain compatible with `io.Writer`. The final API design will
consolidate these choices with the selected consumer-facing structure.
### Upstream diagnostic ownership
## Upstream diagnostic ownership
ConfigKit and PromptKit remain authoritative for their diagnostic semantics,
severity, source context, and disclosure rules. Integration adapters expose
@@ -314,9 +342,10 @@ rules.
2. Review current diagnostic batching, parsing, help, outcome presentation, and
writer ownership to identify the smallest shared changes. Include invocation
failures that occur before a handler receives its `Invocation`.
3. Specify the public API and flag contracts, including interactions with command
and flag aliases, following the selected OD-1 rules above. Assess existing
flag collisions and compatibility impact.
3. Finalize the unified reporting API and flag contracts, including interactions
with command and flag aliases, following OD-1 and OD-2 above. Replace split
handler submission paths and adapt core and integration callers. Account for
flag collisions and document changed public contracts.
4. Implement the selected behavior across core and the integrations. Preserve
upstream rendering and semantics while applying the chosen visibility policy.
5. Verify classification, flag selection, suppression, retained diagnostics,
@@ -333,22 +362,12 @@ rules.
## Open Decisions
### OD-2: Consumer API and output classification
What is the smallest API for substantive output, streaming progress, debug and
informational messages, warnings, and failure diagnostics? How do direct writes through
`Invocation.Streams` interact with it? How can helpers report through the same
invocation? Is a dedicated immediate/deferred reporter needed, and how does it compose with existing
outcome diagnostics?
How do helpers emit Progress without requiring every application to implement
it or manage verbosity checks themselves?
### OD-3: Failure presentation and diagnostic retention
How does the API enforce that Error diagnostics accompany a failed invocation
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
failure explanations and the operation outcome be associated to avoid
inconsistent caller-supplied combinations? 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
diagnostic batches filtered while preserving useful native rendering? What is