sdd-flow-kit 1.3.18 → 1.3.21

package/dist/core/acAssertionBinding.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCriterionLiterals = extractCriterionLiterals;
+exports.testBlockBindsCriterionLiterals = testBlockBindsCriterionLiterals;
+exports.testBlockIsFuzzyOnly = testBlockIsFuzzyOnly;
+exports.checkAcAssertionBinding = checkAcAssertionBinding;
+/**
+ * AC 断言绑定门禁：P0 AC 的验收标准字面量须出现在对应 test/it 块的 expect 中。
+ */
+const path_1 = __importDefault(require("path"));
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
+const MIN_LITERAL_LEN = 4;
+/** 模糊断言：仅匹配过短的成功/失败类文案 */
+const FUZZY_ONLY_ASSERT_RE = /expect\s*\([^)]*\)\s*\.toContain(?:Text)?\s*\(\s*['"](?:成功|失败|错误|保存|完成)['"]\s*\)/;
+/**
+ * 从 05「验收标准」列提取可机械比对的字面量（引号、placeholder、toast 等）。
+ */
+function extractCriterionLiterals(criterion) {
+    var _a;
+    const out = new Set();
+    const text = criterion !== null && criterion !== void 0 ? criterion : "";
+    const quotedPatterns = [
+        /「([^」]{3,})」/g,
+        /"([^"]{3,})"/g,
+        /'([^']{3,})'/g,
+        /`([^`]{3,})`/g,
+    ];
+    for (const re of quotedPatterns) {
+        let m;
+        const r = new RegExp(re.source, re.flags);
+        while ((m = r.exec(text)) !== null) {
+            const v = (_a = m[1]) === null || _a === void 0 ? void 0 : _a.trim();
+            if (v && v.length >= MIN_LITERAL_LEN)
+                out.add(v);
+        }
+    }
+    const placeholder = text.match(/请输入[^\s，,。；;]+/);
+    if ((placeholder === null || placeholder === void 0 ? void 0 : placeholder[0]) && placeholder[0].length >= MIN_LITERAL_LEN) {
+        out.add(placeholder[0]);
+    }
+    const tooltip = text.match(/tooltip[^，,。]*[「"]([^」"]{3,})[」"]/i);
+    if (tooltip === null || tooltip === void 0 ? void 0 : tooltip[1])
+        out.add(tooltip[1].trim());
+    return [...out];
+}
+/**
+ * test 块内 expect 是否包含验收标准中的至少一条字面量。
+ */
+function testBlockBindsCriterionLiterals(blockBody, literals) {
+    if (literals.length === 0)
+        return true;
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    if (!/\bexpect\s*\(/.test(body))
+        return false;
+    const hasLiteral = literals.some((lit) => body.includes(lit));
+    if (hasLiteral)
+        return true;
+    // 允许较长文案的部分匹配（≥8 字取前 8 字）
+    return literals.some((lit) => lit.length >= 8 && body.includes(lit.slice(0, 8)));
+}
+/**
+ * 是否为仅模糊断言、未绑定 PRD 原文的 test 块。
+ */
+function testBlockIsFuzzyOnly(blockBody, literals) {
+    if (literals.length === 0)
+        return false;
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    if (!FUZZY_ONLY_ASSERT_RE.test(body))
+        return false;
+    return !testBlockBindsCriterionLiterals(blockBody, literals);
+}
+/**
+ * P0 / e2e 类 AC 须在有效 test 块内绑定验收标准字面量；P0 禁止纯 manual。
+ */
+function checkAcAssertionBinding(items, testFiles) {
+    var _a, _b;
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_AC_ASSERTION_BINDING === "1" ||
+        process.env.OPSX_SKIP_AC_ASSERTION_BINDING === "1";
+    if (skip) {
+        checks.push({
+            name: "ac-assertion-binding",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_AC_ASSERTION_BINDING=1",
+        });
+        return checks;
+    }
+    const mustCover = items.filter((i) => { var _a; return /^P0$/i.test(i.priority.trim()) || /e2e/i.test((_a = i.testType) !== null && _a !== void 0 ? _a : ""); });
+    for (const ac of mustCover) {
+        const isP0 = /^P0$/i.test(ac.priority.trim());
+        const testType = ((_a = ac.testType) !== null && _a !== void 0 ? _a : "").trim();
+        const criterion = (_b = ac.criterion) !== null && _b !== void 0 ? _b : "";
+        const literals = extractCriterionLiterals(criterion);
+        if (isP0 && /^manual$/i.test(testType)) {
+            checks.push({
+                name: `ac-assertion-${ac.id}`,
+                ok: false,
+                detail: `${ac.id} 为 P0 但测试类型为纯 manual，须补充 unit/e2e 自动化`,
+            });
+            continue;
+        }
+        const e2eRequired = /e2e/i.test(testType);
+        let bound = false;
+        let fuzzyOnly = false;
+        let e2eBound = false;
+        const hitFiles = [];
+        for (const tf of testFiles) {
+            const blocks = (0, testAssertionAnalysis_1.parseTestBlocks)(tf.content);
+            for (const block of blocks) {
+                if (!(0, testAssertionAnalysis_1.testBlockReferencesAc)(block, ac.id))
+                    continue;
+                if (!(0, testAssertionAnalysis_1.testBlockHasExpect)(block))
+                    continue;
+                const literalOk = testBlockBindsCriterionLiterals(block.body, literals);
+                const fuzzy = testBlockIsFuzzyOnly(block.body, literals);
+                if (literalOk && !fuzzy) {
+                    bound = true;
+                    hitFiles.push(path_1.default.basename(tf.rel));
+                    if (E2E_DIR_RE.test(tf.rel))
+                        e2eBound = true;
+                }
+                else if (fuzzy) {
+                    fuzzyOnly = true;
+                }
+                else if (literals.length === 0) {
+                    bound = true;
+                    hitFiles.push(path_1.default.basename(tf.rel));
+                    if (E2E_DIR_RE.test(tf.rel))
+                        e2eBound = true;
+                }
+            }
+        }
+        if (!bound) {
+            const hint = literals.length > 0
+                ? `须在含 [${ac.id}] 的 test 块 expect 中出现验收标准字面量之一: ${literals.slice(0, 3).join("、")}`
+                : `须在含 [${ac.id}] 的 test 块内有 expect`;
+            checks.push({
+                name: `ac-assertion-${ac.id}`,
+                ok: false,
+                detail: `${ac.id}(${ac.priority}) 未绑定验收断言${fuzzyOnly ? "（仅有模糊 toContain 成功/失败）" : ""}；${hint}`,
+            });
+            continue;
+        }
+        if (e2eRequired && !e2eBound) {
+            checks.push({
+                name: `ac-assertion-${ac.id}`,
+                ok: false,
+                detail: `${ac.id} 测试类型含 e2e，但 e2e/ 下无绑定验收字面量的 test 块`,
+            });
+            continue;
+        }
+        checks.push({
+            name: `ac-assertion-${ac.id}`,
+            ok: true,
+            detail: `${ac.id} 已绑定验收字面量: ${[...new Set(hitFiles)].join(", ")}`,
+        });
+    }
+    if (mustCover.length === 0) {
+        checks.push({
+            name: "ac-assertion-binding",
+            ok: true,
+            detail: "无 P0/e2e AC，跳过断言绑定检查",
+        });
+    }
+    else {
+        const allOk = checks.every((c) => c.ok);
+        checks.unshift({
+            name: "ac-assertion-binding",
+            ok: allOk,
+            detail: allOk
+                ? `P0/e2e AC 断言绑定通过（${mustCover.length} 条）`
+                : `部分 AC 未绑定验收字面量`,
+        });
+    }
+    return checks;
+}

package/dist/core/apiFieldContract.js

@@ -36,7 +36,7 @@ async function checkApiFieldContract(pkgRoot, changeName) {
     const modRe = /config\/api\/modules\/([\w/-]+)/g;
     let m;
     while ((m = modRe.exec(blob)) !== null) {
-        moduleRefs.add(m[1].replace(/\/index$/, ""));
+        moduleRefs.add(m[1].replace(/\/index$/, "").replace(/\/$/, ""));
     }
     if (moduleRefs.size === 0) {
         checks.push({

package/dist/core/apiFieldCoverage.js

@@ -0,0 +1,335 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFieldMappingTable = parseFieldMappingTable;
+exports.checkApiFieldCoverage = checkApiFieldCoverage;
+/**
+ * API 字段级覆盖门禁（v1.3.20）：fixture 样例 + 04 字段映射表 + 源码消费点三角校验。
+ */
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const snakeCamel_1 = require("./snakeCamel");
+const FIELD_TABLE_HEADER_RE = /\|\s*后端字段\s*\|\s*前端字段\s*\|/m;
+const NORMALIZE_TEST_RE = /caseTransform|snakeToCamel|normalize\w*Api/i;
+const FIXTURE_LOAD_RE = /fixtures\/|readFileSync|import\s+\w+\s+from\s+['"].*\.json['"]/;
+/**
+ * 从 04 / design 解析 §4.3 响应字段映射表。
+ */
+function parseFieldMappingTable(content) {
+    var _a, _b, _c, _d;
+    const rows = [];
+    if (!FIELD_TABLE_HEADER_RE.test(content))
+        return rows;
+    const section = (_d = (_b = (_a = content.match(/###\s*4\.3[\s\S]*?(?=###\s*4\.4|##\s*5\.)/m)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : (_c = content.match(/##\s*API\s*字段契约[\s\S]*/im)) === null || _c === void 0 ? void 0 : _c[0]) !== null && _d !== void 0 ? _d : content;
+    const lines = section.split("\n");
+    let inTable = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("|") && FIELD_TABLE_HEADER_RE.test(trimmed)) {
+            inTable = true;
+            continue;
+        }
+        if (!inTable || !trimmed.startsWith("|"))
+            continue;
+        if (/^\|\s*[-:]+/.test(trimmed))
+            continue;
+        const cells = trimmed
+            .split("|")
+            .map((c) => c.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (cells.length < 2)
+            continue;
+        if (/后端字段|backend/i.test(cells[0]))
+            continue;
+        const backendField = cells[0].replace(/`/g, "").trim();
+        const frontendField = cells[1].replace(/`/g, "").trim();
+        if (!backendField || !frontendField)
+            continue;
+        rows.push({
+            backendField,
+            frontendField,
+            displayLocation: cells[2],
+        });
+    }
+    return rows;
+}
+async function collectApiModulesFromChange(pkgRoot, changeName) {
+    const changeDir = path_1.default.join(pkgRoot, "openspec/changes", changeName);
+    const mods = new Set();
+    for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+        const c = await (0, fs_1.readFileIfExists)(path_1.default.join(changeDir, f));
+        if (!c)
+            continue;
+        const re = /config\/api\/modules\/([\w/-]+)/g;
+        let m;
+        while ((m = re.exec(c)) !== null) {
+            mods.add(m[1].replace(/\/index$/, "").replace(/\/$/, ""));
+        }
+    }
+    return mods;
+}
+async function listFixtureFiles(pkgRoot, moduleName) {
+    const dirs = [
+        path_1.default.join(pkgRoot, "tests/fixtures", moduleName),
+        path_1.default.join(pkgRoot, "frontend/tests/fixtures", moduleName),
+        path_1.default.join(pkgRoot, "tests/fixtures"),
+        path_1.default.join(pkgRoot, "frontend/tests/fixtures"),
+    ];
+    const files = [];
+    for (const dir of dirs) {
+        let entries;
+        try {
+            entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            if (ent.isFile() && ent.name.endsWith(".json")) {
+                files.push(path_1.default.join(dir, ent.name));
+            }
+        }
+    }
+    return [...new Set(files)];
+}
+async function collectChangeSourceCorpus(pkgRoot, changeName) {
+    const changeDir = path_1.default.join(pkgRoot, "openspec/changes", changeName);
+    let blob = "";
+    const fileRefs = new Set();
+    for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+        const c = await (0, fs_1.readFileIfExists)(path_1.default.join(changeDir, f));
+        if (c)
+            blob += `${c}\n`;
+    }
+    const patterns = [
+        /(?:src|frontend\/src)\/[\w/.-]+\.(vue|tsx?|ts)/g,
+        /views\/[\w/.-]+\.(vue|tsx?)/g,
+        /config\/api\/modules\/[\w/.-]+/g,
+    ];
+    for (const re of patterns) {
+        let m;
+        const r = new RegExp(re.source, "g");
+        while ((m = r.exec(blob)) !== null) {
+            fileRefs.add(m[0].replace(/^frontend\//, ""));
+        }
+    }
+    for (const ref of fileRefs) {
+        const candidates = [
+            path_1.default.join(pkgRoot, ref),
+            path_1.default.join(pkgRoot, "frontend", ref),
+            path_1.default.join(pkgRoot, "src", ref.replace(/^src\//, "")),
+        ];
+        for (const fp of candidates) {
+            const content = await (0, fs_1.readFileIfExists)(fp);
+            if (content) {
+                blob += `\n${content}`;
+                break;
+            }
+        }
+    }
+    const viewRoots = [
+        path_1.default.join(pkgRoot, "src/views"),
+        path_1.default.join(pkgRoot, "frontend/src/views"),
+    ];
+    // 兜底：合并 views 下源码
+    for (const vr of viewRoots) {
+        blob = await walkSourceDir(vr, blob);
+    }
+    return blob;
+}
+async function walkSourceDir(dir, acc) {
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return acc;
+    }
+    let out = acc;
+    for (const ent of entries) {
+        if (ent.name === "node_modules")
+            continue;
+        const full = path_1.default.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            out = await walkSourceDir(full, out);
+        }
+        else if (/\.(vue|tsx?|ts)$/.test(ent.name)) {
+            const c = await (0, fs_1.readFileIfExists)(full);
+            if (c)
+                out += `\n${c}`;
+        }
+    }
+    return out;
+}
+async function findNormalizeTests(pkgRoot, moduleName) {
+    const roots = [
+        path_1.default.join(pkgRoot, "tests"),
+        path_1.default.join(pkgRoot, "frontend/tests"),
+    ];
+    const hits = [];
+    for (const root of roots) {
+        await walkTests(root, moduleName, hits);
+    }
+    return hits;
+}
+async function walkTests(dir, moduleName, hits) {
+    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 walkTests(full, moduleName, hits);
+        }
+        else if (/\.(spec|test)\.(t|j)sx?$/.test(ent.name)) {
+            const content = await (0, fs_1.readFileIfExists)(full);
+            if (!content)
+                continue;
+            if (!NORMALIZE_TEST_RE.test(content))
+                continue;
+            if (content.includes(moduleName) ||
+                content.includes("caseTransform") ||
+                content.includes("snakeToCamel")) {
+                hits.push(full);
+            }
+        }
+    }
+}
+function corpusContainsField(corpus, field) {
+    if (!field || field.length < 2)
+        return true;
+    const camel = field;
+    const snake = field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+    return (corpus.includes(camel) ||
+        corpus.includes(`'${camel}'`) ||
+        corpus.includes(`"${camel}"`) ||
+        corpus.includes(snake));
+}
+/**
+ * 字段级 API 覆盖：fixture（snake 样例）+ normalize 单测 + 04 映射表字段在源码可找到。
+ */
+async function checkApiFieldCoverage(pkgRoot, changeName, outputRoot) {
+    var _a;
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_API_FIELD_COVERAGE === "1" ||
+        process.env.OPSX_SKIP_API_FIELD_COVERAGE === "1";
+    if (skip) {
+        checks.push({
+            name: "api-field-coverage",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_API_FIELD_COVERAGE=1",
+        });
+        return checks;
+    }
+    const modules = await collectApiModulesFromChange(pkgRoot, changeName);
+    if (modules.size === 0) {
+        checks.push({
+            name: "api-field-coverage",
+            ok: true,
+            detail: "change 未引用 API 模块，跳过字段级覆盖",
+        });
+        return checks;
+    }
+    let fieldDoc = "";
+    if (outputRoot) {
+        const tech04 = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, "04-技术文档草稿.md"));
+        if (tech04)
+            fieldDoc += tech04;
+    }
+    const design = await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, "openspec/changes", changeName, "design.md"));
+    if (design)
+        fieldDoc += `\n${design}`;
+    const mappingRows = parseFieldMappingTable(fieldDoc);
+    const corpus = await collectChangeSourceCorpus(pkgRoot, changeName);
+    const failures = [];
+    const passed = [];
+    for (const mod of modules) {
+        const fixtures = await listFixtureFiles(pkgRoot, mod);
+        const validFixtures = [];
+        for (const fp of fixtures) {
+            const raw = await (0, fs_1.readFileIfExists)(fp);
+            if (!raw)
+                continue;
+            try {
+                const payload = JSON.parse(raw);
+                if ((0, snakeCamel_1.hasSnakeCaseKeys)(payload)) {
+                    validFixtures.push({ path: fp, payload });
+                }
+            }
+            catch {
+                // ignore invalid json
+            }
+        }
+        if (validFixtures.length === 0) {
+            failures.push(`${mod}: 缺少 tests/fixtures/${mod}/*.json 后端样例（须含 snake_case 字段，来自联调抓包）`);
+            continue;
+        }
+        const normalizeTests = await findNormalizeTests(pkgRoot, mod);
+        let strongTest = false;
+        for (const tp of normalizeTests) {
+            const t = (_a = (await (0, fs_1.readFileIfExists)(tp))) !== null && _a !== void 0 ? _a : "";
+            if (/expect\s*\(/.test(t) &&
+                /snakeToCamel|normalize/.test(t) &&
+                (FIXTURE_LOAD_RE.test(t) || /subject_id|_[a-z]/.test(t))) {
+                strongTest = true;
+                break;
+            }
+        }
+        if (!strongTest) {
+            failures.push(`${mod}: 缺少 caseTransform/normalize 单测（须 expect 断言 camelCase 字段，建议加载 fixtures/${mod}/*.json）`);
+        }
+        const fixtureKeys = new Set();
+        for (const f of validFixtures) {
+            const row = (0, snakeCamel_1.extractFirstListRow)(f.payload);
+            const normalized = (0, snakeCamel_1.snakeToCamelDeep)(f.payload);
+            if (row) {
+                for (const k of Object.keys(row))
+                    fixtureKeys.add(k);
+            }
+            for (const k of (0, snakeCamel_1.collectLeafCamelKeys)(normalized))
+                fixtureKeys.add(k);
+        }
+        const keysToCheck = mappingRows.length > 0
+            ? mappingRows.map((r) => r.frontendField)
+            : [...fixtureKeys].filter((k) => k.length >= 3).slice(0, 12);
+        const missingInCorpus = keysToCheck.filter((k) => !corpusContainsField(corpus, k));
+        if (keysToCheck.length > 0 && missingInCorpus.length === keysToCheck.length) {
+            failures.push(`${mod}: normalize 后字段 [${keysToCheck.slice(0, 5).join(", ")}] 在 change 源码中均无消费点`);
+        }
+        else if (missingInCorpus.length > 0 && mappingRows.length > 0) {
+            failures.push(`${mod}: 04 映射表前端字段未在源码出现: ${missingInCorpus.slice(0, 6).join(", ")}`);
+        }
+        else {
+            passed.push(`${mod}(fixtures=${validFixtures.length}, fields=${keysToCheck.length - missingInCorpus.length}/${keysToCheck.length})`);
+        }
+    }
+    if (mappingRows.length === 0 && modules.size > 0) {
+        checks.push({
+            name: "api-field-mapping-doc",
+            ok: false,
+            detail: "04/design 缺少 §4.3 字段映射表（| 后端字段 | 前端字段 |）；请在 04-技术文档草稿.md 补充",
+        });
+    }
+    else {
+        checks.push({
+            name: "api-field-mapping-doc",
+            ok: true,
+            detail: `已登记 ${mappingRows.length} 条字段映射`,
+        });
+    }
+    checks.push({
+        name: "api-field-coverage",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `API 字段级覆盖通过: ${passed.join("; ") || "(无模块)"}`
+            : failures.join(" | "),
+    });
+    return checks;
+}