@xulthekl/team-flow 0.32.2 → 0.34.0

package/scripts/lib/conventions-generator.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+// scripts/lib/conventions-generator.mjs — conventions 生成器（v0.34.0 新增）
+//
+// 根据项目技术栈自动生成测试规范 conventions，符合 glaf4-test 要求。
+// 支持存量项目（自动识别）和全新项目（交互式引导）。
+//
+// 使用方式：
+//   node scripts/lib/conventions-generator.mjs --root <项目根目录> [--interactive]
+//
+// 设计来源：test-capability-enhancement-design v1.0 §四
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import path, { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+// ── 常量 ─────────────────────────────────────────────────────────────────────
+
+const TEMPLATE_DIR = join(import.meta.dirname, '../../templates/conventions');
+const GLAF4_TEMPLATE_DIR = join(TEMPLATE_DIR, 'glaf4-compliant');
+
+// 技术栈检测特征
+const TECH_STACK_SIGNATURES = {
+  java: ['pom.xml', 'build.gradle', 'build.gradle.kts'],
+  javascript: ['package.json', 'yarn.lock', 'pnpm-lock.yaml'],
+  python: ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile'],
+};
+
+// 测试框架检测特征
+const TEST_FRAMEWORK_SIGNATURES = {
+  'junit5-mockito': { file: 'pom.xml', content: /junit-jupiter|org\.junit\.jupiter/ },
+  jest: { file: 'package.json', content: /"jest"|"@jest\/|vitest/ },
+  pytest: { file: 'requirements.txt', content: /pytest/ },
+};
+
+// 应用框架检测特征
+const APP_FRAMEWORK_SIGNATURES = {
+  'spring-boot': { file: 'pom.xml', content: /spring-boot|org\.springframework\.boot/ },
+  express: { file: 'package.json', content: /"express"/ },
+  django: { file: 'requirements.txt', content: /django/ },
+};
+
+// ── 技术栈检测 ─────────────────────────────────────────────────────────────
+
+/**
+ * 检测项目技术栈
+ * @param {string} root 项目根目录
+ * @returns {{ language: string|null, buildTool: string|null, testFramework: string|null, appFramework: string|null }}
+ */
+export function detectTechStack(root) {
+  const result = {
+    language: null,
+    buildTool: null,
+    testFramework: null,
+    appFramework: null,
+  };
+
+  // 检测语言
+  for (const [lang, files] of Object.entries(TECH_STACK_SIGNATURES)) {
+    if (files.some(f => existsSync(join(root, f)))) {
+      result.language = lang;
+      break;
+    }
+  }
+
+  // 检测构建工具
+  if (existsSync(join(root, 'pom.xml'))) result.buildTool = 'maven';
+  else if (existsSync(join(root, 'build.gradle')) || existsSync(join(root, 'build.gradle.kts'))) result.buildTool = 'gradle';
+  else if (existsSync(join(root, 'package.json'))) result.buildTool = 'npm';
+  else if (existsSync(join(root, 'yarn.lock'))) result.buildTool = 'yarn';
+  else if (existsSync(join(root, 'pnpm-lock.yaml'))) result.buildTool = 'pnpm';
+  else if (existsSync(join(root, 'requirements.txt')) || existsSync(join(root, 'pyproject.toml'))) result.buildTool = 'pip';
+  else if (existsSync(join(root, 'Pipfile'))) result.buildTool = 'pipenv';
+
+  // 检测测试框架
+  for (const [fw, sig] of Object.entries(TEST_FRAMEWORK_SIGNATURES)) {
+    const filePath = join(root, sig.file);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, 'utf-8');
+      if (sig.content.test(content)) {
+        result.testFramework = fw;
+        break;
+      }
+    }
+  }
+
+  // 检测应用框架
+  for (const [fw, sig] of Object.entries(APP_FRAMEWORK_SIGNATURES)) {
+    const filePath = join(root, sig.file);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, 'utf-8');
+      if (sig.content.test(content)) {
+        result.appFramework = fw;
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+// ── 模板选择 ─────────────────────────────────────────────────────────────
+
+/**
+ * 根据技术栈选择 conventions 模板
+ * @param {{ language: string|null, buildTool: string|null, testFramework: string|null, appFramework: string|null }} techStack
+ * @returns {string[]} 模板文件名列表
+ */
+export function selectTemplates(techStack) {
+  const templates = [];
+
+  if (techStack.language === 'java') {
+    // Java 项目：使用 glaf4-compliant 模板
+    if (existsSync(join(GLAF4_TEMPLATE_DIR, 'java-testing.md'))) {
+      templates.push('glaf4-compliant/java-testing.md');
+    }
+    if (techStack.appFramework === 'spring-boot') {
+      if (existsSync(join(GLAF4_TEMPLATE_DIR, 'spring-patterns.md'))) {
+        templates.push('glaf4-compliant/spring-patterns.md');
+      }
+    }
+  } else if (techStack.language === 'javascript') {
+    templates.push('js-testing.md');
+  } else if (techStack.language === 'python') {
+    templates.push('python-testing.md');
+  }
+
+  return templates;
+}
+
+// ── conventions 生成 ─────────────────────────────────────────────────────
+
+/**
+ * 生成 conventions 文件
+ * @param {string} root 项目根目录
+ * @param {{ language: string|null, buildTool: string|null, testFramework: string|null, appFramework: string|null }} techStack
+ * @param {string[]} templates 模板文件名列表
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function generateConventions(root, techStack, templates) {
+  const conventionsDir = join(root, '.team-flow', 'conventions');
+  const versionsFile = join(conventionsDir, '.versions.json');
+
+  // 创建目录
+  mkdirSync(conventionsDir, { recursive: true });
+
+  // 读取现有版本信息
+  let versions = {};
+  if (existsSync(versionsFile)) {
+    try {
+      versions = JSON.parse(readFileSync(versionsFile, 'utf-8'));
+    } catch {
+      versions = {};
+    }
+  }
+  if (!versions.conventions) versions.conventions = {};
+
+  const created = [];
+  const skipped = [];
+
+  for (const template of templates) {
+    const templatePath = join(TEMPLATE_DIR, template);
+    const fileName = path.basename(template);
+    const targetPath = join(conventionsDir, fileName);
+
+    // 检查是否已存在且未自定义
+    if (existsSync(targetPath)) {
+      const existingVersion = versions.conventions[fileName];
+      if (existingVersion && !existingVersion.customized) {
+        // 读取模板版本
+        const templateContent = readFileSync(templatePath, 'utf-8');
+        const versionMatch = templateContent.match(/version:\s*(\d+\.\d+\.\d+)/);
+        const templateVersion = versionMatch ? versionMatch[1] : '1.0.0';
+
+        if (existingVersion.source_version === templateVersion) {
+          skipped.push(fileName);
+          continue;
+        }
+      }
+    }
+
+    // 复制模板
+    const templateContent = readFileSync(templatePath, 'utf-8');
+    writeFileSync(targetPath, templateContent, 'utf-8');
+
+    // 更新版本信息
+    const versionMatch = templateContent.match(/version:\s*(\d+\.\d+\.\d+)/);
+    const templateVersion = versionMatch ? versionMatch[1] : '1.0.0';
+
+    versions.conventions[fileName] = {
+      source_version: templateVersion,
+      installed_at: new Date().toISOString().split('T')[0],
+      customized: false,
+      last_checked: new Date().toISOString().split('T')[0],
+      source: template,
+    };
+
+    created.push(fileName);
+  }
+
+  // 写入版本信息
+  writeFileSync(versionsFile, JSON.stringify(versions, null, 2), 'utf-8');
+
+  return { created, skipped };
+}
+
+// ── 更新 team-flow.config.json ─────────────────────────────────────────
+
+/**
+ * 更新 team-flow.config.json 的 conventions 字段
+ * @param {string} root 项目根目录
+ * @param {string[]} conventionsFiles conventions 文件名列表
+ */
+export function updateConfig(root, conventionsFiles) {
+  const teamFlowDir = join(root, '.team-flow');
+  const configPath = join(teamFlowDir, 'team-flow.config.json');
+
+  // 确保目录存在
+  mkdirSync(teamFlowDir, { recursive: true });
+
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      config = {};
+    }
+  }
+
+  if (!config.conventions) config.conventions = {};
+
+  for (const file of conventionsFiles) {
+    const key = file.replace(/\.md$/, '').replace(/\//g, '-');
+    config.conventions[key] = `.team-flow/conventions/${file}`;
+  }
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+// ── 交互式引导 ─────────────────────────────────────────────────────────────
+
+/**
+ * 交互式引导用户选择技术栈（全新项目）
+ * @returns {Promise<{ language: string, buildTool: string, testFramework: string, appFramework: string }>}
+ */
+export async function interactiveSetup() {
+  // 注意：在实际使用中，这里需要使用 readline 或 inquirer 等库
+  // 这里提供默认值，实际实现需要集成到 workflow-bootstrap 的交互流程中
+  console.log('\n=== 全新项目技术栈配置 ===\n');
+  console.log('由于当前为脚本模式，使用默认配置：');
+  console.log('  - 编程语言：Java');
+  console.log('  - 构建工具：Maven');
+  console.log('  - 测试框架：JUnit 5 + Mockito');
+  console.log('  - 应用框架：Spring Boot');
+  console.log('\n如需自定义配置，请在 workflow-bootstrap 中使用交互式模式。\n');
+
+  return {
+    language: 'java',
+    buildTool: 'maven',
+    testFramework: 'junit5-mockito',
+    appFramework: 'spring-boot',
+  };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      root: { type: 'string', default: '.' },
+      interactive: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const root = path.resolve(values.root);
+
+  // 检查项目根目录
+  if (!existsSync(root)) {
+    console.error(`项目根目录不存在: ${root}`);
+    process.exit(1);
+  }
+
+  // 检查 conventions 是否已存在
+  const conventionsDir = join(root, '.team-flow', 'conventions');
+  if (existsSync(conventionsDir) && readdirSync(conventionsDir).length > 0) {
+    console.log('⚠️  conventions 已存在，跳过生成');
+    console.log(`   路径: ${conventionsDir}`);
+    process.exit(0);
+  }
+
+  // 检测技术栈
+  let techStack = detectTechStack(root);
+
+  // 如果未检测到技术栈且启用交互式模式
+  if (!techStack.language && values.interactive) {
+    techStack = await interactiveSetup();
+  }
+
+  // 如果仍未检测到技术栈
+  if (!techStack.language) {
+    console.error('❌ 未检测到技术栈特征');
+    console.error('   请指定项目根目录，或使用 --interactive 模式手动配置');
+    process.exit(1);
+  }
+
+  // 选择模板
+  const templates = selectTemplates(techStack);
+
+  if (templates.length === 0) {
+    console.error('❌ 未找到匹配的 conventions 模板');
+    console.error(`   技术栈: ${JSON.stringify(techStack)}`);
+    process.exit(1);
+  }
+
+  // 生成 conventions
+  const result = generateConventions(root, techStack, templates);
+
+  // 更新配置
+  updateConfig(root, result.created);
+
+  // 输出结果
+  if (values.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      techStack,
+      templates,
+      created: result.created,
+      skipped: result.skipped,
+      conventionsDir,
+    }));
+  } else {
+    console.log('✅ conventions 生成完成');
+    console.log(`   技术栈: ${techStack.language} + ${techStack.testFramework}`);
+    console.log(`   创建: ${result.created.join(', ')}`);
+    if (result.skipped.length > 0) {
+      console.log(`   跳过: ${result.skipped.join(', ')}`);
+    }
+    console.log(`   路径: ${conventionsDir}`);
+  }
+}
+
+// 直接运行
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run(process.argv.slice(2)).catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/scripts/lib/test-record.mjs

