@synergyerp/frontend-standards 1.5.9 → 1.6.1

package/eslint-rules/require-call-comment.mjs

@@ -0,0 +1,142 @@
+const EXCLUDED_NAMES = new Set([
+  'navigate',
+  'redirect',
+  'dispatch',
+  'reload',
+  'refresh',
+  'toString',
+  'toFixed',
+  'toLocaleString',
+  'preventDefault',
+  'stopPropagation',
+]);
+
+const ARRAY_METHODS = new Set([
+  'map',
+  'filter',
+  'reduce',
+  'forEach',
+  'find',
+  'some',
+  'every',
+  'flatMap',
+  'flat',
+  'includes',
+  'indexOf',
+  'findIndex',
+]);
+
+const TEST_FRAMEWORK = new Set([
+  'describe',
+  'it',
+  'test',
+  'expect',
+  'beforeEach',
+  'afterEach',
+  'beforeAll',
+  'afterAll',
+  'vi',
+  'jest',
+]);
+
+function isReactHook(name) {
+  return /^use[A-Z]/.test(name);
+}
+
+function isReactSetter(name) {
+  return /^set[A-Z]/.test(name);
+}
+
+function isTestMethod(name) {
+  return TEST_FRAMEWORK.has(name);
+}
+
+function getCallName(callee) {
+  if (!callee) return null;
+  if (callee.type === 'Identifier') return callee.name;
+  if (callee.type === 'MemberExpression' && callee.property.type === 'Identifier') {
+    return callee.property.name;
+  }
+  return null;
+}
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require an inline comment before function calls that perform complex logic.',
+    },
+    messages: {
+      missingComment: 'Add a brief inline comment describing what this function call does.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode || context.getSourceCode();
+
+    function hasCommentOnLineAboveOrSame(node) {
+      const line = node.loc.start.line;
+      const comments = sourceCode.getAllComments();
+      return comments.some(
+        (comment) => comment.loc.end.line === line || comment.loc.end.line === line - 1
+      );
+    }
+
+    function isExcludedCall(node) {
+      if (node.parent?.type === 'JSXExpressionContainer') return true;
+
+      const callee = node.callee;
+      const name = getCallName(callee);
+      if (!name) return true;
+
+      if (isReactHook(name)) return true;
+      if (isReactSetter(name)) return true;
+      if (isTestMethod(name)) return true;
+      if (EXCLUDED_NAMES.has(name)) return true;
+
+      if (ARRAY_METHODS.has(name)) {
+        if (callee.type === 'MemberExpression') return true;
+      }
+
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.object?.type === 'Identifier' &&
+        callee.object.name === 'console'
+      ) {
+        return true;
+      }
+
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.object?.type === 'Identifier' &&
+        callee.object.name === 'Math'
+      ) {
+        return true;
+      }
+
+      return false;
+    }
+
+    function checkCall(node) {
+      if (!node || node.type !== 'CallExpression') return;
+      if (isExcludedCall(node)) return;
+      if (hasCommentOnLineAboveOrSame(node)) return;
+
+      context.report({ node, messageId: 'missingComment' });
+    }
+
+    return {
+      'ExpressionStatement > CallExpression'(node) {
+        checkCall(node);
+      },
+      'ExpressionStatement > AwaitExpression > CallExpression'(node) {
+        checkCall(node);
+      },
+      'VariableDeclarator > CallExpression'(node) {
+        checkCall(node);
+      },
+      'VariableDeclarator > AwaitExpression > CallExpression'(node) {
+        checkCall(node);
+      },
+    };
+  },
+};

package/eslint.config.js

@@ -1,6 +1,7 @@
 import js from '@eslint/js';
 import boundaries from 'eslint-plugin-boundaries';
 import importPlugin from 'eslint-plugin-import';
+import jsdoc from 'eslint-plugin-jsdoc';
 import jsxA11y from 'eslint-plugin-jsx-a11y';
 import prettierPlugin from 'eslint-plugin-prettier/recommended';
 import reactPlugin from 'eslint-plugin-react';
@@ -9,6 +10,7 @@ import reactRefresh from 'eslint-plugin-react-refresh';
 import unicorn from 'eslint-plugin-unicorn';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
