@adguard/agtree 2.1.3 → 3.0.0-alpha.1

package/dist/esm/compatibility-tables/utils/platform-helpers.mjs

@@ -0,0 +1,105 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { SpecificPlatform, GenericPlatform } from '../platforms.mjs';
+
+/* eslint-disable no-bitwise */
+/**
+ * @file Provides platform mapping and helper functions.
+ */
+/**
+ * Map of specific platforms string names to their corresponding enum values.
+ */
+const SPECIFIC_PLATFORM_MAP = new Map([
+    ['adg_os_windows', SpecificPlatform.AdgOsWindows],
+    ['adg_os_mac', SpecificPlatform.AdgOsMac],
+    ['adg_os_android', SpecificPlatform.AdgOsAndroid],
+    ['adg_ext_chrome', SpecificPlatform.AdgExtChrome],
+    ['adg_ext_opera', SpecificPlatform.AdgExtOpera],
+    ['adg_ext_edge', SpecificPlatform.AdgExtEdge],
+    ['adg_ext_firefox', SpecificPlatform.AdgExtFirefox],
+    ['adg_cb_android', SpecificPlatform.AdgCbAndroid],
+    ['adg_cb_ios', SpecificPlatform.AdgCbIos],
+    ['adg_cb_safari', SpecificPlatform.AdgCbSafari],
+    ['ubo_ext_chrome', SpecificPlatform.UboExtChrome],
+    ['ubo_ext_opera', SpecificPlatform.UboExtOpera],
+    ['ubo_ext_edge', SpecificPlatform.UboExtEdge],
+    ['ubo_ext_firefox', SpecificPlatform.UboExtFirefox],
+    ['abp_ext_chrome', SpecificPlatform.AbpExtChrome],
+    ['abp_ext_opera', SpecificPlatform.AbpExtOpera],
+    ['abp_ext_edge', SpecificPlatform.AbpExtEdge],
+    ['abp_ext_firefox', SpecificPlatform.AbpExtFirefox],
+]);
+/**
+ * Map of specific platforms enum values to their corresponding string names.
+ *
+ * @note Reverse of {@link SPECIFIC_PLATFORM_MAP}.
+ */
+const SPECIFIC_PLATFORM_MAP_REVERSE = new Map([...SPECIFIC_PLATFORM_MAP].map(([key, value]) => [value, key]));
+/**
+ * Map of generic platforms string names to their corresponding enum values.
+ */
+const GENERIC_PLATFORM_MAP = new Map([
+    ['adg_os_any', GenericPlatform.AdgOsAny],
+    ['adg_safari_any', GenericPlatform.AdgSafariAny],
+    ['adg_ext_chromium', GenericPlatform.AdgExtChromium],
+    ['adg_ext_any', GenericPlatform.AdgExtAny],
+    ['adg_any', GenericPlatform.AdgAny],
+    ['ubo_ext_chromium', GenericPlatform.UboExtChromium],
+    ['ubo_ext_any', GenericPlatform.UboExtAny],
+    ['ubo_any', GenericPlatform.UboAny],
+    ['abp_ext_chromium', GenericPlatform.AbpExtChromium],
+    ['abp_ext_any', GenericPlatform.AbpExtAny],
+    ['abp_any', GenericPlatform.AbpAny],
+    ['any', GenericPlatform.Any],
+]);
+/**
+ * Check if the platform is a generic platform.
+ *
+ * @param platform Platform to check.
+ *
+ * @returns True if the platform is a generic platform, false otherwise.
+ */
+const isGenericPlatform = (platform) => {
+    // if more than one bit is set, it's a generic platform
+    return !!(platform & (platform - 1));
+};
+/**
+ * Returns the platform enum value for the given platform string name.
+ *
+ * @param platform Platform string name, e.g., 'adg_os_windows'.
+ *
+ * @returns Specific or generic platform enum value.
+ * @throws Error if the platform is unknown.
+ */
+const getPlatformId = (platform) => {
+    const specificPlatform = SPECIFIC_PLATFORM_MAP.get(platform);
+    if (specificPlatform) {
+        return specificPlatform;
+    }
+    const genericPlatform = GENERIC_PLATFORM_MAP.get(platform);
+    if (genericPlatform) {
+        return genericPlatform;
+    }
+    throw new Error(`Unknown platform: ${platform}`);
+};
+/**
+ * Returns the specific platform string name for the given platform enum value.
+ *
+ * @param platform Specific platform enum value.
+ *
+ * @returns Specific platform string name, e.g., 'adg_os_windows'.
+ * @throws Error if the platform is unknown.
+ */
+const getSpecificPlatformName = (platform) => {
+    const specificPlatform = SPECIFIC_PLATFORM_MAP_REVERSE.get(platform);
+    if (!specificPlatform) {
+        throw new Error(`Unknown platform: ${platform}`);
+    }
+    return specificPlatform;
+};
+
+export { GENERIC_PLATFORM_MAP, SPECIFIC_PLATFORM_MAP, SPECIFIC_PLATFORM_MAP_REVERSE, getPlatformId, getSpecificPlatformName, isGenericPlatform };

