diff --git a/docs/roadmap/reporting.md b/docs/roadmap/reporting.md index 9b09525..fd4cdd8 100644 --- a/docs/roadmap/reporting.md +++ b/docs/roadmap/reporting.md @@ -5,8 +5,9 @@ treatment of help and version, message prefixes, and OD-1's flag grammar and scope (including independent Progress control) are selected. OD-2's unified reporting direction, the terminal failure model, and application ownership of error handling are selected. -Exact API signatures, failure explanation details, retention, and delivery -mechanics remain open. Implementation has not started. +OD-3's failure presentation and retention boundaries are selected. +Exact API signatures and OD-4's delivery mechanics remain open. +Implementation has not started. ## Purpose @@ -34,9 +35,9 @@ the application supplies a non-zero outcome and an operator-facing explanation. Reporting does not require the underlying Go error or undertake its tracking, recovery, or identity preservation. -A convenience helper that explicitly presents `err.Error()` as a Warning could -fit this boundary. Such a helper would only convert the supplied error to a -message at the application's request; its inclusion and signature remain open. +Applications can explicitly present `err.Error()` as a Warning through the +ordinary message API, illustrated by `report.Warn(err.Error())`. Defer a separate +`WarnError` convenience helper; this conversion already requires little code. CommandKit retains responsibility for handling its own errors, including routing, parsing, and reporting failures. Integration-owned commands similarly @@ -125,9 +126,9 @@ For multiline diagnostics, prefix the opening line and preserve the structured detail. Integration adapters coordinate native diagnostic rendering to avoid duplicate severity labels or loss of upstream formatting. -Streaming Progress messages use the diagnostic channel so they do not corrupt -substantive output such as JSON or YAML. Progress presentation details remain -part of the consumer API and delivery design below. +Initially, Progress messages are unprefixed streamed lines. They use the +diagnostic channel so they do not corrupt substantive output such as JSON or +YAML. Terminal redraw and progress-bar behavior are outside this implementation. ### Terminal failure model @@ -149,7 +150,7 @@ continue, the handler returns a non-zero outcome with an explicit explanation such as "Unable to export the requested report." The application can choose to include detail from a Go error in that explanation. CommandKit presents the supplied explanation without automatically deriving text from an application -error. The exact failure-construction API remains open under OD-3. +error. Exact API names and signatures remain to be finalized. Output streamed before the failure remains visible according to its selected mode; terminal failure does not withdraw earlier bytes. Deferred messages, @@ -157,6 +158,36 @@ cleanup writes, and delivery failures must respect the end of normal reporting. Their finalization and late-write behavior remain OD-4 details. A terminal failure may have multiple explanatory records, all belonging to that failure. +### Failure explanations and presentation ownership (OD-3) + +Make a non-zero outcome with an explicit message the convenient failure path. +Support structured explanations, including multiple records, through the same +presentation facility for richer application and integration reports. Neither +form requires an underlying Go error. + +The application or integration explicitly identifies the context belonging to +a terminal explanation. Present that context with the failure in every mode, +including quiet. Independent warnings and other messages retain their own +visibility rules. For mixed upstream batches, adapters preserve useful native +rendering while distinguishing terminal explanatory context from independent +messages. Core does not infer those relationships from error chains or text. + +Assign each submitted message one presentation path. Returning a terminal +explanation schedules its presentation once; core does not append another +message derived from an application error cause. Native renderers can supply +already-labelled content without receiving duplicate prefixes. Avoid text-based +deduplication: separate events may legitimately produce identical messages. + +### Retention boundary (OD-3) + +CommandKit provides invocation-scoped CLI presentation. Logging and message +history collection remain application concerns. Keep terminal explanations with +the returned outcome, and keep the temporary state needed for deferred delivery, +parser events awaiting mode selection, and delivery bookkeeping. The reporting +facility does not collect a transcript or retain other emitted or suppressed +messages for later inspection. No optional message-history facility is planned +for this implementation. + ## Selected flag grammar and scope ### Mode selection and resets @@ -316,9 +347,8 @@ output is not part of the proposed direction. Keep errors understandable in every mode, including source locations and related explanatory context. Unrelated warnings and informational messages -remain subject to the selected mode. Whether to retain submitted messages for -programmatic inspection, including suppressed messages, remains open under -OD-3. This concerns presentation records, not application error tracking. +remain subject to the selected mode. Apply the selected retention boundary +without accumulating a message history. ## Selected consumer reporting API direction @@ -358,10 +388,10 @@ explicit status and presentation content; they do not require a Go error cause. 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. +The returned outcome carries terminal explanations, with other retention limited +to the presentation needs described above. 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 under OD-4. Standard @@ -404,16 +434,18 @@ rules. 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, +5. Verify classification, flag selection, suppression, terminal explanations, ordering, duplicate prevention, terminal Error/non-zero-outcome consistency, debug visibility, and write-failure handling with focused behavioral tests and maintained consumer examples. Cover mode resets, mixed canonical/alias ordering, help and discovery contexts, and core parser events presented according to the final mode. Cover explicit progress overrides, debug's progress default, quiet suppression, progress aliases, message prefixes, - and preservation of native multiline diagnostics. Verify the end of normal - reporting after terminal error presentation, including deferred and late - writes under the selected OD-4 behavior. + and preservation of native multiline diagnostics. Cover explicit explanatory + context in quiet mode, independent warnings in mixed batches, already-labelled + native content, and distinct submissions with identical text. Verify the end + of normal reporting after terminal error presentation, including deferred + and late writes under the selected OD-4 behavior. 6. Update GoDoc, the CLI reference, consumer guidance, and release documentation when implemented. Reconcile the selected error-handling boundary with ADR 0005's existing outcome and error-identity commitments before changing @@ -422,27 +454,6 @@ rules. ## Open Decisions -### OD-3: Failure presentation and diagnostic retention - -The terminal failure model and application error-handling boundary are selected -above. The remaining questions concern explicit presentation content: - -- How does a handler supply a non-zero outcome with a simple explanation or - multiple structured explanatory records, including application domain failures? -- How do callers and integration adapters identify the context belonging to a - terminal explanation, and present mixed diagnostic batches while preserving - useful native rendering and applying visibility to independent messages? -- Which submitted messages, if any, are retained for programmatic inspection, - including when suppressed? How is that observation exposed separately from - message submission? -- How is duplicate presentation avoided, and how do adapters apply prefixes to - mixed or already-labelled native diagnostics? -- What presentation should streaming Progress use? Is a convenience helper for - explicitly presenting `err.Error()` as a Warning useful enough to include? - -Application error classification, recovery, and cause tracking are outside -these questions. Delivery failures produced by reporting remain under OD-4. - ### OD-4: Delivery lifecycle and quiet execution How are immediate and deferred messages ordered and finalized, including when @@ -453,6 +464,5 @@ delivery state represents intentional suppression? Does quiet mode discard rendered bytes or skip report rendering, and how does that choice preserve operation semantics and failure detection? Which streaming behavior becomes part of the public contract? -Are initial Progress messages ordinary streamed lines, or is terminal redraw -behavior needed? How do progress delivery failures and retention interact with -other messages? No progress-bar, redraw, or terminal-specific API is selected yet. +How do Progress delivery failures interact with other messages? Progress uses +the selected streamed-line presentation and shared retention boundary.