@epoint-testtech/ep-stage-skill 0.0.3-alpha.2 → 0.0.4-alpha.1

package/dist/test/cli/spec.test.js

@@ -0,0 +1,196 @@
+/**
+ * spec.ts 单元测试（REQ-SPEC-01）。
+ *
+ * 覆盖：
+ * - parseSpecArgs 缺参 / 非法 / -- 分隔符
+ * - runSpec：
+ *   · 缺 contract.json 时报错（引导用户先跑 testcase 子命令）；
+ *   · 正确装配 v1 .spec.ts（含 SKELETON_MARKER_LINE 头部标记 + skeleton 主体）；
+ *   · testcase.json5 不通过 validateTestcase 时抛错（透传 v2 schema 校验）。
+ */
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { parseSpecArgs, runSpec } from '../../src/cli/spec.js';
+let tmpRoot;
+beforeEach(() => {
+    tmpRoot = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-spec-'));
+});
+afterEach(() => {
+    // 留 tmpdir 给宿主清理，避免删 fixture 时误命中其他测试。
+});
+function createContract() {
+    return {
+        contractVersion: 'crud-business-module/v1',
+        module: { id: 'zwplace', label: '场所窗口信息管理' },
+        pages: {
+            list: {
+                role: 'list',
+                pageId: 'gxhzwplacelist',
+                title: '场所窗口信息列表',
+                iframeSrcKeyword: 'gxhzwplacelist',
+                fields: [
+                    { name: 'windowname', label: '窗口名称', controlType: 'minitext', required: false, availability: 'auto_extractable', sources: [] },
+                ],
+                buttons: [],
+                grids: [],
+                dialogs: [],
+                sources: [],
+            },
+            add: {
+                role: 'add',
+                pageId: 'gxhzwplaceadd',
+                title: '新增场所窗口',
+                iframeSrcKeyword: 'gxhzwplaceadd',
+                fields: [
+                    { name: 'windowname', label: '窗口名称', controlType: 'minitext', required: true, availability: 'auto_extractable', sources: [] },
+                ],
+                buttons: [],
+                grids: [],
+                dialogs: [],
+                sources: [],
+            },
+            edit: {
+                role: 'edit',
+                pageId: 'gxhzwplaceedit',
+                title: '修改场所窗口',
+                iframeSrcKeyword: 'gxhzwplaceedit',
+                fields: [
+                    { name: 'windowname', label: '窗口名称', controlType: 'minitext', required: true, availability: 'auto_extractable', sources: [] },
+                ],
+                buttons: [],
+                grids: [],
+                dialogs: [],
+                sources: [],
+            },
+        },
+        dataKey: {
+            field: 'windowname',
+            label: '窗口名称',
+            availability: 'derivable',
+            generationStrategy: 'timestamp_prefix',
+            sources: [],
+        },
+        searchConditions: [
+            {
+                field: 'windowname',
+                label: '窗口名称',
+                component: 'input',
+                seedValue: '自动化测试窗口',
+                generationStrategy: 'timestamp_prefix',
+                sources: [],
+            },
+        ],
+        flows: {
+            create: {
+                entryButton: { pageRole: 'list', label: '新增', sources: [] },
+                targetPageId: 'gxhzwplaceadd',
+                saveButton: { pageRole: 'add', label: '保存并关闭', sources: [] },
+                overrideFields: [],
+            },
+            search: {
+                searchField: { pageRole: 'list', field: 'windowname', label: '窗口名称', sources: [] },
+                submitControl: { pageRole: 'list', label: '查询', sources: [] },
+                resultGrid: 'datagrid',
+            },
+            update: {
+                entryAction: { pageRole: 'list', label: '修改', sources: [] },
+                targetPageId: 'gxhzwplaceedit',
+                updateField: { pageRole: 'edit', field: 'windowname', label: '窗口名称', sources: [] },
+                saveButton: { pageRole: 'edit', label: '保存并关闭', sources: [] },
+            },
+            delete: {
+                entryButton: { pageRole: 'list', label: '删除', sources: [] },
+                expectedOutcome: 'success_delete',
+                confirmControl: { pageRole: 'list', label: '确定', sources: [] },
+            },
+        },
+        assertions: [],
+        businessRules: [],
+        unresolvedSlots: [],
+    };
+}
+function createTestcase() {
+    return {
+        schemaVersion: 'v2',
+        scenario: 'crud.single-page',
+        moduleId: 'zwplace',
+        moduleName: '场所窗口信息管理',
+        menuPath: '业务管理 > 场所窗口',
+        requiredSystems: [{ url: '' }],
+        requiredRoles: [{ role: 'admin' }],
+        coveredActions: [
+            { actionId: 'create', kind: '新增', evidence: ['contract=crud-business-module/v1'] },
+        ],
+        uncoveredCandidates: [],
+        cases: [
+            {
+                caseId: 'zwplace.create',
+                title: '新增',
+                scenario: 'crud.single-page',
+                reviewStatus: 'confirmed',
+                requiredRole: 'admin',
+                evidence: ['contract=crud-business-module/v1'],
+                steps: [],
+                assertions: [],
+                unresolved: [],
+            },
+        ],
+        reasoningSummary: {
+            conclusion: '',
+            evidenceChain: [],
+            alternatives: [],
+            confidence: 'medium',
+            risks: [],
+            needsHumanReview: true,
+        },
+    };
+}
+function writeFixtures() {
+    const testsDir = path.join(tmpRoot, 'requirement-X');
+    mkdirSync(path.join(testsDir, '.ep-stage'), { recursive: true });
+    const testcasePath = path.join(testsDir, 'testcase.json5');
+    const contractPath = path.join(testsDir, '.ep-stage', 'contract.json');
+    writeFileSync(testcasePath, JSON.stringify(createTestcase()), 'utf8');
+    writeFileSync(contractPath, JSON.stringify(createContract()), 'utf8');
+    return { testcasePath, specOut: path.join(testsDir, 'crud.spec.ts') };
+}
+describe('parseSpecArgs', () => {
+    it('缺 --testcase 时抛错', () => {
+        expect(() => parseSpecArgs(['--out', '/x'])).toThrow(/缺少 --testcase/);
+    });
+    it('缺 --out 时抛错', () => {
+        expect(() => parseSpecArgs(['--testcase', '/x'])).toThrow(/缺少 --out/);
+    });
+    it('参数对非法时抛错', () => {
+        expect(() => parseSpecArgs(['--testcase'])).toThrow(/无效参数对/);
+    });
+    it('-- 分隔符被忽略', () => {
+        const args = parseSpecArgs(['--', '--testcase', '/a', '--out', '/b']);
+        expect(args).toEqual({ testcase: '/a', out: '/b' });
+    });
+});
+describe('runSpec', () => {
+    it('正常装配 v1 .spec.ts（含 SKELETON_MARKER_LINE）', () => {
+        const { testcasePath, specOut } = writeFixtures();
+        const result = runSpec({ testcase: testcasePath, out: specOut });
+        expect(result).toEqual({ specPath: specOut, version: 'v1' });
+        const body = readFileSync(specOut, 'utf8');
+        expect(body).toMatch(/^\/\/ === 胶水模式生成（基于 contract \+ coveredActions）===/);
+        // skeleton 主体（来自 generateStageSkeletonCrudSpec）应含 Playwright import 或 test 入口
+        expect(body.length).toBeGreaterThan(100);
+    });
+    it('缺 .ep-stage/contract.json 时抛错引导', () => {
+        const testsDir = path.join(tmpRoot, 'requirement-Y');
+        mkdirSync(testsDir, { recursive: true });
+        const testcasePath = path.join(testsDir, 'testcase.json5');
+        writeFileSync(testcasePath, JSON.stringify(createTestcase()), 'utf8');
+        expect(() => runSpec({ testcase: testcasePath, out: path.join(testsDir, 'out.spec.ts') })).toThrow(/未找到.*contract\.json/);
+    });
+    it('testcase.json5 schemaVersion 不是 v2 时由 validateTestcase 抛错', () => {
+        const { testcasePath, specOut } = writeFixtures();
+        writeFileSync(testcasePath, JSON.stringify({ schemaVersion: 'v1' }), 'utf8');
+        expect(() => runSpec({ testcase: testcasePath, out: specOut })).toThrow(/schemaVersion 不是 v2/);
+    });
+});

