feat(core): add documentUrl to JS api and cli formatters (#2443)

* feat(core): add documentUrl to JS api and cli formatters

* fix(test-harness): strip spectral version from sarif tests

* chore(test-harness): fix whitespace linting issue

* chore(test-harness): fix whitespace lint issue

---------

Co-authored-by: Nauman <[email protected]>
Co-authored-by: Frank Kilcommins <[email protected]>
Co-authored-by: Frank Kilcommins <[email protected]>

Author: 3 people

docs/guides/2-cli.md

@@ -41,12 +41,13 @@ Other options include:
       --resolver                 path to custom json-ref-resolver instance                                      [string]
   -r, --ruleset                  path/URL to a ruleset file                                                     [string]
   -F, --fail-severity            results of this level or above will trigger a failure exit code
-                                                                     [string] [choices: "error", "warn", "info", "hint"] [default: "error"]
-  -D, --display-only-failures    only output results equal to or greater than --fail-severity                    [boolean] [default: false]
-      --ignore-unknown-format    do not warn about unmatched formats                                             [boolean] [default: false]
-      --fail-on-unmatched-globs  fail on unmatched glob patterns                                                 [boolean] [default: false]
-  -v, --verbose                  increase verbosity                                                                               [boolean]
-  -q, --quiet                    no logging - output only                                                                         [boolean]
+                                                  [string] [choices: "error", "warn", "info", "hint"] [default: "error"]
+  -D, --display-only-failures    only output results equal to or greater than --fail-severity [boolean] [default: false]
+      --ignore-unknown-format    do not warn about unmatched formats                          [boolean] [default: false]
+      --fail-on-unmatched-globs  fail on unmatched glob patterns                              [boolean] [default: false]
+      --show-documentation-url   show documentation url in output result                      [boolean] [default: false]
+  -v, --verbose                  increase verbosity                                                            [boolean]
+  -q, --quiet                    no logging - output only                                                      [boolean]
 ```
 
 The Spectral CLI supports loading documents as YAML or JSON, and validation of OpenAPI v2/v3 documents via the built-in ruleset.

packages/cli/src/commands/__tests__/lint.test.ts

@@ -81,6 +81,7 @@ describe('lint', () => {
         output: { stylish: '<stdout>' },
         ignoreUnknownFormat: false,
         failOnUnmatchedGlobs: false,
+        showDocumentationUrl: false,
       });
     });
   });
@@ -94,6 +95,7 @@ describe('lint', () => {
       output: { stylish: '<stdout>' },
       ignoreUnknownFormat: false,
       failOnUnmatchedGlobs: false,
+      showDocumentationUrl: false,
     });
   });
 
@@ -106,6 +108,7 @@ describe('lint', () => {
       output: { stylish: '<stdout>' },
       ignoreUnknownFormat: false,
       failOnUnmatchedGlobs: false,
+      showDocumentationUrl: false,
     });
   });
 
@@ -118,6 +121,7 @@ describe('lint', () => {
       output: { json: '<stdout>' },
       ignoreUnknownFormat: false,
       failOnUnmatchedGlobs: false,
+      showDocumentationUrl: false,
     });
   });
 
@@ -184,6 +188,7 @@ describe('lint', () => {
       output: { stylish: '<stdout>' },
       ignoreUnknownFormat: true,
       failOnUnmatchedGlobs: false,
+      showDocumentationUrl: false,
     });
   });
 
@@ -195,6 +200,7 @@ describe('lint', () => {
       output: { stylish: '<stdout>' },
       ignoreUnknownFormat: false,
       failOnUnmatchedGlobs: true,
+      showDocumentationUrl: false,
     });
   });
 
@@ -244,13 +250,13 @@ describe('lint', () => {
     expect(process.stderr.write).nthCalledWith(2, `Error #1: ${chalk.red('some unhandled exception')}\n`);
     expect(process.stderr.write).nthCalledWith(
       3,
-      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:236`),
+      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:242`),
     );
 
     expect(process.stderr.write).nthCalledWith(4, `Error #2: ${chalk.red('another one')}\n`);
     expect(process.stderr.write).nthCalledWith(
       5,
-      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:237`),
+      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:243`),
     );
 
     expect(process.stderr.write).nthCalledWith(6, `Error #3: ${chalk.red('original exception')}\n`);

packages/cli/src/commands/lint.ts

@@ -151,6 +151,11 @@ const lintCommand: CommandModule = {
           type: 'boolean',
           default: false,
         },
