Skip to content

fix(linter): Improve config option docs rendering for rules with enum configs#20018

Merged
connorshea merged 4 commits intooxc-project:mainfrom
connorshea:claude/fix-forbid-dom-props-docs-HPJBz
Mar 6, 2026
Merged

fix(linter): Improve config option docs rendering for rules with enum configs#20018
connorshea merged 4 commits intooxc-project:mainfrom
connorshea:claude/fix-forbid-dom-props-docs-HPJBz

Conversation

@connorshea
Copy link
Member

@connorshea connorshea commented Mar 5, 2026

Claude's summary:

  • Enhanced schema_markdown.rs to properly handle allOf schemas created by the RemoveRefSiblings visitor
  • When a $ref has sibling properties (like description), schemars' draft-07 visitor wraps it in an allOf
  • The renderer now resolves through allOf structures to find the actual referenced schema

This fixes the problem discovered in #19387 (comment).

This actually improves the generated docs for a few rules:

  • typescript/no-deprecated
  • no-floating-promises
  • react/forbid-dom-props
  • typescript/no-misused-spread
  • typescript/only-throw-error
  • typescript/prefer-readonly-parameter-types
  • typescript/prefer-nullish-coalescing
  • typescript/restrict-template-expressions

Basically, any rule that has a struct nested inside an array has better docs now, as the docs generator actually handles their schema correctly now.

AI Disclosure: Generated by Claude Code.

Examples:

no-deprecated

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[]`

An array of type or value specifiers that are allowed to be used even if deprecated.
Use this to allow specific deprecated APIs that you intentionally want to continue using.

#### allow[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allow[n].from

type: `"file"`

##### allow[n].name

type: `array | string`

Name specifier that can be a single string or array of strings

###### allow[n].name[n]

type: `string`

##### allow[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

react/forbid-dom-props

## Configuration

Configuration for the `forbid-dom-props` rule.

This rule accepts a configuration object with the following properties:

### forbid

type: `array`

An array of prop names or objects that are forbidden on DOM elements.

Each array element can be a string with the property name, or an object
with `propName`, an optional `disallowedFor` array of DOM node names,
and an optional custom `message`.

Examples:

- `["error", { "forbid": ["id", "style"] }]`
- `["error", { "forbid": [{ "propName": "className", "message": "Use class instead" }] }]`
- `["error", { "forbid": [{ "propName": "style", "disallowedFor": ["div", "span"] }] }]`

#### forbid[n]

type: `object | string`

A forbidden prop, either as a plain prop name string or with options.

##### forbid[n].disallowedFor

type: `string[]`

A list of DOM element names (e.g. `["div", "span"]`) on which this
prop is forbidden. If empty or omitted, the prop is forbidden on all
DOM elements.

##### forbid[n].message

type: `string`

A custom message to display when this prop is used.

##### forbid[n].propName

type: `string`

The name of the prop to forbid.

claude and others added 3 commits March 5, 2026 06:06
…enum variants

Schemars' draft-07 `RemoveRefSiblings` visitor moves `$ref` into an
`allOf` wrapper when the schema has sibling properties (e.g. description
from doc comments on enum variants). The doc generation code only handled
nested `anyOf` when flattening schemas, missing these `allOf`-wrapped
refs. This caused rules like `forbid-dom-props` to show only `string`
instead of `object | string` with the full object properties.

https://claude.ai/code/session_01SqwraaYKmCViWS6wotj8ce
Copilot AI review requested due to automatic review settings March 5, 2026 06:19
@github-actions github-actions bot added the C-bug Category - Bug label Mar 5, 2026
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Improves the website schema-to-markdown renderer so rule/config docs render correctly when schemars (draft-07) wraps $ref+siblings into allOf, fixing missing/incorrect docs for enum-based configs and similar patterns.

Changes:

  • Update schema_markdown.rs to unwrap/resolve allOf wrappers while flattening anyOf schemas.
  • Refresh formatter schema markdown snapshots to reflect the improved rendering (e.g., marker-object option now appears as object | array | string with expanded fields).
  • Expand linter rule docs snapshots and the snapshot test selection to include react/forbid-dom-props.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File Description
tasks/website_common/src/schema_markdown.rs Unwraps allOf wrappers during anyOf flattening to correctly resolve referenced schemas for markdown docs.
tasks/website_formatter/src/snapshots/schema_markdown.snap Snapshot updates reflecting improved schema markdown rendering (new object variant expansion).
tasks/website_linter/src/rules/mod.rs Adds react/forbid-dom-props to the small set of rule pages included in the docs snapshot test.
tasks/website_linter/src/rules/snapshots/docs_rule_pages.snap Snapshot updates for improved config docs output and inclusion of the new rule page.

@camc314 camc314 added the 0-merge Merge with Graphite Merge Queue label Mar 5, 2026
@camc314 camc314 self-assigned this Mar 5, 2026
Copy link
Contributor

camc314 commented Mar 5, 2026

Merge activity

  • Mar 5, 9:13 AM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
  • Mar 5, 9:13 AM UTC: camc314 added this pull request to the Graphite merge queue.
  • Mar 5, 9:18 AM UTC: The Graphite merge queue couldn't merge this PR because it failed for an unknown reason (Fast-forward merges are not supported for forked repositories. Please create a branch in the target repository in order to merge).
  • Mar 5, 1:20 PM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
  • Mar 5, 1:21 PM UTC: camc314 added this pull request to the Graphite merge queue.
  • Mar 5, 1:21 PM UTC: The Graphite merge queue couldn't merge this PR because it failed for an unknown reason (Fast-forward merges are not supported for forked repositories. Please create a branch in the target repository in order to merge).

@graphite-app graphite-app bot removed the 0-merge Merge with Graphite Merge Queue label Mar 5, 2026
@camc314 camc314 added the 0-merge Merge with Graphite Merge Queue label Mar 5, 2026
@graphite-app graphite-app bot removed the 0-merge Merge with Graphite Merge Queue label Mar 5, 2026
@connorshea connorshea merged commit d631b31 into oxc-project:main Mar 6, 2026
20 checks passed
@connorshea connorshea deleted the claude/fix-forbid-dom-props-docs-HPJBz branch March 6, 2026 00:51
@connorshea
Copy link
Member Author

I think it wouldn't auto-merge because I put it in my fork (since Claude isn't allowed to write to the oxc repo directly)?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

C-bug Category - Bug

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants