@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/_submit.js

@@ -0,0 +1,718 @@
+'use strict';
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const cp = require('child_process');
+const readline = require('readline');
+const change = require('../../core/change.js');
+const aggregate = require('../../reports/aggregate.js');
+
+/**
+ * Submit-doc rendering, subject composition, attachment collection and
+ * human-confirmation gate for `devflow deliver --notify`.
+ *
+ * Mirrors arb-workflow-kit deploy-submit Step 3-5 conventions:
+ *   1. Generate a single 提测单.md as the email body
+ *   2. Generate one consolidated reports/test-report.md as the default test attachment
+ *   3. Step 4: human confirmation before send (subject + recipients + attachments)
+ *
+ * No external deps — uses fs / child_process / readline only.
+ */
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Subject
+
+/**
+ * Compose email subject. Mirrors arb's `【提测】{需求编号} {需求名称}` format,
+ * augmented with optional project + environment for multi-project mailboxes.
+ *
+ *  full: `【提测】[<project>][<env>] <title>` (when project + env present)
+ *  short: `【提测】 <title>`                 (no project/env)
+ */
+function composeSubject({ st, project, env, prefix }) {
+  const tag = prefix || '【提测】';
+  const parts = [];
+  if (project) parts.push(`[${project}]`);
+  if (env)     parts.push(`[${env}]`);
+  const title = (st && st.title) || (st && st.slug) || 'change';
+  return `${tag}${parts.join('')} ${title}`.replace(/\s+/g, ' ').trim();
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Submit doc body
+
+/**
+ * Render the 提测单 markdown body. Returns a string (caller writes it).
+ *
+ * Sections:
+ *   1. 基本信息 (table)
+ *   2. 变更内容 (extracted from design.md head section, first ## block)
+ *   3. 库表变更 (extracted from design.md DDL/data section and ddl.sql)
+ *   4. 测试重点 (extracted from design.md '## *风险|测试' section if any)
+ *   5. 自测情况 (table built from reports/*.md frontmatter)
+ */
+async function renderSubmitDoc({ root, slug, st, env, base, head, build, detect, time }) {
+  const cdir = change.resolveChangeDir(root, slug);
+  const designPath  = path.join(cdir, 'design.md');
+  const ddlPath     = path.join(cdir, 'ddl.sql');
+  const reportsDir  = path.join(cdir, 'reports');
+
+  const project = (detect && detect.remote && detect.remote.project) || '';
+  const repoFull = (detect && detect.remote && detect.remote.fullPath) || '';
+  const ts = time || new Date().toISOString().slice(0, 16).replace('T', ' ');
+  const submitBranch = head || primaryProjectBranch(st) || '';
+
+  // 1) 基本信息表
+  const infoRows = [
+    ['需求编号',  slug],
+    ['需求名称',  st.title || slug],
+    ['提测时间',  ts],
+    ['服务',      project || '(未识别)'],
+    ['仓库',      repoFull || '(未识别)'],
+    ['目标分支',  base || '(自动检测)'],
+    ['提测分支',  submitBranch || '(未识别)'],
+    ['构建号',    build || '-'],
+    ['测试环境',  env || 'test'],
+    ['复杂度',    st.level || 'L2'],
+  ];
+  const infoTable = renderTable(['项', '值'], infoRows);
+
+  // 2) 变更内容 + 3) 测试重点 (best-effort extraction from design.md)
+  let changes = '_(design.md 不存在,变更内容由本次 PR diff 自查)_';
+  let dbChanges = '_(无数据库表结构变更)_';
+  let risks   = '_(无显式风险节;请重点核对变更内容、库表变更和自测覆盖)_';
+  const ddlSql = fs.existsSync(ddlPath) ? await fsp.readFile(ddlPath, 'utf8') : '';
+  if (fs.existsSync(designPath)) {
+    const designMd = await fsp.readFile(designPath, 'utf8');
+    changes = extractDesignSummary(designMd);
+    dbChanges = extractDbChangeSummary({ designMd, ddlSql });
+    risks   = extractRiskSection(designMd) || risks;
+  } else if (ddlSql.trim()) {
+    dbChanges = extractDbChangeSummary({ ddlSql });
+  }
+
+  // 4) 自测情况 — 扫 reports/*.md frontmatter
+  const reports = await summariseReports({ reportsDir });
+  let testTable;
+  if (reports.length === 0) {
+    testTable = '_(尚无报告。运行 `devflow test unit` / `devflow report self-test` 后再发提测)_';
+  } else {
+    const rows = reports.map((r) => [
+      labelKind(r.kind),
+      statusIcon(r.status),
+      r.total != null ? String(r.total) : '-',
+      r.passed != null ? String(r.passed) : '-',
+      r.failed != null ? String(r.failed) : '-',
+      r.coverage || '-',
+    ]);
+    testTable = renderTable(
+      ['类型', '状态', '用例', '通过', '失败', '覆盖率'],
+      rows
+    );
+  }
+
+  return [
+    `# 【提测】${st.title || slug}`,
+    '',
+    '## 基本信息',
+    '',
+    infoTable,
+    '',
+    '## 变更内容',
+    '',
+    changes,
+    '',
+    '## 库表变更',
+    '',
+    dbChanges,
+    '',
+    '## 测试重点',
+    '',
+    risks,
+    '',
+    '## 自测情况',
+    '',
+    testTable,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Render a consolidated test report attachment for submit mail.
+ *
+ * This intentionally replaces the old "attach every reports/*.md" behavior:
+ * QA gets one readable test document, while raw unit/integration/e2e/smoke
+ * files stay in the change folder unless --attach-reports is explicitly used.
+ */
+async function renderTestReportDoc({ root, slug, st, env, detect, time }) {
+  const cdir = change.resolveChangeDir(root, slug);
+  const reportsDir = path.join(cdir, 'reports');
+  const aggregateReport = aggregate.readAggregate(reportsDir);
+  if (aggregateReport.reports.length) {
+    return fs.readFileSync(path.join(reportsDir, 'test-report.md'), 'utf8');
+  }
+  const project = (detect && detect.remote && detect.remote.project) || '';
+  const ts = time || new Date().toISOString().slice(0, 16).replace('T', ' ');
+  const reports = await summariseReports({ reportsDir });
+  const status = overallReportStatus(reports);
+  const totals = sumReportTotals(reports);
+
+  const lines = [
+    `# 测试报告 - ${st.title || slug}`,
+    '',
+    '## 一、执行结论',
+    '',
+    renderTable(['项', '值'], [
+      ['需求编号', slug],
+      ['需求名称', st.title || slug],
+      ['服务', project || '(未识别)'],
+      ['测试环境', env || 'test'],
+      ['报告时间', ts],
+      ['整体结论', statusIcon(status)],
+      ['用例统计', totals.total == null ? '-' : `总计 ${totals.total},通过 ${totals.passed},失败 ${totals.failed}`],
+    ]),
+    '',
+    '## 二、测试覆盖汇总',
+    '',
+    renderReportSummaryTable(reports),
+    '',
+    '## 三、API / 集成测试',
+    '',
+    renderApiIntegrationSummary({ reportsDir, reports }),
+    '',
+    '## 四、联调测试',
+    '',
+    renderJointTestSummary({ reportsDir, reports }),
+    '',
+    '## 五、失败与遗留',
+    '',
+    renderFailureSummary({ reportsDir, reports }),
+    '',
+    '## 六、提测结论',
+    '',
+    status === 'pass'
+      ? '- 已完成对应级别的测试验证,可提测。'
+      : '- 存在失败、待补充或未识别的测试证据,请确认风险后再提测。',
+    '',
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Pull the section between the 1st `## ` and the 2nd `## ` of design.md.
+ * Falls back to the first 30 lines of body when no `## ` sections.
+ */
+function extractDesignSummary(md) {
+  const lines = md.split('\n');
+  const idx = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) idx.push(i);
+  }
+  if (idx.length >= 2) {
+    return lines.slice(idx[0], idx[1]).join('\n').trim();
+  }
+  if (idx.length === 1) {
+    return lines.slice(idx[0]).join('\n').trim();
+  }
+  // fallback: first 30 non-empty lines
+  return lines.filter((l) => l.trim()).slice(0, 30).join('\n').trim();
+}
+
+/**
+ * Find a `## ...风险...` or `## ...测试...` section and return its body.
+ * Returns null when not found.
+ */
+function extractRiskSection(md) {
+  const lines = md.split('\n');
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s.*(风险|回归|测试)/.test(lines[i])) { start = i; break; }
+  }
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) { end = i; break; }
+  }
+  return lines.slice(start, end).join('\n').trim();
+}
+
+function extractDbChangeSummary({ designMd = '', ddlSql = '' } = {}) {
+  const dbSections = extractDbSections(designMd);
+  const sqlParts = [
+    ...dbSections.flatMap((section) => extractSqlBlocks(section)),
+    ddlSql,
+  ].map((s) => s.trim()).filter(Boolean);
+  const ddlText = sqlParts.join('\n\n');
+  const changes = parseDdlChanges(ddlText);
+  if (changes.length) {
+    return renderTable(
+      ['类型', '表', '字段', '说明'],
+      changes.map((item) => [item.type, item.table || '-', item.field || '-', item.note || '-'])
+    );
+  }
+  const meaningful = dbSections.find(hasMeaningfulDbChange);
+  if (meaningful) return meaningful.trim();
+  if (hasMeaningfulDbChange(ddlSql)) return `\`\`\`sql\n${ddlSql.trim()}\n\`\`\``;
+  return '_(无数据库表结构变更)_';
+}
+
+function extractDbSections(md) {
+  const lines = String(md || '').split('\n');
+  const sections = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(#{2,4})\s+(.+?)\s*$/.exec(lines[i]);
+    if (!m) continue;
+    const title = m[2].replace(/\{#[^}]+\}/g, '').trim();
+    if (!/(DDL|数据层|数据库|库表|表结构)/i.test(title)) continue;
+    const level = m[1].length;
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j++) {
+      const next = /^(#{2,4})\s+/.exec(lines[j]);
+      if (next && next[1].length <= level) { end = j; break; }
+    }
+    sections.push(lines.slice(i, end).join('\n').trim());
+  }
+  return sections;
+}
+
+function extractSqlBlocks(md) {
+  const out = [];
+  const re = /```(?:sql|mysql)?\s*\n([\s\S]*?)```/gi;
+  let m;
+  while ((m = re.exec(String(md || '')))) out.push(m[1]);
+  return out.length ? out : [String(md || '')];
+}
+
+function parseDdlChanges(sql) {
+  const out = [];
+  const statements = splitSqlStatements(stripSqlComments(sql));
+  for (const stmt of statements) {
+    const s = stmt.replace(/\s+/g, ' ').trim();
+    if (!s) continue;
+    let m = /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?`?([A-Za-z0-9_.]+)`?/i.exec(s);
+    if (m) {
+      out.push({ type: '新建表', table: cleanSqlName(m[1]), field: '-', note: firstSqlLine(stmt) });
+      continue;
+    }
+    m = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?`?([A-Za-z0-9_.]+)`?\s+ADD\s+(?:COLUMN\s+)?(?:IF\s+NOT\s+EXISTS\s+)?`?([A-Za-z0-9_]+)`?/i.exec(s);
+    if (m) {
+      out.push({ type: '新增字段', table: cleanSqlName(m[1]), field: cleanSqlName(m[2]), note: ddlCommentOrLine(stmt) });
+      continue;
+    }
+    m = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?`?([A-Za-z0-9_.]+)`?\s+(?:MODIFY|ALTER)\s+(?:COLUMN\s+)?`?([A-Za-z0-9_]+)`?/i.exec(s);
+    if (m) {
+      out.push({ type: '修改字段', table: cleanSqlName(m[1]), field: cleanSqlName(m[2]), note: ddlCommentOrLine(stmt) });
+      continue;
+    }
+    m = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?`?([A-Za-z0-9_.]+)`?\s+CHANGE\s+(?:COLUMN\s+)?`?([A-Za-z0-9_]+)`?\s+`?([A-Za-z0-9_]+)`?/i.exec(s);
+    if (m) {
+      const from = cleanSqlName(m[2]);
+      const to = cleanSqlName(m[3]);
+      out.push({ type: '修改字段', table: cleanSqlName(m[1]), field: from === to ? to : `${from} -> ${to}`, note: ddlCommentOrLine(stmt) });
+      continue;
+    }
+    m = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?`?([A-Za-z0-9_.]+)`?\s+DROP\s+(?:COLUMN\s+)?(?:IF\s+EXISTS\s+)?`?([A-Za-z0-9_]+)`?/i.exec(s);
+    if (m) {
+      out.push({ type: '删除字段', table: cleanSqlName(m[1]), field: cleanSqlName(m[2]), note: firstSqlLine(stmt) });
+    }
+  }
+  return dedupeDdlChanges(out);
+}
+
+function splitSqlStatements(sql) {
+  return String(sql || '').split(/;\s*(?:\n|$)/).map((s) => s.trim()).filter(Boolean);
+}
+
+function stripSqlComments(sql) {
+  return String(sql || '')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .split('\n')
+    .filter((line) => !/^\s*--/.test(line))
+    .join('\n');
+}
+
+function cleanSqlName(name) {
+  return String(name || '').replace(/`/g, '').trim();
+}
+
+function ddlCommentOrLine(stmt) {
+  const comment = /\bCOMMENT\s+'([^']+)'/i.exec(stmt) || /\bCOMMENT\s+"([^"]+)"/i.exec(stmt);
+  return comment ? comment[1].trim() : firstSqlLine(stmt);
+}
+
+function firstSqlLine(stmt) {
+  return String(stmt || '').split('\n').map((line) => line.trim()).filter(Boolean)[0] || '-';
+}
+
+function dedupeDdlChanges(items) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    const key = `${item.type}\0${item.table}\0${item.field}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+function hasMeaningfulDbChange(text) {
+  const s = String(text || '');
+  return /\b(CREATE|ALTER|DROP|RENAME)\s+(TABLE|INDEX)|\bADD\s+COLUMN\b|\bMODIFY\s+COLUMN\b|\bCHANGE\s+COLUMN\b|新增.*(表|字段)|修改.*字段|删除.*字段/i.test(s);
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Reports summary (scan reports/*.md frontmatter)
+
+const KIND_LABEL = {
+  unit: '单元测试',
+  integration: '集成测试',
+  e2e: '端到端',
+  joint: '联调测试',
+  remote: '远程 API',
+  smoke: '冒烟',
+  regression: '回归',
+  perf: '压测',
+  'self-test': '自测(灰度)',
+};
+function labelKind(k) { return KIND_LABEL[k] || k; }
+function statusIcon(s) {
+  if (s === 'pass') return '✅ 通过';
+  if (s === 'fail') return '❌ 失败';
+  if (s === 'blocked') return '⛔ 阻塞';
+  if (s === 'pending') return '⏳ 待补充';
+  return s || '-';
+}
+
+async function summariseReports({ reportsDir }) {
+  if (!fs.existsSync(reportsDir)) return [];
+  const aggregateReport = aggregate.readAggregate(reportsDir);
+  const out = aggregateReport.reports.map((r) => ({
+    ...r,
+    file: `test-report.md#${r.kind}`,
+  }));
+  const seenKinds = new Set(out.map((r) => r.kind));
+  const files = (await fsp.readdir(reportsDir)).filter((f) => f.endsWith('.md'));
+  for (const f of files.sort()) {
+    if (f === 'submit.md' || f === 'test-report.md') continue; // generated mail artifacts
+    const fm = await readFrontmatter(path.join(reportsDir, f));
+    const inferredKind = fm && (fm.kind || f.replace(/-test\.md$|\.md$/, ''));
+    if (inferredKind && seenKinds.has(inferredKind)) continue;
+    if (!fm) {
+      out.push({ kind: f.replace(/\.md$/, ''), status: 'pending', file: f });
+      continue;
+    }
+    out.push({
+      kind: fm.kind || f.replace(/-test\.md$|\.md$/, ''),
+      status: fm.status || 'pending',
+      total: fm.total != null ? Number(fm.total) : null,
+      passed: fm.passed != null ? Number(fm.passed) : null,
+      failed: fm.failed != null ? Number(fm.failed) : null,
+      coverage: fm.coverage || null,
+      failureType: fm.failureType || fm.failure_type || null,
+      file: f,
+    });
+  }
+  return out;
+}
+
+function overallReportStatus(reports) {
+  if (!reports.length) return 'pending';
+  if (reports.some((r) => r.status === 'fail')) return 'fail';
+  if (reports.some((r) => r.status === 'blocked')) return 'blocked';
+  if (reports.some((r) => r.status === 'pending' || !r.status)) return 'pending';
+  if (reports.some((r) => r.status === 'draft')) return 'pending';
+  return 'pass';
+}
+
+function sumReportTotals(reports) {
+  let seen = false;
+  const out = { total: 0, passed: 0, failed: 0 };
+  for (const r of reports) {
+    if (r.total != null || r.passed != null || r.failed != null) seen = true;
+    out.total += Number.isFinite(r.total) ? r.total : 0;
+    out.passed += Number.isFinite(r.passed) ? r.passed : 0;
+    out.failed += Number.isFinite(r.failed) ? r.failed : 0;
+  }
+  return seen ? out : { total: null, passed: null, failed: null };
+}
+
+function renderReportSummaryTable(reports) {
+  if (!reports.length) return '_(尚无测试报告。运行 `devflow test ...` 或 `devflow report self-test` 后再提测)_';
+  const rows = reports.map((r) => [
+    labelKind(r.kind),
+    statusIcon(r.status),
+    r.total != null ? String(r.total) : '-',
+    r.passed != null ? String(r.passed) : '-',
+    r.failed != null ? String(r.failed) : '-',
+    r.coverage || '-',
+    r.failureType || '-',
+    r.file || '-',
+  ]);
+  return renderTable(['类型', '状态', '用例', '通过', '失败', '覆盖率', '失败类型', '来源'], rows);
+}
+
+function renderApiIntegrationSummary({ reportsDir, reports }) {
+  const selected = reports.filter((r) => ['unit', 'integration', 'remote', 'smoke', 'deploy', 'self-test'].includes(r.kind));
+  if (!selected.length) return '_(未发现 API / 集成 / 冒烟 / 部署后自测报告)_';
+  return selected.map((r) => renderReportDigest(reportsDir, r, ['摘要', '环境信息', '执行结果', '用例执行详情', '测试覆盖', '部署证据', '命令', '检查项', '失败详情'])).join('\n\n');
+}
+
+function renderJointTestSummary({ reportsDir, reports }) {
+  const selected = reports.filter((r) => isJointTestReport(reportsDir, r));
+  if (!selected.length) {
+    return [
+      '_(未发现联调测试报告。涉及前后端联调时,建议运行 `devflow test joint --cmd="..." --backend-url=... --frontend-url=...`，或在 `reports/test-report.md#self-test` 中补充“联调测试报告”章节。)_',
+      '',
+      '建议记录:',
+      '- 后端地址、前端地址、数据库/Mock 环境',
+      '- 浏览器操作步骤:打开页面 -> 填写/点击 -> 验证结果',
+      '- 关键截图或录屏证据',
+    ].join('\n');
+  }
+  return selected.map((r) => renderReportDigest(reportsDir, r, ['环境信息', '环境', '执行结果', '用例执行详情', '场景', '失败详情'])).join('\n\n');
+}
+
+function renderFailureSummary({ reportsDir, reports }) {
+  const failed = reports.filter((r) => r.status === 'fail' || r.status === 'blocked' || (r.failed != null && r.failed > 0));
+  if (!failed.length) return '- 暂无失败用例记录。';
+  return failed.map((r) => renderReportDigest(reportsDir, r, ['失败详情', '失败用例', '失败 / 抖动用例'])).join('\n\n');
+}
+
+function isJointTestReport(reportsDir, r) {
+  if (r.kind === 'joint') return true;
+  if (r.kind === 'e2e') return true;
+  const txt = readReportTextSync(reportsDir, r.file);
+  return /联调|前后端|浏览器|截图|前端地址|后端地址/.test(txt);
+}
+
+function renderReportDigest(reportsDir, report, headings) {
+  const txt = readReportTextSync(reportsDir, report.file);
+  const parts = [`### ${labelKind(report.kind)} (${statusIcon(report.status)})`];
+  const picked = [];
+  for (const h of headings) {
+    const section = extractMarkdownSection(txt, h);
+    if (section) picked.push(section);
+  }
+  if (picked.length) {
+    parts.push(picked.join('\n\n'));
+  } else {
+    parts.push(renderTable(['项', '值'], [
+      ['来源', report.file || '-'],
+      ['用例', report.total != null ? String(report.total) : '-'],
+      ['通过', report.passed != null ? String(report.passed) : '-'],
+      ['失败', report.failed != null ? String(report.failed) : '-'],
+      ['覆盖率', report.coverage || '-'],
+    ]));
+  }
+  return parts.join('\n\n');
+}
+
+function readReportTextSync(reportsDir, file) {
+  if (!file) return '';
+  const section = /^test-report\.md#(.+)$/.exec(file);
+  if (section) {
+    const aggregateReport = aggregate.readAggregate(reportsDir);
+    const found = aggregateReport.reports.find((r) => r.kind === section[1]);
+    return found ? found.body : '';
+  }
+  try { return fs.readFileSync(path.join(reportsDir, file), 'utf8'); } catch (_) { return ''; }
+}
+
+function extractMarkdownSection(md, headingText) {
+  if (!md) return '';
+  const lines = md.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(#{2,4})\s+(.+?)\s*$/.exec(lines[i]);
+    if (!m) continue;
+    const title = m[2].replace(/[：:]\s*$/, '').trim();
+    if (title !== headingText) continue;
+    const level = m[1].length;
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j++) {
+      const next = /^(#{2,4})\s+/.exec(lines[j]);
+      if (next && next[1].length <= level) { end = j; break; }
+    }
+    return lines.slice(i, end).join('\n').trim();
+  }
+  return '';
+}
+
+async function readFrontmatter(p) {
+  let txt;
+  try { txt = await fsp.readFile(p, 'utf8'); } catch (_) { return null; }
+  if (!txt.startsWith('---')) return null;
+  const end = txt.indexOf('\n---', 3);
+  if (end < 0) return null;
+  const yaml = txt.slice(3, end).trim();
+  const out = {};
+  for (const line of yaml.split('\n')) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (m) out[m[1]] = m[2].trim();
+  }
+  return out;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Markdown table rendering
+
+function renderTable(header, rows) {
+  const sep = header.map(() => '---');
+  const out = [
+    `| ${header.join(' | ')} |`,
+    `| ${sep.join(' | ')} |`,
+  ];
+  for (const r of rows) out.push(`| ${r.map((c) => String(c).replace(/\|/g, '\\|')).join(' | ')} |`);
+  return out.join('\n');
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Attachments
+
+/**
+ * Build the default attachment list. Email defaults to one consolidated test
+ * attachment (`reports/test-report.md`) to avoid noisy multi-attachment mail.
+ *
+ *   includeSubmit  add reports/submit.md                     (default false)
+ *   includeTestReport add reports/test-report.md              (default true)
+ *   includeDocs    add requirement.md / design.md / plan.md   (default false)
+ *   includeDesignPlan add design.md / plan.md only             (default false)
+ *   includeReports add raw reports/*.md                       (default false)
+ *   extra          additional explicit paths                  (caller-controlled)
+ */
+async function collectAttachments({
+  root,
+  slug,
+  includeSubmit = false,
+  includeTestReport = true,
+  includeDocs = false,
+  includeDesignPlan = false,
+  includeReports = false,
+  extra = [],
+}) {
+  const cdir = change.resolveChangeDir(root, slug);
+  const out = [];
+  const push = (p) => { if (fs.existsSync(p) && !out.includes(p)) out.push(p); };
+
+  if (includeSubmit) {
+    push(path.join(cdir, 'reports', 'submit.md'));
+  }
+  if (includeTestReport) {
+    push(path.join(cdir, 'reports', 'test-report.md'));
+  }
+  if (includeDocs) {
+    for (const f of ['requirement.md', 'design.md', 'plan.md']) {
+      push(path.join(cdir, f));
+    }
+  } else if (includeDesignPlan) {
+    for (const f of ['design.md', 'plan.md']) {
+      push(path.join(cdir, f));
+    }
+  }
+  if (includeReports) {
+    const rdir = path.join(cdir, 'reports');
+    if (fs.existsSync(rdir)) {
+      const list = (await fsp.readdir(rdir)).filter((f) => f.endsWith('.md') && f !== 'submit.md' && f !== 'test-report.md').sort();
+      for (const f of list) push(path.join(rdir, f));
+    }
+  }
+  for (const e of extra) {
+    if (!e) continue;
+    push(path.isAbsolute(e) ? e : path.join(root, e));
+  }
+  return out;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Confirm gate
+
+/**
+ * Show preview and prompt Y/n. Mirrors arb deploy-submit Step 4 (人工确认).
+ * Returns { ok, reason }.
+ *
+ * Override hooks for testing:
+ *   _stdin   — alternative readable (default: process.stdin)
+ *   _stdout  — alternative writable (default: process.stdout)
+ *   _isTty   — () => bool override
+ */
+async function confirmSend(opts = {}) {
+  const stdout = opts._stdout || process.stdout;
+  const stdin  = opts._stdin  || process.stdin;
+  const isTty  = opts._isTty
+    ? opts._isTty()
+    : !!(process.stdin && process.stdin.isTTY && process.stdout && process.stdout.isTTY);
+
+  const print = (s) => stdout.write(s + '\n');
+  print('');
+  print('━━━━━━━━━━━ 提测邮件预览 ━━━━━━━━━━━');
+  print(`  Subject: ${opts.subject}`);
+  print(`  To:      ${(opts.to || []).join(', ') || '(none)'}`);
+  if ((opts.cc || []).length) print(`  Cc:      ${opts.cc.join(', ')}`);
+  print(`  附件 (${(opts.attachments || []).length}):`);
+  for (const a of opts.attachments || []) print(`    - ${a}`);
+  const bodyHead = (opts.body || '').split('\n').slice(0, 30).join('\n');
+  print('');
+  print('  正文(前 30 行):');
+  for (const ln of bodyHead.split('\n')) print(`    │ ${ln}`);
+  print('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  print('');
+
+  if (!isTty) {
+    return { ok: false, reason: 'non-interactive shell — pass --no-confirm to send without prompt' };
+  }
+  const ans = await prompt({ stdin, stdout, q: '确认发送? [Y/n] ', def: 'Y' });
+  const lc = ans.trim().toLowerCase();
+  if (lc === '' || lc === 'y' || lc === 'yes') return { ok: true };
+  return { ok: false, reason: `user declined (answered "${ans}")` };
+}
+
+function prompt({ stdin, stdout, q, def }) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: stdin, output: stdout, terminal: false });
+    rl.question(q, (ans) => { rl.close(); resolve((ans == null ? '' : ans) || def); });
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Misc helpers exported for deliver
+
+/** Best-effort current branch name; '' on failure. */
+function currentBranch(root) {
+  try {
+    const r = cp.spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: root, encoding: 'utf8',
+    });
+    if (r.status === 0) return r.stdout.trim();
+  } catch (_) { /* noop */ }
+  return '';
+}
+
+function primaryProjectBranch(st) {
+  const projects = Array.isArray(st && st.projects) ? st.projects : [];
+  const primary = projects.find((p) => p && p.role === 'primary' && p.branch)
+    || projects.find((p) => p && p.branch);
+  return primary ? primary.branch : '';
+}
+
+module.exports = {
+  composeSubject,
+  renderSubmitDoc,
+  renderTestReportDoc,
+  collectAttachments,
+  confirmSend,
+  summariseReports,
+  currentBranch,
+  primaryProjectBranch,
+  _internals: {
+    extractDesignSummary,
+    extractRiskSection,
+    extractDbChangeSummary,
+    parseDdlChanges,
+    readFrontmatter,
+    renderTable,
+    prompt,
+    overallReportStatus,
+    extractMarkdownSection,
+    isJointTestReport,
+  },
+};