package/dist/test/code-list.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=code-list.test.d.ts.map

package/dist/test/code-list.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-list.test.d.ts","sourceRoot":"","sources":["../../test/code-list.test.ts"],"names":[],"mappings":""}

package/dist/test/code-list.test.js

@@ -0,0 +1,39 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { extractCodeListSummary } from '../src/index.js';
+/**
+ * code_list.md 解析器单元测试。
+ *
+ * 重点覆盖菜单字段的人工读写约定：
+ * - 中文键「菜单」为 code_list.md 人工首选（与「整理目录」同风格），支持 blockquote 与裸行；
+ * - 英文键 menu / menuPath 向后兼容（编码内部字段名仍为 menu）。
+ */
+describe('code_list.md 菜单字段解析', () => {
+    /** 在临时目录写一份最小 code_list.md 并返回其解析摘要。 */
+    function summarizeMenu(lines) {
+        const root = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-codelist-'));
+        const codeListPath = path.join(root, 'code_list.md');
+        writeFileSync(codeListPath, lines.join('\n'), 'utf8');
+        return extractCodeListSummary(codeListPath).menu;
+    }
+    it('中文键「菜单」blockquote 形式（无反引号）', () => {
+        expect(summarizeMenu(['# 场所窗口信息管理代码清单', '> 菜单：场所窗口信息管理>场所窗口信息列表'])).toBe('场所窗口信息管理>场所窗口信息列表');
+    });
+    it('中文键「菜单」blockquote 形式（反引号包裹）', () => {
+        expect(summarizeMenu(['# 场所窗口信息管理代码清单', '> 菜单：`场所窗口信息管理>场所窗口信息列表`'])).toBe('场所窗口信息管理>场所窗口信息列表');
+    });
+    it('中文键「菜单」裸行形式', () => {
+        expect(summarizeMenu(['# 场所窗口信息管理代码清单', '菜单: 场所窗口信息管理>场所窗口信息列表'])).toBe('场所窗口信息管理>场所窗口信息列表');
+    });
+    it('英文键 menu 向后兼容', () => {
+        expect(summarizeMenu(['# 场所窗口信息管理代码清单', 'menu: 场所窗口信息管理>场所窗口信息列表'])).toBe('场所窗口信息管理>场所窗口信息列表');
+    });
+    it('英文键 menuPath 向后兼容', () => {
+        expect(summarizeMenu(['# 场所窗口信息管理代码清单', 'menuPath: 场所窗口信息管理>场所窗口信息列表'])).toBe('场所窗口信息管理>场所窗口信息列表');
+    });
+    it('未声明菜单时返回 undefined', () => {
+        expect(summarizeMenu(['# 场所窗口信息管理代码清单'])).toBeUndefined();
+    });
+});

