backlog-exporter 1.1.1 → 1.3.0

package/README.md

@@ -42,7 +42,7 @@ $ npm install -g backlog-exporter
 $ backlog-exporter COMMAND
 running command...
 $ backlog-exporter (--version)
-backlog-exporter/1.1.1 linux-x64 node-v26.8.1
+backlog-exporter/1.3.0 linux-x64 node-v26.10.0
 $ backlog-exporter --help [COMMAND]
 USAGE
   $ backlog-exporter COMMAND
@@ -270,7 +270,8 @@ $ backlog-exporter issue --domain example.backlog.jp --projectIdOrKey PROJECT_KE
 - ファイル名は同名の衝突を避けるため `{添付ID}_{ファイル名}` になります
 - Markdown の `## 添付ファイル` セクションにローカルファイルへの相対リンクが記載されます（フラグ未指定時はファイル名とサイズのみ記載）
 - 課題の本文・コメント内の添付画像のインライン記法（`![image][ファイル名]` / `#image(ファイル名)`）は、ダウンロード済みファイルへの画像リンクに変換され、Markdown ビューアでそのまま表示できます
-- Wiki・ドキュメントの本文は Backlog の原文のまま維持されます（添付参照記法の書き換えは行いません）。添付ファイルへは `## 添付ファイル` セクションのリンクからアクセスできます
+- Wiki の本文は Backlog の原文のまま維持されます（添付参照記法の書き換えは行いません）。添付ファイルへは `## 添付ファイル` セクションのリンクからアクセスできます
+- ドキュメントの本文は Backlog の構造化データ（JSON）から Markdown に変換されます（見出し・リスト・表・コードブロック等を再現します）。構造化データを取得できない場合はプレーンテキストの本文をそのまま使用します。添付参照記法の書き換えは行わないため、添付ファイルへは `## 添付ファイル` セクションのリンクからアクセスできます
 - ダウンロード済みのファイルは再ダウンロードされないため、`update` コマンドでの差分更新でも効率的に動作します
 - 設定は `backlog-settings.json` に保存され、以降の `update` コマンドで自動的に引き継がれます（`update` コマンド自体でフラグを指定した場合はその実行のみ有効です）
 - Backlog 側で削除された添付ファイルは、誤削除防止のため `prune` コマンドでも削除されず残ります
@@ -302,13 +303,23 @@ $ backlog-exporter issue --domain example.backlog.jp --projectIdOrKey PROJECT_KE
 ## 基本情報
 
 - 課題キー: PROJ-123
+- 種別: タスク
+- カテゴリー: 設計, 実装
 - ステータス: 処理中
 - 優先度: 高
 - 担当者: 山田太郎
