atl-fetch 1.1.0 → 1.2.0

package/dist/services/fetch/fetch-service.js

@@ -3,7 +3,7 @@ import { fetchConfluencePage } from '../confluence/confluence-service.js';
 import { fetchJiraIssue } from '../jira/jira-service.js';
 import { formatConfluencePage, formatJiraIssue, writeToFile } from '../output/output-service.js';
 import { saveConfluencePage, saveConfluenceVersions, saveJiraIssue } from '../storage/storage-service.js';
-import { convertAdfToPlainText, convertStorageFormatToPlainText } from '../text-converter/text-converter.js';
+import { convertStorageFormatToPlainText } from '../text-converter/text-converter.js';
 import { parseUrl } from '../url-parser/url-parser.js';
 /**
  * Jira エラーを FetchError に変換する
@@ -230,15 +230,14 @@ export async function fetchAndSave(url, options) {
             return err(mapJiraErrorToFetchError(issueResult.error));
         }
         const issue = issueResult.value;
-        // ADF をプレーンテキストに変換
-        const descriptionPlainText = issue.description !== null ? convertAdfToPlainText(issue.description) : null;
         // Jira Issue をディレクトリ構造で保存
+        // description は ADF 形式で保存、descriptionPlainText は後方互換性のため維持
         const saveResult = await saveJiraIssue({
             attachments: issue.attachments,
             changelog: issue.changelog,
             comments: issue.comments,
-            description: issue.description,
-            descriptionPlainText,
+            description: issue.descriptionAdf,
+            descriptionPlainText: issue.description,
             key: issue.key,
             summary: issue.summary,
         }, {

package/dist/services/jira/jira-service.js

@@ -108,6 +108,7 @@ function mapApiCommentToJiraComment(apiComment) {
     return {
         author: apiComment.author.displayName,
         body: extractTextFromAdf(apiComment.body),
+        bodyAdf: apiComment.body,
         created: apiComment.created,
         id: apiComment.id,
         updated: apiComment.updated,
@@ -254,6 +255,7 @@ export async function fetchJiraIssue(organization, issueKey) {
         changelog: (apiResponse.changelog?.histories ?? []).map(mapApiChangelogEntryToJiraChangelogEntry),
         comments: (apiResponse.fields.comment?.comments ?? []).map(mapApiCommentToJiraComment),
         description: apiResponse.fields.description ? extractTextFromAdf(apiResponse.fields.description) : null,
+        descriptionAdf: apiResponse.fields.description,
         key: apiResponse.key,
         summary: apiResponse.fields.summary,
     };

package/dist/services/storage/storage-service.d.ts

@@ -16,9 +16,11 @@ import type { ConfluenceSaveData, ConfluenceSaveResult, ConfluenceStorageOptions
  * ├── manifest.json          # 取得メタデータ
  * ├── issue.json             # Issue 全データ（JSON 形式）
  * ├── description.txt        # 説明文のプレーンテキスト
- * ├── content.md             # Markdown 形式
- * ├── changelog.json         # 変更履歴
- * ├── comments.json          # コメント一覧
+ * ├── content.md             # Markdown 形式（Description + Attachments）
+ * ├── comments.md            # コメント一覧（Markdown 形式）
+ * ├── changelog.md           # 変更履歴（Markdown 形式）
+ * ├── changelog.json         # 変更履歴（JSON 形式）
+ * ├── comments.json          # コメント一覧（JSON 形式）
  * ├── attachments.json       # 添付ファイル一覧メタデータ
  * └── attachments/           # 添付ファイル実体
  *     └── {id}_{filename}

package/dist/services/storage/storage-service.js

@@ -10,7 +10,7 @@ import { ensureDir, writeFileContent } from '../../ports/file/file-port.js';
 import { downloadConfluenceAttachment } from '../confluence/confluence-service.js';
 import { diffText } from '../diff/diff-service.js';
 import { downloadJiraAttachment } from '../jira/jira-service.js';
-import { convertStorageFormatToMarkdown } from '../text-converter/text-converter.js';
+import { convertAdfToMarkdown, convertStorageFormatToMarkdown } from '../text-converter/text-converter.js';
 /**
  * 現在時刻を ISO 8601 形式で取得する
  *
@@ -51,9 +51,11 @@ const createJiraManifest = (data, options, attachmentResults) => {
  * ├── manifest.json          # 取得メタデータ
  * ├── issue.json             # Issue 全データ（JSON 形式）
  * ├── description.txt        # 説明文のプレーンテキスト
- * ├── content.md             # Markdown 形式
- * ├── changelog.json         # 変更履歴
- * ├── comments.json          # コメント一覧
+ * ├── content.md             # Markdown 形式（Description + Attachments）
+ * ├── comments.md            # コメント一覧（Markdown 形式）
+ * ├── changelog.md           # 変更履歴（Markdown 形式）
+ * ├── changelog.json         # 変更履歴（JSON 形式）
+ * ├── comments.json          # コメント一覧（JSON 形式）
  * ├── attachments.json       # 添付ファイル一覧メタデータ
  * └── attachments/           # 添付ファイル実体
  *     └── {id}_{filename}
@@ -150,7 +152,7 @@ export const saveJiraIssue = async (data, options) => {
             path: descPath,
         });
     }
-    // content.md を保存（Markdown 形式）
+    // content.md を保存（Markdown 形式：Description + Attachments）
     const markdownContent = formatJiraIssueAsMarkdown(data, attachmentResults);
     const markdownPath = join(issueDir, 'content.md');
     const markdownWriteResult = await writeFileContent(markdownPath, markdownContent);
@@ -161,6 +163,28 @@ export const saveJiraIssue = async (data, options) => {
             path: markdownPath,
         });
     }
+    // comments.md を保存（Markdown 形式）
+    const commentsMarkdownContent = formatCommentsAsMarkdown(data, attachmentResults);
+    const commentsMarkdownPath = join(issueDir, 'comments.md');
+    const commentsMarkdownWriteResult = await writeFileContent(commentsMarkdownPath, commentsMarkdownContent);
+    if (commentsMarkdownWriteResult.isErr()) {
+        return err({
+            kind: 'FILE_WRITE_FAILED',
+            message: `comments.md の書き込みに失敗しました: ${commentsMarkdownWriteResult.error.message}`,
+            path: commentsMarkdownPath,
+        });
+    }
+    // changelog.md を保存（Markdown 形式）
+    const changelogMarkdownContent = formatChangelogAsMarkdown(data);
+    const changelogMarkdownPath = join(issueDir, 'changelog.md');
+    const changelogMarkdownWriteResult = await writeFileContent(changelogMarkdownPath, changelogMarkdownContent);
+    if (changelogMarkdownWriteResult.isErr()) {
+        return err({
+            kind: 'FILE_WRITE_FAILED',
+            message: `changelog.md の書き込みに失敗しました: ${changelogMarkdownWriteResult.error.message}`,
+            path: changelogMarkdownPath,
+        });
+    }
     // changelog.json を保存
     const changelogPath = join(issueDir, 'changelog.json');
     const changelogWriteResult = await writeFileContent(changelogPath, JSON.stringify(data.changelog, null, 2));
@@ -199,54 +223,38 @@ export const saveJiraIssue = async (data, options) => {
 /**
  * Jira Issue を Markdown 形式にフォーマットする（ファイル保存用）
  *
+ * ADF (Atlassian Document Format) を Markdown に変換して保存する。
+ * Confluence と同様に構造を保持した Markdown を生成する。
+ *
  * @param data 保存データ
  * @param attachmentResults 添付ファイルのダウンロード結果
  * @returns Markdown 文字列
  */
 const formatJiraIssueAsMarkdown = (data, attachmentResults) => {
+    // 添付ファイル ID → savedPath のマッピングを生成
+    const attachmentPaths = {};
+    for (const att of attachmentResults) {
+        if (att.status === 'success' && att.savedPath !== undefined) {
+            attachmentPaths[att.id] = att.savedPath;
+        }
+    }
     const lines = [];
     // Title
     lines.push(`# ${data.key}`);
     lines.push('');
     lines.push(`**${data.summary}**`);
     lines.push('');
-    // Description
+    // Description - ADF を Markdown に変換
     lines.push('## Description');
     lines.push('');
-    lines.push(data.descriptionPlainText ?? '(No description)');
-    lines.push('');
-    // Comments
-    lines.push('## Comments');
-    lines.push('');
-    if (data.comments.length === 0) {
-        lines.push('No comments');
+    if (data.description !== null && data.description !== undefined) {
+        const descriptionMarkdown = convertAdfToMarkdown(data.description, attachmentPaths);
+        lines.push(descriptionMarkdown || '(No description)');
     }
     else {
-        for (const comment of data.comments) {
-            lines.push(`### ${comment.author} (${comment.created})`);
-            lines.push('');
-            lines.push(comment.body);
-            lines.push('');
-        }
+        lines.push('(No description)');
     }
-    // Changelog
-    lines.push('## Changelog');
     lines.push('');
-    if (data.changelog.length === 0) {
-        lines.push('No changelog');
-    }
-    else {
-        for (const entry of data.changelog) {
-            lines.push(`### ${entry.author} (${entry.created})`);
-            lines.push('');
-            for (const item of entry.items) {
-                const from = item.fromString ?? '(empty)';
-                const to = item.toString ?? '(empty)';
-                lines.push(`- **${item.field}**: ${from} → ${to}`);
-            }
-            lines.push('');
-        }
-    }
     // Attachments
     lines.push('## Attachments');
     lines.push('');
@@ -272,6 +280,66 @@ const formatJiraIssueAsMarkdown = (data, attachmentResults) => {
     }
     return lines.join('\n');
 };
+/**
+ * Jira コメントを Markdown 形式にフォーマットする（ファイル保存用）
+ *
+ * @param data 保存データ
+ * @param attachmentResults 添付ファイルのダウンロード結果
+ * @returns Markdown 文字列
+ */
+const formatCommentsAsMarkdown = (data, attachmentResults) => {
+    // 添付ファイル ID → savedPath のマッピングを生成
+    const attachmentPaths = {};
+    for (const att of attachmentResults) {
+        if (att.status === 'success' && att.savedPath !== undefined) {
+            attachmentPaths[att.id] = att.savedPath;
+        }
+    }
+    const lines = [];
+    lines.push(`# ${data.key} - Comments`);
+    lines.push('');
+    if (data.comments.length === 0) {
+        lines.push('No comments');
+    }
+    else {
+        for (const comment of data.comments) {
+            lines.push(`## ${comment.author} (${comment.created})`);
+            lines.push('');
+            // コメント本文も ADF 形式なので Markdown に変換
+            const commentMarkdown = convertAdfToMarkdown(comment.bodyAdf, attachmentPaths);
+            lines.push(commentMarkdown || comment.body);
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+};
+/**
+ * Jira 変更履歴を Markdown 形式にフォーマットする（ファイル保存用）
+ *
+ * @param data 保存データ
+ * @returns Markdown 文字列
+ */
+const formatChangelogAsMarkdown = (data) => {
+    const lines = [];
+    lines.push(`# ${data.key} - Changelog`);
+    lines.push('');
+    if (data.changelog.length === 0) {
+        lines.push('No changelog');
+    }
+    else {
+        for (const entry of data.changelog) {
+            lines.push(`## ${entry.author} (${entry.created})`);
+            lines.push('');
+            for (const item of entry.items) {
+                const from = item.fromString ?? '(empty)';
+                const to = item.toString ?? '(empty)';
+                lines.push(`- **${item.field}**: ${from} → ${to}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+};
 /**
  * Confluence ページ用の Manifest を生成する
  *
@@ -735,4 +803,197 @@ if (import.meta.vitest) {
             });
         });
     });
+    describe('formatCommentsAsMarkdown (in-source testing)', () => {
+        // テストの目的: コメントがない場合に "No comments" が出力されること
+        it('Given: コメントがない JiraSaveData, When: formatCommentsAsMarkdown を呼び出す, Then: "No comments" が出力される', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-001',
+                summary: 'テスト',
+            };
+            const result = formatCommentsAsMarkdown(data, []);
+            expect(result).toContain('# TEST-001 - Comments');
+            expect(result).toContain('No comments');
+        });
+        // テストの目的: コメントが正しくフォーマットされること
+        it('Given: コメントを含む JiraSaveData, When: formatCommentsAsMarkdown を呼び出す, Then: コメントが Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [
+                    {
+                        author: 'TestUser',
+                        body: 'テストコメント',
+                        bodyAdf: null, // bodyAdf が null の場合は body が使用される
+                        created: '2024-01-15T10:30:00.000Z',
+                        id: 'cmt-1',
+                        updated: '2024-01-15T10:30:00.000Z',
+                    },
+                ],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-002',
+                summary: 'テスト',
+            };
+            const result = formatCommentsAsMarkdown(data, []);
+            expect(result).toContain('# TEST-002 - Comments');
+            expect(result).toContain('## TestUser');
+            expect(result).toContain('2024-01-15T10:30:00.000Z');
+            expect(result).toContain('テストコメント');
+        });
+        // テストの目的: 複数のコメントが正しくフォーマットされること
+        it('Given: 複数のコメントを含む JiraSaveData, When: formatCommentsAsMarkdown を呼び出す, Then: すべてのコメントが Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [
+                    {
+                        author: 'User1',
+                        body: 'コメント1',
+                        bodyAdf: null,
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cmt-1',
+                        updated: '2024-01-15T10:00:00.000Z',
+                    },
+                    {
+                        author: 'User2',
+                        body: 'コメント2',
+                        bodyAdf: null,
+                        created: '2024-01-16T11:00:00.000Z',
+                        id: 'cmt-2',
+                        updated: '2024-01-16T11:00:00.000Z',
+                    },
+                ],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-003',
+                summary: 'テスト',
+            };
+            const result = formatCommentsAsMarkdown(data, []);
+            expect(result).toContain('## User1');
+            expect(result).toContain('## User2');
+            expect(result).toContain('コメント1');
+            expect(result).toContain('コメント2');
+        });
+    });
+    describe('formatChangelogAsMarkdown (in-source testing)', () => {
+        // テストの目的: 変更履歴がない場合に "No changelog" が出力されること
+        it('Given: 変更履歴がない JiraSaveData, When: formatChangelogAsMarkdown を呼び出す, Then: "No changelog" が出力される', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-001',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('# TEST-001 - Changelog');
+            expect(result).toContain('No changelog');
+        });
+        // テストの目的: 変更履歴が正しくフォーマットされること
+        it('Given: 変更履歴を含む JiraSaveData, When: formatChangelogAsMarkdown を呼び出す, Then: 変更履歴が Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [{ field: 'status', fromString: 'Open', toString: 'In Progress' }],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-002',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('# TEST-002 - Changelog');
+            expect(result).toContain('## ChangeUser');
+            expect(result).toContain('2024-01-15T10:00:00.000Z');
+            expect(result).toContain('**status**');
+            expect(result).toContain('Open');
+            expect(result).toContain('In Progress');
+        });
+        // テストの目的: null 値が (empty) として表示されること
+        it('Given: fromString が null の変更履歴, When: formatChangelogAsMarkdown を呼び出す, Then: (empty) が表示される', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [{ field: 'assignee', fromString: null, toString: 'Developer' }],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-003',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('(empty)');
+            expect(result).toContain('Developer');
+        });
+        // テストの目的: toString が null の場合も (empty) として表示されること
+        it('Given: toString が null の変更履歴, When: formatChangelogAsMarkdown を呼び出す, Then: (empty) が表示される', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [{ field: 'assignee', fromString: 'Developer', toString: null }],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-004',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('Developer');
+            expect(result).toContain('(empty)');
+        });
+        // テストの目的: 複数の変更項目が正しくフォーマットされること
+        it('Given: 複数の変更項目を含む変更履歴, When: formatChangelogAsMarkdown を呼び出す, Then: すべての項目が Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [
+                            { field: 'status', fromString: 'Open', toString: 'In Progress' },
+                            { field: 'priority', fromString: 'Low', toString: 'High' },
+                        ],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-005',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('**status**');
+            expect(result).toContain('**priority**');
+            expect(result).toContain('Open');
+            expect(result).toContain('In Progress');
+            expect(result).toContain('Low');
+            expect(result).toContain('High');
+        });
+    });
 }

package/dist/services/text-converter/text-converter.d.ts

@@ -24,6 +24,14 @@ export declare const convertAdfToPlainText: (adf: unknown) => string;
  * @returns プレーンテキスト
  */
 export declare const convertStorageFormatToPlainText: (storageFormat: string | null | undefined) => string;
+/**
+ * ADF（Atlassian Document Format）を Markdown に変換する
+ *
+ * @param adf ADF ドキュメント（オブジェクトまたは JSON 文字列）
+ * @param attachmentPaths 添付ファイル ID → ローカルパスのマッピング
+ * @returns Markdown 文字列
+ */
+export declare const convertAdfToMarkdown: (adf: unknown, attachmentPaths?: AttachmentPathMapping) => string;
 /**
  * Confluence Storage Format（XHTML）を Markdown に変換する
  *

package/dist/services/text-converter/text-converter.js

@@ -135,6 +135,236 @@ export const convertAdfToPlainText = (adf) => {
     }
     return '';
 };
+// ============================================================
+// ADF → Markdown 変換（Confluence と同じ TurndownService を使用）
+// ============================================================
+/**
+ * HTML 特殊文字をエスケープする
+ *
+ * @param text エスケープ対象の文字列
+ * @returns エスケープ済み文字列
+ */
+const escapeHtml = (text) => {
+    return text
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+};
+/**
+ * ADF マークを HTML タグで囲む
+ *
+ * @param text 対象のテキスト
+ * @param marks 適用するマーク配列
+ * @returns マークを適用した HTML
+ */
+const applyMarksToHtml = (text, marks) => {
+    let result = text;
+    for (const mark of marks) {
+        switch (mark.type) {
+            case 'strong':
+                result = `<strong>${result}</strong>`;
+                break;
+            case 'em':
+                result = `<em>${result}</em>`;
+                break;
+            case 'code':
+                result = `<code>${result}</code>`;
+                break;
+            case 'strike':
+                result = `<s>${result}</s>`;
+                break;
+            case 'underline':
+                result = `<u>${result}</u>`;
+                break;
+            case 'link': {
+                const href = mark.attrs?.['href'];
+                if (typeof href === 'string') {
+                    result = `<a href="${escapeHtml(href)}">${result}</a>`;
+                }
+                break;
+            }
+            case 'textColor': {
+                const color = mark.attrs?.['color'];
+                if (typeof color === 'string') {
+                    result = `<span style="color: ${escapeHtml(color)}">${result}</span>`;
+                }
+                break;
+            }
+            case 'subsup': {
+                const subType = mark.attrs?.['type'];
+                if (subType === 'sub') {
+                    result = `<sub>${result}</sub>`;
+                }
+                else if (subType === 'sup') {
+                    result = `<sup>${result}</sup>`;
+                }
+                break;
+            }
+            // 未知のマークタイプは無視
+            default:
+                break;
+        }
+    }
+    return result;
+};
+/**
+ * ADF ノードを HTML に変換する
+ *
+ * @param node ADF ノード
+ * @param attachmentPaths 添付ファイル ID → ローカルパスのマッピング
+ * @returns HTML 文字列
+ */
+const convertAdfNodeToHtml = (node, attachmentPaths) => {
+    // テキストノードの場合
+    if (node.type === 'text' && node.text !== undefined) {
+        const escapedText = escapeHtml(node.text);
+        if (node.marks !== undefined && node.marks.length > 0) {
+            return applyMarksToHtml(escapedText, node.marks);
+        }
+        return escapedText;
+    }
+    // hardBreak の場合
+    if (node.type === 'hardBreak') {
+        return '<br>';
+    }
+    // rule（水平線）の場合
+    if (node.type === 'rule') {
+        return '<hr>';
+    }
+    // メンションの場合
+    if (node.type === 'mention' && node.attrs !== undefined) {
+        const text = node.attrs['text'];
+        if (typeof text === 'string') {
+            return escapeHtml(text);
+        }
+        return '@ユーザー';
+    }
+    // 絵文字の場合
+    if (node.type === 'emoji' && node.attrs !== undefined) {
+        const text = node.attrs['text'];
+        const shortName = node.attrs['shortName'];
+        if (typeof text === 'string') {
+            return text;
+        }
+        if (typeof shortName === 'string') {
+            return shortName;
+        }
+        return '';
+    }
+    // media ノードの場合（添付ファイル）
+    if (node.type === 'media' && node.attrs !== undefined) {
+        const mediaId = node.attrs['id'];
+        const mediaType = node.attrs['type'];
+        if (typeof mediaId === 'string' && attachmentPaths?.[mediaId] !== undefined) {
+            const localPath = attachmentPaths[mediaId];
+            const alt = typeof node.attrs['alt'] === 'string' ? node.attrs['alt'] : mediaId;
+            return `<img src="${escapeHtml(localPath)}" alt="${escapeHtml(alt)}">`;
+        }
+        // 外部リンクの場合
+        if (mediaType === 'external' || mediaType === 'link') {
+            const url = node.attrs['url'];
+            if (typeof url === 'string') {
+                return `<img src="${escapeHtml(url)}" alt="">`;
+            }
+        }
+        // マッピングがない場合はプレースホルダー
+        return '[添付ファイル]';
+    }
+    // mediaSingle（メディアコンテナ）の場合
+    if (node.type === 'mediaSingle' && node.content !== undefined) {
+        return node.content.map((child) => convertAdfNodeToHtml(child, attachmentPaths)).join('');
+    }
+    // mediaGroup の場合
+    if (node.type === 'mediaGroup' && node.content !== undefined) {
+        return node.content.map((child) => convertAdfNodeToHtml(child, attachmentPaths)).join('');
+    }
+    // inlineCard（インラインリンク）の場合
+    if (node.type === 'inlineCard' && node.attrs !== undefined) {
+        const url = node.attrs['url'];
+        if (typeof url === 'string') {
+            return `<a href="${escapeHtml(url)}">${escapeHtml(url)}</a>`;
+        }
+        return '';
+    }
+    // blockCard（ブロックリンク）の場合
+    if (node.type === 'blockCard' && node.attrs !== undefined) {
+        const url = node.attrs['url'];
+        if (typeof url === 'string') {
+            return `<p><a href="${escapeHtml(url)}">${escapeHtml(url)}</a></p>`;
+        }
+        return '';
+    }
+    // 子ノードがある場合
+    if (node.content !== undefined && Array.isArray(node.content)) {
+        const childrenHtml = node.content.map((child) => convertAdfNodeToHtml(child, attachmentPaths)).join('');
+        switch (node.type) {
+            case 'doc':
+                return childrenHtml;
+            case 'paragraph':
+                return `<p>${childrenHtml}</p>`;
+            case 'heading': {
+                const level = typeof node.attrs?.['level'] === 'number' ? node.attrs['level'] : 1;
+                const safeLevel = Math.max(1, Math.min(6, level));
+                return `<h${safeLevel}>${childrenHtml}</h${safeLevel}>`;
+            }
+            case 'bulletList':
+                return `<ul>${childrenHtml}</ul>`;
+            case 'orderedList':
+                return `<ol>${childrenHtml}</ol>`;
+            case 'listItem':
+                return `<li>${childrenHtml}</li>`;
+            case 'blockquote':
+                return `<blockquote>${childrenHtml}</blockquote>`;
+            case 'codeBlock': {
+                const language = typeof node.attrs?.['language'] === 'string' ? node.attrs['language'] : '';
+                const langClass = language ? ` class="language-${escapeHtml(language)}"` : '';
+                // コードブロック内のテキストは子ノードから取得
+                const codeText = node.content
+                    .map((child) => (child.type === 'text' && child.text !== undefined ? child.text : ''))
+                    .join('');
+                return `<pre><code${langClass}>${escapeHtml(codeText)}</code></pre>`;
+            }
+            case 'table':
+                return `<table>${childrenHtml}</table>`;
+            case 'tableRow':
+                return `<tr>${childrenHtml}</tr>`;
+            case 'tableHeader':
+                return `<th>${childrenHtml}</th>`;
+            case 'tableCell':
+                return `<td>${childrenHtml}</td>`;
+            case 'panel': {
+                // panel タイプを GitHub Alerts 形式に変換
+                const panelType = typeof node.attrs?.['panelType'] === 'string' ? node.attrs['panelType'] : 'info';
+                const alertTypeMap = {
+                    error: 'WARNING',
+                    info: 'NOTE',
+                    note: 'NOTE',
+                    success: 'TIP',
+                    warning: 'WARNING',
+                };
+                const alertType = alertTypeMap[panelType] || 'NOTE';
+                return `<blockquote data-github-alert="${alertType}">${childrenHtml}</blockquote>`;
+            }
+            // 未知のノードタイプは子ノードの内容を返す
+            default:
+                return childrenHtml;
+        }
+    }
+    // 子ノードもテキストもない場合は空文字列
+    return '';
+};
+/**
+ * ADF ドキュメントを HTML に変換する
+ *
+ * @param content ADF ドキュメントのコンテンツ配列
+ * @param attachmentPaths 添付ファイル ID → ローカルパスのマッピング
+ * @returns HTML 文字列
+ */
+const convertAdfContentToHtml = (content, attachmentPaths) => {
+    return content.map((node) => convertAdfNodeToHtml(node, attachmentPaths)).join('');
+};
 /**
  * HTML エンティティをデコードする
  *
@@ -348,20 +578,12 @@ const preprocessHtmlForMarkdown = (html, attachmentPaths) => {
     return result;
 };
 /**
- * Confluence Storage Format（XHTML）を Markdown に変換する
+ * TurndownService インスタンスを作成する（共通設定）
+ * Jira ADF と Confluence Storage Format の両方で使用する
  *
- * @param storageFormat Storage Format 文字列（HTML/XHTML）
- * @param attachmentPaths 添付ファイル名 → ローカルパスのマッピング
- * @returns Markdown 文字列
+ * @returns 設定済みの TurndownService インスタンス
  */
-export const convertStorageFormatToMarkdown = (storageFormat, attachmentPaths) => {
-    // null または undefined の場合は空文字列を返す
-    if (storageFormat === null || storageFormat === undefined || storageFormat === '') {
-        return '';
-    }
-    // 前処理
-    const preprocessedHtml = preprocessHtmlForMarkdown(storageFormat, attachmentPaths);
-    // Turndown インスタンス作成
+const createTurndownService = () => {
     const turndownService = new TurndownService({
         bulletListMarker: '-',
         codeBlockStyle: 'fenced',
@@ -371,9 +593,7 @@ export const convertStorageFormatToMarkdown = (storageFormat, attachmentPaths) =
     });
     // GFM プラグイン（テーブル、取り消し線など）を使用
     turndownService.use(gfm);
-    // --------------------------------------------------
     // カスタムルール: キャプション付き画像（<figure>）
-    // --------------------------------------------------
     turndownService.addRule('figureWithCaption', {
         filter: (node) => {
             return node.nodeName === 'FIGURE';
@@ -397,9 +617,7 @@ export const convertStorageFormatToMarkdown = (storageFormat, attachmentPaths) =
             return '';
         },
     });
-    // --------------------------------------------------
     // カスタムルール: GitHub Alerts（<blockquote data-github-alert="...">）
-    // --------------------------------------------------
     turndownService.addRule('githubAlerts', {
         filter: (node) => {
             if (node.nodeName !== 'BLOCKQUOTE')
@@ -417,9 +635,7 @@ export const convertStorageFormatToMarkdown = (storageFormat, attachmentPaths) =
             return `\n> [!${alertType}]\n${quotedContent}\n`;
         },
     });
-    // --------------------------------------------------
     // カスタムルール: 色変更テキスト（HTML のまま出力）
-    // --------------------------------------------------
     turndownService.addRule('coloredText', {
         filter: (node) => {
             if (node.nodeName !== 'SPAN')
@@ -432,9 +648,7 @@ export const convertStorageFormatToMarkdown = (storageFormat, attachmentPaths) =
             return node.outerHTML;
         },
     });
-    // --------------------------------------------------
     // カスタムルール: セル結合/セル内改行のあるテーブル（HTML のまま出力）
-    // --------------------------------------------------
     turndownService.addRule('complexTable', {
         filter: (node) => {
             if (node.nodeName !== 'TABLE')
@@ -447,6 +661,65 @@ export const convertStorageFormatToMarkdown = (storageFormat, attachmentPaths) =
             return node.outerHTML;
         },
     });
+    return turndownService;
+};
+/**
+ * ADF（Atlassian Document Format）を Markdown に変換する
+ *
+ * @param adf ADF ドキュメント（オブジェクトまたは JSON 文字列）
+ * @param attachmentPaths 添付ファイル ID → ローカルパスのマッピング
+ * @returns Markdown 文字列
+ */
+export const convertAdfToMarkdown = (adf, attachmentPaths) => {
+    // null または undefined の場合は空文字列を返す
+    if (adf === null || adf === undefined) {
+        return '';
+    }
+    // 文字列の場合は JSON としてパースを試みる
+    if (typeof adf === 'string') {
+        // 空文字列の場合
+        if (adf === '') {
+            return '';
+        }
+        try {
+            const parsed = JSON.parse(adf);
+            if (isAdfDocument(parsed)) {
+                const html = convertAdfContentToHtml(parsed.content, attachmentPaths);
+                const turndownService = createTurndownService();
+                return turndownService.turndown(html).trim();
+            }
+        }
+        catch {
+            // JSON パースに失敗した場合は元の文字列を返す
+            return adf;
+        }
+        // パースできたが ADF 形式でない場合は元の文字列を返す
+        return adf;
+    }
+    // オブジェクトの場合は ADF ドキュメントとして処理
+    if (isAdfDocument(adf)) {
+        const html = convertAdfContentToHtml(adf.content, attachmentPaths);
+        const turndownService = createTurndownService();
+        return turndownService.turndown(html).trim();
+    }
+    return '';
+};
+/**
+ * Confluence Storage Format（XHTML）を Markdown に変換する
+ *
+ * @param storageFormat Storage Format 文字列（HTML/XHTML）
+ * @param attachmentPaths 添付ファイル名 → ローカルパスのマッピング
+ * @returns Markdown 文字列
+ */
+export const convertStorageFormatToMarkdown = (storageFormat, attachmentPaths) => {
+    // null または undefined の場合は空文字列を返す
+    if (storageFormat === null || storageFormat === undefined || storageFormat === '') {
+        return '';
+    }
+    // 前処理
+    const preprocessedHtml = preprocessHtmlForMarkdown(storageFormat, attachmentPaths);
+    // 共通の TurndownService を使用
+    const turndownService = createTurndownService();
     // Markdown に変換
     const markdown = turndownService.turndown(preprocessedHtml);
     // 末尾の空白を除去

package/dist/types/jira.d.ts

@@ -6,8 +6,10 @@ export interface JiraComment {
     readonly id: string;
     /** 作成者の表示名 */
     readonly author: string;
-    /** コメント本文 */
+    /** コメント本文（プレーンテキスト） */
     readonly body: string;
+    /** コメント本文（ADF 形式、Markdown 変換用） */
+    readonly bodyAdf: unknown;
     /** 作成日時（ISO 8601 形式） */
     readonly created: string;
     /** 更新日時（ISO 8601 形式） */
@@ -62,6 +64,8 @@ export interface JiraIssue {
     readonly summary: string;
     /** Issue 説明（null の場合は説明なし） */
     readonly description: string | null;
+    /** Issue 説明（ADF 形式、Markdown 変換用） */
+    readonly descriptionAdf: unknown;
     /** コメント一覧 */
     readonly comments: readonly JiraComment[];
     /** 変更履歴一覧 */

package/dist/types/storage.d.ts

@@ -93,9 +93,9 @@ export interface JiraSaveData {
     readonly key: string;
     /** Issue タイトル（要約） */
     readonly summary: string;
-    /** Issue 説明（null の場合は説明なし） */
-    readonly description: string | null;
-    /** 説明のプレーンテキスト（null の場合は説明なし） */
+    /** Issue 説明（ADF 形式、null の場合は説明なし） */
+    readonly description: unknown;
+    /** 説明のプレーンテキスト（null の場合は説明なし、後方互換性のため維持） */
     readonly descriptionPlainText: string | null;
     /** コメント一覧 */
     readonly comments: readonly JiraComment[];

package/package.json

@@ -82,7 +82,7 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",