CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository is a comprehensive multi-language toolkit for ad-blocking, network protection, and AdGuard DNS management:

Rules Compilers (4 languages)

TypeScript (src/rules-compiler-typescript/) - Deno 2.0+ with npm compatibility
C#/.NET 10 (src/rules-compiler-dotnet/) - Library and Spectre.Console CLI with DI support
Python 3.9+ (src/rules-compiler-python/) - pip-installable package with CLI and API
Rust (src/rules-compiler-rust/) - High-performance single binary with zero runtime deps

Shell Scripts

Bash (src/rules-compiler-shell/compile-rules.sh) - Linux/macOS
Zsh (src/rules-compiler-shell/compile-rules.zsh) - macOS/Linux with zsh-specific features
PowerShell Core (src/rules-compiler-shell/compile-rules.ps1) - Cross-platform
Windows Batch (src/rules-compiler-shell/compile-rules.cmd) - Windows wrapper

PowerShell Module

RulesCompiler Module (src/adguard-api-powershell/) - Full-featured PowerShell API with Pester tests

API Client & Tools

AdGuard API Client - .NET (src/adguard-api-dotnet/) - C# SDK for AdGuard DNS API v1.11
AdGuard API Client - TypeScript (src/adguard-api-typescript/) - TypeScript SDK with Deno support
Console UI (src/adguard-api-dotnet/src/AdGuard.ConsoleUI/) - Spectre.Console interactive interface
Linear Import Tool (src/linear/) - TypeScript tool with Deno support

Configuration Support

All compilers support JSON, YAML, and TOML configuration formats with full @jk-com/adblock-compiler compatibility.

Docker Development Environment

A fully-featured Docker environment with all compilers and tools:

# Dockerfile.warp
FROM mcr.microsoft.com/dotnet/sdk:10.0-noble
# Includes: .NET 10 SDK, Deno 2.x, Python 3.12, Rust stable, PowerShell 7
# Pre-installed: hostlist-compiler (via Deno), yq, pytest, ruff, clippy, Pester

Build and run:

docker build -f Dockerfile.warp -t ad-blocking-dev .
docker run -it -v $(pwd):/workspace ad-blocking-dev

Docker Compose (recommended):

docker compose up -d dev           # Start dev environment
docker compose exec dev bash       # Enter container
docker compose --profile test run --rm test  # Run all tests

Warp Environment: jaysonknight/warp-env:ad-blocking (ID: Egji4sZU4TNIOwNasFU73A)

Common Commands

TypeScript Rules Compiler (`src/rules-compiler-typescript/`)

cd src/rules-compiler-typescript

# Deno tasks
deno task start                # Start (auto-detect interactive or CLI mode)
deno task interactive          # Interactive menu mode
deno task compile              # CLI compile mode
deno task compile:yaml         # Compile using YAML config
deno task compile:toml         # Compile using TOML config
deno task dev                  # Run with watch mode
deno task test                 # Run Deno tests
deno task test:coverage        # Run tests with coverage
deno task lint                 # Lint source files
deno task fmt                  # Format source files
deno task check                # Type check
deno task version              # Show version

# CLI with options
deno task start -- -c config.yaml -r -d     # CLI mode with config
deno task start -- --interactive            # Force interactive mode
deno task start -- --validate -c config.yaml  # Validate only
deno run --allow-read --allow-write --allow-env --allow-run src/mod.ts --help
deno run --allow-read --allow-write --allow-env --allow-run src/mod.ts --version

Shell Scripts (`src/rules-compiler-shell/`)

# Bash (Linux/macOS)
./src/rules-compiler-shell/compile-rules.sh                    # Use default config
./src/rules-compiler-shell/compile-rules.sh -c config.yaml -r  # YAML config, copy to rules
./src/rules-compiler-shell/compile-rules.sh -v                 # Show version

# Zsh (macOS/Linux)
./src/rules-compiler-shell/compile-rules.zsh                   # Use default config
./src/rules-compiler-shell/compile-rules.zsh -c config.yaml -r # YAML config, copy to rules
./src/rules-compiler-shell/compile-rules.zsh -v                # Show version

# PowerShell Core (all platforms)
./src/rules-compiler-shell/compile-rules.ps1
./src/rules-compiler-shell/compile-rules.ps1 -ConfigPath config.yaml -CopyToRules
./src/rules-compiler-shell/compile-rules.ps1 -Version

# Windows Batch
src\rules-compiler-shell\compile-rules.cmd -c config.json -r

