Fix repo links in updated changelogs

When this tool populates the Unreleased section of the changelog, it
does not just rewrite that section, but rather, it rewrites the entire
changelog. That behavior comes from the `updateChangelog` function in
`@metamask/auto-changelog`. This function takes the changes to apply,
but it also takes a repository URL, which it will use to construct links
for all of the releases in the changelog.

Unfortunately, the repository URL that this tool passes to
`updateChangelog` is not always the same URL that `auto-changelog` uses.
Specifically, if the developer used a different URL to clone the repo
than is listed in `package.json` under `repository.url`, then when
creating a new release branch, all of the links in the changelog will be
modified to reflect this new URL. This is incorrect, the resulting
changelog will not pass validation when run through `auto-changelog
validate`, forcing the developer to revert the changes to the links in
order to merge the release PR.

This commit addresses this pain point by updating the logic used to
obtain the repository URL to better match what is in
`@metamask/auto-changelog`. This means that the aforementioned links in
the changelog should stay the same when creating a new release branch.

Author: mcmire

src/functional.test.ts

@@ -77,13 +77,9 @@ describe('create-release-branch (functional)', () => {
             },
           });
 
-          expect(await environment.readJsonFile('package.json')).toStrictEqual({
+          expect(await environment.readJsonFile('package.json')).toMatchObject({
             name: '@scope/monorepo',
             version: '2.0.0',
-            private: true,
-            workspaces: ['packages/*'],
-            scripts: { foo: 'bar' },
-            packageManager: '[email protected]',
           });
           expect(
             await environment.readJsonFileWithinPackage('a', 'package.json'),
@@ -190,13 +186,9 @@ describe('create-release-branch (functional)', () => {
             },
           });
 
-          expect(await environment.readJsonFile('package.json')).toStrictEqual({
+          expect(await environment.readJsonFile('package.json')).toMatchObject({
             name: '@scope/monorepo',
             version: '1.1.0',
-            private: true,
-            workspaces: ['packages/*'],
-            scripts: { foo: 'bar' },
-            packageManager: '[email protected]',
           });
           expect(
             await environment.readJsonFileWithinPackage('a', 'package.json'),
@@ -945,12 +937,9 @@ __metadata:
             },
           });
 
-          expect(await environment.readJsonFile('package.json')).toStrictEqual({
+          expect(await environment.readJsonFile('package.json')).toMatchObject({
             name: '@scope/monorepo',
             version: '2.0.0',
-            private: true,
-            workspaces: ['packages/*'],
-            packageManager: '[email protected]',
           });
           expect(
             await environment.readJsonFileWithinPackage('a', 'package.json'),

src/misc-utils.test.ts

@@ -9,6 +9,7 @@ import {
   runCommand,
   getStdoutFromCommand,
   getLinesFromCommand,
+  convertToHttpsGitHubRepositoryUrl,
 } from './misc-utils.js';
 
 jest.mock('which');
@@ -211,4 +212,49 @@ describe('misc-utils', () => {
       expect(lines).toStrictEqual(['  line 1', 'line 2', '   line 3   ']);
     });
   });
+
+  describe('convertToHttpsRepositoryUrl', () => {
+    it('returns the URL of the "origin" remote of the given repo if it looks like a HTTPS public GitHub repo URL', () => {
+      expect(
+        convertToHttpsGitHubRepositoryUrl(
+          'https://github.com/example-org/example-repo',
+        ),
+      ).toBe('https://github.com/example-org/example-repo');
+    });
+
+    it('lops ".git" off from the HTTPS public GitHub repo URL', () => {
+      expect(
+        convertToHttpsGitHubRepositoryUrl(
+          'https://github.com/example-org/example-repo.git',
+        ),
+      ).toBe('https://github.com/example-org/example-repo');
+    });
+
+    it('converts an SSH GitHub repo URL into an HTTPS URL (without the trailing ".git")', () => {
+      expect(
+        convertToHttpsGitHubRepositoryUrl(
+          '[email protected]:example-org/example-repo.git',
+        ),
+      ).toBe('https://github.com/example-org/example-repo');
+    });
+
+    it.each([
+      'foo',
+      'http://github.com/example-org',
+      'https://github.com/example-org',
+      'http://github.com/example-org/example-repo',
+      'https://github.comzzzz/example-org/example-repo',
+      'https://gitbar.foo/example-org/example-repo',
+      '[email protected]:example-org',
+      '[email protected]:example-org/example-repo.git',
+      '[email protected]:example-org/example-repo.foo',
+    ])(
+      'throws if the URL is in an invalid format such as "%s"',
+      (repositoryUrl) => {
+        expect(() => convertToHttpsGitHubRepositoryUrl(repositoryUrl)).toThrow(
+          `Unrecognized repository URL: ${repositoryUrl}`,
+        );
+      },
+    );
+  });
 });

src/misc-utils.ts

@@ -15,6 +15,20 @@ export { isObject };
  */
 export const debug = createDebug('create-release-branch:impl');
 
+/**
+ * Matches URLs in the formats:
+ *
+ * - "https://github.com/OrganizationName/RepoName"
+ * - "https://github.com/OrganizationName/RepoName.git"
+ */
+const HTTPS_GITHUB_URL_REGEX =
+  /^https:\/\/github\.com\/(.+?)\/(.+?)(?:\.git)?$/u;
+
+/**
+ * Matches a URL in the format "[email protected]/OrganizationName/RepoName.git".
+ */
+const SSH_GITHUB_URL_REGEX = /^git@github\.com:(.+?)\/(.+?)\.git$/u;
+
 /**
  * Type guard for determining whether the given value is an instance of Error.
  * For errors generated via `fs.promises`, `error instanceof Error` won't work,
@@ -172,3 +186,28 @@ export async function getLinesFromCommand(
   const { stdout } = await execa(command, args, options);
   return stdout.split('\n').filter((value) => value !== '');
 }
+
+/**
+ * Converts the given GitHub repository URL to its HTTPS version.
+ *
+ * A "GitHub repository URL" looks like one of:
+ *
+ * - https://github.com/OrganizationName/RepositoryName
+ * - [email protected]:OrganizationName/RepositoryName.git
+ *
+ * If the URL does not match either of these patterns, an error is thrown.
+ *
+ * @param url - The URL to convert.
+ * @returns The HTTPS URL of the repository, e.g.
+ * `https://github.com/OrganizationName/RepositoryName`.
+ */
+export function convertToHttpsGitHubRepositoryUrl(url: string): string {
+  const match =
+    url.match(HTTPS_GITHUB_URL_REGEX) ?? url.match(SSH_GITHUB_URL_REGEX);
+
+  if (match) {
+    return `https://github.com/${match[1]}/${match[2]}`;
+  }
+
+  throw new Error(`Unrecognized repository URL: ${url}`);
+}

src/project.test.ts

@@ -3,13 +3,15 @@ import path from 'path';
 import { when } from 'jest-when';
 import { SemVer } from 'semver';
 import * as actionUtils from '@metamask/action-utils';
-import { withSandbox } from '../tests/helpers.js';
+import { withProtectedProcessEnv, withSandbox } from '../tests/helpers.js';
 import {
   buildMockPackage,
   buildMockProject,
   createNoopWriteStream,
 } from '../tests/unit/helpers.js';
+import * as miscUtils from './misc-utils.js';
 import {
+  getValidRepositoryUrl,
   readProject,
   restoreChangelogsForSkippedPackages,
   updateChangelogsForChangedPackages,
@@ -42,6 +44,11 @@ describe('project', () => {
             validatedManifest: {
               workspaces: ['packages/a', 'packages/subpackages/*'],
             },
+            unvalidatedManifest: {
+              repository: {
+                url: projectRepositoryUrl,
+              },
+            },
           },
         );
         const workspacePackages = {
@@ -59,9 +66,6 @@ describe('project', () => {
         };
         const projectTagNames = ['tag1', 'tag2', 'tag3'];
         const stderr = createNoopWriteStream();
-        when(jest.spyOn(repoModule, 'getRepositoryHttpsUrl'))
-          .calledWith(projectDirectoryPath)
-          .mockResolvedValue(projectRepositoryUrl);
         when(jest.spyOn(repoModule, 'getTagNames'))
           .calledWith(projectDirectoryPath)
           .mockResolvedValue(projectTagNames);
@@ -126,6 +130,71 @@ describe('project', () => {
       });
     });
   });
