rule-options

Architecture Overview

Rule options flow through two parallel paths:

SonarQube (HTTP/WebSocket):

SonarQube UI → Java Check Class → configurations() → analyzeProject() → ESLint Linter

External/gRPC:

External Client → gRPC → transformers.ts → parseParamValue() → ESLint Linter

SonarQube sends typed values; gRPC sends string key-value pairs that need type parsing.

Key Files per Rule

The fields Array (config.ts)

The fields array defines options for SonarQube integration and default values.

import type { ESLintConfiguration } from '../helpers/configs.js';

export const fields = [
  [
    // outer array = one ESLint options object
    {
      field: 'max', // ESLint option name
      displayName: 'maximumFunctionParameters', // SonarQube key (if different)
      description: 'Maximum authorized...', // REQUIRED for SQ visibility
      default: 7, // default value; determines type
    },
    {
      field: 'ignoreIIFE',
      default: false, // no description = internal only
    },
  ],
] as const satisfies ESLintConfiguration;

Field Properties

Making Options Visible in SonarQube

A field appears in the SonarQube UI only if it has a description.

Fields without description are internal defaults invisible to users.

// S109/config.ts — NOT visible in SQ (no descriptions)
export const fields = [
  [
    { field: 'ignore', default: [0, 1, -1, 24, 60] },
    { field: 'ignoreDefaultValues', default: true },
  ],
] as const satisfies ESLintConfiguration;

// S2068/config.ts — VISIBLE in SQ (has description)
export const fields = [
  [
    {
      field: 'passwordWords',
      items: { type: 'string' },
      description: 'Comma separated list of words identifying potential passwords.',
      default: ['password', 'pwd', 'passwd', 'passphrase'],
    },
  ],
] as const satisfies ESLintConfiguration;

Configuration Shapes

Object-style (most common)

export const fields = [
  [
    { field: 'max', description: '...', default: 7 },
    { field: 'ignoreIIFE', description: '...', default: false },
  ],
] as const satisfies ESLintConfiguration;
// ESLint receives: [{ max: 7, ignoreIIFE: false }]

Primitive (single value)

export const fields = [{ default: '^[a-z]+
#x27; }] as const satisfies ESLintConfiguration;
// ESLint receives: ['^[a-z]+
#x27;]

Array options (comma-separated in SQ)

export const fields = [
  [
    {
      field: 'passwordWords',
      items: { type: 'string' }, // required for Java codegen
      description: 'Comma separated list...',
      default: ['password', 'pwd'],
    },
  ],
] as const satisfies ESLintConfiguration;
// SQ sends: "password,pwd,secret" → ESLint: [{ passwordWords: ['password','pwd','secret'] }]

Type Parsing (gRPC)

String params from gRPC are parsed based on default type:

JSON Schema vs fields

For original rules, schema and fields must be kept in sync manually. For decorated/external rules, schema is inherited from the external rule.

Adding Options to an Existing Rule

1. Update config.ts — add field to fields array
2. Add description if it should be visible in SonarQube
3. Update meta.ts schema (for original/decorated rules)
4. Run npm run generate-meta — updates generated-meta.ts with new defaultOptions
5. Run npm run generate-java-rule-classes — updates Java check classes
6. Verify Java class has correct configurations() method

Java Check Class (configurations())

// Example: S107Check.java
@Override
public List<Object> configurations() {
  return List.of(Map.of("max", maximum));
}

@RuleProperty(
  key = "maximumFunctionParameters",
  description = "Maximum authorized number of parameters",
  defaultValue = "" + DEFAULT_MAX
)
private int maximum = DEFAULT_MAX;

Use MyRuleCheckTest.java to verify serialization:

assertThat(new MyRuleCheck().configurations()).containsExactly(Map.of("max", 7));

Key Mapping: SonarQube ↔ ESLint

When SQ and ESLint use different names:

// config.ts
{ field: 'max', displayName: 'maximumFunctionParameters', ... }

transformers.ts handles the SQ key → ESLint key mapping at runtime.