@futdevpro/dynamo-eslint 1.14.4 → 1.14.7

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

@@ -0,0 +1,542 @@
+import requireJSDocRule from './require-jsdoc-description';
+
+describe('| require-jsdoc-description', () => {
+  it('| should be a valid ESLint rule', () => {
+    expect(requireJSDocRule.meta?.type).toBe('suggestion');
+    expect(requireJSDocRule.meta?.docs?.description).toContain('Require JSDoc comment blocks');
+    expect(requireJSDocRule.meta?.fixable).toBeUndefined();
+  });
+
+  it('| should have create function that returns visitor object', () => {
+    const mockContext = {
+      report: () => {},
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const result = requireJSDocRule.create(mockContext);
+
+    expect(typeof result).toBe('object');
+    expect(typeof result.FunctionDeclaration).toBe('function');
+    expect(typeof result.ClassDeclaration).toBe('function');
+    expect(typeof result.TSInterfaceDeclaration).toBe('function');
+    expect(typeof result.TSEnumDeclaration).toBe('function');
+    expect(typeof result.MethodDefinition).toBe('function');
+    expect(typeof result.VariableDeclarator).toBe('function');
+  });
+
+  it('| should not report when function has valid JSDoc', () => {
+    const mockContext = {
+      report: (options: any) => {
+        fail('Should not report when function has valid JSDoc');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [{
+          type: 'Block',
+          value: '* This is a test function',
+          loc: { end: { line: 1 } },
+        }],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 2 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+  });
+
+  it('| should report when function is missing JSDoc', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.messageId).toBe('missingJSDoc');
+        expect(options.data.type).toBe('Function');
+        expect(options.data.name).toBe('testFunction');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should report when JSDoc is empty (no description)', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.messageId).toBe('emptyJSDoc');
+        expect(options.data.type).toBe('Function');
+        expect(options.data.name).toBe('testFunction');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [{
+          type: 'Block',
+          value: '*',
+          loc: { end: { line: 1 } },
+        }],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 2 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should report when JSDoc is not on previous line', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.messageId).toBe('invalidJSDocPosition');
+        expect(options.data.type).toBe('Function');
+        expect(options.data.name).toBe('testFunction');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [{
+          type: 'Block',
+          value: '* This is a test function',
+          loc: { end: { line: 1 } },
+        }],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 3 } }, // Gap between comment and function
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should report when function is not exported and scope is public', () => {
+    const mockContext = {
+      report: (options: any) => {
+        fail('Should not report when function is not exported in public scope');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'privateFunction' },
+      loc: { start: { line: 1 } },
+      parent: { type: 'Program', body: [] },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    // In public scope, non-exported functions should not be documented
+  });
+
+  it('| should report when function is private and scope is all', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.messageId).toBe('missingJSDoc');
+      },
+      options: [{ scope: 'all' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'privateFunction' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle class declarations', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.data.type).toBe('Class');
+        expect(options.data.name).toBe('TestClass');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'ClassDeclaration',
+      id: { name: 'TestClass' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.ClassDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle interface declarations', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.data.type).toBe('Interface');
+        expect(options.data.name).toBe('TestInterface');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'TSInterfaceDeclaration',
+      id: { name: 'TestInterface' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.TSInterfaceDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle enum declarations', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.data.type).toBe('Enum');
+        expect(options.data.name).toBe('TestEnum');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'TSEnumDeclaration',
+      id: { name: 'TestEnum' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.TSEnumDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle method definitions', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.data.type).toBe('Method');
+        expect(options.data.name).toBe('testMethod');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'MethodDefinition',
+      key: { name: 'testMethod' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.MethodDefinition(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle function expressions in variable declarations', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.data.type).toBe('Function');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'VariableDeclarator',
+      id: { name: 'testFunction' },
+      init: { type: 'FunctionExpression' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.VariableDeclarator(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle arrow functions in variable declarations', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.data.type).toBe('Function');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'VariableDeclarator',
+      id: { name: 'testArrowFunction' },
+      init: { type: 'ArrowFunctionExpression' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.VariableDeclarator(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should not report when variable declarator is not a function', () => {
+    const mockContext = {
+      report: (options: any) => {
+        fail('Should not report when variable is not a function');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'VariableDeclarator',
+      id: { name: 'testVariable' },
+      init: { type: 'Literal', value: 'test' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.VariableDeclarator(mockNode);
+  });
+
+  it('| should handle JSDoc with @param tags', () => {
+    const mockContext = {
+      report: (options: any) => {
+        fail('Should not report when JSDoc has description and @param tags');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [{
+          type: 'Block',
+          value: '* This function does something\n* @param {string} name The name parameter',
+          loc: { end: { line: 1 } },
+        }],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 2 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+  });
+
+  it('| should handle JSDoc with only @param tags (no description)', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.messageId).toBe('emptyJSDoc');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [{
+          type: 'Block',
+          value: '* @param {string} name The name parameter',
+          loc: { end: { line: 1 } },
+        }],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 2 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle default scope when no options provided', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.messageId).toBe('missingJSDoc');
+      },
+      options: [],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle error cases gracefully', () => {
+    const mockContext = {
+      report: () => {},
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => {
+          throw new Error('Source code error'); 
+        },
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 1 } },
+    } as any;
+
+    // Should not throw error
+    expect(() => {
+      rule.FunctionDeclaration(mockNode);
+    }).not.toThrow();
+  });
+
+  it('| should handle anonymous functions', () => {
+    let reportCalled = false;
+    const mockContext = {
+      report: (options: any) => {
+        reportCalled = true;
+        expect(options.data.name).toBe('anonymous');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: null, // Anonymous function
+      loc: { start: { line: 1 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+
+    expect(reportCalled).toBe(true);
+  });
+
+  it('| should handle multiline JSDoc descriptions', () => {
+    const mockContext = {
+      report: (options: any) => {
+        fail('Should not report when JSDoc has multiline description');
+      },
+      options: [{ scope: 'public' }],
+      sourceCode: {
+        getCommentsBefore: () => [{
+          type: 'Block',
+          value: '* This is a multiline\n* description for the function\n* that explains what it does',
+          loc: { end: { line: 1 } },
+        }],
+      },
+    } as any;
+
+    const rule = requireJSDocRule.create(mockContext);
+
+    const mockNode = {
+      type: 'FunctionDeclaration',
+      id: { name: 'testFunction' },
+      loc: { start: { line: 2 } },
+    } as any;
+
+    rule.FunctionDeclaration(mockNode);
+  });
+});