|
1 | 1 | # CLAUDE.md |
2 | 2 |
|
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 3 | +Ruby gem for encapsulating business logic into processes, with Rails integration, input validation, dependency injection, and observability. |
4 | 4 |
|
5 | | -## Project Overview |
6 | | - |
7 | | -`solid-process` is a Ruby gem for encapsulating business logic into manageable processes. It integrates with Rails and provides input validation, dependency injection, and observability features. |
8 | | - |
9 | | -## Documentation |
10 | | - |
11 | | -- **[docs/REFERENCE.md](docs/REFERENCE.md)** — Comprehensive guide covering every feature with detailed examples. Point AI coding agents here. |
12 | | -- **[docs/overview/](docs/overview/)** — Quick overview guides (010–100) for each topic. |
13 | | - |
14 | | -### Back-to-Top Anchors |
15 | | - |
16 | | -Both `README.md` and `docs/REFERENCE.md` use back-to-top navigation after each main section. When adding a new numbered section to `REFERENCE.md`: |
17 | | - |
18 | | -1. Add `<p align="right"><a href="#table-of-contents">⬆️ back to top</a></p>` before the `---` that closes the section |
19 | | -2. Update the Table of Contents with the new entry |
20 | | - |
21 | | -### Overview File Structure |
22 | | - |
23 | | -Each file in `docs/overview/` follows this layout: |
24 | | - |
25 | | -1. **Header nav** — `<small>` block with `` `Previous` `` and `` `Next` `` links |
26 | | -2. **`---`** separator |
27 | | -3. **Content** — starts with a `#` title |
28 | | -4. **`---`** separator |
29 | | -5. **Footer nav** — `<small>` block with the same `` `Previous` ``/`` `Next` `` links as the header |
30 | | - |
31 | | -Navigation chain: `010_KEY_CONCEPTS` → `020_BASIC_USAGE` → … → `100_PORTS_AND_ADAPTERS`. The first file's `Previous` links to `../README.md#further-reading`; the last file's `Next` links to `../REFERENCE.md`. |
32 | | - |
33 | | -When adding a new overview file: |
34 | | - |
35 | | -1. Follow the numbered naming convention (e.g., `110_NEW_TOPIC.md`) |
36 | | -2. Add header and footer nav blocks with `---` separators |
37 | | -3. Update the `Previous`/`Next` links in the adjacent files to include the new file |
38 | | - |
39 | | -## Common Commands |
| 5 | +## Commands |
40 | 6 |
|
41 | 7 | ```bash |
42 | | -# Setup (install dependencies: bundle + appraisal) |
43 | | -bin/setup |
44 | | - |
45 | | -# Clean install + full test suite. Useful when switching Ruby versions. |
46 | | -bin/matrix |
| 8 | +bin/setup # Install dependencies (bundle + appraisal) |
| 9 | +bin/rake matrix # Run full test suite |
47 | 10 |
|
48 | | -# Run all tests for current Ruby version |
49 | | -bin/rake matrix |
50 | | - |
51 | | -# Run a single test file |
| 11 | +# Single test file |
52 | 12 | bundle exec appraisal rails-8-1 ruby -Ilib:test test/solid/process/result_test.rb |
53 | 13 |
|
54 | | -# Run a specific test by name |
| 14 | +# Single test by name (append -n test_method_name) |
55 | 15 | bundle exec appraisal rails-8-1 ruby -Ilib:test test/solid/process/result_test.rb -n test_method_name |
56 | | - |
57 | | -# Interactive console |
58 | | -bin/console |
59 | 16 | ``` |
60 | 17 |
|
61 | 18 | ## Lint |
62 | 19 |
|
63 | | -**Ensure lint is green before committing.** |
64 | | - |
65 | | -```bash |
66 | | -# Check for style violations (Ruby 3.4+) |
67 | | -bin/rake standard |
68 | | - |
69 | | -# Auto-fix style violations |
70 | | -bin/rake standard:fix |
71 | | -``` |
72 | | - |
73 | | -### Release Checklist |
74 | | - |
75 | | -When `lib/solid/process/version.rb` is changed: |
76 | | -1. Verify `CHANGELOG.md` has a matching version entry (e.g., `## [0.5.0] - YYYY-MM-DD`) |
77 | | -2. Verify `README.md` compatibility matrix is up-to-date if Ruby/Rails support changed |
78 | | - |
79 | | -### Ruby/Rails Version Alignment |
80 | | - |
81 | | -When modifying Ruby or Rails version support, ensure these files stay aligned: |
82 | | - |
83 | | -| File | Purpose | |
84 | | -|------|---------| |
85 | | -| `Appraisals` | Source of truth for gem dependencies per Rails version | |
86 | | -| `Rakefile` | Local `rake matrix` task conditions | |
87 | | -| `.github/workflows/main.yml` | CI matrix and step conditions | |
88 | | -| `README.md` | Compatibility matrix table | |
89 | | - |
90 | | -**Key checks:** |
91 | | -1. Ruby version conditions must match across `Appraisals`, `Rakefile`, and CI |
92 | | -2. CI string values (e.g., `'head'`) need explicit checks since numeric comparisons won't match them |
93 | | -3. README table must reflect the actual tested combinations |
94 | | -4. Ruby `head` should only run against Rails edge (not stable Rails versions) |
95 | | - |
96 | | -## Switching Ruby Versions |
97 | | - |
98 | | -### ASDF |
99 | | - |
100 | | -```bash |
101 | | -asdf list ruby # List installed Ruby versions |
102 | | -asdf set ruby 4.0.1 # Ruby 4.x |
103 | | -``` |
104 | | - |
105 | | -## Tests |
106 | | - |
107 | | -Always test on multiple Ruby versions when fixing compatibility issues. |
108 | | - |
109 | | -### Support Files |
110 | | - |
111 | | -Test fixtures in `test/support/` follow numbered naming (e.g., `051_user_token_creation.rb`) for load order. These define sample processes used across multiple tests. |
112 | | - |
113 | | -### Fix Library Code, Not Tests |
114 | | - |
115 | | -When tests fail due to Ruby version differences: |
116 | | -1. First check if the **library code** can be updated to normalize behavior |
117 | | -2. Only modify tests if the library fix isn't possible |
118 | | - |
119 | | -### Available Rails versions (see Rakefile for full list) |
120 | | -```sh |
121 | | -bundle exec appraisal rails-6-0 rake test # Ruby 2.7, 3.0 |
122 | | -bundle exec appraisal rails-6-1 rake test # Ruby 2.7, 3.0 |
123 | | -bundle exec appraisal rails-7-0 rake test # Ruby 3.0, 3.1, 3.2, 3.3 |
124 | | -bundle exec appraisal rails-7-1 rake test # Ruby 3.0, 3.1, 3.2, 3.3 |
125 | | -bundle exec appraisal rails-7-2 rake test # Ruby 3.1, 3.2, 3.3, 3.4 |
126 | | -bundle exec appraisal rails-8-0 rake test # Ruby 3.2, 3.3, 3.4 |
127 | | -bundle exec appraisal rails-8-1 rake test # Ruby 3.3, 3.4, 4.x |
128 | | -``` |
129 | | - |
130 | | -## Architecture |
131 | | - |
132 | | -### Core Classes |
133 | | - |
134 | | -- **Solid::Process** (`lib/solid/process.rb`) - Base class for business processes. Requires `input` block and `call` method. Returns `Success` or `Failure` outputs. |
| 20 | +**Run `bin/rake standard` before committing.** Auto-fix with `bin/rake standard:fix`. Also ensure changes follow the conventions linked below. |
135 | 21 |
|
136 | | -- **Solid::Model** (`lib/solid/model.rb`) - ActiveModel-based concern providing attributes, validations, and callbacks. |
| 22 | +## References |
137 | 23 |
|
138 | | -- **Solid::Input** (`lib/solid/input.rb`) - Input validation class, includes Solid::Model. |
| 24 | +- **[docs/REFERENCE.md](docs/REFERENCE.md)** — Full feature guide with detailed examples |
| 25 | +- **[docs/overview/](docs/overview/)** — Quick overview guides (010–100) |
139 | 26 |
|
140 | | -- **Solid::Value** (`lib/solid/value.rb`) - Immutable value objects. |
| 27 | +## Conventions |
141 | 28 |
|
142 | | -- **Solid::Output** (`lib/solid/output.rb`) - Wraps solid-result gem for Success/Failure return types. |
| 29 | +- **[Testing](.claude/docs/testing.md)** — Test fixtures, multi-version testing, Rails version matrix |
| 30 | +- **[Documentation](.claude/docs/documentation.md)** — Back-to-top anchors, overview file structure |
| 31 | +- **[Release & Versioning](.claude/docs/release-and-versioning.md)** — Release checklist, Ruby/Rails version alignment |
0 commit comments