refactor: handle circular references in schemas

[magicmatatjahu]

Description

Handle circular references, which are not handled by Spectral internal ref-resolver. The solution in PR doesn't support the really strange cases related with circular references, but for the moment it is sufficient. When we release the first alpha/beta of the new API, then I will try to support all the cases with custom ref-resolver.

Also, that PR move some utils from ./utils file to the new ./document to prevent circular references between TS files - sometimes we need utils from ./utils file in model file, and due to fact that we have reference to the AsyncAPIDocument model, we can case with circular ref between TS files - example with Schema model and MessageTrait.

cc @smoya

Related issue(s)
Part of #481
Part of #482

[smoya]

Correct me if I'm wrong but given:

pathOfData = /components/channels/test
refPath = /channels/test

Would it match (pathOfData.includes(refPath) when it shouldn't?.

[magicmatatjahu]

The string.includes in JS can be used to check if a string has a substring.

[smoya]

I know. What I want to raise here is that '/components/channels/test'.includes('/channels/test') returns true but I think it is not an expected behavior here since both are completely different paths.

[magicmatatjahu]

Circular references you can only have with Schema Objects, so '/components/channels/test'.includes('/channels/test') is not a good example.

You can create circular reference only when you point to the schema which is already used in parent path(s), so schema like:

type: object
properties:
  deepProperty:
    type: object
    properties:
      circular:
        $ref: '#/properties/deepProperty'

is circular in properties/deepProperty/properties/circular path. That case is handled by first if in mentioned function

Another case is related to Spectral and how it resolves circular references. We can have two two schemas, main one and external (from file):

type: object
properties:
  fileProperty:
    $ref: './fromfile.yaml'
        
# fromfile.yaml
type: object
properties:
  deepProperty:
    type: object
    properties:
      circular:
        $ref: '#/properties/deepProperty'

but in this case the circular reference after dereferencing has $ref field still with '#/properties/deepProperty' value, so it means that if we will check path we will have '#/properties/deepProperty' from file pov, not from main file pov, like '#/properties/fileProperty/properties/deepProperty' and due to this fact we need to also check (by second if) the subpath. I hope it's clear now. Above logic is dictated by Spectral "problems".

[magicmatatjahu]

Ok, I fixed conflicts. @smoya Do you have any other concerns?

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[smoya]

LGTM!

I think we should create a new issue for keep working on a final solution regarding handling circular references; could be doing work on Spectral side, json-schema-ref-parser or whatever.

[magicmatatjahu]

@smoya I created issue #599

[magicmatatjahu]

/rtm