woods 1.6.1 → 2.0.0.beta2

data/lib/woods/console/tools/tier1.rb

@@ -28,7 +28,6 @@ module Woods
         # @param columns [Array<String>, nil] Columns to include
         # @return [Hash] Bridge request
         def console_sample(model:, scope: nil, limit: 5, columns: nil)
-          limit = [limit, 25].min
           { tool: 'sample', params: { model: model, scope: scope, limit: limit, columns: columns }.compact }
         end
 
@@ -52,7 +51,6 @@ module Woods
         # @param distinct [Boolean] Return unique values only
         # @return [Hash] Bridge request
         def console_pluck(model:, columns:, scope: nil, limit: 100, distinct: false)
-          limit = [limit, 1000].min
           { tool: 'pluck', params: { model: model, columns: columns, scope: scope,
                                      limit: limit, distinct: distinct }.compact }
         end
@@ -98,13 +96,11 @@ module Woods
         # @param scope [Hash, nil] Filter conditions
         # @param columns [Array<String>, nil] Columns to include
         # @return [Hash] Bridge request
-        # rubocop:disable Metrics/ParameterLists
+        # rubocop:disable-next Metrics/ParameterLists
         def console_recent(model:, order_by: 'created_at', direction: 'desc', limit: 10, scope: nil, columns: nil)
-          limit = [limit, 50].min
           { tool: 'recent', params: { model: model, order_by: order_by, direction: direction,
                                       limit: limit, scope: scope, columns: columns }.compact }
         end
-        # rubocop:enable Metrics/ParameterLists
 
         # System health check.
         #

data/lib/woods/console/tools/tier4.rb

@@ -37,16 +37,27 @@ module Woods
           { tool: 'eval', params: { code: code, timeout: timeout } }
         end
 
-        # Read-only SQL execution with validation.
+        # Read-only SQL execution.
+        #
+        # SQL validation belongs to whoever knows the host's dialect. The
+        # embedded executor re-validates with `SqlValidator.new(dialect:
+        # sql_dialect)` from the live adapter and raises
+        # {Woods::Console::SqlValidationError}, so the registered handler
+        # passes no validator: a handler-stage `SqlValidator.new` is the
+        # conservative postgres+mysql union, and on a MySQL host its
+        # PostgreSQL view of `\'` rejected dialect-valid statements before the
+        # executor could accept them (CON-2). `validator:` stays available for
+        # callers that own their own gate — the bridge path, and specs that
+        # exercise the validator in isolation.
         #
         # @param sql [String] SQL query (must be SELECT or WITH...SELECT)
-        # @param validator [SqlValidator] SQL validator instance
+        # @param validator [SqlValidator, nil] Optional pre-dispatch validator.
+        #   Leave nil to let the executor validate with the adapter's dialect.
         # @param limit [Integer, nil] Optional row limit (max 10000)
         # @return [Hash] Bridge request
-        # @raise [SqlValidationError] if SQL is not read-only
-        def console_sql(sql:, validator:, limit: nil)
-          validator.validate!(sql)
-          limit = [limit, MAX_SQL_LIMIT].min if limit
+        # @raise [SqlValidationError] if a validator was supplied and refuses
+        def console_sql(sql:, validator: nil, limit: nil)
+          validator&.validate!(sql)
           { tool: 'sql', params: { sql: sql, limit: limit }.compact }
         end
 
@@ -61,9 +72,8 @@ module Woods
         # @param scope [Hash, nil] Filter conditions
         # @param limit [Integer, nil] Row limit (max 10000)
         # @return [Hash] Bridge request
-        # rubocop:disable Metrics/ParameterLists
+        # rubocop:disable-next Metrics/ParameterLists
         def console_query(model:, select:, joins: nil, group_by: nil, having: nil, order: nil, scope: nil, limit: nil)
-          limit = [limit, MAX_QUERY_LIMIT].min if limit
           {
             tool: 'query',
             params: {
@@ -78,7 +88,6 @@ module Woods
             }.compact
           }
         end
-        # rubocop:enable Metrics/ParameterLists
       end
     end
   end

