callable_tree 0.3.10 → 0.3.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dccb97d338f0f2d01a1986b2b0418660467fde837a79bd06b67f0df235bee5f2
-  data.tar.gz: 5002a705a96346ea92704eea7c8282beead6d4ef62c7ff2a9865f4b24e629faa
+  metadata.gz: 2eaeaea579c042e73c734e49279adb3321ab6008e4f6165ff4a701228217af00
+  data.tar.gz: e0c848254ac6802960723abb285423c21a477c228396cc384cd84a22fa31d565
 SHA512:
-  metadata.gz: 1d16dd16df13a3c5f5b6a4c5292d50acbf571482dbde0496e29d69d745ad887b4274e84edd5ace4707fe2bdf54d324389a2d1b662ffb94d1e430e5819762f40d
-  data.tar.gz: f531ae0eaaf51065f69e61a8eb4e70b83ba32bc280d699c2fce00b4b4a9c1ac3d8fb5fe61bcb3a7c40805edae1a26c4943bd9d09a4d4760a4e0f67a3dd4f62e9
+  metadata.gz: a144f0e3bcd69957274c4eb80008a812aa0f980163339f9aa0f501cc4ee0b63c1c1097df6dcfb2633aa449be79e620214b81f962b1c0a3b9cc81acdbc037beeb
+  data.tar.gz: 1c3c8fb5f5e4043864506b91ee7dd8b87e616ddecefdf593d9a302de92d056f8c505a483e6b6173a6ce01fe016366ccd56d58aa295f46902a7cf70c3bce039f3

data/.github/workflows/build.yml

@@ -1,18 +1,32 @@
 name: build
 on: [push]
 jobs:
-  build:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 4.0
+          bundler-cache: true
+      - name: Run bundle install
+        run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
+      - run: bundle exec rubocop
+
+  test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: ['2.4', '2.5', '2.6', '2.7', '3.0', '3.1', '3.2']
+        ruby: ['2.4', '2.5', '2.6', '2.7', '3.0', '3.1', '3.2', '3.3', '3.4', '4.0']
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-      - run: gem install bundler:2.3.26
-      - uses: actions/cache@v3
+          bundler-cache: true
+      - uses: actions/cache@v5
         with:
           path: vendor/bundle
           key: ${{ runner.os }}-ruby-${{ matrix.ruby }}-gems-${{ hashFiles('**/Gemfile.lock') }}

data/.github/workflows/codeql-analysis.yml

@@ -38,11 +38,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -53,7 +53,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v4
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -67,4 +67,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v4

data/.gitignore

@@ -9,3 +9,5 @@
 
 # rspec failure tracking
 .rspec_status
+
+/Gemfile.lock

data/.rubocop.yml

@@ -1,5 +1,8 @@
+inherit_from: .rubocop_todo.yml
+
 AllCops:
   NewCops: enable
+  TargetRubyVersion: 2.4
 Style/HashSyntax:
   EnforcedShorthandSyntax: never
 Naming/BlockForwarding:

data/.rubocop_todo.yml