package/dist/esm/compatibility-tables/utils/resource-type-helpers.mjs

@@ -0,0 +1,61 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { isNull } from '../../utils/type-guards.mjs';
+import { modifiersCompatibilityTable } from '../modifiers.mjs';
+import { ResourceType } from '../schemas/resource-type.mjs';
+
+/**
+ * Map of resource types to their corresponding adblock modifier names.
+ *
+ * @note Record type is used to ensure that all resource types are present in the map.
+ */
+const RESOURCE_TYPE_MODIFIER_MAP = Object.freeze({
+    [ResourceType.MainFrame]: 'document',
+    [ResourceType.SubFrame]: 'subdocument',
+    [ResourceType.Stylesheet]: 'stylesheet',
+    [ResourceType.Script]: 'script',
+    [ResourceType.Image]: 'image',
+    [ResourceType.Font]: 'font',
+    [ResourceType.Object]: 'object',
+    [ResourceType.XmlHttpRequest]: 'xmlhttprequest',
+    [ResourceType.Ping]: 'ping',
+    [ResourceType.Media]: 'media',
+    [ResourceType.WebSocket]: 'websocket',
+    [ResourceType.Other]: 'other',
+});
+/**
+ * Gets the adblock modifier name for the given resource type.
+ *
+ * @param resourceType Resource type to get the modifier name for.
+ * @param platform Platform to get the modifier for.
+ *
+ * @returns A string containing the adblock modifier name for the given resource type
+ * or `null` if the modifier could not be found.
+ */
+const getResourceTypeModifier = (resourceType, platform) => {
+    const modifierName = RESOURCE_TYPE_MODIFIER_MAP[resourceType];
+    if (!modifierName) {
+        return null;
+    }
+    const modifierData = modifiersCompatibilityTable.getFirst(modifierName, platform);
+    if (isNull(modifierData)) {
+        return null;
+    }
+    return modifierData.name;
+};
+/**
+ * Checks if the given resource type is valid.
+ *
+ * @param resourceType Resource type to check.
+ *
+ * @returns `true` if the resource type is valid, `false` otherwise.
+ */
+const isValidResourceType = (resourceType) => {
+    return Object.values(ResourceType).includes(resourceType);
+};
+
+export { getResourceTypeModifier, isValidResourceType };

package/dist/esm/compatibility-tables/utils/zod-camelcase.mjs

