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 in the npm-groovy-lint issue tracker :)

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 a preset name `recommended\\|advanced\\|all\\|format\\|grails\\|tests\\|jenkinsfile\\|recommended-jenkinsfile` 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"`
--fixrulesexclude	String	Option for --fix argument: Comma-separated list of rule identifiers to exclude from fixes (if not specified, none are excluded). If used with --fixrules, exclusion is applied last (excluded rules cancel included rules). See Auto-fixable rules Examples: - `"Indentation,IndentationClosingBraces,BracesForIfElse"` - `"UnnecessarySemicolon,SpaceAfterComma"`
--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" and a max heap of half the available memory, between "-Xmx2048m" and "-Xmx4096m"
-P --parallelism	Int	Number of threads used to analyse files in parallel (default: auto, max 4). Use 1 to disable
--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

Fix files but exclude specific rules (useful for avoiding buggy indentation rules)

    npm-groovy-lint --fix --fixrulesexclude Indentation,IndentationClosingBraces,BracesForIfElse my/path/to/file.groovy

Fix only specific rules

    npm-groovy-lint --fix --fixrules SpaceAfterComma,TrailingWhitespace,UnusedImport my/path/to/file.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 v19, install the previous version with npm install -g npm-groovy-lint@18 and see Migrating from v18 to v19
Node.js >= 22.13.0 is required to run this package. If you can't upgrade, you can use nvm to have different node versions on your computer
Java 17 or higher is required. If you do not have a compatible Java version installed on your computer, npm-groovy-lint will install Java 17 for you, so the first run may be long.

Migrating from v18 to v19

v19 is about 3 to 18 times faster, but it changes what a lint reports by default. Check these points when you upgrade.

1. Stop the old CodeNarc server

npm-groovy-lint keeps a CodeNarc server running in the background. Stop it before upgrading:

npm-groovy-lint --killserver
npm install -g npm-groovy-lint@19

If you forgot, run npm-groovy-lint --killserver again with v19: it stops both old and new servers. A v18 --killserver cannot stop a v19 server, so don't mix versions in the same environment (kill the process by its PID, or let it stop by itself after 1 hour idle).

2. Expect fewer violations by default

The default preset, recommended, now reports only what is most likely a mistake (149 rules). v18 reported nearly every CodeNarc rule (390 rules), including style and layout. See Rule presets.

What you may notice:

Fewer violations, and builds that used to fail may now pass. Style rules (NoDef, *TypeRequired, naming, Unnecessary*, size thresholds, Javadoc...) and layout rules (indentation, braces, spacing) are no longer reported by default.
--fix and --format still fix layout exactly as before. Layout is fixed, just not reported.
Inline comments such as // groovylint-disable-next-line NoDef still work. They simply have nothing to hide for rules that are no longer enabled.

To get the old rules back, set extends in your .groovylintrc.json:

You want	Set
Layout violations reported too	`{ "extends": ["recommended", "format"] }`
Style and layout reported (Groovy idioms, naming)	`{ "extends": "advanced" }`
The closest to the v18 default	`{ "extends": "all" }` (see below)
Grails or JUnit/Spock rules	`{ "extends": ["recommended", "grails", "tests"] }`

v18's default was all with a few changes. To get it back as closely as possible:

{
    "extends": "all",
    "rules": {
        "convention.TrailingComma": "off",
        "formatting.SpaceAroundMapEntryColon": "off",
        "logging.Println": "off",
        "unnecessary.UnnecessaryReturnKeyword": "off"
    }
}

3. Check your preset names

recommended, all, format and recommended-jenkinsfile still exist.
The grails, tests and jenkinsfile presets now include recommended. -c jenkinsfile alone is a full lint, not only the Jenkinsfile-specific rules.
extends accepts a list, merged from left to right: { "extends": ["advanced", "jenkinsfile"] }.

4. Check your command lines and environment

