@adguard/agtree 2.1.2 → 3.0.0-alpha.1

package/dist/cjs/parser/rule-parser.js

@@ -0,0 +1,194 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var adblockers = require('../utils/adblockers.js');
+var commentParser = require('./comment/comment-parser.js');
+var cosmeticRuleParser = require('./cosmetic/cosmetic-rule-parser.js');
+var networkRuleParser = require('./network/network-rule-parser.js');
+var index = require('../nodes/index.js');
+var adblockSyntaxError = require('../errors/adblock-syntax-error.js');
+var options = require('./options.js');
+var baseParser = require('./base-parser.js');
+var hostRuleParser = require('./network/host-rule-parser.js');
+
+/* eslint-disable no-param-reassign */
+/**
+ * `RuleParser` is responsible for parsing the rules.
+ *
+ * It automatically determines the category and syntax of the rule, so you can pass any kind of rule to it.
+ */
+class RuleParser extends baseParser.BaseParser {
+    /**
+     * Helper method to parse host rules if the `parseHostRules` option is enabled, otherwise it will
+     * parse network rules.
+     *
+     * @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 Host rule or network rule node.
+     */
+    static parseHostOrNetworkRule(raw, options, baseOffset) {
+        if (options.parseHostRules) {
+            try {
+                return hostRuleParser.HostRuleParser.parse(raw, options, baseOffset);
+            }
+            catch (error) {
+                // Ignore the error, and fall back to network rule parser
+            }
+        }
+        return networkRuleParser.NetworkRuleParser.parse(raw, options, baseOffset);
+    }
+    /**
+     * Parse an adblock rule. You can pass any kind of rule to this method, since it will automatically determine
+     * the category and syntax. If the rule is syntactically invalid, then an error will be thrown. If the
+     * syntax / compatibility cannot be determined clearly, then the value of the `syntax` property will be
+     * `Common`.
+     *
+     * For example, let's have this network rule:
+     * ```adblock
+     * ||example.org^$important
+     * ```
+     * The `syntax` property will be `Common`, since the rule is syntactically correct in every adblockers, but we
+     * cannot determine at parsing level whether `important` is an existing option or not, nor if it exists, then
+     * which adblocker supports it. This is why the `syntax` property is simply `Common` at this point.
+     * The concrete COMPATIBILITY of the rule will be determined later, in a different, higher-level layer, called
+     * "Compatibility table".
+     *
+     * But we can determinate the concrete syntax of this rule:
+     * ```adblock
+     * example.org#%#//scriptlet("scriptlet0", "arg0")
+     * ```
+     * since it is clearly an AdGuard-specific rule and no other adblockers uses this syntax natively. However, we also
+     * cannot determine the COMPATIBILITY of this rule, as it is not clear at this point whether the `scriptlet0`
+     * scriptlet is supported by AdGuard or not. This is also the task of the "Compatibility table". Here, we simply
+     * mark the rule with the `AdGuard` syntax in this case.
+     *
+     * @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 Adblock rule node
+     * @throws If the input matches a pattern but syntactically invalid
+     * @example
+     * Take a look at the following example:
+     * ```js
+     * // Parse a network rule
+     * const ast1 = RuleParser.parse("||example.org^$important");
+     *
+     * // Parse another network rule
+     * const ast2 = RuleParser.parse("/ads.js^$important,third-party,domain=example.org|~example.com");
+     *
+     * // Parse a cosmetic rule
+     * const ast2 = RuleParser.parse("example.org##.banner");
+     *
+     * // Parse another cosmetic rule
+     * const ast3 = RuleParser.parse("example.org#?#.banner:-abp-has(.ad)");
+     *
+     * // Parse a comment rule
+     * const ast4 = RuleParser.parse("! Comment");
+     *
+     * // Parse an empty rule
+     * const ast5 = RuleParser.parse("");
+     *
+     * // Parse a comment rule (with metadata)
+     * const ast6 = RuleParser.parse("! Title: Example");
+     *
+     * // Parse a pre-processor rule
+     * const ast7 = RuleParser.parse("!#if (adguard)");
+     * ```
+     */
+    static parse(raw, options$1 = options.defaultParserOptions, baseOffset = 0) {
+        try {
+            // Empty lines / rules (handle it just for convenience)
+            if (raw.trim().length === 0) {
+                const result = {
+                    type: 'EmptyRule',
+                    category: index.RuleCategory.Empty,
+                    syntax: adblockers.AdblockSyntax.Common,
+                };
+                if (options$1.includeRaws) {
+                    result.raws = {
+                        text: raw,
+                    };
+                }
+                if (options$1.isLocIncluded) {
+                    result.start = baseOffset;
+                    result.end = baseOffset + raw.length;
+                }
+                return result;
+            }
+            // Try to parse the rule with all sub-parsers. If a rule doesn't match
+            // the pattern of a parser, then it will return `null`. For example, a
+            // network rule will not match the pattern of a comment rule, since it
+            // doesn't start with comment marker. But if the rule matches the
+            // pattern of a parser, then it will return the AST of the rule, or
+            // throw an error if the rule is syntactically invalid.
+            if (options$1.ignoreComments) {
+                if (commentParser.CommentParser.isCommentRule(raw)) {
+                    const result = {
+                        type: 'EmptyRule',
+                        category: index.RuleCategory.Empty,
+                        syntax: adblockers.AdblockSyntax.Common,
+                    };
+                    if (options$1.includeRaws) {
+                        result.raws = {
+                            text: raw,
+                        };
+                    }
+                    if (options$1.isLocIncluded) {
+                        result.start = baseOffset;
+                        result.end = baseOffset + raw.length;
+                    }
+                    return result;
+                }
+                return cosmeticRuleParser.CosmeticRuleParser.parse(raw, options$1, baseOffset)
+                    || RuleParser.parseHostOrNetworkRule(raw, options$1, baseOffset);
+            }
+            return commentParser.CommentParser.parse(raw, options$1, baseOffset)
+                || cosmeticRuleParser.CosmeticRuleParser.parse(raw, options$1, baseOffset)
+                || RuleParser.parseHostOrNetworkRule(raw, options$1, baseOffset);
+        }
+        catch (error) {
+            // If tolerant mode is disabled or the error is not known, then simply
+            // re-throw the error
+            if (!options$1.tolerant || !(error instanceof Error)) {
+                throw error;
+            }
+            const errorNode = {
+                type: 'InvalidRuleError',
+                name: error.name,
+                message: error.message,
+            };
+            // If the error is an AdblockSyntaxError, then we can add the
+            // location of the error to the result
+            if (error instanceof adblockSyntaxError.AdblockSyntaxError) {
+                errorNode.start = error.start;
+                errorNode.end = error.end;
+            }
+            // Otherwise, return an invalid rule (tolerant mode)
+            const result = {
+                type: 'InvalidRule',
+                category: index.RuleCategory.Invalid,
+                syntax: adblockers.AdblockSyntax.Common,
+                raw,
+                error: errorNode,
+            };
+            if (options$1.includeRaws) {
+                result.raws = {
+                    text: raw,
+                };
+            }
+            if (options$1.isLocIncluded) {
+                result.start = baseOffset;
+                result.end = baseOffset + raw.length;
+            }
+            return result;
+        }
+    }
+}
+
+exports.RuleParser = RuleParser;

