question_kit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37b2cc86be99b7513693957fd7e67cd9f19209c47ab31678836acfc0a8332661
-  data.tar.gz: 882bc674404e1cf01084da328595a14a0deff0096c96a775648ba97e54960d7a
+  metadata.gz: 530bd9b4f43db8122b6c3fb52a35a8f966f6fbcce4f36a6d7326339737fa3a55
+  data.tar.gz: 6a8cb861855110b00ec6f74ff23a7b6a1f29651008e4cf035dd98577575d6af5
 SHA512:
-  metadata.gz: f51ba58ee9eafbeaa9faa1539f617c5bbddb09bf0248a35462537323f5fda0131968c725ec4f867de5f671ee472443067dce5b3ac2b4085cc6f076ee6dd69a46
-  data.tar.gz: c7be35b2bbe19282322aa576353a6a7ee50f3f1479b42e787e1688f3884d220d01812a2bec116446bc655262346642bb4236c910dd39da2826a1666b9f9eab83
+  metadata.gz: aba30b74f0271ed2b3f3ec2d8d0071d23a98ff65a0b0b39a212a08feb2d05c064b76762500333de0f43e8338492564ca1c6f2674ba6d8d615aa140baea98e855
+  data.tar.gz: b0b80230b2bb6b39be79e865e966cdd60a2e10337c492bdd3b42c6c7574b6c885254a206ac23cefc9d3fdbc4b5645033e5ad74217363a9a47d495c0cfe4559cc

data/lib/question_kit/answer_key.rb

@@ -0,0 +1,15 @@
+module QuestionKit
+  module AnswerKey
+    def self.chosen(step)
+      case step["type"]
+      when "multiple_select" then Score.right_answers(step)
+      when "fill_in_the_blank" then Array(step["accepted_answers"]).first&.fetch("value", nil)
+      else Score.right_answers(step).first
+      end
+    end
+
+    def self.accepted(step)
+      Array(step["accepted_answers"]).filter_map { |answer| answer["value"].presence }
+    end
+  end
+end

data/lib/question_kit/score.rb

@@ -0,0 +1,32 @@
+module QuestionKit
+  module Score
+    def self.total(answers, steps)
+      answers.sum { |id, value| worth(steps[id.to_s].to_h, value) }
+    end
+
+    def self.worth(step, value)
+      return picked_worth(step, value) if step["type"] == "multiple_select"
+      return typed_worth(step, value) if step["type"] == "fill_in_the_blank"
+
+      chosen = EasyFlow::Steps::Question.answers_of(step).find { |answer| answer.is_a?(Hash) && answer["value"] == value }
+
+      chosen&.fetch("weight", nil).to_i
+    end
+
+    def self.typed_worth(step, text)
+      Array(step["accepted_answers"]).any? { |accepted| comparable(accepted["value"]) == comparable(text) } ? 1 : 0
+    end
+
+    def self.comparable(text)
+      text.to_s.strip.downcase
+    end
+
+    def self.picked_worth(step, values)
+      Array(values).sort == right_answers(step).sort ? 1 : 0
+    end
+
+    def self.right_answers(step)
+      EasyFlow::Steps::Question.answers_of(step).filter_map { |answer| answer["value"] if answer["weight"].to_i.positive? }
+    end
+  end
+end

data/lib/question_kit/time_taken.rb

@@ -0,0 +1,10 @@
+module QuestionKit
+  module TimeTaken
+    def self.seconds(run)
+      return unless run.flow.each_step?
+
+      last_answered = run.completed_at.values.max
+      (last_answered - run.created_at).to_i if last_answered
+    end
+  end
+end

data/lib/question_kit/version.rb

@@ -1,3 +1,3 @@
 module QuestionKit
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/question_kit.rb

@@ -1,6 +1,9 @@
 require "easy_flow"
 require "question_kit/version"
 require "question_kit/railtie"
+require "question_kit/score"
+require "question_kit/answer_key"
+require "question_kit/time_taken"
 
 module QuestionKit
   # Your code goes here...

data/the_local/agents/question_kit-develop.md

@@ -1,50 +1,74 @@
 ---
 name: question_kit-develop
