@knpkv/confluence-to-markdown 0.2.0 → 0.4.1

package/src/schemas/hast/HastSchema.ts

@@ -0,0 +1,274 @@
+/**
+ * Effect Schema definitions for HAST (Hypertext Abstract Syntax Tree) nodes.
+ *
+ * HAST is the intermediate representation used when parsing HTML.
+ * These schemas provide type-safe transformation between raw HTML and our AST.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+
+/**
+ * HAST element properties type.
+ *
+ * @category Types
+ */
+export type HastProperties = Record<string, unknown>
+
+/**
+ * HAST text node type.
+ *
+ * @category Types
+ */
+export interface HastText {
+  readonly _tag: "text"
+  readonly value: string
+}
+
+/**
+ * HAST comment node type.
+ *
+ * @category Types
+ */
+export interface HastComment {
+  readonly _tag: "comment"
+  readonly value: string
+}
+
+/**
+ * HAST doctype node type.
+ *
+ * @category Types
+ */
+export interface HastDoctype {
+  readonly _tag: "doctype"
+}
+
+/**
+ * HAST element node type.
+ *
+ * @category Types
+ */
+export interface HastElement {
+  readonly _tag: "element"
+  readonly tagName: string
+  readonly properties: HastProperties
+  readonly children: ReadonlyArray<HastNode>
+}
+
+/**
+ * Union of all HAST node types.
+ *
+ * @category Types
+ */
+export type HastNode = HastText | HastElement | HastComment | HastDoctype
+
+/**
+ * HAST root node type.
+ *
+ * @category Types
+ */
+export interface HastRoot {
+  readonly _tag: "root"
+  readonly children: ReadonlyArray<HastNode>
+}
+
+/**
+ * Create a HAST text node.
+ *
+ * @example
+ * ```typescript
+ * import { makeHastText } from "@knpkv/confluence-to-markdown/schemas/hast"
+ *
+ * const text = makeHastText("Hello world")
+ * console.log(text.value) // "Hello world"
+ * ```
+ *
+ * @category Constructors
+ */
+export const makeHastText = (value: string): HastText => ({
+  _tag: "text",
+  value
+})
+
+/**
+ * Create a HAST comment node.
+ *
+ * @example
+ * ```typescript
+ * import { makeHastComment } from "@knpkv/confluence-to-markdown/schemas/hast"
+ *
+ * const comment = makeHastComment("cf:layout-start")
+ * ```
+ *
+ * @category Constructors
+ */
+export const makeHastComment = (value: string): HastComment => ({
+  _tag: "comment",
+  value
+})
+
+/**
+ * Create a HAST doctype node.
+ *
+ * @category Constructors
+ */
+export const makeHastDoctype = (): HastDoctype => ({
+  _tag: "doctype"
+})
+
+/**
+ * Create a HAST element node.
+ *
+ * @example
+ * ```typescript
+ * import { makeHastElement, makeHastText } from "@knpkv/confluence-to-markdown/schemas/hast"
+ *
+ * const heading = makeHastElement("h1", { id: "title" }, [makeHastText("Hello")])
+ * ```
+ *
+ * @category Constructors
+ */
+export const makeHastElement = (
+  tagName: string,
+  properties: HastProperties = {},
+  children: ReadonlyArray<HastNode> = []
+): HastElement => ({
+  _tag: "element",
+  tagName,
+  properties,
+  children
+})
+
+/**
+ * Create a HAST root node.
+ *
+ * @example
+ * ```typescript
+ * import { makeHastRoot, makeHastElement, makeHastText } from "@knpkv/confluence-to-markdown/schemas/hast"
+ *
+ * const root = makeHastRoot([
+ *   makeHastElement("p", {}, [makeHastText("Content")])
+ * ])
+ * ```
+ *
+ * @category Constructors
+ */
+export const makeHastRoot = (children: ReadonlyArray<HastNode>): HastRoot => ({
+  _tag: "root",
+  children
+})
+
+/**
+ * Type guard to check if a HastNode is a HastElement.
+ *
+ * @category Guards
+ */
+export const isHastElement = (node: HastNode): node is HastElement => node._tag === "element"
+
+/**
+ * Type guard to check if a HastNode is a HastText.
+ *
+ * @category Guards
+ */
+export const isHastText = (node: HastNode): node is HastText => node._tag === "text"
+
+/**
+ * Type guard to check if a HastNode is a HastComment.
+ *
+ * @category Guards
+ */
+export const isHastComment = (node: HastNode): node is HastComment => node._tag === "comment"
+
+/**
+ * Get text content from a HastNode recursively.
+ *
+ * @category Utilities
+ */
+export const getTextContent = (node: HastNode): string => {
+  if (isHastText(node)) {
+    return node.value
+  }
+  if (isHastElement(node)) {
+    return node.children.map(getTextContent).join("")
+  }
+  return ""
+}
+
+// Schema definitions for validation
+
+/**
+ * Schema for HAST text node.
+ *
+ * @category Schemas
+ */
+export const HastTextSchema: Schema.Schema<HastText> = Schema.Struct({
+  _tag: Schema.Literal("text"),
+  value: Schema.String
+})
+
+/**
+ * Schema for HAST comment node.
+ *
+ * @category Schemas
+ */
+export const HastCommentSchema: Schema.Schema<HastComment> = Schema.Struct({
+  _tag: Schema.Literal("comment"),
+  value: Schema.String
+})
+
+/**
+ * Schema for HAST doctype node.
+ *
+ * @category Schemas
+ */
+export const HastDoctypeSchema: Schema.Schema<HastDoctype> = Schema.Struct({
+  _tag: Schema.Literal("doctype")
+})
+
+/**
+ * Schema for HAST properties.
+ *
+ * @category Schemas
+ */
+export const HastPropertiesSchema = Schema.Record({
+  key: Schema.String,
+  value: Schema.Unknown
+})
+
+// Forward reference for recursive schema
+const HastNodeSchemaLazy: Schema.Schema<HastNode> = Schema.suspend(() => HastNodeSchema)
+
+/**
+ * Schema for HAST element node.
+ *
+ * @category Schemas
+ */
+export const HastElementSchema: Schema.Schema<HastElement> = Schema.Struct({
+  _tag: Schema.Literal("element"),
+  tagName: Schema.String,
+  properties: HastPropertiesSchema,
+  children: Schema.Array(HastNodeSchemaLazy)
+})
+
+/**
+ * Schema for HAST node union.
+ *
+ * @category Schemas
+ */
+export const HastNodeSchema: Schema.Schema<HastNode> = Schema.Union(
+  HastTextSchema,
+  HastElementSchema,
+  HastCommentSchema,
+  HastDoctypeSchema
+)
+
+/**
+ * Schema for HAST root.
+ *
+ * @category Schemas
+ */
+export const HastRootSchema: Schema.Schema<HastRoot> = Schema.Struct({
+  _tag: Schema.Literal("root"),
+  children: Schema.Array(HastNodeSchema)
+})

