@knpkv/confluence-to-markdown 0.2.0 → 0.4.2

package/src/parsers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Parsers for Confluence HTML and Markdown to AST.
+ *
+ * @module
+ */
+
+export { parseConfluenceHtml } from "./ConfluenceParser.js"
+export { parseMarkdown } from "./MarkdownParser.js"

package/src/schemas/ConfluenceSchema.ts

@@ -0,0 +1,56 @@
+/**
+ * Bi-directional schema for Confluence HTML <-> AST transformation.
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect"
+import * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
+import type { Document } from "../ast/Document.js"
+import { parseConfluenceHtml } from "../parsers/ConfluenceParser.js"
+import { serializeToConfluence } from "../serializers/ConfluenceSerializer.js"
+
+/**
+ * Schema.Type placeholder for Document to use with transformOrFail.
+ * We use Schema.Any since Document is already a union type.
+ */
+const DocumentSchema = Schema.Any as Schema.Schema<Document, Document>
+
+/**
+ * Bi-directional schema: Confluence HTML string <-> Document AST.
+ *
+ * @example
+ * ```typescript
+ * import { DocumentFromConfluence } from "@knpkv/confluence-to-markdown/schemas/ConfluenceSchema"
+ * import { Schema, Effect } from "effect"
+ *
+ * // Decode: HTML -> AST
+ * const decodeResult = Schema.decodeUnknown(DocumentFromConfluence)(htmlString)
+ *
+ * // Encode: AST -> HTML
+ * const encodeResult = Schema.encode(DocumentFromConfluence)(document)
+ * ```
+ *
+ * @category Schemas
+ */
+export const DocumentFromConfluence: Schema.Schema<
+  Document,
+  string,
+  never
+> = Schema.transformOrFail(
+  Schema.String,
+  DocumentSchema,
+  {
+    strict: true,
+    decode: (html, _opts, ast) =>
+      Effect.mapError(
+        parseConfluenceHtml(html),
+        (err) => new ParseResult.Type(ast, html, err.message)
+      ),
+    encode: (doc, _opts, ast) =>
+      Effect.mapError(
+        serializeToConfluence(doc),
+        (err) => new ParseResult.Type(ast, doc, err.message)
+      )
+  }
+)

package/src/schemas/ConversionSchema.ts

