@knpkv/jira-cli 0.1.1 → 1.0.0

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`)

package/src/internal/sync/schemas.ts

@@ -0,0 +1,103 @@
+/**
+ * Runtime schemas for Jira Markdown Sync local workspace files.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { FIELD_SHAPES } from "./types.js"
+
+const SiteUrl = Schema.String.pipe(
+  Schema.check(Schema.isPattern(/^https:\/\/[a-z0-9][a-z0-9-]*\.atlassian\.net$/))
+)
+
+const NonEmptyString = Schema.String.pipe(Schema.check(Schema.isMinLength(1)))
+
+export const FieldShapeSchema = Schema.Literals(FIELD_SHAPES)
+
+export const RequestedCustomFieldSchema = Schema.Struct({
+  displayName: NonEmptyString,
+  fieldId: Schema.optional(NonEmptyString),
+  shape: FieldShapeSchema,
+  ordered: Schema.optional(Schema.Boolean)
+})
+
+export const WorkspaceConfigSchema = Schema.Struct({
+  version: Schema.Literal(1).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(1 as const))),
+  siteUrl: SiteUrl,
+  documentsDir: NonEmptyString.pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed("issues"))),
+  customFields: Schema.Array(RequestedCustomFieldSchema).pipe(
+    Schema.withDecodingDefaultTypeKey(Effect.succeed([]))
+  )
+})
+
+export const ManifestIssueSchema = Schema.Struct({
+  issueId: NonEmptyString,
+  issueKey: NonEmptyString,
+  documentPath: NonEmptyString,
+  filenameMode: Schema.Literals(["convention", "custom"] as const)
+})
+
+export const SyncManifestSchema = Schema.Struct({
+  version: Schema.Literal(1),
+  siteUrl: SiteUrl,
+  issues: Schema.Array(ManifestIssueSchema)
+})
+
+const UserFieldValueSchema = Schema.Struct({
+  accountId: NonEmptyString,
+  displayName: NonEmptyString
+})
+
+const OptionFieldValueSchema = Schema.Struct({
+  id: Schema.optional(NonEmptyString),
+  value: NonEmptyString
+})
+
+const CascadingFieldValueSchema = Schema.Struct({
+  parent: OptionFieldValueSchema,
+  child: Schema.optional(OptionFieldValueSchema)
+})
+
+const SyncFieldValueItemSchema = Schema.Union([
+  Schema.String,
+  Schema.Number,
+  Schema.Boolean,
+  UserFieldValueSchema,
+  OptionFieldValueSchema
+])
+
+export const SyncFieldValueSchema = Schema.Union([
+  Schema.String,
+  Schema.Number,
+  Schema.Boolean,
+  Schema.Null,
+  UserFieldValueSchema,
+  OptionFieldValueSchema,
+  CascadingFieldValueSchema,
+  Schema.Array(SyncFieldValueItemSchema)
+])
+
+export const BaselineCustomFieldSchema = Schema.Struct({
+  fieldId: NonEmptyString,
+  displayName: NonEmptyString,
+  shape: FieldShapeSchema,
+  value: SyncFieldValueSchema
+})
+
+export const SyncBaselineSchema = Schema.Struct({
+  version: Schema.Literal(1),
+  issueId: NonEmptyString,
+  issueKey: NonEmptyString,
+  fields: Schema.Struct({
+    summary: Schema.String,
+    description: Schema.String,
+    labels: Schema.Array(Schema.String),
+    customFields: Schema.Record(Schema.String, BaselineCustomFieldSchema)
+  }),
+  comments: Schema.Array(Schema.Struct({ id: NonEmptyString }))
+})
+
+export type WorkspaceConfig = Schema.Schema.Type<typeof WorkspaceConfigSchema>
+export type SyncManifest = Schema.Schema.Type<typeof SyncManifestSchema>
+export type SyncBaseline = Schema.Schema.Type<typeof SyncBaselineSchema>

package/src/internal/sync/types.ts

@@ -0,0 +1,192 @@
+/**
+ * Core domain types for Jira Markdown Sync local workspace state.
+ *
+ * @internal
+ */
+
+export const FIELD_SHAPES = [
+  "text",
+  "multilineText",
+  "number",
+  "boolean",
+  "date",
+  "singleSelect",
+  "multiSelect",
+  "user",
+  "cascadingSelect"
+] as const
+
+export type FieldShape = typeof FIELD_SHAPES[number]
+
+export interface RequestedCustomField {
+  readonly displayName: string
+  readonly fieldId?: string | undefined
+  readonly shape: FieldShape
+  readonly ordered?: boolean | undefined
+}
+
+export interface WorkspaceConfig {
+  readonly version: 1
+  readonly siteUrl: string
+  readonly documentsDir: string
+  readonly customFields: ReadonlyArray<RequestedCustomField>
+}
+
+export type FilenameMode = "convention" | "custom"
+
+export interface ManifestIssue {
+  readonly issueId: string
+  readonly issueKey: string
+  readonly documentPath: string
+  readonly filenameMode: FilenameMode
+}
+
+export interface SyncManifest {
+  readonly version: 1
+  readonly siteUrl: string
+  readonly issues: ReadonlyArray<ManifestIssue>
+}
+
+export interface UserFieldValue {
+  readonly accountId: string
+  readonly displayName: string
+}
+
+export interface OptionFieldValue {
+  readonly id?: string | undefined
+  readonly value: string
+}
+
+export interface CascadingFieldValue {
+  readonly parent: OptionFieldValue
+  readonly child?: OptionFieldValue | undefined
+}
+
+export type SyncFieldScalar = string | number | boolean | null
+
+export type SyncFieldValue =
+  | SyncFieldScalar
+  | UserFieldValue
+  | OptionFieldValue
+  | CascadingFieldValue
+  | ReadonlyArray<string | number | boolean | UserFieldValue | OptionFieldValue>
+
+export interface BaselineCustomField {
+  readonly fieldId: string
+  readonly displayName: string
+  readonly shape: FieldShape
+  readonly value: SyncFieldValue
+}
+
+export interface SyncBaselineFields {
+  readonly summary: string
+  readonly description: string
+  readonly labels: ReadonlyArray<string>
+  readonly customFields: Readonly<Record<string, BaselineCustomField>>
+}
+
+export interface SyncBaselineComment {
+  readonly id: string
+}
+
+export interface SyncBaseline {
+  readonly version: 1
+  readonly issueId: string
+  readonly issueKey: string
+  readonly fields: SyncBaselineFields
+  readonly comments: ReadonlyArray<SyncBaselineComment>
+}
+
+export interface IssueDocumentFrontMatter {
+  readonly issueId: string
+  readonly issueKey: string
+  readonly summary: string
+  readonly status: string
+  readonly issueType: string
+  readonly priority: string | null
+  readonly assignee: UserFieldValue | null
+  readonly reporter: UserFieldValue | null
+  readonly labels: ReadonlyArray<string>
+  readonly customFields: Readonly<Record<string, SyncFieldValue>>
+}
+
+export interface CommentDraft {
+  readonly draftId: string
+  readonly body: string
+}
+
+export interface AcceptedComment {
+  readonly id: string
+  readonly author: string
+  readonly created: string
+  readonly body: string
+}
+
+export interface AttachmentReference {
+  readonly filename: string
+  readonly url: string
+}
+
+export interface IssueDocument {
+  readonly frontMatter: IssueDocumentFrontMatter
+  readonly description: string
+  readonly multilineCustomFields: Readonly<Record<string, string>>
+  readonly commentDrafts: ReadonlyArray<CommentDraft>
+  readonly acceptedComments: ReadonlyArray<AcceptedComment>
+  readonly attachments: ReadonlyArray<AttachmentReference>
+  readonly localNotes: string
+}
+
+export type SyncFieldPath =
+  | "summary"
+  | "description"
+  | "labels"
+  | `customFields.${string}`
+  | `readOnly.${string}`
+
+export interface SyncValidationFailure {
+  readonly _tag: "ValidationFailure"
+  readonly message: string
+  readonly issueKey?: string
+  readonly field?: SyncFieldPath
+  readonly path?: string
+}
+
+export interface SyncConflict {
+  readonly issueId: string
+  readonly issueKey: string
+  readonly field: SyncFieldPath
+  readonly baselineValue: SyncFieldValue
+  readonly jiraValue: SyncFieldValue
+  readonly documentValue: SyncFieldValue
+}
+
+export type PlannedFieldChange =
+  | {
+    readonly _tag: "RemoteOnly"
+    readonly issueId: string
+    readonly issueKey: string
+    readonly field: SyncFieldPath
+    readonly jiraValue: SyncFieldValue
+  }
+  | {
+    readonly _tag: "LocalOnly"
+    readonly issueId: string
+    readonly issueKey: string
+    readonly field: SyncFieldPath
+    readonly documentValue: SyncFieldValue
+  }
+  | {
+    readonly _tag: "Conflict"
+    readonly issueId: string
+    readonly issueKey: string
+    readonly field: SyncFieldPath
+    readonly baselineValue: SyncFieldValue
+    readonly jiraValue: SyncFieldValue
+    readonly documentValue: SyncFieldValue
+  }
+
+export interface SyncPlan {
+  readonly changes: ReadonlyArray<PlannedFieldChange>
+  readonly validationFailures: ReadonlyArray<SyncValidationFailure>
+}

package/test/SyncWorkspace.test.ts

@@ -0,0 +1,76 @@
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Layer from "effect/Layer"
+import * as Path from "effect/Path"
+import type { SyncBaseline } from "../src/internal/sync/types.js"
+import { layer as SyncWorkspaceLayer, SyncWorkspace } from "../src/SyncWorkspace.js"
+
+const TestLayer = SyncWorkspaceLayer.pipe(
+  Layer.provide(NodeServices.layer),
+  Layer.provideMerge(NodeServices.layer)
+)
+
+const makeTempRoot = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  return yield* fs.makeTempDirectoryScoped()
+})
+
+describe("SyncWorkspace", () => {
+  it.effect("initializes workspace metadata and visible documents directory", () =>
+    Effect.gen(function*() {
+      const root = yield* makeTempRoot
+      const workspace = yield* SyncWorkspace
+      const paths = yield* workspace.init({ root, siteUrl: "https://example.atlassian.net" })
+      const fs = yield* FileSystem.FileSystem
+
+      expect(yield* fs.exists(paths.documentsDir)).toBe(true)
+      expect(yield* fs.exists(paths.configFile)).toBe(true)
+      expect(yield* fs.exists(paths.manifestFile)).toBe(true)
+      expect(yield* fs.exists(paths.baselinesDir)).toBe(true)
+      expect(yield* fs.exists(paths.historyDir)).toBe(true)
+
+      const config = yield* workspace.readConfig(root)
+      const manifest = yield* workspace.readManifest(root)
+      expect(config.siteUrl).toBe("https://example.atlassian.net")
+      expect(config.documentsDir).toBe("issues")
+      expect(manifest.issues).toEqual([])
+    }).pipe(Effect.provide(TestLayer), Effect.scoped))
+
+  it.effect("writes and reads baselines by issue id", () =>
+    Effect.gen(function*() {
+      const root = yield* makeTempRoot
+      const workspace = yield* SyncWorkspace
+      yield* workspace.init({ root, siteUrl: "https://example.atlassian.net" })
+
+      const baseline: SyncBaseline = {
+        version: 1,
+        issueId: "100123",
+        issueKey: "PROJ-123",
+        fields: {
+          summary: "Fix checkout copy",
+          description: "Description",
+          labels: ["copy"],
+          customFields: {}
+        },
+        comments: []
+      }
+
+      yield* workspace.writeBaseline(root, baseline)
+      expect(yield* workspace.readBaseline(root, "100123")).toEqual(baseline)
+    }).pipe(Effect.provide(TestLayer), Effect.scoped))
+
+  it.effect("uses configured documents directory for convention document paths", () =>
+    Effect.gen(function*() {
+      const root = yield* makeTempRoot
+      const workspace = yield* SyncWorkspace
+      const path = yield* Path.Path
+      yield* workspace.init({ root, siteUrl: "https://example.atlassian.net" })
+      const config = yield* workspace.readConfig(root)
+      yield* workspace.writeConfig(root, { ...config, documentsDir: "issue-docs" })
+
+      const filePath = yield* workspace.conventionDocumentPath(root, "PROJ-123")
+      expect(filePath).toBe(path.join(root, "issue-docs", "PROJ-123.md"))
+    }).pipe(Effect.provide(TestLayer), Effect.scoped))
+})