sdd-flow-kit 1.3.15 → 1.3.21

package/dist/core/testAssertionAnalysis.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * 测试断言深度分析：用于 PRD 语义覆盖、AC 映射与 E2E 深度门禁。
+ * 禁止仅靠注释登记 PRD/AC；要求 test/it 块内存在 expect 等有效断言。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripComments = stripComments;
+exports.parseTestBlocks = parseTestBlocks;
+exports.isRegistryStubFile = isRegistryStubFile;
+exports.testBlockHasExpect = testBlockHasExpect;
+exports.testBlockReferencesAc = testBlockReferencesAc;
+exports.testBlockReferencesAtom = testBlockReferencesAtom;
+exports.hasMeaningfulAtomCoverageInFile = hasMeaningfulAtomCoverageInFile;
+exports.hasMeaningfulAcCoverageInFile = hasMeaningfulAcCoverageInFile;
+exports.testBlockIsPlaceholderOnly = testBlockIsPlaceholderOnly;
+exports.analyzeE2eSpecDepth = analyzeE2eSpecDepth;
+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;
+/** 仅用于登记 PRD 原子、无真实 UI 断言的伪覆盖文件 */
+const REGISTRY_STUB_FILE_RE = /prd-atoms-coverage|prd-atoms-registry|semantic-registry/i;
+/** 浅层 E2E：仅有占位符可见性断言 */
+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;
+/** 移除行注释与块注释，避免注释中的 PRD 或 AC 标识误计为覆盖 */
+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;
+}
+/** 解析 test/it 块（标题 + 回调体近似区间） */
+function parseTestBlocks(content) {
+    var _a, _b, _c;
+    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: (_a = m[1]) !== null && _a !== void 0 ? _a : "", start: m.index, index: idx });
+        idx += 1;
+    }
+    for (let i = 0; i < indices.length; i += 1) {
+        const cur = indices[i];
+        const nextStart = (_c = (_b = indices[i + 1]) === null || _b === void 0 ? void 0 : _b.start) !== null && _c !== void 0 ? _c : 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;
+}
+/** 是否为 PRD 原子登记类伪覆盖文件 */
+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;
+}
+function testBlockHasExpect(block) {
+    return EXPECT_RE.test(block.body);
+}
+/** test 块是否引用 AC（标题或块内显式标注） */
+function testBlockReferencesAc(block, acId) {
+    const bracket = `[${acId}]`;
+    const upper = acId.toUpperCase();
+    return (block.title.includes(bracket) ||
+        block.title.toUpperCase().includes(upper) ||
+        block.body.includes(bracket));
+}
+/** test 块是否引用 PRD 原子或可核对信号 */
+function testBlockReferencesAtom(block, atomId, signals) {
+    const hasId = block.title.includes(atomId) ||
+        block.title.includes(`[${atomId}]`) ||
+        block.body.includes(atomId);
+    if (hasId)
+        return true;
+    return signals.some((s) => s.length >= 4 && (block.title.includes(s) || block.body.includes(s)));
+}
+/**
+ * 判断单条测试文件是否对 PRD 原子有「有效」自动化覆盖（非注释、非 stub、含 expect）。
+ */
+function hasMeaningfulAtomCoverageInFile(relPath, content, atomId, signals) {
+    if (isRegistryStubFile(relPath, content)) {
+        return { covered: false, hasE2e: false };
+    }
+    const isE2e = E2E_DIR_RE.test(relPath);
+    const blocks = parseTestBlocks(content);
+    for (const block of blocks) {
+        if (!testBlockHasExpect(block))
+            continue;
+        if (!testBlockReferencesAtom(block, atomId, signals))
+            continue;
+        return { covered: true, hasE2e: isE2e };
+    }
+    return { covered: false, hasE2e: false };
+}
+/**
+ * 判断单条测试文件是否对 AC 有有效覆盖（test 块内 [AC-XX] + expect）。
+ */
+function hasMeaningfulAcCoverageInFile(relPath, content, acId) {
+    if (isRegistryStubFile(relPath, content)) {
+        return { covered: false, isE2e: false };
+    }
+    const isE2e = E2E_DIR_RE.test(relPath);
+    const blocks = parseTestBlocks(content);
+    for (const block of blocks) {
+        if (!testBlockReferencesAc(block, acId))
+            continue;
+        if (!testBlockHasExpect(block))
+            continue;
+        return { covered: true, isE2e };
+    }
+    return { covered: false, isE2e: false };
+}
+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;
+}
+/**
+ * 评估单个 E2E spec 的断言深度（L3 最低要求）。
+ * 每个非 hook 的 test 块不得仅断言 placeholder；至少一个 test 块须含数据或交互断言。
+ */
+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) => testBlockHasExpect(b)).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 块均缺少数据展示断言（cell/row/toContainText/waitForResponse）或交互操作");
+    }
+    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,
+        },
+    };
+}

