easy_flow 0.4.9 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 310df5972d6ca11a6862e8c101b79f8802adbe620ee90e3c8764cda70feb9492
-  data.tar.gz: c43a02f417356eb7bf31e2e53fa220a4d32b7fefed055ed031dda114eccec951
+  metadata.gz: af61822fb110201f602335911c189fbaf51fc2c2311a86385a307a75d3584069
+  data.tar.gz: 600c9251559a47e18b30122980b62a30c6e6f48e0251b2c480501853d8b1ab49
 SHA512:
-  metadata.gz: 82e5b5eede06952c31b553577668d70499b828e576f5acc2e96964a30f8c897c6762d8e450674d5774d2c54034c0309019cf68138ddc45d9de48b165659bfe29
-  data.tar.gz: 0ad147aae3a60c96b225122d43d7f73e570c275b101b7c74db0bf00389ac01e927026ae5428925c3f9f8887d88a14f1266d82cd5299972b4f53dba7b75e32f9c
+  metadata.gz: 52ec7fba925746a9fbd6b6d1c7c04ea5dba2fbd20318fb9e6f8d61f48b8895aca02738304b54ec1df87f10e59011ad22d7718b37faf73dcc73bbc2390ba31e8e
+  data.tar.gz: '09bc633fa9648da7631bfc60eaa45a7c678cc0ce2726f35003d7f185683885f48596c0cf4f0796d8fcc84ed3af800fce3ce956f8b3464846757ef653cfcf4866'

data/app/controllers/easy_flow/flows_controller.rb

@@ -105,13 +105,15 @@ module EasyFlow
     end
 
     def submitted_answers
-      answers = params.fetch(:answers, {}).permit(*@guide.steps.map(&:id)).to_h.symbolize_keys
-      asked = @guide.step(params[:asked].to_s)
+      given = params.fetch(:answers, {})
+      answers = given.permit(*given.keys.select { |key| @guide.step(key) }).to_h.symbolize_keys
+      key = params[:asked].to_s.to_sym
+      asked = @guide.step(key)
       return answers unless asked
 
-      answer = answers.fetch(asked.id.to_sym, "")
+      answer = answers.fetch(key, "")
       @refused = answer_problem(asked, answer)
-      @refused ? answers.except(asked.id.to_sym) : answers.merge(asked.id.to_sym => answer)
+      @refused ? answers.except(key) : answers.merge(key => answer)
     end
 
     def record_submitted
@@ -139,7 +141,8 @@ module EasyFlow
     end
 
     def asked
-      runner_for(run.pinned_definition).steps.map(&:id)
+      guide = runner_for(run.pinned_definition)
+      guide.steps.map(&:id) | [ guide.next_step(run.recorded)&.id ].compact
     end
   end
 end

data/app/models/easy_flow/digest.rb

@@ -10,7 +10,7 @@ module EasyFlow
     end
 
     def step(id)
-      @document.node(id)
+      @document.node(id.to_s.split("@").first)
     end
 
     def steps
@@ -75,22 +75,37 @@ module EasyFlow
 
     def walk(state)
       recorded = []
-      visited = []
+      latest = {}
+      visits = Hash.new(0)
+      answers_at_visit = {}
+      answered = 0
       cursor = entry
 
-      while cursor && !visited.include?(cursor.id)
-        return [ recorded, cursor ] if pending?(cursor, state)
+      while cursor
+        return [ recorded, nil ] if visits[cursor.id].positive? && answers_at_visit[cursor.id] == answered
 
-        recorded << cursor.id if state.key?(cursor.id)
-        visited << cursor.id
-        cursor = successor(cursor, state)
+        visits[cursor.id] += 1
+        answers_at_visit[cursor.id] = answered
+        key = visit_key(cursor.id, visits[cursor.id])
+        return [ recorded, cursor.with(id: key) ] if pending?(cursor, key, state)
+
+        if state.key?(key)
+          recorded << key
+          latest[cursor.id] = state[key]
+          answered += 1 if step_type(cursor)&.awaits_input?
+        end
+        cursor = successor(cursor, state.merge(latest))
       end
 
       [ recorded, nil ]
     end
 
