@knpkv/atlassian-common 0.2.0

package/src/Hash.ts

@@ -0,0 +1,68 @@
+/**
+ * SHA256 content hashing via Node.js crypto, returning branded {@link ContentHash} values.
+ *
+ * **Mental model**
+ *
+ * - **Effect-wrapped crypto**: {@link hashContent} and {@link hashBuffer} return
+ *   `Effect<ContentHash>` so hashing composes into pipelines without try/catch.
+ * - **Sync escape hatch**: {@link hashContentSync} for contexts where Effect isn't needed.
+ *
+ * **Common tasks**
+ *
+ * - Hash a string: {@link hashContent}
+ * - Hash a buffer: {@link hashBuffer}
+ * - Compare hashes: {@link hashEquals}
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect"
+import * as crypto from "node:crypto"
+import { ContentHash } from "./Brand.js"
+
+/**
+ * Compute SHA256 hash of a string.
+ *
+ * @example
+ * ```typescript
+ * import { hashContent } from "@knpkv/atlassian-common"
+ * import * as Effect from "effect/Effect"
+ *
+ * const hash = Effect.runSync(hashContent("hello world"))
+ * // => "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ *
+ * @category Hash
+ */
+export const hashContent = (content: string): Effect.Effect<ContentHash> =>
+  Effect.sync(() => {
+    const hash = crypto.createHash("sha256").update(content, "utf8").digest("hex")
+    return ContentHash(hash)
+  })
+
+/**
+ * Compute SHA256 hash of a buffer.
+ *
+ * @category Hash
+ */
+export const hashBuffer = (buffer: Buffer | Uint8Array): Effect.Effect<ContentHash> =>
+  Effect.sync(() => {
+    const hash = crypto.createHash("sha256").update(buffer).digest("hex")
+    return ContentHash(hash)
+  })
+
+/**
+ * Check if two hashes are equal.
+ *
+ * @category Hash
+ */
+export const hashEquals = (a: ContentHash, b: ContentHash): boolean => a === b
+
+/**
+ * Synchronous version of hashContent for simple use cases.
+ *
+ * @category Hash
+ */
+export const hashContentSync = (content: string): ContentHash => {
+  const hash = crypto.createHash("sha256").update(content, "utf8").digest("hex")
+  return ContentHash(hash)
+}

package/src/SerializeError.ts

@@ -0,0 +1,50 @@
+/**
+ * Tagged error types for AST serialization and parsing failures.
+ *
+ * **Mental model**
+ *
+ * - **Discriminated by `_tag`**: {@link SerializeError} and {@link ParseError} extend
+ *   `Data.TaggedError`, enabling `Effect.catchTag` for selective recovery.
+ * - **Direction-aware**: Both carry a `target`/`source` field (`"confluence" | "markdown" | "adf"`)
+ *   so handlers know which serialization pipeline failed.
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+
+/**
+ * Error thrown when serializing AST fails.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { SerializeError } from "@knpkv/atlassian-common"
+ *
+ * Effect.gen(function* () {
+ *   // ... serialization operation
+ * }).pipe(
+ *   Effect.catchTag("SerializeError", (error) =>
+ *     Effect.sync(() => console.error(`Serialize error: ${error.message}`))
+ *   )
+ * )
+ * ```
+ *
+ * @category Errors
+ */
+export class SerializeError extends Data.TaggedError("SerializeError")<{
+  readonly target: "confluence" | "markdown" | "adf"
+  readonly nodeType: string
+  readonly message: string
+}> {}
+
+/**
+ * Error thrown when parsing content fails.
+ *
+ * @category Errors
+ */
+export class ParseError extends Data.TaggedError("ParseError")<{
+  readonly source: "confluence" | "markdown" | "adf"
+  readonly message: string
+  readonly position?: { readonly line: number; readonly column: number }
+  readonly rawContent?: string
+}> {}

package/src/ast/BlockNode.ts