.NET Rules Compiler (`src/rules-compiler-dotnet/`)

cd src/rules-compiler-dotnet
dotnet restore RulesCompiler.slnx
dotnet build RulesCompiler.slnx
dotnet test RulesCompiler.slnx
dotnet run --project src/RulesCompiler.Console/RulesCompiler.Console.csproj

# Command-line options
dotnet run --project src/RulesCompiler.Console -- --config path/to/config.yaml
dotnet run --project src/RulesCompiler.Console -- --config config.json --copy
dotnet run --project src/RulesCompiler.Console -- --config config.yaml --verbose
dotnet run --project src/RulesCompiler.Console -- --config config.yaml --validate
dotnet run --project src/RulesCompiler.Console -- --version

Python Rules Compiler (`src/rules-compiler-python/`)

cd src/rules-compiler-python

# Install in development mode
pip install -e .

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest
pytest -v                    # Verbose output
pytest --cov=rules_compiler  # With coverage

# CLI usage
rules-compiler                           # Use default config
rules-compiler -c config.yaml            # Specific config
rules-compiler -c config.json -r         # Compile and copy to rules
rules-compiler -c config.toml -o out.txt # Custom output
rules-compiler -V                        # Show version info
rules-compiler -d                        # Debug output
rules-compiler --help                    # Show help

Rust Rules Compiler (`src/rules-compiler-rust/`)

cd src/rules-compiler-rust

# Build
cargo build              # Debug build
cargo build --release    # Release build (optimized)

# Run tests
cargo test
cargo test -- --nocapture  # With output

# CLI usage
cargo run -- -c config.yaml              # Specific config
cargo run -- -c config.json -r           # Compile and copy to rules
cargo run -- -c config.toml -o out.txt   # Custom output
cargo run -- -V                          # Show version info
cargo run -- -d                          # Debug output
cargo run -- --help                      # Show help

# Release binary
./target/release/rules-compiler -c config.yaml

.NET API Client + Console UI (`src/adguard-api-dotnet/`)

cd src/adguard-api-dotnet
dotnet restore src/AdGuard.ApiClient.sln
dotnet build src/AdGuard.ApiClient.sln
dotnet test src/AdGuard.ApiClient.sln
dotnet run --project src/AdGuard.ConsoleUI/AdGuard.ConsoleUI.csproj

# Run benchmarks
dotnet run --project src/AdGuard.ApiClient.Benchmarks -c Release

TypeScript API Client (`src/adguard-api-typescript/`)

cd src/adguard-api-typescript

# Deno tasks
deno task start            # Start CLI
deno task sync             # Sync rules
deno task cli              # Run CLI directly
deno task test             # Run tests
deno task test:coverage    # Run tests with coverage
deno task lint             # Lint source files
deno task fmt              # Format source files
deno task check            # Type check

Linear Import Tool (`src/linear/`)

cd src/linear

# Deno tasks
deno task import           # Run import tool
deno task import:docs      # Import documentation
deno task import:dry-run   # Preview import
deno task cli              # Run CLI directly
deno task test             # Run tests
deno task lint             # Lint source files
deno task fmt              # Format source files
deno task check            # Type check

PowerShell RulesCompiler Module (`src/adguard-api-powershell/`)

# Import the module
Import-Module ./src/adguard-api-powershell/Invoke-RulesCompiler.psm1

# Check versions and platform info
Get-CompilerVersion | Format-List

# Compile filter rules
Invoke-RulesCompiler

# Compile and copy to rules directory
Invoke-RulesCompiler -CopyToRules

# Run interactive harness
./src/adguard-api-powershell/RulesCompiler-Harness.ps1

# Run Pester tests
Invoke-Pester -Path ./src/adguard-api-powershell/Tests/RulesCompiler-Tests.ps1

# Lint with PSScriptAnalyzer
Invoke-ScriptAnalyzer -Path src/adguard-api-powershell -Recurse

Running Individual Tests

TypeScript (Deno)

cd src/rules-compiler-typescript
deno test src/cli.test.ts                  # By file
deno test --filter "parseArgs"             # By test name
deno task test:coverage                    # With coverage

.NET (xUnit)

cd src/adguard-api-dotnet
dotnet test src/AdGuard.ApiClient.sln --filter "FullyQualifiedName~DevicesApiTests"   # By class
dotnet test src/AdGuard.ApiClient.sln --filter "Name~GetAccountLimits"                # By method