package/dist/core/visualRegression.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVisualAcRequirements = parseVisualAcRequirements;
+exports.listPrdSourceImages = listPrdSourceImages;
+exports.resolveBaselinePath = resolveBaselinePath;
+exports.checkVisualRegression = checkVisualRegression;
+/**
+ * L4 视觉回归门禁：05 visual AC + 基线图存在 + E2E toHaveScreenshot 绑定。
+ */
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const e2eAssertionDepth_1 = require("./e2eAssertionDepth");
+const fs_1 = require("./fs");
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const IMAGE_REF_RE = /(?:source\/[\w/.-]+\.(?:png|jpe?g|webp)|visual-baseline\/[\w/.-]+\.(?:png|jpe?g|webp)|image_\d+\.(?:png|jpe?g|webp))/gi;
+const DIFF_PERCENT_RE = /diff\s*[≤<=]\s*(\d+(?:\.\d+)?)\s*%/i;
+const TO_HAVE_SCREENSHOT_RE = /\btoHaveScreenshot\s*\(/;
+const PAGE_SCREENSHOT_ONLY_RE = /\bpage\.screenshot\s*\(/;
+const UI_SCENARIO_KEYWORDS = /上传|点击|页面|按钮|弹窗|列表|表格|展示|抽屉|详情|编辑|导出|筛选|输入框|对话框|导航|toast|截图|布局/i;
+/**
+ * 从验收标准提取基线图路径与 diff 阈值（如 diff≤2%）。
+ */
+function parseVisualAcRequirements(items) {
+    var _a, _b, _c;
+    const out = [];
+    for (const item of items) {
+        if (!/visual/i.test((_a = item.testType) !== null && _a !== void 0 ? _a : ""))
+            continue;
+        const criterion = (_b = item.criterion) !== null && _b !== void 0 ? _b : "";
+        const baselineRefs = [...new Set(((_c = criterion.match(IMAGE_REF_RE)) !== null && _c !== void 0 ? _c : []).map((s) => s.trim()))];
+        const diffMatch = criterion.match(DIFF_PERCENT_RE);
+        const maxDiffPercent = diffMatch ? Number(diffMatch[1]) : null;
+        out.push({
+            acId: item.id,
+            criterion,
+            baselineRefs,
+            maxDiffPercent,
+        });
+    }
+    return out;
+}
+async function walkImages(dir, out) {
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of entries) {
+        const full = path_1.default.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            await walkImages(full, out);
+        }
+        else if (/\.(png|jpe?g|webp)$/i.test(ent.name)) {
+            out.push(full);
+        }
+    }
+}
+/** PRD run 的 source/ 下是否存在原型截图 */
+async function listPrdSourceImages(outputRoot) {
+    const sourceDir = path_1.default.join(outputRoot, "source");
+    const images = [];
+    await walkImages(sourceDir, images);
+    return images;
+}
+/**
+ * 将验收标准中的基线引用解析为磁盘绝对路径。
+ */
+async function resolveBaselinePath(pkgRoot, outputRoot, ref, prdImages) {
+    const normalized = ref.replace(/\\/g, "/");
+    const candidates = [];
+    if (outputRoot) {
+        candidates.push(path_1.default.join(outputRoot, normalized));
+        candidates.push(path_1.default.join(outputRoot, "visual-baseline", path_1.default.basename(normalized)));
+    }
+    candidates.push(path_1.default.join(pkgRoot, normalized));
+    candidates.push(path_1.default.join(pkgRoot, "visual-baseline", path_1.default.basename(normalized)));
+    for (const c of candidates) {
+        const content = await (0, fs_1.readFileIfExists)(c);
+        if (content !== null)
+            return c;
+    }
+    if (/^image_\d+\./i.test(normalized)) {
+        const hit = prdImages.find((p) => path_1.default.basename(p) === path_1.default.basename(normalized));
+        if (hit)
+            return hit;
+    }
+    const byBase = prdImages.find((p) => p.endsWith(`/${path_1.default.basename(normalized)}`));
+    return byBase !== null && byBase !== void 0 ? byBase : null;
+}
+function e2eBlockHasVisualAssertion(blockBody) {
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    return TO_HAVE_SCREENSHOT_RE.test(body);
+}
+function e2eReferencesBaseline(blockBody, baselineRefs) {
+    if (baselineRefs.length === 0)
+        return TO_HAVE_SCREENSHOT_RE.test((0, testAssertionAnalysis_1.stripComments)(blockBody));
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    return baselineRefs.some((ref) => {
+        const base = path_1.default.basename(ref).replace(/\.(png|jpe?g|webp)$/i, "");
+        return body.includes(ref) || body.includes(base) || body.includes(`'${base}'`) || body.includes(`"${base}"`);
+    });
+}
+async function changeHasUiScenarios(pkgRoot, changeName) {
+    const specsDir = path_1.default.join(pkgRoot, "openspec/changes", changeName, "specs");
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(specsDir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const cap of entries) {
+        if (!cap.isDirectory())
+            continue;
+        const specPath = path_1.default.join(specsDir, cap.name, "spec.md");
+        const content = await (0, fs_1.readFileIfExists)(specPath);
+        if (!content)
+            continue;
+        const blocks = content.split(/^####\s+Scenario:/m);
+        for (let i = 1; i < blocks.length; i += 1) {
+            if (UI_SCENARIO_KEYWORDS.test(blocks[i]))
+                return true;
+        }
+    }
+    return false;
+}
+function hasVisualExempt(tasksContent) {
+    return /^VISUAL_REGRESSION_EXEMPT:/m.test(tasksContent);
+}
+/**
+ * 视觉回归静态门禁（deliver 前）：基线图 + toHaveScreenshot 与 visual AC 绑定。
+ */
+async function checkVisualRegression(pkgRoot, outputRoot, changeName, acItems) {
+    var _a, _b;
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_VISUAL_REGRESSION === "1" ||
+        process.env.OPSX_SKIP_VISUAL_REGRESSION === "1";
+    if (skip) {
+        checks.push({
+            name: "visual-regression",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_VISUAL_REGRESSION=1",
+        });
+        return checks;
+    }
+    const tasksContent = (_a = (await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, "openspec/changes", changeName, "tasks.md")))) !== null && _a !== void 0 ? _a : "";
+    if (hasVisualExempt(tasksContent)) {
+        checks.push({
+            name: "visual-regression",
+            ok: true,
+            detail: "VISUAL_REGRESSION_EXEMPT 已声明，跳过视觉回归门禁",
+        });
+        return checks;
+    }
+    const visualReqs = parseVisualAcRequirements(acItems);
+    const prdImages = outputRoot ? await listPrdSourceImages(outputRoot) : [];
+    const requiresUi = await changeHasUiScenarios(pkgRoot, changeName);
+    const specPaths = await (0, e2eAssertionDepth_1.collectChangeE2eSpecs)(pkgRoot, changeName);
+    if (prdImages.length > 0 && requiresUi && visualReqs.length === 0) {
+        checks.push({
+            name: "visual-ac-required",
+            ok: false,
+            detail: `PRD source 含 ${prdImages.length} 张原型图，但 05 无 visual 类型 AC；请补充基线对比验收项（如 AC-xx-v | visual | 基线 image_3.png）`,
+        });
+        return checks;
+    }
+    if (visualReqs.length === 0) {
+        checks.push({
+            name: "visual-regression",
+            ok: true,
+            detail: "无 visual 类型 AC，跳过视觉回归门禁",
+        });
+        return checks;
+    }
+    const failures = [];
+    let e2eBlob = "";
+    const e2eBlocks = [];
+    for (const rel of specPaths) {
+        const content = (_b = (await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, rel)))) !== null && _b !== void 0 ? _b : "";
+        e2eBlob += content;
+        for (const block of (0, testAssertionAnalysis_1.parseTestBlocks)(content)) {
+            e2eBlocks.push({ spec: rel, title: block.title, body: block.body });
+        }
+    }
+    if (specPaths.length === 0) {
+        failures.push("含 visual AC 但未绑定 e2e spec");
+    }
+    else if (!TO_HAVE_SCREENSHOT_RE.test(e2eBlob)) {
+        failures.push("e2e spec 须使用 toHaveScreenshot 做基线对比（禁止仅 page.screenshot 留证）");
+    }
+    for (const req of visualReqs) {
+        if (req.baselineRefs.length === 0) {
+            failures.push(`${req.acId}: visual AC 验收标准须写明基线路径（source/...png 或 visual-baseline/...png）`);
+            continue;
+        }
+        for (const ref of req.baselineRefs) {
+            const abs = await resolveBaselinePath(pkgRoot, outputRoot, ref, prdImages);
+            if (!abs) {
+                failures.push(`${req.acId}: 基线图不存在 ${ref}（请在 PRD run visual-baseline/ 或 source/ 放置）`);
+            }
+        }
+        const boundBlocks = e2eBlocks.filter((b) => (0, testAssertionAnalysis_1.testBlockReferencesAc)({ title: b.title, body: b.body, index: 0 }, req.acId) && e2eBlockHasVisualAssertion(b.body));
+        if (boundBlocks.length === 0) {
+            failures.push(`${req.acId}: 须在 e2e test 块内含 [${req.acId}] 且调用 toHaveScreenshot（建议 maxDiffPixelRatio≤${req.maxDiffPercent != null ? (req.maxDiffPercent / 100).toFixed(2) : "0.02"}）`);
+            continue;
+        }
+        const baselineBound = boundBlocks.some((b) => e2eReferencesBaseline(b.body, req.baselineRefs));
+        if (!baselineBound && req.baselineRefs.length > 0) {
+            failures.push(`${req.acId}: toHaveScreenshot 须引用基线名 ${req.baselineRefs.map((r) => path_1.default.basename(r)).join("、")}`);
+        }
+        if (req.maxDiffPercent != null) {
+            const ratio = req.maxDiffPercent / 100;
+            const hasRatio = boundBlocks.some((b) => {
+                const body = (0, testAssertionAnalysis_1.stripComments)(b.body);
+                if (new RegExp(`maxDiffPixelRatio:\\s*${ratio}`).test(body))
+                    return true;
+                if (ratio <= 0.02 && /maxDiffPixelRatio:\s*0\.0[12]/.test(body))
+                    return true;
+                return false;
+            });
+            if (!hasRatio) {
+                failures.push(`${req.acId}: 建议 toHaveScreenshot 配置 maxDiffPixelRatio: ${ratio}（与验收标准 diff≤${req.maxDiffPercent}% 一致）`);
+            }
+        }
+    }
+    const screenshotOnlyNoCompare = PAGE_SCREENSHOT_ONLY_RE.test(e2eBlob) && !TO_HAVE_SCREENSHOT_RE.test(e2eBlob);
+    if (screenshotOnlyNoCompare) {
+        failures.push("存在 page.screenshot 但无 toHaveScreenshot，不能算作视觉回归");
+    }
+    checks.push({
+        name: "visual-regression",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `视觉回归绑定通过（${visualReqs.length} 条 visual AC，spec: ${specPaths.join(", ") || "无"}）`
+            : failures.join(" | "),
+    });
+    return checks;
+}

