Neurosis Prevention Mechanism

    replicated-lint
    TypeScript icon, indicating that this package has built-in type declarations

    0.19.1 • Public • Published

    replicated-lint

    CircleCI Code Climate Test Coverage

    YAML linting tools for Replicated applications.

    Usage

    Install the CLI executable with

    npm install -g replicated-lint

    Lint with replicated-lint validate

    replicated-lint validate -f my-app.yml

    or pipe from stdin:

    cat my-app.yml | replicated-lint validate -f -

    Results that have issues will look something like:

    { type: 'info',
      rule: 'prop-configitem-testproc-run-on-save',
      message: 'If a config item\'s test_proc.run_on_save is not set to \'true\', test_proc\'s will not be checked automatically. Consider setting your test_proc\'s run_on_save to automatically validate inputs',
      positions:
       [ { path: 'config.1.items.2.test_proc',
           start: { position: 8130, line: 325, column: 4 },
           end: { position: 8322, line: 331, column: 0 } },
         { path: 'config.3.test_proc',
           start: { position: 8692, line: 346, column: 2 },
           end: { position: 9141, line: 365, column: 2 } } ],
      links: [ 'https://www.replicated.com/docs/packaging-an-application/test-procs/' ] }
    
    # prop-configitem-testproc-run-on-save continued from line 321
    322  
    323    - name: phone_number
    324      type: text
    325      test_proc:
    326        display_name: Is this a Phone Number?
    327        command: regex_match
    328        args:
    329        - "([0-9]{3})[-]([0-9]{3})[-]([0-9]{4})$"
    330        - "That doesn't seem to be a phone number!"
    331  - name: auth
    332    title: Authentication
    333    description: Where will user accounts be provisioned
    334    items:
    

    Extending the CLI with custom rules

    replicated-lint rules can be expressed as JSON, so it is easy to add your own custom rules.

    If you have a custom rule set in no-latest.json, you can pass it to replicated-lint using

    cat my-app.yml | replicated-lint validate -f - --extraRules no-latest.yaml

    --extraRules can be specified multiple times. An example YAML rule set might look something like

    ---
    - name: custom-no-latest
      type: error
      message: "Don't use `latest` for container versions."
      test:
        AnyOf:
          path: components
          pred:
            AnyOf: containers
            pred:
              Eq:
                path: version
                value: latest

    replicated-lint validate supports the following options:

    Options:
      --version         Show version number                                [boolean]
      --help            Show help                                          [boolean]
      --infile, -f      Input file to validate. Use "-" for stdin
                                                             [string] [default: "-"]
      --threshold, -t   Threshold of of issues to report
                      [string] [choices: "info", "warn", "error"] [default: "error"]
      --extraRules, -e  Path to file containing JSON definitions for additional yaml
                        rules. Can be specified multiple times.[array] [default: []]
      --reporter, -r    Output Format to use
                         [string] [choices: "console", "junit"] [default: "console"]
      --outputDir, -o   junit reporter only -- path to directory to output junit xml
                        reports                   [string] [default: "test-results"]
    

    Developing

    Installing Dependencies

    We compile to ES5 and test on nodejs 7.8.0, but earlier versions of node should work as well.

    npm install -g yarn
    yarn

    Running the tests

    To run the tests once

    yarn test

    To watch files and re-run tests on changes, use the tdd script

    ./tdd

    Before committing

    Run

    make project-import PROJECT=<project-name>

    Where <project-name> is the project being updated and should be one of

    • replicated-supportbundle
    • replicated-entitlements
    • replicated-rbac
    • replicated-ship

    For more up to date list check the project directory listing.

    Regenerating the documentation

    replicated-lint docs gen will print reference documentation stdout as markdown. yarn docs will write it to docs/gen.md.

    To update the docs in help center, grab everything in replicated-lint/docs/gen.md and paste it into help-center/.../yaml.md, replacing everything below <!-- the rest of this document is autogenerated-->.

    Library Usage

    replicated-lint is designed with extensibility in mind, making it suitable for general purpose YAML and JSON linting and policy definition

    • Flexible, modular rule sets
    • CLI
    • Autogenerate unit tests and documentation from rule definitions
    npm install --save replicated-lint
    import * as linter from "replicated-lint";
    
    const yaml = `
    ---
    replicated_api_version: 2.8.0
    components:
      - name: ELK
        containers:
          - image: getelk/search`;
    
    
    const ruleViolations = linter.defaultLint(yaml);
    console.log(ruleViolations); // []

    Custom Rule Sets

    linter.rules.all can be substituted or extended with custom rule definitions. A rule's test field should return { matched: true } when the rule is triggered by invalid JSON.

    import * as linter from "replicated-lint";
    
    const yaml = `
    ---
    foo:
      bar: baz`;
    
    const testSpec: any = {
      Or: {
        preds: [
          {Eq: { path: "foo.bar", value: "baz"}},
          {Eq: { path: "foo.bar", value: "boz"}},
        ],
      }
    }
    
    const rules: linter.YAMLRule[] = [
      {
        name: "foo-bar-neq-baz",
        message: "foo.bar can't be baz!",
        test: testSpec,
        type: "error",
      }
    ];
    
    const ruleViolations = linter.lint(yaml, { rules });
    console.log(ruleViolations);  /*
    [{
            type: "error",
            positions: [{
              path: "foo.bar",
              start: {
                position: 12,
                line: 3,
                column: 2,
              },
              end: {
                position: 20,
                line: 3,
                column: 10,
              },
            }],
            message: "foo.bar can't be baz!",
    }]
    */

    Register new rules with linter.enginer.register. Rules should implement JSONReadable<Predicate<any>>, usually as a static method

    import * as linter from "replicated-lint";
    
    
    // rule MyRule checks if root object has property "spam" equal to "eggs"
    class MyRule implements linter.Predicate<any> {
      test(obj: any) {
        const matched = obj.spam !== "eggs"; // fail when spam != eggs
        const paths = ["spam"];              // if matched == true, optionally include a path where a rule was violated
        return { matched, paths };
      }
    
      public static fromJson(obj: any, registry: linter.engine.Registry) {
        return new MyRule();
      }
    }
    
    linter.engine.register(MyRule);
    
    const testSpec: linter.Test = { MyRule: {}};
    
    const rules: linter.YAMLRule[] = [
      {
        name: "spam-eq-eggs",
        message: "spam must be equal to eggs!",
        test: testSpec,
        type: "error",
      }
    ];
    
    const yaml = `
    ---
    spam: eggs`;
    
    const ruleViolations = linter.lint(yaml, { rules });
    console.log(ruleViolations); // []

    Custom implementations of engine.Registry can also be passed as a third argument to linter.lint, otherwise a default registry will be used.

    Install

    npm i replicated-lint

    DownloadsWeekly Downloads

    1,011

    Version

    0.19.1

    License

    MIT

    Unpacked Size

    619 kB

    Total Files

    113

    Last publish

    Collaborators

    • erquhart
    • emosbaugh
    • replicatedhq-user
    • retracedhq