ruby_workspace_manager 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7292181b24a08aeaed78ff41ee3fe3d3284185af153d5c151cd64f6f2bda6948
-  data.tar.gz: 41c43c206dbfbbd9ac68f1d9378bab8820d17386dfa8f025be66bc4eeb628a35
+  metadata.gz: 659d59c0a587e4479114fd819337775db56f4c4ae634757d0c6d6206e46addb1
+  data.tar.gz: '07599b434c9f0f4d2aead2160cdf32029e24cf38701e1e66f1bacc9375c9fb2f'
 SHA512:
-  metadata.gz: 6c72d4000b74f07310757f950e9a081eac2697574c9600bdcfd6d0d1aa1fe0b86b4a2a40b11ef9e9ce5df7762e72fe505e4c88b653bfde16e4d2df8fd343ce07
-  data.tar.gz: 3c40d200f9bf6de9da5f8f45d0147b57b395d95507d3d61e449abcf0317d27cd629b544a4289b711948ad19453994d6cf9fe790f24434d6a650510027b1ed5a6
+  metadata.gz: 8ee35a4451cabe1c66eaae86b1ceee7f64d9009a74e79bb744e27b21208fc7897b31f20df90e80a2546d760ae7e122a9f314455c3354d36fbd3cb426e508f62a
+  data.tar.gz: 1acd2eadb3a504f83cdae5990f02b69bb38304e8e2def62b494099131982e93e7569b7be41198065d1fd132cc012585ecdc033044bd1ffb38d94df4f9d29675b

data/README.md

@@ -610,60 +610,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
 
-### Setup
+Workspace libs declared via `rwm_lib` are path gems. The standard Rails boot sequence handles them automatically:
 
-**1. Gemfile** — declare workspace deps with `rwm_lib`:
+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
+
+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/lib/ruby_workspace_manager.rb

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

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

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.2"
 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.2
 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