npm-groovy-lint

NPM GROOVY LINT (and 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)

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

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
--fix	Boolean	(beta) Automatically fix problems when possible See Autofixable rules
--format	Boolean	(beta) Format source code
-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 jaja/groovy everytime,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"

Autofixable rules (beta)

• BlockEndsWithBlankLine
• BlockStartsWithBlankLine
• ConsecutiveBlankLines
• FileEndsWithoutNewline
• IfStatementBraces
• Indentation (IfStatementBraces and ElsefStatementBraces must be fixed to have correct indentation)
• MisorderedStaticImports
• NoTabCharacter
• SpaceAfterCatch
• SpaceAfterComma
• SpaceAfterIf
• SpaceAfterOpeningBrace
• SpaceAroundOperator
• SpaceBeforeOpeningBrace
• TrailingWhitespace
• UnnecessaryDefInFieldDeclaration
• UnnecessaryGroovyImport
• UnnecessaryGString
• 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

• Embedded Groovy 3.0.2 may have issues with JDK12, please use JDK11 or a precedent version if possible
• CodeNarc server does not seems to Work on some Linux environments (java classes are loaded at each npm-groovy-lint call so performances are slower)
• On some environments, it has been observed that installed Groovy version must match Groovy embedded jars delivered with npm-groovy-lint (3.0.2)

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 mesures for CodeNarc)
• Inspiration from eslint about configuration and run patterns

Changelog

[3.2.2] 2020-03-31

• New option returnrules if you want to return rules descriptions and documentation url in results
• Use npm ci instead of npm install in CircleCI build