@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/scripts/build-metrics-report.js

@@ -1,3 +1,22 @@
+/**
+ * #138 指标面板第一切片:只读聚合呈现面 v1(ADR-11 质量层,工程面交付)。
+ *
+ * 聚合既有落盘侧车(不新增任何数据源)→ 单一 markdown 报告:
+ *   - 事实闸 verdict 分布 + blocked 牊(<stateRoot>/gotry-state/bookable-facts.jsonl)
+ *   - 通道健康 down/cooldown('ok' 恢复事件 latest-wins 超越;<stateRoot>/gotry-state/channel-health.jsonl,30 天窗,
+ *     与 doctor 持久面 readLatestChannelEvents 同口径)
+ *   - 事故面(<stateRoot>/gotry-state/incidents.jsonl,--days 窗,默认 7)
+ *   - 桥延迟 p50/p95/max + >500ms 违约计数(<stateRoot>/gotry-state/bridge-latency.jsonl;
+ *     >500ms 是架构 §11 复审节奏的触发锚点,这里给出可见性)
+ *   - 账本存在性(gotry-state.db 只 stat:openDb 建连即可能写 kv,指标面不打开 SQLite)
+ *   - doctor 报告存在性 + 评测三层入口指针(运行结果由 run-all-tests.sh/CI 承载,v1 不重跑评测)
+ *
+ * 纪律:全程只读(缺文件=空节;坏行跳过,与 incidents/fact-log 同纪律);
+ *       默认写 stdout,仅 --out 指定路径时落盘;零新依赖零 LLM;
+ *       工程面交付,不构成 M3 Exit 证据(#138 口径,Exit 证据归 #22)。
+ *
+ * 运行:npx tsx ts/scripts/build-metrics-report.ts [--state-root <dir>] [--out <file>] [--days <N>]
+ */
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 const BRIDGE_LATENCY_BUDGET_MS = 500;
@@ -6,107 +25,104 @@ function stateFile(stateRoot, name) {
     const root = stateRoot === '.' ? process.cwd() : stateRoot;
     return join(root, 'gotry-state', name);
 }
+/** 坏行跳过的 JSONL 读取(与 incidents/fact-log/channel-health 同纪律) */
 function readJsonl(path) {
-    if (!existsSync(path)) return [];
+    if (!existsSync(path))
+        return [];
     try {
         const rows = [];
-        for (const line of readFileSync(path, 'utf-8').split('\n')){
+        for (const line of readFileSync(path, 'utf-8').split('\n')) {
             const t = line.trim();
-            if (!t) continue;
+            if (!t)
+                continue;
             try {
                 rows.push(JSON.parse(t));
-            } catch  {}
+            }
+            catch { /* 单行损坏不拖垮聚合 */ }
         }
         return rows;
-    } catch  {
+    }
+    catch {
         return [];
     }
 }
 function bounded(value, max = 120) {
-    if (!value) return undefined;
+    if (!value)
+        return undefined;
     return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
 }
