feat(docs): adds ability to delete docs from ReadMe if they're no longer in local folder

README.md

@@ -204,6 +204,10 @@ rdme docs path-to-markdown-files --version={project-version}
 
 This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode).
 
+#### Deleting missing documents
+
+If you wish to delete documents from ReadMe that are no longer present in the directory, pass the `--deleteMissing` option to the command.
+
 #### Edit a Single ReadMe Doc on Your Local Machine
 
 ```sh

__tests__/cmds/docs/index.test.ts

@@ -374,6 +374,63 @@ describe('rdme docs', () => {
     });
   });
 
+  describe('delete docs', () => {
+    it('should delete doc if file is missing and --deleteMissing option is used', async () => {
+      const versionMock = getAPIMock()
+        .get(`/api/v1/version/${version}`)
+        .basicAuth({ user: key })
+        .reply(200, { version });
+      const apiMocks = getAPIMockWithVersionHeader(version)
+        .get('/api/v1/categories?perPage=20&page=1')
+        .basicAuth({ user: key })
+        .reply(200, [{ slug: 'category1', type: 'guide' }], { 'x-total-count': '1' })
+        .get('/api/v1/categories/category1/docs')
+        .basicAuth({ user: key })
+        .reply(200, [{ slug: 'thisDocShouldBeMissingInFolder' }])
+        .delete('/api/v1/docs/thisDocShouldBeMissingInFolder')
+        .basicAuth({ user: key })
+        .reply(204, '');
+      const folderWithoutDocs = './__tests__/__fixtures__/ref-oas';
+      await expect(
+        docs.run({
+          folder: folderWithoutDocs,
+          key,
+          version,
+          deleteMissing: true,
+        })
+      ).resolves.toBe('successfully deleted `thisDocShouldBeMissingInFolder`');
+
+      apiMocks.done();
+      versionMock.done();
+    });
+
+    it('should return doc delete info for dry run', async () => {
+      const versionMock = getAPIMock()
+        .get(`/api/v1/version/${version}`)
+        .basicAuth({ user: key })
+        .reply(200, { version });
+      const apiMocks = getAPIMockWithVersionHeader(version)
+        .get('/api/v1/categories?perPage=20&page=1')
+        .basicAuth({ user: key })
+        .reply(200, [{ slug: 'category1', type: 'guide' }], { 'x-total-count': '1' })
+        .get('/api/v1/categories/category1/docs')
+        .basicAuth({ user: key })
+        .reply(200, [{ slug: 'thisDocShouldBeMissingInFolder' }]);
+      const folderWithoutDocs = './__tests__/__fixtures__/ref-oas';
+      await expect(
+        docs.run({
+          folder: folderWithoutDocs,
+          key,
+          version,
+          deleteMissing: true,
+          dryRun: true,
+        })
+      ).resolves.toBe('🎭 dry run! This will delete `thisDocShouldBeMissingInFolder`');
+      apiMocks.done();
+      versionMock.done();
+    });
+  });
+
   describe('slug metadata', () => {
     it('should use provided slug', async () => {
       const slug = 'new-doc-slug';

src/cmds/docs/index.ts

@@ -4,13 +4,17 @@ import chalk from 'chalk';
 import config from 'config';
 
 import Command, { CommandCategories } from '../../lib/baseCommand';
+import deleteDoc from '../../lib/deleteDoc';
+import getDocs from '../../lib/getDocs';
+import getSlug from '../../lib/getSlug';
 import pushDoc from '../../lib/pushDoc';
 import readdirRecursive from '../../lib/readdirRecursive';
 import { getProjectVersion } from '../../lib/versionSelect';
 
 export type Options = {
   dryRun?: boolean;
   folder?: string;
+  deleteMissing?: boolean;
 };
 
 export default class DocsCommand extends Command {
@@ -41,13 +45,18 @@ export default class DocsCommand extends Command {
         type: Boolean,
         description: 'Runs the command without creating/updating any docs in ReadMe. Useful for debugging.',
       },
+      {
+        name: 'deleteMissing',
+        type: Boolean,
+        description: "Delete a doc from ReadMe if its slug can't be found in the target folder.",
+      },
     ];
   }
 
   async run(opts: CommandOptions<Options>) {
     super.run(opts);
 
-    const { dryRun, folder, key, version } = opts;
+    const { dryRun, folder, key, version, deleteMissing } = opts;
 
     if (!folder) {
       return Promise.reject(new Error(`No folder provided. Usage \`${config.get('cli')} ${this.usage}\`.`));
@@ -67,7 +76,17 @@ export default class DocsCommand extends Command {
 
     Command.debug(`number of files: ${files.length}`);
 
-    if (!files.length) {
+    const changes: string[] = [];
+    if (deleteMissing) {
+      const docs = await getDocs(key, selectedVersion);
+      const docSlugs = docs.map(({ slug }: { slug: string }) => slug);
+      const fileSlugs = new Set(files.map(getSlug));
+      const slugsToDelete = docSlugs.filter((slug: string) => !fileSlugs.has(slug));
+      const deletedDocs = await Promise.all(
+        slugsToDelete.map((slug: string) => deleteDoc(key, selectedVersion, dryRun, slug, this.cmdCategory))
+      );
+      changes.push(...deletedDocs);
+    } else if (!files.length) {
       return Promise.reject(new Error(`We were unable to locate Markdown files in ${folder}.`));
     }
 
@@ -76,7 +95,7 @@ export default class DocsCommand extends Command {
         return pushDoc(key, selectedVersion, dryRun, filename, this.cmdCategory);
       })
     );
