Rulya NPM | npm.io

Rulya

npm

Helps you define and apply semantic validation to a collection of YAML files. Typically used as pre-commit hook or CI/CD build step.

Usage

Create a NPM package in the directory containing the files to validate:

npm init

And set the test script to:

jasmine --require=rulya validate.js

Add Rulya as a development dependency:

npm install rulya --save-dev

Write your validation rules in validate.js:

// Traverse all YAML files in the test-data/articles directory
documents("test-data/articles/**/*.yaml", (doc, path) => {

    // Validate against a JSON schema (can be a URL as well)
    schema("test-data/articles/article.schema.json", doc);

    // Define a rule on the filename
    rule("filename", path, "must have a filename containing the string 'article'", () => {
        expect(path.split("/").slice(-1)[0]).toContain("article");
    });
});

// Traverse all YAML files in the test-data/books directory
documents("test-data/books/**/*.yaml", (doc) => {

    // Iterate through the chapters
    property("chapters", doc.chapters, chapter =>

        // Group rules applied to the chapter titles
        property("title", chapter.title, title => {

            // Define rules for the chapter titles

            rule("capitalized", title, "must start with a capital letter", () => {
                expect(title).toMatch("^[A-Z].*");
            });

            rule("letters-only", title, "must contains only letters", () => {
                expect(title).toMatch("^[A-Za-z ]*$");
            });
        }));

    // A rule can be defined standalone, the property name must be writen in the description though
    rule("page-number", doc.pages, "'pages' must be positive if present", pages => {
        expect(pages == null || pages > 0).toBeTrue();
    });
});

Run your rules with:

npm test

Breaking the Rules

If for some reason you need to disable some rule, use a skip comment with the rule names.

    - title: "a fantastic tale no 1" # skip(capitalized,letters-only)

For rules applying to the whole document, the skip comment must be on the first line:

# skip(schema,filename)
text: Hello

Expectations

Rulya uses Jasmine under the hood, you can use all its matchers in the rule definitions.

API


`documents(pattern,callback)`	Traverses and parses YAML documents using a glob `pattern`.
`property(name,value,callback)`	Steps down in a property to group multiple rules together. It creates a describe section at the Jasmine level. `name` and `value` typically corresponds to a YAML map entry. `callback` will be called with `value` as parameter or each item if `value` is an array.
`rule(name,value,description,callback)`	Defines a rule. `name` identifies the rule if you want to skip it (see Breaking the Rules, above). `value` is the YAML element the rule applies to. This creates a single spec at the Jasmine level.
`schema(reference, doc)`	Validates a document against a JSON Schema. `reference` is the filesystem path or an URL pointing to the schema.

Customization

You can use Jasmine's describe and it functions if you need more flexibility than property and rule provide. Just note that rule manages the skip comment for you.