@adguard/agtree 2.1.3 → 3.0.0

package/dist/esm/converter/filter-list.mjs

@@ -0,0 +1,88 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { RuleConverter } from './rule.mjs';
+import { clone } from '../utils/clone.mjs';
+import { MultiValueMap } from '../utils/multi-value-map.mjs';
+import { createConversionResult } from './base-interfaces/conversion-result.mjs';
+import { BaseConverter } from './base-interfaces/base-converter.mjs';
+
+/**
+ * @file Adblock filter list converter
+ */
+/**
+ * Adblock filter list converter class
+ *
+ * This class just provides an extra layer on top of the {@link RuleConverter}
+ * and can be used to convert entire filter lists.
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ * @todo Implement tolerant mode, which will allow to convert a filter list
+ * even if some of its rules are invalid
+ */
+class FilterListConverter extends BaseConverter {
+    /**
+     * Converts an adblock filter list to AdGuard format, if possible.
+     *
+     * @param filterListNode Filter list node to convert
+     * @param tolerant Indicates whether the converter should be tolerant to invalid rules. If enabled and a rule is
+     * invalid, it will be left as is. If disabled and a rule is invalid, the whole filter list will be failed.
+     * Defaults to `true`.
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the converted node, and its `isConverted` flag indicates whether the original node was converted.
+     * If the node was not converted, the result will contain the original node with the same object reference
+     * @throws If the filter list is invalid or cannot be converted (if the tolerant mode is disabled)
+     */
+    static convertToAdg(filterListNode, tolerant = true) {
+        // Prepare a map to store the converted rules by their index in the filter list
+        const conversionMap = new MultiValueMap();
+        // Iterate over the filtering rules and convert them one by one, then add them to the result (one conversion may
+        // result in multiple rules)
+        for (let i = 0; i < filterListNode.children.length; i += 1) {
+            try {
+                const convertedRules = RuleConverter.convertToAdg(filterListNode.children[i]);
+                // Add the converted rules to the map if they were converted
+                if (convertedRules.isConverted) {
+                    conversionMap.add(i, ...convertedRules.result);
+                }
+            }
+            catch (error) {
+                // If the tolerant mode is disabled, we should throw an error, this will fail the whole filter list
+                // conversion.
+                // Otherwise, we just ignore the error and leave the rule as is
+                if (!tolerant) {
+                    throw error;
+                }
+            }
+        }
+        // If the conversion map is empty, it means that no rules were converted, so we can return the original filter
+        // list
+        if (conversionMap.size === 0) {
+            return createConversionResult(filterListNode, false);
+        }
+        // Otherwise, create a new filter list node with the converted rules
+        const convertedFilterList = {
+            type: 'FilterList',
+            children: [],
+        };
+        // Iterate over the original rules again and add them to the converted filter list, replacing the converted
+        // rules with the new ones at the specified indexes
+        for (let i = 0; i < filterListNode.children.length; i += 1) {
+            const rules = conversionMap.get(i);
+            if (rules) {
+                convertedFilterList.children.push(...rules);
+            }
+            else {
+                // We clone the unconverted rules to avoid mutating the original filter list if we return the converted
+                // one
+                convertedFilterList.children.push(clone(filterListNode.children[i]));
+            }
+        }
+        return createConversionResult(convertedFilterList, true);
+    }
+}
+
+export { FilterListConverter };

package/dist/esm/converter/index.mjs

@@ -0,0 +1,8 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+export { RawFilterListConverter } from './raw-filter-list.mjs';
+export { RuleConverter } from './rule.mjs';

package/dist/esm/converter/misc/network-rule-modifier.mjs

