ruby_workspace_manager 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7292181b24a08aeaed78ff41ee3fe3d3284185af153d5c151cd64f6f2bda6948
-  data.tar.gz: 41c43c206dbfbbd9ac68f1d9378bab8820d17386dfa8f025be66bc4eeb628a35
+  metadata.gz: abb2b2c2c95382842ff412711726e5180b6b044b09278f74fd41bce2d29ae7e0
+  data.tar.gz: 2370c792ceb61d94619822c8b7a6f63277284f178e72d6a3539f782496d64ba1
 SHA512:
-  metadata.gz: 6c72d4000b74f07310757f950e9a081eac2697574c9600bdcfd6d0d1aa1fe0b86b4a2a40b11ef9e9ce5df7762e72fe505e4c88b653bfde16e4d2df8fd343ce07
-  data.tar.gz: 3c40d200f9bf6de9da5f8f45d0147b57b395d95507d3d61e449abcf0317d27cd629b544a4289b711948ad19453994d6cf9fe790f24434d6a650510027b1ed5a6
+  metadata.gz: a6746e8ced0a14de677e83de564c7477e89b0f2519a37447dc1a94dbe28acc3cef2b848c1b3bb2604afe24cd399050d677eceb2dbea194a87163c564df1cada4
+  data.tar.gz: 076e897c277f1074f5c4eef7ee834e5c1920050569783e2a84bac836aa9bb4c82aef182390294663068a24fd6690c172e6946b38ea2e29f0bc9289803ac47283

data/README.md

@@ -211,6 +211,13 @@ rwm_lib "auth", require: false
 
 There is no `rwm_app` helper. Applications are leaf nodes — nothing should depend on them.
 
+`rwm_lib` validates that the library directory exists. If you reference a library that hasn't been created yet, you'll get a clear error:
+
+```
+rwm_lib 'payments': no library found at libs/payments.
+Libraries must live in libs/. Create one with: rwm new lib payments
+```
+
 You can also use raw `gem ... path:` syntax directly. Both work identically for dependency detection.
 
 ### Transitive resolution
@@ -303,6 +310,15 @@ rwm run spec --buffered
 
 When a package fails, its transitive dependents are immediately skipped. Unrelated packages continue running. The exit code is 0 if all packages pass, 1 if any fail.
 
+The summary distinguishes between skip reasons:
+
+```
+5 package(s): 2 passed, 1 failed, 1 skipped (dep failed), 1 skipped (no task).
+```
+
+- **skipped (dep failed)** — a dependency failed, so this package was not attempted
+- **skipped (no task)** — the package's Rakefile doesn't define the requested task
+
 ## Task caching
 
 ### Why caching matters
@@ -528,6 +544,8 @@ rwm affected --base develop
 rwm run spec --affected --base develop
 ```
 
+If the provided `--base` ref doesn't exist, RWM errors immediately instead of silently returning no affected packages.
+
 ## Bootstrap and daily workflow
 
 ### What bootstrap does
@@ -544,6 +562,8 @@ rwm run spec --affected --base develop
 
 Both `rwm init` and `rwm bootstrap` are idempotent.
 
+**Note on parallel installs:** Step 4 runs `bundle install` concurrently across packages. If your packages share a gem installation directory (the default), you may see Bundler log `Waiting for another process to let go of lock`. This is normal — Bundler serializes writes to the shared directory automatically. On large monorepos with many packages, this can slow down bootstrap. If this becomes a bottleneck, consider using `BUNDLE_PATH` per-package or running bootstrap sequentially.
+
 ### The bootstrap rake task
 
 Every scaffolded package includes an empty `bootstrap` task. This is where package-specific setup belongs:
@@ -610,60 +630,135 @@ Exits 0 on pass, 1 on violation. The pre-push hook runs this automatically.
 
 ## Rails and Zeitwerk
 
-Rails uses [Zeitwerk](https://github.com/fxn/zeitwerk) for autoloading. Zeitwerk overrides `Kernel#require`, so `require "auth"` in a controller will fail with a `LoadError` even though the gem is installed. The fix: require workspace libs before Zeitwerk starts.
+### How workspace libs work in Rails
+
+Workspace libs declared via `rwm_lib` are path gems. The standard Rails boot sequence handles them automatically:
 
