npm-groovy-lint

NPM GROOVY LINT (+ Format & Auto-fix !)

Groovy / Jenkinsfile linter and autofixer

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 (beta)
• Use option --fix to activate autofixing of fixable rules (beta)
• Use option --parse to also detect future compilation errors

Easy to integrate in a CD/CI 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

See CHANGELOG

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

INSTALLATION

    $ npm install -g npm-groovy-lint

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

USAGE

    $ npm-groovy-lint OPTIONS

Parameter	Type	Description
-p --path	String	Directory containing the files to lint Example: ./path/to/my/groovy/files
-f --files	String	Comma-separated list of Ant-style file patterns specifying files that must be included. Default: "**/*.groovy,**/Jenkinsfile" Examples: - "**/Jenkinsfile" - "**/*.groovy"
-o --output	String	Output format (txt,json,html,xml), or path to a file with one of these extensions Default: txt Examples: - "txt" - "json" - "./logs/myLintResults.txt" - "./logs/myLintResults.json" - "./logs/myLintResults.html" - "./logs/myLintResults.xml"
-l --loglevel	String	Log level (error,warning or info) Default: info
-c --config	String	Custom path to GroovyLint config file 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 (works only with source argument)
--fix	Boolean	(beta) Automatically fix problems when possible See Autofixable rules
--format	Boolean	(beta) Format source code
--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" - EmptyInstanceInitializer,EmptySwitchStatement,ForLoopShouldBeWhileLoop
-s --source	String	If path and files are not set, you can directly send the source code string to analyze
-v --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/*""
--failonerror	Boolean	Fails if at least one error is found
--failonwarning	Boolean	Fails if at least one warning is found
--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
--failoninfo	Boolean	Fails if at least one error is found
--returnrules	Boolean	Return rules descriptions and URL if set
--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="jdeploy-bundle/lib/example" -rulesetfiles="file:jdeploy-bundle/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)

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.

Define a file named .groovylintrc.json (or .js or .YAML, or include in a property groovyLintConfig in package.json)

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 or all)
• rules: List of rules definition, following format "RuleSection.RuleName": ruleParameters or "RuleName": ruleParameters
  • "RuleSection.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

Example:

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

EXAMPLES

• Lint groovy with JSON output

    $ npm-groovy-lint --output json

• 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="jdeploy-bundle/lib/example" -rulesetfiles="file:jdeploy-bundle/lib/example/RuleSet-Groovy.groovy" -title="TestTitleCodenarc" -maxPriority1Violations=0' -report="html:ReportTestCodenarc.html"

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 (beta)

• BlockEndsWithBlankLine
• BlockStartsWithBlankLine
• ClassEndsWithBlankLine
• ClassStartsWithBlankLine
• ClosingBraceNotAlone
• ConsecutiveBlankLines
• ElseBlockBraces
• FileEndsWithoutNewline
• IfStatementBraces
• Indentation
• IndentationClosingBraces
• IndentationComments
• MisorderedStaticImports
• NoTabCharacter
• SpaceAfterCatch
• SpaceAfterComma
• SpaceAfterFor
• SpaceAfterIf
• SpaceAfterOpeningBrace
• SpaceAfterSemicolon
• SpaceAfterSwitch
• SpaceAfterWhile
• SpaceAroundOperator
• SpaceBeforeOpeningBrace
• TrailingWhitespace
• UnnecessaryDefInFieldDeclaration
• UnnecessaryGString
• UnnecessaryGroovyImport
• UnnecessarySemicolon
• UnnecessaryToString
• UnusedImport

Contribute to add more rules fixes :)

CALL VIA JS 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/jdeploy-bundle/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

• On some environments, it has been observed that installed Groovy version must match Groovy embedded jars delivered with npm-groovy-lint (Groovy 3.0.3)

CONTRIBUTE

Contributions are very welcome !

Please follow Contribution instructions

THANKS

This package uses :

• CodeNarc : https://github.com/CodeNarc/CodeNarc (groovy lint)
• jdeploy : https://github.com/shannah/jdeploy (jar deployment and run)
• slf4j : http://www.slf4j.org/ (logging for CodeNarc)
• log4j : https://logging.apache.org/log4j/2.x/ (logging for CodeNarc)
• GMetrics : https://dx42.github.io/gmetrics/ (Code measures for CodeNarc)
• Inspiration from eslint about configuration and run patterns