@adguard/agtree 2.1.3 → 3.0.0

package/dist/esm/nodes/index.mjs

@@ -0,0 +1,180 @@
+/*
+ * 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
+ */
+/**
+ * Possible operators in the logical expression.
+ */
+var OperatorValue;
+(function (OperatorValue) {
+    OperatorValue["Not"] = "!";
+    OperatorValue["And"] = "&&";
+    OperatorValue["Or"] = "||";
+})(OperatorValue || (OperatorValue = {}));
+/**
+ * Represents the different comment markers that can be used in an adblock rule.
+ *
+ * @example
+ * - If the rule is `! This is just a comment`, then the marker will be `!`.
+ * - If the rule is `# This is just a comment`, then the marker will be `#`.
+ */
+var CommentMarker;
+(function (CommentMarker) {
+    /**
+     * Regular comment marker. It is supported by all ad blockers.
+     */
+    CommentMarker["Regular"] = "!";
+    /**
+     * Hashmark comment marker. It is supported by uBlock Origin and AdGuard,
+     * and also used in hosts files.
+     */
+    CommentMarker["Hashmark"] = "#";
+})(CommentMarker || (CommentMarker = {}));
+/**
+ * Represents the main categories that an adblock rule can belong to.
+ * Of course, these include additional subcategories.
+ */
+var RuleCategory;
+(function (RuleCategory) {
+    /**
+     * Empty "rules" that are only containing whitespaces. These rules are handled just for convenience.
+     */
+    RuleCategory["Empty"] = "Empty";
+    /**
+     * Syntactically invalid rules (tolerant mode only).
+     */
+    RuleCategory["Invalid"] = "Invalid";
+    /**
+     * Comment rules, such as comment rules, metadata rules, preprocessor rules, etc.
+     */
+    RuleCategory["Comment"] = "Comment";
+    /**
+     * Cosmetic rules, such as element hiding rules, CSS rules, scriptlet rules, HTML rules, and JS rules.
+     */
+    RuleCategory["Cosmetic"] = "Cosmetic";
+    /**
+     * Network rules, such as basic network rules, header remover network rules, redirect network rules,
+     * response header filtering rules, etc.
+     */
+    RuleCategory["Network"] = "Network";
+})(RuleCategory || (RuleCategory = {}));
+/**
+ * Represents similar types of modifiers values
+ * which may be separated by a comma `,` (only for DomainList) or a pipe `|`.
+ */
+var ListNodeType;
+(function (ListNodeType) {
+    ListNodeType["Unknown"] = "Unknown";
+    ListNodeType["AppList"] = "AppList";
+    ListNodeType["DomainList"] = "DomainList";
+    ListNodeType["MethodList"] = "MethodList";
+    ListNodeType["StealthOptionList"] = "StealthOptionList";
+})(ListNodeType || (ListNodeType = {}));
+/**
+ * Represents child items for {@link ListNodeType}.
+ */
+var ListItemNodeType;
+(function (ListItemNodeType) {
+    ListItemNodeType["Unknown"] = "Unknown";
+    ListItemNodeType["App"] = "App";
+    ListItemNodeType["Domain"] = "Domain";
+    ListItemNodeType["Method"] = "Method";
+    ListItemNodeType["StealthOption"] = "StealthOption";
+})(ListItemNodeType || (ListItemNodeType = {}));
+/**
+ * Represents possible comment types.
+ */
+var CommentRuleType;
+(function (CommentRuleType) {
+    CommentRuleType["AgentCommentRule"] = "AgentCommentRule";
+    CommentRuleType["CommentRule"] = "CommentRule";
+    CommentRuleType["ConfigCommentRule"] = "ConfigCommentRule";
+    CommentRuleType["HintCommentRule"] = "HintCommentRule";
+    CommentRuleType["MetadataCommentRule"] = "MetadataCommentRule";
+    CommentRuleType["PreProcessorCommentRule"] = "PreProcessorCommentRule";
+})(CommentRuleType || (CommentRuleType = {}));
+/**
+ * Represents possible cosmetic rule types.
+ */
+var CosmeticRuleType;
+(function (CosmeticRuleType) {
+    CosmeticRuleType["ElementHidingRule"] = "ElementHidingRule";
+    CosmeticRuleType["CssInjectionRule"] = "CssInjectionRule";
+    CosmeticRuleType["ScriptletInjectionRule"] = "ScriptletInjectionRule";
+    CosmeticRuleType["HtmlFilteringRule"] = "HtmlFilteringRule";
+    CosmeticRuleType["JsInjectionRule"] = "JsInjectionRule";
+})(CosmeticRuleType || (CosmeticRuleType = {}));
+/**
+ * Represents possible cosmetic rule separators.
+ */
+var CosmeticRuleSeparator;
+(function (CosmeticRuleSeparator) {
+    /**
+     * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide_basic}
+     */
+    CosmeticRuleSeparator["ElementHiding"] = "##";
+    /**
+     * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide_basic}
+     */
+    CosmeticRuleSeparator["ElementHidingException"] = "#@#";
+    /**
+     * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide_basic}
+     */
+    CosmeticRuleSeparator["ExtendedElementHiding"] = "#?#";
+    /**
+     * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide_basic}
+     */
+    CosmeticRuleSeparator["ExtendedElementHidingException"] = "#@?#";
+    /**
+     * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide_basic}
+     */
+    CosmeticRuleSeparator["AbpSnippet"] = "#$#";
+    /**
+     * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide_basic}
+     */
+    CosmeticRuleSeparator["AbpSnippetException"] = "#@$#";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-css-rules}
+     */
+    CosmeticRuleSeparator["AdgCssInjection"] = "#$#";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-css-rules}
+     */
+    CosmeticRuleSeparator["AdgCssInjectionException"] = "#@$#";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-css-rules}
+     */
+    CosmeticRuleSeparator["AdgExtendedCssInjection"] = "#$?#";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-css-rules}
+     */
+    CosmeticRuleSeparator["AdgExtendedCssInjectionException"] = "#@$?#";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#scriptlets}
+     */
+    CosmeticRuleSeparator["AdgJsInjection"] = "#%#";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#scriptlets}
+     */
+    CosmeticRuleSeparator["AdgJsInjectionException"] = "#@%#";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#html-filtering-rules}
+     */
+    CosmeticRuleSeparator["AdgHtmlFiltering"] = "$$";
+    /**
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#html-filtering-rules}
+     */
+    CosmeticRuleSeparator["AdgHtmlFilteringException"] = "$@$";
+})(CosmeticRuleSeparator || (CosmeticRuleSeparator = {}));
+/**
+ * Represents the different types of network rules.
+ */
+var NetworkRuleType;
+(function (NetworkRuleType) {
+    NetworkRuleType["NetworkRule"] = "NetworkRule";
+    NetworkRuleType["HostRule"] = "HostRule";
+})(NetworkRuleType || (NetworkRuleType = {}));
+
+export { CommentMarker, CommentRuleType, CosmeticRuleSeparator, CosmeticRuleType, ListItemNodeType, ListNodeType, NetworkRuleType, OperatorValue, RuleCategory };

