refactor scripts methods, fix types

scripts/build-compatibility-table.js

@@ -24,47 +24,69 @@ const WIKI_COMPATIBILITY_TABLE_PATH = path.resolve(
     COMPATIBILITY_TABLE_OUTPUT_FILENAME,
 );
 
+/**
+ * @typedef {Object} CompatibilityItem
+ * @property {string} adg
+ * @property {string} abp
+ * @property {string} ubo
+ */
+
+/**
+ * @typedef {Object} CompatibilityData
+ * @property {CompatibilityItem[]} scriptlets
+ * @property {CompatibilityItem[]} redirects
+ */
+
 /**
  * Returns data for compatibility table
+ *
+ * @returns {CompatibilityData} input compatibility data from json
  */
 const getTableData = () => {
     const rawData = fs.readFileSync(COMPATIBILITY_TABLE_DATA_PATH);
     return JSON.parse(rawData);
 };
 
-// FIXME: update jsdoc - id arg is missed
 /**
  * Returns markdown row of compatibility table
- * @param {{
- * adg: string,
- * ubo: string,
- * abp: string
- * }} item { an }
+ *
+ * @param {'scriptlets'|'redirects'} id
+ * @param {CompatibilityItem} item params object
+ * @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, item) => {
+const getRow = (id, { adg, abp, ubo }) => {
     let adgCell = '';
-    if (item.adg) {
-        adgCell = item.adg.includes(REMOVED_MARKER)
-            ? item.adg
-            : `[${item.adg}](${WIKI_DIR_PATH}/about-${id}.md#${item.adg})`;
+    if (adg) {
+        adgCell = adg.includes(REMOVED_MARKER)
+            ? adg
+            : `[${adg}](${WIKI_DIR_PATH}/about-${id}.md#${adg})`;
     }
 
-    return `| ${adgCell} | ${item.ubo || ''} | ${item.abp || ''} |${EOL}`;
+    return `| ${adgCell} | ${ubo || ''} | ${abp || ''} |${EOL}`;
 };
 
 /**
  * Generates table header
+ *
+ * @returns {string}
  */
 const getTableHeader = () => {
     let res = `| AdGuard | uBO | Adblock Plus |${EOL}`;
     res += `|---|---|---|${EOL}`;
     return res;
 };
 
