Merge branch 'v10-release' into kanad-2024-12-05/v10-migration-guide

.github/workflows/release.yml

@@ -48,3 +48,20 @@ jobs:
         with:
           github_token: ${{ secrets.RELEASE_GH_TOKEN }}
           branch: next
+
+  # quick assertion to validate that rdme CLI can be installed and run on ubuntu
+  postrelease:
+    name: Post-release checks
+    needs: release
+    runs-on: ubuntu-latest
+    if: ${{ github.ref }} == 'refs/heads/next'
+    steps:
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - name: Install `rdme` from npm
+        run: npm install -g rdme@next
+      - name: Print rdme CLI version
+        run: rdme --version
+        timeout-minutes: 1

CHANGELOG.md

@@ -1,3 +1,17 @@
+## [9.0.2-next.2](https://github.com/readmeio/rdme/compare/v9.0.2-next.1...v9.0.2-next.2) (2024-12-10)
+
+
+### Bug Fixes
+
+* **autocomplete:** bad alias ([#1118](https://github.com/readmeio/rdme/issues/1118)) ([5b8d928](https://github.com/readmeio/rdme/commit/5b8d9286e891b1bc5cfbcfce1a1862cb8dbdf2b4))
+
+## [9.0.2-next.1](https://github.com/readmeio/rdme/compare/v9.0.1...v9.0.2-next.1) (2024-12-10)
+
+
+### Bug Fixes
+
+* remove import attributes ([#1117](https://github.com/readmeio/rdme/issues/1117)) ([e662654](https://github.com/readmeio/rdme/commit/e66265486cac80f79c79f8594b7c60862fadbe12)), closes [#1115](https://github.com/readmeio/rdme/issues/1115) [/github.com/readmeio/rdme/pull/1115#issuecomment-2532123627](https://github.com//github.com/readmeio/rdme/pull/1115/issues/issuecomment-2532123627)
+
 ## [9.0.1](https://github.com/readmeio/rdme/compare/v9.0.0...v9.0.1) (2024-12-09)
 
 

__tests__/commands/logout.test.ts

@@ -1,6 +1,6 @@
 import { describe, afterEach, beforeAll, it, expect } from 'vitest';
 
-import pkg from '../../package.json';
+import pkg from '../../package.json' with { type: 'json' };
 import Command from '../../src/commands/logout.js';
 import configStore from '../../src/lib/configstore.js';
 import { runCommandAndReturnResult } from '../helpers/oclif.js';

__tests__/commands/open.test.ts

@@ -3,7 +3,7 @@ import type { Version } from '../../src/commands/versions/index.js';
 import chalk from 'chalk';
 import { describe, afterEach, beforeAll, it, expect } from 'vitest';
 
-import pkg from '../../package.json';
+import pkg from '../../package.json' with { type: 'json' };
 import Command from '../../src/commands/open.js';
 import configStore from '../../src/lib/configstore.js';
 import { getAPIv1Mock } from '../helpers/get-api-mock.js';

__tests__/commands/whoami.test.ts

@@ -1,6 +1,6 @@
 import { describe, afterEach, it, expect, beforeAll } from 'vitest';
 
-import pkg from '../../package.json';
+import pkg from '../../package.json' with { type: 'json' };
 import Command from '../../src/commands/whoami.js';
 import configStore from '../../src/lib/configstore.js';
 import { runCommandAndReturnResult } from '../helpers/oclif.js';

__tests__/helpers/get-gha-setup.ts

@@ -6,7 +6,7 @@ import { vi } from 'vitest';
 
 import configstore from '../../src/lib/configstore.js';
 import { git } from '../../src/lib/createGHA/index.js';
-import * as getPkgVersion from '../../src/lib/getPkgVersion.js';
+import * as getPkgVersion from '../../src/lib/getPkg.js';
 
 import getGitRemoteMock from './get-git-mock.js';
 

__tests__/lib/createGHA.test.ts

@@ -10,7 +10,7 @@ import { describe, beforeEach, afterEach, it, expect, vi, type MockInstance, bef
 
 import configstore from '../../src/lib/configstore.js';
 import { getConfigStoreKey, getGHAFileName, git } from '../../src/lib/createGHA/index.js';
-import { getMajorPkgVersion } from '../../src/lib/getPkgVersion.js';
+import { getMajorPkgVersion } from '../../src/lib/getPkg.js';
 import { after, before } from '../helpers/get-gha-setup.js';
 import getGitRemoteMock from '../helpers/get-git-mock.js';
 import ghaWorkflowSchema from '../helpers/github-workflow-schema.json' with { type: 'json' };

__tests__/lib/getPkgVersion.test.ts

@@ -3,7 +3,7 @@ import semver from 'semver';
 import { describe, beforeEach, afterEach, it, expect, vi, type MockInstance } from 'vitest';
 
 import pkg from '../../package.json' with { type: 'json' };
-import { getNodeVersion, getPkgVersion } from '../../src/lib/getPkgVersion.js';
+import { getNodeVersion, getPkgVersion, getPkgVersionFromNPM } from '../../src/lib/getPkg.js';
 
 describe('#getNodeVersion()', () => {
   it('should extract version that matches range in package.json', () => {
@@ -27,23 +27,23 @@ describe('#getPkgVersion()', () => {
   });
 
   it('should grab version from package.json by default', () => {
-    return expect(getPkgVersion()).resolves.toBe(pkg.version);
+    return expect(getPkgVersion()).toBe(pkg.version);
   });
 
   it('should fetch version from npm registry', async () => {
     const mock = nock('https://registry.npmjs.com', { encodedQueryParams: true })
       .get('/rdme')
       .reply(200, { 'dist-tags': { latest: '1.0' } });
 
-    await expect(getPkgVersion('latest')).resolves.toBe('1.0');
+    await expect(getPkgVersionFromNPM('latest')).resolves.toBe('1.0');
 
     mock.done();
   });
 
   it('should fallback if npm registry fails', async () => {
     const mock = nock('https://registry.npmjs.com', { encodedQueryParams: true }).get('/rdme').reply(500);
 
-    await expect(getPkgVersion('latest')).resolves.toBe(pkg.version);
+    await expect(getPkgVersionFromNPM('latest')).resolves.toBe(pkg.version);
 
     mock.done();
   });

bin/dev.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S npx tsx
+#!/usr/bin/env npx tsx
 
 async function main() {
   const { execute } = await import('@oclif/core');

bin/run.js

@@ -1,6 +1,4 @@
-#!/usr/bin/env -S node --no-warnings=ExperimentalWarning
-// ^ we need this env variable above to hide the ExperimentalWarnings
-// source: https://github.com/nodejs/node/issues/10802#issuecomment-573376999
+#!/usr/bin/env node
 
 import stringArgv from 'string-argv';
 

bin/set-major-version-tag.js

@@ -37,18 +37,12 @@ async function runGitCmd(args) {
  */
 async function setMajorVersionTag() {
   try {
-    console.log(
-      'kanad test',
-      JSON.stringify({
-        GITHUB_BASE_REF: process.env.GITHUB_BASE_REF,
-        GITHUB_HEAD_REF: process.env.GITHUB_HEAD_REF,
-        GITHUB_REF: process.env.GITHUB_REF,
-        GITHUB_REF_NAME: process.env.GITHUB_REF_NAME,
-        GITHUB_REF_PROTECTED: process.env.GITHUB_REF_PROTECTED,
-        GITHUB_REF_TYPE: process.env.GITHUB_REF_TYPE,
-        GITHUB_WORKFLOW_REF: process.env.GITHUB_WORKFLOW_REF,
-      }),
-    );
+    // The major version tag should only be set when releasing on the `main` branch
+    if (process.env.GITHUB_REF !== 'refs/heads/main') {
+      // eslint-disable-next-line no-console
+      console.warn(`Running with the following ref: ${process.env.GITHUB_REF || 'n/a'}, not setting major version tag`);
+      return;
+    }
 
     const parsedVersion = parse(pkg.version);
 

bin/set-version-output.js

@@ -3,7 +3,7 @@
 import * as core from '@actions/core';
 
 // eslint-disable-next-line import/extensions
-import { getNodeVersion, getMajorPkgVersion } from '../dist/lib/getPkgVersion.js';
+import { getNodeVersion, getMajorPkgVersion } from '../dist/lib/getPkg.js';
 
 /**
  * Sets output parameters for GitHub Actions workflow so we can do

package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdme",
-  "version": "9.0.1",
+  "version": "9.0.2-next.2",
   "description": "ReadMe's official CLI and GitHub Action.",
   "license": "MIT",
   "author": "ReadMe <[email protected]> (https://readme.com)",
@@ -34,7 +34,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/readmeio/rdme.git"
+    "url": "git+https://github.com/readmeio/rdme.git"
   },
   "bugs": {
     "url": "https://github.com/readmeio/rdme/issues"

src/commands/docs/prune.ts

@@ -26,7 +26,8 @@ export default class DocsPruneCommand extends BaseCommand<typeof DocsPruneComman
     message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
   };
 
-  static aliases = ['guides prune'];
+  // this needs to be separated by a colon in order for autocomplete to work properly
+  static aliases = ['guides:prune'];
 
   static description = 'Delete any docs from ReadMe if their slugs are not found in the target folder.';
 

src/lib/configstore.ts

@@ -1,6 +1,6 @@
 import Configstore from 'configstore';
 
-import pkg from '../package.json' with { type: 'json' };
+import { pkg } from './getPkg.js';
 
 const configstore = new Configstore(
   /**

src/lib/createGHA/index.ts

@@ -8,7 +8,7 @@ import prompts from 'prompts';
 import { simpleGit } from 'simple-git';
 
 import configstore from '../configstore.js';
-import { getMajorPkgVersion } from '../getPkgVersion.js';
+import { getMajorPkgVersion } from '../getPkg.js';
 import isCI, { isNpmScript, isTest } from '../isCI.js';
 import { info } from '../logger.js';
 import promptTerminal from '../promptWrapper.js';

src/lib/getPkgVersion.ts → src/lib/getPkg.ts

@@ -1,8 +1,8 @@
 import type { Hook } from '@oclif/core';
 
-import semver from 'semver';
+import { readFileSync } from 'node:fs';
 
-import pkg from '../package.json' with { type: 'json' };
+import semver from 'semver';
 
 import { error } from './logger.js';
 
@@ -13,6 +13,15 @@ const registryUrl = 'https://registry.npmjs.com/rdme';
  */
 type npmDistTag = 'latest';
 
+/**
+ * A synchronous function that reads the `package.json` file for use elsewhere.
+ * Until we drop support Node.js 20, we need to import this way to avoid ExperimentalWarning outputs.
+ *
+ * @see {@link https://nodejs.org/docs/latest-v20.x/api/esm.html#import-attributes}
+ * @see {@link https://www.stefanjudis.com/snippets/how-to-import-json-files-in-es-modules-node-js/}
+ */
+export const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), { encoding: 'utf-8' }));
+
 /**
  * Return the major Node.js version specified in our `package.json` config.
  *
@@ -27,27 +36,39 @@ export function getNodeVersion(): string {
   return parsedVersion.version;
 }
 
+/**
+ * The current `rdme` version, as specified in the `package.json`
+ * or in the oclif hook context.
+ *
+ * @example "8.0.0"
+ * @note we mock this function in our snapshots
+ * @see {@link https://stackoverflow.com/a/54245672}
+ */
+export function getPkgVersion(this: Hook.Context | void): string {
+  return this?.config?.version || pkg.version;
+}
+
 /**
  * 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, hence it's not the default
+ * @note we mock this function in our snapshots
  * @see {@link https://stackoverflow.com/a/54245672}
  */
-export async function getPkgVersion(this: Hook.Context | void, npmDistTag?: npmDistTag): Promise<string> {
+export async function getPkgVersionFromNPM(this: Hook.Context | void, npmDistTag?: npmDistTag): Promise<string> {
   if (npmDistTag) {
     return fetch(registryUrl)
       .then(res => res.json() as Promise<{ 'dist-tags': Record<string, string> }>)
       .then(body => body['dist-tags'][npmDistTag])
       .catch(err => {
         error(`error fetching version from npm registry: ${err.message}`);
-        return pkg.version;
+        return getPkgVersion.call(this);
       });
   }
-  return this?.config?.version || pkg.version;
+  return getPkgVersion.call(this);
 }
 
 /**
@@ -56,5 +77,5 @@ export async function getPkgVersion(this: Hook.Context | void, npmDistTag?: npmD
  * @example 8
  */
 export async function getMajorPkgVersion(this: Hook.Context | void, npmDistTag?: npmDistTag): Promise<number> {
-  return semver.major(await getPkgVersion.call(this, npmDistTag));
+  return semver.major(await getPkgVersionFromNPM.call(this, npmDistTag));
 }

src/lib/readmeAPIFetch.ts

@@ -5,11 +5,10 @@ import path from 'node:path';
 import mime from 'mime-types';
 import { ProxyAgent } from 'undici';
 
-import pkg from '../package.json' with { type: 'json' };
-
 import { APIv1Error } from './apiError.js';
 import config from './config.js';
 import { git } from './createGHA/index.js';
+import { getPkgVersion } from './getPkg.js';
 import isCI, { ciName, isGHA } from './isCI.js';
 import { debug, warn } from './logger.js';
 
@@ -90,7 +89,7 @@ function parseWarningHeader(header: string): WarningHeader[] {
  */
 export function getUserAgent() {
   const gh = isGHA() ? '-github' : '';
-  return `rdme${gh}/${pkg.version}`;
+  return `rdme${gh}/${getPkgVersion()}`;
 }
 
 /**