woods 1.6.1 → 2.0.0.beta2

data/lib/woods/path_dispatcher.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Woods
+  # Resolves a changed file path to the extraction work it implies.
+  #
+  # The incremental path used to route changes purely through
+  # {DependencyGraph#affected_by}, which resolves a path via the graph's
+  # file map — a map populated only from *already-registered* units. A file
+  # that did not exist at the last extraction therefore routed nowhere and
+  # was silently ignored (#164, gap 1). This class supplies the missing
+  # direction: path → extractor, for files the index has never seen.
+  #
+  # Two rule sets:
+  #
+  # * {.file_rules} — file-based extractors, whose per-file method can be
+  #   pointed straight at the new path.
+  # * {.whole_app_rules} — extractors with no per-file entry point (routes,
+  #   middleware, engines, scheduled jobs, state machines, factories,
+  #   events, framework sources). Their trigger paths map to a wholesale
+  #   re-run of that extractor, which is cheap in an already-booted process.
+  #
+  # Class-based extractors (models, controllers, mailers, components,
+  # channels) are deliberately *absent* here. They are reconciled against
+  # their own runtime discovery sets instead (see
+  # {Extractor#reconcile_class_based_types}), which is exact by construction
+  # and needs no path-to-constant guessing.
+  #
+  # Rules are built lazily and memoized: they reference the directory
+  # constants owned by each extractor, so a directory added to (say)
+  # +ServiceExtractor::SERVICE_DIRECTORIES+ flows into dispatch without a
+  # second edit here.
+  #
+  # @example
+  #   Woods::PathDispatcher.new.file_rules_for('app/services/checkout.rb')
+  #   # => [#<Rule extractor_key=:services method_name=:extract_service_file ...>]
+  #
+  class PathDispatcher # rubocop:disable Metrics/ClassLength
+    # A single path → extraction mapping.
+    #
+    # @!attribute extractor_key
+    #   @return [Symbol] key into {Extractor::EXTRACTORS}
+    # @!attribute method_name
+    #   @return [Symbol] per-file extraction method (file rules only)
+    # @!attribute dirs
+    #   @return [Array<String>] Rails.root-relative directory prefixes
+    # @!attribute extensions
+    #   @return [Array<String>, nil] required filename suffixes (nil = any)
+    # @!attribute exclude
+    #   @return [Array<String>, nil] path substrings that disqualify a match
+    # @!attribute require_segment
+    #   @return [String, nil] path substring that must be present
+    # @!attribute recursive
+    #   @return [Boolean] false to match only files directly inside +dirs+
+    # @!attribute exact_paths
+    #   @return [Array<String>, nil] exact relative paths that match
+    # @!attribute basenames
+    #   @return [Array<String>, nil] file basenames that match anywhere under Rails.root (honors +exclude+)
+    Rule = Struct.new(
+      :extractor_key, :method_name, :dirs, :extensions, :exclude,
+      :require_segment, :recursive, :exact_paths, :basenames,
+      keyword_init: true
+    ) do
+      # @param relative_path [String] Rails.root-relative path
+      # @return [Boolean]
+      def matches?(relative_path)
+        return true if exact_paths&.include?(relative_path)
+        return basename_match?(relative_path) if basenames
+
+        filters_pass?(relative_path) && under_a_directory?(relative_path)
+      end
+
+      private
+
+      def basename_match?(relative_path)
+        basenames.include?(File.basename(relative_path)) &&
+          exclude.to_a.none? { |segment| relative_path.include?(segment) }
+      end
+
+      def filters_pass?(relative_path)
+        (extensions.nil? || extensions.any? { |ext| relative_path.end_with?(ext) }) &&
+          exclude.to_a.none? { |segment| relative_path.include?(segment) } &&
+          (require_segment.nil? || relative_path.include?(require_segment))
+      end
+
+      def under_a_directory?(relative_path)
+        dirs.to_a.any? do |dir|
+          next false unless relative_path.start_with?("#{dir}/")
+
+          recursive == false ? File.dirname(relative_path) == dir : true
+        end
+      end
+    end
+
+    class << self
+      # Rules for extractors with a per-file entry point.
+      #
+      # @return [Array<Rule>]
+      def file_rules
+        @file_rules ||= build_file_rules.freeze
+      end
+
+      # Rules for extractors that must be re-run wholesale.
+      #
+      # @return [Array<Rule>]
+      def whole_app_rules
+        @whole_app_rules ||= build_whole_app_rules.freeze
+      end
+
+      # Drop memoized rules. Used by specs that stub extractor constants.
+      #
+      # @return [void]
+      def reset!
+        @file_rules = nil
+        @whole_app_rules = nil
+      end
+
+      private
+
+      def build_file_rules
+        plain_ruby_rules + specialized_rules + caching_rules
+      end
+
+      # Extractors that glob `**/*.rb` under directories they own.
+      def plain_ruby_rules
+        ex = Woods::Extractors
+
+        [
+          [:services, :extract_service_file, ex::ServiceExtractor::SERVICE_DIRECTORIES],
+          [:jobs, :extract_job_file, ex::JobExtractor::JOB_DIRECTORIES],
+          [:serializers, :extract_serializer_file, ex::SerializerExtractor::SERIALIZER_DIRECTORIES],
+          [:managers, :extract_manager_file, ex::ManagerExtractor::MANAGER_DIRECTORIES],
+          [:policies, :extract_policy_file, ex::PolicyExtractor::POLICY_DIRECTORIES],
+          [:validators, :extract_validator_file, ex::ValidatorExtractor::VALIDATOR_DIRECTORIES],
+          [:pundit_policies, :extract_pundit_file, ex::PunditExtractor::PUNDIT_DIRECTORIES],
+          [:decorators, :extract_decorator_file, ex::DecoratorExtractor::DECORATOR_DIRECTORIES],
+          [:configurations, :extract_configuration_file, ex::ConfigurationExtractor::CONFIG_DIRECTORIES]
+        ].map { |key, method_name, dirs| file_rule(key, method_name, dirs) }
+      end
+
+      # Extractors with a narrower or wider surface than "*.rb under my dirs".
+      def specialized_rules
+        ex = Woods::Extractors
+
+        [
+          # ConcernExtractor globs app/**/concerns, not just the two canonical
+          # directories — match any .rb under app/ inside a concerns/ segment.
+          file_rule(:concerns, :extract_concern_file, %w[app], require_segment: '/concerns/'),
+          # GraphQL types sit outside FILE_BASED (they share one extractor
+          # method across four unit types via GRAPHQL_TYPES), which is exactly
+          # why the FILE_BASED-driven coverage guard never noticed they had no
+          # rule: a *new* type/mutation/resolver routed nowhere and never
+          # entered the index — the same failure #164 gap 1 exists to close.
+          file_rule(:graphql, :extract_graphql_file,
+                    [ex::GraphQLExtractor::GRAPHQL_DIRECTORY], extensions: %w[.rb]),
+          file_rule(:i18n, :extract_i18n_file, ex::I18nExtractor::I18N_DIRECTORIES, extensions: %w[.yml]),
+          file_rule(:rake_tasks, :extract_rake_file, ex::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake]),
+          file_rule(:view_templates, :extract_view_template_file,
+                    ex::ViewTemplateExtractor::VIEW_DIRECTORIES, extensions: view_template_extensions),
+          file_rule(:migrations, :extract_migration_file, %w[db/migrate], recursive: false),
+          # POROs are app/models classes that are *not* ActiveRecord models;
+          # the extractor makes that call itself given ar_names.
+          file_rule(:poros, :extract_poro_file, %w[app/models], exclude: %w[/concerns/]),
+          file_rule(:libs, :extract_lib_file, %w[lib], exclude: ex::LibExtractor::EXCLUDED_SEGMENTS),
+          file_rule(:test_mappings, :extract_test_file, %w[spec], extensions: %w[_spec.rb]),
+          file_rule(:test_mappings, :extract_test_file, %w[test], extensions: %w[_test.rb])
+        ]
+      end
+
+      # CachingExtractor scans three separate globs with different extensions.
+      def caching_rules
+        Woods::Extractors::CachingExtractor::SCAN_PATTERNS.map do |_file_type, pattern|
+          dir, glob = pattern.split('/**/', 2)
+          file_rule(:caching, :extract_caching_file, [dir], extensions: [glob.delete_prefix('*')])
+        end
+      end
+
+      def view_template_extensions
+        Woods::Extractors::ViewTemplateExtractor::ENGINES.flat_map { |k| k.new.extensions }.uniq
+      end
+
+      def build_whole_app_rules
+        [
+          whole_app_rule(:routes, %w[config/routes], exact_paths: %w[config/routes.rb]),
+          whole_app_rule(:engines, %w[config/routes], exact_paths: %w[config/routes.rb Gemfile.lock]),
+          whole_app_rule(:middleware, %w[config/initializers config/environments],
+                         exact_paths: %w[config/application.rb Gemfile.lock]),
+          whole_app_rule(:scheduled_jobs, [],
+                         exact_paths: Woods::Extractors::ScheduledJobExtractor::SCHEDULE_FILES.keys),
+          whole_app_rule(:state_machines, Woods::Extractors::StateMachineExtractor::MODEL_DIRECTORIES,
+                         extensions: %w[.rb]),
+          whole_app_rule(:factories, Woods::Extractors::FactoryExtractor::FACTORY_DIRECTORIES,
+                         extensions: %w[.rb]),
+          whole_app_rule(:database_views, %w[db/views], extensions: %w[.sql]),
+          # EventExtractor is a two-pass scan over all of app/ — any Ruby
+          # change can add or remove a publish/subscribe site.
+          whole_app_rule(:events, Woods::Extractors::EventExtractor::APP_DIRECTORIES, extensions: %w[.rb]),
+          # Framework/gem sources are a function of the installed dependency
+          # set, so the lockfile is their one honest trigger (#169). The
+          # `include_framework_sources` gate lives in the extractor
+          # (Extractor#skip_by_configuration?), not here: rules are memoized
+          # per-process while configuration can change, and `relevant?` is
+          # correct either way because Gemfile.lock already triggers
+          # :engines and :middleware.
+          whole_app_rule(:rails_source, [], exact_paths: %w[Gemfile.lock]),
+          # Packwerk boundaries: a package.yml anywhere re-runs the package
+          # extractor wholesale (#280). Vendored and generated trees are the
+          # same ones packwerk excludes by default.
+          whole_app_rule(:packages, [],
+                         basenames: [Woods::Extractors::PackageExtractor::PACKAGE_FILE,
+                                     Woods::Extractors::PackageExtractor::PACKWERK_CONFIG],
+                         exclude: %w[node_modules/ vendor/ tmp/ bin/ script/])
+        ]
+      end
+
+      # File-based extractors glob `**/*.rb` unless they say otherwise, so
+      # that is the default extension filter here too.
+      def file_rule(key, method_name, dirs, **opts)
+        opts[:extensions] ||= %w[.rb]
+        Rule.new(extractor_key: key, method_name: method_name, dirs: Array(dirs), **opts)
+      end
+
+      def whole_app_rule(key, dirs, **opts)
+        Rule.new(extractor_key: key, method_name: nil, dirs: Array(dirs), **opts)
+      end
+    end
+
+    # File-based rules matching a path.
+    #
+    # @param relative_path [String] Rails.root-relative path
+    # @return [Array<Rule>]
+    def file_rules_for(relative_path)
+      self.class.file_rules.select { |rule| rule.matches?(relative_path) }
+    end
+
+    # Extractor keys whose whole-app re-run is triggered by a path.
+    #
+    # @param relative_path [String] Rails.root-relative path
+    # @return [Array<Symbol>]
+    def whole_app_keys_for(relative_path)
+      self.class.whole_app_rules
+          .select { |rule| rule.matches?(relative_path) }
+          .map(&:extractor_key).uniq
+    end
+
+    # Does this path imply any extraction work at all?
+    #
+    # Used to filter a raw git diff down to paths worth handing to
+    # {Extractor#extract_changed}. It is deliberately derived from the rules
+    # rather than from a second hand-maintained pattern list — the two would
+    # drift, and a path the filter drops is a path that never reaches the
+    # index no matter how good the dispatch behind it is.
+    #
+    # Paths under `app/` are relevant even without a rule match: class-based
+    # types are discovered from runtime descendants, not from the path.
+    #
+    # @param relative_path [String] Rails.root-relative path
+    # @return [Boolean]
+    def relevant?(relative_path)
+      return true if relative_path.start_with?('app/') && relative_path.end_with?('.rb')
+
+      file_rules_for(relative_path).any? || whole_app_keys_for(relative_path).any?
+    end
+
+    # Extractor keys whose whole-app re-run is triggered by any path in a set.
+    #
+    # @param relative_paths [Enumerable<String>]
+    # @return [Set<Symbol>]
+    def whole_app_keys_for_all(relative_paths)
+      relative_paths.each_with_object(Set.new) do |path, keys|
+        whole_app_keys_for(path).each { |key| keys.add(key) }
+      end
+    end
+  end
+end

