@adguard/agtree 2.2.0 → 3.0.0-alpha.2

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

@@ -0,0 +1,280 @@
+/**
+ * @file Utility functions for string manipulation.
+ */
+export declare const SINGLE_QUOTE_MARKER = "'";
+export declare const DOUBLE_QUOTE_MARKER = "\"";
+export type NewLineType = 'lf' | 'crlf' | 'cr';
+export type NewLineSplit = [string, NewLineType | null][];
+/**
+ * Utility functions for string manipulation.
+ */
+export declare class StringUtils {
+    /**
+     * Finds the first occurrence 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 (excluded)
+     * @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
+     */
+    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
+     *
+     * @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
+     */
+    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
+     *
+     * @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
+     */
+    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/)
+     *
+     * @param pattern - Source pattern
+     * @param searchedCharacter - Searched character
+     * @param start - Start index
+     * @returns Index or -1 if the character not found
+     */
+    static findUnescapedNonStringNonRegexChar(pattern: string, searchedCharacter: string, start?: number): number;
+    /**
+     * 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
+     *
+     * @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
+     */
+    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
+     *
+     * @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
+     */
+    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
+     *
+     * @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
+     *
+     * @param pattern - Source pattern
+     * @param delimeterCharacter - Delimeter character
+     * @returns Splitted string
+     */
+    static splitStringByUnescapedNonStringNonRegexChar(pattern: string, delimeterCharacter: string): string[];
+    /**
+     * Splits the source pattern along characters that:
+     * - isn't preceded by an escape character
+     *
+     * @param pattern - Source pattern
+     * @param delimeterCharacter - Delimeter character
+     * @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.
+     */
+    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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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
+     * @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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    static skipWSBack(pattern: string, start?: number): number;
+    /**
+     * Checks if the given character is a new line character.
+     *
+     * @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
+     */
+    static splitStringByNewLines(input: string): string[];
+    /**
+     * Splits a string by new lines and stores the new line type for each line
+     *
+     * @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")
+     */
+    static splitStringByNewLinesEx(input: string): NewLineSplit;
+    /**
+     * 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
+     */
+    static mergeStringByNewLines(input: NewLineSplit): string;
+    /**
+     * Helper method to parse a raw string as a number
+     *
+     * @param raw Raw string to parse
+     * @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
+     */
+    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
+     */
+    static escapeCharacters(input: string, characters?: Set<string>): string;
+}

package/dist/types/utils/text-decoder-polyfill.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Optimized utility for decoding strings from byte sequences.
+ */
+/**
+ * Decodes a byte sequence into an UTF-8 string according to the WHATWG spec.
+ * Optimized for performance.
+ *
+ * @param buffer Buffer to read the bytes from.
+ * @param start Start offset in the buffer.
+ * @param end End offset in the buffer.
+ * @returns Decoded string.
+ * @see {@link https://encoding.spec.whatwg.org/#utf-8-decoder}
+ */
+export declare const decodeTextPolyfill: (buffer: Uint8Array, start?: number, end?: number) => string;

package/dist/types/utils/text-encoder-polyfill.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Utility for encoding strings to byte sequences.
+ */
+export interface TextEncoderPolyfillResult {
+    readonly written: number;
+    readonly read: number;
+}
+/**
+ * Encodes an UTF-8 string into a byte sequence according to the WHATWG spec.
+ *
+ * @param str String to encode.
+ * @param buffer Buffer to write the encoded bytes to.
+ * @returns Number of bytes written to the buffer.
+ * @see {@link https://encoding.spec.whatwg.org/#utf-8-encoder}
+ * @note Bytes written maybe larger than the string length, but never smaller.
+ * For example, the string '你好' has a length of 2, but its byte representation has a length of 6.
+ */
+export declare const encodeIntoPolyfill: (str: string, buffer: Uint8Array) => TextEncoderPolyfillResult;

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

