@adguard/agtree 2.1.2 → 3.0.0-alpha.1

package/dist/esm/parser/rule-parser.mjs

@@ -0,0 +1,192 @@
+/*
+ * 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
+ */
+import { AdblockSyntax } from '../utils/adblockers.mjs';
+import { CommentParser } from './comment/comment-parser.mjs';
+import { CosmeticRuleParser } from './cosmetic/cosmetic-rule-parser.mjs';
+import { NetworkRuleParser } from './network/network-rule-parser.mjs';
+import { RuleCategory } from '../nodes/index.mjs';
+import { AdblockSyntaxError } from '../errors/adblock-syntax-error.mjs';
+import { defaultParserOptions } from './options.mjs';
+import { BaseParser } from './base-parser.mjs';
+import { HostRuleParser } from './network/host-rule-parser.mjs';
+
+/* 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 {
+    /**
+     * 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.parse(raw, options, baseOffset);
+            }
+            catch (error) {
+                // Ignore the error, and fall back to network rule parser
+            }
+        }
+        return 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 = defaultParserOptions, baseOffset = 0) {
+        try {
+            // Empty lines / rules (handle it just for convenience)
+            if (raw.trim().length === 0) {
+                const result = {
+                    type: 'EmptyRule',
+                    category: RuleCategory.Empty,
+                    syntax: AdblockSyntax.Common,
+                };
+                if (options.includeRaws) {
+                    result.raws = {
+                        text: raw,
+                    };
+                }
+                if (options.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.ignoreComments) {
+                if (CommentParser.isCommentRule(raw)) {
+                    const result = {
+                        type: 'EmptyRule',
+                        category: RuleCategory.Empty,
+                        syntax: AdblockSyntax.Common,
+                    };
+                    if (options.includeRaws) {
+                        result.raws = {
+                            text: raw,
+                        };
+                    }
+                    if (options.isLocIncluded) {
+                        result.start = baseOffset;
+                        result.end = baseOffset + raw.length;
+                    }
+                    return result;
+                }
+                return CosmeticRuleParser.parse(raw, options, baseOffset)
+                    || RuleParser.parseHostOrNetworkRule(raw, options, baseOffset);
+            }
+            return CommentParser.parse(raw, options, baseOffset)
+                || CosmeticRuleParser.parse(raw, options, baseOffset)
+                || RuleParser.parseHostOrNetworkRule(raw, options, baseOffset);
+        }
+        catch (error) {
+            // If tolerant mode is disabled or the error is not known, then simply
+            // re-throw the error
+            if (!options.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) {
+                errorNode.start = error.start;
+                errorNode.end = error.end;
+            }
+            // Otherwise, return an invalid rule (tolerant mode)
+            const result = {
+                type: 'InvalidRule',
+                category: RuleCategory.Invalid,
+                syntax: AdblockSyntax.Common,
+                raw,
+                error: errorNode,
+            };
+            if (options.includeRaws) {
+                result.raws = {
+                    text: raw,
+                };
+            }
+            if (options.isLocIncluded) {
+                result.start = baseOffset;
+                result.end = baseOffset + raw.length;
+            }
+            return result;
+        }
+    }
+}
+
+export { RuleParser };

package/dist/esm/serializer/base-serializer.mjs

@@ -0,0 +1,29 @@
+/*
+ * 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
+ */
+import { NotImplementedError } from '../errors/not-implemented-error.mjs';
+
+/**
+ * @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();
+    }
+}
+
+export { BaseSerializer };

package/dist/esm/serializer/comment/agent-comment-serializer.mjs

@@ -0,0 +1,71 @@
+/*
+ * 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
+ */
+import { UINT8_MAX, NULL } from '../../utils/constants.mjs';
+import { AgentSerializer } from './agent-serializer.mjs';
+import { isUndefined } from '../../utils/type-guards.mjs';
+import { BaseSerializer } from '../base-serializer.mjs';
+import { AgentCommentMarshallingMap } from '../../marshalling-utils/comment/agent-comment-common.mjs';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.mjs';
+
+/**
+ * `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 {
+    /**
+     * 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(BinaryTypeMarshallingMap.AgentRuleNode);
+        const count = node.children.length;
+        if (count) {
+            buffer.writeUint8(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 > UINT8_MAX) {
+                throw new Error(`Too many children: ${count}, the limit is ${UINT8_MAX}`);
+            }
+            buffer.writeUint8(count);
+            for (let i = 0; i < count; i += 1) {
+                AgentSerializer.serialize(node.children[i], buffer);
+            }
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(AgentCommentMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(AgentCommentMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { AgentCommentSerializer };

package/dist/esm/serializer/comment/agent-serializer.mjs

@@ -0,0 +1,68 @@
+/*
+ * 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
+ */
+import { NULL } from '../../utils/constants.mjs';
+import { ValueSerializer } from '../misc/value-serializer.mjs';
+import { isUndefined } from '../../utils/type-guards.mjs';
+import { BaseSerializer } from '../base-serializer.mjs';
+import { AgentNodeMarshallingMap, FREQUENT_AGENTS_DESERIALIZATION_MAP } from '../../marshalling-utils/comment/agent-common.mjs';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.mjs';
+
+/**
+ * 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(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 {
+    /**
+     * 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(BinaryTypeMarshallingMap.AgentNode);
+        buffer.writeUint8(AgentNodeMarshallingMap.Adblock);
+        ValueSerializer.serialize(node.adblock, buffer, getFrequentAgentsSerializationMap(), true);
+        if (!isUndefined(node.version)) {
+            buffer.writeUint8(AgentNodeMarshallingMap.Version);
+            ValueSerializer.serialize(node.version, buffer);
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(AgentNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(AgentNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { AgentSerializer };

package/dist/esm/serializer/comment/comment-rule-serializer.mjs

@@ -0,0 +1,105 @@
+/*
+ * 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
+ */
+import { AgentCommentSerializer } from './agent-comment-serializer.mjs';
+import { CommentRuleType } from '../../nodes/index.mjs';
+import { ConfigCommentSerializer } from './config-comment-serializer.mjs';
+import { HintCommentSerializer } from './hint-comment-serializer.mjs';
+import { MetadataCommentSerializer } from './metadata-comment-serializer.mjs';
+import { PreProcessorCommentSerializer } from './pre-processor-comment-serializer.mjs';
+import { SimpleCommentSerializer } from './simple-comment-serializer.mjs';
+import { BaseSerializer } from '../base-serializer.mjs';
+
+/**
+ * `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 {
+    /**
+     * 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 CommentRuleType.AgentCommentRule:
+                AgentCommentSerializer.serialize(node, buffer);
+                return;
+            case CommentRuleType.HintCommentRule:
+                HintCommentSerializer.serialize(node, buffer);
+                return;
+            case CommentRuleType.PreProcessorCommentRule:
+                PreProcessorCommentSerializer.serialize(node, buffer);
+                return;
+            case CommentRuleType.MetadataCommentRule:
+                MetadataCommentSerializer.serialize(node, buffer);
+                return;
+            case CommentRuleType.ConfigCommentRule:
+                ConfigCommentSerializer.serialize(node, buffer);
+                return;
+            case CommentRuleType.CommentRule:
+                SimpleCommentSerializer.serialize(node, buffer);
+                break;
+            default:
+                throw new Error('Unknown comment rule type');
+        }
+    }
+}
+
+export { CommentRuleSerializer };

package/dist/esm/serializer/comment/config-comment-serializer.mjs

@@ -0,0 +1,82 @@
+/*
+ * 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
+ */
+import { NULL } from '../../utils/constants.mjs';
+import { ParameterListSerializer } from '../misc/parameter-list-serializer.mjs';
+import { ValueSerializer } from '../misc/value-serializer.mjs';
+import { isUndefined } from '../../utils/type-guards.mjs';
+import { BaseSerializer } from '../base-serializer.mjs';
+import { ConfigNodeMarshallingMap, ConfigCommentRuleMarshallingMap, FREQUENT_COMMANDS_SERIALIZATION_MAP } from '../../marshalling-utils/comment/config-comment-common.mjs';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.mjs';
+
+/**
+ * `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 {
+    /**
+     * 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(BinaryTypeMarshallingMap.ConfigNode);
+        buffer.writeUint8(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 (!isUndefined(node.start)) {
+            buffer.writeUint8(ConfigNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(ConfigNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(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(BinaryTypeMarshallingMap.ConfigCommentRuleNode);
+        buffer.writeUint8(ConfigCommentRuleMarshallingMap.Marker);
+        ValueSerializer.serialize(node.marker, buffer);
+        buffer.writeUint8(ConfigCommentRuleMarshallingMap.Command);
+        ValueSerializer.serialize(node.command, buffer, FREQUENT_COMMANDS_SERIALIZATION_MAP, true);
+        if (!isUndefined(node.params)) {
+            buffer.writeUint8(ConfigCommentRuleMarshallingMap.Params);
+            if (node.params.type === 'ParameterList') {
+                ParameterListSerializer.serialize(node.params, buffer);
+            }
+            else {
+                ConfigCommentSerializer.serializeConfigNode(node.params, buffer);
+            }
+        }
+        if (!isUndefined(node.comment)) {
+            buffer.writeUint8(ConfigCommentRuleMarshallingMap.Comment);
+            ValueSerializer.serialize(node.comment, buffer);
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(ConfigCommentRuleMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(ConfigCommentRuleMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { ConfigCommentSerializer };

package/dist/esm/serializer/comment/hint-comment-serializer.mjs

@@ -0,0 +1,62 @@
+/*
+ * 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
+ */
+import { NULL } from '../../utils/constants.mjs';
+import { HintSerializer } from './hint-serializer.mjs';
+import { AdblockSyntax } from '../../utils/adblockers.mjs';
+import { isUndefined } from '../../utils/type-guards.mjs';
+import { BaseSerializer } from '../base-serializer.mjs';
+import { HintCommentMarshallingMap } from '../../marshalling-utils/comment/hint-comment-common.mjs';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.mjs';
+import { getSyntaxSerializationMap } from '../../marshalling-utils/syntax-serialization-map.mjs';
+
+/**
+ * `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 {
+    /**
+     * 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(BinaryTypeMarshallingMap.HintRuleNode);
+        if (node.syntax === AdblockSyntax.Adg) {
+            buffer.writeUint8(HintCommentMarshallingMap.Syntax);
+            buffer.writeUint8(getSyntaxSerializationMap().get(AdblockSyntax.Adg) ?? 0);
+        }
+        const count = node.children.length;
+        if (count) {
+            buffer.writeUint8(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.serialize(node.children[i], buffer);
+            }
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(HintCommentMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(HintCommentMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { HintCommentSerializer };

package/dist/esm/serializer/comment/hint-serializer.mjs

@@ -0,0 +1,54 @@
+/*
+ * 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
+ */
+import { NULL } from '../../utils/constants.mjs';
+import { ParameterListSerializer } from '../misc/parameter-list-serializer.mjs';
+import { ValueSerializer } from '../misc/value-serializer.mjs';
+import { isUndefined } from '../../utils/type-guards.mjs';
+import { BaseSerializer } from '../base-serializer.mjs';
+import { HintNodeMarshallingMap, FREQUENT_HINTS_SERIALIZATION_MAP, FREQUENT_PLATFORMS_SERIALIZATION_MAP } from '../../marshalling-utils/comment/hint-common.mjs';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.mjs';
+
+/**
+ * `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 {
+    /**
+     * 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(BinaryTypeMarshallingMap.HintNode);
+        buffer.writeUint8(HintNodeMarshallingMap.Name);
+        ValueSerializer.serialize(node.name, buffer, FREQUENT_HINTS_SERIALIZATION_MAP);
+        if (!isUndefined(node.params)) {
+            buffer.writeUint8(HintNodeMarshallingMap.Params);
+            ParameterListSerializer.serialize(node.params, buffer, FREQUENT_PLATFORMS_SERIALIZATION_MAP);
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(HintNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(HintNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { HintSerializer };