@@ -0,0 +1,311 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { SEMICOLON, SPACE } from '../../utils/constants.mjs';
+import { createModifierNode } from '../../ast-utils/modifiers.mjs';
+import { BaseConverter } from '../base-interfaces/base-converter.mjs';
+import { RuleConversionError } from '../../errors/rule-conversion-error.mjs';
+import { MultiValueMap } from '../../utils/multi-value-map.mjs';
+import { createConversionResult } from '../base-interfaces/conversion-result.mjs';
+import { cloneModifierListNode } from '../../ast-utils/clone.mjs';
+import { modifiersCompatibilityTable } from '../../compatibility-tables/modifiers.mjs';
+import { redirectsCompatibilityTable } from '../../compatibility-tables/redirects.mjs';
+import '../../compatibility-tables/scriptlets.mjs';
+import { GenericPlatform } from '../../compatibility-tables/platforms.mjs';
+import '../../compatibility-tables/schemas/base.mjs';
+import '../../compatibility-tables/schemas/modifier.mjs';
+import '../../compatibility-tables/schemas/redirect.mjs';
+import '../../compatibility-tables/schemas/scriptlet.mjs';
+import '../../compatibility-tables/schemas/platform.mjs';
+import '../../compatibility-tables/utils/platform-helpers.mjs';
+import '../../compatibility-tables/schemas/resource-type.mjs';
+import { isValidResourceType } from '../../compatibility-tables/utils/resource-type-helpers.mjs';
+import { isUndefined } from '../../utils/type-guards.mjs';
+
+/**
+ * @file Network rule modifier list converter.
+ */
+/**
+ * @see {@link https://adguard.com/kb/general/ad-filtering/create-own-filters/#csp-modifier}
+ */
+const CSP_MODIFIER = 'csp';
+const CSP_SEPARATOR = SEMICOLON + SPACE;
+/**
+ * @see {@link https://adguard.com/kb/general/ad-filtering/create-own-filters/#csp-modifier}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy}
+ */
+const COMMON_CSP_PARAMS = '\'self\' \'unsafe-eval\' http: https: data: blob: mediastream: filesystem:';
+/**
+ * @see {@link https://help.adblockplus.org/hc/en-us/articles/360062733293#rewrite}
+ */
+const ABP_REWRITE_MODIFIER = 'rewrite';
+/**
+ * @see {@link https://adguard.com/kb/general/ad-filtering/create-own-filters/#redirect-modifier}
+ */
+const REDIRECT_MODIFIER = 'redirect';
+/**
+ * @see {@link https://adguard.com/kb/general/ad-filtering/create-own-filters/#redirect-rule-modifier}
+ */
+const REDIRECT_RULE_MODIFIER = 'redirect-rule';
+/**
+ * @see {@link https://github.com/gorhill/uBlock/wiki/Resources-Library#empty-redirect-resources}
+ */
+const UBO_NOOP_TEXT_RESOURCE = 'noop.txt';
+/**
+ * Redirect-related modifiers.
+ */
+const REDIRECT_MODIFIERS = new Set([
+    ABP_REWRITE_MODIFIER,
+    REDIRECT_MODIFIER,
+    REDIRECT_RULE_MODIFIER,
+]);
+/**
+ * Conversion map for ADG network rule modifiers.
+ */
+const ADG_CONVERSION_MAP = new Map([
+    ['1p', [{ name: () => 'third-party', exception: (actual) => !actual }]],
+    ['3p', [{ name: () => 'third-party' }]],
+    ['css', [{ name: () => 'stylesheet' }]],
+    ['doc', [{ name: () => 'document' }]],
+    ['ehide', [{ name: () => 'elemhide' }]],
+    ['empty', [{ name: () => 'redirect', value: () => 'nooptext' }]],
+    ['first-party', [{ name: () => 'third-party', exception: (actual) => !actual }]],
+    ['frame', [{ name: () => 'subdocument' }]],
+    ['ghide', [{ name: () => 'generichide' }]],
+    ['inline-font', [{ name: () => CSP_MODIFIER, value: () => `font-src ${COMMON_CSP_PARAMS}` }]],
+    ['inline-script', [{ name: () => CSP_MODIFIER, value: () => `script-src ${COMMON_CSP_PARAMS}` }]],
+    ['mp4', [{ name: () => 'redirect', value: () => 'noopmp4-1s' }, { name: () => 'media', value: () => undefined }]],
+    ['queryprune', [{ name: () => 'removeparam' }]],
+    ['shide', [{ name: () => 'specifichide' }]],
+    ['xhr', [{ name: () => 'xmlhttprequest' }]],
+]);
+/**
+ * Helper class for converting network rule modifier lists.
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class NetworkRuleModifierListConverter extends BaseConverter {
+    /**
+     * Converts a network rule modifier list to AdGuard format, if possible.
+     *
+     * @param modifierList Network rule modifier list node to convert
+     * @param isException If `true`, the rule is an exception rule
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the converted node, and its `isConverted` flag indicates whether the original node was converted.
+     * If the node was not converted, the result will contain the original node with the same object reference
+     * @throws If the conversion is not possible
+     */
+    static convertToAdg(modifierList, isException = false) {
+        const conversionMap = new MultiValueMap();
+        // Special case: $csp modifier
+        let cspCount = 0;
+        modifierList.children.forEach((modifierNode, index) => {
+            const modifierConversions = ADG_CONVERSION_MAP.get(modifierNode.name.value);
+            if (modifierConversions) {
+                for (const modifierConversion of modifierConversions) {
+                    const name = modifierConversion.name(modifierNode.name.value);
+                    const exception = modifierConversion.exception
+                        // If the exception value is undefined in the original modifier, it
+                        // means that the modifier isn't negated
+                        ? modifierConversion.exception(modifierNode.exception || false)
+                        : modifierNode.exception;
+                    const value = modifierConversion.value
+                        ? modifierConversion.value(modifierNode.value?.value)
+                        : modifierNode.value?.value;
+                    // Check if the name or the value is different from the original modifier
+                    // If so, add the converted modifier to the list
+                    if (name !== modifierNode.name.value || value !== modifierNode.value?.value) {
+                        conversionMap.add(index, createModifierNode(name, value, exception));
+                    }
+                    // Special case: $csp modifier
+                    if (name === CSP_MODIFIER) {
+                        cspCount += 1;
+                    }
+                }
+                return;
+            }
+            // Handle special case: resource redirection modifiers
+            if (REDIRECT_MODIFIERS.has(modifierNode.name.value)) {
+                // Redirect modifiers can't be negated
+                if (modifierNode.exception === true) {
+                    throw new RuleConversionError(`Modifier '${modifierNode.name.value}' cannot be negated`);
+                }
+                // Convert the redirect resource name to ADG format
+                const redirectResource = modifierNode.value?.value;
+                // Special case: for exception rules, $redirect without value is allowed,
+                // and in this case it means an exception for all redirects
+                if (!redirectResource && !isException) {
+                    throw new RuleConversionError(`No redirect resource specified for '${modifierNode.name.value}' modifier`);
+                }
+                // Leave $redirect and $redirect-rule modifiers as is, but convert $rewrite to $redirect
+                const modifierName = modifierNode.name.value === ABP_REWRITE_MODIFIER
+                    ? REDIRECT_MODIFIER
+                    : modifierNode.name.value;
+                const convertedRedirectResource = redirectResource
+                    ? redirectsCompatibilityTable.getFirst(redirectResource, GenericPlatform.AdgAny)?.name
+                    : undefined;
+                // Check if the modifier name or the redirect resource name is different from the original modifier.
+                // If so, add the converted modifier to the list
+                if (modifierName !== modifierNode.name.value
+                    || (convertedRedirectResource !== undefined && convertedRedirectResource !== redirectResource)) {
+                    conversionMap.add(index, createModifierNode(modifierName, 
+                    // If the redirect resource name is unknown, fall back to the original one
+                    // Later, the validator will throw an error if the resource name is invalid
+                    convertedRedirectResource || redirectResource, modifierNode.exception));
+                }
+            }
+        });
+        // Prepare the result if there are any converted modifiers or $csp modifiers
+        if (conversionMap.size || cspCount) {
+            const modifierListClone = cloneModifierListNode(modifierList);
+            // Replace the original modifiers with the converted ones
+            // One modifier may be replaced with multiple modifiers, so we need to flatten the array
+            modifierListClone.children = modifierListClone.children.map((modifierNode, index) => {
+                const conversionRecord = conversionMap.get(index);
+                if (conversionRecord) {
+                    return conversionRecord;
+                }
+                return modifierNode;
+            }).flat();
+            // Special case: $csp modifier: merge multiple $csp modifiers into one
+            // and put it at the end of the modifier list
+            if (cspCount) {
+                const cspValues = [];
+                modifierListClone.children = modifierListClone.children.filter((modifierNode) => {
+                    if (modifierNode.name.value === CSP_MODIFIER) {
+                        if (!modifierNode.value?.value) {
+                            throw new RuleConversionError('$csp modifier value is missing');
+                        }
+                        cspValues.push(modifierNode.value?.value);
+                        return false;
+                    }
+                    return true;
+                });
+                modifierListClone.children.push(createModifierNode(CSP_MODIFIER, cspValues.join(CSP_SEPARATOR)));
+            }
+            // Before returning the result, remove duplicated modifiers
+            modifierListClone.children = modifierListClone.children.filter((modifierNode, index, self) => self.findIndex((m) => m.name.value === modifierNode.name.value
+                && m.exception === modifierNode.exception
+                && m.value?.value === modifierNode.value?.value) === index);
+            return createConversionResult(modifierListClone, true);
+        }
+        return createConversionResult(modifierList, false);
+    }
+    /**
+     * Converts a network rule modifier list to uBlock format, if possible.
+     *
+     * @param modifierList Network rule modifier list node to convert
+     * @param isException If `true`, the rule is an exception rule
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the converted node, and its `isConverted` flag indicates whether the original node was converted.
+     * If the node was not converted, the result will contain the original node with the same object reference
+     * @throws If the conversion is not possible
+     */
+    // TODO: Optimize
+    static convertToUbo(modifierList, isException = false) {
+        const conversionMap = new MultiValueMap();
+        const resourceTypeModifiersToAdd = new Set();
+        modifierList.children.forEach((modifierNode, index) => {
+            const originalModifierName = modifierNode.name.value;
+            const modifierData = modifiersCompatibilityTable.getFirst(originalModifierName, GenericPlatform.UboAny);
+            // Handle special case: resource redirection modifiers
+            if (REDIRECT_MODIFIERS.has(originalModifierName)) {
+                // Redirect modifiers cannot be negated
+                if (modifierNode.exception === true) {
+                    throw new RuleConversionError(`Modifier '${modifierNode.name.value}' cannot be negated`);
+                }
+                // Convert the redirect resource name to uBO format
+                const redirectResourceName = modifierNode.value?.value;
+                // Special case: for exception rules, $redirect without value is allowed,
+                // and in this case it means an exception for all redirects
+                if (!redirectResourceName && !isException) {
+                    throw new RuleConversionError(`No redirect resource specified for '${modifierNode.name.value}' modifier`);
+                }
+                if (!redirectResourceName) {
+                    // Jump to the next modifier if the redirect resource is not specified
+                    return;
+                }
+                // Leave $redirect and $redirect-rule modifiers as is, but convert $rewrite to $redirect
+                const modifierName = modifierNode.name.value === ABP_REWRITE_MODIFIER
+                    ? REDIRECT_MODIFIER
+                    : modifierNode.name.value;
+                const convertedRedirectResourceData = redirectsCompatibilityTable.getFirst(redirectResourceName, GenericPlatform.UboAny);
+                const convertedRedirectResourceName = convertedRedirectResourceData?.name ?? redirectResourceName;
+                // uBlock requires the $redirect modifier to have a resource type
+                // https://github.com/AdguardTeam/Scriptlets/issues/101
+                if (convertedRedirectResourceData?.resourceTypes?.length) {
+                    // Convert the resource types to uBO modifiers
+                    const uboResourceTypeModifiers = redirectsCompatibilityTable.getResourceTypeModifiers(convertedRedirectResourceData, GenericPlatform.UboAny);
+                    // Special case: noop text resource
+                    // If any of resource type is already present, we don't need to add other resource types,
+                    // otherwise, add all resource types
+                    // TODO: Optimize this logic
+                    // Check if the current resource is the noop text resource
+                    const isNoopTextResource = convertedRedirectResourceName === UBO_NOOP_TEXT_RESOURCE;
+                    // Determine if there are any valid resource types already present
+                    const hasValidResourceType = modifierList.children.some((modifier) => {
+                        const name = modifier.name.value;
+                        if (!isValidResourceType(name)) {
+                            return false;
+                        }
+                        const convertedModifierData = modifiersCompatibilityTable.getFirst(name, GenericPlatform.UboAny);
+                        return uboResourceTypeModifiers.has(convertedModifierData?.name ?? name);
+                    });
+                    // If it's not the noop text resource or if no valid resource types are present
+                    if (!isNoopTextResource || !hasValidResourceType) {
+                        uboResourceTypeModifiers.forEach((resourceType) => {
+                            resourceTypeModifiersToAdd.add(resourceType);
+                        });
+                    }
+                }
+                // Check if the modifier name or the redirect resource name is different from the original modifier.
+                // If so, add the converted modifier to the list
+                if (modifierName !== originalModifierName
+                    || (!isUndefined(convertedRedirectResourceName)
+                        && convertedRedirectResourceName !== redirectResourceName)) {
+                    conversionMap.add(index, createModifierNode(modifierName, 
+                    // If the redirect resource name is unknown, fall back to the original one
+                    // Later, the validator will throw an error if the resource name is invalid
+                    convertedRedirectResourceName || redirectResourceName, modifierNode.exception));
+                }
+                return;
+            }
+            // Generic modifier conversion
+            if (modifierData && modifierData.name !== originalModifierName) {
+                conversionMap.add(index, createModifierNode(modifierData.name, modifierNode.value?.value, modifierNode.exception));
+            }
+        });
+        // Prepare the result if there are any converted modifiers or $csp modifiers
+        if (conversionMap.size || resourceTypeModifiersToAdd.size) {
+            const modifierListClone = cloneModifierListNode(modifierList);
+            // Replace the original modifiers with the converted ones
+            // One modifier may be replaced with multiple modifiers, so we need to flatten the array
+            modifierListClone.children = modifierListClone.children.map((modifierNode, index) => {
+                const conversionRecord = conversionMap.get(index);
+                if (conversionRecord) {
+                    return conversionRecord;
+                }
+                return modifierNode;
+            }).flat();
+            // Before returning the result, remove duplicated modifiers
+            modifierListClone.children = modifierListClone.children.filter((modifierNode, index, self) => self.findIndex((m) => m.name.value === modifierNode.name.value
+                && m.exception === modifierNode.exception
+                && m.value?.value === modifierNode.value?.value) === index);
+            if (resourceTypeModifiersToAdd.size) {
+                const modifierNameSet = new Set(modifierList.children.map((m) => m.name.value));
+                resourceTypeModifiersToAdd.forEach((resourceType) => {
+                    if (!modifierNameSet.has(resourceType)) {
+                        modifierListClone.children.push(createModifierNode(resourceType));
+                    }
+                });
+            }
+            return createConversionResult(modifierListClone, true);
+        }
+        return createConversionResult(modifierList, false);
+    }
+}
+
+export { NetworkRuleModifierListConverter };