@@ -0,0 +1,47 @@
+/**
+ * Checks whether the given value is undefined.
+ *
+ * @param value Value to check.
+ *
+ * @returns `true` if the value is 'undefined', `false` otherwise.
+ */
+export declare const isUndefined: (value: unknown) => value is undefined;
+/**
+ * Checks whether the given value is null.
+ *
+ * @param value Value to check.
+ *
+ * @returns `true` if the value is 'null', `false` otherwise.
+ */
+export declare const isNull: (value: unknown) => value is null;
+/**
+ * Checks whether the given value is a number.
+ *
+ * @param value Value to check.
+ *
+ * @returns `true` if the value is a number, `false` otherwise.
+ */
+export declare const isNumber: (value: unknown) => value is number;
+/**
+ * Checks whether the given value is an integer.
+ *
+ * @param value Value to check.
+ *
+ * @returns `true` if the value is an integer, `false` otherwise.
+ */
+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;
+/**
+ * Checks whether the given value is an array of Uint8Arrays.
+ *
+ * @param value Value to check.
+ *
+ * @returns True if the value type is an array of Uint8Arrays.
+ */
+export declare const isArrayOfUint8Arrays: (value: unknown) => value is Uint8Array[];

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

@@ -0,0 +1,89 @@
+/**
+ * Prefixes for different adblockers to describe the platform-specific modifiers data
+ * stored in the yaml files.
+ */
+export declare const BLOCKER_PREFIX: {
+    AdGuard: string;
+    UblockOrigin: string;
+    AdblockPlus: string;
+};
+/**
+ * Set of all allowed characters for app name except the dot `.`.
+ */
+export declare const APP_NAME_ALLOWED_CHARS: Set<string>;
+/**
+ * Allowed methods for $method modifier.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#method-modifier}
+ */
+export declare const ALLOWED_METHODS: Set<string>;
+/**
+ * Allowed stealth options for $stealth modifier.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#stealth-modifier}
+ */
+export declare const ALLOWED_STEALTH_OPTIONS: Set<string>;
+/**
+ * Allowed CSP directives for $csp modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives}
+ */
+export declare const ALLOWED_CSP_DIRECTIVES: Set<string>;
+/**
+ * Allowed directives for $permissions modifier.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#permissions-modifier}
+ */
+export declare const ALLOWED_PERMISSION_DIRECTIVES: Set<string>;
+/**
+ * One of available tokens for $permission modifier value.
+ *
+ * @see {@link https://w3c.github.io/webappsec-permissions-policy/#structured-header-serialization}
+ */
+export declare const PERMISSIONS_TOKEN_SELF = "self";
+/**
+ * One of allowlist values for $permissions modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy#allowlists}
+ */
+export declare const EMPTY_PERMISSIONS_ALLOWLIST = "()";
+/**
+ * Allowed directives for $referrerpolicy modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy}
+ */
+export declare const REFERRER_POLICY_DIRECTIVES: Set<string>;
+/**
+ * Prefixes for error messages used in modifier validation.
+ */
+export declare const VALIDATION_ERROR_PREFIX: {
+    BLOCK_ONLY: string;
+    EXCEPTION_ONLY: string;
+    INVALID_CSP_DIRECTIVES: string;
+    INVALID_LIST_VALUES: string;
+    INVALID_NOOP: string;
+    INVALID_PERMISSION_DIRECTIVE: string;
+    INVALID_PERMISSION_ORIGINS: string;
+    INVALID_PERMISSION_ORIGIN_QUOTES: string;
+    INVALID_REFERRER_POLICY_DIRECTIVE: string;
+    MIXED_NEGATIONS: string;
+    NO_CSP_VALUE: string;
+    NO_CSP_DIRECTIVE_QUOTE: string;
+    NO_UNESCAPED_PERMISSION_COMMA: string;
+    NOT_EXISTENT: string;
+    NOT_NEGATABLE_MODIFIER: string;
+    NOT_NEGATABLE_VALUE: string;
+    NOT_SUPPORTED: string;
+    REMOVED: string;
+    VALUE_FORBIDDEN: string;
+    VALUE_INVALID: string;
+    VALUE_REQUIRED: string;
+};
+/**
+ * Prefixes for error messages related to issues in the source YAML files' data.
+ */
+export declare const SOURCE_DATA_ERROR_PREFIX: {
+    INVALID_VALUE_FORMAT_REGEXP: string;
+    NO_DEPRECATION_MESSAGE: string;
+    NO_VALUE_FORMAT_FOR_ASSIGNABLE: string;
+};

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