package/src/schemas/hast/index.ts

@@ -0,0 +1,35 @@
+/**
+ * HAST (Hypertext Abstract Syntax Tree) schemas.
+ *
+ * @module
+ */
+export type {
+  HastComment,
+  HastDoctype,
+  HastElement,
+  HastNode,
+  HastProperties,
+  HastRoot,
+  HastText
+} from "./HastSchema.js"
+
+export {
+  getTextContent,
+  HastCommentSchema,
+  HastDoctypeSchema,
+  HastElementSchema,
+  HastNodeSchema,
+  HastPropertiesSchema,
+  HastRootSchema,
+  HastTextSchema,
+  isHastComment,
+  isHastElement,
+  isHastText,
+  makeHastComment,
+  makeHastDoctype,
+  makeHastElement,
+  makeHastRoot,
+  makeHastText
+} from "./HastSchema.js"
+
+export { HastFromHtml } from "./HastFromHtml.js"

package/src/schemas/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Bi-directional schemas for AST transformations.
+ *
+ * @module
+ */
+
+export { DocumentFromConfluence } from "./ConfluenceSchema.js"
+export { ConfluenceToMarkdown, DocumentFromHast, DocumentFromMdast } from "./ConversionSchema.js"
+export { DocumentFromMarkdown } from "./MarkdownSchema.js"
+
+// Re-export node schemas
+export * from "./nodes/index.js"
+
+// Re-export preprocessing
+export { PreprocessedHtmlFromConfluence } from "./preprocessing/index.js"
+export type { PreprocessedHtml } from "./preprocessing/index.js"
+
+// Re-export HAST/MDAST types and schemas
+export * from "./hast/index.js"
+export * from "./mdast/index.js"

