chore: random touch-ups from #1159 (#1160)

## 🧰 Changes cherry-picking over a few random refactors from #1159 that are mostly unrelated to the PR itself: - [x] removes unused fixtures - [x] smol copy tweaks for changelog command ("syncing" is reserved for bidi, this is "uploading" - [x] jsdoc tweaks, including deprecating APIv1-related cruft - [x] various type enhancements - [x] renaming a few things - [x] adding `oclif`'s `this` context (so we can simplify functions and add better debug logs) ## 🧬 QA & Testing do tests still pass?
readmeio · Jan 31, 2025 · 2870c4b · 2870c4b
1 parent e4874fc
commit 2870c4b
Show file tree

Hide file tree

Showing 38 changed files with 153 additions and 184 deletions.
diff --git a/README.md b/README.md
@@ -170,7 +170,7 @@ npm run build && npm run build:docs
 # Command Topics
 
 * [`rdme autocomplete`](documentation/commands/autocomplete.md) - Display autocomplete installation instructions.
-* [`rdme changelogs`](documentation/commands/changelogs.md) - Sync Markdown files to your ReadMe project as Changelog posts.
+* [`rdme changelogs`](documentation/commands/changelogs.md) - Upload Markdown files to your ReadMe project as Changelog posts.
 * [`rdme help`](documentation/commands/help.md) - Display help for rdme.
 * [`rdme login`](documentation/commands/login.md) - Login to a ReadMe project.
 * [`rdme logout`](documentation/commands/logout.md) - Logs the currently authenticated user out of ReadMe.

diff --git a/__tests__/__fixtures__/custompages/existing-docs/not-a-markdown-file b/__tests__/__fixtures__/custompages/existing-docs/not-a-markdown-file
diff --git a/__tests__/__fixtures__/custompages/existing-docs/simple-doc.md b/__tests__/__fixtures__/custompages/existing-docs/simple-doc.md
diff --git a/__tests__/__fixtures__/custompages/existing-docs/subdir/another-doc.md b/__tests__/__fixtures__/custompages/existing-docs/subdir/another-doc.md
diff --git a/__tests__/__fixtures__/custompages/failure-docs/doc-sans-attributes.md b/__tests__/__fixtures__/custompages/failure-docs/doc-sans-attributes.md
diff --git a/__tests__/__fixtures__/custompages/failure-docs/new-doc.md b/__tests__/__fixtures__/custompages/failure-docs/new-doc.md
diff --git a/__tests__/__fixtures__/custompages/new-docs-html/new-doc.html b/__tests__/__fixtures__/custompages/new-docs-html/new-doc.html
diff --git a/__tests__/__fixtures__/custompages/new-docs/new-doc.md b/__tests__/__fixtures__/custompages/new-docs/new-doc.md
diff --git a/__tests__/__fixtures__/custompages/slug-docs/new-doc-slug.md b/__tests__/__fixtures__/custompages/slug-docs/new-doc-slug.md
diff --git a/__tests__/__fixtures__/docs/delete-docs/some-doc.md b/__tests__/__fixtures__/docs/delete-docs/some-doc.md
diff --git a/__tests__/__fixtures__/docs/docs-with-parent-ids/child.md b/__tests__/__fixtures__/docs/docs-with-parent-ids/child.md
diff --git a/__tests__/__fixtures__/docs/docs-with-parent-ids/friend.md b/__tests__/__fixtures__/docs/docs-with-parent-ids/friend.md
diff --git a/__tests__/__fixtures__/docs/docs-with-parent-ids/parent.md b/__tests__/__fixtures__/docs/docs-with-parent-ids/parent.md
diff --git a/__tests__/__fixtures__/docs/docs-with-parent-ids/with-parent-doc.md b/__tests__/__fixtures__/docs/docs-with-parent-ids/with-parent-doc.md
diff --git a/__tests__/__fixtures__/docs/failure-docs/doc-sans-attributes.md b/__tests__/__fixtures__/docs/failure-docs/doc-sans-attributes.md
diff --git a/__tests__/__fixtures__/docs/failure-docs/new-doc.md b/__tests__/__fixtures__/docs/failure-docs/new-doc.md
diff --git a/__tests__/__fixtures__/docs/multiple-docs-cycle/child.md b/__tests__/__fixtures__/docs/multiple-docs-cycle/child.md
diff --git a/__tests__/__fixtures__/docs/multiple-docs-cycle/grandparent.md b/__tests__/__fixtures__/docs/multiple-docs-cycle/grandparent.md
diff --git a/__tests__/__fixtures__/docs/multiple-docs-cycle/parent.md b/__tests__/__fixtures__/docs/multiple-docs-cycle/parent.md
diff --git a/__tests__/__fixtures__/docs/multiple-docs-no-parents/child.md b/__tests__/__fixtures__/docs/multiple-docs-no-parents/child.md
diff --git a/__tests__/__fixtures__/docs/multiple-docs-no-parents/friend.md b/__tests__/__fixtures__/docs/multiple-docs-no-parents/friend.md
diff --git a/__tests__/helpers/get-gha-setup.ts b/__tests__/helpers/get-gha-setup.ts
@@ -13,10 +13,12 @@ import getGitRemoteMock from './get-git-mock.js';
 /**
  * A helper function for setting up tests for our GitHub Action onboarding.
  *
- * @param writeFileSyncCb the mock function that should be called in place of `fs.writeFileSync`.
  * @see {@link __tests__/lib/createGHA.test.ts}
  */
