@whitewall/blip-sdk 0.0.192 → 0.0.194

package/src/utils/builder.ts

@@ -3,19 +3,20 @@
  * a human or an LLM. It renames the `$`-prefixed keys to readable ones, drops
  * layout metadata and denormalizes state names, so it cannot be pushed back to
  * the builder. For the round-trippable format, see `./minifier.ts`.
+ *
+ * Typed over `MinifiedState`, which a full `State` satisfies, so both a pulled
+ * flow and a minified one digest without casts.
  */
-import { type Action, type ContentActionItem, ROOT_STATE_ID, type State } from '../types/flow.ts'
+import { type Condition, isChatStateSendMessage, resolveEntryPointId } from '../types/flow.ts'
+import type { MinifiedAction, MinifiedInput, MinifiedState } from './minifier.ts'
+
+/** A `Condition` with the builder's nullish bookkeeping dropped. */
+export type ConditionDigest = Omit<Condition, 'variable'> & { variable?: string }
 
 export type ActionDigest = {
     type: string
     settings: Record<string, unknown>
-    conditions?: Array<{
-        source: string
-        variable?: string
-        comparison: string
-        operator?: string
-        values: Array<string>
-    }>
+    conditions?: Array<ConditionDigest>
 }
 
 export type InputDigest = {
@@ -23,14 +24,14 @@ export type InputDigest = {
     variable?: string
     validation?: { rule: string; regex?: string; type?: string; error: string }
     expiration?: string
-    conditions?: ActionDigest['conditions']
+    conditions?: Array<ConditionDigest>
 }
 
 export type OutputDigest = {
     stateId: string
     stateName?: string
     typeOfStateId?: string
-    conditions?: ActionDigest['conditions']
+    conditions?: Array<ConditionDigest>
 }
 
 export type StateDigest = {
@@ -41,20 +42,12 @@ export type StateDigest = {
     contentActions?: Array<{ action?: ActionDigest; input?: InputDigest }>
     leavingActions?: Array<ActionDigest>
     outputs?: Array<OutputDigest>
-    defaultOutput: { stateId: string; stateName?: string; typeOfStateId?: string }
+    defaultOutput: OutputDigest
     afterStateChangedActions?: Array<ActionDigest>
     localActions?: Array<ActionDigest>
 }
 
-function digestConditions(
-    conditions?: Array<{
-        source: string
-        variable?: string
-        comparison: string
-        operator?: string
-        values: Array<string>
-    }>,
-): ActionDigest['conditions'] | undefined {
+function digestConditions(conditions?: Array<Condition>): Array<ConditionDigest> | undefined {
     if (!conditions || conditions.length === 0) return undefined
     return conditions.map((c) => ({
         source: c.source,
@@ -72,17 +65,17 @@ function digestActionSettings(settings: Record<string, unknown>): Record<string,
     return clone
 }
 
-export function digestAction(action: Action): ActionDigest {
+export function digestAction(action: MinifiedAction): ActionDigest {
     const result: ActionDigest = {
         type: action.type,
         settings: digestActionSettings(action.settings as Record<string, unknown>),
     }
-    const conditions = digestConditions(action.conditions as ActionDigest['conditions'])
+    const conditions = digestConditions(action.conditions)
     if (conditions) result.conditions = conditions
     return result
 }
 
-function digestInput(input: ContentActionItem['input']): InputDigest | undefined {
+function digestInput(input: MinifiedInput | undefined): InputDigest | undefined {
     if (!input) return undefined
     const result: InputDigest = { bypass: input.bypass }
     if (input.variable) result.variable = input.variable
@@ -95,36 +88,19 @@ function digestInput(input: ContentActionItem['input']): InputDigest | undefined
         }
     }
     if (input.expiration) result.expiration = input.expiration
-    const conditions = digestConditions(input.conditions as ActionDigest['conditions'])
+    const conditions = digestConditions(input.conditions)
     if (conditions) result.conditions = conditions
     return result
 }
 
-/**
- * Typing indicators are noise in every projection of a flow, so both the digest
- * and the minifier drop them. The two signals are checked because `$typeOfContent`
- * is absent from a minified flow and can come back empty from a GET, while the
- * settings mime type is absent from a hand-written action.
- */
-export function isChatStateSendMessage(item: ContentActionItem): boolean {
-    if (item.action?.type !== 'SendMessage') {
-        return false
-    }
-
-    return (
-        item.action.$typeOfContent === 'chat-state' ||
-        item.action.settings.type === 'application/vnd.lime.chatstate+json'
-    )
-}
-
-export function resolveStateName(stateId: string, flow: Record<string, State>): string | undefined {
+export function resolveStateName(stateId: string, flow: Record<string, MinifiedState>): string | undefined {
     const state = flow[stateId]
     return state?.$title
 }
 
 function digestOutput(
-    output: { stateId: string; typeOfStateId?: string; conditions?: Array<unknown>; $invalid?: boolean },
-    flow: Record<string, State>,
+    output: { stateId: string; typeOfStateId?: string; conditions?: Array<Condition> },
+    flow: Record<string, MinifiedState>,
 ): OutputDigest {
     const result: OutputDigest = {
         stateId: output.stateId,
@@ -132,48 +108,39 @@ function digestOutput(
     const name = resolveStateName(output.stateId, flow)
     if (name) result.stateName = name
     if (output.typeOfStateId) result.typeOfStateId = output.typeOfStateId
-    if ('conditions' in output && Array.isArray(output.conditions) && output.conditions.length > 0) {
-        result.conditions = digestConditions(output.conditions as ActionDigest['conditions'])
-    }
+    const conditions = digestConditions(output.conditions)
+    if (conditions) result.conditions = conditions
     return result
 }
 
-export function digestState(stateId: string, state: State, flow: Record<string, State>): StateDigest {
+export function digestState(stateId: string, state: MinifiedState, flow: Record<string, MinifiedState>): StateDigest {
     const result: StateDigest = {
         id: stateId,
         name: state.$title,
-        defaultOutput: {
-            stateId: state.$defaultOutput.stateId,
-            ...(resolveStateName(state.$defaultOutput.stateId, flow)
-                ? { stateName: resolveStateName(state.$defaultOutput.stateId, flow) }
-                : {}),
-            ...(state.$defaultOutput.typeOfStateId ? { typeOfStateId: state.$defaultOutput.typeOfStateId } : {}),
-        },
+        defaultOutput: digestOutput(state.$defaultOutput, flow),
     }
 
-    // Derived from the id so the digest reads the same whether it is handed a
-    // full flow or a minified one, which no longer carries `root`.
-    if (state.root || stateId === ROOT_STATE_ID) result.root = true
+    if (resolveEntryPointId(flow) === stateId) result.root = true
 
     const enteringActions = state.$enteringCustomActions.map(digestAction)
     if (enteringActions.length > 0) result.enteringActions = enteringActions
 
     const contentActions = state.$contentActions
-        .filter((item: ContentActionItem) => !isChatStateSendMessage(item))
-        .map((item: ContentActionItem) => {
+        .filter((item) => !isChatStateSendMessage(item))
+        .map((item) => {
             const entry: { action?: ActionDigest; input?: InputDigest } = {}
             if (item.action) entry.action = digestAction(item.action)
             const input = digestInput(item.input)
             if (input) entry.input = input
             return entry
         })
-        .filter((entry: { action?: ActionDigest; input?: InputDigest }) => entry.action || entry.input)
+        .filter((entry) => entry.action || entry.input)
     if (contentActions.length > 0) result.contentActions = contentActions
 
     const leavingActions = state.$leavingCustomActions.map(digestAction)
     if (leavingActions.length > 0) result.leavingActions = leavingActions
 
-    const outputs = state.$conditionOutputs.map((o: State['$conditionOutputs'][number]) => digestOutput(o, flow))
+    const outputs = state.$conditionOutputs.map((o) => digestOutput(o, flow))
     if (outputs.length > 0) result.outputs = outputs
 
     const afterStateChangedActions = (state.$afterStateChangedActions ?? []).map(digestAction)

package/src/utils/flow-rules.ts

@@ -0,0 +1,453 @@
+/**
+ * Everything the Builder runtime refuses to run, checked against a minified flow.
+ *
+ * A port of the runtime's own validation — `Models/Flow.cs::Validate`,
+ * `Models/Condition.cs::Validate`, `Models/Input.cs::Validate` and the media type
+ * each action deserializes. All of them throw at load or mid-turn, and the runtime
+ * validates the whole flow on every message, so one of these takes the bot down
+ * for every user rather than breaking one branch.
+ *
+ * The line is deliberate: this file only holds what makes the runtime throw. A
+ * flow that is merely suspect — a quick reply nothing matches, a variable nobody
+ * writes — parses fine here, because that is a linter's job and a schema can only
+ * say "invalid" where a linter can say "warning".
+ *
+ * It is one pass over the whole flow, wired into `minifiedFlowSchema` alone. Zod
+ * skips a `.check()` on a value that already has issues, so a check per action and
+ * a check per state would report the innermost problem and hide the rest.
+ */
+
+import type { Condition } from '../types/flow.ts'
+import { CUSTOM_ACTION_LISTS, inputOf, ROOT_STATE_ID, resolveEntryPointId } from '../types/flow.ts'
+import type { MinifiedAction, MinifiedInput, MinifiedState } from './minifier.ts'
+
+/** Every rule this file can report. */
+export type FlowRule =
+    | 'missing-root-state'
+    | 'root-must-wait'
+    | 'dangling-output'
+    | 'input-less-loop'
+    | 'transition-loop'
+    | 'shadowed-output'
+    | 'invalid-condition'
+    | 'invalid-input-validation'
+    | 'invalid-regex'
+    | 'invalid-variable-name'
+    | 'unreadable-variable'
+    | 'malformed-placeholder'
+    | 'missing-media-type'
+    | 'content-type-mismatch'
+    | 'duplicate-title'
+
+/** Reports a failure, tagged with the rule so a caller can group or suppress. */
+export type ReportRule = (rule: FlowRule, path: Array<string | number>, message: string) => void
+
+/**
+ * The rule a zod issue came from, if it came from one of these checks.
+ *
+ * The id travels in the issue's `params`, which zod types as `Record<string, any>`,
+ * so reading it through here is what keeps `FlowRule` meaning anything on the way
+ * out — a caller that reaches into `params` itself gets `any` back.
+ */
+export function flowRuleOf(issue: { code: string; params?: Record<string, unknown> }): FlowRule | undefined {
+    const rule = issue.code === 'custom' ? issue.params?.rule : undefined
+
+    return typeof rule === 'string' ? (rule as FlowRule) : undefined
+}
+
+type Path = Array<string | number>
+
+const UNARY_COMPARISONS = new Set(['exists', 'notExists'])
+
+/** `Models/Input.cs`: the runtime rejects an input variable outside this set. */
+const INPUT_VARIABLE_PATTERN = /^[a-zA-Z0-9.]+$/
+
+/** `Utils/VariableReplacer.cs`: the only shape the runtime substitutes. */
+const VARIABLE_ALPHABET = '[a-zA-Z0-9.@_-]'
+export const VARIABLE_NAME = new RegExp(`^${VARIABLE_ALPHABET}+$`)
+
+/** Anything brace-wrapped, so the shapes the replacer skips can be reported too. */
+const PLACEHOLDER_PATTERN = /{{([^{}]*)}}/g
+
+/** `ContextBase.cs`: what `VariableName.Parse` accepts before the `@`. */
+const READABLE_NAME_PATTERN = /^[\w\d]+(\.[\w\d.]+)?$/
+
+const MEDIA_TYPE_PATTERN = /^[a-z]+\/[\w.+-]+$/i
+
+/** `Variables/VariableSource.cs`: a name whose first segment is one of these reads a provider. */
+export const PROVIDER_NAMESPACES = new Set([
+    'contact',
+    'calendar',
+    'random',
+    'bucket',
+    'config',
+    'input',
+    'state',
+    'tunnel',
+    'application',
+    'ticket',
+    'resource',
+    'aianswers',
+    'secret',
+    'blipfunction',
+    'aiagent',
+])
+
+/** `Models/Flow.cs`: an output names a state, or a `{{variable}}` resolved at runtime. */
+export const isVariableOutput = (stateId: string) => stateId.startsWith('{{') && stateId.endsWith('}}')
+
+/**
+ * `Models/Flow.cs::Validate`, walked in one pass so every problem in the flow is
+ * reported at once.
+ */
+export function checkFlow(flow: Record<string, MinifiedState>, report: ReportRule): void {
+    checkEntryPoint(flow, report)
+
+    const titles = new Map<string, string>()
+
+    for (const [stateId, state] of Object.entries(flow)) {
+        // The runtime keys states by id and does not care, but the builder
+        // addresses them by title, so a duplicate hides one on the canvas.
+        const title = state.$title.toLowerCase()
+        const duplicate = titles.get(title)
+
+        if (duplicate) {
+            report(
+                'duplicate-title',
+                [stateId, '$title'],
+                `Duplicate state title '${state.$title}', already used by '${duplicate}'`,
+            )
+        } else {
+            titles.set(title, stateId)
+        }
+
+        for (const [output, path] of outputsOf(state)) {
+            if (!isVariableOutput(output.stateId) && !(output.stateId in flow)) {
+                report(
+                    'dangling-output',
+                    [stateId, ...path, 'stateId'],
+                    `'${output.stateId}' is not a state in this flow, and is not a {{variable}}`,
+                )
+            }
+        }
+
+        checkLoops(stateId, state, flow, report)
+        checkState(stateId, state, report)
+    }
+}
+
+/** `Models/Flow.cs`: one entry point, and it has to wait for an input. */
+function checkEntryPoint(flow: Record<string, MinifiedState>, report: ReportRule): void {
+    const declared = Object.values(flow).filter((state) => state.root).length
+
+    if (declared > 1) {
+        report(
+            'missing-root-state',
+            [],
+            `${declared} states are marked "root": true, and a flow can only have one entry point`,
+        )
+        return
+    }
+
+    const stateId = resolveEntryPointId(flow)
+
+    if (!stateId) {
+        report(
+            'missing-root-state',
+            [],
+            `No state is marked "root": true, and there is no '${ROOT_STATE_ID}' state to fall back to`,
+        )
+        return
+    }
+
+    const input = inputOf(flow[stateId])
+
+    if (!input || input.bypass) {
+        report(
+            'root-must-wait',
+            [stateId],
+            'The entry point has to wait for an input: give it an input that is not bypassed',
+        )
+    }
+
+    if (input?.conditions?.length) {
+        report('root-must-wait', [stateId], "The entry point's input must not have conditions")
+    }
+}
+
+/** What one state decides on its own, plus its inputs and actions. */
+function checkState(stateId: string, state: MinifiedState, report: ReportRule): void {
+    for (const [index, output] of state.$conditionOutputs.entries()) {
+        // `ConditionsExtensions.cs` returns true for an empty list, so an output
+        // with no conditions always matches and hides every output after it.
+        if (output.conditions.length === 0 && index < state.$conditionOutputs.length - 1) {
+            report(
+                'shadowed-output',
+                [stateId, '$conditionOutputs', index],
+                `This output has no conditions, so it always matches and the ${
+                    state.$conditionOutputs.length - index - 1
+                } output(s) after it can never run`,
+            )
+        }
+
+        for (const [conditionIndex, condition] of output.conditions.entries()) {
+            checkCondition(condition, [stateId, '$conditionOutputs', index, 'conditions', conditionIndex], report)
+        }
+    }
+
+    for (const [index, item] of state.$contentActions.entries()) {
+        if (item.input) {
+            checkInput(item.input, [stateId, '$contentActions', index, 'input'], report)
+        }
+        if (item.action) {
+            checkAction(item.action, [stateId, '$contentActions', index, 'action'], report)
+        }
+    }
+
+    for (const list of CUSTOM_ACTION_LISTS) {
+        for (const [index, action] of (state[list] ?? []).entries()) {
+            checkAction(action, [stateId, list, index], report)
+        }
+    }
+
+    checkVariableReads(stateId, state, report)
+}
+
+/** `Models/Condition.cs::Validate`, plus the regex the comparison would compile. */
+function checkCondition(condition: Condition, path: Path, report: ReportRule): void {
+    if (condition.source === 'context' && !condition.variable) {
+        report('invalid-condition', path, 'A condition on the context has to name a variable')
+    }
+
+    const takesValues = !UNARY_COMPARISONS.has(condition.comparison)
+
+    if (takesValues !== condition.values.length > 0) {
+        report(
+            'invalid-condition',
+            [...path, 'values'],
+            takesValues
+                ? `'${condition.comparison}' has no values to compare against`
+                : `'${condition.comparison}' is rejected by the runtime when values are provided`,
+        )
+    }
+
+    if (condition.comparison === 'matches') {
+        for (const [index, value] of condition.values.entries()) {
+            checkRegex(value, [...path, 'values', index], report)
+        }
+    }
+}
+
+/** `Models/Input.cs::Validate`. */
+function checkInput(input: MinifiedInput, path: Path, report: ReportRule): void {
+    if (input.variable && !INPUT_VARIABLE_PATTERN.test(input.variable)) {
+        report(
+            'invalid-variable-name',
+            [...path, 'variable'],
+            `'${input.variable}' is rejected by the runtime: letters, numbers and dots only`,
+        )
+    }
+
+    if (input.validation) {
+        const { rule, regex, type, error } = input.validation
+
+        if (rule === 'regex' && !regex) {
+            report('invalid-input-validation', [...path, 'validation', 'regex'], "The 'regex' rule needs a regex")
+        }
+
+        if (rule === 'type' && !type) {
+            report('invalid-input-validation', [...path, 'validation', 'type'], "The 'type' rule needs a media type")
+        }
+
+        // Required for every rule, not just regex.
+        if (!error.trim()) {
+            report(
+                'invalid-input-validation',
+                [...path, 'validation', 'error'],
+                'The validation needs the message to send when the answer does not pass',
+            )
+        }
+
+        if (regex) {
+            checkRegex(regex, [...path, 'validation', 'regex'], report)
+        }
+    }
+
+    for (const [index, condition] of (input.conditions ?? []).entries()) {
+        checkCondition(condition, [...path, 'conditions', index], report)
+    }
+}
+
+/** What each action needs before the runtime will run it. */
+function checkAction(action: MinifiedAction, path: Path, report: ReportRule): void {
+    for (const [index, condition] of (action.conditions ?? []).entries()) {
+        checkCondition(condition, [...path, 'conditions', index], report)
+    }
+
+    if (action.type !== 'SendMessage' && action.type !== 'SendRawMessage') {
+        return
+    }
+
+    const { type } = action.settings
+
+    if (!type) {
+        report('missing-media-type', [...path, 'settings', 'type'], `A ${action.type} action requires a settings.type`)
+        return
+    }
+
+    if (action.type === 'SendRawMessage') {
+        if (!MEDIA_TYPE_PATTERN.test(type)) {
+            report('missing-media-type', [...path, 'settings', 'type'], `'${type}' is not a valid media type`)
+        }
+        return
+    }
+
+    // `SendMessageAction.cs` deserializes a `+json` content into a dictionary,
+    // which throws on a string. The plain branch stringifies whatever it gets, so
+    // only the document types are worth checking.
+    if (type !== 'text/plain' && typeof action.settings.content !== 'object') {
+        report(
+            'content-type-mismatch',
+            [...path, 'settings', 'content'],
+            `A '${type}' message needs an object as its content`,
+        )
+    }
+}
+
+/**
+ * A state that can be reached again without the user ever answering.
+ *
+ * `Flow.cs` walks this transitively and refuses to load the flow when the state
+ * has no input element at all; a state whose only way out is itself burns the ten
+ * transitions an input is allowed and throws mid-turn. A bypassed state that has
+ * another way out is left alone: paging through a shrinking variable is a real
+ * pattern, and it terminates.
+ */
+function checkLoops(
+    stateId: string,
+    state: MinifiedState,
+    flow: Record<string, MinifiedState>,
+    report: ReportRule,
+): void {
+    const input = inputOf(state)
+
+    if (input && !input.bypass) {
+        return
+    }
+
+    if (outputsOf(state).every(([output]) => output.stateId === stateId)) {
+        report(
+            'transition-loop',
+            [stateId],
+            'Every output leads back to this state and it does not wait for an input, so the runtime loops until it hits the transition limit',
+        )
+        return
+    }
+
+    if (input) {
+        return
+    }
+
+    const seen = new Set([stateId])
+    const pending = [stateId]
+
+    while (pending.length > 0) {
+        for (const [output] of outputsOf(flow[pending.pop()!])) {
+            if (output.stateId === stateId) {
+                report(
+                    'input-less-loop',
+                    [stateId],
+                    'This state has no input and can be reached again without the user ever answering, which the runtime refuses to load',
+                )
+                return
+            }
+
+            const next = flow[output.stateId]
+
+            if (!next || seen.has(output.stateId)) {
+                continue
+            }
+
+            // A state that waits for an answer breaks the chain.
+            const nextInput = inputOf(next)
+
+            if (!nextInput || nextInput.bypass) {
+                seen.add(output.stateId)
+                pending.push(output.stateId)
+            }
+        }
+    }
+}
+
+/**
+ * Every `{{reference}}` a state carries, deduped, with script sources masked out:
+ * a script's braces are a doc comment or a nested object literal, not a read.
+ */
+export function placeholderReadsOf(state: MinifiedState): Array<string> {
+    const readable = JSON.stringify(state, (_key, value) =>
+        value?.type === 'ExecuteScript' || value?.type === 'ExecuteScriptV2'
+            ? { ...value, settings: { ...value.settings, source: '' } }
+            : value,
+    )
+
+    return [...new Set([...readable.matchAll(PLACEHOLDER_PATTERN)].map((match) => match[1]))]
+}
+
+/**
+ * A `{{...}}` the replacer will not substitute reaches the user with its braces
+ * showing, and one it substitutes but `VariableName.Parse` throws on aborts the
+ * turn instead of resolving to an empty string.
+ */
+function checkVariableReads(stateId: string, state: MinifiedState, report: ReportRule): void {
+    for (const reference of placeholderReadsOf(state)) {
+        if (!VARIABLE_NAME.test(reference)) {
+            report(
+                'malformed-placeholder',
+                [stateId],
+                `'{{${reference}}}' is not a name the runtime substitutes${
+                    reference !== reference.trim() ? ' (spaces are not allowed inside the braces)' : ''
+                }, so it is sent as written`,
+            )
+            continue
+        }
+
+        const name = reference.split('@')[0]
+        const namespace = name.split('.')[0]
+
+        if (PROVIDER_NAMESPACES.has(namespace.toLowerCase())) {
+            continue
+        }
+
+        if (!READABLE_NAME_PATTERN.test(name)) {
+            report(
+                'unreadable-variable',
+                [stateId],
+                `'{{${name}}}' cannot be parsed by the runtime — a hyphen is the usual cause — and reading it aborts the turn`,
+            )
+        } else if (name.includes('.')) {
+            report(
+                'unreadable-variable',
+                [stateId],
+                `'{{${name}}}' looks like a provider read, but '${namespace}' is not one, so reading it aborts the turn. A context variable cannot contain a dot`,
+            )
+        }
+    }
+}
+
+function checkRegex(pattern: string, path: Path, report: ReportRule): void {
+    try {
+        new RegExp(pattern)
+    } catch {
+        report('invalid-regex', path, `'${pattern}' is not a valid regular expression`)
+    }
+}
+
+function outputsOf(state: MinifiedState): Array<[{ stateId: string }, Path]> {
+    return [
+        [state.$defaultOutput, ['$defaultOutput']],
+        ...state.$conditionOutputs.map((output, index): [{ stateId: string }, Path] => [
+            output,
+            ['$conditionOutputs', index],
+        ]),
+    ]
+}