add custom eslint rule to enforce use of our logger (#59032)

Author: Ebonsignori

eslint.config.ts

@@ -12,6 +12,7 @@ import noOnlyTests from 'eslint-plugin-no-only-tests'
 import prettierPlugin from 'eslint-plugin-prettier'
 import prettier from 'eslint-config-prettier'
 import globals from 'globals'
+import customRules from 'eslint-plugin-custom-rules'
 
 export default [
   {
@@ -57,6 +58,7 @@ export default [
       '@typescript-eslint': tseslint,
       'primer-react': primerReact,
       'jsx-a11y': jsxA11y,
+      'custom-rules': customRules,
     },
     rules: {
       // ESLint recommended rules
@@ -98,6 +100,77 @@ export default [
       // Disabled rules to review
       'no-console': 'off', // 800+
       '@typescript-eslint/no-explicit-any': 'off',
+
+      // Custom rules (disabled by default for now)
+      'custom-rules/use-custom-logger': 'off',
+    },
+  },
+
+  // Configuration for eslint-rules directory (CommonJS JavaScript files)
+  {
+    files: ['src/eslint-rules/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'script',
+      globals: {
+        ...globals.node,
+        ...globals.commonjs,
+        ...globals.es2020,
+      },
+    },
+    plugins: {
+      github,
+      import: importPlugin,
+      'eslint-comments': eslintComments,
+      filenames,
+      'no-only-tests': noOnlyTests,
+      prettier: prettierPlugin,
+    },
+    rules: {
+      // ESLint recommended rules
+      ...js.configs.recommended.rules,
+
+      // GitHub plugin recommended rules
+      ...github.configs.recommended.rules,
+
+      // Import plugin error rules
+      ...importPlugin.configs.errors.rules,
+
+      // Allow CommonJS in eslint rules
+      'import/no-commonjs': 'off',
+
+      // Overrides
+      'import/extensions': ['error', { json: 'always' }],
+      'no-empty': ['error', { allowEmptyCatch: true }],
+      'prefer-const': ['error', { destructuring: 'all' }],
+
+      // Disabled rules
+      'i18n-text/no-en': 'off',
+      'filenames/match-regex': 'off',
+      camelcase: 'off',
+      'no-console': 'off',
+    },
+  },
+
+  // Disable custom logger rule for logger implementation itself
+  {
+    files: ['src/observability/logger/**/*.{ts,js}'],
+    rules: {
+      'custom-rules/use-custom-logger': 'off',
+    },
+  },
+
+  // Override for scripts, tests, workflows, content-linter, and React files (disable custom logger rule)
+  {
+    files: [
+      '**/scripts/**/*.{ts,js}',
+      '**/tests/**/*.{ts,js}',
+      'src/workflows/**/*.{ts,js}',
+      'src/content-linter/**/*.{ts,js}',
+      '**/*.{tsx,jsx}',
+    ],
+    rules: {
+      'custom-rules/use-custom-logger': 'off',
     },
   },
 

package-lock.json

@@ -292,6 +292,7 @@
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.2",
+    "eslint-plugin-custom-rules": "file:src/eslint-rules",
     "eslint-plugin-escompat": "^3.11.4",
     "eslint-plugin-eslint-comments": "^3.2.0",
     "eslint-plugin-filenames": "^1.3.2",

package.json

@@ -0,0 +1,21 @@
+# Custom ESLint Rules
+
+We can declare custom rules in this directory and import them from our ESLint config in [eslint.config.ts](../../eslint.config.ts)
+
+Custom rules are useful for enforcing best practices and more effective than a "warning" comment since automated linter tests will fail if custom rules aren't followed.
+
+**Note:** Custom rules must be written as JavaScript (`.js`) files, not TypeScript. ESLint loads custom rule plugins at runtime using Node's module system, which expects JavaScript. While the main ESLint config can be TypeScript, the rule implementations themselves need to be JavaScript.
+
+## Creating a new rule
+
+1. Create the rule in this directory
+2. Export it from [index.js](./index.js)
+3. Enable it in [eslint.config.ts](../../eslint.config.ts) under the `"rules"` key, e.g.
+
+```typescript
+'custom-rules/use-custom-logger': 'error',
+```
+
+Note that the rule is prepended with `custom-rules`
+
+4. Please include a `README.md` in your rule's directory explaining why it is necessary and any times the rule can be ignored.

src/eslint-rules/README.md

@@ -0,0 +1,6 @@
+// Export custom rules from here
+module.exports = {
+  rules: {
+    "use-custom-logger": require("./use-custom-logger/use-custom-logger"),
+  },
+};

src/eslint-rules/index.js

@@ -0,0 +1,10 @@
+{
+  "name": "eslint-plugin-custom-rules",
+  "type": "commonjs",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "index.js",
+  "peerDependencies": {
+    "eslint": "^8.0.0 || ^9.0.0"
+  }
+}

src/eslint-rules/package.json

@@ -0,0 +1,15 @@
+# Use Custom Logger Rule
+
+This rule enforces using `logger.<level>` instead of `console.log` in backend code.
+
+Please see [the logger README](../../observability/logger/README.md) for more details.
+
+## When to ignore
+
+Anywhere that isn't server code doesn't need to use the `logger`. e.g. React components, GitHub Actions, and CLI scripts.
+
+## Auto fix
+
+This rule supports auto-fixing via `--fix`.
+
+Run `npm run lint -- --fix` to apply the changes, but please make sure to double check that the automatic fix looks correct before committing.