In this blog post, we will:

• Demonstrate searching and matching annotations
• Amen annotations using mustache templates

Sensei provides the ability to match problematic code patterns and then amend them to agreed implementations. In this example, I am using @Disabled without a parameter as the problematic code pattern.

Disabled Test Annotation

Disabled tests without a specified reason can prove problematic over the long term because we forget why we disabled it.

@Disabled
   void thisTestMethodHasNoDisabledReason(){
    Assertions.fail("This test is disabled and should not run");
    }

The risk is that, over time, the code base moves on, the disabled test is not updated in step with the purpose of the code and eventually becomes redundant and irrelevant, and potentially never re-enabled.

During code reviews, we will often point out that it is a good idea to add an explanatory description as the annotation parameter.

@Disabled ("Disabled to demonstrate adding a reason")
    void thisTestMethodHasDisabledReason(){
   Assertions.fail("This test is disabled and should not run");
   }

A Sensei Recipe

We can write a recipe to detect when @Disabled is added without explanation and a Quick Fix that reminds us to add the actual reason explaining why we disabled it.

When I think about what I'm going to do, I have to:

• match the Disabled annotation without any parameters
• change the Disabled annotation to have a parameter with marker text "TODO: add a description here"

Create a Warning Recipe

I use Alt+Enter to Create a new Recipe.

Then add the basic descriptive text in the general information.

By making the rule a warning, any matching code is highlighted but not shown as a glaring error.

Find the Annotation

In the recipe editor, I change the Search to match an annotation.

This will highlight all annotations in the preview.

Having done that, I want to filter on the type of annotation.

I could just use Disabled but I fully qualify the class with the package so that it only matches the annotation from JUnit 5. Because the source code is shown in the preview, I can easily copy and paste this in from the actual code to avoid any typos.

I then want to match only annotations without Parameters, and I can use the GUI to do that.

i.e. Search:

search:
  annotation:
    type: "org.junit.jupiter.api.Disabled"
    without:
       parameters:
          - {}

Create a Rewrite Quick Fix Action

For my QuickFix I will use a rewrite action.

I use the Show Variables functionality to show me the Mustache variables and preview the contents.

And then I add the extra code needed to create the place marker comment.

i.e. QuickFix:

availableFixes:
 - name: "Add a todo comment parameter"
   actions:
   - rewrite:
      to: "{{{ . }}}(\"TODO: add a description here\")"
      target: "self"

Sensei in Action

We have created a short video showing the recipe creation process in action.

Summary

When building a rewrite Quick Fix, it is easier when we can search for the code element that we want to rewrite, because it is then the self entity we can act on.

In this example, I used a rewrite action to amend the Annotation. Rewrite is a general-purpose action that can apply to any code element and is a good default to explore.

The Sensei plugin provides an easy way to find specific code patterns in your source code, and then apply rewrite rules to amend the matching code. All within the Intellij IDE, and in real-time.

‍

‍

For example, you could create a rule that matches on JUnit `@Disabled` annotations which do not have a reason, Sensei would then tell you about the issue by highlighting the code in the IDE.

Additionally, when you `alt+enter`, you can have the option to `Add a todo comment parameter`.

When selected, this would amend the code to add a boilerplate reason, which you can then amend, and if you don't, it will show up in your TODO panel.

e.g. `@Disabled` would become ` @Disabled("TODO: add a description here")`

Sensei combines the functionality of a Static Analysis code scanner with a code rewriting engine.

IntelliJ Intention Actions

Based on the above description, the obvious alternative (if you were not using Sensei) is to use the IntelliJ Intention Actions functionality.

Sensei differs from IntelliJ Intention Actions because the aim with Sensei is to provide a way to create matchers and rewriters which are project specific, or even local to an individual developer.

We have tried to put together a GUI that makes both the matching and rewrite rules easy to write and experiment with.

How can it help me personally improve?

When I'm learning a new library, it takes me time to build up muscle memory around the methods and formatting. So I might choose to create personal recipes which

• link off to the official documentation or tutorial pages
• have boilerplate templates which are most effective
• fix poor coding practices
• add boilerplate code to help use a library

I can use Sensei to build temporary recipes which prompt me for the current practices I've chosen to use and help me build up effective habits. And the recipes are temporary because I can remove them when I outgrow them.

How can it help my team improve?

In the same way we can help teams build up muscle memory around agreed coding standards.