@@ -93,6 +93,55 @@ const PARSERS = {
   pytest: parsePytest,
 };
 
+// ── Failure Analysis 分类法（v0.13 §57，来自 glaf4-test analyze-surefire-failures.py）────────
+
+/** 测试失败分类：assertion_failure / runtime_error / framework_error / compile_error / dependency_blocker / unknown */
+export function classifyFailure(text) {
+  const lower = text.toLowerCase();
+
+  // 1. 编译错误
+  if (lower.includes('compilation error') || lower.includes('cannot find symbol') ||
+      lower.includes('incompatible types') || lower.includes('method does not override') ||
+      lower.includes('syntaxerror') || lower.includes('indentationerror')) {
+    return 'compile_error';
+  }
+
+  // 2. 依赖阻塞
+  if (lower.includes('connection refused') || lower.includes('connection timed out') ||
+      lower.includes('unknownhostexception') || lower.includes('could not resolve host') ||
+      lower.includes('no such file or directory') || lower.includes('module not found') ||
+      lower.includes('package does not exist') || lower.includes('dependency') && lower.includes('failed')) {
+    return 'dependency_blocker';
+  }
+
+  // 3. 框架错误
+  if (lower.includes('applicationcontextexception') || lower.includes('beandefinitionstoreexception') ||
+      lower.includes('nosuchbeandefinitionexception') || lower.includes('unsatisfieddependencyexception') ||
+      lower.includes('spring') && lower.includes('failed to load') ||
+      lower.includes('contextconfiguration') || lower.includes('testcontext')) {
+    return 'framework_error';
+  }
+
+  // 4. 运行时异常
+  if (lower.includes('nullpointerexception') || lower.includes('illegalargumentexception') ||
+      lower.includes('indexoutofboundsexception') || lower.includes('classcastexception') ||
+      lower.includes('numberformatexception') || lower.includes('stackoverflowerror') ||
+      lower.includes('outofmemoryerror') || lower.includes('runtimeerror') ||
+      lower.includes('typeerror') || lower.includes('referenceerror')) {
+    return 'runtime_error';
+  }
+
+  // 5. 断言失败
+  if (lower.includes('assertionerror') || lower.includes('expected') && lower.includes('but was') ||
+      lower.includes('assertionfailederror') || lower.includes('expected :') && lower.includes('actual :') ||
+      lower.includes('expect(') || lower.includes('assert') && lower.includes('failed')) {
+    return 'assertion_failure';
+  }
+
+  // 6. 未知
+  return 'unknown';
+}
+
 /** auto 识别：按内容特征匹配 runner。 */
 export function detectRunner(text) {
   const trimmed = text.trim();
@@ -180,7 +229,18 @@ export async function run(args) {
   // 判定：failed==0 且 total>0 才算 pass（total=0 空真拒绝，v0.13 §50.2）
   const verdict = stats.failed === 0 && stats.total > 0 ? 'pass' : 'fail';
   const ts = new Date().toISOString();
-  const record = `${verdict}: total=${stats.total} passed=${stats.passed} failed=${stats.failed} skipped=${stats.skipped} runner=${runner} recorded-by=tf-test-record ts=${ts}`;
+
+  // Failure Analysis 分类（v0.13 §57，来自 glaf4-test）
+  let failureClass = null;
+  if (verdict === 'fail') {
+    const rawText = fromStat.isFile()
+      ? readFileSync(fromPath, 'utf-8')
+      : '';
+    failureClass = classifyFailure(rawText);
+  }
+
+  const failureInfo = failureClass ? ` failure_class=${failureClass}` : '';
+  const record = `${verdict}: total=${stats.total} passed=${stats.passed} failed=${stats.failed} skipped=${stats.skipped} runner=${runner} recorded-by=tf-test-record ts=${ts}${failureInfo}`;
 
   // 原始证据落盘（tests-passing 门禁与 doctor 巡检都要求该文件存在）
   const evidenceDir = join(changeDir, '.superpowers', 'test-evidence');
@@ -200,11 +260,14 @@ export async function run(args) {
   writeState(changeDir, state);
 
   if (values.json) {
-    console.log(JSON.stringify({ ok: true, verdict, ...stats, runner, test_result: record, test_evidence_path: evidenceRel }));
+    const jsonResult = { ok: true, verdict, ...stats, runner, test_result: record, test_evidence_path: evidenceRel };
+    if (failureClass) jsonResult.failure_class = failureClass;
+    console.log(JSON.stringify(jsonResult));
   } else {
     console.log(`${verdict === 'pass' ? '✅' : '❌'} test_result recorded (${runner}): total=${stats.total} passed=${stats.passed} failed=${stats.failed} skipped=${stats.skipped}`);
     console.log(`   evidence: ${evidenceRel}`);
     if (verdict === 'fail') {
+      console.log(`   failure_class: ${failureClass}`);
       console.log('   closing 将被 tests-passing 门禁阻断：修复失败后重新运行测试套件并再次 tf test record。');
     }
   }

package/skills/e2e/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e2e
-description: 从 spec 验收场景生成 Playwright E2E 测试、执行并审计覆盖率（可选 overlay）。用法: /e2e [原型|集成|验收] [spec路径]
+description: "从 spec 验收场景生成 Playwright E2E 测试、执行并审计覆盖率（可选 overlay）。用法: /e2e [原型|集成|验收] [spec路径]"
 version: 0.1.0
 user-invocable: true
 ---

package/skills/test-strategy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-strategy
-description: 测试设计方法论 skill——design_method 选择、分层策略、对抗验证、复杂度分级。build-executor 通过 skills: 预加载。
+description: 测试设计方法论 skill——design_method 选择、分层策略、对抗验证、复杂度分级。build-executor / contract-builder 通过 skills 字段预加载。
 user-invocable: false
 ---
 
@@ -68,3 +68,40 @@ user-invocable: false
 | **TDD** | 新功能/新行为 | RED→GREEN→REFACTOR |
 | **CHARACTERIZATION** | 遗留代码行为捕获 | 只写不改（不改生产代码） |
 | **REGRESSION** | 缺陷复现+修复 | 先复现再修 |
+
+## 8. 组合覆盖声明
+
+> 来源：glaf4-test design-worker 的 combination_coverage 机制（v0.13 §55）
+
+当目标方法满足以下条件之一时，矩阵中**必须声明**组合覆盖策略：
+
+### 触发条件
+
+1. **多参数方法**（param_count > 1）：声明 `pairwise`，要求至少一个 equivalence/boundary 用例覆盖参数组合
+2. **有分支逻辑**（if/case/switch）：声明 `branch`，要求至少一个 state/path 用例覆盖各分支
+
+### 声明格式
+
+在 test-matrix.md 的 description 列中声明：
+
+- `[pairwise] 已覆盖参数组合 A×B, A×C`
+- `[branch] 已覆盖 true/false 分支`
+- `[not_applicable] 单参数无分支，无需组合覆盖`
+
+### 对账规则
+
+contract-builder 生成矩阵后，必须校验：
+- 声明 `pairwise` 的目标，必须有至少 1 个 equivalence 或 boundary 用例覆盖参数组合
+- 声明 `branch` 的目标，必须有至少 1 个 state 或 path 用例覆盖各分支
+- 声明 `not_applicable` 的目标，必须提供理由（如"单参数无分支"）
+
+### 示例
+
+```markdown
+| ID | work_mode | test_tier | design_method | description | priority |
+|----|-----------|-----------|---------------|-------------|----------|
+| TC-001 | TDD | unit | equivalence | [pairwise] 正常查询：page=1, size=10 | P0 |
+| TC-002 | TDD | unit | boundary | [pairwise] 边界：page=0, size=10 | P1 |
+| TC-003 | TDD | unit | boundary | [pairwise] 边界：page=1, size=0 | P1 |
+| TC-004 | TDD | unit | error | [not_applicable] 单参数无分支，无需组合覆盖 | P1 |
+```