@adguard/agtree 2.2.0 → 3.0.0-alpha.2

package/dist/utils/position-provider.js

@@ -0,0 +1,73 @@
+/*
+ * 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 { LF, FF, CR } from './constants.js';
+
+/**
+ * @file Position provider class.
+ */
+/**
+ * Class responsible for converting a character offset in source code into a line and column position.
+ * This conversion is particularly needed in linters and VSCode extensions,
+ * where line and column numbers are more human-friendly and intuitive than character offsets.
+ * Moreover, the VSCode diagnostics API does not directly support character offsets,
+ * it also requires line and column numbers.
+ */
+class PositionProvider {
+    /**
+     * Maps a character offset to a line number.
+     */
+    offsetToLine;
+    /**
+     * Maps a line number to the starting character offset of that line.
+     */
+    lineStartOffsets;
+    /**
+     * Constructs a new PositionProvider instance.
+     *
+     * @param sourceCode The source code as a string.
+     */
+    constructor(sourceCode) {
+        this.offsetToLine = [];
+        this.lineStartOffsets = [0];
+        let currentLine = 0;
+        for (let i = 0; i < sourceCode.length; i += 1) {
+            this.offsetToLine[i] = currentLine;
+            // Handle different types of line breaks: LF, FF, and CR
+            if (sourceCode[i] === LF || sourceCode[i] === FF || sourceCode[i] === CR) {
+                currentLine += 1;
+                this.lineStartOffsets[currentLine] = (sourceCode[i] === CR && sourceCode[i + 1] === LF)
+                    ? i + 2
+                    : i + 1;
+                if (sourceCode[i] === CR && sourceCode[i + 1] === LF) {
+                    // Skip the '\n' in a '\r\n' sequence
+                    i += 1;
+                }
+            }
+        }
+        // Handle the case where the last offset is at the end of the source code
+        this.offsetToLine[sourceCode.length] = currentLine;
+    }
+    /**
+     * Converts a character offset to a line and column position.
+     *
+     * @param offset The zero-based character offset in the source code.
+     * @returns A Position object containing the 1-based line and column number, or null if the offset is out of range.
+     */
+    convertOffsetToPosition(offset) {
+        if (offset < 0 || offset > this.offsetToLine.length - 1) {
+            return null;
+        }
+        const line = this.offsetToLine[offset];
+        const lineStartOffset = this.lineStartOffsets[line];
+        return {
+            line: line + 1,
+            column: offset - lineStartOffset + 1,
+        };
+    }
+}
+
+export { PositionProvider };

package/dist/utils/quotes.js

