woods 1.6.1 → 2.0.0.beta2

data/lib/woods/mcp/tool_response_renderer.rb

@@ -14,6 +14,13 @@ module Woods
     class ToolResponseRenderer
       VALID_FORMATS = %i[claude markdown plain json].freeze
 
+      # Sections of graph_analysis.json in display order. Shared by the
+      # graph_analysis tool (enum and pagination) and the text renderers.
+      GRAPH_ANALYSIS_SECTIONS = %w[
+        orphans dead_ends hubs cycles bridges
+        cross_database_edges volatile_dependencies undeclared_package_edges
+      ].freeze
+
       # Factory method to build the appropriate renderer for a format.
       #
       # @param format [Symbol] One of :claude, :markdown, :plain, :json

data/lib/woods/model_name_cache.rb

@@ -77,10 +77,28 @@ module Woods
 
       private
 
+      # Abstract models are excluded. `ApplicationRecord` is a descendant of
+      # `ActiveRecord::Base` and its name appears in virtually every model file
+      # (`class User < ApplicationRecord`), so including it in the scan regex
+      # wired a `:code_reference` edge from nearly every model to it — graph
+      # noise that also inflated its PageRank into the top ranks, where it
+      # displaced real hubs in retrieval ranking.
+      #
+      # `abstract_class?` is guarded: a descendant that raises on it (a
+      # half-loaded class under the NameError fallback) is kept rather than
+      # dropped, since a phantom edge is a smaller error than a missing model.
       def compute_model_names
         return [] unless defined?(ActiveRecord::Base)
 
-        ActiveRecord::Base.descendants.filter_map(&:name).uniq
+        ActiveRecord::Base.descendants.reject { |klass| abstract_model?(klass) }.filter_map(&:name).uniq
+      end
+
+      # @param klass [Class]
+      # @return [Boolean] true when the class is an abstract AR base class
+      def abstract_model?(klass)
+        klass.respond_to?(:abstract_class?) && klass.abstract_class?
+      rescue StandardError
+        false
       end
 
       def build_regex

data/lib/woods/notion/client.rb

@@ -9,6 +9,16 @@ require_relative 'rate_limiter'
 
 module Woods
   module Notion
+    # Raised on a 401/403 from the Notion API.
+    #
+    # A distinct class because authentication failure is not a per-unit
+    # problem: a bad or unshared token dooms every remaining call in the run.
+    # Without it the exporter's per-unit rescue recorded one error per unit and
+    # kept going, so a wrong token spent the entire cold sync at Notion's 3
+    # req/sec before reporting failure for everything. Subclasses
+    # {Woods::Error}, so existing `rescue Woods::Error` sites are unaffected.
+    class AuthenticationError < Woods::Error; end
+
     # Thin wrapper around the Notion REST API (v2022-06-28).
     #
     # Uses Net::HTTP (stdlib) for zero external dependencies. All requests are
@@ -25,6 +35,31 @@ module Woods
       MAX_RETRIES = 3
       DEFAULT_TIMEOUT = 30
 
+      # Statuses that mean the credential itself is the problem, so no later
+      # request in this run can succeed either. Response codes arrive as
+      # strings from Net::HTTP.
+      AUTH_STATUS_CODES = %w[401 403].freeze
+
+      # HTTP methods safe to retry after *any* transient network failure —
+      # repeating an idempotent request cannot double-apply an operation.
+      # POST and PATCH are deliberately absent: see {#execute_with_retry}.
+      IDEMPOTENT_METHODS = %i[get put delete head].freeze
+
+      # Network failures that provably occur before the server could have
+      # processed the request (the connection was never established), so a
+      # retry is safe even for non-idempotent verbs.
+      PRE_REQUEST_ERRORS = [Net::OpenTimeout, Errno::ECONNREFUSED].freeze
+
+      # Response codes potentially retried. 429 is safe for every verb — it
+      # means the server throttled the request before processing it. 503 is
+      # NOT unconditionally safe: that status proves the *origin* refused to
+      # process the request, but it can also be synthesized by an
+      # intermediary sitting in front of an origin that already committed
+      # the write, so the response alone doesn't prove non-commitment.
+      # {#request}'s `idempotent:` flag gates the 503 retry accordingly —
+      # see {#execute_with_retry} for the equivalent network-level split.
+      RETRYABLE_STATUS_CODES = %w[429 503].freeze
+
       # @param api_token [String] Notion integration API token
       # @param rate_limiter [RateLimiter] Rate limiter instance (default: 3 req/sec)
       # @raise [ArgumentError] if api_token is nil or empty