@@ -0,0 +1,128 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-01-02 20:06:51 UTC using RuboCop version 1.82.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods.
+# AllowedMethods: enums
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'spec/callable_tree/node/external_spec.rb'
+    - 'spec/callable_tree/node/internal/strategizable_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: AllowedParentClasses.
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/callable_tree/node/root.rb'
+
+# Offense count: 10
+# Configuration parameters: AllowKeywordBlockArguments.
+Lint/UnderscorePrefixedVariableName:
+  Exclude:
+    - 'examples/builder/identity.rb'
+    - 'examples/builder/logging.rb'
+    - 'examples/class/logging.rb'
+    - 'examples/factory/identity.rb'
+    - 'examples/factory/logging.rb'
+
+# Offense count: 8
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/callable_tree/node/builder.rb'
+    - 'lib/callable_tree/node/external/builder.rb'
+    - 'spec/callable_tree/node/builder_spec.rb'
+
+# Offense count: 7
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 25
+
+# Offense count: 38
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 798
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 8
+
+# Offense count: 14
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 45
+
+# Offense count: 8
+# Configuration parameters: ExpectMatchingDefinition, CheckDefinitionPathHierarchy, CheckDefinitionPathHierarchyRoots, Regex, IgnoreExecutableScripts, AllowedAcronyms.
+# CheckDefinitionPathHierarchyRoots: lib, spec, test, src
+# AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
+Naming/FileName:
+  Exclude:
+    - 'Rakefile.rb'
+    - 'examples/builder/external-verbosify.rb'
+    - 'examples/builder/internal-broadcastable.rb'
+    - 'examples/builder/internal-composable.rb'
+    - 'examples/builder/internal-seekable.rb'
+    - 'examples/class/external-verbosify.rb'
+    - 'examples/class/internal-broadcastable.rb'
+    - 'examples/class/internal-composable.rb'
+    - 'examples/class/internal-seekable.rb'
+    - 'examples/factory/external-verbosify.rb'
+    - 'examples/factory/internal-broadcastable.rb'
+    - 'examples/factory/internal-composable.rb'
+    - 'examples/factory/internal-seekable.rb'
+
+# Offense count: 1
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'spec/callable_tree/node/builder_spec.rb'
+
+# Offense count: 1
+Style/ClassVars:
+  Exclude:
+    - 'lib/callable_tree/node/internal/strategizable.rb'
+
+# Offense count: 40
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Enabled: false
+
+# Offense count: 45
+Style/MultilineBlockChain:
+  Exclude:
+    - 'examples/builder/external-verbosify.rb'
+    - 'examples/builder/hooks.rb'
+    - 'examples/builder/identity.rb'
+    - 'examples/builder/internal-seekable.rb'
+    - 'examples/builder/logging.rb'
+    - 'examples/class/hooks.rb'
+    - 'examples/class/logging.rb'
+    - 'examples/factory/hooks.rb'
+    - 'examples/factory/logging.rb'
+    - 'lib/callable_tree/node/internal/strategy/seek.rb'
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods.
+# AllowedMethods: respond_to_missing?
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/callable_tree/node/builder.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 210

data/.ruby-version

@@ -1 +1 @@
-3.2.0
+4.0.0

data/AGENTS.md