@@ -0,0 +1,25 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import camelCaseKeys from 'camelcase-keys';
+
+/**
+ * @file Zod camelCase utility.
+ */
+/**
+ * Transforms Zod schema to camelCase.
+ *
+ * @param zod Zod schema.
+ *
+ * @returns Zod schema with camelCase properties.
+ *
+ * @see {@link https://github.com/colinhacks/zod/issues/486#issuecomment-1501097361}
+ */
+const zodToCamelCase = (zod) => {
+    return zod.transform((val) => camelCaseKeys(val));
+};
+
+export { zodToCamelCase };

package/dist/esm/converter/base-interfaces/base-converter.mjs

@@ -0,0 +1,59 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { NotImplementedError } from '../../errors/not-implemented-error.mjs';
+
+/**
+ * @file Base class for converters
+ *
+ * TS doesn't support abstract static methods, so we should use
+ * a workaround and extend this class instead of implementing it
+ */
+/* eslint-disable jsdoc/require-returns-check */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * Basic class for rule converters
+ */
+class BaseConverter {
+    /**
+     * Converts some data to AdGuard format
+     *
+     * @param data Data to convert
+     * @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 data is invalid or incompatible
+     */
+    static convertToAdg(data) {
+        throw new NotImplementedError();
+    }
+    /**
+     * Converts some data to Adblock Plus format
+     *
+     * @param data Data to convert
+     * @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 data is invalid or incompatible
+     */
+    static convertToAbp(data) {
+        throw new NotImplementedError();
+    }
+    /**
+     * Converts some data to uBlock Origin format
+     *
+     * @param data Data to convert
+     * @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 data is invalid or incompatible
+     */
+    static convertToUbo(data) {
+        throw new NotImplementedError();
+    }
+}
+
+export { BaseConverter };

package/dist/esm/converter/base-interfaces/conversion-result.mjs

@@ -0,0 +1,38 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+/**
+ * @file Conversion result interface and helper functions
+ */
+/**
+ * Helper function to create a generic conversion result.
+ *
+ * @param result Conversion result
+ * @param isConverted Indicates whether the input item was converted
+ * @template T Type of the item to convert
+ * @template U Type of the conversion result (defaults to `T`, but can be `T[]` as well)
+ * @returns Generic conversion result
+ */
+// eslint-disable-next-line max-len
+function createConversionResult(result, isConverted) {
+    return {
+        result,
+        isConverted,
+    };
+}
+/**
+ * Helper function to create a node conversion result.
+ *
+ * @param nodes Array of nodes
+ * @param isConverted Indicates whether the input item was converted
+ * @template T Type of the node (extends `Node`)
+ * @returns Node conversion result
+ */
+function createNodeConversionResult(nodes, isConverted) {
+    return createConversionResult(nodes, isConverted);
+}
+
+export { createConversionResult, createNodeConversionResult };

package/dist/esm/converter/base-interfaces/rule-converter-base.mjs

@@ -0,0 +1,60 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { NotImplementedError } from '../../errors/not-implemented-error.mjs';
+import { BaseConverter } from './base-converter.mjs';
+
+/**
+ * @file Base class for rule converters
+ *
+ * TS doesn't support abstract static methods, so we should use
+ * a workaround and extend this class instead of implementing it
+ */
+/* eslint-disable jsdoc/require-returns-check */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * Basic class for rule converters
+ */
+class RuleConverterBase extends BaseConverter {
+    /**
+     * 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) {
+        throw new NotImplementedError();
+    }
+    /**
+     * Converts an adblock filtering rule to Adblock Plus 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 convertToAbp(rule) {
+        throw new NotImplementedError();
+    }
+    /**
+     * 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
+     */
+    static convertToUbo(rule) {
+        throw new NotImplementedError();
+    }
+}
+
+export { RuleConverterBase };

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