data/lib/woods/payload_store.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'fileutils'
+require 'find'
+
+module Woods
+  # Writer-side owner of the per-generation payload directories.
+  #
+  # An index published flat is a directory of independently-written files, so a
+  # reader refreshing mid-publish can load a unit from generation N+1 beside a
+  # graph from N. Publishing each generation's payload into its own immutable
+  # directory and naming that directory from +generation.json+ makes the single
+  # atomic write of that one file the commit point for the whole payload.
+  #
+  # The reader half resolves the pointer ({Woods::MCP::IndexReader#payload_dir});
+  # this is the half that builds what it points at.
+  #
+  # @example Publishing a generation
+  #   payloads = Woods::PayloadStore.new(output_dir)
+  #   dir = payloads.create(next_generation)
+  #   payloads.clone(payloads.path_for(current_generation), dir)  # incremental
+  #   # ... write the run's changes into `dir` ...
+  #   generation.bump!(reason: 'incremental', payload: Woods::PayloadStore.name_for(next_generation))
+  #   payloads.prune(keep: 3, protect: next_generation)
+  #
+  class PayloadStore
+    DIRNAME = 'payloads'
+
+    # How many payload generations to retain, overridable per host via
+    # WOODS_PAYLOAD_RETENTION (read by Extractor#payload_retention). Three is
+    # the current generation plus two a pinned reader might still be inside.
+    DEFAULT_RETENTION = 3
+
+    # @param output_dir [String, Pathname] index output directory
+    def initialize(output_dir)
+      @root = Pathname.new(output_dir.to_s)
+    end
+
+    # @return [Pathname] the directory holding every generation's payload
+    def root
+      @root.join(DIRNAME)
+    end
+
+    # The pointer a {Woods::Generation} carries for a generation's payload.
+    #
+    # Relative to the output directory by contract: the reader resolves it
+    # against its own index root, which is not the absolute path the writer
+    # used whenever the index is read through a volume mount.
+    #
+    # @param number [Integer] generation number
+    # @return [String]
+    def self.name_for(number)
+      "#{DIRNAME}/gen-#{number}"
+    end
+
+    # @param number [Integer] generation number
+    # @return [Pathname] where that generation's payload lives (may not exist)
+    def path_for(number)
+      @root.join(self.class.name_for(number))
+    end
+
+    # Create the payload directory for a generation and return it.
+    #
+    # An existing directory is **emptied** rather than reused. It can only be
+    # there because an earlier run built a payload and then failed before
+    # bumping the generation — nothing points at it, and merging this run's
+    # files into that run's leftovers publishes a mixture of the two.
+    #
+    # @param number [Integer] generation number this payload will be published as
+    # @return [Pathname]
+    def create(number)
+      dir = path_for(number)
+      FileUtils.rm_rf(dir.to_s)
+      FileUtils.mkdir_p(dir.to_s)
+      dir
+    end
+
+    # Populate +target+ with the contents of +source+ using hardlinks.
+    #
+    # This is what makes publishing a whole payload per generation affordable
+    # on an incremental run: an unchanged file costs a directory entry rather
+    # than a copy.
+    #
+    # It is safe **only because every writer against a payload goes through
+    # {Woods::AtomicFile}**, which renames a fresh tempfile over the path. A
+    # rename replaces the directory entry and leaves the old inode alone, so
+    # the previous generation keeps its bytes. A bare +File.write+ to a cloned
+    # path would edit the inode both generations share and corrupt the one a
+    # reader is still pinned to.
+    #
+    # A missing source is a no-op — the first payload has nothing to clone.
+    #
+    # @param source [Pathname, String] the previous generation's payload
+    # @param target [Pathname, String] a directory returned by {#create}
+    # @return [void]
+    def clone(source, target)
+      from = Pathname.new(source.to_s)
+      return unless from.directory?
+
+      to = Pathname.new(target.to_s)
+      # The one directory `find` never offers: it yields the root as `.`, and
+      # a caller seeding a subtree (Extractor#seed_payload_from_flat_root)
+      # passes a target that does not exist yet.
+      FileUtils.mkdir_p(to.to_s)
+      from.find do |entry|
+        relative = entry.relative_path_from(from)
+        next if relative.to_s == '.'
+
+        replicate(entry, to.join(relative))
+      end
+    end
+
+    # Remove superseded payload directories, newest-first.
+    #
+    # +protect+ is never removed however the count works out: it is the
+    # generation +generation.json+ names, and removing it would leave every
+    # reader resolving a stale pointer back to the flat root.
+    #
+    # A directory numbered ABOVE +protect+ cannot be a generation still
+    # ahead of us in a legitimate history — the counter only advances by
+    # bumping past the currently published number — so it can only be a
+    # leftover from before `generation.json` was lost and the counter
+    # restarted lower. `sort.last(keep)` would otherwise read those stale
+    # high numbers as "newest" and retain them forever while pruning the
+    # genuinely-previous generation, so they are always removed regardless
+    # of +keep+; ordinary retention then applies only to +protect+ and
+    # below.
+    #
+    # Directories that do not parse as a generation payload are left alone —
+    # retention only owns what it created.
+    #
+    # @param keep [Integer] how many payload generations to retain
+    # @param protect [Integer] the currently published generation number
+    # A reader pins a payload by holding a shared advisory lock on its
+    # +manifest.json+. Retention takes the same file's exclusive lock without
+    # waiting and skips the generation when another process is still reading
+    # it. The operating system releases the shared lock if a reader crashes,
+    # so there are no PID leases to expire and no stale marker to guess at.
+    # The next publish retries every skipped generation normally.
+    #
+    # The manifest is the lock target rather than a reader-created sidecar so
+    # the Index MCP remains a read-only consumer and payloads written before
+    # this protocol remain protectable. Each published generation has its own
+    # manifest inode: writers replace a cloned manifest through AtomicFile
+    # before publishing, preserving generation-local lock identity.
+    #
+    # @return [Array<Integer>] the generation numbers removed
+    def prune(keep:, protect:)
+      return [] unless root.directory?
+
+      eligible, superseded = generation_dirs.partition { |number, _| number <= protect }
+      retained = eligible.map(&:first).sort.last(keep)
+      prunable = eligible.reject { |number, _| number == protect || retained.include?(number) }
+
+      remove_generation_dirs(superseded + prunable)
+    end
+
+    # Hardlink where the filesystem allows it, copy where it does not — a
+    # payload spanning a device boundary (a bind mount inside the output
+    # directory) must still publish, just without the saving.
+    #
+    # Public so a caller seeding a payload from something other than
+    # {#clone} — {Woods::Extractor#seed_payload_from_flat_root}, which walks
+    # an allowlist of flat-root entries rather than a whole directory tree —
+    # gets the same cross-device fallback. A bare +FileUtils.ln+ there raised
+    # on every run on a filesystem that disallows hardlinks (e.g. some
+    # overlay/bind-mount setups), degrading every run to a flat publish and
+    # never once giving the fallback a chance to run.
+    #
+    # @param source [Pathname, String] file to link or copy
+    # @param destination [Pathname, String] where it should land
+    # @return [void]
+    def link_or_copy(source, destination)
+      FileUtils.ln(source.to_s, destination.to_s)
+    rescue Errno::EXDEV, Errno::EPERM, Errno::EMLINK, NotImplementedError
+      FileUtils.cp(source.to_s, destination.to_s)
+    end
+
+    private
+
+    # @param pairs [Array<Array(Integer, Pathname)>]
+    # @return [Array<Integer>] the generation numbers removed
+    def remove_generation_dirs(pairs)
+      pairs.filter_map { |number, dir| remove_generation_dir(number, dir) }
+    end
+
+    # @return [Integer, nil] the removed generation, or nil while pinned
+    def remove_generation_dir(number, dir)
+      manifest = dir.join('manifest.json')
+      return remove_unlocked_generation(number, dir) unless manifest.file?
+
+      File.open(manifest.to_s, File::RDONLY) do |file|
+        return nil unless file.flock(File::LOCK_EX | File::LOCK_NB)
+
+        remove_unlocked_generation(number, dir)
+      end
+    rescue Errno::ENOENT
+      # An incomplete/orphaned payload has no readable contract a reader can
+      # pin. Retention still owns and may remove that directory.
+      remove_unlocked_generation(number, dir)
+    end
+
+    # @return [Integer]
+    def remove_unlocked_generation(number, dir)
+      FileUtils.rm_rf(dir.to_s)
+      number
+    end
+
+    # @return [Array<Array(Integer, Pathname)>]
+    def generation_dirs
+      root.children.filter_map do |child|
+        match = child.directory? ? child.basename.to_s.match(/\Agen-(\d+)\z/) : nil
+        [match[1].to_i, child] if match
+      end
+    end
+
+    # `Pathname#find` is a pre-order walk: a directory is always visited
+    # before anything inside it. So the directory branch has already created
+    # every parent a file could need, and the `mkdir_p` the file branch used
+    # to run was one stat-heavy syscall chain per unit re-proving what the
+    # previous entry established. On a payload of 8000+ files that was the
+    # bulk of the incremental seed.
+    #
+    # @param entry [Pathname] source entry, as `find` yielded it
+    # @param destination [Pathname] where it belongs in the target
+    # @return [void]
+    def replicate(entry, destination)
+      if entry.directory?
+        FileUtils.mkdir_p(destination.to_s)
+      else
+        link_or_copy(entry, destination)
+      end
+    end
+  end
+end