-// FIXME: add missed args, add @returns, fix Array type
 /**
  * Builds markdown string of scriptlets/redirect compatibility table
- * @param {Array} data array of scriptlets/redirect names
+ * @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 = '') => {
     // title
@@ -82,7 +104,7 @@ const buildTable = (title, data = [], id = '') => {
 /**
  * Saves tables to compatibility table
  *
- * @param  {string[]} args
+ * @param {string[]} args
  */
 const saveTables = (...args) => {
     const res = args.join(`${EOL}${EOL}`);
@@ -109,6 +131,7 @@ const buildCompatibilityTable = () => {
     saveTables(scriptletsTable, redirectsTable);
 };
 
+// TODO: check whether the execution is needed here
 buildCompatibilityTable();
 
 module.exports = {

scripts/build-corelibs.js

@@ -4,7 +4,7 @@ import { minify } from 'terser';
 
 import * as scriptletList from '../src/scriptlets/scriptlets-list';
 import { version } from '../package.json';
-import { writeFile } from './helpers';
+import { writeFileAsync } from './helpers';
 
 const buildCorelibsJson = async () => {
     const { getScriptletFunction } = require('../tmp/scriptlets-func'); // eslint-disable-line import/no-unresolved,global-require
@@ -37,6 +37,6 @@ const buildCorelibsJson = async () => {
 export const buildScriptletsForCorelibs = async () => {
     console.log('Start building corelibs...');
     const json = await buildCorelibsJson();
-    await writeFile(path.resolve(__dirname, '../dist/scriptlets.corelibs.json'), json, 'utf8');
+    await writeFileAsync(path.resolve(__dirname, '../dist/scriptlets.corelibs.json'), json, 'utf8');
     console.log('Corelibs built');
 };

scripts/build-docs.js

@@ -56,13 +56,25 @@ const manageDataFromFiles = () => {
     return { scriptletsData, redirectsData };
 };
 
-// FIXME: check type of `data`
 /**
- * Generates markdown list and describing text
- * @param {Object} data array of filtered objects - scriptlets or redirects
+ * @typedef { import('./helpers').DescribingCommentData } DescribingCommentData
  */
-const getMarkdownData = (data) => {
-    const output = data.reduce((acc, {
+
+/**
+ * @typedef {Object} MarkdownData
+ * @property {string} list table of content
+ * @property {string} body main content which
+ */
+
+/**
+ * Generates markdown list and describing text.
+ *
+ * @param {DescribingCommentData[]} dataItems array of comment data objects
+ *
+ * @returns {MarkdownData}
+ */
+const getMarkdownData = (dataItems) => {
+    const output = dataItems.reduce((acc, {
         name,
         type,
         description,
@@ -89,6 +101,8 @@ ${description}${EOL}
 
 /**
  * Generates markdown list and describing text for static redirect resources
+ *
+ * @returns {MarkdownData}
  */
 const getMarkdownDataForStaticRedirects = () => {
     const staticRedirects = fs.readFileSync(path.resolve(__dirname, staticRedirectsPath), { encoding: 'utf8' });
@@ -118,6 +132,8 @@ ${description}
 
 /**
  * Generates markdown list and describing text for blocking redirect resources, i.e click2load.html
+ *
+ * @returns {MarkdownData}
  */
 const getMarkdownDataForBlockingRedirects = () => {
     const BLOCKING_REDIRECTS_SOURCE_SUB_DIR = 'blocking-redirects';

scripts/build-funcs.js

@@ -18,7 +18,7 @@
 import path from 'path';
 import { minify } from 'terser';
 import { addCall, attachDependencies } from '../src/helpers/injector';
-import { writeFile } from './helpers';
+import { writeFileAsync } from './helpers';
 
 /**
  * Method creates string for file with scriptlets functions,
@@ -67,7 +67,7 @@ export const buildScriptletsFunc = async () => {
         format: { beautify: true },
     });
 
-    await writeFile(path.resolve(__dirname, '../tmp/scriptlets-func.js'), beautifiedScriptletFunctions.code);
+    await writeFileAsync(path.resolve(__dirname, '../tmp/scriptlets-func.js'), beautifiedScriptletFunctions.code);
 
     console.log('Scriptlets functions built successfully');
 };

scripts/build-redirects-map.js

@@ -3,7 +3,7 @@ import { minify } from 'terser';
 import path from 'path';
 
 import { getPreparedRedirects } from './build-redirects';
-import { writeFile } from './helpers';
+import { writeFileAsync } from './helpers';
 
 const createRedirectsMap = (redirects) => {
     const map = {};
@@ -41,7 +41,7 @@ export const buildRedirectsMap = async () => {
         format: { beautify: true },
     });
 
-    await writeFile(path.resolve(__dirname, '../tmp/redirects-map.js'), beautifiedScriptletFunctions.code);
+    await writeFileAsync(path.resolve(__dirname, '../tmp/redirects-map.js'), beautifiedScriptletFunctions.code);
 
     console.log('Finish building redirect map');
 };

scripts/build-redirects.js

@@ -14,7 +14,7 @@ import { minify } from 'terser';
 import * as redirectsList from '../src/redirects/redirects-list';
 import { version } from '../package.json';
 import { rollupStandard } from './rollup-runners';
-import { writeFile, getDataFromFiles } from './helpers';
+import { writeFileAsync, getDataFromFiles } from './helpers';
 import { redirectsFilenames, REDIRECTS_SRC_RELATIVE_DIR_PATH } from './constants';
 
 const FILE_NAME = 'redirects.yml';
@@ -202,7 +202,7 @@ export const getPreparedRedirects = async (options) => {
 const buildJsRedirectFiles = async (redirectsData) => {
     const saveRedirectData = async (redirect) => {
         const redirectPath = `${REDIRECT_FILES_PATH}/${redirect.file}`;
-        await writeFile(redirectPath, redirect.content);
+        await writeFileAsync(redirectPath, redirect.content);
     };
 
     await Promise.all(Object.values(redirectsData)
@@ -230,9 +230,9 @@ const buildStaticRedirectFiles = async (redirectsData) => {
             // replace them all because base64 isn't supposed to have them
             contentToWrite = content.replace(/(\r\n|\n|\r|\s)/gm, '');
             const buff = Buffer.from(contentToWrite, 'base64');
-            await writeFile(redirectPath, buff);
+            await writeFileAsync(redirectPath, buff);
         } else {
-            await writeFile(redirectPath, contentToWrite);
+            await writeFileAsync(redirectPath, contentToWrite);
         }
     };
 
@@ -251,7 +251,7 @@ const buildRedirectsYamlFile = async (mergedRedirects) => {
     // add version and title to the top
     yamlRedirects = `${banner}${yamlRedirects}`;
 
-    await writeFile(RESULT_PATH, yamlRedirects);
+    await writeFileAsync(RESULT_PATH, yamlRedirects);
 };
 
 export const prebuildRedirects = async () => {
@@ -372,7 +372,7 @@ export const buildRedirectsForCorelibs = async () => {
 
     try {
         const jsonString = JSON.stringify(base64Redirects, null, 4);
-        await writeFile(CORELIBS_RESULT_PATH, jsonString);
+        await writeFileAsync(CORELIBS_RESULT_PATH, jsonString);
     } catch (e) {
         // eslint-disable-next-line no-console
         console.log(`Couldn't save to ${CORELIBS_RESULT_PATH}, because of: ${e.message}`);

scripts/build-txt.js

@@ -1,11 +1,11 @@
 import path from 'path';
-import { writeFile } from './helpers';
+import { writeFileAsync } from './helpers';
 import { version } from '../package.json';
 
 const PATH = '../dist';
 const FILENAME = 'build.txt';
 
 export const buildTxt = async () => {
     const content = `version=${version}`;
-    await writeFile(path.resolve(__dirname, PATH, FILENAME), content);
+    await writeFileAsync(path.resolve(__dirname, PATH, FILENAME), content);
 };