diff --git a/src/modeler/candidateExpression.test.ts b/src/modeler/candidateExpression.test.ts index d9f3449..c6fb8c2 100644 --- a/src/modeler/candidateExpression.test.ts +++ b/src/modeler/candidateExpression.test.ts @@ -199,4 +199,107 @@ describe('非法/空输入返回 null 不抛', () => { "${candidateUsersHandler.getCandidateUsers(execution,'【\"foo\":1】')}"; expect(parseCandidateExpression(noItems)).toBeNull(); }); + + // M-2 形状守卫 + it('items 元素非对象(字符串)→ null 不抛', () => { + const bad = + "${candidateUsersHandler.getCandidateUsers(execution,'【\"items\":[\"notanobject\"]】')}"; + expect(() => parseCandidateExpression(bad)).not.toThrow(); + expect(parseCandidateExpression(bad)).toBeNull(); + }); + + it('items 元素 type 非字符串(数字)→ null', () => { + const bad = + "${candidateUsersHandler.getCandidateUsers(execution,'【\"items\":[【\"type\":123,\"content\":\"x\"】]】')}"; + expect(parseCandidateExpression(bad)).toBeNull(); + }); + + it('items 元素为 null → null', () => { + const bad = + "${candidateUsersHandler.getCandidateUsers(execution,'【\"items\":[null]】')}"; + expect(parseCandidateExpression(bad)).toBeNull(); + }); +}); + +describe('I-1 stringToJson 引号映射(T2.4 接用户输入前必须)', () => { + const CAND_PREFIX = "${candidateUsersHandler.getCandidateUsers(execution,'"; + function body(built: string): string { + return built.slice(CAND_PREFIX.length, built.length - "')}".length); + } + + it("content 含 ' 和 \" → build 映射为 ‘/“,值层无裸 '/\"、外层 JUEL 定界符不被截断", () => { + const item: UserPropertyItem = { + type: 'user', + content: `O'Brien "Ann"`, + isCandidate: true, + isSendMail: false, + isSendPhone: false, + isSendMessage: false, + }; + const built = buildCandidateExpression([item], 'candidate'); + // JUEL 单引号字面量安全:整个内容段不得出现裸 ASCII 单引号(否则截断 execution,'...')。 + // 注意 " 是 JSON 结构定界符会合法出现于内容段,故只对 ' 断言整段无裸值。 + expect(body(built)).not.toContain("'"); + // JSON 结构安全:值里的 " 已映射走,build 产物仍是良构表达式,可无损 parse 回来。 + const r = parseCandidateExpression(built); + expect(r).not.toBeNull(); + const c = r!.items[0].content; + expect(c).toContain('‘'); // O‘Brien + expect(c).toContain('“'); // “Ann“(开闭同映射为左引号,与 stringToJson 逐字一致) + expect(c).not.toContain("'"); + expect(c).not.toContain('"'); + expect(built.startsWith(CAND_PREFIX)).toBe(true); + expect(built.endsWith("')}")).toBe(true); + }); + + it('引号映射幂等:build 产物再 parse→build 稳定不变', () => { + const built = buildCandidateExpression( + [{ type: 'user', content: `x'y"z`, isCandidate: true, isSendMail: false, isSendPhone: false }], + 'candidate', + ); + const r = parseCandidateExpression(built)!; + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(built); + }); + + it('meta 字符串叶子(messageTemplate)同样应用引号映射', () => { + const built = buildCandidateExpression( + [{ type: 'user', content: 'u1', isCandidate: true, isSendMail: false, isSendPhone: false }], + 'candidate', + { messageTemplate: `it's` }, + ); + expect(built).toContain('it‘s'); + expect(body(built)).not.toContain("'"); + }); +}); + +describe('I-2 半角 content 变体(scriptUser ${users})——运行期等价', () => { + // 语料实测 20 条:content 用半角 ${users}(非 stringToJson 产物)。parse 保留原值, + // build 把结构性 {} 连同 content 里半角 {} 一并规范化为全角——非字节逐字,但引擎运行期 + // 对整串全局 【→{ 还原后完全等价。 + const HALF = + "${multiInstanceUsersHandler.getUsers(execution,'【\"items\":[【\"type\":\"scriptUser\",\"content\":\"${users}\",\"isCandidate\":true,\"isSendMail\":false,\"isSendPhone\":false】]】')}"; + // 镜像引擎 CandidateUsersHandler:54 的全局字面替换 + const engineRestore = (s: string): string => s.split('【').join('{').split('】').join('}'); + + it('半角 content 可解析,原值保留', () => { + const r = parseCandidateExpression(HALF)!; + expect(r.items[0]).toMatchObject({ type: 'scriptUser', content: '${users}' }); + }); + + it('build 输出恒全角(content 半角{}被规范化),但引擎全局替换后与原文等价', () => { + const r = parseCandidateExpression(HALF)!; + const built = buildCandidateExpression(r.items, r.variant, r.meta); + expect(built).toContain('$【users】'); // 非字节逐字 + expect(engineRestore(built)).toBe(engineRestore(HALF)); // 运行期等价 + }); +}); + +describe('M-1 item 未知键透传(不静默丢未来扩展键,与 meta 全量保留对称)', () => { + it('未知 item 键排在已知键之后,往返逐字不丢', () => { + const WITH_UNKNOWN = + "${candidateUsersHandler.getCandidateUsers(execution,'【\"items\":[【\"type\":\"user\",\"content\":\"u1\",\"isCandidate\":true,\"isSendMail\":false,\"isSendPhone\":false,\"futureFlag\":true】]】')}"; + const r = parseCandidateExpression(WITH_UNKNOWN)!; + expect((r.items[0] as Record).futureFlag).toBe(true); + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(WITH_UNKNOWN); + }); }); diff --git a/src/modeler/candidateExpression.ts b/src/modeler/candidateExpression.ts index fcdc824..f409bfc 100644 --- a/src/modeler/candidateExpression.ts +++ b/src/modeler/candidateExpression.ts @@ -8,12 +8,22 @@ // CandidateUsersHandler:54 以 `.replace("【","{").replace("】","}")`(全局字面替换) // 还原为合法 JSON 再交 Jackson 解析。本编解码器 build 输出恒全角、parse 兼容全角/半角。 // - 外层对象结构:{"items":[{...}],"messageTemplate","taskSuccessService", -// "isSkipInitiator","isNoUserSkip","isSkipBeforeTask"}。引擎运行期候选人解析 -// (convertToUserProperties)只读 items,但 taskSuccessService 等是任务后置服务钩子等 -// 运行期业务字段——侧板只改 items 时必须原样带回(meta),否则重新部署会打掉这些字段。 +// "isSkipInitiator","isNoUserSkip","isSkipBeforeTask"}(语料实测 meta 键集有多种子集)。 +// 引擎运行期候选人解析(convertToUserProperties)只读 items,但 taskSuccessService 等是 +// 任务后置服务钩子等运行期业务字段——侧板只改 items 时必须原样带回(meta),否则重新部署 +// 会打掉这些字段。 +// - 字符串叶子值(content/messageTemplate 等)的转义逐字对齐原版 stringToJson +// (BasePropertiesConverter.java:235-280):`'`→‘(U+2018)、`"`→“(U+201C)、 +// `{`→【、`}`→】,反斜杠与控制字符走标准 JSON 转义。build 对新值应用此契约,防用户输入 +// 含 `'`(截断外层 JUEL 单引号字面量)或 `"`(截断内层 JSON)导致部署后表达式解析即断。 // -// 逐字往返约定:content 不含花括号(与引擎的全局替换同约定),故 JSON.stringify 产出的 -// 结构性 {} 全局换成全角是安全的;content 里的逗号分隔多值与 CHAR 尾部补白空格原样保留。 +// 逐字往返口径(全量 1512 流 4794 条真实表达式实测,见 tools/codec-corpus-sweep.mjs): +// - 4774/4794 build(parse(x))===x 逐字一致;`‘`/`“`/`\/` 在语料 0 命中,故新增引号 +// 转义对存量表达式为 no-op(合法存量叶子值不含裸 ' / ",否则会截断 JUEL/JSON)。 +// - 余 20 条 content 用**半角** `${users}`(scriptUser 会签变体,非 stringToJson 产物): +// parse 保留原值,build 把结构性 {} 连同 content 里的半角 {} 一并规范化为全角【】。此非字节 +// 逐字,但**运行期等价**——引擎 :54 对整串做全局 【→{ 还原,`$【users】` 复原为 `${users}`。 +// - content 里的逗号分隔多值与 CHAR 尾部补白空格原样保留。 const CANDIDATE_PREFIX = "${candidateUsersHandler.getCandidateUsers(execution,'"; const MULTI_PREFIX = "${multiInstanceUsersHandler.getUsers(execution,'"; @@ -38,6 +48,10 @@ export interface ParsedCandidateExpression { meta: Record; } +/** item 的规范键序;未知键在其后按原序透传(与 meta 全量保留对称,不静默丢未来扩展键)。 */ +const KNOWN_ITEM_KEYS = ['type', 'content', 'isCandidate', 'isSendMail', 'isSendPhone', 'isSendMessage']; +const KNOWN_ITEM_KEY_SET = new Set(KNOWN_ITEM_KEYS); + function fullToHalf(s: string): string { return s.split('【').join('{').split('】').join('}'); } @@ -46,21 +60,31 @@ function halfToFull(s: string): string { return s.split('{').join('【').split('}').join('】'); } -/** 按固定规范键序重建 item,只输出存在的键(不凭空增删),保证逐字确定性。 */ -function normalizeItem(it: UserPropertyItem): UserPropertyItem { - const o = {} as UserPropertyItem; - o.type = it.type; - o.content = it.content; - if (it.isCandidate !== undefined) o.isCandidate = it.isCandidate; - if (it.isSendMail !== undefined) o.isSendMail = it.isSendMail; - if (it.isSendPhone !== undefined) o.isSendPhone = it.isSendPhone; - if (it.isSendMessage !== undefined) o.isSendMessage = it.isSendMessage; +/** + * 字符串叶子值转义,逐字对齐原版 stringToJson 里 JSON.stringify **未覆盖**的两处值级映射: + * `'`→‘、`"`→“。(反斜杠/控制字符由 JSON.stringify 覆盖;`{`/`}`→【/】由 halfToFull 覆盖。) + * 对合法存量叶子值(不含裸 ' / ")为 no-op,故不破坏逐字往返;仅对面板新输入生效。 + */ +function escapeLeaf(v: string): string { + return v.split("'").join('‘').split('"').join('“'); +} + +/** 按规范键序重建 item:已知键在前(存在才输出,不凭空增删),未知键按原序透传。 */ +function reorderItem(src: Record): Record { + const o: Record = {}; + for (const k of KNOWN_ITEM_KEYS) { + if (src[k] !== undefined) o[k] = src[k]; + } + for (const k of Object.keys(src)) { + if (!KNOWN_ITEM_KEY_SET.has(k) && src[k] !== undefined) o[k] = src[k]; + } return o; } /** * 解析办理人/会签表达式。识别 candidate / multiInstance 两种前缀,内容段全角【】→{} 后 JSON.parse。 - * 非办理人表达式、缺后缀、坏 JSON、无 items 数组、undefined/空串一律返回 null 不抛。 + * 非办理人表达式、缺后缀、坏 JSON、无 items 数组、items 元素非对象或 type 非字符串、 + * undefined/空串一律返回 null 不抛。 */ export function parseCandidateExpression( expr: string | undefined | null, @@ -91,7 +115,15 @@ export function parseCandidateExpression( const record = obj as Record; if (!Array.isArray(record.items)) return null; - const items = (record.items as UserPropertyItem[]).map(normalizeItem); + // 形状守卫:元素必须是普通对象且 type 为字符串,否则整体返 null(对齐「非法返 null 不抛」)。 + for (const el of record.items) { + if (el === null || typeof el !== 'object' || Array.isArray(el)) return null; + if (typeof (el as Record).type !== 'string') return null; + } + + const items = (record.items as Record[]).map( + reorderItem, + ) as unknown as UserPropertyItem[]; const meta: Record = { ...record }; delete meta.items; @@ -99,8 +131,9 @@ export function parseCandidateExpression( } /** - * 构建办理人/会签表达式:重建外层对象 {items, ...meta} → JSON.stringify(紧凑无空白)→ - * 结构性 {} 换成全角【】(方括号保持半角)→ 套前后缀。round-trip 与真实表达式逐字一致。 + * 构建办理人/会签表达式:重建外层对象 {items, ...meta} → JSON.stringify(紧凑无空白,replacer + * 对字符串叶子应用 stringToJson 引号映射)→ 结构性 {} 换成全角【】(方括号保持半角)→ 套前后缀。 + * round-trip 与真实表达式逐字一致(半角 content 变体除外,见文件头运行期等价说明)。 */ export function buildCandidateExpression( items: UserPropertyItem[], @@ -108,7 +141,12 @@ export function buildCandidateExpression( meta?: Record, ): string { const prefix = variant === 'multiInstance' ? MULTI_PREFIX : CANDIDATE_PREFIX; - const outer = { items: items.map(normalizeItem), ...(meta ?? {}) }; - const content = halfToFull(JSON.stringify(outer)); - return prefix + content + SUFFIX; + const outer = { + items: items.map((it) => reorderItem(it as unknown as Record)), + ...(meta ?? {}), + }; + const json = JSON.stringify(outer, (_key, value) => + typeof value === 'string' ? escapeLeaf(value) : value, + ); + return prefix + halfToFull(json) + SUFFIX; } diff --git a/tools/codec-corpus-sweep.mjs b/tools/codec-corpus-sweep.mjs new file mode 100644 index 0000000..e788690 --- /dev/null +++ b/tools/codec-corpus-sweep.mjs @@ -0,0 +1,178 @@ +#!/usr/bin/env node +/** + * 语料级办理人/会签表达式 codec 往返核查(T2.3 评审加分项) + * + * 对本地 eip4 库(5433, search_path=eip3)里 act_ge_bytearray 的全部真实 BPMN,抽出每个 + * activiti/flowable 的 candidateUsers / collection 属性值(实体解码到 businessObject 属性 + * 值层),跑与 src/modeler/candidateExpression.ts **逐字镜像**的 parse/build,统计: + * - byteIdentical : build(parse(x)) === x 逐字一致 + * - engineEquiv : 非逐字但引擎运行期等价(整串全局 【→{ 、】→} 还原后相同) + * —— 覆盖 content 用半角 ${users} 的 scriptUser 会签变体(build 归一为全角, + * 引擎 CandidateUsersHandler:54 全局替换后复原,语义无损) + * - parseNull : 前缀匹配但解析失败(硬失败) + * - hardMismatch : 既非逐字亦非引擎等价(硬失败) + * + * ⚠️ 本文件内联的 parse/build 必须与 candidateExpression.ts 保持一致;单测 + * (candidateExpression.test.ts)是编解码契约的权威来源,本工具是全语料回归的旁证。 + * + * 取数:psql 子进程(不引 pg 依赖),同 tools/modeler-fidelity-sweep.mjs。 + * 用法:node tools/codec-corpus-sweep.mjs + * 环境变量:PG_HOST(localhost) PG_PORT(5433) PG_DB(eip4) PG_SCHEMA(eip3) EXPECTED_TOTAL(1512) + */ +import { execFileSync } from 'node:child_process'; + +const PG_HOST = process.env.PG_HOST || 'localhost'; +const PG_PORT = process.env.PG_PORT || '5433'; +const PG_DB = process.env.PG_DB || 'eip4'; +const PG_SCHEMA = process.env.PG_SCHEMA || 'eip3'; +const EXPECTED_TOTAL = Number(process.env.EXPECTED_TOTAL || 1512); + +// ── 镜像 src/modeler/candidateExpression.ts(逐字)──────────────────────────── +const CANDIDATE_PREFIX = "${candidateUsersHandler.getCandidateUsers(execution,'"; +const MULTI_PREFIX = "${multiInstanceUsersHandler.getUsers(execution,'"; +const SUFFIX = "')}"; +const KNOWN_ITEM_KEYS = ['type', 'content', 'isCandidate', 'isSendMail', 'isSendPhone', 'isSendMessage']; +const KNOWN_ITEM_KEY_SET = new Set(KNOWN_ITEM_KEYS); +const fullToHalf = (s) => s.split('【').join('{').split('】').join('}'); +const halfToFull = (s) => s.split('{').join('【').split('}').join('】'); +const escapeLeaf = (v) => v.split("'").join('‘').split('"').join('“'); +function reorderItem(src) { + const o = {}; + for (const k of KNOWN_ITEM_KEYS) if (src[k] !== undefined) o[k] = src[k]; + for (const k of Object.keys(src)) if (!KNOWN_ITEM_KEY_SET.has(k) && src[k] !== undefined) o[k] = src[k]; + return o; +} +function parse(expr) { + if (typeof expr !== 'string' || expr.length === 0) return null; + let variant, prefix; + if (expr.startsWith(CANDIDATE_PREFIX)) { variant = 'candidate'; prefix = CANDIDATE_PREFIX; } + else if (expr.startsWith(MULTI_PREFIX)) { variant = 'multiInstance'; prefix = MULTI_PREFIX; } + else return null; + if (!expr.endsWith(SUFFIX)) return null; + const content = expr.slice(prefix.length, expr.length - SUFFIX.length); + let obj; + try { obj = JSON.parse(fullToHalf(content)); } catch { return null; } + if (obj === null || typeof obj !== 'object') return null; + if (!Array.isArray(obj.items)) return null; + for (const el of obj.items) { + if (el === null || typeof el !== 'object' || Array.isArray(el)) return null; + if (typeof el.type !== 'string') return null; + } + const items = obj.items.map(reorderItem); + const meta = { ...obj }; + delete meta.items; + return { items, variant, meta }; +} +function build(items, variant, meta) { + const prefix = variant === 'multiInstance' ? MULTI_PREFIX : CANDIDATE_PREFIX; + const outer = { items: items.map(reorderItem), ...(meta ?? {}) }; + const json = JSON.stringify(outer, (_k, v) => (typeof v === 'string' ? escapeLeaf(v) : v)); + return prefix + halfToFull(json) + SUFFIX; +} +// 镜像引擎 CandidateUsersHandler:54 的整串全局字面替换 +const engineRestore = (s) => s.split('【').join('{').split('】').join('}'); +// ───────────────────────────────────────────────────────────────────────── + +function decodeEntities(s) { + return String(s) + .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16))) + .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(parseInt(d, 10))) + .replace(/"/g, '"') + .replace(/'/g, "'") + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/&/g, '&'); +} + +function pullCorpus() { + const sql = + `set search_path=${PG_SCHEMA},public; ` + + `select b.id_||'|'||translate(encode(b.bytes_,'base64'),E'\\n','') ` + + `from act_ge_bytearray b where b.name_ like '%.bpmn%' or b.name_ like '%.xml';`; + const out = execFileSync( + 'psql', + ['-h', PG_HOST, '-p', PG_PORT, '-d', PG_DB, '-tA', '-c', sql], + { encoding: 'utf8', maxBuffer: 1024 * 1024 * 1024 }, + ); + const docs = []; + for (const line of out.split('\n')) { + if (!line) continue; + const i = line.indexOf('|'); + if (i < 0) continue; + docs.push({ id: line.slice(0, i), b64: line.slice(i + 1) }); + } + return docs; +} + +function main() { + process.stdout.write(`连库拉取语料 (${PG_HOST}:${PG_PORT}/${PG_DB}, schema=${PG_SCHEMA}) ...\n`); + const docs = pullCorpus(); + process.stdout.write(`取到 ${docs.length} 个 .bpmn/.xml 文档,开始 codec 往返扫描 ...\n\n`); + + const EXPR_RE = /(?:activiti|flowable):(?:candidateUsers|collection)="([^"]*)"/g; + let exprs = 0; + let byteIdentical = 0; + let engineEquiv = 0; + let parseNull = 0; + let hardMismatch = 0; + const itemKeySets = new Map(); + const metaKeySets = new Map(); + const hardSamples = []; + const parseNullSamples = []; + + for (const doc of docs) { + const xml = Buffer.from(doc.b64, 'base64').toString('utf8'); + let m; + EXPR_RE.lastIndex = 0; + while ((m = EXPR_RE.exec(xml)) !== null) { + const val = decodeEntities(m[1]); + if (!val.includes('Handler')) continue; // collection 也可是普通变量名,非 handler 表达式 + exprs++; + const r = parse(val); + if (!r) { + parseNull++; + if (parseNullSamples.length < 5) parseNullSamples.push(val.slice(0, 200)); + continue; + } + for (const it of r.items) itemKeySets.set(Object.keys(it).join(','), (itemKeySets.get(Object.keys(it).join(',')) || 0) + 1); + metaKeySets.set(Object.keys(r.meta).join(','), (metaKeySets.get(Object.keys(r.meta).join(',')) || 0) + 1); + const rebuilt = build(r.items, r.variant, r.meta); + if (rebuilt === val) byteIdentical++; + else if (engineRestore(rebuilt) === engineRestore(val)) engineEquiv++; + else { + hardMismatch++; + if (hardSamples.length < 5) hardSamples.push({ val: val.slice(0, 300), rebuilt: rebuilt.slice(0, 300) }); + } + } + } + + const line = '─'.repeat(60); + process.stdout.write(`${line}\ncodec 往返扫描结果\n${line}\n`); + process.stdout.write(`总文档 ${docs.length}(预期 ${EXPECTED_TOTAL})|表达式 ${exprs}\n`); + process.stdout.write(`逐字一致 ${byteIdentical}|引擎运行期等价 ${engineEquiv}|解析失败 ${parseNull}|硬不匹配 ${hardMismatch}\n`); + process.stdout.write(`\nitem 键集分布:\n`); + for (const [k, c] of [...itemKeySets].sort((a, b) => b[1] - a[1])) process.stdout.write(` ${c.toString().padStart(6)} [${k}]\n`); + process.stdout.write(`\nmeta 键集分布:\n`); + for (const [k, c] of [...metaKeySets].sort((a, b) => b[1] - a[1])) process.stdout.write(` ${c.toString().padStart(6)} [${k || '(空)'}]\n`); + if (parseNullSamples.length) { + process.stdout.write(`\n解析失败样本:\n`); + for (const s of parseNullSamples) process.stdout.write(` ${s}\n`); + } + if (hardSamples.length) { + process.stdout.write(`\n硬不匹配样本(既非逐字亦非引擎等价):\n`); + for (const s of hardSamples) process.stdout.write(` 原文: ${s.val}\n 重建: ${s.rebuilt}\n`); + } + process.stdout.write(`${line}\n`); + + // 硬门:每条表达式都能解析,且要么逐字要么引擎等价(无硬失败),且语料规模符合预期。 + const gateOk = parseNull === 0 && hardMismatch === 0 && docs.length === EXPECTED_TOTAL; + process.exit(gateOk ? 0 : 1); +} + +try { + main(); +} catch (e) { + if (e && e.stderr) process.stderr.write(String(e.stderr)); + process.stderr.write(`扫描崩溃: ${(e && e.stack) || e}\n`); + process.exit(2); +}