@adguard/filters-compiler 3.2.8 → 3.2.10-beta.0

package/README.md

@@ -1,119 +1,255 @@
 # AdGuard Filters Compiler
 
-Filters compiler package is a tool for compiling ad blocking filters into a supported format.
-It is used in [FiltersRegistry].
-
-- [Usage](#usage)
-- [Tests](#tests)
-- [Development](#development)
-    - [Schemas maintenance](#schemas-maintenance)
-- [Filters metadata](#filters-metadata)
+> A Node.js library that compiles, converts, validates, and optimizes
+> ad-blocking filter lists into platform-specific formats for AdGuard
+> products across all supported platforms.
+
+> **Note:** This package is developed in [AdGuardSoftwareLimited/ext-compiler].
+> The [AdguardTeam/FiltersCompiler] repository is a public mirror.
+
+## Description
+
+**AdGuard Filters Compiler** is a library for developers who maintain
+ad-blocking filter lists and the build pipelines that ship them. It
+transforms source filter lists — written in the AdGuard filter rules
+syntax — into compiled output tailored to each target platform (browser
+extensions, desktop and mobile apps, and the AdGuard CLI).
+
+AdGuard's filter rules are authored once but must run on many engines
+with different capabilities: not every platform supports scriptlets,
+HTML filtering, `$redirect` modifiers, extended CSS, or regex-based
+`$domain` selectors. The compiler closes that gap. It resolves
+`@include` and `!#include` preprocessor directives, converts rules
+between AdGuard and uBlock Origin formats, validates each rule against
+the `@adguard/tsurlfilter` engine, optimizes blocking rules using
+hit-count statistics, and strips rules that a given platform cannot
+apply.
+
+The library is consumed by [FiltersRegistry] to produce production
+filter builds, but it can be used directly by anyone who needs to
+compile filter lists for AdGuard platforms. The expected source
+directory structure and the filters metadata format are documented in
+the [FiltersRegistry README][filters-metadata].
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Overview](#api-overview)
+- [Usage Examples](#usage-examples)
+    - [Compiling filter lists](#compiling-filter-lists)
+    - [Validating built filters](#validating-built-filters)
+    - [Validating locale translations](#validating-locale-translations)
 - [`@include` directive and its options](#include-directive)
-- [Logging](#logging)
-- [Additional resources](#additional-resources)
+- [Configuration](#configuration)
+    - [Custom platforms](#custom-platforms)
+    - [Logging](#logging)
+    - [Environment variables](#environment-variables)
+- [Supported platforms](#supported-platforms)
+- [Documentation](#documentation)
 
-## Usage
+---
 
-This package is suggested to be used with filters repository with directory structure presented in tests here.
+## Installation
 
-The package could be run with the following command:
+```bash
+npm install @adguard/filters-compiler
+```
 
-```javascript
-const whitelist = [1, 3];
-const blacklist = [2];
+Also available via pnpm or yarn:
 
-const path = require('path');
-const compiler = require("adguard-filters-compiler");
+```bash
+pnpm add @adguard/filters-compiler
+# or
+yarn add @adguard/filters-compiler
+```
 
-const filtersDir = path.join(__dirname, './filters');
-const logPath = path.join(__dirname, './log.txt');
-const reportPath = path.join(__dirname, './report.txt');
+The package ships as dual ESM + CJS, so both `import` and `require`
+work out of the box.
 
-const platformsPath = path.join(__dirname, './platforms');
+## Quick Start
 
-const customPlatformsConfig = {
-    // Here you can redefine some of the platforms from platforms.json
-    // or add new platforms if you need it.
-    "MAC_V3": {
-        "platform": "mac",
-        "path": "mac_v3",
-        "configuration": {
-            "ignoreRuleHints": false,
-            "removeRulePatterns": [
-                "^\\/.*" // remove regex rules for some reason.
-            ],
-            "replacements": [
-                {
-                    "from": "regex",
-                    "to": "repl"
-                }
-            ]
-        },
-        "defines": {
-            "adguard": true,
-            "adguard_app_mac": true
-        }
-    },
-};
+```js
+import { compile } from '@adguard/filters-compiler';
+
+const filtersDir = './filters';
+const logPath = './log.txt';
+const reportPath = './report.txt';
+const platformsPath = './platforms';
 
-compiler.compile(filtersDir, logPath, reportPath, platformsPath, whitelist, blacklist, customPlatformsConfig);
+// Compile every filter for every platform, keeping only filters
+// with IDs 1 and 3, and excluding filter ID 2.
+await compile(filtersDir, logPath, reportPath, platformsPath, [1, 3], [2]);
 ```
 
-The built filters for the platforms can be validated by schemas.
-And there is `validateJSONSchema()` method for that:
+The compiler reads the source filter lists from `filtersDir` and writes
+platform-specific output to subdirectories under `platformsPath`. A
+human-readable compilation report is written to `reportPath`, and a
+timestamped log to `logPath`.
+
+## API Overview
+
+The library exports three functions:
+
+| Function                  | Purpose                                              |
+| ------------------------- | ---------------------------------------------------- |
+| `compile(...)`            | Compiles filter lists into platform-specific output  |
+| `validateJSONSchema(...)` | Validates built platform output against JSON schemas |
+| `validateLocales(...)`    | Validates locale translation files for completeness  |
+
+### `compile(...)`
+
+```ts
+function compile(
+    path: string,
+    logPath: string | undefined,
+    reportFile: string | undefined,
+    platformsPath: string,
+    whitelist: number[],
+    blacklist: number[],
+    customPlatformsConfig?: CustomPlatformsConfig,
+): Promise<void>;
+```
+
+Compiles the filter lists in `path` for all configured platforms and
+writes the results to `platformsPath`.
+
+- `whitelist` — compile only the filter IDs listed here (empty array
+  compiles all filters).
+- `blacklist` — exclude the filter IDs listed here.
+- `customPlatformsConfig` — overrides or extends the built-in platform
+  definitions (see [Custom platforms](#custom-platforms)).
 
-```javascript
-const compiler = require("adguard-filters-compiler");
+### `validateJSONSchema(...)`
 
-const validationResult = compiler.validateJSONSchema(<platformsPath>, <FILTERS_REQUIRED_AMOUNT>);
+```ts
+function validateJSONSchema(
+    platformsPath: string,
+    requiredFiltersAmount: number,
+): boolean;
 ```
 
-where `<platformsPath>` is the path to the platforms directory
-and `<FILTERS_REQUIRED_AMOUNT>` is an expected minimum number of filters.
+Recursively validates the built JSON files in `platformsPath` against
+the schemas bundled with the library (`filters.schema.json` and
+`filters_i18n.schema.json`). `requiredFiltersAmount` is the minimum
+number of filters expected in each platform's `filters.json`.
 
-## Tests
+Returns `true` when all files are valid. On validation failure it logs
+the errors and returns `false` instead of throwing, so callers must
+check the return value.
 
-```bash
-pnpm test
+### `validateLocales(...)`
+
+```ts
+function validateLocales(
+    localesDirPath: string,
+    requiredLocales: string[],
+): ValidateLocalesResult;
+
+interface ValidateLocalesResult {
+    ok: boolean;
+    data?: unknown[]; // per-locale warning details, present when warnings exist
+    log?: string;     // formatted warnings log, present when warnings exist
+}
 ```
 
-## Development
+Validates that the locale files in `localesDirPath` are complete — that
+every filter, group, and tag has a translated name and description for
+all locales listed in `requiredLocales`.
 
-> No new fields should be added to the metadata files for old `mac` and current `mac_v2` platforms,
-> check [generator.js](./src/main/platforms/generator.js) for more details.
+Returns `{ ok: true }` when no problems are found. When warnings are
+found, `data` and `log` contain the per-locale details and `ok` is
+`false` only if at least one warning is critical. Throws when the
+locales directory is missing or empty.
 
-In order to add support for new scriptlets and redirects,
-you should update `@adguard/tsurlfilter` with updated scriptlets.
+## Usage Examples
 
-For fixing scriptlets converting or validation you should update `@adguard/scriptlets`.
+### Compiling filter lists
 
-### Schemas maintenance
+Compile all filters with the default platform configuration:
 
-Schemas which are used for `validateJSONSchema()` method are located in `schemas/` directory:
+```js
+import { compile } from '@adguard/filters-compiler';
 
-- `filters.schema.json` — schema for *filters* metadata;
-- `filters_i18n.schema.json` — schema for *filters_i18n* metadata.
+await compile(
+    './filters',      // source filter lists
+    './log.txt',      // log file (omit to disable logging)
+    './report.txt',   // compilation report
+    './platforms',    // platform output directory
+    [],               // whitelist (empty = compile all)
+    [],               // blacklist (empty = exclude none)
+);
+```
 
-> Schemas in `schemas/mac/` directory are needed for legacy macOS v1 platform, so they should not be changed.
-> The same is true for `schemas/mac_v2/` directory.
+Compile a single filter into a custom platform:
 
-If any changes should be made in the schemas, e.g. adding a new locale or filter or tag,
-**never edit them directly in `schemas/` manually**.
+```js
+import { compile } from '@adguard/filters-compiler';
 
-Instead of that, you should edit scripts in `tasks/build-schemas/` directory
-and use the following command to generate the schemas:
+const customPlatformsConfig = {
+    // Here you can redefine some of the platforms from platforms.json
+    // or add new platforms if you need it.
+    MAC_V3: {
+        platform: 'mac',
+        path: 'mac_v3',
+        configuration: {
+            ignoreRuleHints: false,
+            removeRulePatterns: [
+                '^\\/.*', // drop regex rules
+            ],
+            replacements: [
+                { from: 'regex', to: 'repl' },
+            ],
+        },
+        defines: {
+            adguard: true,
+            adguard_app_mac: true,
+        },
+    },
+};
 
-```bash
-pnpm build-schemas
+await compile(
+    './filters',
+    undefined,          // no log file
+    './report.txt',
+    './platforms',
+    [1],                // only filter ID 1
+    [],
+    customPlatformsConfig,
+);
 ```
 
-## Filters metadata
+### Validating built filters
+
+After compiling, validate the built output against the bundled schemas:
 
-Description of the filters metadata is available in the [FiltersRegistry][filters-metadata] repository.
+```js
+import { validateJSONSchema } from '@adguard/filters-compiler';
+
+// Each platform build must contain at least 50 filters
+const valid = validateJSONSchema('./platforms', 50);
+if (!valid) {
+    throw new Error('Schema validation failed, see log for details');
+}
+```
+
+### Validating locale translations
+
+```js
+import { validateLocales } from '@adguard/filters-compiler';
+
+const result = validateLocales('./locales', ['en', 'fr', 'ko']);
+if (!result.ok) {
+    console.error(result.log);
+}
+```
 
 ## <a name="include-directive"></a> `@include` directive and its options
 
-The `@include` directive provides the ability to include content from the specified address.
+The `@include` directive provides the ability to include content from
+the specified address. Filter source files use it to pull in content
+from other files or remote URLs during compilation, letting you compose
+filter lists from shared fragments.
 
 ### Syntax
 
@@ -121,152 +257,187 @@ The `@include` directive provides the ability to include content from the specif
 @include <filepath> [<options>]
 ```
 
-where:
-
-- `<filepath>` — required, URL or same origin relative file path to be included;
-- `<options>` — optional, a list of options separated by spaces.
-  Available options:
-
-    - `/stripComments` removes AdBlock-style syntax comments from the included file — lines which start with `!`;
-    - `/notOptimized` adds a `!+ NOT_OPTIMIZED` hint to the rules;
-    - `/exclude="<filepath>"` excludes from the included file rules
-      listed in the exceptions file available by `filepath`;
-    - `/addModifiers="<modifiers>"` adds the specified `modifiers` (string as is) to the rules in the included file.
-      The addModifiers option can also work with the host-rule format files.
-      In this case, host-file comments are to be replaced `#` by AdBlock-style syntax comments `!`;
-    - `/ignoreTrustLevel` disables the check of the trust level of the included file.
-      Allowed only for the same origin files.
-    - `/optimizeDomainBlockingRules` remove redundant rules for domain blocking of the included file.
-      Base rules with modifiers and rules of other format will be ignored.
-      Comments are not checked separately and may not be relevant after optimization.
+- `<filepath>` — required, URL or same-origin relative file path to
+  include.
+- `<options>` — optional, space-separated flags:
+
+    - `/stripComments` — removes AdBlock-style comment lines (starting
+      with `!`) from the included file.
+    - `/notOptimized` — adds a `!+ NOT_OPTIMIZED` hint to the rules.
+    - `/exclude="<filepath>"` — excludes rules listed in the exception
+      file at `filepath`.
+    - `/addModifiers="<modifiers>"` — appends the given modifiers (as
+      is) to every rule in the included file. Works with host-rule
+      files too, converting `#` host-file comments to `!` AdBlock-style
+      comments.
+    - `/ignoreTrustLevel` — skips the trust-level check for the
+      included file. Only allowed for same-origin files.
+    - `/optimizeDomainBlockingRules` — removes redundant
+      domain-blocking rules. Rules with modifiers and rules of other
+      formats are ignored.
 
 > [!IMPORTANT]
-> The content of the included file is formatted by the options due to the order of their mention in the directive,
-> except `/ignoreTrustLevel`.
+> Options are applied in the order they appear in the directive, except
+> `/ignoreTrustLevel`.
 
 ### Examples
 
-- Include a file with domains, add modifiers to the rules, exclude some rules,
-   add a hint to the rules, and remove comments from the prepared rules:
-
-    ```adblock
-    @include ../input.txt /addModifiers="script" /exclude="../exclusions.txt" /notOptimized /stripComments /optimizeDomainBlockingRules
-    ```
-
-    The order of execution of the options is as follows:
+Apply all options to an included file:
 
-    1. `@include ../input.txt`: Includes the content of the file named `input.txt` from the parent directory.
-
-        ```adblock
-        # comment
-        example.com
-        example.org
-        ```
-
-    1. `/addModifiers="script"`: Adds the `$script` modifier to all rules in the included file.
-
-        Result of adding modifiers:
+<!-- markdownlint-disable line-length -->
+```adblock
+@include ../input.txt /addModifiers="script" /exclude="../exclusions.txt" /notOptimized /stripComments /optimizeDomainBlockingRules
+```
+<!-- markdownlint-enable line-length -->
 
-        ```adblock
-        ! comment
-        example.com$script
-        example.org$script
-        ```
+Given `../input.txt`:
 
-        > Used to restrict rules with modifiers when blocking the entire domain would result in a breakage.
-        > [issue example](https://github.com/AdguardTeam/FiltersCompiler/issues/190)
+```adblock
+# comment
+example.com
+example.org
+```
 
-    1. `/exclude="../exclusions.txt"`: Excludes rules listed in the exception list from the file named `exclusions.txt`, if they match.
+**1. `/addModifiers="script"`** appends `$script` to every rule and
+converts host-file `#` comments to AdBlock-style `!`:
 
-        Due to the content of `exclusions.txt`:
+```adblock
+! comment
+example.com$script
+example.org$script
+```
 
-        ```adblock
-        example.com$script
-        example2.com$script
-        ```
+**2. `/exclude="../exclusions.txt"`** removes rules listed in
+`exclusions.txt` (for example, `example.com$script`):
 
-        Result of excluding:
+```adblock
+! comment
+example.org$script
+```
 
-        ```adblock
-        ! comment
-        example.org$script
-        ```
+**3. `/notOptimized`** adds the hint:
 
-        > Used to exclude problematic rules in the filter
+```adblock
+! comment
+!+ NOT_OPTIMIZED
+example.org$script
+```
 
-    1. `/notOptimized`: Adds the `!+ NOT_OPTIMIZED` hint to the rules.
+**4. `/stripComments`** removes comment lines:
 
-        Result of adding the hint:
+```adblock
+!+ NOT_OPTIMIZED
+example.org$script
+```
 
-        ```adblock
-        ! comment
-        !+ NOT_OPTIMIZED
-        example.org$script
-        ```
+**5. `/optimizeDomainBlockingRules`** removes redundant domain-blocking
+rules. For example, when `||sub.example.com^` is already covered by
+`||example.com^`, it is dropped, while rules with modifiers such as
+`||test.com^$script` are kept:
 
-        > Used in cases where the filter is designed for mobile site layout and some rules may be removed,
-        > due to the lack of ability to collect statistics on mobile platforms.
+```adblock
+||example.com^
+||domain.com^
+||test.com^$script
+```
 
-    1. `/stripComments`: Removes comments in AdBlock style from the included file.
+Include a remote file with comment stripping:
 
-        ```adblock
-        !+ NOT_OPTIMIZED
-        example.org$script
-        ```
+```adblock
+@include "https://easylist.github.io/easylist/easylist.txt" /stripComments
+```
 
-    1. `/optimizeDomainBlockingRules`: Remove only domain blocking redundant rules from the included file.
+Skip the trust-level check for a same-origin included file:
 
-        Due to the optimization:
+```adblock
+@include ./input.txt /ignoreTrustLevel
+```
 
-        ```adblock
-        ||example.com^
-        ||sub.example.com^
-        ||domain.com^
-        ||test.com^$script
-        ```
+## Configuration
 
-        Result of optimization:
+### Custom platforms
 
-        ```adblock
-        ||example.com^
-        ||domain.com^
-        ||test.com^$script
-        ```
+Pass `customPlatformsConfig` to `compile()` to redefine existing
+platforms or add new ones. Each entry mirrors the structure in
+`src/main/platforms-config.js`:
 
-- Ignore the trust level of the filter list (specified in the metadata) during the file including —
-  include the file rules as is:
+```js
+const customPlatformsConfig = {
+    MAC_V3: {
+        platform: 'mac',           // platform family
+        path: 'mac_v3',            // output subdirectory under platformsPath
+        expires: '12 hours',       // optional cache TTL written to metadata
+        configuration: {
+            ignoreRuleHints: false, // honour `!+ HINT` hints when false
+            removeRulePatterns: [   // regexes of rules to drop
+                '^\\/.*',
+            ],
+            replacements: [        // regex replacements applied to rules
+                { from: 'regex', to: 'repl' },
+            ],
+        },
+        defines: {                  // !#if preprocessor flags for this platform
+            adguard: true,
+            adguard_app_mac: true,
+        },
+    },
+};
+```
 
-    ```adblock
-    @include ./input.txt /ignoreTrustLevel
-    ```
+`replacements[].from` is treated as a regular-expression pattern (it is
+passed to `new RegExp(from, 'g')`), not as literal text. Escape regex
+metacharacters in `from` when a literal match is intended.
 
-## Logging
+### Logging
 
-In order for the compiler to write logs, you need to pass `logPath` to the `compile` function as the second argument:
+The compiler writes a timestamped log file when `logPath` is passed to
+`compile()`. If `logPath` is omitted, no log file is written. The parent
+directory is created automatically when it does not exist.
 
-```javascript
-compile = (path, logPath, reportFile, platformsPath, whitelist, blacklist, customPlatformsConfig)
-```
+Log levels:
 
-If the `logPath` argument is not passed, the log file will not be written. If the directory with the file does not exist, it will be created.
+- `INFO` — general information about the process
+- `WARN` — warnings that do not stop the process
+- `ERROR` — errors indicating failures
 
-### Log Levels
+### Environment variables
 
-The logger supports the following log levels:
+| Variable | Default           | Purpose                                                                                           |
+| -------- | ----------------- | ------------------------------------------------------------------------------------------------- |
+| `TLS`    | (system defaults) | Set to `insecure` to bypass TLS certificate verification when downloading external filter sources |
 
-- `INFO`: General information about the process
-- `WARN`: Warning messages that don't stop the process
-- `ERROR`: Error messages indicating failures
+## Supported platforms
 
-### Logger Initialization
+The compiler ships built-in configurations for the following platforms.
+Each writes its output to a subdirectory under `platformsPath`.
 
-The logger is initialized during compilation when a valid `logPath` is provided.
+| Platform ID                         | Output directory                    | Target                                    |
+| ----------------------------------- | ----------------------------------- | ----------------------------------------- |
+| `WINDOWS`                           | `windows`                           | AdGuard for Windows                       |
+| `MAC`                               | `mac`                               | AdGuard for macOS (legacy v1)             |
+| `MAC_V2`                            | `mac_v2`                            | AdGuard for macOS v2                      |
+| `MAC_V3`                            | `mac_v3`                            | AdGuard for macOS v3                      |
+| `ANDROID`                           | `android`                           | AdGuard for Android                       |
+| `IOS`                               | `ios`                               | AdGuard for iOS                           |
+| `CLI`                               | `cli`                               | AdGuard CLI / CoreLibs                    |
+| `EXTENSION_CHROMIUM`                | `extension/chromium`                | AdGuard Browser Extension (Chromium, MV2) |
+| `EXTENSION_CHROMIUM_MV3`            | `extension/chromium-mv3`            | AdGuard Browser Extension (Chromium, MV3) |
+| `EXTENSION_EDGE`                    | `extension/edge`                    | AdGuard Browser Extension (Edge, MV2)     |
+| `EXTENSION_OPERA`                   | `extension/opera`                   | AdGuard Browser Extension (Opera, MV2)    |
+| `EXTENSION_OPERA_MV3`               | `extension/opera-mv3`               | AdGuard Browser Extension (Opera, MV3)    |
+| `EXTENSION_FIREFOX`                 | `extension/firefox`                 | AdGuard Browser Extension (Firefox)       |
+| `EXTENSION_SAFARI`                  | `extension/safari`                  | AdGuard Browser Extension (Safari)        |
+| `EXTENSION_ANDROID_CONTENT_BLOCKER` | `extension/android-content-blocker` | AdGuard content blocker (Android)         |
+| `EXTENSION_UBLOCK`                  | `extension/ublock`                  | uBlock Origin-compatible output           |
 
-## Additional resources
+## Documentation
 
-- [AGENTS.md](AGENTS.md) — AI agent instructions and code guidelines
-- [DEVELOPMENT.md](DEVELOPMENT.md) — Development environment setup guide
-- [CHANGELOG.md](CHANGELOG.md) — Version history
+- [Development](DEVELOPMENT.md) — setup, build, and contributing workflow
+- [Deployment and configuration](DEPLOYMENT.md) — release pipeline and runtime environment
+- [Changelog](CHANGELOG.md) — version history
+- [LLM agent rules](AGENTS.md) — AI-assisted development guidelines
 
 [FiltersRegistry]: https://github.com/AdguardTeam/FiltersRegistry/
 [filters-metadata]: https://github.com/AdguardTeam/FiltersRegistry/blob/master/README.md#filters-metadata
+[AdGuardSoftwareLimited/ext-compiler]: https://github.com/AdGuardSoftwareLimited/ext-compiler
+[AdguardTeam/FiltersCompiler]: https://github.com/AdguardTeam/FiltersCompiler

package/dist/index.cjs

@@ -23,57 +23,47 @@ var Ajv = require('ajv');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /**
- * Version utility functions
+ * Version utility class.
  */
-const version = {
+class Version {
     /**
-     * Parses version from string
+     * Parses version from string.
      *
-     * @param v version string
-     * @returns {Array}
+     * @param v Version string.
+     * @returns Array of numeric version parts.
      */
-    parse(v) {
-        const version = [];
-        const parts = String(v || '').split('.');
-
+    static parse(v) {
+        const parts = String(v ?? '').split('.');
         const parseVersionPart = (part) => {
-            if (Number.isNaN(part)) {
+            const n = Number(part);
+            if (Number.isNaN(n)) {
                 return 0;
             }
-            return Math.max(part - 0, 0);
+            return Math.max(n, 0);
         };
-
-        // eslint-disable-next-line no-restricted-syntax
-        for (const part of parts) {
-            version.push(parseVersionPart(part));
-        }
-
-        return version;
-    },
-
+        return parts.map(parseVersionPart);
+    }
     /**
-     * Increments build part of version '0.0.0.0'
+     * Increments the build (last) part of a version string `'0.0.0.0'`.
+     * Carries over when a part reaches 100.
      *
-     * @param v version string
-     * @returns {string}
+     * @param v Version string.
+     * @returns Incremented version string.
      */
-    increment(v) {
-        const version = this.parse(v);
-
-        if (version.length > 0) {
-            version[version.length - 1] = version[version.length - 1] + 1;
+    static increment(v) {
+        const parts = Version.parse(v);
+        if (parts.length > 0) {
+            parts[parts.length - 1] += 1;
         }
-
-        for (let i = version.length; i > 0; i -= 1) {
-            if (version[i] === 100) {
-                version[i] = 0;
-                version[i - 1] += 1;
+        for (let i = parts.length; i > 0; i -= 1) {
+            if (parts[i] === 100) {
+                parts[i] = 0;
+                parts[i - 1] += 1;
             }
         }
-
-        return version.join('.');
-    },
-};
+        return parts.join('.');
+    }
+}
 
 /**
  * Extend logger implementation
@@ -3413,7 +3403,7 @@ const makeRevision = function (path, hash) {
             }
 
             if (!currentRevision.hash || currentRevision.hash !== result.hash) {
-                result.version = version.increment(currentRevision.version);
+                result.version = Version.increment(currentRevision.version);
                 result.timeUpdated = new Date().getTime();
             }
         }

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Type declarations for the public API of @adguard/filters-compiler.
+ *
+ * These declarations provide TypeScript consumers with typed signatures for
+ * the three exported functions. They are hand-written because the entry point
+ * (src/index.js) is JavaScript and is not processed by the TypeScript compiler.
+ *
+ * When src/index.js is eventually migrated to TypeScript, this file should be
+ * removed — the compiler will generate declarations automatically.
+ */
+
+/**
+ * Platform configuration for a single platform.
+ */
+export interface PlatformConfig {
+    [key: string]: unknown;
+}
+
+/**
+ * Custom platform configurations keyed by platform name.
+ */
+export type CustomPlatformsConfig = Record<string, PlatformConfig>;
+
+/**
+ * Compiles filter lists for all platforms.
+ *
+ * @param path Path to the filter lists directory.
+ * @param logPath Path for the compilation log file (logging disabled if omitted).
+ * @param reportFile Path for the compilation report file.
+ * @param platformsPath Path for platform-specific output.
+ * @param whitelist Whitelisted filter IDs.
+ * @param blacklist Blacklisted filter IDs.
+ * @param customPlatformsConfig Optional custom platform configurations.
+ */
+export function compile(
+    path: string,
+    logPath: string | undefined,
+    reportFile: string | undefined,
+    platformsPath: string,
+    whitelist: number[],
+    blacklist: number[],
+    customPlatformsConfig?: CustomPlatformsConfig,
+): Promise<void>;
+
+/**
+ * Validates built filter files against JSON schemas.
+ *
+ * Validation failures are logged, not thrown — check the return value.
+ *
+ * @param platformsPath Path to the built platform output.
+ * @param requiredFiltersAmount Minimum number of filters expected.
+ * @returns `true` when all files are valid, `false` on validation failure.
+ */
+export function validateJSONSchema(
+    platformsPath: string,
+    requiredFiltersAmount: number,
+): boolean;
+
+/**
+ * Result of locale validation.
+ */
+export interface ValidateLocalesResult {
+    /** `false` when at least one critical warning was found. */
+    ok: boolean;
+    /** Per-locale warning details. Present when warnings exist. */
+    data?: unknown[];
+    /** Formatted warnings log. Present when warnings exist. */
+    log?: string;
+}
+
+/**
+ * Validates locale translation files.
+ *
+ * @param localesDirPath Path to the locales directory.
+ * @param requiredLocales List of required locale codes.
+ * @returns `{ ok: true }` when no problems are found; when warnings exist,
+ * the result includes `data` and `log`, and `ok` is `false` only for
+ * critical warnings.
+ * @throws Error when the locales directory is missing or empty.
+ */
+export function validateLocales(
+    localesDirPath: string,
+    requiredLocales: string[],
+): ValidateLocalesResult;

package/dist/index.js

@@ -20,57 +20,47 @@ import { parse as parse$1 } from 'tldts';
 import Ajv from 'ajv';
 
 /**
- * Version utility functions
+ * Version utility class.
  */
-const version = {
+class Version {
     /**
-     * Parses version from string
+     * Parses version from string.
      *
-     * @param v version string
-     * @returns {Array}
+     * @param v Version string.
+     * @returns Array of numeric version parts.
      */
-    parse(v) {
-        const version = [];
-        const parts = String(v || '').split('.');
-
+    static parse(v) {
+        const parts = String(v ?? '').split('.');
         const parseVersionPart = (part) => {
-            if (Number.isNaN(part)) {
+            const n = Number(part);
+            if (Number.isNaN(n)) {
                 return 0;
             }
-            return Math.max(part - 0, 0);
+            return Math.max(n, 0);
         };
-
-        // eslint-disable-next-line no-restricted-syntax
-        for (const part of parts) {
-            version.push(parseVersionPart(part));
-        }
-
-        return version;
-    },
-
+        return parts.map(parseVersionPart);
+    }
     /**
-     * Increments build part of version '0.0.0.0'
+     * Increments the build (last) part of a version string `'0.0.0.0'`.
+     * Carries over when a part reaches 100.
      *
-     * @param v version string
-     * @returns {string}
+     * @param v Version string.
+     * @returns Incremented version string.
      */
-    increment(v) {
-        const version = this.parse(v);
-
-        if (version.length > 0) {
-            version[version.length - 1] = version[version.length - 1] + 1;
+    static increment(v) {
+        const parts = Version.parse(v);
+        if (parts.length > 0) {
+            parts[parts.length - 1] += 1;
         }
-
-        for (let i = version.length; i > 0; i -= 1) {
-            if (version[i] === 100) {
-                version[i] = 0;
-                version[i - 1] += 1;
+        for (let i = parts.length; i > 0; i -= 1) {
+            if (parts[i] === 100) {
+                parts[i] = 0;
+                parts[i - 1] += 1;
             }
         }
-
-        return version.join('.');
-    },
-};
+        return parts.join('.');
+    }
+}
 
 /**
  * Extend logger implementation
@@ -3410,7 +3400,7 @@ const makeRevision = function (path, hash) {
             }
 
             if (!currentRevision.hash || currentRevision.hash !== result.hash) {
-                result.version = version.increment(currentRevision.version);
+                result.version = Version.increment(currentRevision.version);
                 result.timeUpdated = new Date().getTime();
             }
         }

package/dist/types/src/main/utils/version.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Version utility class.
+ */
+export declare class Version {
+    /**
+     * Parses version from string.
+     *
+     * @param v Version string.
+     * @returns Array of numeric version parts.
+     */
+    static parse(v: string | null | undefined): number[];
+    /**
+     * Increments the build (last) part of a version string `'0.0.0.0'`.
+     * Carries over when a part reaches 100.
+     *
+     * @param v Version string.
+     * @returns Incremented version string.
+     */
+    static increment(v: string | null | undefined): string;
+}

package/dist/types/test/ts-imports-js.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/version.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,5 @@
 {
   "name": "@adguard/filters-compiler",
-  "version": "3.2.8",
   "description": "AdGuard filters compiler",
   "homepage": "http://adguard.com",
   "type": "module",
@@ -10,48 +9,61 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22",
+    "pnpm": ">=10.33.4 <11"
   },
   "dependencies": {
-    "@adguard/agtree": "^4.0.4",
-    "@adguard/css-tokenizer": "^1.2.0",
-    "@adguard/ecss-tree": "^2.0.1",
+    "@adguard/agtree": "4.1.0-beta.0",
+    "@adguard/css-tokenizer": "1.2.0",
+    "@adguard/ecss-tree": "2.0.1",
+    "@adguard/extended-css": "2.1.1",
+    "@adguard/filters-downloader": "2.4.4",
+    "@adguard/logger": "2.0.0",
+    "@adguard/scriptlets": "2.3.1",
+    "@adguard/tsurlfilter": "4.0.5",
     "@eslint/css-tree": "3.6.6",
-    "@adguard/extended-css": "^2.1.1",
-    "@adguard/filters-downloader": "^2.4.0",
-    "@adguard/logger": "^2.0.0",
-    "@adguard/scriptlets": "^2.3.1",
-    "@adguard/tsurlfilter": "^4.0.5",
-    "ajv": "^8.17.1",
-    "child_process": ">=1.0.2",
-    "jsdom": "^21.1.1",
+    "ajv": "8.17.1",
+    "child_process": "1.0.2",
+    "jsdom": "21.1.2",
     "md5": "2.3.0",
-    "moment": "^2.29.4",
-    "tldts": "^5.7.112",
-    "utf8": "^3.0.0"
+    "moment": "2.30.1",
+    "tldts": "5.7.112",
+    "utf8": "3.0.0"
   },
   "devDependencies": {
-    "@types/jsdom": "^21.1.7",
+    "@rollup/plugin-typescript": "12.3.0",
+    "@types/jsdom": "21.1.7",
+    "@typescript-eslint/eslint-plugin": "8.59.0",
+    "@typescript-eslint/parser": "8.59.0",
     "eslint": "8.57.1",
-    "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-import-resolver-exports": "^1.0.0-beta.5",
-    "eslint-plugin-import": "^2.31.0",
-    "husky": "^8.0.2",
-    "rollup": "^4.39.0",
-    "rollup-plugin-copy": "^3.5.0",
-    "vitest": "^3.0.5"
+    "eslint-config-airbnb-base": "15.0.0",
+    "eslint-import-resolver-exports": "1.0.0-beta.5",
+    "eslint-plugin-import": "2.31.0",
+    "husky": "8.0.2",
+    "markdownlint": "0.40.0",
+    "markdownlint-cli": "0.48.0",
+    "rimraf": "6.1.3",
+    "rollup": "4.39.0",
+    "rollup-plugin-copy": "3.5.0",
+    "tslib": "2.8.1",
+    "typescript": "6.0.3",
+    "vitest": "3.0.5"
   },
+  "version": "3.2.10-beta.0",
   "scripts": {
+    "prebuild": "rimraf dist",
     "build": "rollup --config rollup.config.js --silent",
     "test": "vitest",
-    "lint": "eslint --cache .",
-    "increment": "pnpm version patch --no-git-tag-version",
-    "build-txt": "node tasks/build-txt.mjs",
+    "lint": "pnpm lint:code && pnpm lint:types && pnpm lint:md",
+    "lint:code": "eslint --cache .",
+    "lint:types": "tsc --noEmit",
+    "lint:md": "markdownlint .",
     "build-schemas": "node --experimental-specifier-resolution=node tasks/build-schemas/index.js",
     "tgz": "pnpm pack --out filters-compiler.tgz"
   }

package/dist/build.txt

@@ -1 +0,0 @@
-version=3.2.8