@adguard/agtree 2.1.2 → 3.0.0-alpha.1

package/dist/cjs/nodes/index.js

@@ -0,0 +1,180 @@
+/*
+ * 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';
+
+/**
+ * Possible operators in the logical expression.
+ */
+exports.OperatorValue = void 0;
+(function (OperatorValue) {
+    OperatorValue["Not"] = "!";
+    OperatorValue["And"] = "&&";
+    OperatorValue["Or"] = "||";
+})(exports.OperatorValue || (exports.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 `#`.
+ */
+exports.CommentMarker = void 0;
+(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"] = "#";
+})(exports.CommentMarker || (exports.CommentMarker = {}));
+/**
+ * Represents the main categories that an adblock rule can belong to.
+ * Of course, these include additional subcategories.
+ */
+exports.RuleCategory = void 0;
+(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";
+})(exports.RuleCategory || (exports.RuleCategory = {}));
+/**
+ * Represents similar types of modifiers values
+ * which may be separated by a comma `,` (only for DomainList) or a pipe `|`.
+ */
+exports.ListNodeType = void 0;
+(function (ListNodeType) {
+    ListNodeType["Unknown"] = "Unknown";
+    ListNodeType["AppList"] = "AppList";
+    ListNodeType["DomainList"] = "DomainList";
+    ListNodeType["MethodList"] = "MethodList";
+    ListNodeType["StealthOptionList"] = "StealthOptionList";
+})(exports.ListNodeType || (exports.ListNodeType = {}));
+/**
+ * Represents child items for {@link ListNodeType}.
+ */
+exports.ListItemNodeType = void 0;
+(function (ListItemNodeType) {
+    ListItemNodeType["Unknown"] = "Unknown";
+    ListItemNodeType["App"] = "App";
+    ListItemNodeType["Domain"] = "Domain";
+    ListItemNodeType["Method"] = "Method";
+    ListItemNodeType["StealthOption"] = "StealthOption";
+})(exports.ListItemNodeType || (exports.ListItemNodeType = {}));
+/**
+ * Represents possible comment types.
+ */
+exports.CommentRuleType = void 0;
+(function (CommentRuleType) {
+    CommentRuleType["AgentCommentRule"] = "AgentCommentRule";
+    CommentRuleType["CommentRule"] = "CommentRule";
+    CommentRuleType["ConfigCommentRule"] = "ConfigCommentRule";
+    CommentRuleType["HintCommentRule"] = "HintCommentRule";
+    CommentRuleType["MetadataCommentRule"] = "MetadataCommentRule";
+    CommentRuleType["PreProcessorCommentRule"] = "PreProcessorCommentRule";
+})(exports.CommentRuleType || (exports.CommentRuleType = {}));
+/**
+ * Represents possible cosmetic rule types.
+ */
+exports.CosmeticRuleType = void 0;
+(function (CosmeticRuleType) {
+    CosmeticRuleType["ElementHidingRule"] = "ElementHidingRule";
+    CosmeticRuleType["CssInjectionRule"] = "CssInjectionRule";
+    CosmeticRuleType["ScriptletInjectionRule"] = "ScriptletInjectionRule";
+    CosmeticRuleType["HtmlFilteringRule"] = "HtmlFilteringRule";
+    CosmeticRuleType["JsInjectionRule"] = "JsInjectionRule";
+})(exports.CosmeticRuleType || (exports.CosmeticRuleType = {}));
+/**
+ * Represents possible cosmetic rule separators.
+ */
+exports.CosmeticRuleSeparator = void 0;
+(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"] = "$@$";
+})(exports.CosmeticRuleSeparator || (exports.CosmeticRuleSeparator = {}));
+/**
+ * Represents the different types of network rules.
+ */
+exports.NetworkRuleType = void 0;
+(function (NetworkRuleType) {
+    NetworkRuleType["NetworkRule"] = "NetworkRule";
+    NetworkRuleType["HostRule"] = "HostRule";
+})(exports.NetworkRuleType || (exports.NetworkRuleType = {}));

package/dist/cjs/package.json.js

