Перейти к содержимому
Топаздокументация

Поиск в документации

Спецификация 6.0

Выберите результат стрелками и нажмите Enter, чтобы открыть его.

Введите имя API, номер диагностики, правило или тему проекта.

    Загрузка →

    Проектные решения

    Инструменты

    Ошибка отложенной работы приводит к сбою всей команды

    Принято 8 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Основное выполнение может закончиться прежде, чем отложенная работа получит ошибку выполнения или хоста. Код, который проверяет лишь итоговый статус, тоже должен узнать об этой ошибке.

    Решение

    Ошибка выполнения или хоста в отложенной работе завершает всю команду неудачей. test-ok не выдаётся.

    Рассмотренные варианты

    • Считать итогом успешное завершение основной работы. Успешный статус скрыл бы последующую ошибку.

    Причина

    Инструмент, проверяющий результат команды, увидит ошибку отложенной работы.

    Изменённые правила Test completion and failure reporting →

    Проверки в тестах вычисляют аргументы один раз и точно сравнивают эталон

    Принято 7 ноября 2026 г. · 6.0.0 · Проверяется

    Проблема

    Вычисление аргумента может иметь побочный эффект, а в эталоне важен даже последний перевод строки. Нужно определить поведение после сбоя проверки и при расхождении файла.

    Решение

    • Аргументы вычисляются один раз слева направо. Используются обычные сравнения и извлечение внешнего конструктора.
    • Ошибка проверки TPZ4007 останавливает текущий тест во время выполнения.
    • Существующий эталонный файл UTF-8 сравнивается точно. Файл не создаётся и не обновляется.

    Примеры

    Equality returns unit and execution continues

    assert-eq.tpzEquality returns unit and execution continuesОткрыть песочницу →
    1. import std.io
    2. import std.test
    3. let result: () = test.assertEq([1, 2], [1, 2])
    4. io.writeLine("{result}")
    Ожидаемый выводКод завершения 0
    ()
    
    $ topaz run assert-eq.tpz --language-version 6.0
    Ожидаемый результат

    Ожидаемый результат

    Выполнение завершается. Код завершения 0.

    Ожидаемый стандартный вывод
    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")
    Ожидаемый выводКод завершения 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
    Ожидаемый результат

    Ожидаемый результат

    Выполнение завершается. Код завершения 0.

    Ожидаемый стандартный вывод
    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")
    Ожидаемый выводНенулевой код завершения
    before
    
    $ topaz run main.tpz --language-version 6.0
    expected.txtFail when the final newline is missing from actual text
    1. line
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения run. Ненулевой код завершения.

    • TPZ4007 →

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

    Ожидаемый стандартный вывод
    1. before

    Fail instead of creating a missing golden file

    main.tpzFail instead of creating a missing golden fileОткрыть песочницу →
    1. import std.test
    2. import std.io
    3. io.writeLine("before")
    4. test.assertGolden("missing.txt", "new text")
    5. io.writeLine("after")
    Ожидаемый выводНенулевой код завершения
    before
    
    $ topaz run main.tpz --language-version 6.0
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения run. Ненулевой код завершения.

    • TPZ4007 →

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

    Ожидаемый стандартный вывод
    1. before

    Fail assertOk with the rendered error

    main.tpzFail assertOk with the rendered errorОткрыть песочницу →
    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")
    Ожидаемый выводНенулевой код завершения
    before
    
    $ topaz run main.tpz --language-version 6.0
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения run. Ненулевой код завершения.

    Ожидаемый стандартный вывод
    1. before

    Причина

    Сбой останавливает тест, а повторное сравнение использует тот же эталон.

    Изменённые правила Equality assertions →Compare existing golden text without updating it →Assert a Result constructor and return its payload →Assert presence or absence →

    Очистка хранилища сохраняет рабочие области, которые могут использоваться

    Принято 8 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Старая рабочая область ещё может принадлежать выполняющейся задаче. Владелец или его состояние также могут измениться между просмотром и удалением.

    Решение

    • Область сохраняется независимо от возраста, если владелец активен или его состояние неизвестно.
    • Просмотр статуса и очистка используют одну классификацию. Владелец и его активность проверяются непосредственно перед удалением.

    Рассмотренные варианты

    • Удалять только по возрасту. Старая рабочая область может всё ещё использоваться.

    Причина

    Очистка сохраняет файлы активной задачи и области с неопределённым состоянием владельца.

    Изменённые правила Command behavior →Command behavior →

    Параметры команд без эффекта удаляются

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Сценарий с --types выглядит так, будто запрашивает дополнительную работу. Если параметр ничего не делает, реальное поведение команды трудно прочитать.

    Решение

    Параметры без эффекта, включая --types, удаляются.

    Примеры

    Reject the unused types option

    main.tpzReject the unused types option
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format json --types
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Check with the canonical command

    main.tpzCheck with the canonical commandОткрыть песочницу →
    1. let value = 1
    Ожидаемый выводКод завершения 0
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format json
    Ожидаемый результат

    Ожидаемый результат

    Проверка принимает программу. Код завершения 0.

    Рассмотренные варианты

    • По-прежнему принимать флаги без эффекта. Читатели могли бы решить, что флаг меняет поведение.

    Причина

    Параметр в командной строке обозначает реальную настройку.

    Изменённые правила Type checking without a mode flag →

    Версия выводится командой topaz version

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Вывод версии и подробности могли запрашиваться несколькими способами. В справке и сценариях для одной операции могли встречаться разные названия.

    Решение

    • Запускайте topaz version для вывода версии.
    • Для подробного вывода используйте --verbose. Псевдонимы обеих операций удаляются.

    Примеры

    Reject the version flag alias

    main.tpzReject the version flag alias
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz --version
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Reject the short version alias

    main.tpzReject the short version alias
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz -V
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Reject the short detail alias

    main.tpzReject the short detail alias
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz version -v
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Request the detailed release report

    main.tpzRequest the detailed release report
    1. let value = 1
    Ожидаемый выводКод завершения 0
    $ topaz version --verbose
    Ожидаемый результат

    Ожидаемый результат

    Проверка принимает программу. Код завершения 0.

    Рассмотренные варианты

    • Сохранить прежние псевдонимы. Для одного действия по-прежнему пришлось бы знать несколько названий.

    Причина

    Запись из справки можно использовать прямо в сценариях.

    Изменённые правила Named metadata commands and long options →

    Значение параметра передаётся отдельным аргументом

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Слитная и раздельная запись дают две формы одной команды. Код, собирающий массив аргументов, может использовать одно правило.

    Решение

    Значение передаётся следующим аргументом. Форма --flag=value отклоняется.

    Примеры

    Reject an equals format value

    main.tpzReject an equals format value
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format=json
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Pass values as separate arguments

    main.tpzPass values as separate argumentsОткрыть песочницу →
    1. let value = 1
    Ожидаемый выводКод завершения 0
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format json
    Ожидаемый результат

    Ожидаемый результат

    Проверка принимает программу. Код завершения 0.

    Рассмотренные варианты

    • Принимать слитную и раздельную запись. У значения одного параметра будут две формы.

    Причина

    В списке аргументов видна граница между параметром и значением.

    Изменённые правила Separate option values →

    Параметр команды указывается не более одного раза

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    При сборке аргументов из нескольких частей сценарий может повторить параметр. Если принять оба, трудно понять, какое значение использовалось.

    Решение

    Повтор параметра отклоняется даже при совпадающих значениях.

    Примеры

    Reject a repeated language selector

    main.tpzReject a repeated language selector
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz check main.tpz --format json --language-version 6.0 --language-version 6.0
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Reject conflicting formats in one order

    main.tpzReject conflicting formats in one order
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format json --format human
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Reject conflicting formats in the other order

    main.tpzReject conflicting formats in the other order
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format human --format json
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Give each option once

    main.tpzGive each option onceОткрыть песочницу →
    1. let value = 1
    Ожидаемый выводКод завершения 0
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format json
    Ожидаемый результат

    Ожидаемый результат

    Проверка принимает программу. Код завершения 0.

    Рассмотренные варианты

    • Использовать последнее значение. Порядок сборки аргументов мог бы незаметно изменить поведение команды.

    Причина

    Повтор виден там, где он появился в команде.

    Изменённые правила One occurrence of each option →

    Команды выбирают вывод JSON одним параметром

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Сценарий может читать вывод нескольких команд. Разные флаги для одного формата усложнили бы такой сценарий.

    Решение

    Для команд с выводом JSON используйте --format json. Флаг --json удалён.

    Примеры

    Keep the check diagnostic format

    main.tpzKeep the check diagnostic formatОткрыть песочницу →
    1. let value = 1
    Ожидаемый выводКод завершения 0
    Нет стандартного вывода.
    $ topaz check main.tpz --language-version 6.0 --format json
    Ожидаемый результат

    Ожидаемый результат

    Проверка принимает программу. Код завершения 0.

    Рассмотренные варианты

    • Оставить отдельные флаги у каждой команды. Для одного формата пришлось бы запоминать разные команды выбора.

    Причина

    Сценарии одинаково выбирают формат у разных команд.

    Изменённые правила One JSON format selector →

    В диагностике JSON стабильны код и смысл основной позиции

    Принято 7 ноября 2026 г. · 6.0.0 · Проверяется

    Проблема

    Инструмент читает код и позицию, чтобы перейти к ошибочному выражению. Текст сообщения можно улучшать, сохраняя место подсветки.

    Решение

    • Контракт --format json задаёт структурированную идентичность, обязательные поля и типы, единицы координат, серьёзность и причину, указанную основной позицией.
    • Текст сообщения и метки можно менять. Для изменения идентичности или обещанной позиции нужны версия контракта и инструкция переноса. Удалённые идентификаторы не используются повторно.

    Рассмотренные варианты

    • Исключить смысл позиции из стабильного контракта. Смена подсвечиваемой причины могла бы остаться незаметной.
    • Сделать стабильными также текст сообщений и порядок дополнительных пояснений. Контракт должен ловить неверные причины и позиции, не мешая улучшать формулировки.

    Причина

    Инструменты читают поля, пока формулировки диагностики улучшаются.

    Изменённые правила One JSON format selector →

    Topaz help открывает справку по командам

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Сценарий может случайно пропустить имя команды. Если при этом успешно выводится справка, трудно понять, была ли выполнена задуманная работа.

    Решение

    Запрашивайте справку через topaz help. Запуск без команды считается ошибкой использования.

    Примеры

    Reject an invocation without a command

    main.tpzReject an invocation without a command
    1. let value = 1
    Ожидаемый выводКод завершения 1
    Нет стандартного вывода.
    $ topaz
    Ожидаемый результат

    Ожидаемый результат

    Этап отклонения command. Код завершения 1.

    Рассмотренные варианты

    • Показывать справку при отсутствии команды. Случайный пропуск команды будет выглядеть как запрос справки.
    • Оставить справкой и запуск без команды, и topaz help. У справки было бы два входа, а пропущенная команда выглядела бы как успех.

    Причина

    Запрос справки отличается от пропущенного аргумента.

    Изменённые правила Name the help command →

    Vendor помещает исходники зависимостей в проект

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Две команды могли одинаково получать исходники зависимостей. Пользователю приходилось выяснять, есть ли между ними различие.

    Решение

    Используйте vendor. Команда fetch с тем же действием удаляется.

    Рассмотренные варианты

    • Сохранить обе команды. У одной операции останутся два названия и две записи справки.

    Причина

    В сценариях получение исходников видно по одной команде.

    Изменённые правила One registry materialization command →

    Зависимости объявляются таблицами

    Принято 7 ноября 2026 г. · 6.0.0 · В работе

    Проблема

    Зависимость в виде строки может потребовать смены формата при добавлении поля. Создаваемые инструментами файлы тоже могут использовать одну структуру.

    Решение

    Объявляйте зависимости таблицами. init и add также создают таблицы.

    Рассмотренные варианты

    • Принимать и строки версий, и таблицы. У одной зависимости могли бы быть две структуры.

    Причина

    Поля зависимостей устроены одинаково в разных файлах.

    Изменённые правила Dependency declarations use tables →