-    def pending?(node, state)
-      return false if state.key?(node.id)
+    def visit_key(id, visit)
+      visit == 1 ? id : "#{id}@#{visit}"
+    end
+
+    def pending?(node, key, state)
+      return false if state.key?(key)
 
       step_type(node)&.awaits_input? || acts?(node) || step_type(node)&.waits? || false
     end

data/app/models/easy_flow/runner.rb

@@ -28,7 +28,7 @@ module EasyFlow
 
     def run(progress)
       while (node = @digest.next_step(named(progress.recorded))) && goes_on?(node, named(progress.recorded))
-        progress.record(node.id, result_of(node, named(progress.recorded)))
+        progress.record(node.id, result_of(@digest.step(node.id), named(progress.recorded)))
       end
     end
 

data/app/models/easy_flow/validator.rb

@@ -17,7 +17,7 @@ module EasyFlow
     end
 
     def malformations
-      missing_edge_targets + missing_edge_sources + duplicate_ids + no_beginning
+      missing_edge_targets + missing_edge_sources + duplicate_ids + reserved_ids + no_beginning
     end
 
     private
@@ -41,6 +41,11 @@ module EasyFlow
         .map { |id, _count| Violation.new(node: id, problem: :duplicate_id) }
     end
 
+    def reserved_ids
+      @document.nodes.map(&:id).select { |id| id.to_s.include?("@") }
+        .map { |id| Violation.new(node: id, problem: :reserved_id) }
+    end
+
     def no_beginning
       return [] if known?(@document.entry)
 

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.4.9"
+  VERSION = "0.5.0"
 end

data/the_local/agents/easy_flow-develop.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-develop
-description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, computes a value from earlier answers, picks the next branch, or holds the visitor until something outside the flow has happened), moving a paused run on once what it waits for has happened, refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, serving a host's flows from the app's own controller and routes, acting when a visitor finishes a flow, and reading a run's recorded answers and question labels — MUST BE USED instead of hand-rolling questionnaire steps, branching logic, number comparisons, hard-coded setting options, answer validation, polling or "come back later" pages, flow controllers or answer lookups.
+description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, computes a value from earlier answers, picks the next branch, or holds the visitor until something outside the flow has happened), moving a paused run on once what it waits for has happened, refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, serving a host's flows from the app's own controller and routes, acting when a visitor finishes a flow, and reading a run's recorded answers and question labels, including every visit's answer when a flow loops back to a question already asked — MUST BE USED instead of hand-rolling questionnaire steps, branching logic, number comparisons, hard-coded setting options, answer validation, polling or "come back later" pages, flow controllers or answer lookups.
 tools: Read, Write, Edit, Grep
 scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
 ---
@@ -9,7 +9,7 @@ This local follows the steps below exactly and invents none. Where a step names
 
 ## What easy_flow is
 
-A Rails engine for flows an admin draws on a canvas and a visitor runs one step at a time. Each step is an instance of a step type. The engine ships six: start (`:start`), end (`:terminal`), question (`:question`, a question with a list of answers, which the admin can mark required so a blank answer is refused), and three that pick a branch from an earlier answer with no code — condition (`:condition`, is or is not a chosen value), switch (`:switch`, follows the connection labelled with the answer) and compare (`:compare`, reads the answer as a number and checks it by more than, less than, at least or at most against an amount). Before writing a step type to branch on an answer or a number, ask the developer whether an admin placing one of those three on the canvas is enough. Use this local when the app needs a step type of its own, needs a host's flows on its own pages with its own behaviour when a visitor finishes, or needs to read what a visitor answered. It assumes easy_flow is already installed and a host is declared; if not, hand off to `easy_flow-install` first.
+A Rails engine for flows an admin draws on a canvas and a visitor runs one step at a time. Each step is an instance of a step type. The engine ships six: start (`:start`), end (`:terminal`), question (`:question`, a question with a list of answers, which the admin can mark required so a blank answer is refused), and three that pick a branch from an earlier answer with no code — condition (`:condition`, is or is not a chosen value), switch (`:switch`, follows the connection labelled with the answer) and compare (`:compare`, reads the answer as a number and checks it by more than, less than, at least or at most against an amount). An admin may connect a step back to an earlier one, so a flow can ask the same question more than once, and each visit's answer is kept. Before writing a step type to branch on an answer or a number, ask the developer whether an admin placing one of those three on the canvas is enough. Use this local when the app needs a step type of its own, needs a host's flows on its own pages with its own behaviour when a visitor finishes, or needs to read what a visitor answered. It assumes easy_flow is already installed and a host is declared; if not, hand off to `easy_flow-install` first.
 
 ## Interface
 
