@knpkv/jira-cli 0.3.0 → 1.0.0

package/src/internal/sync/changes.ts

@@ -0,0 +1,118 @@
+/**
+ * Baseline comparison for Jira Markdown Sync planning.
+ *
+ * @internal
+ */
+import { fieldValuesEqual } from "./fieldValues.js"
+import type {
+  PlannedFieldChange,
+  SyncBaselineFields,
+  SyncFieldPath,
+  SyncFieldValue,
+  SyncValidationFailure
+} from "./types.js"
+
+export interface CompareIssueFieldsInput {
+  readonly issueId: string
+  readonly issueKey: string
+  readonly baseline: SyncBaselineFields
+  readonly jira: SyncBaselineFields
+  readonly document: SyncBaselineFields
+}
+
+export interface CompareIssueFieldsResult {
+  readonly changes: ReadonlyArray<PlannedFieldChange>
+  readonly validationFailures: ReadonlyArray<SyncValidationFailure>
+}
+
+export const compareIssueFields = (input: CompareIssueFieldsInput): CompareIssueFieldsResult => {
+  const changes: Array<PlannedFieldChange> = []
+  const validationFailures: Array<SyncValidationFailure> = []
+
+  compareField(input, "summary", input.baseline.summary, input.jira.summary, input.document.summary, changes)
+  compareField(
+    input,
+    "description",
+    input.baseline.description,
+    input.jira.description,
+    input.document.description,
+    changes
+  )
+  compareField(input, "labels", input.baseline.labels, input.jira.labels, input.document.labels, changes)
+
+  const customFieldNames = new Set([
+    ...Object.keys(input.baseline.customFields),
+    ...Object.keys(input.jira.customFields),
+    ...Object.keys(input.document.customFields)
+  ])
+
+  for (const name of customFieldNames) {
+    const field = `customFields.${name}` as const
+    const baseline = input.baseline.customFields[name]?.value
+    const jira = input.jira.customFields[name]?.value
+    const document = input.document.customFields[name]?.value
+
+    if (baseline === undefined || jira === undefined || document === undefined) {
+      validationFailures.push({
+        _tag: "ValidationFailure",
+        issueKey: input.issueKey,
+        field,
+        message: `Missing reconciled custom field "${name}"`
+      })
+      continue
+    }
+
+    compareField(input, field, baseline, jira, document, changes)
+  }
+
+  return { changes, validationFailures }
+}
+
+const compareField = (
+  input: Pick<CompareIssueFieldsInput, "issueId" | "issueKey">,
+  field: SyncFieldPath,
+  baselineValue: SyncFieldValue,
+  jiraValue: SyncFieldValue,
+  documentValue: SyncFieldValue,
+  changes: Array<PlannedFieldChange>
+) => {
+  const jiraChanged = !syncFieldValueEquals(jiraValue, baselineValue)
+  const documentChanged = !syncFieldValueEquals(documentValue, baselineValue)
+
+  if (!jiraChanged && !documentChanged) return
+
+  if (jiraChanged && !documentChanged) {
+    changes.push({
+      _tag: "RemoteOnly",
+      issueId: input.issueId,
+      issueKey: input.issueKey,
+      field,
+      jiraValue
+    })
+    return
+  }
+
+  if (!jiraChanged && documentChanged) {
+    changes.push({
+      _tag: "LocalOnly",
+      issueId: input.issueId,
+      issueKey: input.issueKey,
+      field,
+      documentValue
+    })
+    return
+  }
+
+  changes.push({
+    _tag: "Conflict",
+    issueId: input.issueId,
+    issueKey: input.issueKey,
+    field,
+    baselineValue,
+    jiraValue,
+    documentValue
+  })
+}
+
+export const syncFieldValueEquals = (left: SyncFieldValue, right: SyncFieldValue): boolean =>
+  fieldValuesEqual(left, right)

package/src/internal/sync/config.ts

