@vijayhardaha/dev-config 2.0.0 → 2.0.1

package/README.md

@@ -27,7 +27,7 @@ bun install @vijayhardaha/dev-config --dev
 ### Install Required Packages
 
 ```bash
-bun add --dev eslint prettier @prettier/plugin-xml eslint-plugin-prettier globals eslint-plugin-jsdoc eslint-plugin-import-x typescript typescript-eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser
+bun add --dev eslint @eslint/compat prettier @prettier/plugin-xml eslint-plugin-prettier globals eslint-plugin-jsdoc eslint-plugin-import-x typescript typescript-eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser
 ```
 
 ### Install Optional Packages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vijayhardaha/dev-config",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Reusable development configurations for Next.js + TypeScript projects",
   "scripts": {
     "lint": "eslint .",
@@ -74,10 +74,8 @@
     "stylelint-order": "^8.1.1",
     "vitest": "^4.1.7"
   },
-  "dependencies": {
-    "@eslint/compat": "^2.1.0"
-  },
   "peerDependencies": {
+    "@eslint/compat": ">=2",
     "@prettier/plugin-xml": ">=3",
     "@typescript-eslint/eslint-plugin": ">=8",
     "@typescript-eslint/parser": ">=8",

package/src/eslint/lib/build-config.js

@@ -11,12 +11,127 @@ import { commonRules } from './rules.js';
 import { commonParser } from './setup.js';
 
 /**
- * Builds a common ESLint configuration with support for various options.
+ * Filters and flattens conditional plugins based on user options.
+ *
+ * @param {object} conditionalPlugins - Plugin map keyed by option name.
+ * @param {object} options - User-provided options.
+ *
+ * @returns {object[]} Flat config objects for enabled plugins.
+ */
+const getEnabledPlugins = (conditionalPlugins, options) =>
+  Object.entries(conditionalPlugins)
+    .filter(([key]) => options[key])
+    .flatMap(([, value]) => (Array.isArray(value) ? value : [value]));
+
+/**
+ * Flattens a mixed list of config arrays and objects into a flat config array.
+ *
+ * @param {(Array|object)[]} plugins - Mixed list of flat config arrays and objects.
+ *
+ * @returns {object[]} Flattened config array.
+ */
+const flattenPlugins = (plugins) => {
+  const result = [];
+
+  for (const plugin of plugins) {
+    if (Array.isArray(plugin)) {
+      result.push(...plugin);
+    } else if (typeof plugin === 'object' && plugin !== null) {
+      result.push(plugin);
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Wraps plugin rules with fixupPluginRules for ESLint 10 backward compatibility.
+ *
+ * @param {object[]} flatConfigs - Flat config array.
+ *
+ * @returns {object[]} Config array with wrapped plugin rules.
+ */
+const fixPlugins = (flatConfigs) =>
+  flatConfigs.map((config) => {
+    if (!config.plugins) return config;
+
+    const fixed = { ...config, plugins: {} };
+
+    for (const [name, plugin] of Object.entries(config.plugins)) {
+      fixed.plugins[name] = fixupPluginRules(plugin);
+    }
+
+    return fixed;
+  });
+
+/**
+ * Merges user-provided global ignores with the common defaults.
+ *
+ * @param {string[]|undefined} userGlobalIgnores - User-provided global ignore patterns.
+ *
+ * @returns {object} ESLint ignores config object.
+ */
+const mergeGlobalIgnores = (userGlobalIgnores) =>
+  Array.isArray(userGlobalIgnores) ? globalIgnores(userGlobalIgnores) : globalIgnores();
+
+/**
+ * Builds the main ESLint config object with language options, settings, and rules.
+ *
+ * @param {object} ctx - Context object with all config parameters.
+ * @param {string[]} ctx.filePatterns - File patterns to apply the config to.
+ * @param {object} ctx.opts - Resolved user options.
+ * @param {boolean} ctx.typescript - Enable TypeScript support.
+ * @param {object} ctx.extraLanguageOptions - Additional language options.
+ * @param {object} ctx.parserOptions - Parser options.
+ * @param {object} ctx.extraSettings - Additional settings.
+ * @param {object} ctx.extraRules - Additional rules.
+ *
+ * @returns {import('eslint').Linter.Config} ESLint config object.
+ */
+const buildConfigObject = ({
+  filePatterns,
+  opts,
+  typescript,
+  extraLanguageOptions,
+  parserOptions,
+  extraSettings,
+  extraRules,
+}) => {
+  const { ignores, rules, settings, languageOptions, extend } = opts;
+
+  return {
+    files: [...filePatterns],
+    ...(ignores && { ignores }),
+    ...(typescript && { plugins: { '@typescript-eslint': tsEslint.plugin } }),
+    languageOptions: {
+      ...commonLanguageOptions,
+      ...(typescript && commonParser),
+      ...extraLanguageOptions,
+      ...languageOptions,
+      ...(typescript && { parserOptions: { tsconfigRootDir: process.cwd(), ...parserOptions } }),
+    },
+    settings: {
+      ...(opts.importOrder && { 'import-x/resolver': { typescript: {} } }),
+      ...(opts.jsdoc && { jsdoc: { mode: 'typescript' } }),
+      ...extraSettings,
+      ...settings,
+    },
+    rules: {
+      ...commonRules({ prettier: opts.prettier, importOrder: opts.importOrder, typescript, jsdoc: opts.jsdoc }),
+      ...extraRules,
+      ...rules,
+    },
+    ...extend,
+  };
+};
+
+/**
+ * Builds a flat ESLint configuration with support for various options.
  *
  * @param {object} config - Configuration options.
  * @param {string[]} config.files - File patterns to apply the config to.
  * @param {(Array|object)[]} config.builtinPlugins - Flat config arrays or objects to always include.
- * @param {object} config.conditionalPlugins - Conditional plugins based on options (e.g., { react: true, a11y: true }).
+ * @param {object} config.conditionalPlugins - Conditional plugins based on options.
  * @param {object} [config.languageOptions] - Additional language options.
  * @param {object} [config.parserOptions] - Parser options.
  * @param {object} [config.settings] - Settings object.
@@ -37,79 +152,31 @@ export const buildConfig = ({
   options = {},
   typescript = false,
 }) => {
-  const {
-    prettier = true,
-    importOrder = true,
-    jsdoc = true,
-    ignores,
-    rules,
-    settings,
-    languageOptions,
-    plugins: userPlugins,
-    globalIgnores: userGlobalIgnores,
-    extend,
-  } = options;
-
-  // ---- Build extends configs ----
-  const conditionalPluginList = Object.entries(conditionalPlugins)
-    .filter(([key]) => options[key])
-    .flatMap(([, value]) => (Array.isArray(value) ? value : [value]));
+  const opts = { prettier: true, importOrder: true, jsdoc: true, ...options };
+
+  const conditionalPluginList = getEnabledPlugins(conditionalPlugins, opts);
 
-  const builtPlugins = [
+  const mergedPlugins = [
     ...builtinPlugins,
-    importOrder && importX.flatConfigs.recommended,
-    jsdoc && jsdocPlugin.configs['flat/recommended'],
-    prettier && prettierRecommended,
+    opts.importOrder && importX.flatConfigs.recommended,
+    opts.jsdoc && jsdocPlugin.configs['flat/recommended'],
+    opts.prettier && prettierRecommended,
     ...conditionalPluginList,
+    ...(opts.plugins || []),
   ].filter(Boolean);
 
-  const plugins = [...builtPlugins, ...(userPlugins || [])];
+  const flatConfigs = flattenPlugins(mergedPlugins);
+  const fixedConfigs = fixPlugins(flatConfigs);
+  const mergedGlobalIgnores = mergeGlobalIgnores(opts.globalIgnores);
 
-  // ---- Build config object ----
-  const configObject = {
-    files: [...filePatterns],
-    ...(ignores && { ignores }),
-    ...(typescript && { plugins: { '@typescript-eslint': tsEslint.plugin } }),
-    languageOptions: {
-      ...commonLanguageOptions,
-      ...(typescript && commonParser),
-      ...extraLanguageOptions,
-      ...languageOptions,
-      ...(typescript && { parserOptions: { tsconfigRootDir: process.cwd(), ...parserOptions } }),
-    },
-    settings: {
-      ...(importOrder && { 'import-x/resolver': { typescript: {} } }),
-      ...(jsdoc && { jsdoc: { mode: 'typescript' } }),
-      ...extraSettings,
-      ...settings,
-    },
-    rules: { ...commonRules({ prettier, importOrder, typescript, jsdoc }), ...extraRules, ...rules },
-    ...extend,
-  };
-
-  // Merge user global ignores with common global ignores
-  const mergedGlobalIgnores = Array.isArray(userGlobalIgnores) ? globalIgnores(userGlobalIgnores) : globalIgnores();
-
-  // Collect all flat configs (arrays spread, objects added directly)
-  const flatConfigs = [];
-
-  for (const plugin of plugins) {
-    if (Array.isArray(plugin)) {
-      flatConfigs.push(...plugin);
-    } else if (typeof plugin === 'object' && plugin !== null) {
-      flatConfigs.push(plugin);
-    }
-  }
-
-  // Wrap plugins with fixupPluginRules for ESLint 10 backward compatibility
-  // (addresses removed APIs like context.getFilename in eslint-plugin-react)
-  const fixedConfigs = flatConfigs.map((config) => {
-    if (!config.plugins) return config;
-    const fixed = { ...config, plugins: {} };
-    for (const [name, plugin] of Object.entries(config.plugins)) {
-      fixed.plugins[name] = fixupPluginRules(plugin);
-    }
-    return fixed;
+  const configObject = buildConfigObject({
+    filePatterns,
+    opts,
+    typescript,
+    extraLanguageOptions,
+    parserOptions,
+    extraSettings,
+    extraRules,
   });
 
   return defineConfig([...mergedGlobalIgnores, ...fixedConfigs, configObject]);

package/src/eslint/lib/rules.js

@@ -1,3 +1,72 @@
+// ---- JSDoc Rules: enforce documentation on public/exported APIs ----
+
+/**
+ * JSDoc rules that enforce documentation presence on public/exported APIs.
+ * Covers `@param`, `@returns`, `@throws`, `@description`, and `@property-description`.
+ *
+ * @type {object}
+ */
+const JSDOC_REQUIRE_RULES = {
+  'jsdoc/require-jsdoc': [
+    'error',
+    {
+      publicOnly: true,
+      require: {
+        FunctionDeclaration: true,
+        MethodDefinition: true,
+        ClassDeclaration: true,
+        ArrowFunctionExpression: true,
+      },
+    },
+  ],
+  'jsdoc/require-description': 'error',
+  'jsdoc/require-param': 'error',
+  'jsdoc/require-param-name': 'error',
+  'jsdoc/require-param-description': 'error',
+  'jsdoc/require-param-type': 'error',
+  'jsdoc/require-returns': 'error',
+  'jsdoc/require-returns-description': 'error',
+  'jsdoc/require-returns-type': 'error',
+  'jsdoc/require-throws': 'error',
+  'jsdoc/require-property-description': 'warn',
+};
+
+/**
+ * JSDoc rules that validate tag names, types, and undefined type references.
+ *
+ * @type {object}
+ */
+const JSDOC_CORRECTNESS_RULES = {
+  'jsdoc/check-tag-names': 'error',
+  'jsdoc/no-undefined-types': ['error', { definedTypes: ['JSX.Element'] }],
+  'jsdoc/valid-types': 'error',
+};
+
+/**
+ * JSDoc rules that enforce consistent formatting and tag ordering.
+ *
+ * @type {object}
+ */
+const JSDOC_STYLE_RULES = {
+  'jsdoc/tag-lines': ['error', 'any', { startLines: 1, endLines: 0, applyToEndTag: true }],
+  'jsdoc/check-alignment': 'error',
+  'jsdoc/check-indentation': 'off',
+  'jsdoc/sort-tags': [
+    'warn',
+    {
+      tagSequence: [
+        { tags: ['description'] },
+        { tags: ['template'] },
+        { tags: ['param'] },
+        { tags: ['returns'] },
+        { tags: ['example'] },
+      ],
+    },
+  ],
+  'jsdoc/no-types': 'off',
+  'jsdoc/informative-docs': 'off',
+};
+
 /**
  * Creates JSDoc rules for enforcing documentation on public/exported APIs.
  *
@@ -6,72 +75,7 @@
  * @returns {object} JSDoc ESLint rules object.
  */
 const jsdocRules = (jsdoc = true) =>
-  jsdoc
-    ? {
-        // ---- JSDoc Rules for PUBLIC / EXPORTED APIs ----
-        'jsdoc/require-jsdoc': [
-          'error',
-          {
-            publicOnly: true,
-            require: {
-              FunctionDeclaration: true,
-              MethodDefinition: true,
-              ClassDeclaration: true,
-              ArrowFunctionExpression: true,
-            },
-          },
-        ],
-
-        // Descriptions must exist and be meaningful
-        'jsdoc/require-description': 'error',
-
-        // Params must be fully documented
-        'jsdoc/require-param': 'error',
-        'jsdoc/require-param-name': 'error',
-        'jsdoc/require-param-description': 'error',
-        'jsdoc/require-param-type': 'error',
-
-        // Returns must be documented
-        'jsdoc/require-returns': 'error',
-        'jsdoc/require-returns-description': 'error',
-        'jsdoc/require-returns-type': 'error',
-
-        // Throws must be documented
-        'jsdoc/require-throws': 'error',
-
-        // Strict correctness
-        'jsdoc/check-tag-names': 'error',
-        'jsdoc/no-undefined-types': ['error', { definedTypes: ['JSX.Element'] }],
-        'jsdoc/valid-types': 'error',
-
-        // Enforce clean structure
-        'jsdoc/tag-lines': ['error', 'any', { startLines: 1, endLines: 0, applyToEndTag: true }],
-
-        'jsdoc/check-alignment': 'error',
-        'jsdoc/check-indentation': 'off',
-
-        // Optional but powerful for large teams
-        'jsdoc/sort-tags': [
-          'warn',
-          {
-            tagSequence: [
-              { tags: ['description'] },
-              { tags: ['template'] },
-              { tags: ['param'] },
-              { tags: ['returns'] },
-              { tags: ['example'] },
-            ],
-          },
-        ],
-
-        // Avoid useless docs
-        'jsdoc/no-types': 'off',
-        'jsdoc/informative-docs': 'off',
-
-        // Enforce property docs in typedef-style (optional)
-        'jsdoc/require-property-description': 'warn',
-      }
-    : {};
+  jsdoc ? { ...JSDOC_REQUIRE_RULES, ...JSDOC_CORRECTNESS_RULES, ...JSDOC_STYLE_RULES } : {};
 
 /**
  * Creates TypeScript-specific rules.

package/src/eslint/lib/rules.test.js

@@ -1,71 +1,61 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeAll } from 'vitest';
 
 // Test suite for the ESLint rules configuration module.
 describe('eslint/lib/rules.js', () => {
-  // Test that the module exports the commonRules function.
-  it('should export commonRules function', async () => {
-    // Dynamically import the rules module to test its exports.
+  let commonRules;
+
+  // Module-level import before tests to reduce duplication.
+  beforeAll(async () => {
     const module = await import('./rules.js');
+    commonRules = module.commonRules;
+  });
 
+  // Test that the module exports the commonRules function.
+  it('should export commonRules function', () => {
     // Verify that commonRules is a function.
-    expect(typeof module.commonRules).toBe('function');
+    expect(typeof commonRules).toBe('function');
   });
 
   // Test that commonRules returns an object containing ESLint rules.
-  it('should return an object with rules', async () => {
-    // Dynamically import the rules module to test its function.
-    const module = await import('./rules.js');
-
+  it('should return an object with rules', () => {
     // Call commonRules with no options to get base rules.
-    const result = module.commonRules();
+    const result = commonRules();
 
     // Verify that the result is an object (ESLint rules config).
     expect(typeof result).toBe('object');
   });
 
   // Test that TypeScript rules are included when typescript option is true.
-  it('should include TypeScript rules when typescript is true', async () => {
-    // Dynamically import the rules module to test its function.
-    const module = await import('./rules.js');
-
+  it('should include TypeScript rules when typescript is true', () => {
     // Call commonRules with typescript option enabled.
-    const result = module.commonRules({ typescript: true });
+    const result = commonRules({ typescript: true });
 
     // Verify that a TypeScript-specific rule is present in the config.
     expect(result['@typescript-eslint/no-unused-vars']).toBeDefined();
   });
 
   // Test that import order rules are included when importOrder option is true.
-  it('should include import order rules when importOrder is true', async () => {
-    // Dynamically import the rules module to test its function.
-    const module = await import('./rules.js');
-
+  it('should include import order rules when importOrder is true', () => {
     // Call commonRules with importOrder option enabled.
-    const result = module.commonRules({ importOrder: true });
+    const result = commonRules({ importOrder: true });
 
     // Verify that the import-x/order rule is present in the config.
     expect(result['import-x/order']).toBeDefined();
   });
 
   // Test that Prettier rules are included when prettier option is true.
-  it('should include Prettier rules when prettier is true', async () => {
-    // Dynamically import the rules module to test its function.
-    const module = await import('./rules.js');
-
+  it('should include Prettier rules when prettier is true', () => {
     // Call commonRules with prettier option enabled.
-    const result = module.commonRules({ prettier: true });
+    const result = commonRules({ prettier: true });
 
     // Verify that the prettier/prettier rule is present in the config.
     expect(result['prettier/prettier']).toBeDefined();
   });
 
   // Test that JSDoc rules are included when jsdoc option is true.
-  it('should include JSDoc rules when jsdoc is true', async () => {
-    // Dynamically import the rules module to test its function.
-    const module = await import('./rules.js');
-
+  it('should include JSDoc rules when jsdoc is true', () => {
     // Call commonRules with jsdoc option enabled.
-    const result = module.commonRules({ jsdoc: true });
+    const result = commonRules({ jsdoc: true });
 
     // Verify that the jsdoc/require-jsdoc rule is present in the config.
     expect(result['jsdoc/require-jsdoc']).toBeDefined();