@dmitryrechkin/eslint-standard 1.1.2 → 1.1.4

package/README.md

@@ -9,6 +9,7 @@ A comprehensive ESLint configuration package with TypeScript support, featuring
 - 🔄 **Automatic Import Sorting**: Organizes imports with type imports and regular imports properly grouped
 - 🏗️ **Class Member Ordering**: Auto-reorders class members by visibility (public → protected → private) and type (fields → constructor → methods)
 - 📝 **JSDoc Alignment**: Automatically fixes JSDoc comment indentation and alignment with proper tab formatting
+- 📑 **JSDoc Requirements**: Enforces comprehensive JSDoc documentation with auto-generation of comment blocks
 - 🧹 **Unused Import Removal**: Automatically detects and removes unused imports
 
 ### **Code Style Enforcement**
@@ -16,6 +17,7 @@ A comprehensive ESLint configuration package with TypeScript support, featuring
 - **Modern JavaScript**: Supports ECMAScript 2020 and newer features
 - **Consistent Formatting**: Enforces Allman brace style, tab indentation, single quotes, and semicolons
 - **Naming Conventions**: Comprehensive naming rules for variables, functions, classes, and more
+- **JSDoc Documentation**: Requires comprehensive documentation for all exported functions, classes, methods, interfaces, types, and enums
 - **Customizable**: Flexible configuration options for different project needs
 
 ## 📦 Installation
@@ -68,7 +70,14 @@ export default eslintStandard({
   rules: {
     // Override or add custom rules
     'no-console': 'warn',
-    'perfectionist/sort-classes': 'off' // Disable auto class member sorting if needed
+    'perfectionist/sort-classes': 'off', // Disable auto class member sorting if needed
+    // Disable JSDoc requirements if needed
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-description': 'off',
+    // Disable type hint requirements (if you prefer TypeScript-only types)
+    'jsdoc/require-param-type': 'off',
+    'jsdoc/require-returns-type': 'off',
+    'jsdoc/no-types': ['error', { contexts: ['any'] }]
   }
 });
 ```
@@ -131,7 +140,10 @@ When you run `eslint --fix`, this configuration will automatically:
 2. **🔄 Reorder Class Members**: Arrange class members by visibility and type:
    - Static properties → Instance properties → Constructor → Static methods → Instance methods
    - Within each group: public → protected → private
-3. **📝 Fix JSDoc Indentation**: Align JSDoc comments with proper tab indentation
+3. **📝 Fix JSDoc Comments**: 
+   - Generate missing JSDoc comment blocks for functions, classes, methods, interfaces, types, and enums
+   - Align JSDoc comments with proper tab indentation
+   - Add parameter and return value placeholders
 4. **🧹 Remove Unused Imports**: Clean up unused import statements
 5. **✨ Format Code**: Apply consistent spacing, quotes, semicolons, and brace styles
 
@@ -195,6 +207,44 @@ export class UserService
 }
 ```
 