+import requireCallComment from './eslint-rules/require-call-comment.mjs';
 
 export default tseslint.config(
   // ===== BASE: Ignore patterns =====
@@ -45,9 +47,11 @@ export default tseslint.config(
       'react-hooks': reactHooks,
       'react-refresh': reactRefresh,
       import: importPlugin,
+      jsdoc: jsdoc,
       unicorn: unicorn,
       'jsx-a11y': jsxA11y,
       boundaries: boundaries,
+      custom: { rules: { 'require-call-comment': requireCallComment } },
     },
     languageOptions: {
       ecmaVersion: 'latest',
@@ -204,6 +208,38 @@ export default tseslint.config(
       'react-hooks/exhaustive-deps': 'warn',
       'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
 
+      // ===== JSDOC (FRONTEND_STANDARDS.md Section on Documentation) =====
+      'jsdoc/require-jsdoc': [
+        'error',
+        {
+          contexts: [
+            'ExportNamedDeclaration > VariableDeclarator > ArrowFunctionExpression',
+            'ExportNamedDeclaration > FunctionDeclaration',
+            'VariableDeclarator[id.type="Identifier"] > ArrowFunctionExpression',
+            'VariableDeclarator[id.type="Identifier"] > FunctionExpression',
+            'FunctionDeclaration',
+            'MethodDefinition',
+          ],
+          checkConstructors: false,
+          enableFixer: false,
+        },
+      ],
+      'jsdoc/require-description': ['error', { contexts: ['any'] }],
+      'jsdoc/no-missing-syntax': 'off',
+      'jsdoc/multiline-blocks': ['error', { noMultilineBlocks: true, noSingleLineBlocks: false }],
+      'jsdoc/require-param': ['error', { contexts: ['any'] }],
+      'jsdoc/require-param-name': 'error',
+      'jsdoc/require-param-type': 'off',
+      'jsdoc/require-returns': ['error', { contexts: ['any'] }],
+      'jsdoc/require-returns-type': 'off',
+      'jsdoc/require-returns-check': 'error',
+      'jsdoc/check-tag-names': 'error',
+      'jsdoc/check-types': 'error',
+      'jsdoc/empty-tags': 'error',
+
+      // ===== DOCUMENTATION: Inline call comments =====
+      'custom/require-call-comment': 'error',
+
       // ===== IMPORTS (FRONTEND_STANDARDS.md Section 5.3) =====
       'import/order': [
         'error',
@@ -333,6 +369,12 @@ export default tseslint.config(
       'no-console': 'off',
       '@typescript-eslint/no-explicit-any': 'off',
       'import/no-internal-modules': 'off',
+      'custom/require-call-comment': 'off',
+      'jsdoc/require-jsdoc': 'off',
+      'jsdoc/require-description': 'off',
+      'jsdoc/require-param': 'off',
+      'jsdoc/require-returns': 'off',
+      'jsdoc/require-returns-check': 'off',
     },
   },
 
@@ -342,6 +384,12 @@ export default tseslint.config(
     rules: {
       '@typescript-eslint/no-explicit-any': 'off',
       'import/no-internal-modules': 'off',
+      'custom/require-call-comment': 'off',
+      'jsdoc/require-jsdoc': 'off',
+      'jsdoc/require-description': 'off',
+      'jsdoc/require-param': 'off',
+      'jsdoc/require-returns': 'off',
+      'jsdoc/require-returns-check': 'off',
     },
   }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergyerp/frontend-standards",
-  "version": "1.5.9",
+  "version": "1.6.1",
   "description": "SynergyERP frontend standards — ESLint, Prettier, commitlint, Husky, Vitest, TypeScript configs, modularization enforcement, and PR templates.",
   "private": false,
   "type": "module",
@@ -11,6 +11,7 @@
   },
   "files": [
     "eslint.config.js",
+    "eslint-rules/",
     "prettier.config.js",
     ".prettierignore",
     "commitlint.config.js",
@@ -24,16 +25,6 @@
     "FRONTEND_STANDARDS.md",
     "CICD_STANDARDS.md"
   ],
-  "scripts": {
-    "lint": "eslint .",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "check-modularization": "node scripts/check-modularization.mjs; exit 0",
-    "check-types": "tsc --noEmit; exit 0",
-    "test:ci": "exit 0",
-    "test": "exit 0",
-    "prepare": "echo 'Standards package ready'"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aoholdings/frontend-standards.git"
@@ -69,6 +60,7 @@
     "eslint-plugin-react": "^7.37.0",
     "eslint-plugin-react-hooks": "^5.0.0",
     "eslint-plugin-react-refresh": "^0.4.0",
+    "eslint-plugin-jsdoc": "^50.0.0",
     "eslint-plugin-unicorn": "^56.0.0",
     "globals": "^15.0.0",
     "prettier-plugin-organize-imports": "^4.0.0",
@@ -81,5 +73,14 @@
     "typescript": "^5.5.0",
     "vitest": "^3.0.0",
     "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check-modularization": "node scripts/check-modularization.mjs; exit 0",
+    "check-types": "tsc --noEmit; exit 0",
+    "test:ci": "exit 0",
+    "test": "exit 0"
   }
-}
+}