Foundation / tool
KatanA AST Lint
A Rust library and kal CLI for checking syntax trees and repository structure, integrating structural, prohibited-type, and coding rules into projects and CI.
Developers maintaining Rust code quality and structural conventions across the KatanA series
01
Implemented capabilities
02
Getting started
- Install the CLI with Cargo and move to the Rust workspace to inspect.
- Run kal check; configure source roots and rule severity in kal.json.
Prepare Rust and the required development tools, then check the linked README for environment requirements before installing. Examples show an entry point and do not guarantee operation in every environment.
Evidencecargo install katana-ast-lint
kal check
kal check --json01 / KAL
Where it fits
A repository integration gate
Call KatanaAstLint::from_workspace().assert_clean() from an integration test to load the workspace and apply the shared Rust AST rule set. Source roots and repository-specific allowances remain in each repository's configuration rather than in the shared runner.
Standard AST checks in CI
Run kal check to resolve the workspace root, load kal.json when it is present, and execute the standard rule set. Select --json or --text for reporting, then distinguish violations, configuration failures, and system errors by their exit status.
02 / KAL
Input to output
Resolve workspace and configuration
try_from_workspace searches upward from the current directory for a Cargo workspace root and loads its configuration. If the configuration is missing, invalid, or unreadable, it returns KalRunError for the caller to classify.
Apply rules to source roots
lint_all walks the rule catalog and applies each AST rule to configured source roots or rule inputs. It collects per-rule violations and returns them in stable rule-ID order so reporting and tests are deterministic.
Report and gate
try_assert_clean sends collected violations to the configured reporter. The CLI exits 1 for violations and 2 for configuration or system errors, while assert_clean converts a failing result into a panic for an integration test.
03 / KAL
Key APIs and CLI
KatanaAstLint::try_from_workspace- Resolves the current directory's workspace root and configuration, then returns Result<KatanaAstLint, KalRunError>. CLI or test harness code can use the error to distinguish initialization failure from later violations.
KatanaAstLint::from_workspace- Provides the concise panic-on-error initialization used by the integration-test example. It returns a configured linter on success and panics when workspace setup cannot be completed.
violations- Runs all configured rules, collects their results, sorts them by rule ID, and returns a stable Vec<Violation>. Custom tests and reporters can inspect the violation data without going through the CLI reporter.
kal check --json / --text- Runs the standard rules with the selected JSON or text reporter format. Unknown options and workspace/configuration failures use exit 2, which keeps them distinct from the violation exit 1.
04 / KAL
Concrete example
Gate a repository from an integration test
The public README integration-test example calls KatanaAstLint::from_workspace() to load the workspace configuration and then assert_clean() to run the standard rule set over the repository. It is the minimal way to embed the shared runner in a repository-specific test.
#[test]
fn repository_ast_lint() {
katana_ast_lint::KatanaAstLint::from_workspace().assert_clean();
}05 / KAL
Integration boundaries
Keep kal.json at the repository boundary
Use kal.json to specify source roots, rule severities, rule enablement, and repository-specific inputs. This keeps each repository's scope and allowances local without changing the shared rule implementation.
Run alongside Rust lint foundations
KAL is a shared AST-rule boundary, not a replacement for rustc, Clippy, Dylint, ast-grep, or Semgrep. Keep compiler lints and search-based checks in place and add KAL for KatanA-wide structural conventions rather than treating it as a compiler or type checker.
Evidence
This overview is based on the public repositories at the time of review. Verify implementation and usage in the linked pinned commits.