@xulthekl/team-flow 0.53.0 → 0.55.0

package/scripts/gen-primer.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// gen-primer.mjs — 从设计系统确定性生成 primer.md（v0.55.0，设计 §4.1.2 / §8.2.2）
+//
+// primer 是"AI 约束入口"：组件白名单 + token 速查 + 硬规则 + **页面范式**，供 prototype-builder 消费。
+// 确定性：除"生成时间"一行外，输出完全由设计系统内容决定（纯字符串拼接，零 LLM）。
+//
+// v0.55.0 两项修正（P1.5 实证）：
+//   ① **digest 覆盖 base + 参与合并的端变体**。原先只对 base.md 做 sha256 →
+//      变体变更不判 STALE → prototype Step 0 gate 放行 → **原型静默用旧页面范式**。
+//      无变体时 digest 与旧实现**逐字节一致**（`[base].join('\n') === base`），既有测试不受影响。
+//   ② **「页面范式」段从设计系统派生**，含各端的页面类型表与容器骨架块（builder 的物料来源）。
+//      原先是**硬编码**字符串（primer 里唯一不读 base.md 的段），项目既有页面规范无法进入流程。
+//
+// Usage:
+//   node scripts/gen-primer.mjs <base.md path> [--out <primer path>]
+//     生成 primer（默认写 base.md 同目录 primer.md）；同目录端变体自动参与
+//   node scripts/gen-primer.mjs <base.md path> --check
+//     校验同目录 primer.md 的 digest 与"base + 变体"是否一致
+//     exit 0 = 一致；exit 2 = 过期或缺失（供 builder gate 判定）
+//
+// 配套测试："生成物 == 源表"（tests/lib/gen-primer.test.mjs）
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, dirname, join, resolve } from 'node:path';
+import {
+  parseComponentsTable,
+  parseContract,
+  parseA1Tokens,
+  parseAntiPatterns,
+  parsePageArchetype,
+  subsectionBodyRaw,
+  COMPONENT_COUNT_PASS,
+  COMPONENT_COUNT_WARN,
+} from './lib/ds-parse.mjs';
+import { resolveInputs, readFileOrNull } from './lib/ds-inputs.mjs';
+
+const argv = process.argv.slice(2);
+const CHECK = argv.includes('--check');
+const outIdx = argv.indexOf('--out');
+const outArg = outIdx !== -1 ? argv[outIdx + 1] : null;
+const positional = argv.filter((a, i) => !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1));
+const basePath = positional[0];
+
+if (!basePath) {
+  console.error('Usage: node scripts/gen-primer.mjs <base.md path> [--out <primer path>] [--check]');
+  process.exit(1);
+}
+
+const baseAbs = resolve(basePath);
+if (!existsSync(baseAbs)) {
+  console.error(`base.md not found: ${baseAbs}`);
+  process.exit(1);
+}
+
+const baseContent = readFileSync(baseAbs, 'utf-8');
+
+// ── 变体发现与 digest（v0.55.0）──
+// 复用 guard 的输入解析（下沉在 ds-inputs.mjs，避免 import 顶层副作用的 guard 脚本）。
+const inputs = resolveInputs(baseAbs, null);
+const variantFiles = inputs.files.filter(f => resolve(f) !== baseAbs);
+const variants = variantFiles.map(f => ({ file: f, name: basename(f).replace(/-end\.md$/i, ''), text: readFileOrNull(f) || '' }));
+
+// digest 源 = base + 全部参与合并的变体（无变体时逐字节等同旧实现）
+const digest = createHash('sha256').update([baseContent, ...variants.map(v => v.text)].join('\n'), 'utf-8').digest('hex');
+const digestShort = digest.slice(0, 16);
+const primerPath = outArg ? resolve(outArg) : join(dirname(baseAbs), 'primer.md');
+const DIGEST_RE = /sha256:([0-9a-f]{16,})/;
+const sourceLabel = ['base.md', ...variants.map(v => basename(v.file))].join(' + ');
+
+// ── --check 模式：校验 primer 新鲜度（builder gate 调用）──
+
+if (CHECK) {
+  if (!existsSync(primerPath)) {
+    console.error(`STALE: primer.md 不存在（${primerPath}）——请运行 design-system iterate 生成`);
+    process.exit(2);
+  }
+  const primerContent = readFileSync(primerPath, 'utf-8');
+  const m = primerContent.match(DIGEST_RE);
+  if (!m) {
+    console.error('STALE: primer.md 无 digest 头部（格式不符）——请重新生成');
+    process.exit(2);
+  }
+  if (m[1] !== digestShort && !digest.startsWith(m[1])) {
+    console.error(`STALE: primer.md 已过期（记录 ${m[1]}，当前 ${sourceLabel} ${digestShort}）——请运行 design-system iterate 重新生成`);
+    process.exit(2);
+  }
+  console.log(`OK: primer.md digest 一致（${digestShort}）`);
+  process.exit(0);
+}
+
+// ── 生成模式 ──
+
+const table = parseComponentsTable(baseContent);
+if (!table) {
+  console.error('base.md 的 components 段未检测到组件契约表（需 | 组件 | 类型 | variants | sizes | states | 用途 | 禁止 | 表格）。');
+  console.error('存量系统请先运行 design-system iterate 补全契约表。');
+  process.exit(1);
+}
+
+const contract = parseContract(baseContent);
+const a1 = parseA1Tokens(baseContent);
+const antiPatterns = parseAntiPatterns(baseContent);
+const componentRows = table.rows;
+const count = componentRows.length;
+const countLabel = count >= COMPONENT_COUNT_PASS
+  ? 'PASS（完整）'
+  : count >= COMPONENT_COUNT_WARN
+    ? 'WARN（可用，建议补全）'
+    : 'FAIL（低于起步线）';
+
+// 白名单行：Name(variants · sizes)
+const whitelistLines = componentRows.map(r => {
+  const variants_ = r.hasVariants ? r.variants.replace(/\s*\/\s*/g, '|') : '—';
+  const sizes = r.sizes && r.sizes !== '—' ? r.sizes.replace(/\s*\/\s*/g, '|') : '—';
+  const typeMark = r.type === '豁免' ? '（展示类）' : r.type === '轻量' ? '（轻量）' : '';
+  return `- ${r.name}${typeMark}: variants=${variants_} · sizes=${sizes}`;
+});
+
+// Token 速查行
+const tokenKeys = ['--bg', '--surface', '--fg', '--muted', '--border', '--accent'];
+const tokenLine = tokenKeys
+  .filter(k => a1[k])
+  .map(k => `${k} ${a1[k]}`)
+  .join(' / ');
+const fontDisplay = a1['--font-display'] ? `\n- --font-display: ${a1['--font-display']}` : '';
+const fontBody = a1['--font-body'] ? `\n- --font-body: ${a1['--font-body']}` : '';
+
+const hardRules = [
+  '1. 只使用上方白名单组件与 token；若需系统外元素 → 记录为新组件需求（ds_increment），不自造',
+  '2. 数据展示须覆盖 Loading / Empty / Error / Populated / Edge 五状态（craft/state-coverage.md）',
+  ...antiPatterns.map((p, i) => `${i + 3}. ${p}`),
+];
+
+/**
+ * 「页面范式」段（v0.55.0：**忠实派生物**，不再是硬编码）。
+ *
+ * 逐端摘录 `layout` 段的 `### 页面范式` 与 `### 容器骨架` 子块原文——
+ * 前者给出"页面类型 → 骨架组合"的路由，后者给出**骨架的类名与关键 CSS**（builder 的物料来源：
+ * 内置 `template.html` 里没有 `header-bar`/`sidebar-container` 这类项目容器类）。
+ */
+function pageArchetypeSection() {
+  const scopes = variants.length ? variants : [{ file: baseAbs, name: null, text: baseContent }];
+  const blocks = [];
+  for (const s of scopes) {
+    const label = s.name ? `**${s.name}**` : null;
+    const arche = parsePageArchetype(s.text);
+    const archeSub = subsectionBodyRaw(s.text, 'layout', '页面范式');
+    const skelSub = subsectionBodyRaw(s.text, 'layout', '容器骨架');
+
+    if (!arche.declared) {
+      blocks.push(`${label ? `${label}：` : ''}未声明页面范式来源 —— 在 \`layout\` 段补 \`页面范式来源：引用内置\`（绿地）或 \`项目自有\`（棕地，需附页面类型表与容器骨架块）`);
+    } else if (/^引用内置$/.test(arche.source)) {
+      blocks.push(`${label ? `${label}：` : ''}引用内置 —— \`prototype/references/layouts.md\` 的${s.name ? ` ${s.name} ` : ''}节奏表`);
+    } else if (/^同/.test(arche.source)) {
+      blocks.push(`${label ? `${label}：` : ''}${arche.source}（完整性由被指向端保证）`);
+    } else {
+      blocks.push(`${label ? `${label}：` : ''}以下为设计系统的原文摘录，**以此为准**（内置 layouts.md 仅作回退默认）\n\n${(archeSub || '').trim()}`);
+    }
+    if (skelSub) {
+      blocks.push(`#### 容器骨架${s.name ? `（${s.name}）` : ''}\n\n以下骨架类**不在**内置 \`template.html\` 中，须按类清单契约在页面 \`<style>\` 内定义：\n\n${skelSub.trim()}`);
+    }
+  }
+  return blocks.join('\n\n');
+}
+
+const primer = `# AI Primer — 原型生成约束
+
+> 本文件由 scripts/gen-primer.mjs 从设计系统确定性生成，请勿手工编辑。
+> 生成时间：${new Date().toISOString()} | 来源：${sourceLabel} @ sha256:${digestShort}
+> 契约表：${count} 类组件（${countLabel}） | contract=${contract || 'unset'}
+
+## 可用组件白名单（只用这些）
+
+${whitelistLines.join('\n')}
+
+## Token 速查
+
+${tokenLine || '（base.md 未内联 A1 token 值，请以 design-tokens.css 为准）'}${fontDisplay}${fontBody}
+
+## 硬规则
+
+${hardRules.join('\n')}
+
+## 页面范式
+
+${pageArchetypeSection()}
+`;
+
+mkdirSync(dirname(primerPath), { recursive: true });
+writeFileSync(primerPath, primer, 'utf-8');
+console.log(`primer 已生成：${primerPath}`);
+console.log(`  组件白名单：${count} 类（${countLabel}）`);
+if (variants.length) console.log(`  参与 digest 的变体：${variants.map(v => basename(v.file)).join(' / ')}`);
+console.log(`  digest：sha256:${digestShort}`);

