@homer0/oxlint-config 1.0.3 → 2.0.0

package/src/createConfig.ts

@@ -1,14 +1,24 @@
 import globals from 'globals';
-import { DEFAULT_IGNORES, TEST_FILES, type TestConvention } from './consts.js';
+import {
+  DEFAULT_IGNORES,
+  TEST_FILES,
+  CONFIG_ENVS,
+  type ConfigEnv,
+  type TestConvention,
+} from './consts.js';
 import { extensionFragments } from './fragments.js';
 import {
   nextjs as nextjsRules,
   typeAware as typeAwareRules,
   vitest as vitestRules,
+  noUnderscoreDangleRule,
+  noUnderscoreDangleOptions,
 } from './rules/index.js';
 import type {
   ConfigFragment,
-  ConfigName,
+  ConfigOverrideOptions,
+  DangleRuleOptions,
+  DangleRuleSettings,
   CreateConfigSettings,
   GeneratedConfig,
   GeneratedConfigOverride,
@@ -17,7 +27,11 @@ import type {
   ResolveConfigComponentsOptions,
   ResolveConfigComponentsResult,
   ResolveTestConfigComponentsOptions,
+  ResolveTestConfigComponentsResult,
   CreateTestOverrideOptions,
+  ResolveGlobalsOptions,
+  ResolvedGlobalVars,
+  RuleSettings,
 } from './types.js';
 
 const mergeRules = (...fragments: (ConfigFragment | undefined)[]) =>
@@ -26,42 +40,139 @@ const mergeRules = (...fragments: (ConfigFragment | undefined)[]) =>
     return acc;
   }, {});
 