@@ -0,0 +1,386 @@
+/**
+ * Block-level AST nodes for Atlassian content (headings, paragraphs, tables, lists, etc.).
+ *
+ * **Mental model**
+ *
+ * - **Schema-driven ADT**: Each node is an Effect `Schema.Struct` with a `_tag` discriminant,
+ *   composed into the {@link BlockNode} union via `Schema.Union`.
+ * - **Recursive via suspend**: `List` → `ListItem` → `BlockNode` cycles use `Schema.suspend`
+ *   to break infinite type recursion.
+ * - **Inline children**: Most blocks contain `InlineNode` children for text-level content.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+import { InlineNode, type InlineNode as InlineNodeType } from "./InlineNode.js"
+
+/**
+ * Schema version for migration support.
+ *
+ * @category Version
+ */
+export const SchemaVersion = Schema.Number.pipe(
+  Schema.int(),
+  Schema.positive(),
+  Schema.optionalWith({ default: () => 1 })
+)
+
+/**
+ * Optional raw source for exact roundtrip preservation.
+ *
+ * @category BlockNode
+ */
+export const RawSource = Schema.optional(Schema.String)
+
+/**
+ * Heading element (h1-h6).
+ *
+ * @example
+ * ```typescript
+ * import { Heading, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const h1 = new Heading({
+ *   level: 1,
+ *   children: [new Text({ value: "Introduction" })]
+ * })
+ * ```
+ *
+ * @category BlockNode
+ */
+export class Heading extends Schema.TaggedClass<Heading>()("Heading", {
+  version: SchemaVersion,
+  level: Schema.Literal(1, 2, 3, 4, 5, 6),
+  children: Schema.Array(InlineNode),
+  rawSource: RawSource
+}) {}
+
+/**
+ * Text alignment options.
+ *
+ * @category BlockNode
+ */
+export const TextAlignment = Schema.Literal("left", "center", "right")
+
+/**
+ * Type for TextAlignment.
+ *
+ * @category Types
+ */
+export type TextAlignment = Schema.Schema.Type<typeof TextAlignment>
+
+/**
+ * Paragraph element with optional alignment and indentation.
+ *
+ * @example
+ * ```typescript
+ * import { Paragraph, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const para = new Paragraph({
+ *   children: [new Text({ value: "Hello world" })]
+ * })
+ * ```
+ *
+ * @category BlockNode
+ */
+export class Paragraph extends Schema.TaggedClass<Paragraph>()("Paragraph", {
+  version: SchemaVersion,
+  alignment: Schema.optional(TextAlignment),
+  indent: Schema.optional(Schema.Number),
+  children: Schema.Array(InlineNode),
+  rawSource: RawSource
+}) {}
+
+/**
+ * Code block with optional language.
+ *
+ * @example
+ * ```typescript
+ * import { CodeBlock } from "@knpkv/atlassian-common/ast"
+ *
+ * const code = new CodeBlock({
+ *   language: "typescript",
+ *   code: "const x = 1"
+ * })
+ * ```
+ *
+ * @category BlockNode
+ */
+export class CodeBlock extends Schema.TaggedClass<CodeBlock>()("CodeBlock", {
+  version: SchemaVersion,
+  language: Schema.optional(Schema.String),
+  code: Schema.String,
+  rawSource: RawSource
+}) {}
+
+/**
+ * Thematic break / horizontal rule.
+ *
+ * @example
+ * ```typescript
+ * import { ThematicBreak } from "@knpkv/atlassian-common/ast"
+ *
+ * const hr = new ThematicBreak({})
+ * ```
+ *
+ * @category BlockNode
+ */
+export class ThematicBreak extends Schema.TaggedClass<ThematicBreak>()("ThematicBreak", {
+  rawSource: RawSource
+}) {}
+
+/**
+ * Attachment reference for images.
+ *
+ * @category BlockNode
+ */
+export const ImageAttachment = Schema.Struct({
+  filename: Schema.String,
+  version: Schema.optional(Schema.Number)
+})
+
+/**
+ * Type for ImageAttachment.
+ *
+ * @category Types
+ */
+export type ImageAttachment = Schema.Schema.Type<typeof ImageAttachment>
+
+/**
+ * Image element with support for both URL and attachments.
+ *
+ * @example
+ * ```typescript
+ * import { Image } from "@knpkv/atlassian-common/ast"
+ *
+ * const img = new Image({
+ *   src: "https://example.com/image.png",
+ *   alt: "Example image"
+ * })
+ * ```
+ *
+ * @category BlockNode
+ */
+export class Image extends Schema.TaggedClass<Image>()("Image", {
+  version: SchemaVersion,
+  src: Schema.optional(Schema.String),
+  attachment: Schema.optional(ImageAttachment),
+  alt: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  align: Schema.optional(Schema.String),
+  width: Schema.optional(Schema.Number),
+  rawSource: RawSource
+}) {}
+
+/**
+ * Table cell element.
+ *
+ * @example
+ * ```typescript
+ * import { TableCell, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const cell = new TableCell({
+ *   isHeader: true,
+ *   children: [new Text({ value: "Header" })]
+ * })
+ * ```
+ *
+ * @category BlockNode
+ */
+export class TableCell extends Schema.TaggedClass<TableCell>()("TableCell", {
+  isHeader: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  children: Schema.Array(InlineNode),
+  rawSource: RawSource
+}) {}
+
+/**
+ * Table row element.
+ *
+ * @category BlockNode
+ */
+export class TableRow extends Schema.TaggedClass<TableRow>()("TableRow", {
+  cells: Schema.Array(TableCell),
+  rawSource: RawSource
+}) {}
+
+/**
+ * Table element with optional header row.
+ *
+ * @category BlockNode
+ */
+export class Table extends Schema.TaggedClass<Table>()("Table", {
+  version: SchemaVersion,
+  header: Schema.optional(TableRow),
+  rows: Schema.Array(TableRow),
+  rawSource: RawSource
+}) {}
+
+/**
+ * Unsupported block element - preserves raw content for round-tripping.
+ *
+ * @category BlockNode
+ */
+export class UnsupportedBlock extends Schema.TaggedClass<UnsupportedBlock>()("UnsupportedBlock", {
+  rawHtml: Schema.optional(Schema.String),
+  rawMarkdown: Schema.optional(Schema.String),
+  rawAdf: Schema.optional(Schema.String),
+  source: Schema.Literal("confluence", "markdown", "adf")
+}) {}
+
+// Non-recursive block nodes
+const SimpleBlockNode = Schema.Union(
+  Heading,
+  Paragraph,
+  CodeBlock,
+  ThematicBreak,
+  Image,
+  Table,
+  UnsupportedBlock
+)
+
+/**
+ * Block quote element with nested block content.
+ *
+ * @category BlockNode
+ */
+export const BlockQuote = Schema.Struct({
+  _tag: Schema.Literal("BlockQuote"),
+  version: SchemaVersion,
+  children: Schema.Array(SimpleBlockNode),
+  rawSource: RawSource
+})
+
+/**
+ * Type for BlockQuote.
+ *
+ * @category Types
+ */
+export type BlockQuote = Schema.Schema.Type<typeof BlockQuote>
+
+/**
+ * List item with nested block content.
+ *
+ * @category BlockNode
+ */
+export const ListItem = Schema.Struct({
+  _tag: Schema.Literal("ListItem"),
+  checked: Schema.optional(Schema.Boolean),
+  children: Schema.Array(SimpleBlockNode),
+  rawSource: RawSource
+})
+
+/**
+ * Type for ListItem.
+ *
+ * @category Types
+ */
+export type ListItem = Schema.Schema.Type<typeof ListItem>
+
+/**
+ * List element (ordered or unordered).
+ *
+ * @category BlockNode
+ */
+export const List = Schema.Struct({
+  _tag: Schema.Literal("List"),
+  version: SchemaVersion,
+  ordered: Schema.Boolean,
+  start: Schema.optional(Schema.Number),
+  children: Schema.Array(ListItem),
+  rawSource: RawSource
+})
+
+/**
+ * Type for List.
+ *
+ * @category Types
+ */
+export type List = Schema.Schema.Type<typeof List>
+
+/**
+ * Task item with status.
+ *
+ * @category BlockNode
+ */
+export const TaskItem = Schema.Struct({
+  _tag: Schema.Literal("TaskItem"),
+  id: Schema.String,
+  uuid: Schema.String,
+  status: Schema.Literal("incomplete", "complete"),
+  body: Schema.Array(InlineNode),
+  rawSource: RawSource
+})
+
+/**
+ * Type for TaskItem.
+ *
+ * @category Types
+ */
+export type TaskItem = Schema.Schema.Type<typeof TaskItem>
+
+/**
+ * Task list.
+ *
+ * @category BlockNode
+ */
+export const TaskList = Schema.Struct({
+  _tag: Schema.Literal("TaskList"),
+  version: SchemaVersion,
+  children: Schema.Array(TaskItem),
+  rawSource: RawSource
+})
+
+/**
+ * Type for TaskList.
+ *
+ * @category Types
+ */
+export type TaskList = Schema.Schema.Type<typeof TaskList>
+
+/**
+ * Union of all block node types.
+ *
+ * @category BlockNode
+ */
+export const BlockNode = Schema.Union(
+  Heading,
+  Paragraph,
+  CodeBlock,
+  ThematicBreak,
+  BlockQuote,
+  Image,
+  Table,
+  List,
+  TaskList,
+  UnsupportedBlock
+)
+
+/**
+ * Type for block nodes.
+ *
+ * @category Types
+ */
+export type BlockNode =
+  | Heading
+  | Paragraph
+  | CodeBlock
+  | ThematicBreak
+  | BlockQuote
+  | Image
+  | Table
+  | List
+  | TaskList
+  | UnsupportedBlock
+
+/**
+ * Type helper for inline node children in blocks.
+ *
+ * @category Types
+ */
+export type { InlineNodeType as InlineNode }
+
+/**
+ * Simple block nodes (non-recursive).
+ *
+ * @category BlockNode
+ */
+export { SimpleBlockNode }

