// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[codenarc_plugin]]
= The CodeNarc Plugin

The CodeNarc plugin performs quality checks on your project's Groovy source files using https://codenarc.org/[CodeNarc] and generates reports from these checks.

[[sec:codenarc_usage]]
== Usage

To use the CodeNarc plugin, include the following in your build script:

====
include::sample[dir="snippets/reference/core-plugins/codeQuality/kotlin",files="build.gradle.kts[tags=use-codenarc-plugin]"]
include::sample[dir="snippets/reference/core-plugins/codeQuality/groovy",files="build.gradle[tags=use-codenarc-plugin]"]
====

The plugin adds a number of tasks to the project that perform the quality checks when used with the <<groovy_plugin.adoc#groovy_plugin, Groovy Plugin>>. You can execute the checks by running `gradle check`.

[[sec:codenarc_tasks]]
== Tasks

The CodeNarc plugin adds the following tasks to the project:

`codenarcMain` — link:{groovyDslPath}/org.gradle.api.plugins.quality.CodeNarc.html[CodeNarc]::
+
Runs CodeNarc against the production Groovy source files.

`codenarcTest` — link:{groovyDslPath}/org.gradle.api.plugins.quality.CodeNarc.html[CodeNarc]::
+
Runs CodeNarc against the test Groovy source files.

`codenarc__SourceSet__` — link:{groovyDslPath}/org.gradle.api.plugins.quality.CodeNarc.html[CodeNarc]::
+
Runs CodeNarc against the given source set's Groovy source files.

[[sec:codenarc_dependencies_added_to_other_tasks]]
=== Dependencies added to other tasks

The CodeNarc plugin adds the following dependencies to tasks defined by the Groovy plugin.

`check`::
_Depends on_: All CodeNarc tasks, including `codenarcMain` and `codenarcTest`.

[[sec:codenarc_project_layout]]
== Project layout

The CodeNarc plugin expects the following project layout:

[source,text]
----
<root>
└── config
    └── codenarc           // <1>
        └── codenarc.xml   // <2>
----
<1> CodeNarc configuration files go here
<2> Primary CodeNarc configuration file

NOTE: The default configuration file is resolved relative to the _root_ project directory, so a single `config/codenarc/codenarc.xml` is shared by all projects in the build unless the `config` property is overridden.

[[sec:codenarc_dependency_management]]
== Dependency management

The CodeNarc plugin adds the following dependency configurations:

.CodeNarc plugin - dependency configurations
[cols="a,a", options="header"]
|===
| Name
| Meaning

| `codenarc`
| The CodeNarc libraries to use
|===

[NOTE]
====
If CodeNarc requires a different Groovy version than that used to compile Groovy source, you can supply one using the `codenarc` configuration.
====

====
include::sample[dir="snippets/reference/core-plugins/codeQuality/kotlin",files="build.gradle.kts[tags=specify-groovy-version]"]
include::sample[dir="snippets/reference/core-plugins/codeQuality/groovy",files="build.gradle[tags=specify-groovy-version]"]
====

[[sec:codenarc_configuration]]
== Configuration

The CodeNarc plugin is configured through the link:{groovyDslPath}/org.gradle.api.plugins.quality.CodeNarcExtension.html[CodeNarcExtension] (the `codenarc {}` block). The most commonly used properties and their default values are:

.Gradle defaults for CodeNarc properties
[%header%autowidth,compact]
|===
| Property | Description | Gradle default

| `toolVersion`
| The version of CodeNarc to use.
| `3.7.0-groovy-4.0`

| `config`
| The CodeNarc configuration to use.
| `config/codenarc/codenarc.xml` (relative to the root project)

| `reportFormat`
| The format of the generated report. One of `html`, `xml`, `text`, or `console`.
| `html`

| `maxPriority1Violations`
| The maximum number of priority 1 violations allowed before failing the build.
| `0`

| `maxPriority2Violations`
| The maximum number of priority 2 violations allowed before failing the build.
| `0`

| `maxPriority3Violations`
| The maximum number of priority 3 violations allowed before failing the build.
| `0`

| `reportsDirectory`
| The directory where reports are generated.
| `layout.buildDirectory.dir("reports/codenarc")`
|===

See the link:{groovyDslPath}/org.gradle.api.plugins.quality.CodeNarcExtension.html[CodeNarcExtension] class in the API documentation for the full set of options.
