chore(docs): add versioned documentation with auto-detection

Close #675

Author: Killusions

.github/scripts/merge-versions.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+/**
+ * Merge versions.json for documentation deployment
+ *
+ * This script merges existing versions from S3 with newly deployed versions,
+ * ensuring the version selector shows all available documentation versions.
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+
+/**
+ * Compute sort key for a version string
+ * Returns [category, value] where:
+ * - category 0: "latest"
+ * - category 1: "preview"
+ * - category 2: versioned releases (v1, v2, etc.) - sorted descending
+ * - category 3: unknown/unexpected entries
+ */
+function sortKey(version) {
+  if (version === 'latest') return [0, 0];
+  if (version === 'preview') return [1, 0];
+
+  const match = version.match(/^v(\d+)(?:\D|$)/);
+  if (match) {
+    // Negative value for descending sort within category
+    return [2, -parseInt(match[1], 10)];
+  }
+
+  // Unknown entries sort last, stable by version name
+  return [3, version];
+}
+
+/**
+ * Sort versions in the correct order:
+ * 1. latest
+ * 2. preview
+ * 3. v2, v1 (descending)
+ * 4. unknown entries (alphabetically)
+ */
+function sortVersions(versions) {
+  return versions.sort((a, b) => {
+    const [groupA, valueA] = sortKey(a.version);
+    const [groupB, valueB] = sortKey(b.version);
+
+    if (groupA !== groupB) return groupA - groupB;
+    if (valueA === valueB) return 0;
+    return valueA < valueB ? -1 : 1;
+  });
+}
+
+/**
+ * Merge existing and new versions, removing duplicates
+ */
+function mergeVersions(existingVersions, newVersions) {
+  if (!Array.isArray(existingVersions) || !Array.isArray(newVersions)) {
+    throw new Error('Both existing and new versions files must be a JSON array.');
+  }
+
+  const versionMap = new Map();
+
+  // Add existing versions
+  for (const version of existingVersions) {
+    if (!version || typeof version.version !== 'string') {
+      throw new Error('Invalid versions entry (missing string "version" property).');
+    }
+    versionMap.set(version.version, version);
+  }
+
+  // Add/update with new versions
+  for (const version of newVersions) {
+    if (!version || typeof version.version !== 'string') {
+      throw new Error('Invalid versions entry (missing string "version" property).');
+    }
+    versionMap.set(version.version, version);
+  }
+
+  const merged = Array.from(versionMap.values());
+  return sortVersions(merged);
+}
+
+/**
+ * Main execution
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length !== 3) {
+    console.error(
+      'Usage: merge-versions.mjs <existing-versions-file> <new-versions-file> <output-file>'
+    );
+    process.exit(1);
+  }
+
+  const [existingFile, newFile, outputFile] = args;
+
+  // Read existing versions
+  let existingVersions = [];
+  try {
+    const content = readFileSync(existingFile, 'utf-8');
+    existingVersions = JSON.parse(content);
+
+    if (!Array.isArray(existingVersions)) {
+      throw new Error('Existing versions.json must contain an array');
+    }
+
+    console.log(`Loaded ${existingVersions.length} existing versions`);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      console.log('No existing versions file found, starting fresh');
+    } else {
+      console.error('Error reading existing versions:', error.message);
+      process.exit(1);
+    }
+  }
+
+  // Read new versions
+  let newVersions = [];
+  try {
+    const content = readFileSync(newFile, 'utf-8');
+    newVersions = JSON.parse(content);
+
+    if (!Array.isArray(newVersions)) {
+      throw new Error('New versions.json must contain an array');
+    }
+
+    console.log(`Loaded ${newVersions.length} new versions to deploy`);
+  } catch (error) {
+    console.error('Error reading new versions:', error.message);
+    process.exit(1);
+  }
+
+  // Merge and sort
+  const mergedVersions = mergeVersions(existingVersions, newVersions);
+  console.log(`Merged result: ${mergedVersions.length} total versions`);
+  console.log('Version order:', mergedVersions.map(v => v.version).join(', '));
+
+  // Write output
+  try {
+    writeFileSync(outputFile, JSON.stringify(mergedVersions, null, 2));
+    console.log(`Successfully wrote merged versions to ${outputFile}`);
+  } catch (error) {
+    console.error('Error writing output:', error.message);
+    process.exit(1);
+  }
+}
+
+main();