@knpkv/confluence-to-markdown 0.5.0 → 0.6.0

package/test/AdfWalker.test.ts

@@ -0,0 +1,530 @@
+import type { DocNode } from "@atlaskit/adf-schema"
+import { describe, expect, it } from "vitest"
+import { walk } from "../src/AdfWalker.js"
+
+const doc = (content: ReadonlyArray<unknown>): DocNode => ({ version: 1, type: "doc", content } as unknown as DocNode)
+
+// Expected `attrs=` blob: base64 of the attrs JSON with keys sorted (write
+// the literal in sorted key order so JSON.stringify matches the walker).
+const b64 = (attrs: Record<string, unknown>): string => Buffer.from(JSON.stringify(attrs)).toString("base64")
+
+describe("AdfWalker", () => {
+  it("emits a heading at the right level", () => {
+    const r = walk(doc([{ type: "heading", attrs: { level: 3 }, content: [{ type: "text", text: "Hi" }] }]))
+    expect(r.markdown).toContain("### Hi")
+  })
+
+  it("escapes special characters in text", () => {
+    const r = walk(doc([{ type: "paragraph", content: [{ type: "text", text: "use *stars*" }] }]))
+    expect(r.markdown).toContain("\\*stars\\*")
+  })
+
+  it("does not escape characters that are only special at line-start or in link syntax", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "text", text: "a (b) c+ d! {e} #1 > #2" }]
+    }]))
+    expect(r.markdown).toContain("a (b) c+ d! {e} #1 > #2")
+  })
+
+  it("does not escape code-marked text", () => {
+    // Backslashes inside code spans are literal; escaping here made every
+    // pull/push round-trip double them (a\_b → a\\\_b → …).
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "text", text: "a_b (c*)", marks: [{ type: "code" }] }]
+    }]))
+    expect(r.markdown).toContain("`a_b (c*)`")
+  })
+
+  it("fences code spans containing backticks with a longer delimiter", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "text", text: "a `b` c", marks: [{ type: "code" }] }]
+    }]))
+    expect(r.markdown).toContain("``a `b` c``")
+  })
+
+  it("space-pads code spans that start or end with a backtick", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "text", text: "`tick", marks: [{ type: "code" }] }]
+    }]))
+    expect(r.markdown).toContain("`` `tick ``")
+  })
+
+  it("renders inline marks", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [
+        { type: "text", text: "a", marks: [{ type: "strong" }] },
+        { type: "text", text: "b", marks: [{ type: "em" }] },
+        { type: "text", text: "c", marks: [{ type: "code" }] },
+        { type: "text", text: "d", marks: [{ type: "strike" }] }
+      ]
+    }]))
+    expect(r.markdown).toContain("**a**")
+    expect(r.markdown).toContain("_b_")
+    expect(r.markdown).toContain("`c`")
+    expect(r.markdown).toContain("~~d~~")
+  })
+
+  it("renders a link with title", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{
+        type: "text",
+        text: "go",
+        marks: [{ type: "link", attrs: { href: "https://x.test", title: "T" } }]
+      }]
+    }]))
+    expect(r.markdown).toContain(`[go](https://x.test "T")`)
+  })
+
+  it("falls back lossy marks to HTML and warns", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "text", text: "U", marks: [{ type: "underline" }] }]
+    }]))
+    expect(r.markdown).toContain("<u>U</u>")
+    expect(r.warnings.some((w) => w._tag === "LossyMark" && w.mark === "underline")).toBe(true)
+  })
+
+  it("renders nested bullet lists", () => {
+    const r = walk(doc([{
+      type: "bulletList",
+      content: [{
+        type: "listItem",
+        content: [
+          { type: "paragraph", content: [{ type: "text", text: "outer" }] },
+          {
+            type: "bulletList",
+            content: [{
+              type: "listItem",
+              content: [{ type: "paragraph", content: [{ type: "text", text: "inner" }] }]
+            }]
+          }
+        ]
+      }]
+    }]))
+    expect(r.markdown).toContain("- outer")
+    expect(r.markdown).toContain("inner")
+  })
+
+  it("renders ordered lists with attrs.order", () => {
+    const r = walk(doc([{
+      type: "orderedList",
+      attrs: { order: 5 },
+      content: [{
+        type: "listItem",
+        content: [{ type: "paragraph", content: [{ type: "text", text: "first" }] }]
+      }]
+    }]))
+    expect(r.markdown).toContain("5. first")
+  })
+
+  it("renders a code block with language", () => {
+    const r = walk(doc([{
+      type: "codeBlock",
+      attrs: { language: "ts" },
+      content: [{ type: "text", text: "const x = 1" }]
+    }]))
+    expect(r.markdown).toContain("```ts")
+    expect(r.markdown).toContain("const x = 1")
+    expect(r.markdown).toContain("```")
+  })
+
+  it("renders a table with header row", () => {
+    const r = walk(doc([{
+      type: "table",
+      content: [
+        {
+          type: "tableRow",
+          content: [
+            { type: "tableHeader", content: [{ type: "paragraph", content: [{ type: "text", text: "A" }] }] },
+            { type: "tableHeader", content: [{ type: "paragraph", content: [{ type: "text", text: "B" }] }] }
+          ]
+        },
+        {
+          type: "tableRow",
+          content: [
+            { type: "tableCell", content: [{ type: "paragraph", content: [{ type: "text", text: "1" }] }] },
+            { type: "tableCell", content: [{ type: "paragraph", content: [{ type: "text", text: "2" }] }] }
+          ]
+        }
+      ]
+    }]))
+    expect(r.markdown).toContain("| A | B |")
+    expect(r.markdown).toContain("| --- | --- |")
+    expect(r.markdown).toContain("| 1 | 2 |")
+  })
+
+  it("renders a panel as a GitHub admonition", () => {
+    const r = walk(doc([{
+      type: "panel",
+      attrs: { panelType: "warning" },
+      content: [{ type: "paragraph", content: [{ type: "text", text: "be careful" }] }]
+    }]))
+    expect(r.markdown).toContain("[!WARNING]")
+    expect(r.markdown).toContain("be careful")
+  })
+
+  it("renders task lists with checkbox state", () => {
+    const r = walk(doc([{
+      type: "taskList",
+      content: [
+        {
+          type: "taskItem",
+          attrs: { state: "DONE" },
+          content: [{ type: "text", text: "done" }]
+        },
+        {
+          type: "taskItem",
+          attrs: { state: "TODO" },
+          content: [{ type: "text", text: "todo" }]
+        }
+      ]
+    }]))
+    expect(r.markdown).toContain("- [x] done")
+    expect(r.markdown).toContain("- [ ] todo")
+  })
+
+  it("renders every child of a mediaGroup", () => {
+    const r = walk(doc([{
+      type: "mediaGroup",
+      content: [
+        { type: "media", attrs: { id: "m1", alt: "first", url: "https://x.test/1.png" } },
+        { type: "media", attrs: { id: "m2", alt: "second", url: "https://x.test/2.png" } },
+        { type: "media", attrs: { id: "m3" } }
+      ]
+    }]))
+    expect(r.markdown).toContain("![first](https://x.test/1.png)")
+    expect(r.markdown).toContain("![second](https://x.test/2.png)")
+    expect(r.markdown).toContain("<!-- adf:media id=m3 -->")
+    expect(r.warnings.some((w) => w._tag === "MediaWithoutUrl" && w.mediaId === "m3")).toBe(true)
+  })
+
+  it("emits placeholders + warnings for unknown nodes", () => {
+    const r = walk(doc([{ type: "totallyMadeUp" }]))
+    expect(r.markdown).toContain("<!-- unsupported ADF node: totallyMadeUp -->")
+    expect(r.warnings.some((w) => w._tag === "UnsupportedNode")).toBe(true)
+  })
+
+  it("does not double the @ on mentions whose text already starts with @", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "mention", attrs: { id: "557057:abc", text: "@Andrey Konopkov" } }]
+    }]))
+    expect(r.markdown).toContain("@Andrey Konopkov")
+    expect(r.markdown).not.toContain("@@")
+  })
+
+  it("encodes the mention accountId in a custom-scheme link", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "mention", attrs: { id: "557057:abc-123", text: "@Andrey Konopkov" } }]
+    }]))
+    // ":" gets percent-encoded by encodeURIComponent so the URL is unambiguous.
+    expect(r.markdown).toContain("[@Andrey Konopkov](confluence-mention://557057%3Aabc-123)")
+  })
+
+  it("falls back to plain @text when the mention has no id", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{ type: "mention", attrs: { text: "@Anon" } }]
+    }]))
+    expect(r.markdown).toContain("@Anon")
+    expect(r.markdown).not.toContain("confluence-mention")
+  })
+
+  it("preserves the full attrs (parameters included) in the extension placeholder", () => {
+    const r = walk(doc([{
+      type: "extension",
+      attrs: {
+        extensionType: "com.atlassian.confluence.macro.core",
+        extensionKey: "toc",
+        parameters: { macroParams: { maxLevel: { value: "3" } } }
+      }
+    }]))
+    const attrs = b64({
+      extensionKey: "toc",
+      extensionType: "com.atlassian.confluence.macro.core",
+      parameters: { macroParams: { maxLevel: { value: "3" } } }
+    })
+    expect(r.markdown).toContain(
+      `<!-- adf:extension key=toc type=com.atlassian.confluence.macro.core attrs=${attrs} -->`
+    )
+    expect(
+      r.warnings.some((w) =>
+        w._tag === "UnsupportedExtension" && w.extensionKey === "toc" && w.nodeType === "extension"
+      )
+    ).toBe(true)
+  })
+
+  it("emits the same attrs blob regardless of source key order", () => {
+    const a = walk(doc([{ type: "extension", attrs: { extensionKey: "toc", extensionType: "t" } }]))
+    const b = walk(doc([{ type: "extension", attrs: { extensionType: "t", extensionKey: "toc" } }]))
+    expect(a.markdown).toBe(b.markdown)
+  })
+
+  it("handles inline and bodied extensions", () => {
+    const r = walk(doc([
+      {
+        type: "paragraph",
+        content: [
+          { type: "text", text: "before " },
+          { type: "inlineExtension", attrs: { extensionKey: "jira-issue", extensionType: "com.example" } },
+          { type: "text", text: " after" }
+        ]
+      },
+      {
+        type: "bodiedExtension",
+        attrs: { extensionKey: "details", extensionType: "com.example" },
+        content: [{ type: "paragraph", content: [{ type: "text", text: "body" }] }]
+      }
+    ]))
+    const inlineAttrs = b64({ extensionKey: "jira-issue", extensionType: "com.example" })
+    const bodiedAttrs = b64({ extensionKey: "details", extensionType: "com.example" })
+    expect(r.markdown).toContain(
+      `<!-- adf:inlineExtension key=jira-issue type=com.example attrs=${inlineAttrs} -->`
+    )
+    // The bodied extension renders its body between an open and an end marker
+    // so the push side can re-attach it.
+    expect(r.markdown).toContain(
+      `<!-- adf:bodiedExtension key=details type=com.example attrs=${bodiedAttrs} -->\n\nbody\n\n<!-- adf:/bodiedExtension -->`
+    )
+    expect(r.warnings.filter((w) => w._tag === "UnsupportedExtension")).toHaveLength(2)
+  })
+
+  it("emits the end marker even for an empty bodied extension", () => {
+    // Without it the push side cannot tell "bodied macro with empty body"
+    // apart from a legacy/corrupted open marker, and would change node type.
+    const r = walk(doc([{
+      type: "bodiedExtension",
+      attrs: { extensionKey: "excerpt", extensionType: "com.example" },
+      content: [{ type: "paragraph", content: [] }]
+    }]))
+    expect(r.markdown).toContain("<!-- adf:/bodiedExtension -->")
+  })
+
+  it("emits only the single-line marker for a bodied extension inside a table cell", () => {
+    // <br>-flattened multi-block emission cannot be reverted on push; the
+    // bare marker at least comes back as a clean extension node.
+    const r = walk(doc([{
+      type: "table",
+      content: [{
+        type: "tableRow",
+        content: [{
+          type: "tableCell",
+          content: [{
+            type: "bodiedExtension",
+            attrs: { extensionKey: "details", extensionType: "com.example" },
+            content: [{ type: "paragraph", content: [{ type: "text", text: "body" }] }]
+          }]
+        }]
+      }]
+    }]))
+    expect(r.markdown).not.toContain("adf:/bodiedExtension")
+    expect(r.markdown).not.toContain("body")
+    expect(r.markdown).toContain("<!-- adf:bodiedExtension key=details type=com.example")
+  })
+
+  it("escapes a pipe in a table cell exactly once", () => {
+    const cell = (content: ReadonlyArray<unknown>) => ({
+      type: "tableCell",
+      content: [{ type: "paragraph", content }]
+    })
+    const r = walk(doc([{
+      type: "table",
+      content: [{
+        type: "tableRow",
+        content: [
+          cell([{ type: "text", text: "a|b" }]),
+          // Code spans skip escapeText, so this pipe is only caught by the
+          // table-cell pass — both cells must end up single-escaped.
+          cell([{ type: "text", text: "x|y", marks: [{ type: "code" }] }])
+        ]
+      }]
+    }]))
+    expect(r.markdown).toContain("a\\|b")
+    expect(r.markdown).not.toContain("a\\\\|b")
+    expect(r.markdown).toContain("`x\\|y`")
+  })
+
+  it("renders a mediaSingle caption as an italic line under the media", () => {
+    const r = walk(doc([{
+      type: "mediaSingle",
+      content: [
+        { type: "media", attrs: { id: "m1", alt: "diagram", url: "https://x.test/d.png" } },
+        { type: "caption", content: [{ type: "text", text: "Figure 1" }] }
+      ]
+    }]))
+    expect(r.markdown).toContain("![diagram](https://x.test/d.png)\n_Figure 1_")
+  })
+
+  it("backslash-escapes nestedExpand titles inside table cells (inline HTML context)", () => {
+    const r = walk(doc([{
+      type: "table",
+      content: [{
+        type: "tableRow",
+        content: [{
+          type: "tableCell",
+          content: [{
+            type: "nestedExpand",
+            attrs: { title: "v2 *beta*" },
+            content: [{ type: "paragraph", content: [{ type: "text", text: "inner" }] }]
+          }]
+        }]
+      }]
+    }]))
+    expect(r.markdown).toContain("<summary>v2 \\*beta\\*</summary>")
+  })
+
+  it("entity-escapes expand titles instead of backslash-escaping them", () => {
+    const r = walk(doc([{
+      type: "expand",
+      attrs: { title: `v2 *beta* <a href="x">` },
+      content: [{ type: "paragraph", content: [{ type: "text", text: "inner" }] }]
+    }]))
+    expect(r.markdown).toContain(`<summary>v2 *beta* &lt;a href=&quot;x&quot;&gt;</summary>`)
+    expect(r.markdown).not.toContain("\\*beta\\*")
+  })
+
+  it("lengthens the code-block fence when the code contains backtick runs", () => {
+    const r = walk(doc([{
+      type: "codeBlock",
+      attrs: { language: "md" },
+      content: [{ type: "text", text: "```js\ncode\n```" }]
+    }]))
+    expect(r.markdown).toContain("````md\n```js\ncode\n```\n````")
+  })
+
+  it("sanitizes media alt text and wraps unsafe media urls", () => {
+    // Brackets are substituted, not backslash-escaped: @atlaskit's media
+    // markdown plugin throws on `\[` in alt, which would make pushes fail.
+    const r = walk(doc([{
+      type: "mediaSingle",
+      content: [{
+        type: "media",
+        attrs: { id: "m1", alt: "a [b]\nc", url: "https://x.test/a (1).png" }
+      }]
+    }]))
+    expect(r.markdown).toContain("![a (b) c](<https://x.test/a (1).png>)")
+  })
+
+  it("percent-encodes wrapper-breaking characters in unsafe urls", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [{
+        type: "text",
+        text: "go",
+        marks: [{ type: "link", attrs: { href: "https://x.test/a b<c>d\\e" } }]
+      }]
+    }]))
+    expect(r.markdown).toContain("[go](<https://x.test/a b%3Cc%3Ed%5Ce>)")
+  })
+
+  it("escapes block markers at line start so text cannot become structure", () => {
+    const r = walk(doc([
+      { type: "paragraph", content: [{ type: "text", text: "# not a heading" }] },
+      { type: "paragraph", content: [{ type: "text", text: "> not a quote" }] },
+      { type: "paragraph", content: [{ type: "text", text: "+ not a list" }] },
+      { type: "paragraph", content: [{ type: "text", text: "1. not a list" }] },
+      {
+        type: "paragraph",
+        content: [
+          { type: "text", text: "a" },
+          { type: "hardBreak" },
+          { type: "text", text: "# b stays text" }
+        ]
+      }
+    ]))
+    expect(r.markdown).toContain("\\# not a heading")
+    expect(r.markdown).toContain("\\> not a quote")
+    expect(r.markdown).toContain("\\+ not a list")
+    expect(r.markdown).toContain("1\\. not a list")
+    expect(r.markdown).toContain("\\# b stays text")
+  })
+
+  it("does not escape mid-line hashes or list-like text after the first word", () => {
+    const r = walk(doc([{ type: "paragraph", content: [{ type: "text", text: "a #1 > #2 + b" }] }]))
+    expect(r.markdown).toContain("a #1 > #2 + b")
+  })
+
+  it("strips backticks and whitespace from the code-block language", () => {
+    const r = walk(doc([{
+      type: "codeBlock",
+      attrs: { language: "c`x\ninjected" },
+      content: [{ type: "text", text: "hello" }]
+    }]))
+    expect(r.markdown).toContain("```cxinjected\nhello\n```")
+  })
+
+  it("warns when an inlineCard has no url to render", () => {
+    const r = walk(doc([{
+      type: "paragraph",
+      content: [
+        { type: "text", text: "before " },
+        { type: "inlineCard", attrs: { data: { url: "https://hidden.test" } } },
+        { type: "text", text: " after" }
+      ]
+    }]))
+    expect(r.warnings.some((w) => w._tag === "UnsupportedNode" && w.nodeType === "inlineCard")).toBe(true)
+  })
+
+  it("does not double-wrap an em-marked caption", () => {
+    const r = walk(doc([{
+      type: "mediaSingle",
+      content: [
+        { type: "media", attrs: { id: "m1", url: "https://x.test/d.png" } },
+        { type: "caption", content: [{ type: "text", text: "a caption", marks: [{ type: "em" }] }] }
+      ]
+    }]))
+    expect(r.markdown).toContain("_a caption_")
+    expect(r.markdown).not.toContain("__a caption__")
+  })
+
+  it("omits the caption line when the caption is only whitespace", () => {
+    const r = walk(doc([{
+      type: "mediaSingle",
+      content: [
+        { type: "media", attrs: { id: "m1", url: "https://x.test/d.png" } },
+        { type: "caption", content: [{ type: "text", text: "   " }] }
+      ]
+    }]))
+    expect(r.markdown).toContain("![](https://x.test/d.png)")
+    expect(r.markdown).not.toContain("_")
+  })
+
+  it("never renders a caption as the media when the media child is missing", () => {
+    const r = walk(doc([{
+      type: "mediaSingle",
+      content: [{ type: "caption", content: [{ type: "text", text: "orphan" }] }]
+    }]))
+    expect(r.markdown).toContain("<!-- adf:media id= -->")
+    expect(r.markdown).toContain("_orphan_")
+  })
+
+  it("maps note panels to IMPORTANT and success panels to TIP", () => {
+    const r = walk(doc([
+      {
+        type: "panel",
+        attrs: { panelType: "note" },
+        content: [{ type: "paragraph", content: [{ type: "text", text: "n" }] }]
+      },
+      {
+        type: "panel",
+        attrs: { panelType: "success" },
+        content: [{ type: "paragraph", content: [{ type: "text", text: "s" }] }]
+      }
+    ]))
+    expect(r.markdown).toContain("[!IMPORTANT]")
+    expect(r.markdown).toContain("[!TIP]")
+  })
+
+  it("ends output with exactly one newline", () => {
+    const r = walk(doc([{ type: "paragraph", content: [{ type: "text", text: "x" }] }]))
+    expect(r.markdown.endsWith("\n")).toBe(true)
+    expect(r.markdown.endsWith("\n\n")).toBe(false)
+  })
+})

package/test/AtlaskitTransformers.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import { AtlaskitTransformers, layer as AtlaskitTransformersLayer } from "../src/AtlaskitTransformers.js"
+
+describe("AtlaskitTransformers", () => {
+  it.effect("encodes markdown to ADF JSON", () =>
+    Effect.gen(function*() {
+      const t = yield* AtlaskitTransformers
+      const adf = yield* t.use(({ json, md }) => json.encode(md.parse("# Hello")))
+      expect(adf.type).toBe("doc")
+      expect(adf.content[0]?.type).toBe("heading")
+    }).pipe(Effect.provide(AtlaskitTransformersLayer)))
+
+  it.effect("surfaces synchronous throws as AtlaskitTransformersError", () =>
+    Effect.gen(function*() {
+      const t = yield* AtlaskitTransformers
+      const result = yield* Effect.either(t.use(() => {
+        throw new Error("boom")
+      }))
+      expect(result._tag).toBe("Left")
+      if (result._tag === "Left") {
+        expect(result.left._tag).toBe("AtlaskitTransformersError")
+      }
+    }).pipe(Effect.provide(AtlaskitTransformersLayer)))
+})