기반·도구

KatanA AST Lint

KatanA 시리즈의 AST 기반 규칙을 검사하는 lint 기반입니다. Rustc를 대체하는 컴파일러가 아닙니다.

KatanA 시리즈의 Rust 코드 품질과 구조 규칙을 유지하는 개발자

01

구현된 기능

AST를 이용한 규칙 검사

근거

아키텍처와 금지 타입 등의 규칙 구현

근거

CI와 개발 시 검사에 통합할 수 있는 구성

근거

02

시작하기

  1. 대상 Rust 워크스페이스와 적용할 규칙을 확인합니다.
  2. 기존 KatanA lint 경로로 검사하고 지적 사항을 코드에서 수정합니다.

Rust와 필요한 개발 도구를 준비하고, 도입 전에 링크된 README에서 환경 요구 사항을 확인하세요. 실행 예시는 기능의 시작점이며 모든 환경에서의 동작을 보장하지 않습니다.

근거
sh
cargo install katana-ast-lint
kal check
kal check --json

01 / KAL

사용 장면

Rust repository의 integration gate

KatanaAstLint::from_workspace().assert_clean()을 integration test에서 호출해 공유 Rust AST rule set을 repository 품질 gate에 포함합니다. source roots나 예외는 각 repository 측에 남겨 둘 수 있습니다.

CI에서 표준 AST rule 실행

kal check는 workspace root를 해결하고 kal.json이 있으면 읽어 표준 rule을 실행합니다. --json 또는 --text로 reporter mode를 선택하고 위반·설정 오류·system error를 exit status로 구분할 수 있습니다.

02 / KAL

입력부터 출력까지

  1. workspace와 설정 해결하기

    try_from_workspace는 current directory에서 Cargo workspace root를 찾고 root의 설정을 읽습니다. 설정이 잘못되었거나 읽을 수 없으면 KalRunError로 반환합니다.

  2. source roots에 rule 적용하기

    lint_all이 rule catalog를 순서대로 확인하고 설정된 source roots 또는 rule inputs에 AST rule을 적용합니다. rule별 violations를 수집해 rule ID 순으로 안정화한 뒤 반환합니다.

  3. report와 exit status 사용하기

    try_assert_clean은 위반을 reporter로 전달하고 CLI는 violation이면 exit 1, configuration 또는 system error면 exit 2로 종료합니다. integration test에서는 assert_clean이 실패를 panic으로 전달합니다.

03 / KAL

주요 API·CLI

KatanaAstLint::try_from_workspace — workspace 초기화
current directory에서 workspace root와 설정을 해결해 Result<KatanaAstLint, KalRunError>를 반환합니다. CLI나 test harness가 초기화 실패를 분류해 처리할 수 있습니다.
KatanaAstLint::from_workspace — 간편 초기화
workspace 초기화를 간결하게 쓰는 panic-on-error 진입점입니다. README의 integration test 예처럼 설정 불가를 test failure로 다루려 할 때 사용합니다.
violations — 규칙 위반 목록
모든 rule 결과를 모아 rule ID 순으로 정렬한 Vec<Violation>을 반환합니다. reporter를 거치지 않고 test나 독자 집계에서 위반 데이터를 직접 검사할 수 있습니다.
kal check --json / --text — 결과 보고
CLI의 check는 --json 또는 --text를 받아 표준 rule set 결과를 선택한 형식으로 출력합니다. 알 수 없는 option이나 설정 실패는 위반과 별개의 exit 2가 됩니다.

04 / KAL

구체적인 예

integration test에서 repository 전체 검사

README의 integration test 예는 KatanaAstLint::from_workspace()로 workspace 설정을 읽고 assert_clean()으로 표준 rule 전체를 실행합니다. 공유 runner를 repository 고유 test에 포함하려 할 때의 최소 예입니다.

rust
#[test]
fn repository_ast_lint() {
    katana_ast_lint::KatanaAstLint::from_workspace().assert_clean();
}

05 / KAL

통합 조건과 책임 경계

kal.json을 repository 경계에 두기

kal.json에서 source roots, rule severity, rule enablement, repository-specific inputs를 지정합니다. 공유 rule 구현을 바꾸지 않고 각 repository의 대상 범위와 허용 설정만 로컬에 보관할 수 있습니다.

기존 Rust lint와 함께 사용하기

KAL은 공유 AST rule boundary이며 Clippy, Dylint, ast-grep, Semgrep의 대체품이 아닙니다. Rust compiler lint나 검색 기반 검사를 바꾸지 않고 KatanA 공통 구조 규칙을 추가하는 책임으로 도입합니다.

근거

조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.

저장소읽기 안내f1d75d87d151
근거 · KAL
모든 제품