woods 2.0.0.beta1 → 2.0.0.beta2

data/lib/woods.rb

@@ -24,6 +24,8 @@
 require_relative 'woods/version'
 # Configuration's `component_paths` default lives with the discovery it feeds.
 require_relative 'woods/extractors/component_discovery'
+# Configuration defaults the cycle caps to the analyzer's own constants.
+require_relative 'woods/graph_analyzer'
 
 module Woods
   class Error < StandardError; end
@@ -146,7 +148,9 @@ module Woods
                   :cache_store, :cache_options,
                   :dump_retention_count, :component_paths
     attr_reader :embedding_model, :max_context_tokens, :similarity_threshold, :extractors, :pretty_json,
-                :context_format, :cache_enabled, :volatile_dependency_ratio
+                :context_format, :cache_enabled, :volatile_dependency_ratio,
+                :graph_cycle_limit, :graph_cycle_max_length,
+                :incremental_blast_radius_depth, :durable_payload_writes
 
     def initialize # rubocop:disable Metrics/MethodLength
       @output_dir = nil # Resolved lazily; Rails.root is nil at require time
@@ -205,6 +209,15 @@ module Woods
       @cache_options = {}     # { redis: client, cache: store, ttl: { embeddings: 86400, ... } }
       @dump_retention_count = 3
       @volatile_dependency_ratio = 3.0
+      @graph_cycle_limit = GraphAnalyzer::DEFAULT_CYCLE_LIMIT
+      @graph_cycle_max_length = GraphAnalyzer::DEFAULT_CYCLE_MAX_LENGTH
+      # nil = the unbounded transitive closure. See the setter for why the
+      # default is not a small number.
+      @incremental_blast_radius_depth = nil
+      # false = payload files are written without a per-file fsync and the
+      # whole payload is flushed once before `generation.json` is written.
+      # See the setter.
+      @durable_payload_writes = false
       # Directories the component extractors walk before reading `descendants`,
       # relative to Rails.root. See Extractors::ComponentDiscovery.
       @component_paths = Extractors::ComponentDiscovery::DEFAULT_COMPONENT_PATHS.dup
@@ -274,6 +287,29 @@ module Woods
       @extractors = value
     end
 
+    # Force an fsync on every payload file as it is written, on top of the
+    # single flush the publish already performs.
+    #
+    # Off by default, and off is not a weaker guarantee. Readers resolve only
+    # through `generation.json`; a payload file has no reader until that
+    # pointer names it, and {Woods::Extractor#sync_payload} makes the whole
+    # payload durable before the pointer is written. Turning this on buys
+    # exactly one thing: an individual payload file being durable before the
+    # pointer exists.
+    #
+    # It costs a lot for it. Two forced flushes per file, 8.9ms each on btrfs:
+    # 8000 units is 71s of writing against 1s.
+    #
+    # Turning it on cannot disable the publish flush. That flush *is* the
+    # durability contract, so it has no opt-out.
+    #
+    # @param value [Boolean]
+    # @raise [Woods::ConfigurationError] when value is not a boolean
+    def durable_payload_writes=(value)
+      validate_boolean!(:durable_payload_writes, value)
+      @durable_payload_writes = value
+    end
+
     # @param value [Boolean] Must be true or false
     # @raise [ConfigurationError] if value is not a boolean
     def pretty_json=(value)
@@ -312,6 +348,46 @@ module Woods
       @volatile_dependency_ratio = value.to_f
     end
 
+    # How many distinct cycles {Woods::GraphAnalyzer#cycles} enumerates before
+    # it stops. `nil` removes the cap and restores exhaustive enumeration.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def graph_cycle_limit=(value)
+      @graph_cycle_limit = validate_optional_positive_integer!(:graph_cycle_limit, value)
+    end
+
+    # The longest cycle {Woods::GraphAnalyzer#cycles} records, in distinct
+    # nodes. `nil` removes the cap.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def graph_cycle_max_length=(value)
+      @graph_cycle_max_length = validate_optional_positive_integer!(:graph_cycle_max_length, value)
+    end
+
+    # How many reverse hops an incremental run walks from a changed file
+    # before it stops re-extracting dependents. `nil` (the default) keeps the
+    # unbounded transitive closure.
+    #
+    # A unit's extracted content is mostly a function of its own source and
+    # its own reflection, so on most graphs a small cap re-extracts the same
+    # bytes far faster. It is not safe everywhere, which is why the default
+    # is unbounded: an STI grandchild reads its grandparent's reflection
+    # (`reflect_on_all_associations`, `_validators` and the callback chain
+    # are all inherited), so `SportsCar < Car < Vehicle` has content that
+    # changes when `Vehicle` changes while sitting two hops away in the
+    # graph. A nested `has_many :through` resolves through the same kind of
+    # chain. Set this only on a tree you know has neither.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def incremental_blast_radius_depth=(value)
+      @incremental_blast_radius_depth = validate_optional_positive_integer!(
+        :incremental_blast_radius_depth, value
+      )
+    end
+
     # Accepted for forward compatibility. Nothing reads {gem_configs}; gem
     # source indexing is not implemented.
     #
@@ -325,6 +401,15 @@ module Woods
 
     private
 
+    # @return [Integer, nil] +value+ when it is nil or a positive Integer
+    # @raise [ConfigurationError] otherwise
+    def validate_optional_positive_integer!(name, value)
+      return value if value.nil?
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ConfigurationError, "#{name} must be a positive Integer or nil, got #{value.inspect}"
+    end
+
     def validate_boolean!(name, value)
       return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: woods
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta1
+  version: 2.0.0.beta2
 platform: ruby
 authors:
 - Leah Armstrong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -435,10 +435,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/lost-in-the/woods
-  source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta1
-  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0.beta1/CHANGELOG.md
+  source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta2
+  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0.beta2/CHANGELOG.md
   bug_tracker_uri: https://github.com/lost-in-the/woods/issues
-  documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta1/docs
+  documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta2/docs
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []