@adguard/agtree 2.2.0 → 3.0.0-alpha.2

package/README.md

@@ -39,7 +39,7 @@ You can install the library using
 - [PNPM][pnpm-pkg-manager-url]: `pnpm add @adguard/agtree`
 
 > [!IMPORTANT]
-> AGTree requires Node.js version 18 or higher.
+> AGTree is an ESM-only package and requires Node.js version 18 or higher.
 
 [yarn-pkg-manager-url]: https://yarnpkg.com/en/docs/install
 [npm-pkg-manager-url]: https://www.npmjs.com/get-npm

package/dist/ast-utils/clone.js

@@ -0,0 +1,61 @@
+/*
+ * 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 { isNull } from '../utils/type-guards.js';
+
+/**
+ * @file Custom clone functions for AST nodes, this is probably the most efficient way to clone AST nodes.
+ * @todo Maybe move them to parser classes as 'clone' methods
+ */
+/**
+ * Clones a scriptlet rule node.
+ *
+ * @param node Node to clone
+ * @returns Cloned node
+ */
+function cloneScriptletRuleNode(node) {
+    return {
+        type: node.type,
+        children: node.children.map((child) => (isNull(child) ? null : { ...child })),
+    };
+}
+/**
+ * Clones a domain list node.
+ *
+ * @param node Node to clone
+ * @returns Cloned node
+ */
+function cloneDomainListNode(node) {
+    return {
+        type: node.type,
+        separator: node.separator,
+        children: node.children.map((domain) => ({ ...domain })),
+    };
+}
+/**
+ * Clones a modifier list node.
+ *
+ * @param node Node to clone
+ * @returns Cloned node
+ */
+function cloneModifierListNode(node) {
+    return {
+        type: node.type,
+        children: node.children.map((modifier) => {
+            const res = {
+                type: modifier.type,
+                exception: modifier.exception,
+                name: { ...modifier.name },
+            };
+            if (modifier.value) {
+                res.value = { ...modifier.value };
+            }
+            return res;
+        }),
+    };
+}
+
+export { cloneDomainListNode, cloneModifierListNode, cloneScriptletRuleNode };

package/dist/ast-utils/modifiers.js

@@ -0,0 +1,53 @@
+/*
+ * 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 { isUndefined } from '../utils/type-guards.js';
+import { clone } from '../utils/clone.js';
+
+/**
+ * @file Utility functions for working with modifier nodes
+ */
+/**
+ * Creates a modifier node
+ *
+ * @param name Name of the modifier
+ * @param value Value of the modifier
+ * @param exception Whether the modifier is an exception
+ * @returns Modifier node
+ */
+function createModifierNode(name, value = undefined, exception = false) {
+    const result = {
+        type: 'Modifier',
+        exception,
+        name: {
+            type: 'Value',
+            value: name,
+        },
+    };
+    if (!isUndefined(value)) {
+        result.value = {
+            type: 'Value',
+            value,
+        };
+    }
+    return result;
+}
+/**
+ * Creates a modifier list node
+ *
+ * @param modifiers Modifiers to put in the list (optional, defaults to an empty list)
+ * @returns Modifier list node
+ */
+function createModifierListNode(modifiers = []) {
+    const result = {
+        type: 'ModifierList',
+        // We need to clone the modifiers to avoid side effects
+        children: modifiers.length ? clone(modifiers) : [],
+    };
+    return result;
+}
+
+export { createModifierListNode, createModifierNode };

package/dist/ast-utils/network-rules.js

@@ -0,0 +1,41 @@
+/*
+ * 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 { isUndefined } from '../utils/type-guards.js';
+import { RuleCategory, NetworkRuleType } from '../nodes/index.js';
+import { AdblockSyntax } from '../utils/adblockers.js';
+import { clone } from '../utils/clone.js';
+
+/**
+ * @file Utility functions for working with network rule nodes
+ */
+/**
+ * Creates a network rule node
+ *
+ * @param pattern Rule pattern
+ * @param modifiers Rule modifiers (optional, default: undefined)
+ * @param exception Exception rule flag (optional, default: false)
+ * @param syntax Adblock syntax (optional, default: Common)
+ * @returns Network rule node
+ */
+function createNetworkRuleNode(pattern, modifiers = undefined, exception = false, syntax = AdblockSyntax.Common) {
+    const result = {
+        category: RuleCategory.Network,
+        type: NetworkRuleType.NetworkRule,
+        syntax,
+        exception,
+        pattern: {
+            type: 'Value',
+            value: pattern,
+        },
+    };
+    if (!isUndefined(modifiers)) {
+        result.modifiers = clone(modifiers);
+    }
+    return result;
+}
+
+export { createNetworkRuleNode };

