Lint

Lint license headers for a file glob.

Usage

var lint = require( '@stdlib/_tools/lint/license-header-glob' );

lint( [options,] clbk )

Asynchronously lints license headers for a file glob.

lint( onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

The function accepts the following options:

  • header: license header to lint against. May be a string, regular expression, or an object whose keys are filename extensions and whose values are license header strings or regular expressions.
  • dir: root directory from which to search for files. May be either an absolute or relative directory path. Default: current working directory.
  • pattern: filename pattern. Default: '**/*'.
  • ignore: list of glob patterns used to exclude matches.

To search from a specific directory, set the dir option.

var opts = {
    'dir': __dirname
};

lint( opts, onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

To limit the file search to a subset of files, set the pattern option.

var opts = {
    'dir': __dirname,
    'pattern': '**/*.js' // JavaScript files
};

lint( opts, onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

To exclude matches, set the ignore option.

var opts = {
    'pattern': '**/*.jl',
    'ignore': [
        'node_modules/**',
        'build/**',
        'reports/**'
    ]
};

lint( opts, onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

To lint against a particular license header, set the header option.

var opts = {
    'dir': __dirname,
    'pattern': '**/*.js',
    'header': '// This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0'
};

lint( opts, onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

To lint against a license header regular expression,

var opts = {
    'dir': __dirname,
    'pattern': '**/*.js',
    'header': /\/\/ This file is a part of stdlib\. License is Apache-2\.0: http:\/\/www\.apache\.org\/licenses\/LICENSE-2\.0/
};

lint( opts, onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

To lint against an object containing license header strings and/or regular expressions,

var opts = {
    'dir': __dirname,
    'header': {
        // JavaScript files:
        'js': '// This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0',

        // Julia files:
        'jl': '# This file is a part of stdlib. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0',

        // Everything else:
        'default': /\/\* This file is a part of stdlib\. License is Apache-2\.0: http:\/\/www\.apache\.org\/licenses\/LICENSE-2\.0 \*\//
    }
};

lint( opts, onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

If a provided header option object includes a default property, the value assigned to that property is used to lint all other non-ignored files having filename extensions not explicitly included in the object; otherwise, the function ignores any file not having a filename extension explicitly included in the object.

lint.sync( [options] )

Synchronously lints license headers for a file glob.

var errs = lint.sync();
// returns [...]

The function accepts the same options as lint() above.

Notes

  • By default, both functions lint against an Apache-2.0 license header.

  • The linter considers the presence of more than one license header in a file a lint error.

  • License headers are expected to begin within the first 5 lines of a file. If a license header begins elsewhere in a file, the linter considers this a lint error.

  • If all files are valid, the returned result is an empty array.

  • Each failure is returned as an object with the following properties:

    • name: filename.
    • error: reason for failure.
    {
        "name": "path/to/failing/file.abc",
        "error": "malformed or missing license header."
    }
    
  • Only files which fail are returned.

Examples

var lint = require( '@stdlib/_tools/lint/license-header-glob' );

var opts = {
    'dir': __dirname
};

lint( opts, onLint );

function onLint( error, errs ) {
    if ( error ) {
        throw error;
    }
    console.error( JSON.stringify( errs ) );
}

CLI

Usage

Usage: lint-license-header-glob [options] [<dir>]

Options:

  -h, --help             Print this message.
  -V, --version          Print the package version.
      --pattern pattern  Inclusion glob pattern.
      --ignore pattern   Exclusion glob pattern.
      --header license   License header.

Notes

  • Files which fail are printed to stderr as newline-delimited JSON (NDJSON).

  • If not provided a dir argument, the current working directory is the search directory.

  • To provide multiple exclusion glob patterns, set multiple --ignore option arguments.

    $ lint-license-header-glob --ignore=node_modules/** --ignore=build/** --ignore=reports/**
    
  • To provide multiple license headers, set multiple --header option arguments, where each argument value must include a file extension prefix. For example,

    $ lint-license-header-glob --header='awk:beep' --header='js:boop' --header='default:foo'
    
  • If a header is a regular expression, ensure that the option value is properly escaped.

    # Not escaped...
    $ <stdout> | lint-license-header-glob --header /\/\/ @license Apache-2.0/
    
    # Escaped...
    $ <stdout> | lint-license-header-glob --header /\\\\/\\\\/ @license Apache-2.0/
    

Examples

$ lint-license-header-glob .