mrexception / idea-cli-inspector

A little command-line tool to integrate the awesome IntelliJ IDEA code inspections in your continuous integration (CI) process using Jenkins, Bamboo, et. al.

IntelliJ IDEA CLI Inspector Wrapper idea-cli-inspector

A little command-line tool to integrate the awesome IntelliJ IDEA code inspections in your continuous integration (CI) process using Jenkins, Bamboo, et. al.

Why this tool?

IntelliJ IDEA offers a vast amount of very high-quality, built-in code inspections. Currently it has more than 1073 inspections to offer. Using project-shared inspection profiles it’s possible to guide developers in a wide range of coding aspects in a non-annoying way.

In contrast to well-known quality tools like SonarQube these inspections do have quite a few benefits:

• violations are instantly visible during code writing with freely configurable severities and warning levels. (i.e. bold red errors, yellow warning or discreet hints as recommendation)

• false alarms can be easily and immediately suppressed. A simple Alt-Enter directly at the location where they occur is enough.
  Alternatively you can adjust your inspection settings just on-the-fly (i.e. reduce level, disable inspection or configure inspection properties)

• IDEA allows you to check for new violations introduced with your changes while you are trying to commit them

• Many inspections in IDEA provide semi-automatic quickfixes and auto-corrections. So again sometimes addressing an issue is as simply as pressing Alt-Enter Right arrow Enter.

• Because all inspections are based on IDEA´s Psi engine (which is a sort of permanent running syntax compiler) the inspections effectively work on an actual AST. So IDEA understands the code and does not only look for (textual) patterns which in return leads to a significantly lower rate of false-positives.

Nevertheless, though IDEA offers on-the-fly analysis and error visualization it does not stop the developer in committing code violating these helpful guidelines into the project repository. JetBrain´s CI solution TeamCity does offer a easy and good integration. It is also possible to execute the IDEA project inspection on the command line, which will produce a hard-readable set of XML files and no further support for integrating this into an automated tool chain.

Therefore I did hack this little Groovy script to easily include & report inspection checks into your CI chain.

What it does

This tool is aimed to simplify the inclusion of IDEA code inspection in your CI chain. It executes a command-line based run of an IntelliJ inspection run. This produces a set of hardly human-readable XML files in the target directory.

Therefore the tool subsequently parses the generated inspection result files, allows to filter out selected result files and looks for messages with given severity (WARNING and ERROR by default).

The tool will list issues in a humand-readable form and exit with return code 1 if it did find any issues (your CI tool should interpret this as failure) or will happily tell you that everyhing is fine.

Prerequisites & Limitations

The script is developed in Groovy, so this has to be installed. Furthermore you need a valid installation of IntelliJ IDEA.

Note	Due to a limitation of IDEA itself it is not possible to run more than one IDEA instance at the same time. Therefore you must ensure, that no other IDEA is running on your PC / on your CI agents.

Usage

Configuration file base usage

IDEA CLI Inspector supports configuration via a .ideainspect file in the project root directory. Below is a example:

link:.ideainspect[role=include]

Command line based usage

For a full list of options please run ideainspect.groovy -h:

usage: groovy ideainspect.groovy -i <IDEA_HOME> -p <PROFILEXML> -r <PROJDIR>
 -d,--dir <dir>           Limit IDEA inspection to this directory
                          Overrides the scope argument
 -h,--help                Show usage information and quit
 -i,--ideahome <dir>      IDEA or Android Studio
                          installation home directory. Required
 -l,--levels <level>      Levels to look for. Default: WARNING,ERROR
 -p,--profile <file>      Use this inspection profile file located
                          ".idea/inspectionProfiles".
                          Example: "myprofile.xml"
 -r,--rootdir <dir>       IDEA project root directory containing the
                          ".idea" directory
 -s,--skip <file>         Analysis result files to skip. For example
                          "TodoComment" or "TodoComment.xml".
 -sf,--skipfile <regex>   Ignore issues affecting source files matching
                          given regex. Example ".*/generated/.*".
 -ip,--iprops <dir>       The full path to the "idea.properties" file.
                          Info can be found at:
                          http://tools.android.com/tech-docs/configuration
 -sc,--scope <string>     Perform analysis with scope name. These are
                          usually set in IDEA or Android Studio. The
                          scope file should be placed in .idea/scopes/
 -t,--resultdir <dir>     Target directory to place the IDEA inspection
                          XML result files. Default:
                          target/inspection-results

Example usage

$ groovy ideainspect.groovy \
    -i ~/devel/idea \
    -r ~/projects/p1 \
    -p myinspections.xml \
    -d server \
    -s unused,Annotator,TodoComment.xml \
    -l ERROR