+#### JSDoc Documentation with Type Hints
+```typescript
+// ❌ Before - Missing JSDoc
+export function processUser(userData: UserData): ProcessedResult {
+    return process(userData);
+}
+
+// ⚠️ After (auto-fixed) - JSDoc block generated but missing type hints
+/**
+ * 
+ * @param userData
+ * @returns
+ */
+export function processUser(userData: UserData): ProcessedResult {
+    return process(userData);
+}
+
+// ❌ Still fails - Missing type hints and descriptions
+// ESLint errors:
+// - Missing JSDoc @param "userData" type
+// - Missing JSDoc @param "userData" description  
+// - Missing JSDoc @returns type
+// - Missing JSDoc block description
+
+// ✅ Complete JSDoc with type hints (must be added manually)
+/**
+ * Processes user data and returns formatted result.
+ * @param {UserData} userData - The user data to process
+ * @returns {ProcessedResult} The processed user result
+ */
+export function processUser(userData: UserData): ProcessedResult {
+    return process(userData);
+}
+
+// ⚠️ Note: ESLint cannot auto-generate type hints from TypeScript types.
+// Type annotations must be added manually to satisfy the linter requirements.
+```
+
 #### JSDoc Alignment
 ```typescript
 // ❌ Before
@@ -220,6 +270,56 @@ export class UserService
 - **Enum Members**: `UPPER_CASE` or `PascalCase`
 - **Type Parameters**: `PascalCase`
 
+### 📝 JSDoc with Type Hints Requirements
+
+This configuration requires comprehensive JSDoc documentation with type hints:
+
+- **Type Annotations Required**: All parameters and return values must include JSDoc type hints
+- **Description Required**: All functions, parameters, and return values must have descriptions
+- **Auto-generation Limited**: ESLint can generate JSDoc blocks but cannot infer TypeScript types
+- **Manual Completion Needed**: Type hints must be added manually after auto-generation
+
+#### Required JSDoc Format
+
+```javascript
+/**
+ * Function description is required.
+ * @param {string} name - Parameter description is required
+ * @param {number} age - Type hint {number} is required
+ * @returns {string} Return type and description required
+ */
+function greet(name: string, age: number): string {
+    return `Hello ${name}, you are ${age} years old`;
+}
+```
+
+#### Common Type Hint Patterns
+
+```javascript
+// Basic types
+@param {string} name
+@param {number} count
+@param {boolean} isActive
+@param {Object} config
+@param {Array<string>} items
+@param {Function} callback
+
+// Complex types
+@param {UserData} userData - Custom type
+@param {Promise<Response>} response - Generic type
+@param {string|number} id - Union type
+@param {{name: string, age: number}} person - Object type
+@param {string[]} names - Array shorthand
+@returns {void} - For functions with no return
+```
+
+#### Important Notes
+
+1. **ESLint Cannot Auto-Generate Types**: While ESLint can create JSDoc blocks, it cannot determine TypeScript types
+2. **Manual Work Required**: After running `--fix`, you must manually add all type hints
+3. **Duplication with TypeScript**: This approach duplicates type information already in TypeScript
+4. **Maintenance Overhead**: Types must be kept in sync between TypeScript and JSDoc
+
 ## ⚠️ Troubleshooting
 
 ### Peer Dependency Warnings

package/eslint.config.mjs

@@ -155,6 +155,49 @@ export default function ({
 				'jsdoc/check-indentation': 'off', // Disabled to avoid conflicts with our custom plugin
 				'jsdoc/tag-lines': 'off', // Disabled to avoid conflicts with our custom plugin
 				'jsdoc-indent/jsdoc-indent': ['error', { tabWidth: 4 }],
+
+				// JSDoc requirements with type hints
+				'jsdoc/require-jsdoc': ['error', {
+					enableFixer: false, // Don't auto-generate empty JSDoc blocks
+					require: {
+						FunctionDeclaration: true,
+						MethodDefinition: true,
+						ClassDeclaration: true,
+						ArrowFunctionExpression: true,
+						FunctionExpression: true
+					},
+					contexts: [
+						'TSInterfaceDeclaration',
+						'TSTypeAliasDeclaration',
+						'TSEnumDeclaration'
+						// Removed 'ClassProperty' and 'PropertyDefinition' - no JSDoc required for properties
+					]
+				}],
+				'jsdoc/require-description': 'error',
+				'jsdoc/require-param': 'error',
+				'jsdoc/require-param-description': 'error',
+				'jsdoc/require-param-name': 'error',
+				'jsdoc/require-returns': 'error',
+				'jsdoc/require-returns-description': 'error',
+				'jsdoc/check-param-names': 'error',
+				'jsdoc/check-tag-names': 'error',
+				'jsdoc/check-types': 'error',
+				'jsdoc/valid-types': 'error',
+				'jsdoc/no-undefined-types': 'error',
+				'jsdoc/require-yields': 'error',
+				'jsdoc/require-throws': 'error',
+				'jsdoc/check-alignment': 'off', // Handled by custom plugin
+				'jsdoc/multiline-blocks': ['error', {
+					noMultilineBlocks: false,
+					minimumLengthForMultiline: 40
+				}],
+
+				// JSDoc with type hints requirements
+				'jsdoc/require-param-type': 'error', // Require type hints for parameters
+				'jsdoc/require-returns-type': 'error', // Require type hints for returns
+				'jsdoc/no-types': 'off', // Allow type annotations in JSDoc
+				'jsdoc/check-types': 'error', // Ensure valid JSDoc types
+				'jsdoc/valid-types': 'error', // Validate type syntax
 				
 				// Enhanced: Interface brace style
 				'interface-brace/interface-brace-style': 'error',

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@dmitryrechkin/eslint-standard",
 	"description": "This package provides a shared ESLint configuration which includes TypeScript support and a set of specific linting rules designed to ensure high-quality and consistent code style across projects.",
-	"version": "1.1.2",
+	"version": "1.1.4",
 	"main": "eslint.config.mjs",
 	"bin": {
 	  "eslint-standard": "./src/cli/index.mjs"
@@ -15,8 +15,10 @@
 	"scripts": {
 	  "postinstall": "node src/cli/postinstall.mjs",
 	  "package:publish": "npm publish --access public",
-	  "test": "npm run test:formatting",
-	  "test:formatting": "node tests/test-runner.js"
+	  "test": "npm run test:formatting && npm run test:cli",
+	  "test:formatting": "node tests/test-runner.js",
+	  "test:cli": "node tests/test-cli.js",
+	  "test:install": "node tests/test-install-simulation.js"
 	},
 	"keywords": [],
 	"author": "",

package/src/cli/check-deps.mjs

@@ -3,20 +3,32 @@
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
+import { spawn } from 'child_process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// Check for --install flag
+const shouldInstall = process.argv.includes('--install');
+
 // Get peer dependencies
 const packageJsonPath = join(__dirname, '../../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 const peerDeps = packageJson.peerDependencies || {};
 
-// Check if running from node_modules
+// Check if running from node_modules and find project root
 const isInNodeModules = __dirname.includes('node_modules');
-const projectRoot = isInNodeModules 
-	? resolve(__dirname, '../../../../') 
-	: process.cwd();
+let projectRoot;
+
+if (isInNodeModules) {
+	// Handle different package manager structures
+	// pnpm: .pnpm/@org+pkg@version_deps/node_modules/@org/pkg
+	// npm/yarn: node_modules/@org/pkg
+	const parts = __dirname.split('node_modules');
+	projectRoot = parts[0].replace(/[\\/]$/, ''); // Remove trailing slash
+} else {
+	projectRoot = process.cwd();
+}
 
 // Read project's package.json
 let projectPackageJson;
@@ -56,13 +68,33 @@ if (missingDeps.length === 0 && outdatedDeps.length === 0) {
 } else {
 	if (missingDeps.length > 0) {
 		console.log(`\n❌ Missing ${missingDeps.length} dependencies:`);
-		console.log('Run: npx @dmitryrechkin/eslint-standard install-deps');
+		missingDeps.forEach(dep => console.log(`  - ${dep}`));
+		
+		if (shouldInstall) {
+			console.log('\n🔧 Auto-installing missing dependencies...\n');
+			
+			// Import and run the install-deps script
+			try {
+				const installDepsModule = await import('./install-deps.mjs');
+				// The install-deps script will handle the installation
+			} catch (error) {
+				console.error('❌ Failed to auto-install dependencies:', error.message);
+				process.exit(1);
+			}
+		} else {
+			console.log('\n💡 To install missing dependencies:');
+			console.log('   npx @dmitryrechkin/eslint-standard install-deps');
+			console.log('   or run this command with --install flag');
+		}
 	}
 	if (outdatedDeps.length > 0) {
 		console.log(`\n⚠️  ${outdatedDeps.length} dependencies may be outdated:`);
 		outdatedDeps.forEach(dep => console.log(`  - ${dep}`));
 	}
-	process.exit(1);
+	
+	if (!shouldInstall && missingDeps.length > 0) {
+		process.exit(1);
+	}
 }
 
 export default function checkDeps() {

package/src/cli/index.mjs

@@ -20,13 +20,15 @@ Usage:
   npx @dmitryrechkin/eslint-standard <command>
 
 Commands:
-  install-deps    Install all peer dependencies
-  check-deps      Check if all peer dependencies are installed
-  help            Show this help message
+  install-deps         Install all peer dependencies
+  check-deps           Check if all peer dependencies are installed
+  check-deps --install Auto-install missing dependencies if any
+  help                 Show this help message
 
 Examples:
   npx @dmitryrechkin/eslint-standard install-deps
   npx @dmitryrechkin/eslint-standard check-deps
+  npx @dmitryrechkin/eslint-standard check-deps --install
 		`);
 		break;
 	default:

