@adguard/agtree 2.1.3 → 3.0.0

package/dist/cjs/parser/misc/parameter-list-parser.js

@@ -0,0 +1,74 @@
+/*
+ * 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
+ */
+'use strict';
+
+var string = require('../../utils/string.js');
+var constants = require('../../utils/constants.js');
+var options = require('../options.js');
+var baseParser = require('../base-parser.js');
+var valueParser = require('./value-parser.js');
+
+class ParameterListParser extends baseParser.BaseParser {
+    /**
+     * Parses a raw parameter list.
+     *
+     * @param raw Raw input to parse.
+     * @param options Global parser options.
+     * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     * @param separator Separator character (default: comma)
+     * @returns Parameter list AST
+     */
+    static parse(raw, options$1 = options.defaultParserOptions, baseOffset = 0, separator = constants.COMMA) {
+        // Prepare the parameter list node
+        const params = {
+            type: 'ParameterList',
+            children: [],
+        };
+        const { length } = raw;
+        if (options$1.isLocIncluded) {
+            params.start = baseOffset;
+            params.end = baseOffset + length;
+        }
+        let offset = 0;
+        // Parse parameters: skip whitespace before and after each parameter, and
+        // split parameters by the separator character.
+        while (offset < length) {
+            // Skip whitespace before parameter
+            offset = string.StringUtils.skipWS(raw, offset);
+            // Parameter may only contain whitespace
+            // In this case, we reached the end of the parameter list
+            if (raw[offset] === separator || offset === length) {
+                // Add a null for empty parameter
+                params.children.push(null);
+                // Skip separator
+                offset += 1;
+            }
+            else {
+                // Get parameter start position
+                const paramStart = offset;
+                // Get next unescaped separator position
+                const nextSeparator = string.StringUtils.findUnescapedNonStringNonRegexChar(raw, separator, offset);
+                // Get parameter end position
+                const paramEnd = nextSeparator !== -1
+                    ? string.StringUtils.skipWSBack(raw, nextSeparator - 1)
+                    : string.StringUtils.skipWSBack(raw);
+                // Add parameter to the list
+                const param = valueParser.ValueParser.parse(raw.slice(paramStart, paramEnd + 1), options$1, baseOffset + paramStart);
+                params.children.push(param);
+                // Set offset to the next separator position + 1
+                offset = nextSeparator !== -1 ? nextSeparator + 1 : length;
+            }
+        }
+        // If the last character was a separator, add an additional null parameter
+        if (raw[length - 1] === separator) {
+            params.children.push(null);
+        }
+        return params;
+    }
+}
+
+exports.ParameterListParser = ParameterListParser;

package/dist/cjs/parser/misc/stealth-option-list-parser.js

