seams 0.1.0

data/lib/generators/seams/core/templates/spec/concerns/auditable_spec.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Core::Auditable do
+  # Stub a named ActiveRecord class. The polymorphic `auditable_type`
+  # column needs `self.class.name` to be non-nil; `Class.new(...)`
+  # returns an anonymous class whose `.name` is nil, which breaks the
+  # `dependent: :nullify` cleanup on destroy.
+  before do
+    stub_const("Article", Class.new(ActiveRecord::Base) {
+      self.table_name = "articles"
+      include Core::Auditable
+    })
+  end
+
+  let(:model_class) { Article }
+
+  it "creates an audit log on create" do
+    expect { model_class.create!(title: "Hi") }
+      .to change(Core::AuditLog, :count).by(1)
+  end
+
+  it "records the changed attributes on update" do
+    article = model_class.create!(title: "Hi")
+    expect { article.update!(title: "Bye") }
+      .to change(Core::AuditLog, :count).by(1)
+
+    last = Core::AuditLog.recent.first
+    expect(last.action).to eq("update")
+    expect(last.payload).to include("title" => "Bye")
+  end
+
+  it "creates an audit log on destroy" do
+    article = model_class.create!(title: "Hi")
+    expect { article.destroy }
+      .to change(Core::AuditLog, :count).by(1)
+  end
+end

data/lib/generators/seams/core/templates/spec/concerns/sluggable_spec.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Core::Sluggable do
+  let(:model_class) do
+    Class.new(ActiveRecord::Base) do
+      self.table_name = "teams"
+      include Core::Sluggable
+      sluggable_from :name
+    end
+  end
+
+  it "auto-assigns a slug from the source attribute" do
+    record = model_class.create!(name: "Acme Corp!")
+    expect(record.slug).to eq("acme-corp")
+  end
+
+  it "appends a numeric suffix on collision" do
+    model_class.create!(name: "Acme")
+    second = model_class.create!(name: "Acme")
+    expect(second.slug).to eq("acme-2")
+  end
+
+  it "respects an explicitly-set slug" do
+    record = model_class.create!(name: "Whatever", slug: "my-custom")
+    expect(record.slug).to eq("my-custom")
+  end
+end

data/lib/generators/seams/core/templates/spec/models/audit_log_spec.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Core::AuditLog do
+  it "rejects unknown actions" do
+    log = described_class.new(action: "made_up", auditable_type: "Article", auditable_id: 1)
+    expect(log).not_to be_valid
+  end
+
+  describe ".for" do
+    it "filters audit logs to a specific record" do
+      article = double(class: double(name: "Article"), id: "7")
+      described_class.create!(action: "create", auditable_type: "Article", auditable_id: "7")
+      described_class.create!(action: "create", auditable_type: "Article", auditable_id: "8")
+
+      # auditable_id is string-typed (polymorphic over both bigint-PK
+      # and UUID-PK auditables — see the migration's comment).
+      expect(described_class.for(article).pluck(:auditable_id)).to eq(["7"])
+    end
+  end
+end

data/lib/generators/seams/core/templates/spec/runtime/boot_spec.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+RSpec.describe "Core engine boot", type: :integration do
+  it "loads the engine" do
+    expect(defined?(Core::Engine)).to eq("constant")
+  end
+
+  it "registers record.audited.core in Seams::EventRegistry on boot" do
+    expect(Seams::EventRegistry.registered?("record.audited.core")).to be(true)
+  end
+
+  it "exposes the canonical concerns as constants" do
+    expect(defined?(Core::Auditable)).to            eq("constant")
+    expect(defined?(Core::SoftDeletable)).to        eq("constant")
+    expect(defined?(Core::Sluggable)).to            eq("constant")
+    expect(defined?(Core::TenantScoped)).to         eq("constant")
+    expect(defined?(Core::HasCurrentAttributes)).to eq("constant")
+  end
+
+  it "creates the core_audit_logs table from the dummy schema" do
+    expect(ActiveRecord::Base.connection.table_exists?(:core_audit_logs)).to be(true)
+  end
+end

data/lib/generators/seams/core/templates/spec/validators/email_format_validator_spec.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Core::EmailFormatValidator do
+  let(:model_class) do
+    Class.new do
+      include ActiveModel::Validations
+      attr_accessor :email
+      validates :email, "core/email_format": true
+    end
+  end
+
+  it "accepts a normal email" do
+    expect(model_class.new.tap { |o| o.email = "x@y.com" }).to be_valid
+  end
+
+  it "rejects an email without @" do
+    expect(model_class.new.tap { |o| o.email = "no-at" }).not_to be_valid
+  end
+
+  it "rejects emails with consecutive dots" do
+    expect(model_class.new.tap { |o| o.email = "x..y@z.com" }).not_to be_valid
+  end
+
+  it "rejects emails without a TLD" do
+    expect(model_class.new.tap { |o| o.email = "x@y" }).not_to be_valid
+  end
+end

