atl-fetch 1.1.0 → 1.2.1

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

@@ -0,0 +1,270 @@
+/**
+ * Markdown 変換ユーティリティ
+ *
+ * TurndownService の設定と前処理を提供する
+ */
+import TurndownService from 'turndown';
+import { gfm } from 'turndown-plugin-gfm';
+/**
+ * 前処理: 無視する要素を削除し、Confluence 固有タグを処理
+ *
+ * @param html HTML 文字列
+ * @param attachmentPaths 添付ファイルマッピング
+ * @returns 前処理済み HTML
+ */
+export const preprocessHtmlForMarkdown = (html, attachmentPaths) => {
+    let result = html;
+    // colgroup/col を削除
+    result = result.replace(/<colgroup[\s\S]*?<\/colgroup>/gi, '');
+    result = result.replace(/<col[^>]*\/?>/gi, '');
+    // data-highlight-colour 属性を削除
+    result = result.replace(/\s*data-highlight-colour="[^"]*"/gi, '');
+    // ac:local-id, local-id 属性を削除
+    result = result.replace(/\s*(ac:)?local-id="[^"]*"/gi, '');
+    // ac:inline-comment-marker を内容のみに置換
+    result = result.replace(/<ac:inline-comment-marker[^>]*>([\s\S]*?)<\/ac:inline-comment-marker>/gi, '$1');
+    // CDATA セクションを処理
+    result = result.replace(/<!\[CDATA\[([\s\S]*?)]]>/g, '$1');
+    // --------------------------------------------------
+    // Confluence 固有タグを標準 HTML タグに変換（turndown が認識できる形式へ）
+    // --------------------------------------------------
+    // ac:image + ac:caption を <img> + <figcaption> に変換（キャプション付きを先に処理）
+    result = result.replace(/<ac:image[^>]*>[\s\S]*?<ri:attachment[^>]*ri:filename="([^"]*)"[^>]*\/?>[\s\S]*?<ac:caption>([^<]*)<\/ac:caption>[\s\S]*?<\/ac:image>/gi, (_match, filename, caption) => {
+        const localPath = attachmentPaths?.[filename] || filename;
+        return `<figure><img src="${localPath}" alt="${filename}"><figcaption>${caption}</figcaption></figure>`;
+    });
+    // ac:image を <img> に変換（キャプションなしの残り）
+    result = result.replace(/<ac:image[^>]*>[\s\S]*?<ri:attachment[^>]*ri:filename="([^"]*)"[^>]*\/?>[\s\S]*?<\/ac:image>/gi, (_match, filename) => {
+        const localPath = attachmentPaths?.[filename] || filename;
+        return `<img src="${localPath}" alt="${filename}">`;
+    });
+    // ac:structured-macro name="code" を <pre><code> に変換
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="code"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, innerContent) => {
+        // language パラメータを抽出
+        const langMatch = innerContent.match(/<ac:parameter[^>]*ac:name="language"[^>]*>([^<]*)<\/ac:parameter>/i);
+        const lang = langMatch?.[1] || '';
+        // plain-text-body の内容を抽出
+        const bodyMatch = innerContent.match(/<ac:plain-text-body[^>]*>([\s\S]*?)<\/ac:plain-text-body>/i);
+        const code = bodyMatch?.[1] || '';
+        // turndown が認識できる形式に変換
+        const langClass = lang ? ` class="language-${lang}"` : '';
+        return `<pre><code${langClass}>${code}</code></pre>`;
+    });
+    // ac:structured-macro name="info/note/tip/warning" を GitHub Alerts 形式の blockquote に変換
+    const alertMacros = ['info', 'note', 'tip', 'warning'];
+    const alertTypeMap = {
+        info: 'NOTE',
+        note: 'NOTE',
+        tip: 'TIP',
+        warning: 'WARNING',
+    };
+    for (const macroName of alertMacros) {
+        const pattern = new RegExp(`<ac:structured-macro[^>]*ac:name="${macroName}"[^>]*>[\\s\\S]*?<ac:rich-text-body>([\\s\\S]*?)<\\/ac:rich-text-body>[\\s\\S]*?<\\/ac:structured-macro>`, 'gi');
+        result = result.replace(pattern, (_match, content) => {
+            const alertType = alertTypeMap[macroName] || 'NOTE';
+            // 専用のマーカー属性を持つ blockquote に変換
+            return `<blockquote data-github-alert="${alertType}">${content}</blockquote>`;
+        });
+    }
+    // ac:structured-macro name="toc" を [TOC] マーカーに変換（markdown-toc 互換形式）
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="toc"[^>]*>[\s\S]*?<\/ac:structured-macro>/gi, '<p>[TOC]</p>');
+    // ac:structured-macro name="anchor" を <a id="name"></a> に変換
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="anchor"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, innerContent) => {
+        // パラメータの値を抽出（ac:name="" または ac:name="..." 両方対応）
+        const paramMatch = innerContent.match(/<ac:parameter[^>]*>([^<]*)<\/ac:parameter>/i);
+        const anchorName = paramMatch?.[1]?.trim() || '';
+        return anchorName ? `<a id="${anchorName}"></a>` : '';
+    });
+    // ac:structured-macro name="expand" を <details><summary>...</summary>...</details> に変換
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="expand"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, innerContent) => {
+        // title パラメータを抽出
+        const titleMatch = innerContent.match(/<ac:parameter[^>]*ac:name="title"[^>]*>([^<]*)<\/ac:parameter>/i);
+        const title = titleMatch?.[1] || '展開';
+        // rich-text-body の内容を抽出
+        const bodyMatch = innerContent.match(/<ac:rich-text-body>([\s\S]*?)<\/ac:rich-text-body>/i);
+        const body = bodyMatch?.[1] || '';
+        return `<details><summary>${title}</summary>${body}</details>`;
+    });
+    // ac:structured-macro name="excerpt" を処理（hidden=true は削除、それ以外は内容を出力）
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="excerpt"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, innerContent) => {
+        // hidden パラメータをチェック
+        const hiddenMatch = innerContent.match(/<ac:parameter[^>]*ac:name="hidden"[^>]*>([^<]*)<\/ac:parameter>/i);
+        const isHidden = hiddenMatch?.[1]?.toLowerCase() === 'true';
+        if (isHidden) {
+            return ''; // hidden=true の場合は削除
+        }
+        // rich-text-body の内容を抽出
+        const bodyMatch = innerContent.match(/<ac:rich-text-body>([\s\S]*?)<\/ac:rich-text-body>/i);
+        return bodyMatch?.[1] || '';
+    });
+    // ac:structured-macro name="excerpt-include" をプレースホルダーに変換
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="excerpt-include"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, innerContent) => {
+        // ページ名を抽出
+        const pageMatch = innerContent.match(/ri:content-title="([^"]*)"/i);
+        const pageName = pageMatch?.[1] || '不明なページ';
+        return `<p>[抜粋: ${pageName}]</p>`;
+    });
+    // ac:structured-macro name="toc-zone" を [TOC] + 内容に変換
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="toc-zone"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, innerContent) => {
+        // rich-text-body の内容を抽出
+        const bodyMatch = innerContent.match(/<ac:rich-text-body>([\s\S]*?)<\/ac:rich-text-body>/i);
+        const body = bodyMatch?.[1] || '';
+        return `<p>[TOC]</p>${body}`;
+    });
+    // ac:link + ri:page を Markdown リンクに変換（CDATA 処理後のパターンも対応）
+    result = result.replace(/<ac:link[^>]*>[\s\S]*?<ri:page[^>]*ri:content-title="([^"]*)"[^>]*\/>[\s\S]*?<ac:plain-text-link-body[^>]*>([^<]*)<\/ac:plain-text-link-body>[\s\S]*?<\/ac:link>/gi, (_match, pageTitle, linkText) => {
+        return `<a href="${pageTitle}">${linkText}</a>`;
+    });
+    // ac:link + ri:page（リンクテキストなし）を処理
+    result = result.replace(/<ac:link[^>]*>[\s\S]*?<ri:page[^>]*ri:content-title="([^"]*)"[^>]*\/>[\s\S]*?<\/ac:link>/gi, (_match, pageTitle) => {
+        return `<a href="${pageTitle}">${pageTitle}</a>`;
+    });
+    // ac:structured-macro name="column" を td タグに変換（先に処理）
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="column"[^>]*>[\s\S]*?<ac:rich-text-body>([\s\S]*?)<\/ac:rich-text-body>[\s\S]*?<\/ac:structured-macro>/gi, (_match, columnBody) => {
+        return `<td>${columnBody}</td>`;
+    });
+    // ac:structured-macro name="section" をテーブルに変換（column 処理後）
+    result = result.replace(/<ac:structured-macro[^>]*ac:name="section"[^>]*>[\s\S]*?<ac:rich-text-body>([\s\S]*?)<\/ac:rich-text-body>[\s\S]*?<\/ac:structured-macro>/gi, (_match, sectionBody) => {
+        // td タグがあればテーブルとして出力
+        if (sectionBody.includes('<td>')) {
+            return `<table><tr>${sectionBody.trim()}</tr></table>`;
+        }
+        return sectionBody;
+    });
+    return result;
+};
+/**
+ * TurndownService インスタンスを作成する（共通設定）
+ * Jira ADF と Confluence Storage Format の両方で使用する
+ *
+ * @returns 設定済みの TurndownService インスタンス
+ */
+export const createTurndownService = () => {
+    const turndownService = new TurndownService({
+        bulletListMarker: '-',
+        codeBlockStyle: 'fenced',
+        emDelimiter: '*',
+        headingStyle: 'atx',
+        strongDelimiter: '**',
+    });
+    // GFM プラグイン（テーブル、取り消し線など）を使用
+    turndownService.use(gfm);
+    // カスタムルール: キャプション付き画像（<figure>）
+    turndownService.addRule('figureWithCaption', {
+        filter: (node) => {
+            return node.nodeName === 'FIGURE';
+        },
+        replacement: (_content, node) => {
+            const element = node;
+            const img = element.querySelector('img');
+            const figcaption = element.querySelector('figcaption');
+            if (img) {
+                const src = img.getAttribute('src') || '';
+                const alt = img.getAttribute('alt') || '';
+                let result = `![${alt}](${src})`;
+                if (figcaption) {
+                    const captionText = figcaption.textContent?.trim() || '';
+                    if (captionText) {
+                        result += `\n\n*${captionText}*`;
+                    }
+                }
+                return result;
+            }
+            return '';
+        },
+    });
+    // カスタムルール: GitHub Alerts（<blockquote data-github-alert="...">）
+    turndownService.addRule('githubAlerts', {
+        filter: (node) => {
+            if (node.nodeName !== 'BLOCKQUOTE')
+                return false;
+            return node.hasAttribute('data-github-alert');
+        },
+        replacement: (content, node) => {
+            const element = node;
+            const alertType = element.getAttribute('data-github-alert') || 'NOTE';
+            // 内容を再帰的に Markdown 変換
+            const innerMarkdown = content.trim();
+            // 各行に > プレフィックス付加
+            const lines = innerMarkdown.split('\n');
+            const quotedContent = lines.map((line) => `> ${line}`).join('\n');
+            return `\n> [!${alertType}]\n${quotedContent}\n`;
+        },
+    });
+    // カスタムルール: 色変更テキスト（HTML のまま出力）
+    turndownService.addRule('coloredText', {
+        filter: (node) => {
+            if (node.nodeName !== 'SPAN')
+                return false;
+            const style = node.getAttribute('style') || '';
+            return style.includes('color:') || style.includes('color :');
+        },
+        replacement: (_content, node) => {
+            // HTML のまま出力
+            return node.outerHTML;
+        },
+    });
+    // カスタムルール: アンカータグ（id 属性付き）を HTML のまま出力
+    turndownService.addRule('anchorTag', {
+        filter: (node) => {
+            if (node.nodeName !== 'A')
+                return false;
+            return node.hasAttribute('id');
+        },
+        replacement: (_content, node) => {
+            return node.outerHTML;
+        },
+    });
+    // カスタムルール: 背景色テキスト（HTML のまま出力）
+    turndownService.addRule('highlightedText', {
+        filter: (node) => {
+            if (node.nodeName !== 'SPAN')
+                return false;
+            const style = node.getAttribute('style') || '';
+            return style.includes('background-color');
+        },
+        replacement: (_content, node) => {
+            // HTML のまま出力
+            return node.outerHTML;
+        },
+    });
+    // カスタムルール: date ノード用（<time> タグから日付を抽出）
+    turndownService.addRule('dateNode', {
+        filter: 'time',
+        replacement: (_, node) => {
+            return node.getAttribute('datetime') || '';
+        },
+    });
+    // カスタムルール: expand 用（<details> タグを HTML のまま出力）
+    turndownService.addRule('expandDetails', {
+        filter: 'details',
+        replacement: (content, node) => {
+            const element = node;
+            const summary = element.querySelector('summary')?.textContent || '展開';
+            return `\n<details>\n<summary>${summary}</summary>\n\n${content.trim()}\n\n</details>\n`;
+        },
+    });
+    // カスタムルール: border スタイル付き画像（HTML のまま出力）
+    turndownService.addRule('borderedImage', {
+        filter: (node) => {
+            if (node.nodeName !== 'IMG')
+                return false;
+            const style = node.getAttribute('style') || '';
+            return style.includes('border');
+        },
+        replacement: (_content, node) => {
+            return node.outerHTML;
+        },
+    });
+    // カスタムルール: 全テーブルを HTML のまま出力（シンプル・確実）
+    // セル内リスト、画像、複数段落、コードなど全ケースで安定
+    // Confluence の複雑なテーブルも確実に表示
+    // Markdown 対応ビューアでも HTML テーブルは表示可能
+    turndownService.addRule('allTables', {
+        filter: 'table',
+        replacement: (_content, node) => {
+            return '\n\n' + node.outerHTML + '\n\n';
+        },
+    });
+    return turndownService;
+};

