@adguard/agtree 2.2.0 → 3.0.0-alpha.2

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

@@ -0,0 +1,46 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { PIPE } from '../../utils/constants.js';
+import { ListNodeType, ListItemNodeType } from '../../nodes/index.js';
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+import { ListItemsParser } from './list-items-parser.js';
+
+const STEALTH_OPTION_LIST_SEPARATOR = 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 {
+    /**
+     * 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 = defaultParserOptions, baseOffset = 0) {
+        const result = {
+            type: ListNodeType.StealthOptionList,
+            separator: STEALTH_OPTION_LIST_SEPARATOR,
+            children: ListItemsParser.parse(raw, options, baseOffset, STEALTH_OPTION_LIST_SEPARATOR, ListItemNodeType.StealthOption),
+        };
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+export { StealthOptionListParser };

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

@@ -0,0 +1,149 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { StringUtils } from '../../utils/string.js';
+import { ESCAPE_CHARACTER, COMMA } from '../../utils/constants.js';
+import { defaultParserOptions } from '../options.js';
+import { ValueParser } from './value-parser.js';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.js';
+import { QUOTE_SET } from '../../utils/quotes.js';
+import { ParameterListParser } from './parameter-list-parser.js';
+
+/**
+ * Parser for uBO-specific parameter lists.
+ */
+class UboParameterListParser extends 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 = defaultParserOptions, baseOffset = 0, separator = COMMA, requireQuotes = false, supportedQuotes = QUOTE_SET) {
+        // Prepare the parameter list node
+        const params = {
+            type: 'ParameterList',
+            children: [],
+        };
+        const { length } = raw;
+        if (options.isLocIncluded) {
+            params.start = baseOffset;
+            params.end = baseOffset + length;
+        }
+        let offset = 0;
+        // TODO: Eliminate the need for extraNull
+        let extraNull = false;
+        while (offset < length) {
+            offset = StringUtils.skipWS(raw, offset);
+            const paramStart = offset;
+            let paramEnd = offset;
+            if (supportedQuotes.has(raw[offset])) {
+                // Find the closing quote
+                const possibleClosingQuoteIndex = StringUtils.findNextUnescapedCharacter(raw, raw[offset], offset + 1);
+                if (possibleClosingQuoteIndex !== -1) {
+                    // Next non-whitespace character after the closing quote should be the separator
+                    const nextSeparatorIndex = StringUtils.skipWS(raw, possibleClosingQuoteIndex + 1);
+                    if (nextSeparatorIndex === length) {
+                        // If the separator is not found, the param end is the end of the string
+                        paramEnd = 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(`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 = StringUtils.findNextUnescapedCharacterBackwards(raw, separator, possibleClosingQuoteIndex, ESCAPE_CHARACTER, offset + 1);
+                        if (separatorIndexBeforeQuote !== -1) {
+                            // Found separator before (Example 2)
+                            paramEnd = StringUtils.skipWSBack(raw, separatorIndexBeforeQuote - 1) + 1;
+                            offset = separatorIndexBeforeQuote + 1;
+                        }
+                        else {
+                            // Didn't found separator before, search after
+                            const separatorIndexAfterQuote = StringUtils.findNextUnescapedCharacter(raw, separator, possibleClosingQuoteIndex);
+                            if (separatorIndexAfterQuote !== -1) {
+                                // We found separator after (Example 3)
+                                paramEnd = 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 = StringUtils.skipWSBack(raw, length - 1) + 1;
+                                offset = length;
+                            }
+                        }
+                    }
+                }
+                else {
+                    if (requireQuotes) {
+                        throw new 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 = StringUtils.skipWSBack(raw, length - 1) + 1;
+                    offset = length;
+                }
+            }
+            else {
+                if (requireQuotes) {
+                    throw new AdblockSyntaxError(`Expected quote, got: '${raw[offset]}'`, baseOffset + offset, baseOffset + length);
+                }
+                const nextSeparator = StringUtils.findNextUnescapedCharacter(raw, separator, offset);
+                if (nextSeparator === -1) {
+                    // If the separator is not found, the param end is the end of the string
+                    paramEnd = StringUtils.skipWSBack(raw, length - 1) + 1;
+                    offset = length;
+                }
+                else {
+                    // Param end should be the last non-whitespace character before the separator
+                    paramEnd = StringUtils.skipWSBack(raw, nextSeparator - 1) + 1;
+                    offset = nextSeparator + 1;
+                    if (StringUtils.skipWS(raw, length - 1) === nextSeparator) {
+                        extraNull = true;
+                    }
+                }
+            }
+            if (paramStart < paramEnd) {
+                params.children.push(ValueParser.parse(raw.slice(paramStart, paramEnd), options, baseOffset + paramStart));
+            }
+            else {
+                params.children.push(null);
+            }
+        }
+        if (extraNull) {
+            params.children.push(null);
+        }
+        return params;
+    }
+}
+
+export { UboParameterListParser };

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

@@ -0,0 +1,37 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+
+/**
+ * Value parser.
+ * This parser is very simple, it just exists to provide a consistent interface for parsing.
+ */
+class ValueParser extends 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 = defaultParserOptions, baseOffset = 0) {
+        const result = {
+            type: 'Value',
+            value: raw,
+        };
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+export { ValueParser };

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

@@ -0,0 +1,130 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import * as tldts from 'tldts';
+import isIp from 'is-ip';
+import { StringUtils } from '../../utils/string.js';
+import { RuleCategory, NetworkRuleType } from '../../nodes/index.js';
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+import { AdblockSyntax } from '../../utils/adblockers.js';
+import { ValueParser } from '../misc/value-parser.js';
+
+/* 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 {
+    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 = defaultParserOptions, baseOffset = 0) {
+        let offset = 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.parse(raw.slice(startIndex, endIndex), options, baseOffset + startIndex));
+            }
+        };
+        while (offset < rawLength) {
+            if (StringUtils.isWhitespace(raw[offset])) {
+                parsePartIfNeeded(lastPartStartIndex, offset);
+                offset = StringUtils.skipWS(raw, offset);
+                lastPartStartIndex = offset;
+            }
+            else if (raw[offset] === HostRuleParser.COMMENT_MARKER) {
+                const commentStart = offset;
+                offset = StringUtils.skipWS(raw, offset + 1);
+                comment = ValueParser.parse(raw.slice(offset), options, 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: RuleCategory.Network,
+            type: NetworkRuleType.HostRule,
+            syntax: 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.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.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.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        return result;
+    }
+}
+
+export { HostRuleParser };

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

@@ -0,0 +1,117 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { AdblockSyntax } from '../../utils/adblockers.js';
+import { StringUtils } from '../../utils/string.js';
+import { ModifierListParser } from '../misc/modifier-list.js';
+import { NETWORK_RULE_EXCEPTION_MARKER, NETWORK_RULE_EXCEPTION_MARKER_LEN, NETWORK_RULE_SEPARATOR, REGEX_MARKER, ESCAPE_CHARACTER } from '../../utils/constants.js';
+import { NetworkRuleType, RuleCategory } from '../../nodes/index.js';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.js';
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+import { ValueParser } from '../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 {
+    /**
+     * 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 = defaultParserOptions, baseOffset = 0) {
+        let offset = 0;
+        // Skip leading whitespace
+        offset = 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(NETWORK_RULE_EXCEPTION_MARKER, offset)) {
+            offset += 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
+            ? StringUtils.skipWSBack(raw) + 1
+            : StringUtils.skipWSBack(raw, separatorIndex - 1) + 1;
+        // Parse pattern
+        const pattern = ValueParser.parse(raw.slice(patternStart, patternEnd), options, baseOffset + patternStart);
+        // Parse modifiers (if any)
+        let modifiers;
+        // Get a last non-whitespace index
+        const lastNonWsIndex = StringUtils.skipWSBack(raw);
+        // Find start and end index of the modifiers
+        const modifiersStart = separatorIndex + 1;
+        const modifiersEnd = StringUtils.skipWSBack(raw) + 1;
+        if (separatorIndex !== -1) {
+            // Check for empty modifiers
+            if (separatorIndex === lastNonWsIndex) {
+                throw new AdblockSyntaxError('Empty modifiers are not allowed', baseOffset + separatorIndex, baseOffset + raw.length);
+            }
+            modifiers = ModifierListParser.parse(raw.slice(modifiersStart, modifiersEnd), options, 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('Network rule must have a pattern or modifiers', baseOffset, baseOffset + raw.length);
+        }
+        const result = {
+            type: NetworkRuleType.NetworkRule,
+            category: RuleCategory.Network,
+            syntax: AdblockSyntax.Common,
+            exception,
+            pattern,
+            modifiers,
+        };
+        if (options.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options.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] === NETWORK_RULE_SEPARATOR && rule[i + 1] !== REGEX_MARKER && rule[i - 1] !== ESCAPE_CHARACTER) {
+                return i;
+            }
+        }
+        return -1;
+    }
+}
+
+export { NetworkRuleParser };

package/dist/parser/options.js

@@ -0,0 +1,23 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+/**
+ * @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,
+});
+
+export { defaultParserOptions };