data/lib/generators/seams/engine/engine_generator.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rails/generators"
+require "seams"
+require "seams/generators/host_injector"
+require "seams/generators/sibling_rubocop_writer"
+require "seams/generators/dummy_app_writer"
+
+module Seams
+  module Generators
+    # Generates a new Rails engine under engines/<name>/, fully isolated
+    # via `isolate_namespace`, with the Seams boundary cops pre-wired in
+    # the engine's own .rubocop.yml. After generating the new engine,
+    # the cop config of every existing sibling engine is updated so
+    # boundary enforcement covers the new engine without manual edits.
+    #
+    # Run with: bin/rails generate seams:engine billing
+    class EngineGenerator < Rails::Generators::NamedBase
+      include Seams::Generators::HostInjector
+
+      source_root File.expand_path("templates", __dir__)
+
+      NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+      def validate_name
+        unless NAME_PATTERN.match?(name)
+          raise Seams::GeneratorError,
+                "Engine name #{name.inspect} must be lowercase letters, digits, " \
+                "and underscores, starting with a letter."
+        end
+
+        engine_root = File.join(destination_root, "engines", name)
+        return unless File.exist?(engine_root)
+
+        raise Seams::GeneratorError, "Engine #{name.inspect} already exists at #{engine_root}"
+      end
+
+      def create_gemspec
+        template "gemspec.tt", "engines/#{name}/#{name}.gemspec"
+      end
+
+      def create_lib
+        template "lib/engine.rb.tt",  "engines/#{name}/lib/#{name}/engine.rb"
+        template "lib/version.rb.tt", "engines/#{name}/lib/#{name}/version.rb"
+        template "lib/root.rb.tt",    "engines/#{name}/lib/#{name}.rb"
+      end
+
+      def create_config
+        template "config/routes.rb.tt", "engines/#{name}/config/routes.rb"
+      end
+
+      def create_app
+        template "app/application_controller.rb.tt",
+                 "engines/#{name}/app/controllers/#{name}/application_controller.rb"
+        # Phase 1.6 — engine-scoped abstract AR base.
+        template "app/application_record.rb.tt",
+                 "engines/#{name}/app/models/#{name}/application_record.rb"
+      end
+
+      # Phase 1.6 — i18n stub + standalone Gemfile + Rakefile so the
+      # engine can be tested in isolation (cd engines/<name> && rake).
+      def create_locales
+        template "config/locales/en.yml.tt",
+                 "engines/#{name}/config/locales/en.yml"
+      end
+
+      def create_engine_gemfile
+        template "Gemfile.tt", "engines/#{name}/Gemfile"
+      end
+
+      def create_engine_rakefile
+        template "Rakefile.tt", "engines/#{name}/Rakefile"
+      end
+
+      def create_rubocop_config
+        template "rubocop.yml.tt", "engines/#{name}/.rubocop.yml"
+      end
+
+      def create_spec_helper
+        template "spec/spec_helper.rb.tt",   "engines/#{name}/spec/spec_helper.rb"
+        template "spec/example_spec.rb.tt",  "engines/#{name}/spec/#{name}_spec.rb"
+      end
+
+      def create_license
+        template "LICENSE.tt", "engines/#{name}/LICENSE"
+      end
+
+      def create_readme
+        template "README.md.tt", "engines/#{name}/README.md"
+      end
+
+      # Phase 1.6 — per-engine dummy app via the shared DummyAppWriter.
+      # Generic engines start with an empty schema; canonical
+      # generators (auth/billing/etc) overwrite this with their own
+      # schema by calling DummyAppWriter.write! again with the right
+      # SCHEMA body. Runs AFTER create_spec_helper so DummyAppWriter's
+      # File.write silently overwrites the lightweight Thor template
+      # rather than tripping a Thor "conflict" prompt.
+      def create_dummy_app
+        Seams::Generators::DummyAppWriter.write!(
+          engine_path: File.join(destination_root, "engines", name),
+          engine_module: module_name,
+          mount_at: "/#{name}",
+          schema: "# generic engine — no schema yet"
+        )
+      end
+
+      def wire_into_host
+        # Mount the engine into the host's routes (idempotent — skips
+        # if the line already exists, so canonical generators that
+        # call this and ALSO mount themselves are safe).
+        host_inject_mount(engine_class: "#{module_name}::Engine", at: "/#{name}")
+
+        # Drop a host-side initializer stub the user can fill in.
+        # Skipped if a canonical generator (or the host) has already
+        # created one.
+        initializer_path = File.join(destination_root, "config/initializers/#{name}.rb")
+        if File.exist?(initializer_path)
+          say "  exist   config/initializers/#{name}.rb (kept)", :blue
+        elsif File.directory?(File.join(destination_root, "config/initializers"))
+          template "host_initializer.rb.tt", "config/initializers/#{name}.rb"
+        end
+      end
+
+      def update_sibling_engines
+        sibling_dirs = sibling_engine_dirs
+        return if sibling_dirs.empty?
+
+        Seams::Generators::SiblingRubocopWriter.rewrite!(
+          engines_root: engines_root,
+          dirs: (sibling_dirs + [name]).sort
+        )
+
+        say "  update  .rubocop.yml of #{sibling_dirs.size} sibling engine(s)", :green
+      end
+
+      def report
+        say ""
+        say "  Engine `#{name}` generated at engines/#{name}/", :green
+        say "  Run its specs with: bin/rails seams:test[#{name}]"
+        say ""
+      end
+
+      private
+
+      def module_name
+        name.split("_").map(&:capitalize).join
+      end
+
+      def engines_root
+        File.join(destination_root, "engines")
+      end
+
+      def sibling_engine_dirs
+        return [] unless Dir.exist?(engines_root)
+
+        Dir.children(engines_root)
+           .select { |child| File.directory?(File.join(engines_root, child)) }
+           .reject { |child| child.start_with?(".") || child == name }
+           .sort
+      end
+    end
+  end
+end

