@adguard/agtree 2.2.0 → 3.0.0-alpha.2

package/dist/parser/comment/hint-comment-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 { HINT_MARKER, OPEN_PARENTHESIS, BACKSLASH, CLOSE_PARENTHESIS, HINT_MARKER_LEN } from '../../utils/constants.js';
+import { StringUtils } from '../../utils/string.js';
+import { CommentRuleType, RuleCategory } from '../../nodes/index.js';
+import { HintParser } from './hint-parser.js';
+import { AdblockSyntax } from '../../utils/adblockers.js';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.js';
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+
+/**
+ * `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/parser/comment/hint-parser.js

@@ -0,0 +1,129 @@
+/*
+ * 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 { OPEN_PARENTHESIS, SPACE, UNDERSCORE, EMPTY, CLOSE_PARENTHESIS, COMMA } from '../../utils/constants.js';
+import { StringUtils } from '../../utils/string.js';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.js';
+import { ParameterListParser } from '../misc/parameter-list-parser.js';
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+import { ValueParser } from '../misc/value-parser.js';
+
+/* 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/parser/comment/metadata-comment-parser.js

@@ -0,0 +1,129 @@
+/*
+ * 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 { AdblockSyntax } from '../../utils/adblockers.js';
+import { COLON } from '../../utils/constants.js';
+import { CommentMarker, CommentRuleType, RuleCategory } from '../../nodes/index.js';
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+import { ValueParser } from '../misc/value-parser.js';
+
+/**
+ * @file Metadata comments
+ */
+/**
+ * Set of known metadata headers. This helps to quickly identify and validate
+ * metadata headers in the comments.
+ */
+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 };

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

