feat(bin): add migrate option (#76)

README.md

@@ -48,9 +48,10 @@ You can provider all options through CLI flags.
 Usage: typedoc-json-parser [options]
 
 Options:
-  -j, --json <path>  Path to the TypeDoc JSON output file.
-  -v, --verbose      Print verbose information (default: false)
-  -h, --help         display help for command
+  --json [path]     Path to the TypeDoc JSON output file to parse
+  --migrate [path]  Path to the directory containing TypeDoc JSON Parser output files to migrate
+  -v, --verbose     Print verbose information (default: false)
+  -h, --help        display help for command
 ```
 
 You can also set these options through a configuration file. This file should be located at your [current working directory](https://nodejs.org/api/process.html#processcwd). It should be named `.typedoc-json-parserrc`, optionally suffixed with `.json`, `.yml`, or `.yaml`.

package.json

@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@favware/colorette-spinner": "^1.0.1",
+    "@sapphire/node-utilities": "^1.0.0",
     "colorette": "^2.0.19",
     "commander": "^9.4.1",
     "js-yaml": "^4.1.0",

src/bin/commands/migrate-docs.ts

@@ -0,0 +1,40 @@
+import { Spinner } from '@favware/colorette-spinner';
+import { findFilesRecursivelyStringEndsWith } from '@sapphire/node-utilities';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { migrateProject } from '../lib/migrations';
+import type { Options } from '../lib/types/Options';
+import type { RequiredExcept } from '../lib/types/RequiredExcept';
+
+export async function migrateDocs(options: RequiredExcept<Options, 'json'>) {
+  const spinner = new Spinner().start({ text: 'Migrating TypeDoc JSON Parser output files' });
+
+  try {
+    const directory = resolve(process.cwd(), options.migrate);
+    let migratedFiles = 0;
+
+    for await (const path of findFilesRecursivelyStringEndsWith(directory, '.json')) {
+      const data = JSON.parse(await readFile(path, 'utf-8'));
+
+      if ('typeDocJsonParserVersion' in data) {
+        const migrated = migrateProject(data);
+
+        if (migrated) {
+          await writeFile(path, JSON.stringify(migrated, null, 2), 'utf-8');
+
+          migratedFiles++;
+        }
+      }
+    }
+
+    spinner.success({ text: `Migrated ${migratedFiles} TypeDoc JSON Parser output files` });
+  } catch (error) {
+    const cause = error as Error;
+
+    spinner.error({ text: 'Failed to migrate TypeDoc JSON Parser output' });
+
+    if (options.verbose) console.log(cause.stack ?? cause.message);
+
+    process.exit(1);
+  }
+}

src/bin/commands/parse-docs.ts

@@ -5,26 +5,28 @@ import { resolve } from 'node:path';
 import type { JSONOutput } from 'typedoc';
 import { ProjectParser } from '../../lib/structures/ProjectParser';
 import type { Options } from '../lib/types/Options';
+import type { RequiredExcept } from '../lib/types/RequiredExcept';
 
-export async function parseDocs(options: Options) {
-  const spinner = new Spinner().start({ text: 'Parsing TypeDoc JSON output' });
-  const { version } = JSON.parse(await readFile(resolve(process.cwd(), 'package.json'), 'utf8'));
-  const readme = existsSync(resolve(process.cwd(), 'README.md')) ? await readFile(resolve(process.cwd(), 'README.md'), 'utf8') : undefined;
-  const changelog = existsSync(resolve(process.cwd(), 'CHANGELOG.md')) ? await readFile(resolve(process.cwd(), 'CHANGELOG.md'), 'utf8') : undefined;
-  const data = JSON.parse(await readFile(resolve(process.cwd(), options.json), 'utf-8')) as JSONOutput.ProjectReflection;
-  const parsed = new ProjectParser({ data, version, readme, changelog }).toJSON();
+export async function parseDocs(options: RequiredExcept<Options, 'migrate'>) {
+  const spinner = new Spinner().start({ text: 'Parsing TypeDoc JSON output file' });
 
   try {
+    const { version } = JSON.parse(await readFile(resolve(process.cwd(), 'package.json'), 'utf8'));
+    const readme = existsSync(resolve(process.cwd(), 'README.md')) ? await readFile(resolve(process.cwd(), 'README.md'), 'utf8') : undefined;
+    const changelog = existsSync(resolve(process.cwd(), 'CHANGELOG.md')) ? await readFile(resolve(process.cwd(), 'CHANGELOG.md'), 'utf8') : undefined;
+    const data = JSON.parse(await readFile(resolve(process.cwd(), options.json), 'utf-8')) as JSONOutput.ProjectReflection;
+    const parsed = new ProjectParser({ data, version, readme, changelog }).toJSON();
+
     await writeFile(resolve(process.cwd(), options.json), JSON.stringify(parsed, null, 2));
+
+    spinner.success({ text: 'Parsed TypeDoc JSON output file' });
   } catch (error) {
     const cause = error as Error;
 
-    spinner.error({ text: 'Failed to parse TypeDoc JSON output' });
+    spinner.error({ text: 'Failed to parse TypeDoc JSON output file' });
 
     if (options.verbose) console.log(cause.stack ?? cause.message);
 
     process.exit(1);
   }
-
-  spinner.success({ text: 'Parsed TypeDoc JSON output' });
 }

src/bin/index.ts

@@ -1,31 +1,41 @@
 #!/usr/bin/env node
 
+import { bold, red } from 'colorette';
 import { Command } from 'commander';
 import { buildDocs } from './commands/build-docs';
 import { checkRepository } from './commands/check-repository';
+import { migrateDocs } from './commands/migrate-docs';
 import { parseDocs } from './commands/parse-docs';
 import { parseOptions } from './lib/parseOptions';
 import type { Options } from './lib/types/Options';
+import type { RequiredExcept } from './lib/types/RequiredExcept';
 
 async function run() {
   const command = new Command()
-    .option('-j, --json <path>', 'Path to the TypeDoc JSON output file.')
+    .option('--json [path]', 'Path to the TypeDoc JSON output file to parse')
+    .option('--migrate [path]', 'Path to the directory containing TypeDoc JSON Parser output files to migrate')
     .option('-v, --verbose', 'Print verbose information', false);
 
   const program = command.parse(process.argv);
   const options = await parseOptions(program.opts<Partial<Options>>());
 
   if (options.verbose) console.log(`Resolved Options:`, options);
-  if (!Reflect.has(options, 'json')) throw new Error('Missing required option: --json');
+  if (!Reflect.has(options, 'json') && !Reflect.has(options, 'migrate')) {
+    console.error(red(`${bold('[ERROR]')} You must specify either the --json or --migrate option`));
+  }
 
   // Check if the current working directory is a Node.js repository.
   await checkRepository(options);
 
-  // Build the TypeDoc documentation.
-  await buildDocs(options);
+  if (options.migrate) {
+    await migrateDocs(options as RequiredExcept<Options, 'json'>);
+  } else if (options.json) {
+    // Build the TypeDoc documentation.
+    await buildDocs(options);
 
-  // Parse the TypeDoc JSON output.
-  await parseDocs(options);
+    // Parse the TypeDoc JSON output.
+    await parseDocs(options as RequiredExcept<Options, 'migrate'>);
+  }
 }
 
 void run();