data/lib/generators/seams/engine/templates/Gemfile.tt

@@ -0,0 +1,19 @@
+# Engine-local Gemfile. Mostly redundant in the in-tree layout — the
+# host's Gemfile already loads the engine via path-resolution from
+# seams_engines.rb. This file exists so the engine can ALSO be
+# extracted and bundle-installed standalone (CI matrix run, future
+# gem release, etc.) without rewriting the dependency surface.
+#
+# Keep this file aligned with the engine's gemspec — runtime deps
+# go there, dev/test-only tools go here.
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in <%= name %>.gemspec.
+gemspec
+
+group :development, :test do
+  gem "rspec-rails", "~> 7.1"
+  gem "rubocop",     require: false
+  gem "rubocop-rails", require: false
+  gem "rubocop-rspec", require: false
+end

data/lib/generators/seams/engine/templates/LICENSE.tt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <%= Time.now.year %> TODO
+
+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/lib/generators/seams/engine/templates/README.md.tt

@@ -0,0 +1,40 @@
+# <%= module_name %>
+
+> TODO: one-line summary of this engine.
+
+## Events emitted
+
+| Event name | Payload | Emitted when |
+| --- | --- | --- |
+| _none yet_ | | |
+
+Register every event in `lib/<%= name %>/engine.rb` so it shows up in
+`bin/rails seams:list`.
+
+## Events consumed
+
+| Event name | Subscriber | What it does |
+| --- | --- | --- |
+| _none yet_ | | |
+
+## Exposed concerns
+
+Modules in this list are intentionally part of the engine's public
+contract. Other engines may `include` them; `Seams/NoCrossEngineModelAccess`
+will not flag them.
+
+| Concern | Purpose |
+| --- | --- |
+| _none yet_ | |
+
+## Adapters
+
+| Interface | Default | Override via |
+| --- | --- | --- |
+| _none yet_ | | |
+
+## Running the specs
+
+```bash
+bin/rails seams:test[<%= name %>]
+```

data/lib/generators/seams/engine/templates/Rakefile.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Engine-local Rakefile. Like the Gemfile, this is mostly redundant
+# in-tree — the host's `rake` invokes the engine's specs via
+# seams:test[<name>]. It exists so the engine can be tested
+# standalone:
+#
+#   cd engines/<%= name %> && bundle exec rake
+require "bundler/setup"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/generators/seams/engine/templates/app/application_controller.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  class ApplicationController < ::ApplicationController
+  end
+end

data/lib/generators/seams/engine/templates/app/application_record.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  # Engine-scoped abstract Active Record base. Every <%= module_name %>::*
+  # AR model inherits from this rather than from
+  # ::ApplicationRecord so the engine remains usable in a host that
+  # has its own ApplicationRecord with conflicting concerns.
+  #
+  # Hosts that want shared behaviour across all engines can include
+  # a concern here — but only behaviour the engine itself needs.
+  # Cross-engine domain logic belongs in the host's ApplicationRecord
+  # or in a Core engine concern.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/generators/seams/engine/templates/config/locales/en.yml.tt

@@ -0,0 +1,14 @@
+# Engine-scoped i18n. Every translation key SHOULD start with
+# `<%= name %>.` so two engines can never collide on a key (the host's
+# I18n.load_path picks up engines/*/config/locales/*.yml automatically
+# via Rails::Engine).
+#
+# Usage from inside the engine:
+#
+#   I18n.t("<%= name %>.welcome", name: "Ada")
+#
+# Override in the host by dropping a file at
+# config/locales/<%= name %>.en.yml — keys merge top-down, host wins.
+en:
+  <%= name %>:
+    placeholder: "Translate me — engines/<%= name %>/config/locales/en.yml"

