feat: add options parameter with withNursery to buildFromOxlintConfig function (#545)

Nursery rules specified in `.oxlintrc.json` were not being output by
`buildFromOxlintConfigFile`, preventing ESLint from disabling them.
Nursery rules are unstable and excluded by default by design, but users
need opt-in access when explicitly configuring them.

## Changes

**Type & API**
- Added `BuildFromOxlintConfigOptions` type with optional `withNursery:
boolean` flag
- Updated `buildFromOxlintConfig()` and `buildFromOxlintConfigFile()` to
accept optional `options` parameter (defaults to `{ withNursery: false
}`)

**Rule Filtering**
- Modified `scripts/constants.ts`: removed 'nursery' from
`ignoreCategories` to generate nursery rules
- Updated `RulesGenerator` and `ConfigGenerator`: filter nursery rules
when grouping by scope (but include when grouping by category)
- Updated `handleCategoriesScope()` and `handleRulesScope()` to filter
nursery rules unless `withNursery: true`
- Modified `src/configs.ts`: explicitly exclude nursery rules from `all`
and `flat/all` configs

**Generated Files**
- `rules-by-category.ts` and `configs-by-category.ts`: Include nursery
rules (in `nurseryRules` and `flat/nursery` config)
- `rules-by-scope.ts` and `configs-by-scope.ts`: Exclude nursery rules
(no nursery in scope-based groupings like `flat/eslint`, `flat/react`,
etc.)

**Testing**
- Added 6 tests verifying nursery rules behavior with/without
`withNursery` option
- Added 3 tests confirming nursery rules absent from `all`, `flat/all`,
and scope-based configs

## Usage

```typescript
// Default: nursery rules excluded (backward compatible)
buildFromOxlintConfig({
  rules: { 'import/named': 'error' }
});
// => import/named NOT in output

// Opt-in: nursery rules included
buildFromOxlintConfig({
  rules: { 'import/named': 'error' }
}, { withNursery: true });
// => { 'import/named': 'off' }
```

Fully backward compatible—existing behavior unchanged.

Fixes #412

<!-- START COPILOT CODING AGENT SUFFIX -->



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>Nursery rules are not output by
buildFromOxlintConfigFile</issue_title>
> <issue_description><details>
> <summary>.oxlintrc.json</summary>
> 
> ```
> {
>   "$schema": "./node_modules/oxlint/configuration_schema.json",
>   "plugins": [],
>   "rules": {
>     "import/no-cycle": "error",
>     "import/named": "error"
>   }
> }
> 
> ```
> </details>
> 
> 
> <details>
> <summary>Output from eslint-plugin-oxlint</summary>
> 
> ```
> // output from oxlint.buildFromOxlintConfigFile('./.oxlintrc.json')
> 
> [
>   {
>     name: 'oxlint/from-oxlint-config',
>     rules: {
>       'for-direction': 'off',
>       'no-async-promise-executor': 'off',
>       'no-caller': 'off',
>       'no-class-assign': 'off',
>       'no-useless-backreference': 'off',
>       'no-compare-neg-zero': 'off',
>       'no-cond-assign': 'off',
>       'no-const-assign': 'off',
>       'no-constant-binary-expression': 'off',
>       'no-constant-condition': 'off',
>       'no-control-regex': 'off',
>       'no-debugger': 'off',
>       'no-delete-var': 'off',
>       'no-dupe-class-members': 'off',
>       'no-dupe-else-if': 'off',
>       'no-dupe-keys': 'off',
>       'no-duplicate-case': 'off',
>       'no-empty-character-class': 'off',
>       'no-empty-pattern': 'off',
>       'no-empty-static-block': 'off',
>       'no-eval': 'off',
>       'no-ex-assign': 'off',
>       'no-extra-boolean-cast': 'off',
>       'no-func-assign': 'off',
>       'no-global-assign': 'off',
>       'no-import-assign': 'off',
>       'no-invalid-regexp': 'off',
>       'no-irregular-whitespace': 'off',
>       'no-loss-of-precision': 'off',
>       'no-new-native-nonconstructor': 'off',
>       'no-nonoctal-decimal-escape': 'off',
>       'no-obj-calls': 'off',
>       'no-self-assign': 'off',
>       'no-setter-return': 'off',
>       'no-shadow-restricted-names': 'off',
>       'no-sparse-arrays': 'off',
>       'no-this-before-super': 'off',
>       'no-unsafe-finally': 'off',
>       'no-unsafe-negation': 'off',
>       'no-unsafe-optional-chaining': 'off',
>       'no-unused-labels': 'off',
>       'no-unused-private-class-members': 'off',
>       'no-useless-catch': 'off',
>       'no-useless-escape': 'off',
>       'no-useless-rename': 'off',
>       'no-with': 'off',
>       'require-yield': 'off',
>       'use-isnan': 'off',
>       'valid-typeof': 'off',
>       'import/no-cycle': 'off'
>     }
>   },
>   {
>     name: 'oxlint/vue-svelte-exceptions',
>     ignores: [ '**/*.vue', '**/*.svelte' ],
>     rules: { 'no-unused-vars': 'off' }
>   }
> ]
> ```
> </details>
> 
> 
> When explicitly specifying a rule within the [Nursery
category](https://oxc.rs/docs/guide/usage/linter/rules.html#nursery-10)
(in the above example, `import/named`), the plugin doesn't return the
rule. This means it will not be turned off in the ESLint config.
> 
> I would expect that any rules defined in the `.oxlintrc.json` file to
be output as 'off'. The example above sees that non-Nursery rules
(`import/no-cycle`) do this, but Nursery rules are not output.
> </issue_description>
> 
> <agent_instructions>`buildFromOxlintConfig` and
`buildFromOxlintConfigFile` should have a second optional `options`
parameter for nursery rules.
> Do not ignore nursery rules in
https://github.com/oxc-project/eslint-plugin-oxlint/blob/main/scripts/constants.ts
> But do not implement them to the general config in `all` and
`flat/all` config:
>
https://github.com/oxc-project/eslint-plugin-oxlint/blob/ae96e4995816341987448e836acbda732ec561cb/src/configs.ts#L30-L37
> Create tests for:
> - nursery rules are not in the `all` and `flat/all` config
> - nursery rules are not outputted with default `buildFromOxlintConfig`
> - nursery rules are outputted with `options: withNursery=true` and
`buildFromOxlintConfig`</agent_instructions>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> <comment_new><author>@Sysix</author><body>
> Nursery rules are rules which are still under development. 
> Disabling the rule in ESLint will maybe not report warnings in oxlint
as expected.
> This was a design decision:
#255 (review)
and #256.
> 
> ~~This decision was made when `buildFromOxlintConfigFile` was not
created.~~
> Happy to see this implement with a second optional options parameter
for `buildFromOxlintConfigFile`.</body></comment_new>
> </comments>
> 


</details>

- Fixes #412

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/oxc-project/eslint-plugin-oxlint/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Sysix <3897725+Sysix@users.noreply.github.com>
Co-authored-by: Sysix <sysix@sysix-coding.de>

Author: Copilot

scripts/config-generator.ts

@@ -41,7 +41,11 @@ export class ConfigGenerator {
     console.log(`Generating config, grouped by ${this.rulesGrouping}`);
 
     const rulesGrouping = this.rulesGrouping;
-    const rulesArray = this.rulesArray;
+    // Filter out nursery rules when grouping by scope
+    const rulesArray =
+      this.rulesGrouping === RulesGrouping.SCOPE
+        ? this.rulesArray.filter((rule) => rule.category !== 'nursery')
+        : this.rulesArray;
 
     const rulesMap = this.groupItemsBy(rulesArray, rulesGrouping);
     const exportName = pascalCase(this.rulesGrouping);

scripts/constants.ts

@@ -1,9 +1,6 @@
 // these are the rules that don't have a direct equivalent in the eslint rules
 export const ignoreScope = new Set(['oxc', 'deepscan', 'security']);
 
-// these are the rules that are not fully implemented in oxc
-export const ignoreCategories = new Set(['nursery']);
-
 // we are ignoring typescript type-aware rules for now, until it is stable.
 // When support it with a flag, do the same for `ignoreCategories`.
 // List copied from:

scripts/rules-generator.ts

@@ -44,7 +44,11 @@ export class RulesGenerator {
     console.log(`Generating rules, grouped by ${this.rulesGrouping}`);
 
     const rulesGrouping = this.rulesGrouping;
-    const rulesArray = this.rulesArray;
+    // Filter out nursery rules when grouping by scope
+    const rulesArray =
+      this.rulesGrouping === RulesGrouping.SCOPE
+        ? this.rulesArray.filter((rule) => rule.category !== 'nursery')
+        : this.rulesArray;
 
     const rulesMap = this.groupItemsBy(rulesArray, rulesGrouping);
 

scripts/traverse-rules.ts

@@ -1,9 +1,5 @@
 import { execSync } from 'node:child_process';
-import {
-  ignoreCategories,
-  ignoreScope,
-  typescriptTypeAwareRules,
-} from './constants.js';
+import { ignoreScope, typescriptTypeAwareRules } from './constants.js';
 import {
   aliasPluginNames,
   reactHookRulesInsideReactScope,
@@ -98,7 +94,6 @@ export function traverseRules(): Rule[] {
   // get all rules and filter the ignored one
   const rules = readRulesFromCommand().filter(
     (rule) =>
-      !ignoreCategories.has(rule.category) &&
       !ignoreScope.has(rule.scope) &&
       // ignore type-aware rules
       !(

src/build-from-oxlint-config.spec.ts

@@ -192,6 +192,46 @@ describe('integration test with oxlint', () => {
   }
 });
 
+describe('nursery rules', () => {
+  it('should not output nursery rules by default', () => {
+    const config = {
+      rules: {
+        'import/named': 'error',
+        'no-undef': 'error',
+      },
+    };
+
+    const configs = buildFromOxlintConfig(config);
+
+    expect(configs.length).toBeGreaterThanOrEqual(1);
+    expect(configs[0].rules).not.toBeUndefined();
+
+    // nursery rules should NOT be present
+    expect('import/named' in configs[0].rules!).toBe(false);
+    expect('no-undef' in configs[0].rules!).toBe(false);
+  });
+
+  it('should output nursery rules when withNursery option is true', () => {
+    const config = {
+      rules: {
+        'import/named': 'error',
+        'no-undef': 'error',
+      },
+    };
+
+    const configs = buildFromOxlintConfig(config, { withNursery: true });
+
+    expect(configs.length).toBeGreaterThanOrEqual(1);
+    expect(configs[0].rules).not.toBeUndefined();
+
+    // nursery rules SHOULD be present when withNursery is true
+    expect('import/named' in configs[0].rules!).toBe(true);
+    expect('no-undef' in configs[0].rules!).toBe(true);
+    expect(configs[0].rules!['import/named']).toBe('off');
+    expect(configs[0].rules!['no-undef']).toBe('off');
+  });
+});
+
 const createConfigFileAndBuildFromIt = (
   filename: string,
   content: string

src/build-from-oxlint-config/categories.ts

@@ -1,6 +1,7 @@
 import { aliasPluginNames } from '../constants.js';
 import configByCategory from '../generated/configs-by-category.js';
 import {
+  BuildFromOxlintConfigOptions,
   OxlintConfig,
   OxlintConfigCategories,
   OxlintConfigPlugins,
@@ -18,11 +19,17 @@ export const defaultCategories: OxlintConfigCategories = {
 export const handleCategoriesScope = (
   plugins: OxlintConfigPlugins,
   categories: OxlintConfigCategories,
-  rules: Record<string, 'off'>
+  rules: Record<string, 'off'>,
+  options: BuildFromOxlintConfigOptions = {}
 ): void => {
   for (const category in categories) {
     const configName = `flat/${category}`;
 
+    // Skip nursery category unless explicitly enabled
+    if (category === 'nursery' && !options.withNursery) {
+      continue;
+    }
+
     // category is not enabled or not in found categories
     if (categories[category] === 'off' || !(configName in configByCategory)) {
       continue;

src/build-from-oxlint-config/index.ts

@@ -1,4 +1,8 @@
-import { EslintPluginOxlintConfig, OxlintConfig } from './types.js';
+import {
+  BuildFromOxlintConfigOptions,
+  EslintPluginOxlintConfig,
+  OxlintConfig,
+} from './types.js';
 import { handleRulesScope, readRulesFromConfig } from './rules.js';
 import {
   defaultCategories,
@@ -25,7 +29,8 @@ import path from 'node:path';
  * It accepts an object similar to the .oxlintrc.json file.
  */
 export const buildFromOxlintConfig = (
-  config: OxlintConfig
+  config: OxlintConfig,
+  options: BuildFromOxlintConfigOptions = {}
 ): EslintPluginOxlintConfig[] => {
   resolveRelativeExtendsPaths(config);
 
@@ -47,12 +52,12 @@ export const buildFromOxlintConfig = (
     plugins.push('react-hooks');
   }
 
-  handleCategoriesScope(plugins, categories, rules);
+  handleCategoriesScope(plugins, categories, rules, options);
 
   const configRules = readRulesFromConfig(config);
 
   if (configRules !== undefined) {
-    handleRulesScope(configRules, rules);
+    handleRulesScope(configRules, rules, options);
   }
 
   const baseConfig = {
@@ -72,7 +77,7 @@ export const buildFromOxlintConfig = (
   ) as EslintPluginOxlintConfig[];
 
   if (overrides !== undefined) {
-    handleOverridesScope(overrides, configs, categories);
+    handleOverridesScope(overrides, configs, categories, options);
   }
 
   return configs;
@@ -86,7 +91,8 @@ export const buildFromOxlintConfig = (
  * no rules will be deactivated and an error to `console.error` will be emitted
  */
 export const buildFromOxlintConfigFile = (
-  oxlintConfigFile: string
+  oxlintConfigFile: string,
+  options: BuildFromOxlintConfigOptions = {}
 ): EslintPluginOxlintConfig[] => {
   const config = getConfigContent(oxlintConfigFile);
 
@@ -100,5 +106,5 @@ export const buildFromOxlintConfigFile = (
     filePath: path.resolve(oxlintConfigFile),
   };
 
-  return buildFromOxlintConfig(config);
+  return buildFromOxlintConfig(config, options);
 };

src/build-from-oxlint-config/overrides.ts

@@ -2,6 +2,7 @@ import { handleCategoriesScope } from './categories.js';
 import { readPluginsFromConfig } from './plugins.js';
 import { handleRulesScope, readRulesFromConfig } from './rules.js';
 import {
+  BuildFromOxlintConfigOptions,
   EslintPluginOxlintConfig,
   OxlintConfig,
   OxlintConfigCategories,
@@ -11,7 +12,8 @@ import {
 export const handleOverridesScope = (
   overrides: OxlintConfigOverride[],
   configs: EslintPluginOxlintConfig[],
-  baseCategories?: OxlintConfigCategories
+  baseCategories?: OxlintConfigCategories,
+  options: BuildFromOxlintConfigOptions = {}
 ): void => {
   for (const [overrideIndex, override] of overrides.entries()) {
     const eslintRules: Record<string, 'off'> = {};
@@ -23,12 +25,12 @@ export const handleOverridesScope = (
 
     const plugins = readPluginsFromConfig(override);
     if (baseCategories !== undefined && plugins !== undefined) {
-      handleCategoriesScope(plugins, baseCategories, eslintRules);
+      handleCategoriesScope(plugins, baseCategories, eslintRules, options);
     }
 
     const rules = readRulesFromConfig(override);
     if (rules !== undefined) {
-      handleRulesScope(rules, eslintRules);
+      handleRulesScope(rules, eslintRules, options);
     }
 
     eslintConfig.rules = eslintRules;

src/build-from-oxlint-config/rules.ts

@@ -3,11 +3,13 @@ import {
   reactHookRulesInsideReactScope,
 } from '../constants.js';
 import {
+  BuildFromOxlintConfigOptions,
   OxlintConfig,
   OxlintConfigOverride,
   OxlintConfigRules,
 } from './types.js';
 import configByCategory from '../generated/configs-by-category.js';
+import { nurseryRules } from '../generated/rules-by-category.js';
 import { isObject } from './utilities.js';
 
 const allRulesObjects = Object.values(configByCategory).map(
@@ -17,12 +19,22 @@ const allRules: string[] = allRulesObjects.flatMap((rulesObject) =>
   Object.keys(rulesObject)
 );
 
-const getEsLintRuleName = (rule: string): string | undefined => {
+const getEsLintRuleName = (
+  rule: string,
+  options: BuildFromOxlintConfigOptions = {}
+): string | undefined => {
   // there is no plugin prefix, it can be all plugin
   if (!rule.includes('/')) {
-    return allRules.find(
+    const found = allRules.find(
       (search) => search.endsWith(`/${rule}`) || search === rule
     );
+
+    // Filter out nursery rules unless explicitly enabled
+    if (found && !options.withNursery && found in nurseryRules) {
+      return undefined;
+    }
+
+    return found;
   }
 
   // greedy works with `@next/next/no-img-element` as an example
@@ -51,7 +63,14 @@ const getEsLintRuleName = (rule: string): string | undefined => {
   const expectedRule =
     esPluginName === '' ? ruleName : `${esPluginName}/${ruleName}`;
 
-  return allRules.find((rule) => rule === expectedRule);
+  const found = allRules.find((rule) => rule === expectedRule);
+
+  // Filter out nursery rules unless explicitly enabled
+  if (found && !options.withNursery && found in nurseryRules) {
+    return undefined;
+  }
+
+  return found;
 };
 
 /**
@@ -77,10 +96,11 @@ const isActiveValue = (value: unknown) =>
  */
 export const handleRulesScope = (
   oxlintRules: OxlintConfigRules,
-  rules: Record<string, 'off'>
+  rules: Record<string, 'off'>,
+  options: BuildFromOxlintConfigOptions = {}
 ): void => {
   for (const rule in oxlintRules) {
-    const eslintName = getEsLintRuleName(rule);
+    const eslintName = getEsLintRuleName(rule, options);
 
     if (eslintName === undefined) {
       continue;

src/build-from-oxlint-config/types.ts

@@ -1,5 +1,9 @@
 import type { Linter } from 'eslint';
 
+export type BuildFromOxlintConfigOptions = {
+  withNursery?: boolean;
+};
+
 export type OxlintConfigExtends = string[];
 
 export type OxlintConfigPlugins = string[];