@@ -0,0 +1,37 @@
+/**
+ * Result of modifier validation:
+ * - `{ 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> }`
+ */
+export type ValidationResult = {
+    valid: boolean;
+    error?: string;
+    warn?: string;
+};
+/**
+ * Validates the noop modifier (i.e. only underscores).
+ *
+ * @param value Value of the modifier.
+ *
+ * @returns True if the modifier is valid, false otherwise.
+ */
+export declare const isValidNoopModifier: (value: string) => boolean;
+/**
+ * Returns invalid validation result with given error message.
+ *
+ * @param error Error message.
+ *
+ * @returns Validation result `{ valid: false, error }`.
+ */
+export declare const getInvalidValidationResult: (error: string) => ValidationResult;
+/**
+ * Returns invalid validation result which uses {@link VALIDATION_ERROR_PREFIX.VALUE_REQUIRED} as prefix
+ * and specifies the given `modifierName` in the error message.
+ *
+ * @param modifierName Modifier name.
+ *
+ * @returns Validation result `{ valid: false, error }`.
+ */
+export declare const getValueRequiredValidationResult: (modifierName: string) => ValidationResult;

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

@@ -0,0 +1,38 @@
+/**
+ * @file Validator for modifiers.
+ */
+import { type Modifier } from '../nodes';
+import { AdblockSyntax } from '../utils/adblockers';
+import { type ValidationResult } from './helpers';
+/**
+ * Modifier validator class.
+ */
+declare class ModifierValidator {
+    /**
+     * Simply checks whether the modifier exists in any adblocker.
+     *
+     * **Deprecated** and **removed** modifiers are considered as **existent**.
+     *
+     * @param modifier Already parsed modifier AST node.
+     *
+     * @returns True if modifier exists, false otherwise.
+     */
+    exists: (modifier: Modifier) => boolean;
+    /**
+     * Checks whether the given `modifier` is valid for specified `syntax`.
+     *
+     * For `Common` syntax it simply checks whether the modifier exists.
+     * For specific syntax the validation is more complex —
+     * deprecated, assignable, negatable and other requirements are checked.
+     *
+     * @param syntax Adblock syntax to check the modifier for.
+     * @param rawModifier Modifier AST node.
+     * @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.
+     */
+    validate: (syntax: AdblockSyntax, rawModifier: Modifier, isException?: boolean) => ValidationResult;
+}
+export declare const modifierValidator: ModifierValidator;
+export {};

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

@@ -0,0 +1,12 @@
+import { type Modifier } from '../nodes';
+import { type ValidationResult } from './helpers';
+/**
+ * Checks whether the value for given `modifier` is valid.
+ *
+ * @param modifier Modifier AST node.
+ * @param valueFormat Value format for the modifier.
+ * @param valueFormatFlags Optional; RegExp flags for the value format.
+ *
+ * @returns Validation result.
+ */
+export declare const validateValue: (modifier: Modifier, valueFormat: string, valueFormatFlags?: string | null) => ValidationResult;

package/dist/types/version.d.ts

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

package/dist/utils/adblockers.js

@@ -0,0 +1,56 @@
+/*
+ * 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
+ */
+/**
+ * @file Possible adblock syntaxes are listed here.
+ */
+/**
+ * Possible adblock syntaxes (supported by this library)
+ */
+const AdblockSyntax = {
+    /**
+     * Common syntax, which is supported by more than one adblocker (or by all adblockers).
+     *
+     * We typically use this syntax when we cannot determine the concrete syntax of the rule,
+     * because the syntax is used by more than one adblocker natively.
+     *
+     * @example
+     * - `||example.org^$important` is a common syntax, since it is used by all adblockers natively, and
+     * we cannot determine at parsing level whether `important` is a valid option or not, and if it is valid,
+     * then which adblocker supports it.
+     */
+    Common: 'Common',
+    /**
+     * Adblock Plus syntax.
+     *
+     * @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: 'AdblockPlus',
+    /**
+     * uBlock Origin syntax.
+     *
+     * @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: 'UblockOrigin',
+    /**
+     * AdGuard syntax.
+     *
+     * @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: 'AdGuard',
+};
+
+export { AdblockSyntax };

package/dist/utils/binary-schema-version.js

@@ -0,0 +1,17 @@
+/*
+ * 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
+ */
+/**
+ * @file Binary schema version.
+ */
+/**
+ * Binary schema version.
+ * This version number is used to ensure that the binary format is compatible with the current library version.
+ * We increment this number if the serialized format changes in a way that is not backwards-compatible.
+ */
+const BINARY_SCHEMA_VERSION = 1;
+
+export { BINARY_SCHEMA_VERSION };