data/lib/woods/coordination/lock_heartbeat.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative 'pipeline_lock'
+
+module Woods
+  module Coordination
+    # Keeps a held {PipelineLock} fresh for the duration of a block.
+    #
+    # {PipelineLock} staleness is mtime-only, so a holder that goes quiet for
+    # longer than `stale_timeout` has its lock retired by the next writer —
+    # producing exactly the two-writer clobber the lock exists to prevent,
+    # silently, with the generation bumped afterwards so the clobbered index
+    # reads as fresh.
+    #
+    # The daemon refreshes its lock at every cycle boundary. The rake writers
+    # (`woods:extract`, `woods:incremental`, `woods:refresh`) have no such
+    # boundary — the work is one opaque block — so they need a thread.
+    #
+    # Extracted from `lib/tasks/woods.rake` rather than left as a private
+    # method on `main`: a helper in a task file cannot be driven by a spec, and
+    # the properties worth guarding here are its own (the block's value
+    # survives, its exception survives, the thread stops, the pacing follows
+    # the lock) rather than {PipelineLock}'s.
+    class LockHeartbeat
+      # Fraction of the stale window to wait between refreshes. A third means
+      # two consecutive misses still leave the lock fresh — the same ratio
+      # {Woods::Watch::Status} uses for its own heartbeat.
+      INTERVAL_RATIO = 3.0
+
+      # How often the loop wakes to re-check the stop flag. Independent of the
+      # refresh interval so a short run's end is noticed promptly rather than a
+      # third of the window later.
+      TICK = 1.0
+
+      # Run a block with the lock kept fresh underneath it.
+      #
+      # @param lock [PipelineLock] a lock this process currently holds
+      # @param tick [Numeric] seconds between wakeups (injectable for specs)
+      # @return [Object] whatever the block returns
+      def self.run(lock, tick: TICK, &block)
+        new(lock, tick: tick).run(&block)
+      end
+
+      def initialize(lock, tick: TICK)
+        @lock = lock
+        @tick = tick
+        @interval = lock.stale_timeout / INTERVAL_RATIO
+        @stop = false
+      end
+
+      # @return [Object] the block's return value
+      def run
+        thread = start_thread
+        yield
+      ensure
+        @stop = true
+        thread&.join(@tick + 1)
+      end
+
+      private
+
+      def start_thread
+        # A raising heartbeat must never become the caller's error. `join`
+        # re-raises a thread's exception, and this `join` sits in an `ensure` —
+        # so without this rescue a successful extraction would fail with the
+        # heartbeat's error, and a failing one would have its real error
+        # replaced by it, precisely when the real message matters most.
+        thread = Thread.new do
+          beat
+        rescue StandardError => e
+          # Swallowed so it cannot become the caller's error — but not silently.
+          # A dead heartbeat leaves the run unprotected for the rest of its
+          # life, which is the same silent-failure class this class exists to
+          # prevent.
+          warn "[Woods] lock heartbeat stopped: #{e.class}: #{e.message}"
+        end
+        thread.report_on_exception = false
+        thread
+      end
+
+      def beat
+        # Monotonic, not a count of wakeups. The acquire loop in woods.rake uses
+        # CLOCK_MONOTONIC for the same reason: across a laptop suspend the wall
+        # clock advances while a wakeup counter does not, so a counted heartbeat
+        # would still believe it had time left while the lock aged past the
+        # window. Suspend is what actually produces multi-minute quiet periods
+        # on a dev machine.
+        last = now
+        until @stop
+          sleep(@tick)
+          next if @stop || now - last < @interval
+
+          @lock.touch
+          last = now
+        end
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/woods/coordination/pipeline_lock.rb

@@ -4,6 +4,11 @@ require 'fileutils'
 require 'json'
 require 'securerandom'
 
+# Woods::Error is defined in the entry point; required here so this file can
+# be loaded directly (the watch daemon reaches for it without loading the
+# whole gem first).
+require 'woods'
+
 module Woods
   module Coordination
     class LockError < Woods::Error; end
@@ -22,9 +27,28 @@ module Woods
     class PipelineLock
       DEFAULT_STALE_TIMEOUT = 3600 # 1 hour
 