@@ -0,0 +1,54 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { CommentRuleType, CommentMarker } from '../../nodes/index.mjs';
+import { SPACE } from '../../utils/constants.mjs';
+import { RuleConverterBase } from '../base-interfaces/rule-converter-base.mjs';
+import { clone } from '../../utils/clone.mjs';
+import { createNodeConversionResult } from '../base-interfaces/conversion-result.mjs';
+
+/**
+ * @file Comment rule converter
+ */
+/**
+ * Comment rule converter class
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class CommentRuleConverter extends RuleConverterBase {
+    /**
+     * Converts a comment 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 other comment types, if needed
+        // Main task is # -> ! conversion
+        switch (rule.type) {
+            case CommentRuleType.CommentRule:
+                // Check if the rule needs to be converted
+                if (rule.type === CommentRuleType.CommentRule && rule.marker.value === CommentMarker.Hashmark) {
+                    // Add a ! to the beginning of the comment
+                    // TODO: Replace with custom clone method
+                    const ruleClone = clone(rule);
+                    ruleClone.marker.value = CommentMarker.Regular;
+                    // Add the hashmark to the beginning of the comment text
+                    ruleClone.text.value = `${SPACE}${CommentMarker.Hashmark}${ruleClone.text.value}`;
+                    return createNodeConversionResult([ruleClone], true);
+                }
+                return createNodeConversionResult([rule], false);
+            // Leave any other comment rule as is
+            default:
+                return createNodeConversionResult([rule], false);
+        }
+    }
+}
+
+export { CommentRuleConverter };

package/dist/esm/converter/cosmetic/css.mjs

@@ -0,0 +1,69 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { CosmeticRuleSeparator } from '../../nodes/index.mjs';
+import { RuleConverterBase } from '../base-interfaces/rule-converter-base.mjs';
+import { CssSelectorConverter } from '../css/index.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { clone } from '../../utils/clone.mjs';
+import { createNodeConversionResult } from '../base-interfaces/conversion-result.mjs';
+import { CssTokenStream } from '../../parser/css/css-token-stream.mjs';
+
+/**
+ * @file CSS injection rule converter
+ */
+/**
+ * CSS injection rule converter class
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class CssInjectionRuleConverter extends RuleConverterBase {
+    /**
+     * Converts a CSS injection 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) {
+        const separator = rule.separator.value;
+        let convertedSeparator = separator;
+        const stream = new CssTokenStream(rule.body.selectorList.value);
+        const convertedSelectorList = CssSelectorConverter.convertToAdg(stream);
+        // Change the separator if the rule contains ExtendedCSS elements,
+        // but do not force non-extended CSS separator if the rule does not contain any ExtendedCSS selectors,
+        // because sometimes we use it to force executing ExtendedCSS library.
+        if (stream.hasAnySelectorExtendedCssNodeStrict() || rule.body.remove) {
+            convertedSeparator = rule.exception
+                ? CosmeticRuleSeparator.AdgExtendedCssInjectionException
+                : CosmeticRuleSeparator.AdgExtendedCssInjection;
+        }
+        else if (rule.syntax !== AdblockSyntax.Adg) {
+            // If the original rule syntax is not AdGuard, use the default separator
+            // e.g. if the input rule is from uBO, we need to convert ## to #$#.
+            convertedSeparator = rule.exception
+                ? CosmeticRuleSeparator.AdgCssInjectionException
+                : CosmeticRuleSeparator.AdgCssInjection;
+        }
+        // Check if the rule needs to be converted
+        if (!(rule.syntax === AdblockSyntax.Common || rule.syntax === AdblockSyntax.Adg)
+            || separator !== convertedSeparator
+            || convertedSelectorList.isConverted) {
+            // TODO: Replace with custom clone method
+            const ruleClone = clone(rule);
+            ruleClone.syntax = AdblockSyntax.Adg;
+            ruleClone.separator.value = convertedSeparator;
+            ruleClone.body.selectorList.value = convertedSelectorList.result;
+            return createNodeConversionResult([ruleClone], true);
+        }
+        // Otherwise, return the original rule
+        return createNodeConversionResult([rule], false);
+    }
+}
+
+export { CssInjectionRuleConverter };

package/dist/esm/converter/cosmetic/element-hiding.mjs

@@ -0,0 +1,62 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { CosmeticRuleSeparator } from '../../nodes/index.mjs';
+import { RuleConverterBase } from '../base-interfaces/rule-converter-base.mjs';
+import { CssSelectorConverter } from '../css/index.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { clone } from '../../utils/clone.mjs';
+import { createNodeConversionResult } from '../base-interfaces/conversion-result.mjs';
+import { CssTokenStream } from '../../parser/css/css-token-stream.mjs';
+
+/**
+ * @file Element hiding rule converter
+ */
+/**
+ * Element hiding rule converter class
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class ElementHidingRuleConverter extends RuleConverterBase {
+    /**
+     * Converts an element hiding 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) {
+        const separator = rule.separator.value;
+        let convertedSeparator = separator;
+        const stream = new CssTokenStream(rule.body.selectorList.value);
+        const convertedSelectorList = CssSelectorConverter.convertToAdg(stream);
+        // Change the separator if the rule contains ExtendedCSS elements,
+        // but do not force non-extended CSS separator if the rule does not contain any ExtendedCSS selectors,
+        // because sometimes we use it to force executing ExtendedCSS library.
+        if (stream.hasAnySelectorExtendedCssNodeStrict()) {
+            convertedSeparator = rule.exception
+                ? CosmeticRuleSeparator.ExtendedElementHidingException
+                : CosmeticRuleSeparator.ExtendedElementHiding;
+        }
+        // Check if the rule needs to be converted
+        if (!(rule.syntax === AdblockSyntax.Common || rule.syntax === AdblockSyntax.Adg)
+            || separator !== convertedSeparator
+            || convertedSelectorList.isConverted) {
+            // TODO: Replace with custom clone method
+            const ruleClone = clone(rule);
+            ruleClone.syntax = AdblockSyntax.Adg;
+            ruleClone.separator.value = convertedSeparator;
+            ruleClone.body.selectorList.value = convertedSelectorList.result;
+            return createNodeConversionResult([ruleClone], true);
+        }
+        // Otherwise, return the original rule
+        return createNodeConversionResult([rule], false);
+    }
+}
+
+export { ElementHidingRuleConverter };

package/dist/esm/converter/cosmetic/header-removal.mjs

@@ -0,0 +1,123 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { TokenType, getFormattedTokenName } from '@adguard/css-tokenizer';
+import { sprintf } from 'sprintf-js';
+import { RuleConversionError } from '../../errors/rule-conversion-error.mjs';
+import { RuleCategory, CosmeticRuleType } from '../../nodes/index.mjs';
+import { RuleConverterBase } from '../base-interfaces/rule-converter-base.mjs';
+import { createModifierListNode, createModifierNode } from '../../ast-utils/modifiers.mjs';
+import { UBO_HTML_MASK, EMPTY } from '../../utils/constants.mjs';
+import { ADBLOCK_URL_START, ADBLOCK_URL_SEPARATOR } from '../../utils/regexp.mjs';
+import { createNetworkRuleNode } from '../../ast-utils/network-rules.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { createNodeConversionResult } from '../base-interfaces/conversion-result.mjs';
+import { CssTokenStream } from '../../parser/css/css-token-stream.mjs';
+
+/**
+ * @file Converter for request header removal rules
+ */
+const UBO_RESPONSEHEADER_FN = 'responseheader';
+const ADG_REMOVEHEADER_MODIFIER = 'removeheader';
+const ERROR_MESSAGES = {
+    EMPTY_PARAMETER: `Empty parameter for '${UBO_RESPONSEHEADER_FN}' function`,
+    EXPECTED_END_OF_RULE: "Expected end of rule, but got '%s'",
+    MULTIPLE_DOMAINS_NOT_SUPPORTED: 'Multiple domains are not supported yet',
+};
+/**
+ * Converter for request header removal rules
+ *
+ * @todo Implement `convertToUbo` (ABP currently doesn't support header removal rules)
+ */
+class HeaderRemovalRuleConverter extends RuleConverterBase {
+    /**
+     * Converts a header removal rule to AdGuard syntax, 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
+     * @example
+     * If the input rule is:
+     * ```adblock
+     * example.com##^responseheader(header-name)
+     * ```
+     * The output will be:
+     * ```adblock
+     * ||example.com^$removeheader=header-name
+     * ```
+     */
+    static convertToAdg(rule) {
+        // TODO: Add support for ABP syntax once it starts supporting header removal rules
+        // Leave the rule as is if it's not a header removal rule
+        if (rule.category !== RuleCategory.Cosmetic || rule.type !== CosmeticRuleType.HtmlFilteringRule) {
+            return createNodeConversionResult([rule], false);
+        }
+        const stream = new CssTokenStream(rule.body.value);
+        let token;
+        // Skip leading whitespace
+        stream.skipWhitespace();
+        // Next token should be the `^` followed by a `responseheader` function
+        token = stream.get();
+        if (!token || token.type !== TokenType.Delim || rule.body.value[token.start] !== UBO_HTML_MASK) {
+            return createNodeConversionResult([rule], false);
+        }
+        stream.advance();
+        token = stream.get();
+        if (!token) {
+            return createNodeConversionResult([rule], false);
+        }
+        const functionName = rule.body.value.slice(token.start, token.end - 1);
+        if (functionName !== UBO_RESPONSEHEADER_FN) {
+            return createNodeConversionResult([rule], false);
+        }
+        // Parse the parameter
+        const paramStart = token.end;
+        stream.skipUntilBalanced();
+        const paramEnd = stream.getOrFail().end;
+        const param = rule.body.value.slice(paramStart, paramEnd - 1).trim();
+        // Do not allow empty parameter
+        if (param.length === 0) {
+            throw new RuleConversionError(ERROR_MESSAGES.EMPTY_PARAMETER);
+        }
+        stream.expect(TokenType.CloseParenthesis);
+        stream.advance();
+        // Skip trailing whitespace after the function call
+        stream.skipWhitespace();
+        // Expect the end of the rule - so nothing should be left in the stream
+        if (!stream.isEof()) {
+            token = stream.getOrFail();
+            throw new RuleConversionError(sprintf(ERROR_MESSAGES.EXPECTED_END_OF_RULE, getFormattedTokenName(token.type)));
+        }
+        // Prepare network rule pattern
+        const pattern = [];
+        if (rule.domains.children.length === 1) {
+            // If the rule has only one domain, we can use a simple network rule pattern:
+            // ||single-domain-from-the-rule^
+            pattern.push(ADBLOCK_URL_START, rule.domains.children[0].value, ADBLOCK_URL_SEPARATOR);
+        }
+        else if (rule.domains.children.length > 1) {
+            // TODO: Add support for multiple domains, for example:
+            // example.com,example.org,example.net##^responseheader(header-name)
+            // We should consider allowing $domain with $removeheader modifier,
+            // for example:
+            // $removeheader=header-name,domain=example.com|example.org|example.net
+            throw new RuleConversionError(ERROR_MESSAGES.MULTIPLE_DOMAINS_NOT_SUPPORTED);
+        }
+        // Prepare network rule modifiers
+        const modifiers = createModifierListNode();
+        modifiers.children.push(createModifierNode(ADG_REMOVEHEADER_MODIFIER, param));
+        // Construct the network rule
+        return createNodeConversionResult([
+            createNetworkRuleNode(pattern.join(EMPTY), modifiers, 
+            // Copy the exception flag
+            rule.exception, AdblockSyntax.Adg),
+        ], true);
+    }
+}
+
+export { ERROR_MESSAGES, HeaderRemovalRuleConverter };