data/lib/generators/seams/engine/templates/config/routes.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+<%= module_name %>::Engine.routes.draw do
+end

data/lib/generators/seams/engine/templates/gemspec.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "lib/<%= name %>/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "<%= name %>"
+  spec.version     = <%= module_name %>::VERSION
+  spec.authors     = ["TODO"]
+  spec.email       = ["TODO"]
+  spec.summary     = "TODO: short summary of the <%= name %> engine"
+  spec.description = "TODO: longer description"
+  spec.license     = "MIT"
+
+  spec.files = Dir["{app,config,db,lib}/**/*", "LICENSE", "README.md"]
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.add_dependency "rails", ">= 7.1"
+  spec.add_dependency "seams"
+end

data/lib/generators/seams/engine/templates/host_initializer.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Configuration for the <%= module_name %> engine. Uncomment and edit
+# the values you need to override; everything is set to a sensible
+# default in the engine's `Configuration` class.
+#
+# This file is created by `bin/rails generate seams:engine <%= name %>`
+# only on first run; subsequent runs leave it alone.
+
+# <%= module_name %>.configure do |config|
+#   # Add your settings here. Run `bin/rails console` and inspect
+#   # `<%= module_name %>.configuration` to see the available options.
+# end

data/lib/generators/seams/engine/templates/lib/engine.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  class Engine < ::Rails::Engine
+    isolate_namespace <%= module_name %>
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer "<%= name %>.register_events" do
+      # Declare events that this engine emits. Other engines look these
+      # up via Seams::EventRegistry to know what to subscribe to.
+      #
+      # Example:
+      #   Seams::EventRegistry.register("<%= name %>.something_happened.<%= name %>", emitted_by: "<%= module_name %>")
+    end
+
+    initializer "<%= name %>.append_migrations" do |app|
+      unless app.root == root
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/engine/templates/lib/root.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "<%= name %>/version"
+require "<%= name %>/engine"
+
+module <%= module_name %>
+end

data/lib/generators/seams/engine/templates/lib/version.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  VERSION = "0.1.0"
+end

data/lib/generators/seams/engine/templates/rubocop.yml.tt

@@ -0,0 +1,55 @@
+# Self-contained — engines do not inherit from the host's .rubocop.yml
+# so a host using `rubocop-rails-omakase` (or any other style) doesn't
+# force engine code to follow rules written for application code.
+# Engine code is gem-shaped and uses default RuboCop styles.
+
+require:
+  - seams/cops
+
+AllCops:
+  TargetRubyVersion: 4.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "spec/dummy/**/*"
+    - "db/migrate/**/*_create_*.rb"
+    - "tmp/**/*"
+    - "vendor/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/MethodLength:
+  Max: 25
+
+# Engine-scoped boundary enforcement. List every other engine in your
+# host application here so this engine cannot reach into them
+# accidentally. Add concerns the other engines expose (e.g.
+# `Billing::Billable`) to ExposedConcerns to allow `include` calls.
+Seams/NoCrossEngineModelAccess:
+  Enabled: true
+  OwnEngine: <%= module_name %>
+  OtherEngines: []
+  ExposedConcerns: []
+
+Seams/NoCrossEngineDependency:
+  Enabled: true
+  OwnEngine: <%= name %>
+  OtherEngines: []
+
+Seams/KnownQueueNames:
+  Enabled: true
+  KnownQueues:
+    - default
+    - <%= name %>
+
+Seams/MigrationComments:
+  Enabled: true
+  Include:
+    - "db/migrate/**/*.rb"

data/lib/generators/seams/engine/templates/spec/example_spec.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Force-load this engine's lib/ so the constant resolves whether rspec
+# is run from the host root (`bundle exec rspec engines/<%= name %>/spec`)
+# or from inside the engine. The host's spec_helper does not require us.
+# Rails must load before lib/<%= name %>.rb because engine.rb references
+# Rails::Engine.
+require "rails"
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "<%= name %>"
+
+RSpec.describe <%= module_name %> do
+  it "defines a VERSION constant" do
+    expect(<%= module_name %>::VERSION).to match(/\A\d+\.\d+\.\d+\z/)
+  end
+end

data/lib/generators/seams/engine/templates/spec/spec_helper.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+ENV["RAILS_ENV"] ||= "test"
+
+# This engine isn't a published gem; force-load its lib/ so the
+# constant resolves whether rspec is invoked from the engine or from
+# the host root (`bundle exec rspec engines/<%= name %>/spec`).
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "<%= name %>"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.disable_monkey_patching!
+  config.order = :random
+  Kernel.srand config.seed
+end