+      # The transaction-guard filename for a lock of +name+, exposed so
+      # cleanup code that empties a lock directory (woods:clean) can skip the
+      # guard during its sweep — deleting a flock'd guard out from under a
+      # contender's critical section would split the flock across two inodes —
+      # and remove it only after the lock is released.
+      #
+      # @param name [String]
+      # @return [String]
+      def self.guard_filename(name)
+        ".#{name}.lock.guard"
+      end
+
       # @param lock_dir [String] Directory for lock files
       # @param name [String] Lock name (used as filename prefix)
       # @param stale_timeout [Integer] Seconds after which a lock is considered stale
+      # The window after which an untouched lock is considered abandoned.
+      # Exposed so a heartbeat paces itself from the lock it is refreshing
+      # rather than from a constant that only happens to match.
+      #
+      # @return [Numeric]
+      attr_reader :stale_timeout
+
       def initialize(lock_dir:, name:, stale_timeout: DEFAULT_STALE_TIMEOUT)
         @lock_dir = lock_dir
         @name = name
@@ -37,27 +61,47 @@ module Woods
       #
       # @return [Boolean] true if lock acquired, false if already held
       def acquire
-        FileUtils.mkdir_p(@lock_dir)
+        with_path_guard do
+          if File.exist?(@lock_path)
+            return false unless stale?
+            # Retire the stale lock atomically. A bare rm_f + create here is
+            # a TOCTOU race: two processes passing the stale check together
+            # could each delete-and-create, the second deleting the first's
+            # FRESH lock — both would then "hold" it.
+            return false unless retire_stale_unlocked == :cleared
+          end
 
-        if File.exist?(@lock_path)
-          return false unless stale?
-          # Retire the stale lock atomically. A bare rm_f + create here is
-          # a TOCTOU race: two processes passing the stale check together
-          # could each delete-and-create, the second deleting the first's
-          # FRESH lock — both would then "hold" it.
-          return false unless retire_stale_lock
+          # Keep O_EXCL even though cooperating implementations hold the guard:
+          # it still fails closed if an external writer creates the path.
+          begin
+            File.open(@lock_path, File::WRONLY | File::CREAT | File::EXCL) do |file|
+              file.write(lock_content)
+            end
+          rescue Errno::EEXIST
+            raise
+          rescue ScriptError, StandardError
+            discard_partial_lock
+            raise
+          end
+          @held = true
+          true
         end
-
-        # Atomic lock creation: File::EXCL ensures this fails if file already exists
-        File.open(@lock_path, File::WRONLY | File::CREAT | File::EXCL) do |f|
-          f.write(lock_content)
-        end
-        @held = true
-        true
       rescue Errno::EEXIST
         false
       end
 
+      # Retire the lock only when the file captured atomically from the public
+      # lock path is genuinely stale.
+      #
+      # @return [Symbol] `:cleared`, `:not_stale`, or `:missing`
+      def retire_stale
+        return :missing unless File.directory?(@lock_dir)
+
+        with_path_guard { retire_stale_unlocked }
+      rescue Errno::ENOENT
+        :missing
+      end
+
       # Release the lock.
       #
       # Deletes the lock file only if it still carries this instance's
@@ -69,28 +113,18 @@ module Woods
       def release
         return unless @held
 
-        # Clear @held up front so no later failure can leave this instance
-        # believing it still holds the lock.
-        @held = false
+        with_path_guard do
+          next unless @held
 
-        # Rename first, then inspect: a plain read-then-unlink is a TOCTOU —
-        # after we read our own token a takeover could replace the file, and
-        # our unlink would then delete the NEW holder's lock. Renaming
-        # atomically captures whatever is at the path.
-        graveyard = "#{@lock_path}.release.#{Process.pid}.#{SecureRandom.hex(4)}"
-        begin
-          File.rename(@lock_path, graveyard)
-        rescue Errno::ENOENT
-          return # already gone
-        end
-
-        if own_lock?(graveyard)
-          FileUtils.rm_f(graveyard)
-        else
-          # We were legitimately taken over — put the successor's lock back
-          # without clobbering a still-newer holder (see {#restore_lock}).
-          restore_lock(graveyard)
+          # Clear @held before touching the ownership path so another thread
+          # using this instance cannot begin a heartbeat behind this release.
+          @held = false
+          release_unlocked
         end
+      rescue Errno::ENOENT
+        nil
+      ensure
+        @held = false
       end
 
       # Execute a block while holding the lock.
