feat: rdme docs upload

[kanadgupta]

🚥 Resolves RM-11796, RM-11797

🧰 Changes

🚧 outstanding work

• core command + helper logic
• tests
• loading states
• complete error messages
• docs
  • migration guide (see docs: migration guide updates for rdme docs upload #1161)
  • callouts in documentation/rdme.md (see docs: warning callouts on outdated pages #1163)

🔜 to be addressed in follow-up PRs

• safeguards for users that use bidirectional syncing (ticketed in RM-11883 and RM-11901)
• updating the v9 migration guide + deprecation warnings (ticketed in RM-11902)

things to call out

• on a high level, we're mostly matching the functionality of v9's rdme docs in that we're taking markdown files and sending their contents as JSON payloads to the ReadMe API. inferring page hierarchy from directory/file structure is out of scope for this work.
• one big change from rdme@9 is that we now validate page frontmatter against the schemas from our OAS before making any API requests and prompt the user to migrate any frontmatter that we recognize as legacy APIv1 attributes. i'm open to reevaluating this paradigm, but i think it'll be helpful for folks migrating. as an interim escape hatch, this command has a hidden --skip-validation flag, just in case.
• our API expects category and parent page URIs to be a full URI (e.g., /versions/stable/categories/guides/some-uri), but that's a bit arduous for rdme users since most of the URI can be inferred from the rdme command context. as a result, rdme will automatically expand any category/parent URIs that don't match that pattern (e.g., a category URI frontmatter value of some-uri will be changed to /versions/stable/categories/guides/some-uri before making the POST/PATCH request. the frontmatter will still say some-uri.)
• the vast majority of this diff is tests + fixtures + our OAS. the three files of note are:
  • src/lib/syncPagePath.ts
  • src/lib/frontmatter.ts
  • src/commands/docs/upload.ts
• i've tried to build this in a testable and robust way where we can easily add support for reference pages, custom pages, etc. in the future
• PATCH requests to our API (i.e., for making updates to guide pages) that include slug in the body payload will always rename the page. so if you have a slug called some-page and your body payload contains some-page, the API will change your slug to some-page-1. this is most likely unexpected behavior for users of rdme, so i'm always removing the slug from the body payload in favor of using the URL instead. the trade-off is that page renaming isn't really a thing via rdme, but that's why we support bidirectional syncing, right?

🧬 QA & Testing

we're at nearly 100% test coverage with this work 📈 to QA it yourself, check out this branch and run the following:

# install + set up 
npm ci
npm run build

# grab an API key from a readme-refactored-enabled project and pop it at the end of this command:
bin/run.js docs upload __tests__/__fixtures__/docs/mixed-docs --key <key>

[erunion]

leaving formal approval off until this is ready for review but aside from a couple minor questions this looks great. awesome job.

[erunion]

mildly concerned about some file encoding bullshit but it's nothing that can't wait.

this all looks awesome.

[erunion]

May want to move this test case to a different test file because fetchSchema is part of readmeAPIFetch, not frontmatter.

[kanadgupta]

ah yeah good catch, ty

[erunion]

What's this third argument for?

[kanadgupta]

this:

rdme/src/lib/readmeAPIFetch.ts

Lines 264 to 278 in 9f84783

	if (filePath) {
	/**
	* Constructs a full URL to the file using GitHub Actions runner variables
	* @see {@link https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables}
	* @example https://github.com/readmeio/rdme/blob/cb4129d5c7b51ff3b50f933a9c7d0c3d0d33d62c/documentation/rdme.md
	*/
	try {
	const sourceUrl = new URL(
	`${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/blob/${process.env.GITHUB_SHA}/${filePath}`,
	).href;
	headers.set('x-readme-source-url', sourceUrl);
	} catch (e) {
	this.debug(`error constructing github source url: ${e.message}`);
	}
	}

[kanadgupta]

🎉 This PR is included in version 10.2.0-next.1 🎉

The release is available on:

• npm package (@next dist-tag)
• v10.2.0-next.1
• GitHub release

Your semantic-release bot 📦🚀