package/dist/esm/converter/network/index.mjs

@@ -0,0 +1,99 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { NetworkRuleType, RuleCategory } from '../../nodes/index.mjs';
+import { NetworkRuleModifierListConverter } from '../misc/network-rule-modifier.mjs';
+import { RuleConverterBase } from '../base-interfaces/rule-converter-base.mjs';
+import { createNodeConversionResult } from '../base-interfaces/conversion-result.mjs';
+
+/**
+ * @file Network rule converter
+ */
+/**
+ * Network rule converter class (also known as "basic rule converter")
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class NetworkRuleConverter extends RuleConverterBase {
+    /**
+     * Converts a network rule to AdGuard format, if possible.
+     *
+     * @param rule Rule node to convert
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
+     * @throws If the rule is invalid or cannot be converted
+     */
+    static convertToAdg(rule) {
+        // TODO: add support for host rules
+        if (rule.type !== NetworkRuleType.NetworkRule) {
+            throw new Error(`Invalid rule type: ${rule.type}`);
+        }
+        if (rule.modifiers) {
+            const modifiers = NetworkRuleModifierListConverter.convertToAdg(rule.modifiers, rule.exception);
+            // If the object reference is different, it means that the modifiers were converted
+            // In this case, we should clone the entire rule and replace the modifiers with the converted ones
+            if (modifiers.isConverted) {
+                return {
+                    result: [{
+                            category: RuleCategory.Network,
+                            type: NetworkRuleType.NetworkRule,
+                            syntax: rule.syntax,
+                            exception: rule.exception,
+                            pattern: {
+                                type: 'Value',
+                                value: rule.pattern.value,
+                            },
+                            modifiers: modifiers.result,
+                        }],
+                    isConverted: true,
+                };
+            }
+        }
+        // If the modifiers were not converted, return the original rule
+        return createNodeConversionResult([rule], false);
+    }
+    /**
+     * Converts a network rule to uBlock format, if possible.
+     *
+     * @param rule Rule node to convert
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
+     * @throws If the rule is invalid or cannot be converted
+     */
+    static convertToUbo(rule) {
+        // TODO: add support for host rules
+        if (rule.type !== NetworkRuleType.NetworkRule) {
+            throw new Error(`Invalid rule type: ${rule.type}`);
+        }
+        if (rule.modifiers) {
+            const modifiers = NetworkRuleModifierListConverter.convertToUbo(rule.modifiers, rule.exception);
+            // If the object reference is different, it means that the modifiers were converted
+            // In this case, we should clone the entire rule and replace the modifiers with the converted ones
+            if (modifiers.isConverted) {
+                return {
+                    result: [{
+                            category: RuleCategory.Network,
+                            type: NetworkRuleType.NetworkRule,
+                            syntax: rule.syntax,
+                            exception: rule.exception,
+                            pattern: {
+                                type: 'Value',
+                                value: rule.pattern.value,
+                            },
+                            modifiers: modifiers.result,
+                        }],
+                    isConverted: true,
+                };
+            }
+        }
+        // If the modifiers were not converted, return the original rule
+        return createNodeConversionResult([rule], false);
+    }
+}
+
+export { NetworkRuleConverter };

