@adguard/agtree 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -2,14 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog][keepachangelog], and this project
-adheres to [Semantic Versioning][semver].
+The format is based on [Keep a Changelog][keepachangelog], and this project adheres to [Semantic Versioning][semver].
 
-[keepachangelog]: https://keepachangelog.com/en/1.0.0/
-[semver]: https://semver.org/spec/v2.0.0.html
+## 1.1.1 - 2023-08-11
+
+### Fixed
+
+- Validation of assignable modifiers which may be used without a value
 
-## [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
 
 - Migrated parser from AGLint to a separate package.
+
+[keepachangelog]: https://keepachangelog.com/en/1.0.0/
+[semver]: https://semver.org/spec/v2.0.0.html

package/README.md

@@ -1,76 +1,50 @@
+<!-- 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,259 +52,76 @@ 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
-      }
-    ]
-  }
-}
-```
-
-</details>
-
-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.
-
-And this code:
-
-```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');
+AGTree is a universal tool for working with adblock filter lists. It contains the following modules:
 
-// 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);
+- [Adblock rule converter][converter-url]
+- [Adblock rule parser][parser-url]
+- [Compatibility tables][compatibility-tables-url]
 
-// Generate filter list from filter list AST
-const easyListGenerated = FilterListParser.generate(ast);
+AGTree supports all syntaxes currently in use:
 
-// Write generated filter list to file
-await writeFile("easylist-generated.txt", easyListGenerated);
-```
+- <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]
 
 ## Development & Contribution
 
-Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to
-contribute to this project.
+Please read the [CONTRIBUTING.md][contributing-url] file for details on how to contribute to this project.
 
 ## 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.
 
 ## 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.
 
 ## 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.
+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-->
 
+[ab-url]: https://getadblock.com
 [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
 [abp-snippets]: https://help.eyeo.com/adblockplus/snippet-filters-tutorial#snippets-ref
+[abp-url]: https://adblockplus.org
 [adg-compatibility-table]: https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/compatibility-table.md
 [adg-ext-css]: https://github.com/AdguardTeam/ExtendedCss/blob/master/README.md
 [adg-filters]: https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters
 [adg-scriptlets]: https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/about-scriptlets.md#scriptlets
+[adg-url]: https://adguard.com
+[compatibility-tables-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/compatibility-tables
+[contributing-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/CONTRIBUTING.md
+[converter-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/converter
 [css-tree-docs]: https://github.com/csstree/csstree/tree/master/docs
+[discussions-url]: https://github.com/AdguardTeam/tsurlfilter/discussions
+[license-url]: https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/agtree/LICENSE
 [mdn-css-selectors]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
+[new-issue-url]: https://github.com/AdguardTeam/tsurlfilter/issues/new
+[parser-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/parser
 [ubo-filters]: https://github.com/gorhill/uBlock/wiki/Static-filter-syntax
 [ubo-procedural]: https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters
 [ubo-scriptlets]: https://github.com/gorhill/uBlock/wiki/Resources-Library#available-general-purpose-scriptlets
+[ubo-url]: https://github.com/gorhill/uBlock