refactor: init parse, lint and validate functions (#487)

jest.config.ts

@@ -10,6 +10,11 @@ const config: Config.InitialOptions = {
   // The root of your source code, typically /src
   // `<rootDir>` is a token Jest substitutes
   roots: ['<rootDir>'],
+  moduleNameMapper: {
+    '^nimma/legacy$': '<rootDir>/node_modules/nimma/dist/legacy/cjs/index.js',
+    '^nimma/(.*)': '<rootDir>/node_modules/nimma/dist/cjs/$1',
+    '^@stoplight/spectral-ruleset-bundler/(.*)$': '<rootDir>/node_modules/@stoplight/spectral-ruleset-bundler/dist/$1'
+  },
 
   // Test spec file resolution pattern
   // Matches parent folder `__tests__` and filename

src/index.ts

@@ -1,3 +1,10 @@
 export * from './models';
 
+export { lint, validate } from './lint';
+export { parse } from './parse';
 export { stringify, unstringify } from './stringify';
+
+export type { LintOptions, ValidateOptions, ValidateOutput } from './lint';
+export type { StringifyOptions } from './stringify';
+export type { ParseOptions } from './parse';
+export type { ParserInput, ParserOutput, Diagnostic } from './types';

src/lint.ts

@@ -0,0 +1,73 @@
+import {
+  IConstructorOpts,
+  IRunOpts,
+  Spectral,
+  Ruleset,
+  RulesetDefinition,
+} from "@stoplight/spectral-core";
+import { asyncapi as aasRuleset } from "@stoplight/spectral-rulesets";
+
+import { toAsyncAPIDocument, normalizeInput, hasWarningDiagnostic, hasErrorDiagnostic } from "./utils";
+
+import type { AsyncAPIDocument } from "./models/asyncapi";
+import type { ParserInput, Diagnostic } from "./types";
+
+export interface LintOptions extends IConstructorOpts, IRunOpts {
+  ruleset?: RulesetDefinition | Ruleset;
+}
+
+export interface ValidateOptions extends LintOptions {
+  allowedSeverity?: {
+    warning?: boolean;
+  };
+}
+
+export interface ValidateOutput {
+  validated: unknown;
+  diagnostics: Diagnostic[];
+}
+
+export async function lint(asyncapi: ParserInput, options?: LintOptions): Promise<Diagnostic[] | undefined> {
+  if (toAsyncAPIDocument(asyncapi)) {
+    return;
+  }
+  const document = normalizeInput(asyncapi as Exclude<ParserInput, AsyncAPIDocument>);
+  return (await validate(document, options)).diagnostics;
+}
+
+export async function validate(asyncapi: string, options?: ValidateOptions): Promise<ValidateOutput> {
+  const { ruleset, allowedSeverity, ...restOptions } = normalizeOptions(options);
+  const spectral = new Spectral(restOptions);
+
+  spectral.setRuleset(ruleset!);
+  let { resolved, results } = await spectral.runWithResolved(asyncapi);
+
+  if (
+    hasErrorDiagnostic(results) ||
+    (!allowedSeverity?.warning && hasWarningDiagnostic(results))
+  ) {
+    resolved = undefined;
+  }
+
+  return { validated: resolved, diagnostics: results };
+}
+
+const defaultOptions: ValidateOptions = {
+  // TODO: fix that type
+  ruleset: aasRuleset as any,
+  allowedSeverity: {
+    warning: true,
+  }
+};
+function normalizeOptions(options?: ValidateOptions): ValidateOptions {
+  if (!options || typeof options !== 'object') {
+    return defaultOptions;
+  }
+  // shall copy
+  options = { ...defaultOptions, ...options };
+
+  // severity
+  options.allowedSeverity = { ...defaultOptions.allowedSeverity, ...(options.allowedSeverity || {}) };
+
+  return options;
+}

src/models/base.ts

@@ -3,8 +3,8 @@ export class BaseModel {
     private readonly _json: Record<string, any>,
   ) {}
 
-  json<T = Record<string, unknown>>(): T;
-  json<T = unknown>(key: string | number): T;
+  json<T = Record<string, any>>(): T;
+  json<T = any>(key: string | number): T;
   json(key?: string | number) {
     if (key === undefined) return this._json;
     if (!this._json) return;

src/parse.ts

@@ -0,0 +1,64 @@
+import { AsyncAPIDocument } from "./models";
+import { normalizeInput, toAsyncAPIDocument } from "./utils";
+import { validate } from "./lint";
+
+import type { ParserInput, ParserOutput } from './types';
+import type { ValidateOptions } from './lint';
+
+export interface ParseOptions {
+  applyTraits?: boolean;
+  validateOptions?: ValidateOptions;
+}
+
+export async function parse(asyncapi: ParserInput, options?: ParseOptions): Promise<ParserOutput> {
+  let maybeDocument = toAsyncAPIDocument(asyncapi);
+  if (maybeDocument) {
+    return { 
+      source: asyncapi,
+      parsed: maybeDocument,
+      diagnostics: [],
+    };
+  }
+
+  try {
+    const document = normalizeInput(asyncapi as Exclude<ParserInput, AsyncAPIDocument>);
+    options = normalizeOptions(options);
+
+    const { validated, diagnostics } = await validate(document, options.validateOptions);
+    if (validated === undefined) {
+      return {
+        source: asyncapi,
+        parsed: undefined,
+        diagnostics,
+      };
+    }
+
+    const parsed = new AsyncAPIDocument(validated as Record<string, unknown>);
+    return { 
+      source: asyncapi,
+      parsed,
+      diagnostics,
+    };
+  } catch(err) {
+    // TODO: throw proper error
+    throw Error();
+  }
+}
+
+const defaultOptions: ParseOptions = {
+  applyTraits: true,
+};
+function normalizeOptions(options?: ParseOptions): ParseOptions {
+  if (!options || typeof options !== 'object') {
+    return defaultOptions;
+  }
+  // shall copy
+  options = { ...defaultOptions, ...options };
+
+  // traits
+  if (options.applyTraits === undefined) {
+    options.applyTraits = true;
+  }
+
+  return options;
+}

src/stringify.ts

@@ -3,7 +3,11 @@ import { AsyncAPIDocument } from './models';
 import { isAsyncAPIDocument, isParsedDocument, isStringifiedDocument } from './utils';
 import { xParserSpecStringified } from './constants';
 
-export function stringify(document: unknown, space?: string | number): string | undefined {
+export interface StringifyOptions {
+  space?: string | number;
+}
+
+export function stringify(document: unknown, options: StringifyOptions = {}): string | undefined {
   if (isAsyncAPIDocument(document)) {
     document = document.json();
   } else if (isParsedDocument(document)) {
@@ -18,7 +22,7 @@ export function stringify(document: unknown, space?: string | number): string |
   return JSON.stringify({ 
     ...document as Record<string, unknown>,
     [String(xParserSpecStringified)]: true,
-  }, refReplacer(), space);
+  }, refReplacer(), options.space || 2);
 }
 
 export function unstringify(document: unknown): AsyncAPIDocument | undefined {

src/types.ts

@@ -0,0 +1,13 @@
+import type { ISpectralDiagnostic } from '@stoplight/spectral-core';
+import type { AsyncAPIDocument } from './models/asyncapi';
+
+export type MaybeAsyncAPI = { asyncapi: unknown } & Record<string, unknown>;
+export type ParserInput = string | MaybeAsyncAPI | AsyncAPIDocument;
+
+export type Diagnostic = ISpectralDiagnostic;
+
+export interface ParserOutput {
+  source: ParserInput;
+  parsed: AsyncAPIDocument | undefined;
+  diagnostics: Diagnostic[]; 
+}

src/utils.ts

@@ -1,3 +1,4 @@
+import { DiagnosticSeverity } from '@stoplight/types';
 import { AsyncAPIDocument } from './models';
 import { unstringify } from './stringify';
 
@@ -6,6 +7,9 @@ import {
   xParserSpecStringified,
 } from './constants';
 
+import type { ISpectralDiagnostic } from '@stoplight/spectral-core';
+import type { MaybeAsyncAPI } from 'types';
+
 export function toAsyncAPIDocument(maybeDoc: unknown): AsyncAPIDocument | undefined {
   if (isAsyncAPIDocument(maybeDoc)) {
     return maybeDoc;
@@ -36,3 +40,15 @@ export function isStringifiedDocument(maybeDoc: unknown): maybeDoc is Record<str
     Boolean((maybeDoc as Record<string, unknown>)[xParserSpecStringified])
   );
 }
+
+export function normalizeInput(asyncapi: string | MaybeAsyncAPI): string {
+  return JSON.stringify(asyncapi, undefined, 2);
+};
+
+export function hasErrorDiagnostic(diagnostics: ISpectralDiagnostic[]): boolean {
+  return diagnostics.some(diagnostic => diagnostic.severity === DiagnosticSeverity.Error);
+}
+
+export function hasWarningDiagnostic(diagnostics: ISpectralDiagnostic[]): boolean {
+  return diagnostics.some(diagnostic => diagnostic.severity === DiagnosticSeverity.Warning);
+}

test/lint.spec.ts

@@ -0,0 +1,91 @@
+import { lint, validate } from '../src/lint';
+import { hasErrorDiagnostic, hasWarningDiagnostic } from '../src/utils';
+
+describe('lint() & validate()', function() {
+  describe('lint()', function() {
+    it('should lint invalid document', async function() {
+      const document = {
+        asyncapi: '2.0.0',
+        info: {
+          title: 'Valid AsyncApi document',
+          version: '1.0',
+        },
+      }
+
+      const diagnostics = await lint(document);
+      if (!diagnostics) {
+        return;
+      }
+
+      expect(diagnostics.length > 0).toEqual(true);
+      expect(hasErrorDiagnostic(diagnostics)).toEqual(true);
+      expect(hasWarningDiagnostic(diagnostics)).toEqual(true);
+    });
+
+    it('should lint valid document', async function() {
+      const document = {
+        asyncapi: '2.0.0',
+        info: {
+          title: 'Valid AsyncApi document',
+          version: '1.0',
+        },
+        channels: {}
+      }
+
+      const diagnostics = await lint(document);
+      if (!diagnostics) {
+        return;
+      }
+
+      expect(diagnostics.length > 0).toEqual(true);
+      expect(hasErrorDiagnostic(diagnostics)).toEqual(false);
+      expect(hasWarningDiagnostic(diagnostics)).toEqual(true);
+    });
+  });
+
+  describe('validate()', function() {
+    it('should validate invalid document', async function() {
+      const document = JSON.stringify({
+        asyncapi: '2.0.0',
+        info: {
+          title: 'Valid AsyncApi document',
+          version: '1.0',
+        },
+      }, undefined, 2);
+      const { validated, diagnostics } = await validate(document);
+
+      expect(validated).toBeUndefined();
+      expect(diagnostics.length > 0).toEqual(true);
+    });
+
+    it('should validate valid document', async function() {
+      const document = JSON.stringify({
+        asyncapi: '2.0.0',
+        info: {
+          title: 'Valid AsyncApi document',
+          version: '1.0',
+        },
+        channels: {}
+      }, undefined, 2);
+      const { validated, diagnostics } = await validate(document);
+
+      expect(validated).not.toBeUndefined();
+      expect(diagnostics.length > 0).toEqual(true);
+    });
+
+    it('should validate valid document - do not allow warning severity', async function() {
+      const document = JSON.stringify({
+        asyncapi: '2.0.0',
+        info: {
+          title: 'Valid AsyncApi document',
+          version: '1.0',
+        },
+        channels: {}
+      }, undefined, 2);
+      const { validated, diagnostics } = await validate(document, { allowedSeverity: { warning: false } });
+
+      expect(validated).toBeUndefined();
+      expect(diagnostics.length > 0).toEqual(true);
+    });
+  });
+});

test/parse.spec.ts

@@ -0,0 +1,33 @@
+import { AsyncAPIDocument } from '../src/models/asyncapi';
+import { parse } from '../src/parse';
+
+describe('parse()', function() {
+  it('should parse valid document', async function() {
+    const document = {
+      asyncapi: '2.0.0',
+      info: {
+        title: 'Valid AsyncApi document',
+        version: '1.0',
+      },
+      channels: {}
+    }
+    const { parsed, diagnostics } = await parse(document);
+
+    expect(parsed).toBeInstanceOf(AsyncAPIDocument);
+    expect(diagnostics.length > 0).toEqual(true);
+  });
+
+  it('should parse invalid document', async function() {
+    const document = {
+      asyncapi: '2.0.0',
+      info: {
+        title: 'Valid AsyncApi document',
+        version: '1.0',
+      },
+    }
+    const { parsed, diagnostics } = await parse(document);
+
+    expect(parsed).toEqual(undefined);
+    expect(diagnostics.length > 0).toEqual(true);
+  });
+});