@@ -0,0 +1,318 @@
+/**
+ * Direct conversion schema: Confluence HTML <-> Markdown.
+ *
+ * Composes preprocessing, parsing, and serialization into a single transform.
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect"
+import * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
+import type { BlockNode } from "../ast/BlockNode.js"
+import { type Document, makeDocument } from "../ast/Document.js"
+import type { MacroNode } from "../ast/MacroNode.js"
+import type { HastElement, HastNode, HastRoot } from "./hast/index.js"
+import { HastFromHtml, isHastElement } from "./hast/index.js"
+import type { MdastBlockContent, MdastRoot } from "./mdast/index.js"
+import { MdastFromMarkdown, mdastToString } from "./mdast/index.js"
+import { blockNodeFromHastElement, blockNodeFromMdast, blockNodeToMdast } from "./nodes/index.js"
+import { macroNodeFromHastElement, macroNodeToMdast } from "./nodes/macro/index.js"
+import { PreprocessedHtmlFromConfluence } from "./preprocessing/index.js"
+
+type DocumentNode = BlockNode | MacroNode
+
+/**
+ * Parse HAST children to simple block nodes.
+ * Note: Returns BlockNode which is broader than SimpleBlock used by macros,
+ * but at runtime only simple blocks are returned from single-level parsing.
+ */
+const parseBlockChildren = (
+  children: ReadonlyArray<HastNode>
+): Effect.Effect<ReadonlyArray<BlockNode>, ParseResult.ParseError> =>
+  Effect.forEach(
+    children.filter(isHastElement),
+    (el) =>
+      blockNodeFromHastElement(el).pipe(
+        Effect.map((node): ReadonlyArray<BlockNode> => (node !== null ? [node] : []))
+      )
+  ).pipe(Effect.map((arrays) => arrays.flat()))
+
+/**
+ * Parse single HAST element to document node (block or macro).
+ */
+const documentNodeFromHastElement = (
+  element: HastElement
+): Effect.Effect<DocumentNode | null, ParseResult.ParseError> =>
+  Effect.gen(function*() {
+    // Try macro first
+    const macro = yield* macroNodeFromHastElement(element, parseBlockChildren)
+    if (macro !== null) {
+      return macro
+    }
+
+    // Fall back to block
+    const block = yield* blockNodeFromHastElement(element)
+    return block
+  })
+
+/**
+ * Parse HAST root to Document AST.
+ */
+const documentFromHastRoot = (
+  root: HastRoot,
+  rawConfluence?: string
+): Effect.Effect<Document, ParseResult.ParseError> =>
+  Effect.gen(function*() {
+    const elements = root.children.filter(isHastElement)
+    const nodeArrays = yield* Effect.forEach(elements, (el) =>
+      documentNodeFromHastElement(el).pipe(
+        Effect.map((node) => (node !== null ? [node] : []))
+      ))
+    const children = nodeArrays.flat()
+    return makeDocument(children, rawConfluence)
+  })
+
+/**
+ * Parse MDAST root to Document AST.
+ */
+const documentFromMdastRoot = (root: MdastRoot): Document => {
+  const children: Array<DocumentNode> = []
+  for (const node of root.children) {
+    const blockContent = node as MdastBlockContent
+    const block = blockNodeFromMdast(blockContent)
+    children.push(block)
+  }
+  return makeDocument(children)
+}
+
+/**
+ * Check if node is a macro node.
+ */
+const isMacroNode = (node: DocumentNode): node is MacroNode => {
+  return node._tag === "InfoPanel" ||
+    node._tag === "ExpandMacro" ||
+    node._tag === "TocMacro" ||
+    node._tag === "CodeMacro" ||
+    node._tag === "StatusMacro"
+}
+
+/**
+ * Serialize Document AST to Markdown.
+ */
+const documentToMarkdown = (doc: Document): string => {
+  const parts: Array<string> = []
+  for (const node of doc.children) {
+    const mdast = isMacroNode(node)
+      ? macroNodeToMdast(node)
+      : blockNodeToMdast(node as BlockNode)
+    parts.push(mdastToString(mdast))
+  }
+  return parts.join("\n\n")
+}
+
+/**
+ * Schema for transforming preprocessed Confluence HTML to Document AST.
+ */
+export const DocumentFromHast: Schema.Schema<
+  Document,
+  HastRoot,
+  never
+> = Schema.transformOrFail(
+  Schema.Any as Schema.Schema<HastRoot, HastRoot>,
+  Schema.Any as Schema.Schema<Document, Document>,
+  {
+    strict: true,
+    decode: (root, _options, ast) =>
+      documentFromHastRoot(root).pipe(
+        Effect.mapError((e) => new ParseResult.Type(ast, root, e.message))
+      ),
+    encode: (_doc, _options, ast) =>
+      Effect.fail(new ParseResult.Type(ast, _doc, "Document to HAST encoding not implemented"))
+  }
+)
+
+/**
+ * Schema for transforming MDAST root to Document AST.
+ */
+export const DocumentFromMdast: Schema.Schema<
+  Document,
+  MdastRoot,
+  never
+> = Schema.transformOrFail(
+  Schema.Any as Schema.Schema<MdastRoot, MdastRoot>,
+  Schema.Any as Schema.Schema<Document, Document>,
+  {
+    strict: true,
+    decode: (root, _options, _ast) => Effect.succeed(documentFromMdastRoot(root)),
+    encode: (_doc, _options, ast) =>
+      Effect.fail(new ParseResult.Type(ast, _doc, "Document to MDAST encoding not implemented"))
+  }
+)
+
+/**
+ * Direct conversion schema: Confluence HTML string <-> Markdown string.
+ *
+ * @example
+ * ```typescript
+ * import { ConfluenceToMarkdown } from "@knpkv/confluence-to-markdown/schemas/ConversionSchema"
+ * import { Schema, Effect } from "effect"
+ *
+ * // Decode: Confluence HTML -> Markdown
+ * const markdown = Effect.runSync(
+ *   Schema.decode(ConfluenceToMarkdown)(confluenceHtml)
+ * )
+ *
+ * // Encode: Markdown -> Confluence HTML (limited support)
+ * const html = Effect.runSync(
+ *   Schema.encode(ConfluenceToMarkdown)(markdown)
+ * )
+ * ```
+ *
+ * @category Schemas
+ */
+export const ConfluenceToMarkdown: Schema.Schema<
+  string,
+  string,
+  never
+> = Schema.transformOrFail(
+  Schema.String,
+  Schema.String,
+  {
+    strict: true,
+    decode: (html, _options, ast) =>
+      Effect.gen(function*() {
+        // Preprocess
+        const preprocessed = yield* Schema.decode(PreprocessedHtmlFromConfluence)(html).pipe(
+          Effect.mapError((e) => new ParseResult.Type(ast, html, `Preprocessing failed: ${e.message}`))
+        )
+
+        // Parse to HAST
+        const hast = yield* Schema.decode(HastFromHtml)(preprocessed).pipe(
+          Effect.mapError((e) => new ParseResult.Type(ast, html, `HAST parsing failed: ${e.message}`))
+        )
+
+        // Convert to Document
+        const doc = yield* documentFromHastRoot(hast, html).pipe(
+          Effect.mapError((e) => new ParseResult.Type(ast, html, `Document conversion failed: ${e.message}`))
+        )
+
+        // Serialize to Markdown
+        return documentToMarkdown(doc)
+      }),
+    encode: (md, _options, ast) =>
+      Schema.decode(MdastFromMarkdown)(md).pipe(
+        Effect.mapError((e) => new ParseResult.Type(ast, md, `MDAST parsing failed: ${e.message}`)),
+        Effect.map((mdast) => {
+          const doc = documentFromMdastRoot(mdast)
+
+          // Note: Full HTML serialization is complex; return basic HTML
+          // For full fidelity, use the existing ConfluenceSerializer
+          const parts: Array<string> = []
+          for (const node of doc.children) {
+            parts.push(documentNodeToHtml(node))
+          }
+          return parts.join("\n")
+        })
+      )
+  }
+)
+
+/**
+ * Basic document node to HTML conversion.
+ */
+const documentNodeToHtml = (node: DocumentNode): string => {
+  switch (node._tag) {
+    case "Heading":
+      return `<h${node.level}>${node.children.map(inlineToHtml).join("")}</h${node.level}>`
+    case "Paragraph":
+      return `<p>${node.children.map(inlineToHtml).join("")}</p>`
+    case "CodeBlock":
+      return `<pre><code${node.language ? ` class="language-${node.language}"` : ""}>${
+        escapeHtml(node.code)
+      }</code></pre>`
+    case "ThematicBreak":
+      return "<hr />"
+    case "Image":
+      return `<img src="${escapeHtml(node.src ?? "")}" alt="${escapeHtml(node.alt ?? "")}" />`
+    case "BlockQuote":
+      return `<blockquote>${node.children.map((c) => documentNodeToHtml(c as DocumentNode)).join("")}</blockquote>`
+    case "List": {
+      const tag = node.ordered ? "ol" : "ul"
+      return `<${tag}>${
+        node.children.map((item) =>
+          `<li>${item.children.map((c) => documentNodeToHtml(c as DocumentNode)).join("")}</li>`
+        ).join("")
+      }</${tag}>`
+    }
+    case "Table":
+      return `<table>${
+        node.rows.map((row) =>
+          `<tr>${
+            row.cells.map((cell) =>
+              cell.isHeader
+                ? `<th>${cell.children.map(inlineToHtml).join("")}</th>`
+                : `<td>${cell.children.map(inlineToHtml).join("")}</td>`
+            ).join("")
+          }</tr>`
+        ).join("")
+      }</table>`
+    case "InfoPanel":
+      return `<div data-macro="${node.panelType}">${
+        node.children.map((c) => documentNodeToHtml(c as DocumentNode)).join("")
+      }</div>`
+    case "ExpandMacro":
+      return `<details><summary>${escapeHtml(node.title ?? "")}</summary>${
+        node.children.map((c) => documentNodeToHtml(c as DocumentNode)).join("")
+      }</details>`
+    case "TocMacro":
+      return `<nav data-macro="toc"></nav>`
+    case "CodeMacro":
+      return `<pre data-macro="code"${node.language ? ` data-language="${node.language}"` : ""}><code>${
+        escapeHtml(node.code)
+      }</code></pre>`
+    case "StatusMacro":
+      return `<span data-macro="status" data-color="${node.color}">${escapeHtml(node.text)}</span>`
+    default:
+      return ""
+  }
+}
+
+/**
+ * Basic inline node to HTML.
+ */
+const inlineToHtml = (
+  node: { _tag: string; value?: string; children?: ReadonlyArray<unknown>; url?: string }
+): string => {
+  switch (node._tag) {
+    case "Text":
+      return escapeHtml(node.value ?? "")
+    case "Strong":
+      return `<strong>${
+        (node.children as ReadonlyArray<{ _tag: string; value?: string }>)?.map(inlineToHtml).join("") ?? ""
+      }</strong>`
+    case "Emphasis":
+      return `<em>${
+        (node.children as ReadonlyArray<{ _tag: string; value?: string }>)?.map(inlineToHtml).join("") ?? ""
+      }</em>`
+    case "InlineCode":
+      return `<code>${escapeHtml(node.value ?? "")}</code>`
+    case "Link":
+      return `<a href="${escapeHtml(node.url ?? "")}">${
+        (node.children as ReadonlyArray<{ _tag: string; value?: string }>)?.map(inlineToHtml).join("") ?? ""
+      }</a>`
+    case "LineBreak":
+      return "<br />"
+    default:
+      return ""
+  }
+}
+
+/**
+ * Escape HTML special characters.
+ */
+const escapeHtml = (str: string): string =>
+  str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")

