Document how to create custom lint rules about speccy HOT 14 CLOSED

Hello Phil Sturgeon,
I am able to create new rule file, in which added existing one of speccy rule in it. So it works fine for predefined speccy rule. But I want to know the meaning of rule format what is mean by object, truthy, pattern, skip fields. So for example, I want to create rule as "no new line at the end file". In this case what will be the object and other parameter needs to be added.

from speccy.

Is this still being worked on? I can probably help to fix if it's no longer in progress.

We really have a need for custom rules and this is blocking me. Trying to put json files in the global install location isn't really an option.

from speccy.

It's as simple as speccy lint --rules=./file.json. That can be a URL too.

Copy and paste default and tweak from there. We've not got any docs for this yes, so maybe you could consider writing up your approach as you go? Could make for a great "Custom Rules" page on speccy.io.

from speccy.

Hi @ShwetaManekari the linter used by Speccy works on the internal object model parsed from the YAML or JSON file you pass in. It can't see the textual representation, so it wouldn't be able to enforce your rule no-new-line-at-end-of-file, assuming I have interpreted it correctly.

Similarly, it wouldn't be able to enforce things like YAML comments being present or JSON property ordering rules. These things effectively have no bearing on the OpenAPI definition.

As to your wider point, I will add some documentation on the reference linter (oas-linter), but the Speccy linter is effectively a fork of that code, so I'm not sure what the best way is to create documentation which can be used by both projects and kept in step.

from speccy.

from speccy.

I suppose there's no reason why the validator couldn't keep a track of the count of each kind of object in the document and present that to the linter as a virtual object / in-memory extension.

Counting lines is fine, I guess, unless your JSON is un-prettified (all on one line - though that's solvable). There's no reason there shouldn't be an options.text property or something containing the original input (or a rendering of it if an object was passed in originally).

Maybe we should create an in-memory analysis object then pass that to the linter. I'm thinking maybe of adding a jsonSchema rule which could then validate that the analysis object had a lines property of type integer with a maximum value of 1000 etc etc.

For the next iteration I'm sure we can find a way to inject new checkers/rule classes into the base linter. Then I don't have to support alphabetical 😁

from speccy.

First draft of oas-linter rule format documentation is here. Speccy's rule format is a derivative of this (in that it supports the extensions like maxLength and alphabetical).

from speccy.

I'd also like to see this since I would like to be able to enforce the order of OAS properties such as summary first, then description, etc.

from speccy.

Seems the lint rule must be put under the rules folder. https://github.com/wework/speccy/blob/master/lib/loader.js#L97
Prefer to offer ability to passing a relative/absolute path, and allow it be under my own project folder, which would be more clear for teammates.

from speccy.

This is being worked on currently by @dangoosby.

from speccy.

Hey, no code changes required, and you definitely do not need to try and put JSON files in the install location.

If you look at this comment above I've explained very briefly how you can make your own rules files by reusing existing rules actions.

The developer who was writing up this documentation has moved onto other work, and I'm taking over this issue in this sprint. Should be documented in the next few days now. :)

from speccy.

@philsturgeon I've tried what's on the specified comment, but get the below error:

speccy lint --rules=./file.json specification.json
(node:23244) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 3):
Error: ENOENT: no such file or directory, open 'C:\Users\jblazek\AppData\Roaming\npm\node_modules\speccy\rules\file.json.json'

Something is trying to look in my global install and appending '.json', which seems to be coming from what was referenced in the other comment

I'm running speccy 0.8.2 on Windows 10.

from speccy.

from speccy.

Done in #184.

from speccy.