@synergyerp/frontend-standards 1.5.8 → 1.6.0

package/.husky/commit-msg

@@ -1,5 +1,2 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 echo "📝 Validating commit message..."
 pnpm exec commitlint --edit "$1"

package/.husky/pre-commit

@@ -1,6 +1,3 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 # Detect --no-verify bypass patterns
 sh "$(dirname -- "$0")/../scripts/detect-no-verify.sh"
 

package/.husky/pre-push

@@ -1,6 +1,3 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 # Detect --no-verify bypass patterns
 sh "$(dirname -- "$0")/../scripts/detect-no-verify.sh"
 

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 =====
@@ -22,6 +24,7 @@ export default tseslint.config(
       'build/**',
       'scripts/**',
       'vitest.config.base.ts',
+      'vitest.config.base.js',
       'tsconfig.base.json',
       'tsconfig.json',
       '**/*.gen.ts',
@@ -44,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',
@@ -203,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: true }],
+      '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',
@@ -332,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',
     },
   },
 
@@ -341,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.8",
+  "version": "1.6.0",
   "description": "SynergyERP frontend standards — ESLint, Prettier, commitlint, Husky, Vitest, TypeScript configs, modularization enforcement, and PR templates.",
   "private": false,
   "type": "module",
@@ -11,11 +11,13 @@
   },
   "files": [
     "eslint.config.js",
+    "eslint-rules/",
     "prettier.config.js",
     ".prettierignore",
     "commitlint.config.js",
     "tsconfig.base.json",
     "vitest.config.base.ts",
+    "vitest.config.base.js",
     "scripts/",
     ".husky/",
     ".vscode/",
@@ -58,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",

package/vitest.config.base.js

@@ -0,0 +1,36 @@
+import react from '@vitejs/plugin-react';
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules', 'dist', 'build'],
+    css: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'cobertura'],
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: [
+        'src/**/*.test.{ts,tsx}',
+        'src/**/*.spec.{ts,tsx}',
+        'src/**/*.d.ts',
+        'src/test/**',
+        'src/mocks/**',
+        'src/main.tsx',
+        'src/vite-env.d.ts',
+      ],
+      thresholds: {
+        lines: 80,
+        branches: 75,
+        functions: 80,
+        statements: 80,
+        perFile: true,
+      },
+    },
+  },
+});