Creating cookbooks of recipes that we apply when we find the same comments in pull request reviews. Since the cookbooks are stored in version control with the project, they are available to everyone on the project. And we can switch them off when we no longer need prompting.

Sensei helps provide feedback early

What we've tried to build with Sensei is a way of pulling the feedback that helps us improve, and reminders of corrective action, as early into the coding process as we can.

Rather than wait for

• the results of a static analyser
• the comments from a code review

We can instead see the feedback, for custom standards we want to enforce, as we code.

And we have either reminders, or actual rewrite rules, to help us write code that complies with the standards.

Sensei is flexible

In that way, Sensei is a bit of a mix, since it's:

• part Static Analyser
• coding tutor
• rewrite engine

Sensei is flexible enough to make the job of saying "What is Sensei?" that little bit harder.

Sensei fills a gap in the programming workflow

We've tried to make Sensei the missing piece of the programmer workflow that helps you improve specific elements in your coding style, or library use, that you and your team are currently working with.

This flexibility means that it takes a little more time to get to grips with Sensei than a static analysis tool or the built-in IntelliJ Intentions. Still, by spending the time to experiment, you will gain a new way to speed up your learning in your personal development process.

How to experiment?

Once you have downloaded and installed Sensei from the [Intellij Marketplace]

The easiest way to make Sensei work for you is to look at your coding process and consider:

• What documentation do you keep looking up?
  -- You could add some Sensei recipes that link back to that documentation.
• What simple mistakes do you keep making?
  -- You could temporarily codify that poor coding pattern as a matcher, and write a Quick Fix rewrite that amends the code to be what you really want to write.
• What boilerplate code do you write to use a library?
  -- You could create a Quick Fix rule to write the code for you.

Since Sensei is designed to work alongside whatever static analysis tool you're using, if you find that the same violations are being reported from static analysis, then you could replicate the condition in a Sensei recipe. You can then add a Quick Fix to help train you, not just to identify the mistake, but also to move quickly to writing the correct code

Running IntelliJ Inspections From Continuous Integration

IntelliJ IDEA offers functionality to help improve our coding, within the IDE when writing code as Intentions. Intentions can be used in batch to inspect code for patterns throughout the source and even extending to Command-Line analysis or added to Continuous Integration. This post covers the out of the box IntelliJ functionality and expanding with custom Intentions created in Sensei.

‍

IntelliJ Inspections

The Inspections feature of IntelliJ drives the display of many of the errors that are reported dynamically in the IDE when coding e.g.

• detecting abstract classes that can be converted to interfaces,
• identifying redundant class fields which can be local,
• warning about uses of deprecated methods,
• etc.

These Inspections highlight code that matches in the IDE as Intention Actions which often have an associated QuickFix.

The real-time IDE highlighting when code matches an Inspection can help us improve our coding dynamically. After identifying the issue in the code, using IntelliJ Intention Actions to QuickFix the code can reinforce better patterns.

Inspections Profile

Inspections can run as a batch from within the IDE, and from the Command Line or in a Continuous Integration process.

The key to working with IntelliJ inspections as a batch is through the use of an Inspections Profile.

IntelliJ has two default Inspection Profiles: one stored in the Project, and one stored in the IDE.

New Inspection Profiles can be created to configure specific plugins or use-cases e.g.

• Run Checkstyle real-time scan only
• Run a specific set of Sensei rules
• Run the HTML checks
  

The Inspections in a profile can be enabled or disabled from the IntelliJ Preferences. The Preferences dialog is also an easy way to learn the range of Inspections available.

The ‘tool’ icon allows you to duplicate a Profile and create a new Profile to collect a specific set of rules.

Running an Inspection Profile in the IDE

Inspection Profiles can be run from within the IDE using the `Analyze \ Inspect Code...` menu.

The Analyze functionality allows you to control the scope that the Inspection will run against e.g. the whole project, including or excluding test sources, or against a specific set of files. 

You can also manage the Inspection Profiles from here to create or configure a particular profile.

Clicking [OK] on the “Specify Inspection Scope” dialog will trigger IntelliJ into running all the selected Inspections in the profile across the defined scope.

IntelliJ will report the results of running the Inspections in the `Inspection Results` tab.

