@knpkv/jira-cli 0.1.1 → 1.0.0

package/test/VersionService.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it } from "@effect/vitest"
+import { JiraApiClient } from "@knpkv/jira-api-client"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { stripEmails } from "../src/commands/version.js"
+import type { Version } from "../src/VersionService.js"
+import {
+  extractContributorIds,
+  layer as VersionServiceLayer,
+  personFromObject,
+  renderCustomFieldValue,
+  toRelatedWork,
+  VersionService
+} from "../src/VersionService.js"
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+describe("renderCustomFieldValue", () => {
+  it("returns null for null/undefined/empty string", () => {
+    expect(renderCustomFieldValue(null)).toBeNull()
+    expect(renderCustomFieldValue(undefined)).toBeNull()
+    expect(renderCustomFieldValue("")).toBeNull()
+  })
+
+  it("returns plain strings and coerces numbers/booleans", () => {
+    expect(renderCustomFieldValue("hello")).toBe("hello")
+    expect(renderCustomFieldValue(42)).toBe("42")
+    expect(renderCustomFieldValue(true)).toBe("true")
+  })
+
+  it("renders cascading select as 'Parent > Child'", () => {
+    expect(renderCustomFieldValue({ value: "High", child: { value: "Confidential" } })).toBe(
+      "High > Confidential"
+    )
+  })
+
+  it("renders a single select / option as its value", () => {
+    expect(renderCustomFieldValue({ value: "High" })).toBe("High")
+  })
+
+  it("renders a user object as its display name", () => {
+    expect(renderCustomFieldValue({ displayName: "Jane Doe" })).toBe("Jane Doe")
+  })
+
+  it("falls back to name when no value/displayName", () => {
+    expect(renderCustomFieldValue({ name: "Backend" })).toBe("Backend")
+  })
+
+  it("joins arrays with ', ' and drops empties", () => {
+    expect(renderCustomFieldValue([{ value: "A" }, { value: "B" }])).toBe("A, B")
+    expect(renderCustomFieldValue([])).toBeNull()
+    expect(renderCustomFieldValue([null, ""])).toBeNull()
+  })
+
+  it("returns null for an unknown object shape", () => {
+    expect(renderCustomFieldValue({ foo: "bar" })).toBeNull()
+  })
+})
+
+describe("personFromObject", () => {
+  it("builds a Person from an object with accountId", () => {
+    expect(personFromObject({ accountId: "abc", displayName: "Jane", emailAddress: "jane@example.com" })).toEqual({
+      accountId: "abc",
+      displayName: "Jane",
+      emailAddress: "jane@example.com"
+    })
+  })
+
+  it("falls back displayName to accountId and email to null", () => {
+    expect(personFromObject({ accountId: "abc" })).toEqual({
+      accountId: "abc",
+      displayName: "abc",
+      emailAddress: null
+    })
+  })
+
+  it("uses fallbackId when the object has no accountId", () => {
+    expect(personFromObject({ displayName: "Jane" }, "fid")).toEqual({
+      accountId: "fid",
+      displayName: "Jane",
+      emailAddress: null
+    })
+  })
+
+  it("treats a bare string as an accountId", () => {
+    expect(personFromObject("abc")).toEqual({ accountId: "abc", displayName: "abc", emailAddress: null })
+  })
+
+  it("returns null with neither accountId nor fallback", () => {
+    expect(personFromObject({ displayName: "Jane" })).toBeNull()
+    expect(personFromObject(null)).toBeNull()
+    expect(personFromObject("")).toBeNull()
+  })
+})
+
+describe("extractContributorIds", () => {
+  it("returns [] when contributors is missing or not an array", () => {
+    expect(extractContributorIds({})).toEqual([])
+    expect(extractContributorIds({ contributors: "nope" })).toEqual([])
+  })
+
+  it("extracts ids from strings and objects, skipping empties", () => {
+    expect(
+      extractContributorIds({
+        contributors: ["a", { accountId: "b" }, { accountId: "" }, {}, ""]
+      })
+    ).toEqual(["a", "b"])
+  })
+})
+
+describe("toRelatedWork", () => {
+  it("normalises a related-work entry", () => {
+    expect(
+      toRelatedWork({
+        relatedWorkId: "rw-1",
+        title: "Release notes",
+        category: "Communication",
+        url: "https://example.com"
+      })
+    ).toEqual({
+      relatedWorkId: "rw-1",
+      title: "Release notes",
+      category: "Communication",
+      url: "https://example.com"
+    })
+  })
+
+  it("defaults category to empty string and missing fields to null", () => {
+    expect(toRelatedWork({})).toEqual({
+      relatedWorkId: null,
+      title: null,
+      category: "",
+      url: null
+    })
+  })
+})
+
+describe("stripEmails", () => {
+  const versionWithEmails: Version = {
+    id: "10",
+    name: "1.0.0",
+    description: null,
+    released: true,
+    archived: false,
+    startDate: null,
+    releaseDate: "2026-01-01",
+    driver: { accountId: "d", displayName: "Dana", emailAddress: "dana@example.com" },
+    contributors: [
+      { accountId: "c1", displayName: "Cara", emailAddress: "cara@example.com" },
+      { accountId: "c2", displayName: "Cliff", emailAddress: "cliff@example.com" }
+    ],
+    approvers: [
+      {
+        person: { accountId: "a1", displayName: "Amy", emailAddress: "amy@example.com" },
+        status: "APPROVED",
+        declineReason: null,
+        description: null
+      }
+    ],
+    tickets: [
+      {
+        key: "PROJ-1",
+        summary: "Do thing",
+        assignee: { accountId: "t1", displayName: "Tom", emailAddress: "tom@example.com" },
+        labels: [],
+        customFields: {}
+      },
+      { key: "PROJ-2", summary: null, assignee: null, labels: [], customFields: {} }
+    ],
+    url: "https://x/version/10"
+  }
+
+  it("nulls every Person.emailAddress across driver, contributors, approvers and assignees", () => {
+    const stripped = stripEmails(versionWithEmails)
+    expect(stripped.driver?.emailAddress).toBeNull()
+    expect(stripped.contributors.map((c) => c.emailAddress)).toEqual([null, null])
+    expect(stripped.approvers.map((a) => a.person.emailAddress)).toEqual([null])
+    expect(stripped.tickets.map((t) => t.assignee?.emailAddress ?? null)).toEqual([null, null])
+  })
+
+  it("preserves non-email fields and overall shape", () => {
+    const stripped = stripEmails(versionWithEmails)
+    expect(stripped.driver?.displayName).toBe("Dana")
+    expect(stripped.contributors.map((c) => c.accountId)).toEqual(["c1", "c2"])
+    expect(stripped.approvers[0].status).toBe("APPROVED")
+    expect(stripped.tickets.map((t) => t.key)).toEqual(["PROJ-1", "PROJ-2"])
+  })
+
+  it("leaves emails intact when callers keep the original (opt-in path)", () => {
+    // The command emits the unmodified version when --emails is set; assert the
+    // original is untouched (stripEmails returns a copy, never mutating input).
+    expect(versionWithEmails.driver?.emailAddress).toBe("dana@example.com")
+    expect(versionWithEmails.tickets[0].assignee?.emailAddress).toBe("tom@example.com")
+  })
+
+  it("handles a null driver and null assignees without throwing", () => {
+    const stripped = stripEmails({ ...versionWithEmails, driver: null })
+    expect(stripped.driver).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// released / unreleased + cap filtering (via a stubbed client)
+// ---------------------------------------------------------------------------
+
+const versionsFixture = [
+  { id: "1", name: "1.0.0", released: true, self: "https://x/version/1" },
+  { id: "2", name: "2.0.0", released: false, self: "https://x/version/2" },
+  { id: "3", name: "3.0.0", released: true, self: "https://x/version/3" },
+  { id: "4", name: "4.0.0", released: false, self: "https://x/version/4" }
+]
+
+/**
+ * Build a JiraApiClient mock whose `v3.client.GET` routes by path: the version
+ * list endpoint returns the fixture; the JQL search endpoint returns no issues
+ * (so the contributor scan resolves to empty without further calls).
+ */
+const makeJiraLayer = () =>
+  Layer.succeed(JiraApiClient, {
+    v3: {
+      client: {
+        GET: (path: string) =>
+          path === "/rest/api/3/project/{projectIdOrKey}/version"
+            ? Promise.resolve({
+              data: { values: versionsFixture, isLast: true },
+              response: { ok: true, status: 200 }
+            })
+            : Promise.resolve({
+              data: { issues: [], isLast: true },
+              response: { ok: true, status: 200 }
+            })
+      }
+    }
+  } as never)
+
+describe("listProjectVersions filtering", () => {
+  it.effect("returns all versions when neither flag is set", () =>
+    Effect.gen(function*() {
+      const service = yield* VersionService
+      const list = yield* service.listProjectVersions("PROJ")
+      expect(list.map((v) => v.id)).toEqual(["1", "2", "3", "4"])
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(makeJiraLayer())))
+
+  it.effect("keeps only released versions when released=true", () =>
+    Effect.gen(function*() {
+      const service = yield* VersionService
+      const list = yield* service.listProjectVersions("PROJ", { released: true })
+      expect(list.map((v) => v.id)).toEqual(["1", "3"])
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(makeJiraLayer())))
+
+  it.effect("keeps only unreleased versions when unreleased=true", () =>
+    Effect.gen(function*() {
+      const service = yield* VersionService
+      const list = yield* service.listProjectVersions("PROJ", { unreleased: true })
+      expect(list.map((v) => v.id)).toEqual(["2", "4"])
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(makeJiraLayer())))
+
+  it.effect("caps the result count at maxResults", () =>
+    Effect.gen(function*() {
+      const service = yield* VersionService
+      const list = yield* service.listProjectVersions("PROJ", { maxResults: 2 })
+      expect(list.map((v) => v.id)).toEqual(["1", "2"])
+    }).pipe(Effect.provide(VersionServiceLayer), Effect.provide(makeJiraLayer())))
+})

package/test/commandTree.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Ref from "effect/Ref"
+import * as Terminal from "effect/Terminal"
+import { Command } from "effect/unstable/cli"
+import { issueCommand } from "../src/commands/issue.js"
+import { versionCommand } from "../src/commands/version.js"
+import { type Issue, IssueService } from "../src/IssueService.js"
+import { MarkdownWriter } from "../src/MarkdownWriter.js"
+import { type RelatedWork, type Version, VersionService } from "../src/VersionService.js"
+
+interface CommandCalls {
+  readonly issueGet: number
+  readonly issueSearch: number
+  readonly versionList: number
+  readonly versionGet: number
+  readonly versionUpdate: number
+  readonly relatedWorkList: number
+  readonly relatedWorkAdd: number
+  readonly writeMulti: number
+}
+
+const emptyCalls: CommandCalls = {
+  issueGet: 0,
+  issueSearch: 0,
+  relatedWorkAdd: 0,
+  relatedWorkList: 0,
+  versionGet: 0,
+  versionList: 0,
+  versionUpdate: 0,
+  writeMulti: 0
+}
+
+const sampleIssue: Issue = {
+  assignee: null,
+  attachments: [],
+  comments: [],
+  components: [],
+  created: new Date("2026-01-01T00:00:00.000Z"),
+  description: "",
+  fixVersions: [],
+  id: "10000",
+  key: "PROJ-123",
+  labels: [],
+  priority: null,
+  reporter: null,
+  status: "Done",
+  summary: "Sample issue",
+  type: "Task",
+  updated: new Date("2026-01-01T00:00:00.000Z"),
+  url: "https://example.atlassian.net/browse/PROJ-123"
+}
+
+const sampleVersion: Version = {
+  approvers: [],
+  archived: false,
+  contributors: [],
+  description: null,
+  driver: null,
+  id: "10042",
+  name: "1.0.0",
+  releaseDate: null,
+  released: false,
+  startDate: null,
+  tickets: [],
+  url: "https://example.atlassian.net/projects/PROJ/versions/10042"
+}
+
+const sampleRelatedWork: RelatedWork = {
+  category: "Communication",
+  relatedWorkId: "20000",
+  title: "Release notes",
+  url: "https://example.atlassian.net/wiki/spaces/PROJ/pages/123"
+}
+
+const CaptureTerminalLayer = (stdout: Ref.Ref<string>) =>
+  Layer.succeed(
+    Terminal.Terminal,
+    Terminal.Terminal.of({
+      columns: Effect.succeed(100),
+      rows: Effect.succeed(24),
+      readInput: Effect.die("readInput should not be called"),
+      readLine: Effect.die("readLine should not be called"),
+      display: (text) => Ref.update(stdout, (output) => output + text)
+    })
+  )
+
+const CommandServicesLayer = (calls: Ref.Ref<CommandCalls>) =>
+  Layer.mergeAll(
+    Layer.succeed(
+      IssueService,
+      IssueService.of({
+        getByKey: () =>
+          Ref.update(calls, (state) => ({ ...state, issueGet: state.issueGet + 1 })).pipe(
+            Effect.as(sampleIssue)
+          ),
+        search: () => Effect.die("IssueService.search should not be called"),
+        searchAll: () =>
+          Ref.update(calls, (state) => ({ ...state, issueSearch: state.issueSearch + 1 })).pipe(
+            Effect.as([sampleIssue])
+          )
+      })
+    ),
+    Layer.succeed(
+      MarkdownWriter,
+      MarkdownWriter.of({
+        writeMulti: () => Ref.update(calls, (state) => ({ ...state, writeMulti: state.writeMulti + 1 })),
+        writeSingle: () => Effect.die("MarkdownWriter.writeSingle should not be called")
+      })
+    ),
+    Layer.succeed(
+      VersionService,
+      VersionService.of({
+        addRelatedWork: () =>
+          Ref.update(calls, (state) => ({ ...state, relatedWorkAdd: state.relatedWorkAdd + 1 })).pipe(
+            Effect.as(sampleRelatedWork)
+          ),
+        getVersion: () =>
+          Ref.update(calls, (state) => ({ ...state, versionGet: state.versionGet + 1 })).pipe(
+            Effect.as(sampleVersion)
+          ),
+        listProjectVersions: () =>
+          Ref.update(calls, (state) => ({ ...state, versionList: state.versionList + 1 })).pipe(
+            Effect.as([sampleVersion])
+          ),
+        listRelatedWork: () =>
+          Ref.update(calls, (state) => ({ ...state, relatedWorkList: state.relatedWorkList + 1 })).pipe(
+            Effect.as([sampleRelatedWork])
+          ),
+        updateVersion: () =>
+          Ref.update(calls, (state) => ({ ...state, versionUpdate: state.versionUpdate + 1 })).pipe(
+            Effect.as(sampleVersion)
+          )
+      })
+    )
+  )
+
+const runJiraCommand = (
+  args: ReadonlyArray<string>,
+  calls: Ref.Ref<CommandCalls>,
+  stdout: Ref.Ref<string>
+) => {
+  const command = Command.make("jira").pipe(
+    Command.withDescription("Jira CLI commands"),
+    Command.withSubcommands([issueCommand, versionCommand])
+  )
+  const cli = Command.runWith(command, { version: "0.0.0-test" })
+  return cli(args).pipe(
+    Effect.provide(Layer.merge(CommandServicesLayer(calls), CaptureTerminalLayer(stdout))),
+    Effect.exit
+  )
+}
+
+describe("Jira command tree", () => {
+  it.effect("exposes canonical issue commands and removes top-level issue aliases", () =>
+    Effect.gen(function*() {
+      const calls = yield* Ref.make(emptyCalls)
+      const getOutput = yield* Ref.make("")
+      const searchOutput = yield* Ref.make("")
+      const legacyGetOutput = yield* Ref.make("")
+      const legacySearchOutput = yield* Ref.make("")
+
+      const getExit = yield* runJiraCommand(["issue", "get", "PROJ-123"], calls, getOutput)
+      const searchExit = yield* runJiraCommand(["issue", "search", "project = PROJ"], calls, searchOutput)
+      const legacyGetExit = yield* runJiraCommand(["get", "PROJ-123"], calls, legacyGetOutput)
+      const legacySearchExit = yield* runJiraCommand(["search", "project = PROJ"], calls, legacySearchOutput)
+
+      expect(getExit._tag).toBe("Success")
+      expect(searchExit._tag).toBe("Success")
+      expect(legacyGetExit._tag).toBe("Failure")
+      expect(legacySearchExit._tag).toBe("Failure")
+
+      expect(yield* Ref.get(calls)).toMatchObject({
+        issueGet: 1,
+        issueSearch: 1,
+        writeMulti: 2
+      })
+    }))
+
+  it.effect("exposes canonical version commands and rejects legacy names", () =>
+    Effect.gen(function*() {
+      const calls = yield* Ref.make(emptyCalls)
+      const output = yield* Ref.make("")
+      const legacyViewOutput = yield* Ref.make("")
+      const legacySetOutput = yield* Ref.make("")
+      const legacyRelatedWorkOutput = yield* Ref.make("")
+
+      const listExit = yield* runJiraCommand(["version", "list", "--project", "PROJ"], calls, output)
+      const getExit = yield* runJiraCommand(["version", "get", "10042"], calls, output)
+      const updateExit = yield* runJiraCommand(
+        [
+          "version",
+          "update",
+          "10042",
+          "--description",
+          "Q3 release"
+        ],
+        calls,
+        output
+      )
+      const relatedWorkListExit = yield* runJiraCommand(
+        [
+          "version",
+          "related-work",
+          "list",
+          "10042"
+        ],
+        calls,
+        output
+      )
+      const relatedWorkAddExit = yield* runJiraCommand(
+        [
+          "version",
+          "related-work",
+          "add",
+          "10042",
+          "--title",
+          "Release notes",
+          "--url",
+          "https://example.atlassian.net/wiki/spaces/PROJ/pages/123"
+        ],
+        calls,
+        output
+      )
+      const legacyViewExit = yield* runJiraCommand(["version", "view", "10042"], calls, legacyViewOutput)
+      const legacySetExit = yield* runJiraCommand(
+        [
+          "version",
+          "set",
+          "10042",
+          "--description",
+          "Q3 release"
+        ],
+        calls,
+        legacySetOutput
+      )
+      const legacyRelatedWorkExit = yield* runJiraCommand(
+        [
+          "version",
+          "relatedwork",
+          "list",
+          "10042"
+        ],
+        calls,
+        legacyRelatedWorkOutput
+      )
+
+      expect(listExit._tag).toBe("Success")
+      expect(getExit._tag).toBe("Success")
+      expect(updateExit._tag).toBe("Success")
+      expect(relatedWorkListExit._tag).toBe("Success")
+      expect(relatedWorkAddExit._tag).toBe("Success")
+      expect(legacyViewExit._tag).toBe("Failure")
+      expect(legacySetExit._tag).toBe("Failure")
+      expect(legacyRelatedWorkExit._tag).toBe("Failure")
+
+      expect(yield* Ref.get(calls)).toMatchObject({
+        relatedWorkAdd: 1,
+        relatedWorkList: 1,
+        versionGet: 1,
+        versionList: 1,
+        versionUpdate: 1
+      })
+    }))
+})

package/test/frontmatter.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "@effect/vitest"
+import * as yaml from "js-yaml"
+import { extractFrontMatter, serializeIssue } from "../src/internal/frontmatter.js"
+import type { Issue } from "../src/IssueService.js"
+
+/**
+ * Parse the YAML front-matter block of a serialized issue using js-yaml 4
+ * directly. We avoid gray-matter's default parser here because it calls the
+ * removed `safeLoad` — the same incompatibility this module works around.
+ */
+const parseFrontMatter = (output: string): Record<string, unknown> => {
+  const match = output.match(/^---\n([\s\S]*?)\n---/)
+  return match ? (yaml.load(match[1]) as Record<string, unknown>) : {}
+}
+
+const makeIssue = (overrides: Partial<Issue> = {}): Issue => ({
+  key: "OOB-81",
+  id: "10081",
+  summary: "Test ticket",
+  status: "Done",
+  type: "Story",
+  priority: "High",
+  assignee: "Alice",
+  reporter: "Bob",
+  created: new Date("2026-01-01T00:00:00.000Z"),
+  updated: new Date("2026-02-01T00:00:00.000Z"),
+  fixVersions: ["OOB 81"],
+  labels: ["a", "b"],
+  components: ["x"],
+  description: "Hello",
+  attachments: [],
+  comments: [],
+  ...overrides
+})
+
+describe("frontmatter", () => {
+  describe("serializeIssue", () => {
+    // Regression: gray-matter's default YAML engine calls js-yaml's removed
+    // `safeDump`, which throws under the workspace's js-yaml 4 override. The
+    // custom engine must serialize without throwing.
+    it("serializes without throwing under js-yaml 4", () => {
+      expect(() => serializeIssue(makeIssue())).not.toThrow()
+    })
+
+    it("produces parseable YAML front-matter round-tripping the data", () => {
+      const output = serializeIssue(makeIssue())
+      const data = parseFrontMatter(output)
+      expect(data.key).toBe("OOB-81")
+      expect(data.fixVersions).toEqual(["OOB 81"])
+      expect(data.labels).toEqual(["a", "b"])
+      expect(output).toContain("# OOB-81: Test ticket")
+    })
+
+    it("emits null for absent optional fields", () => {
+      const output = serializeIssue(makeIssue({ priority: null, assignee: null, reporter: null }))
+      const data = parseFrontMatter(output)
+      expect(data.priority).toBeNull()
+      expect(data.assignee).toBeNull()
+    })
+  })
+
+  describe("extractFrontMatter", () => {
+    it("renders dates as ISO strings", () => {
+      const fm = extractFrontMatter(makeIssue())
+      expect(fm.created).toBe("2026-01-01T00:00:00.000Z")
+      expect(fm.updated).toBe("2026-02-01T00:00:00.000Z")
+    })
+  })
+})