flow-comet 1.6.4 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +36 -6
- package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
- package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/entry-detail.md +29 -4
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +174 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +17 -95
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +28 -4
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +136 -19
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +54 -18
- package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +6 -6
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +25 -10
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +4 -2
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +21 -13
- package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +163 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +448 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +396 -27
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1035 -172
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +129 -98
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +797 -232
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +91 -22
- package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +69 -13
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +454 -135
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +66 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +109 -13
- package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +55 -2
- package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +149 -34
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +79 -9
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +78 -8
- package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +60 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +167 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +287 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1454 -16
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1205 -77
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +52 -11
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +9 -1
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +22 -6
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +18 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +4100 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +6 -5
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +203 -4
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +312 -63
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +42 -15
- package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
- package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +21 -10
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-review/SKILL.md +33 -18
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +44 -16
- package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
- package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
- package/README.md +3 -3
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +2 -2
- package/scripts/lib/installer-flowkit.mjs +43 -3
|
@@ -0,0 +1,448 @@
|
|
|
1
|
+
// guard-artifact-skeleton.mjs — 工件骨架计算(单一实现)
|
|
2
|
+
//
|
|
3
|
+
// 输入:`<runRoot>/flow-kit/templates/<DOC>.md`(上游模板,内容权威)+ `<packageRoot>/reference/
|
|
4
|
+
// artifact-templates.json`(本仓登记表:条件段 / 可选段 / 结构子段 / 增量段 / 首部 / 标题形态 / 指纹)。
|
|
5
|
+
// 输出:规范化骨架(H2 序列 + 条件标记 + 结构型 H3 + 增量段位置 + 派生来源与指纹)。
|
|
6
|
+
//
|
|
7
|
+
// 单一实现纪律(L-067):骨架只在本模块计算。任何门禁(guard-routing / guard-template-fidelity /
|
|
8
|
+
// evolve / health)一律调用本模块,不得自持「读模板 + 抽 H2」的派生副本。段名归一复用 route-node 的
|
|
9
|
+
// normalizeHeading(去编号 / 去尾部括号 / 大小写归一),本模块不另写第二份段名归一。
|
|
10
|
+
// 「模板缺席时的段名清单」同样只在本模块登记(文件末尾的段名清单段)——消费方只 import,不自持
|
|
11
|
+
// 第二份字面清单(段名清单单一来源)。
|
|
12
|
+
//
|
|
13
|
+
// 模板缺席:derived=false 且 sections 为空(不内置任何兜底骨架)——调用方据此跳过校验并显式声明
|
|
14
|
+
// 「未校验(模板缺失)」。本模块对「登记表缺失 / 模板缺失 / 键未知」一律不抛错。
|
|
15
|
+
//
|
|
16
|
+
// 缓存:按 runRoot 键控(同一进程内每个项目根只算一次)。返回的骨架对象是共享缓存值,消费方只读。
|
|
17
|
+
|
|
18
|
+
import { createHash } from 'crypto';
|
|
19
|
+
import { promises as fs } from 'fs';
|
|
20
|
+
import path from 'path';
|
|
21
|
+
import { normalizeHeading } from '../route-node.mjs';
|
|
22
|
+
import { escapeRegExp } from './task-graph.mjs';
|
|
23
|
+
import { packageRoot, runRoot } from './guard-state-io.mjs';
|
|
24
|
+
|
|
25
|
+
const REGISTRY_PATH = path.join(packageRoot, 'reference', 'artifact-templates.json');
|
|
26
|
+
const HEADING_LINE = { 2: /^##\s+(.+?)\s*$/u, 3: /^###\s+(.+?)\s*$/u };
|
|
27
|
+
|
|
28
|
+
// 模板文本归一(BOM / 行尾):指纹与标题解析共用同一口径——行尾差异是检出的噪音,不应改变指纹。
|
|
29
|
+
function normalizeTemplateText(text) {
|
|
30
|
+
return String(text ?? '').replace(/^\uFEFF/u, '').replace(/\r\n?/gu, '\n');
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// vendored flow-kit 的版本读数:项目根下 flow-kit/ 的 git HEAD(安装器按锁定快照 --detach 检出,
|
|
34
|
+
// 开发检出通常在分支上)。只读 HEAD 与 ref 两个小文件,不起 git 子进程、不写任何东西;读不到 /
|
|
35
|
+
// 非常规形态一律返回 null——「无从判断」不等于「版本不符」,不得据此提示。
|
|
36
|
+
async function readVendoredCommit(root) {
|
|
37
|
+
const flowKitDir = path.join(root, 'flow-kit');
|
|
38
|
+
let gitDir = path.join(flowKitDir, '.git');
|
|
39
|
+
try {
|
|
40
|
+
if ((await fs.stat(gitDir)).isFile()) {
|
|
41
|
+
// worktree / 子模块形态:.git 是指针文件(gitdir: <路径>)
|
|
42
|
+
const matched = normalizeTemplateText(await fs.readFile(gitDir, 'utf8')).trim().match(/^gitdir:\s*(.+)$/u);
|
|
43
|
+
if (matched === null) return null;
|
|
44
|
+
gitDir = path.resolve(flowKitDir, matched[1].trim());
|
|
45
|
+
}
|
|
46
|
+
} catch {
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
let head = null;
|
|
50
|
+
try {
|
|
51
|
+
head = normalizeTemplateText(await fs.readFile(path.join(gitDir, 'HEAD'), 'utf8')).trim();
|
|
52
|
+
} catch {
|
|
53
|
+
return null;
|
|
54
|
+
}
|
|
55
|
+
if (/^[0-9a-f]{40}$/u.test(head)) return head;
|
|
56
|
+
const symbolic = head.match(/^ref:\s*(\S+)$/u);
|
|
57
|
+
if (symbolic === null) return null;
|
|
58
|
+
const ref = symbolic[1];
|
|
59
|
+
try {
|
|
60
|
+
const sha = normalizeTemplateText(await fs.readFile(path.join(gitDir, ...ref.split('/')), 'utf8')).trim();
|
|
61
|
+
if (/^[0-9a-f]{40}$/u.test(sha)) return sha;
|
|
62
|
+
} catch {
|
|
63
|
+
// 松引用缺席时退到 packed-refs(git gc 后的正常形态)
|
|
64
|
+
}
|
|
65
|
+
try {
|
|
66
|
+
const packed = normalizeTemplateText(await fs.readFile(path.join(gitDir, 'packed-refs'), 'utf8'));
|
|
67
|
+
for (const line of packed.split('\n')) {
|
|
68
|
+
const matched = line.match(/^([0-9a-f]{40})\s+(\S+)$/u);
|
|
69
|
+
if (matched !== null && matched[2] === ref) return matched[1];
|
|
70
|
+
}
|
|
71
|
+
} catch {
|
|
72
|
+
// 两个落点都读不到——按「无从判断」处理
|
|
73
|
+
}
|
|
74
|
+
return null;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// 运行期轻提示:登记表锁定的快照 commit 与项目 vendored flow-kit 的 HEAD 不一致时,打一行
|
|
78
|
+
// 提示即返回——不阻断任何门禁、不改状态、不落盘。每个项目根在同一进程内只判定一次(骨架按根缓存,
|
|
79
|
+
// 重复判定只会得到同一结论)。
|
|
80
|
+
const vendoredCommitChecked = new Set();
|
|
81
|
+
|
|
82
|
+
async function maybeWarnVendoredCommit(root, lockedCommit) {
|
|
83
|
+
if (typeof lockedCommit !== 'string' || lockedCommit === '') return;
|
|
84
|
+
if (vendoredCommitChecked.has(root)) return;
|
|
85
|
+
vendoredCommitChecked.add(root);
|
|
86
|
+
const vendored = await readVendoredCommit(root);
|
|
87
|
+
if (vendored === null || vendored === lockedCommit) return;
|
|
88
|
+
console.error('TEMPLATE-FINGERPRINT WARN: 项目 flow-kit 检出 ' + vendored.slice(0, 12)
|
|
89
|
+
+ ' ≠ 登记表锁定快照 ' + lockedCommit.slice(0, 12)
|
|
90
|
+
+ ' —— 骨架按登记表快照校验(不阻断);升级 flow-kit 时须同批更新 reference/artifact-templates.json 的 templateCommit 与每模板 sha256');
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
// 标题行提取(行锚定):只认行首 ATX 标题。非锚定子串命中会被正文里「引用段名」劫持(L-128)。
|
|
94
|
+
function headingLines(text, level) {
|
|
95
|
+
const matcher = HEADING_LINE[level];
|
|
96
|
+
const out = [];
|
|
97
|
+
for (const line of normalizeTemplateText(text).split('\n')) {
|
|
98
|
+
const matched = line.match(matcher);
|
|
99
|
+
if (matched) out.push(matched[1].trim());
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// 段名宽容匹配(单一实现):主体取 normalizeHeading 的结果,译为行锚定正则。编号前缀、尾部括号与
|
|
105
|
+
// 闭合 ATX 在正则里同样可选——「省编号 / 换括号措辞 / 大小写不同 / 尾部补 `##`」命中同一段,核心词
|
|
106
|
+
// 不同则不命中(AC-9)。闭合 ATX 的判定与 normalizeHeading 取同一惯例:收尾的 `#` 串前面必须有空白,
|
|
107
|
+
// 否则那是标题文本本身(`## 波次划分##` 的段名以 `#` 结尾,不是同一条标题)。
|
|
108
|
+
// escapeRegExp 的既有契约是 glob 片段(调用方先 split('*')),故不转义 `*`;段名是字面文本,缺口在
|
|
109
|
+
// 这一行显式闭合,而不是另写一份转义实现。
|
|
110
|
+
// 匹配只对**围栏外的标题行**有意义(围栏内的标题是正文示例):段名判据一律经 lib/section-body.mjs 的
|
|
111
|
+
// 围栏感知扫描取行,本正则不承担围栏语义(对着整篇文本 test 会把示例标题读成段)。
|
|
112
|
+
export function headingPattern(rawName, level = 2) {
|
|
113
|
+
const normalized = normalizeHeading(rawName);
|
|
114
|
+
const body = normalized === '' ? String(rawName ?? '').trim() : normalized;
|
|
115
|
+
const marker = level === 3 ? '###' : '##';
|
|
116
|
+
return new RegExp(
|
|
117
|
+
'^' + marker + '\\s*(?:\\d+(?:\\.\\d+)?\\.?\\s*)?' + headingLiteral(body)
|
|
118
|
+
+ '\\s*(?:[((][^\\n))]*[))])?(?:\\s+#+)?\\s*$',
|
|
119
|
+
'im',
|
|
120
|
+
);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// 段名字面量 → 正则片段:转义正则元字符(`*` 不在 escapeRegExp 的 glob 契约内,单独闭合)。段名
|
|
124
|
+
// 在正则里是字面文本,缺口在这一行显式闭合,而不是各消费方各写一份转义。
|
|
125
|
+
function headingLiteral(rawName) {
|
|
126
|
+
return escapeRegExp(String(rawName ?? '')).replace(/\*/gu, '\\*');
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
// 段标题谓词(同一套归一的谓词形态;lib/section-body.mjs 既接受整行正则,也接受
|
|
130
|
+
// `(heading) => boolean`):判定 = 级别相等 且 标题正文与段名过同一个 normalizeHeading 后相等。
|
|
131
|
+
// 为什么需要谓词形态:标题**正文本身**可以以井号开头(`## ## 验收准则(AC)`)——Markdown 的合法
|
|
132
|
+
// 写法,段形门先剥前导井号再归一(认作在场),而按整行锚定的正则把第二个井号读成段名的一部分:同一份
|
|
133
|
+
// 工件的同一段在两处得到相反答案,一次排版就够关掉其中一处判据(未校验 ≠ 通过)。归一在标题文本层,
|
|
134
|
+
// 井号因此不是判定变量。段形门(guard-template-fidelity)对同一件事用的是同一套归一(标题正文与段名
|
|
135
|
+
// 各过 normalizeHeading 再比);波次门与 AC 覆盖取用本谓词,两处不再各写一份比较。
|
|
136
|
+
// names 可给单个段名或段名清单(回退基准常是一组同义写法,见文件末尾的段名清单段)。
|
|
137
|
+
export function headingPredicate(names, level = 2) {
|
|
138
|
+
const wanted = new Set((Array.isArray(names) ? names : [names])
|
|
139
|
+
.map((name) => normalizeHeading(name))
|
|
140
|
+
.filter((name) => name !== ''));
|
|
141
|
+
return function registeredSectionHeading(heading) {
|
|
142
|
+
return Boolean(heading) && heading.level === level && wanted.has(normalizeHeading(heading.text));
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// 登记表读取(进程内一次)
|
|
147
|
+
let registryCache = null;
|
|
148
|
+
|
|
149
|
+
async function loadRegistry() {
|
|
150
|
+
if (registryCache === null) {
|
|
151
|
+
try {
|
|
152
|
+
registryCache = {
|
|
153
|
+
available: true,
|
|
154
|
+
data: JSON.parse(normalizeTemplateText(await fs.readFile(REGISTRY_PATH, 'utf8'))),
|
|
155
|
+
};
|
|
156
|
+
} catch (error) {
|
|
157
|
+
registryCache = {
|
|
158
|
+
available: false,
|
|
159
|
+
reason: error?.code === 'ENOENT' ? 'registry-missing' : 'registry-unreadable',
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
return registryCache;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
function compileTitlePattern(source) {
|
|
167
|
+
if (typeof source !== 'string' || source.trim() === '') return null;
|
|
168
|
+
try {
|
|
169
|
+
return new RegExp(source, 'i');
|
|
170
|
+
} catch {
|
|
171
|
+
return null;
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
// 骨架对象形态的唯一定义处:缺失 / 未派生路径直接返回它(derived=false + 空集合),正常路径在它上面
|
|
176
|
+
// 填充。单一形态定义让消费方只记一套字段——任何原因下键集合都相同,判「能不能校验」只看 derived。
|
|
177
|
+
function baseSkeleton(key, reason) {
|
|
178
|
+
return {
|
|
179
|
+
key,
|
|
180
|
+
derived: false,
|
|
181
|
+
reason,
|
|
182
|
+
file: null,
|
|
183
|
+
titleForm: null,
|
|
184
|
+
titleRegExp: null,
|
|
185
|
+
headerFields: [],
|
|
186
|
+
frontmatterKeys: [],
|
|
187
|
+
sections: [],
|
|
188
|
+
registryOnlySections: [],
|
|
189
|
+
structureSubsections: [],
|
|
190
|
+
increments: [],
|
|
191
|
+
templateCommit: null,
|
|
192
|
+
templateSha256: null,
|
|
193
|
+
actualSha256: null,
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// 归一后同名的段在宽容口径下不可区分(典型:Button (Primary) / Button (Secondary) 都归一成 button)
|
|
198
|
+
// ——标记 unique=false,消费方须改用精确名匹配,避免「只写了 Secondary 也算 Primary 在场」的静默放过。
|
|
199
|
+
function markUniqueness(entries, scopeOf) {
|
|
200
|
+
const counts = new Map();
|
|
201
|
+
for (const entry of entries) {
|
|
202
|
+
const scope = scopeOf(entry) + '\u0000' + entry.norm;
|
|
203
|
+
counts.set(scope, (counts.get(scope) ?? 0) + 1);
|
|
204
|
+
}
|
|
205
|
+
for (const entry of entries) {
|
|
206
|
+
const scope = scopeOf(entry) + '\u0000' + entry.norm;
|
|
207
|
+
entry.unique = counts.get(scope) === 1;
|
|
208
|
+
}
|
|
209
|
+
return entries;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
// H2 骨架 = 模板标题行(顺序即模板顺序)+ 登记表标记。段集合以**模板**为准(C14),两个方向分开:
|
|
213
|
+
// 模板有而登记表没登记的段按无条件段处理(模板是权威,不告警);登记表登记了而模板里没有的段按模板
|
|
214
|
+
// 忽略,但作为独立集合(registryOnlySections)报出——它是登记表滞后 / 上游删段的唯一可见信号
|
|
215
|
+
// (登记表与模板分叉),静默丢弃会让「模板权威」变成单向失明。
|
|
216
|
+
function buildSections(templateHeadings, registeredSections) {
|
|
217
|
+
const registered = new Map();
|
|
218
|
+
for (const entry of Array.isArray(registeredSections) ? registeredSections : []) {
|
|
219
|
+
if (typeof entry?.name !== 'string') continue;
|
|
220
|
+
registered.set(normalizeHeading(entry.name), entry);
|
|
221
|
+
}
|
|
222
|
+
const sections = templateHeadings.map((name, index) => {
|
|
223
|
+
const norm = normalizeHeading(name);
|
|
224
|
+
const flags = registered.get(norm);
|
|
225
|
+
return {
|
|
226
|
+
name,
|
|
227
|
+
norm,
|
|
228
|
+
index,
|
|
229
|
+
conditional: flags?.conditional === true,
|
|
230
|
+
optional: flags?.optional === true,
|
|
231
|
+
pattern: headingPattern(name, 2),
|
|
232
|
+
};
|
|
233
|
+
});
|
|
234
|
+
const templateNorms = new Set(sections.map((section) => section.norm));
|
|
235
|
+
const registryOnlySections = [...registered.entries()]
|
|
236
|
+
.filter(([norm]) => !templateNorms.has(norm))
|
|
237
|
+
.map(([, entry]) => entry.name);
|
|
238
|
+
return { sections: markUniqueness(sections, () => ''), registryOnlySections };
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
// 结构型 H3 由登记表显式列举(不用正则识别示例条目——示例条目是书写样例,不是骨架)
|
|
242
|
+
function buildStructureSubsections(registeredSubsections) {
|
|
243
|
+
const subsections = [];
|
|
244
|
+
for (const entry of Array.isArray(registeredSubsections) ? registeredSubsections : []) {
|
|
245
|
+
if (typeof entry?.name !== 'string') continue;
|
|
246
|
+
const parent = typeof entry.parent === 'string' ? entry.parent : null;
|
|
247
|
+
subsections.push({
|
|
248
|
+
name: entry.name,
|
|
249
|
+
norm: normalizeHeading(entry.name),
|
|
250
|
+
parent,
|
|
251
|
+
parentNorm: parent === null ? null : normalizeHeading(parent),
|
|
252
|
+
pattern: headingPattern(entry.name, 3),
|
|
253
|
+
});
|
|
254
|
+
}
|
|
255
|
+
return markUniqueness(subsections, (entry) => entry.parentNorm ?? '');
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
// 增量段(上游模板没有、本仓追加的段/标记):位置由登记表表达,供消费方按位置校验(AC-12)
|
|
259
|
+
function buildIncrements(registeredIncrements) {
|
|
260
|
+
const increments = [];
|
|
261
|
+
for (const entry of Array.isArray(registeredIncrements) ? registeredIncrements : []) {
|
|
262
|
+
if (typeof entry?.section !== 'string') continue;
|
|
263
|
+
const position = entry.position && typeof entry.position === 'object' ? entry.position : {};
|
|
264
|
+
const kind = entry.kind === 'marker' ? 'marker' : 'section';
|
|
265
|
+
increments.push({
|
|
266
|
+
section: entry.section,
|
|
267
|
+
norm: normalizeHeading(entry.section),
|
|
268
|
+
kind,
|
|
269
|
+
required: entry.required === true,
|
|
270
|
+
position: {
|
|
271
|
+
mode: typeof position.mode === 'string' ? position.mode : 'anywhere',
|
|
272
|
+
afterSection: position.afterSection ?? null,
|
|
273
|
+
afterNorm: typeof position.afterSection === 'string' ? normalizeHeading(position.afterSection) : null,
|
|
274
|
+
section: position.section ?? null,
|
|
275
|
+
sectionNorm: typeof position.section === 'string' ? normalizeHeading(position.section) : null,
|
|
276
|
+
constraint: position.constraint ?? null,
|
|
277
|
+
},
|
|
278
|
+
pattern: kind === 'marker' ? null : headingPattern(entry.section, 2),
|
|
279
|
+
});
|
|
280
|
+
}
|
|
281
|
+
return increments;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
async function computeSkeleton(requestedKey, root) {
|
|
285
|
+
const registry = await loadRegistry();
|
|
286
|
+
if (!registry.available) return baseSkeleton(requestedKey, registry.reason);
|
|
287
|
+
|
|
288
|
+
const templates = registry.data?.templates ?? {};
|
|
289
|
+
const registeredKey = Object.keys(templates)
|
|
290
|
+
.find((key) => key.toLowerCase() === requestedKey.toLowerCase()) ?? null;
|
|
291
|
+
if (registeredKey === null) {
|
|
292
|
+
const skeleton = baseSkeleton(requestedKey, 'unknown-key');
|
|
293
|
+
skeleton.availableKeys = Object.keys(templates);
|
|
294
|
+
return skeleton;
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
const entry = templates[registeredKey];
|
|
298
|
+
const skeleton = baseSkeleton(registeredKey, null);
|
|
299
|
+
skeleton.file = typeof entry.file === 'string' ? entry.file : null;
|
|
300
|
+
skeleton.titleForm = typeof entry.titleForm === 'string' ? entry.titleForm : null;
|
|
301
|
+
skeleton.titleRegExp = compileTitlePattern(entry.titlePattern);
|
|
302
|
+
skeleton.headerFields = Array.isArray(entry.headerFields) ? [...entry.headerFields] : [];
|
|
303
|
+
skeleton.frontmatterKeys = Array.isArray(entry.frontmatterKeys) ? [...entry.frontmatterKeys] : [];
|
|
304
|
+
skeleton.templateCommit = registry.data?.templateCommit ?? null;
|
|
305
|
+
skeleton.templateSha256 = typeof entry.sha256 === 'string' ? entry.sha256 : null;
|
|
306
|
+
|
|
307
|
+
if (skeleton.file === null) {
|
|
308
|
+
skeleton.reason = 'template-undeclared';
|
|
309
|
+
return skeleton;
|
|
310
|
+
}
|
|
311
|
+
let text = null;
|
|
312
|
+
try {
|
|
313
|
+
text = await fs.readFile(path.resolve(root, ...skeleton.file.split('/')), 'utf8');
|
|
314
|
+
} catch {
|
|
315
|
+
text = null;
|
|
316
|
+
}
|
|
317
|
+
if (text === null) {
|
|
318
|
+
skeleton.reason = 'template-missing';
|
|
319
|
+
return skeleton;
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
const built = buildSections(headingLines(text, 2), entry.sections);
|
|
323
|
+
skeleton.sections = built.sections;
|
|
324
|
+
skeleton.registryOnlySections = built.registryOnlySections;
|
|
325
|
+
skeleton.structureSubsections = buildStructureSubsections(entry.structureSubsections);
|
|
326
|
+
skeleton.increments = buildIncrements(entry.increments);
|
|
327
|
+
skeleton.actualSha256 = createHash('sha256')
|
|
328
|
+
.update(Buffer.from(normalizeTemplateText(text), 'utf8'))
|
|
329
|
+
.digest('hex');
|
|
330
|
+
skeleton.derived = skeleton.sections.length > 0;
|
|
331
|
+
if (!skeleton.derived) skeleton.reason = 'template-empty';
|
|
332
|
+
// 登记表比模板多登记的段:按模板忽略(不阻断),但必须可见——否则登记表滞后只能等发版期指纹
|
|
333
|
+
// 检查才发现(且指纹只报「模板变了」,不说「哪段没用了」)。每个根 + 每个模板键只判一次(骨架
|
|
334
|
+
// 按根缓存),故不会重复刷屏。
|
|
335
|
+
if (skeleton.registryOnlySections.length > 0) {
|
|
336
|
+
console.error('TEMPLATE-REGISTRY WARN: 登记表登记的段在模板里不存在 '
|
|
337
|
+
+ skeleton.registryOnlySections.length + ' 处(' + skeleton.registryOnlySections.join('、')
|
|
338
|
+
+ ';模板 ' + skeleton.file + ')——段集合以模板为准,已按忽略处理(不阻断);'
|
|
339
|
+
+ '请同批更新 reference/artifact-templates.json');
|
|
340
|
+
}
|
|
341
|
+
await maybeWarnVendoredCommit(root, skeleton.templateCommit);
|
|
342
|
+
return skeleton;
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
function resolveRoot(opts) {
|
|
346
|
+
const explicit = opts?.runRoot;
|
|
347
|
+
if (typeof explicit === 'string' && explicit.trim() !== '') return path.resolve(explicit);
|
|
348
|
+
return path.resolve(runRoot);
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
const skeletonCache = new Map(); // 项目根 → (小写键 → 骨架)
|
|
352
|
+
|
|
353
|
+
// 规范化骨架。key 大小写不敏感(既有消费方用 'change'/'summary' 等小写键,登记表用模板基名大写)。
|
|
354
|
+
// opts.runRoot 可指向另一个项目根(测试与临时夹具用);缺省用运行上下文 runRoot。
|
|
355
|
+
export async function buildSkeleton(key, opts = {}) {
|
|
356
|
+
const requested = String(key ?? '').trim();
|
|
357
|
+
const root = resolveRoot(opts);
|
|
358
|
+
let perRoot = skeletonCache.get(root);
|
|
359
|
+
if (!perRoot) {
|
|
360
|
+
perRoot = new Map();
|
|
361
|
+
skeletonCache.set(root, perRoot);
|
|
362
|
+
}
|
|
363
|
+
const cacheKey = requested.toLowerCase();
|
|
364
|
+
const cached = perRoot.get(cacheKey);
|
|
365
|
+
if (cached) return cached;
|
|
366
|
+
const skeleton = await computeSkeleton(requested, root);
|
|
367
|
+
perRoot.set(cacheKey, skeleton);
|
|
368
|
+
return skeleton;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
// 模板指纹:登记表锁定的 commit + sha256 与实际模板读数。drift 三态——true/false = 可比对
|
|
372
|
+
// 且结论明确,null = 无从判断(模板或登记表读数缺失);「模板是否可读」看 actualSha256 是否为 null,
|
|
373
|
+
// 不另设第二个字段表达同一事实。发版期检查据此报红;运行期只做轻提示(computeSkeleton 的
|
|
374
|
+
// maybeWarnVendoredCommit——本函数自身不打印)。
|
|
375
|
+
export async function templateFingerprint(key, opts = {}) {
|
|
376
|
+
const skeleton = await buildSkeleton(key, opts);
|
|
377
|
+
const drift = skeleton.templateSha256 !== null && skeleton.actualSha256 !== null
|
|
378
|
+
? skeleton.templateSha256 !== skeleton.actualSha256
|
|
379
|
+
: null;
|
|
380
|
+
return {
|
|
381
|
+
key: skeleton.key,
|
|
382
|
+
file: skeleton.file,
|
|
383
|
+
templateCommit: skeleton.templateCommit,
|
|
384
|
+
recordedSha256: skeleton.templateSha256,
|
|
385
|
+
actualSha256: skeleton.actualSha256,
|
|
386
|
+
drift,
|
|
387
|
+
derived: skeleton.derived,
|
|
388
|
+
reason: skeleton.reason,
|
|
389
|
+
};
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
// 登记表全部模板的骨架(键 = 模板基名)。登记表不可读 → 空对象(调用方按「未校验」处理)。
|
|
393
|
+
export async function allSkeletons(opts = {}) {
|
|
394
|
+
const registry = await loadRegistry();
|
|
395
|
+
if (!registry.available) return {};
|
|
396
|
+
const out = {};
|
|
397
|
+
for (const key of Object.keys(registry.data?.templates ?? {})) {
|
|
398
|
+
out[key] = await buildSkeleton(key, opts);
|
|
399
|
+
}
|
|
400
|
+
return out;
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
// ---------- 段名清单(全系统唯一一份)----------
|
|
404
|
+
//
|
|
405
|
+
// 模板缺席(模板未安装 / 登记表不可读)时仍然要生效的判据基准:模板缺席恰恰没有骨架可派生,所以
|
|
406
|
+
// 这些名字不可能由骨架算出来——它们是「模板缺席也要拦」的既有判据输入。此前它们以字面清单分散在
|
|
407
|
+
// 骨架模块之外的三处门禁模块里,「段名从哪来」因此有两个答案;现在一律在此登记,消费方只 import,
|
|
408
|
+
// 不得自持字面清单(静态单源锁 + 变异探针见 scenarios/n.mjs 的 TA-21)。
|
|
409
|
+
//
|
|
410
|
+
// 段名归一仍由消费方复用 route-node 的 normalizeHeading——本模块不另写第二份归一。
|
|
411
|
+
|
|
412
|
+
// SUMMARY 模板缺席时的段序兜底:登记表不可读 / 模板未安装时,SUMMARY 门禁仍判乱序与缺段。
|
|
413
|
+
export const LEGACY_SUMMARY_ORDER = ['做了什么', '改动文件', 'verify 输出', '6 维自查', '越界检查', '自检方法'];
|
|
414
|
+
|
|
415
|
+
// 验收准则段的回退**段名**(一组同义写法):同一份字面清单派生两种投影——open 出口对着整篇工件文本
|
|
416
|
+
// test 下面的行正则,AC 覆盖按标题行过共享谓词比较(标题正文以井号开头时行正则判缺席,谓词认在场)。
|
|
417
|
+
// 行正则由名字拼出:回退基准因此只有一份清单,改一处不会让另一处静默落后。
|
|
418
|
+
export const TEMPLATE_FALLBACK_SECTION_NAMES = {
|
|
419
|
+
requirementAcceptance: ['验收准则', '验收标准', 'AC', 'Acceptance Criteria'],
|
|
420
|
+
};
|
|
421
|
+
|
|
422
|
+
// 模板缺席时 open / design 出口的段名回退(键形态保持不变,消费方按既有键取用)。
|
|
423
|
+
export const TEMPLATE_FALLBACK_SECTION_PATTERNS = {
|
|
424
|
+
changeWhy: /^##\s*Why\b/im,
|
|
425
|
+
changeVisualTone: /^##\s*视觉调性/im,
|
|
426
|
+
requirementUserStory: /^##\s*用户故事/im,
|
|
427
|
+
requirementAcceptance: new RegExp(
|
|
428
|
+
'##\\s*(' + TEMPLATE_FALLBACK_SECTION_NAMES.requirementAcceptance.map(headingLiteral).join('|') + ')',
|
|
429
|
+
'i'),
|
|
430
|
+
designDecisionList: /^##\s*\d*\.?\s*决策清单/m,
|
|
431
|
+
};
|
|
432
|
+
|
|
433
|
+
// LESSONS 扫描段名:登记表缺席时的回退名,同时是登记表 increment 的查找键。
|
|
434
|
+
export const LESSONS_SCAN_SECTION = 'LESSONS 扫描';
|
|
435
|
+
|
|
436
|
+
// SUMMARY 必填三段:每个 change 目录下每份 *-SUMMARY.md 都要在场(既有存在性判据,与模板派生
|
|
437
|
+
// 判据并行——它不依赖模板是否安装,故同样属于「段名基准」而不是骨架派生值)。
|
|
438
|
+
export const SUMMARY_REQUIRED_SECTIONS = [
|
|
439
|
+
{ regex: /##\s*verify\s*输出/i, label: '## verify 输出' },
|
|
440
|
+
{ regex: /##\s*6\s*维自查/i, label: '## 6 维自查' },
|
|
441
|
+
{ regex: /##\s*(越界检查|边界检查)/i, label: '## 越界检查' },
|
|
442
|
+
];
|
|
443
|
+
|
|
444
|
+
// 波次段名(TASK 模板的 H2):与上面几份清单同一性质——模板缺席时判据仍要有一份基准名,消费方
|
|
445
|
+
// (lib/wave-projection.mjs)只 import,不自持字面名。宽容匹配由 headingPattern 派生,标题的编号
|
|
446
|
+
// 前缀 / 尾部括号 / 闭合 ATX 因此与 TASK 段形门、AC 覆盖走同一套归一:同一份工件的同一段在两处被
|
|
447
|
+
// 认出同一组写法。「名字与模板一致」由套件在模板在场时对账(不一致即红)——登记值不是自由变量。
|
|
448
|
+
export const WAVE_SECTION_NAME = '波次划分';
|