@@ -0,0 +1,48 @@
+/*
+ * 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
+ */
+'use strict';
+
+var constants = require('../../utils/constants.js');
+var index = require('../../nodes/index.js');
+var options = require('../options.js');
+var baseParser = require('../base-parser.js');
+var listItemsParser = require('./list-items-parser.js');
+
+const STEALTH_OPTION_LIST_SEPARATOR = constants.PIPE;
+/**
+ * `StealthOptionListParser` is responsible for parsing a list of stealth options.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#stealth-modifier}
+ */
+class StealthOptionListParser extends baseParser.BaseParser {
+    /**
+     * Parses a stealth option list which items are separated by `|`,
+     * e.g. `dpi|ip`.
+     *
+     * @param raw Raw input to parse.
+     * @param options Global parser options.
+     * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     *
+     * @returns Stealth option list AST.
+     * @throws An {@link AdblockSyntaxError} if the stealth option list is syntactically invalid.
+     * @throws An {@link Error} if the options are invalid.
+     */
+    static parse(raw, options$1 = options.defaultParserOptions, baseOffset = 0) {
+        const result = {
+            type: index.ListNodeType.StealthOptionList,
+            separator: STEALTH_OPTION_LIST_SEPARATOR,
+            children: listItemsParser.ListItemsParser.parse(raw, options$1, baseOffset, STEALTH_OPTION_LIST_SEPARATOR, index.ListItemNodeType.StealthOption),
+        };
+        if (options$1.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+exports.StealthOptionListParser = StealthOptionListParser;

package/dist/cjs/parser/misc/ubo-parameter-list-parser.js

@@ -0,0 +1,148 @@
+/*
+ * 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
+ */
+'use strict';
+
+var string = require('../../utils/string.js');
+var constants = require('../../utils/constants.js');
+var options = require('../options.js');
+var valueParser = require('./value-parser.js');
+var adblockSyntaxError = require('../../errors/adblock-syntax-error.js');
+var quotes = require('../../utils/quotes.js');
+var parameterListParser = require('./parameter-list-parser.js');
+
+class UboParameterListParser extends parameterListParser.ParameterListParser {
+    /**
+     * Parses an "uBO-specific parameter list".
+     *
+     * @param raw Raw input to parse.
+     * @param options Global parser options.
+     * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     * @param separator Separator character (default: comma).
+     * @param requireQuotes Whether to require quotes around the parameter values (default: false).
+     * @param supportedQuotes Set of accepted quotes (default: {@link QUOTE_SET}).
+     * @returns Parameter list node.
+     *
+     * @note Based on {@link https://github.com/gorhill/uBlock/blob/f9ab4b75041815e6e5690d80851189ae3dc660d0/src/js/static-filtering-parser.js#L607-L699} to provide consistency.
+     */
+    static parse(raw, options$1 = options.defaultParserOptions, baseOffset = 0, separator = constants.COMMA, requireQuotes = false, supportedQuotes = quotes.QUOTE_SET) {
+        // Prepare the parameter list node
+        const params = {
+            type: 'ParameterList',
+            children: [],
+        };
+        const { length } = raw;
+        if (options$1.isLocIncluded) {
+            params.start = baseOffset;
+            params.end = baseOffset + length;
+        }
+        let offset = 0;
+        // TODO: Eliminate the need for extraNull
+        let extraNull = false;
+        while (offset < length) {
+            offset = string.StringUtils.skipWS(raw, offset);
+            const paramStart = offset;
+            let paramEnd = offset;
+            if (supportedQuotes.has(raw[offset])) {
+                // Find the closing quote
+                const possibleClosingQuoteIndex = string.StringUtils.findNextUnescapedCharacter(raw, raw[offset], offset + 1);
+                if (possibleClosingQuoteIndex !== -1) {
+                    // Next non-whitespace character after the closing quote should be the separator
+                    const nextSeparatorIndex = string.StringUtils.skipWS(raw, possibleClosingQuoteIndex + 1);
+                    if (nextSeparatorIndex === length) {
+                        // If the separator is not found, the param end is the end of the string
+                        paramEnd = string.StringUtils.skipWSBack(raw, length - 1) + 1;
+                        offset = length;
+                    }
+                    else if (raw[nextSeparatorIndex] === separator) {
+                        // If the quote is followed by a separator, we can use it as a closing quote
+                        paramEnd = possibleClosingQuoteIndex + 1;
+                        offset = nextSeparatorIndex + 1;
+                    }
+                    else {
+                        if (requireQuotes) {
+                            throw new adblockSyntaxError.AdblockSyntaxError(`Expected separator, got: '${raw[nextSeparatorIndex]}'`, baseOffset + nextSeparatorIndex, baseOffset + length);
+                        }
+                        /**
+                         * At that point found `possibleClosingQuoteIndex` is wrong
+                         * | is `offset`
+                         * ~ is `possibleClosingQuoteIndex`
+                         * ^ is `nextSeparatorIndex`
+                         *
+                         * Example 1: "abc, ').cba='1'"
+                         *                  |      ~^
+                         * Example 2: "abc, ').cba, '1'"
+                         *                  |       ~^
+                         * Example 3: "abc, ').cba='1', cba"
+                         *                  |      ~^
+                         *
+                         * Search for separator before `possibleClosingQuoteIndex`
+                         */
+                        const separatorIndexBeforeQuote = string.StringUtils.findNextUnescapedCharacterBackwards(raw, separator, possibleClosingQuoteIndex, constants.ESCAPE_CHARACTER, offset + 1);
+                        if (separatorIndexBeforeQuote !== -1) {
+                            // Found separator before (Example 2)
+                            paramEnd = string.StringUtils.skipWSBack(raw, separatorIndexBeforeQuote - 1) + 1;
+                            offset = separatorIndexBeforeQuote + 1;
+                        }
+                        else {
+                            // Didn't found separator before, search after
+                            const separatorIndexAfterQuote = string.StringUtils.findNextUnescapedCharacter(raw, separator, possibleClosingQuoteIndex);
+                            if (separatorIndexAfterQuote !== -1) {
+                                // We found separator after (Example 3)
+                                paramEnd = string.StringUtils.skipWSBack(raw, separatorIndexAfterQuote - 1) + 1;
+                                offset = separatorIndexAfterQuote + 1;
+                            }
+                            else {
+                                // If the separator is not found, the param end is the end of the string (Example 1)
+                                paramEnd = string.StringUtils.skipWSBack(raw, length - 1) + 1;
+                                offset = length;
+                            }
+                        }
+                    }
+                }
+                else {
+                    if (requireQuotes) {
+                        throw new adblockSyntaxError.AdblockSyntaxError('Expected closing quote, got end of string', baseOffset + offset, baseOffset + length);
+                    }
+                    // If the closing quote is not found, the param end is the end of the string
+                    paramEnd = string.StringUtils.skipWSBack(raw, length - 1) + 1;
+                    offset = length;
+                }
+            }
+            else {
+                if (requireQuotes) {
+                    throw new adblockSyntaxError.AdblockSyntaxError(`Expected quote, got: '${raw[offset]}'`, baseOffset + offset, baseOffset + length);
+                }
+                const nextSeparator = string.StringUtils.findNextUnescapedCharacter(raw, separator, offset);
+                if (nextSeparator === -1) {
+                    // If the separator is not found, the param end is the end of the string
+                    paramEnd = string.StringUtils.skipWSBack(raw, length - 1) + 1;
+                    offset = length;
+                }
+                else {
+                    // Param end should be the last non-whitespace character before the separator
+                    paramEnd = string.StringUtils.skipWSBack(raw, nextSeparator - 1) + 1;
+                    offset = nextSeparator + 1;
+                    if (string.StringUtils.skipWS(raw, length - 1) === nextSeparator) {
+                        extraNull = true;
+                    }
+                }
+            }
+            if (paramStart < paramEnd) {
+                params.children.push(valueParser.ValueParser.parse(raw.slice(paramStart, paramEnd), options$1, baseOffset + paramStart));
+            }
+            else {
+                params.children.push(null);
+            }
+        }
+        if (extraNull) {
+            params.children.push(null);
+        }
+        return params;
+    }
+}
+
+exports.UboParameterListParser = UboParameterListParser;

package/dist/cjs/parser/misc/value-parser.js

@@ -0,0 +1,39 @@
+/*
+ * 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
+ */
+'use strict';
+
+var options = require('../options.js');
+var baseParser = require('../base-parser.js');
+
+/**
+ * Value parser.
+ * This parser is very simple, it just exists to provide a consistent interface for parsing and generating values.
+ */
+class ValueParser extends baseParser.BaseParser {
+    /**
+     * Parses a value.
+     *
+     * @param raw Raw input to parse.
+     * @param options Global parser options.
+     * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     *
+     * @returns Value node.
+     */
+    static parse(raw, options$1 = options.defaultParserOptions, baseOffset = 0) {
+        const result = {
+            type: 'Value',
+            value: raw,
+        };
+        if (options$1.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+exports.ValueParser = ValueParser;

package/dist/cjs/parser/network/host-rule-parser.js

@@ -0,0 +1,151 @@
+/*
+ * 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
+ */
+'use strict';
+
+var tldts = require('tldts');
+var isIp = require('is-ip');
+var string = require('../../utils/string.js');
+var index = require('../../nodes/index.js');
+var options = require('../options.js');
+var baseParser = require('../base-parser.js');
+var adblockers = require('../../utils/adblockers.js');
+var valueParser = require('../misc/value-parser.js');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var tldts__namespace = /*#__PURE__*/_interopNamespaceDefault(tldts);
+
+/* eslint-disable no-param-reassign */
+/**
+ * `HostRuleParser` is responsible for parsing hosts-like rules.
+ *
+ * HostRule is a structure for simple host-level rules (i.e. /etc/hosts syntax).
+ * It also supports "just domain" syntax. In this case, the IP will be set to 0.0.0.0.
+ *
+ * Rules syntax looks like this:
+ * ```text
+ * IP_address canonical_hostname [aliases...]
+ * ```
+ *
+ * @example
+ * `192.168.1.13 bar.mydomain.org bar` -- ipv4
+ * `ff02::1 ip6-allnodes` -- ipv6
+ * `::1 localhost ip6-localhost ip6-loopback` -- ipv6 aliases
+ * `example.org` -- "just domain" syntax
+ * @see {@link http://man7.org/linux/man-pages/man5/hosts.5.html}
+ */
+class HostRuleParser extends baseParser.BaseParser {
+    static NULL_IP = '0.0.0.0';
+    static COMMENT_MARKER = '#';
+    /**
+     * Parses an etc/hosts-like rule.
+     *
+     * @param raw Raw input to parse.
+     * @param options Global parser options.
+     * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     * @returns Host rule node.
+     *
+     * @throws If the input contains invalid data.
+     */
+    static parse(raw, options$1 = options.defaultParserOptions, baseOffset = 0) {
+        let offset = string.StringUtils.skipWS(raw, 0);
+        const parts = [];
+        let lastPartStartIndex = offset;
+        let comment = null;
+        const rawLength = raw.length;
+        const parsePartIfNeeded = (startIndex, endIndex) => {
+            if (startIndex < endIndex) {
+                parts.push(valueParser.ValueParser.parse(raw.slice(startIndex, endIndex), options$1, baseOffset + startIndex));
+            }
+        };
+        while (offset < rawLength) {
+            if (string.StringUtils.isWhitespace(raw[offset])) {
+                parsePartIfNeeded(lastPartStartIndex, offset);
+                offset = string.StringUtils.skipWS(raw, offset);
+                lastPartStartIndex = offset;
+            }
+            else if (raw[offset] === HostRuleParser.COMMENT_MARKER) {
+                const commentStart = offset;
+                offset = string.StringUtils.skipWS(raw, offset + 1);
+                comment = valueParser.ValueParser.parse(raw.slice(offset), options$1, baseOffset + commentStart);
+                offset = rawLength;
+                lastPartStartIndex = offset;
+            }
+            else {
+                offset += 1;
+            }
+        }
+        parsePartIfNeeded(lastPartStartIndex, offset);
+        const partsLength = parts.length;
+        if (partsLength < 1) {
+            throw new Error('Host rule must have at least one domain name or an IP address and a domain name');
+        }
+        const result = {
+            category: index.RuleCategory.Network,
+            type: index.NetworkRuleType.HostRule,
+            syntax: adblockers.AdblockSyntax.Common,
+        };
+        if (partsLength === 1) {
+            // "Just domain" syntax, e.g. `example.org`
+            // In this case, domain should be valid and IP will be set to 0.0.0.0 by default
+            if (tldts__namespace.getDomain(parts[0].value) !== parts[0].value) {
+                throw new Error(`Not a valid domain: ${parts[0].value}`);
+            }
+            result.ip = {
+                type: 'Value',
+                value: HostRuleParser.NULL_IP,
+            };
+            result.hostnames = {
+                type: 'HostnameList',
+                children: parts,
+            };
+        }
+        else if (partsLength > 1) {
+            // IP + domain list syntax
+            const [ip, ...hostnames] = parts;
+            if (!isIp(ip.value)) {
+                throw new Error(`Invalid IP address: ${ip.value}`);
+            }
+            for (const { value } of hostnames) {
+                if (tldts__namespace.getHostname(value) !== value) {
+                    throw new Error(`Not a valid hostname: ${value}`);
+                }
+            }
+            result.ip = ip;
+            result.hostnames = {
+                type: 'HostnameList',
+                children: hostnames,
+            };
+        }
+        if (comment) {
+            result.comment = comment;
+        }
+        if (options$1.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        return result;
+    }
+}
+
+exports.HostRuleParser = HostRuleParser;

package/dist/cjs/parser/network/network-rule-parser.js

@@ -0,0 +1,113 @@
+/*
+ * 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
+ */
+'use strict';
+
+var adblockers = require('../../utils/adblockers.js');
+var string = require('../../utils/string.js');
+var modifierList = require('../misc/modifier-list.js');
+var constants = require('../../utils/constants.js');
+var index = require('../../nodes/index.js');
+var adblockSyntaxError = require('../../errors/adblock-syntax-error.js');
+var options = require('../options.js');
+var baseParser = require('../base-parser.js');
+var valueParser = require('../misc/value-parser.js');
+
+/**
+ * `NetworkRuleParser` is responsible for parsing network rules.
+ *
+ * Please note that this will parse all syntactically correct network rules.
+ * Modifier compatibility is not checked at the parser level.
+ *
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules}
+ * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#basic}
+ */
+class NetworkRuleParser extends baseParser.BaseParser {
+    /**
+     * Parses a network rule (also known as basic rule).
+     *
+     * @param raw Raw input to parse.
+     * @param options Global parser options.
+     * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     * @returns Network rule AST
+     *
+     * @throws If the rule is syntactically incorrect.
+     */
+    static parse(raw, options$1 = options.defaultParserOptions, baseOffset = 0) {
+        let offset = 0;
+        // Skip leading whitespace
+        offset = string.StringUtils.skipWS(raw, offset);
+        // Handle exception rules
+        let exception = false;
+        // Rule starts with exception marker, eg @@||example.com,
+        // where @@ is the exception marker
+        if (raw.startsWith(constants.NETWORK_RULE_EXCEPTION_MARKER, offset)) {
+            offset += constants.NETWORK_RULE_EXCEPTION_MARKER_LEN;
+            exception = true;
+        }
+        // Save the start of the pattern
+        const patternStart = offset;
+        // Find corresponding (last) separator ($) character (if any)
+        const separatorIndex = NetworkRuleParser.findNetworkRuleSeparatorIndex(raw);
+        // Save the end of the pattern
+        const patternEnd = separatorIndex === -1
+            ? string.StringUtils.skipWSBack(raw) + 1
+            : string.StringUtils.skipWSBack(raw, separatorIndex - 1) + 1;
+        // Parse pattern
+        const pattern = valueParser.ValueParser.parse(raw.slice(patternStart, patternEnd), options$1, baseOffset + patternStart);
+        // Parse modifiers (if any)
+        let modifiers;
+        // Find start and end index of the modifiers
+        const modifiersStart = separatorIndex + 1;
+        const modifiersEnd = string.StringUtils.skipWSBack(raw) + 1;
+        if (separatorIndex !== -1) {
+            modifiers = modifierList.ModifierListParser.parse(raw.slice(modifiersStart, modifiersEnd), options$1, baseOffset + modifiersStart);
+        }
+        // Throw error if there is no pattern and no modifiers
+        if (pattern.value.length === 0 && (modifiers === undefined || modifiers.children.length === 0)) {
+            throw new adblockSyntaxError.AdblockSyntaxError('Network rule must have a pattern or modifiers', baseOffset, baseOffset + raw.length);
+        }
+        const result = {
+            type: index.NetworkRuleType.NetworkRule,
+            category: index.RuleCategory.Network,
+            syntax: adblockers.AdblockSyntax.Common,
+            exception,
+            pattern,
+            modifiers,
+        };
+        if (options$1.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options$1.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+    /**
+     * Finds the index of the separator character in a network rule.
+     *
+     * @param rule Network rule to check
+     * @returns The index of the separator character, or -1 if there is no separator
+     */
+    static findNetworkRuleSeparatorIndex(rule) {
+        // As we are looking for the last separator, we start from the end of the string
+        for (let i = rule.length - 1; i >= 0; i -= 1) {
+            // If we find a potential separator, we should check
+            // - if it's not escaped
+            // - if it's not followed by a regex marker, for example: `example.org^$removeparam=/regex$/`
+            // eslint-disable-next-line max-len
+            if (rule[i] === constants.NETWORK_RULE_SEPARATOR && rule[i + 1] !== constants.REGEX_MARKER && rule[i - 1] !== constants.ESCAPE_CHARACTER) {
+                return i;
+            }
+        }
+        return -1;
+    }
+}
+
+exports.NetworkRuleParser = NetworkRuleParser;

package/dist/cjs/parser/options.js

@@ -0,0 +1,25 @@
+/*
+ * 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
+ */
+'use strict';
+
+/**
+ * @file Common options for all parsers.
+ */
+/**
+ * Default parser options.
+ */
+const defaultParserOptions = Object.freeze({
+    tolerant: false,
+    isLocIncluded: true,
+    parseAbpSpecificRules: true,
+    parseUboSpecificRules: true,
+    includeRaws: true,
+    ignoreComments: false,
+    parseHostRules: false,
+});
+
+exports.defaultParserOptions = defaultParserOptions;