@@ -0,0 +1,11 @@
+/*
+ * 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';
+
+const version = "3.0.0-alpha.1";
+
+exports.version = version;

package/dist/cjs/parser/base-parser.js

@@ -0,0 +1,32 @@
+/*
+ * 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 notImplementedError = require('../errors/not-implemented-error.js');
+
+/**
+ * @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.NotImplementedError();
+    }
+}
+
+exports.BaseParser = BaseParser;

package/dist/cjs/parser/comment/agent-comment-parser.js

@@ -0,0 +1,121 @@
+/*
+ * 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 constants = require('../../utils/constants.js');
+var string = require('../../utils/string.js');
+var index = require('../../nodes/index.js');
+var agentParser = require('./agent-parser.js');
+var adblockSyntaxError = require('../../errors/adblock-syntax-error.js');
+var adblockers = require('../../utils/adblockers.js');
+var cosmeticRuleSeparator = require('../../utils/cosmetic-rule-separator.js');
+var baseParser = require('../base-parser.js');
+var options = require('../options.js');
+var typeGuards = require('../../utils/type-guards.js');
+
+/**
+ * `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.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(constants.OPEN_SQUARE_BRACKET) && rawTrimmed.endsWith(constants.CLOSE_SQUARE_BRACKET)) {
+            // Avoid this case: [$adg-modifier]##[class^="adg-"]
+            return typeGuards.isNull(cosmeticRuleSeparator.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$1 = options.defaultParserOptions, baseOffset = 0) {
+        // Ignore non-agent rules
+        if (!AgentCommentParser.isAgentRule(raw)) {
+            return null;
+        }
+        let offset = 0;
+        // Skip whitespace characters before the rule
+        offset = string.StringUtils.skipWS(raw, offset);
+        // Skip opening bracket
+        offset += 1;
+        // last character should be a closing bracket
+        const closingBracketIndex = string.StringUtils.skipWSBack(raw, raw.length - 1);
+        if (closingBracketIndex === -1 || raw[closingBracketIndex] !== constants.CLOSE_SQUARE_BRACKET) {
+            throw new adblockSyntaxError.AdblockSyntaxError('Missing closing bracket', offset, offset + raw.length);
+        }
+        // Initialize the agent list
+        const result = {
+            type: index.CommentRuleType.AgentCommentRule,
+            syntax: adblockers.AdblockSyntax.Common,
+            category: index.RuleCategory.Comment,
+            children: [],
+        };
+        if (options$1.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options$1.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        while (offset < closingBracketIndex) {
+            // Skip whitespace characters before the agent
+            offset = string.StringUtils.skipWS(raw, offset);
+            // Find the separator or the closing bracket
+            let separatorIndex = raw.indexOf(constants.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 = string.StringUtils.findLastNonWhitespaceCharacter(raw.slice(offset, separatorIndex)) + offset + 1;
+            // Collect the agent
+            result.children.push(agentParser.AgentParser.parse(raw.slice(offset, agentEndIndex), options$1, 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.AdblockSyntaxError('Empty agent list', baseOffset, baseOffset + raw.length);
+        }
+        return result;
+    }
+}
+
+exports.AgentCommentParser = AgentCommentParser;

package/dist/cjs/parser/comment/agent-parser.js

@@ -0,0 +1,111 @@
+/*
+ * 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 valid = require('semver/functions/valid');
+var coerce = require('semver/functions/coerce');
+var string = require('../../utils/string.js');
+var adblockSyntaxError = require('../../errors/adblock-syntax-error.js');
+var adblockers = require('../../utils/adblockers.js');
+var baseParser = require('../base-parser.js');
+var options = require('../options.js');
+var valueParser = require('../misc/value-parser.js');
+var typeGuards = require('../../utils/type-guards.js');
+var agentCommon = require('../../common/agent-common.js');
+
+/* 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.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$1 = 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 = adblockers.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 = string.StringUtils.skipWS(raw, offset);
+            const partEnd = string.StringUtils.findNextWhitespaceCharacter(raw, offset);
+            const part = raw.slice(offset, partEnd);
+            if (AgentParser.isValidVersion(part)) {
+                if (!typeGuards.isUndefined(version)) {
+                    throw new adblockSyntaxError.AdblockSyntaxError('Duplicated versions are not allowed', baseOffset + offset, baseOffset + partEnd);
+                }
+                const parsedNamePart = raw.slice(nameStartIndex, nameEndIndex);
+                name = valueParser.ValueParser.parse(parsedNamePart, options$1, baseOffset + nameStartIndex);
+                version = valueParser.ValueParser.parse(part, options$1, baseOffset + offset);
+                syntax = agentCommon.getAdblockSyntax(parsedNamePart);
+            }
+            else {
+                nameEndIndex = partEnd;
+            }
+            // Skip whitespace after the part
+            offset = string.StringUtils.skipWS(raw, partEnd);
+        }
+        // If we didn't find a version, the whole string is the name
+        if (typeGuards.isUndefined(name)) {
+            const parsedNamePart = raw.slice(nameStartIndex, nameEndIndex);
+            name = valueParser.ValueParser.parse(parsedNamePart, options$1, baseOffset + nameStartIndex);
+            syntax = agentCommon.getAdblockSyntax(parsedNamePart);
+        }
+        // Agent name cannot be empty
+        if (name.value.length === 0) {
+            throw new adblockSyntaxError.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$1.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+exports.AgentParser = AgentParser;

package/dist/cjs/parser/comment/comment-parser.js

@@ -0,0 +1,110 @@
+/*
+ * 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 agentCommentParser = require('./agent-comment-parser.js');
+var configCommentParser = require('./config-comment-parser.js');
+var hintCommentParser = require('./hint-comment-parser.js');
+var metadataCommentParser = require('./metadata-comment-parser.js');
+var preprocessorParser = require('./preprocessor-parser.js');
+var options = require('../options.js');
+var baseParser = require('../base-parser.js');
+var simpleCommentParser = require('./simple-comment-parser.js');
+
+/* 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.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.SimpleCommentParser.isSimpleComment(trimmed) || agentCommentParser.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$1 = 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.AgentCommentParser.parse(raw, options$1, baseOffset)
+            || hintCommentParser.HintCommentParser.parse(raw, options$1, baseOffset)
+            || preprocessorParser.PreProcessorCommentParser.parse(raw, options$1, baseOffset)
+            || metadataCommentParser.MetadataCommentParser.parse(raw, options$1, baseOffset)
+            || configCommentParser.ConfigCommentParser.parse(raw, options$1, baseOffset)
+            || simpleCommentParser.SimpleCommentParser.parse(raw, options$1, baseOffset);
+    }
+}
+
+exports.CommentParser = CommentParser;