dsh-plugin-prompt-tool 1.0.0 → 2.0.1

package/engine/trigger-spec.mjs

@@ -1,141 +1,42 @@
-/**
- * trigger-spec — 声明编译器（B7 T1）：把**纯数据**的触发器声明编译成可注册的形状。
- *
- * 分工：`predicates.mjs` 提供判断原语、`actions.mjs` 提供动作、`trigger.mjs` 提供调度机制，
- * 本文件只做「数据 → 函数」这一步，**不含任何判断或执行的实现**。
- *
- * ## 词汇原样透传（这是本文件最重要的约束）
- *
- * `when` 的键要么是组合运算符（`any` / `all` / `not` / `notAny`），要么是七类原语之一
- * （`text` / `phase` / `source` / `count` / `names` / `session` / `preset`），**值原样传给对应的
- * `createXxxPredicate`**。声明层**不翻译、不改名、不补默认**——一旦这里长出第二套词汇，
- * 「文档里写的选项」与「谓词真正接受的选项」就会开始漂移，而这正是本项目要收敛的问题。
- *
- * ## 为什么 `when` 省略 = 无条件
- *
- * `when` 是**收窄**条件：不写表示「这个动作在该通道上总是执行」。这与「写一个恒真谓词」
- * 在行为上等价，但省略更好读；编译器对省略返回 `undefined`，注册侧据此跳过判定（零开销）。
- *
- * ## 与 `mountTriggers` 的关系
- *
- * `trigger.mjs` 的 `mountTriggers` 要求 `do` 是**函数**，而声明的 `do` 是**动作声明**；
- * B3 收口时两者从未对接。本文件不去接那条线（查证过：`inject-text` 与 `guard` 不经
- * `on(...)` 注册，"执行体"抽不出来），而是编译出 `{when, actions}` 交给
- * `registerAction(ctx, action, { when })` ——判定由动作侧按固定执行阶段提供。
- * 调度层面仍复用 `trigger.mjs` 的 `orderTriggers` / `registrationOptions`。
- */
-import {
-  composite,
-  createCountPredicate,
-  createNameListPredicate,
-  createPhasePredicate,
-  createPresetPredicate,
-  createSessionStatePredicate,
-  createSourcePredicate,
-  createTextPredicate,
-} from './predicates.mjs'
+/** 旧 triggers 声明供离线迁移与历史契约验证；新运行时只编译 rules。 */
 import { ACTION_KINDS, actionExecutionPoint, prepareAction, registerAction } from './actions.mjs'
 import { WATERFALL_POSITIONS, orderTriggers, registrationOptions, wireTriggerObservers } from './trigger.mjs'
-
-/** 七类判断原语：声明里的键 → 工厂。键名与 `predicates.mjs` 的工厂一一对应。 */
-export const PREDICATE_FACTORIES = Object.freeze({
-  text: createTextPredicate,
-  phase: createPhasePredicate,
-  source: createSourcePredicate,
-  count: createCountPredicate,
-  names: createNameListPredicate,
-  session: createSessionStatePredicate,
-  preset: createPresetPredicate,
-})
-
-/** 组合运算符（与 `composite` 的词汇同源，不另立别名）。 */
-export const COMPOSITE_OPERATORS = Object.freeze(['any', 'all', 'not', 'notAny'])
-
-/** 声明允许的字段（未知字段 fail loud：写错键名是最容易被静默忽略的一类错）。 */
-const DECLARATION_FIELDS = Object.freeze(['id', 'channel', 'channelOrder', 'waterfallPosition', 'phase', 'when', 'do'])
-
-/** 判定/动作在 `next()` 之前还是之后执行。 */
+import { compileWhen } from './conditions/index.mjs'
+import { conjunction, expandActions } from './branch.mjs'
+export { compileWhen, COMPOSITE_OPERATORS, PREDICATE_FACTORIES } from './conditions/index.mjs'
+const DECLARATION_FIELDS = Object.freeze(['id', 'channel', 'channelOrder', 'waterfallPosition', 'phase', 'if', 'then', 'else', 'when', 'do'])
 const ACTION_PHASES = Object.freeze(['before-next', 'after-next'])
 