+        'show-documentation-url': {
+          description: 'show documentation url in output result',
+          type: 'boolean',
+          default: false,
+        },
         verbose: {
           alias: 'v',
           description: 'increase verbosity',
@@ -175,6 +180,7 @@ const lintCommand: CommandModule = {
       encoding,
       ignoreUnknownFormat,
       failOnUnmatchedGlobs,
+      showDocumentationUrl,
       ...config
     } = args as unknown as ILintConfig & {
       documents: Array<number | string>;
@@ -189,6 +195,7 @@ const lintCommand: CommandModule = {
         encoding,
         ignoreUnknownFormat,
         failOnUnmatchedGlobs,
+        showDocumentationUrl,
         ruleset,
         stdinFilepath,
         ...pick<Partial<ILintConfig>, keyof ILintConfig>(config, ['verbose', 'quiet', 'resolver']),
@@ -198,6 +205,10 @@ const lintCommand: CommandModule = {
         linterResult.results = filterResultsBySeverity(linterResult.results, failSeverity);
       }
 
+      if (!showDocumentationUrl) {
+        linterResult.results = removeDocumentationUrlFromResults(linterResult.results);
+      }
+
       await Promise.all(
         format.map(f => {
           const formattedOutput = formatOutput(
@@ -279,6 +290,10 @@ const filterResultsBySeverity = (results: IRuleResult[], failSeverity: FailSever
   return results.filter(r => r.severity <= diagnosticSeverity);
 };
 
+const removeDocumentationUrlFromResults = (results: IRuleResult[]): IRuleResult[] => {
+  return results.map(r => ({ ...r, documentationUrl: undefined }));
+};
+
 export const severeEnoughToFail = (results: IRuleResult[], failSeverity: FailSeverity): boolean => {
   const diagnosticSeverity = getDiagnosticSeverity(failSeverity);
   return results.some(r => r.severity <= diagnosticSeverity);

packages/cli/src/services/config.ts

@@ -27,6 +27,7 @@ export interface ILintConfig {
   stdinFilepath?: string;
   ignoreUnknownFormat: boolean;
   failOnUnmatchedGlobs: boolean;
+  showDocumentationUrl: boolean;
   verbose?: boolean;
   quiet?: boolean;
 }

packages/core/src/runner/lintNode.ts

@@ -99,6 +99,7 @@ function processTargetResults(
       severity,
       ...(source !== null ? { source } : null),
       range,
+      documentationUrl: rule.documentationUrl ?? undefined,
     });
   }
 }

packages/core/src/types/spectral.ts

@@ -13,6 +13,7 @@ export interface IRunOpts {
 export interface ISpectralDiagnostic extends IDiagnostic {
   path: JsonPath;
   code: string | number;
+  documentationUrl?: string;
 }
 
 export type IRuleResult = ISpectralDiagnostic;

packages/formatters/src/__tests__/html.test.ts

@@ -18,36 +18,42 @@ describe('HTML formatter', () => {
     <td>3:10</td>
     <td class="severity clr-hint">hint</td>
     <td>Info object should contain \`contact\` object.</td>
+    <td></td>
 </tr>
 
 <tr style="display:none" class="f-0">
     <td>3:10</td>
     <td class="severity clr-warning">warning</td>
     <td>OpenAPI object info \`description\` must be present and non-empty string.</td>
+    <td></td>
 </tr>
 
 <tr style="display:none" class="f-0">
     <td>5:14</td>
     <td class="severity clr-error">error</td>
     <td>Info must contain Stoplight</td>
+    <td></td>
 </tr>
 
 <tr style="display:none" class="f-0">
     <td>17:13</td>
     <td class="severity clr-information">information</td>
     <td>Operation \`description\` must be present and non-empty string.</td>
+    <td></td>
 </tr>
 
 <tr style="display:none" class="f-0">
     <td>64:14</td>
     <td class="severity clr-information">information</td>
     <td>Operation \`description\` must be present and non-empty string.</td>
+    <td></td>
 </tr>
 
 <tr style="display:none" class="f-0">
     <td>86:13</td>
     <td class="severity clr-information">information</td>
     <td>Operation \`description\` must be present and non-empty string.</td>
+    <td></td>
 </tr>`);
   });
 });

packages/formatters/src/github-actions.ts

@@ -41,7 +41,9 @@ export const githubActions: Formatter = results => {
       // FIXME: Use replaceAll instead after removing Node.js 14 support.
       const message = result.message.replace(/\n/g, '%0A');
 
-      return `::${OUTPUT_TYPES[result.severity]} ${paramsString}::${message}`;
+      return `::${OUTPUT_TYPES[result.severity]} ${paramsString}::${message}${
+        result.documentationUrl ? `::${result.documentationUrl}` : ''
+      }`;
     })
     .join('\n');
 };

packages/formatters/src/html/html-template-message.html

@@ -2,4 +2,5 @@
     <td><%= line %>:<%= character %></td>
     <td class="severity clr-<%= severity %>"><%= severity %></td>
     <td><%- message %></td>
+    <td><% if(documentationUrl) { %><a href="<%- documentationUrl %>" target="_blank">documentation</a><% } %></td>
 </tr>

packages/formatters/src/html/index.ts

@@ -50,6 +50,7 @@ function renderMessages(messages: IRuleResult[], parentIndex: number): string {
         severity: getSeverityName(message.severity),
         message: message.message,
         code: message.code,
+        documentationUrl: message.documentationUrl,
       });
     })
     .join('\n');