Feat/compt 82 custom indicator api and health service

.husky/pre-commit

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 npx lint-staged

eslint.config.mjs

@@ -1,42 +1,80 @@
 // @ts-check
 import eslint from "@eslint/js";
-import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
 import globals from "globals";
+import importPlugin from "eslint-plugin-import";
 import tseslint from "typescript-eslint";
 
-export default tseslint.config(
+export default [
   {
-    ignores: ["eslint.config.mjs"],
+    ignores: [
+      "dist/**",
+      "coverage/**",
+      "node_modules/**",
+      // Ignore all example files for CSR architecture
+      "src/example-kit.*",
+      "src/controllers/example.controller.ts",
+      "src/services/example.service.ts",
+      "src/entities/example.entity.ts",
+      "src/repositories/example.repository.ts",
+      "src/guards/example.guard.ts",
+      "src/decorators/example.decorator.ts",
+      "src/dto/create-example.dto.ts",
+      "src/dto/update-example.dto.ts",
+    ],
   },
+
   eslint.configs.recommended,
-  ...tseslint.configs.recommendedTypeChecked,
-  eslintPluginPrettierRecommended,
+
+  // TypeScript ESLint (includes recommended rules)
+  ...tseslint.configs.recommended,
+
+  // Base TS rules (all TS files)
   {
+    files: ["**/*.ts"],
     languageOptions: {
-      globals: {
-        ...globals.node,
-        ...globals.jest,
-      },
-      sourceType: "commonjs",
+      parser: tseslint.parser,
       parserOptions: {
-        projectService: true,
+        project: "./tsconfig.eslint.json",
         tsconfigRootDir: import.meta.dirname,
+        ecmaVersion: "latest",
+        sourceType: "module",
       },
+      globals: { ...globals.node, ...globals.jest },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint.plugin,
+      import: importPlugin,
+    },
+    rules: {
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "@typescript-eslint/consistent-type-imports": ["error", { prefer: "type-imports" }],
+
+      "import/no-duplicates": "error",
+      "import/order": [
+        "error",
+        {
+          "newlines-between": "always",
+          alphabetize: { order: "asc", caseInsensitive: true },
+        },
+      ],
     },
   },
+
+  // Architecture boundary: core must not import Nest
   {
+    files: ["src/core/**/*.ts"],
     rules: {
-      "@typescript-eslint/no-explicit-any": "off",
-      "@typescript-eslint/no-floating-promises": "warn",
-      "@typescript-eslint/no-unsafe-argument": "warn",
-      "@typescript-eslint/no-unused-vars": [
+      "no-restricted-imports": [
         "error",
         {
-          argsIgnorePattern: "^_",
-          varsIgnorePattern: "^_",
+          patterns: [
+            {
+              group: ["@nestjs/*"],
+              message: "Do not import NestJS in core/. Keep core framework-free.",
+            },
+          ],
         },
       ],
-      "no-unused-vars": "off",
     },
   },
-);
+];

jest.config.ts

@@ -46,6 +46,8 @@ const config: Config = {
     "^@filters/(.*)$": "<rootDir>/src/filters/$1",
     "^@middleware/(.*)$": "<rootDir>/src/middleware/$1",
     "^@utils/(.*)$": "<rootDir>/src/utils/$1",
+    "^@interfaces/(.*)$": "<rootDir>/src/interfaces/$1",
+    "^@indicators/(.*)$": "<rootDir>/src/indicators/$1",
   },
 };
 

package.json