cd ../rules-compiler-dotnet
dotnet test RulesCompiler.slnx --filter "FullyQualifiedName~ConfigurationValidatorTests"
dotnet test RulesCompiler.slnx --filter "FullyQualifiedName~TransformationTests"

PowerShell (Pester)

# Run all PowerShell tests
Invoke-Pester -Path ./src/adguard-api-powershell/Tests/

# Run specific test file
Invoke-Pester -Path ./src/adguard-api-powershell/Tests/RulesCompiler-Tests.ps1

# Run with detailed output
Invoke-Pester -Path ./src/adguard-api-powershell/Tests/ -Output Detailed

Python (pytest)

cd src/rules-compiler-python
pytest                                    # Run all tests
pytest -v                                 # Verbose output
pytest tests/test_config.py               # Specific file
pytest -k "test_read_yaml"                # By test name
pytest --cov=rules_compiler               # With coverage

Rust (cargo test)

cd src/rules-compiler-rust
cargo test                                # Run all tests
cargo test -- --nocapture                 # With output
cargo test test_count_rules               # Specific test
cargo test config::                       # Tests in module

Architecture

Filter Rules (`data/output/`)

data/output/adguard_user_filter.txt - Main tracked filter list consumed by AdGuard DNS

Rules Compiler - TypeScript (`src/rules-compiler-typescript/`)

TypeScript compiler using @jk-com/adblock-compiler
Deno 2.0+ runtime with npm compatibility
Supports JSON, YAML, and TOML configuration formats
Library API (src/lib/):
- RulesCompiler - Main service class with fluent builder pattern
- ConfigurationBuilder - Programmatic configuration creation
- Separate library export: @rules-compiler/typescript/lib
Dual Mode Support:
- Interactive menu mode (default when no args)
- CLI mode (when config path or action flags provided)
src/cli.ts - Command-line interface with argument parsing and mode detection
src/config-reader.ts - Multi-format configuration reader
src/compiler.ts - Core compilation logic
src/console/ - Interactive console UI components:
- app.ts - ConsoleApplication class with menu-driven interface
- utils.ts - Console utilities (spinners, tables, colored output)
src/mod.ts - Deno entry point
deno.json - Deno configuration and tasks
Key classes: RulesCompiler, RulesCompilerBuilder, ConfigurationBuilder, ConsoleApplication
Uses Deno's built-in testing framework

Shell Scripts (`src/rules-compiler-shell/`)

Cross-platform shell scripts for filter compilation
compile-rules.sh - Bash script for Linux/macOS
compile-rules.zsh - Zsh script with native zsh features (zparseopts, EPOCHREALTIME)
compile-rules.ps1 - PowerShell Core script (all platforms)
compile-rules.cmd - Windows batch wrapper
Supports JSON, YAML, TOML via external tools (yq, Python)

Rules Compiler - .NET (`src/rules-compiler-dotnet/`)

.NET 10 library for filter compilation
Supports JSON, YAML, and TOML configuration formats
RulesCompiler - Core library with abstractions, models, and services
RulesCompiler.Console - Spectre.Console interactive and CLI frontend
RulesCompiler.Tests - xUnit tests
Key interfaces: IRulesCompilerService, IConfigurationReader, IFilterCompiler
Features: Configuration validation, verbose mode, dependency injection

Rules Compiler - Python (`src/rules-compiler-python/`)

Python 3.9+ package for filter compilation
Supports JSON, YAML, and TOML configuration formats
rules_compiler/config.py - Multi-format configuration reader
rules_compiler/compiler.py - Core RulesCompiler class and compile_rules() function
rules_compiler/cli.py - argparse-based CLI
Install via pip install -e . for development
Key classes: RulesCompiler, CompilerConfiguration, CompilerResult
Tools: pytest, mypy, ruff

Rules Compiler - Rust (`src/rules-compiler-rust/`)

High-performance Rust library and CLI for filter compilation
Supports JSON, YAML, and TOML configuration formats
src/config.rs - Configuration structs and parsing
src/compiler.rs - RulesCompiler struct and compile_rules() function
src/main.rs - clap-based CLI with argument parsing
src/error.rs - CompilerError enum with thiserror
Single binary distribution with zero runtime dependencies (except hostlist-compiler)
Key structs: RulesCompiler, CompilerConfiguration, CompilerResult, VersionInfo
LTO optimization enabled for small binary size

API Client - .NET (`src/adguard-api-dotnet/`)