-const getConfig = (configs: ConfigName[]): ConfigName => {
-  if (configs.length !== 1) {
-    throw new Error(
-      'Exactly one environment config must be selected: "node" or "browser".',
-    );
+/** Combines config rules with user overrides. */
+const mergeRuleSettings = (fragments: ConfigFragment[], settings: RuleSettings[] = []) =>
+  mergeRules(...fragments, ...settings.map((rules) => ({ rules })));
+
+/** Marks environment globals as unavailable. */
+const disableGlobals = (env: ConfigEnv): ResolvedGlobalVars =>
+  Object.fromEntries(
+    Object.keys(extensionFragments[env].globals).map((name) => [name, 'off']),
+  );
+
+/** Checks if an override applies to files. */
+const isConfigOverride = (
+  override: ConfigOverrideOptions | RuleSettings,
+): override is ConfigOverrideOptions => Object.hasOwn(override, 'files');
+
+/** Splits rule overrides from file overrides. */
+const resolveUserOverrides = (overrides: CreateConfigSettings['overrides']) => {
+  if (!overrides) {
+    return {
+      configOverrides: [],
+      ruleOverrides: [],
+    };
   }
 
-  const [config] = configs;
-  if (typeof config === 'undefined') {
-    throw new Error(
-      'Exactly one environment config must be selected: "node" or "browser".',
-    );
+  if (!Array.isArray(overrides)) {
+    return {
+      configOverrides: [],
+      ruleOverrides: [overrides],
+    };
+  }
+
+  return overrides.reduce<{
+    configOverrides: ConfigOverrideOptions[];
+    ruleOverrides: RuleSettings[];
+  }>(
+    (acc, override) => {
+      if (isConfigOverride(override)) {
+        acc.configOverrides.push(override);
+      } else {
+        acc.ruleOverrides.push(override);
+      }
+
+      return acc;
+    },
+    { configOverrides: [], ruleOverrides: [] },
+  );
+};
+
+const allowDangleNames = (rules: RuleSettings, names: string[] = []): RuleSettings => {
+  if (names.length === 0) return rules;
+
+  const dangleRule = rules['no-underscore-dangle'] || noUnderscoreDangleRule;
+  if (!Array.isArray(dangleRule)) return rules;
+
+  const [severity, configuredOptions] = dangleRule as DangleRuleSettings;
+  const options: DangleRuleOptions =
+    typeof configuredOptions === 'object' && configuredOptions !== null
+      ? configuredOptions
+      : {};
+
+  return {
+    ...rules,
+    'no-underscore-dangle': [
+      severity,
+      {
+        ...noUnderscoreDangleOptions,
+        ...options,
+        allow: Array.from(
+          new Set([
+            ...noUnderscoreDangleOptions.allow,
+            ...(options.allow || []),
+            ...names,
+          ]),
+        ),
+      },
+    ],
+  };
+};
+
+const resolveGlobals = ({
+  globals: globalVars = {},
+  doingTestsSetup,
+}: ResolveGlobalsOptions): ResolvedGlobalVars => {
+  if (doingTestsSetup) {
+    return globalVars;
+  }
+
+  return Object.entries(globalVars).reduce<ResolvedGlobalVars>((acc, [name, mode]) => {
+    if (name.startsWith('$')) {
+      const groupName = name.slice(1);
+      if (!Object.hasOwn(globals, groupName)) {
+        throw new Error(`Unknown global group: "${groupName}".`);
+      }
+
+      Object.assign(acc, globals[groupName as keyof typeof globals]);
+    } else {
+      acc[name] = mode === true ? 'writable' : mode;
+    }
+
+    return acc;
+  }, {});
+};
+
+const getEnvironment = (env: ConfigEnv): ConfigEnv => {
+  if (!CONFIG_ENVS.includes(env)) {
+    const humanReadableEnvs = CONFIG_ENVS.map((e) => `"${e}"`).join(' or ');
+    throw new Error(`Environment must be ${humanReadableEnvs}.`);
   }
 
-  return config;
+  return env;
 };
 
+/** Turns a file glob into a list. */
+const resolveFiles = (files: string | string[]): string[] =>
+  Array.isArray(files) ? files.slice() : [files];
+
 const resolveTestFiles = (files: string | string[] | undefined): string[] => {
   if (typeof files === 'undefined') return [];
-  if (Array.isArray(files)) return files.slice();
-  if (Object.hasOwn(TEST_FILES, files))
+  if (typeof files === 'string' && Object.hasOwn(TEST_FILES, files)) {
     return TEST_FILES[files as TestConvention].slice();
+  }
 
-  return [files];
+  return resolveFiles(files);
 };
 
 const resolveTestConfig = ({
   tests,
-  productionConfig,
+  productionEnv,
   productionTs,
-}: ResolveTestConfigOptions): ResolvedTestConfig | undefined => {
-  if (!tests) return undefined;
-
+}: ResolveTestConfigOptions): ResolvedTestConfig => {
   if (tests === true) {
     return {
-      configs: [productionConfig],
+      env: productionEnv,
       files: [...TEST_FILES.colocated, ...TEST_FILES.directory],
       framework: 'vitest',
       ts: productionTs,
@@ -70,7 +181,7 @@ const resolveTestConfig = ({
 
   if (typeof tests === 'string') {
     return {
-      configs: [productionConfig],
+      env: productionEnv,
       files: TEST_FILES[tests].slice(),
       framework: 'vitest',
       ts: productionTs,
@@ -78,7 +189,7 @@ const resolveTestConfig = ({
   }
 
   return {
-    configs: tests.configs ?? [productionConfig],
+    env: tests.env ?? productionEnv,
     files: resolveTestFiles(tests.files),
     framework: tests.framework || 'vitest',
     ts: tests.ts ?? productionTs,
@@ -86,11 +197,11 @@ const resolveTestConfig = ({
 };
 
 const resolveTestConfigComponents = ({
-  config,
+  env,
   testConfig,
   tests,
-  ts,
-}: ResolveTestConfigComponentsOptions) => {
+  ts = false,
+}: ResolveTestConfigComponentsOptions): ResolveTestConfigComponentsResult => {
   if (testConfig) {
     return {
       doingTestsSetup: true,
@@ -109,8 +220,8 @@ const resolveTestConfigComponents = ({
     doingTestsSetup: false,
     testConfig: resolveTestConfig({
       tests,
-      productionConfig: config,
-      productionTs: ts ?? false,
+      productionEnv: env,
+      productionTs: ts,
     }),
   };
 };
@@ -119,8 +230,9 @@ const resolveConfigComponents = (
   options: ResolveConfigComponentsOptions,
 ): ResolveConfigComponentsResult => {
   const {
-    configs,
+    env: environment,
     extensions,
+    globals: globalVars,
     jsdoc,
     nextjs,
     react,
@@ -132,22 +244,23 @@ const resolveConfigComponents = (
 
   const baseExtensionFragment = baseExtensionFragmentOption ?? extensions?.base;
 
-  const config = getConfig(options.configs);
+  const env = getEnvironment(environment);
 
   const { doingTestsSetup, testConfig } = resolveTestConfigComponents({
-    config,
+    env,
     testConfig: options.testConfig,
     tests: options.tests,
     ts,
   });
 
-  const fragments: ConfigFragment[] = [baseFragment, extensionFragments[config]];
+  const fragments: ConfigFragment[] = [baseFragment, extensionFragments[env]];
+  const resolvedGlobals = resolveGlobals({ globals: globalVars, doingTestsSetup });
 
   const plugins = ['import'];
 
   const configGlobals: Array<Record<string, boolean | string>> = [];
 
-  if (configs.includes('node')) {
+  if (env === 'node') {
     plugins.push('node');
   }
 
@@ -190,8 +303,8 @@ const resolveConfigComponents = (
     fragments.push(baseExtensionFragment);
   }
 
-  if (extensions?.[config]) {
-    fragments.push(extensions[config]);
+  if (extensions?.[env]) {
+    fragments.push(extensions[env]);
   }
 
   if (jsdoc && extensions?.jsdoc) {
@@ -207,8 +320,9 @@ const resolveConfigComponents = (
   }
 
   return {
-    config,
+    env,
     fragments,
+    globals: resolvedGlobals,
     plugins,
     testConfig,
     configGlobals:
@@ -217,18 +331,31 @@ const resolveConfigComponents = (
 };
 
 const createTestOverride = ({
+  parentEnv,
   testConfig,
+  allowedDangleNames,
   extensions,
+  extraRules = [],
+  globals: globalVars,
 }: CreateTestOverrideOptions): GeneratedConfigOverride => {
-  const { config, fragments, configGlobals } = resolveConfigComponents({
-    configs: testConfig.configs,
+  const {
+    env,
+    fragments,
+    globals: resolvedGlobals,
+    configGlobals,
+  } = resolveConfigComponents({
+    env: testConfig.env,
     extensions,
+    globals: globalVars,
     testConfig,
     ts: testConfig.ts,
     baseFragment: extensionFragments.tests,
     baseExtensionFragment: extensions?.tests,
   });
-  const rules = mergeRules(...fragments);
+  const rules = allowDangleNames(
+    mergeRuleSettings(fragments, extraRules),
+    allowedDangleNames,
+  );
 
   if (testConfig.files.length === 0) {
     throw new Error('Custom test configuration requires at least one file glob.');
@@ -237,29 +364,132 @@ const createTestOverride = ({
   return {
     files: testConfig.files,
     globals: {
-      ...extensionFragments[config].globals,
+      ...disableGlobals(parentEnv),
+      ...extensionFragments[env].globals,
+      ...resolvedGlobals,
       ...configGlobals,
     },
     rules,
   };
 };
 
+type CreateConfigOverrideOptions = {
+  override: ConfigOverrideOptions;
+  options: CreateConfigSettings;
+  parentEnv: ConfigEnv;
+  rootRuleOverrides: RuleSettings[];
+};
+
+/** Creates a file override and its test override. */
+const createConfigOverride = ({
+  override,
+  options,
+  parentEnv,
+  rootRuleOverrides,
+}: CreateConfigOverrideOptions) => {
+  const { files, ignores, rules: overrideRules, tests, ...overrideOptions } = override;
+  const {
+    env,
+    fragments,
+    globals: resolvedGlobals,
+    plugins,
+    testConfig,
+  } = resolveConfigComponents({
+    ...options,
+    ...overrideOptions,
+    env: override.env ?? parentEnv,
+    tests,
+  });
+  const extraRules = [...rootRuleOverrides, ...(overrideRules ? [overrideRules] : [])];
+
+  return {
+    override: {
+      excludeFiles: ignores,
+      files: resolveFiles(files),
+      globals: {
+        ...disableGlobals(parentEnv),
+        ...extensionFragments[env].globals,
+        ...resolvedGlobals,
+      },
+      rules: allowDangleNames(
+        mergeRuleSettings(fragments, extraRules),
+        options.allowedDangleNames,
+      ),
+    },
+    plugins,
+    testOverride: testConfig
+      ? createTestOverride({
+          parentEnv,
+          testConfig,
+          allowedDangleNames: options.allowedDangleNames,
+          extensions: overrideOptions.extensions ?? options.extensions,
+          extraRules,
+          globals: overrideOptions.globals ?? options.globals,
+        })
+      : undefined,
+  };
+};
+
 /** Creates a native Oxlint configuration from one environment and optional policy layers. */
 export const createConfig = (options: CreateConfigSettings): GeneratedConfig => {
-  const { fragments, plugins, config, testConfig } = resolveConfigComponents(options);
-  const { extensions, ignores, typeAware } = options;
+  const {
+    fragments,
+    globals: resolvedGlobals,
+    plugins: resolvedPlugins,
+    env,
+    testConfig,
+  } = resolveConfigComponents(options);
+  const { allowedDangleNames, extensions, ignores, typeAware } = options;
+  const { configOverrides, ruleOverrides } = resolveUserOverrides(options.overrides);
+  const generatedOverrides: GeneratedConfigOverride[] = [];
+  const plugins = resolvedPlugins.slice();
+
+  if (testConfig) {
+    generatedOverrides.push(
+      createTestOverride({
+        parentEnv: env,
+        testConfig,
+        allowedDangleNames,
+        extensions,
+        extraRules: ruleOverrides,
+        globals: resolvedGlobals,
+      }),
+    );
+  }
+
+  for (const override of configOverrides) {
+    const generatedOverride = createConfigOverride({
+      override,
+      options,
+      parentEnv: env,
+      rootRuleOverrides: ruleOverrides,
+    });
+
+    generatedOverrides.push(generatedOverride.override);
+    if (generatedOverride.testOverride) {
+      generatedOverrides.push(generatedOverride.testOverride);
+    }
+
+    for (const plugin of generatedOverride.plugins) {
+      if (!plugins.includes(plugin)) plugins.push(plugin);
+    }
+  }
 
-  const rules = mergeRules(...fragments);
+  const rules = allowDangleNames(
+    mergeRuleSettings(fragments, ruleOverrides),
+    allowedDangleNames,
+  );
 
   return {
     globals: {
       ...extensionFragments.base.globals,
-      ...extensionFragments[config].globals,
+      ...extensionFragments[env].globals,
+      ...resolvedGlobals,
     },
     ignorePatterns: [...DEFAULT_IGNORES, ...(ignores || [])],
     options: typeAware ? { typeAware: true } : undefined,
     plugins,
     rules,
-    overrides: testConfig ? [createTestOverride({ testConfig, extensions })] : undefined,
+    overrides: generatedOverrides.length > 0 ? generatedOverrides : undefined,
   };
 };

package/src/createNextjsConfig.ts

@@ -5,12 +5,14 @@ const NEXTJS_IGNORES = ['.next/', 'out/', 'build/', 'next-env.d.ts'];
 
 /** Creates a native Oxlint configuration for a Next.js TypeScript project. */
 export const createNextjsConfig = ({
+  globals = {},
   ignores = [],
   ...options
 }: CreateNextjsConfigOptions) =>
   createConfig({
     ...options,
-    configs: ['node'],
+    env: 'node',
+    globals: { $browser: true, ...globals },
     ignores: [...NEXTJS_IGNORES, ...ignores],
     nextjs: true,
     react: true,

package/src/index.ts

@@ -1,17 +1,13 @@
-import { createConfig } from './createConfig.js';
-import type { CreateReactConfigOptions } from './types.js';
-
 export { createConfig } from './createConfig.js';
 export { createNextjsConfig } from './createNextjsConfig.js';
 export { extensionFragments } from './fragments.js';
 export type {
   ConfigFragment,
-  ConfigName,
   CreateConfigOptions,
   CreateNextjsConfigOptions,
-  CreateReactConfigOptions,
-  ExtensionFragmentName,
   ExtensionFragments,
+  GlobalVarMode,
+  GlobalVars,
   GeneratedConfig,
   GeneratedConfigOverride,
   RuleSettings,
@@ -19,10 +15,4 @@ export type {
   TestFramework,
   TestsOption,
 } from './types.js';
-
-/** Creates a native Oxlint configuration with React and JSX accessibility policy. */
-export const createReactConfig = (options: CreateReactConfigOptions) =>
-  createConfig({
-    ...options,
-    react: true,
-  });
+export type { ExtensionFragmentName, ConfigEnv } from './consts.js';

package/src/rules/base.ts

@@ -1,4 +1,11 @@
-const maxComplexity = 30;
+export const maxComplexity = 30;
+export const noUnderscoreDangleOptions = {
+  allow: ['__'],
+  allowAfterThis: true,
+  allowAfterSuper: true,
+  enforceInMethodNames: false,
+};
+export const noUnderscoreDangleRule = ['error', noUnderscoreDangleOptions] as const;
 
 export const base = {
   /**
@@ -452,6 +459,12 @@ export const base = {
    * @see https://eslint.org/docs/latest/rules/no-useless-concat
    */
   'no-useless-concat': 'error',
+  /**
+   * Allow escapes that may be unnecessary but improve regular expression readability.
+   *
+   * @see https://eslint.org/docs/latest/rules/no-useless-escape
+   */
+  'no-useless-escape': 'off',
   /**
    * Disallow redundant return statements.
    *
@@ -822,15 +835,7 @@ export const base = {
    *
    * @see https://eslint.org/docs/latest/rules/no-underscore-dangle
    */
-  'no-underscore-dangle': [
-    'error',
-    {
-      allow: ['__'],
-      allowAfterThis: true,
-      allowAfterSuper: true,
-      enforceInMethodNames: false,
-    },
-  ],
+  'no-underscore-dangle': noUnderscoreDangleRule,
   /**
    * Disallow ternary operators when simpler alternatives exist.
    *

package/src/rules/index.ts

@@ -1,4 +1,4 @@
-export { base } from './base.js';
+export * from './base.js';
 export { browser } from './browser.js';
 export { jsdoc } from './jsdoc.js';
 export { nextjs } from './nextjs.js';