-const BLOCKED_VERDICTS = new Set([
-    'error',
-    'needs-setup'
-]);
+const BLOCKED_VERDICTS = new Set(['error', 'needs-setup']);
+/** 同 fact_id 取最新(与 loadFactRegistry 的 dedupe 同语义;行序后者胜) */
 export function aggregateFacts(rows) {
     const latest = new Map();
     let lines = 0;
-    for (const raw of rows){
-        const row = typeof raw === 'object' && raw !== null ? raw : {};
+    for (const raw of rows) {
+        const row = (typeof raw === 'object' && raw !== null ? raw : {});
         lines += 1;
         const id = typeof row.fact_id === 'string' ? row.fact_id : '';
-        if (!id) continue;
+        if (!id)
+            continue;
         latest.set(id, row);
     }
     const byKind = {};
-    for (const row of latest.values()){
+    for (const row of latest.values()) {
         const kind = typeof row.kind === 'string' && row.kind ? row.kind : 'unknown';
         const verdict = typeof row.verdict === 'string' && row.verdict ? row.verdict : 'n/a';
-        const slot = byKind[kind] ??= {
-            total: 0,
-            verdicts: {},
-            blocked: 0
-        };
+        const slot = (byKind[kind] ??= { total: 0, verdicts: {}, blocked: 0 });
         slot.total += 1;
         slot.verdicts[verdict] = (slot.verdicts[verdict] ?? 0) + 1;
-        if (BLOCKED_VERDICTS.has(verdict)) slot.blocked += 1;
+        if (BLOCKED_VERDICTS.has(verdict))
+            slot.blocked += 1;
     }
-    return {
-        lines,
-        deduped: latest.size,
-        byKind
-    };
+    return { lines, deduped: latest.size, byKind };
 }
 export function aggregateChannels(rows, opts = {}) {
     const nowMs = (opts.now ?? new Date()).getTime();
     const cutoff = nowMs - (opts.windowDays ?? CHANNEL_WINDOW_DAYS) * 86_400_000;
     const counts = new Map();
     const newest = new Map();
+    // ok 超越(外部事件接缝第 1 段):通道最新事件若为 'ok'(本地探针恢复),
+    // 该通道从「当前 down/cooldown」展示面退出——down 计数(历史频率)保留。
     const lastState = new Map();
-    for (const raw of rows){
-        const row = typeof raw === 'object' && raw !== null ? raw : {};
-        if (typeof row.channel !== 'string' || !row.channel) continue;
-        if (typeof row.state === 'string' && [
-            'down',
-            'cooldown',
-            'ok'
-        ].includes(row.state)) {
+    for (const raw of rows) {
+        const row = (typeof raw === 'object' && raw !== null ? raw : {});
+        if (typeof row.channel !== 'string' || !row.channel)
+            continue;
+        if (typeof row.state === 'string' && ['down', 'cooldown', 'ok'].includes(row.state)) {
             lastState.set(row.channel, row.state);
         }
     }
-    for (const raw of rows){
-        const row = typeof raw === 'object' && raw !== null ? raw : {};
-        if (typeof row.channel !== 'string' || !row.channel) continue;
-        if (row.state !== 'down' && row.state !== 'cooldown') continue;
-        if (lastState.get(row.channel) === 'ok') continue;
+    for (const raw of rows) {
+        const row = (typeof raw === 'object' && raw !== null ? raw : {});
+        if (typeof row.channel !== 'string' || !row.channel)
+            continue;
+        if (row.state !== 'down' && row.state !== 'cooldown')
+            continue;
+        if (lastState.get(row.channel) === 'ok')
+            continue;
         const at = typeof row.at === 'string' ? row.at : '';
         const atMs = Date.parse(at);
-        if (Number.isFinite(atMs) && atMs < cutoff) continue;
+        if (Number.isFinite(atMs) && atMs < cutoff)
+            continue;
         counts.set(row.channel, (counts.get(row.channel) ?? 0) + 1);
         const atMsSafe = Number.isFinite(atMs) ? atMs : 0;
         const prev = newest.get(row.channel);
-        if (prev && prev.atMs >= atMsSafe) continue;
+        if (prev && prev.atMs >= atMsSafe)
+            continue;
         newest.set(row.channel, {
             channel: row.channel,
             state: row.state,
             reason: typeof row.reason === 'string' ? row.reason : undefined,
             at: at || undefined,
             events: 0,
-            atMs: atMsSafe
+            atMs: atMsSafe,
         });
     }
-    const latest = [
-        ...newest.values()
-    ].map(({ atMs: _atMs, ...row })=>({
-            ...row,
-            events: counts.get(row.channel) ?? 0
-        }));
-    return {
-        windowDays: opts.windowDays ?? CHANNEL_WINDOW_DAYS,
-        latest
-    };
+    const latest = [...newest.values()].map(({ atMs: _atMs, ...row }) => ({
+        ...row,
+        events: counts.get(row.channel) ?? 0,
+    }));
+    return { windowDays: opts.windowDays ?? CHANNEL_WINDOW_DAYS, latest };
 }
 export function aggregateIncidents(rows, opts = {}) {
     const nowMs = (opts.now ?? new Date()).getTime();
@@ -115,17 +131,16 @@ export function aggregateIncidents(rows, opts = {}) {
     const byKind = {};
     const sources = new Map();
     let total = 0;
-    for (const raw of rows){
-        const row = typeof raw === 'object' && raw !== null ? raw : {};
+    for (const raw of rows) {
+        const row = (typeof raw === 'object' && raw !== null ? raw : {});
         const ts = typeof row.ts === 'string' ? row.ts : '';
         const atMs = Date.parse(ts);
-        if (Number.isFinite(atMs) && atMs < cutoff) continue;
+        if (Number.isFinite(atMs) && atMs < cutoff)
+            continue;
         const kind = typeof row.kind === 'string' && row.kind ? row.kind : 'unknown';
-        const slot = byKind[kind] ??= {
-            count: 0
-        };
+        const slot = (byKind[kind] ??= { count: 0 });
         slot.count += 1;
-        if (!slot.lastTs || Number.isFinite(atMs) && atMs > Date.parse(slot.lastTs)) {
+        if (!slot.lastTs || (Number.isFinite(atMs) && atMs > Date.parse(slot.lastTs))) {
             slot.lastTs = ts || slot.lastTs;
             slot.lastMessage = bounded(typeof row.message === 'string' ? row.message : undefined);
         }
@@ -133,69 +148,51 @@ export function aggregateIncidents(rows, opts = {}) {
         sources.set(source, (sources.get(source) ?? 0) + 1);
         total += 1;
     }
-    const topSources = [
-        ...sources.entries()
-    ].sort((a, b)=>b[1] - a[1]).slice(0, 5).map(([source, count])=>({
-            source,
-            count
-        }));
-    return {
-        windowDays,
-        totalInWindow: total,
-        byKind,
-        topSources
-    };
+    const topSources = [...sources.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([source, count]) => ({ source, count }));
+    return { windowDays, totalInWindow: total, byKind, topSources };
 }
 export function aggregateLatency(rows, opts = {}) {
     const nowMs = (opts.now ?? new Date()).getTime();
     const cutoff = nowMs - (opts.windowDays ?? 7) * 86_400_000;
     const values = [];
     const kinds = new Map();
-    for (const raw of rows){
-        const row = typeof raw === 'object' && raw !== null ? raw : {};
+    for (const raw of rows) {
+        const row = (typeof raw === 'object' && raw !== null ? raw : {});
         const ts = typeof row.ts === 'string' ? row.ts : '';
         const atMs = Date.parse(ts);
-        if (Number.isFinite(atMs) && atMs < cutoff) continue;
+        if (Number.isFinite(atMs) && atMs < cutoff)
+            continue;
         const ms = typeof row.latencyMs === 'number' ? row.latencyMs : Number.NaN;
-        if (!Number.isFinite(ms)) continue;
+        if (!Number.isFinite(ms))
+            continue;
         values.push(ms);
         const kind = typeof row.kind === 'string' && row.kind ? row.kind : 'unknown';
         kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
     }
-    const sorted = [
-        ...values
-    ].sort((a, b)=>a - b);
-    const pick = (q)=>sorted.length === 0 ? 0 : sorted[Math.min(sorted.length - 1, Math.ceil(q * sorted.length) - 1)];
+    const sorted = [...values].sort((a, b) => a - b);
+    const pick = (q) => (sorted.length === 0 ? 0 : sorted[Math.min(sorted.length - 1, Math.ceil(q * sorted.length) - 1)]);
     return {
         count: sorted.length,
         p50: pick(0.5),
         p95: pick(0.95),
         max: sorted.length === 0 ? 0 : sorted[sorted.length - 1],
-        overBudget: sorted.filter((ms)=>ms > BRIDGE_LATENCY_BUDGET_MS).length,
+        overBudget: sorted.filter((ms) => ms > BRIDGE_LATENCY_BUDGET_MS).length,
         budgetMs: BRIDGE_LATENCY_BUDGET_MS,
-        topKinds: [
-            ...kinds.entries()
-        ].sort((a, b)=>b[1] - a[1]).slice(0, 5).map(([kind, count])=>({
-                kind,
-                count
-            }))
+        topKinds: [...kinds.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([kind, count]) => ({ kind, count })),
     };
 }
 function presenceOf(path) {
     try {
-        if (!existsSync(path)) return {
-            exists: false
-        };
+        if (!existsSync(path))
+            return { exists: false };
         const st = statSync(path);
-        return {
-            exists: true,
-            bytes: st.size,
-            mtime: st.mtime.toISOString()
-        };
-    } catch  {
-        return {
-            exists: false
-        };
+        return { exists: true, bytes: st.size, mtime: st.mtime.toISOString() };
+    }
+    catch {
+        return { exists: false };
     }
 }
 export async function collectMetrics(stateRoot, opts = {}) {
@@ -204,27 +201,19 @@ export async function collectMetrics(stateRoot, opts = {}) {
         generatedAt: (opts.now ?? new Date()).toISOString(),
         stateRoot: root,
         facts: aggregateFacts(readJsonl(stateFile(stateRoot, 'bookable-facts.jsonl'))),
-        channels: aggregateChannels(readJsonl(stateFile(stateRoot, 'channel-health.jsonl')), {
-            now: opts.now,
-            windowDays: CHANNEL_WINDOW_DAYS
-        }),
-        incidents: aggregateIncidents(readJsonl(stateFile(stateRoot, 'incidents.jsonl')), {
-            now: opts.now,
-            windowDays: opts.days ?? 7
-        }),
-        latency: aggregateLatency(readJsonl(stateFile(stateRoot, 'bridge-latency.jsonl')), {
-            now: opts.now,
-            windowDays: opts.days ?? 7
-        }),
+        channels: aggregateChannels(readJsonl(stateFile(stateRoot, 'channel-health.jsonl')), { now: opts.now, windowDays: CHANNEL_WINDOW_DAYS }),
+        incidents: aggregateIncidents(readJsonl(stateFile(stateRoot, 'incidents.jsonl')), { now: opts.now, windowDays: opts.days ?? 7 }),
+        latency: aggregateLatency(readJsonl(stateFile(stateRoot, 'bridge-latency.jsonl')), { now: opts.now, windowDays: opts.days ?? 7 }),
         ledger: presenceOf(stateFile(stateRoot, 'gotry-state.db')),
-        doctorReport: presenceOf(stateFile(stateRoot, 'doctor-report.md'))
+        doctorReport: presenceOf(stateFile(stateRoot, 'doctor-report.md')),
     };
 }
 function fmtRate(blocked, total) {
-    return total === 0 ? '—' : `${blocked}/${total}(${(blocked / total * 100).toFixed(0)}%)`;
+    return total === 0 ? '—' : `${blocked}/${total}(${((blocked / total) * 100).toFixed(0)}%)`;
 }
 function fmtBytes(bytes) {
-    if (bytes === undefined) return '—';
+    if (bytes === undefined)
+        return '—';
     return bytes >= 1_048_576 ? `${(bytes / 1_048_576).toFixed(1)}MB` : `${bytes}B`;
 }
 export function renderMetricsReport(s) {
@@ -240,11 +229,12 @@ export function renderMetricsReport(s) {
     const kinds = Object.entries(s.facts.byKind);
     if (kinds.length === 0) {
         L.push('(空:无事实落盘)');
-    } else {
+    }
+    else {
         L.push('| kind | 去重后 | verdict 分布 | blocked(error+needs-setup) |');
         L.push('|---|---|---|---|');
-        for (const [kind, st] of kinds){
-            const dist = Object.entries(st.verdicts).map(([v, n])=>`${v}:${n}`).join(' / ');
+        for (const [kind, st] of kinds) {
+            const dist = Object.entries(st.verdicts).map(([v, n]) => `${v}:${n}`).join(' / ');
             L.push(`| ${kind} | ${st.total} | ${dist} | ${fmtRate(st.blocked, st.total)} |`);
         }
         L.push('');
@@ -255,10 +245,11 @@ export function renderMetricsReport(s) {
     L.push('');
     if (s.channels.latest.length === 0) {
         L.push('(空:窗口内无 down/cooldown 事件)');
-    } else {
+    }
+    else {
         L.push('| 通道 | 最新状态 | 原因 | 时间 | 窗口事件 |');
         L.push('|---|---|---|---|---|');
-        for (const c of s.channels.latest){
+        for (const c of s.channels.latest) {
             L.push(`| ${c.channel} | ${c.state} | ${bounded(c.reason ?? '', 60) ?? '—'} | ${c.at ?? '—'} | ${c.events} |`);
         }
     }
@@ -268,13 +259,14 @@ export function renderMetricsReport(s) {
     const incidentKinds = Object.entries(s.incidents.byKind);
     if (incidentKinds.length === 0) {
         L.push('(空:窗口内无事故)');
-    } else {
+    }
+    else {
         L.push('| kind | 次数 | 最近一次 |');
         L.push('|---|---|---|');
-        for (const [kind, st] of incidentKinds){
+        for (const [kind, st] of incidentKinds) {
             L.push(`| ${kind} | ${st.count} | ${st.lastTs ?? '—'}${st.lastMessage ? ` · ${st.lastMessage}` : ''} |`);
         }
-        const src = s.incidents.topSources.map((t)=>`${t.source}×${t.count}`).join(', ');
+        const src = s.incidents.topSources.map((t) => `${t.source}×${t.count}`).join(', ');
         if (src) {
             L.push('');
             L.push(`Top 来源:${src}`);
@@ -285,16 +277,18 @@ export function renderMetricsReport(s) {
     L.push('');
     if (s.latency.count === 0) {
         L.push('(空:窗口内无延迟记录)');
-    } else {
-        const kinds = s.latency.topKinds.map((t)=>`${t.kind}×${t.count}`).join(', ');
+    }
+    else {
+        const kinds = s.latency.topKinds.map((t) => `${t.kind}×${t.count}`).join(', ');
         L.push(`样本 ${s.latency.count}:p50=${s.latency.p50}ms · p95=${s.latency.p95}ms · max=${s.latency.max}ms · 超预算(>${s.latency.budgetMs}ms)= **${s.latency.overBudget}**`);
-        if (kinds) L.push(`按 kind:${kinds}`);
+        if (kinds)
+            L.push(`按 kind:${kinds}`);
     }
     L.push('');
     L.push('## 账本与体检报告');
     L.push('');
-    L.push(`- 账本 gotry-state.db:${s.ledger.exists ? `存在(${fmtBytes(s.ledger.bytes)},更新 ${s.ledger.mtime};明细经 \`npx gotry state\` 查看,指标面不打开 SQLite)` : '不存在(该 stateRoot 无账本)'}`);
-    L.push(`- doctor 报告 doctor-report.md:${s.doctorReport.exists ? `存在(更新 ${s.doctorReport.mtime})` : '不存在(跑 `npx gotry doctor` 生成)'}`);
+    L.push(`- 账本 gotry-state.db:${s.ledger.exists ? `存在(${fmtBytes(s.ledger.bytes)},更新 ${s.ledger.mtime};明细经 \`npx @danceiny/gotry state\` 查看,指标面不打开 SQLite)` : '不存在(该 stateRoot 无账本)'}`);
+    L.push(`- doctor 报告 doctor-report.md:${s.doctorReport.exists ? `存在(更新 ${s.doctorReport.mtime})` : '不存在(跑 `npx @danceiny/gotry doctor` 生成)'}`);
     L.push('');
     L.push('## 评测三层入口(ADR-11;运行结果由 run-all-tests.sh / CI 承载,v1 不在此重跑)');
     L.push('');
@@ -303,37 +297,35 @@ export function renderMetricsReport(s) {
     L.push('');
     return L.join('\n');
 }
+// ---- CLI ---------------------------------------------------------------------
 export function parseArgs(argv) {
     let stateRoot = '.';
     let out;
     let days = 7;
-    for(let i = 0; i < argv.length; i += 1){
+    for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i];
-        if (a === '--state-root') stateRoot = argv[++i] ?? stateRoot;
-        else if (a === '--out') out = argv[++i];
-        else if (a === '--days') days = Math.max(1, Number.parseInt(argv[++i] ?? '7', 10) || 7);
+        if (a === '--state-root')
+            stateRoot = argv[++i] ?? stateRoot;
+        else if (a === '--out')
+            out = argv[++i];
+        else if (a === '--days')
+            days = Math.max(1, Number.parseInt(argv[++i] ?? '7', 10) || 7);
     }
-    return {
-        stateRoot: isAbsolute(stateRoot) ? stateRoot : resolve(stateRoot),
-        out,
-        days
-    };
+    return { stateRoot: isAbsolute(stateRoot) ? stateRoot : resolve(stateRoot), out, days };
 }
-export async function main(argv) {
+export async function main(argv, injectedNow) {
     const { stateRoot, out, days } = parseArgs(argv);
-    const snapshot = await collectMetrics(stateRoot, {
-        days
-    });
+    const now = injectedNow ?? new Date();
+    const snapshot = await collectMetrics(stateRoot, { days, now });
     const markdown = renderMetricsReport(snapshot);
     if (out) {
         writeFileSync(out, markdown + '\n', 'utf-8');
         process.stdout.write(`指标报告已写 ${out}(stateRoot 只读未动)\n`);
-    } else {
+    }
+    else {
         process.stdout.write(markdown + '\n');
     }
 }
 const invokedDirectly = process.argv[1] && import.meta.url === new URL(`file://${resolve(process.argv[1])}`).href;
-if (invokedDirectly) await main(process.argv.slice(2));
-
-
-//# sourceURL=ts/scripts/build-metrics-report.ts
+if (invokedDirectly)
+    await main(process.argv.slice(2));

package/dist/scripts/changelog-tests.js

@@ -1,10 +1,21 @@
+/**
+ * CHANGELOG 生成器合同测试(run-all §42;2026-08-30 owner 拍板补 changelog 机制)。
+ * 纯函数、零网络、零 git 调用:
+ *   - Conventional Commits 解析:feat/fix/perf/refactor/docs/test/build/ci/chore/revert + scope + ! + PR 引用
+ *   - 不符合 Conventional 的 commit → other 桶(不丢历史)
+ *   - groupCommits 按 Keep a Changelog 显示顺序输出
+ *   - renderMarkdownEntry 节结构(Added/Changed/Fixed/...)
+ *   - prependEntry:不覆盖 CHANGELOG.md 历史段,只在顶部插入新版本段
+ *   - splitChangelog:preamble/history 分隔正确
+ */
 import assert from 'node:assert/strict';
-import { buildEntry, groupCommits, parseCommit, prependEntry, renderMarkdownEntry, splitChangelog } from './build-changelog.js';
+import { buildEntry, groupCommits, parseCommit, prependEntry, renderMarkdownEntry, splitChangelog, } from './build-changelog.js';
 let passed = 0;
 function ok(label) {
     passed += 1;
     console.log(`  ok ${label}`);
 }
+// ---- 1. parseCommit:Conventional 完整形态 ----
 const sample = parseCommit('feat(cost): 价表 provider-aware v2 + 价格漂移监测 (#68)');
 assert.ok(sample);
 assert.equal(sample.type, 'feat');
@@ -12,12 +23,14 @@ assert.equal(sample.scope, 'cost');
 assert.equal(sample.subject, '价表 provider-aware v2 + 价格漂移监测');
 assert.equal(sample.prRef, '68');
 ok('parseCommit feat(scope)! + #PR');
+// ---- 2. parseCommit:不带 scope ----
 const noScope = parseCommit('fix: 修复登录页可见性');
 assert.equal(noScope.type, 'fix');
 assert.equal(noScope.scope, null);
 assert.equal(noScope.subject, '修复登录页可见性');
 assert.equal(noScope.prRef, null);
 ok('parseCommit fix 无 scope');
+// ---- 3. parseCommit:不符合 Conventional → other 桶,保留原文 ----
 const other = parseCommit('docs: README 更新');
 assert.equal(other.type, 'docs');
 const legacy = parseCommit('feat(issue #21 P3.6): 会话扩展 onboarding UX 闭环(点点点 + 装完零重跑)');
@@ -27,53 +40,18 @@ const historical = parseCommit('Merge branch main into feat/x');
 assert.equal(historical.type, 'other');
 assert.equal(historical.subject, 'Merge branch main into feat/x');
 ok('parseCommit 历史 commit + 中文 subject + 无 #PR 兼容');
-for (const t of [
-    'perf',
-    'refactor',
-    'docs',
-    'test',
-    'build',
-    'ci',
-    'chore',
-    'revert'
-]){
+// ---- 4. parseCommit:perf/refactor/docs/test/build/ci/chore/revert 全覆盖 ----
+for (const t of ['perf', 'refactor', 'docs', 'test', 'build', 'ci', 'chore', 'revert']) {
     const p = parseCommit(`${t}: 一些改动`);
     assert.equal(p.type, t);
 }
 ok('parseCommit 全 9 类型支持');
+// ---- 5. groupCommits:Keep a Changelog 显示顺序 ----
 const commits = [
-    {
-        sha: 'aaa',
-        type: 'fix',
-        scope: null,
-        subject: 'fix bug',
-        prRef: '1',
-        raw: ''
-    },
-    {
-        sha: 'bbb',
-        type: 'feat',
-        scope: null,
-        subject: 'add feature',
-        prRef: '2',
-        raw: ''
-    },
-    {
-        sha: 'ccc',
-        type: 'docs',
-        scope: null,
-        subject: 'update docs',
-        prRef: null,
-        raw: ''
-    },
-    {
-        sha: 'ddd',
-        type: 'other',
-        scope: null,
-        subject: 'random commit',
-        prRef: null,
-        raw: ''
-    }
+    { sha: 'aaa', type: 'fix', scope: null, subject: 'fix bug', prRef: '1', raw: '' },
+    { sha: 'bbb', type: 'feat', scope: null, subject: 'add feature', prRef: '2', raw: '' },
+    { sha: 'ccc', type: 'docs', scope: null, subject: 'update docs', prRef: null, raw: '' },
+    { sha: 'ddd', type: 'other', scope: null, subject: 'random commit', prRef: null, raw: '' },
 ];
 const grouped = groupCommits(commits);
 assert.equal(grouped.length, 4);
@@ -82,36 +60,13 @@ assert.equal(grouped[1].type, 'fix');
 assert.equal(grouped[2].type, 'docs');
 assert.equal(grouped[3].type, 'other');
 ok('groupCommits Keep a Changelog 显示顺序(Added → Fixed → Documentation → Other)');
-const entry = buildEntry({
-    version: '0.0.1-rc.16',
-    date: '2026-08-30',
-    commits: [
-        {
-            sha: 'aaa',
-            type: 'feat',
-            scope: null,
-            subject: 'add a brand new feature with substantial description text',
-            prRef: '2',
-            raw: ''
-        },
-        {
-            sha: 'bbb',
-            type: 'fix',
-            scope: null,
-            subject: 'fix a critical bug in the rendering path of the parser',
-            prRef: '1',
-            raw: ''
-        },
-        {
-            sha: 'ccc',
-            type: 'docs',
-            scope: null,
-            subject: 'update the documentation for the new auth module',
-            prRef: null,
-            raw: ''
-        }
-    ]
-});
+// ---- 6. renderMarkdownEntry:节结构 + PR 引用 + sha 后缀 ----
+// 用较长 subject 避开 truncate 逻辑(短 subject 仍可能触发 breaker,断言用「包含」而非「完全等」)
+const entry = buildEntry({ version: '0.0.1-rc.16', date: '2026-08-30', commits: [
+        { sha: 'aaa', type: 'feat', scope: null, subject: 'add a brand new feature with substantial description text', prRef: '2', raw: '' },
+        { sha: 'bbb', type: 'fix', scope: null, subject: 'fix a critical bug in the rendering path of the parser', prRef: '1', raw: '' },
+        { sha: 'ccc', type: 'docs', scope: null, subject: 'update the documentation for the new auth module', prRef: null, raw: '' },
+    ] });
 const md = renderMarkdownEntry(entry);
 assert.match(md, /^## \[0\.0\.1-rc\.16\] - 2026-08-30/);
 assert.match(md, /### Added/);
@@ -119,8 +74,9 @@ assert.match(md, /### Fixed/);
 assert.match(md, /### Documentation/);
 assert.match(md, /- add a brand new feature[^()]*\(#2\)/);
 assert.match(md, /- fix a critical bug[^()]*\(#1\)/);
-assert.match(md, /- update the documentation[^()]*\(ccc\)/);
+assert.match(md, /- update the documentation[^()]*\(ccc\)/); // sha 后缀(无 PR)
 ok('renderMarkdownEntry 节结构 + PR/sha 后缀');
+// ---- 7. prependEntry:不覆盖 CHANGELOG.md 历史段 ----
 const existing = `# Changelog
 
 All notable changes to this project will be documented in this file.
@@ -138,28 +94,25 @@ assert.match(next, /## \[0\.0\.1-rc\.16\] - 2026-08-30/);
 assert.match(next, /## \[0\.0\.1-rc\.15\] - 2026-08-29/);
 assert.match(next, /预订 saga 状态机/);
 ok('prependEntry:新版本段在顶部,历史段原样保留');
+// ---- 8. prependEntry:空文件 → 仅生成 CHANGELOG header + 新段 ----
 const fromEmpty = prependEntry('', newMd);
 assert.match(fromEmpty, /Keep a Changelog/);
 assert.match(fromEmpty, /## \[0\.0\.1-rc\.16\]/);
 ok('prependEntry:空文件首次生成');
+// ---- 9. splitChangelog:preamble 与 history 分割 ----
 const split = splitChangelog(existing);
 assert.ok(split.preamble.includes('All notable changes'));
 assert.ok(split.history[0].includes('## [0.0.1-rc.15]'));
 ok('splitChangelog preamble/history 分隔正确');
-const emptyEntry = buildEntry({
-    version: '0.0.1-rc.16',
-    date: '2026-08-30',
-    commits: []
-});
+// ---- 10. buildEntry 空 sections 不崩(空 commit 列表)----
+const emptyEntry = buildEntry({ version: '0.0.1-rc.16', date: '2026-08-30', commits: [] });
 const emptyMd = renderMarkdownEntry(emptyEntry);
 assert.match(emptyMd, /## \[0\.0\.1-rc\.16\]/);
 ok('buildEntry 空 commit 列表 → 仍输出版本头(0 section,合规)');
+// ---- 11. parseCommit:! 标记(breaking change)----
 const breaking = parseCommit('feat(api)!: 重命名端点 /v1/users → /v2/users (#99)');
 assert.equal(breaking.type, 'feat');
 assert.equal(breaking.subject, '重命名端点 /v1/users → /v2/users');
 assert.equal(breaking.prRef, '99');
 ok('parseCommit feat(scope)!: breaking change marker 容错');
 console.log(`changelog tests: ${passed} 组断言全绿(纯函数)`);
-
-
-//# sourceURL=ts/scripts/changelog-tests.ts