Auto-generated from api/openapi.json (primary) and api/openapi.yaml (optional) - AdGuard DNS API v1.11
Helpers/ConfigurationHelper.cs - Fluent auth, timeouts, user agent
Helpers/RetryPolicyHelper.cs - Polly-based retry for 408/429/5xx
Uses Newtonsoft.Json and JsonSubTypes
Benchmarks project for performance testing

API Client - TypeScript (`src/adguard-api-typescript/`)

TypeScript SDK for AdGuard DNS API v1.11 with feature parity to .NET version
Deno 2.0+ runtime with npm compatibility
Library API (src/lib/):
- AdGuardDnsClientBuilder - Fluent builder for client configuration
- PagedListBuilder - Pagination support for list operations
- Separate library export: @adguard/api-typescript/lib
src/client.ts - Main AdGuardDnsClient class with fluent API
src/api/ - API endpoint implementations (account, devices, DNS servers, statistics, etc.)
src/repositories/ - Higher-level repository pattern abstractions
src/cli/ - Interactive CLI with menu-driven interface
src/mod.ts - Deno entry point
Key classes: AdGuardDnsClient, AdGuardDnsClientBuilder, DeviceRepository, DnsServerRepository
Dependencies (via npm:): axios, commander, inquirer, chalk

Linear Import Tool (`src/linear/`)

TypeScript tool for importing documentation into Linear project management
Deno 2.0+ runtime with npm compatibility
src/linear-import.ts - Main CLI entry point
src/mod.ts - Deno entry point
src/parser.ts - Markdown documentation parser
src/linear-client.ts - Linear API client wrapper
src/types.ts - TypeScript type definitions
Dependencies (via npm:): @linear/sdk, commander, marked, dotenv

Console UI (`src/adguard-api-dotnet/src/AdGuard.ConsoleUI/`)

Spectre.Console menu-driven interface
ApiClientFactory configures SDK from settings or interactive prompt
Features: Device management, DNS servers, statistics, query logs, filter lists

PowerShell Modules (`src/adguard-api-powershell/`)

RulesCompiler Module - Cross-platform PowerShell API mirroring TypeScript compiler
- Invoke-RulesCompiler.psm1 - Main module with exported functions
- RulesCompiler.psd1 - Module manifest
- RulesCompiler-Harness.ps1 - Interactive test harness
- Tests/ - Pester test suite
- Functions: Read-CompilerConfiguration, Invoke-FilterCompiler, Write-CompiledOutput, Invoke-RulesCompiler, Get-CompilerVersion

Configuration Schema

All compilers support the same @jk-com/adblock-compiler configuration schema:

Root-Level Properties

Property	Type	Required	Description
`name`	string	Yes	Filter list name
`description`	string	No	Description
`homepage`	string	No	Homepage URL
`license`	string	No	License identifier
`version`	string	No	Version number
`sources`	array	Yes	List of filter sources
`transformations`	array	No	Global transformations
`inclusions`	array	No	Global include patterns
`exclusions`	array	No	Global exclude patterns

Source Properties

Property	Type	Required	Description
`source`	string	Yes	URL or file path
`name`	string	No	Source identifier
`type`	string	No	`adblock` or `hosts`
`transformations`	array	No	Source-specific transforms
`inclusions`	array	No	Source-specific includes
`exclusions`	array	No	Source-specific excludes

Available Transformations

RemoveComments, Compress, RemoveModifiers, Validate, ValidateAllowIp, Deduplicate, InvertAllow, RemoveEmptyLines, TrimLines, InsertFinalNewLine, ConvertToAscii

Environment Variables

Variable	Description
`ADGUARD_API_KEY`	Universal API credential (works with all languages - recommended)
`AdGuard:ApiKey`	.NET appsettings.json format
`ADGUARD_AdGuard__ApiKey`	.NET environment variable hierarchical format (legacy)
`ADGUARD_LINEAR_API_KEY`	Linear API key for Linear import scripts (`src/linear/`)
`ADGUARD_LINEAR_TEAM_ID`	Optional Linear team ID
`ADGUARD_LINEAR_PROJECT_NAME`	Optional Linear project name
`DEBUG`	Set to any value to enable debug logging
`LOG_LEVEL`	Log level (DEBUG, INFO, WARN, ERROR, SILENT)
`LOG_FORMAT`	Set to `json` for structured logging
`RULESCOMPILER_config`	Default configuration file path (.NET compiler)
`RULESCOMPILER_Logging__LogLevel__Default`	Log level for .NET compiler

