feat: implement functionality to output the scorecard results to JSON

Author: AlbinaBlazhko17

packages/cli/src/commands/scorecard-classic/formatters/json-formatter.ts

@@ -0,0 +1,119 @@
+import { writeFileSync } from 'node:fs';
+import { logger, getLineColLocation } from '@redocly/openapi-core';
+import { blue, green } from 'colorette';
+import { formatPath, getExecutionTime } from '../../../utils/miscellaneous.js';
+
+import type { ScorecardProblem } from '../types.js';
+
+type ScorecardLevel = {
+  summary: {
+    errors: number;
+    warnings: number;
+  };
+  problems: Array<{
+    ruleId: string;
+    ruleUrl?: string;
+    severity: string;
+    message: string;
+    location: {
+      file: string;
+      range: string;
+      pointer?: string;
+    }[];
+  }>;
+};
+
+export type ScorecardJsonOutput = Record<string, ScorecardLevel>;
+
+function formatRange(
+  start: { line: number; col: number },
+  end?: { line: number; col: number }
+): string {
+  const startStr = `Line ${start.line}, Col ${start.col}`;
+  if (!end) {
+    return startStr;
+  }
+  const endStr = `Line ${end.line}, Col ${end.col}`;
+  return `${startStr} → ${endStr}`;
+}
+
+function getRuleUrl(ruleId: string): string | undefined {
+  if (!ruleId.includes('/')) {
+    return `https://redocly.com/docs/cli/rules/oas/${ruleId}.md`;
+  }
+  return undefined;
+}
+
+function stripAnsiCodes(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\u001b\[\d+m/g, '');
+}
+
+export function exportScorecardResultsToJson(
+  path: string,
+  problems: ScorecardProblem[],
+  outputPath: string
+): void {
+  const startedAt = performance.now();
+  const groupedByLevel: Record<string, ScorecardProblem[]> = {};
+
+  for (const problem of problems) {
+    const level = problem.scorecardLevel || 'Unknown';
+    if (!groupedByLevel[level]) {
+      groupedByLevel[level] = [];
+    }
+    groupedByLevel[level].push(problem);
+  }
+
+  const output: ScorecardJsonOutput = {};
+
+  for (const [levelName, levelProblems] of Object.entries(groupedByLevel)) {
+    let errors = 0;
+    let warnings = 0;
+
+    const formattedProblems = levelProblems.map((problem) => {
+      if (problem.severity === 'error') errors++;
+      if (problem.severity === 'warn') warnings++;
+
+      return {
+        ruleId: problem.ruleId,
+        ruleUrl: getRuleUrl(problem.ruleId),
+        severity: problem.severity,
+        message: stripAnsiCodes(problem.message),
+
+        location: problem.location.map((loc) => {
+          const lineCol = getLineColLocation(loc);
+          return {
+            file: loc.source.absoluteRef,
+            range: formatRange(lineCol.start, lineCol.end),
+            pointer: loc.pointer,
+          };
+        }),
+      };
+    });
+
+    output[levelName] = {
+      summary: {
+        errors,
+        warnings,
+      },
+      problems: formattedProblems,
+    };
+  }
+
+  try {
+    writeFileSync(outputPath, JSON.stringify(output, null, 2), 'utf-8');
+    const elapsed = getExecutionTime(startedAt);
+    logger.info(
+      `📊 Scorecard results for ${blue(formatPath(path))} at ${blue(
+        outputPath || 'stdout'
+      )} ${green(elapsed)}.\n`
+    );
+  } catch (error) {
+    logger.info(
+      `❌ Errors encountered while bundling ${blue(
+        formatPath(path)
+      )}: bundle not created (use --force to ignore errors).\n`
+    );
+  }
+}

packages/cli/src/commands/scorecard-classic/index.ts

@@ -1,10 +1,12 @@
-import { getFallbackApisOrExit } from '../../utils/miscellaneous.js';
+import { formatPath, getFallbackApisOrExit } from '../../utils/miscellaneous.js';
 import { BaseResolver, bundle, logger } from '@redocly/openapi-core';
 import { exitWithError } from '../../utils/error.js';
 import { handleLoginAndFetchToken } from './auth/login-handler.js';
 import { printScorecardResults } from './formatters/stylish-formatter.js';
+import { exportScorecardResultsToJson } from './formatters/json-formatter.js';
 import { fetchRemoteScorecardAndPlugins } from './remote/fetch-scorecard.js';
 import { validateScorecard } from './validation/validate-scorecard.js';
+import { gray } from 'colorette';
 
 import type { ScorecardClassicArgv } from './types.js';
 import type { CommandArgs } from '../../wrapper.js';
@@ -37,7 +39,7 @@ export async function handleScorecardClassic({ argv, config }: CommandArgs<Score
     );
   }
 
-  logger.info(`\nRunning Scorecard Classic...\n`);
+  logger.info(gray(`\nRunning scorecard for ${formatPath(path)}...\n`));
   const result = await validateScorecard(
     document,
     externalRefResolver,
@@ -46,5 +48,9 @@ export async function handleScorecardClassic({ argv, config }: CommandArgs<Score
     remoteScorecardAndPlugins?.plugins
   );
 
-  printScorecardResults(result, path);
+  if (argv.output) {
+    exportScorecardResultsToJson(path, result, argv.output);
+  } else {
+    printScorecardResults(result, path);
+  }
 }

packages/cli/src/commands/scorecard-classic/types.ts

@@ -5,6 +5,7 @@ export type ScorecardClassicArgv = {
   api: string;
   config: string;
   'project-url'?: string;
+  output?: string;
 } & VerifyConfigOptions;
 
 export type ScorecardProblem = NormalizedProblem & { scorecardLevel?: string };

packages/cli/src/index.ts

@@ -811,6 +811,11 @@ yargs(hideBin(process.argv))
           describe: 'URL to the project scorecard configuration.',
           type: 'string',
         },
+        output: {
+          describe: 'Output file for JSON results.',
+          type: 'string',
+          alias: 'o',
+        },
       });
     },
     async (argv) => {