@@ -102,6 +102,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `process` returns the value recorded under this step's id. It runs as soon as a visitor reaches the step, before the next step is shown.
    - A type that declares more than one `output` returns a hash from `process`, keyed by each output's name as a string. A later compare step reads the output the admin picks from that hash.
    - `route` returns the value that picks the connection to follow; it is compared as a string with the value each leaving connection is labelled with, so `false` follows the connection labelled `false`. Returning `nil` follows the first connection. A route that returns `true` or `false` declares `output :result, type: :boolean, values: [true, false]`.
+   - In a flow that loops, the first visit to a step is recorded under its id and each later visit under `<id>@<n>`, where `n` counts from 2. `route` is given the latest visit's answer under the plain step id. `process` and `waits_until` are given the answers as recorded, so the plain id holds the first visit's answer and later visits are under `<id>@2`, `<id>@3` and on. A `process` step reached again records its result under its own `<id>@<n>`. When a computing or waiting type reads an earlier step that can be asked again, ask the developer whether it should read the first visit or the latest.
 7. For a type that awaits input, write the partial named in `drawn_by`, for example `app/views/flow_steps/_rating.html.erb`. It receives the display object as `step`. It renders only the input, since the page supplies the form, the Next button and the Back button. The input must be named `answers[<step id>]`, or the answer is not recorded:
 
    ```erb
@@ -109,6 +110,8 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    <%= number_field_tag "answers[#{step.id}]", nil, in: 1..step.scale %>
    ```
 
+   Name the input from `step.id`, never from a stored or hard-coded id. On a later visit to the step in a loop, the node's id is `<id>@<n>`, and the answer is only recorded against that visit when the input is named with it. A `displays_by` block must pass `node.id` through as the display object's `id` for the same reason.
+
    The input must submit one value. An input that submits an array or a hash, such as checkboxes named `answers[<step id>][]`, is dropped and treated as blank.
 
    An answer is recorded as the string the visitor submitted. A compare step still reads a typed answer such as `"12"` as the number it spells, and an answer that is missing or is not a number makes it follow its `false` connection.