package/src/cli/postinstall-check.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { execSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Don't run during local development
+if (!__dirname.includes('node_modules')) {
+	process.exit(0);
+}
+
+// Check if we're in CI environment
+const isCI = process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.GITHUB_ACTIONS;
+
+// Check if scripts are disabled
+const npmConfigIgnoreScripts = process.env.npm_config_ignore_scripts === 'true';
+
+if (isCI || npmConfigIgnoreScripts) {
+	// Silent exit in CI or when scripts are disabled
+	process.exit(0);
+}
+
+// Simple check for missing dependencies
+try {
+	const packageJsonPath = join(__dirname, '../../package.json');
+	const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+	const peerDeps = Object.keys(packageJson.peerDependencies || {});
+	
+	// Quick check if any peer deps are missing
+	let missingCount = 0;
+	for (const dep of peerDeps) {
+		try {
+			// Try to resolve the dependency
+			require.resolve(dep, { paths: [process.cwd()] });
+		} catch {
+			missingCount++;
+		}
+	}
+	
+	if (missingCount > 0) {
+		console.log(`
+⚠️  @dmitryrechkin/eslint-standard: ${missingCount} peer dependencies are missing!
+
+Run this command to check and install them:
+👉 ${'\x1b[36m'}npx @dmitryrechkin/eslint-standard check-deps --install${'\x1b[0m'}
+`);
+	}
+} catch (error) {
+	// Silent fail - don't break installation
+}

package/src/cli/postinstall.mjs

@@ -11,6 +11,17 @@ if (!__dirname.includes('node_modules')) {
 	process.exit(0);
 }
 
+// Check environment variables for auto-install preference
+const autoInstall = process.env.ESLINT_STANDARD_AUTO_INSTALL === 'true';
+const skipInstall = process.env.ESLINT_STANDARD_SKIP_INSTALL === 'true';
+
+// Check if we're in CI environment
+const isCI = process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.GITHUB_ACTIONS;
+
+if (skipInstall || isCI) {
+	process.exit(0);
+}
+
 console.log(`
 ╔════════════════════════════════════════════════════════════════╗
 ║                                                                ║
@@ -21,9 +32,9 @@ console.log(`
 📦 This package requires peer dependencies to work properly.
 
 🚀 Quick install (auto-detects your package manager):
-   ${'\x1b[36m'}npx @dmitryrechkin/eslint-standard install-deps${'\x1b[0m'}
+   ${'\x1b[36m'}npx @dmitryrechkin/eslint-standard check-deps --install${'\x1b[0m'}
 
-📋 Or install manually:
+📋 Or install all dependencies directly:
    ${'\x1b[90m'}npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-unused-imports @stylistic/eslint-plugin eslint-plugin-jsdoc eslint-plugin-simple-import-sort eslint-plugin-perfectionist${'\x1b[0m'}
 
 🔍 To check if all dependencies are installed:
@@ -32,9 +43,22 @@ console.log(`
 📚 Documentation: https://github.com/dmitryrechkin/eslint-standard
 `);
 
-// Run check-deps to show current status
-try {
-	await import('./check-deps.mjs');
-} catch (error) {
-	// Silent fail - don't break installation
+// Don't run check-deps in postinstall to avoid errors
+// Users can run it manually with: npx @dmitryrechkin/eslint-standard check-deps
+
+if (autoInstall) {
+	console.log('\n🤖 Auto-install enabled via ESLINT_STANDARD_AUTO_INSTALL=true');
+	console.log('📦 Checking and installing peer dependencies...\n');
+	
+	try {
+		// Run check-deps with --install flag
+		const { execSync } = await import('child_process');
+		execSync('node ' + join(__dirname, 'index.mjs') + ' check-deps --install', {
+			stdio: 'inherit',
+			cwd: process.cwd()
+		});
+	} catch (error) {
+		console.error('❌ Auto-install failed. Please run manually:');
+		console.error('   npx @dmitryrechkin/eslint-standard check-deps --install');
+	}
 }

package/src/plugins/interface-brace.mjs

@@ -103,7 +103,7 @@ const interfaceBraceRule = {
 								// Replace the space before the brace with a newline and proper indentation
 								return fixer.replaceTextRange(
 									[equalsToken.range[1], openingBrace.range[0]], 
-									' =\n' + baseIndent
+									'\n' + baseIndent
 								);
 							}
 						});