sdd-flow-kit 1.3.14 → 1.3.18

package/scripts/assess-playwright-e2e-coverage.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * 校验 OpenSpec change 的 Playwright E2E 覆盖是否足以验收本 change（防 module 回退钻漏洞）。
+ *
+ * 规则摘要：
+ * - delta specs 含 UI 类 Scenario 时，tasks/proposal/design 或 changeNameToSpecs 必须声明可执行的 e2e/*.spec.ts
+ * - scope=change 将回退 module 且存在 UI Scenario 时，默认 FAIL（须显式 POQUAN_ALLOW_PLAYWRIGHT_MODULE_FALLBACK=1 豁免）
+ *
+ * 用法: node scripts/assess-playwright-e2e-coverage.mjs --change <change-name>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CONFIG_PATH = path.join(ROOT, "e2e/e2e-scope.config.json");
+
+/** UI / 浏览器交互类关键词（出现在 delta Scenario 时强制要求 change 级 e2e spec） */
+const UI_SCENARIO_KEYWORDS =
+  /上传|点击|页面|按钮|弹窗|拖拽|选择文件|附件|输入框|对话框|导航|展示|卡片|加载|选文件|文件选择|工作台|Composer|toast|截图/i;
+
+/** tasks 中「单测代替集成」的典型反模式 */
+const MOCK_COVERS_INTEGRATION_RE =
+  /单测.*覆盖|mock.*覆盖|组件单测.*集成|子组件单测|仅靠.*单测/i;
+
+function loadConfig() {
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+}
+
+function parseArgs(argv) {
+  let change = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) {
+      change = argv[++i];
+    } else if (!a.startsWith("-") && !change) {
+      change = a;
+    }
+  }
+  return { change };
+}
+
+function findChangeDir(changeName) {
+  const active = path.join(ROOT, "openspec/changes", changeName);
+  if (fs.existsSync(active)) return active;
+  return null;
+}
+
+function readChangeArtifacts(changeDir) {
+  const files = ["tasks.md", "proposal.md", "design.md"];
+  const parts = {};
+  let blob = "";
+  for (const f of files) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    const content = fs.readFileSync(fp, "utf8");
+    parts[f] = content;
+    blob += `${content}\n`;
+  }
+  return { parts, blob };
+}
+
+/** 统计 delta specs 中的 Scenario 数量，并检测是否含 UI 交互描述 */
+function analyzeDeltaSpecs(changeDir) {
+  const specsDir = path.join(changeDir, "specs");
+  let scenarioCount = 0;
+  let uiScenarioCount = 0;
+  let deltaBlob = "";
+
+  if (!fs.existsSync(specsDir)) {
+    return { scenarioCount, uiScenarioCount, deltaBlob };
+  }
+
+  for (const cap of fs.readdirSync(specsDir, { withFileTypes: true })) {
+    if (!cap.isDirectory()) continue;
+    const specPath = path.join(specsDir, cap.name, "spec.md");
+    if (!fs.existsSync(specPath)) continue;
+    const content = fs.readFileSync(specPath, "utf8");
+    deltaBlob += `${content}\n`;
+    const blocks = content.split(/^####\s+Scenario:/m);
+    for (let i = 1; i < blocks.length; i += 1) {
+      scenarioCount += 1;
+      if (UI_SCENARIO_KEYWORDS.test(blocks[i])) {
+        uiScenarioCount += 1;
+      }
+    }
+  }
+  return { scenarioCount, uiScenarioCount, deltaBlob };
+}
+
+/** 从 change 文档与配置收集本 change 绑定的 e2e spec 路径（须文件存在） */
+function collectChangeE2eSpecs(changeName, changeDir, config) {
+  const specs = new Set();
+  const specRe = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
+
+  if (changeDir) {
+    for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+      const fp = path.join(changeDir, f);
+      if (!fs.existsSync(fp)) continue;
+      const content = fs.readFileSync(fp, "utf8");
+      let m;
+      while ((m = specRe.exec(content)) !== null) {
+        const rel = m[0];
+        if (fs.existsSync(path.join(ROOT, rel))) specs.add(rel);
+      }
+    }
+  }
+
+  const overrides = config.changeNameToSpecs?.[changeName];
+  if (overrides) {
+    for (const raw of overrides) {
+      const rel = raw.startsWith("e2e/") ? raw : `e2e/${raw}`;
+      if (fs.existsSync(path.join(ROOT, rel))) specs.add(rel);
+    }
+  }
+  return [...specs].sort();
+}
+
+function hasExempt(tasksContent) {
+  if (!tasksContent) return { tdd: false, playwright: false };
+  const tdd = /^TDD_EXEMPT:/m.test(tasksContent);
+  const playwright = /^PLAYWRIGHT_E2E_EXEMPT:/m.test(tasksContent);
+  return { tdd, playwright };
+}
+
+function wouldModuleFallback(changeName, specPaths, config) {
+  if (specPaths.length > 0) return false;
+  const fallback = config.changeScopeFallback ?? "module";
+  return fallback === "module";
+}
+
+function fail(messages) {
+  console.error("[assess-playwright-e2e-coverage] FAIL");
+  for (const msg of messages) {
+    console.error(`  - ${msg}`);
+  }
+  console.error(
+    "  修复: 在 tasks.md 增加 E.1/E.2（写明 e2e/*.spec.ts 路径），或 e2e-scope.config.json → changeNameToSpecs；",
+  );
+  console.error(
+    "  纯无 UI 交互可声明 PLAYWRIGHT_E2E_EXEMPT: <原因>；module 回退须 POQUAN_ALLOW_PLAYWRIGHT_MODULE_FALLBACK=1",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip =
+    process.env.POQUAN_SKIP_PLAYWRIGHT_CHANGE_COVERAGE ||
+    process.env.OPSX_SKIP_PLAYWRIGHT_CHANGE_COVERAGE;
+  if (skip === "1") {
+    console.warn(
+      "[assess-playwright-e2e-coverage] SKIP: POQUAN_SKIP_PLAYWRIGHT_CHANGE_COVERAGE=1",
+    );
+    process.exit(0);
+  }
+
+  const { change } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-playwright-e2e-coverage] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = findChangeDir(change);
+  if (!changeDir) {
+    console.error(
+      `[assess-playwright-e2e-coverage] 活跃 change 不存在: openspec/changes/${change}`,
+    );
+    process.exit(2);
+  }
+
+  const config = loadConfig();
+  const { parts, blob: artifactBlob } = readChangeArtifacts(changeDir);
+  const { scenarioCount, uiScenarioCount, deltaBlob } = analyzeDeltaSpecs(changeDir);
+  const exempt = hasExempt(parts["tasks.md"]);
+  const specPaths = collectChangeE2eSpecs(change, changeDir, config);
+  const moduleFallback = wouldModuleFallback(change, specPaths, config);
+  const allowFallback =
+    process.env.POQUAN_ALLOW_PLAYWRIGHT_MODULE_FALLBACK === "1" ||
+    process.env.OPSX_ALLOW_PLAYWRIGHT_MODULE_FALLBACK === "1";
+
+  if (exempt.tdd || exempt.playwright) {
+    console.log(
+      `[assess-playwright-e2e-coverage] PASS（豁免） change=${change} ` +
+        `TDD_EXEMPT=${exempt.tdd} PLAYWRIGHT_E2E_EXEMPT=${exempt.playwright}`,
+    );
+    process.exit(0);
+  }
+
+  const errors = [];
+  const requiresChangeE2e = uiScenarioCount > 0;
+
+  if (requiresChangeE2e && specPaths.length === 0) {
+    errors.push(
+      `delta 含 ${uiScenarioCount} 个 UI/浏览器交互 Scenario，但未在 tasks/proposal/design 或 changeNameToSpecs 中绑定 e2e/*.spec.ts`,
+    );
+  }
+
+  if (requiresChangeE2e && moduleFallback && !allowFallback) {
+    errors.push(
+      `scope=change 将回退 module 目录（changeScopeFallback=module），无法验收本 change 的 UI Scenario；禁止用模块 smoke 代替 change 验收`,
+    );
+  }
+
+  const tasksContent = parts["tasks.md"] || "";
+  if (
+    requiresChangeE2e &&
+    MOCK_COVERS_INTEGRATION_RE.test(tasksContent) &&
+    !/\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/.test(tasksContent)
+  ) {
+    errors.push(
+      "tasks.md 声称「单测/mock 覆盖集成」但未写明 e2e/*.spec.ts；DOM/Network 交互类功能禁止仅用 mock 单测宣布验收",
+    );
+  }
+
+  if (requiresChangeE2e && specPaths.length > 0) {
+    const hasE2eTask =
+      /E\.1|E2E|playwright test|e2e\/[\w/.-]+\.spec/.test(tasksContent);
+    if (!hasE2eTask) {
+      errors.push(
+        `已配置 e2e spec（${specPaths.join(", ")}），但 tasks.md 缺少 E.1/E.2 Playwright 验收项`,
+      );
+    }
+  }
+
+  if (scenarioCount > 0 && uiScenarioCount === 0 && specPaths.length === 0 && moduleFallback) {
+    console.warn(
+      `[assess-playwright-e2e-coverage] WARN change=${change}: ` +
+        `${scenarioCount} 个 Scenario 未命中 UI 关键词，将允许 module 回退；若含隐式 UI 行为请补 e2e spec`,
+    );
+  }
+
+  if (errors.length > 0) {
+    fail(errors);
+  }
+
+  console.log(
+    `[assess-playwright-e2e-coverage] PASS change=${change} ` +
+      `scenarios=${scenarioCount} uiScenarios=${uiScenarioCount} ` +
+      `e2eSpecs=${specPaths.length > 0 ? specPaths.join(" ") : "(none)"} ` +
+      `moduleFallback=${moduleFallback}`,
+  );
+}
+
+main();