-export function before(writeFileSyncCb) {
+export function before(
+  /** the mock function that should be called in place of `fs.writeFileSync` */
+  writeFileSyncCb: typeof fs.writeFileSync,
+) {
   fs.writeFileSync = vi.fn(writeFileSyncCb);
 
   git.checkIsRepo = vi.fn(() => {

diff --git a/__tests__/helpers/get-git-mock.ts b/__tests__/helpers/get-git-mock.ts
@@ -4,14 +4,13 @@ import { vi } from 'vitest';
 
 /**
  * Creates a mock function for testing `git.remote`.
- *
- * @param remote remote to return (usually `origin`)
- * @param remoteUrl git URL for the given remote
- * @param defaultBranch the HEAD branch
  */
 export default function getGitRemoteMock(
+  /** remote to return (usually `origin`) */
   remote = 'origin',
+  /** git URL for the given remote */
   remoteUrl = 'https://github.com/readmeio/rdme.git',
+  /** the HEAD branch */
   defaultBranch = 'main',
 ) {
   return vi.fn(arr => {

diff --git a/__tests__/helpers/oclif.ts b/__tests__/helpers/oclif.ts
@@ -1,4 +1,4 @@
-import type { Command as OclifCommand } from '@oclif/core';
+import type { CommandClass } from '../../src/index.js';
 
 import path from 'node:path';
 
@@ -36,7 +36,7 @@ export function setupOclifConfig() {
  *
  * @example runCommand(LoginCommand)(['--email', '[email protected]', '--password', 'password'])
  */
-export function runCommand<T extends typeof OclifCommand>(Command: T) {
+export function runCommand(Command: CommandClass) {
   return async function runCommandAgainstArgs(args?: string[]) {
     const oclifConfig = await setupOclifConfig();
     // @ts-expect-error this is the pattern recommended by the @oclif/test docs.
@@ -52,7 +52,7 @@ export function runCommand<T extends typeof OclifCommand>(Command: T) {
  *
  * @example runCommandAndReturnResult(LoginCommand)(['--email', '[email protected]', '--password', 'password'])
  */
-export function runCommandAndReturnResult<T extends typeof OclifCommand>(Command: T) {
+export function runCommandAndReturnResult(Command: CommandClass) {
   return async function runCommandAgainstArgs(args?: string[]) {
     const { error, result } = await runCommand(Command)(args);
     if (error) {

diff --git a/documentation/commands/changelogs.md b/documentation/commands/changelogs.md
@@ -1,13 +1,13 @@
 `rdme changelogs`
 =================
 
-Sync Markdown files to your ReadMe project as Changelog posts.
+Upload Markdown files to your ReadMe project as Changelog posts.
 
 * [`rdme changelogs PATH`](#rdme-changelogs-path)
 
 ## `rdme changelogs PATH`
 
-Sync Markdown files to your ReadMe project as Changelog posts.
+Upload Markdown files to your ReadMe project as Changelog posts.
 
 ```
 USAGE
@@ -22,14 +22,14 @@ FLAGS
   --key=<value>  (required) ReadMe project API key
 
 DESCRIPTION
-  Sync Markdown files to your ReadMe project as Changelog posts.
+  Upload Markdown files to your ReadMe project as Changelog posts.
 
   Syncs Markdown files to the Changelog section of your ReadMe project. The path can either be a directory or a single
   Markdown file. The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check
   out our docs for more info on setting up your front matter: https://docs.readme.com/main/docs/rdme#markdown-file-setup
 
 EXAMPLES
-  Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. The path
+  Passing in a path to a directory will also upload any Markdown files that are located in subdirectories. The path
   input can also be individual Markdown files:
 
     $ rdme changelogs [path] --version={project-version}

diff --git a/src/commands/changelogs.ts b/src/commands/changelogs.ts
@@ -11,7 +11,7 @@ export default class ChangelogsCommand extends BaseCommand<typeof ChangelogsComm
   // needed for unit tests, even though we also specify this in src/index.ts
   static id = 'changelogs' as const;
 
-  static summary = 'Sync Markdown files to your ReadMe project as Changelog posts.';
+  static summary = 'Upload Markdown files to your ReadMe project as Changelog posts.';
 
   static description =
     'Syncs Markdown files to the Changelog section of your ReadMe project. The path can either be a directory or a single Markdown file. The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter: https://docs.readme.com/main/docs/rdme#markdown-file-setup';
@@ -23,7 +23,7 @@ export default class ChangelogsCommand extends BaseCommand<typeof ChangelogsComm
   static examples = [
     {
       description:
-        'Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. The path input can also be individual Markdown files:',
+        'Passing in a path to a directory will also upload any Markdown files that are located in subdirectories. The path input can also be individual Markdown files:',
       command: '<%= config.bin %> <%= command.id %> [path] --version={project-version}',
     },
     {

diff --git a/src/index.ts b/src/index.ts
@@ -1,3 +1,5 @@
+import type { ValueOf } from 'type-fest';
+
 import ChangelogsCommand from './commands/changelogs.js';
 import LoginCommand from './commands/login.js';
 import LogoutCommand from './commands/logout.js';
@@ -36,6 +38,8 @@ export const COMMANDS = {
   whoami: WhoAmICommand,
 };
 
+export type CommandClass = ValueOf<typeof COMMANDS>;
+
 /**
  * A type-safe way to get the command IDs in the CLI for a specific topic.
  *

diff --git a/src/lib/apiError.ts b/src/lib/apiError.ts
@@ -31,6 +31,8 @@ export type APIv2ErrorResponse = Partial<{
 
 /**
  * Error class for handling ReadMe API v1 errors.
+ *
+ * @deprecated Use {@link APIv2Error} instead.
  */
 export class APIv1Error extends Error {
   code: string;

diff --git a/src/lib/createGHA/index.ts b/src/lib/createGHA/index.ts
@@ -22,9 +22,11 @@ type ParsedOpts = Record<string, unknown>;
 
 /**
  * Generates the key for storing info in `configstore` object.
- * @param repoRoot The root of the repo
  */
-export const getConfigStoreKey = (repoRoot: string) => `createGHA.${repoRoot}`;
+export const getConfigStoreKey = (
+  /** the root of the repository */
+  repoRoot: string,
+) => `createGHA.${repoRoot}`;
 /**
  * The directory where GitHub Actions workflow files are stored.
  *
@@ -40,9 +42,11 @@ export const git = simpleGit();
 /**
  * Removes any non-file-friendly characters and adds
  * the full path + file extension for GitHub Workflow files.
- * @param fileName raw file name to clean up
  */
-export const getGHAFileName = (fileName: string) => {
+export const getGHAFileName = (
+  /** raw file name to clean up */
+  fileName: string,
+) => {
   return path.join(GITHUB_WORKFLOW_DIR, `${cleanFileName(fileName).toLowerCase()}.yml`);
 };
 

diff --git a/src/lib/getPkg.ts b/src/lib/getPkg.ts
@@ -51,14 +51,19 @@ export function getPkgVersion(this: Hook.Context | void): string {
 /**
  * The current `rdme` version
  *
- * @param npmDistTag the `npm` dist tag to retrieve. If this value is omitted,
- * the version from the `package.json` is returned.
  * @example "8.0.0"
  * @see {@link https://docs.npmjs.com/adding-dist-tags-to-packages}
  * @note we mock this function in our snapshots
  * @see {@link https://stackoverflow.com/a/54245672}
  */
-export async function getPkgVersionFromNPM(this: Hook.Context | void, npmDistTag?: npmDistTag): Promise<string> {
+export async function getPkgVersionFromNPM(
+  this: Hook.Context | void,
+  /**
+   * The `npm` dist tag to retrieve. If this value is omitted,
+   * the version from the `package.json` is returned.
+   */
+  npmDistTag?: npmDistTag,
+): Promise<string> {
   if (npmDistTag) {
     return fetch(registryUrl)
       .then(res => res.json() as Promise<{ 'dist-tags': Record<string, string> }>)

diff --git a/src/lib/logger.ts b/src/lib/logger.ts
@@ -65,10 +65,15 @@ function oraOptions() {
 
 /**
  * Wrapper for warn statements.
- * @param prefix Text that precedes the warning.
- * This is *not* used in the GitHub Actions-formatted warning.
  */
-function warn(input: string, prefix = 'Warning!') {
+function warn(
+  /**
+   * Text that precedes the warning.
+   * This is *not* used in the GitHub Actions-formatted warning.
+   */
+  input: string,
+  prefix = 'Warning!',
+) {
   /* istanbul ignore next */
   if (isGHA() && !isTest()) return core.warning(input);
   // eslint-disable-next-line no-console

diff --git a/src/lib/loginFlow.ts b/src/lib/loginFlow.ts
@@ -27,11 +27,16 @@ function loginFetch(body: LoginBody) {
  * The prompt flow for logging a user in and writing the credentials to
  * `configstore`. This is a separate lib function because we reuse it both
  * in the `login` command as well as any time a user omits an API key.
- * @param otp an optional one-time passcode, if the user passes one in
- * via a flag to the the `login` command
+ *
  * @returns A Promise-wrapped string with the logged-in user's credentials
  */
-export default async function loginFlow(otp?: string) {
+export default async function loginFlow(
+  /**
+   * An optional one-time passcode, if the user passes one in
+   * via a flag to the the `login` command
+   */
+  otp?: string,
+) {
   const storedConfig = getCurrentConfig();
   const { email, password, project } = await promptTerminal([
     {

diff --git a/src/lib/prepareOas.ts b/src/lib/prepareOas.ts
@@ -44,14 +44,17 @@ const capitalizeSpecType = (type: string) =>
 
 /**
  * Normalizes, validates, and (optionally) bundles an OpenAPI definition.
- *
- * @param path Path to a spec file. If this is missing, the current directory is searched for
- *    certain file names.
- * @param command The command context in which this is being run within (uploading a spec,
- *    validation, or reducing one).
  */
 export default async function prepareOas(
+  /**
+   * Path to a spec file. If this is missing, the current directory is searched for
+   * certain file names.
+   */
   path: string | undefined,
+  /**
+   * The command context in which this is being run within (uploading a spec,
+   * validation, or reducing one).
+   */
   command: `openapi ${OpenAPIAction}`,
   opts: {
     /**