stryker-markdown-reporter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitriy Zverev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# stryker-markdown-reporter
+
+A [StrykerJS](https://stryker-mutator.io/) reporter plugin that writes mutation
+testing results as a Markdown table.
+
+The report is plain Markdown, so it can be committed, attached to a pull request
+comment or appended to a GitHub Actions job summary.
+
+## Example
+
+| File                |     score |   covered | killed | timeout | survived | no cov | ignored | errors |
+| :------------------ | --------: | --------: | -----: | ------: | -------: | -----: | ------: | -----: |
+| **All files**       | 🟡 70.00% | 🟢 82.35% |     13 |       1 |        3 |      3 |       0 |      1 |
+| src/math.ts         | 🟢 90.00% | 🟢 90.00% |      8 |       1 |        1 |      0 |       0 |      0 |
+| src/utils/format.ts | 🔴 50.00% | 🟡 71.43% |      5 |       0 |        2 |      3 |       0 |      1 |
+
+Thresholds: 🟢 ≥ 80, 🟡 ≥ 60, 🔴 < 60, break < 50
+
+## Requirements
+
+- Node.js 22 or later
+- StrykerJS 10 (`@stryker-mutator/core`)
+
+## Installation
+
+```sh
+npm install --save-dev stryker-markdown-reporter
+```
+
+## Usage
+
+Add the plugin and the `markdown` reporter to your Stryker configuration, for
+example `stryker.config.json`:
+
+```json
+{
+    "appendPlugins": ["stryker-markdown-reporter"],
+    "reporters": ["clear-text", "progress", "markdown"]
+}
+```
+
+After a run, the report is written to `reports/mutation/mutation.md`.
+
+## Options
+
+Options are set in the `markdownReporter` section of the Stryker configuration:
+
+```json
+{
+    "markdownReporter": {
+        "fileName": "reports/mutation/mutation.md",
+        "splitErrors": false
+    }
+}
+```
+
+| Option        | Type      | Default                        | Description                                                                  |
+| ------------- | --------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `fileName`    | `string`  | `reports/mutation/mutation.md` | Path of the report file, relative to the working directory.                  |
+| `splitErrors` | `boolean` | `false`                        | Show runtime and compile errors in separate columns instead of a single one. |
+
+## Report
+
+The first row contains the totals for the whole project, followed by one row per
+mutated file.
+
+| Column     | Description                                                                 |
+| ---------- | --------------------------------------------------------------------------- |
+| `score`    | Mutation score: the share of detected mutants among all valid mutants.      |
+| `covered`  | Mutation score based on covered code: mutants without coverage are ignored. |
+| `killed`   | Mutants detected by a failing test.                                         |
+| `timeout`  | Mutants detected by a test timeout.                                         |
+| `survived` | Mutants that no test detected.                                              |
+| `no cov`   | Mutants in code that no test covers.                                        |
+| `ignored`  | Mutants excluded from the run.                                              |
+| `errors`   | Mutants that caused a runtime or compile error.                             |
+
+Scores are marked according to the `thresholds` option of Stryker: 🟢 at or
+above `high`, 🟡 at or above `low`, 🔴 below `low`. A score is shown as `n/a`
+when there are no valid mutants.
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1 @@
+export * from './src/index.js';

package/index.js

@@ -0,0 +1 @@
+export * from './src/index.js';

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "stryker-markdown-reporter",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": "./index.js",
+  "description": "StrykerJS reporter plugin that writes mutation testing results as a Markdown table",
+  "keywords": [
+    "stryker",
+    "stryker-plugin",
+    "stryker-reporter",
+    "mutation-testing",
+    "mutation-testing-report",
+    "reporter",
+    "markdown"
+  ],
+  "homepage": "https://github.com/DmitriyZverev/stryker-markdown-reporter",
+  "bugs": {
+    "url": "https://github.com/DmitriyZverev/stryker-markdown-reporter/issues",
+    "email": "opensource@zver.dev"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Dmitriy Zverev",
+    "email": "opensource@zver.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DmitriyZverev/stryker-markdown-reporter.git"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf .package && npx tsc --outDir .package && cp package.json LICENSE README.md .package",
+    "analyzer:code:fix": "npx eslint --no-error-on-unmatched-pattern --fix --ext .ts,.tsx,.js .",
+    "analyzer:code:check": "npx eslint --no-error-on-unmatched-pattern --ext .ts,.tsx,.js .",
+    "analyzer:api:check": "npx api-extractor run --local --verbose",
+    "formatter:fix": "npx prettier --write \"**/*.{ts,tsx,js,json,yml,md,html}\"",
+    "formatter:check": "npx prettier --check \"**/*.{ts,tsx,js,json,yml,md,html}\"",
+    "test": "npx vitest run"
+  },
+  "dependencies": {
+    "@stryker-mutator/api": "^10.0.0"
+  },
+  "peerDependencies": {
+    "@stryker-mutator/core": "^10.0.0"
+  },
+  "devDependencies": {
+    "@dmitriyzverev/eslint-config": "3.0.1",
+    "@dmitriyzverev/prettier-config": "2.0.0",
+    "@dmitriyzverev/typescript-config": "1.1.1",
+    "@microsoft/api-extractor": "7.59.1",
+    "@stryker-mutator/core": "10.0.0",
+    "@types/node": "24.13.5",
+    "@vitest/coverage-v8": "5.0.1",
+    "eslint": "8.57.1",
+    "prettier": "3.9.7",
+    "typescript": "5.9.3",
+    "vitest": "5.0.1"
+  }
+}

