Support for custom assertions

[RomanHotsiy]

Is your feature request related to a problem? Please describe. Using assertions context and subject syntax seems to be convenient. We need a simple way to add custom assertions as an alternative for writing custom rules.

Custom assertions will be easier to write and custom rules will be needed for complex cases only.

Describe the solution you'd like I would implement it as an extension to plugins. To keep it simpler I would structure all the examples in our docs so it's using a single plugin file and does not split across multiple files.

The simplest plugin may look like:

plugin.js

module.exports = {
  id: 'my-plugin',
  assertions: {
    customFn: (value, opts, location) => {
      if (...) return { isValid: false, location };
      return { isValid: true };
    }
  }
};

We need to implement a simple way to include plugin (using cli args without the need for redocly.yaml): --include-plugin ./plugin.js.

To use the assertion we may use one of the following approaches:

A):

lint:
  rules:
    assert/operation-summary-max-length:
      subject: Operation
      property: summary
      message: Some custom assertion
      severity: error
      my-plugin/customFn: <options>

B):

lint:
  rules:
    assert/operation-summary-max-length:
      subject: Operation
      property: summary
      message: Some custom assertion
      severity: error
      custom:
        name: my-plugin/customFn
        options: <options>

I would vote for the A).

Describe alternatives you've considered None.

[tatomyr]

I also like A better. But would we able to validate the my-plugin/customFn syntax?

We need to implement a simple way to include plugin (using cli args without the need for redocly.yaml)

It looks like we do need redocly.yaml anyway since assertions could only be used inside the redocly config, right?