@@ -112,21 +146,104 @@ module Woods
       #
       # @return [Boolean]
       def locked?
-        @held && File.exist?(@lock_path)
+        return false unless @held
+
+        with_path_guard { @held && File.exist?(@lock_path) }
+      rescue SystemCallError
+        false
+      end
+
+      # Refresh the held lock's mtime so a long but healthy run is not mistaken
+      # for a crashed one.
+      #
+      # Staleness is measured from mtime, and nothing was updating it while the
+      # lock was held. A full extraction on a large host app can exceed
+      # `stale_timeout`, at which point any contender retires the lock of a run
+      # that is still going — producing exactly the two-writer clobber the lock
+      # exists to prevent. A holder that outlives the window must therefore say
+      # so periodically.
+      #
+      # No-op unless this instance holds the lock, so a caller can heartbeat
+      # unconditionally.
+      #
+      # @return [Boolean] true when the mtime was refreshed
+      def touch
+        return false unless @held
+
+        with_path_guard do
+          next false unless @held && File.exist?(@lock_path)
+
+          touch_unlocked?
+        end
+      rescue SystemCallError
+        # The lock vanished (retired by a non-cooperating contender, or the
+        # directory went away). The next acquire/release resolves it.
+        false
       end
 
       private
 
-      # Check if the existing lock file is stale.
+      # Remove a lock file this {#acquire} call created but could not finish
+      # writing (INF-7).
       #
-      # @return [Boolean]
-      def stale?
-        return false unless File.exist?(@lock_path)
+      # A write that fails after the O_EXCL create — a full or read-only disk —
+      # would otherwise leave a 0-byte lock: fresh (mtime now, so never stale),
+      # unparseable (so {#lock_ownership} reads +:unknown+ for every process,
+      # including this one), and never released because +@held+ was never set.
+      # That artifact blocks every writer for the whole stale window; {#touch}
+      # was already fixed never to create one.
+      #
+      # Safe unconditionally: O_EXCL proves *this* call created the path, and
+      # the path guard is still held. Errors from the unlink itself are
+      # swallowed so they cannot replace the real failure being re-raised.
+      #
+      # @return [void]
+      def discard_partial_lock
+        File.unlink(@lock_path)
+      rescue SystemCallError
+        nil
+      end
 
-        age = Time.now - File.mtime(@lock_path)
-        age > @stale_timeout
+      def with_path_guard
+        # Ensure the lock directory itself exists — never its parent. A guard
+        # that lived beside @lock_dir needed the parent writable too, which a
+        # deployment that only grants write access to the lock directory
+        # can't satisfy.
+        FileUtils.mkdir_p(@lock_dir)
+        File.open(guard_path, File::RDWR | File::CREAT, 0o600) do |guard|
+          guard.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      # The transaction guard, kept inside the owned lock directory so it
+      # resolves through the same symlink the lock file itself does. A guard
+      # computed from `File.expand_path(lock_dir)` split in two: expand_path
+      # normalizes `.`/`..` but never dereferences a symlink, so a real path
+      # and a symlinked alias of the same directory produced two different
+      # sibling guard files — flocks that never contended, defeating every
+      # TOCTOU protection `with_path_guard` exists to provide. Deriving the
+      # guard from `File.realpath` and placing it inside the directory
+      # resolves both aliases to the identical path, the same way `@lock_path`
+      # already does implicitly by living inside `lock_dir`.
+      #
+      # Memoized: only the first caller (which has just ensured the directory
+      # exists via `mkdir_p`) needs to resolve it; every later access reuses
+      # that resolution rather than re-touching the filesystem.
+      #
+      # @return [String]
+      def guard_path
+        @guard_path ||= File.join(canonical_lock_dir, self.class.guard_filename(@name))
+      end
+
+      # @return [String] the lock directory's real path when it exists,
+      #   falling back to a lexical expansion when it does not — realpath
+      #   requires an existing path and callers must never be made to create
+      #   one just to compute a guard location.
+      def canonical_lock_dir
+        File.realpath(@lock_dir)
       rescue Errno::ENOENT
-        true
+        File.expand_path(@lock_dir)
       end
 
       # Atomically retire a stale lock file via rename. Rename is atomic on
