基础设施与工具

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
全部产品