CLI는 단일 파일과 패키지에 같은 구문 분석·모듈 해석·타입 검사를 적용하고, 요청한 작업만 다르게 실행합니다.
기본 규칙
check는 검사, run은 해석기 실행, test는 테스트 호스트 실행, emit은 Rust 소스 출력, build는 네이티브·web·web-worker·web-app·http-service·Python 산출물 생성을 담당합니다. dev는 패키지 모드 web-app 또는 제한형 HTTP 서비스를 루프백에서 실행합니다. doc, fmt, LSP와 패키지 명령도 같은 프로그램 해석 규칙을 공유합니다.
사용 방법
빠른 피드백은 check, 기준 실행 결과는 run, 배포 산출물은 build를 사용하세요. --root는 모듈과 패키지의 기준 경로를 지정하고, --locked는 잠금 파일이 매니페스트와 다르면 컴파일 전에 멈춥니다. --format json은 도구가 읽기 쉬운 진단을 출력합니다.
topaz fmt --check는 topaz fmt와 같은 파싱 기반 포맷터와 패키지 파일 선택 규칙을 사용합니다. 다만 소스나 메타데이터를 쓰지 않고 포맷이 다른 모든 경로를 알린 뒤 실패 상태로 끝납니다. 패키지 모드에서는 vendored 의존성과 빌드 산출물을 건너뜁니다.
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도 컴파일러 옵션이 아니라 문서 검사로 유지됩니다.
검사형 emit과 build --backend native는 --native-report-json <경로>를 지원합니다. 이 보고서는 전체 유닛 또는 함수별 선택을 설명할 뿐 stdout, stderr와 생성 산출물을 바꾸지 않습니다. 잘못되었거나 산출물과 충돌하는 경로는 출력 디렉터리를 수정하기 전에 거부하며, 낮추기가 성공한 뒤에만 JSON을 원자적으로 게시합니다.
함수별 결정에는 정확한 Bytes·ByteBuffer 고속 경로와 검사기가 증명한 직접 바이너리 레코드 필드도 포함됩니다. 더 넓거나 증명되지 않은 복합 값은 안정적인 거부 이유와 함께 boxed로 남습니다.
현재 지원
현재 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 emit src/main.tpz --backend native --native-report-json native-report.json
topaz fmt --check --root .
topaz explain TPZ5021 --json
topaz test --root . src/main.tpz -- arg1