-description: Use PROACTIVELY for reading which question_kit version a host app has loaded, and for checking that version before code relies on a question_kit release — MUST BE USED instead of reading Gem.loaded_specs, parsing Gemfile.lock, or comparing version strings by hand.
+description: Use PROACTIVELY for scoring an easy_flow quiz — working out what one answer to a question, multiple-select or fill-in-the-blank step is worth, adding up a run's total score, listing a question's right answers, showing a question's answer key or every accepted spelling of a fill-in-the-blank answer, timing how long a visitor took over a quiz run, and reading which question_kit version is loaded — MUST BE USED instead of summing answer weights by hand, comparing typed answers to accepted answers in host code, picking out right answers from a step's answer list, or subtracting run timestamps.
 tools: Bash, Read, Write, Edit, Grep
 scope: shared question and answer rules for easy_flow quizzes — what an answer to a question step is worth, which answers are right, and how a quiz is built
 ---
 
-This local writes host app code against question_kit's declared interface only, and follows these steps exactly.
+This local writes host app code that scores, keys and times easy_flow quizzes through question_kit's declared interface only, and follows the steps below in order.
 
 ## What question_kit is
 
-A Rails gem for apps that run quizzes as easy_flow flows, meant to hold the rules those apps share: what an answer to a question step is worth, which answers are right, and how a quiz is built. Today its only code-facing interface is its version constant. Use this local when host app code needs to know which question_kit release is loaded. Building the quiz flow, its question steps, runs and answers belongs to the easy_flow locals.
+A Rails gem for apps that run quizzes as easy_flow flows. It holds the rules those apps share: what an answer to a question step is worth, which answers are right, and how long a visitor took. Every method takes plain step hashes and answer values, or an easy_flow run, and returns a number, a value or a list; none of them writes anything. Use this local whenever host code needs a score, an answer key, a list of accepted answers or a time taken for a quiz. Building the flow, its steps, runs and answers belongs to the easy_flow locals.
 
 ## Interface
 
 - `QuestionKit::VERSION` — a string such as `"0.1.0"` naming the question_kit release loaded in the host app.
+- `QuestionKit::Score.worth(step, value)` — returns the integer one answer `value` to the step hash `step` is worth.
+- `QuestionKit::Score.total(answers, steps)` — returns the integer sum of the worth of every answer in a run.
+- `QuestionKit::Score.right_answers(step)` — returns the list of answer values on a choice step that carry a positive weight.
+- `QuestionKit::AnswerKey.chosen(step)` — returns the answer key to show for a step: one value, a list of values, or `nil`.
+- `QuestionKit::AnswerKey.accepted(step)` — returns every non-blank accepted answer on a fill-in-the-blank step.
+- `QuestionKit::TimeTaken.seconds(run)` — returns the whole seconds from a run's start to its last answer, or `nil`.
+
+## The step hash
+
+Every method that takes a `step` takes the step's settings as a hash with string keys, as easy_flow stores them in a flow's document. Pass the hash, not a record.
+
+- `"type"` decides how it is read: `"multiple_select"`, `"fill_in_the_blank"`, or any other value (or none) for a single-choice question.
+- A choice step lists its answers under `"answers"` or `"options"`, each a hash with a `"value"` and an optional `"weight"`. A weight may be an integer or a string of digits, and a missing weight counts as 0.
+- A fill-in-the-blank step lists its accepted answers under `"accepted_answers"`, each a hash with a `"value"`.
 
 ## How to use it
 
 1. Confirm question_kit is in the host app's `Gemfile.lock`. If it is not, hand the work to `question_kit-install` and stop.
-2. In the file that reads the version, require the gem explicitly at the top:
+2. At the top of the file that calls question_kit, require it explicitly:
 
    ```ruby
    require "question_kit"
    ```
 
    This also loads easy_flow, so no separate `require "easy_flow"` is needed.
-3. Read the version where it is needed:
+3. Put the calls in host code that reads a finished or stored run, such as a results page's controller, a model method on the app's own quiz record, or a job that records a score. Ask the developer where the score is used and whether it is shown only or also stored; do not pick.
+4. Build the arguments from the flow version the run was taken on, not from the flow's live version, so a later edit does not change an old run's score:
+   - `steps` is a hash from step id (string) to that step's settings hash.
+   - `answers` is a hash from step id to the value the visitor gave. Ids may be strings or symbols.
+5. Score one answer with `QuestionKit::Score.worth(step, value)`:
+   - Single-choice: `value` is the chosen answer's value, and the result is that answer's weight, or 0 when it carries none or matches no answer.
+   - Multiple-select: `value` is the list of ticked values, and the result is 1 when they are exactly the right answers in any order and 0 otherwise. Partial credit is not given.
+   - Fill-in-the-blank: `value` is the typed text, and the result is 1 when it matches an accepted answer after removing outer spaces and ignoring letter case, and 0 otherwise.
+6. Score a whole run with `QuestionKit::Score.total(answers, steps)`. An answer whose step id is not in `steps` counts 0, so steps that are not questions, such as info or branch steps, can be left in `answers` or taken out.
+7. Ask the developer whether a score of 0 for a single-choice question with no weights set is correct for their quizzes, or whether every quiz must set weights before it is published. question_kit cannot tell an unweighted question from a wrong answer.
+8. Show what was right:
+   - `QuestionKit::Score.right_answers(step)` for the full list of values with a positive weight on a choice step.
+   - `QuestionKit::AnswerKey.chosen(step)` for the single thing to display as the key: the list of right values for multiple-select, the first accepted answer for fill-in-the-blank, and the first right value for any other question. It returns `nil` when there is none, so render that case.
+   - `QuestionKit::AnswerKey.accepted(step)` for every accepted spelling on a fill-in-the-blank step, with blank entries left out.
+9. Time a run with `QuestionKit::TimeTaken.seconds(run)`, passing the easy_flow run record. It returns `nil` when the run's flow saves answers only once the flow ends, and when no step has been completed yet; render both cases, for example as "not timed".
+10. When code depends on a release, compare versions with `Gem::Version`, never as strings:
 