package/dist/services/text-converter/storage-to-plain-text.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Confluence Storage Format → PlainText 変換
+ */
+/**
+ * HTML エンティティをデコードする
+ *
+ * @param text エンコードされた文字列
+ * @returns デコードされた文字列
+ */
+export declare const decodeHtmlEntities: (text: string) => string;
+/**
+ * CDATA セクションからテキストを抽出する
+ *
+ * @param html HTML 文字列
+ * @returns CDATA セクションを処理した文字列
+ */
+export declare const extractCdata: (html: string) => string;
+/**
+ * Confluence マクロのパラメータからテキストを抽出する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export declare const extractMacroParameters: (html: string) => string;
+/**
+ * 画像タグをプレースホルダーに変換する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export declare const convertImagesToPlaceholders: (html: string) => string;
+/**
+ * ユーザーリンクをプレースホルダーに変換する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export declare const convertUserLinksToPlaceholders: (html: string) => string;
+/**
+ * ブロック要素のタグを処理して改行を適切に挿入する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export declare const processBlockElements: (html: string) => string;
+/**
+ * HTML タグを除去する
+ *
+ * @param html HTML 文字列
+ * @returns タグを除去した文字列
+ */
+export declare const stripHtmlTags: (html: string) => string;
+/**
+ * 連続する空白を正規化する
+ *
+ * @param text テキスト
+ * @returns 正規化されたテキスト
+ */
+export declare const normalizeWhitespace: (text: string) => string;
+/**
+ * Confluence の Storage Format（XHTML）をプレーンテキストに変換する
+ *
+ * @param storageFormat Storage Format 文字列
+ * @returns プレーンテキスト
+ */
+export declare const convertStorageFormatToPlainText: (storageFormat: string | null | undefined) => string;

