_{// by RuztyCrabs}

Warning

This is a University Research Project and SHOULD NOT BE USED ON PRODUCTION ENVIRONMENTS. The goal is to determine the feasibility, performance and developer experience of Rust Programming Language for implementing static code analyzers for Ballerina Language.

Table of Contents

• Benchmarks
• Documentation
• Installation
• Usage
• Configuration
• Development environment
  • Using GitHub Codespaces
  • Using VS Code
• Building
  • Prerequisites
  • Steps
• Debugging
  • Prerequisites
  • Steps
• Contributing
• TODO
• License

Benchmarks

Followings are the benchmarks we achieved using the release version 0.3.0:

Execution Time Comparison

Tool	Total Execution Time	Tokens/Second	Performance vs Blazelint
Blazelint	284ms	2,290,000	Baseline (1×)
Ballerina Scan	8m 04.41s (484.41s)	1,341	1,705× slower
ESLint	3.6s	188,900	12.7× slower

Internal Performance Breakdown

Stage	Execution Time	Percentage of Total	Tokens Processed
Lexical Analysis	80.75ms	26.9%	650,306
Parsing	187.90ms	62.6%	650,306
Semantic Analysis	22.87ms	7.6%	650,306
Linting Rules	8.87ms	3.0%	650,306
Total	300.39ms	100.0%	650,306

Notes on Benchmark Context

• Grammar Coverage: Blazelint currently implements approximately 23% of the full Ballerina grammar. The benchmarks reflect this partial implementation, and performance numbers should be considered with this limitation in mind.
• Lexer Scalability: The lexer uses a switch-case dispatch mechanism, ensuring constant time complexity per character. Adding new lexemes will not significantly impact performance.
• Parser Scalability: Uses a recursive descent parser is designed for modular expansion. While adding new grammar rules increases the depth of recursive calls, the architecture supports efficient scaling with minimal overhead for additional rules.

Documentation

• BNF Grammar for Ballerina Subset
• Software Requirement Specification (SRS)
• Pipeline overview
• Quick Reference
• Implementation Notes

Installation

Install the latest published version from crates.io:

cargo install blazelint

Pre-build binaries are available for Linux from the latest GitHub release.

Windows and MacOS binaries will be added in a later release.

Usage

Basic Usage

Analyze a Ballerina source file by passing its path to blazelint:

blazelint path/to/file.bal

Note

Use the limited subset documented in the BNF when defining Ballerina syntax to be linted.

The tool prints the detected diagnostics if there is any and exits with a non-zero status or exits with a zero status with no prints to stdout if the passed file is clean.

Development Usage

Running from a checked-out repository is also supported:

cargo run -- path/to/file.bal

Note

cargo run builds and executes an unoptimized build (for debug requirements). Always use cargo build --release for any benchmark or observations on performance.

For a quick smoke test, you can reuse the sample program in tests/test-bal-files/:

blazelint tests/test-bal-files/simple_errors.bal

Timing Instrumentation

Blazelint supports timing analysis for each pipeline stage. Use the following flags:

• --timing: Displays the total time taken by each pipeline stage (lexing, parsing, semantic analysis, linting).
• --detailed-timing: Provides a detailed breakdown, including per-rule linting durations.

Example:

blazelint --timing path/to/file.bal

Configuration

Configuration File

Blazelint looks for a .blazerc configuration file in the current directory or any parent directory. The configuration uses TOML format:

# .blazerc - Blazelint Configuration File

[rules]
# Naming convention rules
camel-case = "error"       # Enforces camelCase for variables/functions
constant-case = "warn"     # Enforces SCREAMING_SNAKE_CASE for constants

# Code style rules  
line-length = "warn"       # Limits line length
max-function-length = "error"  # Limits function body length
missing-return = "error"   # Ensures functions have return statements
unused-variables = "warn"  # Detects unused variable declarations

# Disable specific rules
some-rule = "off"

[settings]
max-line-length = 120      # Maximum characters per line
max-function-length = 50   # Maximum lines in function body

Rule Configuration Values

Each rule can be configured with one of these severity levels:

• "error" - Causes build failure (non-zero exit code)
• "warn" - Shows warnings but allows build to succeed
• "info" - Shows informational messages
• "off" - Disables the rule completely

Available Rules

Rule	Description	Default Severity	Settings
camel-case	Enforces camelCase naming for variables and functions	error	None
constant-case	Enforces SCREAMING_SNAKE_CASE for constants	warn	None
line-length	Limits line length	warn	max-line-length
max-function-length	Limits function body length	warn	max-function-length
missing-return	Ensures functions have return statements	error	None
unused-variables	Detects unused variable declarations	warn	None

Configuration Discovery

Blazelint searches for .blazerc files in this order:

1. Current directory: ./.blazerc
2. Parent directories: Walks up the directory tree looking for .blazerc
3. Default configuration: Uses built-in defaults if no file found

Rule Engine

The rule engine features:

• Dynamic Rule Loading: Only enabled rules are executed
• Configurable Severity: Each rule respects configured severity levels
• Caching: Configuration is cached for performance
• Extensible Design: New rules can be added easily

Development environment

A pre-configured Dev Container is available that can be used to investigate, develop or debug the program without installing anything on the host machine.

It can be launched and used fully remotely inside a browser using GitHub codespaces, or locally using Visual Studio Code.

Using GitHub Codespaces

1. Click Code → Create codespace from the GitHub UI.
2. Wait for the Codespace to provision (first run will take some significant time).
3. Start Developing!

Using Visual Studio Code

1. Install the Dev Containers extension.
2. Clone this repository and open it in VS Code.
3. Run the Dev Containers: Reopen in Container command.
4. Wait till the container spins up.
5. Start Developing!

The container comes with:

• Rust toolchain
• Typst CLI for building the SRS
• Ballerina runtime
• Extensions for Language Servers, syntax highlighting and debugging support
• Common utilities (zsh, GitHub CLI, git, etc.)

Development Dependencies

The project uses the following key dependencies:

• Core: Standard library only for main linting logic
• Configuration: serde, toml for config file parsing
• Utilities: once_cell, thiserror for error handling and caching
• Testing: assert_cmd, tempfile for integration tests

Building

Prerequisites

• Git 2.51.0 or newer
• Rust Toolchain 1.86.0 or newer (Get it here)

Steps

1. Create a fork and clone to local:

   git clone https://github.com/<your-profile-name>/Blazelint.git

2. cd into the directory:

   cd Blazelint

3. Build with cargo:

   cargo build --release

Debugging

Prerequisites

• Build requirements stated here.
• Visual Studio Code IDE by Microsoft
• Rust Analyzer extension by rust-lang.org
• CodeLLDB extension by Vadim Chugunov
• Ballerina toolchain and IDE extension (optional - for testing or writing ballerina codes)

Steps

• You can adjust the tests/test-bal-files/ files if you need to debug a specific diagnostic.
• Create a .blazerc config file to test configuration changes.
• Set breakpoints as needed.
• Click on Run and Debug from the main method or use ctrl+shift+D to jump to debug menu.

Note

It is possible to debug with any IDE including Neovim, Emacs and etc but we recommend Visual Studio Code for easier setup.

Contributing

• Changes should be developed and push to following branches based on the area of the feature.

  • feature/linter-core: Changes to the linter engine (lexer, parser, semantic analyzer and BNF document).
  • feature/rule-engine: Changes to rule engine, configuration system, and linter rules.
  • ci/cd: Changes related to continous integration and deployments.
  • docs: Changes related to documentation.

• Run all formatter, lint, and test checks locally before opening a pull request:

  bash scripts/check.sh

License

This project is licensed under the MIT License.