inquirex 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a1021c83f11e037c69736dd5fa9228d95af53c9f7967173dd21bf9b096d4f31
+  data.tar.gz: 5b3cec5558da5aa1f9c3850e77ff6021916b9652531862ba621b8a7ea65fd5a7
+SHA512:
+  metadata.gz: aba4ff0487e52177d96fdf385c3268f4ea3c888c7e0e711547ec7b78700c7b5b377d573235823a5d8fe2861553006bed2b7573cdc9c8c38c2fc480ae0af81aa9
+  data.tar.gz: d1f7ccf5705755923d240414abb3e688534a618a36f9607fd60d6a526b72886c5d7fd86d8b1b93589edf16f7627c0ac2c26be4d7d42f1a4109f9f0bf1376ee2e

data/.relaxed_rubocop.yml

@@ -0,0 +1,153 @@
+# Relaxed.Ruby.Style
+## Version 2.5
+
+Style/Alias:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylealias
+
+Style/AsciiComments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleasciicomments
+
+Style/BeginBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylebeginblock
+
+Style/BlockDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleblockdelimiters
+
+Style/CommentAnnotation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylecommentannotation
+
+Style/Documentation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledocumentation
+
+Layout/DotPosition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutdotposition
+
+Style/DoubleNegation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledoublenegation
+
+Style/EndBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleendblock
+
+Style/FormatString:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleformatstring
+
+Style/IfUnlessModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleifunlessmodifier
+
+Style/Lambda:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylelambda
+
+Style/ModuleFunction:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemodulefunction
+
+Style/MultilineBlockChain:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemultilineblockchain
+
+Style/NegatedIf:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedif
+
+Style/NegatedWhile:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedwhile
+
+Style/NumericPredicate:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenumericpredicate
+
+Style/ParallelAssignment:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleparallelassignment
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylepercentliteraldelimiters
+
+Style/PerlBackrefs:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleperlbackrefs
+
+Style/Semicolon:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesemicolon
+
+Style/SignalException:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesignalexception
+
+Style/SingleLineBlockParams:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelineblockparams
+
+Style/SingleLineMethods:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelinemethods
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspacebeforeblockbraces
+
+Layout/SpaceInsideParens:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspaceinsideparens
+
+Style/SpecialGlobalVars:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylespecialglobalvars
+
+Style/StringLiterals:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylestringliterals
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarguments
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarrayliteral
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainhashliteral
+
+Style/SymbolArray:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesymbolarray
+
+Style/WhileUntilModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewhileuntilmodifier
+
+Style/WordArray:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewordarray
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintambiguousregexpliteral
+
+Lint/AssignmentInCondition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics:
+  Enabled: false
+

data/.ruby-version

@@ -0,0 +1 @@
+4.0.2

data/.secrets.baseline

@@ -0,0 +1,127 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-04-13T21:29:03Z"
+}

data/Brewfile

