@checkstack/healthcheck-jenkins-backend 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @checkstack/healthcheck-jenkins-backend
+
+## 0.2.0
+
+### Minor Changes
+
+- 97c5a6b: Add Jenkins health check strategy with 5 collectors
+
+  - **Jenkins Strategy**: Transport client for Jenkins REST API with Basic Auth (username + API token)
+  - **Server Info Collector**: Jenkins version, mode, executor count, job count
+  - **Job Status Collector**: Individual job monitoring, last build status, build duration
+  - **Build History Collector**: Analyze recent builds for trends (success rate, avg duration)
+  - **Queue Info Collector**: Monitor build queue length, wait times, stuck items
+  - **Node Health Collector**: Agent availability, executor utilization
+
+### Patch Changes
+
+- Updated dependencies [97c5a6b]
+- Updated dependencies [8e43507]
+- Updated dependencies [97c5a6b]
+  - @checkstack/backend-api@0.2.0
+  - @checkstack/common@0.1.0
+  - @checkstack/healthcheck-common@0.2.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@checkstack/healthcheck-jenkins-backend",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/collectors/build-history.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+import { BuildHistoryCollector } from "./build-history";
+import type {
+  JenkinsTransportClient,
+  JenkinsResponse,
+} from "../transport-client";
+
+describe("BuildHistoryCollector", () => {
+  const collector = new BuildHistoryCollector();
+
+  const createMockClient = (
+    response: JenkinsResponse
+  ): JenkinsTransportClient => ({
+    exec: async () => response,
+  });
+
+  it("should collect build history successfully", async () => {
+    const mockClient = createMockClient({
+      statusCode: 200,
+      data: {
+        builds: [
+          { number: 10, result: "SUCCESS", duration: 60000 },
+          { number: 9, result: "SUCCESS", duration: 55000 },
+          { number: 8, result: "FAILURE", duration: 40000 },
+          { number: 7, result: "UNSTABLE", duration: 70000 },
+          { number: 6, result: "SUCCESS", duration: 65000 },
+        ],
+      },
+    });
+
+    const result = await collector.execute({
+      config: { jobName: "my-job", buildCount: 10 },
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result.totalBuilds).toBe(5);
+    expect(result.result.successCount).toBe(3);
+    expect(result.result.failureCount).toBe(1);
+    expect(result.result.unstableCount).toBe(1);
+    expect(result.result.successRate).toBe(60);
+    expect(result.result.avgDurationMs).toBe(58000);
+    expect(result.result.minDurationMs).toBe(40000);
+    expect(result.result.maxDurationMs).toBe(70000);
+    expect(result.result.lastSuccessBuildNumber).toBe(10);
+    expect(result.result.lastFailureBuildNumber).toBe(8);
+  });
+
+  it("should handle empty builds array", async () => {
+    const mockClient = createMockClient({
+      statusCode: 200,
+      data: { builds: [] },
+    });
+
+    const result = await collector.execute({
+      config: { jobName: "new-job", buildCount: 10 },
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result.totalBuilds).toBe(0);
+    expect(result.result.successRate).toBe(0);
+  });
+
+  it("should aggregate correctly", () => {
+    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          totalBuilds: 10,
+          successCount: 8,
+          failureCount: 1,
+          unstableCount: 1,
+          abortedCount: 0,
+          successRate: 80,
+          avgDurationMs: 60000,
+          minDurationMs: 40000,
+          maxDurationMs: 80000,
+        },
+      },
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          totalBuilds: 10,
+          successCount: 6,
+          failureCount: 2,
+          unstableCount: 1,
+          abortedCount: 1,
+          successRate: 60,
+          avgDurationMs: 80000,
+          minDurationMs: 50000,
+          maxDurationMs: 100000,
+        },
+      },
+    ];
+
+    const aggregated = collector.aggregateResult(runs);
+
+    expect(aggregated.avgSuccessRate).toBe(70);
+    expect(aggregated.avgBuildDuration).toBe(70000);
+  });
+});

package/src/collectors/build-history.ts