@@ -48,7 +83,10 @@ module Woods
         }
         body[:children] = children if children.any?
 
-        request(:post, 'pages', body)
+        # Notion offers no idempotency key for page creation, and a 503 can
+        # be an intermediary's synthesized response for an origin that
+        # already committed — see {#request}.
+        request(:post, 'pages', body, idempotent: false)
       end
 
       # Update an existing page's properties.
@@ -71,32 +109,7 @@ module Woods
         body[:filter] = filter if filter
         body[:sorts] = sorts if sorts
 
-        request(:post, "databases/#{database_id}/query", body)
-      end
-
-      # Query all pages from a database, auto-paginating.
-      #
-      # @param database_id [String] Database UUID
-      # @param filter [Hash, nil] Notion filter object
-      # @return [Array<Hash>] All matching pages
-      def query_all(database_id:, filter: nil)
-        all_results = []
-        cursor = nil
-
-        loop do
-          body = {}
-          body[:filter] = filter if filter
-          body[:start_cursor] = cursor if cursor
-
-          response = request(:post, "databases/#{database_id}/query", body)
-          all_results.concat(response['results'] || [])
-
-          break unless response['has_more']
-
-          cursor = response['next_cursor']
-        end
-
-        all_results
+        request(:post, "databases/#{database_id}/query", body, read_only: true)
       end
 
       # Find a page by its title property value.
@@ -124,17 +137,30 @@ module Woods
       # @param method [Symbol] HTTP method (:post, :patch, :get)
       # @param path [String] API path (appended to BASE_URL)
       # @param body [Hash, nil] Request body
+      # @param idempotent [Boolean] Whether repeating this request cannot
+      #   double-apply the operation. 429 always retries regardless; a 503
+      #   only retries when `idempotent` is true, since a 503 can be an
+      #   intermediary's response for an origin that already committed a
+      #   non-idempotent write (see {RETRYABLE_STATUS_CODES}).
+      # @param read_only [Boolean] Whether this call reads without mutating
+      #   Notion state, independent of HTTP verb — {#query_database} is a
+      #   POST but commits nothing server-side, so a mid-exchange network
+      #   failure is always safe to retry (see {#safe_to_retry?}).
       # @return [Hash] Parsed JSON response
-      # @raise [Woods::Error] on non-success responses (after retries for 429)
-      def request(method, path, body = nil)
+      # @raise [Woods::Error] on non-success responses (after retries for 429,
+      #   and for 503 when idempotent), or immediately for a non-idempotent
+      #   request's 503
+      def request(method, path, body = nil, idempotent: true, read_only: false)
         retries = 0
 
         loop do
-          response = execute_with_retry(method, path, body)
+          response = execute_with_retry(method, path, body, read_only: read_only)
 
           return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
 
-          if response.code == '429' && retries < MAX_RETRIES
+          raise_ambiguous_response_error(method, response) if response.code == '503' && !idempotent
+
+          if RETRYABLE_STATUS_CODES.include?(response.code) && retries < MAX_RETRIES
             retries += 1
             # Retry-After may be an HTTP-date, which .to_f would collapse to
             # 0.0 — honoring it as-is would hammer a throttling server.
@@ -147,24 +173,42 @@ module Woods
         end
       end
 
-      # Execute HTTP with rate limiting and network error retry.
+      # Execute HTTP with rate limiting and verb-aware network error retry.
+      #
+      # Retry classification depends on the verb. Idempotent verbs
+      # ({IDEMPOTENT_METHODS}) retry every transient failure. Non-idempotent
+      # verbs (POST, PATCH) retry only failures that provably happened before
+      # the server could have processed the request ({PRE_REQUEST_ERRORS});
+      # a mid-exchange failure (Net::ReadTimeout, ECONNRESET) raises instead,
+      # because the request may have been fully delivered and committed
+      # server-side before the connection died — retrying a phantom-committed
+      # POST creates a duplicate object. For pages the exporter's
+      # find-then-create upsert catches the duplicate on the *next* run and
+      # updates it in place, but a duplicated database has no such
+      # reconciliation, so a blind retry here is silent, permanent
+      # duplication in the workspace.
       #
       # Any message from an underlying network error is run through
       # {#redact_token} before being re-raised — a malformed reflected
       # URL or request dump from the stdlib must not leak the bearer
       # token into logs or backtraces.
       #
