@favorodera/eslint-config 0.0.3 → 0.0.4

package/dist/index.mjs

@@ -4,17 +4,32 @@ import { mergeProcessors, processorPassThrough } from "eslint-merge-processors";
 import vueBlocksProcessor from "eslint-processor-vue-blocks";
 import globals from "globals";
 //#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/**",
@@ -60,9 +75,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;
@@ -72,15 +87,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 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 || {}));
 }
@@ -95,6 +115,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 = defu(options, vueDefaults);
 	const sfcBlocks = resolveOptions(resolved.sfcBlocks, sfcBlocksDefaults);
@@ -163,7 +189,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 = []) {
@@ -179,6 +205,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 = defu(options, importsDefaults);
 	const [importPlugin, unusedImportsPlugin] = await Promise.all([importModule(import("eslint-plugin-import-lite")), importModule(import("eslint-plugin-unused-imports"))]);
@@ -220,9 +252,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 = defu(options, javascriptDefaults);
@@ -263,6 +296,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 = defu(options, markdownDefaults);
 	const markdownPlugin = await importModule(import("@eslint/markdown"));
@@ -334,6 +373,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 = defu(options, stylisticDefaults);
 	const stylePlugin = await importModule(import("@stylistic/eslint-plugin"));
@@ -385,9 +430,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 = defu(options, tailwindDefaults);
@@ -415,9 +461,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 = defu(options, typescriptDefaults);
@@ -452,6 +499,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 = defu(options, jsoncDefaults);
 	return [
@@ -729,11 +782,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 = 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 = [];
@@ -746,7 +849,8 @@ function factory(options = {}) {
 		imports,
 		markdown,
 		javascript,
-		jsonc
+		jsonc,
+		jsdoc
 	};
 	for (const [key, configFunction] of Object.entries(configFunctions)) {
 		const configOption = options[key];

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@favorodera/eslint-config",
   "type": "module",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": false,
-  "description": "A starter for creating a TypeScript package.",
+  "description": "Opinionated, type-safe flat ESLint configuration factory for Vue, TypeScript, Tailwind, and more.",
   "author": "Favour Emeka <favorodera@gmail.com>",
   "license": "MIT",
   "funding": "https://github.com/sponsors/favorodera",
@@ -56,6 +56,7 @@
     "eslint-merge-processors": "^2.0.0",
     "eslint-plugin-better-tailwindcss": "^4.5.0",
     "eslint-plugin-import-lite": "^0.6.0",
+    "eslint-plugin-jsdoc": "^63.0.2",
     "eslint-plugin-jsonc": "^3.2.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "eslint-plugin-vue": "^10.9.2",