rules-compiler-rust

Rules Compiler (Rust)

Rust API for compiling AdGuard filter rules.

Features

• Fast, single-binary CLI tool
• Library for embedding in other Rust projects
• Supports JSON, YAML, and TOML configuration formats
• Cross-platform (Windows, macOS, Linux)
• Zero runtime dependencies (statically linked)

Prerequisites

Requirement	Version	Notes
Rust	1.85+	Core language
Node.js	18+	For compilation engine

Building

cd src/rules-compiler-rust

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with debug output
cargo run -- -d -c ../filter-compiler/compiler-config.json

CLI Usage

Configuration File Discovery

The compiler automatically searches for configuration files in the following order:

1. Explicit path: If -c/--config is provided, uses that file
2. Current directory: Looks for compiler-config.{json,yaml,toml}
3. Repository-specific path: src/rules-compiler-typescript/compiler-config.json
4. Parent directories: Traverses up the directory tree looking for compiler-config.{json,yaml,toml} (like git)

This means you can run the compiler from any subdirectory and it will find the nearest configuration file in the directory hierarchy.

Examples

# Use default config (auto-discovery)
rules-compiler

# Use specific configuration file
rules-compiler -c compiler-config.yaml

# Compile and copy to rules directory
rules-compiler -c config.json -r

# Show version info
rules-compiler -V

# Show configuration only
rules-compiler config

# Interactive menu mode
rules-compiler -i

# Enable debug output
rules-compiler -c config.yaml -d

# Show help
rules-compiler --help

# Validate configuration before compiling
rules-compiler compile --validate

# Fail on validation warnings
rules-compiler compile --validate --fail-on-warnings

CLI Options

Option	Short	Description
--config PATH	-c	Path to configuration file
--output PATH	-o	Path to output file
--copy-to-rules	-r	Copy output to rules directory
--format FORMAT	-f	Force format (json, yaml, toml)
--version-info	-V	Show version information
--debug	-d	Enable debug output
--interactive	-i	Run in interactive mode
--help	-h	Show help message

Compile Subcommand Options

Option	Description
--validate	Validate configuration before compiling
--fail-on-warnings	Fail compilation if configuration has validation warnings

Library Usage

Add to your Cargo.toml:

[dependencies]
rules-compiler = { path = "../rules-compiler-rust" }

Basic Usage

use rules_compiler::{RulesCompiler, ConfigurationFormat};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let compiler = RulesCompiler::new();

    let result = compiler.compile(
        "compiler-config.yaml",
        None,           // output_path
        true,           // copy_to_rules
        None,           // rules_directory
        None,           // format
    )?;

    if result.success {
        println!("Compiled {} rules", result.rule_count);
        println!("Output: {}", result.output_path);
    } else {
        eprintln!("Error: {:?}", result.error_message);
    }

    Ok(())
}

Reading Configuration

use rules_compiler::{read_configuration, ConfigurationFormat};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Auto-detect format from extension
    let config = read_configuration("config.yaml", None)?;
    println!("Name: {}", config.name);
    println!("Sources: {}", config.sources.len());

    // Force specific format
    let config = read_configuration("config.txt", Some(ConfigurationFormat::Yaml))?;

    Ok(())
}

Version Information

use rules_compiler::get_version_info;

fn main() {
    let info = get_version_info();

    println!("Module: {}", info.module_version);
    println!("Rust: {}", info.rust_version);
    println!("Platform: {}", info.platform.os_name);

    if let Some(node_version) = info.node_version {
        println!("Node.js: {}", node_version);
    }
}

Helper Functions

use rules_compiler::{count_rules, compute_hash};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Count rules in a file
    let count = count_rules("rules.txt");
    println!("Rules: {}", count);

    // Compute SHA-384 hash
    let hash = compute_hash("output.txt")?;
    println!("Hash: {}", hash);

    Ok(())
}

Configuration Formats

JSON

{
  "name": "My Filter Rules",
  "version": "1.0.0",
  "sources": [
    { "name": "Local", "source": "./rules.txt", "type": "adblock" }
  ],
  "transformations": ["Deduplicate", "Validate"]
}

YAML

name: My Filter Rules
version: 1.0.0
sources:
  - name: Local
    source: ./rules.txt
    type: adblock
transformations:
  - Deduplicate
  - Validate

TOML

name = "My Filter Rules"
version = "1.0.0"
transformations = ["Deduplicate", "Validate"]

[[sources]]
name = "Local"
source = "./rules.txt"
type = "adblock"

API Reference

Structs

Struct	Description
RulesCompiler	Main compiler struct
CompilerResult	Result of a compilation operation
CompilerConfiguration	Configuration file model
FilterSource	Source filter list definition
VersionInfo	Component version information
PlatformInfo	Platform-specific information

Enums

Enum	Values
ConfigurationFormat	Json, Yaml, Toml
CompilerError	Various error types

Functions

Function	Description
compile_rules()	Compile filter rules
read_configuration()	Read configuration from file
detect_format()	Detect format from file extension
to_json()	Convert configuration to JSON
get_version_info()	Get version information
count_rules()	Count rules in a file
compute_hash()	Compute SHA-384 hash

Running Tests

cd src/rules-compiler-rust

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_count_rules

Performance

The Rust implementation offers:

• Faster startup time than interpreted languages
• Lower memory usage
• Single binary distribution (no runtime dependencies)
• Native performance for file operations

Cross-Compilation

Build for other platforms:

# Add target
rustup target add x86_64-pc-windows-gnu
rustup target add aarch64-apple-darwin

# Cross-compile
cargo build --release --target x86_64-pc-windows-gnu
cargo build --release --target aarch64-apple-darwin

License

GPLv3 - See LICENSE for details.