package/dist/core/writeNext.js

@@ -35,7 +35,7 @@ async function writeInitialNext(outputRoot, projectRoot, runId) {
         "| `tasks.md` | AC 的可执行映射（`[AC-XX]`） |",
         "",
         "## 1. Step1 — 拉取 PRD",
-        "按 `01-获取需求文档指引.md` 执行 confluence 脚本；脚本和 gate 会拒绝 `技术文档`/`后端`/`详细设计` 等非 PRD 页面，然后：",
+        "按 `01-获取需求文档指引.md` 执行 confluence 脚本（设置 `SDD_SYNC_SOURCE_DIR` 后自动同步到 `source/PRD.md` + `source/image/`）；脚本和 gate 会拒绝 `技术文档`/`后端`/`详细设计` 等非 PRD 页面，然后：",
         "```bash",
         `npx sdd-flow-kit gate --project-root "${pr}" --run-id ${runId} --expect prd-fetched`,
         `npx sdd-flow-kit phase advance --project-root "${pr}" --run-id ${runId} --to after-prd`,

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadRunSession = exports.resolveRunDir = exports.runDeliver = exports.runPropose = exports.runPhaseAdvance = exports.printGateResult = exports.runGate = exports.toRunOptions = exports.parseInvokeText = exports.runDoctor = exports.setupProject = exports.runFlow = exports.startFlowScaffold = void 0;
+exports.loadRunSession = exports.resolveRunDir = exports.tryAutoSyncSourcePrd = exports.syncSourcePrdFromDocs = exports.runSyncSourcePrd = exports.runDeliver = exports.runPropose = exports.runPhaseAdvance = exports.printGateResult = exports.runGate = exports.toRunOptions = exports.parseInvokeText = exports.runDoctor = exports.setupProject = exports.runFlow = exports.startFlowScaffold = void 0;
 var startFlow_1 = require("./steps/startFlow");
 Object.defineProperty(exports, "startFlowScaffold", { enumerable: true, get: function () { return startFlow_1.startFlowScaffold; } });
 var runFlow_1 = require("./steps/runFlow");
@@ -21,6 +21,11 @@ var runPropose_1 = require("./steps/runPropose");
 Object.defineProperty(exports, "runPropose", { enumerable: true, get: function () { return runPropose_1.runPropose; } });
 var runDeliver_1 = require("./steps/runDeliver");
 Object.defineProperty(exports, "runDeliver", { enumerable: true, get: function () { return runDeliver_1.runDeliver; } });
+var runSyncSourcePrd_1 = require("./steps/runSyncSourcePrd");
+Object.defineProperty(exports, "runSyncSourcePrd", { enumerable: true, get: function () { return runSyncSourcePrd_1.runSyncSourcePrd; } });
+var syncSourcePrd_1 = require("./core/syncSourcePrd");
+Object.defineProperty(exports, "syncSourcePrdFromDocs", { enumerable: true, get: function () { return syncSourcePrd_1.syncSourcePrdFromDocs; } });
+Object.defineProperty(exports, "tryAutoSyncSourcePrd", { enumerable: true, get: function () { return syncSourcePrd_1.tryAutoSyncSourcePrd; } });
 var resolveRun_1 = require("./steps/resolveRun");
 Object.defineProperty(exports, "resolveRunDir", { enumerable: true, get: function () { return resolveRun_1.resolveRunDir; } });
 Object.defineProperty(exports, "loadRunSession", { enumerable: true, get: function () { return resolveRun_1.loadRunSession; } });

package/dist/steps/runGate.js

@@ -7,11 +7,14 @@ exports.runGate = runGate;
 exports.printGateResult = printGateResult;
 const path_1 = __importDefault(require("path"));
 const prdArtifacts_1 = require("../core/prdArtifacts");
+const syncSourcePrd_1 = require("../core/syncSourcePrd");
 const prdCoverage_1 = require("../core/prdCoverage");
 const gitDiffGuard_1 = require("../core/gitDiffGuard");
 const acMatrix_1 = require("../core/acMatrix");
 const projectRoots_1 = require("../core/projectRoots");
 const openspecGate_1 = require("../core/openspecGate");
+const demoImplementationCoverage_1 = require("../core/demoImplementationCoverage");
+const techDocQuality_1 = require("../core/techDocQuality");
 const resolveRun_1 = require("./resolveRun");
 const fs_1 = require("../core/fs");
 function fail(checks, expect, runId) {
@@ -73,7 +76,7 @@ async function resolveImplRoots(projectRoot) {
  * 脚本门禁：失败时 process.exitCode=1，成功 exit 0。
  */
 async function runGate(options) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e, _f, _g;
     const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
     const checks = [];
     if (!loaded || !loaded.resolved) {
@@ -85,7 +88,27 @@ async function runGate(options) {
     const runId = resolved.runId;
     const implRoots = await resolveImplRoots(options.projectRoot);
     if (options.expect === "prd-fetched") {
-        const prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+        let prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+        if (!prd.ok) {
+            const product = (_b = (_a = session === null || session === void 0 ? void 0 : session.product) !== null && _a !== void 0 ? _a : runId.split("-")[1]) !== null && _b !== void 0 ? _b : "ADI";
+            const version = (_d = (_c = session === null || session === void 0 ? void 0 : session.version) !== null && _c !== void 0 ? _c : runId.split("-").slice(2).join("-")) !== null && _d !== void 0 ? _d : "";
+            const sync = await (0, syncSourcePrd_1.tryAutoSyncSourcePrd)({
+                projectRoot: options.projectRoot,
+                outputRoot,
+                product,
+                version,
+            });
+            if (sync.attempted) {
+                checks.push({
+                    name: "source-prd-sync",
+                    ok: sync.ok,
+                    detail: sync.detail,
+                });
+            }
+            if (sync.ok) {
+                prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+            }
+        }
         checks.push({ name: "prd-fetched", ...prd });
         return pass(checks, options.expect, runId);
     }
@@ -105,6 +128,14 @@ async function runGate(options) {
         checks.push({ name: "questions-closed", ...closed });
         const docs = await (0, prdArtifacts_1.areAnalysisDocsReady)(outputRoot);
         checks.push({ name: "analysis-docs", ...docs });
+        const techRaw = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, "04-技术文档草稿.md"));
+        if (process.env.OPSX_SKIP_TECH_DOC_QUALITY !== "1") {
+            const techStruct = (0, techDocQuality_1.checkTechDocStructure)(techRaw !== null && techRaw !== void 0 ? techRaw : "");
+            checks.push({ name: "tech-doc-structure", ok: techStruct.ok, detail: techStruct.detail });
+        }
+        else {
+            checks.push({ name: "tech-doc-structure", ok: true, detail: "OPSX_SKIP_TECH_DOC_QUALITY=1 已跳过" });
+        }
         const acDefined = await (0, prdArtifacts_1.isAcceptanceChecklistDefined)(outputRoot);
         checks.push({ name: "acceptance-checklist-defined", ...acDefined });
         if (session && session.docModeOnly === false) {
@@ -173,6 +204,11 @@ async function runGate(options) {
                 detail: `openspec/changes/${changeName} 不存在，无法校验 AC 映射`,
             });
         }
+        const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+        const demoArtifactChecks = await (0, demoImplementationCoverage_1.checkDemoReferenceArtifacts)(pkgRoot, changeName);
+        for (const c of demoArtifactChecks) {
+            checks.push({ name: c.name, ok: c.ok, detail: c.detail });
+        }
         return pass(checks, options.expect, runId);
     }
     if (options.expect === "ac-signed") {
@@ -183,7 +219,10 @@ async function runGate(options) {
     if (options.expect === "prd-coverage") {
         const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
         const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
-        const coverage = await (0, prdCoverage_1.checkPrdCoverage)(outputRoot, pkgRoot);
+        const changeName = await readActiveChange(options.projectRoot, session, options.change);
+        const coverage = await (0, prdCoverage_1.checkPrdCoverage)(outputRoot, pkgRoot, {
+            changeName: changeName !== null && changeName !== void 0 ? changeName : undefined,
+        });
         for (const c of coverage.checks) {
             checks.push({ name: c.name, ok: c.ok, detail: c.detail });
         }
@@ -211,6 +250,11 @@ async function runGate(options) {
                 found = true;
                 const st = (0, openspecGate_1.checkOpenspecApplyReady)(root, changeName);
                 checks.push({ name: "openspec-apply-ready", ok: st.applyReady, detail: st.detail });
+                const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+                const demoArtifactChecks = await (0, demoImplementationCoverage_1.checkDemoReferenceArtifacts)(pkgRoot, changeName);
+                for (const c of demoArtifactChecks) {
+                    checks.push({ name: c.name, ok: c.ok, detail: c.detail });
+                }
                 break;
             }
         }
@@ -330,8 +374,8 @@ async function runGate(options) {
                     name: "validate-report",
                     ok,
                     detail: ok
-                        ? `验收通过 (pipeline=${(_a = j.pipelineShortExitCode) !== null && _a !== void 0 ? _a : "?"}, e2e=${(_b = j.e2eExitCode) !== null && _b !== void 0 ? _b : "?"})`
-                        : `验收结果: ${(_c = j.verdict) !== null && _c !== void 0 ? _c : "unknown"}`,
+                        ? `验收通过 (pipeline=${(_e = j.pipelineShortExitCode) !== null && _e !== void 0 ? _e : "?"}, e2e=${(_f = j.e2eExitCode) !== null && _f !== void 0 ? _f : "?"})`
+                        : `验收结果: ${(_g = j.verdict) !== null && _g !== void 0 ? _g : "unknown"}`,
                 });
             }
             catch {

package/dist/steps/runSyncSourcePrd.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSyncSourcePrd = runSyncSourcePrd;
+const syncSourcePrd_1 = require("../core/syncSourcePrd");
+const resolveRun_1 = require("./resolveRun");
+/**
+ * CLI：将 docs 版本目录 PRD 同步到 openspec run 的 source/。
+ */
+async function runSyncSourcePrd(options) {
+    var _a, _b, _c, _d;
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved)) {
+        return { ok: false, detail: "未找到 openspec/PRD/<runId> 目录", runId: null };
+    }
+    const { resolved, session } = loaded;
+    const parts = resolved.runId.split("-");
+    const product = (_b = (_a = session === null || session === void 0 ? void 0 : session.product) !== null && _a !== void 0 ? _a : parts[1]) !== null && _b !== void 0 ? _b : "ADI";
+    const version = (_d = (_c = session === null || session === void 0 ? void 0 : session.version) !== null && _c !== void 0 ? _c : parts.slice(2).join("-")) !== null && _d !== void 0 ? _d : "";
+    if (options.dryRun) {
+        return {
+            ok: true,
+            detail: `dry-run: 将把 docs 版本 PRD 同步到 ${resolved.outputRoot}/source/`,
+            runId: resolved.runId,
+        };
+    }
+    const result = await (0, syncSourcePrd_1.syncSourcePrdFromDocs)({
+        projectRoot: options.projectRoot,
+        outputRoot: resolved.outputRoot,
+        product,
+        version,
+    });
+    return {
+        ok: result.ok,
+        detail: result.detail,
+        runId: resolved.runId,
+        imageCount: result.imageCount,
+    };
+}

package/dist/steps/runValidate.js

@@ -114,7 +114,9 @@ async function runValidate(options) {
     if (remediateLoop.escalated) {
         needUserConfirmFromRemediate = true;
     }
-    let prdCoverage = await (0, prdCoverage_1.checkPrdCoverage)(loaded.resolved.outputRoot, pkgRoot);
+    let prdCoverage = await (0, prdCoverage_1.checkPrdCoverage)(loaded.resolved.outputRoot, pkgRoot, {
+        changeName: options.change,
+    });
     if (!prdCoverage.ok) {
         const failed = prdCoverage.checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail}`);
         const payload = {
@@ -210,7 +212,7 @@ async function runValidate(options) {
     }
     return {
         ok: true,
-        detail: "验收通过（prd-coverage + lint+type+unit + 强制 e2e），可进入交付",
+        detail: "验收通过（prd-coverage 含 E2E 深度与 API 契约 + lint+type+unit + 强制 e2e），可进入交付",
         needUserConfirm: false,
     };
 }