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

package/dist/test/generalization.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { compareObservableRuns, summarizeGeneralizationRun, } from '../src/index.js';
+/**
+ * 泛化评估测试。
+ *
+ * 验证 summarizeGeneralizationRun 把单次 run 汇总为可对比指标，
+ * compareObservableRuns 计算两个系统的场景差异/coverage delta/物料解析分歧。
+ */
+describe('generalization evaluation', () => {
+    it('summarizes a single run into comparable metrics', () => {
+        const metricsA = summarizeGeneralizationRun({
+            moduleId: 'zwplace',
+            resolvedInputs: {
+                moduleId: { status: 'resolved', value: 'zwplace', evidence: '' },
+                docsDir: { status: 'resolved', path: '/a/docs', evidence: '' },
+                webappDir: { status: 'resolved', path: '/a/webapp', evidence: '' },
+                javaActionsDir: { status: 'resolved', path: '/a/java', evidence: '' },
+                hintsPath: { status: 'resolved', path: '/a/hints.json', evidence: '' },
+                menu: { status: 'resolved', value: 'm', evidence: '' },
+            },
+            scenario: {
+                moduleId: 'zwplace',
+                candidates: [
+                    { scenario: 'crud.single-page', confidence: 'high', evidenceRefs: [], matchedSkeletonCapabilities: [], unresolved: [] },
+                    { scenario: 'crud.nested', confidence: 'medium', evidenceRefs: [], matchedSkeletonCapabilities: [], unresolved: [] },
+                ],
+                gate: { status: 'confirmed', confirmedBy: 'human', reason: 'ok' },
+                reasoningSummary: { conclusion: '', evidenceChain: [], alternatives: [], confidence: 'high', risks: [], needsHumanReview: false },
+            },
+            coverageDiff: {
+                moduleId: 'zwplace',
+                skeletonCoverageId: 'crud-plus-export/v1',
+                baseline: { plannedWorkflows: ['w1'], candidateWorkflows: ['w2'], unresolvedWorkflows: [] },
+                covered: [{ actionId: 'a', label: 'l', pageId: 'p', status: 'covered', reason: '' }],
+                partiallyCovered: [],
+                gapCandidates: [],
+                unresolved: [],
+                nestedCrudCandidates: [{ pageId: 'p', evidence: [], supportedActions: [], unresolvedReason: 'r' }],
+                comparison: { both: [], onlyBaseline: [], onlyGeneralized: [] },
+                reasoningSummary: { conclusion: '', evidenceChain: [], alternatives: [], confidence: 'medium', risks: [], needsHumanReview: true },
+            },
+        });
+        expect(metricsA).toMatchObject({
+            moduleId: 'zwplace',
+            scenarios: ['crud.single-page', 'crud.nested'],
+            coverage: { covered: 1, gapCandidate: 0, nestedCrud: 1 },
+            baselineWorkflowCount: 2,
+            materialResolution: { docsDir: 'resolved', webappDir: 'resolved', javaActionsDir: 'resolved', hintsPath: 'resolved' },
+        });
+    });
+    it('compares two systems by observability metrics', () => {
+        const metricsA = {
+            moduleId: 'zwplace',
+            materialResolution: { docsDir: 'resolved', webappDir: 'resolved', javaActionsDir: 'resolved', hintsPath: 'resolved' },
+            scenarios: ['crud.single-page', 'crud.nested'],
+            coverage: { covered: 1, gapCandidate: 0, nestedCrud: 1 },
+            baselineWorkflowCount: 2,
+        };
+        const metricsB = {
+            moduleId: 'other',
+            materialResolution: { docsDir: 'missing', webappDir: 'resolved', javaActionsDir: 'resolved', hintsPath: 'missing' },
+            scenarios: ['crud.single-page', 'export'],
+            coverage: { covered: 3, gapCandidate: 2, nestedCrud: 0 },
+            baselineWorkflowCount: 5,
+        };
+        const cmp = compareObservableRuns(metricsA, metricsB);
+        expect(cmp.scenariosOnlyInA).toEqual(['crud.nested']);
+        expect(cmp.scenariosOnlyInB).toEqual(['export']);
+        expect(cmp.coverageDelta).toEqual({ covered: -2, gapCandidate: -2, nestedCrud: 1 });
+        expect(cmp.materialResolutionDivergence).toContain('docsDir');
+        expect(cmp.materialResolutionDivergence).toContain('hintsPath');
+    });
+});

package/dist/test/material-inventory.test.d.ts

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

package/dist/test/material-inventory.test.d.ts.map

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

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

