next_station 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4919adb566091f3858358dc3678ba9b4bdde44ef42a6dcf854c94d59567230f1
+  data.tar.gz: 279c5c6c85214489b599be67fad370048ba49bb0862f388c6a99b1b21d390ac0
+SHA512:
+  metadata.gz: ab2769ab95a44b9f1a5cb760b742f6f7bf9180ba3e412d75e0b39436178d7a37b3b43e30c430487b42fd1d8751f1a852b9602e80727a817cdf32f8b59270e989
+  data.tar.gz: 20708b8341888222dabf110e877dcb30bbeb54b2fade8f0654875af6be4377e92d4b3d607f37775d612eb8a30efacc9e2e344edc16908ee7be171dc79d2d2f9f

data/.aiignore

@@ -0,0 +1,36 @@
+
+spec/contract
+todo.txt
+
+# Ignore build output directories
+target/
+out/
+
+# Ignore Maven wrapper files
+.mvn/
+
+# Ignore project files
+.idea/
+*.iml
+doc/
+.yardoc
+# Ignore compiled Java class files
+*.class
+
+# Ignore all .java files except the ones from the 'src/main' folder
+*.java
+!src/main/**/*.java
+
+# Ignore test reports and test directories
+test-results/
+allure-results/
+
+# Ignore logs and temporary files
+logs/
+*.log
+*.tmp
+*.gem
+tmp/
+
+/log
+/tmp

data/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/

data/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,8 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="RubyResolve" enabled="false" level="WARNING" enabled_by_default="false">
+      <option name="warnImplicitResults" value="false" />
+    </inspection_tool>
+  </profile>
+</component>

data/.idea/junie.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JunieProject">
+    <option name="guidelinesPath" value="AGENTS.md" />
+  </component>
+</project>

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/next_station.iml" filepath="$PROJECT_DIR$/.idea/next_station.iml" />
+    </modules>
+  </component>
+</project>