package/dist/ast-utils/scriptlets.js

@@ -0,0 +1,87 @@
+/*
+ * 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 { EMPTY } from '../utils/constants.js';
+import { QuoteUtils } from '../utils/quotes.js';
+import { isUndefined, isNull } from '../utils/type-guards.js';
+
+/**
+ * @file Utility functions for working with scriptlet nodes
+ */
+/**
+ * Get name of the scriptlet from the scriptlet node
+ *
+ * @param scriptletNode Scriptlet node to get name of
+ * @returns Name of the scriptlet
+ * @throws If the scriptlet is empty
+ */
+function getScriptletName(scriptletNode) {
+    if (scriptletNode.children.length === 0) {
+        throw new Error('Empty scriptlet');
+    }
+    return scriptletNode.children[0]?.value ?? EMPTY;
+}
+/**
+ * Transform the nth argument of the scriptlet node
+ *
+ * @param scriptletNode Scriptlet node to transform argument of
+ * @param index Index of the argument to transform (index 0 is the scriptlet name)
+ * @param transform Function to transform the argument
+ */
+function transformNthScriptletArgument(scriptletNode, index, transform) {
+    const child = scriptletNode.children[index];
+    if (!isUndefined(child)) {
+        const transformed = transform(child?.value ?? null);
+        if (isNull(transformed)) {
+            // eslint-disable-next-line no-param-reassign
+            scriptletNode.children[index] = null;
+            return;
+        }
+        if (isNull(child)) {
+            // eslint-disable-next-line no-param-reassign
+            scriptletNode.children[index] = {
+                type: 'Value',
+                value: transformed,
+            };
+            return;
+        }
+        child.value = transformed;
+    }
+}
+/**
+ * Transform all arguments of the scriptlet node
+ *
+ * @param scriptletNode Scriptlet node to transform arguments of
+ * @param transform Function to transform the arguments
+ */
+function transformAllScriptletArguments(scriptletNode, transform) {
+    for (let i = 0; i < scriptletNode.children.length; i += 1) {
+        transformNthScriptletArgument(scriptletNode, i, transform);
+    }
+}
+/**
+ * Set name of the scriptlet.
+ * Modifies input `scriptletNode` if needed.
+ *
+ * @param scriptletNode Scriptlet node to set name of
+ * @param name Name to set
+ */
+function setScriptletName(scriptletNode, name) {
+    transformNthScriptletArgument(scriptletNode, 0, () => name);
+}
+/**
+ * Set quote type of the scriptlet parameters
+ *
+ * @param scriptletNode Scriptlet node to set quote type of
+ * @param quoteType Preferred quote type
+ */
+function setScriptletQuoteType(scriptletNode, quoteType) {
+    // null is a special value that means "no value", but we can't change its quote type,
+    // so we need to convert it to empty string
+    transformAllScriptletArguments(scriptletNode, (value) => QuoteUtils.setStringQuoteType(value ?? EMPTY, quoteType));
+}
+
+export { getScriptletName, setScriptletName, setScriptletQuoteType, transformAllScriptletArguments, transformNthScriptletArgument };

package/dist/common/abp-snippet-injection-body-common.js

@@ -0,0 +1,23 @@
+/*
+ * 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
+ */
+/**
+ * Common class for the ABP snippet injection body.
+ * This class contains shared constants and utilities for handling ABP snippet injection bodies.
+ */
+class AbpSnippetInjectionBodyCommon {
+    /**
+     * Error messages used by the parser and generator.
+     */
+    static ERROR_MESSAGES = {
+        /**
+         * Error message indicating that an ABP snippet call is empty.
+         */
+        EMPTY_SCRIPTLET_CALL: 'Empty ABP snippet call',
+    };
+}
+
+export { AbpSnippetInjectionBodyCommon };

package/dist/common/agent-common.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
+ */
+import { AdblockSyntax } from '../utils/adblockers.js';
+
+/**
+ * Possible AdGuard agent markers.
+ */
+const ADG_NAME_MARKERS = new Set([
+    'adguard',
+    'adg',
+]);
+/**
+ * Possible uBlock Origin agent markers.
+ */
+const UBO_NAME_MARKERS = new Set([
+    'ublock',
+    'ublock origin',
+    'ubo',
+]);
+/**
+ * Possible Adblock Plus agent markers.
+ */
+const ABP_NAME_MARKERS = new Set([
+    'adblock',
+    'adblock plus',
+    'adblockplus',
+    'abp',
+]);
+/**
+ * Returns the adblock syntax based on the adblock name parsed from the agent type comment.
+ * Needed for modifiers validation of network rules by AGLint.
+ *
+ * @param name Adblock name.
+ *
+ * @returns Adblock syntax.
+ */
+const getAdblockSyntax = (name) => {
+    let syntax = AdblockSyntax.Common;
+    const lowerCaseName = name.toLowerCase();
+    if (ADG_NAME_MARKERS.has(lowerCaseName)) {
+        syntax = AdblockSyntax.Adg;
+    }
+    else if (UBO_NAME_MARKERS.has(lowerCaseName)) {
+        syntax = AdblockSyntax.Ubo;
+    }
+    else if (ABP_NAME_MARKERS.has(lowerCaseName)) {
+        syntax = AdblockSyntax.Abp;
+    }
+    return syntax;
+};
+
+export { getAdblockSyntax };

