@adguard/agtree 2.1.2 → 3.0.0-alpha.1

package/dist/cjs/converter/cosmetic/header-removal.js

@@ -0,0 +1,126 @@
+/*
+ * 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
+ */
+'use strict';
+
+var cssTokenizer = require('@adguard/css-tokenizer');
+var sprintfJs = require('sprintf-js');
+var ruleConversionError = require('../../errors/rule-conversion-error.js');
+var index = require('../../nodes/index.js');
+var ruleConverterBase = require('../base-interfaces/rule-converter-base.js');
+var modifiers = require('../../ast-utils/modifiers.js');
+var constants = require('../../utils/constants.js');
+var regexp = require('../../utils/regexp.js');
+var networkRules = require('../../ast-utils/network-rules.js');
+var adblockers = require('../../utils/adblockers.js');
+var conversionResult = require('../base-interfaces/conversion-result.js');
+var cssTokenStream = require('../../parser/css/css-token-stream.js');
+
+/**
+ * @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.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 !== index.RuleCategory.Cosmetic || rule.type !== index.CosmeticRuleType.HtmlFilteringRule) {
+            return conversionResult.createNodeConversionResult([rule], false);
+        }
+        const stream = new cssTokenStream.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 !== cssTokenizer.TokenType.Delim || rule.body.value[token.start] !== constants.UBO_HTML_MASK) {
+            return conversionResult.createNodeConversionResult([rule], false);
+        }
+        stream.advance();
+        token = stream.get();
+        if (!token) {
+            return conversionResult.createNodeConversionResult([rule], false);
+        }
+        const functionName = rule.body.value.slice(token.start, token.end - 1);
+        if (functionName !== UBO_RESPONSEHEADER_FN) {
+            return conversionResult.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.RuleConversionError(ERROR_MESSAGES.EMPTY_PARAMETER);
+        }
+        stream.expect(cssTokenizer.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.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.EXPECTED_END_OF_RULE, cssTokenizer.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(regexp.ADBLOCK_URL_START, rule.domains.children[0].value, regexp.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.RuleConversionError(ERROR_MESSAGES.MULTIPLE_DOMAINS_NOT_SUPPORTED);
+        }
+        // Prepare network rule modifiers
+        const modifiers$1 = modifiers.createModifierListNode();
+        modifiers$1.children.push(modifiers.createModifierNode(ADG_REMOVEHEADER_MODIFIER, param));
+        // Construct the network rule
+        return conversionResult.createNodeConversionResult([
+            networkRules.createNetworkRuleNode(pattern.join(constants.EMPTY), modifiers$1, 
+            // Copy the exception flag
+            rule.exception, adblockers.AdblockSyntax.Adg),
+        ], true);
+    }
+}
+
+exports.ERROR_MESSAGES = ERROR_MESSAGES;
+exports.HeaderRemovalRuleConverter = HeaderRemovalRuleConverter;

package/dist/cjs/converter/cosmetic/html.js

@@ -0,0 +1,384 @@
+/*
+ * 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
+ */
+'use strict';
+
+var cssTokenizer = require('@adguard/css-tokenizer');
+var sprintfJs = require('sprintf-js');
+var index = require('../../nodes/index.js');
+var adblockers = require('../../utils/adblockers.js');
+var ruleConversionError = require('../../errors/rule-conversion-error.js');
+var ruleConverterBase = require('../base-interfaces/rule-converter-base.js');
+var regexp = require('../../utils/regexp.js');
+var conversionResult = require('../base-interfaces/conversion-result.js');
+var clone = require('../../ast-utils/clone.js');
+var cssTokenStream = require('../../parser/css/css-token-stream.js');
+var constants = require('../../utils/constants.js');
+var string = require('../../utils/string.js');
+
+/**
+ * @file HTML filtering rule converter
+ */
+/**
+ * From the AdGuard docs:
+ * Specifies the maximum length for content of HTML element. If this parameter is
+ * set and the content length exceeds the value, a rule does not apply to the element.
+ * If this parameter is not specified, the max-length is considered to be 8192 (8 KB).
+ * When converting from other formats, we set the max-length to 262144 (256 KB).
+ *
+ * @see {@link https://adguard.com/kb/general/ad-filtering/create-own-filters/#html-filtering-rules}
+ */
+const ADG_HTML_DEFAULT_MAX_LENGTH = 8192;
+const ADG_HTML_CONVERSION_MAX_LENGTH = ADG_HTML_DEFAULT_MAX_LENGTH * 32;
+const NOT_SPECIFIED = -1;
+var PseudoClasses;
+(function (PseudoClasses) {
+    PseudoClasses["Contains"] = "contains";
+    PseudoClasses["HasText"] = "has-text";
+    PseudoClasses["MinTextLength"] = "min-text-length";
+})(PseudoClasses || (PseudoClasses = {}));
+var AttributeSelectors;
+(function (AttributeSelectors) {
+    AttributeSelectors["MaxLength"] = "max-length";
+    AttributeSelectors["MinLength"] = "min-length";
+    AttributeSelectors["TagContent"] = "tag-content";
+    AttributeSelectors["Wildcard"] = "wildcard";
+})(AttributeSelectors || (AttributeSelectors = {}));
+const SUPPORTED_UBO_PSEUDO_CLASSES = new Set([
+    PseudoClasses.Contains,
+    PseudoClasses.HasText,
+    PseudoClasses.MinTextLength,
+]);
+const ERROR_MESSAGES = {
+    ABP_NOT_SUPPORTED: 'Invalid rule, ABP does not support HTML filtering rules',
+    TAG_SHOULD_BE_FIRST_CHILD: "Unexpected token '%s' with value '%s', tag selector should be the first child",
+    EXPECTED_BUT_GOT_WITH_VALUE: "Expected '%s', but got '%s' with value '%s'",
+    INVALID_ATTRIBUTE_NAME: "Attribute name should be an identifier, but got '%s' with value '%s'",
+    // eslint-disable-next-line max-len
+    INVALID_ATTRIBUTE_VALUE: `Expected '${cssTokenizer.getFormattedTokenName(cssTokenizer.TokenType.Ident)}' or '${cssTokenizer.getFormattedTokenName(cssTokenizer.TokenType.String)}' as attribute value, but got '%s' with value '%s`,
+    INVALID_FLAG: "Unsupported attribute selector flag '%s'",
+    INVALID_OPERATOR_FOR_ATTR: "Unsupported operator '%s' for '%s' attribute",
+    VALUE_FOR_ATTR_SHOULD_BE_INT: "Value for '%s' attribute should be an integer, but got '%s'",
+    INVALID_PSEUDO_CLASS: "Unsupported pseudo class '%s'",
+    VALUE_FOR_PSEUDO_CLASS_SHOULD_BE_INT: "Value for '%s' pseudo class should be an integer, but got '%s'",
+    // eslint-disable-next-line max-len
+    REGEXP_NOT_SUPPORTED: "Cannot convert RegExp parameter '%s' from '%s' pseudo class, because converting RegExp patterns are not supported yet",
+    ATTRIBUTE_SELECTOR_REQUIRES_VALUE: "Attribute selector '%s' requires a value",
+    INVALID_ATTRIBUTE_SELECTOR_OPERATOR: "Unsupported attribute selector operator '%s'",
+    VALUE_SHOULD_BE_SPECIFIED: 'Value should be specified if operator is specified',
+    OPERATOR_SHOULD_BE_SPECIFIED: 'Operator should be specified if value is specified',
+    UNEXPECTED_TOKEN_WITH_VALUE: "Unexpected token '%s' with value '%s'",
+    FLAGS_NOT_SUPPORTED: 'Flags are not supported for attribute selectors',
+};
+/**
+ * Convert `""` to `\"` within strings, because it does not compatible with the standard CSS syntax.
+ *
+ * @param selector CSS selector string
+ * @returns Escaped CSS selector
+ * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used in the standard CSS syntax,
+ * so we use conversion functions to handle this.
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
+ */
+function escapeDoubleQuotes(selector) {
+    let withinString = false;
+    const buffer = [];
+    for (let i = 0; i < selector.length; i += 1) {
+        if (!withinString && selector[i] === string.DOUBLE_QUOTE_MARKER) {
+            withinString = true;
+            buffer.push(selector[i]);
+        }
+        else if (withinString && selector[i] === string.DOUBLE_QUOTE_MARKER && selector[i + 1] === string.DOUBLE_QUOTE_MARKER) {
+            buffer.push(constants.ESCAPE_CHARACTER);
+            buffer.push(string.DOUBLE_QUOTE_MARKER);
+            i += 1;
+        }
+        else if (withinString && selector[i] === string.DOUBLE_QUOTE_MARKER && selector[i + 1] !== string.DOUBLE_QUOTE_MARKER) {
+            buffer.push(string.DOUBLE_QUOTE_MARKER);
+            withinString = false;
+        }
+        else {
+            buffer.push(selector[i]);
+        }
+    }
+    return buffer.join(constants.EMPTY);
+}
+/**
+ * Convert escaped double quotes `\"` to `""` within strings.
+ *
+ * @param selector CSS selector string
+ * @returns Unescaped CSS selector
+ * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used in the standard CSS syntax,
+ * so we use conversion functions to handle this.
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
+ */
+function unescapeDoubleQuotes(selector) {
+    let withinString = false;
+    const buffer = [];
+    for (let i = 0; i < selector.length; i += 1) {
+        if (selector[i] === string.DOUBLE_QUOTE_MARKER && selector[i - 1] !== constants.ESCAPE_CHARACTER) {
+            withinString = !withinString;
+            buffer.push(selector[i]);
+        }
+        else if (withinString && selector[i] === constants.ESCAPE_CHARACTER && selector[i + 1] === string.DOUBLE_QUOTE_MARKER) {
+            buffer.push(string.DOUBLE_QUOTE_MARKER);
+        }
+        else {
+            buffer.push(selector[i]);
+        }
+    }
+    return buffer.join(constants.EMPTY);
+}
+/**
+ * Helper function to render an attribute selector
+ *
+ * @param attr Attribute name
+ * @param op Operator (optional)
+ * @param value Attribute value (optional)
+ * @param flags Attribute flags (optional)
+ * @returns Rendered attribute selector string
+ */
+function renderAttrSelector(attr, op, value, flags) {
+    const result = [];
+    result.push(constants.OPEN_SQUARE_BRACKET);
+    result.push(attr);
+    {
+        if (value === undefined) {
+            throw new Error(ERROR_MESSAGES.VALUE_SHOULD_BE_SPECIFIED);
+        }
+        result.push(op);
+    }
+    if (value !== undefined) {
+        result.push(string.DOUBLE_QUOTE_MARKER);
+        result.push(value);
+        result.push(string.DOUBLE_QUOTE_MARKER);
+    }
+    result.push(constants.CLOSE_SQUARE_BRACKET);
+    return result.join(constants.EMPTY);
+}
+/**
+ * HTML filtering rule converter class
+ *
+ * @todo Implement `convertToUbo` (ABP currently doesn't support HTML filtering rules)
+ */
+class HtmlRuleConverter extends ruleConverterBase.RuleConverterBase {
+    /**
+     * Converts a HTML rule to AdGuard syntax, if possible. Also can be used to convert
+     * AdGuard rules to AdGuard syntax to validate them.
+     *
+     * _Note:_ uBlock Origin supports multiple selectors within a single rule, but AdGuard doesn't,
+     * so the following rule
+     * ```
+     * example.com##^div[attr1="value1"][attr2="value2"], script:has-text(value)
+     * ```
+     * will be converted to multiple AdGuard rules:
+     * ```
+     * example.com$$div[attr1="value1"][attr2="value2"][max-length="262144"]
+     * example.com$$script[tag-content="value"][max-length="262144"]
+     * ```
+     *
+     * @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) {
+        // Ignore AdGuard rules
+        if (rule.syntax === adblockers.AdblockSyntax.Adg) {
+            return conversionResult.createNodeConversionResult([rule], false);
+        }
+        if (rule.syntax === adblockers.AdblockSyntax.Abp) {
+            throw new ruleConversionError.RuleConversionError(ERROR_MESSAGES.ABP_NOT_SUPPORTED);
+        }
+        const source = escapeDoubleQuotes(rule.body.value);
+        const stream = new cssTokenStream.CssTokenStream(source);
+        const convertedSelector = [];
+        const convertedSelectorList = [];
+        let minLen = NOT_SPECIFIED;
+        let maxLen = NOT_SPECIFIED;
+        // Skip leading whitespace
+        stream.skipWhitespace();
+        // Skip ^
+        stream.expect(cssTokenizer.TokenType.Delim, { value: constants.UBO_HTML_MASK });
+        stream.advance();
+        while (!stream.isEof()) {
+            const token = stream.getOrFail();
+            if (token.type === cssTokenizer.TokenType.Ident) {
+                // Tag selector should be the first child, if present, but whitespace is allowed before it
+                if (convertedSelector.length !== 0 && stream.lookbehindForNonWs() !== undefined) {
+                    throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.TAG_SHOULD_BE_FIRST_CHILD, cssTokenizer.getFormattedTokenName(token.type), source.slice(token.start, token.end)));
+                }
+                convertedSelector.push(source.slice(token.start, token.end));
+                stream.advance();
+            }
+            else if (token.type === cssTokenizer.TokenType.OpenSquareBracket) {
+                // Attribute selectors: https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors#syntax
+                const { start } = token;
+                let tempToken;
+                // Advance opening square bracket
+                stream.advance();
+                // Skip optional whitespace after the opening square bracket
+                stream.skipWhitespace();
+                // Parse attribute name
+                tempToken = stream.getOrFail();
+                if (tempToken.type !== cssTokenizer.TokenType.Ident) {
+                    throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.INVALID_ATTRIBUTE_NAME, cssTokenizer.getFormattedTokenName(tempToken.type), source.slice(tempToken.start, tempToken.end)));
+                }
+                const attr = source.slice(tempToken.start, tempToken.end);
+                stream.advance();
+                // Skip optional whitespace after the attribute name
+                stream.skipWhitespace();
+                // Maybe attribute selector ends here, because value is not required, like in '[disabled]'
+                tempToken = stream.getOrFail();
+                // So check if the next non whitespace token is a closing square bracket
+                if (tempToken.type === cssTokenizer.TokenType.CloseSquareBracket) {
+                    const { end } = tempToken;
+                    stream.advance();
+                    // Special case for min-length and max-length attributes
+                    if (attr === AttributeSelectors.MinLength || attr === AttributeSelectors.MaxLength) {
+                        throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.ATTRIBUTE_SELECTOR_REQUIRES_VALUE, attr));
+                    }
+                    convertedSelector.push(source.slice(start, end));
+                    continue;
+                }
+                // Next token should be a valid attribute selector operator
+                // Only '=' operator is supported
+                stream.expect(cssTokenizer.TokenType.Delim, { value: constants.EQUALS });
+                // Advance the operator
+                stream.advance();
+                // Skip optional whitespace after the operator
+                stream.skipWhitespace();
+                // Parse attribute value
+                tempToken = stream.getOrFail();
+                // According to the spec, attribute value should be an identifier or a string
+                if (tempToken.type !== cssTokenizer.TokenType.Ident && tempToken.type !== cssTokenizer.TokenType.String) {
+                    throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.INVALID_ATTRIBUTE_VALUE, cssTokenizer.getFormattedTokenName(tempToken.type), source.slice(tempToken.start, tempToken.end)));
+                }
+                const value = source.slice(tempToken.start, tempToken.end);
+                // Advance the attribute value
+                stream.advance();
+                // Skip optional whitespace after the attribute value
+                stream.skipWhitespace();
+                // Attribute selector may have flags - but AdGuard HTML filtering does not support them
+                tempToken = stream.getOrFail();
+                if (tempToken.type === cssTokenizer.TokenType.Ident) {
+                    throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.FLAGS_NOT_SUPPORTED));
+                }
+                // Next token should be a closing square bracket
+                stream.expect(cssTokenizer.TokenType.CloseSquareBracket);
+                const { end } = stream.getOrFail();
+                stream.advance();
+                if (attr === AttributeSelectors.MinLength) {
+                    // Min length attribute
+                    const parsed = parseInt(value, 10);
+                    if (Number.isNaN(parsed)) {
+                        throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.VALUE_FOR_ATTR_SHOULD_BE_INT, attr, value));
+                    }
+                    minLen = parsed;
+                }
+                else if (attr === AttributeSelectors.MaxLength) {
+                    // Max length attribute
+                    const parsed = parseInt(value, 10);
+                    if (Number.isNaN(parsed)) {
+                        throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.VALUE_FOR_ATTR_SHOULD_BE_INT, attr, value));
+                    }
+                    maxLen = parsed;
+                }
+                else {
+                    convertedSelector.push(source.slice(start, end));
+                }
+            }
+            else if (token.type === cssTokenizer.TokenType.Colon) {
+                let tempToken;
+                // Pseudo classes: https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#syntax
+                stream.advance();
+                // Next token should be a pseudo class name
+                stream.expect(cssTokenizer.TokenType.Function);
+                tempToken = stream.getOrFail();
+                const fn = source.slice(tempToken.start, tempToken.end - 1); // do not include '('
+                // Pseudo class should be supported
+                if (!SUPPORTED_UBO_PSEUDO_CLASSES.has(fn)) {
+                    throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.INVALID_PSEUDO_CLASS, fn));
+                }
+                const paramStart = tempToken.end;
+                // Find the closing paren
+                stream.skipUntilBalanced();
+                tempToken = stream.getOrFail();
+                const paramEnd = tempToken.end;
+                // Get the parameter
+                const param = source.slice(paramStart, paramEnd - 1);
+                if (fn === PseudoClasses.MinTextLength) {
+                    // Min text length pseudo class
+                    // Parameter should be parsed as an integer
+                    const parsed = parseInt(param, 10);
+                    if (Number.isNaN(parsed)) {
+                        throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.VALUE_FOR_PSEUDO_CLASS_SHOULD_BE_INT, fn, param));
+                    }
+                    minLen = parsed;
+                }
+                else if (fn === PseudoClasses.Contains || fn === PseudoClasses.HasText) {
+                    // Contains and has-text pseudo classes
+                    // Check if the argument is a RegExp
+                    if (regexp.RegExpUtils.isRegexPattern(param)) {
+                        // TODO: Add some support for RegExp patterns later
+                        // Need to find a way to convert some RegExp patterns to glob patterns
+                        throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.REGEXP_NOT_SUPPORTED, param, fn));
+                    }
+                    // Escape unescaped double quotes in the parameter
+                    const paramEscaped = string.StringUtils.escapeCharacter(param, string.DOUBLE_QUOTE_MARKER);
+                    convertedSelector.push(renderAttrSelector(AttributeSelectors.TagContent, constants.EQUALS, paramEscaped));
+                }
+                stream.advance();
+            }
+            else if (token.type === cssTokenizer.TokenType.Comma && token.balance === 0) {
+                if (minLen !== NOT_SPECIFIED) {
+                    convertedSelector.push(renderAttrSelector(AttributeSelectors.MinLength, constants.EQUALS, minLen.toString()));
+                }
+                convertedSelector.push(renderAttrSelector(AttributeSelectors.MaxLength, constants.EQUALS, maxLen !== NOT_SPECIFIED ? maxLen.toString() : ADG_HTML_CONVERSION_MAX_LENGTH.toString()));
+                convertedSelectorList.push(convertedSelector.join(constants.EMPTY));
+                convertedSelector.length = 0;
+                stream.advance();
+            }
+            else if (token.type === cssTokenizer.TokenType.Whitespace) {
+                stream.advance();
+            }
+            else {
+                throw new ruleConversionError.RuleConversionError(sprintfJs.sprintf(ERROR_MESSAGES.UNEXPECTED_TOKEN_WITH_VALUE, cssTokenizer.getFormattedTokenName(token.type), source.slice(token.start, token.end)));
+            }
+        }
+        if (convertedSelector.length !== 0) {
+            if (minLen !== NOT_SPECIFIED) {
+                convertedSelector.push(renderAttrSelector(AttributeSelectors.MinLength, constants.EQUALS, minLen.toString()));
+            }
+            convertedSelector.push(renderAttrSelector(AttributeSelectors.MaxLength, constants.EQUALS, maxLen !== NOT_SPECIFIED ? maxLen.toString() : ADG_HTML_CONVERSION_MAX_LENGTH.toString()));
+            convertedSelectorList.push(convertedSelector.join(constants.EMPTY));
+        }
+        return conversionResult.createNodeConversionResult(
+        // Since AdGuard HTML filtering rules do not support multiple selectors, we need to split each selector
+        // into a separate rule node.
+        convertedSelectorList.map((selector) => ({
+            category: index.RuleCategory.Cosmetic,
+            type: index.CosmeticRuleType.HtmlFilteringRule,
+            syntax: adblockers.AdblockSyntax.Adg,
+            exception: rule.exception,
+            domains: clone.cloneDomainListNode(rule.domains),
+            // Convert the separator based on the exception status
+            separator: {
+                type: 'Value',
+                value: rule.exception
+                    ? index.CosmeticRuleSeparator.AdgHtmlFilteringException
+                    : index.CosmeticRuleSeparator.AdgHtmlFiltering,
+            },
+            body: {
+                type: 'Value',
+                value: unescapeDoubleQuotes(selector),
+            },
+        })), true);
+    }
+}
+
+exports.ERROR_MESSAGES = ERROR_MESSAGES;
+exports.HtmlRuleConverter = HtmlRuleConverter;

package/dist/cjs/converter/cosmetic/index.js

@@ -0,0 +1,120 @@
+/*
+ * 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
+ */
+'use strict';
+
+var index = require('../../nodes/index.js');
+var adblockers = require('../../utils/adblockers.js');
+var html = require('./html.js');
+var scriptlet = require('./scriptlet.js');
+var ruleConversionError = require('../../errors/rule-conversion-error.js');
+var ruleConverterBase = require('../base-interfaces/rule-converter-base.js');
+var adg = require('./rule-modifiers/adg.js');
+var css = require('./css.js');
+var elementHiding = require('./element-hiding.js');
+var headerRemoval = require('./header-removal.js');
+var conversionResult = require('../base-interfaces/conversion-result.js');
+
+/**
+ * @file Cosmetic rule converter
+ */
+/**
+ * Cosmetic rule converter class (also known as "non-basic rule converter")
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+class CosmeticRuleConverter extends ruleConverterBase.RuleConverterBase {
+    /**
+     * Converts a cosmetic 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
+     */
+    static convertToAdg(rule) {
+        let subconverterResult;
+        // Convert cosmetic rule based on its type
+        switch (rule.type) {
+            case index.CosmeticRuleType.ElementHidingRule:
+                subconverterResult = elementHiding.ElementHidingRuleConverter.convertToAdg(rule);
+                break;
+            case index.CosmeticRuleType.ScriptletInjectionRule:
+                subconverterResult = scriptlet.ScriptletRuleConverter.convertToAdg(rule);
+                break;
+            case index.CosmeticRuleType.CssInjectionRule:
+                subconverterResult = css.CssInjectionRuleConverter.convertToAdg(rule);
+                break;
+            case index.CosmeticRuleType.HtmlFilteringRule:
+                // Handle special case: uBO response header filtering rule
+                // TODO: Optimize double CSS tokenization here
+                subconverterResult = headerRemoval.HeaderRemovalRuleConverter.convertToAdg(rule);
+                if (subconverterResult.isConverted) {
+                    break;
+                }
+                subconverterResult = html.HtmlRuleConverter.convertToAdg(rule);
+                break;
+            // Note: Currently, only ADG supports JS injection rules, so we don't need to convert them
+            case index.CosmeticRuleType.JsInjectionRule:
+                subconverterResult = conversionResult.createNodeConversionResult([rule], false);
+                break;
+            default:
+                throw new ruleConversionError.RuleConversionError('Unsupported cosmetic rule type');
+        }
+        let convertedModifiers;
+        // Convert cosmetic rule modifiers, if any
+        if (rule.modifiers) {
+            if (rule.syntax === adblockers.AdblockSyntax.Ubo) {
+                // uBO doesn't support this rule:
+                // example.com##+js(set-constant.js, foo, bar):matches-path(/baz)
+                if (rule.type === index.CosmeticRuleType.ScriptletInjectionRule) {
+                    throw new ruleConversionError.RuleConversionError('uBO scriptlet injection rules don\'t support cosmetic rule modifiers');
+                }
+                convertedModifiers = adg.AdgCosmeticRuleModifierConverter.convertFromUbo(rule.modifiers);
+            }
+            else if (rule.syntax === adblockers.AdblockSyntax.Abp) {
+                // TODO: Implement once ABP starts supporting cosmetic rule modifiers
+                throw new ruleConversionError.RuleConversionError('ABP don\'t support cosmetic rule modifiers');
+            }
+        }
+        if ((subconverterResult.result.length > 1 || subconverterResult.isConverted)
+            || (convertedModifiers && convertedModifiers.isConverted)) {
+            // Add modifier list to the subconverter result rules
+            subconverterResult.result.forEach((subconverterRule) => {
+                if (convertedModifiers && subconverterRule.category === index.RuleCategory.Cosmetic) {
+                    // eslint-disable-next-line no-param-reassign
+                    subconverterRule.modifiers = convertedModifiers.result;
+                }
+            });
+            return subconverterResult;
+        }
+        return conversionResult.createNodeConversionResult([rule], false);
+    }
+    /**
+     * Converts a cosmetic rule to uBlock Origin 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
+     */
+    // TODO: Add support for other cosmetic rule types
+    static convertToUbo(rule) {
+        // Convert cosmetic rule based on its type
+        if (rule.type === index.CosmeticRuleType.ScriptletInjectionRule) {
+            if (rule.syntax === adblockers.AdblockSyntax.Adg && rule.modifiers?.children.length) {
+                // e.g. example.com##+js(set-constant.js, foo, bar):matches-path(/baz)
+                throw new ruleConversionError.RuleConversionError('uBO scriptlet injection rules do not support cosmetic rule modifiers');
+            }
+            return scriptlet.ScriptletRuleConverter.convertToUbo(rule);
+        }
+        return conversionResult.createNodeConversionResult([rule], false);
+    }
+}
+
+exports.CosmeticRuleConverter = CosmeticRuleConverter;