branchout 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8562cdf0b59fc28be9b1c811b63727f18fab5b7d2bd54cd24825886ef359eefe
+  data.tar.gz: d31f8699dba5f5541b217e7a80a634d1b13980e95da99976e74fbefd48233dbf
+SHA512:
+  metadata.gz: d258d697f2f20e02c160d6998c0f6ce8ee5221b0e2b4aeea89a74a3b6289fe3881d185c4be7f2b8a999a9ac0f0b10a83eb9eae45e9b8b89f4b3a8ac870e69d9d
+  data.tar.gz: 37c6415b5be529624d65a394d9a676b77ec74dcd5018f0ee6112e0ff6ebf1fdc66eee12df77c9605d5d8a179c9c0d12877fe712e65dde6de70f285a701b3f422

data/AGENTS.md

@@ -0,0 +1,38 @@
+# Developing branchout
+
+The usage loop for a coding agent that is driving branchout lives in [skills/branchout/SKILL.md](skills/branchout/SKILL.md). Copy or symlink that directory into the agent's skills folder when using the tool from another project (see the README). This file is for changing this repository.
+
+## Setup
+
+Ruby 3.3 or newer. `explore` uses the standard library. Development gems are minitest, rspec, and hegeltest. hegeltest needs Ruby 3.4 or newer, so on Ruby 3.3 leave its group out:
+
+```sh
+bundle install
+BUNDLE_WITHOUT=property bundle install   # Ruby 3.3
+```
+
+## Tests
+
+```sh
+ruby test/run_all.rb
+bundle exec rspec spec/generated
+```
+
+In a checkout whose gems live only in the bundle, as in CI, run both under `bundle exec`. On Ruby 4.0 set `BUNDLE_VERSION=system` for `bundle install` and `bundle exec`. Otherwise bundler switches to the 2.6.9 that `Gemfile.lock` names, that bundler warns about Ruby 4.0's RubyGems constants in every Ruby the tests start, and the CLI tests that require an empty stderr fail. `.github/workflows/ci.yml` runs both on Ruby 3.3 (without the property group) and 4.0, and on 4.0 runs `CLITest` once more with `BRANCHOUT_TEST_SPAWN=1`.
+
+`test/run_all.rb` loads `test/test_*.rb` and `test/generated/*_test.rb`. Coverage is process-global, so each CLI test runs branchout in a process of its own: `test/support/cli.rb` forks it from a server that loaded branchout before any test ran, which saves the Ruby and prism boot of each run. Where fork does not exist, or with `BRANCHOUT_TEST_SPAWN=1`, each run spawns `bin/branchout` instead. `test/test_properties.rb` holds the hegeltest properties of the pure parts and of report determinism. On Ruby 3.3 it reports one skip.
+
+`test/generated/` and `spec/generated/` are checked-in characterization tests for `examples/`. Regenerate one by re-running `explore` with `--strategy inputs --random 0 --seed 1` and `--emit-tests` pointed at `test/generated/<name>_test.rb` (`--format minitest`) or `spec/generated/<name>_spec.rb` (`--format rspec`). `test/test_examples.rb` checks `reports/<name>.*`, `test/generated/`, and `spec/generated/` against a fresh run of each example. Regenerate them together when output changes.
+
+`test/test_readme.rb` runs the `sh` blocks of the README's "Try it without an app" in one empty folder and compares each with the output block after it. It runs the Rails Quick start only when `BRANCHOUT_README_RAILS_APP` names a Rails app with RSpec, factory_bot, and the Quick start's `Loan#approve`, its gems installed and branchout not in its Gemfile: it copies the app, adds the Gemfile lines with this checkout as the gem's path, writes each spec file block when the steps reach it, and runs each `sh` block. The sample app the Quick start quotes holds `Borrower` and `Loan` models, a factory for each, `spec/rails_helper.rb`, and `spec/models/loan_spec.rb`, on activerecord, railties, sqlite3, factory_bot_rails, and rspec-rails. When the report or an emitted spec changes, rerun those steps and paste their output into both READMEs.
+
+## Invariants
+
+- Do not add an LLM client, an API key, or an external command. The agent stays outside the process.
+- The same inputs, flags, and CRuby must produce the same stdout. No timestamps. Paths are relative to the working directory.
+- The tool does not rewrite an inputs file.
+- Do not put secrets in inputs, fixtures, or reports.
+
+## Releasing
+
+A release, a gem push, and a change of the repository's visibility are the owner's to run. A commit that changes `lib/branchout/version.rb` and lands on `main` starts `.github/workflows/release.yml`, and [docs/releasing.md](docs/releasing.md) has the steps. Every change that a gem user can notice adds a line under `## [Unreleased]` in `CHANGELOG.md`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 meganemura
+
+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.