@adguard/agtree 2.1.2 → 3.0.0-alpha.1

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

@@ -0,0 +1,137 @@
+/*
+ * 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
+ */
+import JSON5 from 'json5';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { AGLINT_CONFIG_COMMENT_MARKER, AGLINT_COMMAND_PREFIX, COMMA } from '../../utils/constants.mjs';
+import { CommentMarker, CommentRuleType, RuleCategory } from '../../nodes/index.mjs';
+import { StringUtils } from '../../utils/string.mjs';
+import { ParameterListParser } from '../misc/parameter-list-parser.mjs';
+import { defaultParserOptions } from '../options.mjs';
+import { BaseParser } from '../base-parser.mjs';
+import { ValueParser } from '../misc/value-parser.mjs';
+
+/**
+ * @file AGLint configuration comments. Inspired by ESLint inline configuration comments.
+ * @see {@link https://eslint.org/docs/latest/user-guide/configuring/rules#using-configuration-comments}
+ */
+/**
+ * `ConfigCommentParser` is responsible for parsing inline AGLint configuration rules.
+ * Generally, the idea is inspired by ESLint inline configuration comments.
+ *
+ * @see {@link https://eslint.org/docs/latest/user-guide/configuring/rules#using-configuration-comments}
+ */
+class ConfigCommentParser extends BaseParser {
+    /**
+     * Checks if the raw rule is an inline configuration comment rule.
+     *
+     * @param raw Raw rule
+     * @returns `true` if the rule is an inline configuration comment rule, otherwise `false`.
+     */
+    static isConfigComment(raw) {
+        const trimmed = raw.trim();
+        if (trimmed[0] === CommentMarker.Regular || trimmed[0] === CommentMarker.Hashmark) {
+            // Skip comment marker and trim comment text (it is necessary because of "!     something")
+            const text = raw.slice(1).trim();
+            // The code below is "not pretty", but it runs fast, which is necessary, since it will run on EVERY comment
+            // The essence of the indicator is that the control comment always starts with the "aglint" prefix
+            return ((text[0] === 'a' || text[0] === 'A')
+                && (text[1] === 'g' || text[1] === 'G')
+                && (text[2] === 'l' || text[2] === 'L')
+                && (text[3] === 'i' || text[3] === 'I')
+                && (text[4] === 'n' || text[4] === 'N')
+                && (text[5] === 't' || text[5] === 'T'));
+        }
+        return false;
+    }
+    /**
+     * Parses a raw rule as an inline configuration 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
+     * Inline configuration comment AST or null (if the raw rule cannot be parsed as configuration comment)
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        if (!ConfigCommentParser.isConfigComment(raw)) {
+            return null;
+        }
+        let offset = 0;
+        // Skip leading whitespace (if any)
+        offset = StringUtils.skipWS(raw, offset);
+        // Get comment marker
+        const marker = ValueParser.parse(raw[offset], options, baseOffset + offset);
+        // Skip marker
+        offset += 1;
+        // Skip whitespace (if any)
+        offset = StringUtils.skipWS(raw, offset);
+        // Save the command start position
+        const commandStart = offset;
+        // Get comment text, for example: "aglint-disable-next-line"
+        offset = StringUtils.findNextWhitespaceCharacter(raw, offset);
+        const command = ValueParser.parse(raw.slice(commandStart, offset), options, baseOffset + commandStart);
+        // Skip whitespace after command
+        offset = StringUtils.skipWS(raw, offset);
+        // Get comment (if any)
+        const commentStart = raw.indexOf(AGLINT_CONFIG_COMMENT_MARKER, offset);
+        const commentEnd = commentStart !== -1 ? StringUtils.skipWSBack(raw) + 1 : -1;
+        let comment;
+        // Check if there is a comment
+        if (commentStart !== -1) {
+            comment = ValueParser.parse(raw.slice(commentStart, commentEnd), options, baseOffset + commentStart);
+        }
+        // Get parameter
+        const paramsStart = offset;
+        const paramsEnd = commentStart !== -1
+            ? StringUtils.skipWSBack(raw, commentStart - 1) + 1
+            : StringUtils.skipWSBack(raw) + 1;
+        let params;
+        // `! aglint ...` config comment
+        if (command.value === AGLINT_COMMAND_PREFIX) {
+            params = {
+                type: 'ConfigNode',
+                // It is necessary to use JSON5.parse instead of JSON.parse because JSON5 allows unquoted keys.
+                // But don't forget to add { } to the beginning and end of the string,
+                // otherwise JSON5 will not be able to parse it.
+                // TODO: Better solution? ESLint uses "levn" package for parsing these comments.
+                value: JSON5.parse(`{${raw.slice(paramsStart, paramsEnd)}}`),
+            };
+            if (options.isLocIncluded) {
+                params.start = paramsStart;
+                params.end = paramsEnd;
+            }
+            // Throw error for empty config
+            if (Object.keys(params.value).length === 0) {
+                throw new Error('Empty AGLint config');
+            }
+        }
+        else if (paramsStart < paramsEnd) {
+            params = ParameterListParser.parse(raw.slice(paramsStart, paramsEnd), options, baseOffset + paramsStart, COMMA);
+        }
+        const result = {
+            type: CommentRuleType.ConfigCommentRule,
+            category: RuleCategory.Comment,
+            syntax: AdblockSyntax.Common,
+            marker,
+            command,
+            params,
+            comment,
+        };
+        if (options.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+export { ConfigCommentParser };

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

@@ -0,0 +1,117 @@
+/*
+ * 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
+ */
+import { HINT_MARKER, OPEN_PARENTHESIS, BACKSLASH, CLOSE_PARENTHESIS, HINT_MARKER_LEN } from '../../utils/constants.mjs';
+import { StringUtils } from '../../utils/string.mjs';
+import { CommentRuleType, RuleCategory } from '../../nodes/index.mjs';
+import { HintParser } from './hint-parser.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.mjs';
+import { defaultParserOptions } from '../options.mjs';
+import { BaseParser } from '../base-parser.mjs';
+
+/**
+ * `HintRuleParser` is responsible for parsing AdGuard hint rules.
+ *
+ * @example
+ * The following hint rule
+ * ```adblock
+ * !+ NOT_OPTIMIZED PLATFORM(windows)
+ * ```
+ * contains two hints: `NOT_OPTIMIZED` and `PLATFORM`.
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#hints}
+ */
+class HintCommentParser extends BaseParser {
+    /**
+     * Checks if the raw rule is a hint rule.
+     *
+     * @param raw Raw rule
+     * @returns `true` if the rule is a hint rule, `false` otherwise
+     */
+    static isHintRule(raw) {
+        return raw.trim().startsWith(HINT_MARKER);
+    }
+    /**
+     * Parses a raw rule as a hint 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 Hint AST or null (if the raw rule cannot be parsed as a hint comment)
+     * @throws If the input matches the HINT pattern but syntactically invalid
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#hints-1}
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        // Ignore non-hint rules
+        if (!HintCommentParser.isHintRule(raw)) {
+            return null;
+        }
+        let offset = 0;
+        // Skip whitespace characters before the rule
+        offset = StringUtils.skipWS(raw);
+        // Skip hint marker
+        offset += HINT_MARKER_LEN;
+        const hints = [];
+        // Collect hints. Each hint is a string, optionally followed by a parameter list,
+        // enclosed in parentheses. One rule can contain multiple hints.
+        while (offset < raw.length) {
+            // Split rule into raw hints (e.g. 'HINT_NAME' or 'HINT_NAME(PARAMS)')
+            // Hints are separated by whitespace characters, but we should ignore
+            // whitespace characters inside the parameter list
+            // Ignore whitespace characters before the hint
+            offset = StringUtils.skipWS(raw, offset);
+            // Save the start index of the hint
+            const hintStartIndex = offset;
+            // Find the end of the hint
+            let hintEndIndex = offset;
+            let balance = 0;
+            while (hintEndIndex < raw.length) {
+                if (raw[hintEndIndex] === OPEN_PARENTHESIS && raw[hintEndIndex - 1] !== BACKSLASH) {
+                    balance += 1;
+                    // Throw error for nesting
+                    if (balance > 1) {
+                        throw new AdblockSyntaxError('Invalid hint: nested parentheses are not allowed', baseOffset + hintStartIndex, baseOffset + hintEndIndex);
+                    }
+                }
+                else if (raw[hintEndIndex] === CLOSE_PARENTHESIS && raw[hintEndIndex - 1] !== BACKSLASH) {
+                    balance -= 1;
+                }
+                else if (StringUtils.isWhitespace(raw[hintEndIndex]) && balance === 0) {
+                    break;
+                }
+                hintEndIndex += 1;
+            }
+            offset = hintEndIndex;
+            // Skip whitespace characters after the hint
+            offset = StringUtils.skipWS(raw, offset);
+            // Parse the hint
+            const hint = HintParser.parse(raw.slice(hintStartIndex, hintEndIndex), options, baseOffset + hintStartIndex);
+            hints.push(hint);
+        }
+        // Throw error if no hints were found
+        if (hints.length === 0) {
+            throw new AdblockSyntaxError('Empty hint rule', baseOffset, baseOffset + offset);
+        }
+        const result = {
+            type: CommentRuleType.HintCommentRule,
+            category: RuleCategory.Comment,
+            syntax: AdblockSyntax.Adg,
+            children: hints,
+        };
+        if (options.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + offset;
+        }
+        return result;
+    }
+}
+
+export { HintCommentParser };

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

@@ -0,0 +1,129 @@
+/*
+ * 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
+ */
+import { OPEN_PARENTHESIS, SPACE, UNDERSCORE, EMPTY, CLOSE_PARENTHESIS, COMMA } from '../../utils/constants.mjs';
+import { StringUtils } from '../../utils/string.mjs';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.mjs';
+import { ParameterListParser } from '../misc/parameter-list-parser.mjs';
+import { defaultParserOptions } from '../options.mjs';
+import { BaseParser } from '../base-parser.mjs';
+import { ValueParser } from '../misc/value-parser.mjs';
+
+/* eslint-disable no-param-reassign */
+/**
+ * @file AdGuard Hints
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#hints}
+ */
+/**
+ * `HintParser` is responsible for parsing AdGuard hints.
+ *
+ * @example
+ * If the hint rule is
+ * ```adblock
+ * !+ NOT_OPTIMIZED PLATFORM(windows)
+ * ```
+ * then the hints are `NOT_OPTIMIZED` and `PLATFORM(windows)`, and this
+ * class is responsible for parsing them. The rule itself is parsed by
+ * the `HintRuleParser`, which uses this class to parse single hints.
+ */
+class HintParser extends BaseParser {
+    /**
+     * Parses a raw rule as a hint.
+     *
+     * @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 Hint rule AST or null
+     * @throws If the syntax is invalid
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        let offset = 0;
+        // Skip whitespace characters before the hint
+        offset = StringUtils.skipWS(raw);
+        // Hint should start with the hint name in every case
+        // Save the start offset of the hint name
+        const nameStartIndex = offset;
+        // Parse the hint name
+        for (; offset < raw.length; offset += 1) {
+            const char = raw[offset];
+            // Abort consuming the hint name if we encounter a whitespace character
+            // or an opening parenthesis, which means 'HIT_NAME(' case
+            if (char === OPEN_PARENTHESIS || char === SPACE) {
+                break;
+            }
+            // Hint name should only contain letters, digits, and underscores
+            if (!StringUtils.isAlphaNumeric(char) && char !== UNDERSCORE) {
+                throw new AdblockSyntaxError(`Invalid character "${char}" in hint name: "${char}"`, baseOffset + nameStartIndex, baseOffset + offset);
+            }
+        }
+        // Save the end offset of the hint name
+        const nameEndIndex = offset;
+        // Save the hint name token
+        const name = raw.slice(nameStartIndex, nameEndIndex);
+        // Hint name cannot be empty
+        if (name === EMPTY) {
+            throw new AdblockSyntaxError('Empty hint name', baseOffset, baseOffset + nameEndIndex);
+        }
+        // Now we have two case:
+        //  1. We have HINT_NAME and should return it
+        //  2. We have HINT_NAME(PARAMS) and should continue parsing
+        // Skip whitespace characters after the hint name
+        offset = StringUtils.skipWS(raw, offset);
+        // Throw error for 'HINT_NAME (' case
+        if (offset > nameEndIndex && raw[offset] === OPEN_PARENTHESIS) {
+            throw new AdblockSyntaxError('Unexpected whitespace(s) between hint name and opening parenthesis', baseOffset + nameEndIndex, baseOffset + offset);
+        }
+        // Create the hint name node (we can reuse it in the 'HINT_NAME' case, if needed)
+        const nameNode = ValueParser.parse(name, options, baseOffset + nameStartIndex);
+        // Just return the hint name if we have 'HINT_NAME' case (no params)
+        if (raw[offset] !== OPEN_PARENTHESIS) {
+            const result = {
+                type: 'Hint',
+                name: nameNode,
+            };
+            if (options.isLocIncluded) {
+                result.start = baseOffset;
+                result.end = baseOffset + offset;
+            }
+            return result;
+        }
+        // Skip the opening parenthesis
+        offset += 1;
+        // Find closing parenthesis
+        const closeParenthesisIndex = raw.lastIndexOf(CLOSE_PARENTHESIS);
+        // Throw error if we don't have closing parenthesis
+        if (closeParenthesisIndex === -1) {
+            throw new AdblockSyntaxError(`Missing closing parenthesis for hint "${name}"`, baseOffset + nameStartIndex, baseOffset + raw.length);
+        }
+        // Save the start and end index of the params
+        const paramsStartIndex = offset;
+        const paramsEndIndex = closeParenthesisIndex;
+        // Parse the params
+        const params = ParameterListParser.parse(raw.slice(paramsStartIndex, paramsEndIndex), options, baseOffset + paramsStartIndex, COMMA);
+        offset = closeParenthesisIndex + 1;
+        // Skip whitespace characters after the closing parenthesis
+        offset = StringUtils.skipWS(raw, offset);
+        // Throw error if we don't reach the end of the input
+        if (offset !== raw.length) {
+            throw new AdblockSyntaxError(
+            // eslint-disable-next-line max-len
+            `Unexpected input after closing parenthesis for hint "${name}": "${raw.slice(closeParenthesisIndex + 1, offset + 1)}"`, baseOffset + closeParenthesisIndex + 1, baseOffset + offset + 1);
+        }
+        // Return the HINT_NAME(PARAMS) case AST
+        const result = {
+            type: 'Hint',
+            name: nameNode,
+            params,
+        };
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + offset;
+        }
+        return result;
+    }
+}
+
+export { HintParser };

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

@@ -0,0 +1,129 @@
+/*
+ * 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
+ */
+import { StringUtils } from '../../utils/string.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { COLON } from '../../utils/constants.mjs';
+import { CommentMarker, CommentRuleType, RuleCategory } from '../../nodes/index.mjs';
+import { defaultParserOptions } from '../options.mjs';
+import { BaseParser } from '../base-parser.mjs';
+import { ValueParser } from '../misc/value-parser.mjs';
+
+/**
+ * @file Metadata comments
+ */
+/**
+ * Value map for binary deserialization. This helps to reduce the size of the serialized data,
+ * as it allows us to use a single byte to represent frequently used values.
+ */
+const KNOWN_METADATA_HEADERS = new Set([
+    'Checksum',
+    'Description',
+    'Expires',
+    'Homepage',
+    'Last Modified',
+    'LastModified',
+    'Licence',
+    'License',
+    'Time Updated',
+    'TimeUpdated',
+    'Version',
+    'Title',
+]);
+/**
+ * `MetadataParser` is responsible for parsing metadata comments.
+ * Metadata comments are special comments that specify some properties of the list.
+ *
+ * @example
+ * For example, in the case of
+ * ```adblock
+ * ! Title: My List
+ * ```
+ * the name of the header is `Title`, and the value is `My List`, which means that
+ * the list title is `My List`, and it can be used in the adblocker UI.
+ * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#special-comments}
+ */
+class MetadataCommentParser extends BaseParser {
+    /**
+     * Parses a raw rule as a metadata 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 Metadata comment AST or null (if the raw rule cannot be parsed as a metadata comment)
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        // Fast check to avoid unnecessary work
+        if (raw.indexOf(COLON) === -1) {
+            return null;
+        }
+        let offset = 0;
+        // Skip leading spaces before the comment marker
+        offset = StringUtils.skipWS(raw, offset);
+        // Check if the rule starts with a comment marker (first non-space sequence)
+        if (raw[offset] !== CommentMarker.Regular && raw[offset] !== CommentMarker.Hashmark) {
+            return null;
+        }
+        // Consume the comment marker
+        const marker = ValueParser.parse(raw[offset], options, baseOffset + offset);
+        offset += 1;
+        // Skip spaces
+        offset = StringUtils.skipWS(raw, offset);
+        // Save header start position
+        const headerStart = offset;
+        // Check if the comment text starts with a known header
+        const text = raw.slice(offset);
+        for (const knownHeader of KNOWN_METADATA_HEADERS) {
+            // Check if the comment text starts with the header (case-insensitive)
+            if (text.toLocaleLowerCase().startsWith(knownHeader.toLocaleLowerCase())) {
+                // Skip the header
+                offset += knownHeader.length;
+                // Save header
+                const header = ValueParser.parse(raw.slice(headerStart, offset), options, baseOffset + headerStart);
+                // Skip spaces after the header
+                offset = StringUtils.skipWS(raw, offset);
+                // Check if the rule contains a separator after the header
+                if (raw[offset] !== COLON) {
+                    return null;
+                }
+                // Skip the separator
+                offset += 1;
+                // Skip spaces after the separator
+                offset = StringUtils.skipWS(raw, offset);
+                // Save the value start position
+                const valueStart = offset;
+                // Check if the rule contains a value
+                if (offset >= raw.length) {
+                    return null;
+                }
+                const valueEnd = StringUtils.skipWSBack(raw, raw.length - 1) + 1;
+                // Save the value
+                const value = ValueParser.parse(raw.slice(valueStart, valueEnd), options, baseOffset + valueStart);
+                const result = {
+                    type: CommentRuleType.MetadataCommentRule,
+                    category: RuleCategory.Comment,
+                    syntax: AdblockSyntax.Common,
+                    marker,
+                    header,
+                    value,
+                };
+                if (options.includeRaws) {
+                    result.raws = {
+                        text: raw,
+                    };
+                }
+                if (options.isLocIncluded) {
+                    result.start = baseOffset;
+                    result.end = baseOffset + raw.length;
+                }
+                return result;
+            }
+        }
+        return null;
+    }
+}
+
+export { MetadataCommentParser };