@futdevpro/dynamo-eslint 1.20.3 → 1.20.5

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

@@ -1,572 +0,0 @@
-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)
-        // For multi-line comments, check if the last line of the comment is immediately before the node
-        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 '';
-        }
-
-        // The comment.value contains the text between /** and */
-        // It may start with * and include newlines with * at the beginning of each line
-        const lines = jsdocComment.value.split('\n');
-        let description = '';
-
-        for (const line of lines) {
-          // Remove leading whitespace and * character (JSDoc format: " * text" or "* text")
-          // Handle both formats: " * text" and "* text" and " *text"
-          const cleanLine = line.replace(/^\s*\*+\s?/, '').trim();
-          
-          // Skip empty lines (after removing * and whitespace)
-          if (!cleanLine) {
-            continue;
-          }
-
-          // Stop at @tags (JSDoc tags like @param, @returns, etc.)
-          if (cleanLine.startsWith('@')) {
-            break;
-          }
-
-          // Add to description with space separator
-          if (description) {
-            description += ' ';
-          }
-          description += cleanLine;
-        }
-
-        return description.trim();
-      } catch (error) {
-        console.error('[require-jsdoc-description] Error in extractDescription:', error);
-
-        return '';
-      }
-    }
-
-    /**
-     * Egy node "tartalmi" leading-comment-jenek megtalalasahoz fel kell masznunk a
-     * szintaktikai burkokon, mert a JSDoc nem mindig a belso deklaracio ele kerul:
-     *   - `export class X` / `export interface Y` / `export type Z` / `export enum E`:
-     *     a JSDoc az ExportNamedDeclaration / ExportDefaultDeclaration ELE kerul, NEM
-     *     a belso deklaracio-node ele.
-     *   - arrow-const (`export const fn = () => {}`): a JSDoc a VariableDeclaration
-     *     (ill. annak export-wrapper-e) ele kerul, nem a VariableDeclarator ele.
-     *   - dekorator (pl. `@Component()`-tel annotalt class): a JSDoc a dekorator-stack
-     *     fole kerul, igy a belso class-node kozvetlen elott nincs comment.
-     * Ez a helper visszaadja azokat a "horgony" node-okat, amik ele a
-     * getCommentsBefore-t erdemes hivni — sorrendben a legkulso burkolotol befele.
-     */
-    function getCommentAnchors(node: any): any[] {
-      const anchors: any[] = [ node ];
-
-      try {
-        let climbed: any = node;
-
-        // arrow-const: VariableDeclarator → VariableDeclaration
-        if (climbed.parent && climbed.parent.type === 'VariableDeclaration') {
-          climbed = climbed.parent;
-        }
-
-        // export-wrapper: <decl> → ExportNamedDeclaration / ExportDefaultDeclaration
-        // (csak akkor maszunk fel, ha a wrapper tenyleg EZT a node-ot exportalja)
-        if (climbed.parent
-          && (climbed.parent.type === 'ExportNamedDeclaration' || climbed.parent.type === 'ExportDefaultDeclaration')
-          && climbed.parent.declaration === climbed) {
-          climbed = climbed.parent;
-        }
-
-        // a legkulso burkolo elore kerul (ott van a tartalmi JSDoc tipikusan)
-        if (climbed !== node) {
-          anchors.unshift(climbed);
-        }
-
-        // dekorator: a JSDoc a dekorator-stack fole is kerulhet
-        if (Array.isArray(node.decorators) && node.decorators.length > 0) {
-          anchors.push(node.decorators[0]);
-        }
-      } catch (error) {
-        console.error('[require-jsdoc-description] Error in getCommentAnchors:', error);
-      }
-
-      return anchors;
-    }
-
-    /**
-     * Az osszes szoba johheto "horgony" elott levo comment osszegyujtese. A
-     * getLeadingComments a getCommentsBefore-t MINDEN anchor-ra meghivja es
-     * osszefuzi az eredmenyt — a hasValidJSDoc utana az elso JSDoc-blokkot
-     * keresi ki belole, igy mindegy hogy melyik burok elott talalja meg.
-     */
-    function getLeadingComments(node: any): any[] {
-      const all: any[] = [];
-
-      for (const anchor of getCommentAnchors(node)) {
-        const before: any[] = sourceCode.getCommentsBefore(anchor) || [];
-
-        for (const comment of before) {
-          all.push(comment);
-        }
-      }
-
-      return all;
-    }
-
-    /**
-     * Check if node has valid JSDoc comment
-     */
-    function hasValidJSDoc(node: any): { hasJSDoc: boolean; isValid: boolean; isOnPreviousLine: boolean } {
-      try {
-        const comments = getLeadingComments(node);
-        
-        // Find JSDoc comment (/** ... */)
-        // JSDoc comments are Block comments where the value (content between /** and */) starts with *
-        const jsdocComment = comments.find((comment: any) => {
-          if (comment.type !== 'Block') {
-            return false;
-          }
-          
-          const value = comment.value || '';
-          
-          // JSDoc comment value should start with * (the first character after /**)
-          // Handle cases where there might be whitespace before the *
-          return value.trim().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 name location for error reporting
-     */
-    function getNodeNameLoc(node: any): { start: { line: number; column: number }; end: { line: number; column: number } } | null {
-      try {
-        // For MethodDefinition, use key.loc
-        if (node.key && node.key.loc) {
-          return node.key.loc;
-        }
-
-        // For declarations with id (FunctionDeclaration, ClassDeclaration, etc.)
-        if (node.id && node.id.loc) {
-          return node.id.loc;
-        }
-
-        // For VariableDeclarator
-        if (node.id && node.id.loc) {
-          return node.id.loc;
-        }
-
-        // Fallback to node location if name location not found
-        if (node.loc) {
-          return node.loc;
-        }
-
-        return null;
-      } catch (error) {
-        console.error('[require-jsdoc-description] Error in getNodeNameLoc:', error);
-
-        return null;
-      }
-    }
-
-    /**
-     * 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 'TSTypeAliasDeclaration':
-            return 'Type';
-          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);
-        const nameLoc = getNodeNameLoc(node);
-
-        // Fallback to node location if name location not found
-        const reportLoc = nameLoc || node.loc;
-
-        if (!jsdocResult.hasJSDoc) {
-          context.report({
-            loc: reportLoc,
-            messageId: 'missingJSDoc',
-            data: { type, name },
-          });
-        } else if (!jsdocResult.isOnPreviousLine) {
-          context.report({
-            loc: reportLoc,
-            messageId: 'invalidJSDocPosition',
-            data: { type, name },
-          });
-        } else if (!jsdocResult.isValid) {
-          context.report({
-            loc: reportLoc,
-            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);
-        }
-      },
-
-      // Type alias declarations (CCAP-megerősítés: exportált `type X = …` kötelező JSDoc).
-      TSTypeAliasDeclaration(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 TSTypeAliasDeclaration 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;