@@ -199,10 +202,11 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    end
    ```
 
-   - `state_on_path(answers)` — only the answers on the path the visitor actually took, dropping answers left behind by going back.
-   - `question_text(id)` — the text of a question step. It returns `nil` for a step of any other type.
-   - `choice_label(id, value)` — the label of the chosen answer, or the value itself when there is no label.
-   - `steps`, `step(id)`, `next_step(answers)`, `steps_on_path(answers)`, `slug` and `headline` read the rest of the document.
+   - `state_on_path(answers)` — only the answers on the path the visitor actually took, in the order they were given, dropping answers left behind by going back. In a flow that loops, it holds every visit: the first under the step id and each later one under `:"<id>@<n>"`, such as `:"job@2"`. Ask the developer whether each visit is shown as its own line or the visits to one question are grouped together; to group them, take the part of the key before `@`.
+   - `question_text(id)` — the text of a question step, given either its id or a visit key such as `"job@2"`. It returns `nil` for a step of any other type.
+   - `choice_label(id, value)` — the label of the chosen answer, or the value itself when there is no label. It takes a visit key the same way as `question_text`.
+   - `step(id)` finds the step for either its id or a visit key.
+   - `steps`, `next_step(answers)`, `steps_on_path(answers)`, `slug` and `headline` read the rest of the document.
 
 ## Conventions
 
@@ -215,7 +219,9 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - A type that routes declares the values its output takes, or the canvas offers no connections to label.
 - Always read a run against `run.pinned_definition`, never the flow's live version, since a run keeps the version it started on after a new one is published.
 - Always look flows and runs up through a host.
-- A step's input field is named `answers[<step id>]` and submits one value. Any other name is ignored, and an array or hash is treated as blank.
+- In a flow that loops, a later visit's answer is keyed `<id>@<n>`, so code that reads answers never assumes one answer per step id. A step id may not contain `@`, and a flow with one is refused when published.
+- A loop that comes back to a step with no answer given since the last visit to it ends the flow there, so every loop needs a step that awaits input.
+- A step's input field is named `answers[<step.id>]` and submits one value. Any other name is ignored, and an array or hash is treated as blank.
 - An answer the type's `answer_check` refuses is never recorded, and the visitor is shown the same step with the check's message. An answer no check refuses is recorded, a blank one as `""`.
 - A `waits_until` block is given only the step and the answers recorded so far, so what it waits for must be findable from those.
 - A type that waits never also declares `awaits_input`.

data/the_local/agents/easy_flow-info.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-info
-description: Use to learn what easy_flow offers — guided flows an admin draws on a canvas and a visitor runs one step at a time, versioned documents of steps and connections, hosts and the step types each offers its admins, runs, the built-in step types including questions that can require an answer and branching on an answer or comparing a number, step types the host app registers, the checks they make on an answer, and steps that hold a run until something outside the flow has happened, and the settings an admin fills in, including picks whose options come from the app's data.
+description: Use to learn what easy_flow offers — guided flows an admin draws on a canvas and a visitor runs one step at a time, versioned documents of steps and connections, flows that loop back to ask a step again, hosts and the step types each offers its admins, runs, the built-in step types including questions that can require an answer and branching on an answer or comparing a number, step types the host app registers, the checks they make on an answer, and steps that hold a run until something outside the flow has happened, and the settings an admin fills in, including picks whose options come from the app's data.
 tools: Read
 scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
 ---
@@ -26,6 +26,7 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - To add a step type, give a step type its own rule for refusing an answer, hold a run until something outside the flow has happened, put a flow on the app's own pages, or act on what a visitor answered, use **easy_flow-develop**.
 - To branch a flow on an answer or on a number the visitor gave, no code is needed: an admin places one of the built-in branching steps on the canvas.
 - To make a visitor answer a question before going on, no code is needed: an admin marks that question step as required on the canvas.
+- To ask a step again, such as repeating a question until the visitor says they are done, no code is needed: an admin connects a later step back to an earlier one on the canvas.
 - If the question is only what a word below means, this page is the answer.
 
 ## Conventions
@@ -51,8 +52,12 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Host** — a named part of the app that owns a set of flows. A host sets the visitor layout and the admin layout, how admins are authenticated, how visitors are authorized, how a refusal is answered, and optionally which step types it offers. Flows are always looked up through a host, so one host never sees another's flows.
 - **Offered step types** — the list of step types a host names for its admins to add. A host that names no list offers every registered step type. The list only narrows the palette.
 - **Palette** — the step types an admin can add on a host's canvas. It never holds the start step, always holds the end step, and otherwise holds the step types the host offers. A step already in a flow whose type the host does not offer is still drawn and run.
-- **Run** — one visitor's pass through a flow. A run is pinned to the version that was live when it started, so publishing a new version does not change a run already under way. It records each answer by step id, and going back discards the last answer on the path.
-- **Answers** — the recorded state of a run, keyed by step id. The next step is always worked out from these answers and the connections in the pinned version.
+- **Run** — one visitor's pass through a flow. A run is pinned to the version that was live when it started, so publishing a new version does not change a run already under way. It records each answer by visit, and going back discards the last answer on the path.
+- **Answers** — the recorded state of a run, keyed by visit. The next step is always worked out from these answers and the connections in the pinned version.
+- **Loop** — a connection that leads back to a step the run has already passed, so that step is visited again. Branching steps read the most recent answer to a step, so a loop ends when an answer sends the run down a different connection.
+- **Visit** — one time a run reaches a step. The first visit is keyed by the step id alone, and each later visit is keyed by the step id, an `@`, and the visit number, such as `size@2`. Every visit's answer is kept, and a finished run lists each one.
+- **Stopped loop** — a run that comes back to a step with no new answer given since its last visit there ends at that point rather than cycling forever. Only answers the visitor gives count, so a loop made only of steps that act on their own stops the first time it comes round.
+- **Reserved `@`** — a step id may not contain `@`, since that mark numbers later visits. A flow holding such a step id is reported as invalid.
 - **Refused answer** — an answer the step's answer check turned down. Nothing is recorded for that step, and the visitor is shown the same step again with the check's message. This works the same whether the flow keeps a stored run or carries its answers in the page.
 - **Blank answer** — a step the visitor leaves blank. On a step whose answer check does not refuse it, such as a question that is not required, the blank is recorded and the visitor moves on to the next step.
 - **Checks** — warnings on a flow's shape: an answer value no connection routes, a path nothing follows, and a step that leads nowhere. The engine turns all three on by default. These are separate from answer checks, which look at what a visitor submits.

data/the_local/agents/easy_flow-install.md

@@ -51,7 +51,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    - `admin_authentication_method` — a method on the base controller, called with no arguments before every admin page. With none set, the admin pages are open to anyone.
    - `visitor_authorization_method` — a method on the base controller, called with the flow, returning true when the visitor may run it. With none set, every visitor is refused.
    - `refusal_method` — a method on the base controller, called with the refusal error when a visitor is refused or a flow is unpublished or withdrawn. With none set, the response is `404 Not Found`.
-   - `offers` — the step types this host's admins can add from the canvas palette, as a list of step type names. With none set, every registered step type is offered. The engine's own names are `question`, `condition`, `switch` and `compare`, A step type the app declares is named by the id passed to `EasyFlow.step`, or after its class when it is a step class, so `Steps::Notify` is `notify`. The End step is offered whether it is listed or not, and the Start step is never offered. Ask the developer which step types each host should offer.
+   - `offers` — the step types this host's admins can add from the canvas palette, as a list of step type names. With none set, every registered step type is offered. The engine's own names are `question`, `condition`, `switch` and `compare`. A step type the app declares is named by the id passed to `EasyFlow.step`, or after its class when it is a step class, so `Steps::Notify` is `notify`. The End step is offered whether it is listed or not, and the Start step is never offered. Ask the developer which step types each host should offer.
 
    Each method named here must exist on the base controller. Ask the developer to point at it or write it. Do not invent its logic.
 7. Mount the engine in `config/routes.rb`, once per host. The host name in `defaults` must match a name declared in step 6. When there is more than one mount, give each an `as:` name:
@@ -62,7 +62,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
    ```
 
    A mount whose host name is not declared serves no flows, and its admin pages return `404 Not Found`.
