[DEVOPS-3113] Add ability to version static assets

src/lib/createVersion.js

@@ -4,20 +4,18 @@ const diffManager = require('./diffManager');
 const siteUtils = require('./siteUtils');
 const assetCopier = require('./assetCopier');
 const linker = require('./linker');
+const staticVersioner = require('./staticVersioning')
 
-exports.create = (version, siteDir) => {
+exports.create = (version, siteDir, staticAssets) => {
 	let siteProps = siteUtils.loadSiteProperties(siteDir);
 	throwIfInvalidCommand(version, siteProps);
-	return createVersion(version, siteProps);
+	return createVersion(version, siteProps, staticAssets);
 }
 
 function throwIfInvalidCommand(version, siteProps) {
 	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");
 	}
@@ -26,7 +24,7 @@ function throwIfInvalidCommand(version, siteProps) {
 	}
 }
 
-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 +33,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.copyAssets(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 staticFolderPath = 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.staticFolder = staticFolderPath;
 
     siteProps.pastVersions = pastVersions;
     siteProps.siteConfig = siteConfig;

src/lib/staticVersioning.js

@@ -0,0 +1,115 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function versionStaticAssets(sitePaths, staticAssets, version) {
+    let numberOfVersions = await getNumberOfVersions();
+    let staticDir = sitePaths.staticFolder;
+    let versionDocsDir = sitePaths.versionedDocs;
+    let excludeFromRemoval = ["next"];
+
+    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, excludeFromRemoval);
+            })
+        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.includes(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 docs path and versioned docs path differently
+        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

@@ -3,9 +3,19 @@ const createVersion = require('./lib/createVersion.js');
 
 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 (!staticDir) {
+                staticDir = [];
+            }
+            createVersion.create(version, siteDir, staticDir);
         });
     program.parse(argsParser);
-}
+}