package/src/MarkdownReporter.d.ts

@@ -0,0 +1,14 @@
+import type { StrykerOptions } from '@stryker-mutator/api/core';
+import type { Logger } from '@stryker-mutator/api/logging';
+import type { Reporter } from '@stryker-mutator/api/report';
+import type { MutationTestMetricsResult } from './types.js';
+export declare class MarkdownReporter implements Reporter {
+    static readonly inject: ["options", "logger"];
+    private readonly options;
+    private readonly log;
+    private mainPromise?;
+    constructor(options: StrykerOptions, log: Logger);
+    onMutationTestReportReady(_report: unknown, { systemUnderTestMetrics }: MutationTestMetricsResult): void;
+    wrapUp(): Promise<void> | undefined;
+    private generateReport;
+}

package/src/MarkdownReporter.js

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { commonTokens, tokens } from '@stryker-mutator/api/plugin';
+import { formatReport } from './formatReport.js';
+export class MarkdownReporter {
+    static inject = tokens(commonTokens.options, commonTokens.logger);
+    options;
+    log;
+    mainPromise;
+    constructor(options, log) {
+        this.options = options;
+        this.log = log;
+    }
+    onMutationTestReportReady(_report, { systemUnderTestMetrics }) {
+        this.mainPromise = this.generateReport(systemUnderTestMetrics);
+    }
+    wrapUp() {
+        return this.mainPromise;
+    }
+    async generateReport(systemUnderTestMetrics) {
+        const { markdownReporter: { fileName, splitErrors }, thresholds, } = this.options;
+        this.log.debug(`Using file "${fileName}"`);
+        const markdown = formatReport(systemUnderTestMetrics, { thresholds, splitErrors });
+        await mkdir(dirname(fileName), { recursive: true });
+        await writeFile(fileName, markdown, 'utf8');
+        this.log.info(`Your report can be found at: ${pathToFileURL(resolve(fileName)).href}`);
+    }
+}

package/src/formatReport.d.ts

@@ -0,0 +1,7 @@
+import type { MutationScoreThresholds } from '@stryker-mutator/api/core';
+import type { MetricsResult } from './types.js';
+export interface FormatOptions {
+    thresholds: MutationScoreThresholds;
+    splitErrors: boolean;
+}
+export declare const formatReport: (result: MetricsResult, formatOptions: FormatOptions) => string;

package/src/formatReport.js