@@ -0,0 +1,214 @@
+/*
+ * 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 { ESCAPE_CHARACTER, SINGLE_QUOTE, DOUBLE_QUOTE, BACKTICK_QUOTE, COMMA, SPACE, EMPTY } from './constants.js';
+
+/**
+ * @file Utility functions for working with quotes
+ */
+/**
+ * Set of all possible quote characters supported by the library
+ */
+const QUOTE_SET = new Set([
+    SINGLE_QUOTE,
+    DOUBLE_QUOTE,
+    BACKTICK_QUOTE,
+]);
+/**
+ * Possible quote types for scriptlet parameters
+ */
+const QuoteType = {
+    /**
+     * No quotes at all
+     */
+    None: 'none',
+    /**
+     * Single quotes (`'`)
+     */
+    Single: 'single',
+    /**
+     * Double quotes (`"`)
+     */
+    Double: 'double',
+    /**
+     * Backtick quotes (`` ` ``)
+     */
+    Backtick: 'backtick',
+};
+/**
+ * Utility functions for working with quotes
+ */
+class QuoteUtils {
+    /**
+     * Escape all unescaped occurrences of the character
+     *
+     * @param string String to escape
+     * @param char Character to escape
+     * @returns Escaped string
+     */
+    static escapeUnescapedOccurrences(string, char) {
+        let result = EMPTY;
+        for (let i = 0; i < string.length; i += 1) {
+            if (string[i] === char && (i === 0 || string[i - 1] !== ESCAPE_CHARACTER)) {
+                result += ESCAPE_CHARACTER;
+            }
+            result += string[i];
+        }
+        return result;
+    }
+    /**
+     * Unescape all single escaped occurrences of the character
+     *
+     * @param string String to unescape
+     * @param char Character to unescape
+     * @returns Unescaped string
+     */
+    static unescapeSingleEscapedOccurrences(string, char) {
+        let result = EMPTY;
+        for (let i = 0; i < string.length; i += 1) {
+            if (string[i] === char
+                && string[i - 1] === ESCAPE_CHARACTER
+                && (i === 1 || string[i - 2] !== ESCAPE_CHARACTER)) {
+                result = result.slice(0, -1);
+            }
+            result += string[i];
+        }
+        return result;
+    }
+    /**
+     * Get quote type of the string
+     *
+     * @param string String to check
+     * @returns Quote type of the string
+     */
+    static getStringQuoteType(string) {
+        // Don't check 1-character strings to avoid false positives
+        if (string.length > 1) {
+            if (string.startsWith(SINGLE_QUOTE) && string.endsWith(SINGLE_QUOTE)) {
+                return QuoteType.Single;
+            }
+            if (string.startsWith(DOUBLE_QUOTE) && string.endsWith(DOUBLE_QUOTE)) {
+                return QuoteType.Double;
+            }
+            if (string.startsWith(BACKTICK_QUOTE) && string.endsWith(BACKTICK_QUOTE)) {
+                return QuoteType.Backtick;
+            }
+        }
+        return QuoteType.None;
+    }
+    /**
+     * Set quote type of the string
+     *
+     * @param string String to set quote type of
+     * @param quoteType Quote type to set
+     * @returns String with the specified quote type
+     */
+    static setStringQuoteType(string, quoteType) {
+        const actualQuoteType = QuoteUtils.getStringQuoteType(string);
+        switch (quoteType) {
+            case QuoteType.None:
+                if (actualQuoteType === QuoteType.Single) {
+                    return QuoteUtils.escapeUnescapedOccurrences(string.slice(1, -1), SINGLE_QUOTE);
+                }
+                if (actualQuoteType === QuoteType.Double) {
+                    return QuoteUtils.escapeUnescapedOccurrences(string.slice(1, -1), DOUBLE_QUOTE);
+                }
+                if (actualQuoteType === QuoteType.Backtick) {
+                    return QuoteUtils.escapeUnescapedOccurrences(string.slice(1, -1), BACKTICK_QUOTE);
+                }
+                return string;
+            case QuoteType.Single:
+                if (actualQuoteType === QuoteType.None) {
+                    return SINGLE_QUOTE + QuoteUtils.escapeUnescapedOccurrences(string, SINGLE_QUOTE) + SINGLE_QUOTE;
+                }
+                if (actualQuoteType === QuoteType.Double) {
+                    return SINGLE_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), DOUBLE_QUOTE), SINGLE_QUOTE) + SINGLE_QUOTE;
+                }
+                if (actualQuoteType === QuoteType.Backtick) {
+                    return SINGLE_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), BACKTICK_QUOTE), SINGLE_QUOTE) + SINGLE_QUOTE;
+                }
+                return string;
+            case QuoteType.Double:
+                if (actualQuoteType === QuoteType.None) {
+                    return DOUBLE_QUOTE + QuoteUtils.escapeUnescapedOccurrences(string, DOUBLE_QUOTE) + DOUBLE_QUOTE;
+                }
+                if (actualQuoteType !== QuoteType.Double) {
+                    // eslint-disable-next-line max-len
+                    return DOUBLE_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), SINGLE_QUOTE), DOUBLE_QUOTE) + DOUBLE_QUOTE;
+                }
+                return string;
+            case QuoteType.Backtick:
+                if (actualQuoteType === QuoteType.None) {
+                    // eslint-disable-next-line max-len
+                    return BACKTICK_QUOTE + QuoteUtils.escapeUnescapedOccurrences(string, BACKTICK_QUOTE) + BACKTICK_QUOTE;
+                }
+                if (actualQuoteType !== QuoteType.Backtick) {
+                    // eslint-disable-next-line max-len
+                    return BACKTICK_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), SINGLE_QUOTE), BACKTICK_QUOTE) + BACKTICK_QUOTE;
+                }
+                return string;
+            default:
+                return string;
+        }
+    }
+    /**
+     * Removes bounding quotes from a string, if any
+     *
+     * @param string Input string
+     * @returns String without quotes
+     */
+    static removeQuotes(string) {
+        if (
+        // We should check for string length to avoid false positives
+        string.length > 1
+            && (string[0] === SINGLE_QUOTE || string[0] === DOUBLE_QUOTE || string[0] === BACKTICK_QUOTE)
+            && string[0] === string[string.length - 1]) {
+            return string.slice(1, -1);
+        }
+        return string;
+    }
+    /**
+     * Removes bounding quotes from a string, if any, and unescapes the escaped quotes,
+     * like transforming `'abc\'def'` to `abc'def`.
+     *
+     * @param string Input string
+     * @returns String without quotes
+     */
+    static removeQuotesAndUnescape(string) {
+        if (
+        // We should check for string length to avoid false positives
+        string.length > 1
+            && (string[0] === SINGLE_QUOTE || string[0] === DOUBLE_QUOTE || string[0] === BACKTICK_QUOTE)
+            && string[0] === string[string.length - 1]) {
+            return QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), string[0]);
+        }
+        return string;
+    }
+    /**
+     * Wraps given `strings` with `quote` (defaults to single quote `'`)
+     * and joins them with `separator` (defaults to comma+space `, `).
+     *
+     * @param strings Strings to quote and join.
+     * @param quoteType Quote to use.
+     * @param separator Separator to use.
+     *
+     * @returns String with joined items.
+     *
+     * @example
+     * ['abc', 'def']: strings[]  ->  "'abc', 'def'": string
+     */
+    static quoteAndJoinStrings(strings, quoteType = QuoteType.Single, separator = `${COMMA}${SPACE}`) {
+        return strings
+            .map((s) => QuoteUtils.setStringQuoteType(s, quoteType))
+            .join(separator);
+    }
+}
+
+export { QUOTE_SET, QuoteType, QuoteUtils };

