Invocation, options and results
Ссылкаtopaz explain
topaz explain <TPZ####>
Ввод
Supply exactly one recognized diagnostic code with the TPZ prefix and four decimal digits. Reject missing, extra, malformed, and unknown codes.
Accept - or -, with human output by default. Reject -, source operands, compiler selectors, and other options.
Параметры и конфликты
| Параметр | Значение по умолчанию | Контракт | Конфликты |
|---|---|---|---|
--format human|json | human | Selects human output or one JSON report. The default is human output. | Не перечислены |
Каналы вывода
stdout
stderr
Статус завершения
0
The installed catalog contains the code and its report is printed.
1
Arguments, code lookup, or report output fails.
Эффекты
Read the installed diagnostic catalog. Do not open a program source, create files, or change package metadata.
The explanation comes from the installed catalog without network access.
The same installed catalog, code, output format, and presentation settings produce the same report. Catalog changes between releases can change explanation prose.
No package discovery, dependency resolution, lock validation, or lock update is performed.
Operation
СсылкаUse the code reported by the compiler. Diagnostic pages define causes and repairs. This command defines how to retrieve the explanation.
Option conditions
СсылкаUse - for the JSON report. The - spelling is rejected.
Behavior contract
СсылкаCommand behavior
Arguments and rejection
Supply exactly one recognized diagnostic code with the TPZ prefix and four decimal digits. Reject missing, extra, malformed, and unknown codes.
Accept - or -, with human output by default. Reject -, source operands, compiler selectors, and other options.
Output
Human output contains the code, phase, title, summary, reason, and suggested repairs. JSON output is one object on standard output with string code, phase, title, summary, and why, array fixits of strings, and object machine describing the diagnostic's machine identity.
A runtime machine identity includes its string kind when defined. Failures use standard error and produce no successful explanation object.
Exit status
Exit 0 means the requested code was found and its explanation was printed. Exit 1 means invalid arguments, an unknown code, or an output failure.
Filesystem effects
Read the installed diagnostic catalog. Do not open a program source, create files, or change package metadata.
Network access
The explanation comes from the installed catalog without network access.
Reproducibility
The same installed catalog, code, output format, and presentation settings produce the same report. Catalog changes between releases can change explanation prose.
Packages and locks
No package discovery, dependency resolution, lock validation, or lock update is performed.
Причина
A diagnostic explanation describes an installed code independently of a source file. Rejecting an unknown code prevents an empty success from being mistaken for an explanation.
The linked public CLI recipe checks the exact displayed argument rejection before the requested operation. It does not execute the successful operation or verify its effects.
The safe recipe rejects the source filename supplied in place of a diagnostic code. Successful human and JSON explanations need different operands and remain outside that recipe.
Example contract
СсылкаExample contract
The invocation topaz explain main. is expected to exit with 1.
Reject the non-code fixture operand because diagnostic lookup requires a TPZ#### code. No diagnostic explanation is claimed by this example.
Причина
Diagnostic codes identify causes independently of source filenames. Rejecting a filename prevents a failed lookup from appearing to explain a program.
Example
СсылкаArgument-rejection example
Ссылкаfunction identity<T>(value: T) -> T {value}
Ожидаемый результат
Ожидаемый результат
Textual rejection details remain Pending in the reference model. The independent Tools example gate expects exit 1.
Reject the non-code fixture operand because diagnostic lookup requires a TPZ#### code. No diagnostic explanation is claimed by this example.
Verification scope
СсылкаObserved with Topaz 5.21.3 on 2026-11-06T08:36:29.642Z. This invocation passed; exit 1. 4 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation.