NPM GROOVY LINT (+ Format & Auto-fix)

Groovy & Jenkinsfile Linter, Formatter and Auto-fixer

New: The article about the story of npm-groovy-lint, and why you should dive in open-source community !

Based on CodeNarc , this out of the box package allows to track groovy errors and correct a part of them

Use option --format to format & prettify source code
Use option --fix to activate autofixing of fixable rules

Easy to integrate in a CI/CD process (Jenkins Pipeline,CircleCI...) to lint your groovy or Jenkinsfile at each build :)

You can also use this package in :

Visual Studio Code Groovy Lint extension
Mega-Linter (can be used as GitHub Action, and lints all other languages and formats)
Docker Image

See CHANGELOG

Any question, problem or enhancement request ? Ask here :)

Usage

    npm-groovy-lint [OPTIONS] [FILES|PATH|PATTERN]

Parameter	Type	Description
-o --output	String	Output format (txt,json,sarif,html,xml), or path to a file with one of these extensions Default: `txt` Examples: - `"txt"` - `"json"` - `"./logs/myLintResults.txt"` - `"./logs/myLintResults.sarif"` - `"./logs/myLintResults.html"` - `"./logs/myLintResults.xml"` Note: HTML and XML are directly from CodeNarc so using these formats will disable many npm-groovy-lint features
-l --loglevel	String	Log level (error,warning or info) Default: info
--failon	String	Defines the error level where CLI will fail (return code = 1). error,warning,info or none. Each failure level includes the more critical ones.
-c --config	String	Custom path to GroovyLint config file, or preset config `recommended\\|recommended-jenkinsfile\\|all` Default: Browse current directory to find `.groovylintrc.json\\|js\\|yml\\|package.json` config file, or default npm-groovy-lint config if not defined. Note: command-line arguments have priority on config file properties
--parse	Boolean	Try to compile the source code and return parse errors (since v5.7.0, default to true, use --no-parse to deactivate)
--format	Boolean	Format source code
--fix	Boolean	Automatically fix problems when possible See Auto-fixable rules
-x --fixrules	String	Option for --fix argument: List of rule identifiers to fix (if not specified, all available fixes will be applied). See Auto-fixable rules Examples: - `"SpaceBeforeClosingBrace,SpaceAfterClosingBrace,UnusedImport"` - `"Indentation"`
--nolintafter	Boolean	When format or fix is called, a new lint is performed after the fixes to update the returned error list. If you just want the updated source code and do not care about the error logs, use this parameter to improve performances
-r --rulesets	String	RuleSet file(s) to use for linting, if you do not want to use recommended rules or .groovylintrc.js defined rules. If list of comma separated strings corresponding to CodeNarc rules, a RuleSet file will be dynamically generated Examples: - `"./config/codenarc/RuleSet-Custom.groovy"` - `"./path/to/my/ruleset/files"` - `Indentation{"spacesPerIndentLevel":2,"severity":"warning"},UnnecessarySemicolon,UnnecessaryGString`
--rulesetsoverridetype	String	If list of rules sent in rulesets option, defines if they replace rules defined in .groovylintrc.json, or if they are appended Values: `replaceConfig` (default), `appendConfig`
-s --source	String	If path and files are not set, you can directly send the source code string to analyze
--verbose	Boolean	More outputs in console, including performed fixes
-i --ignorepattern	String	Comma-separated list of Ant-style file patterns specifying files that must be ignored Default: none Example: `"*/test/""`
--noserver	Boolean	npm-groovy-lint launches a microservice to avoid performance issues caused by loading java/groovy each time,that auto kills itself after 1h idle. Use this argument if you do not want to use this feature
--returnrules	Boolean	Return rules descriptions and URL if set
--javaexecutable	String	Override java executable to use Default: java Example: C:\Program Files\Java\jdk1.8.0_144\bin\java.exe
--javaoptions	String	Override java options to use Default: "-Xms256m,-Xmx2048m"
--insight	Boolean	npm-groovy-lint collects anonymous usage statistics using amplitude, in order to make new improvements based on how users use this package. Summary charts are available at https://tinyurl.com/groovy-stats. Analytics obviously does not receive sensitive information like your code, as you can see in analytics.js. If you want to enable anonymous usage statistics, use `--insight` option.
--codenarcargs	String	Use core CodeNarc arguments (all npm-groovy-lint arguments will be ignored) Doc: http://codenarc.github.io/CodeNarc/codenarc-command-line.html Example: `npm-groovy-lint --codenarcargs -basedir="lib/example" -rulesetfiles="file:lib/example/RuleSet-Groovy.groovy" -maxPriority1Violations=0 -report="xml:ReportTestCodenarc.xml`
-h --help	Boolean	Show help (npm-groovy-lint -h OPTIONNAME to see option detail with examples)
-v --version	Boolean	Show npm-groovy-lint version (with CodeNarc version)
-p --path	String	(DEPRECATED) Directory containing the files to lint Example: `./path/to/my/groovy/files`
-f --files	String	(DEPRECATED) Comma-separated list of Ant-style file patterns specifying files that must be included. Default: `"*/.groovy,/Jenkinsfile,/.gradle"` Examples: - `"/Jenkinsfile"` - `"/.groovy"` - `"*/.gradle"` - `"**/mySingleFile.groovy"`