The Sensei plugin from Secure Code Warrior allows you to create custom code matching recipes. Sensei tightly integrates with IntelliJ to make these custom recipes as natural to use as the IntelliJ Intention Actions. Meaning they are loaded into IntelliJ as Inspections and can be grouped, enabled, and disabled using Inspection Profiles. Creating a custom Inspection Profile and then using the Analyze Inspect Code functionality is the recommended way of running Sensei recipes in bulk across a project.

Running an Inspection Profile from the Command Line

IntelliJ has the ability to run inspections from the command line as documented by JetBrains:

- https://www.jetbrains.com/help/idea/working-with-the-ide-features-from-command-line.html

I primarily use macOS, and can run a single instance of IntelliJ from the command line with:

open -na "IntelliJ IDEA CE.app"

To support easier execution I add this to a shell command script.

vi /usr/local/bin/idea

The contents of the script are from the official documentation provided by IntelliJ.

#!/bin/sh
open -na "IntelliJ IDEA CE.app" --args "$@"

I then made this executable to allow me to simplify the command line inspection process.

chmod 755 /usr/local/bin/idea

The official intellij docs describe the general form of the inspection command as:

idea inspect <project> <inspection-profile> <output></output></inspection-profile></project>
[<options>]</options>

In practice, I fully qualify the paths and don’t need any options:

idea inspect /Users/user/GitHub/sensei-blog-examples /Users/user/GitHub/sensei-blog-examples/.idea/inspectionProfiles/senseiprofile.xml /Users/user/GitHub/sensei-blog-examples/scan-results

This runs all the Inspections I added to the `senseiprofile` and reports the results in the `scan-results` folder.

Viewing Inspection Results

We can report these results from within Continuous Integration, as we’ll see later.

We can also view them within IntelliJ itself using the `Analyse \ View Offline Inspection Results…` feature.

This will load the results into the `Inspection Results` tab.

This is officially documented on the JetBrains site:

- https://www.jetbrains.com/help/idea/command-line-code-inspector.html#inspection-results

This might be used during a code review process if the command line execution was incorporated into a Continuous Integration process and the reviewers wanted to check the full source context of any of the Inspection result entries.

Inspection Profiles in Continuous Integration

When adding the Command Line inspection into Continuous Integration we ideally want a report to be generated automatically and there are a number of options open to us.

TeamCity offers out of the box support for Inspection Profiles in Continuous Integration.

- https://www.jetbrains.com/help/teamcity/inspections.html

The Jenkins Warnings NG plugin supports the Command Line output from IntelliJ Inspections as one of the report formats.

- https://github.com/jenkinsci/warnings-ng-plugin

- https://github.com/jenkinsci/warnings-ng-plugin/blob/master/SUPPORTED-FORMATS.md

Community projects like `idea CLI Inspector` exist to support using Inspection Profiles in other CI tooling i.e.

- https://github.com/bentolor/idea-cli-inspector

The future of Inspection Profiles in a CI process looks even brighter with the introduction of the JetBrains Qodana project. The Qodana project is a headless version of IntelliJ with official Github Actions and Docker images.

- https://github.com/JetBrains/Qodana

Qodana is currently in beta, but the Sensei team is monitoring it so that it becomes an officially supported platform for running Sensei rules as part of Continuous Integration.

Summary

Intention Actions allow us to reinforce coding patterns and quickly fix them in the IDE when we make mistakes during coding.

Inspection Profiles allow us to collect these into profiles which can run in batch as an Analyze and Inspect Code action. This can be useful if we encounter a pattern and want to double-check if we have missed that anywhere else in our code.

Inspection Profiles can be run from the command line and even incorporated into Continuous Integration processes supporting a “trust, but verify” model and catch any accidental slippage.

All of the above is built in IntelliJ functionality and JetBrains are improving their Continuous Integration process with the introduction of Qodana.

Sensei recipes are loaded into IntelliJ to act as native Intention Actions and be collected into Inspection Profiles to support batch checking through Inspect Code and Continuous Integration support provided by the official JetBrains Command Line execution functionality.

---

You can install Sensei from within IntelliJ using "Preferences \ Plugins" (Mac) or "Settings \ Plugins" (Windows) then just search for “sensei secure code”.

If you want to try running a project in IntelliJ from the command line then the project used in this post can be found in the `sensei-blog-examples` repository in the Secure Code Warrior GitHub account. An exercise to the reader is to create a profile that will run just the Sensei rules. Give it a try:

https://github.com/securecodewarrior/sensei-blog-examples

Learn more about Sensei