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

Rules for architecture and prohibited types

Evidence

A structure that integrates results into CI and development checks

Evidence

02

Getting started

  1. Install the CLI with Cargo and move to the Rust workspace to inspect.
  2. 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.

Evidence
sh
cargo install katana-ast-lint
kal check
kal check --json

01 / 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

  1. 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.

  2. 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.

  3. 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.

rust
#[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.

RepositoryREADMEf1d75d87d151
Evidence · KAL
All products