Example calls

Lint a file

    npm-groovy-lint path/to/my/groovy/file.groovy

Lint multiple files

    npm-groovy-lint path/to/my/groovy/file.groovy path/to/my/groovy/file2.groovy path/to/my/groovy/file3.groovy

Lint directory

    npm-groovy-lint path/to/my/groovy

Lint pattern

    npm-groovy-lint path/to/my/groovy/*.groovy

Lint groovy with JSON output

    npm-groovy-lint --output json

Format files

    npm-groovy-lint --format my/path/to/file.groovy my/path/to/file2.groovy

Format and fix files

    npm-groovy-lint --fix my/path/to/file.groovy my/path/to/file2.groovy

Get formatted sources in stdout from stdin

    cat path/to/my/Jenkinsfile | npm-groovy-lint --format -

Advanced config

    npm-groovy-lint --path "./path/to/my/groovy/files" --files "**/*.groovy" --config "./config/codenarc/.groovylintrcCustom.js" --loglevel warning --output txt

Lint using core CodeNarc parameters and generate HTML report file

    npm-groovy-lint --codenarcargs -basedir="lib/example" -rulesetfiles="file:lib/example/RuleSet-Groovy.groovy" -title="TestTitleCodenarc" -maxPriority1Violations=0' -report="html:ReportTestCodenarc.html"

Installation

    npm install -g npm-groovy-lint

If you have issues with v9, install previous version with npm install -g npm-groovy-lint@8.2.0
Node.js >= 12 is required to run this package. If you can't upgrade, you can use nvm to have different node versions on your computer
If you do not have java 17 installed on your computer, npm-groovy-lint will install them for you, so the first run may be long.

Configuration

Default rules definition (recommended, based on all tracks a lot of errors, do not hesitate to ignore some of them (like NoDef ou RequiredVariableType) if they are too mean for your project.

Create a file named .groovylintrc.json in the current or any parent directory of where your files to analyze are located

your-repo-root-folder
- src
  - groovy
    - mygroovyfile.groovy
- Jenkinsfile
- .groovylintrc.json (do not forget the dot at the beginning of the file name)

If you are using VsCode Groovy Lint extension, just use QuickFix Ignore in all files and it will generate groovylintrc.json file.

Format

extends: Name of a base configuration (recommended, recommended-jenkinsfile, all)
rules: List of rules definition, following format "RuleSection.RuleName": ruleParameters or "RuleName": ruleParameters
- RuleName: any of the CodeNarc rules
- ruleParameters: can be just a severity override ( "off", "error", "warning", "info" ) , or a property list :
  - severity : off,error,warning,info
  - enabled : true (default) or false
  - any of the rule advanced properties

OR

codenarcRulesets: Comma-separated string containing the list of .xml or .groovy CodeNarc RuleSet files (in case you already are a CodeNarc user and do not wish to switch to npm-groovy-lint config format)

Examples

{
    "extends": "recommended",
    "rules": {
        "comments.ClassJavadoc": "off",
        "formatting.Indentation": {
            "spacesPerIndentLevel": 4,
            "severity": "info"
        },
        "UnnecessaryReturnKeyword": "error"
    }
}

{
    "extends": "recommended-jenkinsfile",
    "rules": {
        "CouldBeElvis": "off",
        "CouldBeSwitchStatement": "off",
        "VariableName": {
            "severity": "info"
        }
    }
}

{
    "codenarcRulesets": "RuleSet-1.groovy,RuleSet-2.groovy"
}

Disabling rules in source

You can disable rules directly by adding comment in file, using eslint style

To temporarily disable rule warnings in your file, use block comments in the following format:

/* groovylint-disable */

def variable = 1;

/* groovylint-enable */

You can also disable or enable warnings for specific rules:

/* groovylint-disable NoDef, UnnecessarySemicolon */

def variable = 1;

/* groovylint-enable NoDef, UnnecessarySemicolon */

To disable rule warnings in an entire file, put a /* groovylint-disable */ block comment at the top of the file:

/* groovylint-disable */

def variable = 1;

You can also disable or enable specific rules for an entire file:

/* groovylint-disable NoDef */

def variable = 1;

To disable all rules on a specific line, use a line or block comment in one of the following formats:

def variable = 1; // groovylint-disable-line

// groovylint-disable-next-line
def variable = 1;

/* groovylint-disable-next-line */
def variable = 1;

def variable = 1; /* groovylint-disable-line */

To disable a specific rule on a specific line:

def variable = 1; // groovylint-disable-line NoDef

// groovylint-disable-next-line NoDef
def variable = 1;

def variable = 1; /* groovylint-disable-line NoDef */

/* groovylint-disable-next-line NoDef */
def variable = 1;

To disable multiple rules on a specific line:

def variable = 1; // groovylint-disable-line NoDef, UnnecessarySemicolon

// groovylint-disable-next-line NoDef, UnnecessarySemicolon
def variable = 1;

def variable = 1; /* groovylint-disable-line NoDef, UnnecessarySemicolon */

/* groovylint-disable-next-line NoDef, UnnecessarySemicolon */
def variable = 1;

Auto-Fixable rules

AssignmentInConditional
BlankLineBeforePackage
BlockEndsWithBlankLine
BlockStartsWithBlankLine
BracesForClass
BracesForForLoop
BracesForIfElse
BracesForMethod
BracesForTryCatchFinally
ClassEndsWithBlankLine
ClassStartsWithBlankLine
ClosingBraceNotAlone
ConsecutiveBlankLines
DuplicateImport
ElseBlockBraces
ExplicitArrayListInstantiation
ExplicitLinkedListInstantiation
FileEndsWithoutNewline
IfStatementBraces
Indentation
IndentationClosingBraces
IndentationComments
InsecureRandom
MisorderedStaticImports
MissingBlankLineAfterImports
MissingBlankLineAfterPackage
NoTabCharacter
SpaceAfterCatch
SpaceAfterComma
SpaceAfterFor
SpaceAfterIf
SpaceAfterOpeningBrace
SpaceAfterSemicolon
SpaceAfterSwitch
SpaceAfterWhile
SpaceAroundOperator
SpaceBeforeClosingBrace
SpaceBeforeOpeningBrace
TrailingWhitespace
UnnecessaryDefInFieldDeclaration
UnnecessaryDefInMethodDeclaration
UnnecessaryDefInVariableDeclaration
UnnecessaryDotClass
UnnecessaryFinalOnPrivateMethod
UnnecessaryGString
UnnecessaryGroovyImport
UnnecessaryPackageReference
UnnecessaryParenthesesForMethodCallWithClosure
UnnecessarySemicolon
UnnecessaryToString
UnusedImport

Contribute to add more rules fixes :)

