Naughty Platypus Memorabilia
    Wondering what’s next for npm?Check out our public roadmap! »

    npm-groovy-lint

    8.2.0 • Public • Published

    NPM GROOVY LINT (+ Format & Auto-fix)

    Version Downloads/week Downloads/total Test codecov Mega-Linter GitHub contributors GitHub stars Docker Pulls Docker Stars License PRs Welcome

    Groovy & Jenkinsfile Linter, Formatter and Auto-fixer

    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 CD/CI process (Jenkins Pipeline,CircleCI...) to lint your groovy or Jenkinsfile at each build :)

    You can also use this package in :

    image

    See CHANGELOG

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

    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,**/*.gradle"
    Examples:
    - "**/Jenkinsfile"
    - "**/*.groovy"
    - "**/*.gradle"
    - "**/mySingleFile.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
    --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 preset config `recommended
    --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 Autofixable rules
    -x
    --fixrules
    String Option for --fix argument: List of rule identifiers to fix (if not specified, all available fixes will be applied). See Autofixable rules
    Examples:
    - "SpaceBeforeClosingBrace,SpaceAfterClosingBrace,UnusedImport"
    - "Indentation"
    --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,-Xmx2048m"
    --no-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 disable anonymous usage statistics, use --no-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)

    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

    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 :

    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"
    }

    Example calls

    • 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="lib/example" -rulesetfiles="file: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

    • 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 :)

    CD/CI

    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 -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 -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/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));

    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

    nvuillam Dave Gallant warhod pawelkopka docwhat CatSue
                                       [Nicolas Vuillamy](https://github.com/nvuillam)                                        |                                           [Dave Gallant](https://github.com/davegallant)                                            |                                          [Howard Lo](https://github.com/warhod)                                          |                                           [Pawel Kopka](https://github.com/pawelkopka)                                            |                                          [docwhat](https://github.com/docwhat)                                           |                                            [CatSue](https://github.com/CatSue)
    

    Release notes

    See complete CHANGELOG

    Install

    npm i npm-groovy-lint

    DownloadsWeekly Downloads

    4,476

    Version

    8.2.0

    License

    GPL-3.0-only

    Unpacked Size

    16.8 MB

    Total Files

    121

    Last publish

    Collaborators

    • avatar