CodeNarc - Developer Guide

Contents

• The codenarc Command-line Script
• New Rule Checklist
• Before You Submit a Pull Request or Patch
• Intellij IDEA Support

The codenarc Command-line Script

There is a codenarc.groovy command-line script in the root directory of the project. It is intended to streamline common development tasks. Currently, it supports a create-rule task for creating new CodeNarc rules.

codenarc create-rule

The create-rule task performs the following steps:

• Prompt for the rule name
• Prompt for the existing ruleset (category) name to which the rule is added
• Create a new rule class file in the proper package (under src/main/groovy)
• Create a new rule test class file (under src/test/groovy)
• Add placeholder description messages for the new rule to “codenarc-base-messages.properties”
• Add the new rule to the chosen ruleset XML file

RUNNING

On Unix/Mac, you can run the following from the project root directory:

  ./codenarc create-rule

On Windows, you can run:

  codenarc create-rule

(If Windows is not configured to automatically run *.groovy files, just can run groovy codenarc create-rule)

AFTER YOU RUN codenarc create-rule

After you run codenarc create-rule, finish up the rule implementation, including the following:

1. Edit the generated rule class and associated test class to add the proper implementation.
2. Modify the description messages for the new rule in “codenarc-base-messages.properties”. Move the message entries under the proper ruleset/category section within the file.
3. Add description to “codenarc-rules-[category].md” document in the “docs” folder.

New Rule Checklist

Perform the following steps when creating a new rule. See The codenarc Command-line Script. for information on the command-line script that automates a good bit of the boilerplate, as indicated below.

1. Implement the new Rule class. This is typically a subclass of AbstractAstVisitorRule. [1]
2. Implement the associated Rule test class. This is typically a subclass of AbstractRuleTestCase. [1]
3. Add the new rule class name to the appropriate RuleSet file under “src/main/resources/rulesets”. [1]
4. Add the new rule description entries to “src/main/resources/codenarc-base-messages.properties”. This includes both “RuleName.description” and “RuleName.description.html” property entries. [1]
5. Run LoadAllPredefinedRuleSetsTest.
6. Add a description of the new rule to “codenarc-rules-[category].md” document in the “docs” folder.

NOTES

• [1] These files are created (skeletons) or updated automatically if you run the codenarc create-rule script to create the rule. See The codenarc Command-line Script.

Before You Submit a Pull Request or Patch

Please do the following before submitting a pull request or patch:

• Run the full CodeNarc test suite. This includes a test called RunCodeNarcAgainstProjectSourceCodeTest that runs CodeNarc against its own source code (including any code that you have added or changed).

Intellij IDEA Support

To generate Intellij IDEA files, execute gradle idea