feat(oas): add oas3-unused-component rule which detects all orphaned components

[mkistler]

This PR creates a new oas3 rule oas3-unused-component which detects and reports any unreferenced component (except securitySchemes, which are not "referenced" in the normal way) in an OpenAPI document.

Checklist

• Tests added / updated
• Docs added / updated

Does this PR introduce a breaking change?

• Yes
• No

Additional context

I'd like to replace the logic in our validator for finding and reporting unused components -- which is not configurable -- with a Spectral rule so that users can override the severity for their out purposes. We've gotten requests from users for this capability:

IBM/openapi-validator#172

But I can't use oas3-unused-components-schema because this would be a regression -- our logic detects all of types of unused components: schemas, parameters, responses, requestBodies, headers, examples, links, and callbacks.

So this PR creates a new rule that is a superset of oas3-unused-components-schema that detects all unused components (except securitySchemes). It leverages the underlying unreferecedReusableObject function internally, so the logic is (IMHO) very straightforward.

Because this new rule is a superset of oas3-unused-components-schema, I changed that rule to be "recommended: false" and set the new rule to "recommended: true"

[mkistler]

@P0lip I think this is now ready for review. I've rebased onto the current develop branch and added documentation for the new rule. I also figured out how to run the test harness so I could fix problems there myself (just one little one this time).

[P0lip]

I like it!
Let's just drop the other obsolete now rule and this should be good to go.

[P0lip]

I'd say we can drop the rule at this point.
oas3-unused-component somewhat overlaps with it.

[mkistler]

Dropping the rule entirely might cause unexpected results for users with a configuration that starts by disabling all rules and then selectively enables rules by name. Since Spectral does not issue a warning about rules it does not recognize in the configuration file, Spectral will silently stop linting their unused schemas.

But I'm happy to remove the rule if you think this is acceptable.

[P0lip]

Yeah, I'd say let's do it, but curious to hear what @philsturgeon thinks about the idea.

Since Spectral does not issue a warning about rules it does not recognize in the configuration file, Spectral will silently stop linting their unused schemas.

We're thinking to change it in the next major version. It's going to throw an error. Failing silently is usually not intended.

[philsturgeon]

The next version should be a major release so the impact should not be too unexpected, we'll just have to communicate it clearly.

[mkistler]

I've updated the PR to remove the oas3-unused-components-schema rule and associated tests. The yard test.prod tests all pass on my local system. I see that the circleci tests are failing on Linux but I don't know if that's anything to do with my changes. So I think this PR is ready to review/merge but if there is something else I need to do just let me know.

[philsturgeon]

Amazing work, thank you so much @mkistler!

[P0lip]

Thanks a bunch! Great job.
Actually, your PR addressed #1073.