feat(docs/migrate): add ability to unzip archives (#1226)

| 🚥 Resolves RM-12508 |
| :------------------- |

## 🧰 Changes

- [x] add auto-detection(ish) of zip files and unzips them before
sending that data to plugin hook
- [x] enhances our `pre_markdown_file_scan` hook to now send data about
the unzip results
- [x] adds a bunch of JSDocs for our exported functions/types

## 🧬 QA & Testing

this isn't a ton of logic but it could definitely use a test or two.
will do a more comprehensive pass of tests in follow-up PRs later this
week.

Author: kanadgupta

package-lock.json

@@ -75,6 +75,7 @@
     "tmp-promise": "^3.0.3",
     "toposort": "^2.0.2",
     "undici": "^5.28.4",
+    "unzipper": "^0.12.3",
     "validator": "^13.7.0"
   },
   "devDependencies": {
@@ -95,6 +96,7 @@
     "@types/prompts": "^2.4.2",
     "@types/semver": "^7.3.12",
     "@types/toposort": "^2.0.7",
+    "@types/unzipper": "^0.10.11",
     "@types/validator": "^13.7.6",
     "@vitest/coverage-v8": "^3.0.0",
     "@vitest/expect": "^3.0.0",

package.json

@@ -12,6 +12,7 @@ import { oraOptions } from '../../lib/logger.js';
 import promptTerminal from '../../lib/promptWrapper.js';
 import { fetchMappings, fetchSchema } from '../../lib/readmeAPIFetch.js';
 import { findPages } from '../../lib/readPage.js';
+import { attemptUnzip } from '../../lib/unzip.js';
 
 const alphaNotice = 'This command is in an experimental alpha and is likely to change. Use at your own risk!';
 
@@ -47,12 +48,13 @@ export default class DocsMigrateCommand extends BaseCommand<typeof DocsMigrateCo
 
     const outputDir = rawOutputDir || (await dir({ prefix: 'rdme-migration-output' })).path;
 
-    let pathInput = rawPathInput;
+    const zipResults = await attemptUnzip(rawPathInput);
+    let { pathInput } = zipResults;
 
     // todo: fix this type once https://github.com/oclif/core/pull/1359 is merged
     const fileScanHookResults: Hook.Result<PluginHooks['pre_markdown_file_scan']['return']> = await this.config.runHook(
       'pre_markdown_file_scan',
-      { pathInput },
+      zipResults,
     );
 
     fileScanHookResults.successes.forEach(success => {

src/commands/docs/migrate.ts

@@ -14,6 +14,14 @@ import { handleAPIv2Res, readmeAPIv2Fetch, type ResponseBody } from './readmeAPI
 type Flags<T extends typeof OclifCommand> = Interfaces.InferredFlags<(typeof BaseCommand)['baseFlags'] & T['flags']>;
 type Args<T extends typeof OclifCommand> = Interfaces.InferredArgs<T['args']>;
 
+/**
+ * This is a light wrapper around the oclif command class that adds some
+ * additional functionality and standardizes the way we handle logging, error handling,
+ * and API requests.
+ *
+ * @note This class is not meant to be used directly, but rather as a base class for other commands.
+ * It is also experimental and may change in the future.
+ */
 export default abstract class BaseCommand<T extends typeof OclifCommand> extends OclifCommand {
   constructor(argv: string[], config: Config) {
     super(argv, config);

src/lib/baseCommand.ts

@@ -1,20 +1,80 @@
 import type { PageMetadata } from '../readPage.js';
 import type { Hooks } from '@oclif/core/interfaces';
 
+interface MarkdownFileScanResultOptsBase {
+  // required for the oclif hook types
+  [key: string]: unknown;
+  /**
+   * The path to the input file or directory as passed to the command line.
+   */
+  pathInput: string;
+  /**
+   * Whether or not the path input is a zip file.
+   */
+  zipped: boolean;
+}
+
+interface MarkdownFileScanResultOptsZipped extends MarkdownFileScanResultOptsBase {
+  /**
+   * The path to the temporary directory where the zip file was unzipped.
+   * This is only present if the input file was a zip file.
+   */
+  unzippedDir: string;
+  zipped: true;
+}
+
+interface MarkdownFileScanResultOptsUnzipped extends MarkdownFileScanResultOptsBase {
+  zipped: false;
+}
+
 /**
+ * The options passed to the `pre_markdown_file_scan` hook.
+ */
+export type MarkdownFileScanResultOpts = MarkdownFileScanResultOptsUnzipped | MarkdownFileScanResultOptsZipped;
+
+/**
+ * Hooks for usage in `rdme` plugins that invoke the `docs migrate` command.
+ *
  * @note These hooks are under active development for internal usage and are subject to change.
  */
 export interface PluginHooks extends Hooks {
+  /**
+   * This hook is called before the Markdown files are searched for with the path input argument.
+   * If the path input is a zip file, it will be unzipped to a temporary directory.
+   *
+   * It can be used to modify the path input to point to a different directory or file.
+   *
+   * For example, say the user wants to upload a zip file. This hook can be used to
+   * set the working directory to a subdirectory within the unzipped contents.
+   */
   pre_markdown_file_scan: {
-    options: {
-      pathInput: string;
-    };
+    options: MarkdownFileScanResultOpts;
+
+    /**
+     * The new directory to scan for Markdown files. If `null` is returned,
+     * this means the original path input will be used.
+     */
     return: string | null;
   };
+
+  /**
+   * This hook is called after the Markdown files are scanned and before they are validated.
+   * It can be used to modify the list of pages that will be validated.
+   *
+   * For example, this hook can be used to add or remove pages
+   * (or to modify the content/frontmatter of an existing page)
+   * from the list of pages that were found in the input directory.
+   */
   pre_markdown_validation: {
     options: {
+      /**
+       * The list of pages that were found in the input directory.
+       */
       pages: PageMetadata[];
     };
+    /**
+     * The list of pages that will be validated and written to the output directory.
+     */
     return: PageMetadata[];
   };
 }

src/lib/hooks/exported.ts

@@ -13,6 +13,11 @@ import ora from 'ora';
 import { oraOptions } from './logger.js';
 import readdirRecursive from './readdirRecursive.js';
 
+/**
+ * The metadata for a page once it has been read.
+ * This includes the Markdown contents of the file, the parsed frontmatter data,
+ * the file path, and the derived slug.
+ */
 export interface PageMetadata<T = Record<string, unknown>> {
   /**
    * The contents of the Markdown file below the YAML frontmatter

src/lib/readPage.ts

@@ -57,6 +57,9 @@ export interface Mappings {
   parentPages: Record<string, string>;
 }
 
+/**
+ * A generic response body type for responses from the ReadMe API.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface ResponseBody extends Record<string, any> {}
 

src/lib/readmeAPIFetch.ts

@@ -31,6 +31,14 @@ export type GuidesRequestRepresentation = FromSchema<
   { keepDefaultedPropertiesOptional: true }
 >;
 
+/**
+ * Derived from our API documentation, this is the schema for the `project` object
+ * as we receive it to the ReadMe API.
+ */
 export type ProjectRepresentation = FromSchema<projectSchema, { keepDefaultedPropertiesOptional: true }>;
 
+/**
+ * Derived from our API documentation, this is the schema for the API key object
+ * as we receive it to the ReadMe API.
+ */
 export type APIKeyRepresentation = FromSchema<apiKeySchema, { keepDefaultedPropertiesOptional: true }>;