package/dist/services/text-converter/storage-to-plain-text.js

@@ -0,0 +1,238 @@
+/**
+ * Confluence Storage Format → PlainText 変換
+ */
+/**
+ * HTML エンティティをデコードする
+ *
+ * @param text エンコードされた文字列
+ * @returns デコードされた文字列
+ */
+export const decodeHtmlEntities = (text) => {
+    return text
+        .replace(/ /g, ' ')
+        .replace(/&/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&#x27;/g, "'")
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number.parseInt(code, 10)));
+};
+/**
+ * CDATA セクションからテキストを抽出する
+ *
+ * @param html HTML 文字列
+ * @returns CDATA セクションを処理した文字列
+ */
+export const extractCdata = (html) => {
+    return html.replace(/<!\[CDATA\[([\s\S]*?)]]>/g, '$1');
+};
+/**
+ * Confluence マクロのパラメータからテキストを抽出する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export const extractMacroParameters = (html) => {
+    // ac:parameter タグから title などのテキストを抽出
+    return html.replace(/<ac:parameter[^>]*ac:name="title"[^>]*>([^<]*)<\/ac:parameter>/g, '$1');
+};
+/**
+ * 画像タグをプレースホルダーに変換する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export const convertImagesToPlaceholders = (html) => {
+    // ac:image タグと ri:attachment から画像ファイル名を抽出
+    return html.replace(/<ac:image[^>]*>[\s\S]*?<ri:attachment\s+ri:filename="([^"]*)"[^>]*\/>[\s\S]*?<\/ac:image>/g, '[画像: $1]');
+};
+/**
+ * ユーザーリンクをプレースホルダーに変換する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export const convertUserLinksToPlaceholders = (html) => {
+    // ri:user タグをプレースホルダーに変換
+    return html.replace(/<ac:link[^>]*>[\s\S]*?<ri:user[^>]*\/>[\s\S]*?<\/ac:link>/g, '[ユーザー]');
+};
+/**
+ * ブロック要素のタグを処理して改行を適切に挿入する
+ *
+ * @param html HTML 文字列
+ * @returns 処理された文字列
+ */
+export const processBlockElements = (html) => {
+    // 閉じタグの前後に改行マーカーを追加
+    let result = html;
+    // パラグラフと見出しの後に改行
+    result = result.replace(/<\/(p|h[1-6])>/gi, '</$1>\n');
+    // リストアイテムの後に改行
+    result = result.replace(/<\/li>/gi, '</li>\n');
+    // テーブル行の後に改行
+    result = result.replace(/<\/tr>/gi, '</tr>\n');
+    // テーブルセルの後にタブ
+    result = result.replace(/<\/(td|th)>/gi, '\t</$1>');
+    // br タグを改行に変換
+    result = result.replace(/<br\s*\/?>/gi, '\n');
+    // blockquote の後に改行
+    result = result.replace(/<\/blockquote>/gi, '</blockquote>\n');
+    return result;
+};
+/**
+ * HTML タグを除去する
+ *
+ * @param html HTML 文字列
+ * @returns タグを除去した文字列
+ */
+export const stripHtmlTags = (html) => {
+    return html.replace(/<[^>]*>/g, '');
+};
+/**
+ * 連続する空白を正規化する
+ *
+ * @param text テキスト
+ * @returns 正規化されたテキスト
+ */
+export const normalizeWhitespace = (text) => {
+    // 行ごとに処理
+    const lines = text.split('\n');
+    const normalizedLines = lines.map((line) => {
+        // 行内の連続する空白を単一スペースに
+        return line.replace(/[ \t]+/g, ' ').trim();
+    });
+    // 空行を除去して結合
+    return normalizedLines.filter((line) => line !== '').join('\n');
+};
+/**
+ * Confluence の Storage Format（XHTML）をプレーンテキストに変換する
+ *
+ * @param storageFormat Storage Format 文字列
+ * @returns プレーンテキスト
+ */
+export const convertStorageFormatToPlainText = (storageFormat) => {
+    // null または undefined の場合は空文字列を返す
+    if (storageFormat === null || storageFormat === undefined || storageFormat === '') {
+        return '';
+    }
+    let result = storageFormat;
+    // CDATA セクションを処理
+    result = extractCdata(result);
+    // マクロパラメータからテキストを抽出
+    result = extractMacroParameters(result);
+    // 画像をプレースホルダーに変換
+    result = convertImagesToPlaceholders(result);
+    // ユーザーリンクをプレースホルダーに変換
+    result = convertUserLinksToPlaceholders(result);
+    // ブロック要素を処理
+    result = processBlockElements(result);
+    // HTML タグを除去
+    result = stripHtmlTags(result);
+    // HTML エンティティをデコード
+    result = decodeHtmlEntities(result);
+    // 空白を正規化
+    result = normalizeWhitespace(result);
+    return result;
+};
+// ============================================================
+// In-source Testing（プライベート関数のテスト）
+// ============================================================
+if (import.meta.vitest) {
+    const { describe, expect, it } = import.meta.vitest;
+    describe('decodeHtmlEntities (in-source testing)', () => {
+        // テストの目的: 各エンティティが正確に変換されること
+        describe('個別エンティティの変換検証', () => {
+            it('Given: &nbsp;, When: decodeHtmlEntities を呼び出す, Then: スペースに変換される', () => {
+                expect(decodeHtmlEntities('&nbsp;')).toBe(' ');
+            });
+            it('Given: &amp;, When: decodeHtmlEntities を呼び出す, Then: & に変換される', () => {
+                expect(decodeHtmlEntities('&amp;')).toBe('&');
+            });
+            it('Given: &lt;, When: decodeHtmlEntities を呼び出す, Then: < に変換される', () => {
+                expect(decodeHtmlEntities('&lt;')).toBe('<');
+            });
+            it('Given: &gt;, When: decodeHtmlEntities を呼び出す, Then: > に変換される', () => {
+                expect(decodeHtmlEntities('&gt;')).toBe('>');
+            });
+            it('Given: &quot;, When: decodeHtmlEntities を呼び出す, Then: " に変換される', () => {
+                expect(decodeHtmlEntities('&quot;')).toBe('"');
+            });
+            it("Given: &#39;, When: decodeHtmlEntities を呼び出す, Then: ' に変換される", () => {
+                expect(decodeHtmlEntities('&#39;')).toBe("'");
+            });
+            it("Given: &#x27;, When: decodeHtmlEntities を呼び出す, Then: ' に変換される", () => {
+                expect(decodeHtmlEntities('&#x27;')).toBe("'");
+            });
+            it('Given: 数値文字参照 &#65;, When: decodeHtmlEntities を呼び出す, Then: A に変換される', () => {
+                expect(decodeHtmlEntities('&#65;')).toBe('A');
+            });
+            it('Given: 数値文字参照 &#12354;, When: decodeHtmlEntities を呼び出す, Then: あ に変換される', () => {
+                expect(decodeHtmlEntities('&#12354;')).toBe('あ');
+            });
+        });
+        // テストの目的: 複数のエンティティが正しい順序で変換されること
+        describe('変換順序の検証', () => {
+            it('Given: &amp;nbsp;, When: decodeHtmlEntities を呼び出す, Then: &nbsp; に変換される（&amp; が先に処理される）', () => {
+                // &amp;nbsp; → &nbsp; になること（&nbsp; → スペース にはならない）
+                expect(decodeHtmlEntities('&amp;nbsp;')).toBe('&nbsp;');
+            });
+            it('Given: &amp;lt;, When: decodeHtmlEntities を呼び出す, Then: < に変換される（連鎖的に置換される）', () => {
+                // &amp; -> & になり、その後 &lt; -> < になる
+                expect(decodeHtmlEntities('&amp;lt;')).toBe('<');
+            });
+        });
+    });
+    describe('convertImagesToPlaceholders (in-source testing)', () => {
+        // テストの目的: 画像タグが '[画像: ファイル名]' に変換されること
+        describe('画像プレースホルダーの検証', () => {
+            it('Given: ac:image タグ, When: convertImagesToPlaceholders を呼び出す, Then: [画像: filename] 形式になる', () => {
+                const html = '<ac:image><ri:attachment ri:filename="test.png"/></ac:image>';
+                const result = convertImagesToPlaceholders(html);
+                expect(result).toBe('[画像: test.png]');
+            });
+            it('Given: 日本語ファイル名の画像, When: convertImagesToPlaceholders を呼び出す, Then: ファイル名がそのまま含まれる', () => {
+                const html = '<ac:image><ri:attachment ri:filename="テスト画像.png"/></ac:image>';
+                const result = convertImagesToPlaceholders(html);
+                expect(result).toBe('[画像: テスト画像.png]');
+            });
+            it('Given: 空のファイル名, When: convertImagesToPlaceholders を呼び出す, Then: [画像: ] となる', () => {
+                const html = '<ac:image><ri:attachment ri:filename=""/></ac:image>';
+                const result = convertImagesToPlaceholders(html);
+                expect(result).toBe('[画像: ]');
+            });
+        });
+    });
+    describe('convertUserLinksToPlaceholders (in-source testing)', () => {
+        // テストの目的: ユーザーリンクが '[ユーザー]' に変換されること
+        describe('ユーザープレースホルダーの検証', () => {
+            it('Given: ri:user タグ, When: convertUserLinksToPlaceholders を呼び出す, Then: [ユーザー] になる', () => {
+                const html = '<ac:link><ri:user ri:account-id="123"/></ac:link>';
+                const result = convertUserLinksToPlaceholders(html);
+                expect(result).toBe('[ユーザー]');
+            });
+            it('Given: 複数のユーザーリンク, When: convertUserLinksToPlaceholders を呼び出す, Then: それぞれ [ユーザー] になる', () => {
+                const html = '<ac:link><ri:user ri:account-id="1"/></ac:link>と<ac:link><ri:user ri:account-id="2"/></ac:link>';
+                const result = convertUserLinksToPlaceholders(html);
+                expect(result).toBe('[ユーザー]と[ユーザー]');
+            });
+        });
+    });
+    describe('normalizeWhitespace (in-source testing)', () => {
+        // テストの目的: 連続空白が単一スペースに正規化されること
+        describe('空白正規化の検証', () => {
+            it('Given: 連続スペース, When: normalizeWhitespace を呼び出す, Then: 単一スペースになる', () => {
+                expect(normalizeWhitespace('a    b')).toBe('a b');
+            });
+            it('Given: 連続タブ, When: normalizeWhitespace を呼び出す, Then: 単一スペースになる', () => {
+                expect(normalizeWhitespace('a\t\t\tb')).toBe('a b');
+            });
+            it('Given: 空行, When: normalizeWhitespace を呼び出す, Then: 空行が削除される', () => {
+                expect(normalizeWhitespace('a\n\n\nb')).toBe('a\nb');
+            });
+            it('Given: 先頭末尾の空白, When: normalizeWhitespace を呼び出す, Then: トリムされる', () => {
+                expect(normalizeWhitespace('  a  ')).toBe('a');
+            });
+        });
+    });
+}

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