@@ -1,7 +1,7 @@
 {
-  "name": "@ciscode/nestjs-developerkit",
+  "name": "@ciscode/health-kit",
   "version": "1.0.0",
-  "description": "Template for NestJS developer kits (npm packages).",
+  "description": "NestJS health-check module — liveness & readiness probes with built-in PostgreSQL, Redis, and HTTP indicators.",
   "author": "CisCode",
   "publishConfig": {
     "access": "public"
@@ -45,10 +45,15 @@
   "peerDependencies": {
     "@nestjs/common": "^10 || ^11",
     "@nestjs/core": "^10 || ^11",
-    "@nestjs/platform-express": "^10 || ^11",
+    "@nestjs/terminus": "^10 || ^11",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7"
   },
+  "peerDependenciesMeta": {
+    "@nestjs/terminus": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1"

src/controllers/health.controller.spec.ts

@@ -0,0 +1,62 @@
+import { ServiceUnavailableException } from "@nestjs/common";
+import type { TestingModule } from "@nestjs/testing";
+import { Test } from "@nestjs/testing";
+import { HealthService } from "@services/health.service";
+import type { HealthCheckResult } from "@services/health.service";
+
+import { createHealthController } from "./health.controller";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const makeService = (liveness: "ok" | "error", readiness: "ok" | "error") =>
+  ({
+    checkLiveness: jest.fn().mockResolvedValue({ status: liveness, indicators: [] }),
+    checkReadiness: jest.fn().mockResolvedValue({ status: readiness, indicators: [] }),
+  }) as unknown as HealthService;
+
+interface HealthControllerInstance {
+  live(): Promise<HealthCheckResult>;
+  ready(): Promise<HealthCheckResult>;
+}
+
+async function buildController(
+  liveness: "ok" | "error",
+  readiness: "ok" | "error",
+): Promise<HealthControllerInstance> {
+  const HealthController = createHealthController("health");
+  const moduleRef: TestingModule = await Test.createTestingModule({
+    controllers: [HealthController],
+    providers: [{ provide: HealthService, useValue: makeService(liveness, readiness) }],
+  }).compile();
+  return moduleRef.get<HealthControllerInstance>(HealthController as never);
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("HealthController (factory)", () => {
+  describe("GET /health/live", () => {
+    it("returns result when all liveness indicators are up", async () => {
+      const controller = await buildController("ok", "ok");
+      const result = await controller.live();
+      expect(result.status).toBe("ok");
+    });
+
+    it("throws ServiceUnavailableException (503) when any liveness indicator is down", async () => {
+      const controller = await buildController("error", "ok");
+      await expect(controller.live()).rejects.toThrow(ServiceUnavailableException);
+    });
+  });
+
+  describe("GET /health/ready", () => {
+    it("returns result when all readiness indicators are up", async () => {
+      const controller = await buildController("ok", "ok");
+      const result = await controller.ready();
+      expect(result.status).toBe("ok");
+    });
+
+    it("throws ServiceUnavailableException (503) when any readiness indicator is down", async () => {
+      const controller = await buildController("ok", "error");
+      await expect(controller.ready()).rejects.toThrow(ServiceUnavailableException);
+    });
+  });
+});

src/controllers/health.controller.ts

@@ -0,0 +1,43 @@
+import {
+  Controller,
+  Get,
+  HttpCode,
+  HttpStatus,
+  ServiceUnavailableException,
+  Type,
+} from "@nestjs/common";
+import { HealthService } from "@services/health.service";
+import type { HealthCheckResult } from "@services/health.service";
+
+/**
+ * Factory that returns a NestJS controller class configured with the
+ * caller-supplied `path` prefix (e.g. `"health"`).
+ *
+ * Platform-agnostic — works with Express and Fastify.
+ * Returns 200 when all indicators are "up",
+ * throws ServiceUnavailableException (503) when any indicator is "down".
+ */
+export function createHealthController(path: string): Type<unknown> {
+  @Controller(path)
+  class HealthController {
+    constructor(private readonly healthService: HealthService) {}
+
+    @Get("live")
+    @HttpCode(HttpStatus.OK)
+    async live(): Promise<HealthCheckResult> {
+      const result = await this.healthService.checkLiveness();
+      if (result.status === "error") throw new ServiceUnavailableException(result);
+      return result;
+    }
+
+    @Get("ready")
+    @HttpCode(HttpStatus.OK)
+    async ready(): Promise<HealthCheckResult> {
+      const result = await this.healthService.checkReadiness();
+      if (result.status === "error") throw new ServiceUnavailableException(result);
+      return result;
+    }
+  }
+
+  return HealthController;
+}

src/decorators/health-indicator.decorator.spec.ts

@@ -0,0 +1,36 @@
+import "reflect-metadata";
+import { HEALTH_INDICATOR_METADATA, HealthIndicator } from "./health-indicator.decorator";
+
+class SomeIndicator {}
+class AnotherIndicator {}
+class UndecotratedIndicator {}
+
+@HealthIndicator("liveness")
+class LivenessIndicator extends SomeIndicator {}
+
+@HealthIndicator("readiness")
+class ReadinessIndicator extends AnotherIndicator {}
+
+describe("@HealthIndicator decorator", () => {
+  it("attaches liveness metadata to the target class", () => {
+    const scope = Reflect.getMetadata(HEALTH_INDICATOR_METADATA, LivenessIndicator);
+    expect(scope).toBe("liveness");
+  });
+
+  it("attaches readiness metadata to the target class", () => {
+    const scope = Reflect.getMetadata(HEALTH_INDICATOR_METADATA, ReadinessIndicator);
+    expect(scope).toBe("readiness");
+  });
+
+  it("returns undefined for undecorated classes", () => {
+    const scope = Reflect.getMetadata(HEALTH_INDICATOR_METADATA, UndecotratedIndicator);
+    expect(scope).toBeUndefined();
+  });
+
+  it("does not affect other classes when decorating one", () => {
+    const livScope = Reflect.getMetadata(HEALTH_INDICATOR_METADATA, LivenessIndicator);
+    const readScope = Reflect.getMetadata(HEALTH_INDICATOR_METADATA, ReadinessIndicator);
+    expect(livScope).toBe("liveness");
+    expect(readScope).toBe("readiness");
+  });
+});