@whitewall/blip-sdk 0.0.191 → 0.0.193

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],
+        ]),
+    ]
+}