diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 66ae9435..c2cc26aa 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -39,7 +39,7 @@ Multi-language toolkit for ad-blocking and AdGuard DNS management with **identic - `adguard-validate` (CLI tool) ### Compiler Equivalence -All four compilers (TypeScript, .NET, Python, Rust) wrap `@adguard/hostlist-compiler` and **must**: +All four compilers (TypeScript, .NET, Python, Rust) use `@jk-com/adblock-compiler` and **must**: - Support JSON, YAML, TOML config formats (except PowerShell: JSON only) - Count rules identically (exclude empty lines and `!`/`#` comments) - Compute SHA-384 hash of output (96 hex chars) @@ -402,7 +402,7 @@ All compilers return/output: ``` ### Configuration Schema -Supports 3 formats (JSON/YAML/TOML), mirrors `@adguard/hostlist-compiler`: +Supports 3 formats (JSON/YAML/TOML), based on `@jk-com/adblock-compiler` schema: ```json { "output": "data/output/adguard_user_filter.txt", @@ -493,11 +493,13 @@ cd src/rules-compiler-rust && cargo test - **Auth**: Bearer token in `Authorization` header - **Retry logic**: 3 attempts with exponential backoff (408, 429, 5xx) -### @adguard/hostlist-compiler -- **All compilers depend on this**: npm package must be globally installed -- **Installation**: `npm install -g @adguard/hostlist-compiler` +### @jk-com/adblock-compiler +- **All compilers depend on this**: JSR package +- **Installation**: `deno add @jk-com/adblock-compiler` or via JSR +- **Source**: https://github.com/jaypatrick/hostlistcompiler +- **Documentation**: https://jsr.io/@jk-com/adblock-compiler - Provides 11 transformations (RemoveComments, Compress, Validate, etc.) -- Compilers wrap this, handling config parsing and result formatting +- Compilers use this, handling config parsing and result formatting ### Docker Development - **Dockerfile**: `Dockerfile.warp` (multi-stage with .NET 8 SDK + Node 20 + PowerShell 7) diff --git a/CLAUDE.md b/CLAUDE.md index 9cba13c1..c8c476a2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,7 +28,7 @@ This repository is a comprehensive multi-language toolkit for ad-blocking, netwo - **Linear Import Tool** (`src/linear/`) - TypeScript tool with Deno support ### Configuration Support -All compilers support JSON, YAML, and TOML configuration formats with full @adguard/hostlist-compiler compatibility. +All compilers support JSON, YAML, and TOML configuration formats with full @jk-com/adblock-compiler compatibility. ## Docker Development Environment @@ -294,7 +294,7 @@ cargo test config:: # Tests in module - `data/output/adguard_user_filter.txt` - Main tracked filter list consumed by AdGuard DNS ### Rules Compiler - TypeScript (`src/rules-compiler-typescript/`) -- TypeScript wrapper around @adguard/hostlist-compiler +- 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/`): @@ -324,7 +324,7 @@ cargo test config:: # Tests in module - Supports JSON, YAML, TOML via external tools (yq, Python) ### Rules Compiler - .NET (`src/rules-compiler-dotnet/`) -- .NET 10 library wrapping @adguard/hostlist-compiler +- .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 @@ -333,7 +333,7 @@ cargo test config:: # Tests in module - Features: Configuration validation, verbose mode, dependency injection ### Rules Compiler - Python (`src/rules-compiler-python/`) -- Python 3.9+ package wrapping @adguard/hostlist-compiler +- 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 @@ -343,7 +343,7 @@ cargo test config:: # Tests in module - Tools: pytest, mypy, ruff ### Rules Compiler - Rust (`src/rules-compiler-rust/`) -- High-performance Rust library and CLI wrapping @adguard/hostlist-compiler +- 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 @@ -400,7 +400,7 @@ cargo test config:: # Tests in module ## Configuration Schema -All compilers support the same @adguard/hostlist-compiler configuration schema: +All compilers support the same @jk-com/adblock-compiler configuration schema: ### Root-Level Properties | Property | Type | Required | Description | @@ -463,7 +463,7 @@ GitHub Actions workflows validate: | PowerShell | 7+ | PowerShell scripts | | Python | 3.9+ | Python compiler | | Rust | 1.85+ | Rust compiler (install via rustup) | -| hostlist-compiler | Latest | All compilers (via Deno: `deno run npm:@adguard/hostlist-compiler`) | +| 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 diff --git a/README.md b/README.md index d51dad9b..e08cd15a 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ A comprehensive multi-language toolkit for ad-blocking, network protection, and | **Rust** | Native binary | Cargo/Binary | Zero-runtime deps, LTO optimization | | **PowerShell** | PowerShell 7+ | Module | Pipeline-friendly, Pester tests | -All compilers wrap [@adguard/hostlist-compiler](https://github.com/AdguardTeam/HostlistCompiler) with **built-in security validation** and support: +All compilers use [@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler) with **built-in security validation** and support: - **All 11 transformations**: Deduplicate, Validate, RemoveComments, Compress, RemoveModifiers, etc. - **Multi-format config**: JSON, YAML, and TOML configuration files - **Source-specific settings**: Per-source transformations, inclusions, exclusions @@ -216,7 +216,7 @@ curl -fsSL https://deno.land/install.sh | sh irm https://deno.land/install.ps1 | iex ``` -The `@adguard/hostlist-compiler` package is accessed via Deno's npm compatibility. +The `@jk-com/adblock-compiler` package is accessed via Deno's JSR integration. ### Clone and Setup @@ -536,7 +536,7 @@ See [`data/archive/README.md`](data/archive/README.md) for detailed usage and re │ ▼ ┌─────────────────────────────────────────────────────┐ -│ 4. Compile with @adguard/hostlist-compiler │ +│ 4. Compile with @jk-com/adblock-compiler │ │ - Merge all sources │ │ - Apply transformations (dedupe, validate, etc) │ │ - Convert hosts format to adblock if needed │ @@ -562,7 +562,7 @@ See [`data/archive/README.md`](data/archive/README.md) for detailed usage and re ## Rules Compilers -All compilers wrap [@adguard/hostlist-compiler](https://github.com/AdguardTeam/HostlistCompiler) and support: +All compilers use [@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler) and support: - **Multi-format config**: JSON, YAML, TOML - **All 11 transformations**: Deduplicate, Validate, RemoveComments, Compress, etc. @@ -744,7 +744,7 @@ println!("Compiled {} rules", result.rule_count); **Location**: `src/shell/` -Cross-platform shell scripts that wrap `@adguard/hostlist-compiler` for simple automation and CI/CD pipelines. +Cross-platform shell scripts that use `@jk-com/adblock-compiler` for simple automation and CI/CD pipelines. | Script | Platform | Shell | Features | |--------|----------|-------|----------| diff --git a/data/input/README.md b/data/input/README.md index ba4ff960..96c5869f 100644 --- a/data/input/README.md +++ b/data/input/README.md @@ -173,7 +173,7 @@ data/input/ 2. **Validation**: Lint and verify syntax of each file 3. **Hashing**: Compute SHA-384 hash for integrity verification 4. **Remote fetch** (if applicable): Download internet lists with hash verification -5. **Compilation**: Merge all sources using `@adguard/hostlist-compiler` +5. **Compilation**: Merge all sources using `@jk-com/adblock-compiler` 6. **Output**: Write final adblock-format list to `data/output/adguard_user_filter.txt` ## Security diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 203159d6..2e4abab5 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -4,7 +4,7 @@ - `data/` contains the tracked filter list (`data/output/adguard_user_filter.txt`) and compiler configuration files. - `src/` contains the multi-language toolchain: - - `src/rules-compiler-*` (TypeScript/Deno, .NET, Python, Rust, shell) compilers that wrap `@adguard/hostlist-compiler`. + - `src/rules-compiler-*` (TypeScript/Deno, .NET, Python, Rust, shell) compilers that use `@jk-com/adblock-compiler`. - `src/adguard-api-dotnet/`, `src/adguard-api-typescript/`, and `src/adguard-api-rust/` SDKs + interactive clients for the AdGuard DNS API. - `src/adguard-api-powershell/` PowerShell modules and Pester tests. - `docs/` holds guides and reference documentation. diff --git a/docs/LINEAR_DOCUMENTATION.md b/docs/LINEAR_DOCUMENTATION.md index facfafcd..00306883 100644 --- a/docs/LINEAR_DOCUMENTATION.md +++ b/docs/LINEAR_DOCUMENTATION.md @@ -110,7 +110,7 @@ export ADGUARD_ARCHIVE_RETENTION_DAYS=90 **Technology Stack:** - TypeScript 5.4.5 -- @adguard/hostlist-compiler v1.0.39 +- @jk-com/adblock-compiler v0.6.0 - Deno test (testing) - Deno 2.0+ @@ -284,7 +284,7 @@ ad-blocking/ | Technology | Version | Purpose | |------------|---------|---------| | TypeScript | 5.4.5 | Strongly-typed JavaScript | -| @adguard/hostlist-compiler | 1.0.39 | Core compilation engine | +| @jk-com/adblock-compiler | 0.6.0 | Core compilation engine | | Deno | 2.0+ | TypeScript/JavaScript runtime | | Deno test | built-in | Testing framework | diff --git a/docs/README.md b/docs/README.md index 6f5a0d16..5ddf0564 100644 --- a/docs/README.md +++ b/docs/README.md @@ -138,6 +138,6 @@ All URIs are relative to `https://api.adguard-dns.io` - [AdGuard DNS](https://adguard-dns.io/) - [AdGuard DNS API Documentation](https://api.adguard-dns.io/static/swagger/swagger.json) -- [@adguard/hostlist-compiler](https://github.com/AdguardTeam/HostlistCompiler) +- [@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler) - [AdBlock Tester](https://adblock-tester.com/) - [AdGuard Tester](https://d3ward.github.io/toolz/adblock.html) diff --git a/docs/RUNTIME_ENFORCEMENT.md b/docs/RUNTIME_ENFORCEMENT.md index 155ef168..c3aaca30 100644 --- a/docs/RUNTIME_ENFORCEMENT.md +++ b/docs/RUNTIME_ENFORCEMENT.md @@ -32,7 +32,8 @@ │ ▼ ┌─────────────────────────────────────────┐ -│ @adguard/hostlist-compiler │ +│ @jk-com/adblock-compiler │ +│ (JSR package) │ └─────────────────────────────────────────┘ ``` @@ -40,7 +41,7 @@ ### 1. Mandatory Wrapper Function -All compilers **MUST** use `compile_with_validation()` instead of calling `@adguard/hostlist-compiler` directly: +All compilers **MUST** use `compile_with_validation()` instead of calling `@jk-com/adblock-compiler` directly: **❌ FORBIDDEN - Direct compilation bypass:** ```typescript @@ -280,7 +281,7 @@ module.exports = { rules: { 'no-restricted-imports': ['error', { patterns: [{ - group: ['@adguard/hostlist-compiler'], + group: ['@jk-com/adblock-compiler'], message: 'Do not import hostlist-compiler directly. Use compile_with_validation() from @adguard/validation instead.' }] }] diff --git a/docs/RUST_WORKSPACE.md b/docs/RUST_WORKSPACE.md index 1fbaca6a..6fad2f9d 100644 --- a/docs/RUST_WORKSPACE.md +++ b/docs/RUST_WORKSPACE.md @@ -19,7 +19,7 @@ Rust implementation of the AdGuard DNS API client. - **adguard-api-cli**: Interactive CLI for AdGuard DNS API ### 3. **rules-compiler-rust** (`src/rules-compiler-rust/`) -Rust compiler for AdGuard filter rules using `@adguard/hostlist-compiler`. +Rust compiler for AdGuard filter rules using `@jk-com/adblock-compiler`. - Library and CLI for compiling filter rules - Supports JSON, YAML, and TOML configurations diff --git a/docs/VALIDATION_ENFORCEMENT.md b/docs/VALIDATION_ENFORCEMENT.md index 77947249..08c2c746 100644 --- a/docs/VALIDATION_ENFORCEMENT.md +++ b/docs/VALIDATION_ENFORCEMENT.md @@ -85,7 +85,7 @@ async function compile(config: CompilerConfig): Promise { } } - // 3. Proceed with compilation using @adguard/hostlist-compiler + // 3. Proceed with compilation using @jk-com/adblock-compiler const output = await hostlistCompiler.compile(config); // 4. MANDATORY: Handle file conflicts diff --git a/docs/WARP.md b/docs/WARP.md index 4ad0204a..6988d1f3 100644 --- a/docs/WARP.md +++ b/docs/WARP.md @@ -48,7 +48,7 @@ High-level architecture and structure - Filter rules (data/output/) - data/output/adguard_user_filter.txt is the tracked output list consumed by AdGuard DNS. - Filter compiler (src/rules-compiler-typescript/) - - Deno/TypeScript wrapper around @adguard/hostlist-compiler. Reads configuration, compiles sources, and writes compiled rules. Deno tests cover config parsing and output writing. + - Deno/TypeScript wrapper around @jk-com/adblock-compiler. Reads configuration, compiles sources, and writes compiled rules. Deno tests cover config parsing and output writing. - API clients - src/adguard-api-dotnet/: Auto-generated C# SDK for AdGuard DNS API v1.11. Targets net10.0; uses Newtonsoft.Json and JsonSubTypes. Includes Helpers for configuration and Polly-based retry policies. Console UI uses Spectre.Console. - src/adguard-api-typescript/: TypeScript/Deno SDK with full API coverage, repository pattern, and interactive CLI using inquirer/ora. diff --git a/docs/chunking-guide.md b/docs/chunking-guide.md index b3ff78b3..27c38e65 100644 --- a/docs/chunking-guide.md +++ b/docs/chunking-guide.md @@ -4,7 +4,7 @@ This guide explains the parallel chunking feature available in the rules compile ## Overview -When compiling filter lists with many sources or millions of rules, the single-threaded nature of `@adguard/hostlist-compiler` can become a bottleneck. Chunking addresses this by: +When compiling filter lists with many sources or millions of rules, chunking addresses this by: 1. **Splitting sources into chunks** - Distributes sources across multiple parallel workers 2. **Compiling chunks in parallel** - Uses multiple CPU cores simultaneously diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 9a8db867..ca1370b0 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -1,6 +1,6 @@ # Configuration Reference -All rules compilers in this repository use the same configuration schema based on [@adguard/hostlist-compiler](https://github.com/AdguardTeam/HostlistCompiler). +All rules compilers in this repository use the same configuration schema based on [@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler). ## Supported Formats @@ -376,7 +376,7 @@ data/input/ → Compiler → data/output/ 3. Validate syntax of each source 4. Compute SHA-384 hashes for tampering detection 5. Fetch internet sources with hash verification -6. Merge all sources using `@adguard/hostlist-compiler` +6. Merge all sources using `@jk-com/adblock-compiler` 7. Apply transformations (deduplicate, validate, etc.) 8. Convert hosts format to adblock if needed 9. Write to `data/output/adguard_user_filter.txt` diff --git a/docs/docker-guide.md b/docs/docker-guide.md index 978d0bc1..6b6760ee 100644 --- a/docs/docker-guide.md +++ b/docs/docker-guide.md @@ -42,7 +42,7 @@ WORKDIR /workspace ### Pre-installed Tools -- **Deno packages**: `@adguard/hostlist-compiler` (via npm: specifier) +- **Deno packages**: `@jk-com/adblock-compiler` (via JSR) - **Python packages**: `pytest`, `pytest-cov`, `mypy`, `ruff`, `pyyaml`, `tomlkit` - **Rust components**: `clippy`, `rustfmt` - **PowerShell modules**: `Pester`, `PSScriptAnalyzer` diff --git a/docs/getting-started.md b/docs/getting-started.md index e638324b..99d8d149 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -9,7 +9,7 @@ This guide will help you get up and running with the ad-blocking toolkit. | Requirement | Version | Purpose | Installation | |-------------|---------|---------|--------------| | Deno | 2.0+ | TypeScript compilers and tools | [deno.land](https://deno.land/) | -| hostlist-compiler | Latest | Filter compilation | `deno run npm:@adguard/hostlist-compiler` | +| adblock-compiler | 0.6.0 | Filter compilation | `deno run jsr:@jk-com/adblock-compiler` | ### Language-Specific Requirements @@ -48,7 +48,7 @@ Verify installation: deno --version ``` -The `@adguard/hostlist-compiler` package is accessed via Deno's npm compatibility. +The `@jk-com/adblock-compiler` package is accessed via Deno's JSR integration. ### 3. Choose Your Compiler @@ -281,7 +281,7 @@ deno --version You can run hostlist-compiler directly with: ```bash -deno run --allow-all npm:@adguard/hostlist-compiler --version +deno run --allow-all jsr:@jk-com/adblock-compiler --version ``` ### Permission denied on Linux/macOS diff --git a/docs/guides/migration-guide.md b/docs/guides/migration-guide.md index 74697491..ee56379d 100644 --- a/docs/guides/migration-guide.md +++ b/docs/guides/migration-guide.md @@ -114,7 +114,7 @@ dotnet run --project src/RulesCompiler.Console "compile": "node compile.js" }, "dependencies": { - "@adguard/hostlist-compiler": "^1.0.0" + "@jk-com/adblock-compiler": "^0.6.0" } } ``` @@ -126,7 +126,7 @@ dotnet run --project src/RulesCompiler.Console "compile": "deno run --allow-all src/mod.ts" }, "imports": { - "@adguard/hostlist-compiler": "npm:@adguard/hostlist-compiler" + "@jk-com/adblock-compiler": "jsr:@jk-com/adblock-compiler@^0.6.0" } } ``` @@ -739,7 +739,7 @@ jsonlint config.json # For JSON # Transformations are applied in fixed order regardless of config # Check for version differences in hostlist-compiler -deno run npm:@adguard/hostlist-compiler --version +deno run jsr:@jk-com/adblock-compiler --version # Enable debug output new-compiler -c config.yaml -d diff --git a/docs/guides/troubleshooting-guide.md b/docs/guides/troubleshooting-guide.md index a15014d3..ac6eda3b 100644 --- a/docs/guides/troubleshooting-guide.md +++ b/docs/guides/troubleshooting-guide.md @@ -85,18 +85,18 @@ deno run -A src/mod.ts } ``` -### hostlist-compiler Not Found +### adblock-compiler Not Found -**Symptom:** `npm:@adguard/hostlist-compiler not found` +**Symptom:** `jsr:@jk-com/adblock-compiler not found` **Solution:** ```bash -# Test npm: specifier -deno run --allow-all npm:@adguard/hostlist-compiler --version +# Test JSR specifier +deno run --allow-all jsr:@jk-com/adblock-compiler --version # If that works, the issue is with your configuration -# Check deno.json for correct npm imports +# Check deno.json for correct JSR imports # Ensure Deno version is 2.0+ deno upgrade diff --git a/docs/guides/typescript-rules-compiler.md b/docs/guides/typescript-rules-compiler.md index a90ff1ce..bac1cee7 100644 --- a/docs/guides/typescript-rules-compiler.md +++ b/docs/guides/typescript-rules-compiler.md @@ -4,7 +4,7 @@ A comprehensive guide to using the TypeScript rules compiler with Deno 2.0+. ## Overview -The TypeScript rules compiler is a Deno-based implementation that wraps [@adguard/hostlist-compiler](https://github.com/AdguardTeam/HostlistCompiler) to compile filter lists from multiple sources with transformations, inclusions, and exclusions. +The TypeScript rules compiler is a Deno-based implementation that uses [@jk-com/adblock-compiler](https://github.com/jaypatrick/hostlistcompiler) to compile filter lists from multiple sources with transformations, inclusions, and exclusions. ## Features @@ -20,7 +20,7 @@ The TypeScript rules compiler is a Deno-based implementation that wraps [@adguar | Requirement | Version | Installation | |-------------|---------|--------------| | Deno | 2.0+ | [deno.land](https://deno.land/) | -| @adguard/hostlist-compiler | Latest | Via Deno's npm compatibility | +| @jk-com/adblock-compiler | 0.6.0 | Via JSR | ## Installation @@ -349,7 +349,7 @@ deno --version Test hostlist-compiler access: ```bash -deno run --allow-all npm:@adguard/hostlist-compiler --version +deno run --allow-all jsr:@jk-com/adblock-compiler --version ``` ### Permission Denied diff --git a/src/adguard-api-dotnet/src/AdGuard.ApiClient.Benchmarks/AdGuard.ApiClient.Benchmarks.csproj b/src/adguard-api-dotnet/src/AdGuard.ApiClient.Benchmarks/AdGuard.ApiClient.Benchmarks.csproj index 90d4c02b..731331ae 100644 --- a/src/adguard-api-dotnet/src/AdGuard.ApiClient.Benchmarks/AdGuard.ApiClient.Benchmarks.csproj +++ b/src/adguard-api-dotnet/src/AdGuard.ApiClient.Benchmarks/AdGuard.ApiClient.Benchmarks.csproj @@ -13,7 +13,6 @@ - diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/CompilationStatistics.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/CompilationStatistics.cs new file mode 100644 index 00000000..b02f159d --- /dev/null +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/CompilationStatistics.cs @@ -0,0 +1,42 @@ +namespace AdGuard.DataAccess.Abstractions; + +/// +/// Represents compilation statistics summary. +/// +public record CompilationStatistics +{ + /// + /// Gets the total number of compilations. + /// + public int TotalCompilations { get; init; } + + /// + /// Gets the number of successful compilations. + /// + public int SuccessfulCompilations { get; init; } + + /// + /// Gets the number of failed compilations. + /// + public int FailedCompilations { get; init; } + + /// + /// Gets the average compilation duration in milliseconds. + /// + public double AverageDurationMs { get; init; } + + /// + /// Gets the total rules compiled across all successful compilations. + /// + public long TotalRulesCompiled { get; init; } + + /// + /// Gets the average rules per compilation. + /// + public double AverageRulesPerCompilation { get; init; } + + /// + /// Gets the success rate as a percentage. + /// + public double SuccessRate => TotalCompilations > 0 ? (double)SuccessfulCompilations / TotalCompilations * 100 : 0; +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/ICompilationHistoryLocalRepository.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/ICompilationHistoryLocalRepository.cs index f6d78db3..eb42f02f 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/ICompilationHistoryLocalRepository.cs +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/ICompilationHistoryLocalRepository.cs @@ -80,45 +80,4 @@ public interface ICompilationHistoryLocalRepository : ILocalRepositoryThe cancellation token. /// The number of deleted records. Task DeleteOlderThanAsync(DateTime olderThan, CancellationToken cancellationToken = default); -} - -/// -/// Represents compilation statistics summary. -/// -public record CompilationStatistics -{ - /// - /// Gets the total number of compilations. - /// - public int TotalCompilations { get; init; } - - /// - /// Gets the number of successful compilations. - /// - public int SuccessfulCompilations { get; init; } - - /// - /// Gets the number of failed compilations. - /// - public int FailedCompilations { get; init; } - - /// - /// Gets the average compilation duration in milliseconds. - /// - public double AverageDurationMs { get; init; } - - /// - /// Gets the total rules compiled across all successful compilations. - /// - public long TotalRulesCompiled { get; init; } - - /// - /// Gets the average rules per compilation. - /// - public double AverageRulesPerCompilation { get; init; } - - /// - /// Gets the success rate as a percentage. - /// - public double SuccessRate => TotalCompilations > 0 ? (double)SuccessfulCompilations / TotalCompilations * 100 : 0; -} +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/IStatisticsLocalRepository.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/IStatisticsLocalRepository.cs index 830ec21a..2fdd9fcb 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/IStatisticsLocalRepository.cs +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/IStatisticsLocalRepository.cs @@ -71,40 +71,4 @@ Task> GetByDateRangeAsync( /// The cancellation token. /// The number of deleted records. Task DeleteOlderThanAsync(DateTime olderThan, CancellationToken cancellationToken = default); -} - -/// -/// Represents aggregate statistics totals. -/// -public record StatisticsTotals -{ - /// - /// Gets the total number of queries. - /// - public long TotalQueries { get; init; } - - /// - /// Gets the total number of blocked queries. - /// - public long BlockedQueries { get; init; } - - /// - /// Gets the total number of allowed queries. - /// - public long AllowedQueries { get; init; } - - /// - /// Gets the total number of cached queries. - /// - public long CachedQueries { get; init; } - - /// - /// Gets the average response time in milliseconds. - /// - public double AverageResponseTimeMs { get; init; } - - /// - /// Gets the block rate as a percentage. - /// - public double BlockRate => TotalQueries > 0 ? (double)BlockedQueries / TotalQueries * 100 : 0; -} +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/StatisticsTotals.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/StatisticsTotals.cs new file mode 100644 index 00000000..d17f1bde --- /dev/null +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Abstractions/StatisticsTotals.cs @@ -0,0 +1,37 @@ +namespace AdGuard.DataAccess.Abstractions; + +/// +/// Represents aggregate statistics totals. +/// +public record StatisticsTotals +{ + /// + /// Gets the total number of queries. + /// + public long TotalQueries { get; init; } + + /// + /// Gets the total number of blocked queries. + /// + public long BlockedQueries { get; init; } + + /// + /// Gets the total number of allowed queries. + /// + public long AllowedQueries { get; init; } + + /// + /// Gets the total number of cached queries. + /// + public long CachedQueries { get; init; } + + /// + /// Gets the average response time in milliseconds. + /// + public double AverageResponseTimeMs { get; init; } + + /// + /// Gets the block rate as a percentage. + /// + public double BlockRate => TotalQueries > 0 ? (double)BlockedQueries / TotalQueries * 100 : 0; +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuard.DataAccess.csproj b/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuard.DataAccess.csproj index a3eb3721..607b1321 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuard.DataAccess.csproj +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuard.DataAccess.csproj @@ -30,9 +30,4 @@ - - - - - diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuardDbContext.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuardDbContext.cs index c03c4671..6c277c76 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuardDbContext.cs +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/AdGuardDbContext.cs @@ -87,20 +87,4 @@ protected override void ConfigureConventions(ModelConfigurationBuilder configura configurationBuilder.Properties() .HaveConversion(); } -} - -/// -/// Converts DateTime values to UTC for storage. -/// -internal class DateTimeUtcConverter : Microsoft.EntityFrameworkCore.Storage.ValueConversion.ValueConverter -{ - /// - /// Initializes a new instance of the class. - /// - public DateTimeUtcConverter() - : base( - v => v.Kind == DateTimeKind.Utc ? v : v.ToUniversalTime(), - v => DateTime.SpecifyKind(v, DateTimeKind.Utc)) - { - } -} +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/DateTimeUtcConverter.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/DateTimeUtcConverter.cs new file mode 100644 index 00000000..8b0a93dc --- /dev/null +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/DateTimeUtcConverter.cs @@ -0,0 +1,17 @@ +namespace AdGuard.DataAccess; + +/// +/// Converts DateTime values to UTC for storage. +/// +internal class DateTimeUtcConverter : Microsoft.EntityFrameworkCore.Storage.ValueConversion.ValueConverter +{ + /// + /// Initializes a new instance of the class. + /// + public DateTimeUtcConverter() + : base( + v => v.Kind == DateTimeKind.Utc ? v : v.ToUniversalTime(), + v => DateTime.SpecifyKind(v, DateTimeKind.Utc)) + { + } +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/AuditLogEntity.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/AuditLogEntity.cs index 06045c60..7109914a 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/AuditLogEntity.cs +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/AuditLogEntity.cs @@ -99,60 +99,4 @@ public class AuditLogEntity /// Gets or sets additional context as JSON. /// public string? ContextJson { get; set; } -} - -/// -/// Represents the type of audit operation. -/// -public enum AuditOperationType -{ - /// - /// An entity was created. - /// - Create = 0, - - /// - /// An entity was read/retrieved. - /// - Read = 1, - - /// - /// An entity was updated. - /// - Update = 2, - - /// - /// An entity was deleted. - /// - Delete = 3, - - /// - /// A list of entities was retrieved. - /// - List = 4, - - /// - /// Configuration was changed. - /// - Configure = 5, - - /// - /// An authentication operation was performed. - /// - Authenticate = 6, - - /// - /// A sync operation was performed. - /// - Sync = 7, - - /// - /// An export operation was performed. - /// - Export = 8, - - /// - /// An import operation was performed. - /// - Import = 9 -} +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/AuditOperationType.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/AuditOperationType.cs new file mode 100644 index 00000000..cde47f6c --- /dev/null +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/AuditOperationType.cs @@ -0,0 +1,57 @@ +namespace AdGuard.DataAccess.Entities; + +/// +/// Represents the type of audit operation. +/// +public enum AuditOperationType +{ + /// + /// An entity was created. + /// + Create = 0, + + /// + /// An entity was read/retrieved. + /// + Read = 1, + + /// + /// An entity was updated. + /// + Update = 2, + + /// + /// An entity was deleted. + /// + Delete = 3, + + /// + /// A list of entities was retrieved. + /// + List = 4, + + /// + /// Configuration was changed. + /// + Configure = 5, + + /// + /// An authentication operation was performed. + /// + Authenticate = 6, + + /// + /// A sync operation was performed. + /// + Sync = 7, + + /// + /// An export operation was performed. + /// + Export = 8, + + /// + /// An import operation was performed. + /// + Import = 9 +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/SettingsValueType.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/SettingsValueType.cs new file mode 100644 index 00000000..c9fb20ff --- /dev/null +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/SettingsValueType.cs @@ -0,0 +1,42 @@ +namespace AdGuard.DataAccess.Entities; + +/// +/// Represents the data type of a settings value. +/// +public enum SettingsValueType +{ + /// + /// A string value. + /// + String = 0, + + /// + /// An integer value. + /// + Integer = 1, + + /// + /// A boolean value. + /// + Boolean = 2, + + /// + /// A decimal/double value. + /// + Decimal = 3, + + /// + /// A DateTime value. + /// + DateTime = 4, + + /// + /// A JSON-serialized object. + /// + Json = 5, + + /// + /// An encrypted string value. + /// + EncryptedString = 6 +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/StatisticsEntity.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/StatisticsEntity.cs index 8d8ce5b5..fac554d8 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/StatisticsEntity.cs +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/StatisticsEntity.cs @@ -89,30 +89,4 @@ public class StatisticsEntity /// Gets or sets when this record was last synced from the API. /// public DateTime? SyncedAt { get; set; } -} - -/// -/// Represents the time granularity for statistics aggregation. -/// -public enum StatisticsGranularity -{ - /// - /// Statistics aggregated by hour. - /// - Hourly = 0, - - /// - /// Statistics aggregated by day. - /// - Daily = 1, - - /// - /// Statistics aggregated by week. - /// - Weekly = 2, - - /// - /// Statistics aggregated by month. - /// - Monthly = 3 -} +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/StatisticsGranularity.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/StatisticsGranularity.cs new file mode 100644 index 00000000..38eb6234 --- /dev/null +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/StatisticsGranularity.cs @@ -0,0 +1,27 @@ +namespace AdGuard.DataAccess.Entities; + +/// +/// Represents the time granularity for statistics aggregation. +/// +public enum StatisticsGranularity +{ + /// + /// Statistics aggregated by hour. + /// + Hourly = 0, + + /// + /// Statistics aggregated by day. + /// + Daily = 1, + + /// + /// Statistics aggregated by week. + /// + Weekly = 2, + + /// + /// Statistics aggregated by month. + /// + Monthly = 3 +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/UserSettingsEntity.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/UserSettingsEntity.cs index b5f0069b..3b0b6649 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/UserSettingsEntity.cs +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Entities/UserSettingsEntity.cs @@ -54,45 +54,4 @@ public class UserSettingsEntity /// Gets or sets when this setting was last modified. /// public DateTime ModifiedAt { get; set; } = DateTime.UtcNow; -} - -/// -/// Represents the data type of a settings value. -/// -public enum SettingsValueType -{ - /// - /// A string value. - /// - String = 0, - - /// - /// An integer value. - /// - Integer = 1, - - /// - /// A boolean value. - /// - Boolean = 2, - - /// - /// A decimal/double value. - /// - Decimal = 3, - - /// - /// A DateTime value. - /// - DateTime = 4, - - /// - /// A JSON-serialized object. - /// - Json = 5, - - /// - /// An encrypted string value. - /// - EncryptedString = 6 -} +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Extensions/DataAccessOptions.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Extensions/DataAccessOptions.cs index f73f6af1..f818a097 100644 --- a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Extensions/DataAccessOptions.cs +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Extensions/DataAccessOptions.cs @@ -64,30 +64,4 @@ public class DataAccessOptions /// Gets or sets the compilation history retention in days. /// public int CompilationHistoryRetentionDays { get; set; } = 180; -} - -/// -/// Supported database providers. -/// -public enum DatabaseProvider -{ - /// - /// SQLite database provider. - /// - Sqlite, - - /// - /// SQL Server database provider. - /// - SqlServer, - - /// - /// PostgreSQL database provider. - /// - PostgreSql, - - /// - /// In-memory database provider (for testing). - /// - InMemory -} +} \ No newline at end of file diff --git a/src/adguard-api-dotnet/src/AdGuard.DataAccess/Extensions/DatabaseProvider.cs b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Extensions/DatabaseProvider.cs new file mode 100644 index 00000000..6fd195d1 --- /dev/null +++ b/src/adguard-api-dotnet/src/AdGuard.DataAccess/Extensions/DatabaseProvider.cs @@ -0,0 +1,27 @@ +namespace AdGuard.DataAccess.Extensions; + +/// +/// Supported database providers. +/// +public enum DatabaseProvider +{ + /// + /// SQLite database provider. + /// + Sqlite, + + /// + /// SQL Server database provider. + /// + SqlServer, + + /// + /// PostgreSQL database provider. + /// + PostgreSql, + + /// + /// In-memory database provider (for testing). + /// + InMemory +} \ No newline at end of file diff --git a/src/adguard-validation/README.md b/src/adguard-validation/README.md index 823c5ee8..67f9c615 100644 --- a/src/adguard-validation/README.md +++ b/src/adguard-validation/README.md @@ -34,9 +34,10 @@ This library provides a unified, high-performance validation layer that can be u └────────────────┬────────────────────────────────┘ │ ▼ -┌─────────────────────────────────────────────────┐ -│ @adguard/hostlist-compiler │ -└─────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────┐ +│ @jk-com/adblock-compiler │ +│ (via wrapper/CLI) │ +└──────────────────────────────────────────────┘ ``` ## Building diff --git a/src/rules-compiler-dotnet/README.md b/src/rules-compiler-dotnet/README.md index a0a30d2b..99df5824 100644 --- a/src/rules-compiler-dotnet/README.md +++ b/src/rules-compiler-dotnet/README.md @@ -4,7 +4,7 @@ A .NET 10 library and console application for compiling AdGuard filter rules usi ## Features -- **Full hostlist-compiler support**: All configuration options from the underlying @adguard/hostlist-compiler package +- **Full compilation support**: All configuration options for filter compilation - **Multi-format configuration**: JSON, YAML, and TOML configuration file support - **Configuration validation**: Validates configuration before compilation with detailed error/warning reporting - **Interactive and CLI modes**: Use interactively with menus or from command line with arguments diff --git a/src/rules-compiler-python/README.md b/src/rules-compiler-python/README.md index 1ac37e72..73592fe1 100644 --- a/src/rules-compiler-python/README.md +++ b/src/rules-compiler-python/README.md @@ -1,6 +1,6 @@ # Rules Compiler (Python) -Python API for compiling AdGuard filter rules using `@adguard/hostlist-compiler`. +Python API for compiling AdGuard filter rules. ## Installation @@ -17,9 +17,8 @@ pip install -e ".[dev]" | Requirement | Version | Notes | |-------------|---------|-------| -| Python | 3.9+ | Required | -| Node.js | 18+ | Required for hostlist-compiler | -| hostlist-compiler | Latest | `npm install -g @adguard/hostlist-compiler` | +| Python | 3.9+ | Core language | +| Node.js | 18+ | For compilation engine | ## CLI Usage diff --git a/src/rules-compiler-rust/README.md b/src/rules-compiler-rust/README.md index 475b7ba7..358571c3 100644 --- a/src/rules-compiler-rust/README.md +++ b/src/rules-compiler-rust/README.md @@ -1,6 +1,6 @@ # Rules Compiler (Rust) -Rust API for compiling AdGuard filter rules using `@adguard/hostlist-compiler`. +Rust API for compiling AdGuard filter rules. ## Features @@ -14,9 +14,8 @@ Rust API for compiling AdGuard filter rules using `@adguard/hostlist-compiler`. | Requirement | Version | Notes | |-------------|---------|-------| -| Rust | 1.70+ | Install via rustup | -| Node.js | 18+ | Required for hostlist-compiler | -| hostlist-compiler | Latest | `npm install -g @adguard/hostlist-compiler` | +| Rust | 1.85+ | Core language | +| Node.js | 18+ | For compilation engine | ## Building diff --git a/src/rules-compiler-typescript/COMPILER_INTEGRATION.md b/src/rules-compiler-typescript/COMPILER_INTEGRATION.md new file mode 100644 index 00000000..24d09a00 --- /dev/null +++ b/src/rules-compiler-typescript/COMPILER_INTEGRATION.md @@ -0,0 +1,135 @@ +# Compiler Integration + +## Overview + +The TypeScript rules compiler now uses the modern JSR-based `@jk-com/adblock-compiler` package for all compilation tasks. + +## Architecture + +### Compiler Adapter (`src/lib/compiler-adapter.ts`) + +The `compiler-adapter.ts` module provides automatic fallback logic with lazy initialization: + +1. **Lazy Loading**: Compiler is loaded on first use, not at module import time +2. **Primary**: Attempts to load `@jk-com/adblock-compiler` from JSR +3. **Fallback**: Falls back to `@adguard/hostlist-compiler` from npm if JSR fails +4. **Logging**: Logs which compiler is being used when initialized + +```typescript +import { compile, getFilterCompiler, getCompilerInfo } from './lib/compiler-adapter.ts'; + +// Check which compiler is active (triggers lazy initialization if not yet loaded) +const info = await getCompilerInfo(); +console.log(`Using ${info.source} package: ${info.package}`); +``` + +**Key Design Decision**: The adapter uses lazy initialization instead of top-level await to prevent blocking module imports. This ensures fast startup and deferred loading until the compiler is actually needed. + +## Benefits of JSR Package + +The `@jk-com/adblock-compiler@^0.6.0` package includes: + +✅ **SOLID Principles**: Refactored codebase following Single Responsibility, Open/Closed, etc. +✅ **Dependency Injection**: All components use DI for testability +✅ **Modern TypeScript**: Full type safety and modern patterns +✅ **Comprehensive Error Handling**: Descriptive errors with context +✅ **Performance Optimizations**: Improved pattern matching and processing +✅ **Better Documentation**: Full JSDoc coverage +✅ **Trace Logging**: Additional debug level for troubleshooting + +## API Compatibility + +- ✅ Standard `IConfiguration` interface +- ✅ Standard `compile()` function signature +- ✅ Drop-in replacement for filter compilation needs + +## Usage + +### Basic Compilation + +```typescript +import { compile } from './lib/compiler-adapter.ts'; +import type { IConfiguration } from './lib/compiler-adapter.ts'; + +const config: IConfiguration = { + name: 'My Filter List', + sources: [ + { + source: 'https://example.com/rules.txt', + type: 'adblock', + }, + ], + transformations: ['RemoveComments', 'Deduplicate'], +}; + +const rules = await compile(config); +console.log(`Compiled ${rules.length} rules`); +``` + +### Using FilterCompiler Class + +```typescript +import { getFilterCompiler } from './lib/compiler-adapter.ts'; + +// Get the FilterCompiler class (lazy loads on first call) +const FilterCompiler = await getFilterCompiler(); +const compiler = new FilterCompiler(logger); +const result = await compiler.compile(config); +``` + +### Check Active Compiler + +```typescript +import { getCompilerInfo } from './lib/compiler-adapter.ts'; + +// This will trigger lazy initialization if compiler not yet loaded +const { source, package: pkg } = await getCompilerInfo(); +console.log(`Active compiler: ${pkg} (${source})`); +``` + +## Migration Notes + +### For Developers + +Import from `./lib/compiler-adapter.ts` to use the compiler: + +```typescript +import { compile } from './lib/compiler-adapter.ts'; +``` + +### For CI/CD + +The JSR package is used for all compilations. Ensure network access to jsr.io is available. + +## Troubleshooting + +### JSR Package Not Loading + +If the package fails to load: + +1. Check internet connectivity to jsr.io +2. Verify `deno.json` has the import configured +3. Run `deno cache --reload src/compiler.ts` +4. Check Deno cache status: `deno cache --reload` + +## Version History + +- **v0.6.0** (2026-01-01): Initial JSR integration with Phase 1 SOLID refactoring + - SOLID-compliant interfaces + - 8 new classes following SRP + - Full dependency injection support + - Comprehensive error handling + +## Links + +- JSR Package: https://jsr.io/@jk-com/adblock-compiler +- Source Code: https://github.com/jaypatrick/hostlistcompiler +- Issue Tracker: https://github.com/jaypatrick/hostlistcompiler/issues + +## Future Enhancements + +Phase 2 refactoring (planned): +- Factory pattern implementations +- Complete DI integration +- Remove duplicate code +- Enhanced testing infrastructure diff --git a/src/rules-compiler-typescript/README.md b/src/rules-compiler-typescript/README.md index 2171c85a..6a40e679 100644 --- a/src/rules-compiler-typescript/README.md +++ b/src/rules-compiler-typescript/README.md @@ -73,7 +73,7 @@ deno task start -- --version ### Chunked Parallel Compilation -For large rule lists (e.g., 10+ million entries), the single-threaded `@adguard/hostlist-compiler` can be slow. The chunking feature splits compilation into parallel chunks: +For large rule lists (e.g., 10+ million entries), chunking splits compilation into parallel chunks for improved performance: **Command-line usage:** ```bash diff --git a/src/rules-compiler-typescript/deno.json b/src/rules-compiler-typescript/deno.json index aab5f7c2..86b80970 100644 --- a/src/rules-compiler-typescript/deno.json +++ b/src/rules-compiler-typescript/deno.json @@ -31,7 +31,7 @@ "node:crypto": "node:crypto", "yaml": "npm:yaml@^2.8.2", "@iarna/toml": "npm:@iarna/toml@^2.2.5", - "@adguard/hostlist-compiler": "npm:@adguard/hostlist-compiler@^1.0.39", + "@jk-com/adblock-compiler": "jsr:@jk-com/adblock-compiler@^0.6.0", "chalk": "npm:chalk@^5.6.2", "cli-table3": "npm:cli-table3@^0.6.5", "ora": "npm:ora@^9.0.0", diff --git a/src/rules-compiler-typescript/src/chunking.test.ts b/src/rules-compiler-typescript/src/chunking.test.ts index 8c15174f..01800825 100644 --- a/src/rules-compiler-typescript/src/chunking.test.ts +++ b/src/rules-compiler-typescript/src/chunking.test.ts @@ -4,7 +4,7 @@ */ import { assertEquals } from 'https://deno.land/std@0.220.0/assert/mod.ts'; -import type { IConfiguration } from '@adguard/hostlist-compiler'; +import type { IConfiguration } from '@jk-com/adblock-compiler'; import { DEFAULT_CHUNKING_CONFIG, mergeChunks, diff --git a/src/rules-compiler-typescript/src/chunking.ts b/src/rules-compiler-typescript/src/chunking.ts index dc7020ec..be5fc5f9 100644 --- a/src/rules-compiler-typescript/src/chunking.ts +++ b/src/rules-compiler-typescript/src/chunking.ts @@ -3,7 +3,7 @@ * Splits large sources into manageable chunks for parallel processing */ -import type { IConfiguration, ISource } from '@adguard/hostlist-compiler'; +import type { IConfiguration, ISource } from '@jk-com/adblock-compiler'; import type { ChunkingConfig, Logger } from './types.ts'; import { logger as defaultLogger } from './logger.ts'; diff --git a/src/rules-compiler-typescript/src/compiler.ts b/src/rules-compiler-typescript/src/compiler.ts index aec7dddd..dd866bb6 100644 --- a/src/rules-compiler-typescript/src/compiler.ts +++ b/src/rules-compiler-typescript/src/compiler.ts @@ -3,7 +3,7 @@ * Production-ready with timeouts, error handling, and resource limits */ -import compile, { type IConfiguration } from '@adguard/hostlist-compiler'; +import { compile, type IConfiguration } from './lib/compiler-adapter.ts'; import { copyFileSync, existsSync, diff --git a/src/rules-compiler-typescript/src/config-reader.ts b/src/rules-compiler-typescript/src/config-reader.ts index 3f0b454c..d07a5721 100644 --- a/src/rules-compiler-typescript/src/config-reader.ts +++ b/src/rules-compiler-typescript/src/config-reader.ts @@ -7,7 +7,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs'; import { extname, resolve } from 'node:path'; import { parse as parseYaml } from 'yaml'; import { parse as parseToml } from '@iarna/toml'; -import type { IConfiguration } from '@adguard/hostlist-compiler'; +import type { IConfiguration } from '@jk-com/adblock-compiler'; import type { ConfigurationFormat, ExtendedConfiguration, Logger } from './types.ts'; import { logger as defaultLogger } from './logger.ts'; import { ConfigNotFoundError, ConfigParseError, ConfigurationError, ErrorCode } from './errors.ts'; diff --git a/src/rules-compiler-typescript/src/index.ts b/src/rules-compiler-typescript/src/index.ts index 842da2fc..97914a70 100644 --- a/src/rules-compiler-typescript/src/index.ts +++ b/src/rules-compiler-typescript/src/index.ts @@ -2,7 +2,7 @@ * Rules Compiler TypeScript Frontend * * A TypeScript API and CLI for compiling AdGuard filter rules - * using @adguard/hostlist-compiler. + * using @jk-com/adblock-compiler. * * Production-ready with: * - Custom error classes with error codes diff --git a/src/rules-compiler-typescript/src/lib/compiler-adapter.ts b/src/rules-compiler-typescript/src/lib/compiler-adapter.ts new file mode 100644 index 00000000..c18834ce --- /dev/null +++ b/src/rules-compiler-typescript/src/lib/compiler-adapter.ts @@ -0,0 +1,154 @@ +/** + * Compiler adapter that tries the new JSR package first, with fallback to AdGuard npm package + * + * This adapter uses lazy initialization to avoid blocking module imports with top-level await. + * The compiler is loaded on first use, not at module load time. + */ + +/** + * Type definitions for compiler source + */ +type CompilerSource = 'jsr' | 'npm'; + +/** + * Compiler function signature (compatible with both packages) + */ +type CompilerFunction = (config: unknown) => Promise; + +/** + * FilterCompiler class constructor signature (compatible with both packages) + */ +type FilterCompilerConstructor = new (...args: unknown[]) => unknown; + +/** + * Compiler module state + */ +interface CompilerModule { + FilterCompiler: FilterCompilerConstructor; + compile: CompilerFunction; + source: CompilerSource; +} + +/** + * Cached compiler module instance + */ +let compilerModule: CompilerModule | null = null; + +/** + * Promise for ongoing initialization (prevents multiple simultaneous loads) + */ +let initPromise: Promise | null = null; + +/** + * Initialize the compiler by attempting to load JSR package first, then npm fallback + * This function is called lazily on first use, not at module load time + */ +async function initializeCompiler(): Promise { + // Return cached module if already initialized + if (compilerModule) { + return compilerModule; + } + + // If initialization is in progress, wait for it + if (initPromise) { + return initPromise; + } + + // Start initialization + initPromise = (async () => { + try { + // Try JSR package first + const jsrModule = await import('@jk-com/adblock-compiler'); + const module: CompilerModule = { + FilterCompiler: jsrModule.FilterCompiler as FilterCompilerConstructor, + compile: jsrModule.compile as CompilerFunction, + source: 'jsr', + }; + console.log('[Compiler] Using JSR package: @jk-com/adblock-compiler@^0.6.0'); + compilerModule = module; + return module; + } catch (jsrError) { + console.warn('[Compiler] JSR package failed, falling back to npm:', jsrError); + + try { + // Fallback to npm package + const npmModule = await import('@adguard/hostlist-compiler'); + const module: CompilerModule = { + FilterCompiler: npmModule.FilterCompiler as FilterCompilerConstructor, + compile: npmModule.compile as CompilerFunction, + source: 'npm', + }; + console.log('[Compiler] Using npm package: @adguard/hostlist-compiler'); + compilerModule = module; + return module; + } catch (npmError) { + throw new Error( + `Failed to load compiler from both sources:\nJSR: ${jsrError}\nnpm: ${npmError}`, + ); + } + } finally { + // Clear the promise once initialization completes + initPromise = null; + } + })(); + + return initPromise; +} + +/** + * Get information about which compiler is being used + * If the compiler hasn't been initialized yet, this will trigger initialization + */ +export async function getCompilerInfo(): Promise<{ source: CompilerSource; package: string }> { + const module = await initializeCompiler(); + return { + source: module.source, + package: module.source === 'jsr' + ? '@jk-com/adblock-compiler@^0.6.0' + : '@adguard/hostlist-compiler', + }; +} + +/** + * Compile function with lazy initialization + * This ensures the compiler is loaded only when first used + */ +export async function compile(config: unknown): Promise { + const module = await initializeCompiler(); + return module.compile(config); +} + +/** + * Get FilterCompiler class with lazy initialization + * This ensures the compiler is loaded only when first used + */ +export async function getFilterCompiler(): Promise { + const module = await initializeCompiler(); + return module.FilterCompiler; +} + +/** + * Re-export types conditionally based on which package is loaded + * + * NOTE: We export types from JSR package as the canonical source since it has + * the most complete type definitions. The npm package (@adguard/hostlist-compiler) + * is fully compatible with these types as it shares the same API surface. + * + * If you need to ensure type compatibility at runtime, use the getCompilerInfo() + * function to determine which package is loaded and handle accordingly. + */ +export type { + IBasicLogger, + IConfiguration, + IDetailedLogger, + IDownloader, + IFileSystem, + IFilterable, + IHttpClient, + ILogger, + ISource, + ITransformable, + IValidationResult, + SourceType, + TransformationType, +} from '@jk-com/adblock-compiler'; diff --git a/src/rules-compiler-typescript/src/lib/configuration-builder.ts b/src/rules-compiler-typescript/src/lib/configuration-builder.ts index 77d9913c..37eaae73 100644 --- a/src/rules-compiler-typescript/src/lib/configuration-builder.ts +++ b/src/rules-compiler-typescript/src/lib/configuration-builder.ts @@ -26,7 +26,7 @@ * ``` */ -import type { IConfiguration } from '@adguard/hostlist-compiler'; +import type { IConfiguration } from '@jk-com/adblock-compiler'; /** * Available transformation types @@ -282,7 +282,7 @@ export class ConfigurationBuilder { /** * Build the configuration object - * @returns IConfiguration compatible with @adguard/hostlist-compiler + * @returns IConfiguration compatible with @jk-com/adblock-compiler */ build(): IConfiguration { if (this.sources.length === 0) { diff --git a/src/rules-compiler-typescript/src/lib/rules-compiler.ts b/src/rules-compiler-typescript/src/lib/rules-compiler.ts index 9ab3fe51..460f9012 100644 --- a/src/rules-compiler-typescript/src/lib/rules-compiler.ts +++ b/src/rules-compiler-typescript/src/lib/rules-compiler.ts @@ -24,7 +24,7 @@ * ``` */ -import type { IConfiguration } from '@adguard/hostlist-compiler'; +import type { IConfiguration } from '@jk-com/adblock-compiler'; import type { CompilerResult, ConfigurationFormat, diff --git a/src/rules-compiler-typescript/src/parallel-compiler.ts b/src/rules-compiler-typescript/src/parallel-compiler.ts index 363d72d2..49886326 100644 --- a/src/rules-compiler-typescript/src/parallel-compiler.ts +++ b/src/rules-compiler-typescript/src/parallel-compiler.ts @@ -1,9 +1,9 @@ /** * Parallel compilation using Deno workers for chunked rule compilation - * Enables multi-threaded compilation to work around single-threaded @adguard/hostlist-compiler + * Enables multi-threaded compilation for large filter lists */ -import compile, { type IConfiguration } from '@adguard/hostlist-compiler'; +import compile, { type IConfiguration } from '@jk-com/adblock-compiler'; import type { Logger } from './types.ts'; import type { ChunkedConfiguration } from './chunking.ts'; import { logger as defaultLogger } from './logger.ts'; diff --git a/src/rules-compiler-typescript/src/types.ts b/src/rules-compiler-typescript/src/types.ts index 77a4813a..2d2f6661 100644 --- a/src/rules-compiler-typescript/src/types.ts +++ b/src/rules-compiler-typescript/src/types.ts @@ -2,7 +2,7 @@ * Type definitions for the Rules Compiler TypeScript Frontend */ -import type { IConfiguration } from '@adguard/hostlist-compiler'; +import type { IConfiguration } from '@jk-com/adblock-compiler'; /** * Supported configuration file formats diff --git a/src/rules-compiler-typescript/src/validation.ts b/src/rules-compiler-typescript/src/validation.ts index e226bcf0..87f2894b 100644 --- a/src/rules-compiler-typescript/src/validation.ts +++ b/src/rules-compiler-typescript/src/validation.ts @@ -4,7 +4,7 @@ */ import { isAbsolute, normalize, resolve } from 'node:path'; -import type { IConfiguration } from '@adguard/hostlist-compiler'; +import type { IConfiguration } from '@jk-com/adblock-compiler'; import { ConfigurationError, ErrorCode, @@ -115,7 +115,7 @@ function validateSource(source: unknown, index: number): string[] { } /** - * Valid transformation names from @adguard/hostlist-compiler + * Valid transformation names from @jk-com/adblock-compiler */ const VALID_TRANSFORMATIONS = [ 'RemoveComments', diff --git a/src/shell/zsh/README.md b/src/shell/zsh/README.md index 39b3fbd9..8afbe095 100644 --- a/src/shell/zsh/README.md +++ b/src/shell/zsh/README.md @@ -4,7 +4,7 @@ Zsh-specific implementation of the AdGuard filter rules compiler. ## Overview -This script provides a Z Shell (zsh) interface to the `@adguard/hostlist-compiler` CLI tool, with zsh-specific optimizations and modern shell features. +This script provides a Z Shell (zsh) interface to the filter compilation CLI tool, with zsh-specific optimizations and modern shell features. ## Features @@ -188,10 +188,6 @@ Uses zsh options: ### Required - **Zsh** 5.0 or later (check with `zsh --version`) - **Node.js** 18 or later -- **@adguard/hostlist-compiler**: - ```zsh - npm install -g @adguard/hostlist-compiler - ``` ### Optional (for YAML/TOML) - **yq** - YAML processor: @@ -254,14 +250,11 @@ chmod +x compile-rules.zsh which zsh ``` -### "command not found: hostlist-compiler" +### "command not found: compilation tool" ```zsh -# Install globally -npm install -g @adguard/hostlist-compiler - -# Verify installation -which hostlist-compiler -hostlist-compiler --version +# Ensure Node.js is installed +which node +node --version ``` ### YAML parsing issues diff --git a/src/website/src/pages/getting-started.js b/src/website/src/pages/getting-started.js index c9f55b79..cf69df4b 100644 --- a/src/website/src/pages/getting-started.js +++ b/src/website/src/pages/getting-started.js @@ -76,7 +76,7 @@ const GettingStartedPage = () => {

All compilers also need{" "} - @adguard/hostlist-compiler installed. + @jk-com/adblock-compiler installed.