Docs

Author: Bencodes

README.md

@@ -8,7 +8,7 @@ for the [Bazel build system](https://bazel.build).
 - configuration and baseline files;
 - HTML, text, XML, Markdown, and SARIF reports;
 - [plugins](https://detekt.dev/docs/extensions/extensions/);
-- customizable Detekt version;
+- customizable Detekt version and JVM flags;
 - [persistent workers](https://blog.bazel.build/2015/12/10/java-workers.html) support;
 - baseline generation via `detekt_create_baseline`;
 - configuration options via [attributes](docs/attrs.md).
@@ -147,11 +147,17 @@ detekt_test(
 
 ### Configuration Options
 
-All three rules share the same configuration options. In addition to `srcs`, `cfgs`, `baseline`, `plugins`,
-and report options, most attributes correspond directly to Detekt CLI flags and pass them through when explicitly set.
+All three rules share the same configuration options. In addition to `srcs`, most attributes correspond directly to
+Detekt CLI flags and pass them through when explicitly set.
 
-`max_issues` is retained for Detekt 1.x. Detekt 2.x uses `fail_on_severity` (`Never`, `Info`, `Warning`, or `Error`);
-the attributes are mutually exclusive and must match the selected Detekt major version.
+`cfgs`, `plugins`, `build_upon_default_config`, `disable_default_rulesets`, `jvm_target`, `language_version`,
+`max_issues`, `fail_on_severity`, `parallel`, JVM flags, and the executable wrapper can be configured once on a
+toolchain. `srcs`, `deps`, `baseline`, `excludes`, `includes`, `all_rules`, `auto_correct`, `base_path`, `config_resource`,
+`is_android`, and report options remain rule-level settings.
+
+`max_issues` is the failure policy for Detekt 1.x. Detekt 2.x uses `fail_on_severity` (`Never`, `Info`, `Warning`, or
+`Error`). Both policies cannot be active at the same level; inactive clear values such as `max_issues = -1` may
+coexist with the other policy. Choose the active option that matches the selected Detekt major version.
 
 More information can be found in the [attributes](docs/attrs.md).
 
@@ -212,41 +218,89 @@ use_repo(detekt, "detekt_cli_all")
 
 Each template may contain `{version}` which will be replaced with the version string.
 
-### Toolchain Defaults
+### Toolchain Configuration and Profiles
+
+`detekt_toolchain` defines a reusable implementation profile. Its JVM flags, executable wrapper, shared configuration,
+plugins, and shared analysis defaults are used by rules that select the profile. The default JVM flags remain
+`-Xms16m` and `-Xmx128m`, and the default JVM target remains `1.8`.
 
-`cfgs`, `plugins`, `build_upon_default_config`, `disable_default_rulesets`, `jvm_target`,
-`language_version`, `max_issues`, and `parallel` can be set once on a custom
-`detekt_toolchain`. Target attributes use those values when left at their rule defaults:
+The `detekt_toolchain` rule is the implementation label used by a rule; it is not the native `toolchain()` registration
+wrapper. Register one implementation when you want it to be the fallback for rules that do not select a profile:
 
 ```python
+load("@rules_detekt//detekt:defs.bzl", "detekt_test")
 load("@rules_detekt//detekt:toolchain.bzl", "detekt_toolchain")
 
 detekt_toolchain(
-    name = "detekt_toolchain_impl",
+    name = "detekt_default_impl",
+    jvm_flags = ["-Xms16m", "-Xmx512m"],
     cfgs = ["//:detekt.yml"],
-    plugins = ["@maven//:io_gitlab_arturbosch_detekt_detekt_formatting"],
+    plugins = ["@maven//:dev_detekt_detekt_rules_ktlint_wrapper"],
     build_upon_default_config = True,
     disable_default_rulesets = True,
     jvm_target = "11",
     language_version = "2.0",
-    max_issues = 0,
+    fail_on_severity = "Error",
     parallel = True,
 )
 
 toolchain(
-    name = "detekt_toolchain",
-    toolchain = ":detekt_toolchain_impl",
+    name = "detekt_registered",
+    toolchain = ":detekt_default_impl",
     toolchain_type = "@rules_detekt//detekt:toolchain_type",
 )
+
+detekt_test(
+    name = "uses_registered_profile",
+    srcs = glob(["src/main/kotlin/**/*.kt"]),
+)
 ```
 
 ```python
-register_toolchains("//tools:detekt_toolchain")
+register_toolchains("//:detekt_registered")
 ```
 
-At the target level, set `cfgs`, `plugins`, `build_upon_default_config`,
-`disable_default_rulesets`, `jvm_target`, `language_version`, `max_issues`, or
-`parallel = True` to use a target-specific value.
+Multiple profiles can coexist in one repository. Select an implementation directly with the rule’s
+`detekt_toolchain` attribute; omitting that attribute uses the registered native toolchain:
+
+```python
+detekt_toolchain(
+    name = "detekt_strict_impl",
+    fail_on_severity = "Error",
+)
+
+detekt_toolchain(
+    name = "detekt_lenient_impl",
+    fail_on_severity = "Never",
+)
+
+detekt_test(
+    name = "strict_profile",
+    srcs = glob(["src/main/kotlin/**/*.kt"]),
+    detekt_toolchain = ":detekt_strict_impl",
+)
+
+detekt_test(
+    name = "lenient_profile",
+    srcs = glob(["src/main/kotlin/**/*.kt"]),
+    detekt_toolchain = ":detekt_lenient_impl",
+    fail_on_severity = "Warning",
+)
+```
+
+Profiles configure the selected runtime; they do not select a Detekt version. To use the supported Detekt 1.23.8
+override, configure that version separately and use its matching 1.x plugins and `max_issues` policy.
+
+For shared options, an omitted rule attribute (or `None` where accepted) inherits from the selected toolchain.
+Explicit values always win: `False`, `[]`, an empty `language_version`, or `max_issues = -1` clears an inherited
+value; list-valued options replace the toolchain list rather than append to it. A rule-level failure option replaces
+the inherited failure-policy pair, so a rule can select either `max_issues` or `fail_on_severity` without inheriting
+the other option. Both policies cannot be active at the same level; inactive clear values may coexist with the other
+policy.
+
+The profile’s runtime determines which failure policy is valid: use `max_issues` with Detekt 1.23.8 and
+`fail_on_severity` with Detekt 2.0.0-alpha.6. JVM and Kotlin language versions are also validated by the selected
+runtime, and plugins must be built for the same Detekt major version.
 
 ### Plugins
 

detekt/defs.bzl

@@ -4,7 +4,22 @@ Rule declarations.
 
 load("@rules_java//java:defs.bzl", "JavaInfo")
 
+_SHARED_ATTRS = [
+    "build_upon_default_config",
+    "cfgs",
+    "disable_default_rulesets",
+    "fail_on_severity",
+    "jvm_target",
+    "language_version",
+    "max_issues",
+    "parallel",
+    "plugins",
+]
+
 _ATTRS = {
+    "detekt_explicit_attrs": attr.string_list(
+        default = [],
+    ),
     "_result_script_template": attr.label(
         default = Label("//detekt:result_script.sh.tpl"),
         allow_single_file = True,
@@ -18,12 +33,12 @@ _ATTRS = {
     "plugins": attr.label_list(
         default = [],
         providers = [JavaInfo],
-        doc = "Extra paths to plugin jars.",
+        doc = "Extra paths to plugin jars. If omitted, inherits from the detekt toolchain; an explicit empty list clears toolchain plugins.",
     ),
     "cfgs": attr.label_list(
         default = [],
         allow_files = [".yml"],
-        doc = "Path to the config file (path/to/config.yml). Multiple configuration files can be specified.",
+        doc = "Path to the config file (path/to/config.yml). Multiple configuration files can be specified. If omitted, inherits from the detekt toolchain; an explicit empty list clears toolchain configs.",
     ),
     "config_resource": attr.string(
         default = "",
@@ -48,11 +63,11 @@ _ATTRS = {
     ),
     "build_upon_default_config": attr.bool(
         default = False,
-        doc = "Preconfigures detekt with a bunch of rules and some opinionated defaults for you. Allows additional provided configurations to override the defaults.",
+        doc = "Preconfigures detekt with a bunch of rules and some opinionated defaults for you. If omitted, inherits from the detekt toolchain; explicit False clears the toolchain value.",
     ),
     "disable_default_rulesets": attr.bool(
         default = False,
-        doc = "Disables default rule sets.",
+        doc = "Disables default rule sets. If omitted, inherits from the detekt toolchain; explicit False clears the toolchain value.",
     ),
     "excludes": attr.string_list(
         default = [],
@@ -64,35 +79,35 @@ _ATTRS = {
     ),
     "jvm_target": attr.string(
         default = "",
-        doc = "EXPERIMENTAL: Target version of the generated JVM bytecode that was generated during compilation and is now being used for type resolution (1.8, 9, 10, ..., 26). The selected Detekt version validates this value.",
+        doc = "EXPERIMENTAL: Target version of the generated JVM bytecode that was generated during compilation and is now being used for type resolution (1.8, 9, 10, ..., 26). If omitted, inherits from the detekt toolchain; explicit values, including empty string, replace it. The selected Detekt version validates this value.",
     ),
     "language_version": attr.string(
         default = "",
-        doc = "EXPERIMENTAL: Compatibility mode for Kotlin language version X.Y, reports errors for all language features that came out later. The selected Detekt version validates this value.",
+        doc = "EXPERIMENTAL: Compatibility mode for Kotlin language version X.Y, reports errors for all language features that came out later. If omitted, inherits from the detekt toolchain; explicit values, including empty string, replace it. The selected Detekt version validates this value.",
     ),
     "max_issues": attr.int(
         default = -1,
-        doc = "Passes only when found issues count does not exceed specified issues count. Negative values inherit from the detekt toolchain.",
+        doc = "Detekt 1.x failure threshold: passes only when the found issue count does not exceed this value. If omitted, inherits from the detekt toolchain; explicit -1 clears it. Mutually exclusive with fail_on_severity.",
     ),
     "fail_on_severity": attr.string(
         default = "",
-        doc = "Detekt 2.x failure threshold (Error, Warning, Info, or Never). Mutually exclusive with max_issues.",
+        doc = "Detekt 2.x failure threshold (Error, Warning, Info, or Never). If omitted, inherits from the detekt toolchain; explicit empty string clears it. Mutually exclusive with max_issues.",
     ),
     "parallel": attr.bool(
         default = False,
-        doc = "Enables parallel compilation and analysis of source files. Defaults to the detekt toolchain value.",
+        doc = "Enables parallel compilation and analysis of source files. If omitted, inherits from the detekt toolchain; explicit False clears the toolchain value.",
     ),
     "txt_report": attr.bool(
         default = False,
-        doc = "Enables / disables the text report generation. The report file name is `{target_name}_detekt_report.txt`.",
+        doc = "Enables / disables the text report generation. The report file name is `{target_name}_detekt_report.txt`; Detekt 2.x uses captured console output for this artifact.",
     ),
     "html_report": attr.bool(
         default = False,
         doc = "Enables / disables the HTML report generation. The report file name is `{target_name}_detekt_report.html`.",
     ),
     "xml_report": attr.bool(
         default = False,
-        doc = "Enables / disables the XML report generation. The report file name is `{target_name}_detekt_report.xml`. FYI Detekt uses the Checkstyle XML reporting format which makes it compatible with tools like SonarQube.",
+        doc = "Enables / disables the XML report generation. The report file name is `{target_name}_detekt_report.xml`. Detekt 2.x maps this output to its `checkstyle` report ID; the format is compatible with tools like SonarQube.",
     ),
     "md_report": attr.bool(
         default = False,
@@ -111,19 +126,36 @@ _ATTRS = {
         doc = "Whether detekt target corresponds to android kotlin library or regular jvm library",
         default = False,
     ),
+    "detekt_toolchain": attr.label(
+        default = None,
+        cfg = "exec",
+        providers = [platform_common.ToolchainInfo],
+        doc = "Optional label of a target providing platform_common.ToolchainInfo. If omitted, uses the registered detekt toolchain.",
+    ),
 }
 
+# Stardoc can consume this schema without exposing the implementation rules.
+DETEKT_ATTRIBUTES = _ATTRS
+
 TOOLCHAIN_TYPE = Label("//detekt:toolchain_type")
 ANDROID_SDK_TOOLCHAIN_TYPE = Label("@rules_android//toolchains/android_sdk:toolchain_type")
 JDK_TOOLCHAIN_TYPE = Label("@bazel_tools//tools/jdk:toolchain_type")
 
+def _uses_rule_attr(ctx, name):
+    return name in ctx.attr.detekt_explicit_attrs
+
+def _detekt_toolchain(ctx):
+    if ctx.attr.detekt_toolchain != None:
+        return ctx.attr.detekt_toolchain[platform_common.ToolchainInfo]
+    return ctx.toolchains[TOOLCHAIN_TYPE]
+
 def _impl(
         ctx,
         run_as_test_target = False,
         create_baseline = False):
     action_inputs = []
     action_outputs = []
-    detekt_toolchain = ctx.toolchains[TOOLCHAIN_TYPE]
+    detekt_toolchain = _detekt_toolchain(ctx)
 
     java_arguments = ctx.actions.args()
 
@@ -144,7 +176,7 @@ def _impl(
     action_inputs.extend(ctx.files.srcs)
     detekt_arguments.add_joined("--input", ctx.files.srcs, join_with = ",")
 
-    cfgs = ctx.files.cfgs or detekt_toolchain.cfgs
+    cfgs = ctx.files.cfgs if _uses_rule_attr(ctx, "cfgs") else detekt_toolchain.cfgs
     action_inputs.extend(cfgs)
     detekt_arguments.add_joined("--config", cfgs, join_with = ",")
 
@@ -184,11 +216,11 @@ def _impl(
     if ctx.attr.base_path:
         detekt_arguments.add("--base-path", ctx.attr.base_path)
 
-    build_upon_default_config = ctx.attr.build_upon_default_config or detekt_toolchain.build_upon_default_config
+    build_upon_default_config = ctx.attr.build_upon_default_config if _uses_rule_attr(ctx, "build_upon_default_config") else detekt_toolchain.build_upon_default_config
     if build_upon_default_config:
         detekt_arguments.add("--build-upon-default-config")
 
-    disable_default_rulesets = ctx.attr.disable_default_rulesets or detekt_toolchain.disable_default_rulesets
+    disable_default_rulesets = ctx.attr.disable_default_rulesets if _uses_rule_attr(ctx, "disable_default_rulesets") else detekt_toolchain.disable_default_rulesets
     if disable_default_rulesets:
         detekt_arguments.add("--disable-default-rulesets")
 
@@ -198,23 +230,30 @@ def _impl(
     if ctx.attr.includes:
         detekt_arguments.add_joined("--includes", ctx.attr.includes, join_with = ",")
 
-    jvm_target = ctx.attr.jvm_target or detekt_toolchain.jvm_target
-    detekt_arguments.add("--jvm-target", jvm_target)
+    jvm_target = ctx.attr.jvm_target if _uses_rule_attr(ctx, "jvm_target") else detekt_toolchain.jvm_target
+    if jvm_target:
+        detekt_arguments.add("--jvm-target", jvm_target)
 
-    language_version = ctx.attr.language_version or detekt_toolchain.language_version
+    language_version = ctx.attr.language_version if _uses_rule_attr(ctx, "language_version") else detekt_toolchain.language_version
     if language_version:
         detekt_arguments.add("--language-version", language_version)
 
-    max_issues = ctx.attr.max_issues if ctx.attr.max_issues >= 0 else detekt_toolchain.max_issues
+    rule_policy = _uses_rule_attr(ctx, "max_issues") or _uses_rule_attr(ctx, "fail_on_severity")
+    max_issues = ctx.attr.max_issues if _uses_rule_attr(ctx, "max_issues") else -1
+    fail_on_severity = ctx.attr.fail_on_severity if _uses_rule_attr(ctx, "fail_on_severity") else ""
+    if not rule_policy:
+        max_issues = detekt_toolchain.max_issues
+        fail_on_severity = detekt_toolchain.fail_on_severity
+
     if max_issues >= 0:
-        if ctx.attr.fail_on_severity:
+        if fail_on_severity:
             fail("max_issues and fail_on_severity cannot be used together")
         detekt_arguments.add("--max-issues", max_issues)
 
-    if ctx.attr.fail_on_severity:
-        detekt_arguments.add("--fail-on-severity", ctx.attr.fail_on_severity)
+    if fail_on_severity:
+        detekt_arguments.add("--fail-on-severity", fail_on_severity)
 
-    parallel = ctx.attr.parallel or detekt_toolchain.parallel
+    parallel = ctx.attr.parallel if _uses_rule_attr(ctx, "parallel") else detekt_toolchain.parallel
     if parallel:
         detekt_arguments.add("--parallel")
 
@@ -231,7 +270,7 @@ def _impl(
         action_inputs.extend(platform_jar_files + classpath)
         detekt_arguments.add("--classpath", ctx.configuration.host_path_separator.join([f.path for f in platform_jar_files] + [f.path for f in classpath]))
 
-    plugins = ctx.files.plugins or detekt_toolchain.plugins
+    plugins = ctx.files.plugins if _uses_rule_attr(ctx, "plugins") else detekt_toolchain.plugins
     plugin_jars = [plugin for plugin in plugins if plugin.extension == "jar"]
     action_inputs.extend(plugin_jars)
     detekt_arguments.add_joined("--plugins", plugin_jars, join_with = ",")
@@ -312,25 +351,46 @@ def _detekt_create_baseline_impl(ctx):
 def _detekt_test_impl(ctx):
     return _impl(ctx = ctx, run_as_test_target = True)
 
-detekt = rule(
+_detekt_rule = rule(
     implementation = _detekt_impl,
     attrs = _ATTRS,
     provides = [DefaultInfo],
     toolchains = [TOOLCHAIN_TYPE, ANDROID_SDK_TOOLCHAIN_TYPE, JDK_TOOLCHAIN_TYPE],
 )
 
-detekt_create_baseline = rule(
+_detekt_create_baseline_rule = rule(
     implementation = _detekt_create_baseline_impl,
     attrs = _ATTRS,
     provides = [DefaultInfo],
     toolchains = [TOOLCHAIN_TYPE, ANDROID_SDK_TOOLCHAIN_TYPE, JDK_TOOLCHAIN_TYPE],
     executable = True,
 )
 
-detekt_test = rule(
+_detekt_test = rule(
     implementation = _detekt_test_impl,
     attrs = _ATTRS,
     provides = [DefaultInfo],
     toolchains = [TOOLCHAIN_TYPE, ANDROID_SDK_TOOLCHAIN_TYPE, JDK_TOOLCHAIN_TYPE],
     test = True,
 )
+
+def _declare(native_rule, name, kwargs):
+    attrs = dict(kwargs)
+    attrs["detekt_explicit_attrs"] = [
+        attr_name
+        for attr_name in _SHARED_ATTRS
+        if attr_name in kwargs and kwargs[attr_name] != None
+    ]
+    native_rule(name = name, **attrs)
+
+def detekt(name, **kwargs):
+    """Run Detekt analysis for the supplied Kotlin sources."""
+    _declare(_detekt_rule, name, kwargs)
+
+def detekt_create_baseline(name, **kwargs):
+    """Create a Detekt baseline for the supplied Kotlin sources."""
+    _declare(_detekt_create_baseline_rule, name, kwargs)
+
+def detekt_test(name, **kwargs):
+    """Run Detekt analysis as a test for the supplied Kotlin sources."""
+    _declare(_detekt_test, name, kwargs)