Customizing Code Health Rules with .codescene/code-health-rules.json

CodeScene lets you fine-tune its code health evaluation by customizing rules specific to your codebase. This is done through a version-controlled configuration file: .codescene/code-health-rules.json. Storing this file inside your Git repository ensures that your customized code health rules are applied consistently and remain in sync with the code they evaluate.

What is `.codescene/code-health-rules.json`?

The .codescene/code-health-rules.json file allows you to:

Disable or down-prioritize specific code health rules.
Override thresholds used in rule detection.
Apply custom rules only to specific parts of the codebase (e.g., test code vs. production code).
Define organization-wide rules through a designated global configuration repo.

You can obtain a ready-to-edit JSON template with documentation directly from the project’s configuration > Code Health section.

Getting Started with Custom Code Health Rules

To begin customizing your code health rules:

Download the Template
Go to your project’s Code Health configuration tab in CodeScene and download the pre-filled JSON template. This template includes all available rules, thresholds, and inline documentation.
Clean Up Unused Rules
Remove any rules you want to keep at their default settings. This keeps your configuration file clean and focused only on the changes you intend to make.
Disable a Rule
Set the weight to 0.0 to turn off a rule completely.
→ Example: Disabling "Large Method" will exclude it from code health scoring and reviews.
Down-Prioritize a Rule
Use a weight lower than 1.0 to reduce the impact of a rule while still tracking it.
→ Example: "Brain Method" with a weight of 0.5 means it counts as half as severe as the default.
Commit the File
Save your configuration as .codescene/code-health-rules.json in the root of your repository and commit it. CodeScene will pick it up automatically in the next analysis.

Customizing Rule Weights

Here's a minimal example of how to override rule weights in your repo:

{
  "usage" : "Persist this file inside your repositories as  ...",
  "rule_sets" : [ {
    "matching_content_path" : "test/**",
    "matching_content_path_doc" : "Specify a glob pattern relative to ...",
    "rules" : [ {
      "name" : "Brain Method",
      "weight" : 0.5
    }, {
      "name" : "Large Method",
      "weight" : 0.0
    } ]
  } ]
}

What This Example Does:

Brain Method still affects code health, but at 50% of its default impact.
Large Method is disabled, meaning it won't impact the code health score.

Tip: Remove rules you don’t want to override to keep your config file clean.

Targeting Specific Parts of Your Code

The matching_content_path field in the .codescene/code-health-rules.json file allows you to scope rule customizations to specific areas of your codebase. This is especially useful when different parts of your project (e.g., tests vs. production code) have different standards.

You define the scope using glob patterns, which match files and directories relative to the root of your repository.

Common Use Cases:

Test Code:
Apply relaxed rules to tests, where practices like larger methods or some duplication might be acceptable.
→ Example: "matching_content_path": "test/**"
Language-Specific Rules:
Apply certain rules only to files in a specific language.
→ Example: "matching_content_path": "**/*.js" for JavaScript files only.

Multiple Rule Sets Supported

You can define multiple rule_sets within the same configuration file, each targeting a different area of your codebase with its own customized rules and thresholds.

What Happens When Rules Are Disabled?

When a rule’s weight is set to 0.0, it becomes inactive. This means:

It no longer contributes to the code health score.
It is not shown in virtual code reviews.
It is excluded from delta analyses and PR quality gates.

To maintain visibility, CodeScene provides a searchable summary of all overridden rules in the Scope section of each analysis.

CodeScene presents a searchable summary of all overridden code health rules

Advanced: Override Low-Level Thresholds

Instead of fully disabling a rule, you can fine-tune the thresholds it uses. For example:

{
  "usage" : "Persist this file inside your repositories as  ...",
  "rule_sets" : [ {
    "matching_content_path" : "test/**",
    "matching_content_path_doc" : "Specify a glob pattern relative to ...",
    "rules" : [],
     "thresholds" : [ {
            "name" : "function_cyclomatic_complexity_warning",
            "value" : 10
        }, {
           "name" : "function_nesting_depth_warning",
            "value" : 3
        }
  } ]
}

These adjustments allow you to accept higher complexity or deeper nesting in specific contexts (e.g., test code) without compromising code health checks elsewhere.

Transparency: Overridden thresholds appear in the virtual code review so developers are aware of their impact.

Global Code Health Rules Across Repositories

For large organizations, it's common to apply a unified set of rules across all repositories in a project. CodeScene supports this by letting you specify one repository as the source of global rules.

To configure global rules:

Go to Project Configuration > Code Health.
In the Repository with global code health rules field, enter the name of the designated repository.
Ensure the repo is listed under General > Repositories.

Use the 'Repository with global code health rules' field in the Hotspots tab. Enter the repository name of the repository containing the rules.

Rule Precedence:

Local rules (.codescene/code-health-rules.json in each repo) – highest priority
Global rules – fallback if no local match
Default CodeScene rules – applied only when no customizations exist

Note: A full analysis is required for updated global rules to take effect in delta analyses.

Best Practices for Customization

Do not disable core rules unless you’re absolutely sure. Rules represent critical design issues; disabling them can hide early warning signs.
Use heuristics flexibly, especially when adapting CodeScene to suit your internal coding conventions.
Use PR integration to automatically detect and flag code health declines before they’re merged.

By tailoring your code health rules through .codescene/code-health-rules.json, you get precise control over how code quality is measured - on your terms. This ensures that CodeScene aligns closely with your team's goals, coding standards, and workflows.