backlog-exporter 1.1.0 → 1.2.0

package/dist/modules/document/domain/document-json-markdown.d.ts

@@ -0,0 +1 @@
+export declare function convertDocumentJsonToMarkdown(json: unknown): string;

package/dist/modules/document/domain/document-json-markdown.js

@@ -0,0 +1,389 @@
+const BLOCK_TYPES = new Set([
+    'blockquote',
+    'bulletList',
+    'codeBlock',
+    'heading',
+    'horizontalRule',
+    'orderedList',
+    'paragraph',
+    'table',
+]);
+// マーク適用順。codeは最内側に置き、他の記号がコードスパンの外に出るようにする
+const MARK_ORDER = ['code', 'bold', 'italic', 'strike', 'link'];
+function isNode(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isBlockLike(node) {
+    return typeof node.type === 'string' && BLOCK_TYPES.has(node.type);
+}
+function childNodes(node) {
+    return Array.isArray(node.content) ? node.content.filter((child) => isNode(child)) : [];
+}
+function nodeMarks(node) {
+    return (Array.isArray(node.marks) ? node.marks : []).filter((mark) => isNode(mark));
+}
+function attrString(node, key) {
+    const value = node.attrs?.[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function markOrder(mark) {
+    const index = MARK_ORDER.indexOf(mark.type ?? '');
+    // 未知のマークは最外側に置く（-1で最内側に来るのを防ぐ）
+    return index === -1 ? MARK_ORDER.length : index;
+}
+function sortMarks(marks) {
+    return [...marks].sort((a, b) => markOrder(a) - markOrder(b));
+}
+// 隣接テキストのマークが同一かの判定用。属性まで含めて比較する
+function markKey(mark) {
+    return `${mark.type ?? ''}:${JSON.stringify(mark.attrs ?? {})}`;
+}
+function marksKey(marks) {
+    return sortMarks(marks)
+        .map((mark) => markKey(mark))
+        .join('|');
+}
+// 連続するバッククォートの最長連を求め、それより長いフェンス/デリミタを選ぶ
+function longestBacktickRun(text) {
+    let longest = 0;
+    for (const run of text.matchAll(/`+/g)) {
+        longest = Math.max(longest, run[0].length);
+    }
+    return longest;
+}
+function inlineCode(text) {
+    const delimiter = '`'.repeat(longestBacktickRun(text) + 1);
+    // 内容の端がバッククォートの場合、区切りと繋がらないよう空白で隔てる
+    const pad = text.startsWith('`') || text.endsWith('`') ? ' ' : '';
+    return `${delimiter}${pad}${text}${pad}${delimiter}`;
+}
+// CommonMarkのリンク先は空白・括弧を含む場合<>で囲う必要がある
+function linkDestination(destination) {
+    return /[\s()]/.test(destination) ? `<${destination}>` : destination;
+}
+function escapeBracketText(text) {
+    return text.replaceAll('[', String.raw `\[`).replaceAll(']', String.raw `\]`);
+}
+// 行頭に来るとブロック記法として解釈される文字をエスケープする。
+// リスト内の字下げはリスト側で付けるため、ここではテキスト自身の先頭空白だけを見る
+function escapeBlockStart(text) {
+    return (text
+        // 4スペース以上の字下げはコードブロックになるため3つまでに詰める
+        .replace(/^ {4,}/, '   ')
+        .replace(/^(\s*)([#>])/, String.raw `$1\$2`)
+        .replace(/^(\s*)(~~~)/, String.raw `$1\$2`)
+        .replace(/^(\s*)([+-])(\s)/, String.raw `$1\$2$3`)
+        .replace(/^(\s*)(\d{1,9})([).])(\s)/, String.raw `$1$2\$3$4`)
+        // setext見出しの下線（=== や ---）は行全体がその文字のときだけ成立する
+        .replace(/^(\s*)([=-])(?=[=-]*\s*$)/, String.raw `$1\$2`));
+}
+// 自動リンクされるURLはエスケープするとリンク先が壊れるため素通しする
+const URL_PATTERN = /https?:\/\/[^\s<>]+/g;
+// インラインの強調記法として解釈されうる文字のみを対象にする（CJK約物は対象外）
+function escapeInline(text) {
+    let result = '';
+    let last = 0;
+    for (const match of text.matchAll(URL_PATTERN)) {
+        result += escapeInlineSpan(text.slice(last, match.index)) + match[0];
+        last = match.index + match[0].length;
+    }
+    return result + escapeInlineSpan(text.slice(last));
+}
+function escapeInlineSpan(text) {
+    return text.replaceAll(/[[\\\]_`*<]/g, String.raw `\$&`);
+}
+function applyMark(text, mark) {
+    switch (mark.type) {
+        case 'bold': {
+            return wrapKeepingWhitespace(text, '**');
+        }
+        case 'code': {
+            return inlineCode(text);
+        }
+        case 'italic': {
+            return wrapKeepingWhitespace(text, '*');
+        }
+        case 'link': {
+            const href = typeof mark.attrs?.href === 'string' ? mark.attrs.href : '';
+            return `[${text}](${linkDestination(href)})`;
+        }
+        case 'strike': {
+            return wrapKeepingWhitespace(text, '~~');
+        }
+        default: {
+            return text;
+        }
+    }
+}
+// 区切り記号の内側に空白があると強調が成立しないため、空白を外側へ追い出す
+function wrapKeepingWhitespace(text, delimiter) {
+    const match = /^(\s*)([\s\S]*?)(\s*)$/.exec(text);
+    if (!match)
+        return `${delimiter}${text}${delimiter}`;
+    const [, leading, core, trailing] = match;
+    if (core === '')
+        return text;
+    return `${leading}${delimiter}${core}${delimiter}${trailing}`;
+}
+function renderMarkedText(text, marks, atLineStart) {
+    if (text === '')
+        return '';
+    const hasCode = marks.some((mark) => mark.type === 'code');
+    // コードマーク内はエスケープせず原文のまま出す
+    let result = hasCode ? text : escapeInline(text);
+    if (!hasCode && atLineStart)
+        result = escapeBlockStart(result);
+    for (const mark of sortMarks(marks)) {
+        result = applyMark(result, mark);
+    }
+    return result;
+}
+// 同じマークの連続テキストは1つに束ねる（**a****b** のような無効な出力を防ぐ）
+function coalesceTextNodes(nodes) {
+    const result = [];
+    for (const node of nodes) {
+        const previous = result.at(-1);
+        if (node.type === 'text' &&
+            previous?.type === 'text' &&
+            marksKey(nodeMarks(previous)) === marksKey(nodeMarks(node))) {
+            result[result.length - 1] = { ...previous, text: (previous.text ?? '') + (node.text ?? '') };
+            continue;
+        }
+        result.push(node);
+    }
+    return result;
+}
+// 隣接テキストが共通の外側マーク（**等）を持つ場合、閉じて開き直すと強調が壊れる。
+// 共通マークで全体を1度だけ包み、内側の差分マークだけを各テキストに適用する
+function renderTextRun(nodes, atLineStart) {
+    const shared = [];
+    if (nodes.length > 1) {
+        const first = sortMarks(nodeMarks(nodes[0]));
+        for (const mark of first) {
+            // codeは内容ごとに区切りが変わるため共通化しない
+            if (mark.type === 'code')
+                continue;
+            if (nodes.every((node) => nodeMarks(node).some((other) => markKey(other) === markKey(mark)))) {
+                shared.push(mark);
+            }
+        }
+    }
+    const sharedKeys = new Set(shared.map((mark) => markKey(mark)));
+    let inner = '';
+    for (const [index, node] of nodes.entries()) {
+        const rest = nodeMarks(node).filter((mark) => !sharedKeys.has(markKey(mark)));
+        inner += renderMarkedText(node.text ?? '', rest, atLineStart && index === 0);
+    }
+    let result = inner;
+    for (const mark of sortMarks(shared)) {
+        result = applyMark(result, mark);
+    }
+    return result;
+}
+// 末尾/先頭のhardBreakは余分な空行になるため落とす
+function trimHardBreaks(nodes) {
+    let start = 0;
+    let end = nodes.length;
+    while (start < end && nodes[start].type === 'hardBreak')
+        start++;
+    while (end > start && nodes[end - 1].type === 'hardBreak')
+        end--;
+    return nodes.slice(start, end);
+}
+function renderInline(nodes, atBlockStart = false) {
+    // 空テキストはマークの結合を妨げるだけなので取り除く
+    const meaningful = nodes.filter((node) => node.type !== 'text' || (node.text ?? '') !== '');
+    const prepared = coalesceTextNodes(trimHardBreaks(meaningful));
+    let result = '';
+    let atLineStart = atBlockStart;
+    for (let index = 0; index < prepared.length; index++) {
+        const node = prepared[index];
+        const isStart = atLineStart;
+        // 行頭とみなせるのはブロック先頭とhardBreak直後だけ
+        atLineStart = false;
+        switch (node.type) {
+            case 'attachmentBadge': {
+                result += renderAttachmentBadge(node);
+                break;
+            }
+            case 'hardBreak': {
+                result += '  \n';
+                atLineStart = true;
+                break;
+            }
+            case 'image': {
+                result += renderImage(node);
+                break;
+            }
+            case 'issueMention': {
+                result += renderIssueMention(node);
+                break;
+            }
+            case 'text': {
+                // 連続するテキストはまとめて処理し、共通マークを1度だけ適用する
+                let end = index;
+                while (end + 1 < prepared.length && prepared[end + 1].type === 'text')
+                    end++;
+                result += renderTextRun(prepared.slice(index, end + 1), isStart);
+                index = end;
+                break;
+            }
+            default: {
+                result += renderInline(childNodes(node), isStart);
+            }
+        }
+    }
+    return result;
+}
+function renderImage(node) {
+    const src = attrString(node, 'src') ?? '';
+    const alt = escapeBracketText(attrString(node, 'alt') ?? '');
+    const title = attrString(node, 'title');
+    const destination = linkDestination(src);
+    return title ? `![${alt}](${destination} "${title}")` : `![${alt}](${destination})`;
+}
+// Backlog独自ノード。attrsの形が公開されていないため、ラベルになりうるキーを順に探す
+function renderAttachmentBadge(node) {
+    const label = attrString(node, 'name') ??
+        attrString(node, 'title') ??
+        attrString(node, 'fileName') ??
+        attrString(node, 'text') ??
+        renderInline(childNodes(node));
+    const src = attrString(node, 'src') ?? attrString(node, 'href') ?? attrString(node, 'url');
+    const resolved = escapeBracketText(label.length > 0 ? label : '添付ファイル');
+    return src ? `[${resolved}](${linkDestination(src)})` : resolved;
+}
+// Backlog独自ノード。課題キーを持つキーを順に探す
+function renderIssueMention(node) {
+    const key = attrString(node, 'issueKey') ??
+        attrString(node, 'key') ??
+        attrString(node, 'label') ??
+        attrString(node, 'text') ??
+        renderInline(childNodes(node));
+    return key;
+}
+function renderCodeBlock(node) {
+    const language = attrString(node, 'language');
+    // Backlogは言語未指定を"auto"として返す
+    const info = language && language !== 'auto' ? language : '';
+    const code = childNodes(node)
+        .map((child) => (typeof child.text === 'string' ? child.text : ''))
+        .join('');
+    // 内容に含まれるバッククォート連より長いフェンスにしてブロックが途中で閉じるのを防ぐ
+    const fence = '`'.repeat(Math.max(3, longestBacktickRun(code) + 1));
+    return `${fence}${info}\n${code}\n${fence}`;
+}
+function renderBlockquote(node) {
+    return renderBlocks(childNodes(node))
+        .split('\n')
+        .map((line) => (line === '' ? '>' : `> ${line}`))
+        .join('\n');
+}
+function renderListItem(node, marker) {
+    const children = childNodes(node);
+    const rendered = children.map((child) => child.type === 'bulletList' || child.type === 'orderedList' ? renderList(child) : renderBlock(child));
+    let body = '';
+    for (const [index, block] of rendered.entries()) {
+        if (block === '')
+            continue;
+        if (body === '') {
+            body = block;
+            continue;
+        }
+        // 段落直後のネストリストはtight listとして1改行で繋ぐ
+        const isNestedList = children[index].type === 'bulletList' || children[index].type === 'orderedList';
+        body += isNestedList ? `\n${block}` : `\n\n${block}`;
+    }
+    if (body === '')
+        return marker.trimEnd();
+    const indent = ' '.repeat(marker.length);
+    return body
+        .split('\n')
+        .map((line, index) => (index === 0 ? `${marker}${line}` : line === '' ? '' : `${indent}${line}`))
+        .join('\n');
+}
+function renderList(node) {
+    const ordered = node.type === 'orderedList';
+    const startAttr = node.attrs?.start;
+    const start = ordered && typeof startAttr === 'number' && Number.isInteger(startAttr) ? startAttr : 1;
+    return childNodes(node)
+        .map((item, index) => renderListItem(item, ordered ? `${start + index}. ` : '- '))
+        .join('\n');
+}
+function renderCell(node) {
+    return childNodes(node)
+        .map((child) => renderBlock(child))
+        .filter((block) => block !== '')
+        .join('<br>')
+        .replaceAll(/ {0,2}\n/g, '<br>')
+        .replaceAll('|', String.raw `\|`);
+}
+function renderTable(node) {
+    const rows = childNodes(node).filter((row) => row.type === 'tableRow' || childNodes(row).length > 0);
+    if (rows.length === 0)
+        return '';
+    const cellRows = rows.map((row) => childNodes(row));
+    const columnCount = Math.max(...cellRows.map((cells) => cells.length));
+    if (columnCount === 0)
+        return '';
+    const lines = cellRows.map((cells) => {
+        const rendered = cells.map((cell) => renderCell(cell));
+        while (rendered.length < columnCount)
+            rendered.push('');
+        return `| ${rendered.join(' | ')} |`;
+    });
+    // 1行目がtableHeaderでなくてもGitHub Markdownとして描画されるよう区切り行を必ず入れる
+    const separator = `| ${Array.from({ length: columnCount }, () => '---').join(' | ')} |`;
+    return [lines[0], separator, ...lines.slice(1)].join('\n');
+}
+function renderBlock(node) {
+    switch (node.type) {
+        case 'blockquote': {
+            return renderBlockquote(node);
+        }
+        case 'bulletList':
+        case 'orderedList': {
+            return renderList(node);
+        }
+        case 'codeBlock': {
+            return renderCodeBlock(node);
+        }
+        case 'heading': {
+            const levelAttr = node.attrs?.level;
+            const level = typeof levelAttr === 'number' && levelAttr >= 1 && levelAttr <= 6 ? Math.trunc(levelAttr) : 1;
+            const inline = renderInline(childNodes(node));
+            return inline === '' ? '' : `${'#'.repeat(level)} ${inline}`;
+        }
+        case 'horizontalRule': {
+            return '---';
+        }
+        case 'image': {
+            return renderImage(node);
+        }
+        case 'paragraph': {
+            return renderInline(childNodes(node), true);
+        }
+        case 'table': {
+            return renderTable(node);
+        }
+        default: {
+            const children = childNodes(node);
+            if (children.length === 0)
+                return renderInline([node], true);
+            // 未知のブロックは内容を落とさずそのまま連結する
+            return children.some((child) => isBlockLike(child)) ? renderBlocks(children) : renderInline(children, true);
+        }
+    }
+}
+function renderBlocks(nodes) {
+    return nodes
+        .map((node) => renderBlock(node))
+        .filter((block) => block !== '')
+        .join('\n\n');
+}
+export function convertDocumentJsonToMarkdown(json) {
+    if (!isNode(json))
+        return '';
+    const blocks = json.type === 'doc' ? childNodes(json) : [json];
+    return renderBlocks(blocks);
+}

package/dist/modules/document/domain/document-markdown.d.ts

@@ -1,2 +1,4 @@
 import { DocumentDetail } from './document.js';
+export declare const EMPTY_BODY_PLACEHOLDER = "\uFF08\u5185\u5BB9\u306A\u3057\uFF09";
+export declare function buildDocumentBody(documentDetail: Pick<DocumentDetail, 'json' | 'plain'>): string;
 export declare function buildDocumentMarkdown(documentDetail: DocumentDetail, backlogDocumentUrl: string, attachmentLinks?: Map<number, string>): string;

package/dist/modules/document/domain/document-markdown.js

@@ -1,5 +1,15 @@
 import { escapeLinkText } from '../../../shared/attachment.js';
 import { wrapBody } from '../../../shared/markdown/body-marker.js';
+import { convertDocumentJsonToMarkdown } from './document-json-markdown.js';
+export const EMPTY_BODY_PLACEHOLDER = '（内容なし）';
+// plainはBacklog側で改行が失われることがあるため、構造を持つjsonを優先する。
+// 本文の有無の判定（親indexの保存要否）もこの結果を唯一の基準にする
+export function buildDocumentBody(documentDetail) {
+    const fromJson = convertDocumentJsonToMarkdown(documentDetail.json);
+    if (fromJson.trim() !== '')
+        return fromJson;
+    return documentDetail.plain?.trim() ? documentDetail.plain : '';
+}
 export function buildDocumentMarkdown(documentDetail, backlogDocumentUrl, attachmentLinks) {
     // 添付ファイルリストの作成（ダウンロード済みはローカルへの相対リンク付き）
     let attachmentsSection = '';
@@ -36,5 +46,5 @@ export function buildDocumentMarkdown(documentDetail, backlogDocumentUrl, attach
 
 ## 内容
 
-${wrapBody(documentDetail.plain || '（内容なし）')}${attachmentsSection}${tagsSection}`;
+${wrapBody(buildDocumentBody(documentDetail) || EMPTY_BODY_PLACEHOLDER)}${attachmentsSection}${tagsSection}`;
 }

package/dist/modules/document/domain/document-path.d.ts

@@ -1,6 +1,7 @@
 import { ExpectedPaths } from '../../prune/domain/expected-paths.js';
-import { DocumentNode } from './document.js';
+import { DocumentNode, DocumentSummary } from './document.js';
 export declare const PARENT_DOCUMENT_INDEX_FILENAME = "00_index.md";
+export declare const DOCUMENT_FALLBACK_PARENT_PATH = "";
 export declare function documentFolderPath(currentPath: string, folderName: string): string;
 export declare function documentFileName(title: string, asParentIndex: boolean): string;
 export declare function documentUrl(domain: string, projectIdOrKey: string, documentId: string): string;
@@ -21,3 +22,4 @@ export interface DocumentTreePaths extends ExpectedPaths {
 }
 export declare function collectDocumentTreePaths(rootNodes: DocumentNode[]): DocumentTreePaths;
 export declare function resolveDocumentLeafPaths(paths: DocumentTreePaths, titlesById: Map<string, string>): void;
+export declare function addFallbackDocumentPaths(paths: ExpectedPaths, documents: DocumentSummary[]): void;

package/dist/modules/document/domain/document-path.js

@@ -4,6 +4,8 @@ import { backlogOrigin } from '../../../shared/backlog-url.js';
 import { sanitizeFileName } from '../../../shared/file-name.js';
 // 子を持つ親ドキュメント自身の本文の保存先。ダウンロード側とprune側でレイアウト定義を共有する
 export const PARENT_DOCUMENT_INDEX_FILENAME = '00_index.md';
+// ツリーに現れないドキュメントの保存先。ツリー上の位置が分からないため出力ルート直下に置く
+export const DOCUMENT_FALLBACK_PARENT_PATH = '';
 export function documentFolderPath(currentPath, folderName) {
     return path.join(currentPath, sanitizeFileName(folderName));
 }
@@ -55,3 +57,9 @@ export function resolveDocumentLeafPaths(paths, titlesById) {
         paths.expectedFiles.add(path.join(leaf.currentPath, `${sanitizeFileName(title)}.md`).normalize('NFC'));
     }
 }
+// ツリーに現れないドキュメントは出力ルート直下に保存されるため、同じ配置で期待パスに加える
+export function addFallbackDocumentPaths(paths, documents) {
+    for (const document of documents) {
+        paths.expectedFiles.add(path.join(DOCUMENT_FALLBACK_PARENT_PATH, documentFileName(document.title, false)).normalize('NFC'));
+    }
+}

package/dist/modules/document/domain/document-save-plan.d.ts

@@ -1,9 +1,10 @@
-export type DocumentSaveAction = 'delete-stale-parent-index' | 'save' | 'skip-empty-parent' | 'skip-parent-index-collision' | 'skip-unchanged';
+export type DocumentSaveAction = 'delete-stale-parent-index' | 'save' | 'skip-empty-parent' | 'skip-fallback-collision' | 'skip-parent-index-collision' | 'skip-unchanged';
 export declare function planDocumentSave(input: {
+    alreadyWrittenThisRun: boolean;
     asParentIndex: boolean;
     body: null | string | undefined;
+    fileExists: boolean;
     lastUpdated?: string;
-    parentIndexAlreadyWrittenThisRun: boolean;
-    parentIndexExists: boolean;
+    missingFromTree: boolean;
     updated: string;
 }): DocumentSaveAction;

package/dist/modules/document/domain/document-save-plan.js

@@ -1,15 +1,21 @@
 // 保存/スキップ/親index削除の判断。本文が空の親はファイルを作らず、空に変更された場合は古い親indexを削除する
 export function planDocumentSave(input) {
-    if (input.asParentIndex && input.parentIndexAlreadyWrittenThisRun) {
+    if (input.asParentIndex && input.alreadyWrittenThisRun) {
         return 'skip-parent-index-collision';
     }
-    // 前回の更新日時チェック（親indexがまだ存在しない場合はバックフィルのため未更新でも保存する）
-    const backfillParentIndex = input.asParentIndex && !input.parentIndexExists;
-    if (input.lastUpdated && !backfillParentIndex && new Date(input.updated) <= new Date(input.lastUpdated)) {
+    // ツリーに現れないドキュメントは出力ルート直下に固定で置かれるため、同名の保存先が既に使われていたら譲る。
+    // ツリー上の位置が確かなドキュメントを、位置の分からないドキュメントで黙って上書きしないための保険
+    if (input.missingFromTree && input.alreadyWrittenThisRun) {
+        return 'skip-fallback-collision';
+    }
+    // 前回の更新日時チェック。親index・ツリーに現れないドキュメントは、そもそも過去のエクスポートで
+    // 取得できていない可能性があるため、ファイルが無い場合は未更新でもバックフィルとして保存する
+    const backfill = (input.asParentIndex || input.missingFromTree) && !input.fileExists;
+    if (input.lastUpdated && !backfill && new Date(input.updated) <= new Date(input.lastUpdated)) {
         return 'skip-unchanged';
     }
     if (input.asParentIndex && !input.body?.trim()) {
-        return input.parentIndexExists ? 'delete-stale-parent-index' : 'skip-empty-parent';
+        return input.fileExists ? 'delete-stale-parent-index' : 'skip-empty-parent';
     }
     return 'save';
 }

package/dist/modules/document/domain/document-tree-gap.d.ts

@@ -0,0 +1,2 @@
+import { DocumentSummary, DocumentTree } from './document.js';
+export declare function findDocumentsMissingFromTree(tree: DocumentTree, titlesById: Map<string, string>): DocumentSummary[];

package/dist/modules/document/domain/document-tree-gap.js

@@ -0,0 +1,21 @@
+// Backlogのドキュメントツリーは、作成後に一度も再保存されていないドキュメントを返さないことがある。
+// ツリーだけを辿るとそれらが構造的に取得できないため、全件が載る一覧APIとの差分で拾う。
+// ゴミ箱のドキュメントを復活させないよう、trashTreeに載っているものは差分から除く。
+export function findDocumentsMissingFromTree(tree, titlesById) {
+    const knownIds = new Set();
+    const collect = (nodes) => {
+        for (const node of nodes ?? []) {
+            knownIds.add(node.id);
+            collect(node.children);
+        }
+    };
+    collect(tree.activeTree.children);
+    collect(tree.trashTree?.children);
+    const missing = [];
+    for (const [id, title] of titlesById) {
+        if (!knownIds.has(id)) {
+            missing.push({ id, title });
+        }
+    }
+    return missing;
+}

package/dist/modules/document/domain/document.d.ts

@@ -11,6 +11,10 @@ export interface DocumentTree {
         children: DocumentNode[];
         id: string;
     };
+    trashTree?: {
+        children: DocumentNode[];
+        id: string;
+    };
 }
 export interface DocumentSummary {
     id: string;
@@ -34,7 +38,7 @@ export interface DocumentDetail {
     };
     emoji?: string;
     id: string;
-    json: string;
+    json: unknown;
     plain: string;
     statusId: number;
     tags: Array<{

package/dist/modules/document/use-case/export-documents.js

@@ -2,9 +2,10 @@ import path from 'node:path';
 import { writeProgress } from '../../../shared/console/progress.js';
 import { deleteFile, ensureDirectory, fileExists, fileSize, writeBinaryFile, writeMarkdownFile, } from '../../../shared/storage/markdown-store.js';
 import { appendLog } from '../../../shared/storage/update-log.js';
-import { buildDocumentMarkdown } from '../domain/document-markdown.js';
-import { documentAttachmentMarkdownLink, documentAttachmentRelativePath, documentFileName, documentFolderPath, documentUrl, PARENT_DOCUMENT_INDEX_FILENAME, } from '../domain/document-path.js';
+import { buildDocumentBody, buildDocumentMarkdown } from '../domain/document-markdown.js';
+import { DOCUMENT_FALLBACK_PARENT_PATH, documentAttachmentMarkdownLink, documentAttachmentRelativePath, documentFileName, documentFolderPath, documentUrl, PARENT_DOCUMENT_INDEX_FILENAME, } from '../domain/document-path.js';
 import { planDocumentSave } from '../domain/document-save-plan.js';
+import { findDocumentsMissingFromTree } from '../domain/document-tree-gap.js';
 export async function exportDocuments(deps, options) {
     const { documentRepository, logger } = deps;
     logger.log('ドキュメントの取得を開始します...');
@@ -13,13 +14,15 @@ export async function exportDocuments(deps, options) {
     logger.log('アクティブなドキュメントツリーを処理します...');
     const processedDocuments = [];
     const writtenFiles = new Set();
-    const fetchAndSaveDocument = async (node, currentPath, asParentIndex = false) => {
+    // 戻り値はファイルを書き出したかどうか（保存件数の集計に使う）
+    const fetchAndSaveDocument = async (node, currentPath, placement = {}) => {
+        const asParentIndex = placement.asParentIndex ?? false;
         try {
             if (processedDocuments.includes(node.id)) {
-                return;
+                return false;
             }
             if (options.documentIds && options.documentIds.length > 0 && !options.documentIds.includes(node.id)) {
-                return;
+                return false;
             }
             processedDocuments.push(node.id);
             writeProgress(`ドキュメント「${node.name}」を処理中...`);
@@ -27,11 +30,12 @@ export async function exportDocuments(deps, options) {
             const fileName = documentFileName(documentDetail.title, asParentIndex);
             const filePath = path.join(options.outputDir, currentPath, fileName);
             const action = planDocumentSave({
+                alreadyWrittenThisRun: writtenFiles.has(filePath),
                 asParentIndex,
-                body: documentDetail.plain,
+                body: buildDocumentBody(documentDetail),
+                fileExists: await fileExists(filePath),
                 lastUpdated: options.lastUpdated,
-                parentIndexAlreadyWrittenThisRun: writtenFiles.has(filePath),
-                parentIndexExists: asParentIndex && (await fileExists(filePath)),
+                missingFromTree: placement.missingFromTree ?? false,
                 updated: documentDetail.updated,
             });
             switch (action) {
@@ -48,6 +52,10 @@ export async function exportDocuments(deps, options) {
                     await writeMarkdownFile(filePath, buildDocumentMarkdown(documentDetail, backlogDocumentUrl, attachmentLinks));
                     writtenFiles.add(filePath);
                     await appendLog(options.outputDir, `ドキュメント「${documentDetail.title}」を更新しました: ${backlogDocumentUrl}`);
+                    return true;
+                }
+                case 'skip-fallback-collision': {
+                    logger.warn(`ツリーに現れないドキュメント「${documentDetail.title}」は、同名のファイルを既に出力しているため保存をスキップしました`);
                     break;
                 }
                 case 'skip-parent-index-collision': {
@@ -60,6 +68,7 @@ export async function exportDocuments(deps, options) {
         catch (error) {
             logger.warn(`ドキュメント ${node.name} の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
         }
+        return false;
     };
     /* eslint-disable no-await-in-loop */
     const processDocumentNode = async (node, currentPath) => {
@@ -70,7 +79,7 @@ export async function exportDocuments(deps, options) {
                 await processDocumentNode(child, folderRelPath);
             }
             // 親自身の本文はフォルダ内の親indexとして子の後に保存する
-            await fetchAndSaveDocument(node, folderRelPath, true);
+            await fetchAndSaveDocument(node, folderRelPath, { asParentIndex: true });
         }
         else {
             await fetchAndSaveDocument(node, currentPath);
@@ -79,10 +88,39 @@ export async function exportDocuments(deps, options) {
     for (const rootNode of documentTree.activeTree.children ?? []) {
         await processDocumentNode(rootNode, '');
     }
+    const missingFromTree = await findDocumentsOutsideTree(deps, documentTree, options, processedDocuments);
+    let savedMissingFromTree = 0;
+    for (const document of missingFromTree) {
+        const saved = await fetchAndSaveDocument({ children: [], id: document.id, name: document.title }, DOCUMENT_FALLBACK_PARENT_PATH, { missingFromTree: true });
+        if (saved) {
+            savedMissingFromTree++;
+        }
+    }
     /* eslint-enable no-await-in-loop */
+    // 検出件数ではなく実際に保存した件数を出す（未更新でスキップした分まで毎回報告しないため）
+    if (savedMissingFromTree > 0) {
+        logger.log(`ツリーに現れないドキュメント${savedMissingFromTree}件を出力ルート直下に保存しました`);
+    }
     logger.log(`\n合計 ${processedDocuments.length}件のドキュメントが処理されました。`);
     logger.log('ドキュメントのダウンロードが完了しました！');
 }
+// ツリーに現れないドキュメントを一覧API（全件が載る）との差分から求める。
+// 一覧の取得に失敗しても従来どおりツリー分のエクスポートは成立させるため、警告に留めて空を返す
+async function findDocumentsOutsideTree(deps, documentTree, options, processedDocuments) {
+    // ID指定の取得で対象がすべてツリー内に見つかっている場合は、一覧APIを呼ぶ必要がない
+    const targetedIds = options.documentIds && options.documentIds.length > 0 ? options.documentIds : undefined;
+    if (targetedIds?.every((id) => processedDocuments.includes(id))) {
+        return [];
+    }
+    try {
+        const titlesById = await deps.documentRepository.fetchAllTitles(options.projectId);
+        return findDocumentsMissingFromTree(documentTree, titlesById);
+    }
+    catch (error) {
+        deps.logger.warn(`ドキュメント一覧の取得に失敗したため、ツリーに現れないドキュメントの確認をスキップします: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
 // 保存できた添付のみリンク化する。個々の失敗は警告に留め、ドキュメント本体の保存は続行する
 async function downloadDocumentAttachments(deps, documentDetail, currentPath, outputDir) {
     const links = new Map();