From 721cb56ff6d3a348e72c2e4a247b528c3e421d0f Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:30:15 +1300 Subject: [PATCH 01/13] feat: add flow schema v4 with variables --- .../canonical/variables.canonical.yaml | 11 + conformance/canonical/variables.expected.json | 4 + conformance/canonical/variables.input.yaml | 12 + .../v3/invalid/variables-in-v3.expected.json | 5 + conformance/v3/invalid/variables-in-v3.yaml | 25 + .../v4/valid/ask-question.expected.json | 5 + conformance/v4/valid/ask-question.yaml | 25 + crates/wavekat-flow/build.rs | 2 +- .../wavekat-flow/schema/flow.v4.schema.json | 307 ++++++++++ crates/wavekat-flow/src/canonical.rs | 4 +- crates/wavekat-flow/src/lib.rs | 13 +- crates/wavekat-flow/src/validate.rs | 21 + docs/ROADMAP.md | 4 +- packages/flow-schema/scripts/generate.mjs | 2 +- .../src/generated/flow.v4.schema.json | 307 ++++++++++ packages/flow-schema/src/generated/model.ts | 34 +- packages/flow-schema/src/generated/schema.ts | 547 +++++++++++++++++- packages/flow-schema/src/index.ts | 4 +- packages/flow-schema/src/model.ts | 10 +- packages/flow-schema/src/parse.ts | 50 +- packages/flow-schema/src/serialize.ts | 4 +- packages/flow-schema/src/structure.ts | 3 +- packages/flow-schema/src/validate.ts | 16 + schema/README.md | 5 + schema/flow.v4.schema.json | 307 ++++++++++ 25 files changed, 1704 insertions(+), 23 deletions(-) create mode 100644 conformance/canonical/variables.canonical.yaml create mode 100644 conformance/canonical/variables.expected.json create mode 100644 conformance/canonical/variables.input.yaml create mode 100644 conformance/v3/invalid/variables-in-v3.expected.json create mode 100644 conformance/v3/invalid/variables-in-v3.yaml create mode 100644 conformance/v4/valid/ask-question.expected.json create mode 100644 conformance/v4/valid/ask-question.yaml create mode 100644 crates/wavekat-flow/schema/flow.v4.schema.json create mode 100644 packages/flow-schema/src/generated/flow.v4.schema.json create mode 100644 schema/flow.v4.schema.json diff --git a/conformance/canonical/variables.canonical.yaml b/conformance/canonical/variables.canonical.yaml new file mode 100644 index 0000000..7f15b7c --- /dev/null +++ b/conformance/canonical/variables.canonical.yaml @@ -0,0 +1,11 @@ +schema_version: 4 +id: flow_vars_canon +name: Ask a question +variables: + question: { description: The question, required: true, max_len: 300 } + note_to_self: { default: "" } +entry: ask +nodes: + ask: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/canonical/variables.expected.json b/conformance/canonical/variables.expected.json new file mode 100644 index 0000000..d8edb18 --- /dev/null +++ b/conformance/canonical/variables.expected.json @@ -0,0 +1,4 @@ +{ + "description": "Top-level `variables` is written right after `note` and before `entry`, each variable in schema property order (`description`, `required`, `default`, `max_len`). A `required: false` and a `max_len: 200` equal their defaults and are dropped; an empty `default` is a value, not a default, so it stays.", + "comments": 1 +} diff --git a/conformance/canonical/variables.input.yaml b/conformance/canonical/variables.input.yaml new file mode 100644 index 0000000..612091e --- /dev/null +++ b/conformance/canonical/variables.input.yaml @@ -0,0 +1,12 @@ +# Variables, written out of order and with defaults spelled out. +schema_version: 4 +name: Ask a question +id: flow_vars_canon +entry: ask +variables: + question: { max_len: 300, required: true, description: The question } + note_to_self: { default: "", required: false, max_len: 200 } +nodes: + ask: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/v3/invalid/variables-in-v3.expected.json b/conformance/v3/invalid/variables-in-v3.expected.json new file mode 100644 index 0000000..be405ec --- /dev/null +++ b/conformance/v3/invalid/variables-in-v3.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A version 3 document may not declare `variables`: an engine that only knows version 3 would ignore them and speak the `{{name}}` placeholders as written, so the field needs the version that has it. The declaration is itself valid structurally; only the version rule refuses it.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["field_requires_newer_schema"] } +} diff --git a/conformance/v3/invalid/variables-in-v3.yaml b/conformance/v3/invalid/variables-in-v3.yaml new file mode 100644 index 0000000..303aa67 --- /dev/null +++ b/conformance/v3/invalid/variables-in-v3.yaml @@ -0,0 +1,25 @@ +schema_version: 3 +id: flow_variables_in_v3 +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, required: true, max_len: 300 } + option1: { description: Answer for key 1, required: true, max_len: 80 } + option2: { description: Answer for key 2, required: true, max_len: 80 } + option3: { description: Answer for key 3, max_len: 80 } + option4: { description: Answer for key 4, max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/v4/valid/ask-question.expected.json b/conformance/v4/valid/ask-question.expected.json new file mode 100644 index 0000000..db8296f --- /dev/null +++ b/conformance/v4/valid/ask-question.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Flow variables: a top-level `variables` map declares details filled per call. The `{{name}}` placeholders in the prompt and menu labels are plain text to this version of the format; they are read and checked by a later step, so here they only have to be accepted. The 9 key loops back to the same menu, which waits for a key and so is not an unbounded loop.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v4/valid/ask-question.yaml b/conformance/v4/valid/ask-question.yaml new file mode 100644 index 0000000..193aa37 --- /dev/null +++ b/conformance/v4/valid/ask-question.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, required: true, max_len: 300 } + option1: { description: Answer for key 1, required: true, max_len: 80 } + option2: { description: Answer for key 2, required: true, max_len: 80 } + option3: { description: Answer for key 3, max_len: 80 } + option4: { description: Answer for key 4, max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/crates/wavekat-flow/build.rs b/crates/wavekat-flow/build.rs index ff26a94..3ef6f9e 100644 --- a/crates/wavekat-flow/build.rs +++ b/crates/wavekat-flow/build.rs @@ -20,7 +20,7 @@ use std::{env, fs, path::Path}; /// Oldest first; the last entry is the one the model is generated from. -const VERSIONS: &[u32] = &[1, 2, 3]; +const VERSIONS: &[u32] = &[1, 2, 3, 4]; fn main() { println!("cargo:rerun-if-changed=build.rs"); diff --git a/crates/wavekat-flow/schema/flow.v4.schema.json b/crates/wavekat-flow/schema/flow.v4.schema.json new file mode 100644 index 0000000..b7c0982 --- /dev/null +++ b/crates/wavekat-flow/schema/flow.v4.schema.json @@ -0,0 +1,307 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": ["schema_version", "id", "name", "entry", "nodes"], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Variable" } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Node" } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "required": { + "description": "Whether a call must supply a non-empty value.", + "type": "boolean", + "default": false + }, + "default": { + "description": "The value used when a call supplies none.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { "title": "Text", "type": "string" }, + { + "title": "Audio", + "type": "object", + "required": ["audio"], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": ["beep", "none"] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": ["open", "close"], + "properties": { + "open": { "type": "string" }, + "close": { "type": "string" } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "tue": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "wed": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "thu": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "fri": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sat": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sun": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": ["date"], + "properties": { + "date": { "description": "\"YYYY-MM-DD\" in the flow's timezone.", "type": "string" }, + "closed": { "description": "Closed all day regardless of ranges.", "type": "boolean", "default": false }, + "ranges": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { "$ref": "#/$defs/GreetingNode" }, + { "$ref": "#/$defs/HoursNode" }, + { "$ref": "#/$defs/MenuNode" }, + { "$ref": "#/$defs/RingNode" }, + { "$ref": "#/$defs/MessageNode" }, + { "$ref": "#/$defs/TransferNode" }, + { "$ref": "#/$defs/HangupNode" }, + { "$ref": "#/$defs/BookNode" } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "greeting" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": ["kind", "schedule", "timezone"], + "properties": { + "kind": { "const": "hours" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { "description": "IANA zone (America/New_York). Validated to resolve at load.", "type": "string" }, + "exceptions": { "type": "array", "items": { "$ref": "#/$defs/HoursException" } }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": ["kind", "prompt", "options"], + "properties": { + "kind": { "const": "menu" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "retries": { "type": "integer", "minimum": 0, "default": 1 }, + "timeout_secs": { "type": "integer", "minimum": 0, "default": 5 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": ["kind", "timeout_secs"], + "properties": { + "kind": { "const": "ring" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "timeout_secs": { "type": "integer", "minimum": 0 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "message" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "max_secs": { "type": "integer", "minimum": 0, "default": 120 }, + "tone": { "allOf": [{ "$ref": "#/$defs/MessageTone" }], "default": "beep" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": ["kind", "target"], + "properties": { + "kind": { "const": "transfer" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "target": { "type": "string" }, + "whisper": { "$ref": "#/$defs/Prompt" }, + "timeout_secs": { "type": "integer", "minimum": 5, "maximum": 120 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": ["kind"], + "properties": { + "kind": { "const": "hangup" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": ["kind", "prompt", "confirm_prompt", "schedule", "timezone", "duration_mins"], + "properties": { + "kind": { "const": "book" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "confirm_prompt": { "$ref": "#/$defs/Prompt" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { "$ref": "#/$defs/HoursException" } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { "$ref": "#/$defs/Exits" } + } + } + } +} diff --git a/crates/wavekat-flow/src/canonical.rs b/crates/wavekat-flow/src/canonical.rs index 769b369..39d9ec0 100644 --- a/crates/wavekat-flow/src/canonical.rs +++ b/crates/wavekat-flow/src/canonical.rs @@ -12,12 +12,12 @@ use std::sync::OnceLock; use serde_json::{Map, Value}; -use crate::{Flow, FLOW_V3_SCHEMA}; +use crate::{Flow, FLOW_V4_SCHEMA}; /// The newest schema, which the model is generated from. pub(crate) fn schema() -> &'static Value { static SCHEMA: OnceLock = OnceLock::new(); - SCHEMA.get_or_init(|| serde_json::from_str(FLOW_V3_SCHEMA).expect("bundled schema is JSON")) + SCHEMA.get_or_init(|| serde_json::from_str(FLOW_V4_SCHEMA).expect("bundled schema is JSON")) } /// Follow `$ref` (and a single-entry `allOf`, the schema's way of putting a diff --git a/crates/wavekat-flow/src/lib.rs b/crates/wavekat-flow/src/lib.rs index be38055..1739bcb 100644 --- a/crates/wavekat-flow/src/lib.rs +++ b/crates/wavekat-flow/src/lib.rs @@ -62,16 +62,21 @@ pub const FLOW_V1_SCHEMA: &str = include_str!("../schema/flow.v1.schema.json"); pub const FLOW_V2_SCHEMA: &str = include_str!("../schema/flow.v2.schema.json"); /// Format version 3 — version 2 plus the screened transfer (`transfer` -/// gains `whisper` and `timeout_secs`). This is also the file the model -/// types are generated from, being the newest. +/// gains `whisper` and `timeout_secs`). pub const FLOW_V3_SCHEMA: &str = include_str!("../schema/flow.v3.schema.json"); +/// Format version 4 — version 3 plus flow variables (a top-level +/// `variables` map). This is also the file the model types are generated +/// from, being the newest. +pub const FLOW_V4_SCHEMA: &str = include_str!("../schema/flow.v4.schema.json"); + /// The schema for a declared version, or `None` if this build has none. pub fn flow_schema(version: u32) -> Option<&'static str> { match version { 1 => Some(FLOW_V1_SCHEMA), 2 => Some(FLOW_V2_SCHEMA), 3 => Some(FLOW_V3_SCHEMA), + 4 => Some(FLOW_V4_SCHEMA), _ => None, } } @@ -82,9 +87,9 @@ pub fn flow_schema(version: u32) -> Option<&'static str> { /// This is what a daemon advertises and the platform refuses to serve /// past: a device that only knows version 1 must never be handed a /// document that uses a component it has no code for. -pub const SUPPORTED_SCHEMA_VERSIONS: &[u32] = &[1, 2, 3]; +pub const SUPPORTED_SCHEMA_VERSIONS: &[u32] = &[1, 2, 3, 4]; /// The newest version this build authors. Reading stays broad /// ([`SUPPORTED_SCHEMA_VERSIONS`]); writing is deliberately one number. /// Twin: `model.ts` `CURRENT_SCHEMA_VERSION`. -pub const CURRENT_SCHEMA_VERSION: u32 = 3; +pub const CURRENT_SCHEMA_VERSION: u32 = 4; diff --git a/crates/wavekat-flow/src/validate.rs b/crates/wavekat-flow/src/validate.rs index 563af81..24871e7 100644 --- a/crates/wavekat-flow/src/validate.rs +++ b/crates/wavekat-flow/src/validate.rs @@ -40,6 +40,10 @@ const MAX_TRANSFER_TIMEOUT_SECS: i64 = 120; /// on a `transfer`. Twin: `model.ts` `TRANSFER_FIELDS_MIN_SCHEMA_VERSION`. const TRANSFER_FIELDS_MIN_SCHEMA_VERSION: u32 = 3; +/// The oldest `schema_version` that may declare `variables`. Twin: +/// `model.ts` `VARIABLES_MIN_SCHEMA_VERSION`. +const VARIABLES_MIN_SCHEMA_VERSION: u32 = 4; + /// One thing wrong with a flow document. Carries enough context (node id, /// exit name, offending value) for the editor to point at it. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] @@ -129,6 +133,9 @@ pub enum ValidationError { declared: i64, }, + #[error("variables needs schema_version {required} (this document declares {declared})")] + VariablesRequireNewerSchema { required: u32, declared: i64 }, + #[error("transfer node {node:?} sets timeout_secs but has no whisper to screen with")] TimeoutWithoutWhisper { node: NodeId }, @@ -181,6 +188,7 @@ impl ValidationError { ValidationError::BookNeverOpen { .. } => "book_never_open", ValidationError::KindRequiresNewerSchema { .. } => "kind_requires_newer_schema", ValidationError::FieldRequiresNewerSchema { .. } => "field_requires_newer_schema", + ValidationError::VariablesRequireNewerSchema { .. } => "field_requires_newer_schema", ValidationError::TimeoutWithoutWhisper { .. } => "timeout_without_whisper", ValidationError::TransferTimeoutOutOfRange { .. } => "transfer_timeout_out_of_range", ValidationError::OutboundNodeNotAllowed { .. } => "outbound_node_not_allowed", @@ -213,6 +221,11 @@ fn kind_min_schema_version(kind: &str) -> i64 { /// /// Twin: `model.ts` `requiredSchemaVersion`. pub fn required_schema_version(flow: &Flow) -> i64 { + let variables = if !flow.variables.is_empty() { + i64::from(VARIABLES_MIN_SCHEMA_VERSION) + } else { + 1 + }; flow.nodes .values() .map(|node| { @@ -230,6 +243,7 @@ pub fn required_schema_version(flow: &Flow) -> i64 { }) .max() .unwrap_or(1) + .max(variables) } /// Validate a parsed flow. `Ok(())` means safe to publish / execute; `Err` @@ -246,6 +260,13 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { )); } + if !flow.variables.is_empty() && flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { + errs.push(ValidationError::VariablesRequireNewerSchema { + required: VARIABLES_MIN_SCHEMA_VERSION, + declared: flow.schema_version, + }); + } + if flow.nodes.is_empty() { errs.push(ValidationError::EmptyFlow); return Err(errs); // graph checks below would be meaningless diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d49d6fd..cb83709 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -187,5 +187,5 @@ Trigger: the format is stable enough and the repo is ready to be public. validation dispatches on the document's declared version, and a per-kind minimum version in both validators is what tells an author "bump the version" instead of "fix the typo". `assistant` becomes - version 4: version 3 went to the screened transfer (`transfer` gains - `whisper` and `timeout_secs`). + version 5: version 3 went to the screened transfer (`transfer` gains + `whisper` and `timeout_secs`) and version 4 to flow variables. diff --git a/packages/flow-schema/scripts/generate.mjs b/packages/flow-schema/scripts/generate.mjs index 6134f17..68e357e 100644 --- a/packages/flow-schema/scripts/generate.mjs +++ b/packages/flow-schema/scripts/generate.mjs @@ -24,7 +24,7 @@ const repoRoot = resolve(pkg, '..', '..'); const genDir = resolve(pkg, 'src', 'generated'); // Oldest first; the last entry is the one the model is generated from. -const VERSIONS = [1, 2, 3]; +const VERSIONS = [1, 2, 3, 4]; const schemaPathFor = (v) => resolve(repoRoot, 'schema', `flow.v${v}.schema.json`); await mkdir(genDir, { recursive: true }); diff --git a/packages/flow-schema/src/generated/flow.v4.schema.json b/packages/flow-schema/src/generated/flow.v4.schema.json new file mode 100644 index 0000000..b7c0982 --- /dev/null +++ b/packages/flow-schema/src/generated/flow.v4.schema.json @@ -0,0 +1,307 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": ["schema_version", "id", "name", "entry", "nodes"], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Variable" } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Node" } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "required": { + "description": "Whether a call must supply a non-empty value.", + "type": "boolean", + "default": false + }, + "default": { + "description": "The value used when a call supplies none.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { "title": "Text", "type": "string" }, + { + "title": "Audio", + "type": "object", + "required": ["audio"], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": ["beep", "none"] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": ["open", "close"], + "properties": { + "open": { "type": "string" }, + "close": { "type": "string" } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "tue": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "wed": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "thu": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "fri": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sat": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sun": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": ["date"], + "properties": { + "date": { "description": "\"YYYY-MM-DD\" in the flow's timezone.", "type": "string" }, + "closed": { "description": "Closed all day regardless of ranges.", "type": "boolean", "default": false }, + "ranges": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { "$ref": "#/$defs/GreetingNode" }, + { "$ref": "#/$defs/HoursNode" }, + { "$ref": "#/$defs/MenuNode" }, + { "$ref": "#/$defs/RingNode" }, + { "$ref": "#/$defs/MessageNode" }, + { "$ref": "#/$defs/TransferNode" }, + { "$ref": "#/$defs/HangupNode" }, + { "$ref": "#/$defs/BookNode" } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "greeting" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": ["kind", "schedule", "timezone"], + "properties": { + "kind": { "const": "hours" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { "description": "IANA zone (America/New_York). Validated to resolve at load.", "type": "string" }, + "exceptions": { "type": "array", "items": { "$ref": "#/$defs/HoursException" } }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": ["kind", "prompt", "options"], + "properties": { + "kind": { "const": "menu" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "retries": { "type": "integer", "minimum": 0, "default": 1 }, + "timeout_secs": { "type": "integer", "minimum": 0, "default": 5 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": ["kind", "timeout_secs"], + "properties": { + "kind": { "const": "ring" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "timeout_secs": { "type": "integer", "minimum": 0 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "message" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "max_secs": { "type": "integer", "minimum": 0, "default": 120 }, + "tone": { "allOf": [{ "$ref": "#/$defs/MessageTone" }], "default": "beep" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": ["kind", "target"], + "properties": { + "kind": { "const": "transfer" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "target": { "type": "string" }, + "whisper": { "$ref": "#/$defs/Prompt" }, + "timeout_secs": { "type": "integer", "minimum": 5, "maximum": 120 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": ["kind"], + "properties": { + "kind": { "const": "hangup" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": ["kind", "prompt", "confirm_prompt", "schedule", "timezone", "duration_mins"], + "properties": { + "kind": { "const": "book" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "confirm_prompt": { "$ref": "#/$defs/Prompt" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { "$ref": "#/$defs/HoursException" } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { "$ref": "#/$defs/Exits" } + } + } + } +} diff --git a/packages/flow-schema/src/generated/model.ts b/packages/flow-schema/src/generated/model.ts index 06966e4..8922a0d 100644 --- a/packages/flow-schema/src/generated/model.ts +++ b/packages/flow-schema/src/generated/model.ts @@ -1,4 +1,4 @@ -// GENERATED from schema/flow.v{1,2,3}.schema.json by scripts/generate.mjs — do not edit. +// GENERATED from schema/flow.v{1,2,3,4}.schema.json by scripts/generate.mjs — do not edit. // Run `pnpm gen` after changing a schema; CI fails on drift. /** @@ -16,11 +16,11 @@ export type Text = string; export type MessageTone = 'beep' | 'none'; /** - * The WaveKat call-flow ("Receptionist") document, schema_version 3. Version 3 is version 2 plus the screened transfer: the `transfer` node gains `whisper` and `timeout_secs`. Every version-2 document is a valid version-3 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning). + * The WaveKat call-flow ("Receptionist") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning). */ export interface Flow { /** - * Document format version. This file describes version 3 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.) (Relaxed from a constant to a plain integer for type generation: one model type covers every supported version.) + * Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.) (Relaxed from a constant to a plain integer for type generation: one model type covers every supported version.) */ schema_version: number; /** @@ -39,6 +39,12 @@ export interface Flow { * The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine. */ note?: string; + /** + * Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written. + */ + variables?: { + [k: string]: Variable; + }; /** * Node id where execution begins. */ @@ -57,6 +63,28 @@ export interface Flow { }; [k: string]: unknown; } +/** + * One declared variable. + */ +export interface Variable { + /** + * What the value is, shown to whoever fills it in. + */ + description?: string; + /** + * Whether a call must supply a non-empty value. + */ + required?: boolean; + /** + * The value used when a call supplies none. + */ + default?: string; + /** + * Longest a value may be, in Unicode characters. + */ + max_len?: number; + [k: string]: unknown; +} /** * Speak a prompt, then continue. Exit: next. */ diff --git a/packages/flow-schema/src/generated/schema.ts b/packages/flow-schema/src/generated/schema.ts index 9d804ae..43eea02 100644 --- a/packages/flow-schema/src/generated/schema.ts +++ b/packages/flow-schema/src/generated/schema.ts @@ -1,4 +1,4 @@ -// GENERATED from schema/flow.v{1,2,3}.schema.json by scripts/generate.mjs — do not edit. +// GENERATED from schema/flow.v{1,2,3,4}.schema.json by scripts/generate.mjs — do not edit. // Run `pnpm gen` after changing a schema; CI fails on drift. export const flowV1Schema = { @@ -1427,5 +1427,548 @@ export const flowV3Schema = { } } as const; +export const flowV4Schema = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": [ + "schema_version", + "id", + "name", + "entry", + "nodes" + ], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/Variable" + } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/Node" + } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "required": { + "description": "Whether a call must supply a non-empty value.", + "type": "boolean", + "default": false + }, + "default": { + "description": "The value used when a call supplies none.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { + "title": "Text", + "type": "string" + }, + { + "title": "Audio", + "type": "object", + "required": [ + "audio" + ], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": [ + "beep", + "none" + ] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": [ + "open", + "close" + ], + "properties": { + "open": { + "type": "string" + }, + "close": { + "type": "string" + } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "tue": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "wed": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "thu": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "fri": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "sat": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "sun": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": [ + "date" + ], + "properties": { + "date": { + "description": "\"YYYY-MM-DD\" in the flow's timezone.", + "type": "string" + }, + "closed": { + "description": "Closed all day regardless of ranges.", + "type": "boolean", + "default": false + }, + "ranges": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { + "$ref": "#/$defs/GreetingNode" + }, + { + "$ref": "#/$defs/HoursNode" + }, + { + "$ref": "#/$defs/MenuNode" + }, + { + "$ref": "#/$defs/RingNode" + }, + { + "$ref": "#/$defs/MessageNode" + }, + { + "$ref": "#/$defs/TransferNode" + }, + { + "$ref": "#/$defs/HangupNode" + }, + { + "$ref": "#/$defs/BookNode" + } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": [ + "kind", + "prompt" + ], + "properties": { + "kind": { + "const": "greeting" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": [ + "kind", + "schedule", + "timezone" + ], + "properties": { + "kind": { + "const": "hours" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "schedule": { + "$ref": "#/$defs/WeeklySchedule" + }, + "timezone": { + "description": "IANA zone (America/New_York). Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "type": "array", + "items": { + "$ref": "#/$defs/HoursException" + } + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": [ + "kind", + "prompt", + "options" + ], + "properties": { + "kind": { + "const": "menu" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "retries": { + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": [ + "kind", + "timeout_secs" + ], + "properties": { + "kind": { + "const": "ring" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "timeout_secs": { + "type": "integer", + "minimum": 0 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": [ + "kind", + "prompt" + ], + "properties": { + "kind": { + "const": "message" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "max_secs": { + "type": "integer", + "minimum": 0, + "default": 120 + }, + "tone": { + "allOf": [ + { + "$ref": "#/$defs/MessageTone" + } + ], + "default": "beep" + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": [ + "kind", + "target" + ], + "properties": { + "kind": { + "const": "transfer" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "target": { + "type": "string" + }, + "whisper": { + "$ref": "#/$defs/Prompt" + }, + "timeout_secs": { + "type": "integer", + "minimum": 5, + "maximum": 120 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": [ + "kind" + ], + "properties": { + "kind": { + "const": "hangup" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": [ + "kind", + "prompt", + "confirm_prompt", + "schedule", + "timezone", + "duration_mins" + ], + "properties": { + "kind": { + "const": "book" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "confirm_prompt": { + "$ref": "#/$defs/Prompt" + }, + "schedule": { + "$ref": "#/$defs/WeeklySchedule" + }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { + "$ref": "#/$defs/HoursException" + } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + } + } +} as const; + /** Newest supported version's schema. */ -export default flowV3Schema; +export default flowV4Schema; diff --git a/packages/flow-schema/src/index.ts b/packages/flow-schema/src/index.ts index 4c7e3dd..965d8f4 100644 --- a/packages/flow-schema/src/index.ts +++ b/packages/flow-schema/src/index.ts @@ -21,14 +21,14 @@ // which crashes code-gen-disallowed runtimes (Cloudflare Workers) at // import time. It lives behind the `@wavekat/flow-schema/structure` // subpath so this barrel stays Ajv-free and safe to bundle on the edge. -import { flowV1Schema, flowV2Schema, flowV3Schema } from './generated/schema.js'; +import { flowV1Schema, flowV2Schema, flowV3Schema, flowV4Schema } from './generated/schema.js'; // Model: generated types + hand-written constants & helpers. export * from './model.js'; // The `book` component: its bounds, and the vocabulary a frozen-audio // device speaks a time with. export * from './book.js'; -export { flowV1Schema, flowV2Schema, flowV3Schema }; +export { flowV1Schema, flowV2Schema, flowV3Schema, flowV4Schema }; // Structural diff between two flows (authoring-only, TS-only — like mutate.ts). export type { FieldChange, FlowDiff, FlowDiffStatus, NodeDiff } from './diff.js'; diff --git a/packages/flow-schema/src/model.ts b/packages/flow-schema/src/model.ts index fa417a2..f6f7ef1 100644 --- a/packages/flow-schema/src/model.ts +++ b/packages/flow-schema/src/model.ts @@ -27,6 +27,7 @@ export type { RingNode, TimeRange, TransferNode, + Variable, WeeklySchedule, } from './generated/model.js'; @@ -52,13 +53,13 @@ export type Component = Node; /** Schema versions this validator understands. Twin: `lib.rs` * `SUPPORTED_SCHEMA_VERSIONS`. */ -export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3]; +export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3, 4]; /** The newest version this build authors — what a new document should * declare. Reading stays broad ({@link SUPPORTED_SCHEMA_VERSIONS}); * writing is deliberately one number. Twin: `lib.rs` * `CURRENT_SCHEMA_VERSION`. */ -export const CURRENT_SCHEMA_VERSION = 3; +export const CURRENT_SCHEMA_VERSION = 4; /** The shortest and longest a screened transfer may ring the person's * phone, in seconds. Twin: `validate.rs` `MIN_TRANSFER_TIMEOUT_SECS` / @@ -70,6 +71,10 @@ export const MAX_TRANSFER_TIMEOUT_SECS = 120; * a `transfer`. Twin: `validate.rs` `TRANSFER_FIELDS_MIN_SCHEMA_VERSION`. */ export const TRANSFER_FIELDS_MIN_SCHEMA_VERSION = 3; +/** The oldest `schema_version` that may declare `variables`. Twin: + * `validate.rs` `VARIABLES_MIN_SCHEMA_VERSION`. */ +export const VARIABLES_MIN_SCHEMA_VERSION = 4; + /** Longest a spoken (text) prompt may be — see `validate.ts`. Twin: * `validate.rs` `MAX_PROMPT_CHARS`. */ export const MAX_PROMPT_CHARS = 2000; @@ -152,6 +157,7 @@ export const KIND_MIN_SCHEMA_VERSION: Record = { export function requiredSchemaVersion(flow: Flow): number { return Math.max( 1, + flow.variables !== undefined ? VARIABLES_MIN_SCHEMA_VERSION : 1, ...Object.values(flow.nodes).map((node) => Math.max( KIND_MIN_SCHEMA_VERSION[node.kind], diff --git a/packages/flow-schema/src/parse.ts b/packages/flow-schema/src/parse.ts index ac8b787..34792c4 100644 --- a/packages/flow-schema/src/parse.ts +++ b/packages/flow-schema/src/parse.ts @@ -24,6 +24,7 @@ import type { MessageTone, Prompt, TimeRange, + Variable, Weekday, WeeklySchedule, } from './model.js'; @@ -190,6 +191,50 @@ function warnUnknownFields( } } +/** The `variables` map: each entry declares one value filled in per call. */ +function decodeVariables( + value: unknown, + issues: Issue[], +): Record | undefined { + if (!isMap(value)) { + error(issues, 'expected_map', '"variables" must be a mapping of variable names', value); + return undefined; + } + const out: Record = {}; + for (const [name, field] of fieldsOf(value, 'variables', issues)) { + const context = `variable "${name}"`; + if (!isMap(field.value)) { + error(issues, 'expected_map', `${context} must be a mapping`, field.value); + continue; + } + const entry = fieldsOf(field.value, context, issues); + warnUnknownFields(entry, ['description', 'required', 'default', 'max_len'], context, issues); + const variable: Variable = {}; + const description = entry.get('description'); + if (description) { + const v = asString(description.value, `${context} description`, issues); + if (v !== undefined) variable.description = v; + } + const isRequired = entry.get('required'); + if (isRequired) { + const v = asBool(isRequired.value, `${context} required`, issues); + if (v !== undefined) variable.required = v; + } + const dflt = entry.get('default'); + if (dflt) { + const v = asString(dflt.value, `${context} default`, issues); + if (v !== undefined) variable.default = v; + } + const maxLen = entry.get('max_len'); + if (maxLen) { + const v = asU32(maxLen.value, `${context} max_len`, issues); + if (v !== undefined) variable.max_len = v; + } + out[name] = variable; + } + return out; +} + function decodePrompt(value: unknown, label: string, issues: Issue[]): Prompt | undefined { if (isScalar(value) && typeof value.value === 'string') return value.value; if (isMap(value)) { @@ -640,7 +685,7 @@ export function parseFlow(source: string): ParseResult { const fields = fieldsOf(root, 'flow document', issues); warnUnknownFields( fields, - ['schema_version', 'id', 'name', 'version', 'note', 'entry', 'nodes', 'ui'], + ['schema_version', 'id', 'name', 'version', 'note', 'variables', 'entry', 'nodes', 'ui'], 'flow document', issues, ); @@ -656,6 +701,8 @@ export function parseFlow(source: string): ParseResult { const version = versionField ? asU32(versionField.value, 'version', issues) : 1; const noteField = fields.get('note'); const note = noteField ? asString(noteField.value, 'note', issues) : undefined; + const variablesField = fields.get('variables'); + const variables = variablesField ? decodeVariables(variablesField.value, issues) : undefined; const entryField = required(fields, 'entry', 'flow document', issues, root); const entry = entryField && asString(entryField.value, 'entry', issues); @@ -704,6 +751,7 @@ export function parseFlow(source: string): ParseResult { name, version, ...(note === undefined ? {} : { note }), + ...(variables === undefined ? {} : { variables }), entry, nodes, ui: ui as Flow['ui'], diff --git a/packages/flow-schema/src/serialize.ts b/packages/flow-schema/src/serialize.ts index 2a3f6ef..4177c34 100644 --- a/packages/flow-schema/src/serialize.ts +++ b/packages/flow-schema/src/serialize.ts @@ -8,13 +8,13 @@ // are required, and their defaults all come from there, so a schema change // needs no change here. -import { flowV3Schema } from './generated/schema.js'; +import { flowV4Schema } from './generated/schema.js'; import type { Flow } from './model.js'; type Json = null | boolean | number | string | Json[] | { [key: string]: Json }; type Schema = { [key: string]: unknown }; -const ROOT = flowV3Schema as unknown as Schema; +const ROOT = flowV4Schema as unknown as Schema; /** Follow `$ref` (and a single-entry `allOf`, the schema's way of putting * a default next to a ref) to the schema that describes a value. */ diff --git a/packages/flow-schema/src/structure.ts b/packages/flow-schema/src/structure.ts index 9c12d7f..019f69e 100644 --- a/packages/flow-schema/src/structure.ts +++ b/packages/flow-schema/src/structure.ts @@ -18,7 +18,7 @@ import { Ajv2020 } from 'ajv/dist/2020.js'; import type { ErrorObject, ValidateFunction } from 'ajv'; -import { flowV1Schema, flowV2Schema, flowV3Schema } from './generated/schema.js'; +import { flowV1Schema, flowV2Schema, flowV3Schema, flowV4Schema } from './generated/schema.js'; const ajv = new Ajv2020({ allErrors: true, strict: false }); @@ -33,6 +33,7 @@ const validators = new Map([ [1, ajv.compile(flowV1Schema)], [2, ajv.compile(flowV2Schema)], [3, ajv.compile(flowV3Schema)], + [4, ajv.compile(flowV4Schema)], ]); export type StructuralResult = diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 65e5681..01cadf3 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -20,6 +20,7 @@ import { MIN_TRANSFER_TIMEOUT_SECS, SUPPORTED_SCHEMA_VERSIONS, TRANSFER_FIELDS_MIN_SCHEMA_VERSION, + VARIABLES_MIN_SCHEMA_VERSION, VALID_DIGITS, isScreenedTransfer, isTerminal, @@ -67,6 +68,21 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { }); } + // Flow-level, so it carries no node. Same code as a transfer field on an + // older document: the field needs a newer version than the one declared. + if (flow.variables !== undefined && flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) { + issues.push({ + severity: 'error', + code: 'field_requires_newer_schema', + message: `variables needs schema_version ${VARIABLES_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, + params: { + field: 'variables', + required: VARIABLES_MIN_SCHEMA_VERSION, + declared: flow.schema_version, + }, + }); + } + const nodeIds = Object.keys(flow.nodes); if (nodeIds.length === 0) { issues.push({ severity: 'error', code: 'empty_flow', message: 'flow has no nodes' }); diff --git a/schema/README.md b/schema/README.md index 7ee4ef0..a7b77e6 100644 --- a/schema/README.md +++ b/schema/README.md @@ -10,6 +10,7 @@ version it declares, and no other. | `flow.v1.schema.json` | `schema_version: 1` | the original seven components | | `flow.v2.schema.json` | `schema_version: 2` | `book` — appointment booking over the phone | | `flow.v3.schema.json` | `schema_version: 3` | `transfer` gains `whisper` and `timeout_secs` — a screened transfer | +| `flow.v4.schema.json` | `schema_version: 4` | top-level `variables` — details a caller fills in per call | Version 2 is version 1 plus one component: every v1 document is a valid v2 document once its `schema_version` is bumped, and nothing else changed. @@ -17,6 +18,10 @@ Version 3 is version 2 plus two optional fields on `transfer`: every v2 document is a valid v3 document once its `schema_version` is bumped. The bump is for what the fields do, not for their shape. A reader that ignored `whisper` would hand the call over without calling the target first. +Version 4 is version 3 plus one optional top-level field, `variables`: every +v3 document is a valid v4 document once its `schema_version` is bumped. The +bump is again for what the field does: a reader that ignored it would speak +the `{{name}}` placeholders as written. Everything downstream is generated or checked against these files: diff --git a/schema/flow.v4.schema.json b/schema/flow.v4.schema.json new file mode 100644 index 0000000..b7c0982 --- /dev/null +++ b/schema/flow.v4.schema.json @@ -0,0 +1,307 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": ["schema_version", "id", "name", "entry", "nodes"], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Variable" } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Node" } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "required": { + "description": "Whether a call must supply a non-empty value.", + "type": "boolean", + "default": false + }, + "default": { + "description": "The value used when a call supplies none.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { "title": "Text", "type": "string" }, + { + "title": "Audio", + "type": "object", + "required": ["audio"], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": ["beep", "none"] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": ["open", "close"], + "properties": { + "open": { "type": "string" }, + "close": { "type": "string" } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "tue": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "wed": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "thu": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "fri": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sat": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sun": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": ["date"], + "properties": { + "date": { "description": "\"YYYY-MM-DD\" in the flow's timezone.", "type": "string" }, + "closed": { "description": "Closed all day regardless of ranges.", "type": "boolean", "default": false }, + "ranges": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { "$ref": "#/$defs/GreetingNode" }, + { "$ref": "#/$defs/HoursNode" }, + { "$ref": "#/$defs/MenuNode" }, + { "$ref": "#/$defs/RingNode" }, + { "$ref": "#/$defs/MessageNode" }, + { "$ref": "#/$defs/TransferNode" }, + { "$ref": "#/$defs/HangupNode" }, + { "$ref": "#/$defs/BookNode" } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "greeting" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": ["kind", "schedule", "timezone"], + "properties": { + "kind": { "const": "hours" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { "description": "IANA zone (America/New_York). Validated to resolve at load.", "type": "string" }, + "exceptions": { "type": "array", "items": { "$ref": "#/$defs/HoursException" } }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": ["kind", "prompt", "options"], + "properties": { + "kind": { "const": "menu" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "retries": { "type": "integer", "minimum": 0, "default": 1 }, + "timeout_secs": { "type": "integer", "minimum": 0, "default": 5 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": ["kind", "timeout_secs"], + "properties": { + "kind": { "const": "ring" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "timeout_secs": { "type": "integer", "minimum": 0 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "message" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "max_secs": { "type": "integer", "minimum": 0, "default": 120 }, + "tone": { "allOf": [{ "$ref": "#/$defs/MessageTone" }], "default": "beep" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": ["kind", "target"], + "properties": { + "kind": { "const": "transfer" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "target": { "type": "string" }, + "whisper": { "$ref": "#/$defs/Prompt" }, + "timeout_secs": { "type": "integer", "minimum": 5, "maximum": 120 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": ["kind"], + "properties": { + "kind": { "const": "hangup" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": ["kind", "prompt", "confirm_prompt", "schedule", "timezone", "duration_mins"], + "properties": { + "kind": { "const": "book" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "confirm_prompt": { "$ref": "#/$defs/Prompt" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { "$ref": "#/$defs/HoursException" } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { "$ref": "#/$defs/Exits" } + } + } + } +} From d2f01c12e3e5975e9fa2817f8afe853adb167c47 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:32:15 +1300 Subject: [PATCH 02/13] fix: treat empty variables as none --- .../v3/valid/empty-variables.expected.json | 5 +++ conformance/v3/valid/empty-variables.yaml | 8 ++++ crates/wavekat-flow/src/validate.rs | 44 ++++++++++++++++++- packages/flow-schema/src/model.ts | 7 ++- packages/flow-schema/src/parse.ts | 4 +- packages/flow-schema/src/validate.ts | 3 +- packages/flow-schema/test/model.test.ts | 10 +++++ packages/flow-schema/test/parse.test.ts | 37 ++++++++++++++++ 8 files changed, 113 insertions(+), 5 deletions(-) create mode 100644 conformance/v3/valid/empty-variables.expected.json create mode 100644 conformance/v3/valid/empty-variables.yaml diff --git a/conformance/v3/valid/empty-variables.expected.json b/conformance/v3/valid/empty-variables.expected.json new file mode 100644 index 0000000..126f8a6 --- /dev/null +++ b/conformance/v3/valid/empty-variables.expected.json @@ -0,0 +1,5 @@ +{ + "description": "An empty `variables` map declares nothing, so it is the same as no map: a version 3 document may carry it. Only a non-empty map needs version 4.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v3/valid/empty-variables.yaml b/conformance/v3/valid/empty-variables.yaml new file mode 100644 index 0000000..529f00d --- /dev/null +++ b/conformance/v3/valid/empty-variables.yaml @@ -0,0 +1,8 @@ +schema_version: 3 +id: flow_empty_vars +name: Empty variables in version 3 +entry: bye +variables: {} +nodes: + bye: + kind: hangup diff --git a/crates/wavekat-flow/src/validate.rs b/crates/wavekat-flow/src/validate.rs index 24871e7..f18da45 100644 --- a/crates/wavekat-flow/src/validate.rs +++ b/crates/wavekat-flow/src/validate.rs @@ -133,8 +133,12 @@ pub enum ValidationError { declared: i64, }, - #[error("variables needs schema_version {required} (this document declares {declared})")] - VariablesRequireNewerSchema { required: u32, declared: i64 }, + #[error("{field} needs schema_version {required} (this document declares {declared})")] + VariablesRequireNewerSchema { + field: &'static str, + required: u32, + declared: i64, + }, #[error("transfer node {node:?} sets timeout_secs but has no whisper to screen with")] TimeoutWithoutWhisper { node: NodeId }, @@ -262,6 +266,7 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { if !flow.variables.is_empty() && flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { errs.push(ValidationError::VariablesRequireNewerSchema { + field: "variables", required: VARIABLES_MIN_SCHEMA_VERSION, declared: flow.schema_version, }); @@ -1544,4 +1549,39 @@ nodes: assert_eq!(validate(&parse(&src)), Ok(())); assert_eq!(validate_outbound(&parse(&src)), Ok(())); } + // ── flow variables ─────────────────────────────────────────────────── + const WITH_VARIABLES: &str = "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n q: { required: true }\nnodes:\n a:\n kind: hangup\n prompt: \"{{q}}\"\n"; + + #[test] + fn variables_need_v4() { + let flow = parse(WITH_VARIABLES); + assert_eq!(required_schema_version(&flow), 4); + assert_eq!(validate(&flow), Ok(())); + } + + #[test] + fn variables_in_v3_are_refused() { + let src = WITH_VARIABLES.replace("schema_version: 4", "schema_version: 3"); + let errs = validate(&parse(&src)).unwrap_err(); + assert_eq!( + errs, + vec![ValidationError::VariablesRequireNewerSchema { + field: "variables", + required: 4, + declared: 3, + }] + ); + assert_eq!(errs[0].code(), "field_requires_newer_schema"); + } + + #[test] + fn empty_variables_are_no_variables() { + let src = WITH_VARIABLES + .replace("schema_version: 4", "schema_version: 3") + .replace(" q: { required: true }\n", "") + .replace("variables:\n", "variables: {}\n"); + let flow = parse(&src); + assert_eq!(required_schema_version(&flow), 1); + assert_eq!(validate(&flow), Ok(())); + } } diff --git a/packages/flow-schema/src/model.ts b/packages/flow-schema/src/model.ts index f6f7ef1..1175668 100644 --- a/packages/flow-schema/src/model.ts +++ b/packages/flow-schema/src/model.ts @@ -138,6 +138,11 @@ export const KIND_MIN_SCHEMA_VERSION: Record = { book: 2, }; +/** An empty `variables` map declares nothing, so it is the same as none. */ +export function hasVariables(flow: Flow): boolean { + return flow.variables !== undefined && Object.keys(flow.variables).length > 0; +} + /** * The lowest `schema_version` that can carry this document's components — * the version it *needs*, as against the one it declares. @@ -157,7 +162,7 @@ export const KIND_MIN_SCHEMA_VERSION: Record = { export function requiredSchemaVersion(flow: Flow): number { return Math.max( 1, - flow.variables !== undefined ? VARIABLES_MIN_SCHEMA_VERSION : 1, + hasVariables(flow) ? VARIABLES_MIN_SCHEMA_VERSION : 1, ...Object.values(flow.nodes).map((node) => Math.max( KIND_MIN_SCHEMA_VERSION[node.kind], diff --git a/packages/flow-schema/src/parse.ts b/packages/flow-schema/src/parse.ts index 34792c4..f1ee2cb 100644 --- a/packages/flow-schema/src/parse.ts +++ b/packages/flow-schema/src/parse.ts @@ -751,7 +751,9 @@ export function parseFlow(source: string): ParseResult { name, version, ...(note === undefined ? {} : { note }), - ...(variables === undefined ? {} : { variables }), + // An empty map declares nothing; drop it so it round-trips (the Rust + // twin skips an empty map when writing). + ...(variables === undefined || Object.keys(variables).length === 0 ? {} : { variables }), entry, nodes, ui: ui as Flow['ui'], diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 01cadf3..37e0161 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -21,6 +21,7 @@ import { SUPPORTED_SCHEMA_VERSIONS, TRANSFER_FIELDS_MIN_SCHEMA_VERSION, VARIABLES_MIN_SCHEMA_VERSION, + hasVariables, VALID_DIGITS, isScreenedTransfer, isTerminal, @@ -70,7 +71,7 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // Flow-level, so it carries no node. Same code as a transfer field on an // older document: the field needs a newer version than the one declared. - if (flow.variables !== undefined && flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) { + if (hasVariables(flow) && flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) { issues.push({ severity: 'error', code: 'field_requires_newer_schema', diff --git a/packages/flow-schema/test/model.test.ts b/packages/flow-schema/test/model.test.ts index 9d0f02e..56a778d 100644 --- a/packages/flow-schema/test/model.test.ts +++ b/packages/flow-schema/test/model.test.ts @@ -47,6 +47,16 @@ nodes: `; describe('requiredSchemaVersion', () => { + it('is 4 once the document declares variables, and 1 when the map is empty', () => { + const flow = parsed(V1_ONLY); + flow.variables = { q: { required: true } }; + expect(requiredSchemaVersion(flow)).toBe(4); + flow.variables = {}; + expect(requiredSchemaVersion(flow)).toBe(1); + delete flow.variables; + expect(requiredSchemaVersion(flow)).toBe(1); + }); + it('is 1 for a document built only from components v1 had', () => { expect(requiredSchemaVersion(parsed(V1_ONLY))).toBe(1); }); diff --git a/packages/flow-schema/test/parse.test.ts b/packages/flow-schema/test/parse.test.ts index f66d4f8..a9f29f4 100644 --- a/packages/flow-schema/test/parse.test.ts +++ b/packages/flow-schema/test/parse.test.ts @@ -414,3 +414,40 @@ describe('known fields follow the schema', () => { } }); }); + +describe('parseFlow variables', () => { + const doc = (variables: string) => + `schema_version: 4\nid: f\nname: F\nentry: a\nvariables:${variables}\nnodes:\n a:\n kind: hangup\n`; + const codes = (source: string) => + parseFlow(source) + .issues.filter((i) => i.severity === 'error') + .map((i) => i.code); + + it('decodes every field of a variable', () => { + const { flow, issues } = parseFlow( + doc('\n q: { description: Ask, required: true, default: hi, max_len: 30 }'), + ); + expect(issues).toEqual([]); + expect(flow?.variables).toEqual({ + q: { description: 'Ask', required: true, default: 'hi', max_len: 30 }, + }); + }); + + it('refuses variables that is not a mapping', () => { + const r = parseFlow(doc(' [a, b]')); + expect(r.flow).toBeNull(); + expect(codes(doc(' [a, b]'))).toEqual(['expected_map']); + }); + + it('refuses an entry that is not a mapping', () => { + expect(codes(doc('\n q: nope'))).toEqual(['expected_map']); + }); + + it('refuses a required that is not a boolean', () => { + expect(codes(doc('\n q: { required: "yes" }'))).toEqual(['expected_boolean']); + }); + + it('refuses a max_len that is not an integer', () => { + expect(codes(doc('\n q: { max_len: lots }'))).toEqual(['expected_integer']); + }); +}); From 476a2bb7884d6cb9d3c20dc2a5b2e7e9fe4068dc Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:39:49 +1300 Subject: [PATCH 03/13] feat: require variable defaults and prompt templates --- .../canonical/prompt-template.canonical.yaml | 10 +++ .../canonical/prompt-template.expected.json | 4 ++ .../canonical/prompt-template.input.yaml | 10 +++ .../canonical/variables.canonical.yaml | 2 +- conformance/canonical/variables.expected.json | 2 +- conformance/canonical/variables.input.yaml | 4 +- .../v3/invalid/template-in-v3.expected.json | 5 ++ conformance/v3/invalid/template-in-v3.yaml | 12 ++++ conformance/v3/invalid/variables-in-v3.yaml | 10 +-- .../variable-without-default.expected.json | 5 ++ .../v4/invalid/variable-without-default.yaml | 10 +++ conformance/v4/valid/ask-question.yaml | 10 +-- .../rendered-template-prompt.expected.json | 6 ++ .../v4/valid/rendered-template-prompt.yaml | 14 ++++ .../wavekat-flow/schema/flow.v4.schema.json | 12 ++-- crates/wavekat-flow/src/engine.rs | 3 + crates/wavekat-flow/src/model_ext.rs | 27 ++++++++ crates/wavekat-flow/src/validate.rs | 66 ++++++++++++++++++- crates/wavekat-flow/tests/canonical.rs | 1 + .../src/generated/flow.v4.schema.json | 12 ++-- packages/flow-schema/src/generated/model.ts | 12 ++-- packages/flow-schema/src/generated/schema.ts | 14 ++-- packages/flow-schema/src/model.ts | 15 +++++ packages/flow-schema/src/parse.ts | 35 +++++----- packages/flow-schema/src/validate.ts | 18 +++++ packages/flow-schema/test/model.test.ts | 12 +++- packages/flow-schema/test/parse.test.ts | 38 +++++++++-- schema/README.md | 2 +- schema/flow.v4.schema.json | 12 ++-- 29 files changed, 313 insertions(+), 70 deletions(-) create mode 100644 conformance/canonical/prompt-template.canonical.yaml create mode 100644 conformance/canonical/prompt-template.expected.json create mode 100644 conformance/canonical/prompt-template.input.yaml create mode 100644 conformance/v3/invalid/template-in-v3.expected.json create mode 100644 conformance/v3/invalid/template-in-v3.yaml create mode 100644 conformance/v4/invalid/variable-without-default.expected.json create mode 100644 conformance/v4/invalid/variable-without-default.yaml create mode 100644 conformance/v4/valid/rendered-template-prompt.expected.json create mode 100644 conformance/v4/valid/rendered-template-prompt.yaml diff --git a/conformance/canonical/prompt-template.canonical.yaml b/conformance/canonical/prompt-template.canonical.yaml new file mode 100644 index 0000000..615e1ae --- /dev/null +++ b/conformance/canonical/prompt-template.canonical.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_template_canon +name: Voiced with defaults +variables: + name: { default: there } +entry: ask +nodes: + ask: + kind: hangup + prompt: { audio: vprompt_abc123, transcript: Hi there, template: "Hi {{name}}" } diff --git a/conformance/canonical/prompt-template.expected.json b/conformance/canonical/prompt-template.expected.json new file mode 100644 index 0000000..bec01ec --- /dev/null +++ b/conformance/canonical/prompt-template.expected.json @@ -0,0 +1,4 @@ +{ + "description": "An audio prompt that keeps its `template` writes it after `transcript` (`audio`, `transcript`, `template`), the schema property order.", + "comments": 0 +} diff --git a/conformance/canonical/prompt-template.input.yaml b/conformance/canonical/prompt-template.input.yaml new file mode 100644 index 0000000..5fcf391 --- /dev/null +++ b/conformance/canonical/prompt-template.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +name: Voiced with defaults +id: flow_template_canon +entry: ask +variables: + name: { default: there } +nodes: + ask: + kind: hangup + prompt: { template: "Hi {{name}}", transcript: Hi there, audio: vprompt_abc123 } diff --git a/conformance/canonical/variables.canonical.yaml b/conformance/canonical/variables.canonical.yaml index 7f15b7c..8837d90 100644 --- a/conformance/canonical/variables.canonical.yaml +++ b/conformance/canonical/variables.canonical.yaml @@ -2,7 +2,7 @@ schema_version: 4 id: flow_vars_canon name: Ask a question variables: - question: { description: The question, required: true, max_len: 300 } + question: { description: The question, default: Ready?, max_len: 300 } note_to_self: { default: "" } entry: ask nodes: diff --git a/conformance/canonical/variables.expected.json b/conformance/canonical/variables.expected.json index d8edb18..4287f02 100644 --- a/conformance/canonical/variables.expected.json +++ b/conformance/canonical/variables.expected.json @@ -1,4 +1,4 @@ { - "description": "Top-level `variables` is written right after `note` and before `entry`, each variable in schema property order (`description`, `required`, `default`, `max_len`). A `required: false` and a `max_len: 200` equal their defaults and are dropped; an empty `default` is a value, not a default, so it stays.", + "description": "Top-level `variables` is written right after `note` and before `entry`, each variable in schema property order (`description`, `default`, `max_len`). A `max_len` equal to its default (200) is dropped; an empty `default` is a value, and it stays.", "comments": 1 } diff --git a/conformance/canonical/variables.input.yaml b/conformance/canonical/variables.input.yaml index 612091e..5b6950e 100644 --- a/conformance/canonical/variables.input.yaml +++ b/conformance/canonical/variables.input.yaml @@ -4,8 +4,8 @@ name: Ask a question id: flow_vars_canon entry: ask variables: - question: { max_len: 300, required: true, description: The question } - note_to_self: { default: "", required: false, max_len: 200 } + question: { max_len: 300, default: Ready?, description: The question } + note_to_self: { max_len: 200, default: "" } nodes: ask: kind: hangup diff --git a/conformance/v3/invalid/template-in-v3.expected.json b/conformance/v3/invalid/template-in-v3.expected.json new file mode 100644 index 0000000..6d0b0bd --- /dev/null +++ b/conformance/v3/invalid/template-in-v3.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A version 3 document may not give an audio prompt a `template`: an older engine would ignore it and play the clip with the defaults it was voiced from, so the field needs the version that has it.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["field_requires_newer_schema"] } +} diff --git a/conformance/v3/invalid/template-in-v3.yaml b/conformance/v3/invalid/template-in-v3.yaml new file mode 100644 index 0000000..33d4679 --- /dev/null +++ b/conformance/v3/invalid/template-in-v3.yaml @@ -0,0 +1,12 @@ +schema_version: 3 +id: flow_template_in_v3 +name: Template in a version 3 document +entry: ask +nodes: + ask: + kind: greeting + prompt: { audio: vprompt_abc123, template: "Hi {{name}}" } + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/conformance/v3/invalid/variables-in-v3.yaml b/conformance/v3/invalid/variables-in-v3.yaml index 303aa67..13e767e 100644 --- a/conformance/v3/invalid/variables-in-v3.yaml +++ b/conformance/v3/invalid/variables-in-v3.yaml @@ -4,11 +4,11 @@ name: Ask a question entry: ask variables: intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } - question: { description: The question, required: true, max_len: 300 } - option1: { description: Answer for key 1, required: true, max_len: 80 } - option2: { description: Answer for key 2, required: true, max_len: 80 } - option3: { description: Answer for key 3, max_len: 80 } - option4: { description: Answer for key 4, max_len: 80 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } nodes: ask: kind: menu diff --git a/conformance/v4/invalid/variable-without-default.expected.json b/conformance/v4/invalid/variable-without-default.expected.json new file mode 100644 index 0000000..d7c29f6 --- /dev/null +++ b/conformance/v4/invalid/variable-without-default.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Every variable declares a `default`, so a flow called with no values still plays. A variable without one is refused at the shape level; the default may be an empty string.", + "structurallyValid": false, + "semantic": { "ok": false, "errors": [] } +} diff --git a/conformance/v4/invalid/variable-without-default.yaml b/conformance/v4/invalid/variable-without-default.yaml new file mode 100644 index 0000000..4f579de --- /dev/null +++ b/conformance/v4/invalid/variable-without-default.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_var_no_default +name: Variable with no default +entry: bye +variables: + question: { description: The question, max_len: 300 } +nodes: + bye: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/v4/valid/ask-question.yaml b/conformance/v4/valid/ask-question.yaml index 193aa37..41dd236 100644 --- a/conformance/v4/valid/ask-question.yaml +++ b/conformance/v4/valid/ask-question.yaml @@ -4,11 +4,11 @@ name: Ask a question entry: ask variables: intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } - question: { description: The question, required: true, max_len: 300 } - option1: { description: Answer for key 1, required: true, max_len: 80 } - option2: { description: Answer for key 2, required: true, max_len: 80 } - option3: { description: Answer for key 3, max_len: 80 } - option4: { description: Answer for key 4, max_len: 80 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } nodes: ask: kind: menu diff --git a/conformance/v4/valid/rendered-template-prompt.expected.json b/conformance/v4/valid/rendered-template-prompt.expected.json new file mode 100644 index 0000000..d90b6fc --- /dev/null +++ b/conformance/v4/valid/rendered-template-prompt.expected.json @@ -0,0 +1,6 @@ +{ + "description": "An audio prompt may keep the `template` it was voiced from, so a call that overrides a variable can speak the filled text instead of the clip. The clip is a required asset as ever; `template` is advisory to a reader that does not fill (here it is plain text, not yet scanned).", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] }, + "requiredAssets": ["vprompt_abc123"] +} diff --git a/conformance/v4/valid/rendered-template-prompt.yaml b/conformance/v4/valid/rendered-template-prompt.yaml new file mode 100644 index 0000000..b412b12 --- /dev/null +++ b/conformance/v4/valid/rendered-template-prompt.yaml @@ -0,0 +1,14 @@ +schema_version: 4 +id: flow_rendered_template +name: A prompt voiced with its defaults +entry: ask +variables: + name: { description: Who is called, default: "there", max_len: 40 } +nodes: + ask: + kind: greeting + prompt: { audio: vprompt_abc123, template: "Hi {{name}}" } + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/crates/wavekat-flow/schema/flow.v4.schema.json b/crates/wavekat-flow/schema/flow.v4.schema.json index b7c0982..95b693a 100644 --- a/crates/wavekat-flow/schema/flow.v4.schema.json +++ b/crates/wavekat-flow/schema/flow.v4.schema.json @@ -51,18 +51,14 @@ "Variable": { "description": "One declared variable.", "type": "object", + "required": ["default"], "properties": { "description": { "description": "What the value is, shown to whoever fills it in.", "type": "string" }, - "required": { - "description": "Whether a call must supply a non-empty value.", - "type": "boolean", - "default": false - }, "default": { - "description": "The value used when a call supplies none.", + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", "type": "string" }, "max_len": { @@ -90,6 +86,10 @@ "transcript": { "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" } } } diff --git a/crates/wavekat-flow/src/engine.rs b/crates/wavekat-flow/src/engine.rs index dd1d234..681cce2 100644 --- a/crates/wavekat-flow/src/engine.rs +++ b/crates/wavekat-flow/src/engine.rs @@ -580,6 +580,7 @@ async fn run_book( fx.speak(&Prompt::Audio { audio: reference, transcript: None, + template: None, }) .await .map_err(EngineError::Effect)?; @@ -598,6 +599,7 @@ async fn run_book( fx.speak(&Prompt::Audio { audio: book::taken_ref(), transcript: None, + template: None, }) .await .map_err(EngineError::Effect)?; @@ -643,6 +645,7 @@ async fn collect_offer_choice( fx.speak(&Prompt::Audio { audio: reference, transcript: None, + template: None, }) .await .map_err(EngineError::Effect)?; diff --git a/crates/wavekat-flow/src/model_ext.rs b/crates/wavekat-flow/src/model_ext.rs index 63ffe08..1429d14 100644 --- a/crates/wavekat-flow/src/model_ext.rs +++ b/crates/wavekat-flow/src/model_ext.rs @@ -274,6 +274,16 @@ impl Prompt { Prompt::Audio { transcript, .. } => transcript.as_deref(), } } + + /// The `{{name}}` text an audio prompt was voiced from with its + /// variables' defaults, `None` for a text prompt or a plain clip. The + /// text itself is not scanned here. Twin: `model.ts` `promptTemplate`. + pub fn template(&self) -> Option<&str> { + match self { + Prompt::Text(_) => None, + Prompt::Audio { template, .. } => template.as_deref(), + } + } } impl Flow { @@ -372,10 +382,25 @@ nodes: let audio = Prompt::Audio { audio: "vprompt_ab12cd34".into(), transcript: Some("open eleven to ten".into()), + template: None, }; assert_eq!(audio.as_text(), None); } + #[test] + fn template_is_only_on_an_audio_prompt() { + assert_eq!(Prompt::Text("Hi {{name}}".into()).template(), None); + let plain: Prompt = serde_yaml_ng::from_str("{ audio: vprompt_ff00ee11 }").unwrap(); + assert_eq!(plain.template(), None); + let voiced: Prompt = + serde_yaml_ng::from_str("{ audio: vprompt_ff00ee11, template: \"Hi {{name}}\" }") + .unwrap(); + assert_eq!(voiced.template(), Some("Hi {{name}}")); + let yaml = serde_yaml_ng::to_string(&voiced).unwrap(); + let again: Prompt = serde_yaml_ng::from_str(&yaml).unwrap(); + assert_eq!(again.template(), Some("Hi {{name}}")); + } + #[test] fn transcript_is_the_spoken_words_regardless_of_voicing() { // Text prompt is its own transcript. @@ -386,6 +411,7 @@ nodes: let with_text = Prompt::Audio { audio: "vprompt_ab12cd34".into(), transcript: Some("open eleven to ten".into()), + template: None, }; assert_eq!(with_text.transcript(), Some("open eleven to ten")); @@ -393,6 +419,7 @@ nodes: let without_text = Prompt::Audio { audio: "vprompt_ff00ee11".into(), transcript: None, + template: None, }; assert_eq!(without_text.transcript(), None); } diff --git a/crates/wavekat-flow/src/validate.rs b/crates/wavekat-flow/src/validate.rs index f18da45..3c653e3 100644 --- a/crates/wavekat-flow/src/validate.rs +++ b/crates/wavekat-flow/src/validate.rs @@ -44,6 +44,10 @@ const TRANSFER_FIELDS_MIN_SCHEMA_VERSION: u32 = 3; /// `model.ts` `VARIABLES_MIN_SCHEMA_VERSION`. const VARIABLES_MIN_SCHEMA_VERSION: u32 = 4; +/// The oldest `schema_version` that may give an audio prompt a `template`. +/// Twin: `model.ts` `TEMPLATE_MIN_SCHEMA_VERSION`. +const TEMPLATE_MIN_SCHEMA_VERSION: u32 = 4; + /// One thing wrong with a flow document. Carries enough context (node id, /// exit name, offending value) for the editor to point at it. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] @@ -243,7 +247,14 @@ pub fn required_schema_version(flow: &Flow) -> i64 { } _ => 1, }; - kind_min_schema_version(node.kind()).max(fields) + let template = if node.prompts().iter().any(|p| p.template().is_some()) { + i64::from(TEMPLATE_MIN_SCHEMA_VERSION) + } else { + 1 + }; + kind_min_schema_version(node.kind()) + .max(fields) + .max(template) }) .max() .unwrap_or(1) @@ -286,6 +297,7 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { check_exits(id, node, flow, &mut errs); check_node(id, node, &mut errs); check_transfer_fields_version(id, node, flow.schema_version, &mut errs); + check_template_version(id, node, flow.schema_version, &mut errs); // A component the document's own version doesn't have. Checked // per node rather than once per flow so the editor points at the @@ -351,6 +363,27 @@ fn check_transfer_fields_version( } } +/// `template` on an audio prompt of a document older than the version that +/// has it. One error per node, whichever prompt carries it. +fn check_template_version( + id: &NodeId, + node: &Node, + declared: i64, + errs: &mut Vec, +) { + if declared >= i64::from(TEMPLATE_MIN_SCHEMA_VERSION) { + return; + } + if node.prompts().iter().any(|p| p.template().is_some()) { + errs.push(ValidationError::FieldRequiresNewerSchema { + node: id.clone(), + field: "template", + required: TEMPLATE_MIN_SCHEMA_VERSION, + declared, + }); + } +} + /// The kinds a flow may use on a call the app *places*, as of /// `schema_version` 2 and earlier: no person is standing by. Kept for /// compatibility; [`outbound_kinds`] is the version-aware list. Twin: @@ -1550,7 +1583,7 @@ nodes: assert_eq!(validate_outbound(&parse(&src)), Ok(())); } // ── flow variables ─────────────────────────────────────────────────── - const WITH_VARIABLES: &str = "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n q: { required: true }\nnodes:\n a:\n kind: hangup\n prompt: \"{{q}}\"\n"; + const WITH_VARIABLES: &str = "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n q: { default: hi }\nnodes:\n a:\n kind: hangup\n prompt: \"{{q}}\"\n"; #[test] fn variables_need_v4() { @@ -1578,10 +1611,37 @@ nodes: fn empty_variables_are_no_variables() { let src = WITH_VARIABLES .replace("schema_version: 4", "schema_version: 3") - .replace(" q: { required: true }\n", "") + .replace(" q: { default: hi }\n", "") .replace("variables:\n", "variables: {}\n"); let flow = parse(&src); assert_eq!(required_schema_version(&flow), 1); assert_eq!(validate(&flow), Ok(())); } + + const WITH_TEMPLATE: &str = "schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_abc123, template: \"Hi {{name}}\" }\n"; + + #[test] + fn template_needs_v4() { + let flow = parse(WITH_TEMPLATE); + assert_eq!(required_schema_version(&flow), 4); + assert_eq!(validate(&flow), Ok(())); + let plain = WITH_TEMPLATE.replace(", template: \"Hi {{name}}\"", ""); + assert_eq!(required_schema_version(&parse(&plain)), 1); + } + + #[test] + fn template_in_v3_is_refused() { + let src = WITH_TEMPLATE.replace("schema_version: 4", "schema_version: 3"); + let errs = validate(&parse(&src)).unwrap_err(); + assert_eq!( + errs, + vec![ValidationError::FieldRequiresNewerSchema { + node: "a".into(), + field: "template", + required: 4, + declared: 3, + }] + ); + assert_eq!(errs[0].code(), "field_requires_newer_schema"); + } } diff --git a/crates/wavekat-flow/tests/canonical.rs b/crates/wavekat-flow/tests/canonical.rs index 92dc629..7d9677d 100644 --- a/crates/wavekat-flow/tests/canonical.rs +++ b/crates/wavekat-flow/tests/canonical.rs @@ -153,6 +153,7 @@ fn voicing_through_prompt_slots() { *prompt = Prompt::Audio { audio: format!("vprompt_{n}"), transcript: Some(text.clone()), + template: None, }; n += 1; } diff --git a/packages/flow-schema/src/generated/flow.v4.schema.json b/packages/flow-schema/src/generated/flow.v4.schema.json index b7c0982..95b693a 100644 --- a/packages/flow-schema/src/generated/flow.v4.schema.json +++ b/packages/flow-schema/src/generated/flow.v4.schema.json @@ -51,18 +51,14 @@ "Variable": { "description": "One declared variable.", "type": "object", + "required": ["default"], "properties": { "description": { "description": "What the value is, shown to whoever fills it in.", "type": "string" }, - "required": { - "description": "Whether a call must supply a non-empty value.", - "type": "boolean", - "default": false - }, "default": { - "description": "The value used when a call supplies none.", + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", "type": "string" }, "max_len": { @@ -90,6 +86,10 @@ "transcript": { "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" } } } diff --git a/packages/flow-schema/src/generated/model.ts b/packages/flow-schema/src/generated/model.ts index 8922a0d..40edacc 100644 --- a/packages/flow-schema/src/generated/model.ts +++ b/packages/flow-schema/src/generated/model.ts @@ -72,13 +72,9 @@ export interface Variable { */ description?: string; /** - * Whether a call must supply a non-empty value. + * The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional. */ - required?: boolean; - /** - * The value used when a call supplies none. - */ - default?: string; + default: string; /** * Longest a value may be, in Unicode characters. */ @@ -107,6 +103,10 @@ export interface Audio { * The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text. */ transcript?: string; + /** + * The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip. + */ + template?: string; [k: string]: unknown; } /** diff --git a/packages/flow-schema/src/generated/schema.ts b/packages/flow-schema/src/generated/schema.ts index 43eea02..5afd508 100644 --- a/packages/flow-schema/src/generated/schema.ts +++ b/packages/flow-schema/src/generated/schema.ts @@ -1490,18 +1490,16 @@ export const flowV4Schema = { "Variable": { "description": "One declared variable.", "type": "object", + "required": [ + "default" + ], "properties": { "description": { "description": "What the value is, shown to whoever fills it in.", "type": "string" }, - "required": { - "description": "Whether a call must supply a non-empty value.", - "type": "boolean", - "default": false - }, "default": { - "description": "The value used when a call supplies none.", + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", "type": "string" }, "max_len": { @@ -1534,6 +1532,10 @@ export const flowV4Schema = { "transcript": { "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" } } } diff --git a/packages/flow-schema/src/model.ts b/packages/flow-schema/src/model.ts index 1175668..2dccbe8 100644 --- a/packages/flow-schema/src/model.ts +++ b/packages/flow-schema/src/model.ts @@ -138,6 +138,10 @@ export const KIND_MIN_SCHEMA_VERSION: Record = { book: 2, }; +/** The oldest `schema_version` that may give an audio prompt a `template`. + * Twin: `validate.rs` `TEMPLATE_MIN_SCHEMA_VERSION`. */ +export const TEMPLATE_MIN_SCHEMA_VERSION = 4; + /** An empty `variables` map declares nothing, so it is the same as none. */ export function hasVariables(flow: Flow): boolean { return flow.variables !== undefined && Object.keys(flow.variables).length > 0; @@ -166,6 +170,7 @@ export function requiredSchemaVersion(flow: Flow): number { ...Object.values(flow.nodes).map((node) => Math.max( KIND_MIN_SCHEMA_VERSION[node.kind], + nodePrompts(node).some((p) => promptTemplate(p) !== null) ? TEMPLATE_MIN_SCHEMA_VERSION : 1, node.kind === 'transfer' && (node.whisper !== undefined || node.timeout_secs !== undefined) ? TRANSFER_FIELDS_MIN_SCHEMA_VERSION : 1, @@ -286,6 +291,16 @@ export function promptTranscript(prompt: Prompt): string | null { return typeof prompt.transcript === 'string' ? prompt.transcript : null; } +/** + * The `{{name}}` text an audio prompt was voiced from with its variables' + * defaults, `null` for a text prompt or a plain clip. Not scanned here. + * Twin: `model_ext.rs` `Prompt::template`. + */ +export function promptTemplate(prompt: Prompt): string | null { + if (typeof prompt === 'string') return null; + return typeof prompt.template === 'string' ? prompt.template : null; +} + /** * A generated-clip ref is a `voice_prompts` id (`vprompt_`) — a clip the * platform produced and owns. Anything else in an `audio:` field is a ref the diff --git a/packages/flow-schema/src/parse.ts b/packages/flow-schema/src/parse.ts index f1ee2cb..e74633e 100644 --- a/packages/flow-schema/src/parse.ts +++ b/packages/flow-schema/src/parse.ts @@ -208,23 +208,16 @@ function decodeVariables( continue; } const entry = fieldsOf(field.value, context, issues); - warnUnknownFields(entry, ['description', 'required', 'default', 'max_len'], context, issues); - const variable: Variable = {}; + warnUnknownFields(entry, ['description', 'default', 'max_len'], context, issues); + const dflt = required(entry, 'default', context, issues, field.value); + const defaultValue = dflt && asString(dflt.value, `${context} default`, issues); + if (defaultValue === undefined) continue; + const variable: Variable = { default: defaultValue }; const description = entry.get('description'); if (description) { const v = asString(description.value, `${context} description`, issues); if (v !== undefined) variable.description = v; } - const isRequired = entry.get('required'); - if (isRequired) { - const v = asBool(isRequired.value, `${context} required`, issues); - if (v !== undefined) variable.required = v; - } - const dflt = entry.get('default'); - if (dflt) { - const v = asString(dflt.value, `${context} default`, issues); - if (v !== undefined) variable.default = v; - } const maxLen = entry.get('max_len'); if (maxLen) { const v = asU32(maxLen.value, `${context} max_len`, issues); @@ -242,15 +235,25 @@ function decodePrompt(value: unknown, label: string, issues: Issue[]): Prompt | // `transcript` is the words the clip speaks, carried for display and // traces (model `Audio.transcript`); advisory only — playback still uses // `audio`. Known here so it neither warns nor gets dropped on decode. - warnUnknownFields(fields, ['audio', 'transcript'], label, issues); + warnUnknownFields(fields, ['audio', 'transcript', 'template'], label, issues); const audio = fields.get('audio'); if (audio) { const ref = asString(audio.value, `${label} audio`, issues); if (ref === undefined) return undefined; + const out: { audio: string; transcript?: string; template?: string } = { audio: ref }; const transcriptField = fields.get('transcript'); - if (!transcriptField) return { audio: ref }; - const transcript = asString(transcriptField.value, `${label} transcript`, issues); - return transcript === undefined ? undefined : { audio: ref, transcript }; + if (transcriptField) { + const transcript = asString(transcriptField.value, `${label} transcript`, issues); + if (transcript === undefined) return undefined; + out.transcript = transcript; + } + const templateField = fields.get('template'); + if (templateField) { + const template = asString(templateField.value, `${label} template`, issues); + if (template === undefined) return undefined; + out.template = template; + } + return out; } } error(issues, 'bad_prompt', `${label} must be text or { audio: ref }`, value); diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 37e0161..ece86b1 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -20,11 +20,14 @@ import { MIN_TRANSFER_TIMEOUT_SECS, SUPPORTED_SCHEMA_VERSIONS, TRANSFER_FIELDS_MIN_SCHEMA_VERSION, + TEMPLATE_MIN_SCHEMA_VERSION, VARIABLES_MIN_SCHEMA_VERSION, hasVariables, VALID_DIGITS, isScreenedTransfer, isTerminal, + nodePrompts, + promptTemplate, promptText, requiredExits, } from './model.js'; @@ -101,6 +104,21 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { } for (const [id, node] of Object.entries(flow.nodes)) { + if ( + flow.schema_version < TEMPLATE_MIN_SCHEMA_VERSION && + nodePrompts(node).some((p) => promptTemplate(p) !== null) + ) { + issues.push({ + ...at(id), + code: 'field_requires_newer_schema', + message: `node "${id}" gives a prompt a template, which needs schema_version ${TEMPLATE_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, + params: { + field: 'template', + required: TEMPLATE_MIN_SCHEMA_VERSION, + declared: flow.schema_version, + }, + }); + } const exits = node.exits ?? {}; // Exit keys must be exactly the set the component defines, and // every target must exist. diff --git a/packages/flow-schema/test/model.test.ts b/packages/flow-schema/test/model.test.ts index 56a778d..c9600c4 100644 --- a/packages/flow-schema/test/model.test.ts +++ b/packages/flow-schema/test/model.test.ts @@ -47,9 +47,19 @@ nodes: `; describe('requiredSchemaVersion', () => { + it('is 4 for an audio prompt that keeps a template', () => { + const flow = parsed(V1_ONLY); + const bye = flow.nodes.bye; + if (bye?.kind !== 'hangup') throw new Error('fixture'); + bye.prompt = { audio: 'vprompt_abc123', template: 'Hi {{name}}' }; + expect(requiredSchemaVersion(flow)).toBe(4); + bye.prompt = { audio: 'vprompt_abc123' }; + expect(requiredSchemaVersion(flow)).toBe(1); + }); + it('is 4 once the document declares variables, and 1 when the map is empty', () => { const flow = parsed(V1_ONLY); - flow.variables = { q: { required: true } }; + flow.variables = { q: { default: 'hi' } }; expect(requiredSchemaVersion(flow)).toBe(4); flow.variables = {}; expect(requiredSchemaVersion(flow)).toBe(1); diff --git a/packages/flow-schema/test/parse.test.ts b/packages/flow-schema/test/parse.test.ts index a9f29f4..78d37de 100644 --- a/packages/flow-schema/test/parse.test.ts +++ b/packages/flow-schema/test/parse.test.ts @@ -425,11 +425,11 @@ describe('parseFlow variables', () => { it('decodes every field of a variable', () => { const { flow, issues } = parseFlow( - doc('\n q: { description: Ask, required: true, default: hi, max_len: 30 }'), + doc('\n q: { description: Ask, default: hi, max_len: 30 }'), ); expect(issues).toEqual([]); expect(flow?.variables).toEqual({ - q: { description: 'Ask', required: true, default: 'hi', max_len: 30 }, + q: { description: 'Ask', default: 'hi', max_len: 30 }, }); }); @@ -443,11 +443,39 @@ describe('parseFlow variables', () => { expect(codes(doc('\n q: nope'))).toEqual(['expected_map']); }); - it('refuses a required that is not a boolean', () => { - expect(codes(doc('\n q: { required: "yes" }'))).toEqual(['expected_boolean']); + it('refuses a variable with no default', () => { + expect(codes(doc('\n q: { max_len: 30 }'))).toEqual(['missing_field']); + }); + + it('refuses a default that is not text', () => { + expect(codes(doc('\n q: { default: [a] }'))).toEqual(['expected_string']); + }); + + it('accepts an empty default', () => { + expect(parseFlow(doc('\n q: { default: "" }')).flow?.variables).toEqual({ q: { default: '' } }); }); it('refuses a max_len that is not an integer', () => { - expect(codes(doc('\n q: { max_len: lots }'))).toEqual(['expected_integer']); + expect(codes(doc('\n q: { default: x, max_len: lots }'))).toEqual(['expected_integer']); + }); +}); + +describe('parseFlow prompt template', () => { + const doc = (prompt: string) => + `schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: ${prompt}\n`; + + it('keeps the template after the transcript', () => { + const { flow, issues } = parseFlow( + doc('{ audio: vprompt_abc123, transcript: Hi there, template: "Hi {{name}}" }'), + ); + expect(issues).toEqual([]); + expect(flow?.nodes.a).toMatchObject({ + prompt: { audio: 'vprompt_abc123', transcript: 'Hi there', template: 'Hi {{name}}' }, + }); + }); + + it('refuses a template that is not text', () => { + const r = parseFlow(doc('{ audio: vprompt_abc123, template: [a] }')); + expect(r.issues.map((i) => i.code)).toContain('expected_string'); }); }); diff --git a/schema/README.md b/schema/README.md index a7b77e6..6e477a3 100644 --- a/schema/README.md +++ b/schema/README.md @@ -10,7 +10,7 @@ version it declares, and no other. | `flow.v1.schema.json` | `schema_version: 1` | the original seven components | | `flow.v2.schema.json` | `schema_version: 2` | `book` — appointment booking over the phone | | `flow.v3.schema.json` | `schema_version: 3` | `transfer` gains `whisper` and `timeout_secs` — a screened transfer | -| `flow.v4.schema.json` | `schema_version: 4` | top-level `variables` — details a caller fills in per call | +| `flow.v4.schema.json` | `schema_version: 4` | top-level `variables` (each with a required `default`) — details a caller fills in per call; an audio prompt may keep its `template` | Version 2 is version 1 plus one component: every v1 document is a valid v2 document once its `schema_version` is bumped, and nothing else changed. diff --git a/schema/flow.v4.schema.json b/schema/flow.v4.schema.json index b7c0982..95b693a 100644 --- a/schema/flow.v4.schema.json +++ b/schema/flow.v4.schema.json @@ -51,18 +51,14 @@ "Variable": { "description": "One declared variable.", "type": "object", + "required": ["default"], "properties": { "description": { "description": "What the value is, shown to whoever fills it in.", "type": "string" }, - "required": { - "description": "Whether a call must supply a non-empty value.", - "type": "boolean", - "default": false - }, "default": { - "description": "The value used when a call supplies none.", + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", "type": "string" }, "max_len": { @@ -90,6 +86,10 @@ "transcript": { "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" } } } From f05992fd25c3d6cb916544607af451571cc6e56e Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:44:40 +1300 Subject: [PATCH 04/13] feat: validate flow placeholders --- .../v3/valid/braces-in-prompt.expected.json | 5 + conformance/v3/valid/braces-in-prompt.yaml | 12 + ...aceholder-in-transfer-target.expected.json | 5 + .../placeholder-in-transfer-target.yaml | 10 + .../v4/invalid/unknown-variable.expected.json | 5 + conformance/v4/invalid/unknown-variable.yaml | 14 + crates/wavekat-flow/src/lib.rs | 1 + crates/wavekat-flow/src/validate.rs | 251 +++++++++++++++++- crates/wavekat-flow/src/vars.rs | 215 +++++++++++++++ packages/flow-schema/src/index.ts | 10 + packages/flow-schema/src/model.ts | 4 + packages/flow-schema/src/validate.ts | 172 +++++++++++- packages/flow-schema/src/vars.ts | 107 ++++++++ packages/flow-schema/test/vars.test.ts | 116 ++++++++ 14 files changed, 925 insertions(+), 2 deletions(-) create mode 100644 conformance/v3/valid/braces-in-prompt.expected.json create mode 100644 conformance/v3/valid/braces-in-prompt.yaml create mode 100644 conformance/v4/invalid/placeholder-in-transfer-target.expected.json create mode 100644 conformance/v4/invalid/placeholder-in-transfer-target.yaml create mode 100644 conformance/v4/invalid/unknown-variable.expected.json create mode 100644 conformance/v4/invalid/unknown-variable.yaml create mode 100644 crates/wavekat-flow/src/vars.rs create mode 100644 packages/flow-schema/src/vars.ts create mode 100644 packages/flow-schema/test/vars.test.ts diff --git a/conformance/v3/valid/braces-in-prompt.expected.json b/conformance/v3/valid/braces-in-prompt.expected.json new file mode 100644 index 0000000..f8f9d79 --- /dev/null +++ b/conformance/v3/valid/braces-in-prompt.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Before version 4 a `{{` in a prompt is ordinary text, spoken as written. Existing flows that happen to contain braces keep working.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v3/valid/braces-in-prompt.yaml b/conformance/v3/valid/braces-in-prompt.yaml new file mode 100644 index 0000000..0d36ce9 --- /dev/null +++ b/conformance/v3/valid/braces-in-prompt.yaml @@ -0,0 +1,12 @@ +schema_version: 3 +id: flow_braces +name: Braces are just text +entry: say +nodes: + say: + kind: greeting + prompt: "Press {{1}} now, or {{ stay on the line }}." + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/conformance/v4/invalid/placeholder-in-transfer-target.expected.json b/conformance/v4/invalid/placeholder-in-transfer-target.expected.json new file mode 100644 index 0000000..0f30cd3 --- /dev/null +++ b/conformance/v4/invalid/placeholder-in-transfer-target.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Placeholders are only for a prompt, an audio prompt's template and a menu label. A transfer target is never filled in, so a `{{` there is refused rather than dialled.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["placeholder_not_allowed"] } +} diff --git a/conformance/v4/invalid/placeholder-in-transfer-target.yaml b/conformance/v4/invalid/placeholder-in-transfer-target.yaml new file mode 100644 index 0000000..717c881 --- /dev/null +++ b/conformance/v4/invalid/placeholder-in-transfer-target.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_placeholder_target +name: Placeholder in a phone number +entry: go +variables: + number: { description: Who to ring, default: "+6491234567", max_len: 20 } +nodes: + go: + kind: transfer + target: "{{number}}" diff --git a/conformance/v4/invalid/unknown-variable.expected.json b/conformance/v4/invalid/unknown-variable.expected.json new file mode 100644 index 0000000..e68c671 --- /dev/null +++ b/conformance/v4/invalid/unknown-variable.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A `{{name}}` placeholder must name a variable the flow declares; otherwise the call would speak the braces or nothing. Unknown names are refused.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["unknown_variable"] } +} diff --git a/conformance/v4/invalid/unknown-variable.yaml b/conformance/v4/invalid/unknown-variable.yaml new file mode 100644 index 0000000..7763fc2 --- /dev/null +++ b/conformance/v4/invalid/unknown-variable.yaml @@ -0,0 +1,14 @@ +schema_version: 4 +id: flow_unknown_variable +name: Placeholder with no variable +entry: ask +variables: + question: { description: The question, default: "Anything?", max_len: 100 } +nodes: + ask: + kind: greeting + prompt: "{{question}} Also {{ghost}}." + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/crates/wavekat-flow/src/lib.rs b/crates/wavekat-flow/src/lib.rs index 1739bcb..f0bba06 100644 --- a/crates/wavekat-flow/src/lib.rs +++ b/crates/wavekat-flow/src/lib.rs @@ -41,6 +41,7 @@ pub mod engine; pub mod hours; pub mod trace; pub mod validate; +pub mod vars; /// Re-exported so callers name the generated maps' type without a matching /// `indexmap` dependency of their own. diff --git a/crates/wavekat-flow/src/validate.rs b/crates/wavekat-flow/src/validate.rs index 3c653e3..5c4693a 100644 --- a/crates/wavekat-flow/src/validate.rs +++ b/crates/wavekat-flow/src/validate.rs @@ -18,6 +18,7 @@ use crate::book::{self}; use crate::hours::{self, HoursError}; use crate::model::{Flow, Node, Prompt}; use crate::model_ext::NodeId; +use crate::vars::{self, TemplateError}; use crate::SUPPORTED_SCHEMA_VERSIONS; /// Longest a spoken (text) prompt may be. A backstop against a pasted-essay @@ -48,6 +49,11 @@ const VARIABLES_MIN_SCHEMA_VERSION: u32 = 4; /// Twin: `model.ts` `TEMPLATE_MIN_SCHEMA_VERSION`. const TEMPLATE_MIN_SCHEMA_VERSION: u32 = 4; +/// The longest a variable's `max_len` may be, in characters. The schema +/// carries the same cap; the validators re-check it so a value built in +/// code is held to it too. Twin: `model.ts` `MAX_VARIABLE_LEN`. +const MAX_VARIABLE_LEN: u64 = 500; + /// One thing wrong with a flow document. Carries enough context (node id, /// exit name, offending value) for the editor to point at it. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] @@ -144,6 +150,34 @@ pub enum ValidationError { declared: i64, }, + #[error("variable name {name:?} must be a lowercase letter, then up to 31 lowercase letters, digits or underscores")] + VariableBadName { node: Option, name: String }, + + #[error("variable {name:?} max_len is {value} (allowed: 1-{MAX_VARIABLE_LEN})")] + VariableMaxLenOutOfRange { name: String, value: u64 }, + + #[error("node {node:?} {field} has a malformed placeholder: {reason}")] + TemplateSyntax { + node: NodeId, + field: String, + reason: String, + }, + + #[error( + "node {node:?} {field} uses {name:?}, which the flow does not declare under variables" + )] + UnknownVariable { + node: NodeId, + field: String, + name: String, + }, + + #[error("{} holds a {{{{ placeholder, which is only allowed in a prompt, a prompt template or a menu label", .node.as_ref().map(|n| format!("node {n:?} {fields:?}")).unwrap_or_else(|| format!("{fields:?}")))] + PlaceholderNotAllowed { + node: Option, + fields: Vec, + }, + #[error("transfer node {node:?} sets timeout_secs but has no whisper to screen with")] TimeoutWithoutWhisper { node: NodeId }, @@ -197,6 +231,11 @@ impl ValidationError { ValidationError::KindRequiresNewerSchema { .. } => "kind_requires_newer_schema", ValidationError::FieldRequiresNewerSchema { .. } => "field_requires_newer_schema", ValidationError::VariablesRequireNewerSchema { .. } => "field_requires_newer_schema", + ValidationError::VariableBadName { .. } => "variable_bad_name", + ValidationError::VariableMaxLenOutOfRange { .. } => "variable_max_len_out_of_range", + ValidationError::TemplateSyntax { .. } => "template_syntax", + ValidationError::UnknownVariable { .. } => "unknown_variable", + ValidationError::PlaceholderNotAllowed { .. } => "placeholder_not_allowed", ValidationError::TimeoutWithoutWhisper { .. } => "timeout_without_whisper", ValidationError::TransferTimeoutOutOfRange { .. } => "transfer_timeout_out_of_range", ValidationError::OutboundNodeNotAllowed { .. } => "outbound_node_not_allowed", @@ -283,6 +322,8 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { }); } + check_variables(flow, &mut errs); + if flow.nodes.is_empty() { errs.push(ValidationError::EmptyFlow); return Err(errs); // graph checks below would be meaningless @@ -298,6 +339,7 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { check_node(id, node, &mut errs); check_transfer_fields_version(id, node, flow.schema_version, &mut errs); check_template_version(id, node, flow.schema_version, &mut errs); + check_placeholders(id, node, flow, &mut errs); // A component the document's own version doesn't have. Checked // per node rather than once per flow so the editor points at the @@ -328,6 +370,136 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { } } +/// Declared variable names and `max_len`s, and placeholder-looking text in +/// the flow's own string fields. Only on a v4 document: before that `{{` +/// is ordinary text and `variables` is refused as a whole. +fn check_variables(flow: &Flow, errs: &mut Vec) { + if flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { + return; + } + let mut names: Vec<&String> = flow.variables.keys().collect(); + names.sort(); + for name in names { + if !vars::is_variable_name(name) { + errs.push(ValidationError::VariableBadName { + node: None, + name: name.clone(), + }); + } + let max_len = flow.variables[name].max_len.get(); + if max_len > MAX_VARIABLE_LEN { + errs.push(ValidationError::VariableMaxLenOutOfRange { + name: name.clone(), + value: max_len, + }); + } + } + let mut fields: Vec = [("id", &flow.id), ("name", &flow.name)] + .into_iter() + .filter(|(_, v)| v.contains("{{")) + .map(|(k, _)| k.to_string()) + .collect(); + fields.sort(); + if !fields.is_empty() { + errs.push(ValidationError::PlaceholderNotAllowed { node: None, fields }); + } +} + +/// Check every place a node may hold a placeholder (string prompts, an +/// audio prompt's `template`, menu option labels) against the declared +/// variables, and refuse `{{` in any other string field. A v1-v3 document +/// is skipped entirely: there `{{` is text to be spoken as written. +fn check_placeholders(id: &NodeId, node: &Node, flow: &Flow, errs: &mut Vec) { + if flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { + return; + } + let mut scan = |field: String, text: &str| match vars::parse_template(text) { + Ok(_) => { + for name in vars::template_names(text) { + if !flow.variables.contains_key(&name) { + errs.push(ValidationError::UnknownVariable { + node: id.clone(), + field: field.clone(), + name, + }); + } + } + } + Err(TemplateError::BadName(name)) => errs.push(ValidationError::VariableBadName { + node: Some(id.clone()), + name, + }), + Err(e) => errs.push(ValidationError::TemplateSyntax { + node: id.clone(), + field, + reason: e.to_string(), + }), + }; + for (field, prompt) in node.prompt_slots() { + match prompt { + Prompt::Text(text) => scan(field.to_string(), text), + Prompt::Audio { .. } => { + if let Some(template) = prompt.template() { + scan(format!("{field}.template"), template); + } + } + } + } + if let Node::Menu { options, .. } = node { + let mut keys: Vec<&String> = options.keys().collect(); + keys.sort(); + for key in keys { + scan(format!("options.{key}"), &options[key]); + } + } + + // Everything else: any string value holding `{{` is out of place. + let Ok(serde_json::Value::Object(map)) = serde_json::to_value(node) else { + return; + }; + let mut bad = Vec::new(); + for (key, value) in &map { + if key != "exits" && key != "kind" { + collect_stray_braces(key, value, &mut bad); + } + } + bad.sort(); + if !bad.is_empty() { + errs.push(ValidationError::PlaceholderNotAllowed { + node: Some(id.clone()), + fields: bad, + }); + } +} + +/// Paths of string values under `value` that hold `{{`, apart from the +/// slots where a placeholder is allowed: a plain-string `prompt`, +/// `confirm_prompt` or `whisper`, any `.template`, and menu `options`. +fn collect_stray_braces(path: &str, value: &serde_json::Value, out: &mut Vec) { + use serde_json::Value; + match value { + Value::String(s) => { + let allowed = matches!(path, "prompt" | "confirm_prompt" | "whisper") + || path.ends_with(".template") + || path.starts_with("options."); + if s.contains("{{") && !allowed { + out.push(path.to_string()); + } + } + Value::Array(items) => { + for (i, item) in items.iter().enumerate() { + collect_stray_braces(&format!("{path}.{i}"), item, out); + } + } + Value::Object(map) => { + for (key, item) in map { + collect_stray_braces(&format!("{path}.{key}"), item, out); + } + } + _ => {} + } +} + /// `whisper` and `timeout_secs` on a document older than the version that /// has them. Reported per field, so the editor can say which one to drop /// or which version to raise. @@ -1622,7 +1794,9 @@ nodes: #[test] fn template_needs_v4() { - let flow = parse(WITH_TEMPLATE); + let declared = + WITH_TEMPLATE.replace("nodes:", "variables:\n name: { default: there }\nnodes:"); + let flow = parse(&declared); assert_eq!(required_schema_version(&flow), 4); assert_eq!(validate(&flow), Ok(())); let plain = WITH_TEMPLATE.replace(", template: \"Hi {{name}}\"", ""); @@ -1644,4 +1818,79 @@ nodes: ); assert_eq!(errs[0].code(), "field_requires_newer_schema"); } + + fn v4_flow(vars: &str, nodes: &str) -> String { + format!("schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n{vars}\nnodes:\n{nodes}") + } + + const Q: &str = " q: { default: \"x\" }\n"; + + #[test] + fn v4_placeholder_must_be_declared() { + let f = v4_flow( + Q, + " a:\n kind: hangup\n prompt: \"Hi {{q}} {{ghost}}\"\n", + ); + assert_eq!(codes(&f), vec!["unknown_variable"]); + let ok = v4_flow(Q, " a:\n kind: hangup\n prompt: \"Hi {{q}}\"\n"); + assert_eq!(validate(&parse(&ok)), Ok(())); + } + + #[test] + fn v4_menu_labels_and_templates_are_scanned() { + let f = v4_flow( + Q, + " a:\n kind: menu\n prompt: { audio: vprompt_ab12, template: \"{{nope}}\" }\n options: { \"1\": \"{{q}}\", \"2\": \"{{bad}}\" }\n exits: { \"1\": b, \"2\": b, no_input: b, invalid: b }\n b:\n kind: hangup\n prompt: bye\n", + ); + assert_eq!(codes(&f), vec!["unknown_variable", "unknown_variable"]); + } + + #[test] + fn v4_bad_template_syntax_and_names() { + let f = v4_flow(Q, " a:\n kind: hangup\n prompt: \"{{#q}} open\"\n"); + assert_eq!(codes(&f), vec!["template_syntax"]); + let f = v4_flow(Q, " a:\n kind: hangup\n prompt: \"{{Q}}\"\n"); + assert_eq!(codes(&f), vec!["variable_bad_name"]); + } + + #[test] + fn v4_declared_names_must_fit_the_pattern() { + let f = v4_flow( + " Bad: { default: \"\" }\n", + " a:\n kind: hangup\n prompt: bye\n", + ); + assert_eq!(codes(&f), vec!["variable_bad_name"]); + } + + #[test] + fn v4_max_len_is_capped() { + let f = v4_flow( + " q: { default: \"\", max_len: 501 }\n", + " a:\n kind: hangup\n prompt: bye\n", + ); + assert_eq!(codes(&f), vec!["variable_max_len_out_of_range"]); + } + + #[test] + fn placeholder_in_transfer_target_is_refused() { + let f = v4_flow(Q, " a:\n kind: transfer\n target: \"{{q}}\"\n"); + assert_eq!(codes(&f), vec!["placeholder_not_allowed"]); + } + + #[test] + fn placeholder_in_a_transcript_is_refused() { + let f = v4_flow( + Q, + " a:\n kind: hangup\n prompt: { audio: vprompt_ab12, transcript: \"Hi {{q}}\" }\n", + ); + assert_eq!(codes(&f), vec!["placeholder_not_allowed"]); + } + + #[test] + fn v3_braces_are_plain_text() { + let f = parse( + "schema_version: 3\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: \"Press {{1}} now }} {{#x\"\n", + ); + assert_eq!(validate(&f), Ok(())); + } } diff --git a/crates/wavekat-flow/src/vars.rs b/crates/wavekat-flow/src/vars.rs new file mode 100644 index 0000000..f6e68f6 --- /dev/null +++ b/crates/wavekat-flow/src/vars.rs @@ -0,0 +1,215 @@ +//! Placeholder syntax shared by validation and filling. +//! +//! A template is text with `{{name}}` placeholders and `{{#name}}…{{/name}}` +//! conditional blocks (kept only when the variable's value is non-empty). +//! Blocks do not nest and have no else. Names are `[a-z][a-z0-9_]{0,31}`. +//! Twin: `packages/flow-schema/src/vars.ts`. + +/// One piece of a parsed template. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Segment<'a> { + /// Literal text, spoken as written. + Text(&'a str), + /// A `{{name}}` placeholder. + Var(&'a str), + /// A `{{#name}}…{{/name}}` block; `body` holds only `Text` and `Var`. + Block { + name: &'a str, + body: Vec>, + }, +} + +/// Why a template could not be parsed. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum TemplateError { + #[error("a `{{{{` or block is never closed")] + Unclosed, + #[error("blocks cannot be nested")] + Nested, + #[error("{0:?} is not a valid variable name (a lowercase letter, then up to 31 lowercase letters, digits or underscores)")] + BadName(String), + #[error("block close {{{{/{0}}}}} does not match an open block")] + Mismatched(String), +} + +/// Whether `name` fits `[a-z][a-z0-9_]{0,31}`. Twin: `isVariableName`. +pub fn is_variable_name(name: &str) -> bool { + let mut chars = name.chars(); + matches!(chars.next(), Some('a'..='z')) + && name.len() <= 32 + && chars.all(|c| matches!(c, 'a'..='z' | '0'..='9' | '_')) +} + +enum Tok<'a> { + Text(&'a str), + Var(&'a str), + Open(&'a str), + Close(&'a str), +} + +/// Split `s` into tokens. The flag is true when a `{{` has no `}}`. +fn tokens(s: &str) -> (Vec>, bool) { + let mut out = Vec::new(); + let mut rest = s; + while let Some(start) = rest.find("{{") { + if start > 0 { + out.push(Tok::Text(&rest[..start])); + } + let after = &rest[start + 2..]; + let Some(end) = after.find("}}") else { + return (out, true); + }; + let inner = &after[..end]; + out.push(if let Some(name) = inner.strip_prefix('#') { + Tok::Open(name) + } else if let Some(name) = inner.strip_prefix('/') { + Tok::Close(name) + } else { + Tok::Var(inner) + }); + rest = &after[end + 2..]; + } + if !rest.is_empty() { + out.push(Tok::Text(rest)); + } + (out, false) +} + +/// Parse `s` into segments. +pub fn parse_template(s: &str) -> Result>, TemplateError> { + let (toks, unclosed) = tokens(s); + let mut out = Vec::new(); + // The open block: its name and the body gathered so far. + let mut open: Option<(&str, Vec>)> = None; + for tok in toks { + match tok { + Tok::Text(t) => match &mut open { + Some((_, body)) => body.push(Segment::Text(t)), + None => out.push(Segment::Text(t)), + }, + Tok::Var(n) => { + if !is_variable_name(n) { + return Err(TemplateError::BadName(n.to_string())); + } + match &mut open { + Some((_, body)) => body.push(Segment::Var(n)), + None => out.push(Segment::Var(n)), + } + } + Tok::Open(n) => { + if !is_variable_name(n) { + return Err(TemplateError::BadName(n.to_string())); + } + if open.is_some() { + return Err(TemplateError::Nested); + } + open = Some((n, Vec::new())); + } + Tok::Close(n) => { + if !is_variable_name(n) { + return Err(TemplateError::BadName(n.to_string())); + } + match open.take() { + Some((name, body)) if name == n => out.push(Segment::Block { name, body }), + _ => return Err(TemplateError::Mismatched(n.to_string())), + } + } + } + } + if unclosed || open.is_some() { + return Err(TemplateError::Unclosed); + } + Ok(out) +} + +/// Every variable name `s` mentions, first-mention order, no repeats. +/// Best effort on a malformed template: the well-formed names it holds. +pub fn template_names(s: &str) -> Vec { + let mut names: Vec = Vec::new(); + for tok in tokens(s).0 { + if let Tok::Var(n) | Tok::Open(n) = tok { + if is_variable_name(n) && !names.iter().any(|x| x == n) { + names.push(n.to_string()); + } + } + } + names +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parses_text_vars_and_blocks() { + assert_eq!( + parse_template("Hi {{a}}.{{#b}} B={{b}}{{/b}}").unwrap(), + vec![ + Segment::Text("Hi "), + Segment::Var("a"), + Segment::Text("."), + Segment::Block { + name: "b", + body: vec![Segment::Text(" B="), Segment::Var("b")] + }, + ] + ); + } + + #[test] + fn plain_text_and_stray_closers_pass_through() { + assert_eq!(parse_template("").unwrap(), vec![]); + assert_eq!( + parse_template("a }} b").unwrap(), + vec![Segment::Text("a }} b")] + ); + } + + #[test] + fn rejects_nested_and_unclosed_blocks() { + assert_eq!( + parse_template("{{#a}}{{#b}}{{/b}}{{/a}}"), + Err(TemplateError::Nested) + ); + assert_eq!(parse_template("{{#a}} x"), Err(TemplateError::Unclosed)); + assert_eq!(parse_template("{{a"), Err(TemplateError::Unclosed)); + } + + #[test] + fn rejects_mismatched_closers() { + assert_eq!( + parse_template("{{/a}}"), + Err(TemplateError::Mismatched("a".into())) + ); + assert_eq!( + parse_template("{{#a}}{{/b}}"), + Err(TemplateError::Mismatched("b".into())) + ); + } + + #[test] + fn rejects_bad_names() { + assert_eq!( + parse_template("{{A}}"), + Err(TemplateError::BadName("A".into())) + ); + assert_eq!( + parse_template("{{1a}}"), + Err(TemplateError::BadName("1a".into())) + ); + assert_eq!( + parse_template("{{}}"), + Err(TemplateError::BadName(String::new())) + ); + assert!(parse_template(&format!("{{{{{}}}}}", "a".repeat(32))).is_ok()); + assert!(parse_template(&format!("{{{{{}}}}}", "a".repeat(33))).is_err()); + } + + #[test] + fn names_are_listed_once_in_order() { + assert_eq!( + template_names("{{b}} {{#a}}{{a}}{{/a}} {{b}}"), + vec!["b".to_string(), "a".to_string()] + ); + } +} diff --git a/packages/flow-schema/src/index.ts b/packages/flow-schema/src/index.ts index 965d8f4..86bf4e6 100644 --- a/packages/flow-schema/src/index.ts +++ b/packages/flow-schema/src/index.ts @@ -64,3 +64,13 @@ export { setSchemaVersion, stampIdentity, } from './mutate.js'; + +export { + isVariableName, + parseTemplate, + templateErrorCode, + templateIssues, + templateNames, + tryParseTemplate, +} from './vars.js'; +export type { Segment, TemplateError } from './vars.js'; diff --git a/packages/flow-schema/src/model.ts b/packages/flow-schema/src/model.ts index 2dccbe8..df407ed 100644 --- a/packages/flow-schema/src/model.ts +++ b/packages/flow-schema/src/model.ts @@ -75,6 +75,10 @@ export const TRANSFER_FIELDS_MIN_SCHEMA_VERSION = 3; * `validate.rs` `VARIABLES_MIN_SCHEMA_VERSION`. */ export const VARIABLES_MIN_SCHEMA_VERSION = 4; +/** The longest a variable's `max_len` may be, in characters. The schema + * carries the same cap. Twin: `validate.rs` `MAX_VARIABLE_LEN`. */ +export const MAX_VARIABLE_LEN = 500; + /** Longest a spoken (text) prompt may be — see `validate.ts`. Twin: * `validate.rs` `MAX_PROMPT_CHARS`. */ export const MAX_PROMPT_CHARS = 2000; diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index ece86b1..51cd0fb 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -12,10 +12,11 @@ // and menu/hours sanity caps. All problems are collected (not // fail-fast) so the editor can show every one at once. -import type { BookNode, ComponentKind, Flow, Prompt, TransferNode } from './model.js'; +import type { BookNode, ComponentKind, Flow, Node, Prompt, TransferNode } from './model.js'; import { KIND_MIN_SCHEMA_VERSION, MAX_PROMPT_CHARS, + MAX_VARIABLE_LEN, MAX_TRANSFER_TIMEOUT_SECS, MIN_TRANSFER_TIMEOUT_SECS, SUPPORTED_SCHEMA_VERSIONS, @@ -46,6 +47,7 @@ import { parseBookVocabularyRef, } from './book.js'; import type { Issue } from './issues.js'; +import { isVariableName, templateNames, tryParseTemplate } from './vars.js'; import { validateHours } from './hours.js'; type NodeRanges = Record; @@ -87,6 +89,9 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { }); } + const mentioned = new Set(); + checkVariables(flow, issues); + const nodeIds = Object.keys(flow.nodes); if (nodeIds.length === 0) { issues.push({ severity: 'error', code: 'empty_flow', message: 'flow has no nodes' }); @@ -119,6 +124,7 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { }, }); } + checkPlaceholders(id, node, flow, issues, at, mentioned); const exits = node.exits ?? {}; // Exit keys must be exactly the set the component defines, and // every target must exist. @@ -238,6 +244,20 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { } // Reachability and trap analysis need a real entry to walk from. + // TS-only: a declared variable no placeholder mentions is dead weight. + if (flow.schema_version >= VARIABLES_MIN_SCHEMA_VERSION) { + for (const name of Object.keys(flow.variables ?? {})) { + if (!mentioned.has(name)) { + issues.push({ + severity: 'warning', + code: 'unused_variable', + message: `variable "${name}" is declared but no prompt or menu label uses it`, + params: { name }, + }); + } + } + } + if (entryExists) checkGraph(flow, issues, at); return issues; @@ -337,6 +357,156 @@ function checkBookBounds( } } +/** Declared variable names and `max_len`s, and placeholder-looking text in + * the flow's own string fields. Only on a v4 document: before that `{{` is + * ordinary text and `variables` is refused as a whole. Twin: `check_variables`. */ +function checkVariables(flow: Flow, issues: Issue[]): void { + if (flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) return; + for (const name of Object.keys(flow.variables ?? {}).sort()) { + if (!isVariableName(name)) { + issues.push({ + severity: 'error', + code: 'variable_bad_name', + message: `variable name "${name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, + params: { name }, + }); + } + const maxLen = flow.variables?.[name]?.max_len; + if (maxLen !== undefined && (!Number.isInteger(maxLen) || maxLen < 1 || maxLen > MAX_VARIABLE_LEN)) { + issues.push({ + severity: 'error', + code: 'variable_max_len_out_of_range', + message: `variable "${name}" max_len is ${maxLen} (allowed: 1-${MAX_VARIABLE_LEN})`, + params: { name, value: maxLen }, + }); + } + } + const fields = (['id', 'name'] as const).filter((k) => flow[k].includes('{{')).sort(); + if (fields.length > 0) { + issues.push({ + severity: 'error', + code: 'placeholder_not_allowed', + message: `${JSON.stringify(fields)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, + params: { fields }, + }); + } +} + +/** Check every place a node may hold a placeholder (string prompts, an audio + * prompt's `template`, menu option labels) against the declared variables, + * and refuse `{{` in any other string field. A v1-v3 document is skipped: + * there `{{` is text to be spoken as written. Twin: `check_placeholders`. */ +function checkPlaceholders( + id: string, + node: Node, + flow: Flow, + issues: Issue[], + at: (node: string) => Pick, + mentioned: Set, +): void { + if (flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) return; + const scan = (field: string, text: string) => { + const { error } = tryParseTemplate(text); + for (const name of templateNames(text)) mentioned.add(name); + if (error === null) { + for (const name of templateNames(text)) { + if (!Object.hasOwn(flow.variables ?? {}, name)) { + issues.push({ + ...at(id), + code: 'unknown_variable', + message: `node "${id}" ${field} uses "${name}", which the flow does not declare under variables`, + params: { field, name }, + }); + } + } + } else if (error.kind === 'bad_name') { + issues.push({ + ...at(id), + code: 'variable_bad_name', + message: `variable name "${error.name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, + params: { name: error.name }, + }); + } else { + issues.push({ + ...at(id), + code: 'template_syntax', + message: `node "${id}" ${field} has a malformed placeholder: ${TEMPLATE_REASONS[error.kind]}`, + params: { field, reason: TEMPLATE_REASONS[error.kind] }, + }); + } + }; + for (const [field, prompt] of nodePromptSlots(node)) { + if (typeof prompt === 'string') scan(field, prompt); + else if (typeof prompt.template === 'string') scan(`${field}.template`, prompt.template); + } + if (node.kind === 'menu') { + for (const key of Object.keys(node.options).sort()) { + scan(`options.${key}`, node.options[key] ?? ''); + } + } + + // Everything else: any string value holding `{{` is out of place. + const bad: string[] = []; + for (const [key, value] of Object.entries(node)) { + if (key !== 'exits' && key !== 'kind') collectStrayBraces(key, value, bad); + } + bad.sort(); + if (bad.length > 0) { + issues.push({ + ...at(id), + code: 'placeholder_not_allowed', + message: `node "${id}" ${JSON.stringify(bad)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, + params: { fields: bad }, + }); + } +} + +const TEMPLATE_REASONS = { + unclosed: 'a `{{` or block is never closed', + nested: 'blocks cannot be nested', + mismatched: 'a block close does not match an open block', +} as const; + +/** The prompt slots of a node with the field each comes from. */ +function nodePromptSlots(node: Node): [string, Prompt][] { + switch (node.kind) { + case 'greeting': + case 'menu': + case 'message': + return [['prompt', node.prompt]]; + case 'hangup': + return node.prompt === undefined ? [] : [['prompt', node.prompt]]; + case 'book': + return [ + ['prompt', node.prompt], + ['confirm_prompt', node.confirm_prompt], + ]; + case 'transfer': + return node.whisper === undefined ? [] : [['whisper', node.whisper]]; + default: + return []; + } +} + +/** Paths of string values under `value` that hold `{{`, apart from the slots + * where a placeholder is allowed: a plain-string `prompt`, `confirm_prompt` + * or `whisper`, any `.template`, and menu `options`. */ +function collectStrayBraces(path: string, value: unknown, out: string[]): void { + if (typeof value === 'string') { + const allowed = + path === 'prompt' || + path === 'confirm_prompt' || + path === 'whisper' || + path.endsWith('.template') || + path.startsWith('options.'); + if (value.includes('{{') && !allowed) out.push(path); + } else if (Array.isArray(value)) { + value.forEach((item, i) => collectStrayBraces(`${path}.${i}`, item, out)); + } else if (value !== null && typeof value === 'object') { + for (const [key, item] of Object.entries(value)) collectStrayBraces(`${path}.${key}`, item, out); + } +} + function checkPrompt( id: string, prompt: Prompt, diff --git a/packages/flow-schema/src/vars.ts b/packages/flow-schema/src/vars.ts new file mode 100644 index 0000000..dd9f5da --- /dev/null +++ b/packages/flow-schema/src/vars.ts @@ -0,0 +1,107 @@ +// Placeholder syntax shared by validation and filling. Twin of +// `crates/wavekat-flow/src/vars.rs`; keep the two in lockstep. +// +// A template is text with `{{name}}` placeholders and `{{#name}}…{{/name}}` +// conditional blocks (kept only when the variable's value is non-empty). +// Blocks do not nest and have no else. Names are `[a-z][a-z0-9_]{0,31}`. + +/** One piece of a parsed template. A block's body holds only text and vars. */ +export type Segment = + | { kind: 'text'; text: string } + | { kind: 'var'; name: string } + | { kind: 'block'; name: string; body: Segment[] }; + +/** Why a template could not be parsed. */ +export type TemplateError = + | { kind: 'unclosed' } + | { kind: 'nested' } + | { kind: 'bad_name'; name: string } + | { kind: 'mismatched'; name: string }; + +const NAME_RE = /^[a-z][a-z0-9_]{0,31}$/; + +/** Whether `name` fits `[a-z][a-z0-9_]{0,31}`. Twin: `is_variable_name`. */ +export function isVariableName(name: string): boolean { + return NAME_RE.test(name); +} + +type Tok = + | { t: 'text'; v: string } + | { t: 'var' | 'open' | 'close'; v: string }; + +/** Split `s` into tokens. `unclosed` is true when a `{{` has no `}}`. */ +function tokens(s: string): { toks: Tok[]; unclosed: boolean } { + const toks: Tok[] = []; + let rest = s; + for (;;) { + const start = rest.indexOf('{{'); + if (start < 0) break; + if (start > 0) toks.push({ t: 'text', v: rest.slice(0, start) }); + const after = rest.slice(start + 2); + const end = after.indexOf('}}'); + if (end < 0) return { toks, unclosed: true }; + const inner = after.slice(0, end); + if (inner.startsWith('#')) toks.push({ t: 'open', v: inner.slice(1) }); + else if (inner.startsWith('/')) toks.push({ t: 'close', v: inner.slice(1) }); + else toks.push({ t: 'var', v: inner }); + rest = after.slice(end + 2); + } + if (rest.length > 0) toks.push({ t: 'text', v: rest }); + return { toks, unclosed: false }; +} + +/** Parse `s`; the first defect, if any, comes back as `error`. */ +export function tryParseTemplate(s: string): { segments: Segment[]; error: TemplateError | null } { + const { toks, unclosed } = tokens(s); + const segments: Segment[] = []; + let open: { name: string; body: Segment[] } | null = null; + const fail = (error: TemplateError) => ({ segments: [], error }); + for (const tok of toks) { + const into = open ? open.body : segments; + if (tok.t === 'text') { + into.push({ kind: 'text', text: tok.v }); + continue; + } + if (!isVariableName(tok.v)) return fail({ kind: 'bad_name', name: tok.v }); + if (tok.t === 'var') { + into.push({ kind: 'var', name: tok.v }); + } else if (tok.t === 'open') { + if (open) return fail({ kind: 'nested' }); + open = { name: tok.v, body: [] }; + } else { + if (!open || open.name !== tok.v) return fail({ kind: 'mismatched', name: tok.v }); + segments.push({ kind: 'block', name: open.name, body: open.body }); + open = null; + } + } + if (unclosed || open) return fail({ kind: 'unclosed' }); + return { segments, error: null }; +} + +/** Parse `s` into segments; empty when the template is malformed. Throws nothing. */ +export function parseTemplate(s: string): Segment[] { + return tryParseTemplate(s).segments; +} + +/** The validator code for a template defect. */ +export function templateErrorCode(error: TemplateError): 'template_syntax' | 'variable_bad_name' { + return error.kind === 'bad_name' ? 'variable_bad_name' : 'template_syntax'; +} + +/** Codes for what is wrong with `s`: empty when well formed, else one code. */ +export function templateIssues(s: string): string[] { + const { error } = tryParseTemplate(s); + return error === null ? [] : [templateErrorCode(error)]; +} + +/** Every variable name `s` mentions, first-mention order, no repeats. + * Best effort on a malformed template: the well-formed names it holds. */ +export function templateNames(s: string): string[] { + const names: string[] = []; + for (const tok of tokens(s).toks) { + if ((tok.t === 'var' || tok.t === 'open') && isVariableName(tok.v) && !names.includes(tok.v)) { + names.push(tok.v); + } + } + return names; +} diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts new file mode 100644 index 0000000..fa48f71 --- /dev/null +++ b/packages/flow-schema/test/vars.test.ts @@ -0,0 +1,116 @@ +import { describe, expect, it } from 'vitest'; + +import { checkFlow } from '../src/check.js'; +import { parseTemplate, templateIssues, templateNames, tryParseTemplate } from '../src/vars.js'; + +describe('parseTemplate', () => { + it('parses text, vars and blocks', () => { + expect(parseTemplate('Hi {{a}}.{{#b}} B={{b}}{{/b}}')).toEqual([ + { kind: 'text', text: 'Hi ' }, + { kind: 'var', name: 'a' }, + { kind: 'text', text: '.' }, + { + kind: 'block', + name: 'b', + body: [ + { kind: 'text', text: ' B=' }, + { kind: 'var', name: 'b' }, + ], + }, + ]); + }); + + it('passes plain text and stray closers through', () => { + expect(parseTemplate('')).toEqual([]); + expect(parseTemplate('a }} b')).toEqual([{ kind: 'text', text: 'a }} b' }]); + }); + + it('rejects nested and unclosed blocks', () => { + expect(tryParseTemplate('{{#a}}{{#b}}{{/b}}{{/a}}').error).toEqual({ kind: 'nested' }); + expect(tryParseTemplate('{{#a}} x').error).toEqual({ kind: 'unclosed' }); + expect(tryParseTemplate('{{a').error).toEqual({ kind: 'unclosed' }); + }); + + it('rejects mismatched closers', () => { + expect(tryParseTemplate('{{/a}}').error).toEqual({ kind: 'mismatched', name: 'a' }); + expect(tryParseTemplate('{{#a}}{{/b}}').error).toEqual({ kind: 'mismatched', name: 'b' }); + }); + + it('rejects bad names', () => { + expect(tryParseTemplate('{{A}}').error).toEqual({ kind: 'bad_name', name: 'A' }); + expect(tryParseTemplate('{{1a}}').error).toEqual({ kind: 'bad_name', name: '1a' }); + expect(tryParseTemplate('{{}}').error).toEqual({ kind: 'bad_name', name: '' }); + expect(tryParseTemplate(`{{${'a'.repeat(32)}}}`).error).toBeNull(); + expect(tryParseTemplate(`{{${'a'.repeat(33)}}}`).error).not.toBeNull(); + }); + + it('reports codes and names', () => { + expect(templateIssues('{{a}}')).toEqual([]); + expect(templateIssues('{{a')).toEqual(['template_syntax']); + expect(templateIssues('{{A}}')).toEqual(['variable_bad_name']); + expect(templateNames('{{b}} {{#a}}{{a}}{{/a}} {{b}}')).toEqual(['b', 'a']); + }); +}); + +const flow = (version: number, vars: string, body: string) => + `schema_version: ${version}\nid: f\nname: F\nentry: a\n${vars}nodes:\n${body}`; + +function errorCodes(src: string): string[] { + return checkFlow(src) + .issues.filter((i) => i.severity === 'error') + .map((i) => i.code); +} + +const Q = 'variables:\n q: { default: x }\n'; +const HANGUP = (prompt: string) => ` a:\n kind: hangup\n prompt: ${prompt}\n`; + +describe('placeholders in a flow', () => { + it('v4 placeholder must be declared', () => { + expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}} {{ghost}}"')))).toEqual(['unknown_variable']); + expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}}"')))).toEqual([]); + }); + + it('scans menu labels and templates', () => { + const body = + ' a:\n kind: menu\n prompt: { audio: vprompt_ab12, template: "{{nope}}" }\n options: { "1": "{{q}}", "2": "{{bad}}" }\n exits: { "1": b, "2": b, no_input: b, invalid: b }\n b:\n kind: hangup\n prompt: bye\n'; + expect(errorCodes(flow(4, Q, body))).toEqual(['unknown_variable', 'unknown_variable']); + }); + + it('reports bad syntax and names', () => { + expect(errorCodes(flow(4, Q, HANGUP('"{{#q}} open"')))).toEqual(['template_syntax']); + expect(errorCodes(flow(4, Q, HANGUP('"{{Q}}"')))).toEqual(['variable_bad_name']); + }); + + it('checks declared names and max_len', () => { + const body = HANGUP('bye'); + expect(errorCodes(flow(4, 'variables:\n Bad: { default: "" }\n', body))).toEqual([ + 'variable_bad_name', + ]); + expect( + errorCodes(flow(4, 'variables:\n q: { default: "", max_len: 501 }\n', body)), + ).toContain('variable_max_len_out_of_range'); + }); + + it('refuses placeholders in a transfer target and a transcript', () => { + expect(errorCodes(flow(4, Q, ' a:\n kind: transfer\n target: "{{q}}"\n'))).toEqual([ + 'placeholder_not_allowed', + ]); + expect( + errorCodes(flow(4, Q, HANGUP('{ audio: vprompt_ab12, transcript: "Hi {{q}}" }'))), + ).toEqual(['placeholder_not_allowed']); + }); + + it('treats braces as plain text before v4', () => { + expect(errorCodes(flow(3, '', HANGUP('"Press {{1}} now }} {{#x"')))).toEqual([]); + }); + + it('warns about a variable nothing uses', () => { + const issues = checkFlow(flow(4, Q, HANGUP('bye'))).issues; + expect(issues.filter((i) => i.code === 'unused_variable')).toMatchObject([ + { severity: 'warning', params: { name: 'q' } }, + ]); + expect( + checkFlow(flow(4, Q, HANGUP('"{{#q}}x{{/q}}"'))).issues.some((i) => i.code === 'unused_variable'), + ).toBe(false); + }); +}); From c78a3b0c38327d0e118238aae538c7f26fe004c4 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:46:37 +1300 Subject: [PATCH 05/13] fix: align placeholder check order and edge tests --- crates/wavekat-flow/src/vars.rs | 14 + packages/flow-schema/src/validate.ts | 374 +++++++++++++++---------- packages/flow-schema/test/vars.test.ts | 186 +++++++----- 3 files changed, 364 insertions(+), 210 deletions(-) diff --git a/crates/wavekat-flow/src/vars.rs b/crates/wavekat-flow/src/vars.rs index f6e68f6..11f1f39 100644 --- a/crates/wavekat-flow/src/vars.rs +++ b/crates/wavekat-flow/src/vars.rs @@ -205,6 +205,20 @@ mod tests { assert!(parse_template(&format!("{{{{{}}}}}", "a".repeat(33))).is_err()); } + #[test] + fn brace_edge_cases() { + assert_eq!( + parse_template("{{{a}}}"), + Err(TemplateError::BadName("{a".into())) + ); + assert_eq!( + parse_template("{ {a} }").unwrap(), + vec![Segment::Text("{ {a} }")] + ); + assert_eq!(parse_template("}}").unwrap(), vec![Segment::Text("}}")]); + assert_eq!(parse_template("{{#a}} x {{"), Err(TemplateError::Unclosed)); + } + #[test] fn names_are_listed_once_in_order() { assert_eq!( diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 51cd0fb..15aec36 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -12,7 +12,14 @@ // and menu/hours sanity caps. All problems are collected (not // fail-fast) so the editor can show every one at once. -import type { BookNode, ComponentKind, Flow, Node, Prompt, TransferNode } from './model.js'; +import type { + BookNode, + ComponentKind, + Flow, + Node, + Prompt, + TransferNode, +} from "./model.js"; import { KIND_MIN_SCHEMA_VERSION, MAX_PROMPT_CHARS, @@ -31,7 +38,7 @@ import { promptTemplate, promptText, requiredExits, -} from './model.js'; +} from "./model.js"; import { DEFAULT_BOOK_BUFFER_MINS, DEFAULT_BOOK_HORIZON_DAYS, @@ -45,10 +52,10 @@ import { MIN_BOOK_DURATION_MINS, bookVocabularyRefs, parseBookVocabularyRef, -} from './book.js'; -import type { Issue } from './issues.js'; -import { isVariableName, templateNames, tryParseTemplate } from './vars.js'; -import { validateHours } from './hours.js'; +} from "./book.js"; +import type { Issue } from "./issues.js"; +import { isVariableName, templateNames, tryParseTemplate } from "./vars.js"; +import { validateHours } from "./hours.js"; type NodeRanges = Record; @@ -59,16 +66,16 @@ type NodeRanges = Record; */ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { const issues: Issue[] = []; - const at = (node: string): Pick => ({ - severity: 'error', + const at = (node: string): Pick => ({ + severity: "error", node, range: nodeRanges[node], }); if (!SUPPORTED_SCHEMA_VERSIONS.includes(flow.schema_version)) { issues.push({ - severity: 'error', - code: 'unsupported_schema_version', + severity: "error", + code: "unsupported_schema_version", message: `schema_version ${flow.schema_version} is not supported`, params: { version: flow.schema_version }, }); @@ -76,13 +83,16 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // Flow-level, so it carries no node. Same code as a transfer field on an // older document: the field needs a newer version than the one declared. - if (hasVariables(flow) && flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) { + if ( + hasVariables(flow) && + flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION + ) { issues.push({ - severity: 'error', - code: 'field_requires_newer_schema', + severity: "error", + code: "field_requires_newer_schema", message: `variables needs schema_version ${VARIABLES_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, params: { - field: 'variables', + field: "variables", required: VARIABLES_MIN_SCHEMA_VERSION, declared: flow.schema_version, }, @@ -94,57 +104,49 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { const nodeIds = Object.keys(flow.nodes); if (nodeIds.length === 0) { - issues.push({ severity: 'error', code: 'empty_flow', message: 'flow has no nodes' }); + issues.push({ + severity: "error", + code: "empty_flow", + message: "flow has no nodes", + }); return issues; // graph checks below would be meaningless } const entryExists = flow.entry in flow.nodes; if (!entryExists) { issues.push({ - severity: 'error', - code: 'missing_entry', + severity: "error", + code: "missing_entry", message: `entry "${flow.entry}" is not a node`, params: { entry: flow.entry }, }); } for (const [id, node] of Object.entries(flow.nodes)) { - if ( - flow.schema_version < TEMPLATE_MIN_SCHEMA_VERSION && - nodePrompts(node).some((p) => promptTemplate(p) !== null) - ) { - issues.push({ - ...at(id), - code: 'field_requires_newer_schema', - message: `node "${id}" gives a prompt a template, which needs schema_version ${TEMPLATE_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, - params: { - field: 'template', - required: TEMPLATE_MIN_SCHEMA_VERSION, - declared: flow.schema_version, - }, - }); - } - checkPlaceholders(id, node, flow, issues, at, mentioned); const exits = node.exits ?? {}; // Exit keys must be exactly the set the component defines, and // every target must exist. const requiredNames = new Set(requiredExits(node)); const presentNames = new Set(Object.keys(exits)); - const missing = [...requiredNames].filter((name) => !presentNames.has(name)).sort(); + const missing = [...requiredNames] + .filter((name) => !presentNames.has(name)) + .sort(); if (missing.length > 0) { issues.push({ ...at(id), - code: 'missing_exits', - message: `node "${id}" (${node.kind}) is missing required exits: ${missing.join(', ')}`, + code: "missing_exits", + message: `node "${id}" (${node.kind}) is missing required exits: ${missing.join(", ")}`, params: { kind: node.kind, missing }, }); } - const unexpected = [...presentNames].filter((name) => !requiredNames.has(name)).sort(); + const unexpected = [...presentNames] + .filter((name) => !requiredNames.has(name)) + .sort(); if (unexpected.length > 0) { issues.push({ ...at(id), - code: 'unexpected_exits', - message: `node "${id}" (${node.kind}) has exits it does not define: ${unexpected.join(', ')}`, + code: "unexpected_exits", + message: `node "${id}" (${node.kind}) has exits it does not define: ${unexpected.join(", ")}`, params: { kind: node.kind, unexpected }, }); } @@ -156,7 +158,7 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // corpus (conformance/v1/invalid/dangling-exit). The platform's // pre-consolidation copy emitted `unknown_exit_target`; the corpus // is authoritative, so the code is reconciled here. - code: 'unknown_target', + code: "unknown_target", message: `node "${id}" exit "${exit}" points at "${target}", which is not a node`, params: { exit, target }, }); @@ -165,17 +167,17 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // Per-component config sanity. switch (node.kind) { - case 'greeting': - case 'message': + case "greeting": + case "message": checkPrompt(id, node.prompt, issues, at); break; - case 'menu': { + case "menu": { checkPrompt(id, node.prompt, issues, at); const digits = Object.keys(node.options); if (digits.length === 0) { issues.push({ ...at(id), - code: 'empty_menu', + code: "empty_menu", message: `menu node "${id}" offers no options`, }); } @@ -183,7 +185,7 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { if (!VALID_DIGITS.includes(digit)) { issues.push({ ...at(id), - code: 'bad_digit', + code: "bad_digit", message: `menu node "${id}" option key "${digit}" is not a DTMF digit (0-9, *, #)`, params: { key: digit }, }); @@ -191,42 +193,69 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { } break; } - case 'hours': + case "hours": issues.push( - ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map((issue) => ({ + ...validateHours( + id, + node.schedule, + node.timezone, + node.exceptions ?? [], + ).map((issue) => ({ ...issue, range: nodeRanges[id], })), ); break; - case 'transfer': - if (node.target.trim() === '') { + case "transfer": + if (node.target.trim() === "") { issues.push({ ...at(id), - code: 'empty_transfer_target', + code: "empty_transfer_target", message: `transfer node "${id}" has an empty target`, }); } checkTransferFields(id, node, flow.schema_version, issues, at); break; - case 'hangup': + case "hangup": if (node.prompt !== undefined) checkPrompt(id, node.prompt, issues, at); break; - case 'book': + case "book": checkPrompt(id, node.prompt, issues, at); checkPrompt(id, node.confirm_prompt, issues, at); issues.push( - ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map((issue) => ({ + ...validateHours( + id, + node.schedule, + node.timezone, + node.exceptions ?? [], + ).map((issue) => ({ ...issue, range: nodeRanges[id], })), ); checkBookBounds(id, node, issues, at); break; - case 'ring': + case "ring": break; } + if ( + flow.schema_version < TEMPLATE_MIN_SCHEMA_VERSION && + nodePrompts(node).some((p) => promptTemplate(p) !== null) + ) { + issues.push({ + ...at(id), + code: "field_requires_newer_schema", + message: `node "${id}" gives a prompt a template, which needs schema_version ${TEMPLATE_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, + params: { + field: "template", + required: TEMPLATE_MIN_SCHEMA_VERSION, + declared: flow.schema_version, + }, + }); + } + checkPlaceholders(id, node, flow, issues, at, mentioned); + // A component the document's own version doesn't have. Checked per // node rather than once per flow so the editor points at the step // that has to change, and separate from `unknown_kind` (which a @@ -236,9 +265,13 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { if (minVersion !== undefined && flow.schema_version < minVersion) { issues.push({ ...at(id), - code: 'kind_requires_newer_schema', + code: "kind_requires_newer_schema", message: `node "${id}" is a ${node.kind} step, which needs schema_version ${minVersion} (this document declares ${flow.schema_version})`, - params: { kind: node.kind, required: minVersion, declared: flow.schema_version }, + params: { + kind: node.kind, + required: minVersion, + declared: flow.schema_version, + }, }); } } @@ -249,8 +282,8 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { for (const name of Object.keys(flow.variables ?? {})) { if (!mentioned.has(name)) { issues.push({ - severity: 'warning', - code: 'unused_variable', + severity: "warning", + code: "unused_variable", message: `variable "${name}" is declared but no prompt or menu label uses it`, params: { name }, }); @@ -273,7 +306,7 @@ function checkTransferFields( node: TransferNode, declared: number, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { if (node.whisper !== undefined) checkPrompt(id, node.whisper, issues, at); const timeout = node.timeout_secs; @@ -281,14 +314,17 @@ function checkTransferFields( if (node.whisper === undefined) { issues.push({ ...at(id), - code: 'timeout_without_whisper', + code: "timeout_without_whisper", message: `transfer node "${id}" sets timeout_secs but has no whisper to screen with`, }); } - if (timeout < MIN_TRANSFER_TIMEOUT_SECS || timeout > MAX_TRANSFER_TIMEOUT_SECS) { + if ( + timeout < MIN_TRANSFER_TIMEOUT_SECS || + timeout > MAX_TRANSFER_TIMEOUT_SECS + ) { issues.push({ ...at(id), - code: 'transfer_timeout_out_of_range', + code: "transfer_timeout_out_of_range", message: `transfer node "${id}" timeout_secs is ${timeout} (allowed: ${MIN_TRANSFER_TIMEOUT_SECS}–${MAX_TRANSFER_TIMEOUT_SECS})`, params: { value: timeout, @@ -299,13 +335,17 @@ function checkTransferFields( } } if (declared < TRANSFER_FIELDS_MIN_SCHEMA_VERSION) { - for (const field of ['whisper', 'timeout_secs'] as const) { + for (const field of ["whisper", "timeout_secs"] as const) { if (node[field] === undefined) continue; issues.push({ ...at(id), - code: 'field_requires_newer_schema', + code: "field_requires_newer_schema", message: `transfer node "${id}" sets ${field}, which needs schema_version ${TRANSFER_FIELDS_MIN_SCHEMA_VERSION} (this document declares ${declared})`, - params: { field, required: TRANSFER_FIELDS_MIN_SCHEMA_VERSION, declared }, + params: { + field, + required: TRANSFER_FIELDS_MIN_SCHEMA_VERSION, + declared, + }, }); } } @@ -325,32 +365,62 @@ function checkBookBounds( id: string, node: BookNode, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { - const range = (field: string, value: number, min: number, max: number): void => { + const range = ( + field: string, + value: number, + min: number, + max: number, + ): void => { if (value < min || value > max) { issues.push({ ...at(id), - code: 'book_out_of_range', + code: "book_out_of_range", message: `book node "${id}" ${field} is ${value} (allowed: ${min}–${max})`, params: { field, value, min, max }, }); } }; - range('duration_mins', node.duration_mins, MIN_BOOK_DURATION_MINS, MAX_BOOK_DURATION_MINS); - range('buffer_mins', node.buffer_mins ?? DEFAULT_BOOK_BUFFER_MINS, 0, MAX_BOOK_BUFFER_MINS); - range('lead_mins', node.lead_mins ?? DEFAULT_BOOK_LEAD_MINS, 0, MAX_BOOK_LEAD_MINS); - range('horizon_days', node.horizon_days ?? DEFAULT_BOOK_HORIZON_DAYS, 1, MAX_BOOK_HORIZON_DAYS); - range('max_offers', node.max_offers ?? DEFAULT_BOOK_MAX_OFFERS, 1, MAX_BOOK_OFFERS); + range( + "duration_mins", + node.duration_mins, + MIN_BOOK_DURATION_MINS, + MAX_BOOK_DURATION_MINS, + ); + range( + "buffer_mins", + node.buffer_mins ?? DEFAULT_BOOK_BUFFER_MINS, + 0, + MAX_BOOK_BUFFER_MINS, + ); + range( + "lead_mins", + node.lead_mins ?? DEFAULT_BOOK_LEAD_MINS, + 0, + MAX_BOOK_LEAD_MINS, + ); + range( + "horizon_days", + node.horizon_days ?? DEFAULT_BOOK_HORIZON_DAYS, + 1, + MAX_BOOK_HORIZON_DAYS, + ); + range( + "max_offers", + node.max_offers ?? DEFAULT_BOOK_MAX_OFFERS, + 1, + MAX_BOOK_OFFERS, + ); const speaksATime = bookVocabularyRefs(node).some( - (ref) => parseBookVocabularyRef(ref)?.kind === 'time', + (ref) => parseBookVocabularyRef(ref)?.kind === "time", ); if (!speaksATime) { issues.push({ ...at(id), - code: 'book_never_open', + code: "book_never_open", message: `book node "${id}" can never offer an appointment: no opening leaves room for ${node.duration_mins} minutes`, params: { duration: node.duration_mins }, }); @@ -365,27 +435,32 @@ function checkVariables(flow: Flow, issues: Issue[]): void { for (const name of Object.keys(flow.variables ?? {}).sort()) { if (!isVariableName(name)) { issues.push({ - severity: 'error', - code: 'variable_bad_name', + severity: "error", + code: "variable_bad_name", message: `variable name "${name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, params: { name }, }); } const maxLen = flow.variables?.[name]?.max_len; - if (maxLen !== undefined && (!Number.isInteger(maxLen) || maxLen < 1 || maxLen > MAX_VARIABLE_LEN)) { + if ( + maxLen !== undefined && + (!Number.isInteger(maxLen) || maxLen < 1 || maxLen > MAX_VARIABLE_LEN) + ) { issues.push({ - severity: 'error', - code: 'variable_max_len_out_of_range', + severity: "error", + code: "variable_max_len_out_of_range", message: `variable "${name}" max_len is ${maxLen} (allowed: 1-${MAX_VARIABLE_LEN})`, params: { name, value: maxLen }, }); } } - const fields = (['id', 'name'] as const).filter((k) => flow[k].includes('{{')).sort(); + const fields = (["id", "name"] as const) + .filter((k) => flow[k].includes("{{")) + .sort(); if (fields.length > 0) { issues.push({ - severity: 'error', - code: 'placeholder_not_allowed', + severity: "error", + code: "placeholder_not_allowed", message: `${JSON.stringify(fields)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, params: { fields }, }); @@ -401,7 +476,7 @@ function checkPlaceholders( node: Node, flow: Flow, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, mentioned: Set, ): void { if (flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) return; @@ -413,48 +488,49 @@ function checkPlaceholders( if (!Object.hasOwn(flow.variables ?? {}, name)) { issues.push({ ...at(id), - code: 'unknown_variable', + code: "unknown_variable", message: `node "${id}" ${field} uses "${name}", which the flow does not declare under variables`, params: { field, name }, }); } } - } else if (error.kind === 'bad_name') { + } else if (error.kind === "bad_name") { issues.push({ ...at(id), - code: 'variable_bad_name', + code: "variable_bad_name", message: `variable name "${error.name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, params: { name: error.name }, }); } else { issues.push({ ...at(id), - code: 'template_syntax', + code: "template_syntax", message: `node "${id}" ${field} has a malformed placeholder: ${TEMPLATE_REASONS[error.kind]}`, params: { field, reason: TEMPLATE_REASONS[error.kind] }, }); } }; for (const [field, prompt] of nodePromptSlots(node)) { - if (typeof prompt === 'string') scan(field, prompt); - else if (typeof prompt.template === 'string') scan(`${field}.template`, prompt.template); + if (typeof prompt === "string") scan(field, prompt); + else if (typeof prompt.template === "string") + scan(`${field}.template`, prompt.template); } - if (node.kind === 'menu') { + if (node.kind === "menu") { for (const key of Object.keys(node.options).sort()) { - scan(`options.${key}`, node.options[key] ?? ''); + scan(`options.${key}`, node.options[key] ?? ""); } } // Everything else: any string value holding `{{` is out of place. const bad: string[] = []; for (const [key, value] of Object.entries(node)) { - if (key !== 'exits' && key !== 'kind') collectStrayBraces(key, value, bad); + if (key !== "exits" && key !== "kind") collectStrayBraces(key, value, bad); } bad.sort(); if (bad.length > 0) { issues.push({ ...at(id), - code: 'placeholder_not_allowed', + code: "placeholder_not_allowed", message: `node "${id}" ${JSON.stringify(bad)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, params: { fields: bad }, }); @@ -462,27 +538,27 @@ function checkPlaceholders( } const TEMPLATE_REASONS = { - unclosed: 'a `{{` or block is never closed', - nested: 'blocks cannot be nested', - mismatched: 'a block close does not match an open block', + unclosed: "a `{{` or block is never closed", + nested: "blocks cannot be nested", + mismatched: "a block close does not match an open block", } as const; /** The prompt slots of a node with the field each comes from. */ function nodePromptSlots(node: Node): [string, Prompt][] { switch (node.kind) { - case 'greeting': - case 'menu': - case 'message': - return [['prompt', node.prompt]]; - case 'hangup': - return node.prompt === undefined ? [] : [['prompt', node.prompt]]; - case 'book': + case "greeting": + case "menu": + case "message": + return [["prompt", node.prompt]]; + case "hangup": + return node.prompt === undefined ? [] : [["prompt", node.prompt]]; + case "book": return [ - ['prompt', node.prompt], - ['confirm_prompt', node.confirm_prompt], + ["prompt", node.prompt], + ["confirm_prompt", node.confirm_prompt], ]; - case 'transfer': - return node.whisper === undefined ? [] : [['whisper', node.whisper]]; + case "transfer": + return node.whisper === undefined ? [] : [["whisper", node.whisper]]; default: return []; } @@ -492,18 +568,19 @@ function nodePromptSlots(node: Node): [string, Prompt][] { * where a placeholder is allowed: a plain-string `prompt`, `confirm_prompt` * or `whisper`, any `.template`, and menu `options`. */ function collectStrayBraces(path: string, value: unknown, out: string[]): void { - if (typeof value === 'string') { + if (typeof value === "string") { const allowed = - path === 'prompt' || - path === 'confirm_prompt' || - path === 'whisper' || - path.endsWith('.template') || - path.startsWith('options.'); - if (value.includes('{{') && !allowed) out.push(path); + path === "prompt" || + path === "confirm_prompt" || + path === "whisper" || + path.endsWith(".template") || + path.startsWith("options."); + if (value.includes("{{") && !allowed) out.push(path); } else if (Array.isArray(value)) { value.forEach((item, i) => collectStrayBraces(`${path}.${i}`, item, out)); - } else if (value !== null && typeof value === 'object') { - for (const [key, item] of Object.entries(value)) collectStrayBraces(`${path}.${key}`, item, out); + } else if (value !== null && typeof value === "object") { + for (const [key, item] of Object.entries(value)) + collectStrayBraces(`${path}.${key}`, item, out); } } @@ -511,7 +588,7 @@ function checkPrompt( id: string, prompt: Prompt, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { const text = promptText(prompt); if (text !== null) { @@ -519,7 +596,7 @@ function checkPrompt( if (len > MAX_PROMPT_CHARS) { issues.push({ ...at(id), - code: 'prompt_too_long', + code: "prompt_too_long", message: `node "${id}" prompt is ${len} chars (max ${MAX_PROMPT_CHARS})`, params: { len, max: MAX_PROMPT_CHARS }, }); @@ -531,7 +608,7 @@ function checkPrompt( function checkGraph( flow: Flow, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { const reachable = reachableFromEntry(flow); @@ -539,7 +616,7 @@ function checkGraph( if (!reachable.has(id)) { issues.push({ ...at(id), - code: 'unreachable', + code: "unreachable", message: `node "${id}" is unreachable from entry`, }); } @@ -557,7 +634,9 @@ function checkGraph( grew = false; for (const [id, node] of Object.entries(flow.nodes)) { if (canEnd.has(id)) continue; - if (Object.values(node.exits ?? {}).some((target) => canEnd.has(target))) { + if ( + Object.values(node.exits ?? {}).some((target) => canEnd.has(target)) + ) { canEnd.add(id); grew = true; } @@ -571,7 +650,7 @@ function checkGraph( if (!canEnd.has(id)) { issues.push({ ...at(id), - code: 'trapped', + code: "trapped", message: `node "${id}" can never reach a way to end the call (caller trapped)`, }); } @@ -614,14 +693,18 @@ function reachableFromEntry(flow: Flow): Set { * version 3). */ export const OUTBOUND_KINDS: readonly ComponentKind[] = [ - 'greeting', - 'menu', - 'message', - 'hangup', - 'hours', + "greeting", + "menu", + "message", + "hangup", + "hours", ]; -const OUTBOUND_KINDS_V3: readonly ComponentKind[] = [...OUTBOUND_KINDS, 'ring', 'transfer']; +const OUTBOUND_KINDS_V3: readonly ComponentKind[] = [ + ...OUTBOUND_KINDS, + "ring", + "transfer", +]; /** * The kinds a flow declaring `schemaVersion` may use on an outbound call. @@ -657,10 +740,13 @@ export function outboundKinds(schemaVersion: number): readonly ComponentKind[] { * * Twin: `validate.rs` `validate_outbound`. */ -export function validateOutbound(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { +export function validateOutbound( + flow: Flow, + nodeRanges: NodeRanges = {}, +): Issue[] { const issues = validateFlow(flow, nodeRanges); - const at = (node: string): Pick => ({ - severity: 'error', + const at = (node: string): Pick => ({ + severity: "error", node, range: nodeRanges[node], }); @@ -672,14 +758,14 @@ export function validateOutbound(flow: Flow, nodeRanges: NodeRanges = {}): Issue if (!allowed.includes(node.kind as ComponentKind)) { issues.push({ ...at(id), - code: 'outbound_node_not_allowed', + code: "outbound_node_not_allowed", message: `node "${id}" is a ${node.kind} step, which an outbound call cannot run`, params: { kind: node.kind }, }); - } else if (node.kind === 'transfer' && !isScreenedTransfer(node)) { + } else if (node.kind === "transfer" && !isScreenedTransfer(node)) { issues.push({ ...at(id), - code: 'outbound_blind_transfer', + code: "outbound_blind_transfer", message: `transfer node "${id}" has no whisper: an outbound call must screen the person it hands the callee to`, }); } @@ -688,7 +774,7 @@ export function validateOutbound(flow: Flow, nodeRanges: NodeRanges = {}): Issue for (const id of unboundedLoopNodes(flow)) { issues.push({ ...at(id), - code: 'outbound_unbounded_loop', + code: "outbound_unbounded_loop", message: `node "${id}" is on a loop that never waits for the callee, so an outbound call could repeat it forever`, }); } @@ -700,18 +786,20 @@ export function validateOutbound(flow: Flow, nodeRanges: NodeRanges = {}): Issue * a `greeting` (always `next`), `hours` (picked by the clock), `ring` or * screened `transfer` step (`no_answer`: nobody picked up), and a * `menu`'s `no_input` (taken when nobody presses a key — voicemail, say). */ -function silentExits(node: Flow['nodes'][string] | undefined): string[] { +function silentExits(node: Flow["nodes"][string] | undefined): string[] { if (!node) return []; const exits = Object.entries(node.exits ?? {}); switch (node.kind) { - case 'greeting': - case 'hours': - case 'ring': + case "greeting": + case "hours": + case "ring": return exits.map(([, target]) => target); - case 'transfer': + case "transfer": return isScreenedTransfer(node) ? exits.map(([, target]) => target) : []; - case 'menu': - return exits.filter(([key]) => key === 'no_input').map(([, target]) => target); + case "menu": + return exits + .filter(([key]) => key === "no_input") + .map(([, target]) => target); default: return []; } diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts index fa48f71..c4ad9f4 100644 --- a/packages/flow-schema/test/vars.test.ts +++ b/packages/flow-schema/test/vars.test.ts @@ -1,54 +1,88 @@ -import { describe, expect, it } from 'vitest'; - -import { checkFlow } from '../src/check.js'; -import { parseTemplate, templateIssues, templateNames, tryParseTemplate } from '../src/vars.js'; - -describe('parseTemplate', () => { - it('parses text, vars and blocks', () => { - expect(parseTemplate('Hi {{a}}.{{#b}} B={{b}}{{/b}}')).toEqual([ - { kind: 'text', text: 'Hi ' }, - { kind: 'var', name: 'a' }, - { kind: 'text', text: '.' }, +import { describe, expect, it } from "vitest"; + +import { checkFlow } from "../src/check.js"; +import { + parseTemplate, + templateIssues, + templateNames, + tryParseTemplate, +} from "../src/vars.js"; + +describe("parseTemplate", () => { + it("parses text, vars and blocks", () => { + expect(parseTemplate("Hi {{a}}.{{#b}} B={{b}}{{/b}}")).toEqual([ + { kind: "text", text: "Hi " }, + { kind: "var", name: "a" }, + { kind: "text", text: "." }, { - kind: 'block', - name: 'b', + kind: "block", + name: "b", body: [ - { kind: 'text', text: ' B=' }, - { kind: 'var', name: 'b' }, + { kind: "text", text: " B=" }, + { kind: "var", name: "b" }, ], }, ]); }); - it('passes plain text and stray closers through', () => { - expect(parseTemplate('')).toEqual([]); - expect(parseTemplate('a }} b')).toEqual([{ kind: 'text', text: 'a }} b' }]); + it("passes plain text and stray closers through", () => { + expect(parseTemplate("")).toEqual([]); + expect(parseTemplate("a }} b")).toEqual([{ kind: "text", text: "a }} b" }]); }); - it('rejects nested and unclosed blocks', () => { - expect(tryParseTemplate('{{#a}}{{#b}}{{/b}}{{/a}}').error).toEqual({ kind: 'nested' }); - expect(tryParseTemplate('{{#a}} x').error).toEqual({ kind: 'unclosed' }); - expect(tryParseTemplate('{{a').error).toEqual({ kind: 'unclosed' }); + it("rejects nested and unclosed blocks", () => { + expect(tryParseTemplate("{{#a}}{{#b}}{{/b}}{{/a}}").error).toEqual({ + kind: "nested", + }); + expect(tryParseTemplate("{{#a}} x").error).toEqual({ kind: "unclosed" }); + expect(tryParseTemplate("{{a").error).toEqual({ kind: "unclosed" }); }); - it('rejects mismatched closers', () => { - expect(tryParseTemplate('{{/a}}').error).toEqual({ kind: 'mismatched', name: 'a' }); - expect(tryParseTemplate('{{#a}}{{/b}}').error).toEqual({ kind: 'mismatched', name: 'b' }); + it("rejects mismatched closers", () => { + expect(tryParseTemplate("{{/a}}").error).toEqual({ + kind: "mismatched", + name: "a", + }); + expect(tryParseTemplate("{{#a}}{{/b}}").error).toEqual({ + kind: "mismatched", + name: "b", + }); }); - it('rejects bad names', () => { - expect(tryParseTemplate('{{A}}').error).toEqual({ kind: 'bad_name', name: 'A' }); - expect(tryParseTemplate('{{1a}}').error).toEqual({ kind: 'bad_name', name: '1a' }); - expect(tryParseTemplate('{{}}').error).toEqual({ kind: 'bad_name', name: '' }); - expect(tryParseTemplate(`{{${'a'.repeat(32)}}}`).error).toBeNull(); - expect(tryParseTemplate(`{{${'a'.repeat(33)}}}`).error).not.toBeNull(); + it("rejects bad names", () => { + expect(tryParseTemplate("{{A}}").error).toEqual({ + kind: "bad_name", + name: "A", + }); + expect(tryParseTemplate("{{1a}}").error).toEqual({ + kind: "bad_name", + name: "1a", + }); + expect(tryParseTemplate("{{}}").error).toEqual({ + kind: "bad_name", + name: "", + }); + expect(tryParseTemplate(`{{${"a".repeat(32)}}}`).error).toBeNull(); + expect(tryParseTemplate(`{{${"a".repeat(33)}}}`).error).not.toBeNull(); }); - it('reports codes and names', () => { - expect(templateIssues('{{a}}')).toEqual([]); - expect(templateIssues('{{a')).toEqual(['template_syntax']); - expect(templateIssues('{{A}}')).toEqual(['variable_bad_name']); - expect(templateNames('{{b}} {{#a}}{{a}}{{/a}} {{b}}')).toEqual(['b', 'a']); + it("handles brace edge cases like the Rust twin", () => { + expect(tryParseTemplate("{{{a}}}").error).toEqual({ + kind: "bad_name", + name: "{a", + }); + expect(parseTemplate("{ {a} }")).toEqual([ + { kind: "text", text: "{ {a} }" }, + ]); + expect(parseTemplate("}}")).toEqual([{ kind: "text", text: "}}" }]); + expect(tryParseTemplate("{{#a}} x {{").error).toEqual({ kind: "unclosed" }); + }); + + it("reports codes and names", () => { + expect(templateIssues("{{a}}")).toEqual([]); + expect(templateIssues("{{a")).toEqual(["template_syntax"]); + expect(templateIssues("{{A}}")).toEqual(["variable_bad_name"]); + expect(templateNames("{{b}} {{#a}}{{a}}{{/a}} {{b}}")).toEqual(["b", "a"]); }); }); @@ -57,60 +91,78 @@ const flow = (version: number, vars: string, body: string) => function errorCodes(src: string): string[] { return checkFlow(src) - .issues.filter((i) => i.severity === 'error') + .issues.filter((i) => i.severity === "error") .map((i) => i.code); } -const Q = 'variables:\n q: { default: x }\n'; -const HANGUP = (prompt: string) => ` a:\n kind: hangup\n prompt: ${prompt}\n`; +const Q = "variables:\n q: { default: x }\n"; +const HANGUP = (prompt: string) => + ` a:\n kind: hangup\n prompt: ${prompt}\n`; -describe('placeholders in a flow', () => { - it('v4 placeholder must be declared', () => { - expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}} {{ghost}}"')))).toEqual(['unknown_variable']); +describe("placeholders in a flow", () => { + it("v4 placeholder must be declared", () => { + expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}} {{ghost}}"')))).toEqual([ + "unknown_variable", + ]); expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}}"')))).toEqual([]); }); - it('scans menu labels and templates', () => { + it("scans menu labels and templates", () => { const body = ' a:\n kind: menu\n prompt: { audio: vprompt_ab12, template: "{{nope}}" }\n options: { "1": "{{q}}", "2": "{{bad}}" }\n exits: { "1": b, "2": b, no_input: b, invalid: b }\n b:\n kind: hangup\n prompt: bye\n'; - expect(errorCodes(flow(4, Q, body))).toEqual(['unknown_variable', 'unknown_variable']); + expect(errorCodes(flow(4, Q, body))).toEqual([ + "unknown_variable", + "unknown_variable", + ]); }); - it('reports bad syntax and names', () => { - expect(errorCodes(flow(4, Q, HANGUP('"{{#q}} open"')))).toEqual(['template_syntax']); - expect(errorCodes(flow(4, Q, HANGUP('"{{Q}}"')))).toEqual(['variable_bad_name']); + it("reports bad syntax and names", () => { + expect(errorCodes(flow(4, Q, HANGUP('"{{#q}} open"')))).toEqual([ + "template_syntax", + ]); + expect(errorCodes(flow(4, Q, HANGUP('"{{Q}}"')))).toEqual([ + "variable_bad_name", + ]); }); - it('checks declared names and max_len', () => { - const body = HANGUP('bye'); - expect(errorCodes(flow(4, 'variables:\n Bad: { default: "" }\n', body))).toEqual([ - 'variable_bad_name', - ]); + it("checks declared names and max_len", () => { + const body = HANGUP("bye"); + expect( + errorCodes(flow(4, 'variables:\n Bad: { default: "" }\n', body)), + ).toEqual(["variable_bad_name"]); expect( - errorCodes(flow(4, 'variables:\n q: { default: "", max_len: 501 }\n', body)), - ).toContain('variable_max_len_out_of_range'); + errorCodes( + flow(4, 'variables:\n q: { default: "", max_len: 501 }\n', body), + ), + ).toContain("variable_max_len_out_of_range"); }); - it('refuses placeholders in a transfer target and a transcript', () => { - expect(errorCodes(flow(4, Q, ' a:\n kind: transfer\n target: "{{q}}"\n'))).toEqual([ - 'placeholder_not_allowed', - ]); + it("refuses placeholders in a transfer target and a transcript", () => { + expect( + errorCodes(flow(4, Q, ' a:\n kind: transfer\n target: "{{q}}"\n')), + ).toEqual(["placeholder_not_allowed"]); expect( - errorCodes(flow(4, Q, HANGUP('{ audio: vprompt_ab12, transcript: "Hi {{q}}" }'))), - ).toEqual(['placeholder_not_allowed']); + errorCodes( + flow(4, Q, HANGUP('{ audio: vprompt_ab12, transcript: "Hi {{q}}" }')), + ), + ).toEqual(["placeholder_not_allowed"]); }); - it('treats braces as plain text before v4', () => { - expect(errorCodes(flow(3, '', HANGUP('"Press {{1}} now }} {{#x"')))).toEqual([]); + it("treats braces as plain text before v4", () => { + expect( + errorCodes(flow(3, "", HANGUP('"Press {{1}} now }} {{#x"'))), + ).toEqual([]); }); - it('warns about a variable nothing uses', () => { - const issues = checkFlow(flow(4, Q, HANGUP('bye'))).issues; - expect(issues.filter((i) => i.code === 'unused_variable')).toMatchObject([ - { severity: 'warning', params: { name: 'q' } }, + it("warns about a variable nothing uses", () => { + const issues = checkFlow(flow(4, Q, HANGUP("bye"))).issues; + expect(issues.filter((i) => i.code === "unused_variable")).toMatchObject([ + { severity: "warning", params: { name: "q" } }, ]); expect( - checkFlow(flow(4, Q, HANGUP('"{{#q}}x{{/q}}"'))).issues.some((i) => i.code === 'unused_variable'), + checkFlow(flow(4, Q, HANGUP('"{{#q}}x{{/q}}"'))).issues.some( + (i) => i.code === "unused_variable", + ), ).toBe(false); }); }); From 5baad1af38044d1b1df998fcbbaeca5081b74f1d Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:46:52 +1300 Subject: [PATCH 06/13] fix: restore repo prettier style in flow-schema --- packages/flow-schema/src/validate.ts | 341 ++++++++++--------------- packages/flow-schema/src/vars.ts | 4 +- packages/flow-schema/test/vars.test.ts | 195 +++++++------- 3 files changed, 224 insertions(+), 316 deletions(-) diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 15aec36..aceb6be 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -12,14 +12,7 @@ // and menu/hours sanity caps. All problems are collected (not // fail-fast) so the editor can show every one at once. -import type { - BookNode, - ComponentKind, - Flow, - Node, - Prompt, - TransferNode, -} from "./model.js"; +import type { BookNode, ComponentKind, Flow, Node, Prompt, TransferNode } from './model.js'; import { KIND_MIN_SCHEMA_VERSION, MAX_PROMPT_CHARS, @@ -38,7 +31,7 @@ import { promptTemplate, promptText, requiredExits, -} from "./model.js"; +} from './model.js'; import { DEFAULT_BOOK_BUFFER_MINS, DEFAULT_BOOK_HORIZON_DAYS, @@ -52,10 +45,10 @@ import { MIN_BOOK_DURATION_MINS, bookVocabularyRefs, parseBookVocabularyRef, -} from "./book.js"; -import type { Issue } from "./issues.js"; -import { isVariableName, templateNames, tryParseTemplate } from "./vars.js"; -import { validateHours } from "./hours.js"; +} from './book.js'; +import type { Issue } from './issues.js'; +import { isVariableName, templateNames, tryParseTemplate } from './vars.js'; +import { validateHours } from './hours.js'; type NodeRanges = Record; @@ -66,16 +59,16 @@ type NodeRanges = Record; */ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { const issues: Issue[] = []; - const at = (node: string): Pick => ({ - severity: "error", + const at = (node: string): Pick => ({ + severity: 'error', node, range: nodeRanges[node], }); if (!SUPPORTED_SCHEMA_VERSIONS.includes(flow.schema_version)) { issues.push({ - severity: "error", - code: "unsupported_schema_version", + severity: 'error', + code: 'unsupported_schema_version', message: `schema_version ${flow.schema_version} is not supported`, params: { version: flow.schema_version }, }); @@ -83,16 +76,13 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // Flow-level, so it carries no node. Same code as a transfer field on an // older document: the field needs a newer version than the one declared. - if ( - hasVariables(flow) && - flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION - ) { + if (hasVariables(flow) && flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) { issues.push({ - severity: "error", - code: "field_requires_newer_schema", + severity: 'error', + code: 'field_requires_newer_schema', message: `variables needs schema_version ${VARIABLES_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, params: { - field: "variables", + field: 'variables', required: VARIABLES_MIN_SCHEMA_VERSION, declared: flow.schema_version, }, @@ -105,9 +95,9 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { const nodeIds = Object.keys(flow.nodes); if (nodeIds.length === 0) { issues.push({ - severity: "error", - code: "empty_flow", - message: "flow has no nodes", + severity: 'error', + code: 'empty_flow', + message: 'flow has no nodes', }); return issues; // graph checks below would be meaningless } @@ -115,8 +105,8 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { const entryExists = flow.entry in flow.nodes; if (!entryExists) { issues.push({ - severity: "error", - code: "missing_entry", + severity: 'error', + code: 'missing_entry', message: `entry "${flow.entry}" is not a node`, params: { entry: flow.entry }, }); @@ -128,25 +118,21 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // every target must exist. const requiredNames = new Set(requiredExits(node)); const presentNames = new Set(Object.keys(exits)); - const missing = [...requiredNames] - .filter((name) => !presentNames.has(name)) - .sort(); + const missing = [...requiredNames].filter((name) => !presentNames.has(name)).sort(); if (missing.length > 0) { issues.push({ ...at(id), - code: "missing_exits", - message: `node "${id}" (${node.kind}) is missing required exits: ${missing.join(", ")}`, + code: 'missing_exits', + message: `node "${id}" (${node.kind}) is missing required exits: ${missing.join(', ')}`, params: { kind: node.kind, missing }, }); } - const unexpected = [...presentNames] - .filter((name) => !requiredNames.has(name)) - .sort(); + const unexpected = [...presentNames].filter((name) => !requiredNames.has(name)).sort(); if (unexpected.length > 0) { issues.push({ ...at(id), - code: "unexpected_exits", - message: `node "${id}" (${node.kind}) has exits it does not define: ${unexpected.join(", ")}`, + code: 'unexpected_exits', + message: `node "${id}" (${node.kind}) has exits it does not define: ${unexpected.join(', ')}`, params: { kind: node.kind, unexpected }, }); } @@ -158,7 +144,7 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // corpus (conformance/v1/invalid/dangling-exit). The platform's // pre-consolidation copy emitted `unknown_exit_target`; the corpus // is authoritative, so the code is reconciled here. - code: "unknown_target", + code: 'unknown_target', message: `node "${id}" exit "${exit}" points at "${target}", which is not a node`, params: { exit, target }, }); @@ -167,17 +153,17 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { // Per-component config sanity. switch (node.kind) { - case "greeting": - case "message": + case 'greeting': + case 'message': checkPrompt(id, node.prompt, issues, at); break; - case "menu": { + case 'menu': { checkPrompt(id, node.prompt, issues, at); const digits = Object.keys(node.options); if (digits.length === 0) { issues.push({ ...at(id), - code: "empty_menu", + code: 'empty_menu', message: `menu node "${id}" offers no options`, }); } @@ -185,7 +171,7 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { if (!VALID_DIGITS.includes(digit)) { issues.push({ ...at(id), - code: "bad_digit", + code: 'bad_digit', message: `menu node "${id}" option key "${digit}" is not a DTMF digit (0-9, *, #)`, params: { key: digit }, }); @@ -193,49 +179,43 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { } break; } - case "hours": + case 'hours': issues.push( - ...validateHours( - id, - node.schedule, - node.timezone, - node.exceptions ?? [], - ).map((issue) => ({ - ...issue, - range: nodeRanges[id], - })), + ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map( + (issue) => ({ + ...issue, + range: nodeRanges[id], + }), + ), ); break; - case "transfer": - if (node.target.trim() === "") { + case 'transfer': + if (node.target.trim() === '') { issues.push({ ...at(id), - code: "empty_transfer_target", + code: 'empty_transfer_target', message: `transfer node "${id}" has an empty target`, }); } checkTransferFields(id, node, flow.schema_version, issues, at); break; - case "hangup": + case 'hangup': if (node.prompt !== undefined) checkPrompt(id, node.prompt, issues, at); break; - case "book": + case 'book': checkPrompt(id, node.prompt, issues, at); checkPrompt(id, node.confirm_prompt, issues, at); issues.push( - ...validateHours( - id, - node.schedule, - node.timezone, - node.exceptions ?? [], - ).map((issue) => ({ - ...issue, - range: nodeRanges[id], - })), + ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map( + (issue) => ({ + ...issue, + range: nodeRanges[id], + }), + ), ); checkBookBounds(id, node, issues, at); break; - case "ring": + case 'ring': break; } @@ -245,10 +225,10 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { ) { issues.push({ ...at(id), - code: "field_requires_newer_schema", + code: 'field_requires_newer_schema', message: `node "${id}" gives a prompt a template, which needs schema_version ${TEMPLATE_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, params: { - field: "template", + field: 'template', required: TEMPLATE_MIN_SCHEMA_VERSION, declared: flow.schema_version, }, @@ -265,7 +245,7 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { if (minVersion !== undefined && flow.schema_version < minVersion) { issues.push({ ...at(id), - code: "kind_requires_newer_schema", + code: 'kind_requires_newer_schema', message: `node "${id}" is a ${node.kind} step, which needs schema_version ${minVersion} (this document declares ${flow.schema_version})`, params: { kind: node.kind, @@ -282,8 +262,8 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { for (const name of Object.keys(flow.variables ?? {})) { if (!mentioned.has(name)) { issues.push({ - severity: "warning", - code: "unused_variable", + severity: 'warning', + code: 'unused_variable', message: `variable "${name}" is declared but no prompt or menu label uses it`, params: { name }, }); @@ -306,7 +286,7 @@ function checkTransferFields( node: TransferNode, declared: number, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { if (node.whisper !== undefined) checkPrompt(id, node.whisper, issues, at); const timeout = node.timeout_secs; @@ -314,17 +294,14 @@ function checkTransferFields( if (node.whisper === undefined) { issues.push({ ...at(id), - code: "timeout_without_whisper", + code: 'timeout_without_whisper', message: `transfer node "${id}" sets timeout_secs but has no whisper to screen with`, }); } - if ( - timeout < MIN_TRANSFER_TIMEOUT_SECS || - timeout > MAX_TRANSFER_TIMEOUT_SECS - ) { + if (timeout < MIN_TRANSFER_TIMEOUT_SECS || timeout > MAX_TRANSFER_TIMEOUT_SECS) { issues.push({ ...at(id), - code: "transfer_timeout_out_of_range", + code: 'transfer_timeout_out_of_range', message: `transfer node "${id}" timeout_secs is ${timeout} (allowed: ${MIN_TRANSFER_TIMEOUT_SECS}–${MAX_TRANSFER_TIMEOUT_SECS})`, params: { value: timeout, @@ -335,11 +312,11 @@ function checkTransferFields( } } if (declared < TRANSFER_FIELDS_MIN_SCHEMA_VERSION) { - for (const field of ["whisper", "timeout_secs"] as const) { + for (const field of ['whisper', 'timeout_secs'] as const) { if (node[field] === undefined) continue; issues.push({ ...at(id), - code: "field_requires_newer_schema", + code: 'field_requires_newer_schema', message: `transfer node "${id}" sets ${field}, which needs schema_version ${TRANSFER_FIELDS_MIN_SCHEMA_VERSION} (this document declares ${declared})`, params: { field, @@ -365,62 +342,32 @@ function checkBookBounds( id: string, node: BookNode, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { - const range = ( - field: string, - value: number, - min: number, - max: number, - ): void => { + const range = (field: string, value: number, min: number, max: number): void => { if (value < min || value > max) { issues.push({ ...at(id), - code: "book_out_of_range", + code: 'book_out_of_range', message: `book node "${id}" ${field} is ${value} (allowed: ${min}–${max})`, params: { field, value, min, max }, }); } }; - range( - "duration_mins", - node.duration_mins, - MIN_BOOK_DURATION_MINS, - MAX_BOOK_DURATION_MINS, - ); - range( - "buffer_mins", - node.buffer_mins ?? DEFAULT_BOOK_BUFFER_MINS, - 0, - MAX_BOOK_BUFFER_MINS, - ); - range( - "lead_mins", - node.lead_mins ?? DEFAULT_BOOK_LEAD_MINS, - 0, - MAX_BOOK_LEAD_MINS, - ); - range( - "horizon_days", - node.horizon_days ?? DEFAULT_BOOK_HORIZON_DAYS, - 1, - MAX_BOOK_HORIZON_DAYS, - ); - range( - "max_offers", - node.max_offers ?? DEFAULT_BOOK_MAX_OFFERS, - 1, - MAX_BOOK_OFFERS, - ); + range('duration_mins', node.duration_mins, MIN_BOOK_DURATION_MINS, MAX_BOOK_DURATION_MINS); + range('buffer_mins', node.buffer_mins ?? DEFAULT_BOOK_BUFFER_MINS, 0, MAX_BOOK_BUFFER_MINS); + range('lead_mins', node.lead_mins ?? DEFAULT_BOOK_LEAD_MINS, 0, MAX_BOOK_LEAD_MINS); + range('horizon_days', node.horizon_days ?? DEFAULT_BOOK_HORIZON_DAYS, 1, MAX_BOOK_HORIZON_DAYS); + range('max_offers', node.max_offers ?? DEFAULT_BOOK_MAX_OFFERS, 1, MAX_BOOK_OFFERS); const speaksATime = bookVocabularyRefs(node).some( - (ref) => parseBookVocabularyRef(ref)?.kind === "time", + (ref) => parseBookVocabularyRef(ref)?.kind === 'time', ); if (!speaksATime) { issues.push({ ...at(id), - code: "book_never_open", + code: 'book_never_open', message: `book node "${id}" can never offer an appointment: no opening leaves room for ${node.duration_mins} minutes`, params: { duration: node.duration_mins }, }); @@ -435,8 +382,8 @@ function checkVariables(flow: Flow, issues: Issue[]): void { for (const name of Object.keys(flow.variables ?? {}).sort()) { if (!isVariableName(name)) { issues.push({ - severity: "error", - code: "variable_bad_name", + severity: 'error', + code: 'variable_bad_name', message: `variable name "${name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, params: { name }, }); @@ -447,20 +394,18 @@ function checkVariables(flow: Flow, issues: Issue[]): void { (!Number.isInteger(maxLen) || maxLen < 1 || maxLen > MAX_VARIABLE_LEN) ) { issues.push({ - severity: "error", - code: "variable_max_len_out_of_range", + severity: 'error', + code: 'variable_max_len_out_of_range', message: `variable "${name}" max_len is ${maxLen} (allowed: 1-${MAX_VARIABLE_LEN})`, params: { name, value: maxLen }, }); } } - const fields = (["id", "name"] as const) - .filter((k) => flow[k].includes("{{")) - .sort(); + const fields = (['id', 'name'] as const).filter((k) => flow[k].includes('{{')).sort(); if (fields.length > 0) { issues.push({ - severity: "error", - code: "placeholder_not_allowed", + severity: 'error', + code: 'placeholder_not_allowed', message: `${JSON.stringify(fields)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, params: { fields }, }); @@ -476,7 +421,7 @@ function checkPlaceholders( node: Node, flow: Flow, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, mentioned: Set, ): void { if (flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) return; @@ -488,49 +433,48 @@ function checkPlaceholders( if (!Object.hasOwn(flow.variables ?? {}, name)) { issues.push({ ...at(id), - code: "unknown_variable", + code: 'unknown_variable', message: `node "${id}" ${field} uses "${name}", which the flow does not declare under variables`, params: { field, name }, }); } } - } else if (error.kind === "bad_name") { + } else if (error.kind === 'bad_name') { issues.push({ ...at(id), - code: "variable_bad_name", + code: 'variable_bad_name', message: `variable name "${error.name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, params: { name: error.name }, }); } else { issues.push({ ...at(id), - code: "template_syntax", + code: 'template_syntax', message: `node "${id}" ${field} has a malformed placeholder: ${TEMPLATE_REASONS[error.kind]}`, params: { field, reason: TEMPLATE_REASONS[error.kind] }, }); } }; for (const [field, prompt] of nodePromptSlots(node)) { - if (typeof prompt === "string") scan(field, prompt); - else if (typeof prompt.template === "string") - scan(`${field}.template`, prompt.template); + if (typeof prompt === 'string') scan(field, prompt); + else if (typeof prompt.template === 'string') scan(`${field}.template`, prompt.template); } - if (node.kind === "menu") { + if (node.kind === 'menu') { for (const key of Object.keys(node.options).sort()) { - scan(`options.${key}`, node.options[key] ?? ""); + scan(`options.${key}`, node.options[key] ?? ''); } } // Everything else: any string value holding `{{` is out of place. const bad: string[] = []; for (const [key, value] of Object.entries(node)) { - if (key !== "exits" && key !== "kind") collectStrayBraces(key, value, bad); + if (key !== 'exits' && key !== 'kind') collectStrayBraces(key, value, bad); } bad.sort(); if (bad.length > 0) { issues.push({ ...at(id), - code: "placeholder_not_allowed", + code: 'placeholder_not_allowed', message: `node "${id}" ${JSON.stringify(bad)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, params: { fields: bad }, }); @@ -538,27 +482,27 @@ function checkPlaceholders( } const TEMPLATE_REASONS = { - unclosed: "a `{{` or block is never closed", - nested: "blocks cannot be nested", - mismatched: "a block close does not match an open block", + unclosed: 'a `{{` or block is never closed', + nested: 'blocks cannot be nested', + mismatched: 'a block close does not match an open block', } as const; /** The prompt slots of a node with the field each comes from. */ function nodePromptSlots(node: Node): [string, Prompt][] { switch (node.kind) { - case "greeting": - case "menu": - case "message": - return [["prompt", node.prompt]]; - case "hangup": - return node.prompt === undefined ? [] : [["prompt", node.prompt]]; - case "book": + case 'greeting': + case 'menu': + case 'message': + return [['prompt', node.prompt]]; + case 'hangup': + return node.prompt === undefined ? [] : [['prompt', node.prompt]]; + case 'book': return [ - ["prompt", node.prompt], - ["confirm_prompt", node.confirm_prompt], + ['prompt', node.prompt], + ['confirm_prompt', node.confirm_prompt], ]; - case "transfer": - return node.whisper === undefined ? [] : [["whisper", node.whisper]]; + case 'transfer': + return node.whisper === undefined ? [] : [['whisper', node.whisper]]; default: return []; } @@ -568,17 +512,17 @@ function nodePromptSlots(node: Node): [string, Prompt][] { * where a placeholder is allowed: a plain-string `prompt`, `confirm_prompt` * or `whisper`, any `.template`, and menu `options`. */ function collectStrayBraces(path: string, value: unknown, out: string[]): void { - if (typeof value === "string") { + if (typeof value === 'string') { const allowed = - path === "prompt" || - path === "confirm_prompt" || - path === "whisper" || - path.endsWith(".template") || - path.startsWith("options."); - if (value.includes("{{") && !allowed) out.push(path); + path === 'prompt' || + path === 'confirm_prompt' || + path === 'whisper' || + path.endsWith('.template') || + path.startsWith('options.'); + if (value.includes('{{') && !allowed) out.push(path); } else if (Array.isArray(value)) { value.forEach((item, i) => collectStrayBraces(`${path}.${i}`, item, out)); - } else if (value !== null && typeof value === "object") { + } else if (value !== null && typeof value === 'object') { for (const [key, item] of Object.entries(value)) collectStrayBraces(`${path}.${key}`, item, out); } @@ -588,7 +532,7 @@ function checkPrompt( id: string, prompt: Prompt, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { const text = promptText(prompt); if (text !== null) { @@ -596,7 +540,7 @@ function checkPrompt( if (len > MAX_PROMPT_CHARS) { issues.push({ ...at(id), - code: "prompt_too_long", + code: 'prompt_too_long', message: `node "${id}" prompt is ${len} chars (max ${MAX_PROMPT_CHARS})`, params: { len, max: MAX_PROMPT_CHARS }, }); @@ -608,7 +552,7 @@ function checkPrompt( function checkGraph( flow: Flow, issues: Issue[], - at: (node: string) => Pick, + at: (node: string) => Pick, ): void { const reachable = reachableFromEntry(flow); @@ -616,7 +560,7 @@ function checkGraph( if (!reachable.has(id)) { issues.push({ ...at(id), - code: "unreachable", + code: 'unreachable', message: `node "${id}" is unreachable from entry`, }); } @@ -634,9 +578,7 @@ function checkGraph( grew = false; for (const [id, node] of Object.entries(flow.nodes)) { if (canEnd.has(id)) continue; - if ( - Object.values(node.exits ?? {}).some((target) => canEnd.has(target)) - ) { + if (Object.values(node.exits ?? {}).some((target) => canEnd.has(target))) { canEnd.add(id); grew = true; } @@ -650,7 +592,7 @@ function checkGraph( if (!canEnd.has(id)) { issues.push({ ...at(id), - code: "trapped", + code: 'trapped', message: `node "${id}" can never reach a way to end the call (caller trapped)`, }); } @@ -693,18 +635,14 @@ function reachableFromEntry(flow: Flow): Set { * version 3). */ export const OUTBOUND_KINDS: readonly ComponentKind[] = [ - "greeting", - "menu", - "message", - "hangup", - "hours", + 'greeting', + 'menu', + 'message', + 'hangup', + 'hours', ]; -const OUTBOUND_KINDS_V3: readonly ComponentKind[] = [ - ...OUTBOUND_KINDS, - "ring", - "transfer", -]; +const OUTBOUND_KINDS_V3: readonly ComponentKind[] = [...OUTBOUND_KINDS, 'ring', 'transfer']; /** * The kinds a flow declaring `schemaVersion` may use on an outbound call. @@ -740,13 +678,10 @@ export function outboundKinds(schemaVersion: number): readonly ComponentKind[] { * * Twin: `validate.rs` `validate_outbound`. */ -export function validateOutbound( - flow: Flow, - nodeRanges: NodeRanges = {}, -): Issue[] { +export function validateOutbound(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { const issues = validateFlow(flow, nodeRanges); - const at = (node: string): Pick => ({ - severity: "error", + const at = (node: string): Pick => ({ + severity: 'error', node, range: nodeRanges[node], }); @@ -758,14 +693,14 @@ export function validateOutbound( if (!allowed.includes(node.kind as ComponentKind)) { issues.push({ ...at(id), - code: "outbound_node_not_allowed", + code: 'outbound_node_not_allowed', message: `node "${id}" is a ${node.kind} step, which an outbound call cannot run`, params: { kind: node.kind }, }); - } else if (node.kind === "transfer" && !isScreenedTransfer(node)) { + } else if (node.kind === 'transfer' && !isScreenedTransfer(node)) { issues.push({ ...at(id), - code: "outbound_blind_transfer", + code: 'outbound_blind_transfer', message: `transfer node "${id}" has no whisper: an outbound call must screen the person it hands the callee to`, }); } @@ -774,7 +709,7 @@ export function validateOutbound( for (const id of unboundedLoopNodes(flow)) { issues.push({ ...at(id), - code: "outbound_unbounded_loop", + code: 'outbound_unbounded_loop', message: `node "${id}" is on a loop that never waits for the callee, so an outbound call could repeat it forever`, }); } @@ -786,20 +721,18 @@ export function validateOutbound( * a `greeting` (always `next`), `hours` (picked by the clock), `ring` or * screened `transfer` step (`no_answer`: nobody picked up), and a * `menu`'s `no_input` (taken when nobody presses a key — voicemail, say). */ -function silentExits(node: Flow["nodes"][string] | undefined): string[] { +function silentExits(node: Flow['nodes'][string] | undefined): string[] { if (!node) return []; const exits = Object.entries(node.exits ?? {}); switch (node.kind) { - case "greeting": - case "hours": - case "ring": + case 'greeting': + case 'hours': + case 'ring': return exits.map(([, target]) => target); - case "transfer": + case 'transfer': return isScreenedTransfer(node) ? exits.map(([, target]) => target) : []; - case "menu": - return exits - .filter(([key]) => key === "no_input") - .map(([, target]) => target); + case 'menu': + return exits.filter(([key]) => key === 'no_input').map(([, target]) => target); default: return []; } diff --git a/packages/flow-schema/src/vars.ts b/packages/flow-schema/src/vars.ts index dd9f5da..81ff8e2 100644 --- a/packages/flow-schema/src/vars.ts +++ b/packages/flow-schema/src/vars.ts @@ -25,9 +25,7 @@ export function isVariableName(name: string): boolean { return NAME_RE.test(name); } -type Tok = - | { t: 'text'; v: string } - | { t: 'var' | 'open' | 'close'; v: string }; +type Tok = { t: 'text'; v: string } | { t: 'var' | 'open' | 'close'; v: string }; /** Split `s` into tokens. `unclosed` is true when a `{{` has no `}}`. */ function tokens(s: string): { toks: Tok[]; unclosed: boolean } { diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts index c4ad9f4..ba320d7 100644 --- a/packages/flow-schema/test/vars.test.ts +++ b/packages/flow-schema/test/vars.test.ts @@ -1,88 +1,81 @@ -import { describe, expect, it } from "vitest"; - -import { checkFlow } from "../src/check.js"; -import { - parseTemplate, - templateIssues, - templateNames, - tryParseTemplate, -} from "../src/vars.js"; - -describe("parseTemplate", () => { - it("parses text, vars and blocks", () => { - expect(parseTemplate("Hi {{a}}.{{#b}} B={{b}}{{/b}}")).toEqual([ - { kind: "text", text: "Hi " }, - { kind: "var", name: "a" }, - { kind: "text", text: "." }, +import { describe, expect, it } from 'vitest'; + +import { checkFlow } from '../src/check.js'; +import { parseTemplate, templateIssues, templateNames, tryParseTemplate } from '../src/vars.js'; + +describe('parseTemplate', () => { + it('parses text, vars and blocks', () => { + expect(parseTemplate('Hi {{a}}.{{#b}} B={{b}}{{/b}}')).toEqual([ + { kind: 'text', text: 'Hi ' }, + { kind: 'var', name: 'a' }, + { kind: 'text', text: '.' }, { - kind: "block", - name: "b", + kind: 'block', + name: 'b', body: [ - { kind: "text", text: " B=" }, - { kind: "var", name: "b" }, + { kind: 'text', text: ' B=' }, + { kind: 'var', name: 'b' }, ], }, ]); }); - it("passes plain text and stray closers through", () => { - expect(parseTemplate("")).toEqual([]); - expect(parseTemplate("a }} b")).toEqual([{ kind: "text", text: "a }} b" }]); + it('passes plain text and stray closers through', () => { + expect(parseTemplate('')).toEqual([]); + expect(parseTemplate('a }} b')).toEqual([{ kind: 'text', text: 'a }} b' }]); }); - it("rejects nested and unclosed blocks", () => { - expect(tryParseTemplate("{{#a}}{{#b}}{{/b}}{{/a}}").error).toEqual({ - kind: "nested", + it('rejects nested and unclosed blocks', () => { + expect(tryParseTemplate('{{#a}}{{#b}}{{/b}}{{/a}}').error).toEqual({ + kind: 'nested', }); - expect(tryParseTemplate("{{#a}} x").error).toEqual({ kind: "unclosed" }); - expect(tryParseTemplate("{{a").error).toEqual({ kind: "unclosed" }); + expect(tryParseTemplate('{{#a}} x').error).toEqual({ kind: 'unclosed' }); + expect(tryParseTemplate('{{a').error).toEqual({ kind: 'unclosed' }); }); - it("rejects mismatched closers", () => { - expect(tryParseTemplate("{{/a}}").error).toEqual({ - kind: "mismatched", - name: "a", + it('rejects mismatched closers', () => { + expect(tryParseTemplate('{{/a}}').error).toEqual({ + kind: 'mismatched', + name: 'a', }); - expect(tryParseTemplate("{{#a}}{{/b}}").error).toEqual({ - kind: "mismatched", - name: "b", + expect(tryParseTemplate('{{#a}}{{/b}}').error).toEqual({ + kind: 'mismatched', + name: 'b', }); }); - it("rejects bad names", () => { - expect(tryParseTemplate("{{A}}").error).toEqual({ - kind: "bad_name", - name: "A", + it('rejects bad names', () => { + expect(tryParseTemplate('{{A}}').error).toEqual({ + kind: 'bad_name', + name: 'A', }); - expect(tryParseTemplate("{{1a}}").error).toEqual({ - kind: "bad_name", - name: "1a", + expect(tryParseTemplate('{{1a}}').error).toEqual({ + kind: 'bad_name', + name: '1a', }); - expect(tryParseTemplate("{{}}").error).toEqual({ - kind: "bad_name", - name: "", + expect(tryParseTemplate('{{}}').error).toEqual({ + kind: 'bad_name', + name: '', }); - expect(tryParseTemplate(`{{${"a".repeat(32)}}}`).error).toBeNull(); - expect(tryParseTemplate(`{{${"a".repeat(33)}}}`).error).not.toBeNull(); + expect(tryParseTemplate(`{{${'a'.repeat(32)}}}`).error).toBeNull(); + expect(tryParseTemplate(`{{${'a'.repeat(33)}}}`).error).not.toBeNull(); }); - it("handles brace edge cases like the Rust twin", () => { - expect(tryParseTemplate("{{{a}}}").error).toEqual({ - kind: "bad_name", - name: "{a", + it('handles brace edge cases like the Rust twin', () => { + expect(tryParseTemplate('{{{a}}}').error).toEqual({ + kind: 'bad_name', + name: '{a', }); - expect(parseTemplate("{ {a} }")).toEqual([ - { kind: "text", text: "{ {a} }" }, - ]); - expect(parseTemplate("}}")).toEqual([{ kind: "text", text: "}}" }]); - expect(tryParseTemplate("{{#a}} x {{").error).toEqual({ kind: "unclosed" }); + expect(parseTemplate('{ {a} }')).toEqual([{ kind: 'text', text: '{ {a} }' }]); + expect(parseTemplate('}}')).toEqual([{ kind: 'text', text: '}}' }]); + expect(tryParseTemplate('{{#a}} x {{').error).toEqual({ kind: 'unclosed' }); }); - it("reports codes and names", () => { - expect(templateIssues("{{a}}")).toEqual([]); - expect(templateIssues("{{a")).toEqual(["template_syntax"]); - expect(templateIssues("{{A}}")).toEqual(["variable_bad_name"]); - expect(templateNames("{{b}} {{#a}}{{a}}{{/a}} {{b}}")).toEqual(["b", "a"]); + it('reports codes and names', () => { + expect(templateIssues('{{a}}')).toEqual([]); + expect(templateIssues('{{a')).toEqual(['template_syntax']); + expect(templateIssues('{{A}}')).toEqual(['variable_bad_name']); + expect(templateNames('{{b}} {{#a}}{{a}}{{/a}} {{b}}')).toEqual(['b', 'a']); }); }); @@ -91,77 +84,61 @@ const flow = (version: number, vars: string, body: string) => function errorCodes(src: string): string[] { return checkFlow(src) - .issues.filter((i) => i.severity === "error") + .issues.filter((i) => i.severity === 'error') .map((i) => i.code); } -const Q = "variables:\n q: { default: x }\n"; -const HANGUP = (prompt: string) => - ` a:\n kind: hangup\n prompt: ${prompt}\n`; +const Q = 'variables:\n q: { default: x }\n'; +const HANGUP = (prompt: string) => ` a:\n kind: hangup\n prompt: ${prompt}\n`; -describe("placeholders in a flow", () => { - it("v4 placeholder must be declared", () => { - expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}} {{ghost}}"')))).toEqual([ - "unknown_variable", - ]); +describe('placeholders in a flow', () => { + it('v4 placeholder must be declared', () => { + expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}} {{ghost}}"')))).toEqual(['unknown_variable']); expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}}"')))).toEqual([]); }); - it("scans menu labels and templates", () => { + it('scans menu labels and templates', () => { const body = ' a:\n kind: menu\n prompt: { audio: vprompt_ab12, template: "{{nope}}" }\n options: { "1": "{{q}}", "2": "{{bad}}" }\n exits: { "1": b, "2": b, no_input: b, invalid: b }\n b:\n kind: hangup\n prompt: bye\n'; - expect(errorCodes(flow(4, Q, body))).toEqual([ - "unknown_variable", - "unknown_variable", - ]); + expect(errorCodes(flow(4, Q, body))).toEqual(['unknown_variable', 'unknown_variable']); }); - it("reports bad syntax and names", () => { - expect(errorCodes(flow(4, Q, HANGUP('"{{#q}} open"')))).toEqual([ - "template_syntax", - ]); - expect(errorCodes(flow(4, Q, HANGUP('"{{Q}}"')))).toEqual([ - "variable_bad_name", - ]); + it('reports bad syntax and names', () => { + expect(errorCodes(flow(4, Q, HANGUP('"{{#q}} open"')))).toEqual(['template_syntax']); + expect(errorCodes(flow(4, Q, HANGUP('"{{Q}}"')))).toEqual(['variable_bad_name']); }); - it("checks declared names and max_len", () => { - const body = HANGUP("bye"); - expect( - errorCodes(flow(4, 'variables:\n Bad: { default: "" }\n', body)), - ).toEqual(["variable_bad_name"]); - expect( - errorCodes( - flow(4, 'variables:\n q: { default: "", max_len: 501 }\n', body), - ), - ).toContain("variable_max_len_out_of_range"); + it('checks declared names and max_len', () => { + const body = HANGUP('bye'); + expect(errorCodes(flow(4, 'variables:\n Bad: { default: "" }\n', body))).toEqual([ + 'variable_bad_name', + ]); + expect(errorCodes(flow(4, 'variables:\n q: { default: "", max_len: 501 }\n', body))).toContain( + 'variable_max_len_out_of_range', + ); }); - it("refuses placeholders in a transfer target and a transcript", () => { - expect( - errorCodes(flow(4, Q, ' a:\n kind: transfer\n target: "{{q}}"\n')), - ).toEqual(["placeholder_not_allowed"]); + it('refuses placeholders in a transfer target and a transcript', () => { + expect(errorCodes(flow(4, Q, ' a:\n kind: transfer\n target: "{{q}}"\n'))).toEqual([ + 'placeholder_not_allowed', + ]); expect( - errorCodes( - flow(4, Q, HANGUP('{ audio: vprompt_ab12, transcript: "Hi {{q}}" }')), - ), - ).toEqual(["placeholder_not_allowed"]); + errorCodes(flow(4, Q, HANGUP('{ audio: vprompt_ab12, transcript: "Hi {{q}}" }'))), + ).toEqual(['placeholder_not_allowed']); }); - it("treats braces as plain text before v4", () => { - expect( - errorCodes(flow(3, "", HANGUP('"Press {{1}} now }} {{#x"'))), - ).toEqual([]); + it('treats braces as plain text before v4', () => { + expect(errorCodes(flow(3, '', HANGUP('"Press {{1}} now }} {{#x"')))).toEqual([]); }); - it("warns about a variable nothing uses", () => { - const issues = checkFlow(flow(4, Q, HANGUP("bye"))).issues; - expect(issues.filter((i) => i.code === "unused_variable")).toMatchObject([ - { severity: "warning", params: { name: "q" } }, + it('warns about a variable nothing uses', () => { + const issues = checkFlow(flow(4, Q, HANGUP('bye'))).issues; + expect(issues.filter((i) => i.code === 'unused_variable')).toMatchObject([ + { severity: 'warning', params: { name: 'q' } }, ]); expect( checkFlow(flow(4, Q, HANGUP('"{{#q}}x{{/q}}"'))).issues.some( - (i) => i.code === "unused_variable", + (i) => i.code === 'unused_variable', ), ).toBe(false); }); From bd8ef7769956a8833f72efb10b5921eaed633ef0 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:50:48 +1300 Subject: [PATCH 07/13] feat: fill flow variables --- conformance/README.md | 5 + conformance/fill/audio-kept.expected.yaml | 8 + conformance/fill/audio-kept.input.yaml | 10 + conformance/fill/audio-kept.values.json | 1 + conformance/fill/audio-text.expected.yaml | 8 + conformance/fill/audio-text.input.yaml | 10 + conformance/fill/audio-text.values.json | 1 + conformance/fill/defaults.expected.yaml | 18 + conformance/fill/defaults.input.yaml | 25 ++ conformance/fill/defaults.values.json | 1 + conformance/fill/option3.expected.yaml | 18 + conformance/fill/option3.input.yaml | 25 ++ conformance/fill/option3.values.json | 1 + conformance/fill/too-long.expected.json | 1 + conformance/fill/too-long.input.yaml | 25 ++ conformance/fill/too-long.values.json | 1 + conformance/fill/two-options.expected.yaml | 18 + conformance/fill/two-options.input.yaml | 25 ++ conformance/fill/two-options.values.json | 1 + .../fill/unknown-variable.expected.json | 1 + conformance/fill/unknown-variable.input.yaml | 25 ++ conformance/fill/unknown-variable.values.json | 1 + crates/wavekat-flow/src/vars.rs | 343 ++++++++++++++++++ crates/wavekat-flow/tests/conformance.rs | 44 +++ packages/flow-schema/src/index.ts | 3 +- packages/flow-schema/src/model.ts | 21 ++ packages/flow-schema/src/validate.ts | 22 +- packages/flow-schema/src/vars.ts | 100 +++++ packages/flow-schema/test/conformance.test.ts | 51 ++- packages/flow-schema/test/vars.test.ts | 156 +++++++- 30 files changed, 945 insertions(+), 24 deletions(-) create mode 100644 conformance/fill/audio-kept.expected.yaml create mode 100644 conformance/fill/audio-kept.input.yaml create mode 100644 conformance/fill/audio-kept.values.json create mode 100644 conformance/fill/audio-text.expected.yaml create mode 100644 conformance/fill/audio-text.input.yaml create mode 100644 conformance/fill/audio-text.values.json create mode 100644 conformance/fill/defaults.expected.yaml create mode 100644 conformance/fill/defaults.input.yaml create mode 100644 conformance/fill/defaults.values.json create mode 100644 conformance/fill/option3.expected.yaml create mode 100644 conformance/fill/option3.input.yaml create mode 100644 conformance/fill/option3.values.json create mode 100644 conformance/fill/too-long.expected.json create mode 100644 conformance/fill/too-long.input.yaml create mode 100644 conformance/fill/too-long.values.json create mode 100644 conformance/fill/two-options.expected.yaml create mode 100644 conformance/fill/two-options.input.yaml create mode 100644 conformance/fill/two-options.values.json create mode 100644 conformance/fill/unknown-variable.expected.json create mode 100644 conformance/fill/unknown-variable.input.yaml create mode 100644 conformance/fill/unknown-variable.values.json diff --git a/conformance/README.md b/conformance/README.md index a43e001..cc940b7 100644 --- a/conformance/README.md +++ b/conformance/README.md @@ -28,6 +28,11 @@ of the outbound gate, which includes the base validation. These cases stay out of the top-level `valid/`/`invalid/` buckets because a flow refused for outbound — one with a `ring` step, say — is a perfectly good inbound flow. +`fill/` pins `fill` (flow variables): per case, `.input.yaml` (a v4 flow), +`.values.json` (the caller's values), and either `.expected.yaml` +(the filled flow, compared after canonical serialization) or +`.expected.json` = `{"errors": [codes]}` (the exact refusal). + Every `.yaml` has a sibling `.expected.json`: ```json diff --git a/conformance/fill/audio-kept.expected.yaml b/conformance/fill/audio-kept.expected.yaml new file mode 100644 index 0000000..9b38cef --- /dev/null +++ b/conformance/fill/audio-kept.expected.yaml @@ -0,0 +1,8 @@ +schema_version: 4 +id: flow_audio +name: Audio template +entry: hi +nodes: + hi: + kind: hangup + prompt: { audio: vprompt_a } diff --git a/conformance/fill/audio-kept.input.yaml b/conformance/fill/audio-kept.input.yaml new file mode 100644 index 0000000..da6506e --- /dev/null +++ b/conformance/fill/audio-kept.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_audio +name: Audio template +entry: hi +variables: + name: { default: there } +nodes: + hi: + kind: hangup + prompt: { audio: vprompt_a, template: "Hi {{name}}" } diff --git a/conformance/fill/audio-kept.values.json b/conformance/fill/audio-kept.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/audio-kept.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/fill/audio-text.expected.yaml b/conformance/fill/audio-text.expected.yaml new file mode 100644 index 0000000..0fd107e --- /dev/null +++ b/conformance/fill/audio-text.expected.yaml @@ -0,0 +1,8 @@ +schema_version: 4 +id: flow_audio +name: Audio template +entry: hi +nodes: + hi: + kind: hangup + prompt: Hi Ann diff --git a/conformance/fill/audio-text.input.yaml b/conformance/fill/audio-text.input.yaml new file mode 100644 index 0000000..da6506e --- /dev/null +++ b/conformance/fill/audio-text.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_audio +name: Audio template +entry: hi +variables: + name: { default: there } +nodes: + hi: + kind: hangup + prompt: { audio: vprompt_a, template: "Hi {{name}}" } diff --git a/conformance/fill/audio-text.values.json b/conformance/fill/audio-text.values.json new file mode 100644 index 0000000..361d405 --- /dev/null +++ b/conformance/fill/audio-text.values.json @@ -0,0 +1 @@ +{"name":"Ann"} diff --git a/conformance/fill/defaults.expected.yaml b/conformance/fill/defaults.expected.yaml new file mode 100644 index 0000000..68ea1c9 --- /dev/null +++ b/conformance/fill/defaults.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/defaults.input.yaml b/conformance/fill/defaults.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/defaults.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/defaults.values.json b/conformance/fill/defaults.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/defaults.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/fill/option3.expected.yaml b/conformance/fill/option3.expected.yaml new file mode 100644 index 0000000..ad1b803 --- /dev/null +++ b/conformance/fill/option3.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 3 for Both. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "3": Both, "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/option3.input.yaml b/conformance/fill/option3.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/option3.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/option3.values.json b/conformance/fill/option3.values.json new file mode 100644 index 0000000..751a63d --- /dev/null +++ b/conformance/fill/option3.values.json @@ -0,0 +1 @@ +{"option3":"Both"} diff --git a/conformance/fill/too-long.expected.json b/conformance/fill/too-long.expected.json new file mode 100644 index 0000000..eb02174 --- /dev/null +++ b/conformance/fill/too-long.expected.json @@ -0,0 +1 @@ +{"errors":["variable_too_long"]} diff --git a/conformance/fill/too-long.input.yaml b/conformance/fill/too-long.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/too-long.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/too-long.values.json b/conformance/fill/too-long.values.json new file mode 100644 index 0000000..473f628 --- /dev/null +++ b/conformance/fill/too-long.values.json @@ -0,0 +1 @@ +{"question": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"} diff --git a/conformance/fill/two-options.expected.yaml b/conformance/fill/two-options.expected.yaml new file mode 100644 index 0000000..15bbe95 --- /dev/null +++ b/conformance/fill/two-options.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Which database? Press 1 for Postgres. Press 2 for SQLite. Press 9 to hear this again." + options: { "1": Postgres, "2": SQLite, "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/two-options.input.yaml b/conformance/fill/two-options.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/two-options.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/two-options.values.json b/conformance/fill/two-options.values.json new file mode 100644 index 0000000..e9b8f5b --- /dev/null +++ b/conformance/fill/two-options.values.json @@ -0,0 +1 @@ +{"question":"Which database?","option1":"Postgres","option2":"SQLite"} diff --git a/conformance/fill/unknown-variable.expected.json b/conformance/fill/unknown-variable.expected.json new file mode 100644 index 0000000..d8d8aa6 --- /dev/null +++ b/conformance/fill/unknown-variable.expected.json @@ -0,0 +1 @@ +{"errors":["variable_unknown"]} diff --git a/conformance/fill/unknown-variable.input.yaml b/conformance/fill/unknown-variable.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/unknown-variable.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/unknown-variable.values.json b/conformance/fill/unknown-variable.values.json new file mode 100644 index 0000000..a6e7a62 --- /dev/null +++ b/conformance/fill/unknown-variable.values.json @@ -0,0 +1 @@ +{"colour":"red"} diff --git a/crates/wavekat-flow/src/vars.rs b/crates/wavekat-flow/src/vars.rs index 11f1f39..6276086 100644 --- a/crates/wavekat-flow/src/vars.rs +++ b/crates/wavekat-flow/src/vars.rs @@ -5,6 +5,10 @@ //! Blocks do not nest and have no else. Names are `[a-z][a-z0-9_]{0,31}`. //! Twin: `packages/flow-schema/src/vars.ts`. +use std::collections::BTreeMap; + +use crate::model::{Exits, Flow, Node, Prompt}; + /// One piece of a parsed template. #[derive(Debug, Clone, PartialEq, Eq)] pub enum Segment<'a> { @@ -136,6 +140,149 @@ pub fn template_names(s: &str) -> Vec { names } +/// Why [`fill`] refused the values. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum FillError { + #[error("the flow declares no variable named {0:?}")] + Unknown(String), + #[error("variable {name:?} is {len} characters; its max_len is {max}")] + TooLong { name: String, max: u64, len: u64 }, +} + +impl FillError { + /// The stable code, shared with the TypeScript twin. + pub fn code(&self) -> &'static str { + match self { + FillError::Unknown(_) => "variable_unknown", + FillError::TooLong { .. } => "variable_too_long", + } + } +} + +/// A caller's value, trimmed with control characters stripped. +fn clean(value: &str) -> String { + value + .chars() + .filter(|c| !c.is_control()) + .collect::() + .trim() + .to_string() +} + +fn render(segments: &[Segment<'_>], effective: &dyn Fn(&str) -> String, out: &mut String) { + for seg in segments { + match seg { + Segment::Text(t) => out.push_str(t), + Segment::Var(n) => out.push_str(&effective(n)), + Segment::Block { name, body } => { + if !effective(name).is_empty() { + render(body, effective, out); + } + } + } + } +} + +/// Turn a flow with variables plus a caller's values into a plain flow the +/// engine can run: every placeholder replaced, `variables` gone, +/// `schema_version` unchanged. Twin: `vars.ts` `fill`. +/// +/// A name's effective value is the caller's (trimmed, control characters +/// stripped) when that is non-empty, else the variable's default. Values are +/// inserted as text and never parsed again. A menu option whose label is +/// exactly `{{name}}` with an empty value is removed, with its exit. An audio +/// prompt with a `template` stays audio (dropping the template) unless a +/// variable it names got a non-default value; then it becomes the filled +/// text. A flow without variables comes back as a clone. A malformed template is left as written (validation rejects those +/// before fill is reached). +pub fn fill(flow: &Flow, values: &BTreeMap) -> Result> { + // No variables: `{{` is ordinary text (v1-v3), so there is nothing to fill. + if flow.variables.is_empty() && values.is_empty() { + return Ok(flow.clone()); + } + let mut errors = Vec::new(); + let mut given: BTreeMap<&str, String> = BTreeMap::new(); + for (name, raw) in values { + let Some(var) = flow.variables.get(name) else { + errors.push(FillError::Unknown(name.clone())); + continue; + }; + let value = clean(raw); + let len = value.chars().count() as u64; + if len > var.max_len.get() { + errors.push(FillError::TooLong { + name: name.clone(), + max: var.max_len.get(), + len, + }); + } else if !value.is_empty() { + given.insert(name, value); + } + } + if !errors.is_empty() { + return Err(errors); + } + let effective = |name: &str| -> String { + given + .get(name) + .cloned() + .or_else(|| flow.variables.get(name).map(|v| v.default.clone())) + .unwrap_or_default() + }; + let fill_text = |text: &str| -> String { + match parse_template(text) { + Ok(segments) => { + let mut out = String::new(); + render(&segments, &effective, &mut out); + out + } + Err(_) => text.to_string(), + } + }; + + let mut out = flow.clone(); + out.variables.clear(); + for node in out.nodes.values_mut() { + for (_, prompt) in node.prompt_slots_mut() { + match prompt { + Prompt::Text(text) => *text = fill_text(text), + Prompt::Audio { template, .. } => { + let Some(t) = template.take() else { continue }; + let overridden = template_names(&t).iter().any(|n| { + given + .get(n.as_str()) + .is_some_and(|v| flow.variables.get(n).is_none_or(|d| &d.default != v)) + }); + if overridden { + *prompt = Prompt::Text(fill_text(&t)); + } + } + } + } + if let Node::Menu { options, exits, .. } = node { + let mut dropped = Vec::new(); + for (key, label) in options.iter_mut() { + let bare = label + .strip_prefix("{{") + .and_then(|l| l.strip_suffix("}}")) + .filter(|n| is_variable_name(n)); + if bare.is_some_and(|n| effective(n).is_empty()) { + dropped.push(key.clone()); + } else { + *label = fill_text(label); + } + } + for key in dropped { + options.shift_remove(&key); + if let Some(Exits(map)) = exits { + map.shift_remove(&key); + } + } + } + } + Ok(out) +} + #[cfg(test)] mod tests { use super::*; @@ -226,4 +373,200 @@ mod tests { vec!["b".to_string(), "a".to_string()] ); } + + const ASK: &str = include_str!("../../../conformance/v4/valid/ask-question.yaml"); + + fn ask() -> Flow { + Flow::from_yaml(ASK).unwrap() + } + + fn vals(pairs: &[(&str, &str)]) -> BTreeMap { + pairs + .iter() + .map(|(k, v)| (k.to_string(), v.to_string())) + .collect() + } + + fn menu(flow: &Flow) -> (String, Vec<(String, String)>, Vec) { + let Node::Menu { + prompt, + options, + exits, + .. + } = &flow.nodes["ask"] + else { + panic!("ask is a menu") + }; + let Prompt::Text(text) = prompt else { + panic!("text prompt") + }; + ( + text.clone(), + options + .iter() + .map(|(k, v)| (k.clone(), v.clone())) + .collect(), + exits.as_ref().unwrap().keys().cloned().collect(), + ) + } + + fn pairs(list: &[(&str, &str)]) -> Vec<(String, String)> { + list.iter() + .map(|(k, v)| (k.to_string(), v.to_string())) + .collect() + } + + #[test] + fn fills_question_and_two_options() { + let filled = fill( + &ask(), + &vals(&[ + ("question", "Which database?"), + ("option1", "Postgres"), + ("option2", "SQLite"), + ]), + ) + .unwrap(); + let (prompt, options, exits) = menu(&filled); + assert_eq!( + prompt, + "Claude has a question. Which database? Press 1 for Postgres. Press 2 for SQLite. Press 9 to hear this again." + ); + assert_eq!( + options, + pairs(&[("1", "Postgres"), ("2", "SQLite"), ("9", "Repeat")]) + ); + assert!(!exits.contains(&"3".to_string()) && !exits.contains(&"4".to_string())); + assert!(filled.variables.is_empty()); + assert_eq!(filled.schema_version, 4); + } + + #[test] + fn keeps_option3_when_given() { + let filled = fill(&ask(), &vals(&[("option3", "Both")])).unwrap(); + let (prompt, options, exits) = menu(&filled); + assert!(prompt.contains(" Press 3 for Both."), "{prompt}"); + assert!(options.contains(&("3".to_string(), "Both".to_string()))); + let Node::Menu { exits: e, .. } = &filled.nodes["ask"] else { + unreachable!() + }; + assert_eq!(e.as_ref().unwrap()["3"], "thanks"); + assert!(!exits.contains(&"4".to_string())); + } + + #[test] + fn no_values_plays_the_defaults() { + let filled = fill(&ask(), &BTreeMap::new()).unwrap(); + let (prompt, options, exits) = menu(&filled); + assert_eq!( + prompt, + "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + ); + assert_eq!( + options, + pairs(&[("1", "Yes"), ("2", "No"), ("9", "Repeat")]) + ); + assert!(!exits.contains(&"3".to_string()) && !exits.contains(&"4".to_string())); + } + + #[test] + fn rendered_prompt_stays_audio_when_defaults_kept() { + let mut flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n name: { default: there }\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_a, template: \"Hi {{name}}\" }\n", + ) + .unwrap(); + let filled = fill(&flow, &BTreeMap::new()).unwrap(); + let Node::Hangup { prompt, .. } = &filled.nodes["a"] else { + unreachable!() + }; + assert!(matches!( + prompt, + Some(Prompt::Audio { audio, template: None, .. }) if audio == "vprompt_a" + )); + // Giving the default itself changes nothing. + let same = fill(&flow, &vals(&[("name", "there")])).unwrap(); + assert!(matches!( + &same.nodes["a"], + Node::Hangup { + prompt: Some(Prompt::Audio { .. }), + .. + } + )); + let filled = fill(&flow, &vals(&[("name", "Ann")])).unwrap(); + let Node::Hangup { prompt, .. } = &filled.nodes["a"] else { + unreachable!() + }; + assert!(matches!(prompt, Some(Prompt::Text(t)) if t == "Hi Ann")); + flow.variables.clear(); + } + + #[test] + fn blank_value_falls_back_to_default() { + let filled = fill(&ask(), &vals(&[("question", " ")])).unwrap(); + assert!(menu(&filled) + .0 + .contains("Claude needs your input on screen.")); + } + + #[test] + fn control_characters_are_stripped() { + let filled = fill(&ask(), &vals(&[("question", " Hi\u{7}\n there ")])).unwrap(); + assert!(menu(&filled) + .0 + .contains("Claude has a question. Hi there Press")); + } + + #[test] + fn unknown_value_is_an_error() { + let errs = fill(&ask(), &vals(&[("colour", "red")])).unwrap_err(); + assert_eq!(errs, vec![FillError::Unknown("colour".into())]); + assert_eq!(errs[0].code(), "variable_unknown"); + } + + #[test] + fn values_are_not_expanded() { + let filled = fill(&ask(), &vals(&[("question", "{{option1}} {x}")])).unwrap(); + assert!(menu(&filled).0.contains("{{option1}} {x}")); + } + + #[test] + fn max_len_counts_characters() { + let mut flow = ask(); + flow.variables.get_mut("question").unwrap().max_len = 300.try_into().unwrap(); + assert!(fill(&flow, &vals(&[("question", &"问".repeat(150))])).is_ok()); + assert!(fill(&flow, &vals(&[("question", &"问".repeat(300))])).is_ok()); + let errs = fill(&flow, &vals(&[("question", &"问".repeat(301))])).unwrap_err(); + assert_eq!( + errs, + vec![FillError::TooLong { + name: "question".into(), + max: 300, + len: 301 + }] + ); + assert_eq!(errs[0].code(), "variable_too_long"); + } + + #[test] + fn filled_flow_passes_validate_outbound() { + for v in [ + vals(&[]), + vals(&[("option3", "Both"), ("option4", "Neither")]), + ] { + let filled = fill(&ask(), &v).unwrap(); + crate::validate::validate_outbound(&filled).unwrap(); + } + } + + #[test] + fn a_flow_without_variables_is_returned_unchanged() { + let plain = Flow::from_yaml( + "schema_version: 3\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: Hi {{x}}\n", + ) + .unwrap(); + assert_eq!( + fill(&plain, &BTreeMap::new()).unwrap().to_yaml(), + plain.to_yaml() + ); + } } diff --git a/crates/wavekat-flow/tests/conformance.rs b/crates/wavekat-flow/tests/conformance.rs index 7345f36..8e70f83 100644 --- a/crates/wavekat-flow/tests/conformance.rs +++ b/crates/wavekat-flow/tests/conformance.rs @@ -285,3 +285,47 @@ fn outbound_corpus_matches_expectations() { } assert!(ran > 0, "the outbound corpus has no cases"); } + +// The fill corpus: `conformance/fill/.input.yaml` + `.values.json` +// run through `fill`. A success case has `.expected.yaml`, compared with +// the filled flow after canonical serialization; a refusal has +// `.expected.json` = `{"errors": [codes]}` (exact list, in order). +#[test] +fn corpus_fill_matches_expectations() { + let dir = corpus_root().join("fill"); + let mut ran = 0; + for (stem, path) in yaml_cases_in(&dir) { + let Some(case) = stem.strip_suffix(".input") else { + continue; + }; + let flow = Flow::from_yaml(&fs::read_to_string(&path).unwrap()).unwrap(); + let values: std::collections::BTreeMap = serde_json::from_str( + &fs::read_to_string(dir.join(format!("{case}.values.json"))).unwrap(), + ) + .unwrap(); + let result = wavekat_flow::vars::fill(&flow, &values); + let expected_yaml = dir.join(format!("{case}.expected.yaml")); + if expected_yaml.exists() { + let filled = result.unwrap_or_else(|e| panic!("fill/{case} should succeed: {e:?}")); + let want = Flow::from_yaml(&fs::read_to_string(expected_yaml).unwrap()).unwrap(); + assert_eq!(filled.to_yaml(), want.to_yaml(), "fill/{case}"); + } else { + #[derive(serde::Deserialize)] + struct Refusal { + errors: Vec, + } + let want: Refusal = serde_json::from_str( + &fs::read_to_string(dir.join(format!("{case}.expected.json"))).unwrap(), + ) + .unwrap(); + let got: Vec = result + .expect_err(&format!("fill/{case} should be refused")) + .iter() + .map(|e| e.code().to_string()) + .collect(); + assert_eq!(got, want.errors, "fill/{case}"); + } + ran += 1; + } + assert!(ran > 0, "the fill corpus has no cases"); +} diff --git a/packages/flow-schema/src/index.ts b/packages/flow-schema/src/index.ts index 86bf4e6..70dcef5 100644 --- a/packages/flow-schema/src/index.ts +++ b/packages/flow-schema/src/index.ts @@ -66,6 +66,7 @@ export { } from './mutate.js'; export { + fill, isVariableName, parseTemplate, templateErrorCode, @@ -73,4 +74,4 @@ export { templateNames, tryParseTemplate, } from './vars.js'; -export type { Segment, TemplateError } from './vars.js'; +export type { FillError, Segment, TemplateError } from './vars.js'; diff --git a/packages/flow-schema/src/model.ts b/packages/flow-schema/src/model.ts index df407ed..61d955c 100644 --- a/packages/flow-schema/src/model.ts +++ b/packages/flow-schema/src/model.ts @@ -337,6 +337,27 @@ export function nodePrompts(node: Node): Prompt[] { } } +/** The prompt slots of a node with the field each comes from. */ +export function nodePromptSlots(node: Node): [string, Prompt][] { + switch (node.kind) { + case 'greeting': + case 'menu': + case 'message': + return [['prompt', node.prompt]]; + case 'hangup': + return node.prompt === undefined ? [] : [['prompt', node.prompt]]; + case 'book': + return [ + ['prompt', node.prompt], + ['confirm_prompt', node.confirm_prompt], + ]; + case 'transfer': + return node.whisper === undefined ? [] : [['whisper', node.whisper]]; + default: + return []; + } +} + /** * Every audio asset the flow needs on the device, sorted and unique: * the refs its prompts point at, plus — for a `book` node — the diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index aceb6be..4e9c0f2 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -27,6 +27,7 @@ import { VALID_DIGITS, isScreenedTransfer, isTerminal, + nodePromptSlots, nodePrompts, promptTemplate, promptText, @@ -487,27 +488,6 @@ const TEMPLATE_REASONS = { mismatched: 'a block close does not match an open block', } as const; -/** The prompt slots of a node with the field each comes from. */ -function nodePromptSlots(node: Node): [string, Prompt][] { - switch (node.kind) { - case 'greeting': - case 'menu': - case 'message': - return [['prompt', node.prompt]]; - case 'hangup': - return node.prompt === undefined ? [] : [['prompt', node.prompt]]; - case 'book': - return [ - ['prompt', node.prompt], - ['confirm_prompt', node.confirm_prompt], - ]; - case 'transfer': - return node.whisper === undefined ? [] : [['whisper', node.whisper]]; - default: - return []; - } -} - /** Paths of string values under `value` that hold `{{`, apart from the slots * where a placeholder is allowed: a plain-string `prompt`, `confirm_prompt` * or `whisper`, any `.template`, and menu `options`. */ diff --git a/packages/flow-schema/src/vars.ts b/packages/flow-schema/src/vars.ts index 81ff8e2..5246407 100644 --- a/packages/flow-schema/src/vars.ts +++ b/packages/flow-schema/src/vars.ts @@ -5,6 +5,9 @@ // conditional blocks (kept only when the variable's value is non-empty). // Blocks do not nest and have no else. Names are `[a-z][a-z0-9_]{0,31}`. +import type { Flow } from './model.js'; +import { nodePromptSlots } from './model.js'; + /** One piece of a parsed template. A block's body holds only text and vars. */ export type Segment = | { kind: 'text'; text: string } @@ -103,3 +106,100 @@ export function templateNames(s: string): string[] { } return names; } + +/** Why `fill` refused a value. */ +export type FillError = { code: 'variable_unknown' | 'variable_too_long'; name: string }; + +const DEFAULT_MAX_LEN = 200; + +/** A caller's value, trimmed with control characters stripped. Twin: `clean`. */ +function clean(value: string): string { + return value.replace(/\p{Cc}/gu, '').trim(); +} + +function render(segments: Segment[], effective: (name: string) => string): string { + let out = ''; + for (const seg of segments) { + if (seg.kind === 'text') out += seg.text; + else if (seg.kind === 'var') out += effective(seg.name); + else if (effective(seg.name) !== '') out += render(seg.body, effective); + } + return out; +} + +/** + * Turn a flow with variables plus a caller's values into a plain flow the + * engine can run: every placeholder replaced, `variables` gone, + * `schema_version` unchanged. The input is not modified. Twin: `vars.rs` `fill`. + * + * A name's effective value is the caller's (trimmed, control characters + * stripped) when that is non-empty, else the variable's default. Values are + * inserted as text and never parsed again. A menu option whose label is + * exactly `{{name}}` with an empty value is removed, with its exit. An audio + * prompt with a `template` stays audio (dropping the template) unless a + * variable it names got a non-default value; then it becomes the filled text. + * A flow without variables comes back as a clone. A malformed template is + * left as written (validation rejects those before fill is reached). + */ +export function fill( + flow: Flow, + values: Record, +): { flow: Flow } | { errors: FillError[] } { + const declared = flow.variables ?? {}; + const out = structuredClone(flow); + if (Object.keys(declared).length === 0 && Object.keys(values).length === 0) return { flow: out }; + + const errors: FillError[] = []; + const given = new Map(); + for (const name of Object.keys(values).sort()) { + const variable = Object.hasOwn(declared, name) ? declared[name] : undefined; + if (variable === undefined) { + errors.push({ code: 'variable_unknown', name }); + continue; + } + const value = clean(values[name] ?? ''); + if ([...value].length > (variable.max_len ?? DEFAULT_MAX_LEN)) { + errors.push({ code: 'variable_too_long', name }); + } else if (value !== '') { + given.set(name, value); + } + } + if (errors.length > 0) return { errors }; + + const defaultOf = (name: string): string => + Object.hasOwn(declared, name) ? (declared[name]?.default ?? '') : ''; + const effective = (name: string): string => given.get(name) ?? defaultOf(name); + const fillText = (text: string): string => { + const { segments, error } = tryParseTemplate(text); + return error === null ? render(segments, effective) : text; + }; + + delete out.variables; + for (const node of Object.values(out.nodes)) { + for (const [field, prompt] of nodePromptSlots(node)) { + let next: typeof prompt = prompt; + if (typeof prompt === 'string') { + next = fillText(prompt); + } else if (typeof prompt.template === 'string') { + const { template, ...clip } = prompt; + const overridden = templateNames(template).some( + (n) => given.has(n) && given.get(n) !== defaultOf(n), + ); + next = overridden ? fillText(template) : clip; + } + (node as unknown as Record)[field] = next; + } + if (node.kind === 'menu') { + for (const [key, label] of Object.entries(node.options)) { + const bare = /^\{\{([^{}]*)\}\}$/.exec(label)?.[1]; + if (bare !== undefined && isVariableName(bare) && effective(bare) === '') { + delete node.options[key]; + if (node.exits) delete node.exits[key]; + } else { + node.options[key] = fillText(label); + } + } + } + } + return { flow: out }; +} diff --git a/packages/flow-schema/test/conformance.test.ts b/packages/flow-schema/test/conformance.test.ts index 2e135a0..a8d4184 100644 --- a/packages/flow-schema/test/conformance.test.ts +++ b/packages/flow-schema/test/conformance.test.ts @@ -18,7 +18,15 @@ import { fileURLToPath } from 'node:url'; import { describe, expect, it } from 'vitest'; import { parse } from 'yaml'; -import { checkFlow, hasErrors, parseFlow, requiredAssets, validateOutbound } from '../src/index.js'; +import { + checkFlow, + fill, + hasErrors, + parseFlow, + requiredAssets, + serializeFlow, + validateOutbound, +} from '../src/index.js'; import { validateStructure } from '../src/structure.js'; const here = dirname(fileURLToPath(import.meta.url)); @@ -189,3 +197,44 @@ describe('conformance corpus — outbound (validateOutbound)', () => { }); } }); + +// The fill corpus: `conformance/fill/.input.yaml` + `.values.json` +// run through `fill`. A success case has `.expected.yaml`, compared with +// the filled flow after canonical serialization; a refusal has +// `.expected.json` = `{"errors": [codes]}` (exact list, in order). The +// Rust crate runs the same cases (`corpus_fill_matches_expectations`). +const FILL_DIR = resolve(corpusRoot, 'fill'); +const FILL_CASES = readdirSync(FILL_DIR) + .filter((f) => f.endsWith('.input.yaml')) + .map((f) => f.slice(0, -'.input.yaml'.length)) + .sort(); + +function decode(src: string, label: string) { + const { flow, issues } = parseFlow(src); + if (!flow) throw new Error(`${label}: ${JSON.stringify(issues)}`); + return flow; +} + +describe('conformance corpus — fill', () => { + it('has cases', () => { + expect(FILL_CASES.length).toBeGreaterThan(0); + }); + + for (const name of FILL_CASES) { + it(name, () => { + const read = (ext: string) => readFileSync(resolve(FILL_DIR, `${name}.${ext}`), 'utf8'); + const flow = decode(read('input.yaml'), name); + const values = JSON.parse(read('values.json')) as Record; + const result = fill(flow, values); + if (existsSync(resolve(FILL_DIR, `${name}.expected.yaml`))) { + if (!('flow' in result)) throw new Error(JSON.stringify(result.errors)); + const want = decode(read('expected.yaml'), name); + expect(serializeFlow(result.flow)).toBe(serializeFlow(want)); + } else { + const want = JSON.parse(read('expected.json')) as { errors: string[] }; + if (!('errors' in result)) throw new Error('expected fill to be refused'); + expect(result.errors.map((e) => e.code)).toEqual(want.errors); + } + }); + } +}); diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts index ba320d7..ea48fcf 100644 --- a/packages/flow-schema/test/vars.test.ts +++ b/packages/flow-schema/test/vars.test.ts @@ -1,7 +1,20 @@ import { describe, expect, it } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + import { checkFlow } from '../src/check.js'; -import { parseTemplate, templateIssues, templateNames, tryParseTemplate } from '../src/vars.js'; +import type { Flow } from '../src/model.js'; +import { parseFlow } from '../src/parse.js'; +import { serializeFlow } from '../src/serialize.js'; +import { validateOutbound } from '../src/validate.js'; +import { + fill, + parseTemplate, + templateIssues, + templateNames, + tryParseTemplate, +} from '../src/vars.js'; describe('parseTemplate', () => { it('parses text, vars and blocks', () => { @@ -143,3 +156,144 @@ describe('placeholders in a flow', () => { ).toBe(false); }); }); + +const ASK_PATH = fileURLToPath( + new URL('../../../conformance/v4/valid/ask-question.yaml', import.meta.url), +); + +function load(source: string): Flow { + const { flow, issues } = parseFlow(source); + if (!flow) throw new Error(JSON.stringify(issues)); + return flow; +} + +const ask = (): Flow => load(readFileSync(ASK_PATH, 'utf8')); + +function filled(flow: Flow, values: Record): Flow { + const result = fill(flow, values); + if (!('flow' in result)) throw new Error(JSON.stringify(result.errors)); + return result.flow; +} + +function askMenu(flow: Flow) { + const node = flow.nodes.ask; + if (node?.kind !== 'menu') throw new Error('ask is a menu'); + return node; +} + +const VOICED: Flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: a', + 'variables:', + ' name: { default: there }', + 'nodes:', + ' a:', + ' kind: hangup', + ' prompt: { audio: vprompt_a, template: "Hi {{name}}" }', + '', + ].join('\n'), +); + +describe('fill', () => { + it('fills_question_and_two_options', () => { + const flow = filled(ask(), { + question: 'Which database?', + option1: 'Postgres', + option2: 'SQLite', + }); + const menu = askMenu(flow); + expect(menu.prompt).toBe( + 'Claude has a question. Which database? Press 1 for Postgres. Press 2 for SQLite. Press 9 to hear this again.', + ); + expect(menu.options).toEqual({ '1': 'Postgres', '2': 'SQLite', '9': 'Repeat' }); + expect(menu.exits).not.toHaveProperty('3'); + expect(menu.exits).not.toHaveProperty('4'); + expect(flow.variables).toBeUndefined(); + expect(flow.schema_version).toBe(4); + }); + + it('keeps_option3_when_given', () => { + const menu = askMenu(filled(ask(), { option3: 'Both' })); + expect(menu.prompt as string).toContain(' Press 3 for Both.'); + expect(menu.options['3']).toBe('Both'); + expect(menu.exits?.['3']).toBe('thanks'); + expect(menu.exits).not.toHaveProperty('4'); + }); + + it('no_values_plays_the_defaults', () => { + const menu = askMenu(filled(ask(), {})); + expect(menu.prompt).toBe( + 'Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again.', + ); + expect(menu.options).toEqual({ '1': 'Yes', '2': 'No', '9': 'Repeat' }); + expect(menu.exits).not.toHaveProperty('3'); + }); + + it('rendered_prompt_stays_audio_when_defaults_kept', () => { + const kept = filled(VOICED, {}).nodes.a; + expect(kept).toMatchObject({ prompt: { audio: 'vprompt_a' } }); + expect(kept).not.toHaveProperty('prompt.template'); + expect(filled(VOICED, { name: 'there' }).nodes.a).toMatchObject({ + prompt: { audio: 'vprompt_a' }, + }); + expect(filled(VOICED, { name: 'Ann' }).nodes.a).toMatchObject({ prompt: 'Hi Ann' }); + }); + + it('blank_value_falls_back_to_default', () => { + expect(askMenu(filled(ask(), { question: ' ' })).prompt as string).toContain( + 'Claude needs your input on screen.', + ); + }); + + it('strips control characters', () => { + expect(askMenu(filled(ask(), { question: ' Hi\u0007\n there ' })).prompt as string).toContain( + 'Claude has a question. Hi there Press', + ); + }); + + it('unknown_value_is_an_error', () => { + expect(fill(ask(), { colour: 'red' })).toEqual({ + errors: [{ code: 'variable_unknown', name: 'colour' }], + }); + }); + + it('values_are_not_expanded', () => { + expect(askMenu(filled(ask(), { question: '{{option1}} {x}' })).prompt as string).toContain( + '{{option1}} {x}', + ); + }); + + it('max_len_counts_characters', () => { + const flow = ask(); + flow.variables!.question!.max_len = 300; + expect('flow' in fill(flow, { question: '问'.repeat(150) })).toBe(true); + expect('flow' in fill(flow, { question: '问'.repeat(300) })).toBe(true); + expect(fill(flow, { question: '问'.repeat(301) })).toEqual({ + errors: [{ code: 'variable_too_long', name: 'question' }], + }); + // Emoji outside the BMP are one character each, not two UTF-16 units. + expect('flow' in fill(flow, { question: '😀'.repeat(300) })).toBe(true); + }); + + it('filled_flow_passes_validate_outbound', () => { + const cases: Record[] = [{}, { option3: 'Both', option4: 'Neither' }]; + for (const values of cases) { + const issues = validateOutbound(filled(ask(), values)); + expect(issues.filter((i) => i.severity === 'error')).toEqual([]); + } + }); + + it('does not touch the input and returns a flow without variables unchanged', () => { + const flow = ask(); + const before = serializeFlow(flow); + filled(flow, { option3: 'Both' }); + expect(serializeFlow(flow)).toBe(before); + const plain = load( + 'schema_version: 3\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: Hi {{x}}\n', + ); + expect(serializeFlow(filled(plain, {}))).toBe(serializeFlow(plain)); + }); +}); From 6545483c17e7c519a35fc02af25c0a6b8b6afd9c Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:54:14 +1300 Subject: [PATCH 08/13] fix: harden fill trim and menu options --- Cargo.lock | 4 +- conformance/fill/blank-unicode.expected.yaml | 18 ++++ conformance/fill/blank-unicode.input.yaml | 25 ++++++ conformance/fill/blank-unicode.values.json | 1 + crates/wavekat-flow/src/vars.rs | 91 +++++++++++++++++--- packages/flow-schema/src/vars.ts | 33 +++++-- packages/flow-schema/test/vars.test.ts | 52 +++++++++-- 7 files changed, 195 insertions(+), 29 deletions(-) create mode 100644 conformance/fill/blank-unicode.expected.yaml create mode 100644 conformance/fill/blank-unicode.input.yaml create mode 100644 conformance/fill/blank-unicode.values.json diff --git a/Cargo.lock b/Cargo.lock index 50040d9..6d2b6f1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -121,7 +121,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" name = "compat-old-readers" version = "0.0.1" dependencies = [ - "wavekat-flow 0.0.11", + "wavekat-flow 0.0.12", "wavekat-flow 0.0.6", ] @@ -1562,7 +1562,7 @@ dependencies = [ [[package]] name = "wavekat-flow" -version = "0.0.12" +version = "0.0.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "aa8de375720073be7590b3e3a0cb70ef88569bc483c3938d147d7a02c12408ca" dependencies = [ diff --git a/conformance/fill/blank-unicode.expected.yaml b/conformance/fill/blank-unicode.expected.yaml new file mode 100644 index 0000000..68ea1c9 --- /dev/null +++ b/conformance/fill/blank-unicode.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/blank-unicode.input.yaml b/conformance/fill/blank-unicode.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/blank-unicode.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/blank-unicode.values.json b/conformance/fill/blank-unicode.values.json new file mode 100644 index 0000000..05e62cf --- /dev/null +++ b/conformance/fill/blank-unicode.values.json @@ -0,0 +1 @@ +{"question":"\ufeff \u0085\u00a0\u2003"} diff --git a/crates/wavekat-flow/src/vars.rs b/crates/wavekat-flow/src/vars.rs index 6276086..e153acd 100644 --- a/crates/wavekat-flow/src/vars.rs +++ b/crates/wavekat-flow/src/vars.rs @@ -147,6 +147,8 @@ pub enum FillError { Unknown(String), #[error("variable {name:?} is {len} characters; its max_len is {max}")] TooLong { name: String, max: u64, len: u64 }, + #[error("filling leaves menu {node:?} with no options")] + NoOptions { node: String }, } impl FillError { @@ -155,17 +157,19 @@ impl FillError { match self { FillError::Unknown(_) => "variable_unknown", FillError::TooLong { .. } => "variable_too_long", + FillError::NoOptions { .. } => "menu_without_options", } } } -/// A caller's value, trimmed with control characters stripped. +/// A caller's value with control characters stripped, then trimmed of +/// Unicode White_Space plus U+FEFF. Twin: `clean` in `vars.ts`. fn clean(value: &str) -> String { value .chars() .filter(|c| !c.is_control()) .collect::() - .trim() + .trim_matches(|c: char| c.is_whitespace() || c == '\u{FEFF}') .to_string() } @@ -242,7 +246,7 @@ pub fn fill(flow: &Flow, values: &BTreeMap) -> Result *text = fill_text(text), @@ -272,6 +276,12 @@ pub fn fill(flow: &Flow, values: &BTreeMap) -> Result) -> Result Vec<&str> { + let Node::Menu { options, .. } = &flow.nodes["m"] else { + unreachable!() + }; + options.keys().map(String::as_str).collect() } #[test] diff --git a/packages/flow-schema/src/vars.ts b/packages/flow-schema/src/vars.ts index 5246407..f6f8511 100644 --- a/packages/flow-schema/src/vars.ts +++ b/packages/flow-schema/src/vars.ts @@ -108,13 +108,19 @@ export function templateNames(s: string): string[] { } /** Why `fill` refused a value. */ -export type FillError = { code: 'variable_unknown' | 'variable_too_long'; name: string }; +export type FillError = { + code: 'variable_unknown' | 'variable_too_long' | 'menu_without_options'; + /** The variable, or for `menu_without_options` the menu node id. */ + name: string; +}; const DEFAULT_MAX_LEN = 200; -/** A caller's value, trimmed with control characters stripped. Twin: `clean`. */ +/** A caller's value with control characters stripped, then trimmed of Unicode + * White_Space plus U+FEFF (JS `\s` covers FEFF but not U+0085). Twin: `clean` + * in `vars.rs`. */ function clean(value: string): string { - return value.replace(/\p{Cc}/gu, '').trim(); + return value.replace(/\p{Cc}/gu, '').replace(/^[\s\u0085]+|[\s\u0085]+$/g, ''); } function render(segments: Segment[], effective: (name: string) => string): string { @@ -140,6 +146,11 @@ function render(segments: Segment[], effective: (name: string) => string): strin * variable it names got a non-default value; then it becomes the filled text. * A flow without variables comes back as a clone. A malformed template is * left as written (validation rejects those before fill is reached). + * + * Contract: validate the SOURCE flow first (`validateOutbound`); the result is + * not meant to be re-validated (a value may itself hold `{{`). `fill` keeps + * options and exits consistent, and refuses with `menu_without_options` when + * every option of a menu would be dropped. */ export function fill( flow: Flow, @@ -175,7 +186,7 @@ export function fill( }; delete out.variables; - for (const node of Object.values(out.nodes)) { + for (const [id, node] of Object.entries(out.nodes)) { for (const [field, prompt] of nodePromptSlots(node)) { let next: typeof prompt = prompt; if (typeof prompt === 'string') { @@ -190,16 +201,24 @@ export function fill( (node as unknown as Record)[field] = next; } if (node.kind === 'menu') { + const dropped: string[] = []; for (const [key, label] of Object.entries(node.options)) { const bare = /^\{\{([^{}]*)\}\}$/.exec(label)?.[1]; if (bare !== undefined && isVariableName(bare) && effective(bare) === '') { - delete node.options[key]; - if (node.exits) delete node.exits[key]; + dropped.push(key); } else { node.options[key] = fillText(label); } } + if (dropped.length > 0 && dropped.length === Object.keys(node.options).length) { + errors.push({ code: 'menu_without_options', name: id }); + continue; + } + for (const key of dropped) { + delete node.options[key]; + if (node.exits) delete node.exits[key]; + } } } - return { flow: out }; + return errors.length > 0 ? { errors } : { flow: out }; } diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts index ea48fcf..fe413c9 100644 --- a/packages/flow-schema/test/vars.test.ts +++ b/packages/flow-schema/test/vars.test.ts @@ -278,12 +278,52 @@ describe('fill', () => { expect('flow' in fill(flow, { question: '😀'.repeat(300) })).toBe(true); }); - it('filled_flow_passes_validate_outbound', () => { - const cases: Record[] = [{}, { option3: 'Both', option4: 'Neither' }]; - for (const values of cases) { - const issues = validateOutbound(filled(ask(), values)); - expect(issues.filter((i) => i.severity === 'error')).toEqual([]); - } + it('source validates and fill keeps hostile values literal', () => { + const issues = validateOutbound(ask()); + expect(issues.filter((i) => i.severity === 'error')).toEqual([]); + const menu = askMenu(filled(ask(), { question: '{{option1}} {x}' })); + expect(menu.prompt as string).toContain('{{option1}} {x}'); + }); + + it('dropping_every_option_is_an_error', () => { + const flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: m', + 'variables:', + ' a: { default: "" }', + 'nodes:', + ' m:', + ' kind: menu', + ' prompt: Pick', + ' options: { "1": "{{a}}" }', + ' exits: { "1": m, no_input: m, invalid: m }', + '', + ].join('\n'), + ); + expect(fill(flow, {})).toEqual({ errors: [{ code: 'menu_without_options', name: 'm' }] }); + expect('flow' in fill(flow, { a: 'Yes' })).toBe(true); + }); + + it('leaves a malformed template as written', () => { + const flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: a', + 'variables:', + ' b: { default: x }', + 'nodes:', + ' a:', + ' kind: hangup', + ' prompt: "Hi {{b"', + '', + ].join('\n'), + ); + expect(filled(flow, { b: 'y' }).nodes.a).toMatchObject({ prompt: 'Hi {{b' }); }); it('does not touch the input and returns a flow without variables unchanged', () => { From 50f37ee20c52572b8e37bcd4daff44e2e567f4f2 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:55:43 +1300 Subject: [PATCH 09/13] docs: state fill contract --- crates/wavekat-flow/src/vars.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/crates/wavekat-flow/src/vars.rs b/crates/wavekat-flow/src/vars.rs index e153acd..50523bd 100644 --- a/crates/wavekat-flow/src/vars.rs +++ b/crates/wavekat-flow/src/vars.rs @@ -197,8 +197,14 @@ fn render(segments: &[Segment<'_>], effective: &dyn Fn(&str) -> String, out: &mu /// exactly `{{name}}` with an empty value is removed, with its exit. An audio /// prompt with a `template` stays audio (dropping the template) unless a /// variable it names got a non-default value; then it becomes the filled -/// text. A flow without variables comes back as a clone. A malformed template is left as written (validation rejects those -/// before fill is reached). +/// text. A flow without variables comes back as a clone. A malformed template +/// is left as written (validation rejects those before fill is reached). +/// +/// Contract: validate the source flow first (`validate_outbound`); the result +/// is not meant to be re-validated (a value may itself hold `{{`). `fill` +/// keeps options and exits consistent on its own. Errors: `variable_unknown`, +/// `variable_too_long`, and `menu_without_options` when every option of a menu +/// would be dropped. pub fn fill(flow: &Flow, values: &BTreeMap) -> Result> { // No variables: `{{` is ordinary text (v1-v3), so there is nothing to fill. if flow.variables.is_empty() && values.is_empty() { From 65e8d44ee871fdf9785ae54d723f676d3f288d8d Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:55:43 +1300 Subject: [PATCH 10/13] chore: restore Cargo.lock --- Cargo.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 6d2b6f1..50040d9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -121,7 +121,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" name = "compat-old-readers" version = "0.0.1" dependencies = [ - "wavekat-flow 0.0.12", + "wavekat-flow 0.0.11", "wavekat-flow 0.0.6", ] @@ -1562,7 +1562,7 @@ dependencies = [ [[package]] name = "wavekat-flow" -version = "0.0.6" +version = "0.0.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "aa8de375720073be7590b3e3a0cb70ef88569bc483c3938d147d7a02c12408ca" dependencies = [ From a953d7b2b541e83bff6ad1f888ef69080b10d5de Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 21:57:00 +1300 Subject: [PATCH 11/13] feat: report menu choice labels --- crates/wavekat-flow/src/engine.rs | 44 +++++++++++++++++++++++++++++-- crates/wavekat-flow/src/trace.rs | 12 ++++++--- 2 files changed, 51 insertions(+), 5 deletions(-) diff --git a/crates/wavekat-flow/src/engine.rs b/crates/wavekat-flow/src/engine.rs index 681cce2..66235ae 100644 --- a/crates/wavekat-flow/src/engine.rs +++ b/crates/wavekat-flow/src/engine.rs @@ -701,6 +701,7 @@ async fn run_menu( "menu", StepDetail::MenuChoice { digit: digit.as_key().to_string(), + label: options.get(digit.as_key()).cloned(), }, ); return goto(id, node, digit.as_key()); @@ -1071,7 +1072,10 @@ nodes: assert_eq!(trace.steps[1].detail, StepDetail::Hours { open: false }); assert_eq!( trace.steps[2].detail, - StepDetail::MenuChoice { digit: "1".into() } + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Hours".into()) + } ); // The caller heard the opening-hours greeting. assert!(fx @@ -1080,6 +1084,39 @@ nodes: .any(|s| s.contains("open Tuesday to Sunday"))); } + #[tokio::test] + async fn menu_choice_carries_its_label() { + let mut fx = MockEffects::new(closed_time()) + .digits([Some(Digit::D1)]) + .message_secs(5); + let trace = run_trace(&luigis(), &mut fx).await; + assert_eq!( + trace.steps[2].detail, + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Hours".into()) + } + ); + let json = serde_json::to_value(&trace.steps[2].detail).unwrap(); + assert_eq!(json["label"], "Hours"); + } + + #[test] + fn old_menu_choice_json_still_reads() { + let d: StepDetail = + serde_json::from_str(r#"{"detail":"menu_choice","digit":"1"}"#).unwrap(); + assert_eq!( + d, + StepDetail::MenuChoice { + digit: "1".into(), + label: None + } + ); + // No label key is written when there is none. + let json = serde_json::to_value(&d).unwrap(); + assert!(json.get("label").is_none()); + } + #[tokio::test] async fn closed_silence_takes_no_input_exit() { // No digits scripted → every collect times out → no_input. @@ -1121,7 +1158,10 @@ nodes: assert_eq!( trace.steps[2].detail, - StepDetail::MenuChoice { digit: "1".into() } + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Hours".into()) + } ); assert_eq!(trace.outcome, FlowOutcome::MessageLeft); } diff --git a/crates/wavekat-flow/src/trace.rs b/crates/wavekat-flow/src/trace.rs index 2e878ee..57796ed 100644 --- a/crates/wavekat-flow/src/trace.rs +++ b/crates/wavekat-flow/src/trace.rs @@ -12,7 +12,7 @@ use std::time::Instant; -use serde::Serialize; +use serde::{Deserialize, Serialize}; use crate::NodeId; @@ -88,7 +88,7 @@ pub struct TraceStep { /// The per-node outcome. Tagged so it serializes to a self-describing object /// the renderer can switch on. -#[derive(Debug, Clone, PartialEq, Serialize)] +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(tag = "detail", rename_all = "snake_case")] pub enum StepDetail { /// A greeting/`say_hours` spoke and continued. @@ -96,7 +96,13 @@ pub enum StepDetail { /// An `hours` branch resolved. Hours { open: bool }, /// A menu caller pressed a mapped option. - MenuChoice { digit: String }, + /// `label` is the pressed option's label from the flow (absent in + /// traces written before labels were reported). + MenuChoice { + digit: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + label: Option, + }, /// A menu exhausted its retries with no input at all. MenuNoInput, /// A menu exhausted its retries hearing only unmapped keys. From c6677a8fbed1247887b008ae2ccd892e4dacc926 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 23:18:12 +1300 Subject: [PATCH 12/13] fix: harden flow variables before release Final-review fixes for schema v4 flow variables, in both languages: - A `note` (flow or step) is a comment and is never scanned for placeholders (conformance v4/valid/placeholder-in-note). - `fill` returns a plain v3 document: schema_version 4+ becomes 3, and the result passes validate_outbound and round-trips on its own. A filled prompt over the prompt limit is refused with `prompt_too_long` (Rust FillError::PromptTooLong { node }). Fill corpus outputs are now v3; new cases prompt-too-long, all-options-dropped, value-with-braces. - `engine::run` fills a flow that still declares variables with its defaults before running it; a fill error ends the run as a defect. - A variable default longer than its max_len is refused with `variable_default_too_long`. - Schema, README and corpus wording describe the real v4 behaviour; module docs state that a blank value falls back to the default. - compat-old-readers: the oldest reader refuses v4 documents with an error, not a panic. --- README.md | 2 +- conformance/README.md | 10 +- .../fill/all-options-dropped.expected.json | 1 + .../fill/all-options-dropped.input.yaml | 16 +++ .../fill/all-options-dropped.values.json | 1 + conformance/fill/audio-kept.expected.yaml | 2 +- conformance/fill/audio-text.expected.yaml | 2 +- conformance/fill/blank-unicode.expected.yaml | 2 +- conformance/fill/defaults.expected.yaml | 2 +- conformance/fill/option3.expected.yaml | 2 +- .../fill/prompt-too-long.expected.json | 1 + conformance/fill/prompt-too-long.input.yaml | 10 ++ conformance/fill/prompt-too-long.values.json | 1 + conformance/fill/two-options.expected.yaml | 2 +- .../fill/value-with-braces.expected.yaml | 18 +++ conformance/fill/value-with-braces.input.yaml | 25 ++++ .../fill/value-with-braces.values.json | 1 + .../variable-default-too-long.expected.json | 5 + .../v4/invalid/variable-default-too-long.yaml | 10 ++ .../v4/valid/ask-question.expected.json | 2 +- .../valid/placeholder-in-note.expected.json | 5 + conformance/v4/valid/placeholder-in-note.yaml | 17 +++ .../rendered-template-prompt.expected.json | 2 +- .../compat-old-readers/tests/old_readers.rs | 30 +++++ crates/wavekat-flow/README.md | 3 +- .../wavekat-flow/schema/flow.v4.schema.json | 4 +- crates/wavekat-flow/src/engine.rs | 80 ++++++++++++ crates/wavekat-flow/src/validate.rs | 60 ++++++++- crates/wavekat-flow/src/vars.rs | 118 +++++++++++++++--- crates/wavekat-flow/tests/conformance.rs | 16 ++- .../src/generated/flow.v4.schema.json | 4 +- packages/flow-schema/src/generated/model.ts | 4 +- packages/flow-schema/src/generated/schema.ts | 4 +- packages/flow-schema/src/model.ts | 3 + packages/flow-schema/src/validate.ts | 25 +++- packages/flow-schema/src/vars.ts | 62 ++++++--- packages/flow-schema/test/conformance.test.ts | 10 +- packages/flow-schema/test/vars.test.ts | 57 ++++++++- schema/README.md | 22 ++-- schema/flow.v4.schema.json | 4 +- 40 files changed, 563 insertions(+), 82 deletions(-) create mode 100644 conformance/fill/all-options-dropped.expected.json create mode 100644 conformance/fill/all-options-dropped.input.yaml create mode 100644 conformance/fill/all-options-dropped.values.json create mode 100644 conformance/fill/prompt-too-long.expected.json create mode 100644 conformance/fill/prompt-too-long.input.yaml create mode 100644 conformance/fill/prompt-too-long.values.json create mode 100644 conformance/fill/value-with-braces.expected.yaml create mode 100644 conformance/fill/value-with-braces.input.yaml create mode 100644 conformance/fill/value-with-braces.values.json create mode 100644 conformance/v4/invalid/variable-default-too-long.expected.json create mode 100644 conformance/v4/invalid/variable-default-too-long.yaml create mode 100644 conformance/v4/valid/placeholder-in-note.expected.json create mode 100644 conformance/v4/valid/placeholder-in-note.yaml diff --git a/README.md b/README.md index e67f0db..2a05dd0 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ code per language — **pinned by the shared corpus**, not generated. See ## Versioning -- `schema_version` is a property of the **document** (currently `3`). Each +- `schema_version` is a property of the **document** (currently `4`). Each version gets its own `schema/flow.vN.schema.json` and its own frozen `conformance/vN/` corpus. Growth is additive; an unsupported version is rejected, never silently migrated. diff --git a/conformance/README.md b/conformance/README.md index cc940b7..01bad02 100644 --- a/conformance/README.md +++ b/conformance/README.md @@ -28,10 +28,12 @@ of the outbound gate, which includes the base validation. These cases stay out of the top-level `valid/`/`invalid/` buckets because a flow refused for outbound — one with a `ring` step, say — is a perfectly good inbound flow. -`fill/` pins `fill` (flow variables): per case, `.input.yaml` (a v4 flow), -`.values.json` (the caller's values), and either `.expected.yaml` -(the filled flow, compared after canonical serialization) or -`.expected.json` = `{"errors": [codes]}` (the exact refusal). +`fill/` pins `fill` (flow variables): per case, `.input.yaml` (a v4 flow +that passes `validate_outbound`), `.values.json` (the caller's values), +and either `.expected.yaml` (the filled flow, compared after canonical +serialization) or `.expected.json` = `{"errors": [codes]}` (the exact +refusal). A filled flow is a `schema_version: 3` document: both suites also +check that it passes `validate_outbound` on its own and reads back as itself. Every `.yaml` has a sibling `.expected.json`: diff --git a/conformance/fill/all-options-dropped.expected.json b/conformance/fill/all-options-dropped.expected.json new file mode 100644 index 0000000..9b79fa0 --- /dev/null +++ b/conformance/fill/all-options-dropped.expected.json @@ -0,0 +1 @@ +{"errors":["menu_without_options"]} diff --git a/conformance/fill/all-options-dropped.input.yaml b/conformance/fill/all-options-dropped.input.yaml new file mode 100644 index 0000000..718dbf4 --- /dev/null +++ b/conformance/fill/all-options-dropped.input.yaml @@ -0,0 +1,16 @@ +schema_version: 4 +id: flow_all_options_dropped +name: Every option optional +entry: ask +variables: + option1: { description: Answer for key 1, default: "", max_len: 80 } + option2: { description: Answer for key 2, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "Pick one.{{#option1}} Press 1 for {{option1}}.{{/option1}}{{#option2}} Press 2 for {{option2}}.{{/option2}}" + options: { "1": "{{option1}}", "2": "{{option2}}" } + exits: { "1": bye, "2": bye, no_input: bye, invalid: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/conformance/fill/all-options-dropped.values.json b/conformance/fill/all-options-dropped.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/all-options-dropped.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/fill/audio-kept.expected.yaml b/conformance/fill/audio-kept.expected.yaml index 9b38cef..b96dbf5 100644 --- a/conformance/fill/audio-kept.expected.yaml +++ b/conformance/fill/audio-kept.expected.yaml @@ -1,4 +1,4 @@ -schema_version: 4 +schema_version: 3 id: flow_audio name: Audio template entry: hi diff --git a/conformance/fill/audio-text.expected.yaml b/conformance/fill/audio-text.expected.yaml index 0fd107e..5be5bd6 100644 --- a/conformance/fill/audio-text.expected.yaml +++ b/conformance/fill/audio-text.expected.yaml @@ -1,4 +1,4 @@ -schema_version: 4 +schema_version: 3 id: flow_audio name: Audio template entry: hi diff --git a/conformance/fill/blank-unicode.expected.yaml b/conformance/fill/blank-unicode.expected.yaml index 68ea1c9..e19c786 100644 --- a/conformance/fill/blank-unicode.expected.yaml +++ b/conformance/fill/blank-unicode.expected.yaml @@ -1,4 +1,4 @@ -schema_version: 4 +schema_version: 3 id: flow_ask_question name: Ask a question entry: ask diff --git a/conformance/fill/defaults.expected.yaml b/conformance/fill/defaults.expected.yaml index 68ea1c9..e19c786 100644 --- a/conformance/fill/defaults.expected.yaml +++ b/conformance/fill/defaults.expected.yaml @@ -1,4 +1,4 @@ -schema_version: 4 +schema_version: 3 id: flow_ask_question name: Ask a question entry: ask diff --git a/conformance/fill/option3.expected.yaml b/conformance/fill/option3.expected.yaml index ad1b803..662c274 100644 --- a/conformance/fill/option3.expected.yaml +++ b/conformance/fill/option3.expected.yaml @@ -1,4 +1,4 @@ -schema_version: 4 +schema_version: 3 id: flow_ask_question name: Ask a question entry: ask diff --git a/conformance/fill/prompt-too-long.expected.json b/conformance/fill/prompt-too-long.expected.json new file mode 100644 index 0000000..ae7cce0 --- /dev/null +++ b/conformance/fill/prompt-too-long.expected.json @@ -0,0 +1 @@ +{"errors":["prompt_too_long"]} diff --git a/conformance/fill/prompt-too-long.input.yaml b/conformance/fill/prompt-too-long.input.yaml new file mode 100644 index 0000000..cb1f66a --- /dev/null +++ b/conformance/fill/prompt-too-long.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_prompt_too_long +name: A prompt that grows past the limit +entry: say +variables: + detail: { description: Read out five times, default: "", max_len: 500 } +nodes: + say: + kind: hangup + prompt: "{{detail}} {{detail}} {{detail}} {{detail}} {{detail}}" diff --git a/conformance/fill/prompt-too-long.values.json b/conformance/fill/prompt-too-long.values.json new file mode 100644 index 0000000..f7ee735 --- /dev/null +++ b/conformance/fill/prompt-too-long.values.json @@ -0,0 +1 @@ +{"detail": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"} diff --git a/conformance/fill/two-options.expected.yaml b/conformance/fill/two-options.expected.yaml index 15bbe95..f572165 100644 --- a/conformance/fill/two-options.expected.yaml +++ b/conformance/fill/two-options.expected.yaml @@ -1,4 +1,4 @@ -schema_version: 4 +schema_version: 3 id: flow_ask_question name: Ask a question entry: ask diff --git a/conformance/fill/value-with-braces.expected.yaml b/conformance/fill/value-with-braces.expected.yaml new file mode 100644 index 0000000..141834a --- /dev/null +++ b/conformance/fill/value-with-braces.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 3 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Is {{option1}} a {x}? Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/value-with-braces.input.yaml b/conformance/fill/value-with-braces.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/value-with-braces.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/value-with-braces.values.json b/conformance/fill/value-with-braces.values.json new file mode 100644 index 0000000..3ddf43a --- /dev/null +++ b/conformance/fill/value-with-braces.values.json @@ -0,0 +1 @@ +{"question":"Is {{option1}} a {x}?"} diff --git a/conformance/v4/invalid/variable-default-too-long.expected.json b/conformance/v4/invalid/variable-default-too-long.expected.json new file mode 100644 index 0000000..789960d --- /dev/null +++ b/conformance/v4/invalid/variable-default-too-long.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A variable's `default` is held to its own `max_len`, counted in characters like a caller's value. A default that would itself be refused as a value is refused when the flow is checked, not first noticed on a call.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["variable_default_too_long"] } +} diff --git a/conformance/v4/invalid/variable-default-too-long.yaml b/conformance/v4/invalid/variable-default-too-long.yaml new file mode 100644 index 0000000..c450fa4 --- /dev/null +++ b/conformance/v4/invalid/variable-default-too-long.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_default_too_long +name: Default longer than its limit +entry: bye +variables: + question: { description: The question, default: "Is this too long?", max_len: 10 } +nodes: + bye: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/v4/valid/ask-question.expected.json b/conformance/v4/valid/ask-question.expected.json index db8296f..7bc8b1b 100644 --- a/conformance/v4/valid/ask-question.expected.json +++ b/conformance/v4/valid/ask-question.expected.json @@ -1,5 +1,5 @@ { - "description": "Flow variables: a top-level `variables` map declares details filled per call. The `{{name}}` placeholders in the prompt and menu labels are plain text to this version of the format; they are read and checked by a later step, so here they only have to be accepted. The 9 key loops back to the same menu, which waits for a key and so is not an unbounded loop.", + "description": "Flow variables: a top-level `variables` map declares details filled per call. The prompt and menu labels use `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks, and each one names a declared variable, so the flow is accepted. The empty defaults of option3 and option4 make those keys optional: filled with no values, their blocks are dropped from the prompt and their bare `{{option3}}`/`{{option4}}` labels remove the options and their exits. The 9 key loops back to the same menu, which waits for a key and so is not an unbounded loop.", "structurallyValid": true, "semantic": { "ok": true, "errors": [] } } diff --git a/conformance/v4/valid/placeholder-in-note.expected.json b/conformance/v4/valid/placeholder-in-note.expected.json new file mode 100644 index 0000000..bfbf23a --- /dev/null +++ b/conformance/v4/valid/placeholder-in-note.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A `note` is a comment for people and is never read by the engine, so it is never scanned for placeholders: a `{{q}}` there, declared or not, and even a malformed `{{#`, changes no verdict. This holds for the flow's top-level note and for every step's note.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v4/valid/placeholder-in-note.yaml b/conformance/v4/valid/placeholder-in-note.yaml new file mode 100644 index 0000000..1d64136 --- /dev/null +++ b/conformance/v4/valid/placeholder-in-note.yaml @@ -0,0 +1,17 @@ +schema_version: 4 +id: flow_placeholder_note +name: Placeholders in notes +note: "Fill {{question}} per call; {{q}} is not a variable, and {{#half open is fine here." +entry: ask +variables: + question: { description: The question, default: "Anything?", max_len: 100 } +nodes: + ask: + kind: greeting + note: "Speaks {{question}}. {{q}} in a note is never read." + prompt: "{{question}}" + exits: { next: bye } + bye: + kind: hangup + note: "{{q}}" + prompt: Goodbye. diff --git a/conformance/v4/valid/rendered-template-prompt.expected.json b/conformance/v4/valid/rendered-template-prompt.expected.json index d90b6fc..af6bf6a 100644 --- a/conformance/v4/valid/rendered-template-prompt.expected.json +++ b/conformance/v4/valid/rendered-template-prompt.expected.json @@ -1,5 +1,5 @@ { - "description": "An audio prompt may keep the `template` it was voiced from, so a call that overrides a variable can speak the filled text instead of the clip. The clip is a required asset as ever; `template` is advisory to a reader that does not fill (here it is plain text, not yet scanned).", + "description": "An audio prompt may keep the `template` it was voiced from, so a call that overrides a variable can speak the filled text instead of the clip. The clip is a required asset as ever; Its placeholders are checked like a text prompt's, so `{{name}}` must be declared. A reader that does not fill ignores `template` and plays the clip.", "structurallyValid": true, "semantic": { "ok": true, "errors": [] }, "requiredAssets": ["vprompt_abc123"] diff --git a/crates/compat-old-readers/tests/old_readers.rs b/crates/compat-old-readers/tests/old_readers.rs index 41330a3..ac80858 100644 --- a/crates/compat-old-readers/tests/old_readers.rs +++ b/crates/compat-old-readers/tests/old_readers.rs @@ -168,3 +168,33 @@ fn old_reader_refuses_a_screened_transfer_rather_than_run_it_blind() { wavekat_flow::validate::validate(&wavekat_flow::Flow::from_yaml(&yaml).unwrap()).is_ok() ); } + +#[test] +fn old_reader_refuses_a_flow_with_variables_rather_than_speak_the_braces() { + // `variables` is what gives a `{{name}}` placeholder its meaning. A + // reader that does not know it would speak the braces as written, so + // the document declares version 4 and the old reader must refuse it + // with an error. A panic would take the daemon down with it, so every + // v4 document is read inside `catch_unwind`. + for name in [ + "ask-question", + "rendered-template-prompt", + "placeholder-in-note", + ] { + let yaml = fs::read_to_string(corpus().join(format!("v4/valid/{name}.yaml"))).unwrap(); + assert!( + !old_flow::SUPPORTED_SCHEMA_VERSIONS.contains(&schema_version(&yaml)), + "{OLDEST_READER} claims to read version 4" + ); + let refused = std::panic::catch_unwind(|| match old_flow::Flow::from_yaml(&yaml) { + Err(_) => true, + Ok(old) => old_validate(&old).is_err(), + }) + .unwrap_or_else(|_| panic!("{OLDEST_READER} panicked on v4/valid/{name}")); + assert!(refused, "{OLDEST_READER} accepted v4/valid/{name}"); + assert!( + wavekat_flow::validate::validate(&wavekat_flow::Flow::from_yaml(&yaml).unwrap()) + .is_ok() + ); + } +} diff --git a/crates/wavekat-flow/README.md b/crates/wavekat-flow/README.md index c9d8bcb..ab14dc6 100644 --- a/crates/wavekat-flow/README.md +++ b/crates/wavekat-flow/README.md @@ -32,7 +32,8 @@ this crate. | `edit` | Load a document to edit it: `edit::load` refuses unknown fields (a save would delete them) and unsupported versions, and returns the YAML comments a save drops; `edit::load_draft` fills a new draft's missing `id`/`name` | | `Flow::to_yaml` | The canonical text of a flow, byte for byte what the TypeScript `serializeFlow` writes. Edit by parsing, changing the flow, and calling this | | `hours` | Business-hours / timezone math (IANA zones, holiday exceptions) | -| `engine` | The flow interpreter + the `FlowEffects` async trait your runtime implements | +| `vars` | Flow variables (v4): the `{{name}}` / `{{#name}}…{{/name}}` placeholder syntax, and `vars::fill`, which turns a flow plus a call's values into a plain v3 flow that validates on its own | +| `engine` | The flow interpreter + the `FlowEffects` async trait your runtime implements; a flow that still declares variables is filled with its defaults before it runs | | `trace` | Serializable run traces emitted by the engine | | `FLOW_V1_SCHEMA` | The normative JSON Schema, bundled as a string for structural validation | diff --git a/crates/wavekat-flow/schema/flow.v4.schema.json b/crates/wavekat-flow/schema/flow.v4.schema.json index 95b693a..893386e 100644 --- a/crates/wavekat-flow/schema/flow.v4.schema.json +++ b/crates/wavekat-flow/schema/flow.v4.schema.json @@ -30,7 +30,7 @@ "type": "string" }, "variables": { - "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", "type": "object", "additionalProperties": { "$ref": "#/$defs/Variable" } }, @@ -183,7 +183,7 @@ "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, "prompt": { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", "type": "object", "additionalProperties": { "type": "string" } }, diff --git a/crates/wavekat-flow/src/engine.rs b/crates/wavekat-flow/src/engine.rs index 66235ae..4fb1742 100644 --- a/crates/wavekat-flow/src/engine.rs +++ b/crates/wavekat-flow/src/engine.rs @@ -28,6 +28,7 @@ use crate::book; use crate::hours::{self, HoursError}; use crate::model::{Flow, HoursException, MessageTone, Node, Prompt, WeeklySchedule}; use crate::trace::{FlowOutcome, StepDetail, Trace}; +use crate::vars::{self, FillError}; use crate::NodeId; /// Backstop against a cycle in a flow that somehow reached the engine @@ -245,6 +246,8 @@ enum EngineError { MissingExit { node: NodeId, exit: String }, #[error("hours evaluation at {node:?} failed: {source}")] Hours { node: NodeId, source: HoursError }, + #[error("the flow's variables could not be filled with their defaults: {}", .0.iter().map(|e| format!("{} ({e})", e.code())).collect::>().join(", "))] + Fill(Vec), } impl EngineError { @@ -277,7 +280,25 @@ enum Step { /// caller hangs up mid-flow — still holds the steps executed so far. A /// cancelled run never writes `outcome`; it keeps the [`FlowOutcome::Defect`] /// placeholder. +/// +/// A flow that still declares `variables` is never run as written: it is +/// first filled with its defaults ([`vars::fill`] with no values), so the +/// caller never hears a placeholder. Fill the flow yourself to run it with a +/// call's values. A flow that cannot be filled ends as a defect before any +/// node runs. pub async fn run(flow: &Flow, fx: &mut E, trace: &mut Trace) { + let filled; + let flow = if flow.variables.is_empty() { + flow + } else { + match vars::fill(flow, &std::collections::BTreeMap::new()) { + Ok(f) => { + filled = f; + &filled + } + Err(errs) => return abort(trace, EngineError::Fill(errs)), + } + }; let mut current = flow.entry.clone(); for _ in 0..MAX_STEPS { @@ -1101,6 +1122,65 @@ nodes: assert_eq!(json["label"], "Hours"); } + const ASK: &str = include_str!("../../../conformance/v4/valid/ask-question.yaml"); + + #[tokio::test] + async fn an_unfilled_flow_runs_with_its_defaults() { + // Handed the v4 flow as written, not a filled one: the engine fills + // it with the defaults rather than speak the braces. + let flow = Flow::from_yaml(ASK).unwrap(); + let mut fx = MockEffects::new(open_time()).digits([Some(Digit::D1)]); + let trace = run_trace(&flow, &mut fx).await; + assert_eq!(trace.outcome, FlowOutcome::HungUp); + assert_eq!( + trace.steps[0].detail, + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Yes".into()) + } + ); + assert!(fx.spoken[0].contains("Press 1 for Yes."), "{:?}", fx.spoken); + assert!( + fx.spoken.iter().all(|s| !s.contains("{{")), + "{:?}", + fx.spoken + ); + } + + #[tokio::test] + async fn an_unfilled_flow_drops_an_empty_option() { + // option3's default is empty, so key 3 is not an option: every press + // is invalid (retries: 2, so three tries) and the call ends at `bye`. + let flow = Flow::from_yaml(ASK).unwrap(); + let mut fx = MockEffects::new(open_time()).digits([ + Some(Digit::D3), + Some(Digit::D3), + Some(Digit::D3), + ]); + let trace = run_trace(&flow, &mut fx).await; + assert_eq!(trace.steps[0].detail, StepDetail::MenuInvalid); + assert_eq!(trace.outcome, FlowOutcome::HungUp); + assert!(fx.spoken.iter().any(|s| s.contains("No answer recorded"))); + } + + #[tokio::test] + async fn a_flow_that_cannot_be_filled_is_a_defect() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: m\nvariables:\n a: { default: \"\" }\nnodes:\n m:\n kind: menu\n prompt: Pick\n options: { \"1\": \"{{a}}\" }\n exits: { \"1\": m, no_input: m, invalid: m }\n", + ) + .unwrap(); + let mut fx = MockEffects::new(open_time()); + let trace = run_trace(&flow, &mut fx).await; + assert_eq!(trace.outcome, FlowOutcome::Defect); + assert!(trace.steps.is_empty()); + assert!(fx.spoken.is_empty()); + assert!(trace + .error + .as_deref() + .unwrap() + .contains("menu_without_options")); + } + #[test] fn old_menu_choice_json_still_reads() { let d: StepDetail = diff --git a/crates/wavekat-flow/src/validate.rs b/crates/wavekat-flow/src/validate.rs index 5c4693a..17d67c1 100644 --- a/crates/wavekat-flow/src/validate.rs +++ b/crates/wavekat-flow/src/validate.rs @@ -25,7 +25,7 @@ use crate::SUPPORTED_SCHEMA_VERSIONS; /// prompt that would trap a caller under minutes of TTS; generous enough that /// no real greeting hits it. Audio-asset prompts are unbounded here. Twin: /// `packages/flow-schema/src/model.ts` `MAX_PROMPT_CHARS`. -const MAX_PROMPT_CHARS: usize = 2000; +pub(crate) const MAX_PROMPT_CHARS: usize = 2000; /// The DTMF keys a `menu` option may be keyed by. Twin: /// `packages/flow-schema/src/model.ts` `VALID_DIGITS`. @@ -156,6 +156,9 @@ pub enum ValidationError { #[error("variable {name:?} max_len is {value} (allowed: 1-{MAX_VARIABLE_LEN})")] VariableMaxLenOutOfRange { name: String, value: u64 }, + #[error("variable {name:?} default is {len} characters; its max_len is {max}")] + VariableDefaultTooLong { name: String, max: u64, len: u64 }, + #[error("node {node:?} {field} has a malformed placeholder: {reason}")] TemplateSyntax { node: NodeId, @@ -233,6 +236,7 @@ impl ValidationError { ValidationError::VariablesRequireNewerSchema { .. } => "field_requires_newer_schema", ValidationError::VariableBadName { .. } => "variable_bad_name", ValidationError::VariableMaxLenOutOfRange { .. } => "variable_max_len_out_of_range", + ValidationError::VariableDefaultTooLong { .. } => "variable_default_too_long", ValidationError::TemplateSyntax { .. } => "template_syntax", ValidationError::UnknownVariable { .. } => "unknown_variable", ValidationError::PlaceholderNotAllowed { .. } => "placeholder_not_allowed", @@ -370,9 +374,10 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { } } -/// Declared variable names and `max_len`s, and placeholder-looking text in -/// the flow's own string fields. Only on a v4 document: before that `{{` -/// is ordinary text and `variables` is refused as a whole. +/// Declared variable names, `max_len`s and defaults, and placeholder-looking +/// text in the flow's own `id` and `name` (its `note` is a comment and never +/// scanned). Only on a v4 document: before that `{{` is ordinary text and +/// `variables` is refused as a whole. fn check_variables(flow: &Flow, errs: &mut Vec) { if flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { return; @@ -393,6 +398,15 @@ fn check_variables(flow: &Flow, errs: &mut Vec) { value: max_len, }); } + // A default is held to the same limit as a caller's value. + let len = flow.variables[name].default.chars().count() as u64; + if len > max_len { + errs.push(ValidationError::VariableDefaultTooLong { + name: name.clone(), + max: max_len, + len, + }); + } } let mut fields: Vec = [("id", &flow.id), ("name", &flow.name)] .into_iter() @@ -453,13 +467,15 @@ fn check_placeholders(id: &NodeId, node: &Node, flow: &Flow, errs: &mut Vec "variable_unknown", FillError::TooLong { .. } => "variable_too_long", FillError::NoOptions { .. } => "menu_without_options", + FillError::PromptTooLong { .. } => "prompt_too_long", } } } @@ -188,26 +201,30 @@ fn render(segments: &[Segment<'_>], effective: &dyn Fn(&str) -> String, out: &mu } /// Turn a flow with variables plus a caller's values into a plain flow the -/// engine can run: every placeholder replaced, `variables` gone, -/// `schema_version` unchanged. Twin: `vars.ts` `fill`. +/// engine can run: every placeholder replaced, `variables` and every audio +/// prompt's `template` gone, and a declared `schema_version` of 4 or more +/// set to 3. Twin: `vars.ts` `fill`. /// /// A name's effective value is the caller's (trimmed, control characters -/// stripped) when that is non-empty, else the variable's default. Values are -/// inserted as text and never parsed again. A menu option whose label is -/// exactly `{{name}}` with an empty value is removed, with its exit. An audio -/// prompt with a `template` stays audio (dropping the template) unless a -/// variable it names got a non-default value; then it becomes the filled -/// text. A flow without variables comes back as a clone. A malformed template -/// is left as written (validation rejects those before fill is reached). +/// stripped) when that is non-empty, else the variable's default; so a blank +/// value falls back to the default and cannot clear it. Values are inserted +/// as text and never parsed again. A menu option whose label is exactly a +/// bare `{{name}}` with an empty effective value is removed, with its exit; +/// any other label is filled and kept. An audio prompt with a `template` +/// stays audio (dropping the template) unless a variable it names got a +/// non-default value; then it becomes the filled text. A v1-v3 flow without +/// variables comes back as a clone. A malformed template is left as written +/// (validation rejects those before fill is reached). /// -/// Contract: validate the source flow first (`validate_outbound`); the result -/// is not meant to be re-validated (a value may itself hold `{{`). `fill` -/// keeps options and exits consistent on its own. Errors: `variable_unknown`, -/// `variable_too_long`, and `menu_without_options` when every option of a menu -/// would be dropped. +/// Contract: validate the source flow first (`validate_outbound`). The result +/// is a v3 document that validates on its own: a value holding `{{` is plain +/// text in v3, and `fill` keeps options and exits consistent. Errors: +/// `variable_unknown`, `variable_too_long`, `menu_without_options` when every +/// option of a menu would be dropped, and `prompt_too_long` when a filled +/// prompt is longer than validation allows. pub fn fill(flow: &Flow, values: &BTreeMap) -> Result> { - // No variables: `{{` is ordinary text (v1-v3), so there is nothing to fill. - if flow.variables.is_empty() && values.is_empty() { + // No variables before v4: `{{` is ordinary text, so there is nothing to fill. + if flow.variables.is_empty() && values.is_empty() && flow.schema_version < 4 { return Ok(flow.clone()); } let mut errors = Vec::new(); @@ -252,7 +269,12 @@ pub fn fill(flow: &Flow, values: &BTreeMap) -> Result= 4 { + out.schema_version = 3; + } for (node_id, node) in out.nodes.iter_mut() { + let mut too_long = false; for (_, prompt) in node.prompt_slots_mut() { match prompt { Prompt::Text(text) => *text = fill_text(text), @@ -268,6 +290,14 @@ pub fn fill(flow: &Flow, values: &BTreeMap) -> Result crate::validate::MAX_PROMPT_CHARS; + } + } + if too_long { + errors.push(FillError::PromptTooLong { + node: node_id.clone(), + }); } if let Node::Menu { options, exits, .. } = node { let mut dropped = Vec::new(); @@ -458,7 +488,7 @@ mod tests { ); assert!(!exits.contains(&"3".to_string()) && !exits.contains(&"4".to_string())); assert!(filled.variables.is_empty()); - assert_eq!(filled.schema_version, 4); + assert_eq!(filled.schema_version, 3); } #[test] @@ -573,6 +603,60 @@ mod tests { assert!(menu(&filled).0.contains("{{option1}} {x}")); } + #[test] + fn filled_flow_with_braces_in_a_value_validates_as_v3() { + let filled = fill(&ask(), &vals(&[("question", "Is {{x}} {{#y}} ok?")])).unwrap(); + assert_eq!(filled.schema_version, 3); + assert!(menu(&filled).0.contains("Is {{x}} {{#y}} ok?")); + crate::validate::validate_outbound(&filled).unwrap(); + // And it reads back as itself: in v3 the braces are plain text. + let text = filled.to_yaml(); + let back = Flow::from_yaml(&text).unwrap(); + assert_eq!(back.to_yaml(), text); + crate::validate::validate_outbound(&back).unwrap(); + } + + #[test] + fn a_v4_flow_without_variables_still_comes_back_as_v3() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_a, template: Hello }\n", + ) + .unwrap(); + crate::validate::validate_outbound(&flow).unwrap(); + let filled = fill(&flow, &BTreeMap::new()).unwrap(); + assert_eq!(filled.schema_version, 3); + assert!(matches!( + &filled.nodes["a"], + Node::Hangup { + prompt: Some(Prompt::Audio { template: None, .. }), + .. + } + )); + crate::validate::validate_outbound(&filled).unwrap(); + } + + #[test] + fn a_filled_prompt_over_the_limit_is_an_error() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n d: { default: \"\", max_len: 500 }\nnodes:\n a:\n kind: hangup\n prompt: \"{{d}}{{d}}{{d}}{{d}}\"\n", + ) + .unwrap(); + // 4 x 500 = 2000: exactly the limit is fine. + assert!(fill(&flow, &vals(&[("d", &"问".repeat(500))])).is_ok()); + let mut over = flow.clone(); + let Node::Hangup { + prompt: Some(Prompt::Text(t)), + .. + } = &mut over.nodes["a"] + else { + unreachable!() + }; + t.push('!'); + let errs = fill(&over, &vals(&[("d", &"问".repeat(500))])).unwrap_err(); + assert_eq!(errs, vec![FillError::PromptTooLong { node: "a".into() }]); + assert_eq!(errs[0].code(), "prompt_too_long"); + } + #[test] fn dropping_every_option_is_an_error() { let flow = Flow::from_yaml( diff --git a/crates/wavekat-flow/tests/conformance.rs b/crates/wavekat-flow/tests/conformance.rs index 8e70f83..0d372d6 100644 --- a/crates/wavekat-flow/tests/conformance.rs +++ b/crates/wavekat-flow/tests/conformance.rs @@ -303,12 +303,26 @@ fn corpus_fill_matches_expectations() { &fs::read_to_string(dir.join(format!("{case}.values.json"))).unwrap(), ) .unwrap(); + // Every source is a flow that passes the gate fill expects in front of it. + wavekat_flow::validate::validate_outbound(&flow) + .unwrap_or_else(|e| panic!("fill/{case} source should validate: {e:?}")); let result = wavekat_flow::vars::fill(&flow, &values); let expected_yaml = dir.join(format!("{case}.expected.yaml")); if expected_yaml.exists() { let filled = result.unwrap_or_else(|e| panic!("fill/{case} should succeed: {e:?}")); let want = Flow::from_yaml(&fs::read_to_string(expected_yaml).unwrap()).unwrap(); - assert_eq!(filled.to_yaml(), want.to_yaml(), "fill/{case}"); + let text = filled.to_yaml(); + assert_eq!(text, want.to_yaml(), "fill/{case}"); + // The result is a v3 document that validates on its own and + // reads back as itself. + assert_eq!(filled.schema_version, 3, "fill/{case}"); + wavekat_flow::validate::validate_outbound(&filled) + .unwrap_or_else(|e| panic!("fill/{case} result should validate: {e:?}")); + assert_eq!( + Flow::from_yaml(&text).unwrap().to_yaml(), + text, + "fill/{case}" + ); } else { #[derive(serde::Deserialize)] struct Refusal { diff --git a/packages/flow-schema/src/generated/flow.v4.schema.json b/packages/flow-schema/src/generated/flow.v4.schema.json index 95b693a..893386e 100644 --- a/packages/flow-schema/src/generated/flow.v4.schema.json +++ b/packages/flow-schema/src/generated/flow.v4.schema.json @@ -30,7 +30,7 @@ "type": "string" }, "variables": { - "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", "type": "object", "additionalProperties": { "$ref": "#/$defs/Variable" } }, @@ -183,7 +183,7 @@ "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, "prompt": { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", "type": "object", "additionalProperties": { "type": "string" } }, diff --git a/packages/flow-schema/src/generated/model.ts b/packages/flow-schema/src/generated/model.ts index 40edacc..98a8db3 100644 --- a/packages/flow-schema/src/generated/model.ts +++ b/packages/flow-schema/src/generated/model.ts @@ -40,7 +40,7 @@ export interface Flow { */ note?: string; /** - * Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written. + * Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written. */ variables?: { [k: string]: Variable; @@ -180,7 +180,7 @@ export interface MenuNode { note?: string; prompt: Prompt; /** - * Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. + * Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call. */ options: { [k: string]: string; diff --git a/packages/flow-schema/src/generated/schema.ts b/packages/flow-schema/src/generated/schema.ts index 5afd508..0aa6e11 100644 --- a/packages/flow-schema/src/generated/schema.ts +++ b/packages/flow-schema/src/generated/schema.ts @@ -1465,7 +1465,7 @@ export const flowV4Schema = { "type": "string" }, "variables": { - "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", "type": "object", "additionalProperties": { "$ref": "#/$defs/Variable" @@ -1750,7 +1750,7 @@ export const flowV4Schema = { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", "type": "object", "additionalProperties": { "type": "string" diff --git a/packages/flow-schema/src/model.ts b/packages/flow-schema/src/model.ts index 61d955c..45c31b1 100644 --- a/packages/flow-schema/src/model.ts +++ b/packages/flow-schema/src/model.ts @@ -79,6 +79,9 @@ export const VARIABLES_MIN_SCHEMA_VERSION = 4; * carries the same cap. Twin: `validate.rs` `MAX_VARIABLE_LEN`. */ export const MAX_VARIABLE_LEN = 500; +/** A variable's `max_len` when it gives none; the schema's default. */ +export const DEFAULT_VARIABLE_MAX_LEN = 200; + /** Longest a spoken (text) prompt may be — see `validate.ts`. Twin: * `validate.rs` `MAX_PROMPT_CHARS`. */ export const MAX_PROMPT_CHARS = 2000; diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 4e9c0f2..67a421a 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -14,6 +14,7 @@ import type { BookNode, ComponentKind, Flow, Node, Prompt, TransferNode } from './model.js'; import { + DEFAULT_VARIABLE_MAX_LEN, KIND_MIN_SCHEMA_VERSION, MAX_PROMPT_CHARS, MAX_VARIABLE_LEN, @@ -375,9 +376,10 @@ function checkBookBounds( } } -/** Declared variable names and `max_len`s, and placeholder-looking text in - * the flow's own string fields. Only on a v4 document: before that `{{` is - * ordinary text and `variables` is refused as a whole. Twin: `check_variables`. */ +/** Declared variable names, `max_len`s and defaults, and placeholder-looking + * text in the flow's own `id` and `name` (its `note` is a comment and never + * scanned). Only on a v4 document: before that `{{` is ordinary text and + * `variables` is refused as a whole. Twin: `check_variables`. */ function checkVariables(flow: Flow, issues: Issue[]): void { if (flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) return; for (const name of Object.keys(flow.variables ?? {}).sort()) { @@ -401,6 +403,17 @@ function checkVariables(flow: Flow, issues: Issue[]): void { params: { name, value: maxLen }, }); } + // A default is held to the same limit as a caller's value. + const max = maxLen ?? DEFAULT_VARIABLE_MAX_LEN; + const len = [...(flow.variables?.[name]?.default ?? '')].length; + if (len > max) { + issues.push({ + severity: 'error', + code: 'variable_default_too_long', + message: `variable "${name}" default is ${len} characters; its max_len is ${max}`, + params: { name, max, len }, + }); + } } const fields = (['id', 'name'] as const).filter((k) => flow[k].includes('{{')).sort(); if (fields.length > 0) { @@ -466,10 +479,12 @@ function checkPlaceholders( } } - // Everything else: any string value holding `{{` is out of place. + // Everything else: any string value holding `{{` is out of place. A + // `note` is a comment for people, never read by the engine, so it is + // never scanned (nor is the flow's own note, see `checkVariables`). const bad: string[] = []; for (const [key, value] of Object.entries(node)) { - if (key !== 'exits' && key !== 'kind') collectStrayBraces(key, value, bad); + if (key !== 'exits' && key !== 'kind' && key !== 'note') collectStrayBraces(key, value, bad); } bad.sort(); if (bad.length > 0) { diff --git a/packages/flow-schema/src/vars.ts b/packages/flow-schema/src/vars.ts index f6f8511..685d670 100644 --- a/packages/flow-schema/src/vars.ts +++ b/packages/flow-schema/src/vars.ts @@ -4,9 +4,16 @@ // A template is text with `{{name}}` placeholders and `{{#name}}…{{/name}}` // conditional blocks (kept only when the variable's value is non-empty). // Blocks do not nest and have no else. Names are `[a-z][a-z0-9_]{0,31}`. +// +// `fill` gives each name an effective value: the caller's, cleaned, or the +// variable's default when the caller gives none or a blank one. So a blank +// value falls back to the default; it cannot clear a default. Only a menu +// option whose label is exactly a bare `{{name}}` is dropped when its +// effective value is empty; any other text that holds an empty placeholder is +// kept, with the placeholder filled as nothing. import type { Flow } from './model.js'; -import { nodePromptSlots } from './model.js'; +import { DEFAULT_VARIABLE_MAX_LEN, MAX_PROMPT_CHARS, nodePromptSlots } from './model.js'; /** One piece of a parsed template. A block's body holds only text and vars. */ export type Segment = @@ -109,13 +116,12 @@ export function templateNames(s: string): string[] { /** Why `fill` refused a value. */ export type FillError = { - code: 'variable_unknown' | 'variable_too_long' | 'menu_without_options'; - /** The variable, or for `menu_without_options` the menu node id. */ + code: 'variable_unknown' | 'variable_too_long' | 'menu_without_options' | 'prompt_too_long'; + /** The variable, or for `menu_without_options` and `prompt_too_long` the + * node id. */ name: string; }; -const DEFAULT_MAX_LEN = 200; - /** A caller's value with control characters stripped, then trimmed of Unicode * White_Space plus U+FEFF (JS `\s` covers FEFF but not U+0085). Twin: `clean` * in `vars.rs`. */ @@ -135,22 +141,27 @@ function render(segments: Segment[], effective: (name: string) => string): strin /** * Turn a flow with variables plus a caller's values into a plain flow the - * engine can run: every placeholder replaced, `variables` gone, - * `schema_version` unchanged. The input is not modified. Twin: `vars.rs` `fill`. + * engine can run: every placeholder replaced, `variables` and every audio + * prompt's `template` gone, and a declared `schema_version` of 4 or more set + * to 3. The input is not modified. Twin: `vars.rs` `fill`. * * A name's effective value is the caller's (trimmed, control characters - * stripped) when that is non-empty, else the variable's default. Values are - * inserted as text and never parsed again. A menu option whose label is - * exactly `{{name}}` with an empty value is removed, with its exit. An audio - * prompt with a `template` stays audio (dropping the template) unless a - * variable it names got a non-default value; then it becomes the filled text. - * A flow without variables comes back as a clone. A malformed template is - * left as written (validation rejects those before fill is reached). + * stripped) when that is non-empty, else the variable's default; so a blank + * value falls back to the default and cannot clear it. Values are inserted as + * text and never parsed again. A menu option whose label is exactly a bare + * `{{name}}` with an empty effective value is removed, with its exit; any + * other label is filled and kept. An audio prompt with a `template` stays + * audio (dropping the template) unless a variable it names got a non-default + * value; then it becomes the filled text. A v1-v3 flow without variables + * comes back as a clone. A malformed template is left as written (validation + * rejects those before fill is reached). * - * Contract: validate the SOURCE flow first (`validateOutbound`); the result is - * not meant to be re-validated (a value may itself hold `{{`). `fill` keeps - * options and exits consistent, and refuses with `menu_without_options` when - * every option of a menu would be dropped. + * Contract: validate the SOURCE flow first (`validateOutbound`). The result is + * a v3 document that validates on its own: a value holding `{{` is plain text + * in v3, and `fill` keeps options and exits consistent. Errors: + * `variable_unknown`, `variable_too_long`, `menu_without_options` when every + * option of a menu would be dropped, and `prompt_too_long` when a filled + * prompt is longer than validation allows. */ export function fill( flow: Flow, @@ -158,7 +169,13 @@ export function fill( ): { flow: Flow } | { errors: FillError[] } { const declared = flow.variables ?? {}; const out = structuredClone(flow); - if (Object.keys(declared).length === 0 && Object.keys(values).length === 0) return { flow: out }; + if ( + Object.keys(declared).length === 0 && + Object.keys(values).length === 0 && + flow.schema_version < 4 + ) { + return { flow: out }; + } const errors: FillError[] = []; const given = new Map(); @@ -169,7 +186,7 @@ export function fill( continue; } const value = clean(values[name] ?? ''); - if ([...value].length > (variable.max_len ?? DEFAULT_MAX_LEN)) { + if ([...value].length > (variable.max_len ?? DEFAULT_VARIABLE_MAX_LEN)) { errors.push({ code: 'variable_too_long', name }); } else if (value !== '') { given.set(name, value); @@ -186,7 +203,10 @@ export function fill( }; delete out.variables; + // Variables and templates are gone, so what is left is a v3 document. + if (out.schema_version >= 4) out.schema_version = 3; for (const [id, node] of Object.entries(out.nodes)) { + let tooLong = false; for (const [field, prompt] of nodePromptSlots(node)) { let next: typeof prompt = prompt; if (typeof prompt === 'string') { @@ -198,8 +218,10 @@ export function fill( ); next = overridden ? fillText(template) : clip; } + if (typeof next === 'string' && [...next].length > MAX_PROMPT_CHARS) tooLong = true; (node as unknown as Record)[field] = next; } + if (tooLong) errors.push({ code: 'prompt_too_long', name: id }); if (node.kind === 'menu') { const dropped: string[] = []; for (const [key, label] of Object.entries(node.options)) { diff --git a/packages/flow-schema/test/conformance.test.ts b/packages/flow-schema/test/conformance.test.ts index a8d4184..df97dc0 100644 --- a/packages/flow-schema/test/conformance.test.ts +++ b/packages/flow-schema/test/conformance.test.ts @@ -225,11 +225,19 @@ describe('conformance corpus — fill', () => { const read = (ext: string) => readFileSync(resolve(FILL_DIR, `${name}.${ext}`), 'utf8'); const flow = decode(read('input.yaml'), name); const values = JSON.parse(read('values.json')) as Record; + // Every source is a flow that passes the gate fill expects in front of it. + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); const result = fill(flow, values); if (existsSync(resolve(FILL_DIR, `${name}.expected.yaml`))) { if (!('flow' in result)) throw new Error(JSON.stringify(result.errors)); const want = decode(read('expected.yaml'), name); - expect(serializeFlow(result.flow)).toBe(serializeFlow(want)); + const text = serializeFlow(result.flow); + expect(text).toBe(serializeFlow(want)); + // The result is a v3 document that validates on its own and + // reads back as itself. + expect(result.flow.schema_version).toBe(3); + expect(validateOutbound(result.flow).filter((i) => i.severity === 'error')).toEqual([]); + expect(serializeFlow(decode(text, name))).toBe(text); } else { const want = JSON.parse(read('expected.json')) as { errors: string[] }; if (!('errors' in result)) throw new Error('expected fill to be refused'); diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts index fe413c9..c644e6c 100644 --- a/packages/flow-schema/test/vars.test.ts +++ b/packages/flow-schema/test/vars.test.ts @@ -131,6 +131,24 @@ describe('placeholders in a flow', () => { ); }); + it('refuses a default longer than its max_len, counted in characters', () => { + const body = HANGUP('"{{q}}"'); + expect(errorCodes(flow(4, 'variables:\n q: { default: "问问问", max_len: 2 }\n', body))).toEqual( + ['variable_default_too_long'], + ); + expect(errorCodes(flow(4, 'variables:\n q: { default: "问问", max_len: 2 }\n', body))).toEqual( + [], + ); + }); + + it('never scans a note, on the flow or on a step', () => { + const src = + 'schema_version: 4\nid: f\nname: F\nnote: "{{ghost}} {{#x"\nentry: a\n' + + Q + + 'nodes:\n a:\n kind: hangup\n note: "{{ghost}} {{#x"\n prompt: "{{q}}"\n'; + expect(errorCodes(src)).toEqual([]); + }); + it('refuses placeholders in a transfer target and a transcript', () => { expect(errorCodes(flow(4, Q, ' a:\n kind: transfer\n target: "{{q}}"\n'))).toEqual([ 'placeholder_not_allowed', @@ -212,7 +230,7 @@ describe('fill', () => { expect(menu.exits).not.toHaveProperty('3'); expect(menu.exits).not.toHaveProperty('4'); expect(flow.variables).toBeUndefined(); - expect(flow.schema_version).toBe(4); + expect(flow.schema_version).toBe(3); }); it('keeps_option3_when_given', () => { @@ -285,6 +303,43 @@ describe('fill', () => { expect(menu.prompt as string).toContain('{{option1}} {x}'); }); + it('filled flow with braces in a value validates as v3', () => { + const flow = filled(ask(), { question: 'Is {{x}} {{#y}} ok?' }); + expect(flow.schema_version).toBe(3); + expect(askMenu(flow).prompt as string).toContain('Is {{x}} {{#y}} ok?'); + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); + // And it reads back as itself: in v3 the braces are plain text. + const text = serializeFlow(flow); + const back = load(text); + expect(serializeFlow(back)).toBe(text); + expect(validateOutbound(back).filter((i) => i.severity === 'error')).toEqual([]); + }); + + it('a v4 flow without variables still comes back as v3', () => { + const flow = load( + 'schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_a, template: Hello }\n', + ); + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); + const out = filled(flow, {}); + expect(out.schema_version).toBe(3); + expect(out.nodes.a).toMatchObject({ prompt: { audio: 'vprompt_a' } }); + expect(out.nodes.a).not.toHaveProperty('prompt.template'); + expect(validateOutbound(out).filter((i) => i.severity === 'error')).toEqual([]); + }); + + it('a filled prompt over the limit is an error', () => { + const src = (prompt: string) => + load( + `schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n d: { default: "", max_len: 500 }\nnodes:\n a:\n kind: hangup\n prompt: "${prompt}"\n`, + ); + // 4 x 500 = 2000: exactly the limit is fine; counted in characters. + const value = { d: '😀'.repeat(500) }; + expect('flow' in fill(src('{{d}}{{d}}{{d}}{{d}}'), value)).toBe(true); + expect(fill(src('{{d}}{{d}}{{d}}{{d}}!'), value)).toEqual({ + errors: [{ code: 'prompt_too_long', name: 'a' }], + }); + }); + it('dropping_every_option_is_an_error', () => { const flow = load( [ diff --git a/schema/README.md b/schema/README.md index 6e477a3..5f8f001 100644 --- a/schema/README.md +++ b/schema/README.md @@ -10,7 +10,7 @@ version it declares, and no other. | `flow.v1.schema.json` | `schema_version: 1` | the original seven components | | `flow.v2.schema.json` | `schema_version: 2` | `book` — appointment booking over the phone | | `flow.v3.schema.json` | `schema_version: 3` | `transfer` gains `whisper` and `timeout_secs` — a screened transfer | -| `flow.v4.schema.json` | `schema_version: 4` | top-level `variables` (each with a required `default`) — details a caller fills in per call; an audio prompt may keep its `template` | +| `flow.v4.schema.json` | `schema_version: 4` | top-level `variables` (each with a required `default`) — details a caller fills in per call, used through `{{name}}` placeholders; an audio prompt may keep the `template` it was voiced from | Version 2 is version 1 plus one component: every v1 document is a valid v2 document once its `schema_version` is bumped, and nothing else changed. @@ -18,10 +18,15 @@ Version 3 is version 2 plus two optional fields on `transfer`: every v2 document is a valid v3 document once its `schema_version` is bumped. The bump is for what the fields do, not for their shape. A reader that ignored `whisper` would hand the call over without calling the target first. -Version 4 is version 3 plus one optional top-level field, `variables`: every -v3 document is a valid v4 document once its `schema_version` is bumped. The -bump is again for what the field does: a reader that ignored it would speak -the `{{name}}` placeholders as written. +Version 4 is version 3 plus an optional top-level field, `variables`, and an +optional `template` on an audio prompt. Unlike the earlier bumps, `{{` now +means something: in a v4 document every `{{name}}` in a prompt, a `template` +or a menu label must be a well-formed placeholder naming a declared variable, +and `{{` anywhere else (apart from a `note`) is refused. So a v3 document is a +valid v4 document once bumped only if it holds no `{{`. The bump is again for +what the fields do: a reader that ignored `variables` would speak the +placeholders as written. Filling a v4 document with a call's values +(`fill`) gives back a v3 document, which every v3 reader runs. Everything downstream is generated or checked against these files: @@ -50,8 +55,10 @@ The schema owns **structure only**: - the field set and types of `Flow` and every node kind, - the `kind` discriminated union (`greeting`, `hours`, `menu`, `ring`, `message`, `transfer`, `hangup`, and `book` from v2), -- enums (`MessageTone`), the `Prompt` = `string | { audio, transcript? }` shape - (`transcript` is the optional text an audio clip was synthesized from), +- enums (`MessageTone`), the `Prompt` = `string | { audio, transcript?, template? }` + shape (`transcript` is the optional text an audio clip was synthesized from; + `template`, from v4, the text with placeholders it was voiced from), +- the `variables` map and each variable's `default` and `max_len` (v4), - required vs. optional fields and their defaults, - `schema_version` pinned to that file's version (a document declaring another version does not validate against it — it validates against that version's @@ -71,6 +78,7 @@ validator and are pinned by the shared `conformance/` corpus: | `book` numeric bounds, and whether its schedule leaves room for one appointment | arithmetic over the node's own schedule | | Which components a `schema_version` may carry | a rule *about* versions, not expressible inside one | | Safe-subset YAML (reject anchors, aliases, tags, duplicate keys) | concrete-syntax concern; anchors don't survive parsing | +| Placeholders (v4): well formed, naming a declared variable, only in a prompt, a `template` or a menu label; a default within its `max_len` | a parse of free text, checked against the flow's own `variables` | ## Unknown fields diff --git a/schema/flow.v4.schema.json b/schema/flow.v4.schema.json index 95b693a..893386e 100644 --- a/schema/flow.v4.schema.json +++ b/schema/flow.v4.schema.json @@ -30,7 +30,7 @@ "type": "string" }, "variables": { - "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). Prompts and menu labels refer to them with `{{name}}` placeholders (read and checked from a later step; to this version of the schema they are plain text). Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", "type": "object", "additionalProperties": { "$ref": "#/$defs/Variable" } }, @@ -183,7 +183,7 @@ "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, "prompt": { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", "type": "object", "additionalProperties": { "type": "string" } }, From cc2b1d000a7e3e48ab2f99524ede84305beec68a Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sun, 1 Nov 2026 23:23:17 +1300 Subject: [PATCH 13/13] fix: prune nodes left unreachable by fill After dropping options, fill removes every node no longer reachable from entry (both languages), so the filled v3 document validates on its own. Adds fill/dropped-option-only-path and fixes a typo in a v4 case description. --- .../dropped-option-only-path.expected.yaml | 13 +++++++ .../fill/dropped-option-only-path.input.yaml | 18 ++++++++++ .../fill/dropped-option-only-path.values.json | 1 + .../rendered-template-prompt.expected.json | 2 +- .../wavekat-flow/schema/flow.v4.schema.json | 2 +- crates/wavekat-flow/src/validate.rs | 2 +- crates/wavekat-flow/src/vars.rs | 34 ++++++++++++++++--- .../src/generated/flow.v4.schema.json | 2 +- packages/flow-schema/src/generated/model.ts | 2 +- packages/flow-schema/src/generated/schema.ts | 2 +- packages/flow-schema/src/validate.ts | 2 +- packages/flow-schema/src/vars.ts | 14 ++++++-- packages/flow-schema/test/vars.test.ts | 34 +++++++++++++++++++ schema/flow.v4.schema.json | 2 +- 14 files changed, 115 insertions(+), 15 deletions(-) create mode 100644 conformance/fill/dropped-option-only-path.expected.yaml create mode 100644 conformance/fill/dropped-option-only-path.input.yaml create mode 100644 conformance/fill/dropped-option-only-path.values.json diff --git a/conformance/fill/dropped-option-only-path.expected.yaml b/conformance/fill/dropped-option-only-path.expected.yaml new file mode 100644 index 0000000..29773dd --- /dev/null +++ b/conformance/fill/dropped-option-only-path.expected.yaml @@ -0,0 +1,13 @@ +schema_version: 3 +id: flow_dropped_path +name: An option with its own ending +entry: ask +nodes: + ask: + kind: menu + prompt: "Press 1 for yes. Press 2 for no." + options: { "1": "Yes", "2": "No" } + exits: { "1": thanks, "2": thanks, no_input: thanks, invalid: thanks } + thanks: + kind: hangup + prompt: Thanks. Goodbye. diff --git a/conformance/fill/dropped-option-only-path.input.yaml b/conformance/fill/dropped-option-only-path.input.yaml new file mode 100644 index 0000000..c9701c6 --- /dev/null +++ b/conformance/fill/dropped-option-only-path.input.yaml @@ -0,0 +1,18 @@ +schema_version: 4 +id: flow_dropped_path +name: An option with its own ending +entry: ask +variables: + option3: { description: Answer for key 3, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "Press 1 for yes. Press 2 for no.{{#option3}} Press 3 for {{option3}}.{{/option3}}" + options: { "1": "Yes", "2": "No", "3": "{{option3}}" } + exits: { "1": thanks, "2": thanks, "3": only3, no_input: thanks, invalid: thanks } + only3: + kind: hangup + prompt: You picked the third answer. Goodbye. + thanks: + kind: hangup + prompt: Thanks. Goodbye. diff --git a/conformance/fill/dropped-option-only-path.values.json b/conformance/fill/dropped-option-only-path.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/dropped-option-only-path.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/v4/valid/rendered-template-prompt.expected.json b/conformance/v4/valid/rendered-template-prompt.expected.json index af6bf6a..ee96e34 100644 --- a/conformance/v4/valid/rendered-template-prompt.expected.json +++ b/conformance/v4/valid/rendered-template-prompt.expected.json @@ -1,5 +1,5 @@ { - "description": "An audio prompt may keep the `template` it was voiced from, so a call that overrides a variable can speak the filled text instead of the clip. The clip is a required asset as ever; Its placeholders are checked like a text prompt's, so `{{name}}` must be declared. A reader that does not fill ignores `template` and plays the clip.", + "description": "An audio prompt may keep the `template` it was voiced from, so a call that overrides a variable can speak the filled text instead of the clip. The clip is a required asset as ever; its placeholders are checked like a text prompt's, so `{{name}}` must be declared. A reader that does not fill ignores `template` and plays the clip.", "structurallyValid": true, "semantic": { "ok": true, "errors": [] }, "requiredAssets": ["vprompt_abc123"] diff --git a/crates/wavekat-flow/schema/flow.v4.schema.json b/crates/wavekat-flow/schema/flow.v4.schema.json index 893386e..eef6d91 100644 --- a/crates/wavekat-flow/schema/flow.v4.schema.json +++ b/crates/wavekat-flow/schema/flow.v4.schema.json @@ -183,7 +183,7 @@ "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, "prompt": { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", "type": "object", "additionalProperties": { "type": "string" } }, diff --git a/crates/wavekat-flow/src/validate.rs b/crates/wavekat-flow/src/validate.rs index 17d67c1..38d7598 100644 --- a/crates/wavekat-flow/src/validate.rs +++ b/crates/wavekat-flow/src/validate.rs @@ -712,7 +712,7 @@ fn unbounded_loop_nodes(flow: &Flow) -> Vec<&str> { /// Node ids reachable from `entry` over exit edges (`entry` included when /// it exists). -fn reachable_from_entry(flow: &Flow) -> BTreeSet<&str> { +pub(crate) fn reachable_from_entry(flow: &Flow) -> BTreeSet<&str> { let mut reachable: BTreeSet<&str> = BTreeSet::new(); let Some((entry, _)) = flow.nodes.get_key_value(&flow.entry) else { return reachable; diff --git a/crates/wavekat-flow/src/vars.rs b/crates/wavekat-flow/src/vars.rs index c6d5328..62a4935 100644 --- a/crates/wavekat-flow/src/vars.rs +++ b/crates/wavekat-flow/src/vars.rs @@ -210,7 +210,8 @@ fn render(segments: &[Segment<'_>], effective: &dyn Fn(&str) -> String, out: &mu /// value falls back to the default and cannot clear it. Values are inserted /// as text and never parsed again. A menu option whose label is exactly a /// bare `{{name}}` with an empty effective value is removed, with its exit; -/// any other label is filled and kept. An audio prompt with a `template` +/// any other label is filled and kept; a node left unreachable from `entry` +/// once those exits are gone is removed too. An audio prompt with a `template` /// stays audio (dropping the template) unless a variable it names got a /// non-default value; then it becomes the filled text. A v1-v3 flow without /// variables comes back as a clone. A malformed template is left as written @@ -326,11 +327,18 @@ pub fn fill(flow: &Flow, values: &BTreeMap) -> Result = crate::validate::reachable_from_entry(&out) + .into_iter() + .map(str::to_string) + .collect(); + out.nodes.retain(|id, _| reachable.contains(id.as_str())); + Ok(out) } #[cfg(test)] @@ -657,6 +665,22 @@ mod tests { assert_eq!(errs[0].code(), "prompt_too_long"); } + #[test] + fn nodes_only_a_dropped_option_reached_are_pruned() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: m\nvariables:\n c: { default: \"\" }\nnodes:\n m:\n kind: menu\n prompt: Pick\n options: { \"1\": One, \"3\": \"{{c}}\" }\n exits: { \"1\": end, \"3\": only3, no_input: end, invalid: end }\n only3:\n kind: greeting\n prompt: Three\n exits: { next: deeper }\n deeper:\n kind: hangup\n end:\n kind: hangup\n", + ) + .unwrap(); + crate::validate::validate_outbound(&flow).unwrap(); + let filled = fill(&flow, &BTreeMap::new()).unwrap(); + let ids: Vec<&str> = filled.nodes.keys().map(String::as_str).collect(); + assert_eq!(ids, vec!["m", "end"]); + crate::validate::validate_outbound(&filled).unwrap(); + // Given a value, key 3 and everything behind it stay. + let kept = fill(&flow, &vals(&[("c", "Three")])).unwrap(); + assert_eq!(kept.nodes.len(), 4); + } + #[test] fn dropping_every_option_is_an_error() { let flow = Flow::from_yaml( diff --git a/packages/flow-schema/src/generated/flow.v4.schema.json b/packages/flow-schema/src/generated/flow.v4.schema.json index 893386e..eef6d91 100644 --- a/packages/flow-schema/src/generated/flow.v4.schema.json +++ b/packages/flow-schema/src/generated/flow.v4.schema.json @@ -183,7 +183,7 @@ "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, "prompt": { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", "type": "object", "additionalProperties": { "type": "string" } }, diff --git a/packages/flow-schema/src/generated/model.ts b/packages/flow-schema/src/generated/model.ts index 98a8db3..4746d00 100644 --- a/packages/flow-schema/src/generated/model.ts +++ b/packages/flow-schema/src/generated/model.ts @@ -180,7 +180,7 @@ export interface MenuNode { note?: string; prompt: Prompt; /** - * Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call. + * Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call. */ options: { [k: string]: string; diff --git a/packages/flow-schema/src/generated/schema.ts b/packages/flow-schema/src/generated/schema.ts index 0aa6e11..5758af6 100644 --- a/packages/flow-schema/src/generated/schema.ts +++ b/packages/flow-schema/src/generated/schema.ts @@ -1750,7 +1750,7 @@ export const flowV4Schema = { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", "type": "object", "additionalProperties": { "type": "string" diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 67a421a..c834b55 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -596,7 +596,7 @@ function checkGraph( /** Node ids reachable from `entry` over exit edges (`entry` included when * it exists). */ -function reachableFromEntry(flow: Flow): Set { +export function reachableFromEntry(flow: Flow): Set { const reachable = new Set(); if (!(flow.entry in flow.nodes)) return reachable; reachable.add(flow.entry); diff --git a/packages/flow-schema/src/vars.ts b/packages/flow-schema/src/vars.ts index 685d670..1e93453 100644 --- a/packages/flow-schema/src/vars.ts +++ b/packages/flow-schema/src/vars.ts @@ -14,6 +14,7 @@ import type { Flow } from './model.js'; import { DEFAULT_VARIABLE_MAX_LEN, MAX_PROMPT_CHARS, nodePromptSlots } from './model.js'; +import { reachableFromEntry } from './validate.js'; /** One piece of a parsed template. A block's body holds only text and vars. */ export type Segment = @@ -150,7 +151,8 @@ function render(segments: Segment[], effective: (name: string) => string): strin * value falls back to the default and cannot clear it. Values are inserted as * text and never parsed again. A menu option whose label is exactly a bare * `{{name}}` with an empty effective value is removed, with its exit; any - * other label is filled and kept. An audio prompt with a `template` stays + * other label is filled and kept; a node left unreachable from `entry` once + * those exits are gone is removed too. An audio prompt with a `template` stays * audio (dropping the template) unless a variable it names got a non-default * value; then it becomes the filled text. A v1-v3 flow without variables * comes back as a clone. A malformed template is left as written (validation @@ -242,5 +244,13 @@ export function fill( } } } - return errors.length > 0 ? { errors } : { flow: out }; + if (errors.length > 0) return { errors }; + // A dropped option can leave the nodes only it led to unreachable; a caller + // could never get there, so they go too and the result still validates on + // its own. + const reachable = reachableFromEntry(out); + for (const id of Object.keys(out.nodes)) { + if (!reachable.has(id)) delete out.nodes[id]; + } + return { flow: out }; } diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts index c644e6c..2478530 100644 --- a/packages/flow-schema/test/vars.test.ts +++ b/packages/flow-schema/test/vars.test.ts @@ -340,6 +340,40 @@ describe('fill', () => { }); }); + it('prunes nodes only a dropped option reached', () => { + const flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: m', + 'variables:', + ' c: { default: "" }', + 'nodes:', + ' m:', + ' kind: menu', + ' prompt: Pick', + ' options: { "1": One, "3": "{{c}}" }', + ' exits: { "1": end, "3": only3, no_input: end, invalid: end }', + ' only3:', + ' kind: greeting', + ' prompt: Three', + ' exits: { next: deeper }', + ' deeper:', + ' kind: hangup', + ' end:', + ' kind: hangup', + '', + ].join('\n'), + ); + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); + const out = filled(flow, {}); + expect(Object.keys(out.nodes)).toEqual(['m', 'end']); + expect(validateOutbound(out).filter((i) => i.severity === 'error')).toEqual([]); + // Given a value, key 3 and everything behind it stay. + expect(Object.keys(filled(flow, { c: 'Three' }).nodes)).toHaveLength(4); + }); + it('dropping_every_option_is_an_error', () => { const flow = load( [ diff --git a/schema/flow.v4.schema.json b/schema/flow.v4.schema.json index 893386e..eef6d91 100644 --- a/schema/flow.v4.schema.json +++ b/schema/flow.v4.schema.json @@ -183,7 +183,7 @@ "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, "prompt": { "$ref": "#/$defs/Prompt" }, "options": { - "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, and its exit, from the call.", + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", "type": "object", "additionalProperties": { "type": "string" } },