CI/CD Alignment

GitHub Actions workflows validate:

.github/workflows/dotnet.yml - Builds/tests .NET projects (API client and rules compiler) with .NET 10
.github/workflows/typescript.yml - Deno 2.x for all TypeScript projects
.github/workflows/security.yml - Consolidated security scanning (CodeQL, DevSkim, PSScriptAnalyzer)
.github/workflows/release.yml - Builds and publishes release binaries (.NET, Rust, Python)
.github/workflows/claude.yml - Claude AI integration for @claude mentions
.github/workflows/claude-code-review.yml - Automated PR code review

Prerequisites

Requirement	Version	Required For
.NET SDK	10.0+	.NET compiler, API client
Deno	2.0+	TypeScript projects (rules compiler, API client, linear)
PowerShell	7+	PowerShell scripts
Python	3.9+	Python compiler
Rust	1.85+	Rust compiler (install via rustup)
adblock-compiler	0.6.0	TypeScript compiler (via JSR: `deno add @jk-com/adblock-compiler`)
Docker	24.0+	Container development (optional but recommended)

Key File Locations

Main filter list: data/output/adguard_user_filter.txt
Compiler configs: src/rules-compiler-*/
Deno configs: src/*/deno.json
OpenAPI spec: api/openapi.yaml
Docker config: Dockerfile.warp, docker-compose.yml, .dockerignore
Documentation: docs/
Environment template: .env.example

Uh oh!

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Project Overview

Rules Compilers (4 languages)

Shell Scripts

PowerShell Module

API Client & Tools

Configuration Support

Docker Development Environment

Common Commands

TypeScript Rules Compiler (src/rules-compiler-typescript/)

Shell Scripts (src/rules-compiler-shell/)

.NET Rules Compiler (src/rules-compiler-dotnet/)

Python Rules Compiler (src/rules-compiler-python/)

Rust Rules Compiler (src/rules-compiler-rust/)

.NET API Client + Console UI (src/adguard-api-dotnet/)

TypeScript API Client (src/adguard-api-typescript/)

Linear Import Tool (src/linear/)

PowerShell RulesCompiler Module (src/adguard-api-powershell/)

Running Individual Tests

TypeScript (Deno)

.NET (xUnit)

PowerShell (Pester)

Python (pytest)

Rust (cargo test)

Architecture

Filter Rules (data/output/)

Rules Compiler - TypeScript (src/rules-compiler-typescript/)

Shell Scripts (src/rules-compiler-shell/)

Rules Compiler - .NET (src/rules-compiler-dotnet/)

Rules Compiler - Python (src/rules-compiler-python/)

Rules Compiler - Rust (src/rules-compiler-rust/)

API Client - .NET (src/adguard-api-dotnet/)

API Client - TypeScript (src/adguard-api-typescript/)

Linear Import Tool (src/linear/)

Console UI (src/adguard-api-dotnet/src/AdGuard.ConsoleUI/)

PowerShell Modules (src/adguard-api-powershell/)

Configuration Schema

Root-Level Properties

Source Properties

Available Transformations

Environment Variables

CI/CD Alignment

Prerequisites

Key File Locations

TypeScript Rules Compiler (`src/rules-compiler-typescript/`)

Shell Scripts (`src/rules-compiler-shell/`)

.NET Rules Compiler (`src/rules-compiler-dotnet/`)

Python Rules Compiler (`src/rules-compiler-python/`)

Rust Rules Compiler (`src/rules-compiler-rust/`)

.NET API Client + Console UI (`src/adguard-api-dotnet/`)

TypeScript API Client (`src/adguard-api-typescript/`)

Linear Import Tool (`src/linear/`)

PowerShell RulesCompiler Module (`src/adguard-api-powershell/`)

Filter Rules (`data/output/`)

Rules Compiler - TypeScript (`src/rules-compiler-typescript/`)

Shell Scripts (`src/rules-compiler-shell/`)

Rules Compiler - .NET (`src/rules-compiler-dotnet/`)

Rules Compiler - Python (`src/rules-compiler-python/`)

Rules Compiler - Rust (`src/rules-compiler-rust/`)

API Client - .NET (`src/adguard-api-dotnet/`)

API Client - TypeScript (`src/adguard-api-typescript/`)

Linear Import Tool (`src/linear/`)

Console UI (`src/adguard-api-dotnet/src/AdGuard.ConsoleUI/`)

PowerShell Modules (`src/adguard-api-powershell/`)