@@ -0,0 +1,76 @@
+/**
+ * Workspace Config parsing and serialization.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as yaml from "js-yaml"
+import { SyncValidationError, SyncWorkspaceError } from "../../JiraCliError.js"
+import { WorkspaceConfigSchema } from "./schemas.js"
+import type { WorkspaceConfig } from "./types.js"
+
+export const parseWorkspaceConfig = (
+  path: string,
+  content: string
+): Effect.Effect<WorkspaceConfig, SyncWorkspaceError | SyncValidationError> =>
+  Effect.gen(function*() {
+    const raw = yield* Effect.try({
+      try: () => yaml.load(content) ?? {},
+      catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse workspace config YAML", path, cause })
+    })
+    const config = yield* Schema.decodeUnknownEffect(WorkspaceConfigSchema)(raw).pipe(
+      Effect.map((config) => config as WorkspaceConfig),
+      Effect.mapError((cause) =>
+        new SyncValidationError({ message: "Invalid Jira Markdown Sync workspace config", path, cause })
+      )
+    )
+    yield* validateCustomFieldDeclarations(path, config)
+    return config
+  })
+
+export const serializeWorkspaceConfig = (config: WorkspaceConfig): string => yaml.dump(config, { lineWidth: 100 })
+
+export const makeDefaultWorkspaceConfig = (siteUrl: string): WorkspaceConfig => ({
+  version: 1,
+  siteUrl,
+  documentsDir: "issues",
+  customFields: []
+})
+
+const validateCustomFieldDeclarations = (
+  path: string,
+  config: WorkspaceConfig
+): Effect.Effect<void, SyncValidationError> =>
+  Effect.gen(function*() {
+    const displayNames = new Map<string, number>()
+    const fieldIds = new Set<string>()
+
+    for (const field of config.customFields) {
+      displayNames.set(field.displayName, (displayNames.get(field.displayName) ?? 0) + 1)
+      if (field.fieldId) {
+        if (fieldIds.has(field.fieldId)) {
+          return yield* Effect.fail(
+            new SyncValidationError({
+              message: `Duplicate Requested Custom Field id "${field.fieldId}"`,
+              field: field.displayName,
+              path
+            })
+          )
+        }
+        fieldIds.add(field.fieldId)
+      }
+    }
+
+    for (const field of config.customFields) {
+      if ((displayNames.get(field.displayName) ?? 0) > 1 && !field.fieldId) {
+        return yield* Effect.fail(
+          new SyncValidationError({
+            message: `Duplicate Requested Custom Field "${field.displayName}" must specify fieldId`,
+            field: field.displayName,
+            path
+          })
+        )
+      }
+    }
+  })

package/src/internal/sync/document.ts

@@ -0,0 +1,201 @@
+/**
+ * Parser and serializer for strict Jira Markdown Sync Issue Documents.
+ *
+ * @internal
+ */
+import matter from "gray-matter"
+import * as yaml from "js-yaml"
+import { SyncValidationError } from "../../JiraCliError.js"
+import type {
+  AcceptedComment,
+  AttachmentReference,
+  CommentDraft,
+  IssueDocument,
+  IssueDocumentFrontMatter
+} from "./types.js"
+
+const yamlEngine = {
+  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  stringify: (data: object): string => yaml.dump(data)
+}
+
+export const DESCRIPTION_SECTION = "Description"
+export const NEW_COMMENTS_SECTION = "New Comments"
+export const COMMENTS_SECTION = "Comments"
+export const ATTACHMENTS_SECTION = "Attachments"
+export const LOCAL_NOTES_SECTION = "Local Notes"
+
+const BUILT_IN_SECTIONS = new Set([
+  DESCRIPTION_SECTION,
+  NEW_COMMENTS_SECTION,
+  COMMENTS_SECTION,
+  ATTACHMENTS_SECTION,
+  LOCAL_NOTES_SECTION
+])
+
+export const serializeIssueDocument = (document: IssueDocument): string => {
+  const body = [
+    `# ${document.frontMatter.issueKey}: ${document.frontMatter.summary}`,
+    "",
+    section(DESCRIPTION_SECTION, document.description),
+    ...Object.entries(document.multilineCustomFields).map(([name, content]) => section(name, content)),
+    section(NEW_COMMENTS_SECTION, serializeCommentDrafts(document.commentDrafts)),
+    section(COMMENTS_SECTION, serializeAcceptedComments(document.acceptedComments)),
+    section(ATTACHMENTS_SECTION, serializeAttachments(document.attachments)),
+    section(LOCAL_NOTES_SECTION, document.localNotes)
+  ].filter((part) => part.length > 0).join("\n")
+
+  return matter.stringify(body, document.frontMatter, { engines: { yaml: yamlEngine } })
+}
+
+export const parseIssueDocument = (path: string, content: string): IssueDocument => {
+  const parsed = matter(content, { engines: { yaml: yamlEngine } })
+  const frontMatter = parseFrontMatter(path, parsed.data)
+  const sections = parseSections(path, parsed.content)
+
+  const description = sections.get(DESCRIPTION_SECTION) ?? fail(path, `Missing ${DESCRIPTION_SECTION} section`)
+  const localNotes = sections.get(LOCAL_NOTES_SECTION) ?? ""
+  const multilineCustomFields = Object.fromEntries(
+    [...sections.entries()].filter(([name]) => !BUILT_IN_SECTIONS.has(name))
+  )
+
+  return {
+    frontMatter,
+    description,
+    multilineCustomFields,
+    commentDrafts: parseCommentDrafts(path, sections.get(NEW_COMMENTS_SECTION) ?? ""),
+    acceptedComments: parseAcceptedComments(sections.get(COMMENTS_SECTION) ?? ""),
+    attachments: parseAttachments(sections.get(ATTACHMENTS_SECTION) ?? ""),
+    localNotes
+  }
+}
+
+const section = (name: string, content: string): string => {
+  const normalized = content.trim()
+  return normalized.length > 0 ? `## ${name}\n\n${normalized}\n` : `## ${name}\n`
+}
+
+const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDocumentFrontMatter => {
+  const requiredString = (key: string): string => {
+    const value = data[key]
+    if (typeof value !== "string") fail(path, `Missing or invalid front matter field "${key}"`)
+    return value as string
+  }
+
+  const nullableString = (key: string): string | null => {
+    const value = data[key]
+    if (value === null || value === undefined) return null
+    if (typeof value !== "string") fail(path, `Invalid front matter field "${key}"`)
+    return value as string
+  }
+
+  const userValue = (key: string) => {
+    const value = data[key]
+    if (value === null || value === undefined) return null
+    if (typeof value !== "object") fail(path, `Invalid user field "${key}"`)
+    const record = value as Record<string, unknown>
+    if (typeof record["accountId"] !== "string" || typeof record["displayName"] !== "string") {
+      fail(path, `Invalid user field "${key}"`)
+    }
+    return {
+      accountId: record["accountId"] as string,
+      displayName: record["displayName"] as string
+    }
+  }
+
+  const labels = data["labels"]
+  if (!Array.isArray(labels) || labels.some((label) => typeof label !== "string")) {
+    fail(path, `Missing or invalid front matter field "labels"`)
+  }
+
+  const customFields = data["customFields"]
+  if (customFields === null || typeof customFields !== "object" || Array.isArray(customFields)) {
+    fail(path, `Missing or invalid front matter field "customFields"`)
+  }
+
+  return {
+    issueId: requiredString("issueId"),
+    issueKey: requiredString("issueKey"),
+    summary: requiredString("summary"),
+    status: requiredString("status"),
+    issueType: requiredString("issueType"),
+    priority: nullableString("priority"),
+    assignee: userValue("assignee"),
+    reporter: userValue("reporter"),
+    labels: labels as ReadonlyArray<string>,
+    customFields: customFields as IssueDocumentFrontMatter["customFields"]
+  }
+}
+
+const parseSections = (path: string, content: string): Map<string, string> => {
+  const lines = content.split(/\r?\n/)
+  const sections = new Map<string, Array<string>>()
+  let current: string | null = null
+
+  for (const line of lines) {
+    const match = /^## (.+)$/.exec(line)
+    if (match?.[1]) {
+      current = match[1].trim()
+      if (sections.has(current)) fail(path, `Duplicate section "${current}"`)
+      sections.set(current, [])
+    } else if (current) {
+      sections.get(current)?.push(line)
+    }
+  }
+
+  return new Map([...sections.entries()].map(([name, body]) => [name, trimOuterBlankLines(body).join("\n")]))
+}
+
+const serializeCommentDrafts = (drafts: ReadonlyArray<CommentDraft>): string =>
+  drafts.map((draft) => `<!-- draftId: ${draft.draftId} -->\n${draft.body.trim()}`).join("\n\n")
+
+const parseCommentDrafts = (path: string, content: string): ReadonlyArray<CommentDraft> => {
+  if (content.trim().length === 0) return []
+  const parts = content.split(/(?=<!-- draftId: )/g).filter((part) => part.trim().length > 0)
+  return parts.map((part) => {
+    const match = /^<!-- draftId: ([^ ]+) -->\n?([\s\S]*)$/.exec(part.trim())
+    const draftId = match?.[1] ?? fail(path, "Malformed comment draft marker")
+    return { draftId, body: match?.[2]?.trim() ?? "" }
+  })
+}
+
+const serializeAcceptedComments = (comments: ReadonlyArray<AcceptedComment>): string =>
+  comments.map((comment) =>
+    `### ${comment.author} - ${comment.created}\n<!-- jiraCommentId: ${comment.id} -->\n\n${comment.body.trim()}`
+  ).join("\n\n")
+
+const parseAcceptedComments = (content: string): ReadonlyArray<AcceptedComment> => {
+  if (content.trim().length === 0) return []
+  const parts = content.split(/(?=^### )/gm).filter((part) => part.trim().length > 0)
+  return parts.flatMap((part) => {
+    const match = /^### (.+) - (.+)\n<!-- jiraCommentId: ([^ ]+) -->\n?([\s\S]*)$/.exec(part.trim())
+    if (!match?.[1] || !match[2] || !match[3]) return []
+    return [{
+      author: match[1],
+      created: match[2],
+      id: match[3],
+      body: match[4]?.trim() ?? ""
+    }]
+  })
+}
+
+const serializeAttachments = (attachments: ReadonlyArray<AttachmentReference>): string =>
+  attachments.map((attachment) => `- [${attachment.filename}](${attachment.url})`).join("\n")
+
+const parseAttachments = (content: string): ReadonlyArray<AttachmentReference> =>
+  content.split(/\r?\n/).flatMap((line) => {
+    const match = /^- \[(.+)]\((.+)\)$/.exec(line.trim())
+    return match?.[1] && match[2] ? [{ filename: match[1], url: match[2] }] : []
+  })
+
+const trimOuterBlankLines = (lines: ReadonlyArray<string>): ReadonlyArray<string> => {
+  let start = 0
+  let end = lines.length
+  while (start < end && lines[start]?.trim() === "") start++
+  while (end > start && lines[end - 1]?.trim() === "") end--
+  return lines.slice(start, end)
+}
+
+const fail = (path: string, message: string): never => {
+  throw new SyncValidationError({ message, path })
+}

package/src/internal/sync/fieldValues.ts

@@ -0,0 +1,145 @@
+/**
+ * Field value helpers for Jira Markdown Sync reconciliation.
+ *
+ * @internal
+ */
+import type { CascadingFieldValue, OptionFieldValue, SyncFieldValue, UserFieldValue } from "./types.js"
+
+export type CompleteListItem = string | number | boolean | UserFieldValue | OptionFieldValue
+
+export type CompleteListValue = ReadonlyArray<CompleteListItem>
+
+export interface CanonicalFieldValueOptions {
+  readonly ordered?: boolean | undefined
+}
+
+export const explicitClear = null
+
+export const isExplicitClear = (value: unknown): value is null => value === null
+
+export const userFieldValue = (accountId: string, displayName: string): UserFieldValue => ({
+  accountId,
+  displayName
+})
+
+export const makeUserFieldValue = userFieldValue
+
+export const optionFieldValue = (value: string, id?: string): OptionFieldValue =>
+  id === undefined ? { value } : { id, value }
+
+export const makeOptionFieldValue = optionFieldValue
+
+export const cascadingFieldValue = (
+  parent: OptionFieldValue,
+  child?: OptionFieldValue
+): CascadingFieldValue => child === undefined ? { parent } : { parent, child }
+
+export const makeCascadingFieldValue = cascadingFieldValue
+
+export const completeListValue = (
+  items: Iterable<CompleteListItem>,
+  options: CanonicalFieldValueOptions = {}
+): CompleteListValue => canonicalFieldOrder(Array.from(items), options)
+
+export const makeCompleteListValue = completeListValue
+
+export const isUserFieldValue = (value: unknown): value is UserFieldValue => {
+  if (!isRecord(value)) return false
+  return typeof value["accountId"] === "string" && typeof value["displayName"] === "string"
+}
+
+export const isOptionFieldValue = (value: unknown): value is OptionFieldValue => {
+  if (!isRecord(value) || typeof value["value"] !== "string") return false
+  const id = value["id"]
+  return id === undefined || typeof id === "string"
+}
+
+export const isCascadingFieldValue = (value: unknown): value is CascadingFieldValue => {
+  if (!isRecord(value) || !isOptionFieldValue(value["parent"])) return false
+  const child = value["child"]
+  return child === undefined || isOptionFieldValue(child)
+}
+
+export const isCompleteListValue = (value: unknown): value is CompleteListValue =>
+  Array.isArray(value) && value.every(isCompleteListItem)
+
+export const canonicalFieldOrder = <A extends CompleteListItem>(
+  items: ReadonlyArray<A>,
+  options: CanonicalFieldValueOptions = {}
+): ReadonlyArray<A> => options.ordered === true ? [...items] : [...items].sort(compareCompleteListItems)
+
+export const canonicalizeFieldValue = (
+  value: SyncFieldValue,
+  options: CanonicalFieldValueOptions = {}
+): SyncFieldValue => {
+  if (Array.isArray(value)) return canonicalFieldOrder(value, options)
+  if (isCascadingFieldValue(value)) {
+    return value.child === undefined
+      ? { parent: canonicalizeOption(value.parent) }
+      : { parent: canonicalizeOption(value.parent), child: canonicalizeOption(value.child) }
+  }
+  if (isUserFieldValue(value)) return { accountId: value.accountId, displayName: value.displayName }
+  if (isOptionFieldValue(value)) return canonicalizeOption(value)
+  return value
+}
+
+export const fieldValuesEqual = (
+  left: SyncFieldValue,
+  right: SyncFieldValue,
+  options: CanonicalFieldValueOptions = {}
+): boolean => canonicalFieldValueKey(left, options) === canonicalFieldValueKey(right, options)
+
+export const compareCompleteListItems = (left: CompleteListItem, right: CompleteListItem): number => {
+  const leftKey = completeListItemOrderKey(left)
+  const rightKey = completeListItemOrderKey(right)
+  return leftKey.localeCompare(rightKey, "en", { numeric: true })
+}
+
+const canonicalizeOption = (value: OptionFieldValue): OptionFieldValue =>
+  value.id === undefined ? { value: value.value } : { id: value.id, value: value.value }
+
+const canonicalFieldValueKey = (
+  value: SyncFieldValue,
+  options: CanonicalFieldValueOptions
+): string => {
+  if (value === null) return "clear:"
+  if (Array.isArray(value)) {
+    return `list:${canonicalFieldOrder(value, options).map(completeListItemOrderKey).join("\u0000")}`
+  }
+  if (isCascadingFieldValue(value)) {
+    return `cascading:${optionOrderKey(value.parent)}\u0000${
+      value.child === undefined ? "" : optionOrderKey(value.child)
+    }`
+  }
+  if (isUserFieldValue(value)) return userOrderKey(value)
+  if (isOptionFieldValue(value)) return optionOrderKey(value)
+  return `${typeof value}:${String(value)}`
+}
+
+const completeListItemOrderKey = (value: CompleteListItem): string => {
+  if (isUserFieldValue(value)) return userOrderKey(value)
+  if (isOptionFieldValue(value)) return optionOrderKey(value)
+  return `${typeof value}:${String(value)}`
+}
+
+const userOrderKey = (value: UserFieldValue): string =>
+  `user:${value.displayName.toLocaleLowerCase("en")}\u0000${value.accountId}`
+
+const optionOrderKey = (value: OptionFieldValue): string =>
+  `option:${value.value.toLocaleLowerCase("en")}\u0000${value.id ?? ""}`
+
+const isCompleteListItem = (value: unknown): value is CompleteListItem => {
+  switch (typeof value) {
+    case "string":
+    case "number":
+    case "boolean":
+      return true
+    case "object":
+      return isUserFieldValue(value) || isOptionFieldValue(value)
+    default:
+      return false
+  }
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  value !== null && typeof value === "object" && !Array.isArray(value)

package/src/internal/sync/manifest.ts

@@ -0,0 +1,32 @@
+/**
+ * Sync Manifest helpers.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { SyncValidationError, SyncWorkspaceError } from "../../JiraCliError.js"
+import { SyncManifestSchema } from "./schemas.js"
+import type { SyncManifest } from "./types.js"
+
+export const makeEmptyManifest = (siteUrl: string): SyncManifest => ({
+  version: 1,
+  siteUrl,
+  issues: []
+})
+
+export const parseSyncManifest = (
+  path: string,
+  content: string
+): Effect.Effect<SyncManifest, SyncWorkspaceError | SyncValidationError> =>
+  Effect.gen(function*() {
+    const raw = yield* Effect.try({
+      try: () => JSON.parse(content) as unknown,
+      catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Manifest JSON", path, cause })
+    })
+    return yield* Schema.decodeUnknownEffect(SyncManifestSchema)(raw).pipe(
+      Effect.mapError((cause) => new SyncValidationError({ message: "Invalid Sync Manifest", path, cause }))
+    )
+  })
+
+export const serializeSyncManifest = (manifest: SyncManifest): string => `${JSON.stringify(manifest, null, 2)}\n`

package/src/internal/sync/paths.ts

@@ -0,0 +1,48 @@
+/**
+ * Path helpers for Jira Markdown Sync workspace files.
+ *
+ * @internal
+ */
+import type * as Path from "effect/Path"
+import type { WorkspaceConfig } from "./types.js"
+
+export const METADATA_DIR = ".jira-md"
+export const DEFAULT_DOCUMENTS_DIR = "issues"
+export const CONFIG_FILE = "config.yaml"
+export const MANIFEST_FILE = "manifest.json"
+export const BASELINES_DIR = "baselines"
+export const HISTORY_DIR = "history"
+
+export interface SyncWorkspacePaths {
+  readonly root: string
+  readonly documentsDir: string
+  readonly metadataDir: string
+  readonly configFile: string
+  readonly manifestFile: string
+  readonly baselinesDir: string
+  readonly historyDir: string
+}
+
+export const resolveWorkspacePaths = (
+  path: Path.Path,
+  root: string,
+  config?: Pick<WorkspaceConfig, "documentsDir">
+): SyncWorkspacePaths => {
+  const documentsDir = path.resolve(root, config?.documentsDir ?? DEFAULT_DOCUMENTS_DIR)
+  const metadataDir = path.resolve(root, METADATA_DIR)
+  return {
+    root: path.resolve(root),
+    documentsDir,
+    metadataDir,
+    configFile: path.join(metadataDir, CONFIG_FILE),
+    manifestFile: path.join(metadataDir, MANIFEST_FILE),
+    baselinesDir: path.join(metadataDir, BASELINES_DIR),
+    historyDir: path.join(metadataDir, HISTORY_DIR)
+  }
+}
+
+export const baselineFilePath = (path: Path.Path, paths: SyncWorkspacePaths, issueId: string): string =>
+  path.join(paths.baselinesDir, `${issueId}.json`)
+
+export const conventionDocumentPath = (path: Path.Path, paths: SyncWorkspacePaths, issueKey: string): string =>
+  path.join(paths.documentsDir, `${issueKey}.md`)