@hatem427/code-guard-ci 3.0.0 → 3.2.0

package/config/fastify.config.ts

@@ -0,0 +1,326 @@
+/**
+ * ============================================================================
+ * fastify.config.ts — Fastify-specific coding rules
+ * ============================================================================
+ *
+ * Registers rules that apply to Fastify projects:
+ *   - Schema-first validation enforcement
+ *   - Plugin scope correctness
+ *   - Async handler patterns
+ *   - Security: CORS, helmet, rate limiting
+ *   - Error response shape
+ *   - Hook lifecycle usage
+ */
+
+import { registerRules, Rule } from './guidelines.config';
+
+const fastifyRules: Rule[] = [
+
+  // ── Schema-First Validation ───────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: fastify-schema-required
+  // ROLE: Enforce schema definitions on all routes
+  // PURPOSE: Fastify uses JSON Schema / TypeBox for both request validation
+  //          and response serialization. Without schemas, inputs are not
+  //          validated and responses include all properties (potential data leak).
+  //          Schemas also enable Fastify's fast-json-stringify for ~2× serialization speed.
+  // EXAMPLE:
+  //   WRONG:
+  //     fastify.post('/users', async (req, reply) => {
+  //       return userService.create(req.body);
+  //     });
+  //   RIGHT:
+  //     fastify.post('/users', {
+  //       schema: {
+  //         body: CreateUserSchema,
+  //         response: { 201: UserResponseSchema },
+  //       },
+  //     }, async (req, reply) => {
+  //       return userService.create(req.body);
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'fastify-schema-required',
+    label: 'Define schema for every route (body, params, response)',
+    description:
+      'Every Fastify route must define a schema object with at minimum body/params validation and response schemas. This enables validation, serialization speed, and prevents data leaks.',
+    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('.route.ts') &&
+        !file.relativePath.endsWith('.routes.ts')
+      ) {
+        return [];
+      }
+
+      // Look for fastify.post/put/patch/delete without a schema key
+      const routeRegex = /fastify\.\s*(?:post|put|patch|delete)\s*\(\s*['"`][^'"]+['"`]\s*,\s*async/g;
+      let match;
+      while ((match = routeRegex.exec(file.content)) !== null) {
+        const near = file.content.slice(Math.max(0, match.index - 200), match.index + 50);
+        if (!near.includes('schema')) {
+          const lineNum = file.content.slice(0, match.index).split('\n').length;
+          violations.push({
+            line: lineNum,
+            message:
+              'Mutating route (POST/PUT/PATCH/DELETE) is missing a schema definition. Add body validation schema and response schema.',
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['fastify'],
+    category: 'Validation',
+  },
+
+  // ─────────────────────────────────────────
+  // RULE: fastify-response-schema
+  // ROLE: Enforce response schema definitions
+  // PURPOSE: Without a response schema, Fastify falls back to slow JSON.stringify
+  //          and may expose internal fields. Response schemas activate fast-json-stringify
+  //          and act as a serialisation allowlist.
+  // EXAMPLE:
+  //   WRONG:
+  //     fastify.get('/users/:id', async (req, reply) => { return user; });
+  //   RIGHT:
+  //     fastify.get('/users/:id', {
+  //       schema: { response: { 200: UserResponseSchema } },
+  //     }, async (req, reply) => { return user; });
+  // ─────────────────────────────────────────
+  {
+    id: 'fastify-response-schema',
+    label: 'Always define a response schema',
+    description:
+      'Define response schemas for all routes to enable fast-json-stringify serialization and prevent accidental exposure of sensitive fields.',
+    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('.route.ts') &&
+        !file.relativePath.endsWith('.routes.ts')
+      ) {
+        return [];
+      }
+
+      const hasSchema = /schema\s*:\s*\{/.test(file.content);
+      const hasResponseSchema = /response\s*:\s*\{/.test(file.content);
+
+      if (hasSchema && !hasResponseSchema) {
+        violations.push({
+          line: null,
+          message:
+            'Route schema found but no response schema defined. Add response: { 200: Schema } to enable fast serialization and prevent data leaks.',
+        });
+      }
+
+      return violations;
+    },
+    applicableTo: ['fastify'],
+    category: 'Validation',
+  },
+
+  // ── Plugin Architecture ────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: fastify-use-fastify-plugin
+  // ROLE: Enforce plugin scope correctness
+  // PURPOSE: In Fastify, plugins registered without fastify-plugin are
+  //          scoped to a child context — decorations, hooks, and routes
+  //          added inside won't be visible to siblings or the root instance.
+  //          Shared utilities (auth, db) must use fastify-plugin to break scope.
+  // EXAMPLE:
+  //   WRONG:
+  //     export async function authPlugin(fastify: FastifyInstance) {
+  //       fastify.decorate('verifyToken', verifyToken);
+  //     }
+  //   RIGHT:
+  //     import fp from 'fastify-plugin';
+  //     export default fp(async function authPlugin(fastify: FastifyInstance) {
+  //       fastify.decorate('verifyToken', verifyToken);
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'fastify-use-fastify-plugin',
+    label: 'Shared plugins must use fastify-plugin (fp)',
+    description:
+      'Plugins that add decorations, hooks, or services used by other plugins must be wrapped with fastify-plugin (fp) to share scope with the parent context.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      if (
+        !file.relativePath.includes('/plugins/') &&
+        !file.relativePath.endsWith('.plugin.ts') &&
+        !file.relativePath.endsWith('.plugin.js')
+      ) {
+        return [];
+      }
+
+      const usesDecorate = /fastify\.decorate\s*\(/.test(file.content);
+      const usesFastifyPlugin = /fastify-plugin|fp\s*\(/.test(file.content);
+
+      if (usesDecorate && !usesFastifyPlugin) {
+        return [
+          {
+            line: null,
+            message:
+              'Plugin adds decorators but is not wrapped with fastify-plugin (fp). Other plugins/routes will not see these decorations.',
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: ['fastify'],
+    category: 'Architecture',
+  },
+
+  // ── Async Handler Patterns ────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: fastify-async-handler
+  // ROLE: Enforce async handler pattern
+  // PURPOSE: Mixing reply.send() with async return values causes double-send
+  //          errors in Fastify. Async handlers should return the value;
+  //          Fastify handles serialization. Use reply.send() OR return, not both.
+  // EXAMPLE:
+  //   WRONG:
+  //     fastify.get('/users', async (req, reply) => {
+  //       const users = await userService.findAll();
+  //       reply.send(users);   // + implicit return → double send!
+  //     });
+  //   RIGHT:
+  //     fastify.get('/users', async (req, reply) => {
+  //       return userService.findAll();  // Fastify handles send automatically
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'fastify-async-handler',
+    label: 'Return values from async handlers — avoid reply.send() + return',
+    description:
+      'In async Fastify handlers, return the response value directly. Calling reply.send() AND returning a value causes a double-send error.',
+    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('.route.ts')
+      ) {
+        return [];
+      }
+
+      for (let i = 0; i < file.lines.length; i++) {
+        if (/reply\.send\s*\(/.test(file.lines[i])) {
+          // Check if there's a return after send on same or next line
+          const nearby = file.lines.slice(i, i + 3).join(' ');
+          if (/reply\.send[^;]*;\s*(?:return|})/.test(nearby)) {
+            violations.push({
+              line: i + 1,
+              message:
+                'reply.send() followed by implicit return in async handler. Use: return myValue; instead of reply.send(myValue).',
+            });
+          }
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['fastify'],
+    category: 'Async Patterns',
+  },
+
+  // ── Security ──────────────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: fastify-use-helmet
+  // ROLE: Enforce security headers
+  // PURPOSE: @fastify/helmet sets a baseline of secure HTTP headers.
+  //          Without it, Fastify serves responses without X-Frame-Options,
+  //          Content-Security-Policy, or HSTS headers.
+  // EXAMPLE:
+  //   WRONG:
+  //     const fastify = Fastify();
+  //     fastify.register(cors);
+  //   RIGHT:
+  //     const fastify = Fastify();
+  //     fastify.register(helmet);
+  //     fastify.register(cors, { origin: allowedOrigins });
+  // ─────────────────────────────────────────
+  {
+    id: 'fastify-use-helmet',
+    label: 'Register @fastify/helmet for security headers',
+    description:
+      'Register @fastify/helmet to add baseline security headers (HSTS, X-Frame-Options, CSP, etc.) to all responses.',
+    severity: 'error',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      if (
+        !file.relativePath.endsWith('server.ts') &&
+        !file.relativePath.endsWith('app.ts') &&
+        !file.relativePath.endsWith('index.ts')
+      ) {
+        return [];
+      }
+
+      const hasFastify = /Fastify\s*\(|fastify\s*\(\s*\)/.test(file.content);
+      const hasHelmet = /helmet/.test(file.content);
+
+      if (hasFastify && !hasHelmet) {
+        return [
+          {
+            line: null,
+            message:
+              'Fastify server missing @fastify/helmet. Register it: fastify.register(import("@fastify/helmet")).',
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: ['fastify'],
+    category: 'Security',
+  },
+
+  // ─────────────────────────────────────────
+  // RULE: fastify-cors-options
+  // ROLE: Enforce CORS configuration
+  // PURPOSE: Registering @fastify/cors without an origin restriction allows
+  //          cross-origin requests from any domain, defeating CORS entirely.
+  // EXAMPLE:
+  //   WRONG:
+  //     fastify.register(cors);   // allows all origins
+  //   RIGHT:
+  //     fastify.register(cors, { origin: ['https://myapp.com'] });
+  // ─────────────────────────────────────────
+  {
+    id: 'fastify-cors-options',
+    label: '@fastify/cors must restrict origin',
+    description:
+      'Do not register @fastify/cors without an explicit origin allowlist. An unrestricted CORS policy allows any website to make authenticated requests to your API.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'js'],
+    pattern: /register\s*\(\s*cors\s*\)/g,
+    applicableTo: ['fastify'],
+    category: 'Security',
+  },
+];
+
+// Register all Fastify-specific rules
+registerRules('fastify', fastifyRules);
+
+export { fastifyRules };

package/config/hono.config.ts

@@ -0,0 +1,331 @@
+/**
+ * ============================================================================
+ * hono.config.ts — Hono-specific coding rules
+ * ============================================================================
+ *
+ * Registers rules that apply to Hono (edge + server) projects:
+ *   - Zod validation enforcement
+ *   - Context variable typing
+ *   - Middleware chaining patterns
+ *   - HTTPException usage
+ *   - Environment access patterns
+ *   - Stateless / edge-first patterns
+ */
+
+import { registerRules, Rule } from './guidelines.config';
+
+const honoRules: Rule[] = [
+
+  // ── Validation ────────────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: hono-use-zod-validator
+  // ROLE: Enforce schema-based request validation
+  // PURPOSE: Accessing c.req.json() or c.req.query() without validation
+  //          passes raw untyped data to your handlers. Using @hono/zod-validator
+  //          ensures type safety and returns a 400 automatically on bad input.
+  // EXAMPLE:
+  //   WRONG:
+  //     app.post('/users', async (c) => {
+  //       const body = await c.req.json();  // untyped, unvalidated
+  //     });
+  //   RIGHT:
+  //     import { zValidator } from '@hono/zod-validator';
+  //     app.post('/users', zValidator('json', CreateUserSchema), async (c) => {
+  //       const body = c.req.valid('json');  // typed and validated
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'hono-use-zod-validator',
+    label: 'Use zValidator for request body validation',
+    description:
+      'Use @hono/zod-validator middleware on routes that accept request bodies. Calling c.req.json() directly bypasses type safety and validation.',
+    severity: 'error',
+    fileExtensions: ['ts'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      if (
+        !file.relativePath.includes('/routes/') &&
+        !file.relativePath.endsWith('.route.ts') &&
+        !file.relativePath.endsWith('.routes.ts')
+      ) {
+        return [];
+      }
+
+      // Detect routes that use c.req.json() without zValidator
+      for (let i = 0; i < file.lines.length; i++) {
+        const line = file.lines[i];
+        if (/c\.req\.json\s*\(/.test(line)) {
+          // Check surrounding context for zValidator
+          const context = file.lines.slice(Math.max(0, i - 10), i).join('\n');
+          if (!context.includes('zValidator') && !context.includes('z.object')) {
+            violations.push({
+              line: i + 1,
+              message:
+                'c.req.json() used without zValidator middleware. Use zValidator("json", schema) before the handler and access via c.req.valid("json").',
+            });
+          }
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['hono'],
+    category: 'Validation',
+  },
+
+  // ─────────────────────────────────────────
+  // RULE: hono-use-valid-not-json
+  // ROLE: Enforce validated data access after zValidator
+  // PURPOSE: After applying zValidator middleware, handlers must use
+  //          c.req.valid() to access the validated, typed data.
+  //          c.req.json() bypasses validation and returns raw untyped data.
+  // EXAMPLE:
+  //   WRONG:
+  //     app.post('/user', zValidator('json', schema), async (c) => {
+  //       const body = await c.req.json(); // still untyped!
+  //     });
+  //   RIGHT:
+  //     app.post('/user', zValidator('json', schema), async (c) => {
+  //       const body = c.req.valid('json'); // typed + validated
+  //     });
+  // ─────────────────────────────────────────
+  {
+    id: 'hono-use-valid-not-json',
+    label: 'After zValidator, use c.req.valid() not c.req.json()',
+    description:
+      'When zValidator middleware is applied, access validated data via c.req.valid("json") instead of await c.req.json(). The latter bypasses type narrowing.',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      if (!file.content.includes('zValidator')) return [];
+
+      for (let i = 0; i < file.lines.length; i++) {
+        if (/await c\.req\.json\s*\(/.test(file.lines[i])) {
+          violations.push({
+            line: i + 1,
+            message:
+              'zValidator is used in this file. Replace await c.req.json() with c.req.valid("json") to access the typed validated data.',
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['hono'],
+    category: 'Validation',
+  },
+
+  // ── Error Handling ────────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: hono-use-http-exception
+  // ROLE: Enforce HTTPException for expected errors
+  // PURPOSE: Throwing a raw Error in a Hono handler produces a generic 500
+  //          response with no meaningful body. HTTPException allows you to set
+  //          a specific status code and message that will be formatted by
+  //          Hono's onError handler consistently.
+  // EXAMPLE:
+  //   WRONG:
+  //     throw new Error('User not found');
+  //   RIGHT:
+  //     throw new HTTPException(404, { message: 'User not found' });
+  // ─────────────────────────────────────────
+  {
+    id: 'hono-use-http-exception',
+    label: 'Use HTTPException instead of raw Error',
+    description:
+      'Throw HTTPException from hono with a status code and message for expected errors (404, 401, 400, etc.). Raw Error objects produce unformatted 500 responses.',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      if (
+        !file.relativePath.includes('/routes/') &&
+        !file.relativePath.includes('/handlers/') &&
+        !file.relativePath.endsWith('.route.ts') &&
+        !file.relativePath.endsWith('.handler.ts')
+      ) {
+        return [];
+      }
+
+      for (let i = 0; i < file.lines.length; i++) {
+        if (/throw\s+new\s+Error\s*\(/.test(file.lines[i])) {
+          violations.push({
+            line: i + 1,
+            message:
+              'Raw Error thrown. Use HTTPException: throw new HTTPException(404, { message: "Not found" })',
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['hono'],
+    category: 'Error Handling',
+  },
+
+  // ── Context Variables ─────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: hono-type-context-variables
+  // ROLE: Enforce typed context variables
+  // PURPOSE: Using c.get() and c.set() without typed Variables means the
+  //          TypeScript compiler cannot verify keys exist, leading to
+  //          undefined value bugs at runtime.
+  // EXAMPLE:
+  //   WRONG:
+  //     app.use(async (c, next) => {
+  //       c.set('user', user); // no type checking on 'user' key
+  //     });
+  //   RIGHT:
+  //     type Variables = { user: User };
+  //     const app = new Hono<{ Variables: Variables }>();
+  //     app.use(async (c, next) => { c.set('user', user); });
+  // ─────────────────────────────────────────
+  {
+    id: 'hono-type-context-variables',
+    label: 'Type context Variables for c.get() / c.set()',
+    description:
+      'Declare a typed Variables interface and pass it as a generic to new Hono<{ Variables: Variables }>(). This enables TypeScript to validate context variable keys and values.',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: null,
+    customCheck: (file) => {
+      const hasContextSet = /c\.set\s*\(/.test(file.content);
+      const hasHonoGeneric = /new\s+Hono\s*</.test(file.content);
+      const hasVariablesType = /Variables\s*=\s*\{/.test(file.content);
+
+      if (hasContextSet && !hasHonoGeneric && !hasVariablesType) {
+        return [
+          {
+            line: null,
+            message:
+              'c.set() is used without typed Variables. Define: type Variables = { ... } and use new Hono<{ Variables: Variables }>().',
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: ['hono'],
+    category: 'Type Safety',
+  },
+
+  // ── Environment Access ────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: hono-use-c-env
+  // ROLE: Enforce correct env access on edge runtimes
+  // PURPOSE: On Cloudflare Workers and similar runtimes, process.env is
+  //          unavailable. Environment bindings are accessed via c.env.
+  //          Even on Node.js, centralising env access via c.env makes
+  //          the app portable across runtimes.
+  // EXAMPLE:
+  //   WRONG:
+  //     const secret = process.env['JWT_SECRET'];
+  //   RIGHT:
+  //     // In Hono handler:
+  //     const secret = c.env.JWT_SECRET;
+  // ─────────────────────────────────────────
+  {
+    id: 'hono-use-c-env',
+    label: 'Use c.env for environment variables (edge-compatible)',
+    description:
+      'Prefer c.env over process.env for environment variables. process.env is not available in Cloudflare Workers or Deno and makes apps runtime-specific.',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      if (
+        !file.relativePath.includes('/routes/') &&
+        !file.relativePath.includes('/handlers/') &&
+        !file.relativePath.endsWith('.route.ts') &&
+        !file.relativePath.endsWith('.handler.ts') &&
+        !file.relativePath.endsWith('.middleware.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 used in Hono handler/route. Use c.env.VARIABLE_NAME for edge-runtime portability.',
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['hono'],
+    category: 'Security',
+  },
+
+  // ── Route Organisation ────────────────────────────────────────────────────
+
+  // ─────────────────────────────────────────
+  // RULE: hono-use-sub-apps
+  // ROLE: Enforce composable route architecture
+  // PURPOSE: Defining all routes on a single root Hono instance leads to a
+  //          monolithic file. Sub-apps (separate Hono instances per domain)
+  //          composed via app.route() enable feature isolation and per-domain
+  //          middleware application.
+  // EXAMPLE:
+  //   WRONG:
+  //     app.get('/users', ...)
+  //     app.post('/users', ...)
+  //     app.get('/products', ...)   // all in one file
+  //   RIGHT:
+  //     // users.route.ts
+  //     const users = new Hono();
+  //     users.get('/', ...)
+  //     export default users;
+  //     // app.ts
+  //     app.route('/users', users);
+  // ─────────────────────────────────────────
+  {
+    id: 'hono-use-sub-apps',
+    label: 'Organise routes as Hono sub-apps using app.route()',
+    description:
+      'Define each domain\'s routes in a separate Hono sub-app and compose them via app.route("/prefix", subApp). Avoid putting all routes on a single root instance.',
+    severity: 'info',
+    fileExtensions: ['ts'],
+    pattern: null,
+    customCheck: (file) => {
+      if (!file.relativePath.endsWith('index.ts') && !file.relativePath.endsWith('app.ts')) {
+        return [];
+      }
+
+      const routeCount = (file.content.match(/app\.\s*(?:get|post|put|patch|delete)\s*\(/g) || []).length;
+
+      if (routeCount > 5) {
+        return [
+          {
+            line: null,
+            message: `${routeCount} routes defined on a single Hono instance. Extract into domain sub-apps and use app.route('/prefix', subApp).`,
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: ['hono'],
+    category: 'Architecture',
+  },
+];
+
+// Register all Hono-specific rules
+registerRules('hono', honoRules);
+
+export { honoRules };