-### Setup
+1. `config/boot.rb` calls `Bundler.setup` — adds all gem `lib/` directories to `$LOAD_PATH`
+2. `config/application.rb` calls `Bundler.require(*Rails.groups)` — auto-requires every gem, including workspace libs and their transitive deps
+3. `config/environment.rb` calls `Rails.application.initialize!` — Zeitwerk activates for the app's own code
 
-**1. Gemfile** — declare workspace deps with `rwm_lib`:
+By the time Zeitwerk starts in step 3, workspace libs are already loaded as plain Ruby modules. Zeitwerk never touches them — it only manages directories in `config.autoload_paths`.
+
+**No special setup is needed in `application.rb`.** A standard Rails template works:
 
 ```ruby
 # apps/web/Gemfile
+require "rwm/gemfile"
+
 source "https://rubygems.org"
 gemspec
 
-require "rwm/gemfile"
-
 rwm_lib "auth"    # transitive deps resolved automatically
 ```
 
-`ruby_workspace_manager` must be a runtime dependency (not in `:development` group) for Rails apps:
+```ruby
+# apps/web/config/application.rb
+require_relative "boot"
+require "rails/all"
+Bundler.require(*Rails.groups)
+
+module Web
+  class Application < Rails::Application
+    config.load_defaults 8.0
+  end
+end
+```
+
+That's it. `Bundler.require` loads `auth` and all of its transitive workspace dependencies. No manual `Rwm.require_libs`, no ordering tricks.
+
+### A note on Zeitwerk
+
+> [!IMPORTANT]
+> **Correction (v0.6.2):** Documentation in v0.6.1 and earlier incorrectly stated that Zeitwerk overrides `Kernel#require`. This was wrong. Zeitwerk uses `Module#autoload` and `const_missing` to lazily load files from `config.autoload_paths`. A plain `require "auth"` (from `Bundler.require` or anywhere else) works normally at any point during the boot sequence — Zeitwerk does not intercept it.
+
+### The practical lib workflow
+
+**Develop inside your Rails app first.** While a feature is in active development, keep the code in your Rails app's `app/` directory where Zeitwerk gives you hot reloading for free. Change a file, refresh the page, see the result.
+
+**Extract when stable.** When the code has solidified — the interface is settled, multiple apps could use it, you're not changing it every day — extract it into a workspace lib. This is the natural monorepo rhythm: apps are where you experiment, libs are where you consolidate.
+
+At extraction time, choose how the lib is structured.
+
+### Traditional structure (the default)
+
+This is what `rwm new lib` scaffolds. The lib's entry point loads all sub-files eagerly with `require_relative`:
 
 ```ruby
-# apps/web/web.gemspec
-spec.add_dependency "ruby_workspace_manager"
+# libs/auth/lib/auth.rb
+require_relative "auth/token"
+require_relative "auth/user"
+
+module Auth
+  VERSION = "0.1.0"
+end
 ```
 
-**2. application.rb** — require workspace libs before Rails loads:
+**Pros:** Works everywhere — Rails, non-Rails, any Ruby app. Simple. Standard gem structure.
+
+**Cons:** No hot reloading in Rails development. After changing a lib file, you restart the server. This is fine for stable extracted code — you're not changing it often.
+
+This is the right choice for most workspace libs.
+
+### Zeitwerk-compatible structure (opt-in)
+
+Choose this when you're still actively iterating on a lib **and** multiple Rails apps consume it. The lib follows Zeitwerk naming conventions — one constant per file, no `require_relative`:
 
 ```ruby
-# apps/web/config/application.rb
-require_relative "boot"
+# libs/auth/lib/auth.rb
+module Auth
+end
 
-require "rwm/rails"
-Rwm.require_libs
+# libs/auth/lib/auth/token.rb — defines Auth::Token
+# libs/auth/lib/auth/user.rb  — defines Auth::User
+# Zeitwerk auto-discovers these. No require lines needed.
+```
 
-require "rails"
-require "action_controller/railtie"
+Each consuming Rails app opts in by adding the lib to its autoload paths and telling Bundler not to auto-require it:
 