package/src/schemas/MarkdownSchema.ts

@@ -0,0 +1,56 @@
+/**
+ * Bi-directional schema for Markdown <-> AST transformation.
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect"
+import * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
+import type { Document } from "../ast/Document.js"
+import { parseMarkdown } from "../parsers/MarkdownParser.js"
+import { serializeToMarkdown } from "../serializers/MarkdownSerializer.js"
+
+/**
+ * Schema.Type placeholder for Document to use with transformOrFail.
+ * We use Schema.Any since Document is already a union type.
+ */
+const DocumentSchema = Schema.Any as Schema.Schema<Document, Document>
+
+/**
+ * Bi-directional schema: Markdown string <-> Document AST.
+ *
+ * @example
+ * ```typescript
+ * import { DocumentFromMarkdown } from "@knpkv/confluence-to-markdown/schemas/MarkdownSchema"
+ * import { Schema, Effect } from "effect"
+ *
+ * // Decode: Markdown -> AST
+ * const decodeResult = Schema.decodeUnknown(DocumentFromMarkdown)(markdownString)
+ *
+ * // Encode: AST -> Markdown
+ * const encodeResult = Schema.encode(DocumentFromMarkdown)(document)
+ * ```
+ *
+ * @category Schemas
+ */
+export const DocumentFromMarkdown: Schema.Schema<
+  Document,
+  string,
+  never
+> = Schema.transformOrFail(
+  Schema.String,
+  DocumentSchema,
+  {
+    strict: true,
+    decode: (md, _opts, ast) =>
+      Effect.mapError(
+        parseMarkdown(md),
+        (err) => new ParseResult.Type(ast, md, err.message)
+      ),
+    encode: (doc, _opts, ast) =>
+      Effect.mapError(
+        serializeToMarkdown(doc),
+        (err) => new ParseResult.Type(ast, doc, err.message)
+      )
+  }
+)

