add implemented version info to docs. #273 AG-18483

Squashed commit of the following: commit a4ed413 Merge: 2de8352 66582ca Author: Slava Leleka <v.leleka@adguard.com> Date: Tue May 16 12:31:26 2023 +0300 Merge branch 'master' into feature/AG-18483 commit 2de8352 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 20:05:31 2023 +0300 throw an error if added not set commit a23d11b Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:38:24 2023 +0300 add changelog todo commit 9618dbb Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:33:50 2023 +0300 update v1.0.4 commit 5189d11 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:32:35 2023 +0300 update v1.0.4 commit 8896454 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:30:35 2023 +0300 update v1.6.2 commit cf5b9f3 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:29:38 2023 +0300 handle v1.9.1 commit ebfac6c Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:29:04 2023 +0300 handle v1.8.2 commit c453c2c Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:27:33 2023 +0300 handle v1.7.10 commit c211874 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:26:57 2023 +0300 handle v1.7.3 commit 1b1af6d Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:23:00 2023 +0300 handle v1.6.55 commit b496d6f Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:22:09 2023 +0300 handle v1.6.18 commit 6f8d1db Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:21:25 2023 +0300 handle v1.6.2 commit a5cd94e Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:18:49 2023 +0300 handle v1.5.0 commit a1b3b95 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:15:43 2023 +0300 handle v1.4.3 commit d10aca0 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:14:39 2023 +0300 handle v1.3.19 commit d4f09e5 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:13:08 2023 +0300 handle v1.3.18 commit fd59952 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:12:18 2023 +0300 handle v1.3.14 commit 4b45062 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:10:59 2023 +0300 handle v1.3.9 commit e4f7f8e Author: Slava Leleka <v.leleka@adguard.com> Date: Mon May 15 18:10:10 2023 +0300 handle v1.2.3 ... and 11 more commits
AdguardTeam · May 16, 2023 · 39bf026 · 39bf026
1 parent 66582ca
commit 39bf026
Show file tree

Hide file tree

Showing 87 changed files with 331 additions and 34 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -37,6 +37,7 @@ module.exports = {
                 'scriptlet',
                 'trustedScriptlet',
                 'redirect',
+                'added',
                 'jest-environment',
             ],
         }],

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,9 @@ 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

diff --git a/scripts/build-docs.js b/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),

diff --git a/scripts/helpers.js b/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,
     };
 };

diff --git a/src/redirects/amazon-apstag.js b/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 = {

diff --git a/src/redirects/ati-smarttag.js b/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 = {

diff --git a/src/redirects/blocking-redirects.yml b/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
     ```

diff --git a/src/redirects/didomi-loader.js b/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() { }

diff --git a/src/redirects/fingerprintjs2.js b/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 = '';

diff --git a/src/redirects/fingerprintjs3.js b/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 = (() => {

diff --git a/src/redirects/gemius.js b/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 () {};

diff --git a/src/redirects/google-analytics-ga.js b/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

diff --git a/src/redirects/google-analytics.js b/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

diff --git a/src/redirects/google-ima3.js b/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) {

diff --git a/src/redirects/googlesyndication-adsbygoogle.js b/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) {

diff --git a/src/redirects/googletagservices-gpt.js b/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();

diff --git a/src/redirects/matomo.js b/src/redirects/matomo.js
@@ -3,13 +3,16 @@ import { hit, noopFunc } from '../helpers/index';
 
 /**
  * @redirect matomo
+ *
  * @description
  * Mocks the piwik.js file of Matomo (formerly Piwik).
  *
  * **Example**
  * ```
  * ||example.org/piwik.js$script,redirect=matomo
  * ```
+ *
+ * @added v1.5.0.
  */
 
 export function Matomo(source) {