package/dist/utils/regexp.js

@@ -0,0 +1,176 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { PIPE, CARET, ASTERISK, CLOSE_CURLY_BRACKET, CLOSE_PARENTHESIS, CLOSE_SQUARE_BRACKET, DOLLAR_SIGN, DOT, ESCAPE_CHARACTER, OPEN_CURLY_BRACKET, OPEN_PARENTHESIS, OPEN_SQUARE_BRACKET, PLUS, QUESTION_MARK, SLASH, REGEX_MARKER, EMPTY } from './constants.js';
+
+/**
+ * @file Regular expression utilities
+ */
+// Special RegExp constants
+const REGEX_START = CARET; // '^'
+const REGEX_END = DOLLAR_SIGN; // '$'
+const REGEX_ANY_CHARACTERS = DOT + ASTERISK; // '.*'
+// Special adblock pattern symbols and their RegExp equivalents
+const ADBLOCK_URL_START = PIPE + PIPE; // '||'
+const ADBLOCK_URL_START_REGEX = '^(http|https|ws|wss)://([a-z0-9-_.]+\\.)?';
+const ADBLOCK_URL_SEPARATOR = CARET; // '^'
+const ADBLOCK_URL_SEPARATOR_REGEX = '([^ a-zA-Z0-9.%_-]|$)';
+const ADBLOCK_WILDCARD = ASTERISK; // '*'
+const ADBLOCK_WILDCARD_REGEX = REGEX_ANY_CHARACTERS;
+// Negation wrapper for RegExp patterns
+const REGEX_NEGATION_PREFIX = '^((?!';
+const REGEX_NEGATION_SUFFIX = ').)*$';
+/**
+ * Special RegExp symbols
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#special-escape
+ */
+const SPECIAL_REGEX_SYMBOLS = new Set([
+    ASTERISK,
+    CARET,
+    CLOSE_CURLY_BRACKET,
+    CLOSE_PARENTHESIS,
+    CLOSE_SQUARE_BRACKET,
+    DOLLAR_SIGN,
+    DOT,
+    ESCAPE_CHARACTER,
+    OPEN_CURLY_BRACKET,
+    OPEN_PARENTHESIS,
+    OPEN_SQUARE_BRACKET,
+    PIPE,
+    PLUS,
+    QUESTION_MARK,
+    SLASH,
+]);
+/**
+ * Utility functions for working with RegExp patterns
+ */
+class RegExpUtils {
+    /**
+     * Checks whether a string possibly is a RegExp pattern.
+     * Flags are not supported.
+     *
+     * Note: it does not perform a full validation of the pattern,
+     * it just checks if the string starts and ends with a slash.
+     *
+     * @param pattern - Pattern to check
+     * @returns `true` if the string is a RegExp pattern, `false` otherwise
+     */
+    static isRegexPattern(pattern) {
+        const trimmedPattern = pattern.trim();
+        // Avoid false positives
+        return trimmedPattern.length > REGEX_MARKER.length * 2
+            && trimmedPattern.startsWith(REGEX_MARKER)
+            && trimmedPattern.endsWith(REGEX_MARKER)
+            && trimmedPattern[REGEX_MARKER.length - 2] !== ESCAPE_CHARACTER;
+    }
+    /**
+     * Negates a RegExp pattern. Technically, this method wraps the pattern in `^((?!` and `).)*$`.
+     *
+     * RegExp modifiers are not supported.
+     *
+     * @param pattern Pattern to negate (can be wrapped in slashes or not)
+     * @returns Negated RegExp pattern
+     */
+    static negateRegexPattern(pattern) {
+        let result = pattern.trim();
+        let slashes = false;
+        // Remove the leading and trailing slashes (/)
+        if (RegExpUtils.isRegexPattern(result)) {
+            result = result.substring(REGEX_MARKER.length, result.length - REGEX_MARKER.length);
+            slashes = true;
+        }
+        // Only negate the pattern if it's not already negated
+        if (!(result.startsWith(REGEX_NEGATION_PREFIX) && result.endsWith(REGEX_NEGATION_SUFFIX))) {
+            // Remove leading caret (^)
+            if (result.startsWith(REGEX_START)) {
+                result = result.substring(REGEX_START.length);
+            }
+            // Remove trailing dollar sign ($)
+            if (result.endsWith(REGEX_END)) {
+                result = result.substring(0, result.length - REGEX_END.length);
+            }
+            // Wrap the pattern in the negation
+            result = `${REGEX_NEGATION_PREFIX}${result}${REGEX_NEGATION_SUFFIX}`;
+        }
+        // Add the leading and trailing slashes back if they were there
+        if (slashes) {
+            result = `${REGEX_MARKER}${result}${REGEX_MARKER}`;
+        }
+        return result;
+    }
+    /**
+     * Converts a basic adblock rule pattern to a RegExp pattern. Based on
+     * https://github.com/AdguardTeam/tsurlfilter/blob/9b26e0b4a0e30b87690bc60f7cf377d112c3085c/packages/tsurlfilter/src/rules/simple-regex.ts#L219
+     *
+     * @param pattern Pattern to convert
+     * @returns RegExp equivalent of the pattern
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules}
+     */
+    static patternToRegexp(pattern) {
+        const trimmed = pattern.trim();
+        // Return regex for any character sequence if the pattern is just |, ||, * or empty
+        if (trimmed === ADBLOCK_URL_START
+            || trimmed === PIPE
+            || trimmed === ADBLOCK_WILDCARD
+            || trimmed === EMPTY) {
+            return REGEX_ANY_CHARACTERS;
+        }
+        // If the pattern is already a RegExp, just return it, but remove the leading and trailing slashes
+        if (RegExpUtils.isRegexPattern(pattern)) {
+            return pattern.substring(REGEX_MARKER.length, pattern.length - REGEX_MARKER.length);
+        }
+        let result = EMPTY;
+        let offset = 0;
+        let len = trimmed.length;
+        // Handle leading pipes
+        if (trimmed[0] === PIPE) {
+            if (trimmed[1] === PIPE) {
+                // Replace adblock url start (||) with its RegExp equivalent
+                result += ADBLOCK_URL_START_REGEX;
+                offset = ADBLOCK_URL_START.length;
+            }
+            else {
+                // Replace single pipe (|) with the RegExp start symbol (^)
+                result += REGEX_START;
+                offset = REGEX_START.length;
+            }
+        }
+        // Handle trailing pipes
+        let trailingPipe = false;
+        if (trimmed.endsWith(PIPE)) {
+            trailingPipe = true;
+            len -= PIPE.length;
+        }
+        // Handle the rest of the pattern, if any
+        for (; offset < len; offset += 1) {
+            if (trimmed[offset] === ADBLOCK_WILDCARD) {
+                // Replace adblock wildcard (*) with its RegExp equivalent
+                result += ADBLOCK_WILDCARD_REGEX;
+            }
+            else if (trimmed[offset] === ADBLOCK_URL_SEPARATOR) {
+                // Replace adblock url separator (^) with its RegExp equivalent
+                result += ADBLOCK_URL_SEPARATOR_REGEX;
+            }
+            else if (SPECIAL_REGEX_SYMBOLS.has(trimmed[offset])) {
+                // Escape special RegExp symbols (we handled pipe (|) and asterisk (*) already)
+                result += ESCAPE_CHARACTER + trimmed[offset];
+            }
+            else {
+                // Just add any other character
+                result += trimmed[offset];
+            }
+        }
+        // Handle trailing pipes
+        if (trailingPipe) {
+            // Replace trailing pipe (|) with the RegExp end symbol ($)
+            result += REGEX_END;
+        }
+        return result;
+    }
+}
+
+export { ADBLOCK_URL_SEPARATOR, ADBLOCK_URL_SEPARATOR_REGEX, ADBLOCK_URL_START, ADBLOCK_URL_START_REGEX, ADBLOCK_WILDCARD, ADBLOCK_WILDCARD_REGEX, REGEX_ANY_CHARACTERS, REGEX_END, REGEX_NEGATION_PREFIX, REGEX_NEGATION_SUFFIX, REGEX_START, RegExpUtils, SPECIAL_REGEX_SYMBOLS };