@@ -0,0 +1,141 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { extractCodeListSummary, resolveMaterialInventory, } from '../src/index.js';
+describe('material inventory resolver', () => {
+    it('maps code_list material refs to contract generation inputs', () => {
+        const root = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-material-'));
+        const codeListPath = path.join(root, '_docs', 'code_list.md');
+        const specPath = path.join(root, '_docs', '003-场所窗口信息管理-20260518', 'spec.yaml');
+        const htmlPath = path.join(root, 'src/main/webapp/perpage/zwplace/gxhzwplacelist.html');
+        const javaPath = path.join(root, 'src/main/java/com/epoint/zwplace/action/GxhZwPlaceListAction.java');
+        const hintsPath = path.join(root, '_docs', 'zwplace.module-hints.json');
+        mkdirSync(path.dirname(specPath), { recursive: true });
+        mkdirSync(path.dirname(htmlPath), { recursive: true });
+        mkdirSync(path.dirname(javaPath), { recursive: true });
+        writeFileSync(specPath, 'module:\n  id: zwplace\n');
+        writeFileSync(htmlPath, '<html></html>');
+        writeFileSync(javaPath, 'class GxhZwPlaceListAction {}');
+        writeFileSync(hintsPath, '{}');
+        writeFileSync(codeListPath, [
+            '# 场所窗口信息管理代码清单',
+            'menu: 场所窗口信息管理>场所窗口信息列表',
+            '`_docs/003-场所窗口信息管理-20260518/spec.yaml`',
+            '`src/main/webapp/perpage/zwplace/gxhzwplacelist.html`',
+            '`src/main/java/com/epoint/zwplace/action/GxhZwPlaceListAction.java`',
+            '`_docs/zwplace.module-hints.json`',
+        ].join('\n'), 'utf8');
+        const codeList = extractCodeListSummary(codeListPath);
+        const result = resolveMaterialInventory({
+            codeListPath,
+            codeList,
+            debugOverrides: {},
+            stageContext: {
+                projectName: 'glue-project',
+                projectDir: root,
+                mode: 'glue',
+                envPath: '.env',
+                envFilePath: path.join(root, '.env'),
+                knowledgeRoot: root,
+                codeListPaths: [codeListPath],
+                stageContextPath: path.join(root, 'stage-context.md'),
+            },
+        });
+        expect(result.resolvedInputs).toMatchObject({
+            moduleId: { status: 'resolved', value: 'zwplace' },
+            docsDir: { status: 'resolved', path: path.dirname(specPath) },
+            webappDir: { status: 'resolved', path: path.dirname(htmlPath) },
+            javaActionsDir: { status: 'resolved', path: path.dirname(javaPath) },
+            hintsPath: { status: 'resolved', path: hintsPath },
+            menu: { status: 'resolved', value: '场所窗口信息管理>场所窗口信息列表' },
+        });
+        expect(result.gate.status).toBe('confirmed');
+    });
+    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');
+        writeFileSync(codeListPath, '# 空代码清单\n');
+        const result = resolveMaterialInventory({
+            codeListPath,
+            codeList: extractCodeListSummary(codeListPath),
+            debugOverrides: {},
+        });
+        expect(result.gate).toMatchObject({
+            status: 'needs_review',
+        });
+        expect(result.resolvedInputs.webappDir.status).toBe('missing');
+        expect(result.resolvedInputs.javaActionsDir.status).toBe('missing');
+    });
+    it('supports a writable external code_list that already contains write-back fields', () => {
+        const root = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-material-writeback-'));
+        const knowledgeRoot = path.join(root, 'knowledge-project', 'zwplace');
+        const writableDir = path.join(root, 'agent-input');
+        const docsPath = path.join(writableDir, 'zwplace-observable-docs', 'zwplace.context.md');
+        const hintsPath = path.join(writableDir, 'zwplace.module-hints.json');
+        const htmlPath = path.join(knowledgeRoot, 'src', 'main', 'webapp', 'perpage', 'zwplace', 'gxhzwplacelist.html');
+        const javaPath = path.join(knowledgeRoot, 'src', 'main', 'java', 'com', 'epoint', 'zwplace', 'action', 'GxhZwPlaceListAction.java');
+        const codeListPath = path.join(writableDir, 'zwplace.observable.code_list.md');
+        mkdirSync(path.dirname(docsPath), { recursive: true });
+        mkdirSync(path.dirname(htmlPath), { recursive: true });
+        mkdirSync(path.dirname(javaPath), { recursive: true });
+        writeFileSync(docsPath, '# zwplace context\n');
+        writeFileSync(hintsPath, '{}');
+        writeFileSync(htmlPath, '<html></html>');
+        writeFileSync(javaPath, 'class GxhZwPlaceListAction {}');
+        writeFileSync(codeListPath, [
+            '# 场所窗口信息管理代码清单',
+            `knowledgeRoot: ${knowledgeRoot}`,
+            'menu: 场所窗口信息管理>场所窗口信息列表',
+            '`./zwplace-observable-docs/zwplace.context.md`',
+            '`src/main/webapp/perpage/zwplace/gxhzwplacelist.html`',
+            '`src/main/java/com/epoint/zwplace/action/GxhZwPlaceListAction.java`',
+            '`./zwplace.module-hints.json`',
+        ].join('\n'), 'utf8');
+        const codeList = extractCodeListSummary(codeListPath);
+        const result = resolveMaterialInventory({
+            codeListPath,
+            codeList,
+            debugOverrides: {},
+        });
+        expect(codeList.knowledgeRoot).toBe(knowledgeRoot);
+        expect(codeList.knowledgeRootSource).toBe('code_list');
+        expect(codeList.menu).toBe('场所窗口信息管理>场所窗口信息列表');
+        expect(result.resolvedInputs).toMatchObject({
+            docsDir: { status: 'resolved', path: path.dirname(docsPath) },
+            webappDir: { status: 'resolved', path: path.dirname(htmlPath) },
+            javaActionsDir: { status: 'resolved', path: path.dirname(javaPath) },
+            hintsPath: { status: 'resolved', path: hintsPath },
+            menu: { status: 'resolved', value: '场所窗口信息管理>场所窗口信息列表' },
+        });
+    });
+    it('resolves the checked-in writable schemeresource code_list example', () => {
+        const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+        const examplesDir = path.join(packageRoot, 'examples');
+        const codeListPath = path.join(examplesDir, 'schemeresource.observable.code_list.md');
+        const knowledgeRoot = path.resolve(examplesDir, '../../../knowledge-project/epoint-web-v9.5.2');
+        const docsDir = path.join(examplesDir, 'schemeresource-observable-docs');
+        const webappDir = path.join(knowledgeRoot, 'src', 'main', 'webapp', 'perpage', 'schemeresource');
+        const javaActionsDir = path.join(knowledgeRoot, 'src', 'main', 'java', 'com', 'epoint', 'schemeresource', 'action');
+        const hintsPath = path.join(examplesDir, 'schemeresource.module-hints.json');
+        const codeList = extractCodeListSummary(codeListPath);
+        const result = resolveMaterialInventory({
+            codeListPath,
+            codeList,
+            debugOverrides: {},
+        });
+        expect(codeList.knowledgeRoot).toBe(knowledgeRoot);
+        expect(codeList.knowledgeRootSource).toBe('code_list');
+        expect(codeList.menu).toBe('方案资源文档>方案资源文档列表');
+        expect(result.resolvedInputs).toMatchObject({
+            moduleId: { status: 'resolved', value: 'schemeresource' },
+            docsDir: { status: 'resolved', path: docsDir },
+            webappDir: { status: 'resolved', path: webappDir },
+            javaActionsDir: { status: 'resolved', path: javaActionsDir },
+            hintsPath: { status: 'resolved', path: hintsPath },
+            menu: { status: 'resolved', value: '方案资源文档>方案资源文档列表' },
+        });
+        expect(result.gate.status).toBe('confirmed');
+    });
+});

