documentStructure.ts

/* eslint-disable sonarjs/no-duplicate-string */

import specs from '@asyncapi/specs';
import { createRulesetFunction } from '@stoplight/spectral-core';
import { schema as schemaFn } from '@stoplight/spectral-functions';

import { AsyncAPIFormats } from '../formats';
import { getSemver } from '../../utils';

import type { ErrorObject } from 'ajv';
import type { IFunctionResult, Format } from '@stoplight/spectral-core';

type AsyncAPIVersions = keyof typeof specs.schemas;
type RawSchema = Record<string, unknown>;

function shouldIgnoreError(error: ErrorObject): boolean {
  return (
    // oneOf is a fairly error as we have 2 options to choose from for most of the time.
    error.keyword === 'oneOf' ||
    // the required $ref is entirely useless, since aas-schema rules operate on resolved content, so there won't be any $refs in the document
    (error.keyword === 'required' && error.params.missingProperty === '$ref')
  );
}

// ajv throws a lot of errors that have no understandable context, e.g. errors related to the fact that a value doesn't meet the conditions of some sub-schema in `oneOf`, `anyOf` etc.
// for this reason, we filter these unnecessary errors and leave only the most important ones (usually the first occurring in the list of errors). 
function prepareResults(errors: ErrorObject[]): void {
  // Update additionalProperties errors to make them more precise and prevent them from being treated as duplicates
  for (let i = 0; i < errors.length; i++) {
    const error = errors[i];

    if (error.keyword === 'additionalProperties') {
      error.instancePath = `${error.instancePath}/${String(error.params['additionalProperty'])}`;
    } else if (error.keyword === 'required' && error.params.missingProperty === '$ref') {
      errors.splice(i, 1);
      i--;
    }
  }

  for (let i = 0; i < errors.length; i++) {
    const error = errors[i];

    if (i + 1 < errors.length && errors[i + 1].instancePath === error.instancePath) {
      errors.splice(i + 1, 1);
      i--;
    } else if (i > 0 && shouldIgnoreError(error) && errors[i - 1].instancePath.startsWith(error.instancePath)) {
      errors.splice(i, 1);
      i--;
    }
  }
}

// this is needed because some v3 object fields are expected to be only `$ref` to other objects.
// In order to validate resolved references, we modify those schemas and instead allow the definition of the object
function prepareV3ResolvedSchema(copied: any, version: string): any {
  // channel object
  const channelObject = copied.definitions[`http://asyncapi.com/definitions/${version}/channel.json`];
  if (channelObject?.properties?.servers?.items) {
    channelObject.properties.servers.items.$ref = `http://asyncapi.com/definitions/${version}/server.json`;
  }

  // operation object
  const operationSchema = copied.definitions[`http://asyncapi.com/definitions/${version}/operation.json`];
  if (operationSchema?.properties?.channel) {
    operationSchema.properties.channel.$ref = `http://asyncapi.com/definitions/${version}/channel.json`;
  }
  if (operationSchema?.properties?.messages?.items) {
    operationSchema.properties.messages.items.$ref = `http://asyncapi.com/definitions/${version}/messageObject.json`;
  }

  // operation reply object
  const operationReplySchema = copied.definitions[`http://asyncapi.com/definitions/${version}/operationReply.json`];
  if (operationReplySchema?.properties?.channel) {
    operationReplySchema.properties.channel.$ref = `http://asyncapi.com/definitions/${version}/channel.json`;
  }
  if (operationReplySchema?.properties?.messages?.items) {
    operationReplySchema.properties.messages.items.$ref = `http://asyncapi.com/definitions/${version}/messageObject.json`;
  }

  return copied;
}

function getCopyOfSchema(version: AsyncAPIVersions): RawSchema {
  return JSON.parse(JSON.stringify(specs.schemas[version])) as RawSchema;
}

const serializedSchemas = new Map<AsyncAPIVersions, RawSchema>();
function getSerializedSchema(version: AsyncAPIVersions, resolved: boolean): RawSchema {
  const serializedSchemaKey = resolved ? `${version}-resolved` : `${version}-unresolved`;
  const schema = serializedSchemas.get(serializedSchemaKey as AsyncAPIVersions);
  if (schema) {
    return schema;
  }

  // Copy to not operate on the original json schema - between imports (in different modules) we operate on this same schema.
  let copied = getCopyOfSchema(version) as { '$id': string, definitions: RawSchema };
  // Remove the meta schemas because they are already present within Ajv, and it's not possible to add duplicated schemas.
  delete copied.definitions['http://json-schema.org/draft-07/schema'];
  delete copied.definitions['http://json-schema.org/draft-04/schema'];
  // Spectral caches the schemas using '$id' property
  copied['$id'] = copied['$id'].replace('asyncapi.json', `asyncapi-${resolved ? 'resolved' : 'unresolved'}.json`);

  // Remove format: "uri-reference" from ReferenceObject so that $ref values with special chars
  // like `[`, `]` (valid JSON Pointer segments but not RFC 3986 URIs) pass validation.
  const referenceObject = copied.definitions[`http://asyncapi.com/definitions/${version}/ReferenceObject.json`] as any;
  if (referenceObject?.format === 'uri-reference') {
    delete referenceObject.format;
  }

  const { major } = getSemver(version);
  if (resolved && major === 3) {
    copied = prepareV3ResolvedSchema(copied, version);
  }

  serializedSchemas.set(serializedSchemaKey as AsyncAPIVersions, copied);
  return copied;
}

const refErrorMessage = 'Property "$ref" is not expected to be here';
function filterRefErrors(errors: IFunctionResult[], resolved: boolean) {
  if (resolved) {
    return errors.filter(err => err.message !== refErrorMessage);
  }

  return errors
    .filter(err => err.message === refErrorMessage)
    .map(err => {
      err.message = 'Referencing in this place is not allowed';
      return err;
    });
}

export function getSchema(docFormats: Set<Format>, resolved: boolean): Record<string, any> | void {
  for (const [version, format] of AsyncAPIFormats) {
    if (docFormats.has(format)) {
      return getSerializedSchema(version as AsyncAPIVersions, resolved);
    }
  }
}

export const documentStructure = createRulesetFunction<unknown, { resolved: boolean }>(
  {
    input: null,
    options: {
      type: 'object',
      properties: {
        resolved: {
          type: 'boolean',
        },
      },
      required: ['resolved'],
    },
  },
  (targetVal, options, context) => {
    const formats = context.document?.formats;
    if (!formats) {
      return;
    }

    const resolved = options.resolved;
    const schema = getSchema(formats, resolved);
    if (!schema) {
      return;
    }

    const errors = schemaFn(targetVal, { allErrors: true, schema, prepareResults: resolved ? prepareResults : undefined }, context);
    if (!Array.isArray(errors)) {
      return;
    }

    return filterRefErrors(errors, resolved);
  },
);