package/scripts/assess-tech-doc-quality.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * 校验 04-技术文档草稿.md 是否符合模板结构（gate docs-closed 同款规则）。
+ *
+ * 用法: node scripts/assess-tech-doc-quality.mjs --run-dir <openspec/PRD/runId>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const REQUIRED = [
+  { label: "文档元信息", re: /##\s*文档元信息/m },
+  { label: "1. 改造范围", re: /##\s*1\.\s*改造范围/m },
+  { label: "2. 页面与交互设计", re: /##\s*2\.\s*页面与交互设计/m },
+  { label: "2.4 演示代码参照", re: /###\s*2\.4\s*演示代码参照/m },
+  { label: "3. 前端状态与数据模型设计", re: /##\s*3\.\s*前端状态与数据模型设计/m },
+  { label: "4. 接口与数据交互设计", re: /##\s*4\.\s*接口与数据交互设计/m },
+  { label: "5. 表单与校验设计", re: /##\s*5\.\s*表单与校验设计/m },
+  { label: "6. 异常、边界与降级方案", re: /##\s*6\.\s*异常、边界与降级方案/m },
+  { label: "7. 改造清单", re: /##\s*7\.\s*改造清单/m },
+  { label: "8. 风险点与应对策略", re: /##\s*8\.\s*风险点与应对策略/m },
+  { label: "9. 发布、灰度与回滚", re: /##\s*9\.\s*发布、灰度与回滚/m },
+  { label: "10. 测试与验收要点", re: /##\s*10\.\s*测试与验收要点/m },
+  { label: "11. 待确认事项", re: /##\s*11\.\s*待确认事项/m },
+];
+
+const MIN_LINES = 150;
+
+function parseArgs(argv) {
+  let runDir = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--run-dir" && argv[i + 1]) runDir = argv[++i];
+    else if (!a.startsWith("-") && !runDir) runDir = a;
+  }
+  return { runDir };
+}
+
+function fail(messages) {
+  console.error("[assess-tech-doc-quality] FAIL");
+  for (const m of messages) console.error(`  - ${m}`);
+  console.error("  修复: 在现有 04-技术文档草稿.md 模板上逐节填写，见 04-技术文档生成指引.md");
+  process.exit(1);
+}
+
+function main() {
+  const skip = process.env.OPSX_SKIP_TECH_DOC_QUALITY;
+  if (skip === "1") {
+    console.warn("[assess-tech-doc-quality] SKIP");
+    process.exit(0);
+  }
+
+  const { runDir } = parseArgs(process.argv);
+  if (!runDir) {
+    console.error("[assess-tech-doc-quality] 缺少 --run-dir <openspec/PRD/runId>");
+    process.exit(2);
+  }
+
+  const absRun = path.isAbsolute(runDir) ? runDir : path.join(ROOT, runDir);
+  const docPath = path.join(absRun, "04-技术文档草稿.md");
+  if (!fs.existsSync(docPath)) {
+    fail(["04-技术文档草稿.md 不存在"]);
+  }
+
+  const content = fs.readFileSync(docPath, "utf8");
+  const lines = content.split("\n");
+  const errors = [];
+
+  if (lines.length < MIN_LINES) {
+    errors.push(`行数 ${lines.length} < ${MIN_LINES}，疑似摘要版而非完整技术文档`);
+  }
+
+  for (const sec of REQUIRED) {
+    if (!sec.re.test(content)) errors.push(`缺少章节: ${sec.label}`);
+  }
+
+  if (!/\|\s*接口\s*\|\s*Method\s*\|/m.test(content)) {
+    errors.push("缺少 §4.1 接口清单表格");
+  }
+
+  if (!/\|\s*演示模块\s*\|\s*演示文件\/组件\s*\|/m.test(content)) {
+    errors.push("缺少 §2.4 演示模块映射表格");
+  }
+
+  if (errors.length > 0) fail(errors);
+  console.log(`[assess-tech-doc-quality] PASS lines=${lines.length} path=${docPath}`);
+}
+
+main();

package/scripts/install-git-hooks.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# 安装 pre-commit：提交前执行 opsx:gate（见 AGENTS.md）
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+HOOK_PATH="$(git -C "$ROOT_DIR" rev-parse --git-dir 2>/dev/null)/hooks/pre-commit"
+
+if [[ ! -d "$(dirname "$HOOK_PATH")" ]]; then
+  echo "[opsx:install-hooks] ERROR: 不在 git 仓库内" >&2
+  exit 1
+fi
+
+cat >"$HOOK_PATH" <<'HOOK'
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+if command -v pnpm >/dev/null 2>&1; then
+  pnpm run opsx:gate
+else
+  bash scripts/assert-active-openspec-change.sh
+fi
+HOOK
+
+chmod +x "$HOOK_PATH"
+echo "[opsx:install-hooks] 已安装 pre-commit -> $HOOK_PATH"
+echo "[opsx:install-hooks] 提交含 src/ 或 e2e/ 改动时将校验 OpenSpec change 绑定"

package/scripts/lib/test-assertion-analysis.mjs

@@ -0,0 +1,134 @@
+/**
+ * 测试断言分析（与 src/core/testAssertionAnalysis.ts 保持语义一致，供 scripts 独立运行）。
+ */
+
+const TEST_TITLE_RE = /(?:^|\n)\s*(?:test|it)(?:\.(?:only|skip))?\s*\(\s*(?:async\s*)?[`'"]([^`'"]*)[`'"]/g;
+const EXPECT_RE = /\bexpect\s*\(/;
+const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
+const REGISTRY_STUB_FILE_RE = /prd-atoms-coverage|prd-atoms-registry|semantic-registry/i;
+const PLACEHOLDER_ONLY_RE = /getByPlaceholder|getByLabel|getByTestId/i;
+const DATA_ASSERTION_RE =
+  /getByRole\s*\(\s*['"]cell|getByRole\s*\(\s*['"]row|toContainText|waitForResponse|\.n-data-table|data-table-tbody|data-table-body/i;
+const HOOK_TITLE_RE = /^(?:beforeEach|afterEach|beforeAll|afterAll)$/i;
+
+export function stripComments(content) {
+  let out = "";
+  let i = 0;
+  while (i < content.length) {
+    if (content[i] === "/" && content[i + 1] === "/") {
+      while (i < content.length && content[i] !== "\n") i += 1;
+      continue;
+    }
+    if (content[i] === "/" && content[i + 1] === "*") {
+      i += 2;
+      while (i < content.length && !(content[i] === "*" && content[i + 1] === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    out += content[i];
+    i += 1;
+  }
+  return out;
+}
+
+export function parseTestBlocks(content) {
+  const stripped = stripComments(content);
+  const blocks = [];
+  const re = new RegExp(TEST_TITLE_RE.source, "g");
+  let m;
+  const indices = [];
+  let idx = 0;
+  while ((m = re.exec(stripped)) !== null) {
+    indices.push({ title: m[1] ?? "", start: m.index, index: idx });
+    idx += 1;
+  }
+  for (let i = 0; i < indices.length; i += 1) {
+    const cur = indices[i];
+    const nextStart = indices[i + 1]?.start ?? stripped.length;
+    const slice = stripped.slice(cur.start, Math.min(cur.start + 4000, nextStart));
+    blocks.push({ title: cur.title, body: slice, index: cur.index });
+  }
+  return blocks;
+}
+
+export function isRegistryStubFile(relPath, content) {
+  const norm = relPath.replace(/\\/g, "/");
+  if (REGISTRY_STUB_FILE_RE.test(norm)) return true;
+  if (!E2E_DIR_RE.test(norm)) return false;
+  const blocks = parseTestBlocks(content);
+  if (blocks.length === 0) return false;
+  const allShallow = blocks.every((b) => {
+    const hasExpect = EXPECT_RE.test(b.body);
+    const onlyCount =
+      /expect\s*\([^)]*\)\s*\.toBeGreaterThan\s*\(\s*0\s*\)/.test(b.body) &&
+      !DATA_ASSERTION_RE.test(b.body) &&
+      !/\bpage\.goto\b/.test(b.body);
+    return !hasExpect || onlyCount;
+  });
+  return allShallow && blocks.length >= 3;
+}
+
+export function testBlockIsPlaceholderOnly(block) {
+  if (HOOK_TITLE_RE.test(block.title.trim())) return false;
+  if (!EXPECT_RE.test(block.body)) return false;
+  const hasPlaceholder = PLACEHOLDER_ONLY_RE.test(block.body);
+  const hasData = DATA_ASSERTION_RE.test(block.body);
+  const hasInteraction = /\b(?:click|dblclick|fill|press|selectOption)\b/.test(block.body);
+  return hasPlaceholder && !hasData && !hasInteraction;
+}
+
+export function analyzeE2eSpecDepth(relPath, content) {
+  const issues = [];
+  if (isRegistryStubFile(relPath, content)) {
+    return {
+      ok: false,
+      issues: ["伪覆盖登记文件，不能作为 change 级 E2E 验收"],
+      stats: { testCount: 0, testsWithExpect: 0, hasGoto: false, hasDataAssertion: false, hasInteraction: false },
+    };
+  }
+
+  const stripped = stripComments(content);
+  const blocks = parseTestBlocks(content);
+  const hookBlocks = blocks.filter((b) => HOOK_TITLE_RE.test(b.title.trim()));
+  const testBlocks = blocks.filter((b) => !HOOK_TITLE_RE.test(b.title.trim()));
+  const testsWithExpect = testBlocks.filter((b) => EXPECT_RE.test(b.body)).length;
+  const hasGoto = /\bpage\.goto\b/.test(stripped);
+  const hasDataInTests = testBlocks.some((b) => DATA_ASSERTION_RE.test(b.body));
+  const hasInteractionInTests = testBlocks.some((b) =>
+    /\b(?:click|dblclick|fill|press|selectOption)\b/.test(b.body),
+  );
+  const placeholderOnlyTests = testBlocks.filter((b) => testBlockIsPlaceholderOnly(b));
+
+  if (testBlocks.length === 0) issues.push("未解析到 test/it 用例（不含 hook）");
+  if (testsWithExpect === 0) issues.push("无含 expect( 的 test/it 块");
+  if (!hasGoto && !hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) {
+    issues.push("缺少 page.goto（页面可达性未验证）");
+  }
+  if (placeholderOnlyTests.length > 0) {
+    issues.push(
+      `以下用例仅断言 placeholder/label: ${placeholderOnlyTests.map((t) => t.title).join(", ")}`,
+    );
+  }
+  if (!hasDataInTests && !hasInteractionInTests) {
+    issues.push("所有 test 块均缺少数据展示断言或交互操作");
+  }
+
+  const ok =
+    testBlocks.length > 0 &&
+    testsWithExpect > 0 &&
+    (hasGoto || hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) &&
+    placeholderOnlyTests.length === 0 &&
+    (hasDataInTests || hasInteractionInTests);
+
+  return {
+    ok,
+    issues,
+    stats: {
+      testCount: testBlocks.length,
+      testsWithExpect,
+      hasGoto,
+      hasDataAssertion: hasDataInTests,
+      hasInteraction: hasInteractionInTests,
+    },
+  };
+}