package/dist/test/crud-contract.test.js

@@ -11,7 +11,7 @@ const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 const zwplaceDocs = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/_docs');
 const zwplaceWebapp = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/src/main/webapp/perpage/zwplace');
 const zwplaceActions = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/src/main/java/com/epoint/zwplace/action');
-const codeListPath = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/_docs/code_list.md');
+const codeListPath = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/_docs/014-测试需求10-20260622/code_list.md');
 function readZwplaceSpecFixture() {
     return {
         path: join(zwplaceDocs, 'spec.yaml'),
@@ -743,37 +743,6 @@ describe('stage-skeleton Playwright generator', () => {
         expect(compileResult.status).toBe(0);
         expect(compileResult.stderr).toBe('');
     });
-    it('generates a stage-skeleton spec from CLI', () => {
-        const outDir = mkdtempSync(join(tmpdir(), 'test-glue-playwright-'));
-        const contractFile = join(outDir, 'zwplace.crud.contract.json');
-        const specFile = join(outDir, 'zwplace.spec.ts');
-        try {
-            writeFileSync(contractFile, JSON.stringify(buildZwplaceContractWithHints(), null, 2), 'utf8');
-            execFileSync('pnpm', [
-                'generate:playwright-tests',
-                '--',
-                '--contract',
-                contractFile,
-                '--out',
-                specFile,
-                '--menu',
-                '场所窗口信息管理>场所窗口信息列表'
-            ], { cwd: packageRoot, stdio: 'pipe' });
-            const script = readFileSync(specFile, 'utf8');
-            expect(script).toContain("import { CrudPage, ExportPage, LoginPage, MenuPage, type CrudFlowSlots, type ExportFlowSlots, type CrudWorkflowData } from '../skeletons';");
-            expect(script).toContain("import { GlueWorkflowRecorder, runRecordedWorkflow, type GlueWorkflowRecordInput } from '../report/glue-report';");
-            expect(script).toContain('const crudSlots: CrudFlowSlots =');
-            expect(script).toContain("workflowId: 'zwplace.create'");
-            expect(script).toContain('workflowData = crudPage.prepareWorkflowData();');
-            expect(script).not.toContain('runCrudFlow');
-            const compileResult = compileGlueTemplateSpec(script);
-            expect(compileResult.status).toBe(0);
-            expect(compileResult.stderr).toBe('');
-        }
-        finally {
-            rmSync(outDir, { recursive: true, force: true });
-        }
-    });
     it('prefers contract locators and result grid ids over hard-coded zwplace fallbacks', () => {
         const contract = buildZwplaceContractWithHints();
         contract.flows.create.entryButton.locator = 'css=[data-create]';
@@ -816,4 +785,15 @@ describe('stage-skeleton Playwright generator', () => {
             menuNavigation: '场所窗口信息管理>场所窗口信息列表'
         })).toThrow('当前数据生成策略无法自动映射到 CrudFlowSlots: external_data_pool');
     });
+    it('defaults human_required generation strategy to timestamp_prefix (CRUD 冒烟标配，避免 tester 未喂策略时硬死锁)', () => {
+        const contract = buildZwplaceContractWithHints();
+        contract.dataKey.generationStrategy = 'human_required';
+        contract.searchConditions[0].generationStrategy = 'human_required';
+        const script = generateStageSkeletonCrudSpec({
+            contract,
+            menuNavigation: '场所窗口信息管理>场所窗口信息列表'
+        });
+        expect(script).toContain("strategy: 'timestamp_prefix'");
+        expect(script).not.toContain('human_required');
+    });
 });