+- 親課題: [PROJ-100 親課題のタイトル](https://example.backlog.jp/view/PROJ-100)
+- 開始日: 2023/01/01
+- 期限日: 2023/01/31
 - 作成日時: 2023/01/01 10:00:00
 - 更新日時: 2023/01/02 15:30:45
 - [Backlog Issue Link](https://example.backlog.jp/view/PROJ-123)
 
+## 子課題
+
+- [PROJ-124 子課題のタイトル](https://example.backlog.jp/view/PROJ-124)
+- [PROJ-125 もう 1 つの子課題](https://example.backlog.jp/view/PROJ-125)
+
 ## カスタム属性
 
 | 属性名             | 値                             |
@@ -333,6 +344,15 @@ $ backlog-exporter issue --domain example.backlog.jp --projectIdOrKey PROJECT_KE
 コメントの内容がここに表示されます。
 ```
 
+**親課題・子課題について**:
+
+- 親課題がある場合のみ「親課題」の行を、子課題がある場合のみ「子課題」セクションを出力します
+- 3 階層（親課題・子課題・孫課題）にも対応しています。各ファイルは 1 つ上と 1 つ下の階層を出力するため、2 階層目の課題には「親課題」の行と「子課題」セクションの両方が出ます
+- 子課題は、プロジェクト全体のエクスポート（`issue` / `all`）では取得済みの課題から組み立てるため追加の API 呼び出しは発生しません。課題キーを指定した再取得（`update --issueIdOrKey`）でのみ API から取得します（対象課題を 100 件ずつまとめて引きます）
+- ID を指定しない差分更新（`update`）では、更新された課題に加えてその直接の親課題・子課題も書き直すため、子課題の追加や件名の変更は親子どちらのファイルにも反映されます。ただし親課題を変更・解除した子課題の元の親と、削除された子課題の親は書き直されないため、揃えるには `issue` / `all` で再エクスポートしてください
+- `--statusId` で状態を絞り込んだ場合、絞り込みから外れた子課題は「子課題」セクションに現れません
+- 親課題が別プロジェクトにあるなどで課題キーを解決できなかった場合は `- 親課題: (ID: 100)` のように課題 ID のみを出力します
+
 ### Wiki の出力形式
 
 ```markdown
@@ -363,7 +383,7 @@ Backlog の書式がそのまま保持されます。
 
 <!-- backlog-exporter:body:start -->
 ここにドキュメントの本文内容が入ります。
-Backlog の書式がそのまま保持されます。
+Backlog の構造化データから変換された Markdown が入ります。
 <!-- backlog-exporter:body:end -->
 
 ## 添付ファイル

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,415 @@
+const BLOCK_TYPES = new Set([
+    'blockquote',
+    'bulletList',
+    'codeBlock',
+    'heading',
+    'horizontalRule',
+    'orderedList',
+    'paragraph',
+    'table',
+    'taskList',
+]);
+// マーク適用順。codeは最内側に置き、他の記号がコードスパンの外に出るようにする
+const MARK_ORDER = ['code', 'bold', 'italic', 'strike', 'link'];
+function isNode(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isListNode(node) {
+    return node.type === 'bulletList' || node.type === 'orderedList' || node.type === 'taskList';
+}
+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 'documentMention': {
+                result += renderDocumentMention(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独自ノード。attrsにのみ値を持ち子ノードが無いためリンクに組み立てる
+function renderDocumentMention(node) {
+    const label = attrString(node, 'label') ?? attrString(node, 'title') ?? attrString(node, 'text') ?? renderInline(childNodes(node));
+    const url = attrString(node, 'url') ?? attrString(node, 'href');
+    const resolved = escapeBracketText(label.length > 0 ? label : 'ドキュメント');
+    return url ? `[${resolved}](${linkDestination(url)})` : 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');
+}
+// チェックボックス記法の継続行はリスト記号"- "の幅で字下げする。
+// マーカー全長(6桁)だとCommonMarkがコードブロックと解釈しネストが壊れる
+const TASK_ITEM_INDENT = 2;
+function renderListItem(node, marker, indentWidth = marker.length) {
+    const children = childNodes(node);
+    const rendered = children.map((child) => (isListNode(child) ? renderList(child) : renderBlock(child)));
+    let body = '';
+    for (const [index, block] of rendered.entries()) {
+        if (block === '')
+            continue;
+        if (body === '') {
+            body = block;
+            continue;
+        }
+        // 段落直後のネストリストはtight listとして1改行で繋ぐ
+        body += isListNode(children[index]) ? `\n${block}` : `\n\n${block}`;
+    }
+    if (body === '')
+        return marker.trimEnd();
+    const indent = ' '.repeat(indentWidth);
+    return body
+        .split('\n')
+        .map((line, index) => (index === 0 ? `${marker}${line}` : line === '' ? '' : `${indent}${line}`))
+        .join('\n');
+}
+function taskMarker(item) {
+    return item.attrs?.checked === true ? '- [x] ' : '- [ ] ';
+}
+function renderList(node) {
+    if (node.type === 'taskList') {
+        return childNodes(node)
+            .map((item) => renderListItem(item, taskMarker(item), TASK_ITEM_INDENT))
+            .join('\n');
+    }
+    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':
+        case 'taskList': {
+            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.d.ts

@@ -38,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,7 +2,7 @@ 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 { 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';
@@ -32,7 +32,7 @@ export async function exportDocuments(deps, options) {
             const action = planDocumentSave({
                 alreadyWrittenThisRun: writtenFiles.has(filePath),
                 asParentIndex,
-                body: documentDetail.plain,
+                body: buildDocumentBody(documentDetail),
                 fileExists: await fileExists(filePath),
                 lastUpdated: options.lastUpdated,
                 missingFromTree: placement.missingFromTree ?? false,

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

@@ -1,5 +1,15 @@
+import { IssueParent, IssueRef, IssueRelations } from './issue-relations.js';
 import { CustomField, Issue, IssueAttachment, IssueComment } from './issue.js';
 export declare function createCustomFieldsSection(customFields?: CustomField[]): string;
 export declare function buildAttachmentsSection(attachments: IssueAttachment[] | undefined, localLinks?: Map<number, string>): string;
 export declare function buildCommentsSection(comments: IssueComment[], backlogIssueUrl: string, rewriteBody?: (text: string) => string): string;
-export declare function buildIssueMarkdown(issue: Issue, comments: IssueComment[], backlogIssueUrl: string, attachmentLinks?: Map<number, string>): string;
+export declare function formatCategories(categories?: Issue['category']): string;
+export type IssueUrlResolver = (issueKey: string) => string;
+export declare function buildParentIssueLine(parent: IssueParent | null, issueUrl?: IssueUrlResolver): string;
+export declare function buildChildIssuesSection(children: IssueRef[], issueUrl?: IssueUrlResolver): string;
+export interface BuildIssueMarkdownOptions {
+    attachmentLinks?: Map<number, string>;
+    issueUrl?: IssueUrlResolver;
+    relations?: IssueRelations;
+}
+export declare function buildIssueMarkdown(issue: Issue, comments: IssueComment[], backlogIssueUrl: string, options?: BuildIssueMarkdownOptions): string;

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

@@ -99,11 +99,40 @@ export function buildCommentsSection(comments, backlogIssueUrl, rewriteBody = (t
     // 最後の区切り線を削除
     return commentsSection.slice(0, -5);
 }
-export function buildIssueMarkdown(issue, comments, backlogIssueUrl, attachmentLinks) {
+// Backlogのカテゴリーは複数設定できるため、カンマ区切りで並べる
+export function formatCategories(categories) {
+    if (!categories || categories.length === 0)
+        return '未設定';
+    return categories.map((category) => category.name).join(', ');
+}
+// URL解決関数が無い場合は壊れたリンクを書かないよう、ラベルだけを出す
+function issueRefLink(ref, issueUrl) {
+    const label = `${ref.issueKey} ${ref.summary}`.trim();
+    return issueUrl ? `[${escapeLinkText(label)}](${issueUrl(ref.issueKey)})` : label;
+}
+// 課題キーを解決できなかった親はリンクにできないため、Backlog上のIDだけを出す
+export function buildParentIssueLine(parent, issueUrl) {
+    if (!parent)
+        return '';
+    if (!parent.ref)
+        return `\n- 親課題: (ID: ${parent.parentIssueId})`;
+    return `\n- 親課題: ${issueRefLink(parent.ref, issueUrl)}`;
+}
+// 件数が可変なので基本情報の箇条書きではなく独立セクションにする
+export function buildChildIssuesSection(children, issueUrl) {
+    if (children.length === 0)
+        return '';
+    const lines = children.map((child) => `- ${issueRefLink(child, issueUrl)}`);
+    return `\n\n## 子課題\n\n${lines.join('\n')}`;
+}
+export function buildIssueMarkdown(issue, comments, backlogIssueUrl, options = {}) {
+    const { attachmentLinks, issueUrl, relations } = options;
     const rewriteBody = (text) => rewriteInlineImages(text, issue.attachments, attachmentLinks);
     const commentsSection = buildCommentsSection(comments, backlogIssueUrl, rewriteBody);
     const customFieldsSection = createCustomFieldsSection(issue.customFields);
     const attachmentsSection = buildAttachmentsSection(issue.attachments, attachmentLinks);
+    const parentIssueLine = buildParentIssueLine(relations?.parent ?? null, issueUrl);
+    const childIssuesSection = buildChildIssuesSection(relations?.children ?? [], issueUrl);
     const assigneeName = issue.assignee ? issue.assignee.name : '未割り当て';
     const startDate = issue.startDate ? new Date(issue.startDate).toLocaleDateString('ja-JP') : '未設定';
     const dueDate = issue.dueDate ? new Date(issue.dueDate).toLocaleDateString('ja-JP') : '未設定';
@@ -112,14 +141,15 @@ export function buildIssueMarkdown(issue, comments, backlogIssueUrl, attachmentL
 ## 基本情報
 - 課題キー: ${issue.issueKey}
 - 種別: ${issue.issueType.name}
+- カテゴリー: ${formatCategories(issue.category)}
 - ステータス: ${issue.status.name}
 - 優先度: ${issue.priority.name}
-- 担当者: ${assigneeName}
+- 担当者: ${assigneeName}${parentIssueLine}
 - 開始日: ${startDate}
 - 期限日: ${dueDate}
 - 作成日時: ${new Date(issue.created).toLocaleString('ja-JP')}
 - 更新日時: ${new Date(issue.updated).toLocaleString('ja-JP')}
-- [Backlog Issue Link](${backlogIssueUrl})${customFieldsSection}${attachmentsSection}
+- [Backlog Issue Link](${backlogIssueUrl})${childIssuesSection}${customFieldsSection}${attachmentsSection}
 
 ## 詳細
 

package/dist/modules/issue/domain/issue-relations.d.ts

@@ -0,0 +1,19 @@
+import { Issue } from './issue.js';
+export interface IssueRef {
+    issueKey: string;
+    summary: string;
+}
+export interface IssueParent {
+    parentIssueId: number;
+    ref: IssueRef | null;
+}
+export interface IssueRelations {
+    children: IssueRef[];
+    parent: IssueParent | null;
+}
+export declare function toIssueRef(issue: Pick<Issue, 'issueKey' | 'summary'>): IssueRef;
+export declare function buildIssueRefIndex(issues: Issue[]): Map<number, IssueRef>;
+export declare function buildChildIndex(issues: Issue[]): Map<number, IssueRef[]>;
+export declare function withParentsAndChildren(allIssues: Issue[], updatedIssues: Issue[]): Issue[];
+export declare function findChildren(issue: Issue, childIndex: Map<number, IssueRef[]>): IssueRef[];
+export declare function findParent(issue: Issue, refIndex: Map<number, IssueRef>): IssueParent | null;

package/dist/modules/issue/domain/issue-relations.js

@@ -0,0 +1,42 @@
+export function toIssueRef(issue) {
+    return { issueKey: issue.issueKey, summary: issue.summary };
+}
+export function buildIssueRefIndex(issues) {
+    return new Map(issues.map((issue) => [issue.id, toIssueRef(issue)]));
+}
+// parentIssueIdでグルーピングするだけなので、親子孫の3階層でもそのまま成立する
+export function buildChildIndex(issues) {
+    const childIndex = new Map();
+    // 一覧APIの返却順はソート指定に依存するため、Backlogの画面に合わせて課題ID昇順に固定する
+    for (const issue of [...issues].sort((a, b) => a.id - b.id)) {
+        if (issue.parentIssueId === null || issue.parentIssueId === undefined)
+            continue;
+        const siblings = childIndex.get(issue.parentIssueId);
+        if (siblings) {
+            siblings.push(toIssueRef(issue));
+        }
+        else {
+            childIndex.set(issue.parentIssueId, [toIssueRef(issue)]);
+        }
+    }
+    return childIndex;
+}
+// 課題のファイルには直接の親と子しか載らないため、更新された課題の上下1段を書き直せば親子の表示が揃う
+export function withParentsAndChildren(allIssues, updatedIssues) {
+    const updatedIds = new Set(updatedIssues.map((issue) => issue.id));
+    const parentIds = new Set(updatedIssues
+        .map((issue) => issue.parentIssueId)
+        .filter((parentIssueId) => parentIssueId !== null));
+    return allIssues.filter((issue) => updatedIds.has(issue.id) ||
+        parentIds.has(issue.id) ||
+        (issue.parentIssueId !== null && updatedIds.has(issue.parentIssueId)));
+}
+export function findChildren(issue, childIndex) {
+    return childIndex.get(issue.id) ?? [];
+}
+export function findParent(issue, refIndex) {
+    const parentIssueId = issue.parentIssueId ?? null;
+    if (parentIssueId === null)
+        return null;
+    return { parentIssueId, ref: refIndex.get(parentIssueId) ?? null };
+}

package/dist/modules/issue/domain/issue-repository.d.ts

@@ -3,6 +3,8 @@ export interface IssueRepository {
     downloadAttachment(issueIdOrKey: string, attachmentId: number): Promise<ArrayBuffer>;
     fetchAllComments(issueKey: string): Promise<IssueComment[]>;
     fetchByIdOrKey(issueIdOrKey: string): Promise<Issue>;
+    fetchByIds(ids: number[]): Promise<Issue[]>;
+    fetchChildren(parentIssueIds: number[]): Promise<Issue[]>;
     fetchPage(options: {
         count: number;
         offset: number;

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

@@ -4,6 +4,7 @@ export interface Issue {
         name: string;
     };
     attachments?: IssueAttachment[];
+    category: IssueCategory[];
     created: string;
     customFields: CustomField[];
     description: string;
@@ -14,6 +15,7 @@ export interface Issue {
         id: number;
         name: string;
     };
+    parentIssueId: null | number;
     priority: {
         id: number;
         name: string;
@@ -31,6 +33,10 @@ export interface IssueAttachment {
     name: string;
     size: number;
 }
+export interface IssueCategory {
+    id: number;
+    name: string;
+}
 export interface CustomField {
     id: number;
     name: string;

package/dist/modules/issue/repository/backlog-issue-repository.js

@@ -1,3 +1,11 @@
+const PAGE_SIZE = 100;
+function listParams(key, values, offset) {
+    return {
+        count: PAGE_SIZE.toString(),
+        [key]: values.map((value) => value.toString()),
+        offset: offset.toString(),
+    };
+}
 export function newBacklogIssueRepository(client) {
     return {
         async downloadAttachment(issueIdOrKey, attachmentId) {
@@ -26,6 +34,22 @@ export function newBacklogIssueRepository(client) {
         async fetchByIdOrKey(issueIdOrKey) {
             return client.getJson(`/issues/${issueIdOrKey}`);
         },
+        async fetchByIds(ids) {
+            return client.getJson('/issues', listParams('id[]', ids, 0));
+        },
+        // 課題キー指定エクスポートのように取得済み集合に子が含まれない場合の補完用。
+        // 複数の親をまとめて指定できるため、課題ごとではなく一括で引く
+        async fetchChildren(parentIssueIds) {
+            const children = [];
+            for (;;) {
+                // eslint-disable-next-line no-await-in-loop
+                const page = await client.getJson('/issues', listParams('parentIssueId[]', parentIssueIds, children.length));
+                children.push(...page);
+                if (page.length < PAGE_SIZE) {
+                    return children;
+                }
+            }
+        },
         async fetchPage(options) {
             const params = {
                 count: options.count.toString(),

package/dist/modules/issue/use-case/export-issues.js

@@ -5,6 +5,9 @@ import { appendLog } from '../../../shared/storage/update-log.js';
 import { filterIssuesUpdatedSince } from '../domain/issue-filter.js';
 import { buildIssueMarkdown } from '../domain/issue-markdown.js';
 import { attachmentMarkdownLink, attachmentRelativePath, issueRelativePath, issueUrl } from '../domain/issue-path.js';
+import { buildChildIndex, buildIssueRefIndex, findChildren, findParent, withParentsAndChildren, } from '../domain/issue-relations.js';
+// Backlogの配列パラメータの上限に合わせ、一括取得は100件ずつに分ける
+const BULK_FETCH_SIZE = 100;
 export async function exportIssues(deps, options) {
     const { logger } = deps;
     logger.log('課題の取得を開始します...');
@@ -20,12 +23,18 @@ export async function exportIssues(deps, options) {
         logger.log('更新が必要な課題はありません。');
         return;
     }
+    const updatedIssueIds = new Set(filteredIssues.map((issue) => issue.id));
+    const targetIssues = withParentsAndChildren(allIssues, filteredIssues);
+    if (targetIssues.length > filteredIssues.length) {
+        logger.log(`親子の表示を揃えるため、${targetIssues.length - filteredIssues.length}件の課題もあわせて書き直します。`);
+    }
     logger.log('課題を保存しています...');
-    for (const [index, issue] of filteredIssues.entries()) {
+    const relationIndex = await buildRelationIndex(deps, allIssues, targetIssues, options);
+    for (const [index, issue] of targetIssues.entries()) {
         try {
-            writeProgress(`課題を保存中... (${index + 1}/${filteredIssues.length}件)`);
+            writeProgress(`課題を保存中... (${index + 1}/${targetIssues.length}件)`);
             // eslint-disable-next-line no-await-in-loop
-            await saveIssue(deps, issue, options);
+            await saveIssue(deps, issue, options, { relationIndex, relationOnly: !updatedIssueIds.has(issue.id) });
         }
         catch (error) {
             logger.warn(`課題 ${issue.issueKey} の保存に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
@@ -71,23 +80,85 @@ async function fetchAllIssues(deps, options) {
     }
     return issues;
 }
-async function saveIssue(deps, issue, options) {
+async function saveIssue(deps, issue, options, { relationIndex, relationOnly }) {
     const backlogIssueUrl = issueUrl(options.domain, issue.issueKey);
-    // コメント取得に失敗しても課題本体は保存する
     let comments = [];
     try {
         comments = await deps.issueRepository.fetchAllComments(issue.issueKey);
     }
     catch (error) {
-        deps.logger.warn(`課題 ${issue.issueKey} のコメント取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
+        const reason = error instanceof Error ? error.message : String(error);
+        // 更新された課題はコメントが欠けても本体を保存するが、親子の表示を揃えるためだけの書き直しでは既存のファイルを残す
+        if (relationOnly) {
+            deps.logger.warn(`課題 ${issue.issueKey} のコメント取得に失敗したため、親子の表示の更新を見送りました: ${reason}`);
+            return;
+        }
+        deps.logger.warn(`課題 ${issue.issueKey} のコメント取得に失敗しました: ${reason}`);
     }
-    const attachmentLinks = options.downloadAttachments
-        ? await downloadIssueAttachments(deps, issue, options)
-        : undefined;
+    const attachmentLinks = options.downloadAttachments ? await downloadIssueAttachments(deps, issue, options) : undefined;
     const filePath = path.join(options.outputDir, issueRelativePath(issue, options));
-    await writeMarkdownFile(filePath, buildIssueMarkdown(issue, comments, backlogIssueUrl, attachmentLinks));
+    await writeMarkdownFile(filePath, buildIssueMarkdown(issue, comments, backlogIssueUrl, {
+        attachmentLinks,
+        issueUrl: (issueKey) => issueUrl(options.domain, issueKey),
+        relations: {
+            children: findChildren(issue, relationIndex.childIndex),
+            parent: findParent(issue, relationIndex.refIndex),
+        },
+    }));
     await appendLog(options.outputDir, `課題「${issue.summary}」を更新しました: ${backlogIssueUrl}`);
 }
+// 取得済みの課題だけでは足りない親子をAPIで補い、索引を組み立てる。
+// 課題ごとに引くとN+1になるため、いずれも配列パラメータでまとめて取得する。
+// 補完に失敗しても課題本体の保存は続行する（関連情報が欠けるだけに留める）
+async function buildRelationIndex(deps, allIssues, targets, options) {
+    const sources = [...allIssues];
+    // 課題キー指定では取得済み集合に子が含まれないため、対象課題の子をまとめて引く
+    if (options.issueIdOrKeys && options.issueIdOrKeys.length > 0) {
+        sources.push(...(await fetchChildrenOf(deps, targets)));
+    }
+    sources.push(...(await fetchMissingParents(deps, targets, buildIssueRefIndex(sources))));
+    return { childIndex: buildChildIndex(sources), refIndex: buildIssueRefIndex(sources) };
+}
+async function fetchChildrenOf(deps, targets) {
+    const children = [];
+    for (const ids of chunkIds(targets.map((target) => target.id))) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            children.push(...(await deps.issueRepository.fetchChildren(ids)));
+        }
+        catch (error) {
+            deps.logger.warn(`子課題の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return children;
+}
+// 別プロジェクトの親やstatusIdで絞り込まれた親は取得済み集合に現れないため、IDから引き直す
+async function fetchMissingParents(deps, targets, refIndex) {
+    const missingIds = [
+        ...new Set(targets
+            .map((target) => target.parentIssueId)
+            .filter((parentIssueId) => typeof parentIssueId === 'number')
+            .filter((parentIssueId) => !refIndex.has(parentIssueId))),
+    ];
+    const parents = [];
+    for (const ids of chunkIds(missingIds)) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            parents.push(...(await deps.issueRepository.fetchByIds(ids)));
+        }
+        catch (error) {
+            deps.logger.warn(`親課題の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return parents;
+}
+function chunkIds(ids) {
+    const chunks = [];
+    for (let index = 0; index < ids.length; index += BULK_FETCH_SIZE) {
+        chunks.push(ids.slice(index, index + BULK_FETCH_SIZE));
+    }
+    return chunks;
+}
 // 保存できた添付のみリンク化する。個々の失敗は警告に留め、課題本体の保存は続行する
 async function downloadIssueAttachments(deps, issue, options) {
     const links = new Map();

package/dist/shared/backlog/http-client.d.ts

@@ -2,6 +2,7 @@ export declare class HttpError extends Error {
     readonly status: number;
     constructor(status: number, statusText: string, url: string);
 }
+export type QueryParams = Record<string, string | string[]>;
 export declare function rateLimitWaitMs(resetHeader: null | string, nowMs: number): number;
 export declare class BacklogHttpClient {
     private readonly apiKey;
@@ -12,8 +13,8 @@ export declare class BacklogHttpClient {
         domain: string;
         onRateLimitExceeded?: (waitSeconds: number) => void;
     });
-    getBinary(pathname: string, params?: Record<string, string>): Promise<ArrayBuffer>;
-    getJson<T>(pathname: string, params?: Record<string, string>): Promise<T>;
+    getBinary(pathname: string, params?: QueryParams): Promise<ArrayBuffer>;
+    getJson<T>(pathname: string, params?: QueryParams): Promise<T>;
     private fetchWithRetry;
     private maskApiKey;
     private requestUrl;

package/dist/shared/backlog/http-client.js

@@ -87,7 +87,12 @@ export class BacklogHttpClient {
         return url.replace(/apiKey=[^&]*/, 'apiKey=***');
     }
     requestUrl(pathname, params) {
-        const searchParams = new URLSearchParams({ apiKey: this.apiKey, ...params });
+        const searchParams = new URLSearchParams({ apiKey: this.apiKey });
+        for (const [key, value] of Object.entries(params)) {
+            for (const item of Array.isArray(value) ? value : [value]) {
+                searchParams.append(key, item);
+            }
+        }
         return `${this.baseUrl}${pathname}?${searchParams.toString()}`;
     }
 }

package/oclif.manifest.json

@@ -566,5 +566,5 @@
       ]
     }
   },
-  "version": "1.1.1"
+  "version": "1.3.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "backlog-exporter",
   "description": "A new CLI generated with oclif",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "author": "ShuntaToda",
   "bin": {
     "backlog-exporter": "bin/run.js"