rclnodejs 1.9.0 → 2.0.0-beta.0

package/tools/jsdoc/regenerate-published-docs.js

@@ -1,605 +0,0 @@
-// Copyright (c) 2026 The Robot Web Tools Contributors. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-'use strict';
-
-const childProcess = require('child_process');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const repoRoot = path.resolve(__dirname, '../..');
-const buildIndexScript = path.join(__dirname, 'build-index.js');
-const defaultOutputRoot = path.join(repoRoot, 'build', 'gh-pages-docs');
-const semverDirectoryPattern = /^\d+\.\d+\.\d+$/;
-const sharedAssetDirectoryName = '_static';
-const sharedAssetFolders = ['fonts', 'scripts', 'styles'];
-
-function parseArgs(argv) {
-  const options = {
-    branch: 'gh-pages',
-    outputRoot: defaultOutputRoot,
-    versions: null,
-    preservePublished: false,
-    fullRebuild: false,
-    keepWorktrees: false,
-  };
-
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-
-    if (arg === '--branch') {
-      options.branch = argv[index + 1];
-      index += 1;
-    } else if (arg === '--out') {
-      options.outputRoot = path.resolve(argv[index + 1]);
-      index += 1;
-    } else if (arg === '--versions') {
-      options.versions = argv[index + 1]
-        .split(',')
-        .map((value) => value.trim())
-        .filter(Boolean);
-      index += 1;
-    } else if (arg === '--preserve-published') {
-      options.preservePublished = true;
-    } else if (arg === '--full-rebuild') {
-      options.fullRebuild = true;
-    } else if (arg === '--keep-worktrees') {
-      options.keepWorktrees = true;
-    } else {
-      throw new Error(`Unknown argument: ${arg}`);
-    }
-  }
-
-  return options;
-}
-
-function runCommand(command, args, options = {}) {
-  try {
-    return childProcess.execFileSync(command, args, {
-      cwd: options.cwd || repoRoot,
-      encoding: 'utf8',
-      env: options.env || process.env,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-  } catch (error) {
-    const stderr = error.stderr ? String(error.stderr).trim() : '';
-    const stdout = error.stdout ? String(error.stdout).trim() : '';
-    const details = [stderr, stdout].filter(Boolean).join('\n');
-
-    throw new Error(
-      details
-        ? `${command} ${args.join(' ')}\n${details}`
-        : `${command} ${args.join(' ')} failed`
-    );
-  }
-}
-
-function compareVersionsAsc(left, right) {
-  const leftParts = left.split('.').map(Number);
-  const rightParts = right.split('.').map(Number);
-  const maxLength = Math.max(leftParts.length, rightParts.length);
-
-  for (let index = 0; index < maxLength; index += 1) {
-    const leftValue = leftParts[index] || 0;
-    const rightValue = rightParts[index] || 0;
-
-    if (leftValue !== rightValue) {
-      return leftValue - rightValue;
-    }
-  }
-
-  return 0;
-}
-
-function getPublishedVersions(branch) {
-  const output = runCommand('git', [
-    'ls-tree',
-    '--name-only',
-    `${branch}:docs`,
-  ]);
-
-  return output
-    .split(/\r?\n/)
-    .map((entry) => entry.trim())
-    .filter((entry) => semverDirectoryPattern.test(entry))
-    .sort(compareVersionsAsc);
-}
-
-function getTaggedReleaseVersions() {
-  return runCommand('git', ['tag', '--list'])
-    .split(/\r?\n/)
-    .map((entry) => entry.trim())
-    .filter((entry) => semverDirectoryPattern.test(entry))
-    .sort(compareVersionsAsc);
-}
-
-function getCurrentWorkspaceVersion() {
-  const packageInfo = JSON.parse(
-    fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')
-  );
-
-  if (!semverDirectoryPattern.test(packageInfo.version)) {
-    throw new Error(
-      `Current package.json version is not a release semver: ${packageInfo.version}`
-    );
-  }
-
-  return packageInfo.version;
-}
-
-function assertTagsExist(versions) {
-  const tags = new Set(getTaggedReleaseVersions());
-
-  const missing = versions.filter((version) => !tags.has(version));
-
-  if (missing.length) {
-    throw new Error(
-      `Missing Git tags for requested versions: ${missing.join(', ')}`
-    );
-  }
-}
-
-function ensureCleanOutput(outputRoot) {
-  fs.rmSync(outputRoot, { recursive: true, force: true });
-  fs.mkdirSync(path.join(outputRoot, 'docs'), { recursive: true });
-}
-
-function getGeneratedVersions(outputRoot) {
-  const docsRoot = path.join(outputRoot, 'docs');
-
-  if (!fs.existsSync(docsRoot)) {
-    return [];
-  }
-
-  return fs
-    .readdirSync(docsRoot, { withFileTypes: true })
-    .filter(
-      (entry) => entry.isDirectory() && semverDirectoryPattern.test(entry.name)
-    )
-    .map((entry) => entry.name)
-    .sort(compareVersionsAsc);
-}
-
-function writeBranchFile(branch, sourcePath, destinationPath) {
-  try {
-    const contents = runCommand('git', ['show', `${branch}:${sourcePath}`]);
-    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-    fs.writeFileSync(destinationPath, contents, 'utf8');
-  } catch (error) {
-    if (sourcePath === '.nojekyll') {
-      fs.writeFileSync(destinationPath, '', 'utf8');
-      return;
-    }
-
-    throw error;
-  }
-}
-
-function appendJsFiles(directoryPath, inputs) {
-  if (!fs.existsSync(directoryPath)) {
-    return;
-  }
-
-  fs.readdirSync(directoryPath, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.js'))
-    .sort((left, right) => left.name.localeCompare(right.name))
-    .forEach((entry) => {
-      inputs.push(path.join(directoryPath, entry.name));
-    });
-}
-
-function getJsdocInputs(sourceRoot) {
-  const inputs = [];
-  const indexPath = path.join(sourceRoot, 'index.js');
-
-  if (fs.existsSync(indexPath)) {
-    inputs.push(indexPath);
-  }
-
-  appendJsFiles(path.join(sourceRoot, 'lib'), inputs);
-  appendJsFiles(path.join(sourceRoot, 'lib', 'action'), inputs);
-
-  if (!inputs.length) {
-    throw new Error(`No JSDoc input files found for ${sourceRoot}`);
-  }
-
-  return inputs;
-}
-
-function sanitizePathSegment(value) {
-  return value.replace(/[^a-zA-Z0-9._-]/g, '_');
-}
-
-function addWorktree(ref, tempRoot, directoryName = ref) {
-  const worktreePath = path.join(tempRoot, sanitizePathSegment(directoryName));
-
-  runCommand('git', [
-    'worktree',
-    'add',
-    '--detach',
-    '--force',
-    worktreePath,
-    ref,
-  ]);
-
-  return worktreePath;
-}
-
-function removeWorktree(worktreePath, keepWorktrees) {
-  if (keepWorktrees) {
-    return;
-  }
-
-  try {
-    runCommand('git', ['worktree', 'remove', '--force', worktreePath]);
-  } catch {
-    fs.rmSync(worktreePath, { recursive: true, force: true });
-  }
-}
-
-function writeIndexPackage(packageJsonPath, outputRoot) {
-  const packageInfo = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-  const trimmedPackageInfo = {
-    name: packageInfo.name,
-    version: packageInfo.version,
-    repository: packageInfo.repository,
-  };
-  const destinationPath = path.join(outputRoot, '_index-package.json');
-
-  fs.writeFileSync(
-    destinationPath,
-    `${JSON.stringify(trimmedPackageInfo, null, 2)}\n`,
-    'utf8'
-  );
-
-  return destinationPath;
-}
-
-function copyIfExists(sourcePath, destinationPath) {
-  if (!fs.existsSync(sourcePath)) {
-    return;
-  }
-
-  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-  fs.cpSync(sourcePath, destinationPath, { recursive: true, force: true });
-}
-
-function copyDirectoryContents(sourceDir, destinationDir) {
-  if (!fs.existsSync(sourceDir)) {
-    return;
-  }
-
-  fs.mkdirSync(destinationDir, { recursive: true });
-
-  fs.readdirSync(sourceDir, { withFileTypes: true }).forEach((entry) => {
-    fs.cpSync(
-      path.join(sourceDir, entry.name),
-      path.join(destinationDir, entry.name),
-      { recursive: true, force: true }
-    );
-  });
-}
-
-function copyPublishedSnapshot(branch, outputRoot, tempRoot, keepWorktrees) {
-  const worktreePath = addWorktree(branch, tempRoot, `branch-${branch}`);
-  const rootFiles = ['.nojekyll', 'README.md', '_index-package.json'];
-
-  try {
-    copyDirectoryContents(
-      path.join(worktreePath, 'docs'),
-      path.join(outputRoot, 'docs')
-    );
-
-    rootFiles.forEach((fileName) => {
-      copyIfExists(
-        path.join(worktreePath, fileName),
-        path.join(outputRoot, fileName)
-      );
-    });
-  } finally {
-    removeWorktree(worktreePath, keepWorktrees);
-  }
-}
-
-function buildVersionDocs(version, outputDocsRoot, tempRoot, keepWorktrees) {
-  const worktreePath = addWorktree(version, tempRoot, version);
-
-  try {
-    const inputs = getJsdocInputs(worktreePath);
-
-    runCommand(
-      'npx',
-      [
-        'jsdoc',
-        '--package',
-        path.join(worktreePath, 'package.json'),
-        ...inputs,
-        '-t',
-        __dirname,
-        '-d',
-        outputDocsRoot,
-      ],
-      { cwd: repoRoot }
-    );
-
-    return {
-      worktreePath,
-      packageJsonPath: path.join(worktreePath, 'package.json'),
-    };
-  } catch (error) {
-    removeWorktree(worktreePath, keepWorktrees);
-    throw error;
-  }
-}
-
-function buildDocsFromSourceRoot(sourceRoot, outputDocsRoot) {
-  const inputs = getJsdocInputs(sourceRoot);
-
-  runCommand(
-    'npx',
-    [
-      'jsdoc',
-      '--package',
-      path.join(sourceRoot, 'package.json'),
-      ...inputs,
-      '-t',
-      __dirname,
-      '-d',
-      outputDocsRoot,
-    ],
-    { cwd: repoRoot }
-  );
-
-  return {
-    packageJsonPath: path.join(sourceRoot, 'package.json'),
-  };
-}
-
-function buildDocsIndex(outputRoot, packageJsonPath) {
-  runCommand('node', [buildIndexScript], {
-    cwd: repoRoot,
-    env: {
-      ...process.env,
-      RCLNODEJS_DOCS_ROOT: path.join(outputRoot, 'docs'),
-      RCLNODEJS_DOCS_INDEX_PATH: path.join(outputRoot, 'docs', 'index.html'),
-      RCLNODEJS_LOCAL_INDEX_PATH: '',
-      RCLNODEJS_PACKAGE_JSON_PATH: packageJsonPath,
-      RCLNODEJS_GIT_CWD: repoRoot,
-    },
-  });
-}
-
-function removeTemporaryPublishArtifacts(outputRoot) {
-  ['README.md', '_index-package.json'].forEach((fileName) => {
-    fs.rmSync(path.join(outputRoot, fileName), { force: true });
-  });
-}
-
-function rewriteVersionHtmlToSharedAssets(versionRoot) {
-  fs.readdirSync(versionRoot, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.html'))
-    .forEach((entry) => {
-      const filePath = path.join(versionRoot, entry.name);
-      const original = fs.readFileSync(filePath, 'utf8');
-      const rewritten = original.replace(
-        /(href|src)="(styles|scripts)\//g,
-        '$1="../_static/$2/'
-      );
-
-      if (rewritten !== original) {
-        fs.writeFileSync(filePath, rewritten, 'utf8');
-      }
-    });
-}
-
-function hoistSharedAssets(outputRoot) {
-  const docsRoot = path.join(outputRoot, 'docs');
-  const versions = getGeneratedVersions(outputRoot);
-
-  if (!versions.length) {
-    return;
-  }
-
-  const sourceVersion = versions[versions.length - 1];
-  const sourceVersionRoot = path.join(docsRoot, sourceVersion);
-  const sharedRoot = path.join(docsRoot, sharedAssetDirectoryName);
-
-  fs.mkdirSync(sharedRoot, { recursive: true });
-
-  sharedAssetFolders.forEach((folderName) => {
-    fs.cpSync(
-      path.join(sourceVersionRoot, folderName),
-      path.join(sharedRoot, folderName),
-      { recursive: true, force: true }
-    );
-  });
-
-  versions.forEach((version) => {
-    const versionRoot = path.join(docsRoot, version);
-
-    rewriteVersionHtmlToSharedAssets(versionRoot);
-
-    sharedAssetFolders.forEach((folderName) => {
-      fs.rmSync(path.join(versionRoot, folderName), {
-        recursive: true,
-        force: true,
-      });
-    });
-  });
-}
-
-function ensureSharedAssetsForVersion(outputRoot, version) {
-  const docsRoot = path.join(outputRoot, 'docs');
-  const versionRoot = path.join(docsRoot, version);
-  const sharedRoot = path.join(docsRoot, sharedAssetDirectoryName);
-
-  if (!fs.existsSync(versionRoot)) {
-    return;
-  }
-
-  fs.mkdirSync(sharedRoot, { recursive: true });
-
-  sharedAssetFolders.forEach((folderName) => {
-    const sourcePath = path.join(versionRoot, folderName);
-
-    if (!fs.existsSync(sourcePath)) {
-      return;
-    }
-
-    fs.cpSync(sourcePath, path.join(sharedRoot, folderName), {
-      recursive: true,
-      force: true,
-    });
-  });
-
-  rewriteVersionHtmlToSharedAssets(versionRoot);
-
-  sharedAssetFolders.forEach((folderName) => {
-    fs.rmSync(path.join(versionRoot, folderName), {
-      recursive: true,
-      force: true,
-    });
-  });
-}
-
-function main() {
-  const options = parseArgs(process.argv.slice(2));
-
-  if (options.preservePublished && options.fullRebuild) {
-    throw new Error(
-      'Use either --preserve-published or --full-rebuild, not both.'
-    );
-  }
-
-  const publishedVersions = options.versions
-    ? options.versions
-    : getPublishedVersions(options.branch);
-  const currentVersion = getCurrentWorkspaceVersion();
-  const versions = Array.from(
-    new Set(publishedVersions.concat(currentVersion))
-  ).sort(compareVersionsAsc);
-
-  if (!versions.length) {
-    throw new Error(`No published versions found in ${options.branch}:docs`);
-  }
-
-  assertTagsExist(
-    publishedVersions.filter((version) => version !== currentVersion)
-  );
-  ensureCleanOutput(options.outputRoot);
-
-  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'rclnodejs-jsdoc-'));
-  const latestVersion = versions[versions.length - 1];
-  let latestPackageJsonPath = null;
-
-  try {
-    if (options.preservePublished) {
-      copyPublishedSnapshot(
-        options.branch,
-        options.outputRoot,
-        tempRoot,
-        options.keepWorktrees
-      );
-      console.log(
-        `Preserved ${publishedVersions.length} published versions from ${options.branch}.`
-      );
-    } else {
-      writeBranchFile(
-        options.branch,
-        '.nojekyll',
-        path.join(options.outputRoot, '.nojekyll')
-      );
-      writeBranchFile(
-        options.branch,
-        'README.md',
-        path.join(options.outputRoot, 'README.md')
-      );
-    }
-
-    console.log(`Regenerating ${versions.length} documentation versions.`);
-
-    if (!options.preservePublished || options.fullRebuild) {
-      publishedVersions.forEach((version) => {
-        if (version === currentVersion) {
-          return;
-        }
-
-        console.log(`- ${version}`);
-
-        const buildResult = buildVersionDocs(
-          version,
-          path.join(options.outputRoot, 'docs'),
-          tempRoot,
-          options.keepWorktrees
-        );
-
-        if (version === latestVersion) {
-          latestPackageJsonPath = writeIndexPackage(
-            buildResult.packageJsonPath,
-            options.outputRoot
-          );
-        }
-
-        removeWorktree(buildResult.worktreePath, options.keepWorktrees);
-      });
-    }
-
-    if (options.preservePublished && !options.fullRebuild) {
-      const existingIndexPackagePath = path.join(
-        options.outputRoot,
-        '_index-package.json'
-      );
-
-      if (fs.existsSync(existingIndexPackagePath)) {
-        latestPackageJsonPath = existingIndexPackagePath;
-      }
-    }
-
-    console.log(`- ${currentVersion} (current workspace)`);
-
-    const buildResult = buildDocsFromSourceRoot(
-      repoRoot,
-      path.join(options.outputRoot, 'docs')
-    );
-
-    if (currentVersion === latestVersion) {
-      latestPackageJsonPath = writeIndexPackage(
-        buildResult.packageJsonPath,
-        options.outputRoot
-      );
-    }
-
-    buildDocsIndex(
-      options.outputRoot,
-      latestPackageJsonPath || path.join(repoRoot, 'package.json')
-    );
-
-    if (options.preservePublished && !options.fullRebuild) {
-      ensureSharedAssetsForVersion(options.outputRoot, currentVersion);
-    } else {
-      hoistSharedAssets(options.outputRoot);
-    }
-
-    removeTemporaryPublishArtifacts(options.outputRoot);
-
-    console.log(`Published docs tree ready at ${options.outputRoot}`);
-  } finally {
-    if (!options.keepWorktrees) {
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  }
-}
-
-main();