@adguard/agtree 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -8,7 +8,33 @@ adheres to [Semantic Versioning][semver].
 [keepachangelog]: https://keepachangelog.com/en/1.0.0/
 [semver]: https://semver.org/spec/v2.0.0.html
 
-## [Unreleased]
+## [1.1.0] - 2023-08-10
+
+### Added
+
+- Compatibility tables for modifiers
+- Validator for modifiers
+- Basic rule converter
+- New utils (regex, quotes)
+
+### Changed
+
+- Updated dependencies
+- Improved library build
+- Improved CSSTree utils
+- Export CSSTree utils
+- Store raw data while parsing
+- General code improvements
+
+### Fixed
+
+- Package metadata
+- Type import/export
+- Modifier list parsing
+- Scriptlet parsing
+- Metadata parsing
+
+## [1.0.1] - 2023-05-24
 
 ### Added
 

package/README.md

@@ -1,76 +1,72 @@
+<!-- markdownlint-disable -->
+
 &nbsp;
 
 <p align="center">
-  <picture>
-    <source
-      media="(prefers-color-scheme: dark)"
-      srcset="
-        https://cdn.adtidy.org/website/github.com/AGTree/agtree_darkmode.svg
-      "
-    />
-    <img
-      alt="AGTree"
-      src="https://cdn.adtidy.org/website/github.com/AGTree/agtree_lightmode.svg"
-      width="350px"
-    />
-  </picture>
+    <picture>
+        <source
+            media="(prefers-color-scheme: dark)"
+            srcset="https://cdn.adtidy.org/website/github.com/AGTree/agtree_darkmode.svg"
+        />
+        <img
+            alt="AGTree"
+            src="https://cdn.adtidy.org/website/github.com/AGTree/agtree_lightmode.svg"
+            width="350px"
+        />
+    </picture>
 </p>
 <h3 align="center">Universal adblock filter list parser</h3>
 <p align="center">Supported syntaxes:</p>
 <p align="center">
-  <a href="https://adguard.com"
-    ><img
-      src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg"
-      width="14px"
-    />
-    AdGuard</a
-  >
-  |
-  <a href="https://github.com/gorhill/uBlock"
-    ><img
-      src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg"
-      width="14px"
-    />
-    uBlock Origin</a
-  >
-  |
-  <a href="https://getadblock.com"
-    ><img
-      src="https://cdn.adguard.com/website/github.com/AGLint/ab_logo.svg"
-      width="14px"
-    />
-    AdBlock</a
-  >
-  |
-  <a href="https://adblockplus.org"
-    ><img
-      src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg"
-      width="14px"
-    />
-    Adblock Plus</a
-  >
+    <a href="https://adguard.com">
+        <img
+            src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg"
+            width="14px"
+        />
+        AdGuard
+    </a>
+    |
+    <a href="https://github.com/gorhill/uBlock">
+        <img
+            src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg"
+            width="14px"
+        />
+        uBlock Origin
+    </a>
+    |
+    <a href="https://getadblock.com">
+        <img
+            src="https://cdn.adguard.com/website/github.com/AGLint/ab_logo.svg"
+            width="14px"
+        />
+        AdBlock
+    </a>
+    |
+    <a href="https://adblockplus.org">
+        <img
+            src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg"
+            width="14px"
+        />
+        Adblock Plus
+    </a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@adguard/agtree"
-    ><img src="https://img.shields.io/npm/v/@adguard/agtree" alt="NPM version"
-  /></a>
-  <a href="https://www.npmjs.com/package/@adguard/agtree"
-    ><img
-      src="https://img.shields.io/npm/dm/@adguard/agtree"
-      alt="NPM Downloads"
-  /></a>
-  <a href="https://github.com/AdguardTeam/AGTree/blob/master/LICENSE"
-    ><img src="https://img.shields.io/npm/l/@adguard/agtree" alt="License"
-  /></a>
+    <a href="https://www.npmjs.com/package/@adguard/agtree">
+        <img src="https://img.shields.io/npm/v/@adguard/agtree" alt="NPM version" />
+    </a>
+    <a href="https://www.npmjs.com/package/@adguard/agtree">
+        <img src="https://img.shields.io/npm/dm/@adguard/agtree" alt="NPM Downloads" />
+    </a>
+    <a href="https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/agtree/LICENSE">
+        <img src="https://img.shields.io/npm/l/@adguard/agtree" alt="License" />
+    </a>
 </p>
