diff --git a/docs/roadmap/reporting.md b/docs/roadmap/reporting.md index 6d57885..f7e6c64 100644 --- a/docs/roadmap/reporting.md +++ b/docs/roadmap/reporting.md @@ -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