@adguard/agtree 3.0.0 → 3.1.0

package/dist/types/deserializer/network/hostname-list-deserializer.d.ts

@@ -1,6 +1,9 @@
 import { BaseDeserializer } from '../base-deserializer';
 import { type HostnameList } from '../../nodes';
 import { type InputByteBuffer } from '../../utils/input-byte-buffer';
+/**
+ * Deserializes hostname list nodes from binary format.
+ */
 export declare class HostnameListDeserializer extends BaseDeserializer {
     /**
      * Deserializes a hostname list node from binary format.

package/dist/types/generator/comment/agent-comment-generator.d.ts

@@ -1,5 +1,8 @@
 import type { AgentCommentRule } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Generator for agent comment rules.
+ */
 export declare class AgentCommentGenerator extends BaseGenerator {
     /**
      * Converts an adblock agent AST to a string.

package/dist/types/generator/comment/agent-generator.d.ts

@@ -1,5 +1,9 @@
 import { BaseGenerator } from '../base-generator';
 import type { Agent } from '../../nodes';
+/**
+ * Generator for adblock agent nodes.
+ * This class is responsible for converting adblock agent nodes into their string representation.
+ */
 export declare class AgentGenerator extends BaseGenerator {
     /**
      * Converts an adblock agent node to a string.

package/dist/types/generator/comment/comment-rule-generator.d.ts

@@ -1,60 +1,7 @@
 import { type AnyCommentRule } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
 /**
- * `CommentParser` is responsible for parsing 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.
+ * `CommentRuleGenerator` is responsible for generating any comment-like adblock rules.
  */
 export declare class CommentRuleGenerator extends BaseGenerator {
     /**

package/dist/types/generator/comment/config-comment-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from '../base-generator';
 import type { ConfigCommentRule } from '../../nodes';
+/**
+ * Converts inline configuration comment nodes to their string format.
+ */
 export declare class ConfigCommentGenerator extends BaseGenerator {
     /**
      * Converts an inline configuration comment node to a string.

package/dist/types/generator/comment/hint-comment-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from '../base-generator';
 import type { HintCommentRule } from '../../nodes';
+/**
+ * Hint comment generator.
+ */
 export declare class HintCommentGenerator extends BaseGenerator {
     /**
      * Converts a hint rule node to a raw string.

package/dist/types/generator/comment/hint-generator.d.ts

@@ -1,11 +1,14 @@
 import type { Hint } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Hint generator.
+ */
 export declare class HintGenerator extends BaseGenerator {
     /**
-     * Converts a single hint AST to a string.
+     * Generates a string representation of a hint.
      *
-     * @param hint Hint AST
-     * @returns Hint string
+     * @param hint Hint AST node
+     * @returns String representation of the hint
      */
     static generate(hint: Hint): string;
 }

package/dist/types/generator/comment/index.d.ts

@@ -1,2 +1 @@
-import { CommentRuleGenerator } from './comment-rule-generator';
-export { CommentRuleGenerator };
+export { CommentRuleGenerator } from './comment-rule-generator';

package/dist/types/generator/comment/metadata-comment-generator.d.ts

@@ -1,5 +1,8 @@
 import type { MetadataCommentRule } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Metadata comment generator.
+ */
 export declare class MetadataCommentGenerator extends BaseGenerator {
     /**
      * Converts a metadata comment rule node to a string.

package/dist/types/generator/comment/pre-processor-comment-generator.d.ts

@@ -1,5 +1,8 @@
 import type { PreProcessorCommentRule } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Pre-processor comment generator.
+ */
 export declare class PreProcessorCommentGenerator extends BaseGenerator {
     /**
      * Converts a pre-processor comment node to a string.

package/dist/types/generator/comment/simple-comment-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from '../base-generator';
 import type { CommentRule } from '../../nodes';
+/**
+ * Simple comment generator.
+ */
 export declare class SimpleCommentGenerator extends BaseGenerator {
     /**
      * Converts a comment rule node to a string.

package/dist/types/generator/cosmetic/body/abp-snippet-injection-body-generator.d.ts

@@ -1,11 +1,15 @@
 import type { ScriptletInjectionRuleBody } from '../../../nodes';
 import { BaseGenerator } from '../../base-generator';
+/**
+ * Adblock Plus snippet injection body generator.
+ */
 export declare class AbpSnippetInjectionBodyGenerator extends BaseGenerator {
     /**
      * Generates a string representation of the Adblock Plus-style snippet call body.
      *
      * @param node Scriptlet injection rule body
      * @returns String representation of the rule body
+     * @throws Error if the scriptlet call is empty
      */
     static generate(node: ScriptletInjectionRuleBody): string;
 }

package/dist/types/generator/cosmetic/body/adg-scriptlet-injection-body-generator.d.ts

@@ -1,8 +1,11 @@
 import type { ScriptletInjectionRuleBody } from '../../../nodes';
 import { BaseGenerator } from '../../base-generator';
+/**
+ * AdGuard scriptlet injection body generator.
+ */
 export declare class AdgScriptletInjectionBodyGenerator extends BaseGenerator {
     /**
-     * Error messages used by the parser.
+     * Error messages used by the generator.
      */
     static readonly ERROR_MESSAGES: {
         NO_MULTIPLE_SCRIPTLET_CALLS: string;
@@ -12,6 +15,7 @@ export declare class AdgScriptletInjectionBodyGenerator extends BaseGenerator {
      *
      * @param node Scriptlet injection rule body
      * @returns String representation of the rule body
+     * @throws Error if the scriptlet call has multiple parameters
      */
     static generate(node: ScriptletInjectionRuleBody): string;
 }

package/dist/types/generator/cosmetic/body/ubo-scriptlet-injection-body-generator.d.ts

@@ -1,8 +1,11 @@
 import { BaseGenerator } from '../../base-generator';
 import type { ScriptletInjectionRuleBody } from '../../../nodes';
+/**
+ * uBlock scriptlet injection body generator.
+ */
 export declare class UboScriptletInjectionBodyGenerator extends BaseGenerator {
     /**
-     * Error messages used by the parser.
+     * Error messages used by the generator.
      */
     static readonly ERROR_MESSAGES: {
         NO_MULTIPLE_SCRIPTLET_CALLS: string;
@@ -12,6 +15,7 @@ export declare class UboScriptletInjectionBodyGenerator extends BaseGenerator {
      *
      * @param node Scriptlet injection rule body
      * @returns String representation of the rule body
+     * @throws Error if the scriptlet call has multiple parameters
      */
     static generate(node: ScriptletInjectionRuleBody): string;
 }

package/dist/types/generator/cosmetic/cosmetic-rule-body-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from '../base-generator';
 import { type AnyCosmeticRule } from '../../nodes';
+/**
+ * Cosmetic rule body generator.
+ */
 export declare class CosmeticRuleBodyGenerator extends BaseGenerator {
     /**
      * Generates the rule body from the node.
@@ -10,6 +13,8 @@ export declare class CosmeticRuleBodyGenerator extends BaseGenerator {
      * - '##.foo' → '.foo'
      * - 'example.com,example.org##.foo' → '.foo'
      * - 'example.com#%#//scriptlet('foo')' → '//scriptlet('foo')'
+     *
+     * @throws Error if the rule type is unknown
      */
     static generate(node: AnyCosmeticRule): string;
 }

package/dist/types/generator/cosmetic/cosmetic-rule-generator.d.ts

@@ -12,18 +12,10 @@ export declare const ERROR_MESSAGES: {
     SYNTAX_DISABLED: string;
 };
 /**
- * `CosmeticRuleParser` is responsible for parsing cosmetic rules.
+ * `CosmeticRuleGenerator` is responsible for generating cosmetic rules from their AST representation.
  *
- * Where possible, it automatically detects the difference between supported syntaxes:
- *  - AdGuard
- *  - uBlock Origin
- *  - Adblock Plus
- *
- * If the syntax is common / cannot be determined, the parser gives `Common` syntax.
- *
- * Please note that syntactically correct rules are parsed even if they are not actually
- * compatible with the given adblocker. This is a completely natural behavior, meaningful
- * checking of compatibility is not done at the parser level.
+ * This class takes a parsed cosmetic rule Abstract Syntax Tree (AST) and converts it back into a raw string format.
+ * It handles the generation of the pattern, separator, uBO rule modifiers, and the rule body.
  */
 export declare class CosmeticRuleGenerator extends BaseGenerator {
     /**

package/dist/types/generator/cosmetic/cosmetic-rule-pattern-generator.d.ts

@@ -1,5 +1,8 @@
 import type { AnyCosmeticRule } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Cosmetic rule pattern generator.
+ */
 export declare class CosmeticRulePatternGenerator extends BaseGenerator {
     /**
      * Generates the rule pattern from the AST.

package/dist/types/generator/css/adg-css-injection-generator.d.ts

@@ -1,5 +1,8 @@
 import type { CssInjectionRuleBody } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * AdGuard CSS injection generator.
+ */
 export declare class AdgCssInjectionGenerator extends BaseGenerator {
     private static removeDeclaration;
     /**

package/dist/types/generator/css/ubo-selector-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from '../base-generator';
 import { type UboSelector } from '../../nodes';
+/**
+ * UBO selector generator.
+ */
 export declare class UboSelectorGenerator extends BaseGenerator {
     /**
      * Serializes a uBO selector node to a string.

package/dist/types/generator/filterlist-generator.d.ts

@@ -1,8 +1,7 @@
 import { type FilterList } from '../nodes';
 import { BaseGenerator } from './base-generator';
 /**
- * `FilterListParser` is responsible for parsing a whole adblock filter list (list of rules).
- * It is a wrapper around `RuleParser` which parses each line separately.
+ * Generates a serialized filter list.
  */
 export declare class FilterListGenerator extends BaseGenerator {
     /**
@@ -11,7 +10,9 @@ export declare class FilterListGenerator extends BaseGenerator {
      * @param ast AST to generate
      * @param preferRaw If `true`, then the parser will use `raws.text` property of each rule
      * if it is available. Default is `false`.
+     * @param tolerant If `true`, errors during rule generation will be logged to the console and invalid rules
+     * will be skipped. If `false`, an error will be thrown on the first invalid rule. Default is `true`.
      * @returns Serialized filter list
      */
-    static generate(ast: FilterList, preferRaw?: boolean): string;
+    static generate(ast: FilterList, preferRaw?: boolean, tolerant?: boolean): string;
 }

package/dist/types/generator/misc/domain-list-generator.d.ts

@@ -1,5 +1,8 @@
 import type { DomainList } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Domain list generator.
+ */
 export declare class DomainListGenerator extends BaseGenerator {
     /**
      * Converts a domain list node to a string.

package/dist/types/generator/misc/list-items-generator.d.ts

@@ -1,4 +1,7 @@
 import { type ListItem, type ListItemNodeType } from '../../nodes';
+/**
+ * Utility class for generating string representations of list items.
+ */
 export declare class ListItemsGenerator {
     /**
      * Generates a string representation of a list item.

package/dist/types/generator/misc/logical-expression-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from '../base-generator';
 import { type AnyExpressionNode } from '../../nodes';
+/**
+ * Generator for logical expression nodes.
+ */
 export declare class LogicalExpressionGenerator extends BaseGenerator {
     /**
      * Generates a string representation of the logical expression (serialization).

package/dist/types/generator/misc/modifier-generator.d.ts

@@ -1,10 +1,13 @@
 import type { Modifier } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Generator for modifier nodes.
+ */
 export declare class ModifierGenerator extends BaseGenerator {
     /**
-     * Generates a string from a modifier (serializes it).
+     * Converts a modifier AST node to a string.
      *
-     * @param modifier Modifier to generate string from
+     * @param modifier Modifier AST node to convert
      * @returns String representation of the modifier
      */
     static generate(modifier: Modifier): string;

package/dist/types/generator/misc/modifier-list-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from '../base-generator';
 import type { ModifierList } from '../../nodes';
+/**
+ * Generator for modifier list nodes.
+ */
 export declare class ModifierListGenerator extends BaseGenerator {
     /**
      * Converts a modifier list AST to a string.

package/dist/types/generator/misc/parameter-list-generator.d.ts

@@ -1,5 +1,8 @@
 import type { ParameterList } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Generator for parameter list nodes.
+ */
 export declare class ParameterListGenerator extends BaseGenerator {
     /**
      * Converts a parameter list AST to a string.

package/dist/types/generator/misc/value-generator.d.ts

@@ -1,5 +1,8 @@
 import type { Value } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Generator for value nodes.
+ */
 export declare class ValueGenerator extends BaseGenerator {
     /**
      * Converts a value node to a string.

package/dist/types/generator/network/host-rule-generator.d.ts

@@ -1,5 +1,8 @@
 import type { HostRule } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Generator for host rule nodes.
+ */
 export declare class HostRuleGenerator extends BaseGenerator {
     /**
      * Converts a host rule node to a raw string.

package/dist/types/generator/network/network-rule-generator.d.ts

@@ -1,11 +1,14 @@
 import type { NetworkRule } from '../../nodes';
 import { BaseGenerator } from '../base-generator';
+/**
+ * Generator for network rule nodes.
+ */
 export declare class NetworkRuleGenerator extends BaseGenerator {
     /**
-     * Converts a network rule (basic rule) AST to a string.
+     * Generates a string from a network rule AST node.
      *
-     * @param node Network rule node
-     * @returns Raw string
+     * @param node Network rule node to generate a string from.
+     * @returns Generated string representation of the network rule.
      */
     static generate(node: NetworkRule): string;
 }

package/dist/types/generator/rule-generator.d.ts

@@ -1,5 +1,8 @@
 import { BaseGenerator } from './base-generator';
 import { type AnyRule } from '../nodes';
+/**
+ * RuleGenerator is responsible for converting adblock rule ASTs to their string representation.
+ */
 export declare class RuleGenerator extends BaseGenerator {
     /**
      * Converts a rule AST to a string.

package/dist/types/marshalling-utils/comment/agent-comment-common.d.ts

@@ -6,8 +6,9 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum AgentCommentMarshallingMap {
-    Children = 1,
-    Start = 2,
-    End = 3
-}
+export declare const AgentCommentMarshallingMap: {
+    readonly Children: 1;
+    readonly Start: 2;
+    readonly End: 3;
+};
+export type AgentCommentMarshallingMap = typeof AgentCommentMarshallingMap[keyof typeof AgentCommentMarshallingMap];

package/dist/types/marshalling-utils/comment/agent-common.d.ts

@@ -6,12 +6,13 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum AgentNodeMarshallingMap {
-    Adblock = 1,
-    Version = 2,
-    Start = 3,
-    End = 4
-}
+export declare const AgentNodeMarshallingMap: {
+    readonly Adblock: 1;
+    readonly Version: 2;
+    readonly Start: 3;
+    readonly End: 4;
+};
+export type AgentNodeMarshallingMap = typeof AgentNodeMarshallingMap[keyof typeof AgentNodeMarshallingMap];
 /**
  * Value map for binary deserialization. This helps to reduce the size of the serialized data,
  * as it allows us to use a single byte to represent frequently used values.

package/dist/types/marshalling-utils/comment/config-comment-common.d.ts

@@ -6,14 +6,15 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum ConfigCommentRuleMarshallingMap {
-    Marker = 1,
-    Command = 2,
-    Params = 3,
-    Comment = 4,
-    Start = 5,
-    End = 6
-}
+export declare const ConfigCommentRuleMarshallingMap: {
+    readonly Marker: 1;
+    readonly Command: 2;
+    readonly Params: 3;
+    readonly Comment: 4;
+    readonly Start: 5;
+    readonly End: 6;
+};
+export type ConfigCommentRuleMarshallingMap = typeof ConfigCommentRuleMarshallingMap[keyof typeof ConfigCommentRuleMarshallingMap];
 /**
  * Property 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 a property.
@@ -22,11 +23,12 @@ export declare const enum ConfigCommentRuleMarshallingMap {
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum ConfigNodeMarshallingMap {
-    Value = 1,
-    Start = 2,
-    End = 3
-}
+export declare const ConfigNodeMarshallingMap: {
+    readonly Value: 1;
+    readonly Start: 2;
+    readonly End: 3;
+};
+export type ConfigNodeMarshallingMap = typeof ConfigNodeMarshallingMap[keyof typeof ConfigNodeMarshallingMap];
 /**
  * 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.

package/dist/types/marshalling-utils/comment/hint-comment-common.d.ts

@@ -6,9 +6,10 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum HintCommentMarshallingMap {
-    Syntax = 1,
-    Children = 2,
-    Start = 3,
-    End = 4
-}
+export declare const HintCommentMarshallingMap: {
+    readonly Syntax: 1;
+    readonly Children: 2;
+    readonly Start: 3;
+    readonly End: 4;
+};
+export type HintCommentMarshallingMap = typeof HintCommentMarshallingMap[keyof typeof HintCommentMarshallingMap];

package/dist/types/marshalling-utils/comment/hint-common.d.ts

@@ -6,12 +6,13 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum HintNodeMarshallingMap {
-    Name = 1,
-    Params = 2,
-    Start = 3,
-    End = 4
-}
+export declare const HintNodeMarshallingMap: {
+    readonly Name: 1;
+    readonly Params: 2;
+    readonly Start: 3;
+    readonly End: 4;
+};
+export type HintNodeMarshallingMap = typeof HintNodeMarshallingMap[keyof typeof HintNodeMarshallingMap];
 /**
  * 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.

package/dist/types/marshalling-utils/comment/metadata-comment-common.d.ts

@@ -6,13 +6,14 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum MetadataCommentMarshallingMap {
-    Marker = 1,
-    Header = 2,
-    Value = 3,
-    Start = 4,
-    End = 5
-}
+export declare const MetadataCommentMarshallingMap: {
+    readonly Marker: 1;
+    readonly Header: 2;
+    readonly Value: 3;
+    readonly Start: 4;
+    readonly End: 5;
+};
+export type MetadataCommentMarshallingMap = typeof MetadataCommentMarshallingMap[keyof typeof MetadataCommentMarshallingMap];
 /**
  * Value map for binary deserialization. This helps to reduce the size of the serialized data,
  * as it allows us to use a single byte to represent frequently used values.

package/dist/types/marshalling-utils/comment/pre-processor-comment-common.d.ts

@@ -6,13 +6,14 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum PreProcessorRuleMarshallingMap {
-    Name = 1,
-    Params = 2,
-    Syntax = 3,
-    Start = 4,
-    End = 5
-}
+export declare const PreProcessorRuleMarshallingMap: {
+    readonly Name: 1;
+    readonly Params: 2;
+    readonly Syntax: 3;
+    readonly Start: 4;
+    readonly End: 5;
+};
+export type PreProcessorRuleMarshallingMap = typeof PreProcessorRuleMarshallingMap[keyof typeof PreProcessorRuleMarshallingMap];
 /**
  * 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.

package/dist/types/marshalling-utils/comment/simple-comment-common.d.ts

@@ -6,9 +6,10 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum SimpleCommentMarshallingMap {
-    Marker = 1,
-    Text = 2,
-    Start = 3,
-    End = 4
-}
+export declare const SimpleCommentMarshallingMap: {
+    readonly Marker: 1;
+    readonly Text: 2;
+    readonly Start: 3;
+    readonly End: 4;
+};
+export type SimpleCommentMarshallingMap = typeof SimpleCommentMarshallingMap[keyof typeof SimpleCommentMarshallingMap];

package/dist/types/marshalling-utils/cosmetic/body/abp-snippet-injection-body-common.d.ts

@@ -6,11 +6,12 @@
  *
  * @note Only 256 values can be represented this way.
  */
-export declare const enum AbpSnippetBodyMarshallingMap {
-    Children = 1,
-    Start = 2,
-    End = 3
-}
+export declare const AbpSnippetBodyMarshallingMap: {
+    readonly Children: 1;
+    readonly Start: 2;
+    readonly End: 3;
+};
+export type AbpSnippetBodyMarshallingMap = typeof AbpSnippetBodyMarshallingMap[keyof typeof AbpSnippetBodyMarshallingMap];
 /**
  * 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.