+<!-- markdownlint-restore -->
 
 Table of Contents:
 
 - [Introduction](#introduction)
-- [Usage](#usage)
-  - [Parsing rules](#parsing-rules)
-  - [Parsing filter lists](#parsing-filter-lists)
 - [Development \& Contribution](#development--contribution)
 - [Ideas \& Questions](#ideas--questions)
 - [License](#license)
@@ -78,249 +74,74 @@ Table of Contents:
 
 ## Introduction
 
-AGTree is a universal adblock filter list parser. It supports all syntaxes
-currently in use: AdGuard, uBlock Origin and AdBlock / Adblock Plus.
-
-## Usage
-
-AGTree provides a powerful, error-tolerant parser for all kinds of ad blocking
-rules. It fully supports AdGuard, uBlock Origin and Adblock Plus syntaxes, and
-provides a high-detail AST for all rules.
-
-Basically, the parser API has two main parts:
-
-- Parser: parsing rules (string &#8594; AST)
-- Generator: serialization of ASTs (AST &#8594; string)
-
-### Parsing rules
-
-You can parse individual rules using the `RuleParser` class. It has a `parse`
-method that takes a rule string and returns an AST. For example, this code:
-
-```typescript
-import { RuleParser } from "@adguard/agtree";
-
-// RuleParser automatically determines the rule type
-const ast = RuleParser.parse("/ads.js^$script");
-```
-
-will gives you this AST:
-
-```json
-{
-  "type": "NetworkRule",
-  "category": "Network",
-  "syntax": "Common",
-  "exception": false,
-  "pattern": {
-    "type": "Value",
-    "value": "/ads.js^"
-  },
-  "modifiers": {
-    "type": "ModifierList",
-    "children": [
-      {
-        "type": "Modifier",
-        "modifier": {
-          "type": "Value",
-          "value": "script"
-        },
-        "exception": false
-      }
-    ]
-  }
-}
-```
-
-<details>
-
-<summary>Show full AST (with locations)</summary>
-
-```json
-{
-  "type": "NetworkRule",
-  "loc": {
-    "start": {
-      "offset": 0,
-      "line": 1,
-      "column": 1
-    },
-    "end": {
-      "offset": 15,
-      "line": 1,
-      "column": 16
-    }
-  },
-  "raws": {
-    "text": "/ads.js^$script"
-  },
-  "category": "Network",
-  "syntax": "Common",
-  "exception": false,
-  "pattern": {
-    "type": "Value",
-    "loc": {
-      "start": {
-        "offset": 0,
-        "line": 1,
-        "column": 1
-      },
-      "end": {
-        "offset": 8,
-        "line": 1,
-        "column": 9
-      }
-    },
-    "value": "/ads.js^"
-  },
-  "modifiers": {
-    "type": "ModifierList",
-    "loc": {
-      "start": {
-        "offset": 9,
-        "line": 1,
-        "column": 10
-      },
-      "end": {
-        "offset": 15,
-        "line": 1,
-        "column": 16
-      }
-    },
-    "children": [
-      {
-        "type": "Modifier",
-        "loc": {
-          "start": {
-            "offset": 9,
-            "line": 1,
-            "column": 10
-          },
-          "end": {
-            "offset": 15,
-            "line": 1,
-            "column": 16
-          }
-        },
-        "modifier": {
-          "type": "Value",
-          "loc": {
-            "start": {
-              "offset": 9,
-              "line": 1,
-              "column": 10
-            },
-            "end": {
-              "offset": 15,
-              "line": 1,
-              "column": 16
-            }
-          },
-          "value": "script"
-        },
-        "exception": false
-      }
-    ]
-  }
-}
-```
+AGTree is a universal tool for working with adblock filter lists. It contains
+the following modules:
 
-</details>
+- [Adblock rule converter][converter-url]
+- [Adblock rule parser][parser-url]
+- [Compatibility tables][compatibility-tables-url]
 
-As you can see, this AST is very detailed and contains all the information about
-the rule: syntax, category, exception, modifiers, node locations, and so on.
-Locations are especially useful for linters, since they allow you to point to
-the exact place in the rule where the error occurred.
+AGTree supports all syntaxes currently in use:
 
-And this code:
+- <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px"> [AdGuard][adg-url]
+- <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px"> [uBlock Origin][ubo-url]
+- <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px"> [Adblock Plus][abp-url]
+- <img src="https://cdn.adguard.com/website/github.com/AGLint/ab_logo.svg" width="14px"> [AdBlock][ab-url]
 
-```typescript
-RuleParser.generate(ast);
-```
-
-will generate the adblock rule from the AST (serialization):
-
-```adblock
-/ads.js^$script
-```
-
-Please keep in mind that the parser omits unnecessary whitespaces, so the
-generated rule may not match with the original rule character by character.
-Only the formatting can change, the rule itself remains the same. You can
-pass any rule to the parser, it automatically determines the type and category
-of the rule. If the rule is syntactically incorrect, the parser will throw an
-error.
-
-### Parsing filter lists
-
-You can also parse complete filter lists using the `FilterListParser` class.
-It works the same way as the `RuleParser` class. Here is an example of parsing
-[EasyList](https://easylist.to/easylist/easylist.txt) and generating it back:
-
-```typescript
-import { FilterListParser } from "@adguard/agtree";
-import { writeFile } from "fs/promises";
-// Requires installing "node-fetch" package
-import fetch from "node-fetch";
-
-// Download EasyList
-const easyList = await (
-  await fetch("https://easylist.to/easylist/easylist.txt")
-).text();
-
-// Or read it from file
-// const easyList = await readFile('easylist.txt', 'utf-8');
-
-// Parse EasyList to AST. By default, parser is very tolerant,
-// if it can't parse some rules, it will just mark them as "raw".
-// If you want to disable this behavior, you can pass the second
-// argument as "false" to the "parse" method, like this:
-// const ast = FilterListParser.parse(easyList, false);
-const ast = FilterListParser.parse(easyList);
-
-// Generate filter list from filter list AST
-const easyListGenerated = FilterListParser.generate(ast);
-
-// Write generated filter list to file
-await writeFile("easylist-generated.txt", easyListGenerated);
-```
+[ab-url]: https://getadblock.com
+[abp-url]: https://adblockplus.org
+[adg-url]: https://adguard.com
+[compatibility-tables-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/compatibility-tables
+[converter-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/converter
+[parser-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/parser
+[ubo-url]: https://github.com/gorhill/uBlock
 
 ## Development & Contribution
 
-Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to
+Please read the [CONTRIBUTING.md][contributing-url] file for details on how to
 contribute to this project.
 
+[contributing-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/CONTRIBUTING.md
+
 ## Ideas & Questions
 
-If you have any questions or ideas for new features, please open an issue or a
-discussion. We will be happy to discuss it with you.
+If you have any questions or ideas for new features, please
+[open an issue][new-issue-url] or a [discussion][discussions-url]. We will be
+happy to discuss it with you.
+
+[discussions-url]: https://github.com/AdguardTeam/tsurlfilter/discussions
+[new-issue-url]: https://github.com/AdguardTeam/tsurlfilter/issues/new
 
 ## License
 
-AGTree is licensed under the MIT License. See the [LICENSE](LICENSE) file for
-details.
+AGTree is licensed under the MIT License. See the [LICENSE][license-url] file
+for details.
+
+[license-url]: https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/agtree/LICENSE
 
 ## References
 
 Here are some useful links to help you write adblock rules. This list is not
 exhaustive, so if you know any other useful resources, please let us know.
 
+<!--markdownlint-disable MD013-->
 - Syntax documentation:
-  - [AdGuard: _How to create your own ad filters_][adg-filters]
-  - [uBlock Origin: _Static filter syntax_][ubo-filters]
-  - [Adblock Plus: _How to write filters_][abp-filters]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px"> [AdGuard: *How to create your own ad filters*][adg-filters]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px"> [uBlock Origin: *Static filter syntax*][ubo-filters]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px"> [Adblock Plus: *How to write filters*][abp-filters]
 - Extended CSS documentation:
-  - [MDN: _CSS selectors_][mdn-css-selectors]
-  - [AdGuard: _Extended CSS capabilities_][adg-ext-css]
-  - [uBlock Origin: _Procedural cosmetic filters_][ubo-procedural]
-  - [Adblock Plus: _Extended CSS selectors_][abp-ext-css]
+    - [MDN: *CSS selectors*][mdn-css-selectors]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px"> [AdGuard: *Extended CSS capabilities*][adg-ext-css]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px"> [uBlock Origin: *Procedural cosmetic filters*][ubo-procedural]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px"> [Adblock Plus: *Extended CSS selectors*][abp-ext-css]
 - Scriptlets:
-  - [AdGuard scriptlets][adg-scriptlets]
-  - [uBlock Origin scriptlets][ubo-scriptlets]
-  - [Adblock Plus snippets][abp-snippets]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px"> [AdGuard scriptlets][adg-scriptlets]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px"> [uBlock Origin scriptlets][ubo-scriptlets]
+    - <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px"> [Adblock Plus snippets][abp-snippets]
 - Third party libraries:
-  - [CSSTree docs][css-tree-docs]
-- [AdGuard's compatibility table][adg-compatibility-table]
+    - <img src="https://raw.githubusercontent.com/csstree/csstree/master/assets/csstree-logo-rounded.svg" width="14px"> [CSSTree docs][css-tree-docs]
+- <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px"> [AdGuard's compatibility table][adg-compatibility-table]
+<!--markdownlint-enable MD013-->
 
 [abp-ext-css]: https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide-emulation
 [abp-filters]: https://help.eyeo.com/adblockplus/how-to-write-filters