constable-rails 0.1.0 → 1.1.0

data/lib/generators/constable/install_generator.rb

@@ -19,6 +19,7 @@ module Constable
     #   test/cases/example_case.rb   a worked case so `constable test` does something
     #   .constable/config.yml        every setting, at its default, as a reference
     #   .rubocop.yml                 the linter, merged into yours if you have one
+    #   .gitignore                   two lines, so the blotter stays local
     #
     # Plus the optional :cold_case Gemfile group, but only when there is actually
     # an RSpec or Minitest suite in the repo to import. Installing the gem into a
@@ -44,18 +45,44 @@ module Constable
                                   desc: "Don't write the example case under test/cases/"
       class_option :skip_support, type: :boolean, default: false,
                                   desc: "Don't write the example files under test/support/"
+      class_option :skip_config, type: :boolean, default: false,
+                                 desc: "Don't write .constable/config.yml -- configure in Ruby instead"
 
-      COLD_CASE_GROUP = <<~RUBY
+      COLD_CASE_HEADER = <<~RUBY
         # Cold cases: your existing RSpec/Minitest files, run verbatim through their own
         # real engine, with results merged into Constable's reporting and CI gate. These
-        # two gems are needed only for as long as cold cases exist -- delete the group
-        # once the suite is fully modernized and both dependencies drop out with it.
-        group :cold_case do
-          gem "rspec-rails"
-          gem "minitest"
-        end
+        # gems are needed only for as long as cold cases exist -- delete the group once
+        # the suite is fully modernized and the dependencies drop out with it.
       RUBY
 
