seams 0.1.0

data/lib/seams/cli/resolve.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "seams"
+require "seams/generators/splicer"
+
+module Seams
+  module CLI
+    # Implementation behind `bin/seams resolve` — gap-report 1.2 from
+    # the 2026-05 framework feature-gap survey: the documented escape
+    # hatch from seams' generators.
+    #
+    # Three modes:
+    #
+    #   bin/seams resolve --eject <engine>/<file>
+    #
+    #     Marks a single host file as host-owned. The next regeneration
+    #     of the engine skips this file. The file already lives in the
+    #     host's working tree (seams generates "the code is in your
+    #     repo") — eject just prepends an explicit ownership header
+    #     and tells the engine generator to leave it alone.
+    #
+    #   bin/seams resolve --list-markers <engine>
+    #
+    #     Lists every `# seams:insertion-point ...` marker the engine
+    #     ships across all of its templated files. Helps the host
+    #     operator see which extension points are public contract
+    #     before writing a follow-up generator.
+    #
+    #   bin/seams resolve --list-ejected
+    #
+    #     Surveys engines/ for files marked with the eject header and
+    #     lists them. Useful for "what's diverged from the gem".
+    #
+    # Returns true on success / false on failure. The caller (the
+    # `bin/seams` shim) translates that into a non-zero exit code.
+    #
+    # Several methods here legitimately return true/false to signal
+    # success/failure but are command verbs (`run_eject`,
+    # `engine_present?` is fine, `fail_with` etc). Rubocop's
+    # PredicateMethod cop wants every bool-returning method renamed
+    # with a trailing `?`, but that's wrong for the run_* dispatchers
+    # (they're imperative, not predicates). AbcSize / CyclomaticComplexity
+    # likewise trigger on the run_* methods because CLI command
+    # branches are inherently branchy. The cops are disabled at file
+    # scope and the methods are kept linear and well-commented.
+    # rubocop:disable Naming/PredicateMethod, Metrics/AbcSize, Metrics/CyclomaticComplexity
+    class Resolve
+      DEFAULT_ENGINES_ROOT = "engines"
+
+      # Header injected at the top of every ejected file. Position
+      # matters: future regenerations check the FIRST line of an
+      # existing destination file for this exact prefix.
+      EJECT_HEADER_PREFIX = "# seams:ejected from"
+      EJECT_HEADER_LINES  = lambda do |from|
+        <<~HEADER
+          #{EJECT_HEADER_PREFIX} #{from}
+          # Re-running `bin/rails generate seams:#{from.split(".").first}` will NOT overwrite this file.
+          # To return to the gem version: delete this file and re-run the generator.
+        HEADER
+      end
+
+      # Files at this list of relative paths under engines/<engine>/
+      # are NOT eject-eligible. See doc note in EjectAware module.
+      INELIGIBLE_RELATIVE_PATTERNS = [
+        %r{\Adb/migrate/},                # one-shot, host runs them
+        %r{\Alib/[^/]+/engine\.rb\z},     # framework-managed boot file
+        %r{\Alib/[^/]+/version\.rb\z},    # framework-managed version constant
+        /\AGemfile\z/,                    # engine's own Gemfile
+        %r{\A[^/]+\.gemspec\z},           # engine's gemspec
+        /\ARakefile\z/                    # engine's Rakefile (loads engine tasks)
+      ].freeze
+
+      def initialize(mode:, argument: nil, engines_root: DEFAULT_ENGINES_ROOT, output: $stdout, error: $stderr)
+        @mode         = mode
+        @argument     = argument
+        @engines_root = engines_root
+        @output       = output
+        @error        = error
+      end
+
+      def call
+        case @mode
+        when :eject         then run_eject
+        when :list_markers  then run_list_markers
+        when :list_ejected  then run_list_ejected
+        else
+          fail_with("unknown mode: #{@mode.inspect}")
+        end
+      end
+
+      private
+
+      # ---- Mode 1: --eject <engine>/<file_relative> ----
+
+      def run_eject
+        return false unless argument_present?(usage: "bin/seams resolve --eject <engine>/<file>")
+
+        engine, relative = split_eject_argument(@argument)
+        return false unless engine && relative
+
+        return false unless engine_present?(engine)
+        return false unless eject_eligible?(engine, relative)
+
+        full_path = File.join(@engines_root, engine, relative)
+        return fail_with("file not found: #{full_path}") unless File.exist?(full_path)
+
+        contents = File.read(full_path)
+        if contents.start_with?(EJECT_HEADER_PREFIX)
+          @output.puts("already ejected: #{full_path}")
+          return true
+        end
+
+        from = "#{engine}.#{relative}"
+        File.write(full_path, EJECT_HEADER_LINES.call(from) + contents)
+        line_count = File.read(full_path).each_line.count
+        @output.puts("ejected: #{full_path} (lines: #{line_count}; from: #{from})")
+        true
+      end
+
+      def split_eject_argument(argument)
+        # Argument shape: "<engine>/<file/path>". The first segment is
+        # the engine; everything after the first slash is the relative
+        # path within the engine root. We deliberately match on the
+        # FIRST slash so paths like "auth/app/mailers/auth/foo.rb"
+        # round-trip correctly.
+        if argument.include?("/")
+          engine, relative = argument.split("/", 2)
+          return [engine, relative] if engine && !engine.empty? && relative && !relative.empty?
+        end
+
+        fail_with("expected '<engine>/<file>', got #{argument.inspect}")
+        [nil, nil]
+      end
+
+      def eject_eligible?(engine, relative)
+        return true unless INELIGIBLE_RELATIVE_PATTERNS.any? { |pattern| pattern.match?(relative) }
+
+        fail_with(
+          "refusing to eject #{engine}/#{relative}: this file is framework-managed " \
+          "(migrations, engine.rb, version.rb, Gemfile, .gemspec) and is not eject-eligible. " \
+          "See doc/INSERTION_POINTS.md and Seams::Generators::EjectAware for the rule."
+        )
+        false
+      end
+
+      # ---- Mode 2: --list-markers <engine> ----
+
+      def run_list_markers
+        return false unless argument_present?(usage: "bin/seams resolve --list-markers <engine>")
+        return false unless engine_present?(@argument)
+
+        engine_root = File.join(@engines_root, @argument)
+        markers = collect_markers(engine_root)
+
+        if markers.empty?
+          @output.puts("#{@argument}: no insertion-point markers found in #{engine_root}/")
+          @output.puts("  This engine may not have been retrofitted to Wave 10. " \
+                       "Re-run `bin/rails generate seams:#{@argument}` to pick up the marker set.")
+          return true
+        end
+
+        print_marker_table(markers)
+        true
+      end
+
+      def collect_markers(engine_root)
+        rb_files = Dir.glob(File.join(engine_root, "**", "*.rb"))
+        rb_files.flat_map do |path|
+          Seams::Generators::Splicer.list_markers(file_path: path).map do |info|
+            relative = path.sub(%r{\A#{Regexp.escape(engine_root)}/}, "")
+            description = description_for(path, info[:line_number])
+            info.merge(file: relative, description: description)
+          end
+        end
+      end
+
+      # Best-effort one-line description: read the comment immediately
+      # PRECEDING the marker (one or two lines back) — the catalogue
+      # convention is to document the marker's purpose in a sibling
+      # comment line. Falls back to an empty string if no such comment
+      # exists; the table prints "(no description)" in that case.
+      def description_for(file_path, marker_line_number)
+        return "" unless File.exist?(file_path)
+
+        lines = File.readlines(file_path)
+        # marker_line_number is 1-indexed; the description line, if any,
+        # sits immediately above. Guard against marker_line_number == 1
+        # explicitly — Ruby's negative array index would otherwise wrap
+        # to the LAST line of the file, which is nonsensical here.
+        return "" if marker_line_number <= 1
+
+        candidate = lines[marker_line_number - 2]
+        return "" unless candidate
+
+        stripped = candidate.strip
+        return "" unless stripped.start_with?("#")
+        return "" if stripped.start_with?("# seams:insertion-point")
+
+        stripped.sub(/\A#\s?/, "").strip
+      end
+
+      def print_marker_table(markers)
+        marker_width = markers.map { |m| m[:marker].length }.max
+        location_width = markers.map { |m| "#{m[:file]}:#{m[:line_number]}".length }.max
+
+        markers.each do |info|
+          location = "#{info[:file]}:#{info[:line_number]}"
+          description = info[:description].empty? ? "(no description)" : %("#{info[:description]}")
+          @output.puts("#{info[:marker].ljust(marker_width)}  #{location.ljust(location_width)}  #{description}")
+        end
+      end
+
+      # ---- Mode 3: --list-ejected ----
+
+      def run_list_ejected
+        unless Dir.exist?(@engines_root)
+          @output.puts("no engines directory at #{@engines_root}/")
+          return true
+        end
+
+        ejected = collect_ejected_files
+        if ejected.empty?
+          @output.puts("no ejected files in #{@engines_root}/")
+          return true
+        end
+
+        @output.puts("seams: #{ejected.size} ejected file(s)")
+        ejected.each { |path, source| @output.puts("  #{path}  (from: #{source})") }
+        true
+      end
+
+      def collect_ejected_files
+        # Cheap two-pass scan: read first 200 bytes of every text file
+        # under engines/, look for the prefix. We deliberately skip
+        # binaries (anything that isn't .rb / .erb / .yml / .yaml / .rake / .css / .js)
+        # because the eject header is always a `#`-comment and only
+        # text-ish files carry it.
+        text_extensions = %w[.rb .erb .yml .yaml .rake .css .js .txt .md].freeze
+        Dir.glob(File.join(@engines_root, "**", "*"))
+           .select { |path| File.file?(path) && text_extensions.include?(File.extname(path)) }
+           .sort
+           .filter_map do |path|
+             head = File.read(path, 200)
+             next nil unless head.start_with?(EJECT_HEADER_PREFIX)
+
+             source = head.lines.first.to_s.sub(EJECT_HEADER_PREFIX, "").strip
+             [path, source]
+           end
+      end
+
+      # ---- Shared helpers ----
+
+      def argument_present?(usage:)
+        return true if @argument && !@argument.empty?
+
+        fail_with("missing argument. Usage: #{usage}")
+        false
+      end
+
+      def engine_present?(engine)
+        engine_root = File.join(@engines_root, engine)
+        return true if File.directory?(engine_root)
+
+        fail_with("engine #{engine.inspect} not found at #{engine_root}/. " \
+                  "Run `bin/rails generate seams:#{engine}` first.")
+        false
+      end
+
+      def fail_with(message)
+        @error.puts("seams resolve: #{message}")
+        false
+      end
+    end
+    # rubocop:enable Naming/PredicateMethod, Metrics/AbcSize, Metrics/CyclomaticComplexity
+  end
+end

data/lib/seams/cli/test_changed.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "seams"
+
+module Seams
+  module CLI
+    # Runs RSpec for every engine that has changed against the merge
+    # base with `main` (or another base via the `base:` keyword).
+    # Falls back to "run every engine's specs" when the merge base
+    # cannot be resolved (CI on a shallow clone, no git, etc) — better
+    # to over-run than to silently skip.
+    #
+    #   bin/rails seams:test:changed                 # base = main
+    #   bin/rails seams:test:changed BASE=develop
+    #
+    # Returns true when every engine spec run passed; false otherwise.
+    # The caller (rake task or bin/seams) translates that to an exit
+    # code.
+    class TestChanged
+      DEFAULT_BASE         = "main"
+      DEFAULT_ENGINES_ROOT = "engines"
+
+      def initialize(base: DEFAULT_BASE, engines_root: DEFAULT_ENGINES_ROOT, output: $stdout)
+        @base         = base
+        @engines_root = engines_root
+        @output       = output
+      end
+
+      def call
+        engines = changed_engines
+        if engines.empty?
+          @output.puts("seams:test:changed — no engines changed since #{@base}; skipping.")
+          return true
+        end
+
+        @output.puts("seams:test:changed — running specs for #{engines.size} engine(s):")
+        engines.each { |name| @output.puts("  - #{name}") }
+        @output.puts("")
+
+        failed = engines.reject { |name| run_engine_specs(name) }
+        if failed.empty?
+          @output.puts("All affected engine specs passed.")
+          true
+        else
+          @output.puts("Failed engines: #{failed.join(", ")}")
+          false
+        end
+      end
+
+      private
+
+      def changed_engines
+        return all_engines unless git_available?
+
+        merge_base = resolve_merge_base
+        return all_engines if merge_base.empty?
+
+        engine_names_from_diff(merge_base)
+      end
+
+      # Array-form shell-out: no interpolation into a shell, so a
+      # @base value like `; rm -rf /` passes as one argv element to
+      # git rather than getting evaluated. shell_escape is defence in
+      # depth on top of that.
+      def resolve_merge_base
+        capture_command(["git", "merge-base", shell_escape(@base), "HEAD"]).strip
+      end
+
+      def engine_names_from_diff(merge_base)
+        diff = capture_command(["git", "diff", "--name-only", merge_base, "HEAD", "--",
+                                "#{@engines_root}/*"])
+        diff.lines
+            .filter_map { |line| line.split("/")[1] }
+            .uniq
+            .sort
+            .select { |name| File.directory?(File.join(@engines_root, name)) }
+      end
+
+      def capture_command(argv)
+        IO.popen(argv, err: File::NULL, &:read)
+      rescue StandardError
+        ""
+      end
+
+      def all_engines
+        return [] unless Dir.exist?(@engines_root)
+
+        Dir.children(@engines_root)
+           .select { |child| File.directory?(File.join(@engines_root, child)) }
+           .reject { |child| child.start_with?(".") }
+           .sort
+      end
+
+      def run_engine_specs(name)
+        spec_dir = File.join(@engines_root, name, "spec")
+        return true if Dir.glob(File.join(spec_dir, "**", "*_spec.rb")).empty?
+
+        @output.puts("=== bundle exec rspec #{spec_dir} ===")
+        system("bundle", "exec", "rspec", spec_dir)
+      end
+
+      def git_available?
+        system("which git > /dev/null 2>&1")
+      end
+
+      # The base branch comes from a keyword arg or env var — both
+      # untrusted. Allow only branch-safe characters before
+      # interpolating into a shell-out (we never reach the shell
+      # because we shell-escape, but defence in depth keeps the
+      # intent explicit).
+      def shell_escape(value)
+        value.to_s.gsub(%r{[^A-Za-z0-9_\-/.]}, "")
+      end
+    end
+  end
+end

data/lib/seams/cli.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "seams"
+require "seams/cli/list"
+require "seams/cli/test_changed"
+require "seams/cli/quality"
+require "seams/cli/resolve"
+
+module Seams
+  # Top-level CLI aggregator. Each public method delegates to a
+  # single-purpose CLI class so the rake tasks (and bin/seams) have
+  # one entry point. Returns true on success, false on failure —
+  # callers translate that into a process exit code.
+  #
+  #   Seams::CLI.list                            # bin/rails seams:list
+  #   Seams::CLI.test_changed(base: "main")      # seams:test:changed
+  #   Seams::CLI.quality                         # seams:quality:all
+  #   Seams::CLI.resolve(mode: :eject, ...)      # bin/seams resolve --eject ...
+  module CLI
+    module_function
+
+    def list(engines_root: "engines", output: $stdout)
+      Seams::CLI::List.new(engines_root: engines_root, output: output).call
+    end
+
+    def test_changed(base: "main", engines_root: "engines", output: $stdout)
+      Seams::CLI::TestChanged.new(
+        base: base,
+        engines_root: engines_root,
+        output: output
+      ).call
+    end
+
+    def quality(engines_root: "engines", output: $stdout)
+      Seams::CLI::Quality.new(engines_root: engines_root, output: output).call
+    end
+
+    def resolve(mode:, argument: nil, engines_root: "engines", output: $stdout, error: $stderr)
+      Seams::CLI::Resolve.new(
+        mode: mode,
+        argument: argument,
+        engines_root: engines_root,
+        output: output,
+        error: error
+      ).call
+    end
+  end
+end

data/lib/seams/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Seams
+  # Global Seams configuration. Set via Seams.configure { |c| ... } in
+  # config/initializers/seams.rb of the host application.
+  class Configuration
+    attr_accessor :event_bus_adapter,
+                  :observability_adapter,
+                  :event_namespace_separator,
+                  :host_app_name
+
+    def initialize
+      @event_bus_adapter = "Seams::Events::Adapters::ActiveSupport"
+      @observability_adapter = "Seams::Observability::Adapters::RailsLogger"
+      @event_namespace_separator = "."
+      @host_app_name = nil
+    end
+  end
+end

data/lib/seams/cops/known_queue_names.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Seams
+      # Ensures every `queue_as` call uses a queue name that has been
+      # registered in the host application's `.rubocop.yml`. Catches typos
+      # and prevents jobs from being silently routed to a queue that no
+      # worker is listening on.
+      class KnownQueueNames < Base
+        MSG = "Queue `%<name>s` is not registered. Add it to .rubocop.yml " \
+              "under Seams/KnownQueueNames#KnownQueues, or pick one of: %<known>s."
+
+        # @!method queue_as_literal?(node)
+        def_node_matcher :queue_as_literal?, <<~PATTERN
+          (send nil? :queue_as ${sym str})
+        PATTERN
+
+        def on_send(node)
+          literal = queue_as_literal?(node)
+          return unless literal
+
+          name = literal.value.to_s
+          return if known_queues.include?(name)
+
+          add_offense(
+            node,
+            message: format(MSG, name: name, known: known_queues.join(", "))
+          )
+        end
+
+        private
+
+        def known_queues
+          Array(cop_config["KnownQueues"]).map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/seams/cops/migration_comments.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Seams
+      # Requires every migration to start with a leading comment block
+      # so that future readers know what the migration does, why it was
+      # needed, and what its data/downtime implications are.
+      class MigrationComments < Base
+        MSG = "Migration `%<name>s` must be preceded by a comment block explaining " \
+              "what changes and why (data implications, downtime risk, rollback notes)."
+
+        # Comments that look like directives, not documentation. We strip these
+        # out before deciding whether the migration carries a real doc block.
+        #
+        # The Parser associator already drops the encoding/shebang/frozen_string_literal
+        # family of magic comments (skip_directives), so this regex only has to
+        # cover the directives Parser leaves attached: Sorbet sigils, RuboCop
+        # disable/enable, shareable_constant_value, warn_indent.
+        MAGIC_COMMENT = /
+          \A\s*\#\s*
+          (?:
+            frozen_string_literal
+            | encoding
+            | warn_indent
+            | shareable_constant_value
+            | typed
+            | rubocop:(?:disable|enable|todo)
+          )
+        /x
+
+        # @!method migration_class?(node)
+        def_node_matcher :migration_class?, <<~PATTERN
+          (class (const nil? $_) (send (const (const _ :ActiveRecord) :Migration) :[] _) ...)
+        PATTERN
+
+        def on_class(node)
+          name = migration_class?(node)
+          return unless name
+          return if leading_comment?(node)
+
+          add_offense(node, message: format(MSG, name: name))
+        end
+
+        private
+
+        # True if the migration class is preceded by at least one comment
+        # that the parser associates with this specific class node and that
+        # isn't a magic comment / directive.
+        #
+        # We rely on `ast_with_comments` (Parser::Source::Comment.associate_by_identity)
+        # rather than line-based scanning so that comments which actually
+        # belong to a sibling class or method above the migration are not
+        # misread as documentation for the migration.
+        def leading_comment?(node)
+          documenting_comments_for(node).any?
+        end
+
+        def documenting_comments_for(node)
+          comments = processed_source.ast_with_comments&.fetch(node, nil) || []
+          comments.reject { |comment| MAGIC_COMMENT.match?(comment.text) }
+        end
+      end
+    end
+  end
+end

data/lib/seams/cops/no_cross_engine_dependency.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Seams
+      # Flags `require`/`require_relative` calls that pull source files
+      # out of another engine. Engines should depend on each other only
+      # through public events (Seams::Events::Publisher) and
+      # explicitly-exposed concerns — not by requiring private files.
+      class NoCrossEngineDependency < Base
+        MSG = "Engine `%<own>s` must not require `%<path>s` from another engine. " \
+              "Communicate via events or via `%<other>s`'s exposed concerns."
+
+        # @!method require_call?(node)
+        def_node_matcher :require_call?, <<~PATTERN
+          (send nil? {:require :require_relative} (str $_))
+        PATTERN
+
+        def on_send(node)
+          path = require_call?(node)
+          return unless path
+
+          offending_engine = other_engine_for(path)
+          return unless offending_engine
+
+          add_offense(
+            node,
+            message: format(MSG, own: own_engine, path: path,
+                                 other: capitalize(offending_engine))
+          )
+        end
+
+        private
+
+        def own_engine
+          cop_config["OwnEngine"].to_s
+        end
+
+        def other_engines
+          Array(cop_config["OtherEngines"]).map(&:to_s)
+        end
+
+        def other_engine_for(path)
+          # Match either "billing/foo" or "../../billing/foo" — the engine
+          # name is whichever directory segment matches another engine.
+          segments = path.split("/")
+          other_engines.find { |engine| segments.include?(engine) }
+        end
+
+        def capitalize(name)
+          name.split(/[_-]/).map(&:capitalize).join
+        end
+      end
+    end
+  end
+end