package/src/schemas/mdast/MdastFromMarkdown.ts

@@ -0,0 +1,118 @@
+/**
+ * Schema transformation from Markdown string to MDAST (Markdown Abstract Syntax Tree).
+ *
+ * Uses remark-parse for Markdown 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 remarkGfm from "remark-gfm"
+import remarkParse from "remark-parse"
+import remarkStringify from "remark-stringify"
+import { unified } from "unified"
+import type { MdastRoot } from "./MdastSchema.js"
+import { makeMdastRoot, MdastRootSchema } from "./MdastSchema.js"
+
+// Unist/Mdast types from remark-parse (simplified)
+interface UnistNode {
+  type: string
+  value?: string
+  depth?: number
+  lang?: string
+  url?: string
+  title?: string | null
+  alt?: string | null
+  ordered?: boolean
+  start?: number
+  checked?: boolean | null
+  children?: Array<UnistNode>
+}
+
+interface UnistRoot {
+  type: "root"
+  children: Array<UnistNode>
+}
+
+/**
+ * Convert unist node from remark-parse to our MdastNode type.
+ * For now, we pass through the structure since MdastNode types match unist closely.
+ */
+const convertToMdastRoot = (root: UnistRoot): MdastRoot =>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  makeMdastRoot(root.children as any)
+
+/**
+ * Convert our MdastRoot type back to unist format for serialization.
+ */
+const convertFromMdastRoot = (root: MdastRoot): UnistRoot => ({
+  type: "root",
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  children: root.children as any
+})
+
+/**
+ * Transform Markdown string to MDAST root.
+ *
+ * Uses remark-parse to parse Markdown and converts the result to our schema types.
+ * Supports bidirectional transformation (decode Markdown -> MDAST, encode MDAST -> Markdown).
+ *
+ * @example
+ * ```typescript
+ * import { MdastFromMarkdown } from "@knpkv/confluence-to-markdown/schemas/mdast"
+ * import * as Schema from "effect/Schema"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const mdast = yield* Schema.decode(MdastFromMarkdown)("# Hello\n\nWorld")
+ *   console.log(mdast.children.length) // 2
+ *   console.log(mdast.children[0].type) // "heading"
+ * })
+ *
+ * Effect.runPromise(program)
+ * ```
+ *
+ * @category Mdast
+ */
+export const MdastFromMarkdown = Schema.transformOrFail(
+  Schema.String,
+  MdastRootSchema,
+  {
+    strict: true,
+    decode: (markdown, _options, ast) =>
+      Effect.try({
+        try: () => {
+          const result = unified()
+            .use(remarkParse)
+            .use(remarkGfm)
+            .parse(markdown) as UnistRoot
+          return convertToMdastRoot(result)
+        },
+        catch: (error) =>
+          new ParseResult.Type(
+            ast,
+            markdown,
+            `Markdown parse error: ${error instanceof Error ? error.message : String(error)}`
+          )
+      }),
+    encode: (mdast, _options, ast) =>
+      Effect.try({
+        try: () => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const unist = convertFromMdastRoot(mdast as any)
+          return unified()
+            .use(remarkGfm)
+            .use(remarkStringify, { bullet: "-", emphasis: "_" })
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .stringify(unist as any)
+        },
+        catch: (error) =>
+          new ParseResult.Type(
+            ast,
+            mdast,
+            `Markdown stringify error: ${error instanceof Error ? error.message : String(error)}`
+          )
+      })
+  }
+)