+      # Only the engines this repo actually has files for, and only ones the Gemfile does
+      # not already declare. An app adopting Constable *from RSpec* -- which is most of
+      # them -- already has rspec-rails, and declaring it twice is not a style question:
+      # Bundler refuses to parse the file at all, so the install leaves the app unbootable.
+      COLD_CASE_GEMS = { rspec: "rspec-rails", minitest: "minitest" }.freeze
+
+      # Per engine, so a repo with only RSpec files does not get minitest added to its
+      # Gemfile for a migration it is never going to do.
+      LEGACY_GLOBS = { rspec: "spec/**/*_spec.rb", minitest: "test/**/*_test.rb" }.freeze
+
+      # The blotter is machine state: this laptop's flake history and jail docket. Sharing
+      # it through git would hand CI somebody else's docket and conflict on every run.
+      GITIGNORE_ENTRY = <<~TEXT
+        # Constable's blotter -- flake history, the jail docket, warrants. Local state:
+        # each machine keeps its own, and CI starts clean.
+        /.constable/*.sqlite3
+        /.constable/*.sqlite3-*
+      TEXT
+
+      NEW_SETTINGS_HEADER = <<~TEXT
+        # ---------------------------------------------------------------------------
+        # Added by `rails generate constable:install` on a later upgrade. These settings
+        # did not exist when this file was written; each is shown at its default, so
+        # deleting any of them changes nothing.
+        # ---------------------------------------------------------------------------
+
+      TEXT
+
       RUBOCOP_EXTENSION = "rubocop-constable"
 
       def create_case_helper
@@ -69,8 +96,32 @@ module Constable
         template "authenticatable.rb.tt", "test/support/authenticatable.rb"
       end
 
+      # The config file doubles as the reference -- every key at its default, with the
+      # reasoning above it -- which only works if it stays current. A gem upgrade cannot
+      # rewrite it (that would clobber your settings) and Thor's only other answer is to
+      # skip the file entirely, so before 1.1.0 a setting added after you installed was
+      # invisible: `output` shipped in 1.0.0 and never appeared in an existing config.
+      #
+      # So: create it if it is missing, and otherwise append only the settings it does not
+      # already mention. Your edits and comments are never touched.
       def create_config
-        template "config.yml.tt", ".constable/config.yml"
+        if options[:skip_config]
+          say_status :skip, ".constable/config.yml (configure in test/case_helper.rb instead)", :blue
+          return
+        end
+
+        path = File.join(destination_root, ".constable/config.yml")
+        return template("config.yml.tt", ".constable/config.yml") unless File.exist?(path)
+
+        missing = missing_config_blocks(File.read(path))
+        if missing.empty?
+          say_status :identical, ".constable/config.yml (every setting is documented)", :blue
+          return
+        end
+
+        names = missing.flat_map { |block| config_keys_in(block) }
+        say_status :append, ".constable/config.yml (#{names.join(", ")})", :green
+        append_to_file ".constable/config.yml", "\n#{NEW_SETTINGS_HEADER}#{missing.join("\n\n")}\n"
       end
 
       def create_example_case
@@ -101,7 +152,31 @@ module Constable
           return
         end
 
-        append_to_file "Gemfile", "\n#{COLD_CASE_GROUP}"
+        gems = cold_case_gems_to_add
+        if gems.empty?
+          say_status :skip, "Gemfile (every cold-case engine is already declared)", :blue
+          return
+        end
+
+        append_to_file "Gemfile", "\n#{cold_case_group(gems)}"
+      end
+
+      # The blotter must not be committed. Appended rather than templated, because an app
+      # always has a .gitignore already and ours is two lines of it.
+      def ignore_the_blotter
+        path = File.join(destination_root, ".gitignore")
+
+        unless File.exist?(path)
+          create_file ".gitignore", GITIGNORE_ENTRY
+          return
+        end
+
+        if File.read(path).include?("/.constable/*.sqlite3")
+          say_status :identical, ".gitignore (blotter already ignored)", :blue
+          return
+        end
+
+        append_to_file ".gitignore", "\n#{GITIGNORE_ENTRY}"
       end
 
       # An app that already lints has opinions in .rubocop.yml worth more than
@@ -137,6 +212,58 @@ module Constable
 
       private
 
+      # An engine earns a line only if this repo has files for it and the Gemfile does not
+      # already declare it.
+      def cold_case_gems_to_add
+        COLD_CASE_GEMS.filter_map do |engine, gem_name|
+          next unless legacy_files?(engine)
+          next if gem_declared?(gem_name)
+
+          gem_name
+        end
+      end
+
+      def cold_case_group(gems)
+        lines = gems.map { |gem_name| %(  gem "#{gem_name}") }
+        "#{COLD_CASE_HEADER}group :cold_case do\n#{lines.join("\n")}\nend\n"
+      end
+
+      # Matches `gem "rspec-rails"` and `gem 'rspec-rails', "~> 8.0"` alike, and ignores a
+      # commented-out line, which is a suggestion rather than a declaration.
+      def gem_declared?(gem_name)
+        gemfile_contents.each_line.any? do |line|
+          stripped = line.strip
+          next false if stripped.start_with?("#")
+
+          stripped.match?(/\Agem\s+["']#{Regexp.escape(gem_name)}["']/)
+        end
+      end
+
+      # Blocks in the shipped reference whose settings the existing file never mentions.
+      # A "block" is a run of lines between blank ones: the comment and the setting it
+      # explains travel together, because a bare key with no reasoning is not a reference.
+      def missing_config_blocks(existing)
+        present = config_keys_in(existing)
+
+        reference_blocks.select do |block|
+          keys = config_keys_in(block)
+          keys.any? && (keys - present) == keys
+        end
+      end
+
+      def reference_blocks
+        File.read(find_in_source_paths("config.yml.tt")).split(/\n{2,}/).map(&:rstrip).reject(&:empty?)
+      end
+
+      # Top-level YAML keys only, ignoring comments and nested ones -- a commented-out
+      # example is a suggestion, not a declaration.
+      def config_keys_in(text)
+        text.lines.filter_map do |line|
+          match = line.match(/\A([a-z][a-z0-9_]*):/)
+          match && match[1]
+        end.uniq
+      end
+
       def gemfile_contents
         File.read(File.join(destination_root, "Gemfile"))
       end
@@ -148,6 +275,10 @@ module Constable
         Dir.glob(File.join(destination_root, "{spec,test}/**/*_{spec,test}.rb")).any?
       end
 
+      def legacy_files?(engine)
+        Dir.glob(File.join(destination_root, LEGACY_GLOBS.fetch(engine))).any?
+      end
+
       # A textual merge, not a YAML round trip: parsing and re-emitting someone's
       # .rubocop.yml would silently eat every comment in it, and comments in a
       # lint config are usually the reason a rule is there at all.

data/lib/generators/constable/templates/case_helper.rb.tt

@@ -67,9 +67,37 @@ end
 #  reimplementation of them would be a slightly wrong one.
 # -----------------------------------------------------------------------------
 
