feat: add markdown output format to stats command (#1395)

* fix: Remove non-json format elements from JSON output

* feat: Add markdown output format, suitable for use in GitHub Job Summaries

* chore: run prettier, update snapshot for existing tests

* chore: add tests for all the stats output formats

* chore: add museum file, run prettier

* fix: Tidy up some ends spotted by eslint

* fix: Tidy up some ends spotted by eslint

* feat: reinstate debug/timing output for stylish format only

* chore: update snapshots with timing output

* chore: run prettier

* feat: Add markdown table formatting to stats markdown output

* chore: update snapshots for new output format

* docs: Add changeset for markdown format option in stats command

.changeset/pink-waves-press.md

@@ -0,0 +1,5 @@
+---
+"@redocly/cli": patch
+---
+
+Added markdown format option to stats command for use with GitHub job summaries.

__tests__/commands.test.ts

@@ -494,4 +494,35 @@ describe('E2E', () => {
       expect(fs.statSync(join(testPath, 'nested/redoc-static.html')).size).toEqual(33016);
     });
   });
+
+  describe('stats', () => {
+    const folderPath = join(__dirname, 'stats');
+
+    test('stats should produce correct output (stylish format)', () => {
+      const testPath = join(folderPath, 'stats-stylish');
+      const args = getParams('../../../packages/cli/src/index.ts', 'stats', ['museum.yaml']);
+      const result = getCommandOutput(args, testPath);
+      (<any>expect(result)).toMatchSpecificSnapshot(join(testPath, 'snapshot.js'));
+    });
+
+    test('stats should produce correct JSON output', () => {
+      const testPath = join(folderPath, 'stats-json');
+      const args = getParams('../../../packages/cli/src/index.ts', 'stats', [
+        'museum.yaml',
+        '--format=json',
+      ]);
+      const result = getCommandOutput(args, testPath);
+      (<any>expect(result)).toMatchSpecificSnapshot(join(testPath, 'snapshot.js'));
+    });
+
+    test('stats should produce correct Markdown format', () => {
+      const testPath = join(folderPath, 'stats-markdown');
+      const args = getParams('../../../packages/cli/src/index.ts', 'stats', [
+        'museum.yaml',
+        '--format=markdown',
+      ]);
+      const result = getCommandOutput(args, testPath);
+      (<any>expect(result)).toMatchSpecificSnapshot(join(testPath, 'snapshot.js'));
+    });
+  });
 });

__tests__/stats/stats-json/museum.yaml

@@ -0,0 +1 @@
+../../../resources/museum.yaml

__tests__/stats/stats-json/snapshot.js

@@ -0,0 +1,39 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`E2E stats stats should produce correct JSON output 1`] = `
+{
+  "refs": {
+    "metric": "🚗 References",
+    "total": 39
+  },
+  "externalDocs": {
+    "metric": "📦 External Documents",
+    "total": 0
+  },
+  "schemas": {
+    "metric": "📈 Schemas",
+    "total": 22
+  },
+  "parameters": {
+    "metric": "👉 Parameters",
+    "total": 6
+  },
+  "links": {
+    "metric": "🔗 Links",
+    "total": 0
+  },
+  "pathItems": {
+    "metric": "➡️  Path Items",
+    "total": 5
+  },
+  "operations": {
+    "metric": "👷 Operations",
+    "total": 8
+  },
+  "tags": {
+    "metric": "🔖 Tags",
+    "total": 3
+  }
+}
+
+`;

__tests__/stats/stats-markdown/museum.yaml

@@ -0,0 +1 @@
+../../../resources/museum.yaml

__tests__/stats/stats-markdown/snapshot.js

@@ -0,0 +1,16 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`E2E stats stats should produce correct Markdown format 1`] = `
+| Feature  | Count  |
+| --- | --- |
+| 🚗 References | 39 |
+| 📦 External Documents | 0 |
+| 📈 Schemas | 22 |
+| 👉 Parameters | 6 |
+| 🔗 Links | 0 |
+| ➡️  Path Items | 5 |
+| 👷 Operations | 8 |
+| 🔖 Tags | 3 |
+
+
+`;

__tests__/stats/stats-stylish/museum.yaml

@@ -0,0 +1 @@
+../../../resources/museum.yaml

__tests__/stats/stats-stylish/snapshot.js

@@ -0,0 +1,19 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`E2E stats stats should produce correct output (stylish format) 1`] = `
+
+Document: museum.yaml stats:
+
+🚗 References: 39 
+📦 External Documents: 0 
+📈 Schemas: 22 
+👉 Parameters: 6 
+🔗 Links: 0 
+➡️  Path Items: 5 
+👷 Operations: 8 
+🔖 Tags: 3 
+
+museum.yaml: stats processed in <test>ms
+
+
+`;

packages/cli/src/commands/stats.ts

@@ -46,15 +46,37 @@ function printStatsJson(statsAccumulator: StatsAccumulator) {
   process.stdout.write(JSON.stringify(json, null, 2));
 }
 
-function printStats(statsAccumulator: StatsAccumulator, api: string, format: string) {
-  process.stderr.write(`Document: ${colors.magenta(api)} stats:\n\n`);
+function printStatsMarkdown(statsAccumulator: StatsAccumulator) {
+  let output = '| Feature  | Count  |\n| --- | --- |\n';
+  for (const key of Object.keys(statsAccumulator)) {
+    output +=
+      '| ' +
+      statsAccumulator[key as StatsName].metric +
+      ' | ' +
+      statsAccumulator[key as StatsName].total +
+      ' |\n';
+  }
+  process.stdout.write(output);
+}
+
+function printStats(
+  statsAccumulator: StatsAccumulator,
+  api: string,
+  startedAt: number,
+  format: string
+) {
   switch (format) {
     case 'stylish':
+      process.stderr.write(`Document: ${colors.magenta(api)} stats:\n\n`);
       printStatsStylish(statsAccumulator);
+      printExecutionTime('stats', startedAt, api);
       break;
     case 'json':
       printStatsJson(statsAccumulator);
       break;
+    case 'markdown':
+      printStatsMarkdown(statsAccumulator);
+      break;
   }
 }
 
@@ -107,6 +129,5 @@ export async function handleStats(argv: StatsOptions, config: Config) {
     ctx,
   });
 
-  printStats(statsAccumulator, path, argv.format);
-  printExecutionTime('stats', startedAt, path);
+  printStats(statsAccumulator, path, startedAt, argv.format);
 }

packages/cli/src/index.ts

@@ -46,7 +46,7 @@ yargs
         },
         format: {
           description: 'Use a specific output format.',
-          choices: ['stylish', 'json'] as ReadonlyArray<OutputFormat>,
+          choices: ['stylish', 'json', 'markdown'] as ReadonlyArray<OutputFormat>,
           default: 'stylish' as OutputFormat,
         },
       }),