AG-17246 fix code style to conform to guidelines

Merge in ADGUARD-FILTERS/scriptlets from fix/AG-17246 to release/v1.8

Squashed commit of the following:

commit 62ebaba
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Mon Jan 9 21:20:40 2023 +0300

    remove dashes after param docs

commit 3e1ea2d
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Mon Jan 9 21:18:22 2023 +0300

    swap wildcard to 'any' for param types

commit 9edacb0
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Dec 30 14:52:40 2022 +0300

    config and apply check-types

commit 8a17e2d
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Dec 30 14:10:50 2022 +0300

    remove unsupported import syntax

commit c49ebf4
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Dec 29 20:51:12 2022 +0300

    enable rules for helpers p2

commit 279c589
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Dec 29 20:18:20 2022 +0300

    enable rules for helpers p1

commit 6e3f5de
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Dec 29 17:04:06 2022 +0300

    split overrides into separate eslint configs

commit bbffe49
Merge: 8717f33 0aeb1d5
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Dec 29 16:34:42 2022 +0300

    merge master

commit 8717f33
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 20:39:28 2022 +0300

    use rules for helpers

commit 026785f
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 20:03:59 2022 +0300

    fix tag-lines p2

commit 9a4aa4d
Merge: 048e32c 89185d3
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 18:48:44 2022 +0300

    merge release/v1.8

commit 048e32c
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 15:09:30 2022 +0300

    enable jsdoc/require-property-description

commit c3d3d5d
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 14:39:00 2022 +0300

    enable jsdoc/tag-lines

commit fe47c15
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 14:14:21 2022 +0300

    enable jsdoc/require-returns

commit f5d898e
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 13:33:58 2022 +0300

    enable jsdoc/newline-after-description

commit 034db74
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Dec 28 12:59:12 2022 +0300

    enable jsdoc/check-tag-names

commit 286558e
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Tue Dec 27 21:11:37 2022 +0300

    enable jsdoc/require-param-type

commit b34878a
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Tue Dec 27 20:59:30 2022 +0300

    enable jsdoc/check-alignment

commit fe20657
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Tue Dec 27 20:56:32 2022 +0300

    enable jsdoc/check-types

commit 4908c90
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Tue Dec 27 20:48:19 2022 +0300

    enable jsdoc/check-param-names

... and 4 more commits

.eslintrc.js

@@ -0,0 +1,48 @@
+module.exports = {
+    extends: [
+        'airbnb-base',
+        'plugin:jsdoc/recommended',
+    ],
+    parser: '@babel/eslint-parser',
+    parserOptions: {
+        babelOptions: {
+            rootMode: 'upward',
+        },
+    },
+    env: {
+        browser: true,
+        qunit: true,
+    },
+    rules: {
+        'max-len': [
+            'error',
+            {
+                code: 120,
+                ignoreUrls: true,
+            },
+        ],
+        indent: ['error', 4, { SwitchCase: 1 }],
+        'no-param-reassign': 0,
+        'no-shadow': 0,
+        'import/prefer-default-export': 0,
+        'arrow-body-style': 0,
+        'import/no-extraneous-dependencies': 0,
+        'no-await-in-loop': 0,
+        'no-restricted-syntax': 0,
+        // jsdoc rules
+        'jsdoc/check-tag-names': ['error', { definedTags: ['scriptlet', 'trustedScriptlet', 'redirect'] }],
+        'jsdoc/require-jsdoc': 0,
+        'jsdoc/require-param': 0,
+        'jsdoc/valid-types': 0,
+        'jsdoc/no-undefined-types': 0,
+        'jsdoc/require-param-description': 0,
+        'jsdoc/require-returns-description': 0,
+    },
+    settings: {
+        jsdoc: {
+            preferredTypes: {
+                object: 'Object',
+            },
+        },
+    },
+};

package.json

@@ -69,6 +69,7 @@
         "eslint-config-airbnb-base": "^14.2.1",
         "eslint-plugin-compat": "^3.9.0",
         "eslint-plugin-import": "^2.22.1",
+        "eslint-plugin-jsdoc": "^39.6.4",
         "fs-extra": "^10.0.1",
         "husky": "~8.0.2",
         "js-reporters": "^2.1.0",

scripts/build-compatibility-table.js

