@adguard/agtree 4.0.0 → 4.0.2

package/dist/types/utils/string.d.ts

@@ -11,71 +11,77 @@ export type NewLineSplit = [string, NewLineType | null][];
 export declare class StringUtils {
     /**
      * Finds the first occurrence of a character that:
-     * - isn't preceded by an escape character
+     * - isn't preceded by an escape character.
+     *
+     * @param pattern Source pattern.
+     * @param searchedCharacter Searched character.
+     * @param start Start index.
+     * @param escapeCharacter Escape character, \ by default.
+     * @param end End index (excluded).
      *
-     * @param pattern - Source pattern
-     * @param searchedCharacter - Searched character
-     * @param start - Start index
-     * @param escapeCharacter - Escape character, \ by default
-     * @param end - End index (excluded)
-     * @returns Index or -1 if the character not found
+     * @returns Index or -1 if the character not found.
      */
     static findNextUnescapedCharacter(pattern: string, searchedCharacter: string, start?: number, escapeCharacter?: string, end?: number): number;
     /**
      * Finds the first occurrence in backward direction of a character that isn't preceded by an escape character.
      *
-     * @param pattern - Source pattern
-     * @param searchedCharacter - Searched character
-     * @param start - Start index
-     * @param escapeCharacter - Escape character, \ by default
-     * @param end - End index (Included)
-     * @returns Index or -1 if the character not found
+     * @param pattern Source pattern.
+     * @param searchedCharacter Searched character.
+     * @param start Start index.
+     * @param escapeCharacter Escape character, \ by default.
+     * @param end End index (Included).
+     *
+     * @returns Index or -1 if the character not found.
      */
     static findNextUnescapedCharacterBackwards(pattern: string, searchedCharacter: string, start?: number, escapeCharacter?: string, end?: number): number;
     /**
      * Finds the last occurrence of a character that:
-     * - isn't preceded by an escape character
+     * - isn't preceded by an escape character.
      *
-     * @param pattern - Source pattern
-     * @param searchedCharacter - Searched character
-     * @param escapeCharacter - Escape character, \ by default
-     * @returns Index or -1 if the character not found
+     * @param pattern Source pattern.
+     * @param searchedCharacter Searched character.
+     * @param escapeCharacter Escape character, \ by default.
+     *
+     * @returns Index or -1 if the character not found.
      */
     static findLastUnescapedCharacter(pattern: string, searchedCharacter: string, escapeCharacter?: string): number;
     /**
      * Finds the next occurrence of a character that:
      * - isn't preceded by an escape character
-     * - isn't followed by the specified character
-     *
-     * @param pattern - Source pattern
-     * @param start - Start index
-     * @param searchedCharacter - Searched character
-     * @param notFollowedBy - Searched character not followed by this character
-     * @param escapeCharacter - Escape character, \ by default
-     * @returns Index or -1 if the character not found
+     * - isn't followed by the specified character.
+     *
+     * @param pattern Source pattern.
+     * @param start Start index.
+     * @param searchedCharacter Searched character.
+     * @param notFollowedBy Searched character not followed by this character.
+     * @param escapeCharacter Escape character, \ by default.
+     *
+     * @returns Index or -1 if the character not found.
      */
     static findNextUnescapedCharacterThatNotFollowedBy(pattern: string, start: number, searchedCharacter: string, notFollowedBy: string, escapeCharacter?: string): number;
     /**
      * Finds the last occurrence of a character that:
      * - isn't preceded by an escape character
-     * - isn't followed by the specified character
+     * - isn't followed by the specified character.
+     *
+     * @param pattern Source pattern.
+     * @param searchedCharacter Searched character.
+     * @param notFollowedBy Searched character not followed by this character.
+     * @param escapeCharacter Escape character, \ by default.
      *
-     * @param pattern - Source pattern
-     * @param searchedCharacter - Searched character
-     * @param notFollowedBy - Searched character not followed by this character
-     * @param escapeCharacter - Escape character, \ by default
-     * @returns Index or -1 if the character not found
+     * @returns Index or -1 if the character not found.
      */
     static findLastUnescapedCharacterThatNotFollowedBy(pattern: string, searchedCharacter: string, notFollowedBy: string, escapeCharacter?: string): number;
     /**
      * Finds the next occurrence of a character that:
      * - isn't part of any string literal ('literal' or "literal")
-     * - isn't part of any RegExp expression (/regexp/)
+     * - isn't part of any RegExp expression (/regexp/).
+     *
+     * @param pattern Source pattern.
+     * @param searchedCharacter Searched character.
+     * @param start Start index.
      *
-     * @param pattern - Source pattern
-     * @param searchedCharacter - Searched character
-     * @param start - Start index
-     * @returns Index or -1 if the character not found
+     * @returns Index or -1 if the character not found.
      */
     static findUnescapedNonStringNonRegexChar(pattern: string, searchedCharacter: string, start?: number): number;
     /**
@@ -96,71 +102,79 @@ export declare class StringUtils {
     /**
      * Finds the next occurrence of a character that:
      * - isn't part of any string literal ('literal' or "literal")
-     * - isn't preceded by an escape character
+     * - isn't preceded by an escape character.
+     *
+     * @param pattern Source pattern.
+     * @param searchedCharacter Searched character.
+     * @param start Start index.
+     * @param escapeCharacter Escape character, \ by default.
      *
-     * @param pattern - Source pattern
-     * @param searchedCharacter - Searched character
-     * @param start - Start index
-     * @param escapeCharacter - Escape character, \ by default
-     * @returns Index or -1 if the character not found
+     * @returns Index or -1 if the character not found.
      */
     static findNextUnquotedUnescapedCharacter(pattern: string, searchedCharacter: string, start?: number, escapeCharacter?: string): number;
     /**
      * Finds the next occurrence of a character that:
      * - isn't "bracketed"
-     * - isn't preceded by an escape character
+     * - isn't preceded by an escape character.
+     *
+     * @param pattern Source pattern.
+     * @param searchedCharacter Searched character.
+     * @param start Start index.
+     * @param escapeCharacter Escape character, \ by default.
+     * @param openBracket Open bracket, ( by default.
+     * @param closeBracket Close bracket, ( by default.
      *
-     * @param pattern - Source pattern
-     * @param searchedCharacter - Searched character
-     * @param start - Start index
-     * @param escapeCharacter - Escape character, \ by default
-     * @param openBracket - Open bracket, ( by default
-     * @param closeBracket - Close bracket, ( by default
-     * @throws If the opening and closing brackets are the same
-     * @returns Index or -1 if the character not found
+     * @returns Index or -1 if the character not found.
+     *
+     * @throws If the opening and closing brackets are the same.
      */
     static findNextNotBracketedUnescapedCharacter(pattern: string, searchedCharacter: string, start?: number, escapeCharacter?: string, openBracket?: string, closeBracket?: string): number;
     /**
      * Splits the source pattern along characters that:
      * - isn't part of any string literal ('literal' or "literal")
-     * - isn't preceded by an escape character
+     * - isn't preceded by an escape character.
      *
-     * @param pattern - Source pattern
-     * @param delimeterCharacter - Delimeter character
-     * @returns Splitted string
+     * @param pattern Source pattern.
+     * @param delimeterCharacter Delimeter character.
+     *
+     * @returns Splitted string.
      */
     static splitStringByUnquotedUnescapedCharacter(pattern: string, delimeterCharacter: string): string[];
     /**
      * Splits the source pattern along characters that:
      * - isn't part of any string literal ('literal' or "literal")
      * - isn't part of any RegExp expression (/regexp/)
-     * - isn't preceded by an escape character
+     * - isn't preceded by an escape character.
+     *
+     * @param pattern Source pattern.
+     * @param delimeterCharacter Delimeter character.
      *
-     * @param pattern - Source pattern
-     * @param delimeterCharacter - Delimeter character
-     * @returns Splitted string
+     * @returns Splitted string.
      */
     static splitStringByUnescapedNonStringNonRegexChar(pattern: string, delimeterCharacter: string): string[];
     /**
      * Splits the source pattern along characters that:
-     * - isn't preceded by an escape character
+     * - isn't preceded by an escape character.
+     *
+     * @param pattern Source pattern.
+     * @param delimeterCharacter Delimeter character.
      *
-     * @param pattern - Source pattern
-     * @param delimeterCharacter - Delimeter character
-     * @returns Splitted string
+     * @returns Splitted string.
      */
     static splitStringByUnescapedCharacter(pattern: string, delimeterCharacter: string): string[];
     /**
      * Determines whether the given character is a space or tab character.
      *
-     * @param char - The character to check.
-     * @returns true if the given character is a space or tab character, false otherwise.
+     * @param char The character to check.
+     *
+     * @returns True if the given character is a space or tab character, false otherwise.
      */
     static isWhitespace(char: string): boolean;
     /**
      * Checks if the given character is a digit.
      *
      * @param char The character to check.
+     *
      * @returns `true` if the given character is a digit, `false` otherwise.
      */
     static isDigit(char: string): boolean;
@@ -168,6 +182,7 @@ export declare class StringUtils {
      * Checks if the given character is a small letter.
      *
      * @param char The character to check.
+     *
      * @returns `true` if the given character is a small letter, `false` otherwise.
      */
     static isSmallLetter(char: string): boolean;
@@ -175,6 +190,7 @@ export declare class StringUtils {
      * Checks if the given character is a capital letter.
      *
      * @param char The character to check.
+     *
      * @returns `true` if the given character is a capital letter, `false` otherwise.
      */
     static isCapitalLetter(char: string): boolean;
@@ -182,114 +198,130 @@ export declare class StringUtils {
      * Checks if the given character is a letter (small or capital).
      *
      * @param char The character to check.
+     *
      * @returns `true` if the given character is a letter, `false` otherwise.
      */
     static isLetter(char: string): boolean;
     /**
      * Checks if the given character is a letter or a digit.
      *
-     * @param char Character to check
+     * @param char Character to check.
+     *
      * @returns `true` if the given character is a letter or a digit, `false` otherwise.
      */
     static isAlphaNumeric(char: string): boolean;
     /**
      * Searches for the first non-whitespace character in the source pattern.
      *
-     * @param pattern - Source pattern
-     * @param start - Start index
-     * @returns Index or -1 if the character not found
+     * @param pattern Source pattern.
+     * @param start Start index.
+     *
+     * @returns Index or -1 if the character not found.
      */
     static findFirstNonWhitespaceCharacter(pattern: string, start?: number): number;
     /**
      * Searches for the last non-whitespace character in the source pattern.
      *
-     * @param pattern - Source pattern
-     * @returns Index or -1 if the character not found
+     * @param pattern Source pattern.
+     *
+     * @returns Index or -1 if the character not found.
      */
     static findLastNonWhitespaceCharacter(pattern: string): number;
     /**
      * Finds the next whitespace character in the pattern.
      *
-     * @param pattern Pattern to search in
-     * @param start Start index
-     * @returns Index of the next whitespace character or the length of the pattern if not found
+     * @param pattern Pattern to search in.
+     * @param start Start index.
+     *
+     * @returns Index of the next whitespace character or the length of the pattern if not found.
      */
     static findNextWhitespaceCharacter(pattern: string, start?: number): number;
     /**
      * Escapes a specified character in the string.
      *
-     * @param pattern - Input string
-     * @param character - Character to escape
-     * @param escapeCharacter - Escape character (optional)
-     * @returns Escaped string
+     * @param pattern Input string.
+     * @param character Character to escape.
+     * @param escapeCharacter Escape character (optional).
+     *
+     * @returns Escaped string.
      */
     static escapeCharacter(pattern: string, character: string, escapeCharacter?: string): string;
     /**
      * Searches for the next non-whitespace character in the source pattern.
      *
-     * @param pattern Pattern to search
-     * @param start Start index
-     * @returns Index of the next non-whitespace character or the length of the pattern
+     * @param pattern Pattern to search.
+     * @param start Start index.
+     *
+     * @returns Index of the next non-whitespace character or the length of the pattern.
      */
     static skipWS(pattern: string, start?: number): number;
     /**
      * Searches for the previous non-whitespace character in the source pattern.
      *
-     * @param pattern Pattern to search
-     * @param start Start index
-     * @returns Index of the previous non-whitespace character or -1
+     * @param pattern Pattern to search.
+     * @param start Start index.
+     *
+     * @returns Index of the previous non-whitespace character or -1.
      */
     static skipWSBack(pattern: string, start?: number): number;
     /**
      * Checks if the given character is a new line character.
      *
-     * @param char Character to check
+     * @param char Character to check.
+     *
      * @returns `true` if the given character is a new line character, `false` otherwise.
      */
     static isEOL(char: string): boolean;
     /**
      * Splits a string along newline characters.
      *
-     * @param input - Input string
-     * @returns Splitted string
+     * @param input Input string.
+     *
+     * @returns Splitted string.
      */
     static splitStringByNewLines(input: string): string[];
     /**
-     * Splits a string by new lines and stores the new line type for each line
+     * Splits a string by new lines and stores the new line type for each line.
+     *
+     * @param input The input string to be split.
      *
-     * @param input The input string to be split
      * @returns An array of tuples, where each tuple contains a line of the input string and its
-     * corresponding new line type ("lf", "crlf", or "cr")
+     * corresponding new line type ("lf", "crlf", or "cr").
      */
     static splitStringByNewLinesEx(input: string): NewLineSplit;
     /**
-     * Merges an array of tuples (line, newLineType) into a single string
+     * Merges an array of tuples (line, newLineType) into a single string.
      *
-     * @param input The array of tuples to be merged
-     * @returns A single string containing the lines and new line characters from the input array
+     * @param input The array of tuples to be merged.
+     *
+     * @returns A single string containing the lines and new line characters from the input array.
      */
     static mergeStringByNewLines(input: NewLineSplit): string;
     /**
-     * Helper method to parse a raw string as a number
+     * Helper method to parse a raw string as a number.
+     *
+     * @param raw Raw string to parse.
      *
-     * @param raw Raw string to parse
-     * @returns Parsed number
-     * @throws If the raw string can't be parsed as a number
+     * @returns Parsed number.
+     *
+     * @throws If the raw string can't be parsed as a number.
      */
     static parseNumber(raw: string): number;
     /**
      * Checks if the given value is a string.
      *
-     * @param value Value to check
-     * @returns `true` if the value is a string, `false` otherwise
+     * @param value Value to check.
+     *
+     * @returns `true` if the value is a string, `false` otherwise.
      */
     static isString(value: unknown): value is string;
     /**
      * Escapes the given characters in the input string.
      *
-     * @param input Input string
-     * @param characters Characters to escape (by default, no characters are escaped)
-     * @returns Escaped string
+     * @param input Input string.
+     * @param characters Characters to escape (by default, no characters are escaped).
+     *
+     * @returns Escaped string.
      */
     static escapeCharacters(input: string, characters?: Set<string>): string;
 }

package/dist/types/utils/type-guards.d.ts

@@ -34,6 +34,7 @@ export declare const isInteger: (value: unknown) => value is number;
  * Checks whether the given value is a string.
  *
  * @param value Value to check.
+ *
  * @returns `true` if the value is a string, `false` otherwise.
  */
 export declare const isString: (value: unknown) => value is string;

package/dist/types/validator/helpers.d.ts

@@ -3,7 +3,7 @@
  * - `{ valid: true }` for valid and _fully supported_ modifier;
  * - `{ valid: true, warn: <deprecation notice> }` for valid
  *   and _still supported but deprecated_ modifier;
- * - otherwise `{ valid: true, error: <invalidity reason> }`
+ * - otherwise `{ valid: true, error: <invalidity reason> }`.
  */
 export type ValidationResult = {
     valid: boolean;

package/dist/types/validator/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * @file Validator for modifiers.
  */
+import { type AnyPlatform } from '../compatibility-tables/index.js';
 import { type Modifier } from '../nodes/index.js';
 import { type ValidationResult } from './helpers.js';
-import { type AnyPlatform } from '../compatibility-tables/index.js';
 /**
  * Modifier validator class.
  */
@@ -28,10 +28,10 @@ declare class ModifierValidator {
      * @param isException Whether the modifier is used in exception rule, default to false.
      * Needed to check whether the modifier is allowed only in blocking or exception rules.
      *
+     * @returns Result of modifier validation.
+     *
      * @note For single product: specific platforms use exact lookup, generic platforms use first match.
      * If multiple products are specified (e.g., AdgAny | UboAny), validation is skipped and returns valid.
-     *
-     * @returns Result of modifier validation.
      */
     validate: (platforms: AnyPlatform, modifier: Modifier, isException?: boolean) => ValidationResult;
 }

package/dist/types/version.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file AGTree version
+ * @file AGTree version.
  */
 declare const AGTREE_VERSION: string;
 export { AGTREE_VERSION };

package/dist/utils/adblockers.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -18,7 +18,7 @@ const AdblockProduct = {
      */
     Abp: 'AdblockPlus',
     /**
-     * uBlock Origin.
+     * UBlock Origin..
      *
      * @see {@link https://github.com/gorhill/uBlock}
      */
@@ -31,7 +31,7 @@ const AdblockProduct = {
     Adg: 'AdGuard',
 };
 /**
- * Possible adblock syntaxes (supported by this library)
+ * Possible adblock syntaxes (supported by this library).
  */
 const AdblockSyntax = {
     /**
@@ -49,29 +49,32 @@ const AdblockSyntax = {
     /**
      * Adblock Plus syntax.
      *
+     * @see {@link https://adblockplus.org/}
+     *
      * @example
      * - `example.org#$#abort-on-property-read alert` is an Adblock Plus syntax, since it is not used by any other
      * adblockers directly (probably supported by some on-the-fly conversion, but this is not the native syntax).
-     * @see {@link https://adblockplus.org/}
      */
     Abp: AdblockProduct.Abp,
     /**
-     * uBlock Origin syntax.
+     * UBlock Origin syntax..
+     *
+     * @see {@link https://github.com/gorhill/uBlock}
      *
      * @example
      * - `example.com##+js(set, atob, noopFunc)` is an uBlock Origin syntax, since it is not used by any other
      * adblockers directly (probably supported by some on-the-fly conversion, but this is not the native syntax).
-     * @see {@link https://github.com/gorhill/uBlock}
      */
     Ubo: AdblockProduct.Ubo,
     /**
      * AdGuard syntax.
      *
+     * @see {@link https://adguard.com/}
+     *
      * @example
      * - `example.org#%#//scriptlet("abort-on-property-read", "alert")` is an AdGuard syntax, since it is not used
      * by any other adblockers directly (probably supported by some on-the-fly conversion, but this is not the native
      * syntax).
-     * @see {@link https://adguard.com/}
      */
     Adg: AdblockProduct.Adg,
 };

package/dist/utils/bit-count.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme

package/dist/utils/categorizer.js

@@ -1,12 +1,12 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
  */
 import { CosmeticRuleParser } from '../parser/cosmetic/cosmetic-rule-parser.js';
-import { isNull } from './type-guards.js';
 import { defaultParserOptions } from '../parser/options.js';
+import { isNull } from './type-guards.js';
 
 /**
  * Utility functions for categorizing rules.

package/dist/utils/clone.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -7,7 +7,7 @@
 import cloneDeep from 'clone-deep';
 
 /**
- * @file Clone related utilities
+ * @file Clone related utilities.
  *
  * We should keep clone related functions in this file. Thus, we just provide
  * a simple interface for cloning values, we use it across the AGTree project,
@@ -17,8 +17,9 @@ import cloneDeep from 'clone-deep';
  * Clones an input value to avoid side effects. Use it only in justified cases,
  * because it can impact performance negatively.
  *
- * @param value Value to clone
- * @returns Cloned value
+ * @param value Value to clone.
+ *
+ * @returns Cloned value.
  */
 function clone(value) {
     // TODO: Replace cloneDeep with a more efficient implementation

package/dist/utils/constants.js

@@ -1,11 +1,11 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
  */
 /**
- * @file Constant values used by all parts of the library
+ * @file Constant values used by all parts of the library.
  */
 // TODO: remove unused constants
 // General

package/dist/utils/cosmetic-rule-separator.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -8,7 +8,7 @@ import { CosmeticRuleSeparator } from '../nodes/index.js';
 import { AT_SIGN, SPACE } from './constants.js';
 
 /**
- * @file Cosmetic rule separator finder and categorizer
+ * @file Cosmetic rule separator finder and categorizer.
  */
 /**
  * Utility class for cosmetic rule separators.
@@ -17,8 +17,9 @@ class CosmeticRuleSeparatorUtils {
     /**
      * Checks whether the specified separator is an exception.
      *
-     * @param separator Separator to check
-     * @returns `true` if the separator is an exception, `false` otherwise
+     * @param separator Separator to check.
+     *
+     * @returns `true` if the separator is an exception, `false` otherwise.
      */
     static isException(separator) {
         // Simply check the second character
@@ -27,8 +28,9 @@ class CosmeticRuleSeparatorUtils {
     /**
      * Checks whether the specified separator is marks an Extended CSS cosmetic rule.
      *
-     * @param separator Separator to check
-     * @returns `true` if the separator is marks an Extended CSS cosmetic rule, `false` otherwise
+     * @param separator Separator to check.
+     *
+     * @returns `true` if the separator is marks an Extended CSS cosmetic rule, `false` otherwise.
      */
     static isExtendedCssMarker(separator) {
         return (separator === CosmeticRuleSeparator.ExtendedElementHiding
@@ -40,16 +42,18 @@ class CosmeticRuleSeparatorUtils {
      * Looks for the cosmetic rule separator in the rule. This is a simplified version that
      * masks the recursive function.
      *
-     * @param rule Raw rule
-     * @returns Separator result or null if no separator was found
+     * @param rule Raw rule.
+     *
+     * @returns Separator result or null if no separator was found.
      */
     static find(rule) {
         /**
          * Helper function to create results of the `find` method.
          *
-         * @param start Start position
-         * @param separator Separator type
-         * @returns Cosmetic rule separator node
+         * @param start Start position.
+         * @param separator Separator type.
+         *
+         * @returns Cosmetic rule separator node.
          */
         // eslint-disable-next-line max-len
         function createResult(start, separator) {