+      # @param method [Symbol] HTTP method, used to classify retryability
+      # @param read_only [Boolean] see {#request}
       # @return [Net::HTTPResponse]
-      # @raise [Woods::Error] on persistent network failures
-      def execute_with_retry(method, path, body)
+      # @raise [Woods::Error] on persistent network failures, or immediately
+      #   when a non-idempotent request fails ambiguously mid-exchange
+      def execute_with_retry(method, path, body, read_only: false)
         attempts = 0
         begin
           @rate_limiter.throttle { execute_http(method, path, body) }
         rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED => e
+          raise_ambiguous_network_error(method, e) unless safe_to_retry?(method, e, read_only: read_only)
+
           attempts += 1
           if attempts >= MAX_RETRIES
             raise Woods::Error,
-                  "Network error after #{attempts} retries: #{redact_token(e.message)}"
+                  "Network error after #{attempts} attempts: #{redact_token(e.message)}"
           end
 
           sleep(2**attempts)
@@ -172,6 +216,57 @@ module Woods
         end
       end
 
+      # Whether a failed request may be retried without risking a
+      # double-apply: the call is a read regardless of verb, the verb
+      # itself is idempotent, or the failure class proves the request
+      # never reached the server.
+      #
+      # @param method [Symbol] HTTP method
+      # @param error [Exception] the network failure
+      # @param read_only [Boolean] see {#request}
+      # @return [Boolean]
+      def safe_to_retry?(method, error, read_only: false)
+        read_only || IDEMPOTENT_METHODS.include?(method) || PRE_REQUEST_ERRORS.any? { |klass| error.is_a?(klass) }
+      end
+
+      # Raise for a non-idempotent request that failed mid-exchange. The
+      # request may have been committed server-side before the failure, so
+      # the operator must verify workspace state before re-running rather
+      # than have the client silently duplicate the write.
+      #
+      # @param method [Symbol] HTTP method
+      # @param error [Exception] the ambiguous network failure
+      # @raise [Woods::Error] always
+      def raise_ambiguous_network_error(method, error)
+        raise Woods::Error,
+              "#{method.to_s.upcase} request interrupted mid-exchange (#{error.class}); " \
+              'the operation may or may not have been applied server-side. ' \
+              "Not retrying automatically to avoid duplicates; verify before re-running: #{redact_token(error.message)}"
+      end
+
+      # Raise for a non-idempotent request that received a 503. The response
+      # doesn't prove the origin never processed the request — an
+      # intermediary can synthesize a 503 for a request the origin already
+      # committed — so this mirrors {#raise_ambiguous_network_error}: same
+      # error class, same "verify before re-running" guidance, because the
+      # risk (a silently duplicated create) is identical.
+      #
+      # @param method [Symbol] HTTP method
+      # @param response [Net::HTTPResponse] the 503 response
+      # @raise [Woods::Error] always
+      def raise_ambiguous_response_error(method, response)
+        parsed = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          {}
+        end
+        detail = parsed['message'] || 'Service Unavailable'
+        raise Woods::Error,
+              "#{method.to_s.upcase} request received 503 (#{redact_token(detail)}); " \
+              'the operation may or may not have been applied server-side. ' \
+              'Not retrying automatically to avoid duplicates; verify before re-running.'
+      end
+
       # Raise a descriptive error from a non-success Notion response.
       # The response body is scrubbed before being formatted into the
       # exception — if the Notion API ever echoes back a header (or a
@@ -185,7 +280,8 @@ module Woods
           { 'message' => "Unparseable response body: #{response.body&.slice(0, 200)}" }
         end
         message = parsed['message'] || 'Unknown error'
-        raise Woods::Error,
+        error_class = AUTH_STATUS_CODES.include?(response.code) ? AuthenticationError : Woods::Error
+        raise error_class,
               "Notion API error #{response.code}: #{redact_token(message)}"
       end