@favorodera/eslint-config 0.0.3 → 0.0.4

package/README.md

@@ -1 +1,144 @@
-# Eslint Config
+<div align="center">
+  <h1>ESLint Config</h1>
+  <p><strong>Opinionated, type-safe flat ESLint configuration factory</strong></p>
+  <p>
+    <a href="https://github.com/favorodera/eslint-config/blob/main/LICENSE"><img src="https://img.shields.io/github/license/favorodera/eslint-config.svg?style=plastic&label=License&color=blue" alt="License"></a>
+    <a href="https://github.com/favorodera/eslint-config/stargazers"><img src="https://img.shields.io/github/stars/favorodera/eslint-config.svg?style=plastic&label=Stars&color=blue" alt="GitHub Stars"></a>
+    <a href="https://www.npmjs.com/package/@favorodera/eslint-config"><img src="https://img.shields.io/npm/v/@favorodera/eslint-config.svg?style=plastic&label=Version&color=blue" alt="NPM Version"></a>
+  </p>
+</div>
+
+<br>
+
+An opinionated, highly customizable ESLint flat configuration factory. It provides a seamless, type-safe linting experience out-of-the-box for Vue, TypeScript, Tailwind CSS, Markdown, and more.
+
+## Features
+
+- **Flat Config First** — Built from the ground up for ESLint's new flat config system.
+- **TypeScript Support** — Robust linting for TypeScript out of the box.
+- **Vue Integration** — First-class support for Vue 3 single-file components.
+- **Stylistic Rules** — Consistent code styling powered by ESLint Stylistic.
+- **Tailwind CSS** — Built-in rules for Tailwind classes sorting and best practices.
+- **Auto-formatting** — Formats JSON, JSONC, Markdown, and JS/TS automatically.
+- **Type-safe Rules** — Rules are generated with JSDoc comments, giving you rich auto-complete and descriptions right in your IDE.
+- **Highly Configurable** — Easily enable or disable specific rulesets based on your project's needs.
+
+## Supported Configs
+
+The following configurations are bundled and enabled by default (they can be individually disabled or customized):
+
+- **JavaScript** — Core ESLint rules (`@eslint/js`)
+- **TypeScript** — Type-aware linting (`typescript-eslint`)
+- **Vue** — Single-file component support (`eslint-plugin-vue`, `vue-eslint-parser`)
+- **Stylistic** — Formatting rules (`@stylistic/eslint-plugin`)
+- **Tailwind CSS** — Utility class linting and sorting (`eslint-plugin-better-tailwindcss`)
+- **Imports** — Auto-sorting and unused imports removal (`eslint-plugin-import-lite`, `eslint-plugin-unused-imports`)
+- **Markdown** — Linting for markdown files and embedded code blocks (`@eslint/markdown`)
+- **JSON/JSONC/JSON5** — Formatting and sorting for JSON files like `package.json` (`eslint-plugin-jsonc`)
+- **JSDoc** — Standardized comment formatting (`eslint-plugin-jsdoc`)
+
+## Usage
+
+### Install
+
+<details>
+<summary><b>pnpm</b></summary>
+
+```bash
+pnpm install -D eslint @favorodera/eslint-config
+```
+</details>
+
+<details>
+<summary><b>npm</b></summary>
+
+```bash
+npm install -D eslint @favorodera/eslint-config
+```
+</details>
+
+<details>
+<summary><b>yarn</b></summary>
+
+```bash
+yarn add -D eslint @favorodera/eslint-config
+```
+</details>
+
+<details>
+<summary><b>bun</b></summary>
+
+```bash
+bun add -D eslint @favorodera/eslint-config
+```
+</details>
+
+### Configure
+
+Create an `eslint.config.mjs` (or `eslint.config.ts`) file in the root of your project. Since all configurations are enabled by default, you only need to pass options if you want to disable or customize something:
+
+```javascript
+import { factory } from '@favorodera/eslint-config'
+
+export default factory({
+  // All configs are true by default!
+  
+  // Example: Disable tailwind if you aren't using it
+  tailwind: false,
+
+  // Example: Customize specific rulesets
+  stylistic: {
+    settings: {
+      quotes: 'double',
+      indent: 4
+    }
+  }
+})
+```
+
+## Development
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) v22 or later
+- [pnpm](https://pnpm.io/installation) v11 or later
+
+### Getting Started
+
+```bash
+# Install all dependencies
+pnpm install
+
+# Start compiler in watch mode and open ESLint config inspector
+pnpm dev
+
+# Build the project
+pnpm build
+
+# Lint, typecheck, build, and test in one go
+pnpm ready
+```
+
+### Useful Commands
+
+| Command | What it does |
+|---------|-------------|
+| `pnpm dev` | Generates types, starts watch mode, and opens `@eslint/config-inspector` |
+| `pnpm build` | Production build using `tsdown` |
+| `pnpm script:generate-rules-types` | Extracts and generates type definitions for all ESLint rules |
+| `pnpm lint` | Lint the repository |
+| `pnpm typecheck` | Type-check without emitting files |
+| `pnpm test` | Run test suites with Vitest |
+| `pnpm ready` | Full pipeline: install → build → lint → typecheck → test |
+
+## Contributing & Issues
+
+Feel free to open an issue or submit a pull request if you'd like to improve the rules, add new features, or fix a bug. Please ensure you run `pnpm ready` before submitting your PR to make sure tests and linting pass.
+
+## Inspiration
+
+This project takes heavy inspiration from [antfu/eslint-config](https://github.com/antfu/eslint-config) and similar modern ESLint presets, adapting their best patterns into a custom set of opinionated rules.
+
+## License
+
+[MIT](./LICENSE) &copy; [Favour Emeka](https://github.com/favorodera)

package/dist/index.cjs

@@ -29,17 +29,32 @@ eslint_processor_vue_blocks = __toESM(eslint_processor_vue_blocks, 1);
 let globals = require("globals");
 globals = __toESM(globals, 1);
 //#region src/globs.ts
+/** Glob pattern for matching JavaScript files */
 const jsGlob = "**/*.{js,cjs,mjs}";
+/** Glob pattern for matching TypeScript files */
 const tsGlob = "**/*.{ts,cts,mts}";
+/** Glob pattern for matching Vue single-file components */
 const vueGlob = "**/*.vue";
+/** Glob pattern for matching Markdown files */
 const mdGlob = "**/*.md";
+/** Glob pattern for matching virtual files extracted from Markdown */
 const mdInMdGlob = "**/*.md/*.md";
+/** Glob pattern for matching code blocks embedded in Markdown files */
 const codeInMdGlob = "**/*.md/**/*.{js,cjs,mjs,ts,cts,mts,vue}";
+/** Glob pattern for matching JSON files */
 const jsonGlob = "**/*.json";
+/** Glob pattern for matching JSON5 files */
 const json5Glob = "**/*.json5";
+/** Glob pattern for matching JSON with Comments files */
 const jsoncGlob = "**/*.jsonc";
+/** Glob patterns for matching TypeScript configuration files */
 const tsConfigGlob = ["**/tsconfig.json", "**/tsconfig.*.json"];
+/** Glob pattern for matching package.json files */
 const packageJsonGlob = "**/package.json";
+/**
+* Common glob patterns for files and directories that should be ignored by ESLint.
+* Includes node_modules, build outputs, lock files, temporary files, and tool-specific caches.
+*/
 const ignoresGlob = [
 	"**/node_modules/**",
 	"**/dist/**",
@@ -85,9 +100,9 @@ const ignoresGlob = [
 *
 * Handles both ESM modules (which wrap exports under `.default`) and
 * CJS / plain-object modules uniformly.
-*
-* @param module - A module or a promise that resolves to one
-* @returns The `.default` export if it exists, otherwise the module itself
+* @template TModule The type of the module being imported.
+* @param module A module or a promise that resolves to one.
+* @returns The `.default` export if it exists, otherwise the module itself.
 */
 async function importModule(module) {
 	const resolved = await module;
@@ -97,15 +112,20 @@ async function importModule(module) {
 /**
 * Normalize boolean or options value into merged options or null.
 * Returns null when the input is false or undefined.
-*
-* @param value - boolean, options object, or undefined
-* @param defaults - defaults to merge with
-* @returns merged options or false
+* @template TOptions The type of the options object.
+* @param value The configuration value, which can be a boolean, an options object, or undefined.
+* @param defaults The default options to merge with if `value` is true or an object.
+* @returns The merged options object, or false if the feature is disabled.
 */
 function resolveOptions(value, defaults) {
 	if (!value) return false;
 	return (0, defu.defu)(value === true ? {} : value, defaults);
 }
+/**
+* Extracts and merges the rules from multiple ESLint configuration arrays.
+* @param configArrays Rest parameter representing multiple arrays of ESLint flat config items.
+* @returns A single object containing all the merged rules from the provided configurations.
+*/
 function extractRules(...configArrays) {
 	return Object.assign({}, ...configArrays.flat().map((config) => config?.rules || {}));
 }
@@ -120,6 +140,12 @@ const vueDefaults = {
 	files: [vueGlob],
 	sfcBlocks: sfcBlocksDefaults
 };
+/**
+* Constructs the flat config items for Vue linting, setting up the custom template parser,
+* Vue block processors, and rules to enforce recommended component syntax.
+* @param options Vue configuration options.
+* @returns Promise resolving to Vue ESLint config items.
+*/
 async function vue(options) {
 	const resolved = (0, defu.defu)(options, vueDefaults);
 	const sfcBlocks = resolveOptions(resolved.sfcBlocks, sfcBlocksDefaults);
@@ -188,7 +214,7 @@ async function vue(options) {
 const defaultPatterns = ignoresGlob;
 /**
 * Globs for ignoring files and directories from ESLint scanning.
-* @param patterns - Additional ignore patterns or a function to modify the defaults.
+* @param patterns Additional ignore patterns or a function to modify the defaults.
 * @returns An array containing the ignore flat config item.
 */
 function ignores(patterns = []) {
@@ -204,6 +230,12 @@ const importsDefaults = { files: [
 	tsGlob,
 	vueGlob
 ] };
+/**
+* Constructs the flat config items for imports linting, providing plugin setup and
+* specific rules to enforce consistent import ordering and unused variable checks.
+* @param options Configuration options for imports linting.
+* @returns Promise resolving to imports ESLint config items.
+*/
 async function imports(options) {
 	const resolved = (0, defu.defu)(options, importsDefaults);
 	const [importPlugin, unusedImportsPlugin] = await Promise.all([importModule(import("eslint-plugin-import-lite")), importModule(import("eslint-plugin-unused-imports"))]);
@@ -245,9 +277,10 @@ const javascriptDefaults = { files: [
 	vueGlob
 ] };
 /**
-* Javascript linting via `eslint`
-* @param options - Javascript configuration options
-* @returns Promise resolving to javascript ESLint config items
+* Constructs the flat config items for core JavaScript linting, setting up the required
+* language options, globals, and recommended baseline rules.
+* @param options Javascript configuration options.
+* @returns Promise resolving to javascript ESLint config items.
 */
 async function javascript(options) {
 	const resolved = (0, defu.defu)(options, javascriptDefaults);
@@ -288,6 +321,12 @@ const markdownDefaults = {
 	files: [mdGlob],
 	gfm: true
 };
+/**
+* Constructs the flat config items for Markdown linting, extracting and linting
+* embedded code blocks within the document according to specified rules.
+* @param options Markdown configuration options.
+* @returns Promise resolving to Markdown ESLint config items.
+*/
 async function markdown(options) {
 	const resolved = (0, defu.defu)(options, markdownDefaults);
 	const markdownPlugin = await importModule(import("@eslint/markdown"));
@@ -359,6 +398,12 @@ const stylisticDefaults = {
 		vueGlob
 	]
 };
+/**
+* Constructs the flat config items for Stylistic linting, applying customized
+* formatting settings such as quotes, indentation, and spacing.
+* @param options Stylistic configuration options.
+* @returns Promise resolving to stylistic ESLint config items.
+*/
 async function stylistic(options) {
 	const resolved = (0, defu.defu)(options, stylisticDefaults);
 	const stylePlugin = await importModule(import("@stylistic/eslint-plugin"));
@@ -410,9 +455,10 @@ const tailwindDefaults = {
 	settings: { detectComponentClasses: true }
 };
 /**
-* Tailwind linting via `eslint-plugin-better-tailwindcss`.
-* @param options - Tailwind configuration options
-* @returns Promise resolving to Tailwind ESLint config items
+* Constructs the flat config items for Tailwind CSS linting, providing custom settings
+* to parse and lint utility classes, and enforcing consistent ordering.
+* @param options Tailwind configuration options.
+* @returns Promise resolving to Tailwind ESLint config items.
 */
 async function tailwind(options) {
 	const resolved = (0, defu.defu)(options, tailwindDefaults);
@@ -440,9 +486,10 @@ async function tailwind(options) {
 //#region src/configs/typescript.ts
 const typescriptDefaults = { files: [tsGlob] };
 /**
-* Typescript linting via `typescript-eslint`.
-* @param options - TypeScript configuration options
-* @returns Array of TypeScript ESLint config items
+* Constructs the flat config items for TypeScript linting, initializing the parser
+* and extending the recommended and strict type-aware rule sets.
+* @param options TypeScript configuration options.
+* @returns Promise resolving to TypeScript ESLint config items.
 */
 async function typescript(options) {
 	const resolved = (0, defu.defu)(options, typescriptDefaults);
@@ -477,6 +524,12 @@ const jsoncDefaults = { files: [
 	jsoncGlob,
 	jsonGlob
 ] };
+/**
+* Constructs the flat config items for JSON, JSON5, and JSONC linting, setting up
+* the custom parser, rule validations, and sorting rules for package.json/tsconfig.json.
+* @param options JSONC configuration options.
+* @returns Promise resolving to JSONC ESLint config items.
+*/
 async function jsonc(options) {
 	const resolved = (0, defu.defu)(options, jsoncDefaults);
 	return [
@@ -754,11 +807,61 @@ async function jsonc(options) {
 	];
 }
 //#endregion
+//#region src/configs/jsdoc.ts
+const jsdocDefaults = { files: [
+	jsGlob,
+	tsGlob,
+	vueGlob
+] };
+/**
+* Constructs the flat config items for JSDoc linting, ensuring comments follow
+* proper styling, parameter checks, and types alignment.
+* @param options JSDoc configuration options.
+* @returns Promise resolving to JSDoc ESLint config items.
+*/
+async function jsdoc(options) {
+	const resolved = (0, defu.defu)(options, jsdocDefaults);
+	const jsdocPlugin = await importModule(import("eslint-plugin-jsdoc"));
+	const baseRules = {
+		...jsdocPlugin.configs["flat/recommended-typescript-error"]?.rules,
+		...jsdocPlugin.configs["flat/stylistic-typescript-error"]?.rules
+	};
+	return [{
+		name: "favorodera/jsdoc/setup",
+		plugins: { jsdoc: jsdocPlugin }
+	}, {
+		name: "favorodera/tailwind/rules",
+		files: resolved.files,
+		rules: {
+			...baseRules || {},
+			"jsdoc/check-access": "warn",
+			"jsdoc/check-param-names": "warn",
+			"jsdoc/check-property-names": "warn",
+			"jsdoc/check-types": "warn",
+			"jsdoc/empty-tags": "warn",
+			"jsdoc/implements-on-classes": "warn",
+			"jsdoc/no-defaults": "warn",
+			"jsdoc/no-multi-asterisks": "warn",
+			"jsdoc/require-param-name": "warn",
+			"jsdoc/require-property": "warn",
+			"jsdoc/require-property-description": "warn",
+			"jsdoc/require-property-name": "warn",
+			"jsdoc/require-returns-check": "warn",
+			"jsdoc/require-returns-description": "warn",
+			"jsdoc/require-yields-check": "warn",
+			"jsdoc/check-alignment": "warn",
+			"jsdoc/multiline-blocks": "warn",
+			...resolved.overrides
+		}
+	}];
+}
+//#endregion
 //#region src/factory.ts
 /**
-* Factory to create a flat ESLint config
-* @param options - Configuration options for the ESLint config
-* @returns Flat ESLint config composer
+* Factory to create a flat ESLint config.
+* It builds an ESLint config by sequentially adding sub-configs based on the provided options.
+* @param options Configuration options for enabling/disabling or configuring specific rule sets.
+* @returns A flat config composer instance that can be exported directly or further modified.
 */
 function factory(options = {}) {
 	const configs = [];
@@ -771,7 +874,8 @@ function factory(options = {}) {
 		imports,
 		markdown,
 		javascript,
-		jsonc
+		jsonc,
+		jsdoc
 	};
 	for (const [key, configFunction] of Object.entries(configFunctions)) {
 		const configOption = options[key];