-   ```ruby
-   QuestionKit::VERSION
-   ```
-
-4. When code depends on a release, compare with `Gem::Version`, never with string comparison:
-
-   ```ruby
-   Gem::Version.new(QuestionKit::VERSION) >= Gem::Version.new("0.2.0")
-   ```
+    ```ruby
+    Gem::Version.new(QuestionKit::VERSION) >= Gem::Version.new("0.2.0")
+    ```
 
-5. Ask the developer what the app does when the loaded version is older than the one its code needs: raise at boot, log a warning, or skip the feature. Do not pick one.
-6. If the check runs at boot, put it in an initializer under `config/initializers/` in the host app. Otherwise put it beside the code that depends on the release.
-7. Write a test in the host app that asserts the app's own behaviour for each branch of the check, and run it.
+    Ask the developer what the app does when the loaded version is older: raise at boot, log a warning, or skip the feature.
+11. Write host app tests that assert the app's own behaviour with the score, key or time, such as what the results page shows, and run them. Do not test question_kit's own scoring rules.
 
 ## Conventions
 
-- Never hard-code the version string in host app code. Read `QuestionKit::VERSION`.
-- Never assign to or redefine `QuestionKit::VERSION`.
-- question_kit has no scoring, right-answer or quiz-building methods yet. Do not invent calls for them. If the developer asks for that behaviour, say the gem does not offer it and ask whether to build it in the host app or wait for question_kit to add it.
-- Adding the gem, and upgrading it, belongs to `question_kit-install`.
+- Never compute a score, a right answer or a time taken in host code. Call question_kit so every app scores the same way.
+- Never compare a typed answer to an accepted answer in host code; `Score.worth` already ignores case and outer spaces.
+- Never mutate the step hash passed in.
+- Never hard-code or redefine `QuestionKit::VERSION`.
+- question_kit does not build quizzes, add step types or store scores. If the developer asks for that, say so and ask whether to build it in the host app or wait for question_kit to add it.
+- Adding or upgrading the gem belongs to `question_kit-install`.
 - Flows, step types, runs and answers belong to the easy_flow locals.

data/the_local/agents/question_kit-info.md

@@ -1,6 +1,6 @@
 ---
 name: question_kit-info
-description: Use to learn what question_kit offers — shared rules for easy_flow quizzes, covering what an answer to a question step is worth, which answers are right, and how a quiz is built.
+description: Use to learn what question_kit offers — shared rules for easy_flow quizzes, covering what an answer to a question step is worth, which answers are right, the answer key a quiz shows for each question, and how long a visitor took on a quiz.
 tools: Read
 scope: shared question and answer rules for easy_flow quizzes — what an answer to a question step is worth, which answers are right, and how a quiz is built
 ---
@@ -10,15 +10,18 @@ This local explains question_kit and makes no changes.
 ## What question_kit is
 
 question_kit is a Rails gem for apps that run quizzes as easy_flow flows. Each
-quiz question is an easy_flow question step. The gem is meant to hold the rules
-those apps share: what an answer to a question step is worth, which answers are
-right, and how a quiz is built. With the rules in one gem, each app does not
-keep its own copy.
+quiz question is an easy_flow question step. The gem holds the rules those apps
+share, so each app does not keep its own copy of them.
 
