Inspect & lint flows

​

bot.describe(): Mermaid diagram or JSON graph

import { writeFileSync } from 'node:fs'
import { Bot, flow, describeFlows } from '@botmesh/core'

bot.use(
  flow('register')
    .timeout('2m')
    .ask('Name?', 'name')
    .choose('Plan?', { pro: 'Pro', free: 'Free' })
    .goto('support'),
)
bot.conversation('support', async (c, ctx) => { /* ... */ })

writeFileSync('flows.mmd', bot.describe())         // Mermaid (default): paste it in mermaid.live or a ```mermaid block
const graph = bot.describe({ format: 'json' })     // { version: 1, flows, groups, nodes, edges }, plain JSON data
bot.describe({ direction: 'LR', maxLabelLength: 40 })
describeFlows([flowA, flowB])                       // without a Bot: a list of FlowBuilder/CompiledFlow

• One subgraph per DSL flow. The entry node (▶) lists every trigger that starts it (bot.use, bot.when(trigger, flow), a bot.conversation trigger). With bot.when(trigger, flow) the flow’s own trigger is not routed, and the diagram shows that.
• say, ask (→ state key, ⏱ when the step has its own timeout, ✓schema when it validates with a schema), do (with the function name if it has one: do: saveUser()), media (with its kind: media (document): ...), choose (a diamond; options are arrows labelled 1) Label, like the menu the user sees), form (its fields and state key), guard (guard: isAdmin(), with ✗→ target when it redirects), use (the sub-flow drawn inline, returning to the next step), delay (.delay() steps; a { delay } option is appended to its step’s label), goto (a dotted arrow to the target flow) and end.
• An option’s then: is its own node when it is an action, or a nested subgraph that returns to the parent’s next step when it is a sub-flow. An option’s goto is an arrow to its target flow.
• The flow’s .timeout() and .persistent() go in the subgraph title.
• A goto to a flow that does not exist is drawn as a missing: name node.
• Steps after an unconditional goto have no incoming arrow (visible dead code).
• Async conversations (bot.conversation(name, fn)) are opaque: one node with their triggers.
• User text is escaped with Mermaid entity codes, so it cannot break a label or inject %%{init}%% directives. Node ids (f0_in, f0_s3, f0_end…) are stable and the same in Mermaid, JSON and lint results.

​

bot.lint(): static checks

for (const d of bot.lint({ minSeverity: 'warning' })) {
  bot.logger.warn({ code: d.code, flow: d.flow, path: d.path }, d.message)
}
if (bot.lint().some((d) => d.severity === 'error')) process.exitCode = 1  // CI gate
bot.lint({ rules: { 'missing-timeout': false } })                          // turn a rule off
lintFlows([flowA, flowB])                                                    // without a Bot

​

Lower-level helpers

• describeFlows(source, options) and lintFlows(source, options) accept a Bot, a FlowInventory or an array of flows.
• bot.flowInventory() returns the snapshot they work on (registrations, routes, the default timeout and whether the store is durable) for your own tooling. MemoryStore#durable is true when it has a file.
• describeTrigger(trigger) returns { label, patterns, match, scope, predicate }.

​

Next steps

• Conversation flows
• Testing