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

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');

packages/formatters/src/json.ts

@@ -2,13 +2,20 @@ import { Formatter } from './types';
 
 export const json: Formatter = results => {
  const outputJson = results.map(result => {
+ let documentationUrlObject = {};
+ if (result.documentationUrl) {
+ documentationUrlObject = {
+ documentationUrl: result.documentationUrl,
+ };
+ }
  return {
  code: result.code,
  path: result.path,
  message: result.message,
  severity: result.severity,
  range: result.range,
  source: result.source,
+ ...documentationUrlObject,
  };
  });
  return JSON.stringify(outputJson, null, '\t');

packages/formatters/src/junit.ts

@@ -62,6 +62,9 @@ export const junit: Formatter = (results, { failSeverity }) => {
  output += `line ${result.range.start.line + 1}, col ${result.range.start.character + 1}, `;
  output += `${prepareForCdata(result.message)} (${result.code}) `;
  output += `at path ${prepareForCdata(path)}`;
+ if (result.documentationUrl) {
+ output += `, ${result.documentationUrl}`;
+ }
  output += ']]>';
  output += `</failure>`;
  output += '</testcase>\n';

packages/formatters/src/pretty.ts

@@ -74,6 +74,11 @@ export const pretty: Formatter = results => {
  { text: chalk[color].bold(result.code), padding: PAD_TOP0_LEFT2, width: COLUMNS[2] },
  { text: chalk.gray(result.message), padding: PAD_TOP0_LEFT2, width: COLUMNS[3] },
  { text: chalk.cyan(printPath(result.path, PrintStyle.Dot)), padding: PAD_TOP0_LEFT2 },
+ {
+ text: chalk.gray(result.documentationUrl ?? ''),
+ padding: PAD_TOP0_LEFT2,
+ width: result.documentationUrl ? undefined : 0.1,
+ },
  );
  ui.div();
  });

packages/formatters/src/sarif.ts

@@ -44,7 +44,7 @@ export const sarif: Formatter = (results, _, ctx) => {
  const severity: DiagnosticSeverity = result.severity || DiagnosticSeverity.Error;
  sarifResultBuilder.initSimple({
  level: OUTPUT_TYPES[severity] || 'error',
- messageText: result.message,
+ messageText: result.documentationUrl ? `${result.message} -- ${result.documentationUrl}` : result.message,
  ruleId: result.code.toString(),
  fileUri: relative(process.cwd(), result.source ?? '').replace(/\\/g, '/'),
  startLine: result.range.start.line + 1,

packages/formatters/src/stylish.ts

@@ -72,6 +72,7 @@ export const stylish: Formatter = results => {
  result.code ?? '',
  result.message,
  printPath(result.path, PrintStyle.Dot),
+ result.documentationUrl ?? '',
  ]);
 
  output += `${table(pathTableData, {

packages/formatters/src/teamcity.ts

@@ -23,7 +23,8 @@ function inspectionType(result: IRuleResult & { source: string }): string {
  const code = escapeString(result.code);
  const severity = getSeverityName(result.severity);
  const message = escapeString(result.message);
- return `##teamcity[inspectionType category='openapi' id='${code}' name='${code}' description='${severity} -- ${message}']`;
+ const documentationUrl = result.documentationUrl ? ` -- ${escapeString(result.documentationUrl)}` : '';
+ return `##teamcity[inspectionType category='openapi' id='${code}' name='${code}' description='${severity} -- ${message}${documentationUrl}']`;
 }
 
 function inspection(result: IRuleResult & { source: string }): string {

packages/formatters/src/text.ts

@@ -12,7 +12,8 @@ function renderResults(results: IRuleResult[]): string {
  const line = result.range.start.line + 1;
  const character = result.range.start.character + 1;
  const severity = getSeverityName(result.severity);
- return `${result.source}:${line}:${character} ${severity} ${result.code} "${result.message}"`;
+ const documentationUrl = result.documentationUrl ? ` ${result.documentationUrl}` : '';
+ return `${result.source}:${line}:${character} ${severity} ${result.code} "${result.message}"${documentationUrl}`;
  })
  .join('\n');
 }

packages/rulesets/src/asyncapi/functions/__tests__/asyncApi2DocumentSchema.test.ts

@@ -43,6 +43,7 @@ describe('asyncApi2DocumentSchema', () => {
  ).toEqual([
  {
  code: 'asyncapi-schema',
+ documentationUrl: 'https://meta.stoplight.io/docs/spectral/docs/reference/asyncapi-rules.md#asyncapi-schema',
  message: '"info" property must have required property "title"',
  path: ['info'],
  severity: DiagnosticSeverity.Error,
@@ -131,13 +132,15 @@ describe('asyncApi2DocumentSchema', () => {
  ).toEqual([
  {
  code: 'asyncapi-schema',
+ documentationUrl: 'https://meta.stoplight.io/docs/spectral/docs/reference/asyncapi-rules.md#asyncapi-schema',
  message: '"0" property type must be string',
  path: ['channels', '/user/signedup', 'servers', '0'],
  severity: DiagnosticSeverity.Error,
  range: expect.any(Object),
  },
  {
  code: 'asyncapi-schema',
+ documentationUrl: 'https://meta.stoplight.io/docs/spectral/docs/reference/asyncapi-rules.md#asyncapi-schema',
  message: '"2" property type must be string',
  path: ['channels', '/user/signedup', 'servers', '2'],
  severity: DiagnosticSeverity.Error,
@@ -184,6 +187,7 @@ describe('asyncApi2DocumentSchema', () => {
  ).toEqual([
  {
  code: 'asyncapi-schema',
+ documentationUrl: 'https://meta.stoplight.io/docs/spectral/docs/reference/asyncapi-rules.md#asyncapi-schema',
  message: '"kafka" property must have required property "url"',
  path: ['components', 'servers', 'kafka'],
  severity: DiagnosticSeverity.Error,