Improve parser (#5)

* Rename UboHTML to UboHtml

* Remove static lengths

* Reorganization of some constants

* Consistent names, remove redundant JSDoc types

* Rename options to modifiers to keep consistency

* Make  available via public API

* Fix #6

* Consistent raw parameter

* Fix description

* Remove redundant config comment

.eslintrc

@@ -33,6 +33,8 @@
             {
                 "SwitchCase": 1
             }
-        ]
+        ],
+        "jsdoc/require-param-type": 0,
+        "jsdoc/require-returns-type": 0
     }
 }

README.md

@@ -47,7 +47,7 @@ will gives you this AST:
 {
     "category": "Cosmetic",
     "type": "ScriptletRule",
-    "syntax": "AdGuard",
+    "syntax": "Adg",
     "exception": false,
     "modifiers": [],
     "domains": [
@@ -99,7 +99,7 @@ example.com,~example.net#%#//scriptlet('prevent-setInterval', 'check', '!300')
 > *Please note that unnecessary spaces will disappear and CSS selectors will be regenerated according to uniform formatting*
 
 ```typescript
-import { RuleParser } from "aglint/parser";
+import { RuleParser } from "aglint";
 
 // General rules (ADG/uBO/ABP)
 console.log(RuleParser.generate(RuleParser.parse("##.ad")));

package.json

@@ -23,31 +23,21 @@
     },
     "homepage": "https://github.com/AdguardTeam/AGLint#readme",
     "type": "module",
-    "main": "dist/index.cjs",
-    "module": "dist/index.mjs",
-    "exports": {
-        ".": {
-            "import": "./dist/index.mjs",
-            "require": "./dist/index.cjs"
-        },
-        "./parser": {
-            "import": "./dist/parser/index.mjs",
-            "require": "./dist/parser/index.cjs"
-        }
-    },
-    "typings": "dist/types",
+    "main": "dist/aglint.cjs",
+    "module": "dist/aglint.mjs",
+    "types": "dist/aglint.d.ts",
     "files": [
         "dist",
         "src"
     ],
     "engines": {
-        "node": ">=12"
+        "node": ">=14"
     },
     "scripts": {
         "lint": "eslint . --ext .ts",
         "test": "jest --runInBand .",
         "coverage": "jest --coverage",
-        "build": "yarn rimraf dist && yarn rollup --config rollup.config.ts --configPlugin typescript && tsc --declaration --emitDeclarationOnly --outdir dist/types"
+        "build": "yarn rimraf dist && tsc --declaration --emitDeclarationOnly --outdir dist/types && yarn rollup --config rollup.config.ts --configPlugin typescript && yarn rimraf dist/types"
     },
     "devDependencies": {
         "@rollup/plugin-commonjs": "^23.0.2",

rollup.config.ts

@@ -2,29 +2,35 @@ import typescript from "@rollup/plugin-typescript";
 import resolve from "@rollup/plugin-node-resolve";
 import commonjs from "@rollup/plugin-commonjs";
 import externals from "rollup-plugin-node-externals";
+import dts from "rollup-plugin-dts";
 
 const esm = {
-    input: "src/parser/index.ts",
+    input: "./src/index.ts",
     output: [
         {
-            file: `dist/parser/index.mjs`,
+            file: `./dist/aglint.mjs`,
             format: "esm",
             sourcemap: false,
         },
     ],
     plugins: [
         externals(),
-        typescript({ declaration: false }),
+        typescript({
+            declaration: false,
+            compilerOptions: {
+                moduleResolution: "node16",
+            },
+        }),
         commonjs({ sourceMap: false }),
         resolve({ preferBuiltins: false }),
     ],
 };
 
 const cjs = {
-    input: "src/parser/index.ts",
+    input: "./src/index.ts",
     output: [
         {
-            file: `dist/parser/index.cjs`,
+            file: `./dist/aglint.cjs`,
             format: "cjs",
             exports: "auto",
             sourcemap: false,
@@ -38,4 +44,12 @@ const cjs = {
     ],
 };
 
-export default [esm, cjs];
+export default [
+    esm,
+    cjs,
+    {
+        input: "./dist/types/index.d.ts",
+        output: [{ file: "dist/aglint.d.ts", format: "es" }],
+        plugins: [dts()],
+    },
+];

src/parser/comment/agent.ts

@@ -1,8 +1,8 @@
 import { AdblockSyntax } from "../../utils/adblockers";
 import { SPACE } from "../../utils/constants";
 import { StringUtils } from "../../utils/string";
-import { RuleCategories } from "../common";
-import { CommentMarker, CommentRuleType, IComment } from "./common";
+import { RuleCategory } from "../common";
+import { CommentMarker, CommentRuleType, Comment } from "./common";
 
 const AGENT_LIST_OPEN = "[";
 const AGENT_LIST_CLOSE = "]";
@@ -12,7 +12,7 @@ const AGENT_SEPARATOR = ";";
  * Represents an agent (eg `Adblock Plus 2.0`, where adblock is `Adblock Plus` and version is `2.0`).
  * Specifying the version is optional.
  */
-export interface IAgentMember {
+export interface AgentMember {
     adblock: string;
     version?: string;
 }
@@ -34,9 +34,9 @@ export interface IAgentMember {
  *    [uBlock Origin]
  *    ```
  */
-export interface IAgent extends IComment {
+export interface Agent extends Comment {
     type: CommentRuleType.Agent;
-    agents: IAgentMember[];
+    agents: AgentMember[];
 }
 
 /**
@@ -59,8 +59,8 @@ export class AgentParser {
     /**
      * Determines whether a rule is an adblock agent.
      *
-     * @param {string} raw - Raw rule
-     * @returns {boolean} true/false
+     * @param raw - Raw rule
+     * @returns true/false
      */
     public static isAgent(raw: string): boolean {
         const trimmed = raw.trim();
@@ -77,15 +77,15 @@ export class AgentParser {
     /**
      * Parses an adblock agent member.
      *
-     * @param {string} raw - Raw agent member, eg `Adblock Plus 2.0`
-     * @returns {IAgentMember} - Agent member AST
+     * @param raw - Raw agent member, eg `Adblock Plus 2.0`
+     * @returns - Agent member AST
      * @example
      * ```js
      * AgentParser.parseAgent('Adblock Plus 2.0');
      * AgentParser.parseAgent('uBlock Origin 1.40.1');
      * ```
      */
-    private static parseAgent(raw: string): IAgentMember {
+    private static parseAgent(raw: string): AgentMember {
         const trimmed = raw.trim();
         const splitted = trimmed.split(SPACE);
 
@@ -112,10 +112,10 @@ export class AgentParser {
     /**
      * Parses a raw rule as an adblock agent comment.
      *
-     * @param {string} raw - Raw rule
-     * @returns {IAgent | null} Adblock agent AST or null (if the raw rule cannot be parsed as an adblock agent comment)
+     * @param raw - Raw rule
+     * @returns Adblock agent AST or null (if the raw rule cannot be parsed as an adblock agent comment)
      */
-    public static parse(raw: string): IAgent | null {
+    public static parse(raw: string): Agent | null {
         const trimmed = raw.trim();
 
         // Check basic adblock agents pattern: [...], ![...], ! [...], #[...], etc.
@@ -141,7 +141,7 @@ export class AgentParser {
 
         // Parse content between brackets
         if (openingBracketIndex != -1) {
-            const collectedAgents: IAgentMember[] = [];
+            const collectedAgents: AgentMember[] = [];
             const rawAgents = trimmed.slice(openingBracketIndex + 1, -1);
             const agents = rawAgents.split(AGENT_SEPARATOR);
             for (const agent of agents) {
@@ -155,7 +155,7 @@ export class AgentParser {
             }
 
             return {
-                category: RuleCategories.Comment,
+                category: RuleCategory.Comment,
                 type: CommentRuleType.Agent,
                 syntax: AdblockSyntax.Unknown,
                 agents: collectedAgents,
@@ -168,10 +168,10 @@ export class AgentParser {
     /**
      * Converts an adblock agent AST to a string.
      *
-     * @param {IAgent} ast - Agent AST
-     * @returns {string} Raw string
+     * @param ast - Agent AST
+     * @returns Raw string
      */
-    public static generate(ast: IAgent): string {
+    public static generate(ast: Agent): string {
         let result = AGENT_LIST_OPEN;
 
         result += ast.agents

src/parser/comment/comment.ts

@@ -1,13 +1,13 @@
 import { StringUtils } from "../../utils/string";
 import { CosmeticRuleSeparatorUtils } from "../../utils/cosmetic-rule-separator";
-import { CommentMarker, CommentRuleType, IComment } from "./common";
-import { AgentParser, IAgent } from "./agent";
-import { HintParser, IHint } from "./hint";
-import { IMetadata, MetadataParser } from "./metadata";
-import { IPreProcessor, PreProcessorParser } from "./preprocessor";
-import { RuleCategories } from "../common";
+import { CommentMarker, CommentRuleType, Comment } from "./common";
+import { AgentParser, Agent } from "./agent";
+import { HintParser, Hint } from "./hint";
+import { Metadata, MetadataParser } from "./metadata";
+import { PreProcessor, PreProcessorParser } from "./preprocessor";
+import { RuleCategory } from "../common";
 import { AdblockSyntax } from "../../utils/adblockers";
-import { ConfigCommentParser, IConfigComment } from "./inline-config";
+import { ConfigCommentParser, ConfigComment } from "./inline-config";
 
 /**
  * Represents a simple comment.
@@ -21,7 +21,7 @@ import { ConfigCommentParser, IConfigComment } from "./inline-config";
  *     ```
  *   - etc.
  */
-export interface ISimpleComment extends IComment {
+export interface SimpleComment extends Comment {
     type: CommentRuleType.Comment;
 
     /** Comment marker: `!` or `#` */
@@ -86,8 +86,8 @@ export class CommentParser {
     /**
      * Determines whether a rule is a regular comment.
      *
-     * @param {string} raw - Raw data
-     * @returns {boolean} true/false
+     * @param raw - Raw data
+     * @returns true/false
      */
     public static isRegularComment(raw: string): boolean {
         return raw.trim()[0] == CommentMarker.Regular;
@@ -96,8 +96,8 @@ export class CommentParser {
     /**
      * Determines whether a rule is a comment.
      *
-     * @param {string} raw - Raw rule
-     * @returns {boolean} true/false
+     * @param raw - Raw rule
+     * @returns true/false
      */
     public static isComment(raw: string): boolean {
         const trimmed = raw.trim();
@@ -133,10 +133,10 @@ export class CommentParser {
     /**
      * Parses a raw rule as comment.
      *
-     * @param {string} raw - Raw rule
-     * @returns {IComment | null} Comment AST or null (if the raw rule cannot be parsed as comment)
+     * @param raw - Raw rule
+     * @returns Comment AST or null (if the raw rule cannot be parsed as comment)
      */
-    public static parse(raw: string): IComment | null {
+    public static parse(raw: string): Comment | null {
         const trimmed = raw.trim();
 
         if (!CommentParser.isComment(trimmed)) {
@@ -149,8 +149,8 @@ export class CommentParser {
             PreProcessorParser.parse(trimmed) ||
             MetadataParser.parse(trimmed) ||
             ConfigCommentParser.parse(trimmed) ||
-            <IComment>{
-                category: RuleCategories.Comment,
+            <Comment>{
+                category: RuleCategory.Comment,
                 type: CommentRuleType.Comment,
                 syntax: AdblockSyntax.Unknown,
                 marker: trimmed[0],
@@ -162,23 +162,23 @@ export class CommentParser {
     /**
      * Converts a comment AST to a string.
      *
-     * @param {IComment} ast - Comment AST
-     * @returns {string} Raw string
+     * @param ast - Comment AST
+     * @returns Raw string
      */
-    public static generate(ast: IComment): string {
+    public static generate(ast: Comment): string {
         switch (ast.type) {
             case CommentRuleType.Agent:
-                return AgentParser.generate(<IAgent>ast);
+                return AgentParser.generate(<Agent>ast);
             case CommentRuleType.Hint:
-                return HintParser.generate(<IHint>ast);
+                return HintParser.generate(<Hint>ast);
             case CommentRuleType.PreProcessor:
-                return PreProcessorParser.generate(<IPreProcessor>ast);
+                return PreProcessorParser.generate(<PreProcessor>ast);
             case CommentRuleType.Metadata:
-                return MetadataParser.generate(<IMetadata>ast);
+                return MetadataParser.generate(<Metadata>ast);
             case CommentRuleType.ConfigComment:
-                return ConfigCommentParser.generate(<IConfigComment>ast);
+                return ConfigCommentParser.generate(<ConfigComment>ast);
             case CommentRuleType.Comment:
-                return (<ISimpleComment>ast).marker + (<ISimpleComment>ast).text;
+                return (<SimpleComment>ast).marker + (<SimpleComment>ast).text;
         }
     }
 }