JS script to copy ADRs automatically

The script copies ADRs from the `doc/adr` folder into the web-doc
project, so that HTML pages can be generated for them.

The script runs automatically when the user starts the project with
`yarn dev`.

Before copying the files the script compares folders and only copies
folders and files that are missing, or that were modified.

The script runs synchronously, so that the project only starts after the
ADRs have been copied.

Singed-off-by: Rodrigo Pinto <rodrigo.pinto@calian.ca>

doc/web-doc/README.md

@@ -2,36 +2,47 @@
 
 ## Installation
 
-Requirements: NodeJS version 16 or above.
+Requirements: NodeJS on the same version as the one required for [Theia IDE][theia-prereq].
 
 ```bash
 cd doc/web-doc
 yarn
 ```
 
+> Executing `yarn` from the root of `theia-trace-extension` does not install the dependencies in `doc/web-doc`. The configuration for Lerna to support such a feature may be added in the future.
+
 Run site
 
 ```bash
 yarn dev
+```
+
+Or start the server and open the app in a new browser tab
 
-# or start the server and open the app in a new browser tab
+```bash
 yarn dev --open
 ```
 
-The site will be running at `http://localhost:5173`.
+The site will be running at [localhost, port 5173].
 
-## Code style
+## Development
 
-Run Prettier from the root.
+Run Prettier from the root of the web-doc project (at `doc/web-doc/` from the root of `theia-trace-extension`) using the following commands:
 
-Check code style:
+To check code style:
 
-	yarn lint
+```bash
+yarn lint
+```
 
-Fix code style:
+To fix code style:
 
-	yarn format
+```bash
+yarn format
+```
 
-## Development
+Website created with [SvelteKit].
 
-Website created with [SvelteKit](https://kit.svelte.dev)
+[theia-prereq]: https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#prerequisites
+[sveltekit]: https://kit.svelte.dev
+[localhost, port 5173]: http://localhost:5173

doc/web-doc/doc-loader.js

@@ -0,0 +1,94 @@
+import fs from 'fs-extra';
+import { compareSync } from 'dir-compare';
+import { once } from 'node:events';
+import { createInterface } from 'node:readline';
+
+const src = '../adr/';
+const dest = 'doc-sources/adr-source/';
+
+const errorCallback = (err) => {
+	if (err) throw err;
+};
+
+const comparisonOptions = {
+	excludeFilter: '.DS_Store',
+	compareSize: true,
+  compareContent: true
+};
+
+// Sanitizer of markdown files
+
+const sanitizer = (chunk) => {
+	return chunk.replace(/{/g, '{').replace(/}/g, '}');
+};
+
+const processLineByLine = async (file) => {
+	try {
+		let result = '';
+		let mermaid = false;
+		let mermaidBlock = '';
+
+		const rl = createInterface({
+			input: file,
+			crlfDelay: Infinity
+		});
+
+		rl.on('line', (line) => {
+			if (mermaid) {
+				mermaidBlock += line + '\n';
+
+				if (line.includes('```')) {
+					mermaid = false;
+					result += sanitizer(mermaidBlock);
+					mermaidBlock = '';
+				}
+			} else {
+				result += line + '\n';
+			}
+
+      if (line.includes('```mermaid')) {
+				mermaid = true;
+			}
+		});
+
+		await once(rl, 'close');
+
+		return result;
+	} catch (err) {
+		console.error(err);
+	}
+};
+
+// Compare folders
+
+if (!fs.existsSync('doc-sources')) {
+  fs.mkdirSync('doc-sources');
+  fs.mkdirSync(dest);
+} else if (!fs.existsSync(dest)) {
+  fs.mkdirSync(dest);
+}
+
+const comparison = compareSync(src, dest, comparisonOptions);
+
+// Copy missing files and folders
+
+if (!comparison.same) {
+	comparison.diffSet.forEach(async (dif) => {
+		if ((dif.state === 'left' || dif.state === 'distinct') && dif.path1 === src) {
+			if (dif.type1 === 'file' && dif.name1.slice(-3) === '.md') {
+        // Remove outdated file
+        if (dif.state === 'distinct') {
+          fs.rmSync(dest + dif.name2, { force: true })
+        }
+
+				// Sanitize Markdown files
+				const file = fs.createReadStream(src + dif.name1, 'utf8');
+				const sanitized = await processLineByLine(file);
+				fs.writeFileSync(dest + dif.name1, sanitized.toString());
+			} else {
+				// Copy
+				fs.copySync(src + dif.name1, dest + dif.name1, { recursive: true }, errorCallback);
+			}
+		}
+	});
+}

doc/web-doc/package.json

@@ -3,11 +3,12 @@
 	"version": "0.0.1",
 	"private": true,
 	"scripts": {
-		"dev": "vite dev",
+		"dev": "node doc-loader;vite dev",
 		"build": "vite build",
 		"preview": "vite preview",
 		"lint": "prettier --plugin-search-dir . --check . && eslint .",
-		"format": "prettier --plugin-search-dir . --write ."
+		"format": "prettier --plugin-search-dir . --write .",
+		"load": "node doc-loader"
 	},
 	"devDependencies": {
 		"@sveltejs/adapter-auto": "^1.0.0",
@@ -20,5 +21,12 @@
 		"svelte": "^3.54.0",
 		"vite": "^4.0.0"
 	},
-	"type": "module"
+	"type": "module",
+	"dependencies": {
+		"@ysuzuki19/remark-mermaid": "^1.0.2",
+		"dir-compare": "^4.0.0",
+		"fs-extra": "^11.1.0",
+		"mdsvex": "^0.10.6",
+		"mermaid": "^9.3.0"
+	}
 }