@@ -0,0 +1,56 @@
+# Agent Guide for callable_tree
+
+## Project Overview
+`callable_tree` is a Ruby gem for building tree-structured executable workflows. It provides a framework for organizing complex logic into a tree of callable nodes, offering a structured, modular alternative to complex conditional logic. Nodes are matched against input (`match?`) and executed (`call`) in a chain from root to leaf.
+
+## Core Concepts
+- **Nodes**:
+  - `Root`: The entry point of the tree.
+  - `Internal`: Branch nodes that contain child nodes. Strategies:
+    - `seekable`: Calls the first matching child (like `case`).
+    - `broadcastable`: Calls all matching children.
+    - `composable`: Pipes output from one child to the next.
+  - `External`: Leaf nodes that perform actual work.
+- **Traversal**:
+  - `match?(input)`: Determines if a node should process the input.
+  - `call(input)`: Executes the node logic.
+  - `terminate?`: Controls when to stop traversal (mostly for `seekable`).
+- **Hooks** (`hookable`):
+  - Enable instrumentation (logging, debugging) by adding callbacks.
+  - `before_matcher!`, `after_matcher!`: Hook into matching phase.
+  - `before_caller!`, `after_caller!`: Hook into call phase.
+  - `before_terminator!`, `after_terminator!`: Hook into termination phase.
+- **Verbosify** (`verbosify`):
+  - Wraps External node output in `CallableTree::Node::External::Output` struct.
+  - Provides `value`, `options`, and `routes` (call path) for debugging.
+
+## Directory Structure
+- `lib/`: Source code.
+- `spec/`: RSpec tests.
+- `examples/`: Usage examples.
+  - `examples/class/`: Class-style node definitions (using `include CallableTree::Node::*`).
+  - `examples/builder/`: Builder-style definitions (using `Builder.new.matcher { }.caller { }.build`).
+  - `examples/factory/`: Factory-style definitions (using `External.create(caller: ...)` or `External::Pod.new`).
+  - `examples/docs/`: Sample data files (JSON, XML) used by examples.
+
+## Development
+- **Tool Version Manager**: mise
+- **Language**: Ruby (>= 2.4.0)
+- **Dependency Management**: Bundler
+  - Execute `bundle` commands via `mise` (e.g., `mise x -- bundle exec ...`)
+- **Testing**: RSpec
+  - Run all tests: `mise x -- bundle exec rake` or `mise x -- bundle exec rake spec`
+- **Commit Messages**: Follow the convention in [CONTRIBUTING.md](CONTRIBUTING.md).
+- **Linter/Formatter**:
+  - Uses `rubocop`.
+  - Run checks: `mise x -- bundle exec rubocop`
+- **CI/CD**:
+  - GitHub Actions: `.github/workflows/build.yml` runs tests and linter on push/PR.
+- **Release Process**:
+  - Version: `lib/callable_tree/version.rb`
+  - Tagging: Create a git tag (e.g., `v0.4.0`) and push.
+
+## Architecture
+- **Composite Pattern**: Used for `Internal` nodes to treat individual objects and compositions uniformly.
+- **Builder Pattern**: `CallableTree::Node::Internal::Builder` and `CallableTree::Node::External::Builder` provide a fluent interface for constructing complex trees.
+- **Pod Pattern**: `CallableTree::Node::Internal::Pod` and `CallableTree::Node::External::Pod` enable inline node creation via `External.create` / `Internal.create` factory methods with proc-based behaviors.

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.3.12] - 2026-01-07
+
+- Add Factory style for inline node creation as a third option alongside Class and Builder styles.
+  - `CallableTree::Node::External.create` and `CallableTree::Node::Internal.create` factory methods
+  - Supports `hookable: true` option for Hooks (before/around/after callbacks)
+  - See `examples/factory/*.rb` for details.
+
+## [0.3.11] - 2026-01-03
+
+- Fix a typo in `Strategizable#strategize` where it incorrectly called `strategy!` instead of `strategize!`.`
+
 ## [0.3.10] - 2022-12-30
 
 - Change `CallableTree::Node::Internal#broadcastable` to take `matchable` keyword parameter as boolean. It defaults to `true`, which is the same behavior as before.

data/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Commit Message Convention
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## Header
+
+The header is mandatory and must not exceed 72 characters.
+
+### Type
+
+Must be one of the following:
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation only changes
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **perf**: A code change that improves performance
+- **test**: Adding missing tests or correcting existing tests
+- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+- **chore**: Other changes that don't modify src or test files
+- **revert**: Reverts a previous commit
+
+### Scope
+
+The scope is optional and should be a phrase describing the section of the codebase affected.
+
+### Subject
+
+The subject contains a succinct description of the change:
+
+- Use the imperative, present tense: "change" not "changed" nor "changes"
+- Don't capitalize the first letter
+- No dot (.) at the end
+
+## Body
+
+The body is optional and should include the motivation for the change and contrast this with previous behavior.
+
+## Footer
+
+The footer is optional and should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit closes.
+
+## Branch Naming
+
+We generally use the following prefixes for branch names:
+
+- `feature/`: New features (e.g., `feature/login-screen`)
+- `fix/`: Bug fixes (e.g., `fix/memory-leak`)
+- `docs/`: Documentation only changes (e.g., `docs/update-readme`)
+- `style/`: Changes that do not affect the meaning of the code (e.g., `style/rubocop-fixes`)
+- `refactor/`: Code changes that neither fix a bug nor add a feature (e.g., `refactor/extract-method`)
+- `test/`: Adding or correcting tests (e.g., `test/add-rspec-cases`)
+- `chore/`: Changes to the build process or auxiliary tools and libraries (e.g., `chore/update-gems`)
+
+Use kebab-case for the branch name (e.g., `feature/my-new-feature`).
+

data/Gemfile

@@ -5,6 +5,8 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in callable_tree.gemspec
 gemspec
 
-gem 'rake', '~> 13.0'
+gem 'rake', '~> 13.3'
 
-gem 'rspec', '~> 3.0'
+gem 'rspec', '~> 3.13'
+
+gem 'rubocop', require: false if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('4.0')