-const objectOrUndefined = (value, label) => {
-  if (value === undefined || value === null) return undefined
-  if (typeof value !== 'object' || Array.isArray(value)) {
-    throw new TypeError(`trigger-spec: ${label} must be an object`)
-  }
-  return value
+/** `then`/`do` 归一化为动作声明数组；分支节点留到 `expandActions` 展开。 */
+function actionList(value, label) {
+  const list = Array.isArray(value) ? value : [value]
+  if (list.length === 0) throw new TypeError(`${label} must be an action declaration or a non-empty array of them`)
+  return list
 }
 
-/**
- * 编译 `when`：声明对象 → 谓词函数；`undefined` / `null` → `undefined`（无条件）。
- *
- * 节点形状（两种，互斥）：
- *   - 组合节点：`{ any: [节点…] }` / `{ all: [节点…] }` / `{ notAny: [节点…] }` / `{ not: 节点 }`
- *   - 原语节点：`{ <类别>: <选项对象> }`
- * **一个节点只能声明一个键**——混合声明（如同时给 `all` 与 `not`）在编译期抛错，
- * 于是优先级永远是显式的树形嵌套，而不是靠"先算 not 再算 and"的隐式约定。
- *
- * @param {unknown} node 声明里的 `when`
- * @param {object} [context] `{ ctx, standingMountFor }`：`preset` 原语需要它们（挂载期注入）
- * @returns {Function|undefined} 谓词函数
- */
-export function compileWhen(node, context = {}) {
-  if (node === undefined || node === null) return undefined
-  if (typeof node !== 'object' || Array.isArray(node)) {
-    throw new TypeError('trigger-spec: when must be an object (a composite node or a predicate node)')
-  }
-  const keys = Object.keys(node)
-  if (keys.length === 0) {
-    throw new TypeError('trigger-spec: when must not be an empty object — 空节点是「恒真」还是「写漏了」无法区分')
-  }
-  if (keys.length > 1) {
-    throw new TypeError(
-      `trigger-spec: when must declare exactly one key — got ${keys.sort().join(', ')}`
-      + `（allowed: ${[...COMPOSITE_OPERATORS, ...Object.keys(PREDICATE_FACTORIES)].sort().join(', ')}）`,
-    )
-  }
-  const [key] = keys
-  const value = node[key]
-
-  if (COMPOSITE_OPERATORS.includes(key)) {
-    if (key === 'not') {
-      return composite({ not: compileWhen(value, context) })
-    }
-    if (!Array.isArray(value) || value.length === 0) {
-      throw new TypeError(`trigger-spec: when.${key} must be a non-empty array of nodes`)
-    }
-    return composite({ [key]: value.map((child) => compileWhen(child, context)) })
+/** 展开后的叶子必须是已知动作。 */
+function assertActionKind(action, at) {
+  if (action === null || typeof action !== 'object' || Array.isArray(action)) {
+    throw new TypeError(`trigger-spec: ${at} must be an action declaration object`)
   }
-
-  const factory = PREDICATE_FACTORIES[key]
-  if (factory === undefined) {
+  if (typeof action.kind !== 'string' || !Object.hasOwn(ACTION_KINDS, action.kind)) {
     throw new TypeError(
-      `trigger-spec: unknown predicate ${JSON.stringify(key)}`
-      + ` — known predicates: ${Object.keys(PREDICATE_FACTORIES).join(', ')}; composite: ${COMPOSITE_OPERATORS.join(', ')}`,
+      `trigger-spec: ${at}.kind must be one of ${Object.keys(ACTION_KINDS).join(', ')} — got ${JSON.stringify(action.kind)}`,
     )
   }
-  const options = objectOrUndefined(value, `when.${key}`) ?? {}
-  // `preset` 原语的取法需要挂载期注入（见 predicates.mjs 的三条硬约束），其余原语只用选项。
-  if (key === 'preset') {
-    return createPresetPredicate({ ...options, ctx: context.ctx, standingMountFor: context.standingMountFor })
-  }
-  return factory(options)
+  return action
 }
 
-/** `do` 归一化为动作声明数组；每个元素的 `kind` 必须是已知动作。 */
-function compileActions(value) {
-  const list = Array.isArray(value) ? value : [value]
-  if (list.length === 0) throw new TypeError('trigger-spec: do must be an action declaration or a non-empty array of them')
-  return list.map((action, index) => {
-    if (action === null || typeof action !== 'object' || Array.isArray(action)) {
-      throw new TypeError(`trigger-spec: do[${index}] must be an action declaration object`)
-    }
-    if (typeof action.kind !== 'string' || !Object.hasOwn(ACTION_KINDS, action.kind)) {
-      throw new TypeError(
-        `trigger-spec: do[${index}].kind must be one of ${Object.keys(ACTION_KINDS).join(', ')} — got ${JSON.stringify(action.kind)}`,
-      )
-    }
-    return action
-  })
+/**
+ * 声明级 `if` 与动作自身分支条件的合取；来自**声明级** `else` 的动作跳过声明级判定
+ * （它的条件里已含 `not(if)`）。两个条件缺省都表示无条件。
+ */
+function actionGate(declarationWhen, action) {
+  const own = action.actionWhen
+  const base = action.bypassRuleWhen === true ? undefined : declarationWhen
+  if (base === undefined) return own
+  if (own === undefined) return base
+  return subject => base(subject) === true && own(subject) === true
 }
 
 /**
@@ -161,9 +62,13 @@ export function compileDeclaration(spec, context = {}) {
   if (typeof spec.channel !== 'string' || spec.channel.length === 0) {
     throw new TypeError(`trigger-spec: trigger ${spec.id}: channel must be a non-empty event name`)
   }
-  if (spec.do === undefined) {
-    throw new TypeError(`trigger-spec: trigger ${spec.id}: do is required`)
-  }
+  const label = `trigger-spec: trigger ${spec.id}`
+  // 旧名已按引擎重构退役：显式拒绝并给出新名。
+  if (spec.when !== undefined) throw new TypeError(`${label}: "when" 已退役，改用 "if"`)
+  if (spec.do !== undefined) throw new TypeError(`${label}: "do" 已退役，改用 "then"`)
+  const triggerIf = spec.if
+  const triggerThen = spec.then
+  if (triggerThen === undefined) throw new TypeError(`${label}: then is required`)
   const channelOrder = spec.channelOrder ?? 0
   if (!Number.isSafeInteger(channelOrder) || channelOrder < 0) {
     throw new TypeError(`trigger-spec: trigger ${spec.id}: channelOrder must be a non-negative safe integer`)
@@ -172,11 +77,22 @@ export function compileDeclaration(spec, context = {}) {
   if (!WATERFALL_POSITIONS.has(waterfallPosition)) {
     throw new TypeError(`trigger-spec: trigger ${spec.id}: waterfallPosition must be one of ${[...WATERFALL_POSITIONS].join(', ')}`)
   }
-  const actions = compileActions(spec.do)
-  const when = compileWhen(spec.when, context)
+  // 声明级 `if` 由注册侧判定；声明级 `else` 的动作自带 `not(if)` 并跳过它，否则自相矛盾。
+  const expanded = [
+    ...expandActions(actionList(triggerThen, `${label}.then`), {}, `${label}.then`),
+    ...(spec.else === undefined ? [] : expandActions(actionList(spec.else, `${label}.else`), {
+      outer: triggerIf === undefined ? [] : [{ not: triggerIf }],
+      bypass: true,
+    }, `${label}.else`)),
+  ]
+  const when = compileWhen(triggerIf, context)
+  const actions = expanded.map(({ node, conditions, bypass }, index) => Object.assign(
+    { ...assertActionKind(node, `action[${index}]`) },
+    { actionWhen: compileWhen(conjunction(conditions), context), bypassRuleWhen: bypass },
+  ))
   // 保存期复用注册入口的纯准备阶段；不绑定 ctx，不创建预算或监听器。
   for (const action of actions) prepareAction(action, {
-    when, promptConfigOptions: context.promptConfigOptions, ...registrationOptions({ waterfallPosition }),
+    when: action.actionWhen ?? when, promptConfigOptions: context.promptConfigOptions, ...registrationOptions({ waterfallPosition }),
   })
   const phase = spec.phase ?? actionExecutionPoint(actions[0]).phase
   if (!ACTION_PHASES.includes(phase)) {
@@ -240,7 +156,7 @@ export function mountDeclarations(ctx, compiled, { plugin, warnOnce } = {}) {
         plugin,
         warnOnce,
         promptConfigOptions: trigger.promptConfigOptions,
-        when: trigger.when,
+        when: actionGate(trigger.when, action),
         prepend: trigger.waterfallPosition === 'outermost',
       }))
     }