data/lib/woods/published_index/edge_shaper.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Woods
+  class PublishedIndex
+    # Turns raw `dependency_graph.json` data into the flat, uniform edge shape
+    # {PublishedIndex#edges} returns: `{ from:, to:, via:, through:,
+    # through_db:, disable_joins: }`.
+    #
+    # Pulled out of {PublishedIndex} itself because this walk is pure data
+    # shaping with no dependency on the pinned generation or its retention
+    # lock; keeping it separate is what lets the surrounding class stay under
+    # `Metrics/ClassLength` without an exclude entry.
+    module EdgeShaper
+      # Every forward edge in the graph: primary nodes and variants alike. An
+      # identifier shared by more than one type contributes one edge per
+      # owning type, two edges are never folded into one just because they
+      # look alike once reduced to this shape.
+      #
+      # @param graph [Hash] raw dependency graph data
+      #   ({Woods::MCP::IndexReader#raw_graph_data})
+      # @return [Array<Hash>] `{ from:, to:, via:, through:, through_db:, disable_joins: }`
+      def self.call(graph)
+        primary = (graph['edges'] || {}).flat_map { |from, list| Array(list).map { |raw| edge_hash(from, raw) } }
+        primary + variant_edges(graph)
+      end
+
+      # Edges owned by a type recorded only in the graph's `variants` section:
+      # an identifier that names units of more than one type keeps its other
+      # types' out-edges there, since the primary `edges` map holds only one
+      # type's edges per identifier.
+      #
+      # @param graph [Hash] raw dependency graph data
+      # @return [Array<Hash>]
+      def self.variant_edges(graph)
+        variant_records(graph).flat_map do |record|
+          Array(record['edges']).map { |raw| edge_hash(record['identifier'], raw) }
+        end
+      end
+
+      # @param graph [Hash] raw dependency graph data
+      # @return [Array<Hash>] entries from `variants` that name an identifier
+      def self.variant_records(graph)
+        Array(graph['variants']).select { |record| record.is_a?(Hash) && record['identifier'] }
+      end
+
+      # @param from [String]
+      # @param raw [String, Hash] a bare target (pre-via graphs) or an edge hash
+      # @return [Hash]
+      def self.edge_hash(from, raw)
+        if raw.is_a?(Hash)
+          { from: from, to: raw['target'], via: raw['via'], through: raw['through'],
+            through_db: raw['through_db'], disable_joins: raw['disable_joins'] == true }
+        else
+          { from: from, to: raw.to_s, via: nil, through: nil, through_db: nil, disable_joins: false }
+        end
+      end
+
+      private_class_method :variant_edges, :variant_records, :edge_hash
+    end
+  end
+end

