fix(msp): add files to results of discover and mutationTest (#7)

Add `files` to both `discover` and `mutationTest` results, inspired by the report-schema.

I've also reworked the readme to be more consistent:
- removed arbitrary `export` and `readonly` keywords
- consistently use `type` instead of `interface`

Author: nicojs

packages/mutation-server-protocol/README.md

@@ -89,23 +89,42 @@ The `discover` method is used to discover mutants in the given file paths. The s
 The `DiscoveredMutant` type is a subset of the `MutantResult` type. The `MutantResult` is the type that can be found in the [mutation testing report schema](https://github.com/stryker-mutator/mutation-testing-elements/blob/2902d56301cfdaa8ad2be59f3bca07bdf96f89b4/packages/report-schema/src/mutation-testing-report-schema.json#L37).
 
 ```ts
-export interface DiscoverParams {
+type DiscoverParams = {
   /**
    * The files to run discovery on, or undefined to discover all files in the current project.
    * A file ending with a `/` indicates a directory. Each path can specify exactly which code blocks to mutate/discover using a mutation range.
    * This can be done by postfixing your file with `:startLine[:startColumn]-endLine[:endColumn]`.
    */
   files?: string[];
-}
-
-type DiscoveredMutant = Pick<
-  schema.MutantResult,
-  'id' | 'location' | 'description' | 'mutatorName' | 'replacement'
->;
-
-export interface DiscoverResult {
-  mutants: readonly DiscoveredMutant[];
-}
+};
+
+type DiscoverResult = {
+  files: DiscoveredFiles;
+};
+
+type DiscoveredFiles = Record<string, DiscoveredFile>;
+
+type DiscoveredFile = {
+  mutants: DiscoveredMutant[];
+};
+
+type DiscoveredMutant = {
+  id: string;
+  location: Location;
+  description?: string;
+  mutatorName: string;
+  replacement?: string;
+};
+
+type Location = {
+  start: Position;
+  end: Position;
+};
+
+type Position = {
+  line: number;
+  column: number;
+};
 ```
 
 #### MutationTest
@@ -118,18 +137,42 @@ Whenever a partial result is in, the server is expected to send a `reportMutatio
 > The MutantResult should adhere to the [mutation testing report schema](https://github.com/stryker-mutator/mutation-testing-elements/blob/2902d56301cfdaa8ad2be59f3bca07bdf96f89b4/packages/report-schema/src/mutation-testing-report-schema.json#L37)
 
 ```ts
-export interface MutationTestParams {
+type MutationTestParams = {
   /**
    * The files to run mutation testing on, or undefined to run mutation testing on all files in the current project.
    * A file ending with a `/` indicates a directory. Each path can specify exactly which code blocks to mutate/discover using a mutation range.
    * This can be done by postfixing your file with `:startLine[:startColumn]-endLine[:endColumn]`.
    */
   files?: string[];
-}
-
-export interface MutationTestResult {
-  mutants: schema.MutantResult[];
-}
+};
+
+type MutationTestResult = {
+  files: MutantResultFiles;
+};
+
+type MutantResultFiles = Record<string, MutantResultFile>;
+
+type MutantResultFile = {
+  mutants: MutantResult[];
+};
+
+type MutantResult = DiscoveredMutant & {
+  coveredBy?: string[];
+  duration?: number;
+  killedBy?: string[];
+  static?: boolean;
+  status: MutantStatus;
+  statusReason?: string;
+  testsCompleted?: number;
+};
+
+type MutantStatus =
+  | 'Killed'
+  | 'Survived'
+  | 'NoCoverage'
+  | 'Timeout'
+  | 'CompileError'
+  | 'RuntimeError';
 ```
 
 ### Error messages

packages/mutation-server-protocol/src/schema.spec.ts

@@ -40,21 +40,39 @@ describe('Schema', () => {
   }
 
   describe('DiscoverResult', () => {
-    it('should have a mutants field', () => {
-      DiscoverResult.parse({ mutants: [] });
+    it('should have a files field', () => {
+      DiscoverResult.parse({ files: {} });
     });
+
+    it('should allow an arbitrary amount of files', () => {
+      DiscoverResult.parse({
+        files: {
+          'src/index.ts': {
+            mutants: [],
+          },
+          'src/foo.ts': {
+            mutants: [],
+          },
+        },
+      });
+    });
+
     it('should allow an array of DiscoveredMutants', () => {
       DiscoverResult.parse({
-        mutants: [
-          {
-            id: '1',
-            location: {
-              start: { line: 1, column: 1 },
-              end: { line: 1, column: 1 },
-            },
-            mutatorName: 'foo',
+        files: {
+          'src/index.ts': {
+            mutants: [
+              {
+                id: '1',
+                location: {
+                  start: { line: 1, column: 1 },
+                  end: { line: 1, column: 1 },
+                },
+                mutatorName: 'foo',
+              },
+            ],
           },
-        ],
+        },
       });
     });
     it('should throw if the mutants array is missing', () => {
@@ -204,12 +222,28 @@ describe('Schema', () => {
     });
   });
   describe('MutationTestResult', () => {
-    it('should parse an empty array', () => {
-      MutationTestResult.parse({ mutants: [] });
+    it('should parse empty files', () => {
+      MutationTestResult.parse({ files: {} });
+    });
+    it('should parse an arbitrary amount of files', () => {
+      MutationTestResult.parse({
+        files: {
+          'src/foo.ts': {
+            mutants: [],
+          },
+          'src/bar.ts': {
+            mutants: [],
+          },
+        },
+      });
     });
     it('should parse an array of MutantResults', () => {
       MutationTestResult.parse({
-        mutants: [validMinimalMutantResult()],
+        files: {
+          'src/index.ts': {
+            mutants: [validMinimalMutantResult()],
+          },
+        },
       });
     });
     it('should throw if mutants is missing', () => {

packages/mutation-server-protocol/src/schema.ts

@@ -9,6 +9,7 @@ import {
   enum as enum_,
   type z,
   boolean,
+  record,
 } from 'zod';
 
 export const ConfigureParams = object({
@@ -60,8 +61,18 @@ export const DiscoveredMutant = object({
   replacement: string().optional(),
 });
 
+export type DiscoveredMutant = z.infer<typeof DiscoveredMutant>;
+
+export const DiscoveredFile = object({ mutants: array(DiscoveredMutant) });
+
+export type DiscoveredFile = z.infer<typeof DiscoveredFile>;
+
+export const DiscoveredFiles = record(string(), DiscoveredFile);
+
+export type DiscoveredFiles = z.infer<typeof DiscoveredFiles>;
+
 export const DiscoverResult = object({
-  mutants: array(DiscoveredMutant),
+  files: DiscoveredFiles,
 });
 
 export type DiscoverResult = z.infer<typeof DiscoverResult>;
@@ -123,8 +134,16 @@ export const MutantResult = DiscoveredMutant.extend({
 
 export type MutantResult = z.infer<typeof MutantResult>;
 
+export const MutantResultFile = object({ mutants: array(MutantResult) });
+
+export type MutantResultFile = z.infer<typeof MutantResultFile>;
+
+export const MutationResultFiles = record(string(), MutantResultFile);
+
+export type MutationResultFiles = z.infer<typeof MutationResultFiles>;
+
 export const MutationTestResult = object({
-  mutants: array(MutantResult),
+  files: MutationResultFiles,
 });
 
 export type MutationTestResult = z.infer<typeof MutationTestResult>;