[DEVOPS-3113] Add ability to version static assets

package.json

@@ -15,6 +15,7 @@
 		"eslint-plugin-mocha": "^8.0.0",
 		"mocha": "^8.1.1",
 		"mock-fs": "^4.12.0",
+		"rewire": "5.0.0",
 		"sinon": "^9.0.3"
 	},
 	"dependencies": {
@@ -25,4 +26,3 @@
 	},
 	"license": "GPL-3.0"
 }
-

src/lib/assetCopier.js

@@ -6,7 +6,7 @@ const readDirectory = util.promisify(fs.readdir);
 const copyFile = util.promisify(fs.copyFile);
 const lstatFile = util.promisify(fs.lstat);
 
-exports.copyAssets = async (docsDir, version) => {
+exports.copyDocAssets = async (docsDir, version) => {
     console.info("Copying assets for the new version...");
     let pathToAssets = path.join(docsDir, "assets");
     if (!fs.existsSync(pathToAssets)) {

src/lib/createVersion.js

@@ -4,29 +4,35 @@ const diffManager = require('./diffManager');
 const siteUtils = require('./siteUtils');
 const assetCopier = require('./assetCopier');
 const linker = require('./linker');
+const staticVersioner = require('./staticVersioner')
+const path = require("path");
 
-exports.create = (version, siteDir) => {
+exports.create = (version, siteDir, staticAssets) => {
 	let siteProps = siteUtils.loadSiteProperties(siteDir);
-	throwIfInvalidCommand(version, siteProps);
-	return createVersion(version, siteProps);
+	throwIfInvalidCommand(version, siteProps, staticAssets);
+	return createVersion(version, siteProps, staticAssets);
 }
 
-function throwIfInvalidCommand(version, siteProps) {
+function throwIfInvalidCommand(version, siteProps, staticAssets) {
 	if (!fs.existsSync(siteProps.paths.versionJS)) {
 		throw new Error("version.js file is missing");
 	}
-	if (typeof version === undefined) {
-		throw new TypeError("Verion not specified");
-	}
-	if (version.includes('/')) {
-		throw new TypeError("Invalid version format. (/) character is not allowed in version");
-	}
 	if (siteProps.pastVersions.includes(version)) {
 		throw new TypeError("The specified version already exists");
 	}
+	if (staticAssets.length > 0) {
+		staticAssets.forEach(staticType => {
+			let staticTypeDirPath = path.join(siteProps.path.staticDir, staticType);
+			fs.access(staticTypeDirPath, err => {
+				if (err) {
+					throw new TypeError(`The ${staticType} directory does not exist under the static directory`)
+				}
+			})
+		})
+	}
 }
 
-async function createVersion(version, siteProps) {
+async function createVersion(version, siteProps, staticAssets) {
 	await Promise.all([diffManager.generateFileDiff(siteProps.paths.docs), diffManager.generateSidebarDiff(siteProps.paths.siteDir)]);
 	console.info("Diff generation completed...");
 	runDocusaurusVersionCommand(version, siteProps.paths.siteDir);
@@ -35,8 +41,11 @@ async function createVersion(version, siteProps) {
 		diffManager.cleanUpFileDiff(siteProps.paths.versionedDocs, version),
 		diffManager.cleanUpSidebarDiff(siteProps.paths.siteDir),
 		diffManager.cleanUpSidebarDiff(siteProps.paths.siteDir, version),
-		assetCopier.copyAssets(siteProps.paths.docs, version)
+		assetCopier.copyDocAssets(siteProps.paths.docs, version),
 	]);
+	if (staticAssets) {
+		await staticVersioner.versionStaticAssets(siteProps.paths, staticAssets, version);
+	}
 	return linker.linkAssetsInMarkdownFiles(siteProps.paths.versionedDocs, version);
 }
 

src/lib/siteUtils.js

@@ -8,6 +8,7 @@ exports.loadSiteProperties = (siteDir) => {
     let versionJSONPath = path.join(resolvedSiteDir, "versions.json");
     let siteConfigPath = path.join(resolvedSiteDir, "siteConfig.js");
     let versionedDocsPath = path.join(resolvedSiteDir, "versioned_docs");
+    let staticDirPath = path.join(resolvedSiteDir, "static");
     let pastVersions = [];
 
     if(fs.existsSync(versionJSONPath)) {
@@ -30,6 +31,7 @@ exports.loadSiteProperties = (siteDir) => {
     siteProps.paths.siteConfig = siteConfigPath;
     siteProps.paths.docs = docsPath;
     siteProps.paths.versionedDocs = versionedDocsPath;
+    siteProps.paths.staticDir = staticDirPath;
 
     siteProps.pastVersions = pastVersions;
     siteProps.siteConfig = siteConfig;

src/lib/staticVersioner.js

@@ -0,0 +1,113 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function versionStaticAssets(sitePaths, staticAssets, version) {
+    let numberOfVersions = await getNumberOfVersions();
+    let staticDir = sitePaths.staticDir;
+    let versionDocsDir = sitePaths.versionedDocs;
+
+    for (const staticType of staticAssets) {
+        console.info("Versioning static asset files...");
+        let staticTypePath = path.join(staticDir, staticType);
+        let staticTypeNextPath = path.join(staticTypePath, "next");
+        // if a static asset is versioned for the first time, create the next directory
+        await fs.access(staticTypeNextPath)
+            .catch(async () => {
+                await copyDirectory(staticTypePath, staticTypeNextPath);
+                await removeFilesInDirectory(staticTypePath, "next");
+            })
+        let staticTypeVersionPath = path.join(staticTypePath, version);
+        await copyDirectory(staticTypeNextPath, staticTypeVersionPath)
+    }
+
+    let baseVersionedDocsPath = path.join(versionDocsDir, `version-${version}`);
+    if (numberOfVersions === 1) {
+        await updateRelativePaths(sitePaths.docs, staticAssets);
+    }
+    await updateRelativePaths(baseVersionedDocsPath, staticAssets, version);
+}
+
+async function getNumberOfVersions() {
+    let fileContent = await fs.readFile("./versions.json", "utf8");
+    let jsonContent = JSON.parse(fileContent);
+    return jsonContent.length;
+}
+
+async function copyDirectory(from, to) {
+    await fs.mkdir(to);
+
+    const files = await fs.readdir(from, {withFileTypes: true});
+    for (const file of files) {
+        let relativePath = path.join(from, file.name);
+        let targetPath = path.join(to, file.name);
+        if (file.isDirectory() && relativePath !== to) {
+            await copyDirectory(relativePath, targetPath);
+        } else if(!file.isDirectory()) {
+            await fs.copyFile(relativePath, targetPath)
+                .catch((err) => console.log(err + '\n' + `${relativePath} could not be copied`));
+        }
+    }
+}
+
+async function removeFilesInDirectory(from, exclude) {
+    const files = await fs.readdir(from, {withFileTypes: true});
+    for (const file of files) {
+        if (exclude !== file.name) {
+            await fs.rm(path.join(from, file.name), {recursive: true});
+        }
+    }
+}
+
+/*
+  Recursive function that loops through all files in the current directory and
+  subdirectories, and replaces the links in each file.
+ */
+async function updateRelativePaths(basePath, staticAssets, version="") {
+    // read all files from directory
+    const files = await fs.readdir(basePath, {withFileTypes: true});
+    for (const file of files) {
+        // if file type is a directory, a recursive call is made
+        if (file.isDirectory()) {
+            let subDirName = file.name;
+            await updateRelativePaths(path.join(basePath, subDirName), staticAssets, version);
+        } else {
+            let filePath = path.join(basePath, file.name);
+            await replaceRelativePaths(filePath, staticAssets, version);
+        }
+    }
+}
+
+async function replaceRelativePaths(filePath, staticAssets, version="") {
+    let fileContent = await fs.readFile(filePath, {encoding: "utf8", flag: "r+"});
+    // flag to set when files are modified
+    let isFileContentModified = false;
+    let numberOfVersions = await getNumberOfVersions();
+
+    // loop through all the passed in static assets and replace the text
+    for (const staticType of staticAssets) {
+
+        let relativeLinkPattern = new RegExp(`../${staticType}/next`, 'gm');
+        let replacementText = `${staticType}/${version}`;
+
+        // if versioning for the first time, replace the links in the docs path and versioned docs path accordingly
+        if (numberOfVersions === 1 && filePath.includes('/docs/')) {
+            relativeLinkPattern = new RegExp(`../${staticType}/`, 'gm')
+            replacementText = `../../${staticType}/next/`;
+        } else if (numberOfVersions === 1 && filePath.includes('/versioned_docs/')) {
+            relativeLinkPattern = new RegExp(`../${staticType}/`, 'gm');
+            replacementText = `../${staticType}/${version}/`;
+        }
+
+        fileContent = fileContent.replace(relativeLinkPattern, function() {
+            isFileContentModified = true;
+            return replacementText;
+        });
+    }
+
+    // if contents have been modified then write to file
+    if (isFileContentModified) {
+        await fs.writeFile(filePath, fileContent);
+    }
+}
+
+module.exports.versionStaticAssets = versionStaticAssets;

src/snapshotVersion.js

@@ -1,11 +1,25 @@
 const program = require('commander');
 const createVersion = require('./lib/createVersion.js');
+const fs = require("fs");
 
 module.exports = (argsParser = process.argv) => {
     program
-        .command('create <version> [siteDir]')
-        .action((version, siteDir = ".") => {
-            createVersion.create(version, siteDir);
+        .command('create')
+        .storeOptionsAsProperties(true)
+        .requiredOption('--version <type>', '[required] The value of the new version to create.')
+        .option('--siteDir <type>', '[optional] The absolute or relative path to the `website` directory of the Docusaurus V1 project.', '.')
+        .option('--staticDir <type...>', '[optional] The static asset directory to be versioned. Only the name of the folder is required.')
+        .action((options) => {
+            let version = options.version;
+            let siteDir = options.siteDir;
+            let staticDir = options.staticDir;
+            if (version.includes('/')) {
+                throw new TypeError("Invalid version format. (/) character is not allowed in version");
+            }
+            if (!staticDir) {
+                staticDir = [];
+            }
+            createVersion.create(version, siteDir, staticDir);
         });
     program.parse(argsParser);
-}
+}

test/lib/assetCopierTest.js

@@ -21,7 +21,7 @@ describe("Copy assets for versioning", function() {
         });
 
         let docsDir = path.join(process.cwd(), "docs");
-        await assetCopier.copyAssets(docsDir, "1.2.4");
+        await assetCopier.copyDocAssets(docsDir, "1.2.4");
         let versionedAssetPath = path.join(docsDir, "assets", "version-1.2.4");
         let versionedOverviewPath = path.join(versionedAssetPath, "Overview.png");
         let versionedAPIPath = path.join(versionedAssetPath, "API");

test/lib/createVersionTest.js

@@ -59,8 +59,8 @@ describe('createVersion does preliminary checks and calls diffManager',
                     'yarn run version 1.2.3');
                 sinon.assert.calledOnce(shell.exec);
 
-                sinon.assert.calledOnce(assetCopier.copyAssets);
-                sinon.assert.calledWithExactly(assetCopier.copyAssets, siteProps.paths.docs, "1.2.3");
+                sinon.assert.calledOnce(assetCopier.copyDocAssets);
+                sinon.assert.calledWithExactly(assetCopier.copyDocAssets, siteProps.paths.docs, "1.2.3");
 
                 sinon.assert.calledOnce(linker.linkAssetsInMarkdownFiles);
                 sinon.assert.calledWithExactly(linker.linkAssetsInMarkdownFiles,
@@ -96,7 +96,7 @@ describe('createVersion does preliminary checks and calls diffManager',
             sinon.assert.calledWithExactly(siteUtils.loadSiteProperties, SITE_DIR);
             sinon.assert.notCalled(diffManager.generateFileDiff);
             sinon.assert.notCalled(diffManager.cleanUpFileDiff);
-            sinon.assert.notCalled(assetCopier.copyAssets);
+            sinon.assert.notCalled(assetCopier.copyDocAssets);
             sinon.assert.notCalled(linker.linkAssetsInMarkdownFiles);
             sinon.assert.notCalled(shell.cd);
             sinon.assert.notCalled(shell.exec);