data/lib/woods/published_index/generation_catalog.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Woods
+  class PublishedIndex
+    # Resolves `generation.json` and enumerates published `payloads/gen-N`
+    # directories.
+    #
+    # Split out of {PublishedIndex} because this is pure pointer and
+    # directory inspection: it never touches an open reader or its retention
+    # lock, and keeping it separate is what lets {PublishedIndex} itself stay
+    # under `Metrics/ClassLength` without an exclude entry.
+    module GenerationCatalog
+      # The published generation pointer, distinguishing "no pointer file"
+      # (a flat index, where {Woods::Generation::UNPUBLISHED} is the honest
+      # answer) from "a pointer file that will not parse" (a corrupt install,
+      # which {Woods::Generation#current} silently maps to that same
+      # UNPUBLISHED sentinel). Only this method's caller has already checked
+      # which one it is, so only here can the two be told apart.
+      #
+      # @param root [Pathname]
+      # @return [Woods::Generation::Marker]
+      # @raise [PublishedIndex::CorruptPointerError] when the file exists but will not parse
+      def self.pointer(root)
+        generation = Woods::Generation.new(output_dir: root)
+        return Woods::Generation::UNPUBLISHED unless File.exist?(generation.path)
+
+        marker = generation.current
+        return marker unless marker.equal?(Woods::Generation::UNPUBLISHED)
+
+        raise PublishedIndex::CorruptPointerError, "Unreadable generation pointer: #{generation.path}"
+      end
+
+      # Published generation numbers, ascending. See
+      # {PublishedIndex.available_generations} for what "published" means.
+      #
+      # @param root [Pathname]
+      # @return [Array<Integer>]
+      # @raise [PublishedIndex::CorruptPointerError] when `generation.json` exists but will not parse
+      def self.available(root)
+        marker = pointer(root)
+        return [] if marker.number.zero?
+
+        payloads = Woods::PayloadStore.new(root)
+        return [] unless payloads.root.directory?
+
+        payloads.root.children.filter_map { |child| published_number(child, marker.number) }.sort
+      end
+
+      # A directory's generation number, when it qualifies as published:
+      # named `gen-<N>` for N at or below +pointer+, holding a
+      # `manifest.json`.
+      #
+      # @param child [Pathname]
+      # @param pointer [Integer] the currently published generation number
+      # @return [Integer, nil]
+      def self.published_number(child, pointer)
+        return nil unless child.directory?
+
+        match = child.basename.to_s.match(/\Agen-(\d+)\z/)
+        return nil unless match
+
+        number = match[1].to_i
+        return nil if number > pointer
+        return nil unless child.join('manifest.json').file?
+
+        number
+      end
+
+      private_class_method :published_number
+    end
+  end
+end