merge master, resolve conflicts

Author: slavaleleka

.eslintrc.js

@@ -37,6 +37,7 @@ module.exports = {
                 'scriptlet',
                 'trustedScriptlet',
                 'redirect',
+                'added',
                 'jest-environment',
             ],
         }],

CHANGELOG.md

@@ -4,13 +4,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+<!-- TODO: add @added tag to the files with specific version -->
+<!--       during new scriptlets or redirects releasing -->
 
 ## [Unreleased]
 
 ### Changed
 
-- `trusted-set-cookie` and `trusted-set-cookie-reaload` scriptlets to not encode cookie name and value [#311](https://github.com/AdguardTeam/Scriptlets/issues/311)
-- improved `prevent-fetch` — if `responseType` is not specified,
+- `trusted-set-cookie` and `trusted-set-cookie-reload` scriptlets to not encode cookie name and value
+  [#311](https://github.com/AdguardTeam/Scriptlets/issues/311)
+- improved `prevent-fetch`: if `responseType` is not specified,
   original response type is returned instead of `default` [#297](https://github.com/AdguardTeam/Scriptlets/issues/291)
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@adguard/scriptlets",
-    "version": "1.9.13",
+    "version": "1.9.14",
     "description": "AdGuard's JavaScript library of Scriptlets and Redirect resources",
     "scripts": {
         "build": "babel-node bundler.js",

scripts/build-docs.js

@@ -102,18 +102,21 @@ const getMarkdownData = (dataItems) => {
     const output = dataItems.reduce((acc, {
         name,
         type,
+        versionAdded,
         description,
         source,
     }) => {
-        // low case name should be used as anchor
+        // low case name should be used as an anchor in the table of content
         acc.list.push(`* [${name}](#${name.toLowerCase()})${EOL}`);
 
         const typeOfSrc = type.toLowerCase().includes('scriptlet') ? 'Scriptlet' : 'Redirect';
 
-        // low case name should be used as anchor
-        const body = `### <a id="${name.toLowerCase()}"></a> ⚡️ ${name}
+        // 1. Low case name should be used as an anchor
+        // 2. There is no EOL after 'version' string because `description` starts with `\n`
+        const body = `### <a id="${name.toLowerCase()}"></a> ⚡️ ${name}${EOL}
+${versionAdded ? `> Added in ${versionAdded}` : '> Adding version is unknown.'}
 ${description}${EOL}
-[${typeOfSrc} source](${source})
+[${typeOfSrc} source](${source})${EOL}
 * * *${EOL}${EOL}`;
         acc.body.push(body);
 
@@ -135,18 +138,25 @@ const getMarkdownDataForStaticRedirects = () => {
     const staticRedirects = fs.readFileSync(path.resolve(__dirname, staticRedirectsPath), { encoding: 'utf8' });
     const parsedStaticRedirects = yaml.safeLoad(staticRedirects);
 
-    const output = parsedStaticRedirects.reduce((acc, { title, description }) => {
-        if (description) {
-            acc.list.push(`* [${title}](#${title})${EOL}`);
+    const output = parsedStaticRedirects.reduce((acc, { title, description, added }) => {
+        if (!title) {
+            throw new Error('No title for static redirect');
+        }
+        if (!description) {
+            throw new Error(`No description for static redirect '${title}'`);
+        }
+        if (!added) {
+            throw new Error(`No added version for static redirect '${title}'`);
+        }
+
+        acc.list.push(`* [${title}](#${title})${EOL}`);
 
-            const body = `### <a id="${title}"></a> ⚡️ ${title}
-${description}
-[Redirect source](${STATIC_REDIRECTS_RELATIVE_SOURCE})
+        const body = `### <a id="${title}"></a> ⚡️ ${title}${EOL}
+${added ? `> Added in ${added}.` : '> Adding version is unknown.'}${EOL}
+${description}${EOL}
+[Redirect source](${STATIC_REDIRECTS_RELATIVE_SOURCE})${EOL}
 * * *${EOL}${EOL}`;
-            acc.body.push(body);
-        } else {
-            throw new Error(`No description for ${title}`);
-        }
+        acc.body.push(body);
 
         return acc;
     }, { list: [], body: [] });
@@ -170,18 +180,25 @@ const getMarkdownDataForBlockingRedirects = () => {
     const blockingRedirects = fs.readFileSync(blockingRedirectsPath, { encoding: 'utf8' });
     const parsedBlockingRedirects = yaml.safeLoad(blockingRedirects);
 
-    const output = parsedBlockingRedirects.reduce((acc, { title, description }) => {
-        if (description) {
-            acc.list.push(`* [${title}](#${title})${EOL}`);
+    const output = parsedBlockingRedirects.reduce((acc, { title, description, added }) => {
+        if (!title) {
+            throw new Error('No title for blocking redirect');
+        }
+        if (!description) {
+            throw new Error(`No description for blocking redirect '${title}'`);
+        }
+        if (!added) {
+            throw new Error(`No added version for blocking redirect '${title}'`);
+        }
+
+        acc.list.push(`* [${title}](#${title})${EOL}`);
 
-            const body = `### <a id="${title}"></a> ⚡️ ${title}
-${description}
-[Redirect source](${BLOCKING_REDIRECTS_RELATIVE_SOURCE}/${title})
+        const body = `### <a id="${title}"></a> ⚡️ ${title}${EOL}
+${added ? `> Added in ${added}.` : '> Adding version is unknown.'}${EOL}
+${description}${EOL}
+[Redirect source](${BLOCKING_REDIRECTS_RELATIVE_SOURCE}/${title})${EOL}
 * * *${EOL}${EOL}`;
-            acc.body.push(body);
-        } else {
-            throw new Error(`No description for ${title}`);
-        }
+        acc.body.push(body);
 
         return acc;
     }, { list: [], body: [] });
@@ -206,8 +223,8 @@ const buildWikiAboutPages = () => {
         const staticRedirectsMarkdownData = getMarkdownDataForStaticRedirects();
         const blockingRedirectsMarkdownData = getMarkdownDataForBlockingRedirects();
 
-        const scriptletsPageContent = `## <a id="scriptlets"></a> Available Scriptlets
-${scriptletsMarkdownData.list}* * *
+        const scriptletsPageContent = `## <a id="scriptlets"></a> Available Scriptlets${EOL}
+${scriptletsMarkdownData.list}* * *${EOL}
 ${scriptletsMarkdownData.body}`;
         fs.writeFileSync(
             path.resolve(__dirname, aboutScriptletsPath),

scripts/helpers.js

@@ -32,15 +32,15 @@ const getFilesList = (relativeDirPath) => {
 
 /**
  * @typedef {Object} CommentTag
- * @property {string} type tag name
- * @property {string} string text following the tag
+ * @property {string} type Tag name, e.g. `@scriptlet`, `@redirect`, `@added`.
+ * @property {string} string Text following the tag name.
  */
 
 /**
  * Returns parsed tags data which we use to describe the sources:
  * - `@scriptlet`/`trustedScriptlet`/`@redirect` to describe the type and name of source;
  * - `@description` actual description for scriptlet or redirect.
- * required comments from file.
+ * - `@added` means version when scriptlet or redirect was implemented.
  * In one file might be comments describing scriptlet and redirect as well.
  *
  * @param {string} filePath absolute path to file
@@ -95,11 +95,17 @@ Please add one OR edit the list of NON_SCRIPTLETS_FILES / NON_REDIRECTS_FILES.`)
  * @returns {DescribingCommentData}
  */
 const prepareCommentsData = (commentTags, source) => {
-    const [base, sup] = commentTags;
+    const [typeTag, descriptionTag, addedTag] = commentTags;
+    const name = typeTag.string;
+    const versionAdded = addedTag?.string;
+    if (!versionAdded) {
+        throw new Error(`No @added tag for ${name}`);
+    }
     return {
-        type: base.type,
-        name: base.string,
-        description: sup.string,
+        type: typeTag.type,
+        name,
+        description: descriptionTag.string,
+        versionAdded,
         source,
     };
 };

src/redirects/amazon-apstag.js

@@ -2,6 +2,7 @@ import { hit, noopFunc } from '../helpers/index';
 
 /**
  * @redirect amazon-apstag
+ *
  * @description
  * Mocks Amazon's apstag.js
  *
@@ -12,6 +13,8 @@ import { hit, noopFunc } from '../helpers/index';
  * ```
  * ||amazon-adsystem.com/aax2/apstag.js$script,redirect=amazon-apstag
  * ```
+ *
+ * @added v1.2.3.
  */
 export function AmazonApstag(source) {
     const apstagWrapper = {

src/redirects/ati-smarttag.js

@@ -2,6 +2,7 @@ import { hit, noopFunc } from '../helpers/index';
 
 /**
  * @redirect ati-smarttag
+ *
  * @description
  * Mocks AT Internat SmartTag.
  * https://developers.atinternet-solutions.com/as2-tagging-en/javascript-en/getting-started-javascript-en/tracker-initialisation-javascript-en/
@@ -10,6 +11,8 @@ import { hit, noopFunc } from '../helpers/index';
  * ```
  * ||bloctel.gouv.fr/assets/scripts/smarttag.js$script,redirect=ati-smarttag
  * ```
+ *
+ * @added v1.5.0.
  */
 export function ATInternetSmartTag(source) {
     const setNoopFuncWrapper = {

src/redirects/blocking-redirects.yml

@@ -4,13 +4,15 @@
 # use ">" if property contains long string
 
 - title: click2load.html
+  added: v1.5.0
   description: |-
     Redirects resource and replaces supposed content by decoy frame with button for original content recovering
 
     Related UBO redirect resource:
     https://github.com/gorhill/uBlock/blob/1.31.0/src/web_accessible_resources/click2load.html
 
     **Example**
+
     ```
     ||youtube.com/embed/$frame,third-party,redirect=click2load.html
     ```

src/redirects/didomi-loader.js

@@ -9,6 +9,7 @@ import {
 
 /**
  * @redirect didomi-loader
+ *
  * @description
  * Mocks Didomi's CMP loader script.
  * https://developers.didomi.io/
@@ -17,6 +18,8 @@ import {
  * ```
  * ||sdk.privacy-center.org/fbf86806f86e/loader.js$script,redirect=didomi-loader
  * ```
+ *
+ * @added v1.6.2.
  */
 export function DidomiLoader(source) {
     function UserConsentStatusForVendorSubscribe() { }

src/redirects/fingerprintjs2.js

@@ -3,6 +3,7 @@ import { hit } from '../helpers/index';
 
 /**
  * @redirect fingerprintjs2
+ *
  * @description
  * Mocks FingerprintJS v2
  * https://github.com/fingerprintjs
@@ -14,6 +15,8 @@ import { hit } from '../helpers/index';
  * ```
  * ||the-japan-news.com/modules/js/lib/fgp/fingerprint2.js$script,redirect=fingerprintjs2
  * ```
+ *
+ * @added v1.5.0.
  */
 export function Fingerprintjs2(source) {
     let browserId = '';

src/redirects/fingerprintjs3.js

@@ -6,6 +6,7 @@ import {
 
 /**
  * @redirect fingerprintjs3
+ *
  * @description
  * Mocks FingerprintJS v3
  * https://github.com/fingerprintjs
@@ -17,6 +18,8 @@ import {
  * ```
  * ||sephora.com/js/ufe/isomorphic/thirdparty/fp.min.js$script,redirect=fingerprintjs3
  * ```
+ *
+ * @added v1.6.2.
  */
 export function Fingerprintjs3(source) {
     const visitorId = (() => {

src/redirects/gemius.js

@@ -3,6 +3,7 @@ import { hit, noopFunc } from '../helpers/index';
 
 /**
  * @redirect gemius
+ *
  * @description
  * Mocks Gemius Analytics.
  * https://flowplayer.com/developers/plugins/gemius
@@ -11,6 +12,8 @@ import { hit, noopFunc } from '../helpers/index';
  * ```
  * ||gapt.hit.gemius.pl/gplayer.js$script,redirect=gemius
  * ```
+ *
+ * @added v1.5.0.
  */
 export function Gemius(source) {
     const GemiusPlayer = function () {};

src/redirects/google-analytics-ga.js

@@ -7,6 +7,7 @@ import {
 
 /**
  * @redirect google-analytics-ga
+ *
  * @description
  * Mocks old Google Analytics API.
  *
@@ -17,6 +18,8 @@ import {
  * ```
  * ||google-analytics.com/ga.js$script,redirect=google-analytics-ga
  * ```
+ *
+ * @added v1.0.10.
  */
 export function GoogleAnalyticsGa(source) {
     // Gaq constructor

src/redirects/google-analytics.js

@@ -7,6 +7,7 @@ import {
 
 /**
  * @redirect google-analytics
+ *
  * @description
  * Mocks Google's Analytics and Tag Manager APIs.
  * [Covers obsolete googletagmanager-gtm redirect functionality](https://github.com/AdguardTeam/Scriptlets/issues/127).
@@ -19,6 +20,8 @@ import {
  * ||google-analytics.com/analytics.js$script,redirect=google-analytics
  * ||googletagmanager.com/gtm.js$script,redirect=googletagmanager-gtm
  * ```
+ *
+ * @added v1.0.10.
  */
 export function GoogleAnalytics(source) {
     // eslint-disable-next-line func-names

src/redirects/google-ima3.js

@@ -7,13 +7,16 @@ import {
 
 /**
  * @redirect google-ima3
+ *
  * @description
  * Mocks the IMA SDK of Google.
  *
  * **Example**
  * ```
  * ||imasdk.googleapis.com/js/sdkloader/ima3.js$script,redirect=google-ima3
  * ```
+ *
+ * @added v1.6.2.
  */
 
 export function GoogleIma3(source) {

src/redirects/googlesyndication-adsbygoogle.js

@@ -3,6 +3,7 @@ import { hit } from '../helpers/index';
 /* eslint-disable max-len */
 /**
  * @redirect googlesyndication-adsbygoogle
+ *
  * @description
  * Mocks Google AdSense API.
  *
@@ -13,6 +14,8 @@ import { hit } from '../helpers/index';
  * ```
  * ||pagead2.googlesyndication.com/pagead/js/adsbygoogle.js$script,redirect=googlesyndication-adsbygoogle
  * ```
+ *
+ * @added v1.0.10.
  */
 /* eslint-enable max-len */
 export function GoogleSyndicationAdsByGoogle(source) {

src/redirects/googletagservices-gpt.js

@@ -11,6 +11,7 @@ import {
 
 /**
  * @redirect googletagservices-gpt
+ *
  * @description
  * Mocks Google Publisher Tag API.
  *
@@ -21,6 +22,8 @@ import {
  * ```
  * ||googletagservices.com/tag/js/gpt.js$script,redirect=googletagservices-gpt
  * ```
+ *
+ * @added v1.0.10.
  */
 export function GoogleTagServicesGpt(source) {
     const slots = new Map();