-8. Ask the developer whether visitors' steps should be drawn with the engine's own partial or with one from the app. For the app's own, create a partial, for example `app/views/steps/_step.html.erb`, which receives the step as the local `step`. It is rendered inside the engine's form, so it draws only the fields, and the visitor's answer must be submitted as `answers[<%= step.id %>]`. Then add to the initializer:
+8. Ask the developer whether visitors' steps should be drawn with the engine's own partial or with one from the app. For the app's own, create a partial, for example `app/views/steps/_step.html.erb`, which receives the step as the local `step`. It is rendered inside the engine's form, so it draws only the fields, and the visitor's answer must be submitted as `answers[<%= step.id %>]`. Always build the field name from `step.id` and never from a fixed id. When a flow loops back and asks a question again, `step.id` names that visit, so each visit's answer is stored apart. Then add to the initializer:
 
    ```ruby
    EasyFlow.draws_with("steps/step")

data/the_local/interface.yml

@@ -32,6 +32,8 @@ sources:
   - app/models/easy_flow/steps/question.rb
   - app/models/easy_flow/run.rb
   - app/models/easy_flow/runner.rb
+  - app/models/easy_flow/digest.rb
+  - app/models/easy_flow/validator.rb
   - app/models/easy_flow/question_runner.rb
   - config/routes.rb
   - db/migrate/20260924120000_create_easy_flow_definitions.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_flow
 version: !ruby/object:Gem::Version
-  version: 0.4.9
+  version: 0.5.0
 platform: ruby
 authors:
 - tylercschneider