<div align="right">_{// by RuztyCrabs}</div>

[!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

Internal Performance Breakdown

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

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.