package/src/schemas/hast/HastFromHtml.ts

@@ -0,0 +1,153 @@
+/**
+ * Schema transformation from HTML string to HAST (Hypertext Abstract Syntax Tree).
+ *
+ * Uses rehype-parse for HTML parsing and wraps the result in Effect Schema types.
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect"
+import * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
+import rehypeParse from "rehype-parse"
+import rehypeStringify from "rehype-stringify"
+import { unified } from "unified"
+import type { HastNode, HastRoot } from "./HastSchema.js"
+import {
+  HastRootSchema,
+  makeHastComment,
+  makeHastDoctype,
+  makeHastElement,
+  makeHastRoot,
+  makeHastText
+} from "./HastSchema.js"
+
+// Unist/Hast types from rehype-parse (simplified)
+interface UnistNode {
+  type: string
+  value?: string
+  tagName?: string
+  properties?: Record<string, unknown>
+  children?: Array<UnistNode>
+}
+
+interface UnistRoot {
+  type: "root"
+  children: Array<UnistNode>
+}
+
+/**
+ * Convert unist node from rehype-parse to our HastNode type.
+ */
+const convertToHastNode = (node: UnistNode): HastNode => {
+  switch (node.type) {
+    case "text":
+      return makeHastText(node.value ?? "")
+    case "comment":
+      return makeHastComment(node.value ?? "")
+    case "doctype":
+      return makeHastDoctype()
+    case "element":
+      return makeHastElement(
+        node.tagName ?? "div",
+        node.properties ?? {},
+        (node.children ?? []).map(convertToHastNode)
+      )
+    default:
+      // Unknown node type - treat as comment to preserve
+      return makeHastComment(`unknown:${node.type}`)
+  }
+}
+
+/**
+ * Convert our HastNode type back to unist format for serialization.
+ */
+const convertFromHastNode = (node: HastNode): UnistNode => {
+  switch (node._tag) {
+    case "text":
+      return { type: "text", value: node.value }
+    case "comment":
+      return { type: "comment", value: node.value }
+    case "doctype":
+      return { type: "doctype" }
+    case "element":
+      return {
+        type: "element",
+        tagName: node.tagName,
+        properties: node.properties,
+        children: node.children.map(convertFromHastNode)
+      }
+  }
+}
+
+/**
+ * Convert unist root to HastRoot.
+ */
+const convertToHastRoot = (root: UnistRoot): HastRoot => makeHastRoot(root.children.map(convertToHastNode))
+
+/**
+ * Convert HastRoot back to unist root for serialization.
+ */
+const convertFromHastRoot = (root: HastRoot): UnistRoot => ({
+  type: "root",
+  children: root.children.map(convertFromHastNode)
+})
+
+/**
+ * Transform HTML string to HAST root.
+ *
+ * Uses rehype-parse to parse HTML and converts the result to our schema types.
+ * Supports bidirectional transformation (decode HTML -> HAST, encode HAST -> HTML).
+ *
+ * @example
+ * ```typescript
+ * import { HastFromHtml } from "@knpkv/confluence-to-markdown/schemas/hast"
+ * import * as Schema from "effect/Schema"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const hast = yield* Schema.decode(HastFromHtml)("<h1>Hello</h1><p>World</p>")
+ *   console.log(hast.children.length) // 2
+ *   console.log(hast.children[0]._tag) // "element"
+ * })
+ *
+ * Effect.runPromise(program)
+ * ```
+ *
+ * @category Hast
+ */
+export const HastFromHtml: Schema.Schema<HastRoot, string> = Schema.transformOrFail(
+  Schema.String,
+  HastRootSchema,
+  {
+    strict: true,
+    decode: (html, _options, ast) =>
+      Effect.try({
+        try: () => {
+          const result = unified()
+            .use(rehypeParse, { fragment: true })
+            .parse(html) as UnistRoot
+          return convertToHastRoot(result)
+        },
+        catch: (error) =>
+          new ParseResult.Type(
+            ast,
+            html,
+            `HTML parse error: ${error instanceof Error ? error.message : String(error)}`
+          )
+      }),
+    encode: (hast, _options, ast) =>
+      Effect.try({
+        try: () => {
+          const unist = convertFromHastRoot(hast)
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          return unified().use(rehypeStringify).stringify(unist as any)
+        },
+        catch: (error) =>
+          new ParseResult.Type(
+            ast,
+            hast,
+            `HTML stringify error: ${error instanceof Error ? error.message : String(error)}`
+          )
+      })
+  }
+)