package/dist/esm/converter/raw-filter-list.mjs

@@ -0,0 +1,56 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { createConversionResult } from './base-interfaces/conversion-result.mjs';
+import { BaseConverter } from './base-interfaces/base-converter.mjs';
+import { FilterListParser } from '../parser/filterlist-parser.mjs';
+import { FilterListConverter } from './filter-list.mjs';
+import { defaultParserOptions } from '../parser/options.mjs';
+import { FilterListGenerator } from '../generator/filterlist-generator.mjs';
+
+/**
+ * @file Filter list converter for raw filter lists
+ *
+ * Technically, this is a wrapper around `FilterListConverter` that works with nodes instead of strings.
+ */
+/**
+ * Adblock filter list converter class.
+ *
+ * You can use this class to convert string-based filter lists, since most of the converters work with nodes.
+ * This class just provides an extra layer on top of the {@link FilterListConverter} and calls the parser/serializer
+ * before/after the conversion internally.
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class RawFilterListConverter extends BaseConverter {
+    /**
+     * Converts an adblock filter list text to AdGuard format, if possible.
+     *
+     * @param rawFilterList Raw filter list text to convert
+     * @param tolerant Indicates whether the converter should be tolerant to invalid rules. If enabled and a rule is
+     * invalid, it will be left as is. If disabled and a rule is invalid, the whole filter list will be failed.
+     * Defaults to `true`.
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the array of converted filter list text, and its `isConverted` flag indicates whether the original rule was
+     * converted. If the rule was not converted, the original filter list text will be returned
+     * @throws If the filter list is invalid or cannot be converted (if the tolerant mode is disabled)
+     */
+    static convertToAdg(rawFilterList, tolerant = true) {
+        const conversionResult = FilterListConverter.convertToAdg(FilterListParser.parse(rawFilterList, {
+            ...defaultParserOptions,
+            isLocIncluded: false,
+            tolerant,
+        }), tolerant);
+        // If the filter list was not converted, return the original text
+        if (!conversionResult.isConverted) {
+            return createConversionResult(rawFilterList, false);
+        }
+        // Otherwise, serialize the filter list and return the result
+        return createConversionResult(FilterListGenerator.generate(conversionResult.result), true);
+    }
+}
+
+export { RawFilterListConverter };

