CLI는 단일 파일과 패키지에 같은 구문 분석·모듈 해석·타입 검사를 적용하고, 요청한 작업만 다르게 실행합니다.
기본 규칙
check는 검사, run은 해석기 실행, test는 테스트 호스트 실행, emit은 Rust 소스 출력, build는 네이티브·web·web-worker·web-app·Python 산출물 생성을 담당합니다. dev는 패키지 모드 web-app만 루프백에서 제공하고 다시 빌드합니다. doc, fmt, LSP, 마이그레이션 명령도 같은 프로그램 해석 규칙을 공유합니다. Topaz 5.7.0 공개 CLI에는 web-app 대상과 dev 명령이 포함됩니다.
사용 방법
빠른 피드백은 check, 기준 실행 결과는 run, 배포 산출물은 build를 사용하세요. --root는 모듈과 패키지의 기준 경로를 지정하고, --locked는 잠금 파일이 매니페스트와 다르면 컴파일 전에 멈춥니다. --format json은 도구가 읽기 쉬운 진단을 출력합니다.
topaz fmt --check는 topaz fmt와 같은 파싱 기반 포맷터와 패키지 파일 선택 규칙을 사용합니다. 다만 소스나 메타데이터를 쓰지 않고 포맷이 다른 모든 경로를 알린 뒤 실패 상태로 끝납니다. 패키지 모드에서는 vendored 의존성과 빌드 산출물을 건너뜁니다.
Topaz 5.6.4에서는 정본 topaz-5.7 언어 위에 check --profile agent-pack을 적용해 에이전트가 작성한 소스 형식의 범위를 실행 전에 검사할 수 있습니다. 언어 자체는 허용하지만 agent-pack이 제외한 형식도 이 단계에서 거부합니다. JSON 모드에서는 stderr에 프로필·규칙·소스 범위와, 식별자 교정이 명확할 때만 자동 적용 가능한 수정 정보를 담은 topaz.profile-diagnostic/v1 JSONL을 출력하고, stdout에는 topaz.profile-check/v1 요약 하나만 출력합니다. test-profile은 테스트 전용 정본 assert(...) 함수만 명시적으로 허용합니다. 코드 펜스 라벨·예제의 자족성·SPEC 인용은 pack 또는 문서 리뷰에서 계속 확인해야 하며, 번역·메타데이터·서술 규칙을 다루는 public-docs도 컴파일러 옵션이 아니라 문서 검사로 유지됩니다.
현재 지원
현재 공개된 5.7.0 CLI는 파일과 패키지 모드, 사람용·JSON 진단, 언어와 프로필 선택, 오류 코드 설명, 프로그램 인수 전달을 지원합니다. 정적 오류는 실행과 산출물 생성 전에 보고됩니다.
제한 사항
진단 출력은 소스 위치, 안정적인 오류 코드, 요약, 필요한 세부 정보를 포함합니다. 호스트 컴파일러의 오류는 Topaz 진단을 대신하지 않고 부가 정보로만 표시됩니다. 실패한 검사·실행·빌드는 0이 아닌 종료 코드를 반환합니다.
명령 예시
topaz check --root . src/main.tpz
topaz check --format json src/main.tpz
topaz check --profile agent-pack --format json src/main.tpz
topaz fmt --check --root .
topaz explain TPZ5021 --json
topaz test --root . src/main.tpz -- arg1