基礎與工具

KatanA AST Lint

用於檢查 KatanA 系列 AST 規則的 lint 基礎,不是 Rustc 的替代編譯器。

維護 KatanA 系列 Rust 程式碼品質與結構規則的開發者

01

已實作功能

使用 AST 進行規則檢查

依據

實作架構和禁止型別等規則

依據

可整合到 CI 與開發時檢查

依據

02

開始使用

  1. 確認目標 Rust workspace 與要套用的規則。
  2. 透過 KatanA 現有 lint 流程執行檢查,並在程式碼中修正問題。

請準備 Rust 與必要的開發工具,並在導入前透過連結的 README 確認環境需求。執行範例是功能入口,不保證在所有環境中運作。

依據
sh
cargo install katana-ast-lint
kal check
kal check --json

01 / KAL

使用情境

Rust 儲存庫整合門

從整合測試中呼叫 KatanaAstLint::from_workspace().assert_clean() 將共享 Rust AST 規則集合併到儲存庫的質量門中。源根和異常可以保留在每個儲存庫中。

從 CI 執行標準 AST 規則

kal check 解析工作區根目錄,讀取 kal.json(如果存在),並執行標準規則。您可以使用 --json 或 --text 選擇報告器模式,並通過退出狀態區分違規、配置錯誤和系統錯誤。

02 / KAL

從輸入到輸出的流程

  1. 解決工作區和設定

    try_from_workspace 在當前目錄中搜索 Cargo 工作空間根目錄並讀取根目錄的配置。如果設定無效或不可讀,則返回 KalRunError。

  2. 將規則應用於源根

    lint_all 遍歷規則目錄並將 AST 規則應用於配置的源根或規則輸入。收集每條規則的違規行為,穩定它們並按規則 ID 的順序返回它們。

  3. 使用報告和退出狀態

    try_assert_clean 將違規傳遞給報告者,CLI 對於違規則退出 1,對於配置或系統錯誤則退出 2。對於整合測試,您可以使用assert_clean 將失敗視為恐慌。

03 / KAL

主要 API 與 CLI

KatanaAstLint::try_from_workspace — 可回傳錯誤的初始化
從當前目錄解析工作區根目錄和設定並返回 Result<KatanaAstLint, KalRunError>。 CLI 和測試工具可以對初始化失敗進行分類和處理。
KatanaAstLint::from_workspace — 工作區初始化
這是一個錯誤恐慌入口點,用於簡潔地編寫工作區初始化。當您想要將不可配置性視為測試失敗時,請使用此選項,如 README 中的整合測試示例所示。
violations — 違規資料
收集所有規則的結果並返回按規則 ID 排序的 Vec<Violation>。違規資料可以通過測試和獨立彙總直接檢查,無需通過報告者。
kal check --json / --text — 命令列輸出
CLI 檢查接受 --json 或 --text 並以您選擇的格式輸出標準規則集的結果。未知選項和配置失敗會導致退出 2,這與違規不同。

04 / KAL

透過範例理解

通過整合測試檢查整個儲存庫

自述檔案中的整合測試示例使用 KatanaAstLint::from_workspace() 讀取工作區配置,並使用 assert_clean() 執行整個標準規則。當您想要將共享執行器合併到特定於儲存庫的測試中時,這是一個最小的示例。

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

05 / KAL

整合條件與責任邊界

將 kal.json 放入儲存庫邊界

在 kal.json 中指定源根、規則嚴重性、規則啟用和特定於儲存庫的輸入。您可以在本地僅保留每個儲存庫的範圍和容差設定,而無需更改共享規則實施。

與現有 Rust lint 一起使用

KAL 是共享 AST 規則邊界,不能替代 Clippy、Dylint、ast-grep 或 Semgrep。它不會取代 Rust 編譯器 lint 或基於搜尋的檢查,但會作為向 KatanA 新增通用結構規則的責任而引入。

依據

內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。

儲存庫閱讀指南f1d75d87d151
依據 · KAL
所有產品