package/dist/test/inference/module-hints-inference.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=module-hints-inference.test.d.ts.map

package/dist/test/inference/module-hints-inference.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-hints-inference.test.d.ts","sourceRoot":"","sources":["../../../test/inference/module-hints-inference.test.ts"],"names":[],"mappings":""}

package/dist/test/inference/module-hints-inference.test.js

@@ -0,0 +1,25 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { extractCodeListSummary, extractHtmlPage, extractJavaAction } from '../../src/index.js';
+import { buildSourceAnalysis } from '../../src/inference/source-analysis.js';
+import { inferModuleHintsFromMaterials } from '../../src/inference/module-hints-inference.js';
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const knowledgeRoot = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2');
+const requirementDir = join(knowledgeRoot, '_docs/014-测试需求10-20260622');
+const webappDir = join(knowledgeRoot, 'src/main/webapp/perpage/zwplace');
+const javaActionsDir = join(knowledgeRoot, 'src/main/java/com/epoint/zwplace/action');
+describe('inferModuleHintsFromMaterials', () => {
+    it('不依赖 module-hints 文件也能推理 zwplace 的基础骨架槽位', () => {
+        const codeListPath = join(requirementDir, 'code_list.md');
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = ['gxhzwplacelist.html', 'gxhzwplaceadd.html', 'gxhzwplaceedit.html'].map((file) => extractHtmlPage(join(webappDir, file)));
+        const actions = ['GxhZwPlaceListAction.java', 'GxhZwPlaceAddAction.java', 'GxhZwPlaceEditAction.java'].map((file) => extractJavaAction(join(javaActionsDir, file)));
+        const sourceAnalysis = buildSourceAnalysis({ codeListPath, docsDir: requirementDir, codeList, pages, actions });
+        const result = inferModuleHintsFromMaterials({ sourceAnalysis, pages, actions });
+        expect(result.hints.dataKey?.selectedField).toBe('placename');
+        expect(result.hints.searchConditions?.[0]?.field).toBe('placename');
+        expect(result.inference.mode).toBe('inferred');
+        expect(result.inference.customWorkflows.map((workflow) => workflow.label)).toContain('同步窗口管理系统');
+    });
+});

package/dist/test/inference/source-analysis.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-analysis.test.d.ts.map

package/dist/test/inference/source-analysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-analysis.test.d.ts","sourceRoot":"","sources":["../../../test/inference/source-analysis.test.ts"],"names":[],"mappings":""}

package/dist/test/inference/source-analysis.test.js

