blinkers v0.3.1

Blinkers

Blinkers is a quick sweep through the code to find debug code, TODOs and pet-peeve type issues.

• Excesive console.log statements from debugging a complex issue,
• TODOs and FIXMEs that haven't yet been cleared,
• Ensuring all your modules are in strict mode, and
• Indenting with tabs, trailing spaces, long lines, and final newlines.

This is not meant to be a replacement for linting but a supplement. Linting highlights issues that should never be part of your code. This tool highlights issues that may appear due to debugging but should be cleared eventually cleared up.

For example, console.log commands are not a problem per se but are often left over from debugging an issue, cluttering both the log files and the code itself.

Installing

1. Install the package

   npm install --save-dev blinkers

2. Build your .blinkers.yaml config file. Start by copying the example and then build on it.

   cp ./node_modules/blinkers/examples/node.yaml .binkers.yaml

3. (Optional) Add a blinkers script to your package.json file.

   "scripts": {
     "blinkers": "./node_modules/blinkers/bin/blinkers.js"
   },

4. Add npm run blinkers or ./node_modules/blinkers/bin/blinkers.js to your build, CI/CD, pre-commit, etc processes so that the output comes up often.

Configuration file

Place a configuration file in the root directory of the project called .blinkers.yaml or blinkers.yaml. The file has three sections

• excludeDirs: a list of all directory names to ignore. For example, if node_modules is listed, everything under every directory named node_modules will be ignored.
• fileTypes: determines which test to run against which files. This section is an array, each entry having the following:
  • patterns can be strings or regular expressions (objects with one member: regex). Any filenames with this pattern will be tested.
  • exclude a list of files that may match one of the patterns above but you still don't want to be part of the test.
  • tests the tests to run. Either a string or an object, if the test has options, use the object form.
• options: options for this tool.
• plugins: the plugin files to load before running this tool. Has built-in plugins and support for custom plugins. The built-in plugins are prefixed with blinkers:.

Pragmas in the code

ignore-lines

Some plugins support ignore-lines commands.

In the case of console.log -- I will always need some console.log statements, but most of them should be removed as soon as I'm done working with them. To avoid flagging the necessary console.log statements, add an ignore-line command.

// @@ blinkers jsts.console-log ignore-line
console.log('a line of code');
console.log('this line won\'t be ignored);

To skip multiple lines, you may either specify a number of lines, or ignore a whole block.

// @@ blinkers jsts.console-log ignore-lines 2
console.log('line 1');
console.log('line 2');
console.log('this line won\'t be ignored);

// or

// @@ blinkers jsts.console-log ignore-block
console.log('line 1');
console.log('line 2');
console.log(' ... ');
console.log('line n');
// @@ blinkers jsts-log ignore-block end

Note that all of these tests have console-log, meaning this ignore works with the console.log test. Other tests have skips enabled too:

• console-log
• debug-logging

Plugins

This package comes with a handful of useful plugins, but there will often be situations where you want to flag additional things. In this situation, you can create a plugin.

The structure of a plugin is pretty simple: You have your plugin functions and your plugin registration. There is nothing to import in your plugin file -- all the supporting functions you need are passed to your plugins as parameters.

Example

'use strict';

function hyphenHyphenHyphen(content, { observe}) {  
  const firstLine = content.rawLines[0];
  if (firstLine) {
    if (firstLine !== '---') {
      observe(0, 'YAML files should start with `---`' + firstLine);
    }
  } else {
    observe(null, 'Empty YAML file');
  }
}

export default function plugin(register) {
  register('yaml.---', hyphenHyphenHyphen);
}

First there is the plugin function, then the registration.

The plugin function takes two parameters: content and context.

• content is the content of a file to scan. The content is broken down in multiple ways in the object.
• context is the options and some library functions to use. The most notable member is observe which is your main way to report this plugin's observations.

Then the plugin needs to be registers. The registration is done by a function that takes one parameter: the register method. This function must be the default export of the module.