If you use	In v19
Node.js older than 22.13	Upgrade Node.js to 22.13 or higher
`--files`	It was silently ignored since v13: every file under `--path` was linted. It is now applied, so only matching files are linted
`DEBUG=npm-groovy-lint` to get debug logs	Use `NODE_DEBUG=npm-groovy-lint` instead
`--serverhost http://localhost`	The default is now `http://127.0.0.1`. Keep your value only if you really run the server elsewhere
A machine or container with little memory	The server's max heap is now half the available memory, between 2048m (the v18 value) and 4096m. Set `--javaoptions "-Xms256m,-Xmx1024m"` to use less
Many cores, and you want one thread	Files are now analysed on up to 4 threads. Use `--parallelism 1` to analyse one file at a time

Configuration

Rule presets

npm-groovy-lint ships tiered presets, the way ESLint separates eslint:recommended from the rest. The default is recommended.

Preset	Rules	What it reports
`recommended` (default)	149	Only what is most likely a mistake: code that does not do what its author meant, dead code, security and concurrency hazards, misused APIs
`advanced`	344	`recommended` + style: Groovy idioms, design, naming conventions, complexity thresholds, Javadoc and layout
`all`	390	Every CodeNarc rule, including those that do nothing until you configure them (`IllegalRegex`, `RequiredString`...)
`format`	40	Layout only: indentation, braces, blank lines, spacing. This is what `--format` and `--fix` apply

Plus three framework add-ons: grails, tests (JUnit and Spock) and jenkinsfile (relaxes the rules a pipeline always breaks). Each extends recommended, so using one standalone (-c jenkinsfile) is a full lint; to compose them on top of another tier, list them after it:

{
    "extends": ["advanced", "grails", "tests"]
}

Presets are merged from left to right, and your own rules always win.

recommended reports no layout at all — that belongs to format. Layout is still fixed, just not reported: npm-groovy-lint --fix applies the format rules on top of the lint ruleset, so it repairs indentation, braces and spacing exactly as before, and --format is unchanged. A rule you disable in your own config stays disabled under --fix.

To report layout too, add the format preset — or take everything with advanced:

{
    "extends": ["recommended", "format"]
}

Anything can be re-enabled one rule at a time by naming it in your own rules block.

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, advanced, all, format, grails, tests, jenkinsfile, recommended-jenkinsfile), or a list of them merged from left to right — see Rule presets
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": ["advanced", "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

Use the GitHub Container Registry image by replacing the image name:

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

Other

You can run npm-groovy-lint using its official Docker Hub image or its GHCR 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

    import NpmGroovyLint from "npm-groovy-lint/lib/groovy-lint.js";
    import fs from "node:fs";

    const npmGroovyLintConfig = {
        source: fs.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));

Performance

npm-groovy-lint runs CodeNarc inside a local server (the "CodeNarc server") that stays alive between calls and stops itself after 1 hour idle, so only the first call pays the Java startup cost.

Parallel analysis: files are split across up to 4 threads inside the server. Use --parallelism <n> (-P) to change the number of threads, or --parallelism 1 to analyse files one at a time.
Result cache: the server keeps the results of each file in memory, so re-linting a file that did not change returns instantly. The cache is only used for the default JSON output: it is skipped when CodeNarc must write a report itself (--output html or xml, or --codenarcargs reports). It is emptied when the server stops (--killserver), and never used with --noserver.
Memory: the server's max heap is half the memory available (the container limit when there is one), between 2048m and 4096m. Set it yourself with --javaoptions, for example --javaoptions "-Xms256m,-Xmx1024m".

Troubleshooting

If you have issues with npm-groovy-lint, you can report it on the repository

To help reproducing, you can access advanced logs using the NODE_DEBUG env variable

Examples:

NODE_DEBUG=npm-groovy-lint npm-groovy-lint ....
NODE_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 run server:run before running npm-groovy-lint: you'll see the live logs of the to CodeNarc Server for npm-groovy-lint.