95 lines
5.1 KiB
Markdown
95 lines
5.1 KiB
Markdown
# ADR 0005: Return explicit outcomes and deliver reports through defined channels
|
|
|
|
## Status
|
|
|
|
Proposed
|
|
|
|
## Date
|
|
|
|
2026-10-06
|
|
|
|
## Context
|
|
|
|
An invocation crosses routing, parsing, provider acquisition, a standard or
|
|
application handler, report writing, and the application entry point. Operators
|
|
and subprocess consumers need consistent classifications for those stages.
|
|
Applications also have meaningful domain outcomes of their own.
|
|
|
|
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes process and domain
|
|
ownership. [ADR 0003](0003-public-facade.md) establishes public error and backend
|
|
boundaries. The remaining decisions concern the public outcome model, report
|
|
and diagnostic channels, and standard process-status mappings.
|
|
|
|
## Decision
|
|
|
|
CommandKit returns an invocation outcome with an explicit classification and
|
|
recommended process status. The public model distinguishes successful operation,
|
|
usage error, operational failure, and application domain outcome. Failures retain
|
|
their consumer-facing cause and supported `errors.Is`/`errors.As` identity.
|
|
Exact Go declarations remain part of facade API design.
|
|
|
|
Use these mappings for CommandKit-owned commands:
|
|
|
|
| Status | Meaning |
|
|
| --- | --- |
|
|
| `0` | The requested operation completed successfully, including help and completed comparison. |
|
|
| `1` | A syntactically valid operation failed during loading, validation, lookup, inspection, cancellation, diagnostics delivery, or report writing. |
|
|
| `2` | The invocation failed command, flag, scope, format, operand, repetition, or input-combination validation. |
|
|
|
|
CommandKit's handler result contract accepts domain classifications and suggested
|
|
process statuses supplied by the caller. CommandKit preserves that classification
|
|
when returning the handler's result.
|
|
A custom domain status and a shared usage status may have the same numeric value;
|
|
their explicit classifications retain their distinct meanings. The application
|
|
entry point controls final process termination and status mapping.
|
|
|
|
CommandKit writes standard reports to the supplied report stream, conventionally
|
|
stdout, and its warnings and errors to the supplied diagnostic stream,
|
|
conventionally stderr. Callers choose the streams. Each CommandKit diagnostic has
|
|
one delivery owner and one emission through the selected channel. The provider
|
|
contract carries acquisition diagnostics and their delivery state so CommandKit
|
|
can present pending diagnostics once. CommandKit adapts backend
|
|
syntax failures into its public classification and safe diagnostic presentation.
|
|
Usage guidance accompanies usage errors; operational failures receive diagnostics
|
|
appropriate to the failed operation.
|
|
|
|
Warning severity alone permits a successful operation. A diagnostic writer
|
|
failure is an operational failure. Source coordinates and source-ID legends are
|
|
preserved where supplied by the owning library.
|
|
|
|
Report writers use the application's supplied streams. Shell redirection provides
|
|
file output for the initial standard. A writer failure can leave a partial report
|
|
and returns operational failure. The outcome identifies incomplete delivery;
|
|
checking it before interpreting reports is recommended caller practice. Custom
|
|
handler output remains application-owned. Multi-scope loading and ordering follow
|
|
[the YAML report policy](0007-native-yaml-reports.md).
|
|
|
|
A completed semantic comparison returns success with its differences and coverage
|
|
gaps recorded in the report. Its outcome describes successful inspection; the
|
|
application or consuming script can interpret differences according to its task.
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| A single failure classification | Simplifies outcome handling. Callers derive syntax, operational, and domain distinctions through additional interpretation. |
|
|
| Backend errors and output as the public outcome model | Reuses framework machinery directly. Backend conventions become dependencies for applications and subprocess consumers. |
|
|
| One common mapping for application domain failures | Produces uniform numeric statuses. Applications adapt existing artifact and execution outcomes to shared categories. |
|
|
| Handler-owned diagnostics for every failure | Gives each handler full presentation control. Shared diagnostic consistency requires repeated ownership and formatting coordination. |
|
|
| Dedicated file-output options | Adds direct file targeting. The standard acquires creation, replacement, and retention responsibilities alongside report writing. |
|
|
|
|
## Consequences
|
|
|
|
The outcome model supports both Go callers and executable entry points. Explicit
|
|
classification keeps domain identity intact through adapter and facade conversion.
|
|
Single diagnostic ownership supports predictable presentation.
|
|
|
|
CommandKit handlers and writers coordinate cause propagation and delivery
|
|
responsibility. Output failures may produce partial bytes; callers receive an
|
|
outcome describing delivery failure. The public result/error design preserves
|
|
these semantics
|
|
through fresh invocation state and private adapter callbacks.
|
|
|
|
Acceptance establishes the compatibility meaning of these status values and
|
|
delivery rules across standard commands.
|