@adguard/filters-compiler 3.2.10 → 3.2.12

package/dist/index.js

@@ -1,7 +1,7 @@
 import path$1 from 'path';
 import { fileURLToPath } from 'url';
 import { RuleFactory, CosmeticRule, NetworkRule, setConfiguration, CompatibilityTypes } from '@adguard/tsurlfilter';
-import fs$1 from 'fs';
+import fs$2 from 'fs';
 import md5 from 'md5';
 import { FiltersDownloader } from '@adguard/filters-downloader';
 import { ADG_SCRIPTLET_MASK, CosmeticRuleType, AdblockSyntax, RuleParser, RuleConverter, RuleGenerator, CommentParser, RuleCategory, RegExpUtils } from '@adguard/agtree';
@@ -16,6 +16,7 @@ import { createRequire } from 'module';
 import { JSDOM } from 'jsdom';
 import crypto from 'crypto';
 import moment from 'moment';
+import fs$1 from 'fs/promises';
 import { parse as parse$1 } from 'tldts';
 import Ajv from 'ajv';
 
@@ -69,53 +70,43 @@ class CompilerLogger extends Logger {
     /**
      * File descriptor
      *
-     * @type {number | null}
-     *
      * @private
      */
     #fd = null;
-
+    /**
+     * Log file path, set after successful initialization.
+     */
+    logFile;
     /**
      * Helper to append message to log file
-     *
-     * @param {string} message
-     * @param {'INFO'|'WARN'|'ERROR'} level
-     *
-     * @private
      */
     #append(message, level) {
         if (this.#fd == null) {
             return;
         }
-
         const line = `[${new Date().toLocaleTimeString()}] [${level}]: ${message}${os.EOL}`;
-
         // Using appendFileSync with an fd ensures atomic append semantics.
         fs.appendFileSync(this.#fd, line, 'utf8');
     }
-
     /** @inheritdoc */
     info(message) {
         super.info(message);
         this.#append(message, 'INFO');
     }
-
     /** @inheritdoc */
     error(message) {
         super.error(message);
         this.#append(message, 'ERROR');
     }
-
     /** @inheritdoc */
     warn(message) {
         super.warn(message);
         this.#append(message, 'WARN');
     }
-
     /**
      * Initializes logger
      *
-     * @param {string} logFilePath - log file path
+     * @param logFilePath - log file path
      *
      * The log file is opened with 'w' (truncate/create). Subsequent writes are appended.
      */
@@ -125,26 +116,23 @@ class CompilerLogger extends Logger {
             console.warn('Log file is not specified');
             return;
         }
-
         // Ensure the directory exists before creating the log file
         const dir = path.dirname(logFilePath);
         fs.mkdirSync(dir, { recursive: true });
-
         // Close any previous descriptor to avoid leaks
         if (this.#fd != null) {
             try {
                 fs.closeSync(this.#fd);
-            } catch {
+            }
+            catch {
                 /* noop */
             }
             this.#fd = null;
         }
-
-        // Open (truncate) now; we’ll append to the same fd later.
+        // Open (truncate) now; we'll append to the same fd later.
         this.#fd = fs.openSync(logFilePath, 'w');
         this.logFile = logFilePath;
     }
-
     /**
      * Optional: call to close the file descriptor when done (e.g., on shutdown)
      */
@@ -152,13 +140,13 @@ class CompilerLogger extends Logger {
         if (this.#fd != null) {
             try {
                 fs.closeSync(this.#fd);
-            } finally {
+            }
+            finally {
                 this.#fd = null;
             }
         }
     }
 }
-
 const logger = new CompilerLogger();
 
 // TODO: a lot of these masks can be imported from @adguard/agtree
@@ -1009,27 +997,24 @@ const checkAffinityDirectives = (lines) => {
 };
 
 /* eslint-disable global-require */
-
 const require = createRequire(import.meta.url);
-
 /**
  * Some sources require proper user-agents and forbid downloading without.
  */
 const USER_AGENT = 'Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko)'
     + 'Chrome/63.0.3239.132 Mobile Safari/537.36';
-
 /**
- * Sync downloads file from url
+ * Downloads file from url
  *
  * @param url
- * @param {number} [retryNum=0] number of times to retry downloading, defaults to 0
- * @returns {*}
+ * @param retryNum number of times to retry downloading, defaults to 0
+ * @returns raw content of the file
  */
-const tryDownloadFile = function (url, retryNum = 0) {
+const tryDownloadFile = async function (url, retryNum = 0) {
     let args = ['--fail', '--silent', '--user-agent', USER_AGENT, '-L', url];
     if (retryNum) {
         args.push('--retry');
-        args.push(retryNum);
+        args.push(String(retryNum));
     }
     const options = { encoding: 'utf8', maxBuffer: Infinity };
     const tlsCheck = process.env.TLS;
@@ -1039,97 +1024,279 @@ const tryDownloadFile = function (url, retryNum = 0) {
     return require('child_process')
         .execFileSync('curl', args, options);
 };
-
 /**
- * Sync downloads file from url with two attempts
+ * Number of times to retry downloading after the first failed attempt for `downloadFile` function.
+ */
+const RETRY_NUM = 5;
+/**
+ * Downloads file from url with two attempts
  *
  * @param url
- * @returns {*}
+ * @returns raw content of the file
  */
-const downloadFile = (url) => {
+const downloadFile = async (url) => {
     logger.info(`Downloading: ${url}`);
-
     // 5 times to retry after first fail attempt:
     // 1 sec for first time, double for every forthcoming attempts
     // so it will take: 1 + 2 + 4 + 8 + 16 = 31 seconds
     // https://curl.se/docs/manpage.html#--retry
-    const RETRY_NUM = 5;
-
     try {
-        return tryDownloadFile(url);
-    } catch (e) {
+        return await tryDownloadFile(url);
+    }
+    catch (e) {
         logger.warn(e);
         logger.warn(`Retry downloading: ${url}`);
         return tryDownloadFile(url, RETRY_NUM);
     }
 };
 
-/* eslint-disable global-require */
-
-// Here we can access optimizable filters and its optimization percentages
-// eslint-disable-next-line max-len
-const OPTIMIZATION_PERCENT_URL = 'https://chrome.adtidy.org/optimization_config/percent.json?key=4DDBE80A3DA94D819A00523252FB6380';
-// eslint-disable-next-line max-len
-const OPTIMIZATION_STATS_URL = 'https://chrome.adtidy.org/filters/{0}/stats.json?key=4DDBE80A3DA94D819A00523252FB6380';
-
-let filtersOptimizationPercent = null;
-
 /**
- * Downloads and caches filters optimization percentages configuration
+ * Runs `fn` over `items` with at most `concurrency` calls in flight at once.
+ *
+ * @param items - Items to process.
+ * @param max - Max number of concurrent `fn` calls.
+ * @param fn - Async worker invoked for each item.
  */
-const getFiltersOptimizationPercent = () => {
+const mapWithConcurrency = async (items, max, fn) => {
+    const workerCount = Math.min(max, items.length);
+    // Each worker owns a fixed, disjoint slice of indices (workerIndex, workerIndex + workerCount, ...)
+    // decided up front, so there's no shared mutable state for workers to race over.
+    const worker = async (startIndex) => {
+        for (let i = startIndex; i < items.length; i += workerCount) {
+            // eslint-disable-next-line no-await-in-loop
+            await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: workerCount }, (_, startIndex) => worker(startIndex)));
+};
 
-    if (filtersOptimizationPercent === null) {
-        filtersOptimizationPercent = JSON.parse(downloadFile(OPTIMIZATION_PERCENT_URL));
+/**
+ * Optimizes filters by removing low-hit rules using each filter's hit-counts
+ * collected from AdGuard users who opted into filter rules statistics.
+ * Statistics are fetched remotely or read from a local cache.
+ *
+ * @see {@link https://github.com/AdguardTeam/FiltersRegistry#optimization} for more information.
+ *
+ * @see localOptimizationStatistics for managing a local cache of optimization stats files.
+ * @see getOptimizationStatistics for retrieving optimization stats for a filter.
+ * @see skipRuleWithOptimization for checking if a rule should be skipped based on optimization stats.
+ */
+// Here we can access optimizable filters and its optimization percentages
+const OPTIMIZATION_KEY = '4DDBE80A3DA94D819A00523252FB6380';
+const OPTIMIZATION_PERCENT_URL = `https://chrome.adtidy.org/optimization_config/percent.json?key=${OPTIMIZATION_KEY}`;
+// Path segment constants for the local config directory layout:
+//   <basePath>/filters/<filterId>/stats.json
+const STATS_JSON = 'stats.json';
+const FILTERS_DIR_NAME = 'filters';
+/**
+ * Thrown by `getOptimizationStatistics` when a filter's stats cannot be
+ * retrieved, from either a local file or the remote server.
+ *
+ * Carries `filterId` and `sourcePath` as structured fields so callers can
+ * build their own actionable message instead of matching on `error.message`.
+ */
+class OptimizationStatsError extends Error {
+    filterId;
+    sourcePath;
+    code = 'OPTIMIZATION_STATS_UNAVAILABLE';
+    constructor(filterId, sourcePath, options) {
+        super(`Unable to retrieve optimization stats for ${filterId}, at ${sourcePath}. `
+            + 'Please ensure the stats file exists and is accessible.', options);
+        this.filterId = filterId;
+        this.sourcePath = sourcePath;
+        this.name = 'OptimizationStatsError';
     }
-
-    if (filtersOptimizationPercent.config.length === 0) {
-        // eslint-disable-next-line no-throw-literal
-        throw 'Invalid configuration';
+}
+const downloadOptimizationPercent = async () => downloadFile(OPTIMIZATION_PERCENT_URL);
+const getOptimizationStatsUrl = (filterId) => `https://chrome.adtidy.org/filters/${filterId}/stats.json?key=${OPTIMIZATION_KEY}`;
+/**
+ * Downloads optimization stats for a single filter from the remote server.
+ *
+ * @param filterId - Numeric filter identifier.
+ * @returns Raw JSON string of the stats file.
+ */
+const downloadOptimizationStats = async (filterId) => {
+    const optimizationStatsUrl = getOptimizationStatsUrl(filterId);
+    return downloadFile(optimizationStatsUrl);
+};
+/**
+ * When set, `getOptimizationStatistics` reads stats from local files under this
+ * directory instead of fetching from the remote server.
+ */
+let localStatsPath = null;
+/**
+ * Cached set of filter IDs that have optimization stats available.
+ * Populated lazily on the first `getOptimizableFilterIds` call.
+ * Shared across concurrent callers to avoid redundant percent.json fetches.
+ */
+let optimizableFilterIdsPromise = null;
+/**
+ * Returns the set of optimizable filter IDs.
+ *
+ * Lazily initializes a shared singleton on first call so that concurrent
+ * callers share one in-flight fetch of `percent.json`.
+ * `percent.json` is always fetched remotely, even when `use` has
+ * been called — only the per-filter stats content is read from local files.
+ *
+ * @returns Set of filter IDs that have optimization stats available.
+ */
+const getOptimizableFilterIds = async () => {
+    if (optimizableFilterIdsPromise === null) {
+        optimizableFilterIdsPromise = (async () => {
+            const percent = JSON.parse(await downloadOptimizationPercent());
+            return new Set(percent.config.map(({ filterId: id }) => id));
+        })();
+        // Clear the singleton on rejection so a transient network error
+        // doesn't poison the cache for all subsequent callers.
+        optimizableFilterIdsPromise.catch(() => {
+            optimizableFilterIdsPromise = null;
+        });
     }
-
-    return filtersOptimizationPercent;
+    return optimizableFilterIdsPromise;
 };
-
 /**
- * Downloads filter optimization config for the filter
+ * Validates that stats have non-empty groups.
+ *
+ * @param filterId - Numeric filter identifier.
+ * @param stats - Parsed optimization stats object.
+ * @throws {Error} if stats is not an object, or if stats.groups is missing or empty.
  */
-const getFilterOptimizationConfig = (filterId) => {
-
-    // config: [{filterId: 1, percent: 45}, ...]
-    const filterOptimizationPercent = getFiltersOptimizationPercent().config
-        .find((config) => config.filterId === filterId);
-
-    let optimizationConfig = null;
-    if (filterOptimizationPercent) {
-        optimizationConfig = JSON.parse(downloadFile(OPTIMIZATION_STATS_URL.replace('{0}', filterId)));
-        if (!optimizationConfig || !optimizationConfig.groups || optimizationConfig.groups.length === 0) {
-            throw new Error(`Unable to retrieve optimization stats for ${filterId}`);
+function assertValidStats(filterId, stats) {
+    if (stats === null || typeof stats !== 'object') {
+        throw new Error(`Invalid optimization stats for ${filterId}: expected an object`);
+    }
+    if (!('groups' in stats) || !Array.isArray(stats.groups) || stats.groups.length === 0) {
+        throw new Error(`Invalid optimization stats for ${filterId}: missing or empty groups`);
+    }
+}
+/**
+ * Manages a local on-disk cache of optimization stats files.
+ *
+ * Typical usage for generating the cache:
+ * 1. `download(basePath, includedFilterIds, excludedFilterIds)` — save
+ *    `stats.json` for filters listed in the remote `percent.json`.
+ *
+ * Typical usage for using the cache:
+ * 1. `use(basePath)` — tells `getOptimizationStatistics` to read stats
+ *    from local files lazily during compilation instead of fetching remotely.
+ * 2. `reset(basePath)` — remove the cache directory and clear in-memory state.
+ */
+const localOptimizationStatistics = {
+    /**
+     * Downloads `stats.json` files for filters listed in the remote
+     * `percent.json` and saves them to disk.
+     * Existing `stats.json` files will be overwritten.
+     *
+     * `includedFilterIds` and `excludedFilterIds` cannot both be non-empty.
+     *
+     * @param basePath - Directory to save `filters/<filterId>/stats.json` into.
+     * @param includedFilterIds - Filter IDs to process; empty (default) processes all.
+     * @param excludedFilterIds - Filter IDs to exclude; empty (default) excludes none.
+     * @throws {Error} When both `includedFilterIds` and `excludedFilterIds` are non-empty.
+     */
+    download: async (basePath, includedFilterIds = [], excludedFilterIds = []) => {
+        if (includedFilterIds.length > 0 && excludedFilterIds.length > 0) {
+            throw new Error('includedFilterIds and excludedFilterIds cannot both be non-empty');
         }
+        const percent = JSON.parse(await downloadOptimizationPercent());
+        const configs = percent.config.filter(({ filterId }) => {
+            if (includedFilterIds.length > 0) {
+                return includedFilterIds.includes(filterId);
+            }
+            if (excludedFilterIds.length > 0) {
+                return !excludedFilterIds.includes(filterId);
+            }
+            return true;
+        });
+        const FILTERS_PATH = path$1.join(basePath, FILTERS_DIR_NAME);
+        /**
+         * Bounds concurrency so a large `percent.json` cannot fan out into unbounded
+         * parallel requests if the underlying transport ever becomes truly async.
+         */
+        const DOWNLOAD_CONCURRENCY = 8;
+        await mapWithConcurrency(configs, DOWNLOAD_CONCURRENCY, async ({ filterId }) => {
+            const dir = path$1.join(FILTERS_PATH, String(filterId));
+            const statsPath = path$1.join(dir, STATS_JSON);
+            const content = await downloadOptimizationStats(filterId);
+            await fs$1.mkdir(dir, { recursive: true });
+            await fs$1.writeFile(statsPath, content, 'utf-8');
+        });
+    },
+    /**
+     * Configures `getOptimizationStatistics` to read stats from local files under
+     * `basePath` instead of fetching from the remote server.
+     * Stats are loaded lazily on demand during compilation. `percent.json` is
+     * still fetched remotely to determine which filters are optimizable.
+     *
+     * @param basePath - Directory containing `filters/<filterId>/stats.json`.
+     */
+    use(basePath) {
+        localStatsPath = basePath;
+        optimizableFilterIdsPromise = null;
+    },
+    /**
+     * Removes the cache directory and clears in-memory state.
+     *
+     * @param basePath - Directory to remove.
+     */
+    async reset(basePath) {
+        await fs$1.rm(basePath, { recursive: true, force: true });
+        localStatsPath = null;
+        optimizableFilterIdsPromise = null;
+    },
+};
+/**
+ * Returns the optimization stats for the given filter, or `null` when
+ * optimization is disabled or the filter is not listed in `percent.json`.
+ *
+ * When `localOptimizationStatistics.use(path)` has been called, stats
+ * are read lazily from local files. Otherwise stats are fetched from the
+ * remote server.
+ *
+ * @param filterId - Numeric filter identifier.
+ * @returns Parsed stats object, or `null` when the filter has no optimization stats.
+ * @throws {Error} When the stats are missing or malformed.
+ */
+const getOptimizationStatistics = async (filterId) => {
+    const ids = await getOptimizableFilterIds();
+    if (!ids.has(filterId)) {
+        return null;
     }
-
-    return optimizationConfig;
+    let stats;
+    try {
+        const content = localStatsPath !== null
+            ? await fs$1.readFile(path$1.join(localStatsPath, FILTERS_DIR_NAME, String(filterId), STATS_JSON), 'utf-8')
+            : await downloadOptimizationStats(filterId);
+        stats = JSON.parse(content);
+    }
+    catch (originalError) {
+        const statsPath = localStatsPath === null
+            ? getOptimizationStatsUrl(filterId)
+            : `${localStatsPath}/filters/${filterId}/stats.json`;
+        throw new OptimizationStatsError(filterId, statsPath, { cause: originalError });
+    }
+    assertValidStats(filterId, stats);
+    return stats;
 };
-
 /**
- * Checks if rule should be skipped, because optimization is enabled for this filter
- * and hits of this rule is lower than some value
- * @param ruleText Rule text
- * @param optimizationConfig Optimization config for this filter (retrieved with getFilterOptimizationConfig)
+ * Checks if rule should be skipped because optimization is enabled for this filter
+ * and the hit count for this rule is below the configured threshold.
+ *
+ * @param ruleText - Rule text to check.
+ * @param optimizationStats - Optimization config for this filter.
+ * @returns `true` if the rule should be skipped, `false` otherwise.
  */
-const skipRuleWithOptimization = (ruleText, optimizationConfig) => {
-    if (!optimizationConfig) {
+const skipRuleWithOptimization = (ruleText, optimizationStats) => {
+    if (!optimizationStats) {
         return false;
     }
-
     // eslint-disable-next-line no-restricted-syntax
-    for (const group of optimizationConfig.groups) {
+    for (const group of optimizationStats.groups) {
         const hits = group.rules[ruleText];
         if (hits !== undefined && hits < group.config.hits) {
             return true;
         }
     }
-
     return false;
 };
 
@@ -1490,7 +1657,7 @@ let adguardFiltersServerUrl = null;
  */
 const readFile$2 = function (path) {
     try {
-        return fs$1.readFileSync(path, { encoding: 'utf-8' });
+        return fs$2.readFileSync(path, { encoding: 'utf-8' });
     } catch (e) {
         return null;
     }
@@ -1603,7 +1770,7 @@ const createDir = (dir) => {
     return dir.split(sep).reduce((parentDir, childDir) => {
         const curDir = path$1.resolve(baseDir, parentDir, childDir);
         try {
-            fs$1.mkdirSync(curDir);
+            fs$2.mkdirSync(curDir);
         } catch (err) {
             if (err.code === 'EEXIST') { // curDir already exists!
                 return curDir;
@@ -1874,11 +2041,11 @@ const loadLocales = function (dir) {
         filters: {},
     };
 
-    const locales = fs$1.readdirSync(dir);
+    const locales = fs$2.readdirSync(dir);
     // eslint-disable-next-line no-restricted-syntax
     for (const directory of locales) {
         const localeDir = path$1.join(dir, directory);
-        if (fs$1.lstatSync(localeDir).isDirectory()) {
+        if (fs$2.lstatSync(localeDir).isDirectory()) {
             const groups = JSON.parse(readFile$2(path$1.join(localeDir, 'groups.json')));
             if (groups) {
                 // eslint-disable-next-line no-restricted-syntax
@@ -2103,8 +2270,8 @@ const writeFiltersMetadata = function (platformsPath, filtersDir, filtersMetadat
 
         const filtersContent = JSON.stringify(sortMetadataFilters(metadata), null, '\t');
 
-        fs$1.writeFileSync(filtersFileJson, filtersContent, 'utf8');
-        fs$1.writeFileSync(filtersFileJs, filtersContent, 'utf8');
+        fs$2.writeFileSync(filtersFileJson, filtersContent, 'utf8');
+        fs$2.writeFileSync(filtersFileJs, filtersContent, 'utf8');
 
         logger.info(`Writing filters localizations: ${config.path}`);
         const filtersI18nFileJson = path$1.join(platformDir, FILTERS_I18N_METADATA_FILE_JSON);
@@ -2145,8 +2312,8 @@ const writeFiltersMetadata = function (platformsPath, filtersDir, filtersMetadat
 
         const i18nContent = JSON.stringify(i18nMetadata, null, '\t');
 
-        fs$1.writeFileSync(filtersI18nFileJson, i18nContent, 'utf8');
-        fs$1.writeFileSync(filtersI18nFileJs, i18nContent, 'utf8');
+        fs$2.writeFileSync(filtersI18nFileJson, i18nContent, 'utf8');
+        fs$2.writeFileSync(filtersI18nFileJs, i18nContent, 'utf8');
     }
 
     logger.info('Writing filters metadata done');
@@ -2206,12 +2373,12 @@ const writeLocalScriptRules = function (platformsPath) {
         // remove scriptlet rules in local_script_rules.json
         rulesJson.rules = removeScriptletRules(rulesJson.rules);
 
-        fs$1.writeFileSync(
+        fs$2.writeFileSync(
             path$1.join(platformDir, LOCAL_SCRIPT_RULES_FILE),
             rulesTxt.join(RULES_SEPARATOR),
             'utf8',
         );
-        fs$1.writeFileSync(
+        fs$2.writeFileSync(
             path$1.join(platformDir, LOCAL_SCRIPT_RULES_FILE_JSON),
             JSON.stringify(rulesJson, null, 4),
             'utf8',
@@ -2225,12 +2392,12 @@ const writeLocalScriptRules = function (platformsPath) {
  * Loads and processes filter metadata from the specified directory.
  *
  * @param {string} filterDir - The directory containing the filter metadata and revision files.
- * @param {number[]} [whitelist] - An optional array of whitelist filter IDs.
- * @param {number[]} [blacklist] - An optional array of blacklist filter IDs.
+ * @param {number[]} [includedFilterIds] - An optional array of filter IDs to include.
+ * @param {number[]} [excludedFilterIds] - An optional array of filter IDs to exclude.
  * @returns {Object} The processed filter metadata.
  * @throws {Error} If the metadata or revision file cannot be read.
  */
-const loadFilterMetadata = function (filterDir, whitelist, blacklist) {
+const loadFilterMetadata = function (filterDir, includedFilterIds, excludedFilterIds) {
     const metadataFilePath = path$1.join(filterDir, metadataFile);
     const metadataString = readFile$2(metadataFilePath);
     if (!metadataString) {
@@ -2253,8 +2420,8 @@ const loadFilterMetadata = function (filterDir, whitelist, blacklist) {
 
     const { filterId } = result;
     if (
-        (whitelist && whitelist.includes(filterId))
-        || (blacklist && !blacklist.includes(filterId))
+        (includedFilterIds && includedFilterIds.includes(filterId))
+        || (excludedFilterIds && !excludedFilterIds.includes(filterId))
     ) {
         checkFilterId(metadataFilterIdsPool, filterId);
     }
@@ -2298,7 +2465,7 @@ const writeFilterFile = function (filterFile, adbHeader, rulesHeader, rules) {
         data = [adbHeader].concat(data);
     }
 
-    fs$1.writeFileSync(filterFile, data.join(RULES_SEPARATOR), 'utf8');
+    fs$2.writeFileSync(filterFile, data.join(RULES_SEPARATOR), 'utf8');
 };
 
 /**
@@ -2378,10 +2545,10 @@ const removeRuleDuplicates = function (list) {
  *
  * @param filterDir - Path to filter directory
  * @param platformsPath - Path to platforms folder
- * @param whitelist - Array of filter ids to whitelist
- * @param blacklist - Array of filter ids to blacklist
+ * @param includedFilterIds - Array of filter ids to include
+ * @param excludedFilterIds - Array of filter ids to exclude
  */
-const buildFilter$1 = async (filterDir, platformsPath, whitelist, blacklist) => {
+const buildFilter$1 = async (filterDir, platformsPath, includedFilterIds, excludedFilterIds) => {
     const originalRules = readFile$2(path$1.join(filterDir, filterFile)).split('\r\n');
 
     const metadataFilePath = path$1.join(filterDir, metadataFile);
@@ -2391,17 +2558,17 @@ const buildFilter$1 = async (filterDir, platformsPath, whitelist, blacklist) =>
     const { filterId } = metadata;
     checkFilterId(filterIdsPool, filterId);
 
-    if (whitelist && whitelist.length > 0 && whitelist.indexOf(filterId) < 0) {
-        logger.info(`Filter ${filterId} skipped with whitelist`);
+    if (includedFilterIds && includedFilterIds.length > 0 && includedFilterIds.indexOf(filterId) < 0) {
+        logger.info(`Filter ${filterId} skipped due to '--include' option`);
         return;
     }
 
-    if (blacklist && blacklist.length > 0 && blacklist.indexOf(filterId) >= 0) {
-        logger.info(`Filter ${filterId} skipped with blacklist`);
+    if (excludedFilterIds && excludedFilterIds.length > 0 && excludedFilterIds.indexOf(filterId) >= 0) {
+        logger.info(`Filter ${filterId} skipped due to '--skip' option`);
         return;
     }
 
-    const optimizationConfig = getFilterOptimizationConfig(filterId);
+    const optimizationConfig = await getOptimizationStatistics(filterId);
 
     // eslint-disable-next-line guard-for-in,no-restricted-syntax
     for (const platform in platformPathsConfig) {
@@ -2495,30 +2662,30 @@ const isObsoleteFilter = (metadata) => metadata.tags && metadata.tags.some((tag)
  * @param filtersDir
  * @param filtersMetadata
  * @param platformsPath
- * @param whitelist
- * @param blacklist
+ * @param includedFilterIds
+ * @param excludedFilterIds
  * @param obsoleteFiltersMetadata
  */
 const parseDirectory$1 = async (
     filtersDir,
     filtersMetadata,
     platformsPath,
-    whitelist,
-    blacklist,
+    includedFilterIds,
+    excludedFilterIds,
     obsoleteFiltersMetadata,
 ) => {
-    const items = fs$1.readdirSync(filtersDir);
+    const items = fs$2.readdirSync(filtersDir);
     // eslint-disable-next-line no-restricted-syntax
     for (const directory of items) {
         const filterDir = path$1.join(filtersDir, directory);
-        if (fs$1.lstatSync(filterDir).isDirectory()) {
+        if (fs$2.lstatSync(filterDir).isDirectory()) {
             const metadataFilePath = path$1.join(filterDir, metadataFile);
-            if (fs$1.existsSync(metadataFilePath)) {
+            if (fs$2.existsSync(metadataFilePath)) {
                 logger.info(`Building filter platforms: ${directory}`);
                 // eslint-disable-next-line no-await-in-loop
-                await buildFilter$1(filterDir, platformsPath, whitelist, blacklist);
+                await buildFilter$1(filterDir, platformsPath, includedFilterIds, excludedFilterIds);
                 logger.info(`Building filter platforms: ${directory} done`);
-                const filterMetadata = loadFilterMetadata(filterDir, whitelist, blacklist);
+                const filterMetadata = loadFilterMetadata(filterDir, includedFilterIds, excludedFilterIds);
                 filtersMetadata.push(filterMetadata);
                 if (isObsoleteFilter(filterMetadata)) {
                     obsoleteFiltersMetadata.push(filterMetadata);
@@ -2529,8 +2696,8 @@ const parseDirectory$1 = async (
                     filterDir,
                     filtersMetadata,
                     platformsPath,
-                    whitelist,
-                    blacklist,
+                    includedFilterIds,
+                    excludedFilterIds,
                     obsoleteFiltersMetadata,
                 );
             }
@@ -2543,14 +2710,12 @@ const parseDirectory$1 = async (
  *
  * @async
  * @param {string} filtersDir - The directory containing filter files to be processed.
- * @param {string} platformsPath - The output path where the generated platform files will be stored.
- * @param {Array<number>} whitelist - A list of whitelist filter IDs.
- * @param {Array<number>} blacklist - A list of blacklist filter IDs.
+ * @param {string|null} platformsPath - The path where platform data will be generated; `null` skips platform output.
+ * @param {Array<number>|null} [includedFilterIds] - A list of filter IDs to include.
+ * @param {Array<number>|null} [excludedFilterIds] - A list of filter IDs to exclude.
  * @returns {Promise<void>} Resolves when the generation process is complete.
- *
- * @throws {Error} If `platformsPath` or `platformPathsConfig` is not specified.
  */
-const generate = async (filtersDir, platformsPath, whitelist, blacklist) => {
+const generate = async (filtersDir, platformsPath, includedFilterIds, excludedFilterIds) => {
     if (!platformsPath) {
         logger.warn('Platforms build output path is not specified');
         return;
@@ -2566,7 +2731,14 @@ const generate = async (filtersDir, platformsPath, whitelist, blacklist) => {
     const filtersMetadata = [];
     const obsoleteFiltersMetadata = [];
 
-    await parseDirectory$1(filtersDir, filtersMetadata, platformsPath, whitelist, blacklist, obsoleteFiltersMetadata);
+    await parseDirectory$1(
+        filtersDir,
+        filtersMetadata,
+        platformsPath,
+        includedFilterIds,
+        excludedFilterIds,
+        obsoleteFiltersMetadata,
+    );
 
     writeFiltersMetadata(platformsPath, filtersDir, filtersMetadata, obsoleteFiltersMetadata);
     writeLocalScriptRules(platformsPath);
@@ -2632,7 +2804,7 @@ const skipFilter = (metadata) => {
  */
 const create = (reportPath) => {
     if (reportPath) {
-        fs$1.writeFileSync(reportPath, reportData, 'utf8');
+        fs$2.writeFileSync(reportPath, reportData, 'utf8');
         return;
     }
     log(reportData);
@@ -2835,11 +3007,11 @@ const DIFF_PATH_TAG = 'Diff-Path:';
  * @returns {*}
  */
 const readFile$1 = function (path) {
-    if (!fs$1.existsSync(path)) {
+    if (!fs$2.existsSync(path)) {
         return null;
     }
 
-    return fs$1.readFileSync(path, { encoding: 'utf-8' });
+    return fs$2.readFileSync(path, { encoding: 'utf-8' });
 };
 
 /**
@@ -2849,7 +3021,7 @@ const readFile$1 = function (path) {
  * @param data
  */
 const writeFile = function (path, data) {
-    fs$1.writeFileSync(path, data, 'utf8');
+    fs$2.writeFileSync(path, data, 'utf8');
 };
 
 /**
@@ -3146,7 +3318,7 @@ const include = async (filterDir, directiveLine, excluded) => {
     const externalInclude = url.includes(':');
 
     const included = externalInclude
-        ? downloadFile(url)
+        ? await downloadFile(url)
         : readFile$1(path$1.join(filterDir, url));
 
     if (included) {
@@ -3413,11 +3585,11 @@ const makeRevision = function (path, hash) {
  * Builds filter txt file from directory contents
  *
  * @param {string} filterDir - The path to the directory containing filters.
- * @param {Array<number>} whitelist - An array whitelist filters IDs.
- * @param {Array<number>} blacklist - An array blacklist filters IDs.
+ * @param {Array<number>|null} [includedFilterIds] - An array of filter IDs to include.
+ * @param {Array<number>|null} [excludedFilterIds] - An array of filter IDs to exclude.
  * @returns {Promise<void>} A promise that resolves when all filters and its subdirectories have been processed.
  */
-const buildFilter = async function (filterDir, whitelist, blacklist) {
+const buildFilter = async function (filterDir, includedFilterIds, excludedFilterIds) {
     const templateContent = readFile$1(path$1.join(filterDir, TEMPLATE_FILE));
     if (!templateContent) {
         throw new Error('Invalid template');
@@ -3434,12 +3606,12 @@ const buildFilter = async function (filterDir, whitelist, blacklist) {
         return;
     }
 
-    if (whitelist && whitelist.length > 0 && whitelist.indexOf(filterId) < 0) {
+    if (includedFilterIds && includedFilterIds.length > 0 && includedFilterIds.indexOf(filterId) < 0) {
         logger.info(`Filter ${filterId} skipped due to '--include' option`);
         return;
     }
 
-    if (blacklist && blacklist.length > 0 && blacklist.indexOf(filterId) >= 0) {
+    if (excludedFilterIds && excludedFilterIds.length > 0 && excludedFilterIds.indexOf(filterId) >= 0) {
         logger.info(`Filter ${filterId} skipped due to '--skip' option`);
         return;
     }
@@ -3479,30 +3651,30 @@ const buildFilter = async function (filterDir, whitelist, blacklist) {
 };
 
 /**
- * Asynchronously parses a directory and processes filters based on the provided whitelist and blacklist.
+ * Asynchronously parses a directory and processes filters based on the provided included/excluded filter IDs.
  *
  * @param {string} filtersDir - The path to the directory containing filters.
- * @param {Array<number>} whitelist - An array whitelist filters IDs.
- * @param {Array<number>} blacklist - An array blacklist filters IDs.
+ * @param {Array<number>|null} [includedFilterIds] - An array of filter IDs to include.
+ * @param {Array<number>|null} [excludedFilterIds] - An array of filter IDs to exclude.
  * @returns {Promise<void>} A promise that resolves when all filters and its subdirectories have been processed.
  */
-const parseDirectory = async function (filtersDir, whitelist, blacklist) {
-    const items = fs$1.readdirSync(filtersDir)
+const parseDirectory = async function (filtersDir, includedFilterIds, excludedFilterIds) {
+    const items = fs$2.readdirSync(filtersDir)
         .sort((a, b) => getFilterIdFromDirName(a) - getFilterIdFromDirName(b));
 
     // eslint-disable-next-line no-restricted-syntax
     for (const directory of items) {
         const filterDir = path$1.join(filtersDir, directory);
-        if (fs$1.lstatSync(filterDir).isDirectory()) {
+        if (fs$2.lstatSync(filterDir).isDirectory()) {
             const template = path$1.join(filterDir, TEMPLATE_FILE);
-            if (fs$1.existsSync(template)) {
+            if (fs$2.existsSync(template)) {
                 logger.info(`Building filter ${directory}...`);
                 // eslint-disable-next-line no-await-in-loop
-                await buildFilter(filterDir, whitelist, blacklist);
+                await buildFilter(filterDir, includedFilterIds, excludedFilterIds);
                 logger.info(`Filter ${directory} ok`);
             } else {
                 // eslint-disable-next-line no-await-in-loop
-                await parseDirectory(filterDir, whitelist, blacklist);
+                await parseDirectory(filterDir, includedFilterIds, excludedFilterIds);
             }
         }
     }
@@ -3516,10 +3688,10 @@ const parseDirectory = async function (filtersDir, whitelist, blacklist) {
  * @param {string} filtersDir - The directory containing filter files to be processed.
  * @param {string} logFile - The path to the log file where logs will be written.
  * @param {string} reportFile - The path to the report file to be created.
- * @param {string} platformsPath - The path where platform data will be generated.
+ * @param {string|null} platformsPath - The path where platform data will be generated; `null` skips platform output.
  * @param {Object} platformsConfig - The configuration object for platforms.
- * @param {Array<number>} whitelist - A list of filter file names to include in processing.
- * @param {Array<number>} blacklist - A list of filter file names to exclude from processing.
+ * @param {Array<number>|null} [includedFilterIds] - A list of filter IDs to include in processing.
+ * @param {Array<number>|null} [excludedFilterIds] - A list of filter IDs to exclude from processing.
  * @returns {Promise<void>} A promise that resolves when the build process is complete.
  */
 const build = async (
@@ -3528,16 +3700,16 @@ const build = async (
     reportFile,
     platformsPath,
     platformsConfig,
-    whitelist,
-    blacklist,
+    includedFilterIds,
+    excludedFilterIds,
 ) => {
     logger.initialize(logFile);
     init(FILTER_FILE, METADATA_FILE, REVISION_FILE, platformsConfig, ADGUARD_FILTERS_SERVER_URL);
 
-    await parseDirectory(filtersDir, whitelist, blacklist);
+    await parseDirectory(filtersDir, includedFilterIds, excludedFilterIds);
 
     logger.info('Generating platforms');
-    await generate(filtersDir, platformsPath, whitelist, blacklist);
+    await generate(filtersDir, platformsPath, includedFilterIds, excludedFilterIds);
     logger.info('Generating platforms done');
     create(reportFile);
 };
@@ -3558,14 +3730,14 @@ const OLD_MAC_V2_PLATFORM = 'mac_v2';
 const loadSchemas = (dir) => {
     const schemas = {};
 
-    const items = fs$1.readdirSync(dir);
+    const items = fs$2.readdirSync(dir);
     // eslint-disable-next-line no-restricted-syntax
     for (const f of items) {
         if (f.endsWith(SCHEMA_EXTENSION)) {
             const validationFileName = f.substr(0, f.indexOf(SCHEMA_EXTENSION));
 
             logger.info(`Loading schema for ${validationFileName}`);
-            schemas[validationFileName] = JSON.parse(fs$1.readFileSync(path$1.join(dir, f)));
+            schemas[validationFileName] = JSON.parse(fs$2.readFileSync(path$1.join(dir, f)));
         }
     }
 
@@ -3585,7 +3757,7 @@ const loadSchemas = (dir) => {
 const validateDir = (dir, validator, schemas, oldSchemas, filtersRequiredAmount) => {
     let items;
     try {
-        items = fs$1.readdirSync(dir);
+        items = fs$2.readdirSync(dir);
     } catch (e) {
         logger.info(e.message);
         return false;
@@ -3593,7 +3765,7 @@ const validateDir = (dir, validator, schemas, oldSchemas, filtersRequiredAmount)
     // eslint-disable-next-line no-restricted-syntax
     for (const f of items) {
         const item = path$1.join(dir, f);
-        if (fs$1.lstatSync(item).isDirectory()) {
+        if (fs$2.lstatSync(item).isDirectory()) {
             if (!validateDir(item, validator, schemas, oldSchemas)) {
                 return false;
             }
@@ -3616,7 +3788,7 @@ const validateDir = (dir, validator, schemas, oldSchemas, filtersRequiredAmount)
             if (schema) {
                 logger.info(`Validating ${item}`);
 
-                const json = JSON.parse(fs$1.readFileSync(item));
+                const json = JSON.parse(fs$2.readFileSync(item));
 
                 // Validate filters amount
                 if (fileName === 'filters') {
@@ -3630,11 +3802,11 @@ const validateDir = (dir, validator, schemas, oldSchemas, filtersRequiredAmount)
                 const valid = validate(json);
 
                 // json can be updated with default values
-                fs$1.writeFileSync(item, JSON.stringify(json, null, '\t'));
+                fs$2.writeFileSync(item, JSON.stringify(json, null, '\t'));
 
                 // duplicate to .js file as well
                 const jsFileName = `${fileName}.js`;
-                fs$1.writeFileSync(
+                fs$2.writeFileSync(
                     path$1.join(path$1.dirname(item), jsFileName),
                     JSON.stringify(json, null, '\t'),
                 );
@@ -3725,13 +3897,13 @@ const WARNING_TYPES = {
  * Sync reads file content
  * @param filePath - path to locales file
  */
-const readFile = (filePath) => fs$1.readFileSync(path$1.resolve(__dirname$1, filePath), 'utf8');
+const readFile = (filePath) => fs$2.readFileSync(path$1.resolve(__dirname$1, filePath), 'utf8');
 
 /**
  * Sync reads directory content
  * @param dirPath - path to directory
  */
-const readDir = (dirPath) => fs$1.readdirSync(path$1.resolve(__dirname$1, dirPath), 'utf8');
+const readDir = (dirPath) => fs$2.readdirSync(path$1.resolve(__dirname$1, dirPath), 'utf8');
 
 /**
  * Validates messages keys
@@ -4829,7 +5001,15 @@ process.on('unhandledRejection', (error) => {
     throw error;
 });
 
-const compile = (path, logPath, reportFile, platformsPath, whitelist, blacklist, customPlatformsConfig) => {
+const compile = (
+    path,
+    logPath,
+    reportFile,
+    platformsPath,
+    includedFilterIds,
+    excludedFilterIds,
+    customPlatformsConfig,
+) => {
     if (customPlatformsConfig) {
         logger.info('Using custom platforms configuration');
         // eslint-disable-next-line no-restricted-syntax, guard-for-in
@@ -4845,8 +5025,8 @@ const compile = (path, logPath, reportFile, platformsPath, whitelist, blacklist,
         reportFile,
         platformsPath,
         platformsConfig,
-        whitelist,
-        blacklist,
+        includedFilterIds,
+        excludedFilterIds,
     );
 };
 
@@ -4858,4 +5038,4 @@ const validateLocales = (localesDirPath, requiredLocales) => {
     return localesValidator.validate(localesDirPath, requiredLocales);
 };
 
-export { compile, validateJSONSchema, validateLocales };
+export { OptimizationStatsError, compile, localOptimizationStatistics, validateJSONSchema, validateLocales };