+# -----------------------------------------------------------------------------
+#  Support files -- shared modules and custom matchers.
+#
+#  Same role RSpec's spec/support/**/*.rb plays. Shared behavior *across* files
+#  is a plain module you `include`; there is deliberately no shared-examples DSL
+#  here, because Ruby's own composition tools already do that job with fewer
+#  rules to learn and more flexibility once the reuse stops being simple.
+#
+#  Sorted on purpose: Dir[] returns filesystem order, which differs between your
+#  laptop and CI. A suite that loads its own support files in an unpredictable
+#  order has already lost the argument about determinism.
+#
+#  Loaded BEFORE the tier classes below, so `include Authenticatable` on a tier
+#  is a thing you can actually write. Loading them afterwards would make the
+#  advice in test/support/authenticatable.rb raise NameError.
+# -----------------------------------------------------------------------------
+
+Dir[Rails.root.join("test/support/**/*.rb")].sort.each { |f| require f }
+
+# Factories, when the app has them. `create(:user)` is what a converted spec will be
+# full of, and a NoMethodError on the first native run is a bad way to learn that the
+# include was missing. Guarded, so a suite with no factory gem is unaffected.
+module CaseFactories
+  include FactoryBot::Syntax::Methods if defined?(FactoryBot::Syntax::Methods)
+end
+
 # No database, no request stack, no browser -- just Ruby. The fastest thing
 # Constable can run, and where most of a suite should live.
 class UnitCase < Constable::Case
+  include CaseFactories
+
   tier :unit
 end
 
@@ -78,6 +106,12 @@ end
 # investigation runs inside a transaction that is rolled back afterwards.
 class IntegrationCase < Constable::Case
   include Constable::RailsSupport::Integration
+  include CaseFactories
+
+  # Every integration case gets the app's sign-in helpers. Uncomment once
+  # test/support/authenticatable.rb says something true about your app:
+  #
+  # include Authenticatable
 
   tier :integration
 end
@@ -87,6 +121,8 @@ end
 # and Rails' own `driven_by`. There is no `response` here -- a system case looks
 # at the rendered page, which is the whole reason to pay for a browser.
 class SystemCase < Constable::Case
+  include CaseFactories
+
   # Capybara is not a Constable dependency. System cases are opt-in, and a suite
   # with no browser tests shouldn't be made to install a browser driver to boot.
   include Constable::RailsSupport::System if defined?(Capybara)
@@ -100,34 +136,52 @@ class SystemCase < Constable::Case
 end
 
 # -----------------------------------------------------------------------------
-#  Support files -- shared modules and custom matchers.
-#
-#  Same role RSpec's spec/support/**/*.rb plays. Shared behavior *across* files
-#  is a plain module you `include`; there is deliberately no shared-examples DSL
-#  here, because Ruby's own composition tools already do that job with fewer
-#  rules to learn and more flexibility once the reuse stops being simple.
-#
-#  Sorted on purpose: Dir[] returns filesystem order, which differs between your
-#  laptop and CI. A suite that loads its own support files in an unpredictable
-#  order has already lost the argument about determinism.
+#  Code-level configuration.
 # -----------------------------------------------------------------------------
 
-Dir[Rails.root.join("test/support/**/*.rb")].sort.each { |f| require f }
-
-# -----------------------------------------------------------------------------
-#  Code-level configuration.
+#  Code only, by default: matchers and suite hooks can be written nowhere else.
+#
+#  Settings can be written here too, and this file wins over
+#  .constable/config.yml -- a CLI flag wins over both, for one run. Use the file
+#  for values that differ per project or per branch, where being greppable
+#  without running anything is worth something. Use Ruby when the value has to be
+#  computed, which YAML cannot do:
+#
+#      c.parallel_workers = ENV.fetch("CI_WORKERS", 4).to_i
+#      c.coverage         = ENV["CI"] == "true"
+#
+#  Every setting, at its default -- uncomment what you want and delete the rest.
+#  `.constable/config.yml` explains each one at length and is optional; between
+#  the two, this file can be the only place you configure Constable.
+#
+#      c.cold_cases         = []      # RSpec/Minitest globs to run as cold cases
+#      c.parallel_workers   = "auto"  # or an integer. Each worker gets its own database
+#      c.output             = :concise    # or :expanded -- a line per test, with timings
+#      c.fail_on_warnings   = false   # CI: fail when the warning count is not trending down
+#      c.warrants           = false   # rerun a failure in isolation before believing it
+#      c.warrant_retries    = 5
+#      c.parole_period      = 10      # clean runs before a paroled test releases itself
+#      c.auto_relink        = false   # auto-confirm rename detection
+#      c.coverage           = false
+#      c.coverage_threshold = 90      # diff-based: only lines changed in this diff
+#      c.coverage_html      = false
+#      c.tiers              = { "unit" => "test/cases/models/**/*" }
+#
+#  `storage` is the one setting that cannot go here: the blotter is opened before
+#  this file loads, so `constable jail` and `constable status` can read the docket
+#  without booting the app. Setting it here raises rather than being ignored. Use
+#  .constable/config.yml, or CONSTABLE_STORAGE_URL / _PATH / _ADAPTER.
+#
+#  Not config/initializers/: initializers run on every boot including production,
+#  where a test-only gem is not in the bundle. Same reason RSpec, SimpleCov and
+#  WebMock all configure from the test helper rather than an initializer.
 # -----------------------------------------------------------------------------
 
 Constable.configure do |c|