package/dist/common/ubo-selector-common.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
+ */
+/**
+ * Known uBO-specific pseudo-class names.
+ */
+const UboPseudoName = {
+    MatchesMedia: 'matches-media',
+    MatchesPath: 'matches-path',
+    Remove: 'remove',
+    Style: 'style',
+};
+
+export { UboPseudoName };

package/dist/compatibility-tables/base.js

@@ -0,0 +1,262 @@
+/*
+ * 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 { GenericPlatform } from './platforms.js';
+import { isUndefined } from '../utils/type-guards.js';
+import { isGenericPlatform } from './utils/platform-helpers.js';
+import { AdblockSyntax } from '../utils/adblockers.js';
+
+/* eslint-disable no-bitwise */
+/**
+ * @file Provides common compatibility table methods.
+ */
+/**
+ * Base compatibility table class which provides common methods to work with compatibility data.
+ *
+ * @template T Compatibility data schema.
+ */
+class CompatibilityTableBase {
+    /**
+     * Compatibility table data.
+     */
+    data;
+    /**
+     * Optional name transformer function. If provided,
+     * it will be called in all methods before processing compatibility data names.
+     */
+    nameTransformer;
+    /**
+     * Creates a new instance of the common compatibility table.
+     *
+     * @param data Compatibility table data.
+     * @param nameTransformer Optional name transformer function.
+     */
+    constructor(data, nameTransformer = null) {
+        this.data = data;
+        this.nameTransformer = nameTransformer;
+    }
+    /**
+     * Helper method to get a 'row' from the compatibility table data by name.
+     *
+     * @param name Compatibility data name.
+     * @returns Compatibility table row storage or `null` if not found.
+     */
+    getRowStorage(name) {
+        const idx = this.data.map[name];
+        if (isUndefined(idx)) {
+            return null;
+        }
+        return this.data.shared[idx];
+    }
+    /**
+     * Checks whether a compatibility data `name` exists for any platform.
+     *
+     * @note Technically, do the same as `exists()` method with generic platform _any_
+     * but it is faster because it does not apply complex logic.
+     *
+     * @param name Compatibility data name.
+     *
+     * @returns True if the compatibility data exists, false otherwise.
+     */
+    existsAny(name) {
+        const normalizedName = this.nameTransformer ? this.nameTransformer(name) : name;
+        return !isUndefined(this.data.map[normalizedName]);
+    }
+    /**
+     * Checks whether a compatibility data `name` exists for a specified platform.
+     *
+     * @param name Compatibility data name.
+     * @param platform Specific or generic platform.
+     *
+     * @returns True if the compatibility data exists, false otherwise.
+     */
+    exists(name, platform) {
+        const normalizedName = this.nameTransformer ? this.nameTransformer(name) : name;
+        const data = this.getRowStorage(normalizedName);
+        if (!data) {
+            return false;
+        }
+        const isMatch = (idx) => {
+            const el = data.shared[idx];
+            return !isUndefined(el) && (el.name === normalizedName || !!el.aliases?.includes(normalizedName));
+        };
+        if (isGenericPlatform(platform)) {
+            // Since indexes are specific platforms in the compatibility table data,
+            // we can't index them directly if the platform is generic (union of specific platforms).
+            // In this case, we need to iterate over the keys and return true on the first match.
+            const keys = Object.keys(data.map);
+            for (let i = 0; i < keys.length; i += 1) {
+                const key = Number(keys[i]);
+                if (platform & key) {
+                    const idx = data.map[key];
+                    if (isMatch(idx)) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        }
+        const idx = data.map[platform];
+        return isMatch(idx);
+    }
+    /**
+     * Returns a compatibility data by name and specific platform.
+     *
+     * @param name The name of the compatibility data.
+     * @param platform The specific platform.
+     *
+     * @returns A single compatibility data or `null` if not found.
+     */
+    getSingle(name, platform) {
+        const normalizedName = this.nameTransformer ? this.nameTransformer(name) : name;
+        const data = this.getRowStorage(normalizedName);
+        if (!data) {
+            return null;
+        }
+        const idx = data.map[platform];
+        return isUndefined(idx) ? null : data.shared[idx];
+    }
+    /**
+     * Returns all compatibility data records for name and specified platform.
+     *
+     * @param name Compatibility data name.
+     * @param platform Specific or generic platform.
+     *
+     * @returns Multiple records grouped by platforms.
+     * Technically, it is an object where keys are platform enums values and values are compatibility data records.
+     *
+     * @note Platform enum values can be converted to string names using {@link getSpecificPlatformName} on demand.
+     */
+    getMultiple(name, platform) {
+        const normalizedName = this.nameTransformer ? this.nameTransformer(name) : name;
+        const data = this.getRowStorage(normalizedName);
+        if (!data) {
+            return null;
+        }
+        if (isGenericPlatform(platform)) {
+            const result = {};
+            const keys = Object.keys(data.map);
+            for (let i = 0; i < keys.length; i += 1) {
+                const key = Number(keys[i]);
+                if (platform & key) {
+                    const idx = data.map[key];
+                    if (!isUndefined(idx)) {
+                        result[key] = data.shared[idx];
+                    }
+                }
+            }
+            return result;
+        }
+        const idx = data.map[platform];
+        if (isUndefined(idx)) {
+            return null;
+        }
+        return { key: data.shared[idx] };
+    }
+    /**
+     * Returns all compatibility data records for the specified platform.
+     *
+     * @param platform Specific or generic platform.
+     *
+     * @returns Array of multiple records grouped by platforms.
+     */
+    getAllMultiple(platform) {
+        const result = [];
+        for (let i = 0; i < this.data.shared.length; i += 1) {
+            const data = this.data.shared[i];
+            const names = new Set(data.shared.map(({ name }) => name));
+            names.forEach((name) => {
+                const multipleRecords = this.getMultiple(name, platform);
+                if (multipleRecords) {
+                    result.push(multipleRecords);
+                }
+            });
+        }
+        return result;
+    }
+    /**
+     * Returns the first compatibility data record for name and specified platform.
+     *
+     * @param name Compatibility data name.
+     * @param platform Specific or generic platform.
+     *
+     * @returns First found compatibility data record or `null` if not found.
+     */
+    getFirst(name, platform) {
+        const normalizedName = this.nameTransformer ? this.nameTransformer(name) : name;
+        const data = this.getRowStorage(normalizedName);
+        if (!data) {
+            return null;
+        }
+        if (isGenericPlatform(platform)) {
+            const keys = Object.keys(data.map);
+            for (let i = 0; i < keys.length; i += 1) {
+                const key = Number(keys[i]);
+                if (platform & key) {
+                    const idx = data.map[key];
+                    if (!isUndefined(idx)) {
+                        // return the first found record
+                        return data.shared[idx];
+                    }
+                }
+            }
+            return null;
+        }
+        const idx = data.map[platform];
+        if (isUndefined(idx)) {
+            return null;
+        }
+        return data.shared[idx];
+    }
+    /**
+     * Returns all compatibility data records for the specified name.
+     *
+     * @param name Compatibility data name.
+     *
+     * @returns Array of multiple records grouped by platforms.
+     */
+    getRow(name) {
+        const normalizedName = this.nameTransformer ? this.nameTransformer(name) : name;
+        const data = this.getRowStorage(normalizedName);
+        if (!data) {
+            return [];
+        }
+        return data.shared;
+    }
+    /**
+     * Returns all compatibility data grouped by products.
+     *
+     * @returns Array of multiple records grouped by products.
+     */
+    getRowsByProduct() {
+        const result = [];
+        for (let i = 0; i < this.data.shared.length; i += 1) {
+            const data = this.data.shared[i];
+            const keys = Object.keys(data.map);
+            const row = {
+                [AdblockSyntax.Adg]: {},
+                [AdblockSyntax.Ubo]: {},
+                [AdblockSyntax.Abp]: {},
+            };
+            for (let j = 0; j < keys.length; j += 1) {
+                const key = Number(keys[j]);
+                if (key & GenericPlatform.AdgAny) {
+                    row[AdblockSyntax.Adg][key] = data.shared[data.map[key]];
+                }
+                else if (key & GenericPlatform.UboAny) {
+                    row[AdblockSyntax.Ubo][key] = data.shared[data.map[key]];
+                }
+                else if (key & GenericPlatform.AbpAny) {
+                    row[AdblockSyntax.Abp][key] = data.shared[data.map[key]];
+                }
+            }
+            result.push(row);
+        }
+        return result;
+    }
+}
+
+export { CompatibilityTableBase };