data/.idea/next_station.iml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/features" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/spec" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+      <excludeFolder url="file://$MODULE_DIR$/doc" />
+    </content>
+    <orderEntry type="jdk" jdkName="rbenv: 4.0.1" jdkType="RUBY_SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="ast (v2.4.3, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bigdecimal (v4.0.1, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v4.0.5, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="concurrent-ruby (v1.3.6, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.6.2, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-configurable (v1.3.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-core (v1.2.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-events (v1.1.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-inflector (v1.3.1, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-initializer (v3.2.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-logic (v1.6.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-monitor (v1.0.1, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-schema (v1.15.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-struct (v1.8.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-types (v1.9.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="dry-validation (v1.11.1, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ice_nine (v0.11.2, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="json (v2.18.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="language_server-protocol (v3.17.0.5, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="lint_roller (v1.1.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="logger (v1.7.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parallel (v1.27.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parser (v3.3.10.1, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="prism (v1.9.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="racc (v1.8.1, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rainbow (v3.1.1, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="regexp_parser (v2.11.3, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec (v3.13.2, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.13.6, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.13.5, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.13.7, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.13.7, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop (v1.84.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop-ast (v1.49.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ruby-progressbar (v1.13.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-display_width (v3.2.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-emoji (v4.2.0, rbenv: 4.0.1) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="zeitwerk (v2.7.4, rbenv: 4.0.1) [gem]" level="application" />
+  </component>
+</module>

data/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

data/AGENTS.md

@@ -0,0 +1,157 @@
+# Development Guidelines
+
+This document defines the principles and conventions that should guide the development of this Ruby gem. The main goal is to produce code that is clean, readable, maintainable, and safe in concurrent environments, prioritizing long-term quality over short-term convenience.
+
+## 0. What is the purpose of this gem?
+
+> **Note:** This is just a high-level overview of the gem for reference. **Do not attempt to implement or write it from this description**—it’s meant to explain what the gem does, not how to build it.
+
+NextStation is a lightweight, thread-safe toolkit for building Railway Oriented Programming (ROP) style operations in Ruby. It helps decouple business logic from controllers/models in both plain Ruby and Rails apps (without depending on Rails).
+
+- Clean, SOLID-friendly DSL for defining operations and steps
+- Immutable context, isolated operation state
+- Explicit success/failure results with typed, localized errors
+- Validations (dry-validation) and Results (dry-struct) integration
+- Step controls: conditional skip, retries, and minimal branching
+- Dependency Injection
+- Plugins system with hook points (includes JSON Logging via semantic_logger)
+- Introspection via class config helpers
+
+## 1. Design Principles
+
+### SOLID as a foundation
+The application of SOLID principles should be favored whenever it is reasonable:
+
+- Single Responsibility Principle (SRP)  
+  Each class or module should have one clear responsibility.
+- Open/Closed Principle (OCP)  
+  Code should be open for extension but closed for modification.
+- Liskov Substitution Principle (LSP)  
+  Subtypes must be substitutable for their base types without unexpected behavior.
+- Interface Segregation Principle (ISP)  
+  Prefer small, focused interfaces over large, generic ones.
+- Dependency Inversion Principle (DIP)  
+  Depend on abstractions, not on concrete implementations.
+
+SOLID principles are guidelines, not rigid rules.
+Avoid forcing abstractions when they introduce unnecessary complexity, excessive nesting of files or directories, or an explosion of tiny classes.
+
+## 2. Readability and Simplicity
+
+- Code readability is a top priority.
+- Prefer explicit and easy-to-understand code over clever or overly compact solutions.
+- A new developer should be able to quickly understand the intent of the code.
+- Use clear and descriptive names for classes, methods, and variables.
+- Avoid comments that explain what the code does; the code should be self-explanatory.  
+- Comments should explain why a decision was made when it is not obvious.
+- Yardoc comments are encouraged for public API. Must be updated to stay in sync with the current behavior if you
+  change that portion of the code.
+
+## 3. RuboCop Conventions
+
+- Code should follow RuboCop conventions as the general standard.
+- Breaking a RuboCop rule is acceptable when:
+    - Following it introduces unnecessary complexity.
+    - It significantly harms readability.
+    - It forces unnatural or artificial code structures.
+
+In such cases:
+- The decision must be deliberate and justified.
+- Prefer disabling rules locally (`# rubocop:disable`) rather than globally.
+
+## 4. Thread Safety
+
+The gem must be thread-safe by default, considering usage in concurrent environments.
+
+Expected best practices:
+
+- Avoid mutable global state.
+- Do not use class variables (`@@`) unless strictly necessary and proven safe.
+- Prefer immutable objects.
+- Properly synchronize access to shared resources when required.
+- Be cautious with memoization in concurrent contexts.
+
+## 5. Framework-Agnostic Design (Rails Optional)
+
+This gem is intended to be usable both in Rails and non-Rails environments.
+
+Guidelines:
+
+- Do not introduce dependencies that force users to install Rails-related gems.
+- Avoid relying on Rails-specific libraries such as ActiveSupport, ActiveModel, etc.
+- Use plain Ruby alternatives whenever possible.
+- If Rails-specific integrations are needed, they should be:
+    - Optional
+    - Clearly isolated
+    - Loaded conditionally
+
+The core functionality of the gem must remain framework-agnostic.
+
+## 6. Code Structure
+
+- Maintain a clear and consistent organization of files and modules.
+- Modules should reflect the domain and intent of the code.
+- Avoid oversized classes; split responsibilities when appropriate.
+- Favor composition over inheritance.
+
+## 7. Runtime Optimization (YJIT and JRuby)
+This gem should be written with performance considerations for both **CRuby (with YJIT enabled)** and **JRuby**, without sacrificing readability or maintainability.
+
+### YJIT Considerations (CRuby)
+When writing code intended to benefit from YJIT:
+
+- Avoid using OpenStruct
+- Avoid redefining basic integer operations (i.e. +, -, <, >, etc.)
+- Avoid redefining the meaning of nil, equality, etc.
+- Avoid allocating objects in the hot parts of your code
+- Minimize layers of indirection
+- Avoid writing wrapper classes if you can (e.g. a class that only wraps a Ruby hash)
+- Avoid methods that just call another method
+- Ruby method calls are costly. Avoid things such as methods that only return a value from a hash
+
+### JRuby Considerations
+
+When targeting JRuby compatibility and performance:
+
+- Avoid Ruby features with poor JVM performance characteristics (e.g., heavy use of `eval`).
+- Prefer long-lived objects over frequent short-lived allocations when reasonable.
+- Be mindful of object churn in hot paths.
+- Avoid relying on MRI-specific behavior or undocumented internals.
+- Ensure all code is compatible with JRuby’s threading and concurrency model.
+
+## 8. Documentation Consistency
+
+- Any functional or behavioral change must be reflected in the documentation.
+- The README must be updated to stay in sync with the current behavior and API of the gem.
+- Examples, usage instructions, and configuration options should accurately reflect the current implementation.
+- Avoid specs that require excessive setup or deep object graphs.
+
+
+## 9. RSpec Style and Structure
+
+- Use `describe` for classes and modules.
+- Use `context` to describe meaningful state or conditions.
+- Use `it` blocks with clear, descriptive sentences.
+- Prefer `let` over instance variables.
+- Avoid excessive use of `before(:all)`; prefer `before(:each)`.
+### Modification of existing specs:
+If new behavior requires additional coverage:
+- Add new test files or new examples.
+- Test modifications are allowed only when they are strictly necessary to support new or explicitly requested functionality.
+
+### Do NOT touch the human-generated specs.
+- IMPORTANT: Files under `spec/contract/` are immutable and must never be modified by you.
+
+### Ignore result of human-generated specs.
+Spec under `spec/contract/` may fail as you do not control this. You must ignore the results of these specs.
+- When running rspec or scpec commands, you can find a way to exclude those files during your test run.
+
+
+## 10. Pragmatism
+
+- These guidelines exist to improve the codebase, not to slow down development.
+- When in doubt, choose and prefer the solution that is:
+    1. More readable
+    2. Simpler
+    3. Easier to maintain in the long term
+- Dont forget to update the README.

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in next_station.gemspec
+gemspec
+
+group :development do
+  gem 'rspec'
+  gem 'rubocop', require: false
+end