fix(eslint): upgrade deps and add JSDoc comments (#313)

## Summary

This PR includes dependency upgrades for `typescript-eslint` and `lint-staged` after a security audit, along with comprehensive JSDoc documentation for all config files.

## Changes

- Upgraded `@typescript-eslint/eslint-plugin` and `@typescript-eslint/parser` to address audit findings
- Updated `lint-staged` to the latest version
- Added detailed JSDoc comments to all CLI functions and stages
- Documented all config file functions (astro, command, comments, disables, ignores, imports, javascript, jsdoc, jsonc, jsx, markdown, nextjs, node, perfectionist, prettier, react, regexp, sort, svelte, test, toml, typescript, unicorn, vue, yaml)
- Improved type documentation in factory and types files
- Added empty changeset for tracking

## Motivation

1. **Security**: Address security findings from audit by upgrading typescript-eslint packages
2. **Maintainability**: Improve code documentation for better developer experience
3. **Consistency**: Ensure all public APIs have proper JSDoc documentation following best practices



## Summary by CodeRabbit

* **New Features**
  * Added JSDoc plugin support for ESLint configuration.

* **Bug Fixes**
  * Fixed issues after package upgrade.
  * Repositioned React rules to core plugin for consistency.

* **Chores**
  * Updated configuration packages (@mheob/commitlint-config, @mheob/eslint-config) to patch versions.
  * Updated TypeScript ESLint and lint-staged dependencies.

* **Documentation**
  * Enhanced comprehensive documentation for ESLint configuration functions.

Author: mheob

.changeset/breezy-aliens-clap.md

@@ -0,0 +1,6 @@
+---
+'@mheob/commitlint-config': patch
+'@mheob/eslint-config': patch
+---
+
+fix issues after upgrade

.changeset/funny-sloths-live.md

@@ -0,0 +1,2 @@
+---
+---

packages/eslint-config/src/cli/run.ts

@@ -25,8 +25,24 @@ export interface CliRunOptions {
 }
 
 /**
+ * Executes the CLI migration/setup wizard for eslint configuration.
  *
- * @param options
+ * This function guides the user through the setup or migration of ESLint config files,
+ * supporting various frameworks. It checks whether an `eslint.config.js` or `eslint.config.mjs`
+ * already exists in the current working directory and aborts if so. Optionally, it can skip prompts
+ * if `options.yes` or the `SKIP_PROMPT` environment variable is set.
+ *
+ * The flow offers the following stages:
+ *   1. Warn the user and abort if ESLint config already exists.
+ *   2. Prompt (or programmatically resolve, if `yes` is set) for:
+ *      - Whether to continue if there are uncommitted git changes.
+ *      - Which frameworks to include in the setup.
+ *      - Whether to update VSCode settings for recommended integration.
+ *   3. Applies updates by calling helper update stages for `package.json`, ESLint files, and VSCode settings.
+ *   4. Displays a success message describing next steps.
+ *
+ * @param options - CLI run options to control wizard behavior.
+ * @returns Promise that resolves once setup is complete.
  */
 export async function run(options: CliRunOptions = {}): Promise<void> {
 	const argumentSkipPrompt = Boolean(process.env.SKIP_PROMPT) || options.yes;

packages/eslint-config/src/cli/stages/update-eslint-files.ts

@@ -12,8 +12,14 @@ import type { PromptResult } from '../types';
 import { getEslintConfigContent } from '../utils';
 
 /**
+ * Updates the ESLint configuration files based on the user's choices.
  *
- * @param result
+ * This function reads the existing .eslintignore file (if it exists),
+ * processes it to extract ignored patterns, and generates a new ESLint
+ * configuration file based on the selected frameworks.
+ *
+ * @param result - The user's choices from the CLI prompt.
+ * @returns Promise that resolves once the configuration files are updated.
  */
 export async function updateEslintFiles(result: PromptResult): Promise<void> {
 	const cwd = process.cwd();

packages/eslint-config/src/cli/stages/update-package-json.ts

@@ -11,8 +11,13 @@ import type { PromptResult } from '../types';
 import { versionsMap } from '../versions-map.generated';
 
 /**
+ * Updates the package.json file to include the required dependencies for the selected frameworks.
  *
- * @param result
+ * This function reads the existing package.json file, updates the @mheob/eslint-config
+ * dependency version, and adds any additional dependencies required by the selected frameworks.
+ *
+ * @param result - The user's choices from the CLI prompt.
+ * @returns Promise that resolves once the package.json file is updated.
  */
 export async function updatePackageJson(result: PromptResult): Promise<void> {
 	const cwd = process.cwd();

packages/eslint-config/src/cli/stages/update-vscode-settings.ts

@@ -10,8 +10,13 @@ import { vscodeSettingsString } from '../constants';
 import type { PromptResult } from '../types';
 
 /**
+ * Updates the VSCode settings file to include the recommended ESLint configuration.
  *
- * @param result
+ * This function creates or updates the .vscode/settings.json file with the recommended
+ * ESLint configuration based on the user's choices.
+ *
+ * @param result - The user's choices from the CLI prompt.
+ * @returns Promise that resolves once the settings file is updated.
  */
 export async function updateVscodeSettings(result: PromptResult): Promise<void> {
 	const cwd = process.cwd();

packages/eslint-config/src/configs/astro.ts

@@ -3,8 +3,14 @@ import type { OptionsFiles, OptionsOverrides, TypedFlatConfigItem } from '../typ
 import { ensurePackages, interopDefault } from '../utils';
 
 /**
+ * Configures the ESLint rules for Astro projects.
  *
- * @param options
+ * This function sets up the necessary ESLint plugins and parsers for Astro projects,
+ * including the `eslint-plugin-astro` and `astro-eslint-parser`. It also configures
+ * the language options for the Astro files, including the globals, parser, and parser options.
+ *
+ * @param options - The options for configuring the Astro ESLint rules.
+ * @returns Promise that resolves once the Astro ESLint rules are configured.
  */
 export async function astro(
 	options: OptionsFiles & OptionsOverrides = {},

packages/eslint-config/src/configs/command.ts

@@ -3,7 +3,13 @@ import createCommand from 'eslint-plugin-command/config';
 import type { TypedFlatConfigItem } from '../types';
 
 /**
+ * Configures the ESLint rules for command line interface (CLI) projects.
  *
+ * This function sets up the necessary ESLint plugin for command line interface projects,
+ * including the `eslint-plugin-command`. It also configures the language options for the
+ * command line interface files, including the parser, parser options, and source type.
+ *
+ * @returns Promise that resolves once the command line interface ESLint rules are configured.
  */
 export async function command(): Promise<TypedFlatConfigItem[]> {
 	return [

packages/eslint-config/src/configs/comments.ts

@@ -2,7 +2,14 @@ import { pluginComments } from '../plugins';
 import type { TypedFlatConfigItem } from '../types';
 
 /**
+ * Configures the ESLint rules for comments.
  *
+ * This function sets up the necessary ESLint plugin for comments,
+ * including the `eslint-plugin-eslint-comments`. It also configures
+ * the rules for comments, including the no-aggregating-enable,
+ * no-duplicate-disable, no-unlimited-disable, and no-unused-enable rules.
+ *
+ * @returns Promise that resolves once the comments ESLint rules are configured.
  */
 export async function comments(): Promise<TypedFlatConfigItem[]> {
 	return [

packages/eslint-config/src/configs/disables.ts

@@ -2,7 +2,17 @@ import { GLOB_SRC, GLOB_SRC_EXT, GLOB_TSX } from '../globs';
 import type { TypedFlatConfigItem } from '../types';
 
 /**
+ * Configures the ESLint rules for disables.
  *
+ * This function sets up the necessary ESLint rules for disables,
+ * including the rules for disables, including the no-import-dist,
+ * no-import-node-modules-by-path, no-top-level-await, no-console,
+ * unicorn/no-process-exit, no-require-imports, antfu/no-top-level-await,
+ * no-console, ts/explicit-function-return-type, sort-imports,
+ * eslint-comments/no-unlimited-disable, no-restricted-syntax,
+ * unused-imports/no-unused-vars.
+ *
+ * @returns Promise that resolves once the disables ESLint rules are configured.
  */
 export async function disables(): Promise<TypedFlatConfigItem[]> {
 	return [