@@ -2,28 +2,19 @@
  * テキスト変換サービス
  *
  * Jira の ADF（Atlassian Document Format）と Confluence の Storage Format を
- * プレーンテキストに変換する機能を提供する。
- * また、Confluence の Storage Format を Markdown に変換する機能も提供する。
+ * プレーンテキストや Markdown に変換する機能を提供する。
  */
+import type { AttachmentPathMapping } from './types.js';
+export { convertAdfToPlainText } from './adf-to-plain-text.js';
+export { convertStorageFormatToPlainText } from './storage-to-plain-text.js';
 /**
- * 添付ファイルパスのマッピング型
- * filename -> savedPath
- */
-type AttachmentPathMapping = Record<string, string>;
-/**
- * ADF（Atlassian Document Format）をプレーンテキストに変換する
+ * ADF（Atlassian Document Format）を Markdown に変換する
  *
  * @param adf ADF ドキュメント（オブジェクトまたは JSON 文字列）
- * @returns プレーンテキスト
- */
-export declare const convertAdfToPlainText: (adf: unknown) => string;
-/**
- * Confluence の Storage Format（XHTML）をプレーンテキストに変換する
- *
- * @param storageFormat Storage Format 文字列
- * @returns プレーンテキスト
+ * @param attachmentPaths 添付ファイル ID → ローカルパスのマッピング
+ * @returns Markdown 文字列
  */
-export declare const convertStorageFormatToPlainText: (storageFormat: string | null | undefined) => string;
+export declare const convertAdfToMarkdown: (adf: unknown, attachmentPaths?: AttachmentPathMapping) => string;
 /**
  * Confluence Storage Format（XHTML）を Markdown に変換する
  *
@@ -32,4 +23,3 @@ export declare const convertStorageFormatToPlainText: (storageFormat: string | n
  * @returns Markdown 文字列
  */
 export declare const convertStorageFormatToMarkdown: (storageFormat: string | null | undefined, attachmentPaths?: AttachmentPathMapping) => string;
-export {};