지연 작업이 실패하면 명령도 실패합니다
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
run · runtime · 검증 · 미실행
assert-eq.tpzEquality returns unit and execution continues플레이그라운드 열기 →import std.ioimport std.testlet result: () = test.assertEq([1, 2], [1, 2])io.writeLine("{result}")
기대 결과
기대 결과
실행을 마칩니다. 종료 코드 0.
표준 오류 출력 없음.
기대 표준 출력이 예제는 아직 실행하지 않았습니다.
Match exact line endings and an empty golden file
run · running · 검증 · 미실행
main.tpzMatch exact line endings and an empty golden fileimport std.testimport std.iotest.assertGolden("expected.txt", "alpha\r\nβ\n")test.assertGolden("empty.txt", "")io.writeLine("golden text matched")
기대 출력종료 코드 0
golden text matched
expected.txtMatch exact line endings and an empty golden file empty.txtMatch exact line endings and an empty golden file 기대 결과
기대 결과
실행을 마칩니다. 종료 코드 0.
표준 오류 출력 없음.
기대 표준 출력이 예제는 아직 실행하지 않았습니다.
Fail when the final newline is missing from actual text
run · running · 검증 · 미실행
main.tpzFail when the final newline is missing from actual textimport std.testimport std.ioio.writeLine("before")test.assertGolden("expected.txt", "line")io.writeLine("after")
expected.txtFail when the final newline is missing from actual text 기대 결과
기대 결과
거절 단계 run. 종료 코드가 0이 아닙니다.
기대 표준 출력이 예제는 아직 실행하지 않았습니다.
Fail instead of creating a missing golden file
run · running · 검증 · 미실행
main.tpzFail instead of creating a missing golden file플레이그라운드 열기 →import std.testimport std.ioio.writeLine("before")test.assertGolden("missing.txt", "new text")io.writeLine("after")
기대 결과
기대 결과
거절 단계 run. 종료 코드가 0이 아닙니다.
기대 표준 출력이 예제는 아직 실행하지 않았습니다.
Fail assertOk with the rendered error
run · running · 검증 · 미실행
main.tpzFail assertOk with the rendered error플레이그라운드 열기 →import std.testimport std.iolet value: Result<int, string> = Err("bad")io.writeLine("before")test.assertOk(value)io.writeLine("after")
기대 결과
기대 결과
거절 단계 run. 종료 코드가 0이 아닙니다.
기대 표준 출력이 예제는 아직 실행하지 않았습니다.
이유
실패가 단언 위치에서 드러나고 기존 기준 파일을 그대로 두고 다시 검사할 수 있습니다.
바뀐 규칙 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 · command-validation · 검증 · 미실행
main.tpzReject the unused types option 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
check · command-validation · 검증 · 미실행
기대 결과
기대 결과
검사가 프로그램을 받아들입니다. 종료 코드 0.
표준 오류 출력 없음.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
검토한 대안
- 동작이 없는 플래그도 계속 받는다. 옵션이 무엇을 바꾸는지 확인하기 전에는 명령을 오해할 수 있습니다.
이유
명령에 남은 옵션은 실제 동작과 연결됩니다.
바뀐 규칙 Type checking without a mode flag →
판 번호는 topaz version으로 확인합니다
2026년 11월 7일 채택 · 6.0.0 · 구현 중
문제
판 번호 확인이나 자세한 출력을 여러 철자로 쓸 수 있었습니다. 문서와 스크립트에서 같은 명령을 찾아도 다른 이름으로 나타날 수 있습니다.
결정
- 판 번호 조회는
topaz version을 씁니다. - 자세한 출력은
--verbose를 씁니다. 두 동작의 별칭은 제거합니다.
예제
reject · command-validation · 검증 · 미실행
main.tpzReject the version flag alias 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
reject · command-validation · 검증 · 미실행
main.tpzReject the short version alias 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
reject · command-validation · 검증 · 미실행
main.tpzReject the short detail alias 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
check · command-validation · 검증 · 미실행
main.tpzRequest the detailed release report 기대 결과
기대 결과
검사가 프로그램을 받아들입니다. 종료 코드 0.
표준 오류 출력 없음.
이 예제는 아직 실행하지 않았습니다.
검토한 대안
- 기존 별칭도 유지한다. 같은 명령과 옵션을 여러 이름으로 찾아야 합니다.
이유
도움말에서 고른 철자를 스크립트에서도 그대로 씁니다.
바뀐 규칙 Named metadata commands and long options →
명령의 옵션 값은 별도 인자로 줍니다
2026년 11월 7일 채택 · 6.0.0 · 구현 중
문제
옵션과 값을 붙이거나 떼어 쓰면 같은 명령의 호출 형태가 달라집니다. 명령을 배열로 구성하는 코드도 한 규칙을 쓰면 됩니다.
결정
값이 필요한 옵션에는 다음 인자로 값을 줍니다. --flag=value 형태는 받지 않습니다.
예제
reject · command-validation · 검증 · 미실행
main.tpzReject an equals format value 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
check · command-validation · 검증 · 미실행
기대 결과
기대 결과
검사가 프로그램을 받아들입니다. 종료 코드 0.
표준 오류 출력 없음.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
검토한 대안
- 붙여 쓰기와 별도 인자를 모두 받는다. 같은 옵션 값을 두 형태로 전달하게 됩니다.
이유
인자 목록에서 옵션과 값의 경계를 볼 수 있습니다.
바뀐 규칙 Separate option values →
같은 명령 옵션은 한 번만 줍니다
2026년 11월 7일 채택 · 6.0.0 · 구현 중
문제
스크립트 여러 곳에서 인자를 모으면 같은 옵션이 두 번 들어갈 수 있습니다. 둘 다 읽을 때 어떤 값이 쓰였는지 추적하기 어렵습니다.
결정
같은 옵션을 두 번 주면 값이 같아도 거절합니다.
예제
reject · command-validation · 검증 · 미실행
main.tpzReject a repeated language selector 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
reject · command-validation · 검증 · 미실행
main.tpzReject conflicting formats in one order 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
reject · command-validation · 검증 · 미실행
main.tpzReject conflicting formats in the other order 기대 결과
기대 결과
거절 단계 command. 종료 코드 1.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
check · command-validation · 검증 · 미실행
기대 결과
기대 결과
검사가 프로그램을 받아들입니다. 종료 코드 0.
표준 오류 출력 없음.
표준 출력 없음.
이 예제는 아직 실행하지 않았습니다.
검토한 대안
- 마지막 값을 사용한다. 인자를 합치는 순서가 명령의 동작을 조용히 바꿀 수 있습니다.
이유
중복이 생긴 명령에서 바로 문제를 찾을 수 있습니다.
바뀐 규칙 One occurrence of each option →
2026년 11월 7일 채택 · 6.0.0 · 구현 중
문제
여러 명령의 출력을 스크립트에서 읽다 보면 명령마다 다른 플래그를 알아야 할 수 있습니다. 같은 형식을 요청하는 이름을 하나로 맞춥니다.
결정
JSON을 출력하는 명령에는 --format json을 씁니다. --json는 없앱니다.
예제
check · command-validation · 검증 · 미실행
기대 결과
기대 결과
검사가 프로그램을 받아들입니다. 종료 코드 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 · command-validation · 검증 · 미실행
main.tpzReject an invocation without a command 기대 결과
기대 결과
거절 단계 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 →