railsmith 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b7d121f9233f121988b7811ac803943a3d2d784ccf018e31ecb1dd681747c632
+  data.tar.gz: 0d8b3debcd71cd67bec213d7614528d61584b45f1a380b35536d5e738d848871
+SHA512:
+  metadata.gz: 6c82716d751374815ebe15f4fdc0763c3ff79dbf58b1985d9d8a2bbaa70e19fe010174563401fc23c811533009ad054c8d0de7130502ce80a10e2346f309d6f7
+  data.tar.gz: 97bf97006557c7fa4e6f5c19d83d47b81c48dd751bee5d66a6d812ee5072edeeaf5a3e95b8b09ec42bc3ad778e1fae3b886c93c63cbd676240cdfef96b413786

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.8

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to Railsmith are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.0] — 2026-03-29
+
+First stable release. Public DSL and result contract are now frozen.
+
+### Added
+
+#### Core
+- `Railsmith::Result` — immutable value object with `success?`, `failure?`, `value`, `error`, `code`, `meta`, and `to_h`.
+- `Railsmith::Errors` — normalized error builders: `validation_error`, `not_found`, `conflict`, `unauthorized`, `unexpected`.
+- `Railsmith::BaseService` — lifecycle entrypoint `call(action:, params:, context:)` with deterministic hook ordering and subclass override points.
+
+#### CRUD
+- Default `create`, `update`, and `destroy` actions on any service that declares `model(ModelClass)`.
+- Automatic exception mapping: `ActiveRecord::RecordNotFound` → `not_found`, `ActiveRecord::RecordInvalid` → `validation_error`, `ActiveRecord::RecordNotUnique` → `conflict`.
+- Safe record lookup helper with consistent not-found failure shape.
+
+#### Bulk Operations
+- `bulk_create`, `bulk_update`, `bulk_destroy` on model-backed services.
+- Per-item result aggregation with batch `summary` (`total`, `success_count`, `failure_count`, `all_succeeded`).
+- Transaction modes: `:all_or_nothing` (rollback on any failure) and `:best_effort` (commit successful items).
+- Configurable batch size limit.
+
+#### Domain Context
+- `Railsmith::DomainContext` — carries `current_domain` and arbitrary `meta` through a call chain.
+- `service_domain :name` declaration on `BaseService` subclasses.
+- Context propagation guard: emits `cross_domain.warning.railsmith` ActiveSupport instrumentation event when context domain differs from service domain.
+- Allowlist configuration for approved cross-domain crossings.
+- `on_cross_domain_violation` callback hook for custom handling.
+
+#### Architecture Checks
+- `Railsmith::ArchChecks::DirectModelAccessChecker` — static analysis for controllers that access models directly.
+- `Railsmith::ArchChecks::MissingServiceUsageChecker` — flags controller actions that touch models without calling a service-style entrypoint.
+- Text and JSON report formatters (`Railsmith::ArchReport`).
+- `Railsmith::ArchChecks::Cli` — Ruby API for the same scan as `railsmith:arch_check`, with optional `env:`, `output:`, and `warn_proc:` for tests and embedding.
+- `rake railsmith:arch_check` task with `RAILSMITH_PATHS`, `RAILSMITH_FORMAT`, and `RAILSMITH_FAIL_ON_ARCH_VIOLATIONS` environment variable support; the task delegates to `Railsmith::ArchChecks::Cli.run` (same report shape and exit semantics for callers).
+
+#### Generators
+- `railsmith:install` — creates `config/initializers/railsmith.rb` and `app/services/` directory tree.
+- `railsmith:domain NAME` — scaffolds a domain module skeleton with conventional subdirectories.
+- `railsmith:model_service MODEL` — scaffolds a `BaseService` subclass, namespace-aware with `--domain` flag.
+- `railsmith:operation NAME` — scaffolds a plain-Ruby operation with `call` entrypoint returning `Railsmith::Result`.
+
+#### Configuration
+- `Railsmith.configure` block with: `warn_on_cross_domain_calls`, `strict_mode`, `on_cross_domain_violation`, `cross_domain_allowlist`, `fail_on_arch_violations`.
+
+#### Documentation
+- [Quickstart](docs/quickstart.md)
+- [Cookbook](docs/cookbook.md) — CRUD, bulk, domain context, error mapping, observability
+- [Legacy Adoption Guide](docs/legacy-adoption.md) — incremental migration strategy
+
+---
+
+## [0.1.0] — pre-release
+
+Internal bootstrap release. Gem skeleton, CI baseline, and initial service scaffolding. Not intended for production use.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 samaswin
+
+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/MIGRATION.md