+```ruby
+# apps/web/Gemfile
+rwm_lib "auth", require: false    # Bundler won't auto-require
+```
+
+```ruby
+# apps/web/config/application.rb
 module Web
   class Application < Rails::Application
-    config.load_defaults 8.0
+    config.autoload_paths << Rwm.lib_path("auth")
+    config.eager_load_paths << Rwm.lib_path("auth")
   end
 end
 ```
 
-`Rwm.require_libs` requires exactly the libs that `rwm_lib` resolved in the Gemfile — direct and transitive. After this line, workspace libraries are loaded as plain Ruby modules. Zeitwerk takes over for the app's own code and never touches them.
+Now Zeitwerk manages `auth` — lazy loading in development (with hot reloading), eager loading in production. Changes to lib files are picked up on the next request without restarting the server.
 
-### Why this ordering matters
+**Trade-offs:**
 
-The Rails boot sequence: `config/boot.rb` runs `Bundler.setup` (adds gems to load path) → `config/application.rb` (your code, then Rails) → `config/environment.rb` (Zeitwerk activates). `Rwm.require_libs` must run after Bundler.setup and before `require "rails"`.
+- All consumer apps must add the lib to their autoload paths — this is a per-app decision
+- The lib cannot use `require_relative` for its own files (Zeitwerk must control loading)
+- Non-Rails consumers need a different loading strategy (e.g., `Zeitwerk::Loader.for_gem` or a `Dir.glob` require)
 
 ### What doesn't work
 
-- `require "auth"` inside a controller or model — Zeitwerk is already active.
-- Adding workspace libs to `config.autoload_paths` — they have their own structure.
+**Mixing `Bundler.require` and `autoload_paths` for the same lib.** If `Bundler.require` loads a lib (the default) and you also add it to `config.autoload_paths`, the lib's constants are loaded twice — once eagerly by Bundler, once lazily by Zeitwerk. Reloading breaks because Zeitwerk didn't control the initial load. Pick one or the other per lib.
+
+**Using `require_relative` inside a Zeitwerk-managed lib.** Initial loading works fine — Zeitwerk tolerates other loading mechanisms. But after a Zeitwerk reload cycle (in development), files loaded by `require_relative` are still in `$LOADED_FEATURES`. Ruby's `require_relative` sees them as already loaded and skips them. The constants were removed by Zeitwerk's reload but never re-defined. Result: `NameError`.
+
+### `Rwm.require_libs` — when you need it
+
+For standard Rails apps, `Bundler.require` handles everything. `Rwm.require_libs` exists for edge cases:
+
+- Non-standard Rails setups that don't call `Bundler.require`
+- Non-Rails apps that want to load all workspace libs in one call
+- Explicit control over when workspace libs are loaded
+
+```ruby
+require "rwm/rails"
+Rwm.require_libs    # requires all libs resolved by rwm_lib, idempotent
+```
 
-Non-Rails apps don't have this problem and can `require` workspace libs defined in their Gemfile anywhere in their code.
+Non-Rails apps don't need any of this — `require` workspace libs from your Gemfile anywhere in your code, as with any gem.
 
 ## VSCode integration
 

data/bin/rwm

@@ -3,4 +3,4 @@
 
 require "rwm"
 
-Rwm::CLI.run(ARGV)
+exit(Rwm::CLI.run(ARGV))

data/lib/ruby_workspace_manager.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "rwm"

data/lib/rwm/affected_detector.rb

@@ -24,6 +24,7 @@ module Rwm
       @graph = graph
       @committed_only = committed_only
       @base_branch = base_branch || detect_base_branch
+      validate_base_branch! if base_branch
     end
 
     # Returns packages directly changed + their transitive dependents
@@ -57,6 +58,13 @@ module Rwm
 
     private
 
+    def validate_base_branch!
+      _, _, status = Open3.capture3("git", "-C", workspace.root, "rev-parse", "--verify", "#{@base_branch}^{commit}")
+      return if status.success?
+
+      raise Rwm::Error, "Base ref '#{@base_branch}' does not exist. Check the branch name or pass a valid --base ref."
+    end
+
     def detect_base_branch
       # Try to read the remote's default branch
       ref, _, status = Open3.capture3("git", "-C", workspace.root, "symbolic-ref", "refs/remotes/origin/HEAD")