-  # Workers default to `auto` -- processor count minus a little headroom, so the
-  # machine stays usable while the suite runs. Pin it only when a CI container
-  # lies about its core count.
-  # c.parallel_workers = 4
-
-  # One-time global setup, run once per process before the whole suite. This is
-  # for configuring the world -- drivers, adapters, formats -- and deliberately
-  # not for creating records that tests then share. See the note at the bottom
-  # of this file about why that distinction is the whole ballgame.
+  # One-time global setup, run once per process before the whole suite. For
+  # configuring the world -- drivers, adapters, formats -- and deliberately not
+  # for creating records that tests then share. See the note at the bottom of
+  # this file about why that distinction is the whole ballgame.
   #
   # c.before_suite do
   #   Capybara.default_driver    = :rack_test

data/lib/generators/constable/templates/config.yml.tt

@@ -1,13 +1,29 @@
 # .constable/config.yml
 #
-# Settings, as opposed to code. Everything here is a number, a flag or a glob;
-# anything that is Ruby -- custom matchers, tier base classes, one-time global
-# setup -- lives in test/case_helper.rb instead.
+# Optional. Everything here can also be written in Ruby, in test/case_helper.rb:
 #
-# Every key Constable understands is present below at its default value, so this
-# file doubles as the complete reference. Delete anything you haven't changed;
-# the behavior is identical either way. CLI flags win over this file for the
-# duration of a single run.
+#     Constable.configure do |c|
+#       c.parallel_workers = ENV.fetch("CI_WORKERS", 4).to_i
+#       c.output           = :expanded
+#     end
+#
+# ...which is the better home for anything computed, and the more familiar one if you
+# come from RSpec's spec_helper.rb. Ruby wins over this file; a CLI flag wins over both.
+#
+# Two reasons this file exists at all:
+#
+#   1. `storage` cannot go anywhere else. The blotter is opened before case_helper.rb
+#      loads, so that `constable jail`, `warrants`, `watchlist` and `status` can read the
+#      docket without booting the app -- a broken app should not stop you reading the
+#      docket. Setting it in Ruby raises rather than being quietly ignored.
+#
+#   2. A settings file is greppable and diffable without executing anything, which is
+#      what you want for the values that differ per project or per branch.
+#
+# Every key Constable understands is below at its default, so this doubles as the
+# reference. Delete anything you have not changed; the behavior is identical either way.
+# Re-run `rails generate constable:install --skip` after upgrading and any settings added
+# since will be appended here, leaving your own values and comments alone.
 
 # Glob paths to run as cold cases: original RSpec/Minitest files, driven verbatim
 # through their own real engine, with pass/fail/timing fed into Constable's
@@ -57,6 +73,15 @@ fail_on_warnings: false  # CI: fail the build when the warning count doesn't tre
 
 parallel_workers: auto   # or an explicit integer
 
+# How much the live stream says while the suite is running. The summary is identical
+# either way -- this only changes what you watch on the way there.
+#
+#   concise   one glyph per test, grouped into a run per case. A thousand tests stay
+#             inside one screen, and a wall of green is the point.
+#   expanded  a line per test: glyph, name, duration. Slower to read in bulk, but you
+#             can see which test is hanging while it hangs, rather than after.
+output: concise          # concise | expanded
+
 # Fallback path-based tier inference, used only when a case doesn't inherit from
 # a tiered base class. The base classes in test/case_helper.rb are the primary
 # mechanism and always win -- this is here so an un-migrated file still lands in

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constable-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ray Hughes
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -96,7 +96,7 @@ description: |
   The gem is published as "constable-rails"; everything inside it -- the module, the
   CLI, the config directory -- is simply "constable".
 email:
-- r.hughes2136@gmail.com
+- raymond.hughes@live.com
 executables:
 - constable
 extensions: []
@@ -141,6 +141,7 @@ files:
 - lib/constable/storage/sqlite_adapter.rb
 - lib/constable/version.rb
 - lib/constable/warrants.rb
+- lib/constable/worker_databases.rb
 - lib/generators/constable/base.rb
 - lib/generators/constable/channel/channel_generator.rb
 - lib/generators/constable/channel/templates/channel_case.rb.tt