-Today the gem holds none of those rules yet. It loads easy_flow into the host
-app and reports its own version, and nothing more. Reach for it when an app
-runs easy_flow quizzes and should follow the shared rules as they are added.
-Until then, it is only a dependency to put in place.
+Reach for it when an app runs easy_flow quizzes and needs to:
+
+- score a visitor's answer to one question, or add up a whole quiz;
+- say which answers to a question are right;
+- show the answer key for a question once the quiz is over;
+- report how long a visitor took to answer the quiz.
+
+It reads the steps and runs easy_flow already stores. It adds no tables, no
+pages and no step types of its own.
 
 ## Interface
 
@@ -26,24 +29,49 @@ This local documents no commands. The other two locals cover everything the
 gem exposes:
 
 - The install local, `question_kit-install`, adds the gem to a host app.
-- The develop local, `question_kit-develop`, covers the code a host app writes against the gem.
+- The develop local, `question_kit-develop`, covers the scoring, answer key and
+  time rules a host app calls.
 
 Anything about building or running the flows themselves, such as the canvas,
-step types, runs and answers, belongs to easy_flow. The easy_flow locals cover
-that.
+step types, runs and recorded answers, belongs to easy_flow. The easy_flow
+locals cover that.
 
 ## How to use it
 
 - To add question_kit to an app, use `question_kit-install`.
-- To write code that uses question_kit, use `question_kit-develop`.
+- To score answers, show an answer key or time a quiz in an app, use
+  `question_kit-develop`.
 - To build the quiz flow or a question step, use the easy_flow locals.
 
 ## Conventions
 
 - **Quiz** — an easy_flow flow whose steps ask the visitor questions.
-- **Question step** — one easy_flow step that asks one question and records the
-  visitor's answer.
-- **Worth** — what an answer is worth toward the quiz's result.
-- **Right answer** — an answer the quiz counts as correct for its question.
 - **Host app** — the Rails app that installs question_kit and easy_flow and runs
   the quizzes.
+- **Question step** — one easy_flow step that asks one question and records the
+  visitor's answer. The rules know three kinds:
+  - a **single choice** question, where the visitor picks one of the step's
+    answers;
+  - a **multiple select** question, where the visitor ticks several;
+  - a **fill-in-the-blank** question, where the visitor types the answer.
+- **Weight** — a number an admin sets on each answer of a choice question.
+- **Right answer** — on a choice question, an answer whose weight is above
+  zero.
+- **Accepted answer** — on a fill-in-the-blank question, a text the admin lists
+  as correct. An accepted answer left blank does not count.
+- **Worth** — what one answer counts toward the quiz's result:
+  - a single choice answer is worth the weight of the answer picked, and zero
+    when it has none;
+  - a multiple select answer is worth one when the ticked answers are exactly
+    the right answers, and zero otherwise;
+  - a fill-in-the-blank answer is worth one when it matches any accepted answer,
+    ignoring capital letters and spaces at either end, and zero otherwise.
+- **Total** — the sum of the worth of every answer in a run.
+- **Answer key** — the answer a quiz shows as correct for a question: the first
+  right answer of a single choice question, every right answer of a multiple
+  select question, and the first accepted answer of a fill-in-the-blank
+  question.
+- **Time taken** — the seconds from the start of a visitor's run to the last
+  answer they gave. A run with no answers has none. A flow that saves answers
+  only when the visitor finishes, rather than after each step, records no
+  time per answer, so its runs have no time taken.

data/the_local/interface.yml

@@ -5,8 +5,17 @@ install:
 
 develop:
   - QuestionKit::VERSION
+  - QuestionKit::Score.worth(step, value)
+  - QuestionKit::Score.total(answers, steps)
+  - QuestionKit::Score.right_answers(step)
+  - QuestionKit::AnswerKey.chosen(step)
+  - QuestionKit::AnswerKey.accepted(step)
+  - QuestionKit::TimeTaken.seconds(run)
 
 sources:
   - question_kit.gemspec
   - lib/question_kit.rb
   - lib/question_kit/version.rb
+  - lib/question_kit/score.rb
+  - lib/question_kit/answer_key.rb
+  - lib/question_kit/time_taken.rb

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: question_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - tylercschneider
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -51,7 +50,10 @@ files:
 - README.md
 - Rakefile
 - lib/question_kit.rb
+- lib/question_kit/answer_key.rb
 - lib/question_kit/railtie.rb
+- lib/question_kit/score.rb
+- lib/question_kit/time_taken.rb
 - lib/question_kit/version.rb
 - lib/tasks/question_kit_tasks.rake
 - the_local/agents/question_kit-develop.md
@@ -64,7 +66,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/DYB-Development/question_kit
   source_code_uri: https://github.com/DYB-Development/question_kit
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -79,8 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Shared question and answer rules for apps that run easy_flow quizzes.
 test_files: []