data/lib/rwm/commands/graph.rb

@@ -23,6 +23,15 @@ module Rwm
           puts graph.to_dot
         when :mermaid
           puts graph.to_mermaid
+        else
+          # Show a brief package listing when no format is requested
+          unless graph.packages.empty?
+            graph.packages.each_value do |pkg|
+              deps = graph.edges[pkg.name] || []
+              dep_str = deps.empty? ? "" : " → #{deps.join(", ")}"
+              puts "  #{pkg.type == "lib" ? "lib" : "app"}/#{pkg.name}#{dep_str}"
+            end
+          end
         end
 
         0

data/lib/rwm/commands/run.rb

@@ -100,21 +100,25 @@ module Rwm
 
         passed = runner.results.count(&:passed?)
         failed_results = runner.results.select { |r| r.failed? || r.errored? }
-        skipped = runner.results.count { |r| r.skipped? || r.dep_skipped? }
+        no_task = runner.results.count(&:skipped?)
+        dep_failed = runner.results.count(&:dep_skipped?)
 
         total = runner.results.size
         parts = []
         parts << "#{passed} passed" unless passed.zero?
         parts << "#{failed_results.size} failed" unless failed_results.empty?
-        parts << "#{skipped} skipped" unless skipped.zero?
+        parts << "#{dep_failed} skipped (dep failed)" unless dep_failed.zero?
+        parts << "#{no_task} skipped (no task)" unless no_task.zero?
 
         puts
         puts "#{total} package(s): #{parts.join(", ")}."
 
         passed_results = runner.results.select(&:passed?)
-        skipped_results = runner.results.select { |r| r.skipped? || r.dep_skipped? }
+        no_task_results = runner.results.select(&:skipped?)
+        dep_skipped_results = runner.results.select(&:dep_skipped?)
         Rwm.debug("passed: #{passed_results.map(&:package_name).join(", ")}") unless passed_results.empty?
-        Rwm.debug("skipped (no matching task): #{skipped_results.map(&:package_name).join(", ")}") unless skipped_results.empty?
+        Rwm.debug("skipped (no matching task): #{no_task_results.map(&:package_name).join(", ")}") unless no_task_results.empty?
+        Rwm.debug("skipped (dep failed): #{dep_skipped_results.map(&:package_name).join(", ")}") unless dep_skipped_results.empty?
 
         if failed_results.empty?
           0

data/lib/rwm/dependency_graph.rb

@@ -103,13 +103,30 @@ module Rwm
       end
 
       Rwm.debug("graph: loading from cache at #{path}")
-      data = JSON.parse(read_locked(path))
+      begin
+        data = JSON.parse(read_locked(path))
+      rescue Errno::ENOENT
+        Rwm.debug("graph: cache file disappeared, rebuilding")
+        return build_and_save(workspace)
+      rescue JSON::ParserError
+        Rwm.debug("graph: cache file contains invalid JSON, rebuilding")
+        return build_and_save(workspace)
+      end
+
       graph = new
 
       workspace.packages.each { |pkg| graph.add_package(pkg) }
 
       data["edges"]&.each do |name, deps|
-        deps.each { |dep| graph.add_edge(name, dep) }
+        next unless graph.packages.key?(name)
+
+        deps.each do |dep|
+          if graph.packages.key?(dep)
+            graph.add_edge(name, dep)
+          else
+            Rwm.debug("graph: skipping stale edge #{name} -> #{dep} (package removed)")
+          end
+        end
       end
 
       graph

data/lib/rwm/gemfile.rb

@@ -17,17 +17,33 @@ require "set"
 
 module Rwm
   @resolved_libs = Set.new
+  @workspace_root = nil
 
   def self.resolved_libs
     @resolved_libs
   end
 
+  def self.workspace_root
+    @workspace_root
+  end
+
+  def self.workspace_root=(path)
+    @workspace_root = path
+  end
+
+  def self.lib_path(name)
+    raise "rwm: workspace root not set (was rwm_lib used in the Gemfile?)" unless @workspace_root
+
+    File.join(@workspace_root, "libs", name.to_s, "lib")
+  end
+
   module GemfileDsl
     def rwm_workspace_root
       @rwm_workspace_root ||= begin
         out, _, status = Open3.capture3("git", "rev-parse", "--show-toplevel")
         root = status.success? ? out.strip : ""
         raise "rwm: not inside a git repository" if root.empty?