This looks for a IntelliJ installation in ~/devel/idea, tries to perform a CLI-based code inspection run on the IDEA project ~/projects/p1/.idea with an inspection profile ~/projects/p1/.idea/inspectionProfiles/myinspections.xml limiting the inspection run to the subdirectory server within your project.

The IDEA inspection run will produce a set of .xml files. The amount, levels and result is based on the inspection profile you passed. Option -s tells to skip & ignore the warnings contained in the inspection result files unused.xml, Annotator.xml and TodoComment.xml. You can ommit the .xml suffix for convenience.

By default it will then look for entries marked as [WARNING] or [ERROR] within the remaining inspection result report files. In our case we only care for ERROR entries. If it finds entries, it will report the file joined with a description pointing to the file location and the inspection rule.

Example output

➜ idea-cli-inspector.git git:(master) ✗ ./ideainspect.groovy -i ~/devel/idea -r ../dashboard.git -p bens_idea15_2015_11.xml -d server -s Annotator,JSUnresolvedLibraryURL.xml,JavaDoc,TodoComment -l ERROR,WARNING

= IntellIJ IDEA Code Analysis Wrapper - v1.0 - @bentolor
#
# Running IDEA IntelliJ Inspection
#
Executing: /home/ben/devel/idea/bin/idea.sh [/home/ben/devel/idea/bin/idea.sh, inspect, /home/ben/projects/idea-cli-inspector.git/../dashboard.git, /home/ben/projects/idea-cli-inspector.git/../dashboard.git/.idea/inspectionProfiles/bens_idea15_2015_11.xml, /home/ben/projects/idea-cli-inspector.git/../dashboard.git/target/inspection-results, -d, server]
log4j:WARN No appenders could be found for logger (io.netty.util.internal.logging.InternalLoggerFactory).
log4j:WARN Please initialize the log4j system properly.
log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
Please configure library 'Node.js v4.2.1 Core Modules' which is used in module 'client'

   ...
   IDEA spilling out quite a bunch of exceptions during inspection run
   ...

#
# Inspecting produced result files in ../dashboard.git/target/inspection-results
#
# Looking for: [[WARNING], [ERROR]]
# Ignoring : [Annotator, JSUnresolvedLibraryURL, JavaDoc, TodoComment]
--- ClassNamePrefixedWithPackageName.xml
[WARNING] server/src/main/java/de/foo/dashboard/data/DatasetVerticle.java:28 -- Class name <code>DatasetVerticle</code> begins with its package name #loc
[WARNING] server/src/main/java/de/foo/dashboard/data/DatasetBuilder.java:17 -- Class name <code>DatasetBuilder</code> begins with its package name #loc

--- InterfaceNamingConvention.xml
[WARNING] server/src/main/java/de/foo/dashboard/constants/Events.java:11 -- Interface name <code>Events</code> is too short (6 < 8) #loc

--- SameParameterValue.xml
[WARNING] server/src/main/java/de/foo/dashboard/data/DatasetBuilder.java:30 -- Actual value of parameter '<code>type</code>' is always '<code>de.exxcellent.dashboard.constants.DatasetType.ARRAY</code>'

--- Skipping JavaDoc.xml
--- Skipping TodoComment.xml
--- DeprecatedClassUsageInspection.xml
[WARNING] server/pom.xml:99 -- 'io.vertx.core.Starter' is deprecated

--- Skipping JSUnresolvedLibraryURL.xml
--- Skipping Annotator.xml
--- unused.xml
[WARNING] server/src/main/java/de/foo/dashboard/data/DatasetBuilder.java:40 -- Method is never used.
[WARNING] server/src/main/java/de/foo/dashboard/constants/DatasetType.java:14 -- Field has no usages.
[WARNING] server/src/main/java/de/foo/dashboard/constants/DatasetType.java:14 -- Field has no usages.
[WARNING] server/src/main/java/de/foo/dashboard/data/DatasetVerticle.java:28 -- Class is not instantiated.
[WARNING] server/src/main/java/de/foo/dashboard/transformers/History.java:23 -- Class is not instantiated.

#
# Analysis Result
#
Entries found. return code: 1

Troubleshooting & FAQ

I receive a error message Please, specify sdk 'null' for module 'foo'

Probably you excluded misc.xml from the versionied IDEA project. Which is fine because this file is quite volatile. But this is the file where IDEA stores the "Root JDK".

To fix this error simply assign every module a SDK other than "Project SDK".

The analysis seems to produce different results on subsequent runs on the same sources (esp. JavaScript)

This seems to be an issue with the IDEA caches which IntelliJ keeps i.e. under .IntelliJ2016.1/system. Try if deleting this directory prior to executing the analysis runs produces stable results.

What shall I pass as IDEA home directory for Mac OSX?

/Applications/IntelliJ\ IDEA.app should be the default installation folder.

Source code & Contributions

The source code is located under https://github.com/bentolor/idea-cli-inspector.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0