+
+  describe('getValidRepositoryUrl', () => {
+    describe('if the `npm_package_repository_url` environment variable is set', () => {
+      it('returns the HTTPS version of this URL', async () => {
+        await withProtectedProcessEnv(async () => {
+          process.env.npm_package_repository_url =
+            '[email protected]:example-org/example-repo.git';
+          const packageManifest = {};
+          const repositoryDirectoryPath = '/path/to/project';
+
+          expect(
+            await getValidRepositoryUrl(
+              packageManifest,
+              repositoryDirectoryPath,
+            ),
+          ).toBe('https://github.com/example-org/example-repo');
+        });
+      });
+    });
+
+    describe('if package.json has a string "repository" field', () => {
+      it('returns the HTTPS version of this URL', async () => {
+        const packageManifest = {
+          repository: '[email protected]:example-org/example-repo.git',
+        };
+        const repositoryDirectoryPath = '/path/to/project';
+
+        expect(
+          await getValidRepositoryUrl(packageManifest, repositoryDirectoryPath),
+        ).toBe('https://github.com/example-org/example-repo');
+      });
+    });
+
+    describe('if package.json has an object "repository" field with a string "url" field', () => {
+      it('returns the HTTPS version of this URL', async () => {
+        const packageManifest = {
+          repository: {
+            url: '[email protected]:example-org/example-repo.git',
+          },
+        };
+        const repositoryDirectoryPath = '/path/to/project';
+
+        expect(
+          await getValidRepositoryUrl(packageManifest, repositoryDirectoryPath),
+        ).toBe('https://github.com/example-org/example-repo');
+      });
+    });
+
+    describe('if package.json does not have a "repository" field', () => {
+      it('returns the HTTPS version of this URL', async () => {
+        const packageManifest = {};
+        const repositoryDirectoryPath = '/path/to/project';
+        when(jest.spyOn(miscUtils, 'getStdoutFromCommand'))
+          .calledWith('git', ['config', '--get', 'remote.origin.url'], {
+            cwd: repositoryDirectoryPath,
+          })
+          .mockResolvedValue('[email protected]:example-org/example-repo.git');
+
+        expect(
+          await getValidRepositoryUrl(packageManifest, repositoryDirectoryPath),
+        ).toBe('https://github.com/example-org/example-repo');
+      });
+    });
+  });
+
   describe('restoreChangelogsForSkippedPackages', () => {
     it('should reset changelog for packages with changes not included in release', async () => {
       const project = buildMockProject({

src/project.ts

@@ -1,17 +1,25 @@
 import { WriteStream } from 'fs';
 import { resolve } from 'path';
 import { getWorkspaceLocations } from '@metamask/action-utils';
+import { isPlainObject } from '@metamask/utils';
 import { WriteStreamLike, fileExists } from './fs.js';
 import {
   Package,
   readMonorepoRootPackage,
   readMonorepoWorkspacePackage,
   updatePackageChangelog,
 } from './package.js';
-import { getRepositoryHttpsUrl, getTagNames, restoreFiles } from './repo.js';
+import { getTagNames, restoreFiles } from './repo.js';
 import { SemVer } from './semver.js';
-import { PackageManifestFieldNames } from './package-manifest.js';
+import {
+  PackageManifestFieldNames,
+  UnvalidatedPackageManifest,
+} from './package-manifest.js';
 import { ReleaseSpecification } from './release-specification.js';
+import {
+  convertToHttpsGitHubRepositoryUrl,
+  getStdoutFromCommand,
+} from './misc-utils.js';
 
 /**
  * The release version of the root package of a monorepo extracted from its
@@ -83,13 +91,16 @@ export async function readProject(
   projectDirectoryPath: string,
   { stderr }: { stderr: WriteStreamLike },
 ): Promise<Project> {
-  const repositoryUrl = await getRepositoryHttpsUrl(projectDirectoryPath);
   const tagNames = await getTagNames(projectDirectoryPath);
   const rootPackage = await readMonorepoRootPackage({
     packageDirectoryPath: projectDirectoryPath,
     projectDirectoryPath,
     projectTagNames: tagNames,
   });
+  const repositoryUrl = await getValidRepositoryUrl(
+    rootPackage.unvalidatedManifest,
+    projectDirectoryPath,
+  );
   const releaseVersion = examineReleaseVersion(
     rootPackage.validatedManifest.version,
   );
@@ -132,6 +143,62 @@ export async function readProject(
   };
 }
 
+/**
+ * Returns the https-prefixed GitHub repository URL for the project, so that we
+ * know how to construct links to releases inside of the changelog.
+ *
+ * This URL is obtained by looking at the following sources, in this order:
+ *
+ * - `process.env.npm_package_repository_url` (to support MetaMask projects
+ * which still use NPM or Yarn 1.x)
+ * - The `repository` field inside of `package.json` (to support most MetaMask
+ * projects)
+ * - The URL of the "origin" remote (to support newer projects which for some
+ * reason do not have a "repository" field)
+ *
+ * Note that there is a function in `@metamask/auto-changelog` that offers a
+ * similar capability, and in fact, this function should match it as closely as
+ * possible so that when changelogs are updated they also pass
+ * `@metamask/auto-changelog`'s validation step.
+ *
+ * @param packageManifest - The manifest for the package that represents a
+ * project.
+ * @param repositoryDirectoryPath - The path to the repository for the project.
+ * @returns The HTTPS URL of the repository, e.g.
+ * `https://github.com/OrganizationName/RepositoryName`.
+ * @throws If the URL obtained via `package.json` or the "origin" remote is in
+ * in invalid format.
+ */
+export async function getValidRepositoryUrl(
+  packageManifest: UnvalidatedPackageManifest,
+  repositoryDirectoryPath: string,
+): Promise<string> {
+  // Set automatically by NPM or Yarn 1.x
+  const npmPackageRepositoryUrl = process.env.npm_package_repository_url;
+
+  if (npmPackageRepositoryUrl) {
+    return convertToHttpsGitHubRepositoryUrl(npmPackageRepositoryUrl);
+  }
+
+  if (typeof packageManifest.repository === 'string') {
+    return convertToHttpsGitHubRepositoryUrl(packageManifest.repository);
+  }
+
+  if (
+    isPlainObject(packageManifest.repository) &&
+    typeof packageManifest.repository.url === 'string'
+  ) {
+    return convertToHttpsGitHubRepositoryUrl(packageManifest.repository.url);
+  }
+
+  const gitConfigUrl = await getStdoutFromCommand(
+    'git',
+    ['config', '--get', 'remote.origin.url'],
+    { cwd: repositoryDirectoryPath },
+  );
+  return convertToHttpsGitHubRepositoryUrl(gitConfigUrl);
+}
+
 /**
  * Updates the changelog files of all packages that have changes since latest release to include those changes.
  *