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.