Skip to content
Topazdocs

Search documentation

Specification 6.0

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Download →

    Design decisions

    Tools

    A deferred error fails the whole command

    Adopted November 8, 2026 · 6.0.0 · In progress

    Problem

    The main execution can finish before deferred work reports a runtime or host error. Callers that look only at completion status still need to see that failure.

    Decision

    A deferred runtime or host error fails the execution and prevents a test-ok report.

    Alternatives considered

    • Report the main execution’s success as the final result. A later failure would be hidden by the successful result.

    Why

    Tools that inspect command completion can detect deferred failures.

    Changed rules Test completion and failure reporting →

    Test assertions evaluate once and compare golden files exactly

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    Assertion arguments can have side effects, and a final newline can matter in a golden file. Tests need defined behavior both after a failed assertion and when the file differs.

    Decision

    • Evaluate arguments once, from left to right. Use ordinary comparisons and extract the outer constructor.
    • An assertion fault TPZ4007 stops the current test at runtime.
    • Compare the existing UTF-8 golden file exactly, without creating or updating it.

    Examples

    Equality returns unit and execution continues

    assert-eq.tpzEquality returns unit and execution continuesOpen in Playground →
    1. import std.io
    2. import std.test
    3. let result: () = test.assertEq([1, 2], [1, 2])
    4. io.writeLine("{result}")
    Expected outputExit code 0
    ()
    
    $ topaz run assert-eq.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. ()

    Match exact line endings and an empty golden file

    main.tpzMatch exact line endings and an empty golden file
    1. import std.test
    2. import std.io
    3. test.assertGolden("expected.txt", "alpha\r\nβ\n")
    4. test.assertGolden("empty.txt", "")
    5. io.writeLine("golden text matched")
    Expected outputExit code 0
    golden text matched
    
    $ topaz run main.tpz --language-version 6.0
    expected.txtMatch exact line endings and an empty golden file
    1. alpha
    2. β
    empty.txtMatch exact line endings and an empty golden file
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. golden text matched

    Fail when the final newline is missing from actual text

    main.tpzFail when the final newline is missing from actual text
    1. import std.test
    2. import std.io
    3. io.writeLine("before")
    4. test.assertGolden("expected.txt", "line")
    5. io.writeLine("after")
    Expected outputNonzero exit
    before
    
    $ topaz run main.tpz --language-version 6.0
    expected.txtFail when the final newline is missing from actual text
    1. line
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4007 →

      stdlib-assert-golden-mismatch at main.tpz:5:1

    Expected stdout
    1. before

    Fail instead of creating a missing golden file

    main.tpzFail instead of creating a missing golden fileOpen in Playground →
    1. import std.test
    2. import std.io
    3. io.writeLine("before")
    4. test.assertGolden("missing.txt", "new text")
    5. io.writeLine("after")
    Expected outputNonzero exit
    before
    
    $ topaz run main.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4007 →

      stdlib-assert-golden-missing at main.tpz:5:1

    Expected stdout
    1. before

    Fail assertOk with the rendered error

    main.tpzFail assertOk with the rendered errorOpen in Playground →
    1. import std.test
    2. import std.io
    3. let value: Result<int, string> = Err("bad")
    4. io.writeLine("before")
    5. test.assertOk(value)
    6. io.writeLine("after")
    Expected outputNonzero exit
    before
    
    $ topaz run main.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    Expected stdout
    1. before

    Why

    A failed assertion stops the test, and the same checked-in golden file can be compared again.

    Changed rules Equality assertions →Compare existing golden text without updating it →Assert a Result constructor and return its payload →Assert presence or absence →

    Storage cleanup preserves workspaces that may still be in use

    Adopted November 8, 2026 · 6.0.0 · In progress

    Problem

    An old workspace can still belong to a running job. Its ownership or liveness can also change between inspection and deletion.

    Decision

    • Preserve workspaces with a live or uncertain owner regardless of age.
    • Status and cleanup use the same classification. Recheck ownership and liveness immediately before deletion.

    Alternatives considered

    • Delete by age alone. An old workspace can still be in use.

    Why

    Cleanup leaves files in place while an owner is active or its status is uncertain.

    Changed rules Command behavior →Command behavior →

    Command options with no effect are removed

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A script using --types can look as though it requests extra work. An option that does nothing obscures what the command actually runs.

    Decision

    Remove options that have no effect, including --types.

    Examples

    Reject the unused types option

    main.tpzReject the unused types option
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format json --types
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Check with the canonical command

    main.tpzCheck with the canonical commandOpen in Playground →
    1. let value = 1
    Expected outputExit code 0
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Continue accepting no-op flags. Readers could mistake the flag for a behavior change.

    Why

    An option in a command line corresponds to real work or a real choice.

    Changed rules Type checking without a mode flag →

    Topaz version prints the product version

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    Printing the version and requesting verbose output could each have several spellings. Documentation and scripts might use different names for the same operation.

    Decision

    • Run topaz version to print the version.
    • Use --verbose for verbose output. Remove aliases for both operations.

    Examples

    Reject the version flag alias

    main.tpzReject the version flag alias
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz --version
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Reject the short version alias

    main.tpzReject the short version alias
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz -V
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Reject the short detail alias

    main.tpzReject the short detail alias
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz version -v
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Request the detailed release report

    main.tpzRequest the detailed release report
    1. let value = 1
    Expected outputExit code 0
    $ topaz version --verbose
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Keep the aliases. Readers would still need to recognize multiple names for equivalent operations.

    Why

    Use the spelling from help directly in scripts.

    Changed rules Named metadata commands and long options →

    An option value is a separate argument

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    Joining an option with its value or passing two arguments gives the same command two forms. Code that constructs an argument array can use one convention.

    Decision

    Pass the value as the next argument. The --flag=value form is unavailable.

    Examples

    Reject an equals format value

    main.tpzReject an equals format value
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format=json
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Pass values as separate arguments

    main.tpzPass values as separate argumentsOpen in Playground →
    1. let value = 1
    Expected outputExit code 0
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Accept joined and separate values. The same option value would have two spellings.

    Why

    The argument list marks the boundary between the option and its value.

    Changed rules Separate option values →

    A command option occurs at most once

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A script that combines arguments can pass the same option twice. Accepting both occurrences makes it harder to tell which value took effect.

    Decision

    Reject a repeated option even when its values are identical.

    Examples

    Reject a repeated language selector

    main.tpzReject a repeated language selector
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz check main.tpz --format json --language-version 6.0 --language-version 6.0
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Reject conflicting formats in one order

    main.tpzReject conflicting formats in one order
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format json --format human
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Reject conflicting formats in the other order

    main.tpzReject conflicting formats in the other order
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format human --format json
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Give each option once

    main.tpzGive each option onceOpen in Playground →
    1. let value = 1
    Expected outputExit code 0
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Use the last value. Changing the order in which arguments are assembled could silently change behavior.

    Why

    The duplicate is visible at the command that contains it.

    Changed rules One occurrence of each option →

    Commands select JSON output with the same option

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A script can read output from several commands. Command-specific flags would give the same output choice several spellings.

    Decision

    Use --format json on commands with JSON output. Remove --json.

    Examples

    Keep the check diagnostic format

    main.tpzKeep the check diagnostic formatOpen in Playground →
    1. let value = 1
    Expected outputExit code 0
    No stdout.
    $ topaz check main.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Keep separate flags for each command. Users would have to remember different ways to request the same format.

    Why

    Scripts can select the output format consistently across commands.

    Changed rules One JSON format selector →

    JSON diagnostics keep stable codes and primary locations

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    Tools read a diagnostic's code and location to navigate to the offending expression. The message can improve without changing what the tool highlights.

    Decision

    • The --format json contract covers structured identity, required fields and their types, coordinate units, severity and the cause pointed to by the primary location.
    • Message and label wording can change. Redefining an identity or a promised location requires a contract version and migration guidance. Retired identities are never reused.

    Alternatives considered

    • Leave location meaning outside the stable contract. A tool could start highlighting another cause with no clear regression signal.
    • Make message wording and the order of secondary notes stable too. The contract should catch wrong causes and locations without blocking wording improvements.

    Why

    Tools can consume fields while documentation can improve diagnostic wording.

    Changed rules One JSON format selector →

    Topaz help opens command help

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A script can accidentally omit the command name. If that prints help successfully, it is hard to tell whether the intended work ran.

    Decision

    Request help with topaz help. Running without a command is a usage error.

    Examples

    Reject an invocation without a command

    main.tpzReject an invocation without a command
    1. let value = 1
    Expected outputExit code 1
    No stdout.
    $ topaz
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    Alternatives considered

    • Show help when the command is omitted. A missing command would look like an intentional help request.
    • Keep both a bare invocation and topaz help as help. Help would have two entry points, and a missing command would pass as success.

    Why

    Help requests are distinct from missing arguments.

    Changed rules Name the help command →

    Vendor brings dependency sources into the project

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    Two command names could fetch dependency sources in the same way. Users had to determine whether the commands behaved differently.

    Decision

    Use vendor and remove fetch, which performed the same operation.

    Alternatives considered

    • Keep both commands. One operation would still need two names and help entries.

    Why

    Scripts use one recognizable command for bringing in dependency sources.

    Changed rules One registry materialization command →

    Dependency declarations use tables

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A dependency written as a string might need a format conversion before adding a field. Tool-generated files can avoid that difference as well.

    Decision

    Write dependency declarations as tables. init and add also generate tables.

    Alternatives considered

    • Support both version strings and tables. The same dependency could have two structures.

    Why

    Dependency attributes use a consistent structure across manifests.

    Changed rules Dependency declarations use tables →