package/scripts/guard/checks/tasks-complete.mjs

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readState } from '../../lib/state-loader.mjs';
+import { parseTaskLine } from '../../lib/md-normalize.mjs';
 import {
   isLegacyChange,
   fullWorkflowSkipViolation,
@@ -49,16 +50,20 @@ export function checkTasksComplete(changeDir) {
   }
 
   const content = fs.readFileSync(tasksPath, 'utf-8');
-  const unchecked = content.match(/^[ \t]*- \[ \]/gm);
+  // v0.55.0 §8.4.3 横展（FB-4）：识别走共享原语 `parseTaskLine`
+  // （容忍 `*` bullet / 制表符分隔等纯格式变体）。此处是**计数/存在性语义**。
+  // 注：原实现的正则无 `$` 锚且用 `[ \t]*`，本就容忍缩进——本次不放宽也不收紧缩进。
+  const taskLines = content.split('\n').map(line => parseTaskLine(line)).filter(Boolean);
+  const uncheckedCount = taskLines.filter(task => !task.checked).length;
 
-  if (unchecked && unchecked.length > 0) {
+  if (uncheckedCount > 0) {
     return {
       pass: false,
-      failures: [`tasks.md: ${unchecked.length} unchecked task(s) remaining`],
+      failures: [`tasks.md: ${uncheckedCount} unchecked task(s) remaining`],
     };
   }
 
-  const hasAny = content.match(/^[ \t]*- \[[xX]\]/gm);
+  const hasAny = taskLines.some(task => task.checked);
   if (!hasAny) {
     return { pass: false, failures: ['tasks.md: no completed tasks found'] };
   }