@@ -21,15 +21,15 @@ const WIKI_COMPATIBILITY_TABLE_PATH = path.resolve(
 
 /**
  * @typedef {Object} CompatibilityItem
- * @property {string} adg
- * @property {string} abp
- * @property {string} ubo
+ * @property {string} adg AdGuard name
+ * @property {string} abp Adblock Plus name
+ * @property {string} ubo uBlock name
  */
 
 /**
  * @typedef {Object} CompatibilityData
- * @property {CompatibilityItem[]} scriptlets
- * @property {CompatibilityItem[]} redirects
+ * @property {CompatibilityItem[]} scriptlets list of scriptlets compatibility items
+ * @property {CompatibilityItem[]} redirects list of redirects compatibility items
  */
 
 /**
@@ -50,7 +50,6 @@ const getTableData = () => {
  * @param {string} item.adg AdGuard name
  * @param {string} item.abp Adblock Plus name
  * @param {string} item.ubo uBlock name
- *
  * @returns {string} markdown table row
  */
 const getRow = (id, { adg, abp, ubo }) => {
@@ -77,10 +76,10 @@ const getTableHeader = () => {
 
 /**
  * Builds markdown string of scriptlets/redirect compatibility table
+ *
  * @param {string} title title for scriptlets or redirects
  * @param {CompatibilityItem[]} data array of scriptlets or redirects compatibility data items
  * @param {'scriptlets'|'redirects'} id
- *
  * @returns {string} scriptlets or redirects compatibility table
  */
 const buildTable = (title, data = [], id = '') => {

scripts/build-corelibs.js

@@ -7,7 +7,8 @@ import { version } from '../package.json';
 import { writeFile } from './helpers';
 
 const buildCorelibsJson = async () => {
-    const { getScriptletFunction } = require('../tmp/scriptlets-func'); // eslint-disable-line import/no-unresolved,global-require
+    // eslint-disable-next-line import/no-unresolved,global-require
+    const { getScriptletFunction } = require('../tmp/scriptlets-func');
 
     const scriptlets = await Promise.all(Object
         .values(scriptletList)

scripts/build-docs.js

@@ -46,8 +46,9 @@ const aboutTrustedScriptletsPath = path.resolve(
 );
 
 /**
- * Collects required comments from files and
- * returns describing object for scriptlets and redirects
+ * Collects required comments from files
+ *
+ * @returns {Object} describing object for scriptlets and redirects
  */
 const manageDataFromFiles = () => {
     const dataFromScriptletsFiles = getDataFromFiles(
@@ -95,7 +96,6 @@ const manageDataFromFiles = () => {
  * Generates markdown list and describing text.
  *
  * @param {DescribingCommentData[]} dataItems array of comment data objects
- *
  * @returns {MarkdownData}
  */
 const getMarkdownData = (dataItems) => {

scripts/build-funcs.js

@@ -23,6 +23,8 @@ import { writeFile } from './helpers';
 /**
  * Method creates string for file with scriptlets functions,
  * where dependencies are placed inside scriptlet functions
+ *
+ * @returns {string}
  */
 const getScriptletFunctionsString = () => {
     function wrapInFunc(name, code) {
@@ -31,7 +33,8 @@ const getScriptletFunctionsString = () => {
 
     // we require scriptlets list dynamically, because scriptletsList file can be not built in the
     // moment of this script execution
-    const scriptletsList = require('../tmp/scriptlets-list'); // eslint-disable-line global-require, import/no-unresolved
+    // eslint-disable-next-line import/no-unresolved,global-require
+    const scriptletsList = require('../tmp/scriptlets-list');
 
     const scriptletsFunctions = Object.values(scriptletsList);
 

scripts/build-redirects.js

@@ -143,7 +143,9 @@ const getJsRedirects = async (options = {}) => {
     // TODO: seems like duplicate of already existed code
     /**
      * Returns first line of describing comment from redirect resource file
+     *
      * @param {string} rrName redirect resource name
+     * @returns {string|undefined}
      */
     const getComment = (rrName) => {
         const { description } = redirectsDescriptions.find((rr) => rr.name === rrName);
@@ -197,7 +199,7 @@ export const getPreparedRedirects = async (options) => {
 /**
  * Copies non-static redirects sources to dist
  *
- * @param redirectsData
+ * @param {object[]} redirectsData
  */
 const buildJsRedirectFiles = async (redirectsData) => {
     const saveRedirectData = async (redirect) => {
@@ -212,7 +214,7 @@ const buildJsRedirectFiles = async (redirectsData) => {
 /**
  * Prepares static redirects sources to dist
  *
- * @param redirectsData
+ * @param {object[]} redirectsData
  */
 const buildStaticRedirectFiles = async (redirectsData) => {
     const prepareRedirectData = async (redirect) => {

scripts/build-tests.js

@@ -14,9 +14,11 @@ const TEST_FILE_NAME_MARKER = '.test.js';
 
 /**
  * Prepares rollup config for test file
+ *
  * @param {string} fileName test file name
  * @param {string} dirPath resolved directory path
  * @param {string} subDir subdirectory with test files
+ * @returns {Object} rollup config
  */
 const getTestConfig = (fileName, dirPath, subDir) => {
     if (!fs.existsSync(TESTS_DIST)) {

scripts/check-sources-updates.js

@@ -14,8 +14,10 @@ const {
 
 /**
  * Checks if arrays contain the same strings
+ *
  * @param {Array} arr1
  * @param {Array} arr2
+ * @returns {boolean}
  */
 const areArraysOfStringsEqual = (arr1, arr2) => {
     if (arr1.length !== arr2.length) {
@@ -30,6 +32,8 @@ const areArraysOfStringsEqual = (arr1, arr2) => {
 
 /**
  * Returns parsed compatibility table
+ *
+ * @returns {Object}
  */
 const getCompatibilityTable = () => {
     const rawData = fs.readFileSync(COMPATIBILITY_TABLE_DATA_PATH);
@@ -39,7 +43,9 @@ const getCompatibilityTable = () => {
 
 /**
  * Returns list of scriptlets listed in table for specified platform
+ *
  * @param {"ubo"|"abp"} platform
+ * @returns {string[]}
  */
 const getScriptletsFromTable = (platform) => {
     const { scriptlets } = getCompatibilityTable();
@@ -48,22 +54,32 @@ const getScriptletsFromTable = (platform) => {
 
 /**
  * Returns list of redirects listed in table for specified platform
+ *
  * @param {"ubo"|"abp"} platform
+ * @returns {string[]}
  */
 const getRedirectsFromTable = (platform) => {
     const { redirects } = getCompatibilityTable();
     return redirects.map((item) => item[platform]).filter((item) => !!item);
 };
 
+/**
+ * @typedef {Object} Diff
+ * @property {string[]} added added content
+ * @property {string[]} removed removed content
+ */
+
 /**
  * Finds a difference between old and new array
+ *
  * @param {Array} oldList
  * @param {Array} newList
+ * @returns {Diff|null}
  */
 const getDiff = (oldList, newList) => {
     const diff = {
-        removed: [],
         added: [],
+        removed: [],
     };
 
     diff.removed = oldList.filter((item) => (
@@ -77,6 +93,7 @@ const getDiff = (oldList, newList) => {
 
 /**
  * Marks removed rules with (removed) and adds new rules to the end of the table
+ *
  * @param {{removed: Array, added: Array}} diff Object with diffs for certain type and platform
  * @param {"scriptlets"|"redirects"} ruleType
  * @param {"ubo"|"abp"} platform

scripts/helpers.js

@@ -21,6 +21,7 @@ const writeFile = async (filePath, content) => {
 
 /**
  * Gets list of `.js` files in directory
+ *
  * @param {string} relativeDirPath relative path to directory
  * @returns {string[]} array of file names
  */
@@ -43,7 +44,6 @@ const getFilesList = (relativeDirPath) => {
  * In one file might be comments describing scriptlet and redirect as well.
  *
  * @param {string} filePath absolute path to file
- *
  * @returns {CommentTag[]}
  */
 const getDescribingCommentTags = (filePath) => {
@@ -80,7 +80,6 @@ Please add one OR edit the list of NON_SCRIPTLETS_FILES / NON_REDIRECTS_FILES.`)
  * @typedef {Object} DescribingCommentData
  *
  * Collected data from jsdoc-type comment for every scriptlet or redirect.
- *
  * @property {string} type parsed instance tag:
  * 'scriptlet' for '@scriptlet', 'redirect' for '@redirect'
  * @property {string} name name of instance which goes after the instance tag
@@ -93,7 +92,6 @@ Please add one OR edit the list of NON_SCRIPTLETS_FILES / NON_REDIRECTS_FILES.`)
  *
  * @param {CommentTag[]} commentTags parsed tags from describing comment
  * @param {string} source relative path to file
- *
  * @returns {DescribingCommentData}
  */
 const prepareCommentsData = (commentTags, source) => {
@@ -108,9 +106,9 @@ const prepareCommentsData = (commentTags, source) => {
 
 /**
  * Gets data objects which describe every required comment in one directory
+ *
  * @param {string[]} filesList list of files in directory
  * @param {string} relativeDirPath relative path to directory
- *
  * @returns {DescribingCommentData}
  */
 const getDataFromFiles = (filesList, relativeDirPath) => {

scripts/rollup-runners.js

@@ -5,7 +5,8 @@ const { log } = console;
 
 /**
  * Builds scriptlets
- * @param config config may be list of configs or one config
+ *
+ * @param {object|object[]} config config may be list of configs or one config
  */
 export const rollupStandard = async (config) => {
     const runOneConfig = async (config) => {
@@ -26,7 +27,8 @@ export const rollupStandard = async (config) => {
 
 /**
  * Builds scriptlets in the watch mode
- * @param config - config may be list of configs or one config
+ *
+ * @param {object|object[]} config - config may be list of configs or one config
  */
 export const rollupWatch = (config) => {
     const watcher = rollup.watch(config);

src/helpers/.eslintrc.js

@@ -0,0 +1,14 @@
+module.exports = {
+    extends: [
+        '../../.eslintrc',
+        '../.eslintrc',
+    ],
+    rules: {
+        'jsdoc/require-jsdoc': 1,
+        'jsdoc/require-param': 1,
+        'jsdoc/valid-types': 1,
+        'jsdoc/no-undefined-types': 1,
+        'jsdoc/require-param-description': 1,
+        'jsdoc/require-returns-description': 1,
+    },
+};