@@ -0,0 +1,199 @@
+/*
+ * 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 { PREPROCESSOR_MARKER, PREPROCESSOR_MARKER_LEN, HASHMARK, PREPROCESSOR_SEPARATOR, OPEN_PARENTHESIS, SAFARI_CB_AFFINITY, CLOSE_PARENTHESIS, COMMA, IF, INCLUDE } from '../../utils/constants.js';
+import { StringUtils } from '../../utils/string.js';
+import { CommentRuleType, RuleCategory } from '../../nodes/index.js';
+import { LogicalExpressionParser } from '../misc/logical-expression-parser.js';
+import { AdblockSyntaxError } from '../../errors/adblock-syntax-error.js';
+import { ParameterListParser } from '../misc/parameter-list-parser.js';
+import { defaultParserOptions } from '../options.js';
+import { BaseParser } from '../base-parser.js';
+import { ValueParser } from '../misc/value-parser.js';
+
+/**
+ * Pre-processor directives
+ *
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#pre-processor-directives}
+ * @see {@link https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#pre-parsing-directives}
+ */
+/**
+ * `PreProcessorParser` is responsible for parsing preprocessor rules.
+ * Pre-processor comments are special comments that are used to control the behavior of the filter list processor.
+ * Please note that this parser only handles general syntax for now, and does not validate the parameters at
+ * the parsing stage.
+ *
+ * @example
+ * If your rule is
+ * ```adblock
+ * !#if (adguard)
+ * ```
+ * then the directive's name is `if` and its value is `(adguard)`, but the parameter list
+ * is not parsed / validated further.
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#pre-processor-directives}
+ * @see {@link https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#pre-parsing-directives}
+ */
+class PreProcessorCommentParser extends BaseParser {
+    /**
+     * Determines whether the rule is a pre-processor rule.
+     *
+     * @param raw Raw rule
+     * @returns `true` if the rule is a pre-processor rule, `false` otherwise
+     */
+    static isPreProcessorRule(raw) {
+        const trimmed = raw.trim();
+        // Avoid this case: !##... (commonly used in AdGuard filters)
+        return trimmed.startsWith(PREPROCESSOR_MARKER) && trimmed[PREPROCESSOR_MARKER_LEN] !== HASHMARK;
+    }
+    /**
+     * Parses a raw rule as a pre-processor 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
+     * Pre-processor comment AST or null (if the raw rule cannot be parsed as a pre-processor comment)
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        // Ignore non-pre-processor rules
+        if (!PreProcessorCommentParser.isPreProcessorRule(raw)) {
+            return null;
+        }
+        let offset = 0;
+        // Ignore whitespace characters before the rule (if any)
+        offset = StringUtils.skipWS(raw, offset);
+        // Ignore the pre-processor marker
+        offset += PREPROCESSOR_MARKER_LEN;
+        // Ignore whitespace characters after the pre-processor marker (if any)
+        // Note: this is incorrect according to the spec, but we do it for tolerance
+        offset = StringUtils.skipWS(raw, offset);
+        // Directive name should start at this offset, so we save this offset now
+        const nameStart = offset;
+        // Consume directive name, so parse the sequence until the first
+        // whitespace / opening parenthesis / end of string
+        while (offset < raw.length) {
+            const ch = raw[offset];
+            if (ch === PREPROCESSOR_SEPARATOR || ch === OPEN_PARENTHESIS) {
+                break;
+            }
+            offset += 1;
+        }
+        // Save name end offset
+        const nameEnd = offset;
+        // Create name node
+        const name = ValueParser.parse(raw.slice(nameStart, nameEnd), options, baseOffset + nameStart);
+        // Ignore whitespace characters after the directive name (if any)
+        // Note: this may incorrect according to the spec, but we do it for tolerance
+        offset = StringUtils.skipWS(raw, offset);
+        // If the directive name is "safari_cb_affinity", then we have a special case
+        if (name.value === SAFARI_CB_AFFINITY) {
+            // Throw error if there are spaces after the directive name
+            if (offset > nameEnd) {
+                throw new AdblockSyntaxError(`Unexpected whitespace after "${SAFARI_CB_AFFINITY}" directive name`, baseOffset + nameEnd, baseOffset + offset);
+            }
+            // safari_cb_affinity directive optionally accepts a parameter list
+            // So at this point we should check if there are parameters or not
+            // (cb_affinity directive followed by an opening parenthesis or if we
+            // skip the whitespace we reach the end of the string)
+            if (StringUtils.skipWS(raw, offset) !== raw.length) {
+                if (raw[offset] !== OPEN_PARENTHESIS) {
+                    throw new AdblockSyntaxError(`Unexpected character '${raw[offset]}' after '${SAFARI_CB_AFFINITY}' directive name`, baseOffset + offset, baseOffset + offset + 1);
+                }
+                // If we have parameters, then we should parse them
+                // Note: we don't validate the parameters at this stage
+                // Ignore opening parenthesis
+                offset += 1;
+                // Save parameter list start offset
+                const parameterListStart = offset;
+                // Check for closing parenthesis
+                const closingParenthesesIndex = StringUtils.skipWSBack(raw);
+                if (closingParenthesesIndex === -1 || raw[closingParenthesesIndex] !== CLOSE_PARENTHESIS) {
+                    throw new AdblockSyntaxError(`Missing closing parenthesis for '${SAFARI_CB_AFFINITY}' directive`, baseOffset + offset, baseOffset + raw.length);
+                }
+                // Save parameter list end offset
+                const parameterListEnd = closingParenthesesIndex;
+                // Parse parameters between the opening and closing parentheses
+                const result = {
+                    type: CommentRuleType.PreProcessorCommentRule,
+                    category: RuleCategory.Comment,
+                    syntax: AdblockSyntax.Adg,
+                    name,
+                    // comma separated list of parameters
+                    params: ParameterListParser.parse(raw.slice(parameterListStart, parameterListEnd), options, baseOffset + parameterListStart, COMMA),
+                };
+                if (options.includeRaws) {
+                    result.raws = {
+                        text: raw,
+                    };
+                }
+                if (options.isLocIncluded) {
+                    result.start = baseOffset;
+                    result.end = baseOffset + raw.length;
+                }
+                return result;
+            }
+        }
+        // If we reached the end of the string, then we have a directive without parameters
+        // (e.g. "!#safari_cb_affinity" or "!#endif")
+        // No need to continue parsing in this case.
+        if (offset === raw.length) {
+            // Throw error if the directive name is "if" or "include", because these directives
+            // should have parameters
+            if (name.value === IF || name.value === INCLUDE) {
+                throw new AdblockSyntaxError(`Directive "${name.value}" requires parameters`, baseOffset, baseOffset + raw.length);
+            }
+            const result = {
+                type: CommentRuleType.PreProcessorCommentRule,
+                category: RuleCategory.Comment,
+                syntax: AdblockSyntax.Common,
+                name,
+            };
+            if (options.includeRaws) {
+                result.raws = {
+                    text: raw,
+                };
+            }
+            if (options.isLocIncluded) {
+                result.start = baseOffset;
+                result.end = baseOffset + raw.length;
+            }
+            return result;
+        }
+        // Get start and end offsets of the directive parameters
+        const paramsStart = offset;
+        const paramsEnd = StringUtils.skipWSBack(raw) + 1;
+        // Prepare parameters node
+        let params;
+        // Parse parameters. Handle "if" and "safari_cb_affinity" directives
+        // separately.
+        if (name.value === IF) {
+            params = LogicalExpressionParser.parse(raw.slice(paramsStart, paramsEnd), options, baseOffset + paramsStart);
+        }
+        else {
+            params = ValueParser.parse(raw.slice(paramsStart, paramsEnd), options, baseOffset + paramsStart);
+        }
+        const result = {
+            type: CommentRuleType.PreProcessorCommentRule,
+            category: RuleCategory.Comment,
+            syntax: AdblockSyntax.Common,
+            name,
+            params,
+        };
+        if (options.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+export { PreProcessorCommentParser };

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

@@ -0,0 +1,106 @@
+/*
+ * 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 { CosmeticRuleSeparatorUtils } from '../../utils/cosmetic-rule-separator.js';
+import { StringUtils } from '../../utils/string.js';
+import { CommentMarker, RuleCategory, CommentRuleType } from '../../nodes/index.js';
+import { BaseParser } from '../base-parser.js';
+import { ValueParser } from '../misc/value-parser.js';
+import { defaultParserOptions } from '../options.js';
+
+/**
+ * `SimpleCommentParser` is responsible for parsing simple comments.
+ * Some comments have a special meaning in adblock syntax, like agent comments or hints,
+ * but this parser is only responsible for parsing regular comments,
+ * whose only purpose is to provide some human-readable information.
+ *
+ * @example
+ * ```adblock
+ * ! This is a simple comment
+ * # This is a simple comment, but in host-like syntax
+ * ```
+ */
+class SimpleCommentParser extends BaseParser {
+    /**
+     * Checks if the raw rule is a simple comment.
+     *
+     * @param raw Raw input to check.
+     * @returns `true` if the input is a simple comment, `false` otherwise.
+     * @note This method does not check for adblock agent comments.
+     */
+    static isSimpleComment(raw) {
+        const trimmed = raw.trim();
+        // Exclamation mark based comments
+        if (trimmed.startsWith(CommentMarker.Regular)) {
+            return true;
+        }
+        // Hashmark based comments
+        // Note: in this case, we must be sure that we do not mistakenly parse a cosmetic rule as a #-like comment,
+        // since most cosmetic rule separators also start with #
+        if (trimmed.startsWith(CommentMarker.Hashmark)) {
+            const result = CosmeticRuleSeparatorUtils.find(trimmed);
+            // If we cannot find a separator, it means that the rule is definitely a comment
+            if (result === null) {
+                return true;
+            }
+            // Otherwise, we must check if the separator is followed by a valid selector
+            const { end } = result;
+            // No valid selector
+            if (!trimmed[end + 1]
+                || StringUtils.isWhitespace(trimmed[end + 1])
+                || (trimmed[end + 1] === CommentMarker.Hashmark && trimmed[end + 2] === CommentMarker.Hashmark)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Parses a raw rule as a simple 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 rule node or null (if the raw rule cannot be parsed as a simple comment).
+     */
+    static parse(raw, options = defaultParserOptions, baseOffset = 0) {
+        // Ignore non-comment rules
+        if (!this.isSimpleComment(raw)) {
+            return null;
+        }
+        // If we are here, it means that the rule is a regular comment
+        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;
+        // Get comment text
+        const text = ValueParser.parse(raw.slice(offset), options, baseOffset + offset);
+        // Regular comment rule
+        const result = {
+            category: RuleCategory.Comment,
+            type: CommentRuleType.CommentRule,
+            // TODO: Change syntax when hashmark is used
+            syntax: AdblockSyntax.Common,
+            marker,
+            text,
+        };
+        if (options.includeRaws) {
+            result.raws = {
+                text: raw,
+            };
+        }
+        if (options.isLocIncluded) {
+            result.start = baseOffset;
+            result.end = baseOffset + raw.length;
+        }
+        return result;
+    }
+}
+
+export { SimpleCommentParser };