@@ -0,0 +1,156 @@
+# Migration Guide
+
+## Upgrading from 0.x (pre-release) to 1.0.0
+
+Railsmith 1.0.0 is the first stable release. If you were using the 0.x development version, the changes below are required before upgrading.
+
+---
+
+### Requirements
+
+| | 0.x | 1.0.0 |
+|---|---|---|
+| Ruby | >= 3.2.0 | >= 3.2.0 |
+| Rails | 7.0–8.x | 7.0–8.x |
+
+No changes to minimum runtime requirements.
+
+---
+
+### Result contract — now frozen
+
+The `Railsmith::Result` interface is stable and will not change in any 1.x release.
+
+**No action required** if you are already using the documented API (`success?`, `failure?`, `value`, `error`, `code`, `meta`, `to_h`).
+
+If you were accessing any internal instance variables directly (e.g., `result.instance_variable_get(:@data)`), switch to the public API before upgrading.
+
+---
+
+### Error builders — keyword arguments required
+
+All `Railsmith::Errors` factory methods now require keyword arguments.
+
+```ruby
+# Before (0.x, positional — no longer accepted)
+Railsmith::Errors.not_found("User not found", { model: "User" })
+
+# After (1.0.0)
+Railsmith::Errors.not_found(message: "User not found", details: { model: "User" })
+```
+
+Both `message:` and `details:` are optional but must be passed as keywords when provided.
+
+---
+
+### `BaseService.call` — `context:` is now required
+
+In 0.x, `context:` was optional and defaulted to `{}` silently. In 1.0.0, omitting `context:` raises `ArgumentError`.
+
+```ruby
+# Before (0.x — context omitted)
+MyService.call(action: :create, params: { ... })
+
+# After (1.0.0 — context required)
+MyService.call(action: :create, params: { ... }, context: {})
+```
+
+Pass `context: {}` at minimum. Pass a `Railsmith::DomainContext` hash when using domain boundaries.
+
+---
+
+### Cross-domain warnings — ActiveSupport instrumentation only
+
+In 0.x, cross-domain violations could be configured to write directly to `Rails.logger`. In 1.0.0, all violation events are emitted exclusively via ActiveSupport Instrumentation (`cross_domain.warning.railsmith`). Wire up your own subscriber if you need log output:
+
+```ruby
+# config/initializers/railsmith.rb
+ActiveSupport::Notifications.subscribe("cross_domain.warning.railsmith") do |_name, _start, _finish, _id, payload|
+  Rails.logger.warn("[Railsmith] cross-domain: #{payload.inspect}")
+end
+```
+
+The `on_cross_domain_violation` config callback still fires and is the recommended place for custom handling.
+
+---
+
+### Generator output paths — finalized
+
+Domain-scoped services are now always generated under `app/domains/<domain>/services/`. If you used the generator during 0.x development and accepted a different default path, move the files and update `require` paths accordingly.
+
+| Generator | Output path (1.0.0) |
+|-----------|---------------------|
+| `railsmith:model_service User` | `app/services/operations/user_service.rb` |
+| `railsmith:model_service Billing::Invoice --domain=Billing` | `app/domains/billing/services/invoice_service.rb` |
+| `railsmith:operation Billing::Invoices::Create` | `app/domains/billing/operations/invoices/create.rb` |
+
+---
+
+### Initializer — new configuration keys
+
+Add any missing keys to `config/initializers/railsmith.rb`. All keys have safe defaults so omitting them will not raise, but explicit configuration is recommended.
+
+```ruby
+Railsmith.configure do |config|
+  config.warn_on_cross_domain_calls = true   # default: true
+  config.strict_mode = false                  # default: false (reserved for v1.2)
+  config.fail_on_arch_violations = false      # default: false
+  config.cross_domain_allowlist = []          # default: []
+  config.on_cross_domain_violation = nil      # default: nil (no-op)
+end
+```
+
+---
+
+### Bulk operations — transaction mode default
+
+The default `transaction_mode` for bulk operations changed from `:best_effort` in 0.x to `:all_or_nothing` in 1.0.0.
+
+If you rely on partial-success behavior, explicitly pass `transaction_mode: :best_effort`:
+
+```ruby
+MyService.call(
+  action: :bulk_create,
+  params: { items: [...], transaction_mode: :best_effort },
+  context: {}
+)
+```
+
+---
+
+### Upgrade steps
+
+1. Update `Gemfile`: `gem "railsmith", "~> 1.0"`
+2. Run `bundle install`.
+3. Run `bundle exec rspec` — fix any `ArgumentError` on `call` (add `context: {}`).
+4. Search for positional `Railsmith::Errors.*` calls and convert to keywords.
+5. Review initializer against the full key list above.
+6. Run `rake railsmith:arch_check` as a smoke test.
+7. Deploy.
+
+---
+
+## Embedding architecture checks from Ruby
+
+You do not need this section for a normal upgrade. The `railsmith:arch_check` Rake task behaves the same from the shell (`RAILSMITH_PATHS`, `RAILSMITH_FORMAT`, `RAILSMITH_FAIL_ON_ARCH_VIOLATIONS`, and `Railsmith.configure { |c| c.fail_on_arch_violations }`).
+
+If you maintain custom Rake tasks, CI scripts in Ruby, or tests that should run the same scan without shelling out, call the library entrypoint:
+
+```ruby
+require "railsmith/arch_checks"
+
+status = Railsmith::ArchChecks::Cli.run
+# 0 — success or warn-only; 1 — fail-on enabled and violations present
+
+# Optional: isolated env, capture output, or custom warnings
+# require "stringio"
+# out = StringIO.new
+# warnings = []
+# status = Railsmith::ArchChecks::Cli.run(
+#   env: { "RAILSMITH_PATHS" => "app/controllers", "RAILSMITH_FORMAT" => "text" },
+#   output: out,
+#   warn_proc: ->(message) { warnings << message }
+# )
+```
+
+Replace `rake railsmith:arch_check` with `Cli.run` only when you explicitly need an in-process API; the task remains the supported default for apps.

