feat: various changes to get us plugin-ready (#1216)

## 🧰 Changes

this PR handles a lot of housekeeping to lay the groundwork for the
upcoming internal plugins project.

the biggest change is that we're now building declaration files and
shipping types for consumption by other plugins. type imports will look
something like this:

```ts
import type { PageMetadata, PluginHooks } from 'rdme/types';
```

beyond that, it's mostly little bug fixes, formatting tweaks, and test
coverage enhancements. i also removed `@oclif/plugin-not-found` since
the plugin makes it brutally slow if you typo something — figured we can
add it back if folks complain but i'd be surprised if that was the case.

## 🧬 QA & Testing

do tests/etc. pass?

Author: kanadgupta

__tests__/__fixtures__/docs/complex-frontmatter/basic.md

@@ -0,0 +1,11 @@
+---
+category:
+  uri: category-slug
+title: This is the document title
+content:
+  body: frontmatter body
+  excerpt: frontmatter excerpt
+type: basic
+---
+
+Body

__tests__/__fixtures__/docs/complex-frontmatter/link.md

@@ -0,0 +1,13 @@
+---
+category:
+  uri: category-slug
+title: This is the document title
+content:
+  excerpt: frontmatter excerpt
+  link:
+    url: https://example.com
+    new_tab: true
+type: link
+---
+
+Body

__tests__/commands/docs/__snapshots__/upload.test.ts.snap

@@ -85,8 +85,8 @@ exports[`rdme docs upload > given that the file path is a directory > given that
   },
   "stderr": " ›   Warning: This command is in an experimental alpha and is likely to change.
  ›    Use at your own risk!
-- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/multiple-docs...
-✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/multiple-docs... 4 file(s) found!
+- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/multiple-docs\` directory...
+✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/multiple-docs\` directory... 4 file(s) found!
 - 🔬 Validating frontmatter data...
 ✔ 🔬 Validating frontmatter data... no issues found!
 - 🚀 Uploading files to ReadMe...
@@ -124,8 +124,8 @@ exports[`rdme docs upload > given that the file path is a directory > should cre
   },
   "stderr": " ›   Warning: This command is in an experimental alpha and is likely to change.
  ›    Use at your own risk!
-- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs...
-✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs... 2 file(s) found!
+- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory...
+✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... 2 file(s) found!
 - 🔬 Validating frontmatter data...
 ✔ 🔬 Validating frontmatter data... no issues found!
 - 🚀 Uploading files to ReadMe...
@@ -143,8 +143,8 @@ exports[`rdme docs upload > given that the file path is a directory > should err
   "error": [Error: The directory you provided (__tests__/__fixtures__/ref-oas) doesn't contain any of the following file extensions: .markdown, .md, .mdx.],
   "stderr": " ›   Warning: This command is in an experimental alpha and is likely to change.
  ›    Use at your own risk!
-- 🔍 Looking for Markdown files in __tests__/__fixtures__/ref-oas...
-✖ 🔍 Looking for Markdown files in __tests__/__fixtures__/ref-oas... no files found.
+- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/ref-oas\` directory...
+✖ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/ref-oas\` directory... no files found.
 ",
   "stdout": "",
 }
@@ -155,8 +155,8 @@ exports[`rdme docs upload > given that the file path is a directory > should han
   "error": [AggregateError: Multiple dry runs failed. To see more detailed errors for a page, run \`rdme docs upload <path-to-page.md>\` --dry-run.],
   "stderr": " ›   Warning: This command is in an experimental alpha and is likely to change.
  ›    Use at your own risk!
-- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs...
-✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs... 5 file(s) found!
+- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory...
+✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... 5 file(s) found!
 - 🔬 Validating frontmatter data...
 ⚠ 🔬 Validating frontmatter data... issues found in 2 file(s).
  ›   Warning: 1 file(s) have issues that cannot be fixed automatically. The 
@@ -183,8 +183,8 @@ exports[`rdme docs upload > given that the file path is a directory > should han
   "error": [AggregateError: Multiple page uploads failed. To see more detailed errors for a page, run \`rdme docs upload <path-to-page.md>\`.],
   "stderr": " ›   Warning: This command is in an experimental alpha and is likely to change.
  ›    Use at your own risk!
-- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs...
-✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs... 5 file(s) found!
+- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory...
+✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... 5 file(s) found!
 - 🔬 Validating frontmatter data...
 ⚠ 🔬 Validating frontmatter data... issues found in 2 file(s).
  ›   Warning: 1 file(s) have issues that cannot be fixed automatically. The 
@@ -206,6 +206,43 @@ exports[`rdme docs upload > given that the file path is a directory > should han
 }
 `;
 
+exports[`rdme docs upload > given that the file path is a directory > should handle complex frontmatter 1`] = `
+{
+  "result": {
+    "created": [],
+    "failed": [],
+    "skipped": [],
+    "updated": [
+      {
+        "filePath": "__tests__/__fixtures__/docs/complex-frontmatter/basic.md",
+        "response": {},
+        "result": "updated",
+        "slug": "basic",
+      },
+      {
+        "filePath": "__tests__/__fixtures__/docs/complex-frontmatter/link.md",
+        "response": {},
+        "result": "updated",
+        "slug": "link",
+      },
+    ],
+  },
+  "stderr": " ›   Warning: This command is in an experimental alpha and is likely to change.
+ ›    Use at your own risk!
+- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/complex-frontmatter\` directory...
+✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/complex-frontmatter\` directory... 2 file(s) found!
+- 🔬 Validating frontmatter data...
+✔ 🔬 Validating frontmatter data... no issues found!
+- 🚀 Uploading files to ReadMe...
+✔ 🚀 Uploading files to ReadMe... done!
+",
+  "stdout": "🔄 Successfully updated 2 page(s) in ReadMe:
+   - basic (__tests__/__fixtures__/docs/complex-frontmatter/basic.md)
+   - link (__tests__/__fixtures__/docs/complex-frontmatter/link.md)
+",
+}
+`;
+
 exports[`rdme docs upload > given that the file path is a directory > should update existing guides pages in ReadMe for each file in the directory and its subdirectories 1`] = `
 {
   "result": {
@@ -229,8 +266,8 @@ exports[`rdme docs upload > given that the file path is a directory > should upd
   },
   "stderr": " ›   Warning: This command is in an experimental alpha and is likely to change.
  ›    Use at your own risk!
-- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs...
-✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs... 2 file(s) found!
+- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory...
+✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... 2 file(s) found!
 - 🔬 Validating frontmatter data...
 ✔ 🔬 Validating frontmatter data... no issues found!
 - 🚀 Uploading files to ReadMe...

__tests__/commands/docs/upload.test.ts

@@ -404,6 +404,39 @@ describe('rdme docs upload', () => {
       mock.done();
     });
 
+    it('should handle complex frontmatter', async () => {
+      const mock = getAPIv2Mock({ authorization })
+        .head('/versions/stable/guides/basic')
+        .reply(200)
+        .patch('/versions/stable/guides/basic', {
+          title: 'This is the document title',
+          category: { uri: '/versions/stable/categories/guides/category-slug' },
+          content: { body: 'frontmatter body', excerpt: 'frontmatter excerpt' },
+          type: 'basic',
+        })
+        .reply(201, {})
+        .head('/versions/stable/guides/link')
+        .reply(200)
+        .patch('/versions/stable/guides/link', {
+          title: 'This is the document title',
+          category: { uri: '/versions/stable/categories/guides/category-slug' },
+          content: {
+            body: '\nBody\n',
+            excerpt: 'frontmatter excerpt',
+            link: { url: 'https://example.com', new_tab: true },
+          },
+          type: 'link',
+        })
+        .reply(201, {});
+
+      const result = await run(['__tests__/__fixtures__/docs/complex-frontmatter', '--key', key]);
+
+      expect(result).toMatchSnapshot();
+      expect(fs.writeFileSync).not.toHaveBeenCalled();
+
+      mock.done();
+    });
+
     describe('given that the directory contains parent/child docs', () => {
       it('should upload parents before children', async () => {
         const mock = getAPIv2Mock({ authorization })

__tests__/helpers/oclif.ts

@@ -39,6 +39,8 @@ export function setupOclifConfig() {
 export function runCommand(Command: CommandClass) {
   return async function runCommandAgainstArgs(args?: string[]) {
     const oclifConfig = await setupOclifConfig();
+    // @ts-expect-error currently we have mismatching return types in our commands.
+    // we can fix this later but it's not a priority right now.
     return captureOutput<string>(() => Command.run(args, oclifConfig), { testNodeEnv });
   };
 }

__tests__/lib/frontmatter.test.ts

@@ -1,10 +1,13 @@
+import type { PageMetadata } from '../../src/lib/readPage.js';
 import type nock from 'nock';
 import type { SchemaObject } from 'oas/types';
 
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 
 import DocsUploadCommand from '../../src/commands/docs/upload.js';
-import { fix } from '../../src/lib/frontmatter.js';
+import { fix, writeFixes } from '../../src/lib/frontmatter.js';
 import { emptyMappings, fetchSchema } from '../../src/lib/readmeAPIFetch.js';
 import { oasFetchMock } from '../helpers/get-api-mock.js';
 import { setupOclifConfig } from '../helpers/oclif.js';
@@ -309,3 +312,61 @@ describe('#fix', () => {
     `);
   });
 });
+
+describe('#writeFixes', () => {
+  let command: DocsUploadCommand;
+
+  const mockPageData: PageMetadata = {
+    content: 'some content',
+    data: {
+      updated: false,
+    },
+    filePath: 'docs/page.md',
+    hash: '',
+    slug: 'some-page',
+  };
+
+  beforeEach(async () => {
+    const oclifConfig = await setupOclifConfig();
+    command = new DocsUploadCommand([], oclifConfig);
+    vi.spyOn(fs, 'existsSync').mockImplementation(() => false);
+    vi.spyOn(fs, 'mkdirSync').mockImplementation(() => '');
+    vi.spyOn(fs, 'writeFileSync').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should write changes', () => {
+    writeFixes.call(command, mockPageData, { updated: true });
+
+    expect(fs.writeFileSync).toHaveBeenCalledWith(mockPageData.filePath, expect.stringContaining('updated: true'), {
+      encoding: 'utf-8',
+    });
+  });
+
+  it('should write changes to current directory', () => {
+    writeFixes.call(command, mockPageData, { updated: true }, '.');
+
+    expect(fs.writeFileSync).toHaveBeenCalledWith(mockPageData.filePath, expect.stringContaining('updated: true'), {
+      encoding: 'utf-8',
+    });
+  });
+
+  it('should write changes to specified output directory', () => {
+    writeFixes.call(command, mockPageData, { updated: true }, 'out');
+
+    expect(fs.writeFileSync).toHaveBeenCalledWith('out/docs/page.md', expect.stringContaining('updated: true'), {
+      encoding: 'utf-8',
+    });
+  });
+
+  it('should write changes to specified output directory (with trailing slash)', () => {
+    writeFixes.call(command, mockPageData, { updated: true }, 'out/');
+
+    expect(fs.writeFileSync).toHaveBeenCalledWith('out/docs/page.md', expect.stringContaining('updated: true'), {
+      encoding: 'utf-8',
+    });
+  });
+});

bin/set-version-output.js

@@ -2,7 +2,6 @@
 // @ts-check
 import * as core from '@actions/core';
 
-// eslint-disable-next-line import/extensions
 import { getNodeVersion, getMajorPkgVersion } from '../dist/lib/getPkg.js';
 
 /**

knip.ts

@@ -1,7 +1,7 @@
 import type { KnipConfig } from 'knip';
 
 const config: KnipConfig = {
-  entry: ['src/index.ts', 'src/lib/help.ts', 'bin/*.js'],
+  entry: ['src/index.ts', 'src/types.ts', 'src/lib/help.ts', 'bin/*.js'],
   ignore: ['dist-gha/**'],
   // we're choosing not to include semantic release deps in our main dev-deps
   // since we're only using it in CI