+        Rwm.workspace_root ||= root
         root
       end
     end
@@ -37,10 +53,16 @@ module Rwm
       @rwm_resolved ||= Set.new
       return if @rwm_resolved.include?(name)
 
+      path = File.join(rwm_workspace_root, "libs", name)
+
+      unless File.directory?(path)
+        raise "rwm_lib '#{name}': no library found at libs/#{name}. " \
+              "Libraries must live in libs/. Create one with: rwm new lib #{name}"
+      end
+
       @rwm_resolved.add(name)
       Rwm.resolved_libs.add(name) unless @rwm_scanning
 
-      path = File.join(rwm_workspace_root, "libs", name)
       gem(name, **opts, path: path)
 
       # Resolve transitive workspace deps from the target lib's Gemfile

data/lib/rwm/rails.rb

@@ -2,17 +2,28 @@
 
 # Rails integration for RWM workspaces.
 #
-# Usage in config/application.rb:
+# For standard Rails apps, Bundler.require handles workspace libs
+# automatically — no manual require_libs call is needed.
+#
+# This file is for non-standard setups or explicit control:
 #
-#   require_relative "boot"
 #   require "rwm/rails"
 #   Rwm.require_libs
-#   require "rails"
 
 require "rwm/gemfile"
 
 module Rwm
+  @libs_required = false
+
+  def self.libs_required?
+    @libs_required
+  end
+
   def self.require_libs
-    self.resolved_libs.each { |name| require name }
+    return if @libs_required
+
+    resolved_libs.each { |name| require name }
+    @libs_required = true
+    debug("required #{resolved_libs.size} workspace lib(s): #{resolved_libs.to_a.sort.join(', ')}")
   end
 end

data/lib/rwm/task_cache.rb

@@ -24,6 +24,7 @@ module Rwm
       @graph = graph
       @cache_dir = File.join(workspace.root, ".rwm", "cache")
       @content_hashes = {}
+      @content_hash_mutex = Mutex.new
       @cache_declarations = {}
       @declarations_mutex = Mutex.new
     end
@@ -78,7 +79,9 @@ module Rwm
 
     # Compute a content hash for a package: SHA256 of all source files + dependency hashes
     def content_hash(package)
-      return @content_hashes[package.name] if @content_hashes.key?(package.name)
+      @content_hash_mutex.synchronize do
+        return @content_hashes[package.name] if @content_hashes.key?(package.name)
+      end
 
       digest = Digest::SHA256.new
 
@@ -97,7 +100,10 @@ module Rwm
         digest.update(content_hash(dep_pkg))
       end
 
-      @content_hashes[package.name] = digest.hexdigest
+      computed = digest.hexdigest
+      @content_hash_mutex.synchronize do
+        @content_hashes[package.name] = computed
+      end
     end
 
     # Preload cache declarations for multiple packages in parallel.

data/lib/rwm/task_runner.rb

@@ -73,6 +73,9 @@ module Rwm
             running[pkg.name] = Thread.new do
               begin
                 result = run_single(pkg, &command_proc)
+              rescue IOError
+                # Thread killed during I/O (Ctrl+C) — suppress noise
+                next
               rescue => e
                 result = Result.new(
                   package_name: pkg.name, task: "error",

data/lib/rwm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rwm
-  VERSION = "0.6.1"
+  VERSION = "0.6.3"
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: ruby_workspace_manager
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3
 platform: ruby
 authors:
 - Siddharth Bhatt
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tsort
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Convention-over-configuration monorepo tool for Ruby. Manages dependency
   graphs, runs tasks in parallel, detects affected packages, and enforces structural
   conventions.
@@ -22,6 +36,7 @@ files:
 - bin/rwm
 - completions/rwm.bash
 - completions/rwm.zsh
+- lib/ruby_workspace_manager.rb
 - lib/rwm.rb
 - lib/rwm/affected_detector.rb
 - lib/rwm/cli.rb