@@ -0,0 +1,70 @@
+const ALIGNMENTS = Object.freeze({
+    left: {
+        formatMarker: (width) => `:${'-'.repeat(width - 1)}`,
+        pad: (value, width) => value.padEnd(width),
+    },
+    right: {
+        formatMarker: (width) => `${'-'.repeat(width - 1)}:`,
+        pad: (value, width) => value.padStart(width),
+    },
+});
+const MIN_COLUMN_WIDTH = 3;
+const SCORE_MARKERS = Object.freeze({
+    GOOD: '🟢',
+    WARNING: '🟡',
+    DANGER: '🔴',
+});
+const formatTable = (columns, rows) => {
+    const sizedColumns = columns.map((column) => ({
+        ...column,
+        width: Math.max(MIN_COLUMN_WIDTH, column.name.length, ...rows.map((row) => column.getValue(row).length)),
+    }));
+    const formatLine = (getCell) => `| ${sizedColumns.map((column) => ALIGNMENTS[column.alignment].pad(getCell(column), column.width)).join(' | ')} |`;
+    return [
+        formatLine(({ name }) => name),
+        formatLine(({ alignment, width }) => ALIGNMENTS[alignment].formatMarker(width)),
+        ...rows.map((row) => formatLine(({ getValue }) => getValue(row))),
+    ];
+};
+const formatScore = (score, { high, low }) => {
+    if (Number.isNaN(score)) {
+        return 'n/a';
+    }
+    const status = score >= high ? SCORE_MARKERS.GOOD : score >= low ? SCORE_MARKERS.WARNING : SCORE_MARKERS.DANGER;
+    return `${status} ${score.toFixed(2)}%`;
+};
+const metricColumn = (name, getValue) => ({
+    name,
+    alignment: 'right',
+    getValue: ({ metrics }) => String(getValue(metrics)),
+});
+const createColumns = ({ thresholds, splitErrors }) => [
+    { name: 'File', alignment: 'left', getValue: ({ name }) => name },
+    metricColumn('score', (metrics) => formatScore(metrics.mutationScore, thresholds)),
+    metricColumn('covered', (metrics) => formatScore(metrics.mutationScoreBasedOnCoveredCode, thresholds)),
+    metricColumn('killed', (metrics) => metrics.killed),
+    metricColumn('timeout', (metrics) => metrics.timeout),
+    metricColumn('survived', (metrics) => metrics.survived),
+    metricColumn('no cov', (metrics) => metrics.noCoverage),
+    metricColumn('ignored', (metrics) => metrics.ignored),
+    ...(splitErrors
+        ? [
+            metricColumn('runtime errors', (metrics) => metrics.runtimeErrors),
+            metricColumn('compile errors', (metrics) => metrics.compileErrors),
+        ]
+        : [metricColumn('errors', (metrics) => metrics.runtimeErrors + metrics.compileErrors)]),
+];
+const formatThresholds = ({ high, low, break: breaking }) => `Thresholds: ${SCORE_MARKERS.GOOD} ≥ ${high}, ${SCORE_MARKERS.WARNING} ≥ ${low}, ${SCORE_MARKERS.DANGER} < ${low}${breaking === null ? '' : `, break < ${breaking}`}`;
+const escapeMarkdown = (value) => value.replace(/[\\`*_[\]<>|~&$]/g, '\\$&');
+const collectFiles = (result, path = []) => result.childResults.flatMap((child) => child.file
+    ? [{ name: escapeMarkdown([...path, child.name].join('/')), metrics: child.metrics }]
+    : collectFiles(child, [...path, child.name]));
+export const formatReport = (result, formatOptions) => [
+    ...formatTable(createColumns(formatOptions), [
+        { name: '**All files**', metrics: result.metrics },
+        ...collectFiles(result),
+    ]),
+    '',
+    formatThresholds(formatOptions.thresholds),
+    '',
+].join('\n');

package/src/index.d.ts

@@ -0,0 +1,6 @@
+import { PluginKind } from '@stryker-mutator/api/plugin';
+export { strykerValidationSchema } from './strykerValidationSchema.js';
+/**
+ * @public
+ */
+export declare const strykerPlugins: import("@stryker-mutator/api/plugin").ClassPlugin<PluginKind.Reporter, ["options", "logger"]>[];

package/src/index.js

@@ -0,0 +1,7 @@
+import { declareClassPlugin, PluginKind } from '@stryker-mutator/api/plugin';
+import { MarkdownReporter } from './MarkdownReporter.js';
+export { strykerValidationSchema } from './strykerValidationSchema.js';
+/**
+ * @public
+ */
+export const strykerPlugins = [declareClassPlugin(PluginKind.Reporter, 'markdown', MarkdownReporter)];

package/src/strykerValidationSchema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @public
+ */
+export declare const strykerValidationSchema: {
+    $schema: string;
+    type: string;
+    properties: {
+        markdownReporter: {
+            description: string;
+            type: string;
+            additionalProperties: boolean;
+            default: {};
+            properties: {
+                fileName: {
+                    description: string;
+                    type: string;
+                    default: string;
+                };
+                splitErrors: {
+                    description: string;
+                    type: string;
+                    default: boolean;
+                };
+            };
+        };
+    };
+};
+export interface MarkdownReporterOptions {
+    markdownReporter: {
+        fileName: string;
+        splitErrors: boolean;
+    };
+}

package/src/strykerValidationSchema.js

@@ -0,0 +1,27 @@
+/**
+ * @public
+ */
+export const strykerValidationSchema = {
+    $schema: 'http://json-schema.org/draft-07/schema',
+    type: 'object',
+    properties: {
+        markdownReporter: {
+            description: 'Configuration for the markdown reporter',
+            type: 'object',
+            additionalProperties: false,
+            default: {},
+            properties: {
+                fileName: {
+                    description: 'The relative filename for the markdown report',
+                    type: 'string',
+                    default: 'reports/mutation/mutation.md',
+                },
+                splitErrors: {
+                    description: 'Show runtime and compile errors in separate columns instead of a single one',
+                    type: 'boolean',
+                    default: false,
+                },
+            },
+        },
+    },
+};

package/src/types.d.ts

@@ -0,0 +1,20 @@
+export interface Metrics {
+    mutationScore: number;
+    mutationScoreBasedOnCoveredCode: number;
+    killed: number;
+    timeout: number;
+    survived: number;
+    noCoverage: number;
+    ignored: number;
+    runtimeErrors: number;
+    compileErrors: number;
+}
+export interface MetricsResult {
+    name: string;
+    file?: object;
+    childResults: MetricsResult[];
+    metrics: Metrics;
+}
+export interface MutationTestMetricsResult {
+    systemUnderTestMetrics: MetricsResult;
+}

package/src/types.js

@@ -0,0 +1 @@
+export {};