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]

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.

Contribute

Contributions are very welcome !

Please follow Contribution instructions

Thanks

Other packages used

• CodeNarc: groovy lint
• java-caller: Easy call Java commands from Node
• slf4j: logging for CodeNarc
• log4j: logging for CodeNarc
• GMetrics: Code measures for CodeNarc
• Inspiration from eslint about configuration and run patterns

Contributors

Nicolas Vuillamy	Dave Gallant	Howard Lo	Pawel Kopka	docwhat	CatSue

Release notes

See complete CHANGELOG