customRuleReport.md

February 4, 2018 · View on GitHub

Custom Rule Report

As you know, when a user runs solidarity report as of Solidarity 1.1+, a GitHub friendly report is generated to the screen. You can provide this same functionality in your custom plugin by implementing a report function inside of your rules property.

This is supported as of Solidarity v2+

You can add to any report table or create your own. The known report tables are:

basicInfo - Reports the system and report results
cliRules - Report any system CLI results
envRules - Report Environment Variable results
filesystemRules - Report for existence of filesystem results
shellRules - Report for any shell commands and their matches

There is another report called: customRules which holds tables created by custom plugins, which will show in the report.

Let's do two examples:

Example 1: Adding to the cliRules table
Example 2: Adding to the customRules array of tables

We'll use the same rule (always pass) that was identified in the custom rule check section.

We will add an async function named report

module.exports = (context) => {
  // Register this plugin
  context.addPlugin({
    name: 'Always Pass',
    description: 'Example plugin that always passes',
    rules: {
      checkThing: {
        // report for your custom rule goes here
        report: async (rule, context, report) => {
          // CODE GOES HERE
        }
      }
    }
  })
}

Just like other custom rule sections, the function gets rule, and context. Additionally the report object is passed into the function for mutation. No return value is expected.

Example 1: Adding to the `cliRules` table

Let's add to the CLI report. The CLI report commonly has Binary, Location, Version, Desired as values, so pushing an array of 4 items will add a new row to your report.

...
  report: async (rule, context, report) => {
    report.cliRules.push([
      'crazed_monkey',
      '/etc/useless/crazed_monkey',
      '10',
      '12'
    ])
  }
...

Now your row will show in the CLI section of the report. As a bonus, there is a simple helper function attached to the report named addCLI, which takes an object with the props binary, version, and optionally desired. It will then figure out the location for you, and if no desired is passed, the green *ANY* is shown. The above report simplified with addCLI looks like so:

...
  report: async (rule, context, report) => {
    report.addCLI({
      binary: 'crazed_monkey',
      version: '10'
    })
  }
...

The output inserts the results in the CLI section. crazed_monkey

Example 2: Adding to the `customRules` array of tables

If any of the existing tables are not fit for your report needs, you can add tables via your custom plugin. Let's add a table by pushing a table object on the customRules array.

The table object structure is simple: title for the table title, and then a 2D array of rows.

...
  report: async (rule, context, report) => {
    // add custom table
    report.customRules.push({
      title: 'Menu',
      table: [
        ['Food', 'Price', 'Value'],
        ['Taco', '1.09', 'Yummy!'],
        ['Burrito', '1.89', 'Oh yeahhh'],
      ]
    })
  }
...

The result when running solidarity report will be a whole new table printed in the results!

custom_menu

customRuleReport.md