rule-options

用途

本文档面向 SonarJS 的维护与开发工作，说明规则选项（rule options）如何在系统中流转与配置。它用于在 SonarJS 中新增或修改规则选项，处理 fields 数组、SonarQube UI 可见性以及 Java 检查类（Check Class）的配置。

架构概览

规则选项流经两条并行的路径：

SonarQube（HTTP/WebSocket）：

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

外部/gRPC：

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

SonarQube 发送带类型的值；gRPC 发送字符串键值对，需要做类型解析。

每个规则涉及的关键文件

rule.ts：ESLint 规则实现
meta.ts：implementation、eslintId、schema，并重新导出 fields
config.ts：fields 数组——选项的真相来源（source of truth）
generated-meta.ts：自动生成的 defaultOptions——请勿编辑

fields 数组（config.ts）

fields 数组定义用于 SonarQube 集成的选项和默认值。示例：

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

export const fields = [
  [
    // 外层数组 = 一个 ESLint 选项对象
    {
      field: 'max', // ESLint 选项名
      displayName: 'maximumFunctionParameters', // SonarQube 键（如果不同）
      description: 'Maximum authorized...', // SonarQube 可见性所必需
      default: 7, // 默认值；同时决定类型
    },
    {
      field: 'ignoreIIFE',
      default: false, // 无 description = 仅内部使用
    },
  ],
] as const satisfies ESLintConfiguration;

字段属性

field（必需）：ESLint/schema 键名
default（必需）：默认值；同时决定类型（number、string、boolean、array）
description（用于 SQ 可见性）：使选项在 SonarQube UI 中可见
displayName（可选）：当 SonarQube 键与 field 不同时使用
items（用于数组）：{ type: 'string' } 或 { type: 'integer' }
customDefault（可选）：为 SonarQube 使用与 ESLint 不同的默认值
fieldType（可选）：覆盖 SQ 字段类型（例如 'TEXT'）

让选项在 SonarQube 中可见

只有当字段带有 description 时，它才会出现在 SonarQube UI 中。没有 description 的字段是内部默认值，对用户不可见。

不在 SQ 可见的示例（无 description）：

// S109/config.ts — 在 SQ 中不可见（无 description）
export const fields = [
  [
    { field: 'ignore', default: [0, 1, -1, 24, 60] },
    { field: 'ignoreDefaultValues', default: true },
  ],
] as const satisfies ESLintConfiguration;

在 SQ 可见的示例（有 description）：

// S2068/config.ts — 在 SQ 中可见（有 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;

配置形态

对象式（最常见）：

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

原始值（单值）：

export const fields = [{ default: '^[a-z]+$' }] as const satisfies ESLintConfiguration;
// ESLint 收到：['^[a-z]+$']

数组选项（在 SQ 中以逗号分隔）：

export const fields = [
  [
    {
      field: 'passwordWords',
      items: { type: 'string' }, // Java 代码生成所必需
      description: 'Comma separated list...',
      default: ['password', 'pwd'],
    },
  ],
] as const satisfies ESLintConfiguration;
// SQ 发送："password,pwd,secret" → ESLint：[{ passwordWords: ['password','pwd','secret'] }]

类型解析（gRPC）

来自 gRPC 的字符串参数根据默认类型进行解析：

number："5" → 5
boolean："true" → true
string："pattern" → "pattern"
string[]："a,b,c" → ["a","b","c"]
number[]："1,2,3" → [1,2,3]

JSON Schema 与 fields 的对比

JSON Schema（meta.ts）：用于 ESLint 校验；ESLint 在运行时使用；对带选项的原始规则是必需的
fields（config.ts）：用于 SQ UI、默认值与键映射；由 Java 代码生成、meta 生成和 linter 使用；对所有带选项的规则都是必需的

对于原始规则，schema 与 fields 必须手动保持同步。对于装饰/外部规则，schema 继承自外部规则。

为已有规则添加选项

更新 config.ts —— 向 fields 数组添加字段
如需在 SonarQube 中可见，添加 description
更新 meta.ts schema（针对原始/装饰规则）
运行 npm run generate-meta —— 用新的 defaultOptions 更新 generated-meta.ts
运行 npm run generate-java-rule-classes —— 更新 Java 检查类
验证 Java 类具有正确的 configurations() 方法

Java 检查类（configurations()）

// 示例：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;

使用 MyRuleCheckTest.java 验证序列化：

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

键映射：SonarQube ↔ ESLint

当 SQ 与 ESLint 使用不同名称时：

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

transformers.ts 在运行时处理 SQ 键 → ESLint 键的映射。

适用场景与限制

适用于 SonarJS 规则选项的开发、修改与 SonarQube 集成维护场景。关于收费、价格、平台支持范围等信息，资料中暂未提供。