-
-    return chalk.green(updatedDocs.join('\n'));
+    changes.push(...updatedDocs);
+    return chalk.green(changes.join('\n'));
   }
 }

src/lib/deleteDoc.ts

@@ -0,0 +1,40 @@
+import type { CommandCategories } from './baseCommand';
+
+import config from 'config';
+import { Headers } from 'node-fetch';
+
+import fetch, { cleanHeaders, handleRes } from './fetch';
+
+/**
+ * Delete a document from ReadMe
+ *
+ * @param {String} key the project API key
+ * @param {String} selectedVersion the project version
+ * @param {Boolean} dryRun boolean indicating dry run mode
+ * @param {String} slug The slug of the document to delete
+ * @param {String} type module within ReadMe to update (e.g. docs, changelogs, etc.)
+ * @returns {Promise<String>} a string containing the result
+ */
+export default async function deleteDoc(
+  key: string,
+  selectedVersion: string,
+  dryRun: boolean,
+  slug: string,
+  type: CommandCategories
+) {
+  if (dryRun) {
+    return Promise.resolve(`🎭 dry run! This will delete \`${slug}\``);
+  }
+  return fetch(`${config.get('host')}/api/v1/${type}/${slug}`, {
+    method: 'delete',
+    headers: cleanHeaders(
+      key,
+      new Headers({
+        'x-readme-version': selectedVersion,
+        'Content-Type': 'application/json',
+      })
+    ),
+  })
+    .then(handleRes)
+    .then(() => `successfully deleted \`${slug}\``);
+}

src/lib/fetch.ts

@@ -9,6 +9,8 @@ import APIError from './apiError';
 import isGHA from './isGitHub';
 import { debug } from './logger';
 
+const SUCCESS_NO_CONTENT = 204;
+
 /**
  * Getter function for a string to be used in the user-agent header based on the current
  * environment.
@@ -74,6 +76,9 @@ async function handleRes(res: Response) {
   // If we receive a non-JSON response, it's likely an error.
   // Let's debug the raw response body and throw it.
   const body = await res.text();
+  if (res.status === SUCCESS_NO_CONTENT) {
+    return {};
+  }
   debug(`received status code ${res.status} from ${res.url} with non-JSON response: ${body}`);
   return Promise.reject(body);
 }

src/lib/getDocs.ts

@@ -0,0 +1,38 @@
+import config from 'config';
+import { Headers } from 'node-fetch';
+
+import fetch, { cleanHeaders, handleRes } from './fetch';
+import getCategories from './getCategories';
+
+async function getCategoryDocs(key: string, selectedVersion: string, category: string) {
+  return fetch(`${config.get('host')}/api/v1/categories/${category}/docs`, {
+    method: 'get',
+    headers: cleanHeaders(
+      key,
+      new Headers({
+        'x-readme-version': selectedVersion,
+        'Content-Type': 'application/json',
+      })
+    ),
+  }).then(handleRes);
+}
+
+/**
+ * Retrieve the docs under all categories or under a specific one
+ *
+ * @param {String} key the project API key
+ * @param {String} selectedVersion the project version
+ * @param {String} [category] Get docs from the specified category only
+ * @returns {Promise<Array<Object>>} an array containing the docs
+ */
+export default async function getDocs(key: string, selectedVersion: string, category?: string) {
+  if (category) {
+    return getCategoryDocs(key, selectedVersion, category);
+  }
+
+  return getCategories(key, selectedVersion)
+    .then(categories => categories.filter(({ type }: { type: string }) => type === 'guide'))
+    .then(categories => categories.map(({ slug }: { slug: string }) => getCategoryDocs(key, selectedVersion, slug)))
+    .then(Promise.all.bind(Promise))
+    .then(args => [].concat(...args));
+}

src/lib/getSlug.ts

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import path from 'path';
+
+import grayMatter from 'gray-matter';
+
+import { debug } from './logger';
+
+/**
+ * Returns the slug of the specified Markdown or HTML file
+ *
+ * @param {String} filepath path to the HTML/Markdown file
+ *  (file extension must end in `.html`, `.md`., or `.markdown`)
+ * @returns {String} a string containing the slug of the file
+ */
+export default function getSlug(filepath: string) {
+  debug(`reading file ${filepath}`);
+  const file = fs.readFileSync(filepath, 'utf8');
+  const matter = grayMatter(file);
+  debug(`frontmatter for ${filepath}: ${JSON.stringify(matter)}`);
+
+  // Stripping the subdirectories and markdown extension from the filename and lowercasing to get the default slug.
+  return matter.data.slug || path.basename(filepath).replace(path.extname(filepath), '').toLowerCase();
+}