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 --fix to activate autofixing (the function is still in experimental phase, you may have to run it several times at first so CodeNarc take in account the updates)

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

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.js/json/yml/package.json config file, or default npm-groovy-lint config if not defined. Note: command-line arguments have priority on config file properties
-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
--fix	Boolean	(Experimental) Automatically fix problems when possible See Autofixable rules
-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
--codenarcargs	Boolean	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

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

Format :

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

Example:

module.exports = {
    extends: "recommended",
    rules: {
        "comments.ClassJavadoc": 'off',
        "formatting.Indentation": {
            spacesPerIndentLevel: 4,
            severity: "info"
        },
        'unnecessary.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 (experimental)

• ConsecutiveBlankLines
• FileEndsWithoutNewline
• IfStatementBraces
• Indentation (IfStatementBraces and ElsefStatementBraces must be manually fixed to have correct indentation)
• NoTabCharacter
• SpaceAfterCatch
• SpaceAfterComma
• 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 !

• Fork the repo and clone it on your computer
• Run npm run lint then npm run test to check your updates didn't break anything
• Once your code is ready, documented and testing, please make a pull request :)

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.0.0] 2020-03-15

• Local microservice "CodeNarcServer" called via Http by npm-groovy-lint, to avoid loading all groovy/java classes at each lint request. This microservice auto-kills itself after one hour idle.
• Capability to define RuleSets in argument or js/json/yml config file formats instead of groovy/xml RuleSet format
• Test classes for rules fix (before / after fix defined in rule definitions)
• Add debug logs (use it by setting DEBUG env variable , ex: DEBUG=npm-groovy-lint npm-groovy-lint args...)
• Update lines and ranges of other errors after a fix updated the number of lines
• Generate automatically .groovylintrc-all.js during build
• Split rules definition into files instead of all in a huge single file
• Reorganize groovy-lint.js code, using codenarc-factory.js and codenarc-caller.js
• New lib utils.js that can be used by rules definition
• Fix: Crash when there was no error found in a file
• Fix: Remove Promise error display in log after launching CodeNarcServer
• Fix: Add more options exclusivity arguments rules
• Removed "Groovy", "Jenkinsfile" and "All" identifiers for --rulesets arguments. Please now use .groovylintrc.js configuration