본문으로 건너뛰기
토파즈문서

문서 검색

명세 6.0

방향키로 결과를 고르고 Enter를 눌러 여세요.

API 이름, 진단 번호, 규칙 또는 프로젝트 주제를 입력하세요.

    다운로드 →

    설계 결정

    도구

    지연 작업이 실패하면 명령도 실패합니다

    2026년 11월 8일 채택 · 6.0.0 · 구현 중

    문제

    주 실행은 끝났지만 나중에 수행되는 작업에서 실행 오류나 호스트 오류가 날 수 있습니다. 종료 상태만 보는 호출자도 이 실패를 알아야 합니다.

    결정

    지연 작업의 실행 오류나 호스트 오류는 전체 실행을 실패시키며 test-ok를 보고하지 않습니다.

    검토한 대안

    • 주 실행의 성공을 최종 결과로 보고한다. 그 뒤에 발생한 실패가 성공 신호에 가려집니다.

    이유

    명령의 결과를 확인하는 도구도 지연 작업의 실패를 알아차릴 수 있습니다.

    바뀐 규칙 Test completion and failure reporting →

    테스트 단언은 한 번 평가하고 기준 파일을 정확히 비교합니다

    2026년 11월 7일 채택 · 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")
    기대 출력0이 아닌 종료 코드
    before
    
    $ topaz run main.tpz --language-version 6.0
    expected.txtFail when the final newline is missing from actual text
    1. line
    기대 결과

    기대 결과

    거절 단계 run. 종료 코드가 0이 아닙니다.

    • 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")
    기대 출력0이 아닌 종료 코드
    before
    
    $ topaz run main.tpz --language-version 6.0
    기대 결과

    기대 결과

    거절 단계 run. 종료 코드가 0이 아닙니다.

    • 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")
    기대 출력0이 아닌 종료 코드
    before
    
    $ topaz run main.tpz --language-version 6.0
    기대 결과

    기대 결과

    거절 단계 run. 종료 코드가 0이 아닙니다.

    기대 표준 출력
    1. before

    이유

    실패가 단언 위치에서 드러나고 기존 기준 파일을 그대로 두고 다시 검사할 수 있습니다.

    바뀐 규칙 Equality assertions →Compare existing golden text without updating it →Assert a Result constructor and return its payload →Assert presence or absence →

    저장소 정리는 사용 중일 수 있는 작업 공간을 보존합니다

    2026년 11월 8일 채택 · 6.0.0 · 구현 중

    문제

    오래된 작업 공간도 아직 실행 중인 작업이 사용하고 있을 수 있습니다. 상태를 본 뒤 삭제하기 전에도 소유자의 상태는 바뀔 수 있습니다.

    결정

    • 소유자가 살아 있거나 확실히 판단할 수 없으면 작업 공간의 나이와 관계없이 보존합니다.
    • 상태 조회와 정리에 같은 분류를 쓰고 삭제 직전에 소유권과 생존 여부를 다시 확인합니다.

    검토한 대안

    • 경과 시간만으로 삭제한다. 오래 실행되는 작업의 공간도 삭제할 수 있습니다.

    이유

    정리할 때 실행 중이거나 소유 상태가 불확실한 작업의 파일을 보존합니다.

    바뀐 규칙 Command behavior →Command behavior →

    동작이 없는 명령 옵션을 없앱니다

    2026년 11월 7일 채택 · 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으로 확인합니다

    2026년 11월 7일 채택 · 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 →

    명령의 옵션 값은 별도 인자로 줍니다

    2026년 11월 7일 채택 · 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 →

    같은 명령 옵션은 한 번만 줍니다

    2026년 11월 7일 채택 · 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 출력은 --format json으로 고릅니다

    2026년 11월 7일 채택 · 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 진단은 코드와 원인 위치를 안정적으로 제공합니다

    2026년 11월 7일 채택 · 6.0.0 · 확인 중

    문제

    도구는 진단의 코드와 위치를 읽어 잘못된 식으로 이동합니다. 사람이 읽는 문구가 바뀌어도 같은 원인을 표시할 수 있어야 합니다.

    결정

    • --format json은 구조화된 진단 정체성, 필수 필드와 타입, 좌표 단위, 심각도, 주 위치가 가리키는 원인을 계약으로 둡니다.
    • 메시지와 라벨 문구는 다듬을 수 있습니다. 정체성과 약속한 위치 의미를 바꾸려면 계약 판과 이전 안내가 필요합니다. 폐기한 코드는 재사용하지 않습니다.

    검토한 대안

    • 위치의 뜻을 안정 계약에서 뺀다. 같은 진단을 받은 도구가 다른 원인 위치로 이동해도 회귀를 알기 어렵습니다.
    • 설명 문구와 보조 설명의 순서까지 안정 계약으로 둔다. 잘못된 원인과 위치를 회귀로 잡되 문구 개선은 막지 않아야 합니다.

    이유

    도구는 구조화된 필드를 읽고 진단 문구는 사용자가 이해하기 쉽게 개선할 수 있습니다.

    바뀐 규칙 One JSON format selector →

    도움말은 topaz help로 엽니다

    2026년 11월 7일 채택 · 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입니다

    2026년 11월 7일 채택 · 6.0.0 · 구현 중

    문제

    의존성 소스를 같은 방식으로 가져오는 명령이 두 이름으로 나뉘어 있었습니다. 둘 사이에 동작 차이가 있는지 알아봐야 했습니다.

    결정

    vendor를 쓰고 같은 동작을 하는 fetch는 없앱니다.

    검토한 대안

    • 두 명령을 모두 유지한다. 같은 동작을 두 이름으로 설명해야 합니다.

    이유

    의존성 소스를 가져오는 단계를 스크립트에서 한 이름으로 찾을 수 있습니다.

    바뀐 규칙 One registry materialization command →

    의존성 선언은 테이블로 씁니다

    2026년 11월 7일 채택 · 6.0.0 · 구현 중

    문제

    의존성을 문자열과 테이블로 쓸 수 있으면 새 필드를 넣을 때 먼저 형식을 바꿔야 할 수 있습니다. 도구가 만든 파일도 같은 구조를 쓰는 편이 읽기 쉽습니다.

    결정

    의존성 선언은 테이블로 씁니다. init과 add가 만드는 의존성도 테이블입니다.

    검토한 대안

    • 버전 문자열과 테이블을 둘 다 허용한다. 같은 의존성이 서로 다른 구조로 표현됩니다.

    이유

    의존성의 속성이 파일마다 같은 구조에 있습니다.

    바뀐 규칙 Dependency declarations use tables →