@@ -144,23 +261,116 @@ module Woods
       # fresh (someone beat us to the takeover), we put it back and lose the
       # race instead of clobbering a live holder.
       #
-      # @return [Boolean] true if this process retired a genuinely stale lock
-      def retire_stale_lock
+      # @return [Symbol] `:cleared` when genuinely stale, `:not_stale` when a
+      #   fresher successor was restored instead, `:missing` when the lock
+      #   was already gone
+      def retire_stale_unlocked
         graveyard = "#{@lock_path}.stale.#{Process.pid}.#{SecureRandom.hex(4)}"
         File.rename(@lock_path, graveyard)
 
         unless stale_file?(graveyard)
-          # We grabbed a lock that is no longer stale — a competitor already
-          # took over. Restore it (without clobbering a still-newer holder)
-          # and back off.
-          restore_lock(graveyard)
-          return false
+          restore_lock_unlocked(graveyard)
+          return :not_stale
         end
 
         FileUtils.rm_f(graveyard)
-        true
+        :cleared
       rescue Errno::ENOENT
-        false
+        :missing
+      end
+
+      def release_unlocked
+        # Rename first, then inspect: a plain read-then-unlink is a TOCTOU —
+        # after we read our own token a takeover could replace the file, and
+        # our unlink would then delete the NEW holder's lock. Renaming
+        # atomically captures whatever is at the path.
+        graveyard = "#{@lock_path}.release.#{Process.pid}.#{SecureRandom.hex(4)}"
+        begin
+          File.rename(@lock_path, graveyard)
+        rescue Errno::ENOENT
+          return # already gone
+        end
+
+        if own_lock?(graveyard)
+          FileUtils.rm_f(graveyard)
+        else
+          # We were legitimately taken over — put the successor's lock back
+          # without clobbering a still-newer holder (see
+          # {#restore_lock_unlocked}).
+          restore_lock_unlocked(graveyard)
+        end
+      end
+
+      def touch_unlocked?
+        # Ownership, not just presence. `locked?` asks whether *a* lock file
+        # exists and this instance thinks it holds one — which stays true after
+        # a contender has retired us and put its own lock at the same path. A
+        # retired holder would then refresh the **successor's** mtime, and if
+        # that successor crashed its lock would never age out while the retired
+        # process lived, blocking every writer until it exited.
+        #
+        # That is not hypothetical for a heartbeat: being retired mid-run is the
+        # exact scenario a heartbeat exists to prevent, so it is also the state a
+        # heartbeat is most likely to find itself in when it fails to.
+        #
+        # Clearing @held is the honest response — we do not hold it, and
+        # continuing to believe we do would let `release` act on a lock that is
+        # someone else's.
+        case lock_ownership
+        when :ours
+          # Refresh with `File.utime`, never `FileUtils.touch`: touch CREATES a
+          # missing file, and the lock can vanish between the ownership read
+          # and the refresh — a heartbeat racing its own process's `release` is
+          # the ordinary way. Recreating it leaves an empty 0-byte lock no
+          # process owns and no release will delete, blocking every writer for
+          # the full stale window. `utime` raises ENOENT instead, which the
+          # rescue below turns into the same plain false as any other vanished
+          # lock; the next acquire/release resolves it.
+          now = Time.now
+          File.utime(now, now, @lock_path)
+          true
+        when :foreign
+          # Proven someone else's: stop believing we hold it, or `release` would
+          # act on their lock.
+          @held = false
+          false
+        else
+          # Unreadable — a torn write, most likely. Refuse to refresh, but stay
+          # the owner: "I cannot prove this is mine" is not "this is not mine",
+          # and disowning it here would strand the file. `release` opens with
+          # `return unless @held`, so a disowned lock is never cleaned up and
+          # every writer blocks until the stale window expires.
+          false
+        end
+      end
+
+      # Check if the existing lock file is stale.
+      #
+      # @return [Boolean]
+      def stale?
+        return false unless File.exist?(@lock_path)
+
+        age = Time.now - File.mtime(@lock_path)
+        age > @stale_timeout
+      rescue Errno::ENOENT
+        true
+      end
+
+      # Three-state, deliberately — a boolean here conflates the two states
+      # that need different handling.
+      #
+      # `:unknown` is not `:foreign`. Both refuse a refresh, because touching a
+      # lock we cannot prove is ours would extend a stranger's claim. Only
+      # `:foreign` justifies disowning, because only that means someone else
+      # holds it. Collapsing them made an unreadable-but-ours lock leak: `touch`
+      # cleared `@held`, and `release` returns early on `@held`, so nothing ever
+      # removed the file and every writer blocked for the full stale window.
+      #
+      # @return [Symbol] `:ours`, `:foreign`, or `:unknown`
+      def lock_ownership
+        JSON.parse(File.read(@lock_path))['token'] == @token ? :ours : :foreign
+      rescue JSON::ParserError, SystemCallError
+        :unknown
       end
 
       # Whether the lock file at +path+ carries this instance's token.
