Documentation

Rules Compiler Comparison This guide helps you choose the right rules compiler for your use case. All compilers produce identical output and support the same configuration schema. Quick Comparison…

Configuration Reference All rules compilers in this repository use the same configuration schema, validated against schemas/compiler-config.schema.json. The canonical implementation is @bloqr/compiler…

Docker Guide This guide covers using Docker for development with the ad-blocking toolkit. Docker Development Environment The repository includes a pre-configured Docker environment with all necessary…

Getting Started This guide will help you get up and running with the ad-blocking toolkit. Prerequisites Core Requirements Requirement Version Purpose Installation Deno 2.0+ TypeScript compilers and…

@bloqr/compiler-core Guide A comprehensive guide to @bloqr/compiler-core — the in-repo, dependency-free filter compilation engine that all four compilers in this repository dogfood. Table of Contents…

AdGuard ConsoleUI Architecture This document describes the architecture and design patterns used in the AdGuard.ConsoleUI application. Overview AdGuard.ConsoleUI is a menu-driven console application…

Deployment Guide Comprehensive guide for deploying ad-blocking components in production environments. Overview This guide covers deployment strategies for all components in the ad-blocking repository…

Testing Guide Comprehensive guide to running tests for all components in the ad-blocking repository. Overview This project uses different testing frameworks for each language implementation: Component…

TypeScript Rules Compiler Guide A comprehensive guide to using the TypeScript rules compiler with Deno 2.0+. Overview The TypeScript rules compiler (src/adblock-compiler-core/) is a Deno-based…

Troubleshooting Guide Comprehensive guide for troubleshooting common issues across all components in the ad-blocking repository. Overview This guide provides solutions for common issues you may…

Migration Guide Guide for migrating between different compiler implementations and SDK versions in the ad-blocking repository. Overview This guide helps you migrate between: Different rules compiler…

Repository Guidelines Project Structure & Module Organization The tracked filter list and compiler configuration files live in BloqrAI/bloqr-blocklists (formerly data/ in this repo). src/ contains the…

Environment Variables Reference Comprehensive guide to environment variables supported by AdGuard scripts and modules. Overview All AdGuard scripts and modules support environment variables for…

Hash Verification at Each Compilation Stage This document explains the hash verification callback system implemented across all compilers to enforce integrity checks at each stage of the compilation…

Linear Documentation The Linear import tool (which parsed this file and imported it into Linear as a project + issues) moved to BloqrAI/bloqr-apiclients along with the other API clients. This file…

Documentation This directory contains comprehensive documentation for the ad-blocking repository. Quick Links Document Description Why Validation Matters 🔒 Start Here - Understand why security…

Restructuring Retrospective (2026-08) A record of the multi-day effort that took this repo from bloqr-lists — a monolith holding compiled filter lists, API clients, and every rules compiler — to bloqr…

Runtime Enforcement of Validation Library Implementation status note: this document describes the aspirational design (a mandatory compile_with_validation() wrapper with signed metadata). The .NET…

Rust Workspace This directory contains a unified Rust workspace for all Rust projects in the ad-blocking repository. Projects The workspace includes the following crates: 1. rules-validator (src/rules…

Shared Deno Configuration This repository uses a centralized Deno configuration pattern to ensure consistency across all Deno-based projects. Overview Similar to how .NET projects use Directory.Build…

TypeScript Type Definitions (.d.ts) Generation Overview This document describes the implementation of .d.ts type definition file generation for all TypeScript projects in the repository. Why .d.ts…

Validation Library Integration Requirements This document defines the mandatory integration requirements for all rules compilers to ensure consistent security validation across the codebase…

WARP.md This file provides guidance to WARP (warp.dev) when working with code in this repository. Project scope This repo houses the multi-language rules-compiler toolkit: TypeScript/Deno, C#/.NET 1…

Why Validation Matters: Protecting Your Network and Privacy For Everyone: This document explains why our validation system is essential for keeping your network safe and your data private. Written for…

Backporting Policy: bloqr-compiler → adblock-compiler-core This document defines what gets backported from the commercial bloqr-compiler product (BloqrAI/bloqr-compiler) into this repository's open…

Centralized Package Management Overview The repository uses Central Package Management (CPM) to manage all NuGet package versions from a single Directory.Packages.props file located at the repository…

Parallel Chunking for Large Filter Lists This guide explains the parallel chunking feature available in the rules compilers for improved performance when processing large filter lists. Overview When…

Event Pipeline and Zero-Trust Validation This guide explains the event pipeline system available in all rules compilers for monitoring compilation progress and implementing zero-trust validation…

BloqrAI JSR Organization Standards This document defines the standard practices for all BloqrAI repositories that interact with the JSR (JavaScript Registry). Note: This should eventually be moved to…

JSR Token Authentication This document describes how BloqrAI uses JSR tokens for package publishing and consumption in GitHub Actions workflows. Overview JSR provides two types of tokens: Workflow…

BloqrAI Organization Documentation Strategy This document outlines the recommended approach for sharing documentation and standards across all BloqrAI repositories. Current State (Interim) Existing…

Release Guide This guide explains how to create a new release of the ad-blocking repository with automatically built binaries. Overview The repository uses GitHub Actions to automatically build and…

ADR 0002: AGLint/tsurlfilter/ExtendedCss/ecsstree/DiffBuilder Integration Strategy Status: Accepted Date: 2026-08-10 Related: #256 (epic), #265 (this ADR's tracking issue and spike) Context The epic…

ADR 0001: Canonical Rules-Compilation Engine Strategy Across Languages Status: Accepted Date: 2026-08-04 Related: #256 (epic), #262 (this ADR's tracking issue), #279 (implementation), bloqr-compiler…

BloqrAI Versioning Strategy Status: Active standard, org-wide. Scope: Every independently-published @bloqr JSR package, in this repo and any future repo that publishes one. The core rule Code version…

Release Packaging Strategy: Source vs. Binary-Only, CRT/AOT, and Dependency Preflight Status: Active standard. Scope: Distribution of RulesCompiler.Console and Bloqr.Dashboard.Console (the .NET apps…

NuGet Distribution Strategy for the Common .NET Library Status: Active standard. Scope: Bloqr.Compiler.Abstractions and Bloqr.Compiler.Core (the "common .NET library" the epic refers to), and any…

Phase 2: Shell Reorganization + Environment Variables Status: IN PROGRESS This document tracks the implementation of Phase 2 of the PowerShell/Shell modernization project. Completed ✅ Directory…

Documentation Archive This directory contains historical documentation that describes completed migrations, refactorings, and implementation phases. These documents are kept for reference but are no…

Environment Variable Migration Guide Overview The ad-blocking repository has standardized on a single, universal environment variable format that works consistently across all programming languages…

Rust Workspace Modernization - Summary Overview This document summarizes the modernization of Rust projects in the ad-blocking repository. All Rust projects have been unified into a single workspace…

Repository Restructuring Summary Overview This document summarizes the repository structure improvements made to consolidate and organize the ad-blocking multi-language monorepo according to 202…

Centralized Package Management - Migration Summary Problem Statement Question: "Where is the centralized package system?" Answer: There wasn't one - until now! This document details the migration from…

OOP PowerShell Refactoring - Next Steps Completed Work Phase 1: Common Shared Module ✅ Created src/powershell-modules/Common/ module (738 lines) CompilerLogger.psm1 (224 lines) - Structured logging…

.NET Unit Test Updates - Summary Report Overview Updated all .NET unit tests to ensure they compile and pass. Added additional tests to improve code coverage. Test Results All Tests Passing ✅ Project…