@futdevpro/dynamo-eslint 1.14.6 → 1.14.8

package/src/plugin/rules/require-jsdoc-description.ts

@@ -0,0 +1,436 @@
+import { Rule } from 'eslint';
+
+interface RuleOptions {
+  scope?: 'public' | 'all';
+}
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: { 
+      description: 'Require JSDoc comment blocks with description for functions, classes, interfaces, and enums',
+      recommended: true,
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          scope: {
+            type: 'string',
+            enum: [ 'public', 'all' ],
+            default: 'public',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      missingJSDoc: '{{type}} "{{name}}" must have a JSDoc comment with description.',
+      emptyJSDoc: '{{type}} "{{name}}" JSDoc comment must contain description text.',
+      invalidJSDocPosition: '{{type}} "{{name}}" JSDoc comment must be on the line immediately before.',
+    },
+  },
+  create(context) {
+    const options: RuleOptions = context.options[0] || {};
+    const scope: string = options.scope || 'public';
+    const sourceCode: any = context.sourceCode;
+
+    /**
+     * Check if a node is public/exported (should be documented)
+     */
+    function isPublic(node: any): boolean {
+      try {
+        // Check if node itself is exported
+        if (node.parent && node.parent.type === 'ExportNamedDeclaration') {
+          return true;
+        }
+        
+        if (node.parent && node.parent.type === 'ExportDefaultDeclaration') {
+          return true;
+        }
+
+        // Check for export keyword in declaration
+        if (node.type === 'FunctionDeclaration' && node.parent && 
+            node.parent.type === 'Program' && node.id) {
+          // Top-level function - check if exported
+          const program: any = node.parent;
+
+          if (program.body && Array.isArray(program.body)) {
+            for (const statement of program.body) {
+              if (statement.type === 'ExportNamedDeclaration' && 
+                  statement.declaration === node) {
+                return true;
+              }
+            }
+          }
+        }
+
+        // For class members, check accessibility modifiers
+        if (node.type === 'MethodDefinition' || node.type === 'PropertyDefinition') {
+          // If has private modifier, it's not public
+          if (node.accessibility === 'private') {
+            return false;
+          }
+
+          // If has protected modifier, it's not public
+          if (node.accessibility === 'protected') {
+            return false;
+          }
+
+          // Default to public if no modifiers
+          return true;
+        }
+
+        // For top-level declarations, check if they're exported
+        if (node.parent && node.parent.type === 'Program') {
+          // Check if this declaration is exported
+          const program: any = node.parent;
+
+          if (program.body && Array.isArray(program.body)) {
+            for (const statement of program.body) {
+              if (statement.type === 'ExportNamedDeclaration' && 
+                  statement.declaration === node) {
+                return true;
+              }
+
+              if (statement.type === 'ExportDefaultDeclaration' && 
+                  statement.declaration === node) {
+                return true;
+              }
+            }
+          }
+
+          return false; // Not exported
+        }
+
+        // Default to public for other cases
+        return true;
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in isPublic:', error);
+
+        return true; // Default to requiring documentation
+      }
+    }
+
+    /**
+     * Check if JSDoc comment is on the line immediately before the node
+     */
+    function isJSDocOnPreviousLine(node: any, jsdocComment: any): boolean {
+      try {
+        const nodeStart: number | undefined = node.loc?.start?.line;
+        const commentEnd: number | undefined = jsdocComment.loc?.end?.line;
+        
+        if (!nodeStart || !commentEnd) {
+          return false;
+        }
+
+        // JSDoc should be on the line immediately before (no blank lines)
+        return commentEnd === nodeStart - 1;
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in isJSDocOnPreviousLine:', error);
+
+        return false;
+      }
+    }
+
+    /**
+     * Extract description text from JSDoc comment
+     */
+    function extractDescription(jsdocComment: any): string {
+      try {
+        if (!jsdocComment.value) {
+          return '';
+        }
+
+        const lines = jsdocComment.value.split('\n');
+        let description = '';
+
+        for (const line of lines) {
+          // Remove leading * and whitespace
+          const cleanLine = line.replace(/^\s*\*\s?/, '').trim();
+          
+          // Skip empty lines
+          if (!cleanLine) {
+            continue;
+          }
+
+          // Stop at @tags
+          if (cleanLine.startsWith('@')) {
+            break;
+          }
+
+          // Add to description
+          if (description) {
+            description += ' ';
+          }
+          description += cleanLine;
+        }
+
+        return description.trim();
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in extractDescription:', error);
+
+        return '';
+      }
+    }
+
+    /**
+     * Check if node has valid JSDoc comment
+     */
+    function hasValidJSDoc(node: any): { hasJSDoc: boolean; isValid: boolean; isOnPreviousLine: boolean } {
+      try {
+        const comments = sourceCode.getCommentsBefore(node);
+        
+        // Find JSDoc comment (/** ... */)
+        const jsdocComment = comments.find((comment: any) => 
+          comment.type === 'Block' && 
+          comment.value.startsWith('*')
+        );
+
+        if (!jsdocComment) {
+          return { hasJSDoc: false, isValid: false, isOnPreviousLine: false };
+        }
+
+        const isOnPreviousLine: boolean = isJSDocOnPreviousLine(node, jsdocComment);
+        const description: string = extractDescription(jsdocComment);
+        const isValid: boolean = description.length > 0;
+
+        return { hasJSDoc: true, isValid, isOnPreviousLine };
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in hasValidJSDoc:', error);
+
+        return { hasJSDoc: false, isValid: false, isOnPreviousLine: false };
+      }
+    }
+
+    /**
+     * Get node name for error messages
+     */
+    function getNodeName(node: any): string {
+      try {
+        if (node.id && node.id.name) {
+          return node.id.name;
+        }
+
+        if (node.key && node.key.name) {
+          return node.key.name;
+        }
+
+        if (node.name && node.name.name) {
+          return node.name.name;
+        }
+
+        return 'anonymous';
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in getNodeName:', error);
+
+        return 'unknown';
+      }
+    }
+
+    /**
+     * Get node type for error messages
+     */
+    function getNodeType(node: any): string {
+      try {
+        // Check if it's a VariableDeclarator with function expression
+        if (node.type === 'VariableDeclarator' && node.init) {
+          if (node.init.type === 'FunctionExpression' || node.init.type === 'ArrowFunctionExpression') {
+            return 'Function';
+          }
+        }
+
+        switch (node.type) {
+          case 'FunctionDeclaration':
+            return 'Function';
+          case 'FunctionExpression':
+            return 'Function';
+          case 'ArrowFunctionExpression':
+            return 'Function';
+          case 'ClassDeclaration':
+            return 'Class';
+          case 'TSInterfaceDeclaration':
+            return 'Interface';
+          case 'TSEnumDeclaration':
+            return 'Enum';
+          case 'MethodDefinition':
+            return 'Method';
+          case 'PropertyDefinition':
+            return 'Property';
+
+          default:
+            return 'Declaration';
+        }
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in getNodeType:', error);
+
+        return 'Declaration';
+      }
+    }
+
+    /**
+     * Check if node should be documented based on scope
+     */
+    function shouldBeDocumented(node: any): boolean {
+      try {
+        if (scope === 'all') {
+          return true;
+        }
+        
+        if (scope === 'public') {
+          return isPublic(node);
+        }
+
+        return true; // Default to requiring documentation
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in shouldBeDocumented:', error);
+
+        return true;
+      }
+    }
+
+    /**
+     * Report missing or invalid JSDoc
+     */
+    function reportJSDocIssue(
+      node: any, 
+      jsdocResult: { hasJSDoc: boolean; isValid: boolean; isOnPreviousLine: boolean }
+    ): void {
+      try {
+        const name = getNodeName(node);
+        const type = getNodeType(node);
+
+        if (!jsdocResult.hasJSDoc) {
+          context.report({
+            node,
+            messageId: 'missingJSDoc',
+            data: { type, name },
+          });
+        } else if (!jsdocResult.isOnPreviousLine) {
+          context.report({
+            node,
+            messageId: 'invalidJSDocPosition',
+            data: { type, name },
+          });
+        } else if (!jsdocResult.isValid) {
+          context.report({
+            node,
+            messageId: 'emptyJSDoc',
+            data: { type, name },
+          });
+        }
+      } catch (error) {
+        console.error('[require-jsdoc-description] Error in reportJSDocIssue:', error);
+      }
+    }
+
+    return {
+      // Function declarations
+      FunctionDeclaration(node: any): void {
+        try {
+          if (!shouldBeDocumented(node)) {
+            return;
+          }
+
+          const jsdocResult = hasValidJSDoc(node);
+
+          if (!jsdocResult.hasJSDoc || !jsdocResult.isValid || !jsdocResult.isOnPreviousLine) {
+            reportJSDocIssue(node, jsdocResult);
+          }
+        } catch (error) {
+          console.error('[require-jsdoc-description] Error in FunctionDeclaration visitor:', error);
+        }
+      },
+
+      // Function expressions (when assigned to variables)
+      VariableDeclarator(node: any): void {
+        try {
+          if (node.init && 
+              (node.init.type === 'FunctionExpression' || node.init.type === 'ArrowFunctionExpression')) {
+            if (!shouldBeDocumented(node)) {
+              return;
+            }
+
+            const jsdocResult = hasValidJSDoc(node);
+
+            if (!jsdocResult.hasJSDoc || !jsdocResult.isValid || !jsdocResult.isOnPreviousLine) {
+              reportJSDocIssue(node, jsdocResult);
+            }
+          }
+        } catch (error) {
+          console.error('[require-jsdoc-description] Error in VariableDeclarator visitor:', error);
+        }
+      },
+
+      // Class declarations
+      ClassDeclaration(node: any): void {
+        try {
+          if (!shouldBeDocumented(node)) {
+            return;
+          }
+
+          const jsdocResult = hasValidJSDoc(node);
+
+          if (!jsdocResult.hasJSDoc || !jsdocResult.isValid || !jsdocResult.isOnPreviousLine) {
+            reportJSDocIssue(node, jsdocResult);
+          }
+        } catch (error) {
+          console.error('[require-jsdoc-description] Error in ClassDeclaration visitor:', error);
+        }
+      },
+
+      // Interface declarations
+      TSInterfaceDeclaration(node: any): void {
+        try {
+          if (!shouldBeDocumented(node)) {
+            return;
+          }
+
+          const jsdocResult = hasValidJSDoc(node);
+
+          if (!jsdocResult.hasJSDoc || !jsdocResult.isValid || !jsdocResult.isOnPreviousLine) {
+            reportJSDocIssue(node, jsdocResult);
+          }
+        } catch (error) {
+          console.error('[require-jsdoc-description] Error in TSInterfaceDeclaration visitor:', error);
+        }
+      },
+
+      // Enum declarations
+      TSEnumDeclaration(node: any): void {
+        try {
+          if (!shouldBeDocumented(node)) {
+            return;
+          }
+
+          const jsdocResult = hasValidJSDoc(node);
+
+          if (!jsdocResult.hasJSDoc || !jsdocResult.isValid || !jsdocResult.isOnPreviousLine) {
+            reportJSDocIssue(node, jsdocResult);
+          }
+        } catch (error) {
+          console.error('[require-jsdoc-description] Error in TSEnumDeclaration visitor:', error);
+        }
+      },
+
+      // Class methods
+      MethodDefinition(node: any): void {
+        try {
+          if (!shouldBeDocumented(node)) {
+            return;
+          }
+
+          const jsdocResult = hasValidJSDoc(node);
+
+          if (!jsdocResult.hasJSDoc || !jsdocResult.isValid || !jsdocResult.isOnPreviousLine) {
+            reportJSDocIssue(node, jsdocResult);
+          }
+        } catch (error) {
+          console.error('[require-jsdoc-description] Error in MethodDefinition visitor:', error);
+        }
+      },
+    };
+  },
+};
+
+export default rule;