@hatem427/code-guard-ci 3.0.0 → 3.1.0

package/config/node.config.ts

@@ -0,0 +1,425 @@
+/**
+ * ============================================================================
+ * node.config.ts — Express / Node.js-specific coding rules
+ * ============================================================================
+ *
+ * Registers rules that apply to Express and generic Node.js backend projects:
+ *   - Route handler / service separation
+ *   - Async error propagation
+ *   - Input validation enforcement
+ *   - Security: helmet, CORS, parameterized queries
+ *   - Environment configuration patterns
+ *   - Graceful shutdown
+ */
+
+import { registerRules, Rule } from './guidelines.config';
+
+const nodeRules: Rule[] = [
+
+  // ── Architecture ──────────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: node-thin-route-handler
+  // ROLE: Enforce separation of HTTP concerns from business logic
+  // PURPOSE: Route handlers that contain business logic cannot be unit-tested
+  //          without spinning up an Express server. Logic should live in
+  //          service functions that are independently testable.
+  // EXAMPLE:
+  //   WRONG:
+  //     router.post('/users', async (req, res) => {
+  //       const salt = await bcrypt.genSalt();
+  //       const hash = await bcrypt.hash(req.body.password, salt);
+  //       const user = await db.users.create({ ...req.body, password: hash });
+  //       res.status(201).json(user);
+  //     });
+  //   RIGHT:
+  //     router.post('/users', async (req, res, next) => {
+  //       try {
+  //         const user = await userService.createUser(req.body);
+  //         res.status(201).json(user);
+  //       } catch (err) { next(err); }
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'node-thin-route-handler',
+    label: 'Keep route handlers thin — delegate to services',
+    description:
+      'Route handlers should only parse the request, call a service, and send the response. Business logic belongs in service modules.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      if (
+        !file.relativePath.includes('/routes/') &&
+        !file.relativePath.endsWith('.router.ts') &&
+        !file.relativePath.endsWith('.routes.ts')
+      ) {
+        return [];
+      }
+
+      const businessPatterns = [
+        { regex: /bcrypt\.(hash|compare|genSalt)/g, label: 'bcrypt hashing' },
+        { regex: /\.save\s*\(|\.create\s*\(/g, label: 'direct ORM calls' },
+        { regex: /jwt\.sign|jwt\.verify/g, label: 'JWT operations' },
+      ];
+
+      for (let i = 0; i < file.lines.length; i++) {
+        for (const { regex, label } of businessPatterns) {
+          regex.lastIndex = 0;
+          if (regex.test(file.lines[i])) {
+            violations.push({
+              line: i + 1,
+              message: `Business logic (${label}) found in route handler. Move to a service module.`,
+            });
+          }
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['node'],
+    category: 'Architecture',
+  },
+
+  // ── Async & Error Handling ─────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: node-async-next-error
+  // ROLE: Enforce error propagation in async route handlers
+  // PURPOSE: Without next(err), an error thrown in an async handler
+  //          produces an unhandled promise rejection, not a proper HTTP 500.
+  //          Wrapping with try/catch + next(err) — or using express-async-errors
+  //          — ensures errors reach the global error-handling middleware.
+  // EXAMPLE:
+  //   WRONG:
+  //     router.get('/users', async (req, res) => {
+  //       const users = await userService.findAll(); // throws → unhandled rejection
+  //       res.json(users);
+  //     });
+  //   RIGHT:
+  //     router.get('/users', async (req, res, next) => {
+  //       try {
+  //         const users = await userService.findAll();
+  //         res.json(users);
+  //       } catch (err) { next(err); }
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'node-async-next-error',
+    label: 'Async route handlers must forward errors to next()',
+    description:
+      'Async Express route handlers must use try/catch and call next(err) on failure, or use express-async-errors. Unhandled rejections bypass error-handling middleware.',
+    severity: 'error',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      if (
+        !file.relativePath.includes('/routes/') &&
+        !file.relativePath.endsWith('.router.ts') &&
+        !file.relativePath.endsWith('.routes.ts') &&
+        !file.relativePath.endsWith('.router.js')
+      ) {
+        return [];
+      }
+
+      // Detect async route handlers without try/catch or next(err)
+      const asyncHandlerRegex = /router\.\w+\(['"`][^'"]+['"`]\s*,\s*async\s*\(req/g;
+      let match;
+      while ((match = asyncHandlerRegex.exec(file.content)) !== null) {
+        const afterMatch = file.content.slice(match.index, match.index + 500);
+        if (!afterMatch.includes('try {') && !afterMatch.includes('next(err')) {
+          // Approximate line number
+          const lineNum = file.content.slice(0, match.index).split('\n').length;
+          violations.push({
+            line: lineNum,
+            message:
+              'Async route handler without error handling. Wrap with try/catch and call next(err), or install express-async-errors.',
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['node'],
+    category: 'Error Handling',
+  },
+
+  // ─────────────────────────────────────────
+  // RULE: node-error-middleware-signature
+  // ROLE: Enforce 4-argument error middleware signature
+  // PURPOSE: Express only treats a middleware as an error handler when it
+  //          has exactly 4 parameters (err, req, res, next). A 3-param
+  //          function that happens to receive an error object will not work.
+  // EXAMPLE:
+  //   WRONG:
+  //     app.use((err, res) => { res.status(500).json({ error: err.message }); });
+  //   RIGHT:
+  //     app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  //       res.status(err.statusCode ?? 500).json({ message: err.message });
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'node-error-middleware-signature',
+    label: 'Global error handler must have 4 parameters (err, req, res, next)',
+    description:
+      'Express error-handling middleware must declare exactly 4 parameters: (err, req, res, next). With fewer params, Express will not recognise it as an error handler.',
+    severity: 'error',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      if (
+        !file.relativePath.includes('error') &&
+        !file.relativePath.includes('middleware') &&
+        !file.relativePath.endsWith('app.ts') &&
+        !file.relativePath.endsWith('server.ts')
+      ) {
+        return [];
+      }
+
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      for (let i = 0; i < file.lines.length; i++) {
+        const line = file.lines[i];
+        // Detect app.use with callback that looks like error handler but has <4 params
+        if (/app\.use\s*\(\s*(?:['"`][^']+['"`]\s*,\s*)?\s*(?:async\s*)?\([^)]*\)\s*=>/.test(line)) {
+          const params = (line.match(/\(([^)]*)\)/) || [])[1] || '';
+          const count = params.split(',').filter((p: string) => p.trim()).length;
+          if (count === 3 && /err|error/i.test(params)) {
+            violations.push({
+              line: i + 1,
+              message:
+                'Error-handling middleware must declare 4 parameters: (err, req, res, next). Express uses arity to detect error handlers.',
+            });
+          }
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['node'],
+    category: 'Error Handling',
+  },
+
+  // ── Input Validation ──────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: node-validate-request-body
+  // ROLE: Enforce input sanitisation before use
+  // PURPOSE: Using req.body without validation exposes the service to
+  //          malformed data, SQL injection, and XSS. Every route that reads
+  //          req.body must apply a schema validation middleware first.
+  // EXAMPLE:
+  //   WRONG:
+  //     router.post('/users', async (req, res) => {
+  //       const { email, name } = req.body; // unvalidated
+  //     });
+  //   RIGHT:
+  //     import { createUserSchema } from '../schemas/user.schema';
+  //     router.post('/users', validate(createUserSchema), async (req, res) => { ... });
+  // ─────────────────────────────────────────
+  {
+    id: 'node-validate-request-body',
+    label: 'Validate req.body before use',
+    description:
+      'Always define and apply a validation schema (Zod, Joi, express-validator) for routes that read req.body. Unvalidated input is the root cause of most injection vulnerabilities.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      if (
+        !file.relativePath.includes('/routes/') &&
+        !file.relativePath.endsWith('.router.ts') &&
+        !file.relativePath.endsWith('.routes.ts')
+      ) {
+        return [];
+      }
+
+      const hasValidation = /validate\s*\(|zValidator|z\.object|Joi\.object|checkSchema|body\s*\(/.test(file.content);
+
+      if (!hasValidation && /req\.body/.test(file.content)) {
+        violations.push({
+          line: null,
+          message:
+            'req.body is used without any visible validation middleware (Zod, Joi, express-validator). Add a schema validation step before the route handler.',
+        });
+      }
+
+      return violations;
+    },
+    applicableTo: ['node'],
+    category: 'Security',
+  },
+
+  // ── Security ──────────────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: node-use-helmet
+  // ROLE: Enforce security headers
+  // PURPOSE: Without Helmet, Express servers are vulnerable to well-known
+  //          HTTP header-based attacks (clickjacking, MIME-sniffing, XSS via
+  //          missing CSP). Helmet sets a secure baseline in one call.
+  // EXAMPLE:
+  //   WRONG:
+  //     const app = express();
+  //     app.use(cors());
+  //   RIGHT:
+  //     const app = express();
+  //     app.use(helmet());
+  //     app.use(cors({ origin: allowedOrigins }));
+  // ─────────────────────────────────────────
+  {
+    id: 'node-use-helmet',
+    label: 'Use helmet() for security headers',
+    description:
+      'Apply helmet() middleware in the Express app setup to set secure HTTP headers (Content-Security-Policy, X-Frame-Options, HSTS, etc.).',
+    severity: 'error',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      if (
+        !file.relativePath.endsWith('app.ts') &&
+        !file.relativePath.endsWith('server.ts') &&
+        !file.relativePath.endsWith('app.js') &&
+        !file.relativePath.endsWith('server.js')
+      ) {
+        return [];
+      }
+
+      const hasExpress = /express\s*\(\s*\)/.test(file.content);
+      const hasHelmet = /helmet\s*\(\s*\)/.test(file.content);
+
+      if (hasExpress && !hasHelmet) {
+        return [
+          {
+            line: null,
+            message:
+              'Express app is missing helmet(). Install helmet and add app.use(helmet()) before other middleware.',
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: ['node'],
+    category: 'Security',
+  },
+
+  // ─────────────────────────────────────────
+  // RULE: node-no-process-env-scatter
+  // ROLE: Centralise configuration access
+  // PURPOSE: Using process.env in route handlers and services scatters
+  //          configuration reads, prevents startup validation, and makes
+  //          tests hard to write (no clean injection point).
+  //          Validate env vars once at startup in a config module.
+  // EXAMPLE:
+  //   WRONG:
+  //     const secret = process.env['JWT_SECRET'];
+  //   RIGHT:
+  //     import { config } from '../config'; // validated at startup
+  //     const secret = config.jwtSecret;
+  // ─────────────────────────────────────────
+  {
+    id: 'node-no-process-env-scatter',
+    label: 'Centralise process.env access in a config module',
+    description:
+      'Do not read process.env in route handlers, services, or models. Validate env vars at startup in a dedicated config module and import from there.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      // Skip config/env files
+      if (
+        file.relativePath.includes('/config/') ||
+        file.relativePath.includes('.config.') ||
+        file.relativePath.endsWith('env.ts') ||
+        file.relativePath.endsWith('env.js') ||
+        file.relativePath.endsWith('main.ts') ||
+        file.relativePath.endsWith('server.ts')
+      ) {
+        return [];
+      }
+
+      for (let i = 0; i < file.lines.length; i++) {
+        if (/process\.env\b/.test(file.lines[i])) {
+          violations.push({
+            line: i + 1,
+            message:
+              'process.env read inside business code. Move to a config module (validated at startup) and import from there.',
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['node'],
+    category: 'Security',
+  },
+
+  // ── Graceful Shutdown ─────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: node-graceful-shutdown
+  // ROLE: Enforce graceful process shutdown
+  // PURPOSE: Without SIGTERM handling, a Node.js server terminates
+  //          immediately when the container or OS signals shutdown.
+  //          In-flight requests are cut short, and DB connections leak.
+  //          Graceful shutdown waits for open connections to close first.
+  // EXAMPLE:
+  //   WRONG:
+  //     server.listen(port);
+  //   RIGHT:
+  //     server.listen(port);
+  //     process.on('SIGTERM', () => {
+  //       server.close(() => { db.end(); process.exit(0); });
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'node-graceful-shutdown',
+    label: 'Handle SIGTERM for graceful shutdown',
+    description:
+      'Listen for SIGTERM and SIGINT signals to close the HTTP server and DB connections gracefully before exiting. Required in containerised environments.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      if (
+        !file.relativePath.endsWith('main.ts') &&
+        !file.relativePath.endsWith('server.ts') &&
+        !file.relativePath.endsWith('index.ts') &&
+        !file.relativePath.endsWith('server.js')
+      ) {
+        return [];
+      }
+
+      const hasSigterm = /SIGTERM|SIGINT/.test(file.content);
+      const hasServerListen = /\.listen\s*\(/.test(file.content);
+
+      if (hasServerListen && !hasSigterm) {
+        return [
+          {
+            line: null,
+            message:
+              'Server starts but no SIGTERM/SIGINT handler found. Add graceful shutdown: process.on("SIGTERM", () => server.close(() => process.exit(0)))',
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: ['node'],
+    category: 'Reliability',
+  },
+];
+
+// Register all Node.js (Express) specific rules
+registerRules('node', nodeRules);
+
+export { nodeRules };