- Rule doc options lists

- [Scripts](#scripts)

- [Update `README.md`](#update-readmemd)

- [Update rule docs](#update-rule-docs)

- [Configure linting](#configure-linting)

- [Rule doc options lists](#rule-doc-options-lists)

Optionally, add these marker comments to your `README.md` in a `## Configs` section or similar location (uses the `description` property exported by each config if available):

Optionally, add these marker comments to your rule docs in an `## Options` section or similar location:

<!-- begin auto-generated rule options list -->

<!-- end auto-generated rule options list -->

Note that rule option lists are subject-to-change as we add support for more kinds and properties of schemas. To fully take advantage of them, you'll want to ensure your rules have the `meta.schema` property fleshed out with properties like `description`, `type`, `enum`, `default`, `required`, `deprecated`.

- [eslint-plugin/require-meta-schema](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/main/docs/rules/require-meta-schema.md) to ensure your rules have schemas for use in determining options

See the generated rule doc options lists in our example rule doc [`no-foo.md`](./docs/examples/eslint-plugin-test/docs/rules/no-foo.md).

| Name | Description | Type | Choices | Default | Required | Deprecated |

| :---- | :---------------------------- | :------ | :---------------- | :------- | :------- | :--------- |

| `bar` | Choose how to use the rule. | String | `always`, `never` | `always` | Yes | |

| `foo` | Enable some kind of behavior. | Boolean | | `false` | | Yes |

For the purpose of this example, below is the `meta.schema` that would generate the above rule options table:

[{

"type": "object",

"properties": {

"foo": {

"type": "boolean",

"description": "Enable some kind of behavior.",

"deprecated": true,

"default": false

},

"bar": {

"description": "Choose how to use the rule.",

"type": "string",

"enum": ["always", "never"],

"default": "always"

}

},

"required": ["bar"],

"additionalProperties": false

}]

export const BEGIN_RULE_OPTIONS_LIST_MARKER =

'<!-- begin auto-generated rule options list -->';

export const END_RULE_OPTIONS_LIST_MARKER =

'<!-- end auto-generated rule options list -->';

import { updateRuleOptionsList } from './rule-options-list.js';

updateRuleOptionsList(

replaceOrCreateHeader(contents, newHeaderLines, END_RULE_HEADER_MARKER),

rule

),

for (const { name: namedOption } of getAllNamedOptions(schema)) {

import {

BEGIN_RULE_OPTIONS_LIST_MARKER,

END_RULE_OPTIONS_LIST_MARKER,

} from './comment-markers.js';

import { markdownTable } from 'markdown-table';

import type { RuleModule } from './types.js';

import { RuleOption, getAllNamedOptions } from './rule-options.js';

import { capitalizeOnlyFirstLetter } from './string.js';

export enum COLUMN_TYPE {

// Alphabetical order.

DEFAULT = 'default',

DEPRECATED = 'deprecated',

DESCRIPTION = 'description',

ENUM = 'enum',

NAME = 'name',

REQUIRED = 'required',

TYPE = 'type',

const HEADERS: {

[key in COLUMN_TYPE]: string;

} = {

// Alphabetical order.

[COLUMN_TYPE.DEFAULT]: 'Default',

[COLUMN_TYPE.DEPRECATED]: 'Deprecated',

[COLUMN_TYPE.DESCRIPTION]: 'Description',

[COLUMN_TYPE.ENUM]: 'Choices',

[COLUMN_TYPE.NAME]: 'Name',

[COLUMN_TYPE.REQUIRED]: 'Required',

[COLUMN_TYPE.TYPE]: 'Type',

const COLUMN_TYPE_DEFAULT_PRESENCE_AND_ORDERING: {

[key in COLUMN_TYPE]: boolean;

} = {

// Object keys ordered in display order.

// Object values indicate whether the column is displayed by default.

[COLUMN_TYPE.NAME]: true,

[COLUMN_TYPE.DESCRIPTION]: true,

[COLUMN_TYPE.TYPE]: true,

[COLUMN_TYPE.ENUM]: true,

[COLUMN_TYPE.DEFAULT]: true,

[COLUMN_TYPE.REQUIRED]: true,

[COLUMN_TYPE.DEPRECATED]: true,

function ruleOptionToColumnValues(ruleOption: RuleOption): {

[key in COLUMN_TYPE]: string | undefined;

} {

const columns: {

[key in COLUMN_TYPE]: string | undefined;

} = {

// Alphabetical order.

[COLUMN_TYPE.DEFAULT]:

ruleOption.default === undefined

? undefined

: `\`${String(ruleOption.default)}\``,

[COLUMN_TYPE.DEPRECATED]: ruleOption.deprecated ? 'Yes' : undefined,

[COLUMN_TYPE.DESCRIPTION]: ruleOption.description,

[COLUMN_TYPE.ENUM]:

ruleOption.enum && ruleOption.enum.length > 0

? `\`${ruleOption.enum.join('`, `')}\``

: undefined,

[COLUMN_TYPE.NAME]: `\`${ruleOption.name}\``,

[COLUMN_TYPE.REQUIRED]: ruleOption.required ? 'Yes' : undefined,

[COLUMN_TYPE.TYPE]: ruleOption.type

? capitalizeOnlyFirstLetter(ruleOption.type)

: undefined,

};

return columns;

function ruleOptionsToColumnsToDisplay(ruleOptions: readonly RuleOption[]): {

[key in COLUMN_TYPE]: boolean;

} {

const columnsToDisplay: {

[key in COLUMN_TYPE]: boolean;

} = {

// Alphabetical order.

[COLUMN_TYPE.DEFAULT]: ruleOptions.some((ruleOption) => ruleOption.default),

[COLUMN_TYPE.DEPRECATED]: ruleOptions.some(

(ruleOption) => ruleOption.deprecated

),

[COLUMN_TYPE.DESCRIPTION]: ruleOptions.some(

(ruleOption) => ruleOption.description

),

[COLUMN_TYPE.ENUM]: ruleOptions.some((ruleOption) => ruleOption.enum),

[COLUMN_TYPE.NAME]: true,

[COLUMN_TYPE.REQUIRED]: ruleOptions.some(

(ruleOption) => ruleOption.required

),

[COLUMN_TYPE.TYPE]: ruleOptions.some((ruleOption) => ruleOption.type),

};

return columnsToDisplay;

function generateRuleOptionsListMarkdown(rule: RuleModule): string {

const ruleOptions = getAllNamedOptions(rule.meta.schema);

if (ruleOptions.length === 0) {

return '';

}

const columnsToDisplay = ruleOptionsToColumnsToDisplay(ruleOptions);

const listHeaderRow = Object.keys(COLUMN_TYPE_DEFAULT_PRESENCE_AND_ORDERING)

.filter((type) => columnsToDisplay[type as COLUMN_TYPE])

.map((type) => HEADERS[type as COLUMN_TYPE]);

const rows = [...ruleOptions]

.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()))

.map((ruleOption) => {

const ruleOptionColumnValues = ruleOptionToColumnValues(ruleOption);

// Recreate object using correct ordering and presence of columns.

return Object.keys(COLUMN_TYPE_DEFAULT_PRESENCE_AND_ORDERING)

.filter((type) => columnsToDisplay[type as COLUMN_TYPE])

.map((type) => ruleOptionColumnValues[type as COLUMN_TYPE]);

});

return markdownTable(

[listHeaderRow, ...rows],

{ align: 'l' } // Left-align headers.

);

export function updateRuleOptionsList(

markdown: string,

rule: RuleModule

): string {

const listStartIndex = markdown.indexOf(BEGIN_RULE_OPTIONS_LIST_MARKER);

let listEndIndex = markdown.indexOf(END_RULE_OPTIONS_LIST_MARKER);

if (listStartIndex === -1 || listEndIndex === -1) {

// No rule options list found.

return markdown;

}

// Account for length of pre-existing marker.

listEndIndex += END_RULE_OPTIONS_LIST_MARKER.length;

const preList = markdown.slice(0, Math.max(0, listStartIndex));

const postList = markdown.slice(Math.max(0, listEndIndex));

// New rule options list.

const list = generateRuleOptionsListMarkdown(rule);

return `${preList}${BEGIN_RULE_OPTIONS_LIST_MARKER}\n\n${list}\n\n${END_RULE_OPTIONS_LIST_MARKER}${postList}`;

export type RuleOption = {

name: string;

type?: string;

description?: string;

required?: boolean;

enum?: readonly JSONSchema.JSONSchema4Type[];

default?: JSONSchema.JSONSchema4Type;

deprecated?: boolean;

jsonSchema:

| JSONSchema.JSONSchema4

| readonly JSONSchema.JSONSchema4[]

| undefined

| null

): readonly RuleOption[] {

const options: RuleOption[] = [];

options.push(

...Object.entries(js.properties).map(([key, value]) => ({

name: key,

type: value.type ? value.type.toString() : undefined,

description: value.description,

default: value.default,

enum: value.enum,

required:

typeof value.required === 'boolean'

? value.required

: Array.isArray(js.required) && js.required.includes(key),

deprecated: value.deprecated, // eslint-disable-line @typescript-eslint/no-unsafe-assignment -- property exists on future JSONSchema version but we can let it be used anyway.

}))

);

export function hasOptions(

jsonSchema: JSONSchema.JSONSchema4 | readonly JSONSchema.JSONSchema4[]

): boolean {