package/src/ast/Document.ts

@@ -0,0 +1,101 @@
+/**
+ * Root AST node wrapping a sequence of {@link DocumentNode} children.
+ *
+ * **Mental model**
+ *
+ * - **Document = version + children**: The top-level container for parsed Atlassian content.
+ *   `children` is a union of `BlockNode | MacroNode`.
+ * - **Raw source preservation**: Optional `rawSource` field enables lossless roundtripping.
+ *
+ * **Common tasks**
+ *
+ * - Construct a document: {@link makeDocument}
+ * - Type-guard check: {@link isDocument}
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+import { BlockNode, type BlockNode as BlockNodeType, RawSource, SchemaVersion } from "./BlockNode.js"
+import { MacroNode, type MacroNode as MacroNodeType } from "./MacroNode.js"
+
+/**
+ * Document node - represents a Block or Macro node.
+ *
+ * @category Document
+ */
+export const DocumentNode = Schema.Union(BlockNode, MacroNode)
+
+/**
+ * Type for document nodes.
+ *
+ * @category Types
+ */
+export type DocumentNode = BlockNodeType | MacroNodeType
+
+/**
+ * Document schema - the root AST node.
+ *
+ * @example
+ * ```typescript
+ * import { Document, Heading, Paragraph, Text } from "@knpkv/atlassian-common/ast"
+ * import * as Schema from "effect/Schema"
+ *
+ * const doc = {
+ *   version: 1,
+ *   children: [
+ *     new Heading({ level: 1, children: [new Text({ value: "Title" })] }),
+ *     new Paragraph({ children: [new Text({ value: "Content" })] })
+ *   ]
+ * }
+ *
+ * const validated = Schema.decodeUnknownSync(Document)(doc)
+ * ```
+ *
+ * @category Document
+ */
+export const Document = Schema.Struct({
+  version: SchemaVersion,
+  children: Schema.Array(DocumentNode),
+  rawSource: RawSource
+})
+
+/**
+ * Type for Document.
+ *
+ * @category Types
+ */
+export type Document = Schema.Schema.Type<typeof Document>
+
+/**
+ * Create a new Document with default version.
+ *
+ * @example
+ * ```typescript
+ * import { makeDocument, Heading, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const doc = makeDocument([
+ *   new Heading({ level: 1, children: [new Text({ value: "Hello" })] })
+ * ])
+ * ```
+ *
+ * @category Constructors
+ */
+export const makeDocument = (
+  children: ReadonlyArray<DocumentNode>,
+  rawSource?: string
+): Document => ({
+  version: 1,
+  children,
+  ...(rawSource !== undefined ? { rawSource } : {})
+})
+
+/**
+ * Check if a node is a Document.
+ *
+ * @category Guards
+ */
+export const isDocument = (value: unknown): value is Document =>
+  typeof value === "object" &&
+  value !== null &&
+  "children" in value &&
+  Array.isArray((value as Document).children)