@@ -0,0 +1,7 @@
+# Please run `brew bundle` before running `lefthook install`
+
+brew 'lefthook'
+brew 'codespell'
+brew 'mdformat'
+brew 'detect-secrets'
+

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-13
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Konstantin Gredeskoul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,289 @@
+# Inquirex
+
+`inquirex` is a pure Ruby, declarative, rules-driven questionnaire engine for building conditional intake forms, qualification wizards, and branching surveys.
+
+It is the core gem in the Inquirex ecosystem and focuses on:
+
+- A conversational DSL (`ask`, `say`, `header`, `btw`, `warning`, `confirm`)
+- A serializable AST rule system (`contains`, `equals`, `greater_than`, `less_than`, `not_empty`, `all`, `any`)
+- An immutable flow definition graph
+- A runtime engine for stateful step traversal
+- JSON round-trip serialization for cross-platform clients
+- A structured `Answers` wrapper and Mermaid graph export
+
+## Status
+
+- Version: `0.1.0`
+- Ruby: `>= 4.0.0` (project currently uses `4.0.2`)
+- Test suite: `109 examples, 0 failures`
+- Coverage: ~`92.5%` line coverage
+
+## Why Inquirex
+
+Many form builders hard-code branching in controllers, React components, or database callbacks. Inquirex keeps flow logic in one portable graph:
+
+- Define once in Ruby
+- Serialize to JSON
+- Evaluate transitions consistently using rule AST objects
+- Run the same flow in different frontends (web widget, terminal, etc.)
+
+This design is the foundation for the broader ecosystem (`inquirex-ui`, `inquirex-tty`, `inquirex-js`, `inquirex-llm`, `inquirex-rails`).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "inquirex"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require "inquirex"
+
+definition = Inquirex.define id: "tax-intake-2025", version: "1.0.0" do
+  meta title: "Tax Preparation Intake", subtitle: "Let's understand your situation"
+  start :filing_status
+
+  ask :filing_status do
+    type :enum
+    question "What is your filing status?"
+    options single: "Single", married_jointly: "Married Filing Jointly"
+    transition to: :dependents
+  end
+
+  ask :dependents do
+    type :integer
+    question "How many dependents?"
+    default 0
+    transition to: :business_income
+  end
+
+  confirm :business_income do
+    question "Do you have business income?"
+    transition to: :business_count, if_rule: equals(:business_income, true)
+    transition to: :done
+  end
+
+  ask :business_count do
+    type :integer
+    question "How many businesses?"
+    transition to: :done
+  end
+
+  say :done do
+    text "Thanks for completing the intake."
+  end
+end
+
+engine = Inquirex::Engine.new(definition)
+
+engine.answer("single") # filing_status
+engine.answer(2)        # dependents
+engine.answer(false)    # business_income
+engine.advance          # done (display step)
+
+engine.finished? # => true
+```
+
+## DSL Overview
+
+### Flow-level methods
+
+- `start :step_id` sets the entry step
+- `meta title:, subtitle:, brand:` adds optional frontend metadata
+
+### Step verbs
+
+- Collecting verbs: `ask`, `confirm`
+- Display verbs: `say`, `header`, `btw`, `warning`
+
+### Supported input types
+
+- `:string`
+- `:text`
+- `:integer`
+- `:decimal`
+- `:currency`
+- `:boolean`
+- `:enum`
+- `:multi_enum`
+- `:date`
+- `:email`
+- `:phone`
+
+### Step options
+
+- `question "..."` for collecting steps
+- `text "..."` for display steps
+- `options [...]` or `options key: "Label"` for enum-style inputs
+- `default value` or `default { |answers| ... }`
+- `skip_if rule`
+- `transition to: :next_step, if_rule: rule, requires_server: false`
+- `compute { |answers| ... }` (accepted by the DSL as a server-side hook; currently omitted from runtime JSON)
+
+## Rule System (AST, JSON-serializable)
+
+Rule helpers available in DSL blocks:
+
+- `contains(:income_types, "Business")`
+- `equals(:status, "single")`
+- `greater_than(:dependents, 0)`
+- `less_than(:age, 18)`
+- `not_empty(:email)`
+- `all(rule1, rule2, ...)`
+- `any(rule1, rule2, ...)`
+
+Example:
+
+```ruby
+transition to: :complex_path,
+  if_rule: all(
+    contains(:income_types, "Business"),
+    greater_than(:business_count, 2)
+  )
+```
+
+## Runtime Engine
+
+`Inquirex::Engine` holds runtime state:
+
+- `current_step_id`
+- `current_step`
+- `answers` (raw hash)
+- `history` (visited step IDs)
+
+Behavior:
+
+- Use `answer(value)` on collecting steps
+- Use `advance` on display steps
+- Use `finished?` to detect completion
+- Use `to_state` / `.from_state` for persistence/resume
+
+### Validation Adapter
+
+Validation is pluggable:
+
+- `Inquirex::Validation::Adapter` (abstract)
+- `Inquirex::Validation::NullAdapter` (default, accepts everything)
+
+Pass a custom adapter to the engine:
+
+```ruby
+engine = Inquirex::Engine.new(definition, validator: my_validator)
+```
+
+## Serialization
+
+Definitions support round-trip serialization:
+
+```ruby
+json = definition.to_json
+restored = Inquirex::Definition.from_json(json)
+```
+
+Serialized structure includes:
+
+- Flow metadata (`id`, `version`, `meta`, `start`)
+- Steps and transitions
+- Rule AST payloads
+
+Important serialization details:
+
+- Rule objects serialize and deserialize cleanly
+- Proc/lambda defaults are stripped from JSON
+- `requires_server: true` transition flag is preserved
+
+## Answers Wrapper
+
+`Inquirex::Answers` provides structured answer access:
+
+```ruby
+answers = Inquirex::Answers.new(
+  filing_status: "single",
+  business: { count: 3, type: "llc" }
+)
+
+answers.filing_status         # => "single"
+answers[:filing_status]       # => "single"
+answers.business.count        # => 3
+answers.dig("business.count") # => 3
+answers.to_flat_h             # => {"filing_status"=>"single", "business.count"=>3, ...}
+```
+
+## Mermaid Export
+
+Visualize flow graphs with Mermaid:
+
+```ruby
+exporter = Inquirex::Graph::MermaidExporter.new(definition)
+puts exporter.export
+```
+
+Output is `flowchart TD` syntax with:
+
+- One node per step
+- Conditional edge labels from rule `to_s`
+- Truncated node content for readability
+
+## Error Types
+
+Common exceptions under `Inquirex::Errors`:
+
+- `DefinitionError`
+- `UnknownStepError`
+- `SerializationError`
+- `AlreadyFinishedError`
+- `ValidationError`
+- `NonCollectingStepError`
+
+## Development
+
+### Setup
+
+```bash
+bin/setup
+```
+
+### Run tests
+
+```bash
+bundle exec rspec
+```
+
+### Lint
+
+```bash
+bundle exec rubocop
+```
+
+### Useful `just` tasks
+
+```bash
+just install
+just test
+just lint
+just lint-fix
+just ci
+```
+
+## Roadmap Context
+
+This repository is the core runtime (`inquirex`). The full ecosystem roadmap includes:
+
+- `inquirex-ui` for rendering metadata
+- `inquirex-tty` for terminal interaction
+- `inquirex-js` for embeddable web widget runtime
+- `inquirex-llm` for server-side LLM verbs
+- `inquirex-rails` for persistence/API integration
+
+## License
+
+MIT. See `LICENSE.txt`.

data/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "timeout"
+require "yard"
+
+def shell(*args)
+  puts "running: #{args.join(" ")}"
+  system(args.join(" "))
+end
+
+task :clean do
+  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
+end
+
+task gem: [:build] do
+  shell("gem install pkg/*")
+end
+
+task permissions: [:clean] do
+  shell("chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*")
+  shell("find . -type d -exec chmod o+x,g+x {} \\;")
+end
+
+task build: :permissions
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt CHANGELOG.md]
+  t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
+  t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/inquirex

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require "inquirex"

data/justfile

@@ -0,0 +1,38 @@
+set shell := ["bash", "-lc"]
+
+rbenv := 'eval "$(rbenv init -)"'
+
+[no-exit-message]
+recipes:
+    @just --choose
+
+# Sync all dependencies
+install:
+    {{rbenv}} && bin/setup
+
+# Lint and reformat files
+lint-fix *args:
+    {{rbenv}} && bundle exec rubocop -a
+
+alias format := lint-fix
+
+# Lint and reformat files
+lint:
+    {{rbenv}} && bundle exec rubocop
+
+# Run all the tests
+test *args: 
+    {{rbenv}} &&  ENVIRONMENT=test bundle exec rspec {{args}}
+
+# Run tests with coverage
+test-coverage *args:
+    ENVIRONMENT=test COVERAGE=true bundle exec rspec
+
+clean:
+    #!/usr/bin/env bash
+    find . -name .DS_Store -delete -print || true
+    rm -rf tmp/*
+
+# Run all lefthook pre-commit hooks
+ci:
+    {{rbenv}} && lefthook run pre-commit --all-files