CI/CD

Mega-Linter

Latest npm-groovy-lint version is natively integrated in Mega-Linter, that you can use as GitHub action or in other CI tools This tool can also automatically apply fixes on Pull Request branches

CircleCI

# .circleci/config.yml
version: 2.1
jobs:
  lint:
    docker:
      - image: nvuillam/npm-groovy-lint
    steps:
      - checkout

      - run: |
          npm-groovy-lint

workflows:
  version: 2
  "lint":
    jobs:
       - lint

Jenkins

node {
    checkout scm
    docker.image('nvuillam/npm-groovy-lint').inside {
        sh 'npm-groovy-lint'
    }
}

Shell

Run with default settings

docker run --rm -u "$(id -u):$(id -g)" -w=/tmp -v "$PWD":/tmp nvuillam/npm-groovy-lint

Run with additional flags by simply appending them at after docker image name:

docker run --rm -u "$(id -u):$(id -g)" -w=/tmp -v "$PWD":/tmp nvuillam/npm-groovy-lint --failon warning --verbose

Other

You can run npm-groovy-lint using its official docker image

Use as module

You can import npm-groovy-lint into your NPM package and call lint & fix via module, using the same options than from npm-groovy-lint command line

Example

    npm install npm-groovy-lint --save

    const NpmGroovyLint = require("npm-groovy-lint/lib/groovy-lint.js");
    const fse = require("fs-extra");

    const npmGroovyLintConfig = {
        source: fse.readFileSync('./lib/example/SampleFile.groovy').toString(),
        fix: true,
        loglevel: 'warning',
        output: 'none'
    };
    const linter = new NpmGroovyLint(npmGroovyLintConfig, {});
    await linter.run();
    console.log(JSON.stringify(linter.lintResult));

Troubleshooting

If you have issues with MegaLinter, you can report it on the repository

To help reproducing, you can access advanced logs using DEBUG env variables

Examples:

DEBUG=npm-groovy-lint npm-groovy-lint ....
DEBUG=npm-groovy-lint,npm-groovy-lint-trace npm-groovy-lint ....

If you want to see what happens in CodeNarc Server, you can clone the repo and run locally npm server:run before running npm-groovy-lint: you'll see the live logs of the to CodeNarc Server for npm-groovy-lint.