@cliangdev/flux-plugin 0.3.1 → 0.4.0

package/src/server/adapters/github/__tests__/foundation.test.ts

@@ -0,0 +1,537 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+
+const TEST_DIR = `${realpathSync(tmpdir())}/flux-github-test-${Date.now()}`;
+const FLUX_DIR = `${TEST_DIR}/.flux`;
+const PROJECT_JSON_PATH = `${FLUX_DIR}/project.json`;
+
+let mockRequestCount = 0;
+let lastOctokitToken = "";
+let mockGraphqlFn: (
+  query: string,
+  variables?: Record<string, unknown>,
+) => Promise<unknown>;
+
+mock.module("@octokit/rest", () => ({
+  Octokit: class MockOctokit {
+    constructor(opts: { auth?: string }) {
+      lastOctokitToken = opts.auth ?? "";
+    }
+  },
+}));
+
+mock.module("@octokit/graphql", () => {
+  return {
+    graphql: {
+      defaults: (_opts: { headers?: Record<string, string> }) => {
+        return async (query: string, variables?: Record<string, unknown>) => {
+          mockRequestCount++;
+          if (mockGraphqlFn) {
+            return mockGraphqlFn(query, variables);
+          }
+          return {};
+        };
+      },
+    },
+  };
+});
+
+describe("GitHub Adapter Foundation", () => {
+  const originalEnv = process.env.FLUX_PROJECT_ROOT;
+
+  beforeEach(async () => {
+    mockRequestCount = 0;
+    lastOctokitToken = "";
+    mockGraphqlFn = async () => ({});
+
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+
+    mkdirSync(FLUX_DIR, { recursive: true });
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    const { config } = await import("../../../config.js");
+    config.clearCache();
+
+    const { clearAdapterCache } = await import("../../factory.js");
+    clearAdapterCache();
+  });
+
+  afterEach(async () => {
+    if (originalEnv !== undefined) {
+      process.env.FLUX_PROJECT_ROOT = originalEnv;
+    } else {
+      delete process.env.FLUX_PROJECT_ROOT;
+    }
+
+    const { config } = await import("../../../config.js");
+    config.clearCache();
+
+    const { clearAdapterCache } = await import("../../factory.js");
+    clearAdapterCache();
+
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // Label Constants
+  // ---------------------------------------------------------------------------
+
+  describe("Label Constants", () => {
+    test("entity type labels are defined", async () => {
+      const { GITHUB_LABELS } = await import("../types.js");
+
+      expect(GITHUB_LABELS.ENTITY_PRD).toBe("flux:prd");
+      expect(GITHUB_LABELS.ENTITY_EPIC).toBe("flux:epic");
+      expect(GITHUB_LABELS.ENTITY_TASK).toBe("flux:task");
+    });
+
+    test("status labels are defined", async () => {
+      const { GITHUB_LABELS } = await import("../types.js");
+
+      expect(GITHUB_LABELS.STATUS_DRAFT).toBe("status:draft");
+      expect(GITHUB_LABELS.STATUS_PENDING_REVIEW).toBe("status:pending-review");
+      expect(GITHUB_LABELS.STATUS_REVIEWED).toBe("status:reviewed");
+      expect(GITHUB_LABELS.STATUS_APPROVED).toBe("status:approved");
+      expect(GITHUB_LABELS.STATUS_BREAKDOWN_READY).toBe(
+        "status:breakdown-ready",
+      );
+      expect(GITHUB_LABELS.STATUS_COMPLETED).toBe("status:completed");
+      expect(GITHUB_LABELS.STATUS_IN_PROGRESS).toBe("status:in-progress");
+    });
+
+    test("priority labels are defined", async () => {
+      const { GITHUB_LABELS } = await import("../types.js");
+
+      expect(GITHUB_LABELS.PRIORITY_LOW).toBe("priority:low");
+      expect(GITHUB_LABELS.PRIORITY_MEDIUM).toBe("priority:medium");
+      expect(GITHUB_LABELS.PRIORITY_HIGH).toBe("priority:high");
+    });
+
+    test("tag label prefix is defined", async () => {
+      const { GITHUB_LABELS } = await import("../types.js");
+
+      expect(GITHUB_LABELS.TAG_PREFIX).toBe("tag:");
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // GitHubClient
+  // ---------------------------------------------------------------------------
+
+  describe("GitHubClient", () => {
+    const validConfig = {
+      token: "ghp_test_token",
+      owner: "test-owner",
+      repo: "test-repo",
+      projectId: "PVT_kwDOABCD123",
+      refPrefix: "FLUX",
+    };
+
+    test("initializes with token and exposes rest client", async () => {
+      const { GitHubClient } = await import("../client.js");
+      const client = new GitHubClient(validConfig);
+
+      expect(client).toBeDefined();
+      expect(client.rest).toBeDefined();
+    });
+
+    test("passes token to Octokit", async () => {
+      const { GitHubClient } = await import("../client.js");
+      new GitHubClient(validConfig);
+
+      expect(lastOctokitToken).toBe("ghp_test_token");
+    });
+
+    test("graphql helper calls the graphql function", async () => {
+      const { GitHubClient } = await import("../client.js");
+      const client = new GitHubClient(validConfig);
+
+      mockGraphqlFn = async () => ({ viewer: { login: "testuser" } });
+
+      const result = await client.graphql<{ viewer: { login: string } }>(
+        "{ viewer { login } }",
+      );
+
+      expect(result).toEqual({ viewer: { login: "testuser" } });
+      expect(mockRequestCount).toBe(1);
+    });
+
+    test("graphql helper passes variables", async () => {
+      const { GitHubClient } = await import("../client.js");
+      const client = new GitHubClient(validConfig);
+
+      let capturedVariables: Record<string, unknown> | undefined;
+      mockGraphqlFn = async (_query, variables) => {
+        capturedVariables = variables;
+        return {};
+      };
+
+      await client.graphql("query($id: ID!) { node(id: $id) { id } }", {
+        id: "PVT_kwDO123",
+      });
+
+      expect(capturedVariables).toEqual({ id: "PVT_kwDO123" });
+    });
+
+    test("surfaces 401 error with descriptive auth message", async () => {
+      const { GitHubClient } = await import("../client.js");
+      const client = new GitHubClient(validConfig);
+
+      mockGraphqlFn = async () => {
+        const err: any = new Error("Bad credentials");
+        err.status = 401;
+        throw err;
+      };
+
+      await expect(client.graphql("{ viewer { login } }")).rejects.toThrow(
+        "GitHub API auth error",
+      );
+    });
+
+    test("surfaces 403 error with descriptive auth message", async () => {
+      const { GitHubClient } = await import("../client.js");
+      const client = new GitHubClient(validConfig);
+
+      mockGraphqlFn = async () => {
+        const err: any = new Error("Forbidden");
+        err.status = 403;
+        throw err;
+      };
+
+      await expect(client.graphql("{ viewer { login } }")).rejects.toThrow(
+        "GitHub API auth error",
+      );
+    });
+
+    test("auth error message mentions token scope", async () => {
+      const { GitHubClient } = await import("../client.js");
+      const client = new GitHubClient(validConfig);
+
+      mockGraphqlFn = async () => {
+        const err: any = new Error("Bad credentials");
+        err.status = 401;
+        throw err;
+      };
+
+      await expect(client.graphql("{ viewer { login } }")).rejects.toThrow(
+        /repo.*scope|scope.*repo/i,
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // githubConfigExists
+  // ---------------------------------------------------------------------------
+
+  describe("githubConfigExists", () => {
+    test("returns false when project.json does not exist", async () => {
+      const { githubConfigExists } = await import("../config.js");
+      expect(githubConfigExists()).toBe(false);
+    });
+
+    test("returns false when adapter type is local", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({ adapter: { type: "local" } }),
+      );
+
+      const { githubConfigExists } = await import("../config.js");
+      expect(githubConfigExists()).toBe(false);
+    });
+
+    test("returns false when adapter type is linear", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({ adapter: { type: "linear" } }),
+      );
+
+      const { githubConfigExists } = await import("../config.js");
+      expect(githubConfigExists()).toBe(false);
+    });
+
+    test("returns true when adapter type is github", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              token: "ghp_test",
+              owner: "test-owner",
+              repo: "test-repo",
+              projectId: "PVT_kwDO123",
+              refPrefix: "FLUX",
+            },
+          },
+        }),
+      );
+
+      const { githubConfigExists } = await import("../config.js");
+      expect(githubConfigExists()).toBe(true);
+    });
+
+    test("returns false when project.json has no adapter field", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({ name: "test-project" }),
+      );
+
+      const { githubConfigExists } = await import("../config.js");
+      expect(githubConfigExists()).toBe(false);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // loadGithubConfig
+  // ---------------------------------------------------------------------------
+
+  describe("loadGithubConfig", () => {
+    test("throws when project.json is missing", async () => {
+      const { loadGithubConfig } = await import("../config.js");
+      expect(() => loadGithubConfig()).toThrow();
+    });
+
+    test("returns config when project.json has valid github adapter config", async () => {
+      const githubConfig = {
+        token: "ghp_test_token",
+        owner: "acme",
+        repo: "my-repo",
+        projectId: "PVT_kwDOABCD123",
+        refPrefix: "FLUX",
+      };
+
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: githubConfig,
+          },
+        }),
+      );
+
+      const { loadGithubConfig } = await import("../config.js");
+      const loaded = loadGithubConfig();
+
+      expect(loaded.token).toBe("ghp_test_token");
+      expect(loaded.owner).toBe("acme");
+      expect(loaded.repo).toBe("my-repo");
+      expect(loaded.projectId).toBe("PVT_kwDOABCD123");
+      expect(loaded.refPrefix).toBe("FLUX");
+    });
+
+    test("throws when token is missing", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              owner: "acme",
+              repo: "my-repo",
+              projectId: "PVT_kwDO123",
+              refPrefix: "FLUX",
+            },
+          },
+        }),
+      );
+
+      const { loadGithubConfig } = await import("../config.js");
+      expect(() => loadGithubConfig()).toThrow();
+    });
+
+    test("throws when owner is missing", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              token: "ghp_test",
+              repo: "my-repo",
+              projectId: "PVT_kwDO123",
+              refPrefix: "FLUX",
+            },
+          },
+        }),
+      );
+
+      const { loadGithubConfig } = await import("../config.js");
+      expect(() => loadGithubConfig()).toThrow();
+    });
+
+    test("throws when repo is missing", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              token: "ghp_test",
+              owner: "acme",
+              projectId: "PVT_kwDO123",
+              refPrefix: "FLUX",
+            },
+          },
+        }),
+      );
+
+      const { loadGithubConfig } = await import("../config.js");
+      expect(() => loadGithubConfig()).toThrow();
+    });
+
+    test("throws when projectId is missing", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              token: "ghp_test",
+              owner: "acme",
+              repo: "my-repo",
+              refPrefix: "FLUX",
+            },
+          },
+        }),
+      );
+
+      const { loadGithubConfig } = await import("../config.js");
+      expect(() => loadGithubConfig()).toThrow();
+    });
+
+    test("throws when refPrefix is missing", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              token: "ghp_test",
+              owner: "acme",
+              repo: "my-repo",
+              projectId: "PVT_kwDO123",
+            },
+          },
+        }),
+      );
+
+      const { loadGithubConfig } = await import("../config.js");
+      expect(() => loadGithubConfig()).toThrow();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Factory
+  // ---------------------------------------------------------------------------
+
+  describe("Factory - GitHub adapter", () => {
+    test("createAdapter returns GitHubAdapter when type is 'github'", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              token: "ghp_test_token",
+              owner: "acme",
+              repo: "my-repo",
+              projectId: "PVT_kwDOABCD123",
+              refPrefix: "FLUX",
+            },
+          },
+        }),
+      );
+
+      const { createAdapter } = await import("../../factory.js");
+      const { GitHubAdapter } = await import("../adapter.js");
+
+      const adapter = createAdapter({
+        type: "github",
+        config: {
+          token: "ghp_test_token",
+          owner: "acme",
+          repo: "my-repo",
+          projectId: "PVT_kwDOABCD123",
+          refPrefix: "FLUX",
+        } as Record<string, unknown>,
+      });
+
+      expect(adapter).toBeInstanceOf(GitHubAdapter);
+    });
+
+    test("getAdapter returns GitHubAdapter when project.json has adapter.type='github'", async () => {
+      writeFileSync(
+        PROJECT_JSON_PATH,
+        JSON.stringify({
+          adapter: {
+            type: "github",
+            config: {
+              token: "ghp_test_token",
+              owner: "acme",
+              repo: "my-repo",
+              projectId: "PVT_kwDOABCD123",
+              refPrefix: "FLUX",
+            },
+          },
+        }),
+      );
+
+      const { getAdapter } = await import("../../factory.js");
+      const { GitHubAdapter } = await import("../adapter.js");
+
+      const adapter = getAdapter(true);
+
+      expect(adapter).toBeInstanceOf(GitHubAdapter);
+    });
+
+    test("GitHubAdapter implements BackendAdapter interface", async () => {
+      const { GitHubAdapter } = await import("../adapter.js");
+
+      const adapter = new GitHubAdapter({
+        token: "ghp_test",
+        owner: "acme",
+        repo: "my-repo",
+        projectId: "PVT_kwDO123",
+        refPrefix: "FLUX",
+      });
+
+      expect(typeof adapter.createPrd).toBe("function");
+      expect(typeof adapter.updatePrd).toBe("function");
+      expect(typeof adapter.getPrd).toBe("function");
+      expect(typeof adapter.listPrds).toBe("function");
+      expect(typeof adapter.deletePrd).toBe("function");
+      expect(typeof adapter.createEpic).toBe("function");
+      expect(typeof adapter.updateEpic).toBe("function");
+      expect(typeof adapter.getEpic).toBe("function");
+      expect(typeof adapter.listEpics).toBe("function");
+      expect(typeof adapter.deleteEpic).toBe("function");
+      expect(typeof adapter.createTask).toBe("function");
+      expect(typeof adapter.updateTask).toBe("function");
+      expect(typeof adapter.getTask).toBe("function");
+      expect(typeof adapter.listTasks).toBe("function");
+      expect(typeof adapter.deleteTask).toBe("function");
+      expect(typeof adapter.addCriterion).toBe("function");
+      expect(typeof adapter.markCriterionMet).toBe("function");
+      expect(typeof adapter.getCriteria).toBe("function");
+      expect(typeof adapter.addDependency).toBe("function");
+      expect(typeof adapter.removeDependency).toBe("function");
+      expect(typeof adapter.getDependencies).toBe("function");
+      expect(typeof adapter.saveDocument).toBe("function");
+      expect(typeof adapter.getDocuments).toBe("function");
+      expect(typeof adapter.deleteDocument).toBe("function");
+      expect(typeof adapter.getStats).toBe("function");
+    });
+  });
+});