@@ -0,0 +1,23 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { extractCodeListSummary, extractHtmlPage, extractJavaAction } from '../../src/index.js';
+import { buildSourceAnalysis } from '../../src/inference/source-analysis.js';
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const knowledgeRoot = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2');
+const requirementDir = join(knowledgeRoot, '_docs/014-测试需求10-20260622');
+const webappDir = join(knowledgeRoot, 'src/main/webapp/perpage/zwplace');
+const javaActionsDir = join(knowledgeRoot, 'src/main/java/com/epoint/zwplace/action');
+describe('buildSourceAnalysis', () => {
+    it('标记 014 真实物料为 prd+html+java 源分析', () => {
+        const codeListPath = join(requirementDir, 'code_list.md');
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = ['gxhzwplacelist.html', 'gxhzwplaceadd.html'].map((file) => extractHtmlPage(join(webappDir, file)));
+        const actions = ['GxhZwPlaceListAction.java', 'GxhZwPlaceAddAction.java'].map((file) => extractJavaAction(join(javaActionsDir, file)));
+        const analysis = buildSourceAnalysis({ codeListPath, docsDir: requirementDir, codeList, pages, actions });
+        expect(analysis.mode).toBe('prd+html+java');
+        expect(analysis.sources.map((source) => source.kind)).toContain('prd_markdown');
+        expect(analysis.uiSignals.length).toBeGreaterThan(0);
+        expect(analysis.backendSignals.length).toBeGreaterThan(0);
+    });
+});

package/dist/test/material-inventory.test.js

@@ -21,6 +21,7 @@ describe('material inventory resolver', () => {
         writeFileSync(hintsPath, '{}');
         writeFileSync(codeListPath, [
             '# 场所窗口信息管理代码清单',
+            `> 整理目录：\`${root}\``,
             'menu: 场所窗口信息管理>场所窗口信息列表',
             '`_docs/003-场所窗口信息管理-20260518/spec.yaml`',
             '`src/main/webapp/perpage/zwplace/gxhzwplacelist.html`',
@@ -53,6 +54,18 @@ describe('material inventory resolver', () => {
         });
         expect(result.gate.status).toBe('confirmed');
     });
+    it('does not infer knowledgeRoot from _docs hierarchy when code_list lacks structured root info', () => {
+        const root = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-material-no-root-'));
+        const codeListPath = path.join(root, '_docs', '014-测试需求10-20260622', 'code_list.md');
+        mkdirSync(path.dirname(codeListPath), { recursive: true });
+        writeFileSync(codeListPath, [
+            '# 场所窗口信息管理代码清单',
+            '`src/main/webapp/perpage/zwplace/gxhzwplacelist.html`',
+        ].join('\n'), 'utf8');
+        const codeList = extractCodeListSummary(codeListPath);
+        expect(codeList.knowledgeRoot).toBeUndefined();
+        expect(codeList.knowledgeRootSource).toBe('none');
+    });
     it('stops at material gate when webapp or java actions cannot be resolved', () => {
         const root = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-material-missing-'));
         const codeListPath = path.join(root, 'code_list.md');

package/dist/test/observable-pipeline.test.js

@@ -75,7 +75,7 @@ describe('observable pipeline material inventory', () => {
             },
         ]);
     });
-    it('resolves paths relative to knowledge root when code_list is under _docs', () => {
+    it('resolves paths relative to the 整理目录 declared inside code_list', () => {
         const root = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-knowledge-root-'));
         const docsDir = path.join(root, '_docs');
         const htmlPath = path.join(root, 'src', 'main', 'webapp', 'perpage', 'zwplace', 'gxhzwplacelist.html');
@@ -83,9 +83,18 @@ describe('observable pipeline material inventory', () => {
         mkdirSync(path.dirname(htmlPath), { recursive: true });
         mkdirSync(docsDir, { recursive: true });
         writeFileSync(htmlPath, '<html></html>');
-        writeFileSync(codeListPath, '| HTML | `src/main/webapp/perpage/zwplace/gxhzwplacelist.html` |', 'utf8');
+        writeFileSync(codeListPath, [
+            `> 整理目录：\`${root}\``,
+            '',
+            '| HTML | `src/main/webapp/perpage/zwplace/gxhzwplacelist.html` |',
+        ].join('\n'), 'utf8');
         const summary = extractCodeListSummary(codeListPath);
-        expect(summary.materialRefs[0]).toMatchObject({
+        expect(summary.knowledgeRoot).toBe(root);
+        expect(summary.knowledgeRootSource).toBe('code_list');
+        // `> 整理目录：` 声明行因含反引号路径会被物料提取器多读出一条 other 引用，
+        // 故用 find 定位 HTML 引用，而非依赖数组首位。
+        const htmlRef = summary.materialRefs.find((ref) => ref.kind === 'html');
+        expect(htmlRef).toMatchObject({
             kind: 'html',
             path: htmlPath,
             exists: true,