package/dist/esm/package.json.mjs

@@ -0,0 +1,9 @@
+/*
+ * 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
+ */
+const version = "3.0.0";
+
+export { version };

package/dist/esm/parser/base-parser.mjs

@@ -0,0 +1,30 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { NotImplementedError } from '../errors/not-implemented-error.mjs';
+
+/**
+ * @file Base parser class.
+ */
+/**
+ * Base class for parsers. Each parser should extend this class.
+ */
+class BaseParser {
+    /**
+     * Parses the input string and returns the AST node.
+     *
+     * @param input Input string to parse.
+     * @param options Parser options, see {@link ParserOptions}.
+     * @param baseOffset Base offset. Locations in the AST node will be relative to this offset.
+     * @param args Additional, parser-specific arguments, if needed.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    static parse(input, options, baseOffset, ...args) {
+        throw new NotImplementedError();
+    }
+}
+
+export { BaseParser };

package/dist/esm/parser/comment/agent-comment-parser.mjs

@@ -0,0 +1,119 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { OPEN_SQUARE_BRACKET, CLOSE_SQUARE_BRACKET, SEMICOLON } from '../../utils/constants.mjs';
+import { StringUtils } from '../../utils/string.mjs';
+import { CommentRuleType, RuleCategory } from '../../nodes/index.mjs';
+import { AgentParser } from './agent-parser.mjs';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { CosmeticRuleSeparatorUtils } from '../../utils/cosmetic-rule-separator.mjs';
+import { BaseParser } from '../base-parser.mjs';
+import { defaultParserOptions } from '../options.mjs';
+import { isNull } from '../../utils/type-guards.mjs';
+
+/**
+ * `AgentParser` is responsible for parsing an Adblock agent rules.
+ * Adblock agent comment marks that the filter list is supposed to
+ * be used by the specified ad blockers.
+ *
+ * @example
+ *  - ```adblock
+ *    [AdGuard]
+ *    ```
+ *  - ```adblock
+ *    [Adblock Plus 2.0]
+ *    ```
+ *  - ```adblock
+ *    [uBlock Origin]
+ *    ```
+ *  - ```adblock
+ *    [uBlock Origin 1.45.3]
+ *    ```
+ *  - ```adblock
+ *    [Adblock Plus 2.0; AdGuard]
+ *    ```
+ */
+class AgentCommentParser extends BaseParser {
+    /**
+     * Checks if the raw rule is an adblock agent comment.
+     *
+     * @param raw Raw rule
+     * @returns `true` if the rule is an adblock agent, `false` otherwise
+     */
+    static isAgentRule(raw) {
+        const rawTrimmed = raw.trim();
+        if (rawTrimmed.startsWith(OPEN_SQUARE_BRACKET) && rawTrimmed.endsWith(CLOSE_SQUARE_BRACKET)) {
+            // Avoid this case: [$adg-modifier]##[class^="adg-"]
+            return isNull(CosmeticRuleSeparatorUtils.find(rawTrimmed));
+        }
+        return false;
+    }
+    /**
+     * Parses a raw rule as an adblock agent comment.
+     *
+     * @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 Agent rule AST or null (if the raw rule cannot be parsed as an adblock agent comment)
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        // Ignore non-agent rules
+        if (!AgentCommentParser.isAgentRule(raw)) {
+            return null;
+        }
+        let offset = 0;
+        // Skip whitespace characters before the rule
+        offset = StringUtils.skipWS(raw, offset);
+        // Skip opening bracket
+        offset += 1;
+        // last character should be a closing bracket
+        const closingBracketIndex = StringUtils.skipWSBack(raw, raw.length - 1);
+        if (closingBracketIndex === -1 || raw[closingBracketIndex] !== CLOSE_SQUARE_BRACKET) {
+            throw new AdblockSyntaxError('Missing closing bracket', offset, offset + raw.length);
+        }
+        // Initialize the agent list
+        const result = {
+            type: CommentRuleType.AgentCommentRule,
+            syntax: AdblockSyntax.Common,
+            category: RuleCategory.Comment,
+            children: [],
+        };
+        if (options.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        while (offset < closingBracketIndex) {
+            // Skip whitespace characters before the agent
+            offset = StringUtils.skipWS(raw, offset);
+            // Find the separator or the closing bracket
+            let separatorIndex = raw.indexOf(SEMICOLON, offset);
+            if (separatorIndex === -1) {
+                separatorIndex = closingBracketIndex;
+            }
+            // Find the last non-whitespace character of the agent
+            // [AdGuard  ; Adblock Plus 2.0]
+            //        ^
+            // (if we have spaces between the agent name and the separator)
+            const agentEndIndex = StringUtils.findLastNonWhitespaceCharacter(raw.slice(offset, separatorIndex)) + offset + 1;
+            // Collect the agent
+            result.children.push(AgentParser.parse(raw.slice(offset, agentEndIndex), options, baseOffset + offset));
+            // Set the offset to the next agent or the end of the rule
+            offset = separatorIndex + 1;
+        }
+        if (result.children.length === 0) {
+            throw new AdblockSyntaxError('Empty agent list', baseOffset, baseOffset + raw.length);
+        }
+        return result;
+    }
+}
+
+export { AgentCommentParser };

package/dist/esm/parser/comment/agent-parser.mjs

@@ -0,0 +1,109 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import valid from 'semver/functions/valid';
+import coerce from 'semver/functions/coerce';
+import { StringUtils } from '../../utils/string.mjs';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { BaseParser } from '../base-parser.mjs';
+import { defaultParserOptions } from '../options.mjs';
+import { ValueParser } from '../misc/value-parser.mjs';
+import { isUndefined } from '../../utils/type-guards.mjs';
+import { getAdblockSyntax } from '../../common/agent-common.mjs';
+
+/* eslint-disable no-param-reassign */
+/**
+ * `AgentParser` is responsible for parsing single adblock agent elements.
+ *
+ * @example
+ * If the adblock agent rule is
+ * ```adblock
+ * [Adblock Plus 2.0; AdGuard]
+ * ```
+ * then the adblock agents are `Adblock Plus 2.0` and `AdGuard`, and this
+ * class is responsible for parsing them. The rule itself is parsed by
+ * `AgentCommentParser`, which uses this class to parse single agents.
+ */
+class AgentParser extends BaseParser {
+    /**
+     * Checks if the string is a valid version.
+     *
+     * @param str String to check
+     * @returns `true` if the string is a valid version, `false` otherwise
+     */
+    static isValidVersion(str) {
+        return valid(coerce(str)) !== null;
+    }
+    /**
+     * Parses a raw rule as an adblock agent comment.
+     *
+     * @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 Agent rule AST
+     * @throws {AdblockSyntaxError} If the raw rule cannot be parsed as an adblock agent
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        let offset = 0;
+        // Save name start position
+        const nameStartIndex = offset;
+        let nameEndIndex = offset;
+        // Prepare variables for name and version
+        let name;
+        let version;
+        // default value for the syntax
+        let syntax = AdblockSyntax.Common;
+        // Get agent parts by splitting it by spaces. The last part may be a version.
+        // Example: "Adblock Plus 2.0"
+        while (offset < raw.length) {
+            // Skip whitespace before the part
+            offset = StringUtils.skipWS(raw, offset);
+            const partEnd = StringUtils.findNextWhitespaceCharacter(raw, offset);
+            const part = raw.slice(offset, partEnd);
+            if (AgentParser.isValidVersion(part)) {
+                if (!isUndefined(version)) {
+                    throw new AdblockSyntaxError('Duplicated versions are not allowed', baseOffset + offset, baseOffset + partEnd);
+                }
+                const parsedNamePart = raw.slice(nameStartIndex, nameEndIndex);
+                name = ValueParser.parse(parsedNamePart, options, baseOffset + nameStartIndex);
+                version = ValueParser.parse(part, options, baseOffset + offset);
+                syntax = getAdblockSyntax(parsedNamePart);
+            }
+            else {
+                nameEndIndex = partEnd;
+            }
+            // Skip whitespace after the part
+            offset = StringUtils.skipWS(raw, partEnd);
+        }
+        // If we didn't find a version, the whole string is the name
+        if (isUndefined(name)) {
+            const parsedNamePart = raw.slice(nameStartIndex, nameEndIndex);
+            name = ValueParser.parse(parsedNamePart, options, baseOffset + nameStartIndex);
+            syntax = getAdblockSyntax(parsedNamePart);
+        }
+        // Agent name cannot be empty
+        if (name.value.length === 0) {
+            throw new AdblockSyntaxError('Agent name cannot be empty', baseOffset, baseOffset + raw.length);
+        }
+        const result = {
+            type: 'Agent',
+            adblock: name,
+            syntax,
+        };
+        // only add version if it's present
+        if (version) {
+            result.version = version;
+        }
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+export { AgentParser };

package/dist/esm/parser/comment/comment-parser.mjs

@@ -0,0 +1,108 @@
+/*
+ * AGTree v3.0.0 (build date: Tue, 12 Nov 2024 14:05:06 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { AgentCommentParser } from './agent-comment-parser.mjs';
+import { ConfigCommentParser } from './config-comment-parser.mjs';
+import { HintCommentParser } from './hint-comment-parser.mjs';
+import { MetadataCommentParser } from './metadata-comment-parser.mjs';
+import { PreProcessorCommentParser } from './preprocessor-parser.mjs';
+import { defaultParserOptions } from '../options.mjs';
+import { BaseParser } from '../base-parser.mjs';
+import { SimpleCommentParser } from './simple-comment-parser.mjs';
+
+/* eslint-disable no-param-reassign */
+/**
+ * `CommentParser` is responsible for parsing any comment-like adblock rules.
+ *
+ * @example
+ * Example rules:
+ *  - Adblock agent rules:
+ *      - ```adblock
+ *        [AdGuard]
+ *        ```
+ *      - ```adblock
+ *        [Adblock Plus 2.0]
+ *        ```
+ *      - etc.
+ *  - AdGuard hint rules:
+ *      - ```adblock
+ *        !+ NOT_OPTIMIZED
+ *        ```
+ *      - ```adblock
+ *        !+ NOT_OPTIMIZED PLATFORM(windows)
+ *        ```
+ *      - etc.
+ *  - Pre-processor rules:
+ *      - ```adblock
+ *        !#if (adguard)
+ *        ```
+ *      - ```adblock
+ *        !#endif
+ *        ```
+ *      - etc.
+ *  - Metadata rules:
+ *      - ```adblock
+ *        ! Title: My List
+ *        ```
+ *      - ```adblock
+ *        ! Version: 2.0.150
+ *        ```
+ *      - etc.
+ *  - AGLint inline config rules:
+ *      - ```adblock
+ *        ! aglint-enable some-rule
+ *        ```
+ *      - ```adblock
+ *        ! aglint-disable some-rule
+ *        ```
+ *      - etc.
+ *  - Simple comments:
+ *      - Regular version:
+ *        ```adblock
+ *        ! This is just a comment
+ *        ```
+ *      - uBlock Origin / "hostlist" version:
+ *        ```adblock
+ *        # This is just a comment
+ *        ```
+ *      - etc.
+ */
+class CommentParser extends BaseParser {
+    /**
+     * Checks whether a rule is a comment.
+     *
+     * @param raw Raw rule
+     * @returns `true` if the rule is a comment, `false` otherwise
+     */
+    static isCommentRule(raw) {
+        const trimmed = raw.trim();
+        return SimpleCommentParser.isSimpleComment(trimmed) || AgentCommentParser.isAgentRule(trimmed);
+    }
+    /**
+     * Parses a raw rule as comment.
+     *
+     * @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 Comment AST or null (if the raw rule cannot be parsed as comment)
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        // Ignore non-comment rules
+        if (!CommentParser.isCommentRule(raw)) {
+            return null;
+        }
+        // Note: we parse non-functional comments at the end,
+        // if the input does not match any of the previous, more specific comment patterns
+        return AgentCommentParser.parse(raw, options, baseOffset)
+            || HintCommentParser.parse(raw, options, baseOffset)
+            || PreProcessorCommentParser.parse(raw, options, baseOffset)
+            || MetadataCommentParser.parse(raw, options, baseOffset)
+            || ConfigCommentParser.parse(raw, options, baseOffset)
+            || SimpleCommentParser.parse(raw, options, baseOffset);
+    }
+}
+
+export { CommentParser };