package/dist/cjs/serializer/base-serializer.js

@@ -0,0 +1,31 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var notImplementedError = require('../errors/not-implemented-error.js');
+
+/**
+ * @file Base serializer class.
+ */
+/**
+ * Base class for serializers. Each serializer should extend this class.
+ */
+class BaseSerializer {
+    /**
+     * Serializes the AST node to a byte buffer.
+     *
+     * @param node AST node to serialize.
+     * @param buffer Output byte buffer to write to.
+     * @param args Additional, parser-specific arguments, if needed.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    static serialize(node, buffer, ...args) {
+        throw new notImplementedError.NotImplementedError();
+    }
+}
+
+exports.BaseSerializer = BaseSerializer;

package/dist/cjs/serializer/comment/agent-comment-serializer.js

@@ -0,0 +1,73 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var constants = require('../../utils/constants.js');
+var agentSerializer = require('./agent-serializer.js');
+var typeGuards = require('../../utils/type-guards.js');
+var baseSerializer = require('../base-serializer.js');
+var agentCommentCommon = require('../../marshalling-utils/comment/agent-comment-common.js');
+var binaryTypeCommon = require('../../marshalling-utils/misc/binary-type-common.js');
+
+/**
+ * `AgentCommentSerializer` is responsible for serializing an Adblock agent comments.
+ * Adblock agent comment marks that the filter list is supposed to
+ * be used by the specified ad blockers.
+ *
+ * @example
+ *  - ```adblock
+ *    [AdGuard]
+ *    ```
+ *  - ```adblock
+ *    [Adblock Plus 2.0]
+ *    ```
+ *  - ```adblock
+ *    [uBlock Origin]
+ *    ```
+ *  - ```adblock
+ *    [uBlock Origin 1.45.3]
+ *    ```
+ *  - ```adblock
+ *    [Adblock Plus 2.0; AdGuard]
+ *    ```
+ */
+class AgentCommentSerializer extends baseSerializer.BaseSerializer {
+    /**
+     * Serializes an adblock agent list node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    // TODO: add support for raws, if ever needed
+    static serialize(node, buffer) {
+        buffer.writeUint8(binaryTypeCommon.BinaryTypeMarshallingMap.AgentRuleNode);
+        const count = node.children.length;
+        if (count) {
+            buffer.writeUint8(agentCommentCommon.AgentCommentMarshallingMap.Children);
+            // note: we store the count, because re-construction of the array is faster if we know the length
+            // 8 bits is more than enough here
+            if (count > constants.UINT8_MAX) {
+                throw new Error(`Too many children: ${count}, the limit is ${constants.UINT8_MAX}`);
+            }
+            buffer.writeUint8(count);
+            for (let i = 0; i < count; i += 1) {
+                agentSerializer.AgentSerializer.serialize(node.children[i], buffer);
+            }
+        }
+        if (!typeGuards.isUndefined(node.start)) {
+            buffer.writeUint8(agentCommentCommon.AgentCommentMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!typeGuards.isUndefined(node.end)) {
+            buffer.writeUint8(agentCommentCommon.AgentCommentMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(constants.NULL);
+    }
+}
+
+exports.AgentCommentSerializer = AgentCommentSerializer;

package/dist/cjs/serializer/comment/agent-serializer.js

@@ -0,0 +1,70 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var constants = require('../../utils/constants.js');
+var valueSerializer = require('../misc/value-serializer.js');
+var typeGuards = require('../../utils/type-guards.js');
+var baseSerializer = require('../base-serializer.js');
+var agentCommon = require('../../marshalling-utils/comment/agent-common.js');
+var binaryTypeCommon = require('../../marshalling-utils/misc/binary-type-common.js');
+
+/**
+ * Value map for binary serialization. This helps to reduce the size of the serialized data,
+ * as it allows us to use a single byte to represent frequently used values.
+ *
+ * ! IMPORTANT: If you change values here, please update the {@link BINARY_SCHEMA_VERSION}!
+ *
+ * @note Only 256 values can be represented this way.
+ */
+let frequentAgentsSerializationMap;
+const getFrequentAgentsSerializationMap = () => {
+    if (!frequentAgentsSerializationMap) {
+        frequentAgentsSerializationMap = new Map(Array.from(agentCommon.FREQUENT_AGENTS_DESERIALIZATION_MAP).map(([key, value]) => [value.toLowerCase(), key]));
+    }
+    return frequentAgentsSerializationMap;
+};
+/**
+ * `AgentParser` is responsible for parsing single adblock agent elements.
+ *
+ * @example
+ * If the adblock agent rule is
+ * ```adblock
+ * [Adblock Plus 2.0; AdGuard]
+ * ```
+ * then the adblock agents are `Adblock Plus 2.0` and `AdGuard`, and this
+ * class is responsible for parsing them. The rule itself is parsed by
+ * `AgentCommentSerializer`, which uses this class to parse single agents.
+ */
+class AgentSerializer extends baseSerializer.BaseSerializer {
+    /**
+     * Serializes an agent node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        buffer.writeUint8(binaryTypeCommon.BinaryTypeMarshallingMap.AgentNode);
+        buffer.writeUint8(agentCommon.AgentNodeMarshallingMap.Adblock);
+        valueSerializer.ValueSerializer.serialize(node.adblock, buffer, getFrequentAgentsSerializationMap(), true);
+        if (!typeGuards.isUndefined(node.version)) {
+            buffer.writeUint8(agentCommon.AgentNodeMarshallingMap.Version);
+            valueSerializer.ValueSerializer.serialize(node.version, buffer);
+        }
+        if (!typeGuards.isUndefined(node.start)) {
+            buffer.writeUint8(agentCommon.AgentNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!typeGuards.isUndefined(node.end)) {
+            buffer.writeUint8(agentCommon.AgentNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(constants.NULL);
+    }
+}
+
+exports.AgentSerializer = AgentSerializer;

package/dist/cjs/serializer/comment/comment-rule-serializer.js

@@ -0,0 +1,107 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var agentCommentSerializer = require('./agent-comment-serializer.js');
+var index = require('../../nodes/index.js');
+var configCommentSerializer = require('./config-comment-serializer.js');
+var hintCommentSerializer = require('./hint-comment-serializer.js');
+var metadataCommentSerializer = require('./metadata-comment-serializer.js');
+var preProcessorCommentSerializer = require('./pre-processor-comment-serializer.js');
+var simpleCommentSerializer = require('./simple-comment-serializer.js');
+var baseSerializer = require('../base-serializer.js');
+
+/**
+ * `CommentRuleSerializer` is responsible for serializing any comment-like adblock rules.
+ *
+ * @example
+ * Example rules:
+ *  - Adblock agent rules:
+ *      - ```adblock
+ *        [AdGuard]
+ *        ```
+ *      - ```adblock
+ *        [Adblock Plus 2.0]
+ *        ```
+ *      - etc.
+ *  - AdGuard hint rules:
+ *      - ```adblock
+ *        !+ NOT_OPTIMIZED
+ *        ```
+ *      - ```adblock
+ *        !+ NOT_OPTIMIZED PLATFORM(windows)
+ *        ```
+ *      - etc.
+ *  - Pre-processor rules:
+ *      - ```adblock
+ *        !#if (adguard)
+ *        ```
+ *      - ```adblock
+ *        !#endif
+ *        ```
+ *      - etc.
+ *  - Metadata rules:
+ *      - ```adblock
+ *        ! Title: My List
+ *        ```
+ *      - ```adblock
+ *        ! Version: 2.0.150
+ *        ```
+ *      - etc.
+ *  - AGLint inline config rules:
+ *      - ```adblock
+ *        ! aglint-enable some-rule
+ *        ```
+ *      - ```adblock
+ *        ! aglint-disable some-rule
+ *        ```
+ *      - etc.
+ *  - Simple comments:
+ *      - Regular version:
+ *        ```adblock
+ *        ! This is just a comment
+ *        ```
+ *      - uBlock Origin / "hostlist" version:
+ *        ```adblock
+ *        # This is just a comment
+ *        ```
+ *      - etc.
+ */
+class CommentRuleSerializer extends baseSerializer.BaseSerializer {
+    /**
+     * Serializes a comment rule node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        switch (node.type) {
+            case index.CommentRuleType.AgentCommentRule:
+                agentCommentSerializer.AgentCommentSerializer.serialize(node, buffer);
+                return;
+            case index.CommentRuleType.HintCommentRule:
+                hintCommentSerializer.HintCommentSerializer.serialize(node, buffer);
+                return;
+            case index.CommentRuleType.PreProcessorCommentRule:
+                preProcessorCommentSerializer.PreProcessorCommentSerializer.serialize(node, buffer);
+                return;
+            case index.CommentRuleType.MetadataCommentRule:
+                metadataCommentSerializer.MetadataCommentSerializer.serialize(node, buffer);
+                return;
+            case index.CommentRuleType.ConfigCommentRule:
+                configCommentSerializer.ConfigCommentSerializer.serialize(node, buffer);
+                return;
+            case index.CommentRuleType.CommentRule:
+                simpleCommentSerializer.SimpleCommentSerializer.serialize(node, buffer);
+                break;
+            default:
+                throw new Error('Unknown comment rule type');
+        }
+    }
+}
+
+exports.CommentRuleSerializer = CommentRuleSerializer;

package/dist/cjs/serializer/comment/config-comment-serializer.js

@@ -0,0 +1,84 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var constants = require('../../utils/constants.js');
+var parameterListSerializer = require('../misc/parameter-list-serializer.js');
+var valueSerializer = require('../misc/value-serializer.js');
+var typeGuards = require('../../utils/type-guards.js');
+var baseSerializer = require('../base-serializer.js');
+var configCommentCommon = require('../../marshalling-utils/comment/config-comment-common.js');
+var binaryTypeCommon = require('../../marshalling-utils/misc/binary-type-common.js');
+
+/**
+ * `ConfigCommentParser` is responsible for parsing inline AGLint configuration rules.
+ * Generally, the idea is inspired by ESLint inline configuration comments.
+ *
+ * @see {@link https://eslint.org/docs/latest/user-guide/configuring/rules#using-configuration-comments}
+ */
+class ConfigCommentSerializer extends baseSerializer.BaseSerializer {
+    /**
+     * Serializes a config node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serializeConfigNode(node, buffer) {
+        buffer.writeUint8(binaryTypeCommon.BinaryTypeMarshallingMap.ConfigNode);
+        buffer.writeUint8(configCommentCommon.ConfigNodeMarshallingMap.Value);
+        // note: we don't support serializing generic objects, only AGTree nodes
+        // this is a very special case, so we just stringify the configuration object
+        buffer.writeString(JSON.stringify(node.value));
+        if (!typeGuards.isUndefined(node.start)) {
+            buffer.writeUint8(configCommentCommon.ConfigNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!typeGuards.isUndefined(node.end)) {
+            buffer.writeUint8(configCommentCommon.ConfigNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(constants.NULL);
+    }
+    /**
+     * Serializes a metadata comment node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    // TODO: add support for raws, if ever needed
+    static serialize(node, buffer) {
+        buffer.writeUint8(binaryTypeCommon.BinaryTypeMarshallingMap.ConfigCommentRuleNode);
+        buffer.writeUint8(configCommentCommon.ConfigCommentRuleMarshallingMap.Marker);
+        valueSerializer.ValueSerializer.serialize(node.marker, buffer);
+        buffer.writeUint8(configCommentCommon.ConfigCommentRuleMarshallingMap.Command);
+        valueSerializer.ValueSerializer.serialize(node.command, buffer, configCommentCommon.FREQUENT_COMMANDS_SERIALIZATION_MAP, true);
+        if (!typeGuards.isUndefined(node.params)) {
+            buffer.writeUint8(configCommentCommon.ConfigCommentRuleMarshallingMap.Params);
+            if (node.params.type === 'ParameterList') {
+                parameterListSerializer.ParameterListSerializer.serialize(node.params, buffer);
+            }
+            else {
+                ConfigCommentSerializer.serializeConfigNode(node.params, buffer);
+            }
+        }
+        if (!typeGuards.isUndefined(node.comment)) {
+            buffer.writeUint8(configCommentCommon.ConfigCommentRuleMarshallingMap.Comment);
+            valueSerializer.ValueSerializer.serialize(node.comment, buffer);
+        }
+        if (!typeGuards.isUndefined(node.start)) {
+            buffer.writeUint8(configCommentCommon.ConfigCommentRuleMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!typeGuards.isUndefined(node.end)) {
+            buffer.writeUint8(configCommentCommon.ConfigCommentRuleMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(constants.NULL);
+    }
+}
+
+exports.ConfigCommentSerializer = ConfigCommentSerializer;

package/dist/cjs/serializer/comment/hint-comment-serializer.js

@@ -0,0 +1,64 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var constants = require('../../utils/constants.js');
+var hintSerializer = require('./hint-serializer.js');
+var adblockers = require('../../utils/adblockers.js');
+var typeGuards = require('../../utils/type-guards.js');
+var baseSerializer = require('../base-serializer.js');
+var hintCommentCommon = require('../../marshalling-utils/comment/hint-comment-common.js');
+var binaryTypeCommon = require('../../marshalling-utils/misc/binary-type-common.js');
+var syntaxSerializationMap = require('../../marshalling-utils/syntax-serialization-map.js');
+
+/**
+ * `HintCommentSerializer` is responsible for serializing 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 HintCommentSerializer extends baseSerializer.BaseSerializer {
+    /**
+     * Serializes a hint rule node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    // TODO: add support for raws, if ever needed
+    static serialize(node, buffer) {
+        buffer.writeUint8(binaryTypeCommon.BinaryTypeMarshallingMap.HintRuleNode);
+        if (node.syntax === adblockers.AdblockSyntax.Adg) {
+            buffer.writeUint8(hintCommentCommon.HintCommentMarshallingMap.Syntax);
+            buffer.writeUint8(syntaxSerializationMap.getSyntaxSerializationMap().get(adblockers.AdblockSyntax.Adg) ?? 0);
+        }
+        const count = node.children.length;
+        if (count) {
+            buffer.writeUint8(hintCommentCommon.HintCommentMarshallingMap.Children);
+            // note: we store the count, because re-construction of the array is faster if we know the length
+            buffer.writeUint8(count);
+            for (let i = 0; i < count; i += 1) {
+                hintSerializer.HintSerializer.serialize(node.children[i], buffer);
+            }
+        }
+        if (!typeGuards.isUndefined(node.start)) {
+            buffer.writeUint8(hintCommentCommon.HintCommentMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!typeGuards.isUndefined(node.end)) {
+            buffer.writeUint8(hintCommentCommon.HintCommentMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(constants.NULL);
+    }
+}
+
+exports.HintCommentSerializer = HintCommentSerializer;

package/dist/cjs/serializer/comment/hint-serializer.js

@@ -0,0 +1,56 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var constants = require('../../utils/constants.js');
+var parameterListSerializer = require('../misc/parameter-list-serializer.js');
+var valueSerializer = require('../misc/value-serializer.js');
+var typeGuards = require('../../utils/type-guards.js');
+var baseSerializer = require('../base-serializer.js');
+var hintCommon = require('../../marshalling-utils/comment/hint-common.js');
+var binaryTypeCommon = require('../../marshalling-utils/misc/binary-type-common.js');
+
+/**
+ * `HintSerializer` is responsible for serializing 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 HintSerializer extends baseSerializer.BaseSerializer {
+    /**
+     * Serializes a hint node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        buffer.writeUint8(binaryTypeCommon.BinaryTypeMarshallingMap.HintNode);
+        buffer.writeUint8(hintCommon.HintNodeMarshallingMap.Name);
+        valueSerializer.ValueSerializer.serialize(node.name, buffer, hintCommon.FREQUENT_HINTS_SERIALIZATION_MAP);
+        if (!typeGuards.isUndefined(node.params)) {
+            buffer.writeUint8(hintCommon.HintNodeMarshallingMap.Params);
+            parameterListSerializer.ParameterListSerializer.serialize(node.params, buffer, hintCommon.FREQUENT_PLATFORMS_SERIALIZATION_MAP);
+        }
+        if (!typeGuards.isUndefined(node.start)) {
+            buffer.writeUint8(hintCommon.HintNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!typeGuards.isUndefined(node.end)) {
+            buffer.writeUint8(hintCommon.HintNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(constants.NULL);
+    }
+}
+
+exports.HintSerializer = HintSerializer;