Update release spec to only list changed packages (#23)

This PR adds a new property to the Package object,
`hasChangesSinceLatestRelease`. This property is computed when a package
is read from a project by running a diff between the last-created Git
tag associated with that package and whatever the HEAD commit happens to
be, then checking to see whether any of the files changed belong to that
package. If they do, then `hasChangesSinceLatestRelease` is true,
otherwise it's false. This property is then used to filter the list of
packages that are placed within the release spec template when it is
generated.

There are a couple of things to consider here:

* "the last-created Git tag associated with that package" — how do we
know this? How do we map a package's version to a tag? We have to
account for tags that were created by `action-create-release-pr` in the
past as well as the tags that this tool will create in the future. We
also have to know what kind of package this is — whether it's the root
package of a monorepo or a workspace package — because the set of
possible tags will differ. These differences are documented in
`readMonorepoRootPackage` and `readMonorepoWorkspacePackage`.
* What happens if a repo has no tags? Then all of the packages in that
repo are considered to have changed, as they have yet to receive their
initial release, so they will all be included in the release spec
template.

Author: mcmire

src/fs.ts

@@ -5,6 +5,12 @@ import {
 } from '@metamask/action-utils';
 import { wrapError, isErrorWithCode } from './misc-utils';
 
+/**
+ * Represents a writeable stream, such as that represented by `process.stdout`
+ * or `process.stderr`, or a fake one provided in tests.
+ */
+export type WriteStreamLike = Pick<fs.WriteStream, 'write'>;
+
 /**
  * Reads the file at the given path, assuming its content is encoded as UTF-8.
  *

src/initial-parameters.test.ts

@@ -1,7 +1,11 @@
 import os from 'os';
 import path from 'path';
 import { when } from 'jest-when';
-import { buildMockProject, buildMockPackage } from '../tests/unit/helpers';
+import {
+  buildMockProject,
+  buildMockPackage,
+  createNoopWriteStream,
+} from '../tests/unit/helpers';
 import { determineInitialParameters } from './initial-parameters';
 import * as commandLineArgumentsModule from './command-line-arguments';
 import * as envModule from './env';
@@ -23,6 +27,7 @@ describe('initial-parameters', () => {
 
     it('returns an object derived from command-line arguments and environment variables that contains data necessary to run the workflow', async () => {
       const project = buildMockProject();
+      const stderr = createNoopWriteStream();
       when(jest.spyOn(commandLineArgumentsModule, 'readCommandLineArguments'))
         .calledWith(['arg1', 'arg2'])
         .mockResolvedValue({
@@ -34,13 +39,14 @@ describe('initial-parameters', () => {
         .spyOn(envModule, 'getEnvironmentVariables')
         .mockReturnValue({ EDITOR: undefined });
       when(jest.spyOn(projectModule, 'readProject'))
-        .calledWith('/path/to/project')
+        .calledWith('/path/to/project', { stderr })
         .mockResolvedValue(project);
 
-      const config = await determineInitialParameters(
-        ['arg1', 'arg2'],
-        '/path/to/somewhere',
-      );
+      const config = await determineInitialParameters({
+        argv: ['arg1', 'arg2'],
+        cwd: '/path/to/somewhere',
+        stderr,
+      });
 
       expect(config).toStrictEqual({
         project,
@@ -53,6 +59,7 @@ describe('initial-parameters', () => {
       const project = buildMockProject({
         rootPackage: buildMockPackage(),
       });
+      const stderr = createNoopWriteStream();
       when(jest.spyOn(commandLineArgumentsModule, 'readCommandLineArguments'))
         .calledWith(['arg1', 'arg2'])
         .mockResolvedValue({
@@ -67,13 +74,20 @@ describe('initial-parameters', () => {
         .spyOn(projectModule, 'readProject')
         .mockResolvedValue(project);
 
-      await determineInitialParameters(['arg1', 'arg2'], '/path/to/cwd');
+      await determineInitialParameters({
+        argv: ['arg1', 'arg2'],
+        cwd: '/path/to/cwd',
+        stderr,
+      });
 
-      expect(readProjectSpy).toHaveBeenCalledWith('/path/to/cwd/project');
+      expect(readProjectSpy).toHaveBeenCalledWith('/path/to/cwd/project', {
+        stderr,
+      });
     });
 
     it('resolves the given temporary directory relative to the current working directory', async () => {
       const project = buildMockProject();
+      const stderr = createNoopWriteStream();
       when(jest.spyOn(commandLineArgumentsModule, 'readCommandLineArguments'))
         .calledWith(['arg1', 'arg2'])
         .mockResolvedValue({
@@ -85,13 +99,14 @@ describe('initial-parameters', () => {
         .spyOn(envModule, 'getEnvironmentVariables')
         .mockReturnValue({ EDITOR: undefined });
       when(jest.spyOn(projectModule, 'readProject'))
-        .calledWith('/path/to/project')
+        .calledWith('/path/to/project', { stderr })
         .mockResolvedValue(project);
 
-      const config = await determineInitialParameters(
-        ['arg1', 'arg2'],
-        '/path/to/cwd',
-      );
+      const config = await determineInitialParameters({
+        argv: ['arg1', 'arg2'],
+        cwd: '/path/to/cwd',
+        stderr,
+      });
 
       expect(config.tempDirectoryPath).toStrictEqual('/path/to/cwd/tmp');
     });
@@ -100,6 +115,7 @@ describe('initial-parameters', () => {
       const project = buildMockProject({
         rootPackage: buildMockPackage('@foo/bar'),
       });
+      const stderr = createNoopWriteStream();
       when(jest.spyOn(commandLineArgumentsModule, 'readCommandLineArguments'))
         .calledWith(['arg1', 'arg2'])
         .mockResolvedValue({
@@ -111,13 +127,14 @@ describe('initial-parameters', () => {
         .spyOn(envModule, 'getEnvironmentVariables')
         .mockReturnValue({ EDITOR: undefined });
       when(jest.spyOn(projectModule, 'readProject'))
-        .calledWith('/path/to/project')
+        .calledWith('/path/to/project', { stderr })
         .mockResolvedValue(project);
 
-      const config = await determineInitialParameters(
-        ['arg1', 'arg2'],
-        '/path/to/cwd',
-      );
+      const config = await determineInitialParameters({
+        argv: ['arg1', 'arg2'],
+        cwd: '/path/to/cwd',
+        stderr,
+      });
 
       expect(config.tempDirectoryPath).toStrictEqual(
         path.join(os.tmpdir(), 'create-release-branch', '@foo__bar'),
@@ -126,6 +143,7 @@ describe('initial-parameters', () => {
 
     it('returns initial parameters including reset: true, derived from a command-line argument of "--reset true"', async () => {
       const project = buildMockProject();
+      const stderr = createNoopWriteStream();
       when(jest.spyOn(commandLineArgumentsModule, 'readCommandLineArguments'))
         .calledWith(['arg1', 'arg2'])
         .mockResolvedValue({
@@ -137,19 +155,21 @@ describe('initial-parameters', () => {
         .spyOn(envModule, 'getEnvironmentVariables')
         .mockReturnValue({ EDITOR: undefined });
       when(jest.spyOn(projectModule, 'readProject'))
-        .calledWith('/path/to/project')
+        .calledWith('/path/to/project', { stderr })
         .mockResolvedValue(project);
 
-      const config = await determineInitialParameters(
-        ['arg1', 'arg2'],
-        '/path/to/somewhere',
-      );
+      const config = await determineInitialParameters({
+        argv: ['arg1', 'arg2'],
+        cwd: '/path/to/somewhere',
+        stderr,
+      });
 
       expect(config.reset).toBe(true);
     });
 
     it('returns initial parameters including reset: false, derived from a command-line argument of "--reset false"', async () => {
       const project = buildMockProject();
+      const stderr = createNoopWriteStream();
       when(jest.spyOn(commandLineArgumentsModule, 'readCommandLineArguments'))
         .calledWith(['arg1', 'arg2'])
         .mockResolvedValue({
@@ -161,13 +181,14 @@ describe('initial-parameters', () => {
         .spyOn(envModule, 'getEnvironmentVariables')
         .mockReturnValue({ EDITOR: undefined });
       when(jest.spyOn(projectModule, 'readProject'))
-        .calledWith('/path/to/project')
+        .calledWith('/path/to/project', { stderr })
         .mockResolvedValue(project);
 
-      const config = await determineInitialParameters(
-        ['arg1', 'arg2'],
-        '/path/to/somewhere',
-      );
+      const config = await determineInitialParameters({
+        argv: ['arg1', 'arg2'],
+        cwd: '/path/to/somewhere',
+        stderr,
+      });
 
       expect(config.reset).toBe(false);
     });

src/initial-parameters.ts

@@ -1,6 +1,7 @@
 import os from 'os';
 import path from 'path';
 import { readCommandLineArguments } from './command-line-arguments';
+import { WriteStreamLike } from './fs';
 import { readProject, Project } from './project';
 
 interface InitialParameters {
@@ -13,18 +14,25 @@ interface InitialParameters {
  * Reads the inputs given to this tool via `process.argv` and uses them to
  * gather information about the project the tool can use to run.
  *
- * @param argv - The arguments to this executable.
- * @param cwd - The directory in which this executable was run.
+ * @param args - The arguments to this function.
+ * @param args.argv - The arguments to this executable.
+ * @param args.cwd - The directory in which this executable was run.
+ * @param args.stderr - A stream that can be used to write to standard error.
  * @returns The initial parameters.
  */
-export async function determineInitialParameters(
-  argv: string[],
-  cwd: string,
-): Promise<InitialParameters> {
+export async function determineInitialParameters({
+  argv,
+  cwd,
+  stderr,
+}: {
+  argv: string[];
+  cwd: string;
+  stderr: WriteStreamLike;
+}): Promise<InitialParameters> {
   const inputs = await readCommandLineArguments(argv);
 
   const projectDirectoryPath = path.resolve(cwd, inputs.projectDirectory);
-  const project = await readProject(projectDirectoryPath);
+  const project = await readProject(projectDirectoryPath, { stderr });
   const tempDirectoryPath =
     inputs.tempDirectory === undefined
       ? path.join(

src/main.ts

@@ -26,7 +26,7 @@ export async function main({
   stderr: Pick<WriteStream, 'write'>;
 }) {
   const { project, tempDirectoryPath, reset } =
-    await determineInitialParameters(argv, cwd);
+    await determineInitialParameters({ argv, cwd, stderr });
 
   if (project.isMonorepo) {
     stdout.write(

src/misc-utils.test.ts

@@ -6,8 +6,9 @@ import {
   isErrorWithStack,
   wrapError,
   resolveExecutable,
-  getStdoutFromCommand,
   runCommand,
+  getStdoutFromCommand,
+  getLinesFromCommand,
 } from './misc-utils';
 
 jest.mock('which');
@@ -135,6 +136,24 @@ describe('misc-utils', () => {
     });
   });
 
+  describe('runCommand', () => {
+    it('runs the command, discarding its output', async () => {
+      const execaSpy = jest
+        .spyOn(execaModule, 'default')
+        // Typecast: It's difficult to provide a full return value for execa
+        .mockResolvedValue({ stdout: '   some output  ' } as any);
+
+      const result = await runCommand('some command', ['arg1', 'arg2'], {
+        all: true,
+      });
+
+      expect(execaSpy).toHaveBeenCalledWith('some command', ['arg1', 'arg2'], {
+        all: true,
+      });
+      expect(result).toBeUndefined();
+    });
+  });
+
   describe('getStdoutFromCommand', () => {
     it('executes the given command and returns a version of the standard out from the command with whitespace trimmed', async () => {
       const execaSpy = jest
@@ -155,21 +174,43 @@ describe('misc-utils', () => {
     });
   });
 
-  describe('runCommand', () => {
-    it('runs the command, discarding its output', async () => {
+  describe('getLinesFromCommand', () => {
+    it('executes the given command and returns the standard out from the command split into lines', async () => {
       const execaSpy = jest
         .spyOn(execaModule, 'default')
         // Typecast: It's difficult to provide a full return value for execa
-        .mockResolvedValue({ stdout: '   some output  ' } as any);
+        .mockResolvedValue({ stdout: 'line 1\nline 2\nline 3' } as any);
 
-      const result = await runCommand('some command', ['arg1', 'arg2'], {
+      const lines = await getLinesFromCommand(
+        'some command',
+        ['arg1', 'arg2'],
+        { all: true },
+      );
+
+      expect(execaSpy).toHaveBeenCalledWith('some command', ['arg1', 'arg2'], {
         all: true,
       });
+      expect(lines).toStrictEqual(['line 1', 'line 2', 'line 3']);
+    });
+
+    it('does not strip leading and trailing whitespace from the output, but does remove empty lines', async () => {
+      const execaSpy = jest
+        .spyOn(execaModule, 'default')
+        // Typecast: It's difficult to provide a full return value for execa
+        .mockResolvedValue({
+          stdout: '  line 1\nline 2\n\n   line 3   \n',
+        } as any);
+
+      const lines = await getLinesFromCommand(
+        'some command',
+        ['arg1', 'arg2'],
+        { all: true },
+      );
 
       expect(execaSpy).toHaveBeenCalledWith('some command', ['arg1', 'arg2'], {
         all: true,
       });
-      expect(result).toBeUndefined();
+      expect(lines).toStrictEqual(['  line 1', 'line 2', '   line 3   ']);
     });
   });
 });

src/misc-utils.ts

@@ -118,6 +118,23 @@ export async function resolveExecutable(
   }
 }
 
+/**
+ * Runs a command, discarding its output.
+ *
+ * @param command - The command to execute.
+ * @param args - The positional arguments to the command.
+ * @param options - The options to `execa`.
+ * @throws An `execa` error object if the command fails in some way.
+ * @see `execa`.
+ */
+export async function runCommand(
+  command: string,
+  args?: readonly string[] | undefined,
+  options?: execa.Options<string> | undefined,
+): Promise<void> {
+  await execa(command, args, options);
+}
+
 /**
  * Runs a command, retrieving the standard output with leading and trailing
  * whitespace removed.
@@ -138,18 +155,20 @@ export async function getStdoutFromCommand(
 }
 
 /**
- * Runs a command, discarding its output.
+ * Runs a Git command, splitting up the immediate output into lines.
  *
  * @param command - The command to execute.
  * @param args - The positional arguments to the command.
  * @param options - The options to `execa`.
+ * @returns The standard output of the command.
  * @throws An `execa` error object if the command fails in some way.
  * @see `execa`.
  */
-export async function runCommand(
+export async function getLinesFromCommand(
   command: string,
   args?: readonly string[] | undefined,
   options?: execa.Options<string> | undefined,
-): Promise<void> {
-  await execa(command, args, options);
+): Promise<string[]> {
+  const { stdout } = await execa(command, args, options);
+  return stdout.split('\n').filter((value) => value !== '');
 }