data/README.md

@@ -0,0 +1,249 @@
+# Railsmith
+
+Railsmith is a service-layer gem for Rails. It standardizes domain-oriented service boundaries with sensible defaults for CRUD operations, bulk operations, result handling, and cross-domain enforcement.
+
+**Requirements**: Ruby >= 3.2.0, Rails 7.0–8.x
+
+---
+
+## Installation
+
+```ruby
+# Gemfile
+gem "railsmith"
+```
+
+```bash
+bundle install
+rails generate railsmith:install
+```
+
+The install generator creates `config/initializers/railsmith.rb` and the `app/services/` directory tree.
+
+---
+
+## Quick Start
+
+Generate a service for a model:
+
+```bash
+rails generate railsmith:model_service User
+```
+
+Call it:
+
+```ruby
+result = Operations::UserService.call(
+  action: :create,
+  params: { attributes: { name: "Alice", email: "alice@example.com" } },
+  context: {}
+)
+
+if result.success?
+  puts result.value.id
+else
+  puts result.error.message   # => "Validation failed"
+  puts result.error.details   # => { errors: { email: ["is invalid"] } }
+end
+```
+
+See [docs/quickstart.md](docs/quickstart.md) for a full walkthrough.
+
+---
+
+## Result Contract
+
+Every service call returns a `Railsmith::Result`. You never rescue exceptions from service calls.
+
+```ruby
+# Success
+result = Railsmith::Result.success(value: { id: 123 }, meta: { request_id: "abc" })
+result.success?  # => true
+result.value     # => { id: 123 }
+result.meta      # => { request_id: "abc" }
+result.to_h      # => { success: true, value: { id: 123 }, meta: { request_id: "abc" } }
+
+# Failure
+error  = Railsmith::Errors.not_found(message: "User not found", details: { model: "User", id: 1 })
+result = Railsmith::Result.failure(error:)
+result.failure?        # => true
+result.code            # => "not_found"
+result.error.to_h      # => { code: "not_found", message: "User not found", details: { ... } }
+```
+
+---
+
+## Generators
+
+| Command | Output |
+|---------|--------|
+| `rails g railsmith:install` | Initializer + service directories |
+| `rails g railsmith:domain Billing` | `app/domains/billing.rb` + subdirectories |
+| `rails g railsmith:model_service User` | `app/services/operations/user_service.rb` |
+| `rails g railsmith:model_service Billing::Invoice --domain=Billing` | `app/domains/billing/services/invoice_service.rb` |
+| `rails g railsmith:operation Billing::Invoices::Create` | `app/domains/billing/operations/invoices/create.rb` |
+
+---
+
+## CRUD Actions
+
+Services that declare a `model` inherit `create`, `update`, and `destroy` with automatic exception mapping:
+
+```ruby
+module Operations
+  class UserService < Railsmith::BaseService
+    model(User)
+  end
+end
+
+# create
+Operations::UserService.call(action: :create, params: { attributes: { email: "a@b.com" } }, context: {})
+
+# update
+Operations::UserService.call(action: :update, params: { id: 1, attributes: { email: "new@b.com" } }, context: {})
+
+# destroy
+Operations::UserService.call(action: :destroy, params: { id: 1 }, context: {})
+```
+
+Common ActiveRecord exceptions (`RecordNotFound`, `RecordInvalid`, `RecordNotUnique`) are caught and converted to structured failure results automatically.
+
+---
+
+## Bulk Operations
+
+```ruby
+# bulk_create
+Operations::UserService.call(
+  action: :bulk_create,
+  params: {
+    items: [{ name: "Alice", email: "a@b.com" }, { name: "Bob", email: "b@b.com" }],
+    transaction_mode: :best_effort  # or :all_or_nothing
+  },
+  context: {}
+)
+
+# bulk_update
+Operations::UserService.call(
+  action: :bulk_update,
+  params: { items: [{ id: 1, attributes: { name: "Alice Smith" } }] },
+  context: {}
+)
+
+# bulk_destroy
+Operations::UserService.call(
+  action: :bulk_destroy,
+  params: { items: [1, 2, 3] },
+  context: {}
+)
+```
+
+All bulk results include a `summary` (`total`, `success_count`, `failure_count`, `all_succeeded`) and per-item detail. See [docs/cookbook.md](docs/cookbook.md) for the full result shape.
+
+---
+
+## Domain Boundaries
+
+Tag services with a bounded context and track it through all calls:
+
+```bash
+rails generate railsmith:domain Billing
+rails generate railsmith:model_service Billing::Invoice --domain=Billing
+```
+
+```ruby
+module Billing
+  module Services
+    class InvoiceService < Railsmith::BaseService
+      model(Billing::Invoice)
+      service_domain :billing
+    end
+  end
+end
+```
+
+Pass context on every call:
+
+```ruby
+ctx = Railsmith::DomainContext.new(
+  current_domain: :billing,
+  meta: { request_id: "req-abc" }
+).to_h
+
+Billing::Services::InvoiceService.call(action: :create, params: { ... }, context: ctx)
+```
+
+When `current_domain` in the context differs from a service's declared `service_domain`, Railsmith emits a `cross_domain.warning.railsmith` instrumentation event.
+
+Configure enforcement in `config/initializers/railsmith.rb`:
+
+```ruby
+Railsmith.configure do |config|
+  config.warn_on_cross_domain_calls = true   # default
+  config.strict_mode = false
+  config.on_cross_domain_violation = ->(payload) { ... }
+  config.cross_domain_allowlist = [{ from: :catalog, to: :billing }]
+end
+```
+
+---
+
+## Error Types
+
+| Code | Factory |
+|------|---------|
+| `validation_error` | `Railsmith::Errors.validation_error(message:, details:)` |
+| `not_found` | `Railsmith::Errors.not_found(message:, details:)` |
+| `conflict` | `Railsmith::Errors.conflict(message:, details:)` |
+| `unauthorized` | `Railsmith::Errors.unauthorized(message:, details:)` |
+| `unexpected` | `Railsmith::Errors.unexpected(message:, details:)` |
+
+---
+
+## Architecture Checks
+
+Detect controllers that access models directly (and related service-layer rules). From the shell:
+
+```bash
+rake railsmith:arch_check
+RAILSMITH_FORMAT=json rake railsmith:arch_check
+RAILSMITH_FAIL_ON_ARCH_VIOLATIONS=true rake railsmith:arch_check
+```
+
+From Ruby (same environment variables and exit codes as the task), after `require "railsmith/arch_checks"`:
+
+```ruby
+Railsmith::ArchChecks::Cli.run # => 0 or 1
+```
+
+See [Migration](MIGRATION.md#embedding-architecture-checks-from-ruby) for optional `env:`, `output:`, and `warn_proc:` arguments.
+
+---
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md) — install, generate, first call
+- [Cookbook](docs/cookbook.md) — CRUD, bulk, domain context, error mapping, observability
+- [Legacy Adoption Guide](docs/legacy-adoption.md) — incremental migration strategy
+
+---
+
+## Development
+
+```bash
+bin/setup       # install dependencies
+bundle exec rake spec   # run tests
+bin/console     # interactive prompt
+```
+
+To install locally: `bundle exec rake install`.
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome at [github.com/samaswin/railsmith](https://github.com/samaswin/railsmith).
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+load File.expand_path("lib/tasks/railsmith.rake", __dir__)
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]