package/dist/test/observable-chain.test.d.ts

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

package/dist/test/observable-chain.test.d.ts.map

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

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

@@ -0,0 +1,123 @@
+import { mkdtempSync, readFileSync, existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createTraceWriter, renderReviewSummary, } from '../src/index.js';
+describe('observable glue chain trace writer', () => {
+    function createScenarioPayload() {
+        return {
+            stage: 'scenario-inference',
+            stageLabel: '场景推理追踪',
+            inputs: [{ kind: 'code_list', path: '/repo/knowledge/_docs/code_list.md' }],
+            outputs: [{ kind: 'scenario', path: 'scenario-inference.json' }],
+            reasoningSummary: {
+                conclusion: '当前页面是嵌套 CRUD 候选。',
+                evidenceChain: [
+                    {
+                        source: 'html',
+                        path: '/repo/webapp/gxhzwplaceadd.html',
+                        text: '弹窗页面中存在 mini-datagrid 与 添加窗口 按钮',
+                    },
+                ],
+                alternatives: ['crud.single-page', 'crud.nested'],
+                confidence: 'medium',
+                risks: ['子表保存后断言未确认'],
+                needsHumanReview: true,
+            },
+            candidateCount: 1,
+            unresolvedCount: 1,
+            gate: {
+                status: 'needs_review',
+                reason: '需要人工确认嵌套 CRUD 是否进入 testcase。',
+            },
+        };
+    }
+    it('writes stage json and summary markdown with reviewable reasoning', () => {
+        const projectDir = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-trace-'));
+        const writer = createTraceWriter({
+            projectDir,
+            runId: '20260616T120000Z-demo',
+            codeListPath: '/repo/knowledge/_docs/code_list.md',
+        });
+        const payload = createScenarioPayload();
+        const stagePath = writer.writeStage('scenario-inference', payload);
+        const summaryPath = writer.writeSummary([
+            {
+                stage: 'scenario-inference',
+                stageLabel: '场景推理追踪',
+                status: 'needs_review',
+                conclusion: payload.reasoningSummary?.conclusion ?? '',
+                needsHumanReview: true,
+            },
+        ]);
+        const traceDir = path.join(projectDir, '.stage', 'trace', '20260616T120000Z-demo');
+        expect(writer.runId).toBe('20260616T120000Z-demo');
+        expect(stagePath).toBe(path.join(traceDir, 'scenario-inference.json'));
+        expect(summaryPath).toBe(path.join(traceDir, 'summary.md'));
+        expect(existsSync(path.join(traceDir, 'scenario-inference.json'))).toBe(true);
+        expect(JSON.parse(readFileSync(path.join(traceDir, 'scenario-inference.json'), 'utf8'))).toMatchObject({
+            stage: 'scenario-inference',
+            reasoningSummary: {
+                confidence: 'medium',
+                needsHumanReview: true,
+            },
+        });
+        expect(readFileSync(path.join(traceDir, 'summary.md'), 'utf8')).toContain('场景推理追踪');
+        expect(readFileSync(path.join(traceDir, 'summary.md'), 'utf8')).toContain('需要人工确认');
+    });
+    it('rejects stage write when file stage does not match payload stage', () => {
+        const projectDir = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-trace-'));
+        const writer = createTraceWriter({
+            projectDir,
+            runId: '20260616T120000Z-demo',
+            codeListPath: '/repo/knowledge/_docs/code_list.md',
+        });
+        expect(() => writer.writeStage('coverage-diff', createScenarioPayload())).toThrow('trace stage mismatch');
+    });
+    it('rejects unsafe run id path segments', () => {
+        const projectDir = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-trace-'));
+        const unsafeRunIds = ['../escape', 'nested/run', '/tmp/escape', 'trace..escape', '.', ''];
+        for (const runId of unsafeRunIds) {
+            expect(() => createTraceWriter({
+                projectDir,
+                runId,
+                codeListPath: '/repo/knowledge/_docs/code_list.md',
+            })).toThrow('invalid trace runId');
+        }
+    });
+    it('renders human-readable review summary for conversation output', () => {
+        const text = renderReviewSummary({
+            title: '场景推理需要确认',
+            reasoningSummary: {
+                conclusion: '当前页面是嵌套 CRUD 候选。',
+                evidenceChain: [
+                    { source: 'html', path: 'gxhzwplaceadd.html', text: 'mini-datagrid + 添加窗口' },
+                ],
+                alternatives: ['crud.single-page', 'crud.nested'],
+                confidence: 'medium',
+                risks: ['子表保存后断言未确认'],
+                needsHumanReview: true,
+            },
+            nextAction: 'confirm / correct / add-evidence / skip',
+        });
+        expect(text).toContain('结论：当前页面是嵌套 CRUD 候选。');
+        expect(text).toContain('证据链：');
+        expect(text).toContain('待确认项：子表保存后断言未确认');
+        expect(text).toContain('下一步：confirm / correct / add-evidence / skip');
+    });
+    it('renders empty evidence chain explicitly for review summary', () => {
+        const text = renderReviewSummary({
+            title: '场景推理需要确认',
+            reasoningSummary: {
+                conclusion: '当前证据不足。',
+                evidenceChain: [],
+                alternatives: [],
+                confidence: 'low',
+                risks: [],
+                needsHumanReview: true,
+            },
+            nextAction: 'add-evidence',
+        });
+        expect(text).toContain('证据链：\n- 无');
+    });
+});

package/dist/test/observable-pipeline.test.d.ts

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

package/dist/test/observable-pipeline.test.d.ts.map

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