@@ -0,0 +1,280 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import { healthResultNumber } from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "../plugin-metadata";
+import type { JenkinsTransportClient } from "../transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const buildHistoryConfigSchema = z.object({
+  jobName: z
+    .string()
+    .min(1)
+    .describe("Full job path (e.g., 'folder/job-name' or 'my-job')"),
+  buildCount: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(10)
+    .describe("Number of recent builds to analyze"),
+});
+
+export type BuildHistoryConfig = z.infer<typeof buildHistoryConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const buildHistoryResultSchema = z.object({
+  totalBuilds: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Total Builds",
+  }),
+  successCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Successful",
+  }),
+  failureCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Failed",
+  }),
+  unstableCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Unstable",
+  }),
+  abortedCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Aborted",
+  }),
+  successRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Success Rate",
+    "x-chart-unit": "%",
+  }),
+  avgDurationMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Duration",
+    "x-chart-unit": "ms",
+  }),
+  minDurationMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Min Duration",
+    "x-chart-unit": "ms",
+  }),
+  maxDurationMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Max Duration",
+    "x-chart-unit": "ms",
+  }),
+  lastSuccessBuildNumber: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Last Success #",
+  }).optional(),
+  lastFailureBuildNumber: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Last Failure #",
+  }).optional(),
+});
+
+export type BuildHistoryResult = z.infer<typeof buildHistoryResultSchema>;
+
+const buildHistoryAggregatedSchema = z.object({
+  avgSuccessRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Avg Success Rate",
+    "x-chart-unit": "%",
+  }),
+  avgBuildDuration: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Build Duration",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type BuildHistoryAggregatedResult = z.infer<
+  typeof buildHistoryAggregatedSchema
+>;
+
+// ============================================================================
+// BUILD HISTORY COLLECTOR
+// ============================================================================
+
+/**
+ * Collector for Jenkins build history.
+ * Analyzes recent builds for trends and patterns.
+ */
+export class BuildHistoryCollector
+  implements
+    CollectorStrategy<
+      JenkinsTransportClient,
+      BuildHistoryConfig,
+      BuildHistoryResult,
+      BuildHistoryAggregatedResult
+    >
+{
+  id = "build-history";
+  displayName = "Build History";
+  description = "Analyze recent build trends for a Jenkins job";
+
+  supportedPlugins = [pluginMetadata];
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: buildHistoryConfigSchema });
+  result = new Versioned({ version: 1, schema: buildHistoryResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: buildHistoryAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: BuildHistoryConfig;
+    client: JenkinsTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<BuildHistoryResult>> {
+    // Encode job path for URL (handle folders)
+    const jobPath = config.jobName
+      .split("/")
+      .map((part) => `job/${encodeURIComponent(part)}`)
+      .join("/");
+
+    const response = await client.exec({
+      path: `/${jobPath}/api/json`,
+      query: {
+        tree: `builds[number,result,duration,timestamp]{0,${config.buildCount}}`,
+      },
+    });
+
+    if (response.error) {
+      return {
+        result: {
+          totalBuilds: 0,
+          successCount: 0,
+          failureCount: 0,
+          unstableCount: 0,
+          abortedCount: 0,
+          successRate: 0,
+          avgDurationMs: 0,
+          minDurationMs: 0,
+          maxDurationMs: 0,
+        },
+        error: response.error,
+      };
+    }
+
+    const data = response.data as {
+      builds?: Array<{
+        number?: number;
+        result?: string;
+        duration?: number;
+        timestamp?: number;
+      }>;
+    };
+
+    const builds = data.builds || [];
+
+    // Count results
+    let successCount = 0;
+    let failureCount = 0;
+    let unstableCount = 0;
+    let abortedCount = 0;
+    let lastSuccessBuildNumber: number | undefined;
+    let lastFailureBuildNumber: number | undefined;
+
+    const durations: number[] = [];
+
+    for (const build of builds) {
+      if (build.duration !== undefined) {
+        durations.push(build.duration);
+      }
+
+      switch (build.result) {
+        case "SUCCESS": {
+          successCount++;
+          if (lastSuccessBuildNumber === undefined) {
+            lastSuccessBuildNumber = build.number;
+          }
+          break;
+        }
+        case "FAILURE": {
+          failureCount++;
+          if (lastFailureBuildNumber === undefined) {
+            lastFailureBuildNumber = build.number;
+          }
+          break;
+        }
+        case "UNSTABLE": {
+          unstableCount++;
+          break;
+        }
+        case "ABORTED": {
+          abortedCount++;
+          break;
+        }
+      }
+    }
+
+    const totalBuilds = builds.length;
+    const successRate =
+      totalBuilds > 0 ? Math.round((successCount / totalBuilds) * 100) : 0;
+
+    const avgDurationMs =
+      durations.length > 0
+        ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
+        : 0;
+
+    const minDurationMs = durations.length > 0 ? Math.min(...durations) : 0;
+    const maxDurationMs = durations.length > 0 ? Math.max(...durations) : 0;
+
+    return {
+      result: {
+        totalBuilds,
+        successCount,
+        failureCount,
+        unstableCount,
+        abortedCount,
+        successRate,
+        avgDurationMs,
+        minDurationMs,
+        maxDurationMs,
+        lastSuccessBuildNumber,
+        lastFailureBuildNumber,
+      },
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<BuildHistoryResult>[]
+  ): BuildHistoryAggregatedResult {
+    const successRates = runs
+      .map((r) => r.metadata?.successRate)
+      .filter((v): v is number => typeof v === "number");
+
+    const durations = runs
+      .map((r) => r.metadata?.avgDurationMs)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgSuccessRate:
+        successRates.length > 0
+          ? Math.round(
+              successRates.reduce((a, b) => a + b, 0) / successRates.length
+            )
+          : 0,
+      avgBuildDuration:
+        durations.length > 0
+          ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
+          : 0,
+    };
+  }
+}

package/src/collectors/index.ts

@@ -0,0 +1,5 @@
+export { ServerInfoCollector } from "./server-info";
+export { JobStatusCollector } from "./job-status";
+export { BuildHistoryCollector } from "./build-history";
+export { QueueInfoCollector } from "./queue-info";
+export { NodeHealthCollector } from "./node-health";

package/src/collectors/job-status.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "bun:test";
+import { JobStatusCollector } from "./job-status";
+import type {
+  JenkinsTransportClient,
+  JenkinsResponse,
+} from "../transport-client";
+
+describe("JobStatusCollector", () => {
+  const collector = new JobStatusCollector();
+
+  const createMockClient = (
+    response: JenkinsResponse
+  ): JenkinsTransportClient => ({
+    exec: async () => response,
+  });
+
+  it("should collect job status successfully", async () => {
+    const mockClient = createMockClient({
+      statusCode: 200,
+      data: {
+        name: "my-job",
+        buildable: true,
+        color: "blue",
+        inQueue: false,
+        lastBuild: {
+          number: 42,
+          result: "SUCCESS",
+          duration: 60000,
+          timestamp: Date.now() - 3600000, // 1 hour ago
+        },
+      },
+    });
+
+    const result = await collector.execute({
+      config: { jobName: "my-job", checkLastBuild: true },
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result.jobName).toBe("my-job");
+    expect(result.result.buildable).toBe(true);
+    expect(result.result.color).toBe("blue");
+    expect(result.result.lastBuildNumber).toBe(42);
+    expect(result.result.lastBuildResult).toBe("SUCCESS");
+    expect(result.result.lastBuildDurationMs).toBe(60000);
+    expect(result.result.timeSinceLastBuildMs).toBeGreaterThan(0);
+  });
+
+  it("should report error for failed build", async () => {
+    const mockClient = createMockClient({
+      statusCode: 200,
+      data: {
+        name: "failing-job",
+        buildable: true,
+        color: "red",
+        inQueue: false,
+        lastBuild: {
+          number: 10,
+          result: "FAILURE",
+          duration: 30000,
+          timestamp: Date.now() - 1800000,
+        },
+      },
+    });
+
+    const result = await collector.execute({
+      config: { jobName: "failing-job", checkLastBuild: true },
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.error).toBe("Last build: FAILURE");
+    expect(result.result.lastBuildResult).toBe("FAILURE");
+  });
+
+  it("should handle folder paths correctly", async () => {
+    let capturedPath = "";
+    const mockClient: JenkinsTransportClient = {
+      exec: async (req) => {
+        capturedPath = req.path;
+        return {
+          statusCode: 200,
+          data: { name: "nested-job", buildable: true, color: "blue" },
+        };
+      },
+    };
+
+    await collector.execute({
+      config: { jobName: "folder/subfolder/nested-job", checkLastBuild: false },
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(capturedPath).toBe(
+      "/job/folder/job/subfolder/job/nested-job/api/json"
+    );
+  });
+
+  it("should aggregate success rate correctly", () => {
+    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          jobName: "my-job",
+          buildable: true,
+          inQueue: false,
+          color: "blue",
+          lastBuildResult: "SUCCESS",
+          lastBuildDurationMs: 60000,
+        },
+      },
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          jobName: "my-job",
+          buildable: true,
+          inQueue: false,
+          color: "blue",
+          lastBuildResult: "SUCCESS",
+          lastBuildDurationMs: 80000,
+        },
+      },
+      {
+        status: "unhealthy" as const,
+        latencyMs: 100,
+        metadata: {
+          jobName: "my-job",
+          buildable: true,
+          inQueue: false,
+          color: "red",
+          lastBuildResult: "FAILURE",
+          lastBuildDurationMs: 40000,
+        },
+      },
+    ];
+
+    const aggregated = collector.aggregateResult(runs);
+
+    expect(aggregated.successRate).toBe(67); // 2/3
+    expect(aggregated.avgBuildDurationMs).toBe(60000); // (60000+80000+40000)/3
+    expect(aggregated.buildableRate).toBe(100);
+  });
+});