@@ -184,7 +394,7 @@ module Woods
       #
       # @param graveyard [String] path of the renamed-aside lock file
       # @return [void]
-      def restore_lock(graveyard)
+      def restore_lock_unlocked(graveyard)
         File.link(graveyard, @lock_path)
       rescue Errno::EEXIST
         # A newer holder already claimed the path — our copy is obsolete.

data/lib/woods/db/migrations/007_typed_snapshot_units.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Woods
+  module Db
+    module Migrations
+      # Preserve the full identity of units sharing a name across extractor types.
+      module TypedSnapshotUnits
+        VERSION = 7
+
+        def self.up(connection)
+          sql = connection.get_first_value("SELECT sql FROM sqlite_master WHERE name = 'woods_snapshot_units'")
+          CreateSnapshotUnits.up(connection) if sql.nil?
+          return if sql&.match?(/UNIQUE\s*\(snapshot_id, identifier, unit_type\)/i)
+
+          connection.transaction do
+            create_table(connection)
+            connection.execute('INSERT INTO woods_snapshot_units_typed SELECT * FROM woods_snapshot_units')
+            connection.execute('DROP TABLE woods_snapshot_units')
+            connection.execute('ALTER TABLE woods_snapshot_units_typed RENAME TO woods_snapshot_units')
+            connection.execute('CREATE INDEX idx_snapshot_units_identifier ON woods_snapshot_units(identifier)')
+            connection.execute('CREATE INDEX idx_snapshot_units_snapshot ON woods_snapshot_units(snapshot_id)')
+          end
+        end
+
+        def self.create_table(connection)
+          connection.execute(<<~SQL)
+            CREATE TABLE woods_snapshot_units_typed (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              snapshot_id INTEGER NOT NULL,
+              identifier TEXT NOT NULL,
+              unit_type TEXT NOT NULL,
+              source_hash TEXT,
+              metadata_hash TEXT,
+              dependencies_hash TEXT,
+              created_at TEXT NOT NULL DEFAULT (datetime('now')),
+              FOREIGN KEY (snapshot_id) REFERENCES woods_snapshots(id),
+              UNIQUE(snapshot_id, identifier, unit_type)
+            )
+          SQL
+        end
+        private_class_method :create_table
+      end
+    end
+  end
+end

data/lib/woods/db/migrator.rb

@@ -7,6 +7,7 @@ require_relative 'migrations/003_create_embeddings'
 require_relative 'migrations/004_create_snapshots'
 require_relative 'migrations/005_create_snapshot_units'
 require_relative 'migrations/006_rename_tables'
+require_relative 'migrations/007_typed_snapshot_units'
 
 module Woods
   module Db
@@ -28,7 +29,8 @@ module Woods
         Migrations::CreateEmbeddings,
         Migrations::CreateSnapshots,
         Migrations::CreateSnapshotUnits,
-        Migrations::RenameTables
+        Migrations::RenameTables,
+        Migrations::TypedSnapshotUnits
       ].freeze
 
       attr_reader :schema_version
@@ -53,14 +55,6 @@ module Woods
         applied
       end
 
-      # List version numbers of pending (unapplied) migrations.
-      #
-      # @return [Array<Integer>]
-      def pending_versions
-        applied = @schema_version.applied_versions
-        MIGRATIONS.map { |m| m::VERSION }.reject { |v| applied.include?(v) }
-      end
-
       private
 
       # @return [Array<Module>] Pending migration modules