ai-git-tools 2.1.13 → 2.1.15

package/src/redmine/subtask-formatters.js

@@ -0,0 +1,499 @@
+import chalk from 'chalk';
+
+const MANAGED_KEY_PREFIX = 'ai-git-tools:redmine-subtask';
+const FRONTEND_MERMAID_PATTERN = /^(flowchart|graph|sequenceDiagram|stateDiagram(?:-v2)?|classDiagram|erDiagram|journey)\b/m;
+
+function asString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function asStringArray(value) {
+  return Array.isArray(value)
+    ? value.filter(item => typeof item === 'string').map(item => item.trim()).filter(Boolean)
+    : [];
+}
+
+function bulletList(items) {
+  return asStringArray(items).map(item => `- ${item}`).join('\n');
+}
+
+function addSection(sections, title, body) {
+  const content = asString(body);
+  if (content) sections.push(`## ${title}\n\n${content}`);
+}
+
+function formatScope(subtask) {
+  const parts = [];
+  if (subtask.inScope?.length) parts.push(`### 包含\n${bulletList(subtask.inScope)}`);
+  if (subtask.outOfScope?.length) parts.push(`### 不包含\n${bulletList(subtask.outOfScope)}`);
+  return parts.join('\n\n');
+}
+
+function formatBehaviorRules(rules) {
+  const rows = Array.isArray(rules)
+    ? rules
+      .filter(rule => rule?.scenario && rule?.behavior)
+      .map(rule => `| ${String(rule.scenario).replaceAll('|', '\\|')} | ${String(rule.behavior).replaceAll('|', '\\|')} |`)
+    : [];
+  return rows.length > 0 ? `| 情境 | 行為 |\n|---|---|\n${rows.join('\n')}` : '';
+}
+
+function formatMermaid(source) {
+  let cleanSource = asString(source)
+    .replace(/^```mermaid\s*/i, '')
+    .replace(/^```\s*/, '')
+    .replace(/\s*```$/, '')
+    .replace(/^\{\{\s*mermaid\s*/i, '')
+    .replace(/\s*\}\}\s*$/, '')
+    .trim();
+  if (!cleanSource || cleanSource.includes('{{mermaid') || cleanSource.includes('}}')) return '';
+  if (!/^(flowchart|graph|sequenceDiagram|stateDiagram(?:-v2)?|classDiagram|erDiagram|journey)\b/m.test(cleanSource)) return '';
+  return `{{mermaid\n${cleanSource}\n}}`;
+}
+
+function formatFlowcharts(flowcharts) {
+  if (!Array.isArray(flowcharts)) return '';
+  return flowcharts
+    .map(flowchart => {
+      const mermaid = formatMermaid(flowchart?.source);
+      if (!mermaid) return '';
+      const title = asString(flowchart.title) || '流程';
+      const id = asString(flowchart.id) || 'flowchart-1';
+      return `### ${title}\n\n<!-- flowchart-id: ${id} -->\n${mermaid}`;
+    })
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function formatWireframe(wireframe) {
+  const value = asString(wireframe);
+  return value ? `\`\`\`text\n${value}\n\`\`\`` : '';
+}
+
+function normalizeApiPathPlaceholders(value) {
+  return value.replace(/(\/[^{}\s()[\]]*?)\{([A-Za-z][A-Za-z0-9_-]*)\}/g, '$1:$2');
+}
+
+function isFrontendSubtask(subtask = {}) {
+  return Boolean(
+    subtask.type === 'page'
+      || subtask.type === 'feature'
+      || subtask.type === 'shared-infrastructure'
+      || subtask.requirementDescription
+      || subtask.uiWireframe?.screens
+      || subtask.apiContract
+  );
+}
+
+function formatFrontendItem(item, fallback = '') {
+  if (typeof item === 'string') return item;
+  if (!item || typeof item !== 'object') return fallback;
+  const text = asString(item.text || item.value || item.description || item.quote || item.expected || item.behavior);
+  if (!text) return fallback;
+  const source = asString(item.source);
+  const evidenceIds = Array.isArray(item.evidenceIds) && item.evidenceIds.length
+    ? ` [${item.evidenceIds.join(', ')}]`
+    : '';
+  return `${text}${source ? `（${source}）` : ''}${evidenceIds}`;
+}
+
+function formatFrontendItems(items = []) {
+  return (Array.isArray(items) ? items : [])
+    .map(item => formatFrontendItem(item))
+    .filter(Boolean)
+    .map(item => `- ${item}`)
+    .join('\n');
+}
+
+function formatFrontendObject(value) {
+  if (value === null || value === undefined || value === '') return '未提供';
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value, null, 2);
+}
+
+function formatFrontendScope(scopeDecision = {}) {
+  const lines = [`## Frontend 範圍`, '', `- 分析狀態：${asString(scopeDecision.status) || '未判定'}`];
+  const included = formatFrontendItems(scopeDecision.includedRequirements);
+  const excluded = formatFrontendItems(scopeDecision.excludedRequirements);
+  if (included) lines.push('', '### 納入 Frontend', included);
+  if (excluded) lines.push('', '### 排除項目', excluded);
+  return lines.join('\n');
+}
+
+function formatFrontendRoutes(routes = []) {
+  if (!Array.isArray(routes) || routes.length === 0) return '';
+  const rows = routes.map(route => [
+    route.id || '—',
+    route.path || '未提供',
+    route.purpose || '未提供',
+    route.accessRole || '未指定',
+    route.source || 'derived',
+  ].map(value => String(value).replaceAll('|', '\\|')));
+  return [
+    '### Routes',
+    '',
+    '| ID | Path | 用途 | 存取角色 | 來源 |',
+    '|---|---|---|---|---|',
+    ...rows.map(row => `| ${row.join(' | ')} |`),
+  ].join('\n');
+}
+
+function formatFrontendScreens(wireframe = {}) {
+  if (!Array.isArray(wireframe.screens) || wireframe.screens.length === 0) return '';
+  const screens = wireframe.screens.map(screen => [
+      `#### Screen：${screen.title || screen.id || '未命名'}（${screen.screenType || 'custom'}）`,
+      `- Screen ID：${screen.id || '—'}`,
+      `- Route ID：${screen.routeId || '未指定'}`,
+      `- 用途：${screen.purpose || '未提供'}`,
+      screen.regions?.length ? `- 區塊：${screen.regions.join('、')}` : '',
+      screen.controls?.length ? `- 操作：${screen.controls.join('、')}` : '',
+      screen.states?.length ? `- 狀態：${screen.states.join('、')}` : '',
+      screen.wireframe ? `- 來源：${screen.source || 'derived'}\n\n\`\`\`text\n${screen.wireframe}\n\`\`\`` : '- Wireframe：未提供',
+      screen.unresolvedItems?.length
+        ? `- 畫面待確認：${screen.unresolvedItems.join('、')}`
+        : ''
+    ].filter(Boolean).join('\n'));
+  return ['### Screens', ...screens].join('\n\n');
+}
+
+function formatFrontendUserFlow(userFlow = []) {
+  if (!Array.isArray(userFlow) || userFlow.length === 0) return '';
+  const rows = userFlow.map(flow => [
+    flow.step || '—',
+    flow.actor || '未指定',
+    flow.action || '未提供',
+    flow.systemResponse || '未提供',
+    flow.branch || '—',
+    flow.source || 'derived',
+  ].map(value => String(value).replaceAll('|', '\\|')));
+  return [
+    '## 使用者流程',
+    '',
+    '| 步驟 | 角色 | 操作 | 系統回應 | 分支 | 來源 |',
+    '|---|---|---|---|---|---|',
+    ...rows.map(row => `| ${row.join(' | ')} |`),
+  ].join('\n');
+}
+
+function formatFrontendMermaid(mermaid = {}) {
+  if (!mermaid || typeof mermaid !== 'object') return '';
+  let diagram = asString(mermaid.diagram);
+  if (diagram) {
+    diagram = diagram
+      .replace(/^```mermaid\s*/i, '')
+      .replace(/\s*```$/, '')
+      .replace(/^\{\{\s*mermaid\s*/i, '')
+      .replace(/\s*\}\}\s*$/, '')
+      .replace(/\r\n/g, '\n');
+    diagram = normalizeApiPathPlaceholders(diagram)
+      .trim();
+  }
+  const hasUnsupportedType = Boolean(diagram) && !FRONTEND_MERMAID_PATTERN.test(diagram);
+  if (hasUnsupportedType) diagram = '';
+  const status = hasUnsupportedType
+    ? 'unknown'
+    : asString(mermaid.status) || (diagram ? 'ready' : 'not-supported');
+  const title = asString(mermaid.title) || 'Frontend 流程';
+  const evidence = mermaid.evidenceIds?.length ? `\n依據：${mermaid.evidenceIds.join('、')}` : '';
+  const reason = mermaid.reason
+    ? `\n原因：${mermaid.reason}`
+    : hasUnsupportedType ? '\n原因：不支援的 Mermaid diagram type' : '';
+  return [
+    '## Mermaid 流程圖',
+    '',
+    `### ${title}`,
+    '',
+    `- Diagram ID：${mermaid.id || 'flowchart-1'}`,
+    `- Status：${status}`,
+    diagram ? `\n{{mermaid\n${diagram}\n}}` : '',
+    evidence,
+    reason,
+  ].filter(Boolean).join('\n');
+}
+
+function formatFrontendApiContracts(apiContracts = [], requestResponses = []) {
+  if (!Array.isArray(apiContracts) || apiContracts.length === 0) return '';
+  const sections = ['## API Contracts'];
+  for (const api of apiContracts) {
+    const requestResponse = requestResponses.find(item => item.apiId === api.id);
+    const requestExample = requestResponse?.requestExample || '';
+    const responseExample = requestResponse?.responseExample || '';
+    sections.push(
+      '',
+      `### ${api.method || '未提供'} ${api.baseUrl || ''}${api.path || '未提供'}`.trim(),
+      `- API ID：${api.id || '—'}`,
+      `- 用途：${api.purpose || '未提供'}`,
+      `- Auth：${api.auth || '未提供'}`,
+      `- Completeness：${api.completeness || 'partial'}`,
+      '',
+      '#### Request',
+      `- Path params：${formatFrontendObject(api.request?.pathParams)}`,
+      `- Query：${formatFrontendObject(api.request?.query)}`,
+      `- Headers：${formatFrontendObject(api.request?.headers)}`,
+      `- Body：${formatFrontendObject(api.request?.body)}`,
+      `- requestExample：${formatFrontendObject(requestExample)}`,
+      '',
+      '#### Response',
+      `- Status codes：${formatFrontendObject(api.statusCodes)}`,
+      `- Headers：${formatFrontendObject(api.response?.headers)}`,
+      `- Body：${formatFrontendObject(api.response?.body)}`,
+      `- responseExample：${formatFrontendObject(responseExample)}`,
+      `- Errors：${formatFrontendObject(api.errors)}`,
+      `- pagination：${formatFrontendObject(api.pagination)}`,
+      `- filtering：${formatFrontendObject(api.filtering)}`,
+      `- sorting：${formatFrontendObject(api.sorting)}`,
+      `- Evidence：${api.evidenceIds?.length ? api.evidenceIds.join('、') : '未提供'}`
+    );
+  }
+  return sections.join('\n');
+}
+
+function formatFrontendBehavior(subtask) {
+  const sections = [];
+  const state = formatFrontendItems(subtask.state);
+  const validation = formatFrontendItems(subtask.validation);
+  const errors = (subtask.errorHandling || [])
+    .map(item => `- ${item.case || item.scenario || '錯誤情境'}：${item.behavior || item.expected || '未提供'}`)
+    .join('\n');
+  if (state || validation || errors) {
+    sections.push(
+      [
+        '## 狀態與互動',
+        state ? `### State\n${state}` : '',
+        validation ? `### Validation\n${validation}` : '',
+        errors ? `### Error handling\n${errors}` : '',
+      ].filter(Boolean).join('\n\n')
+    );
+  }
+  const optionalSections = [
+    ['Permission/Auth', [subtask.permission, subtask.authentication, subtask.authorization].filter(Boolean).join('\n')],
+    ['Responsive', subtask.responsiveRequirement],
+    ['Accessibility', formatFrontendItems(subtask.accessibilityRequirement)],
+    ['i18n', formatFrontendItems(subtask.i18nRequirement)],
+    ['Performance', formatFrontendItems(subtask.performanceRequirement)],
+    ['Security', formatFrontendItems(subtask.securityRequirement)],
+    ['Analytics', formatFrontendItems(subtask.analyticsRequirement)],
+    ['Browser compatibility', formatFrontendItems(subtask.browserCompatibility)],
+    ['Cache', subtask.cache],
+    ['Polling', subtask.polling],
+    ['Feature flag', subtask.featureFlag],
+  ];
+  for (const [title, body] of optionalSections) {
+    if (body) sections.push(`### ${title}\n${body}`);
+  }
+  return sections.join('\n\n');
+}
+
+function formatFrontendAcceptance(items = []) {
+  const content = formatFrontendItems(items);
+  return content ? `## 驗收條件\n\n${content}` : '';
+}
+
+function formatFrontendTestPlan(items = []) {
+  if (!Array.isArray(items) || items.length === 0) return '';
+  const content = items.map(item => {
+    const scenario = item.scenario || item.case || '未命名情境';
+    const expected = item.expected || item.behavior || '未提供';
+    return `- ${scenario}（${item.layer || '未指定'}）：${expected}${item.source ? `（${item.source}）` : ''}`;
+  }).join('\n');
+  return `## Test Plan\n\n${content}`;
+}
+
+function formatFrontendEvidence(ids = [], evidence = []) {
+  const byId = new Map((Array.isArray(evidence) ? evidence : []).map(item => [item.id, item]));
+  return (Array.isArray(ids) ? ids : [])
+    .map(id => {
+      const item = byId.get(id);
+      if (!item) return `- ${id}`;
+      const location = item.location ? `（${item.location}）` : '';
+      return `- [${id}] ${item.source || 'unknown'}：${item.quote || '未提供'}${location}`;
+    })
+    .join('\n');
+}
+
+function collectFrontendEvidenceIds(value, result = new Set()) {
+  if (Array.isArray(value)) {
+    value.forEach(item => collectFrontendEvidenceIds(item, result));
+    return result;
+  }
+  if (!value || typeof value !== 'object') return result;
+  if (Array.isArray(value.evidenceIds)) value.evidenceIds.forEach(id => result.add(id));
+  Object.entries(value)
+    .filter(([key]) => key !== 'evidenceIds')
+    .forEach(([, item]) => collectFrontendEvidenceIds(item, result));
+  return result;
+}
+
+function formatFrontendContent({ subtask, parentIssueId, scopeDecision = {}, evidence = [] }) {
+  const routes = formatFrontendRoutes(subtask.route);
+  const screens = formatFrontendScreens(subtask.uiWireframe);
+  const evidenceIdSet = collectFrontendEvidenceIds({ scopeDecision, subtask });
+  for (const item of [
+    ...(scopeDecision.includedRequirements || []),
+    ...(scopeDecision.excludedRequirements || []),
+  ]) {
+    if (item?.evidenceIds?.length) item.evidenceIds.forEach(id => evidenceIdSet.add(id));
+    else if (item?.id) evidenceIdSet.add(item.id);
+  }
+  const evidenceIds = [...evidenceIdSet];
+  const sections = [
+    formatFrontendScope(scopeDecision),
+    `## 需求說明\n\n${subtask.requirementDescription}`,
+    `## 功能需求\n\n${formatFrontendItems(subtask.functionalRequirements)}`,
+    `## 工作範圍\n\n${formatFrontendItems(subtask.scope?.inScope) || '- 未提供'}${subtask.scope?.outOfScope?.length ? `\n\n### 不包含\n${formatFrontendItems(subtask.scope.outOfScope)}` : ''}`,
+    routes || screens ? `## Screens 與 Routes\n\n${[routes, screens].filter(Boolean).join('\n\n')}` : '',
+    formatFrontendUserFlow(subtask.userFlow),
+    formatFrontendMermaid(subtask.mermaid),
+    formatFrontendApiContracts(subtask.apiContract, subtask.requestResponse),
+    formatFrontendBehavior(subtask),
+    subtask.frontendTechnicalConstraint?.length
+      ? `## Frontend 技術限制\n\n${formatFrontendItems(subtask.frontendTechnicalConstraint)}`
+      : '',
+    `## 依賴與開發順序\n\n- Development order：${subtask.developmentOrder || '未提供'}\n- Dependencies：${subtask.dependsOnIds?.length ? subtask.dependsOnIds.join('、') : '無'}`,
+    formatFrontendAcceptance(subtask.acceptanceCriteria),
+    formatFrontendTestPlan(subtask.testPlan),
+    subtask.unresolvedItems?.length
+      ? `## 待確認事項\n\n${subtask.unresolvedItems.map(item => `- [ ] ${item}`).join('\n')}`
+      : '',
+    evidenceIds.length
+      ? `## Evidence\n\n${formatFrontendEvidence(evidenceIds, evidence)}`
+      : '',
+    `<!-- ${buildManagedSubtaskKey(parentIssueId, subtask.id)} -->`,
+  ];
+  return sections.filter(Boolean).join('\n\n').trim();
+}
+
+/**
+ * 建立受控的子任務識別字串
+ * @param {number|string} parentIssueId
+ * @param {string} key
+ * @returns {string}
+ */
+export function buildManagedSubtaskKey(parentIssueId, key) {
+  return `${MANAGED_KEY_PREFIX} parent=${parentIssueId} key=${asString(key)}`;
+}
+
+/**
+ * 從子任務 description 讀取受控識別字串
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function getManagedSubtaskKey(content = '') {
+  const match = String(content).match(/<!--\s*(ai-git-tools:redmine-subtask parent=\S+ key=\S+)\s*-->/);
+  return match?.[1] || null;
+}
+
+/**
+ * 將單一候選子任務格式化為 Redmine description
+ * @param {{subtask: object, parentIssueId: number|string}} input
+ * @returns {string}
+ */
+export function formatSubtaskContent({ subtask = {}, parentIssueId, scopeDecision = {}, evidence = [] }) {
+  if (isFrontendSubtask(subtask)) {
+    return formatFrontendContent({ subtask, parentIssueId, scopeDecision, evidence });
+  }
+  const sections = [];
+  addSection(sections, '目的', subtask.purpose);
+  addSection(sections, '工作範圍', formatScope(subtask));
+  addSection(sections, '實作重點', bulletList(subtask.implementationDetails));
+  addSection(sections, '行為規則', formatBehaviorRules(subtask.behaviorRules));
+  addSection(sections, '驗收條件', bulletList(subtask.acceptanceCriteria));
+
+  const dependencies = bulletList(subtask.dependsOnKeys);
+  const unresolvedItems = asStringArray(subtask.unresolvedItems);
+  const dependencyParts = [];
+  if (dependencies) dependencyParts.push(`### 依賴\n${dependencies}`);
+  if (unresolvedItems.length) {
+    dependencyParts.push(`### 待確認\n${unresolvedItems.map(item => `- [ ] ${item}`).join('\n')}`);
+  }
+  addSection(sections, '依賴與待確認', dependencyParts.join('\n\n'));
+  addSection(sections, '流程圖', formatFlowcharts(subtask.flowcharts));
+  addSection(sections, 'Wireframe', formatWireframe(subtask.wireframe));
+  addSection(sections, '證據', bulletList(subtask.evidence));
+
+  sections.push(`<!-- ${buildManagedSubtaskKey(parentIssueId, subtask.key)} -->`);
+  return sections.join('\n\n').trim();
+}
+
+function formatFrontendPreview({ parent = {}, candidates = [], scopeDecision = {}, analysisScope = 'frontend' }) {
+  const lines = [
+    chalk.bold.cyan('═'.repeat(72)),
+    chalk.bold('Redmine Frontend 子任務拆分預覽'),
+    chalk.bold.cyan('═'.repeat(72)),
+    '',
+    chalk.bold.cyan(`Issue #${parent.id || '—'}：${parent.subject || '無標題'}`),
+    `Analysis scope：${analysisScope}`,
+    `Scope decision：${scopeDecision.status || '未判定'}`,
+    scopeDecision.excludedRequirements?.length
+      ? `排除項目：${scopeDecision.excludedRequirements.map(item => item.quote || item.text).filter(Boolean).join('、')}`
+      : '排除項目：無',
+    '既有子任務：',
+  ];
+
+  if (parent.children?.length) {
+    for (const child of parent.children) lines.push(`- #${child.id} ${child.subject || '無標題'}`);
+  } else {
+    lines.push('- 無');
+  }
+
+  for (const [index, candidate] of candidates.entries()) {
+    const screens = candidate.uiWireframe?.screens || [];
+    const apiStatuses = (candidate.apiContract || []).map(api => api.completeness || 'partial');
+    const evidenceIds = candidate.evidenceIds?.length ? candidate.evidenceIds : candidate.evidence || [];
+    lines.push(
+      '',
+      chalk.bold.green(`[${index + 1}/${candidates.length}] ${candidate.title || '無標題'}`),
+      `類型：${candidate.type || '—'}`,
+      `Screens：${screens.length ? screens.map(screen => `${screen.id}（${screen.screenType}）`).join('、') : '無'}`,
+      `API completeness：${apiStatuses.length ? apiStatuses.join('、') : '無 API'}`,
+      `Mermaid：${candidate.mermaid?.status || '未提供'}`,
+      evidenceIds.length ? `依據：${evidenceIds.join('、')}` : '依據：未提供',
+      candidate.unresolvedItems?.length ? `待確認：${candidate.unresolvedItems.join('、')}` : '待確認：無',
+      candidate.content || '',
+      chalk.dim('─'.repeat(72))
+    );
+  }
+
+  lines.push('', chalk.yellow('尚未修改 Redmine。請審核 Frontend scope、screens、API 與 content 後再使用 --apply。'));
+  return lines.join('\n').trim();
+}
+
+/**
+ * 產生主 Issue 子任務 terminal preview
+ * @param {{parent: object, candidates: Array<object>}} input
+ * @returns {string}
+ */
+export function formatSubtaskPreview({ parent = {}, candidates = [], scopeDecision = {}, analysisScope }) {
+  if (analysisScope || candidates.some(candidate => isFrontendSubtask(candidate))) {
+    return formatFrontendPreview({ parent, candidates, scopeDecision, analysisScope: analysisScope || 'frontend' });
+  }
+  const lines = [
+    chalk.bold.cyan('═'.repeat(72)),
+    chalk.bold('Redmine 子任務拆分預覽'),
+    chalk.bold.cyan('═'.repeat(72)),
+    '',
+    chalk.bold.cyan(`Issue #${parent.id || '—'}：${parent.subject || '無標題'}`),
+    '既有子任務：',
+  ];
+
+  if (parent.children?.length) {
+    for (const child of parent.children) lines.push(`- #${child.id} ${child.subject || '無標題'}`);
+  } else {
+    lines.push('- 無');
+  }
+
+  for (const [index, candidate] of candidates.entries()) {
+    lines.push(
+      '',
+      chalk.bold.green(`[${index + 1}/${candidates.length}] ${candidate.title || '無標題'}`),
+      `分類：${candidate.category || '—'}`,
+      candidate.dependsOnKeys?.length ? `依賴：${candidate.dependsOnKeys.join('、')}` : '依賴：無',
+      candidate.evidence?.length ? `依據：${candidate.evidence.join('、')}` : '依據：未提供',
+      candidate.content || '',
+      chalk.dim('─'.repeat(72))
+    );
+  }
+
+  lines.push('', chalk.yellow('尚未修改 Redmine。請審核 title 與 content 後再使用 --apply。'));
+  return lines.join('\n').trim();
+}