package/dist/esm/converter/rule.mjs

@@ -0,0 +1,81 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { RuleCategory, NetworkRuleType } from '../nodes/index.mjs';
+import { CommentRuleConverter } from './comment/index.mjs';
+import { CosmeticRuleConverter } from './cosmetic/index.mjs';
+import { NetworkRuleConverter } from './network/index.mjs';
+import { RuleConversionError } from '../errors/rule-conversion-error.mjs';
+import { RuleConverterBase } from './base-interfaces/rule-converter-base.mjs';
+import { createConversionResult } from './base-interfaces/conversion-result.mjs';
+
+/**
+ * @file Adblock rule converter
+ *
+ * This file is the entry point for all rule converters
+ * which automatically detects the rule type and calls
+ * the corresponding "sub-converter".
+ */
+/**
+ * Adblock filtering rule converter class
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class RuleConverter extends RuleConverterBase {
+    /**
+     * Converts an adblock filtering rule to AdGuard format, if possible.
+     *
+     * @param rule Rule node to convert
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
+     * @throws If the rule is invalid or cannot be converted
+     */
+    static convertToAdg(rule) {
+        // Delegate conversion to the corresponding sub-converter
+        // based on the rule category
+        switch (rule.category) {
+            case RuleCategory.Comment:
+                return CommentRuleConverter.convertToAdg(rule);
+            case RuleCategory.Cosmetic:
+                return CosmeticRuleConverter.convertToAdg(rule);
+            case RuleCategory.Network:
+                // TODO: Handle hosts rules later
+                if (rule.type === NetworkRuleType.HostRule) {
+                    return createConversionResult([rule], false);
+                }
+                return NetworkRuleConverter.convertToAdg(rule);
+            case RuleCategory.Invalid:
+            case RuleCategory.Empty:
+                // Just forward the rule as is
+                return createConversionResult([rule], false);
+            default:
+                // Never happens during normal operation
+                throw new RuleConversionError('Unknown rule category');
+        }
+    }
+    /**
+     * Converts an adblock filtering rule to uBlock Origin format, if possible.
+     *
+     * @param rule Rule node to convert
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
+     * @throws If the rule is invalid or cannot be converted
+     */
+    // TODO: Add support for other rule types
+    static convertToUbo(rule) {
+        if (rule.category === RuleCategory.Cosmetic) {
+            return CosmeticRuleConverter.convertToUbo(rule);
+        }
+        if (rule.category === RuleCategory.Network) {
+            return NetworkRuleConverter.convertToUbo(rule);
+        }
+        return createConversionResult([rule], false);
+    }
+}
+
+export { RuleConverter };