woods 1.1.0 → 1.3.0

data/lib/woods/unblocked/document_builder.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+module Woods
+  module Unblocked
+    # Converts extracted unit JSON into condensed Markdown documents
+    # optimized for Unblocked's code review and Q&A context.
+    #
+    # Each unit type has a specialized formatting strategy that emphasizes
+    # what matters for code review: associations, blast radius, entry points,
+    # side effects, and structural complexity.
+    #
+    # @example
+    #   builder = DocumentBuilder.new(repo_url: "https://github.com/acme/myapp")
+    #   doc = builder.build(unit_data)
+    #   # => { title: "Order (model)", body: "# Order (model)\n...", uri: "https://..." }
+    #
+    class DocumentBuilder
+      # @param repo_url [String] GitHub repo base URL for citation URIs
+      def initialize(repo_url:)
+        @repo_url = repo_url.chomp('/')
+      end
+
+      # Build a document hash from a unit's extracted data.
+      #
+      # @param unit_data [Hash] Parsed unit JSON (from IndexReader)
+      # @return [Hash] { title:, body:, uri: }
+      def build(unit_data)
+        type = unit_data['type']
+        identifier = unit_data['identifier']
+        file_path = unit_data['file_path']
+
+        {
+          title: "#{identifier} (#{type})",
+          body: build_body(unit_data),
+          uri: build_uri(file_path)
+        }
+      end
+
+      private
+
+      def build_uri(file_path)
+        return @repo_url unless file_path
+
+        "#{@repo_url}/blob/main/#{file_path}"
+      end
+
+      def build_body(unit_data)
+        type = unit_data['type']
+        body = case type
+               when 'model' then build_model_body(unit_data)
+               when 'controller' then build_controller_body(unit_data)
+               when 'service', 'job', 'mailer', 'manager', 'decorator', 'concern'
+                 build_generic_body(unit_data)
+               when 'graphql', 'graphql_type', 'graphql_mutation', 'graphql_resolver', 'graphql_query'
+                 build_graphql_body(unit_data)
+               else build_generic_body(unit_data)
+               end
+        # Defensive credential scrub — current builders only emit structured
+        # metadata, but if a future formatter adds source_code or comments
+        # (mirroring Notion's `ModelMapper#extract_description`) the scrub
+        # keeps credential material from reaching Unblocked.
+        redact_credentials(body)
+      end
+
+      # Run the assembled body through CredentialScanner. Fails closed (empty
+      # body) if the scanner raises, so a shipping failure never leaks
+      # unredacted content.
+      #
+      # @param body [String]
+      # @return [String]
+      def redact_credentials(body)
+        return body if body.nil? || body.empty?
+
+        require 'woods/console/credential_scanner'
+        redacted, _counts = credential_scanner.scan(body)
+        redacted
+      rescue StandardError
+        ''
+      end
+
+      def credential_scanner
+        @credential_scanner ||= Woods::Console::CredentialScanner.new
+      end
+
+      # ── Model formatting ─────────────────────────────────────────────
+
+      def build_model_body(unit)
+        meta = unit['metadata'] || {}
+        sections = []
+
+        sections << model_header(unit, meta)
+        sections << model_associations(meta)
+        sections << model_dependents(unit)
+        sections << model_entry_points(unit)
+        sections << model_schema_highlights(meta)
+        sections << model_side_effects(unit)
+
+        sections.compact.join("\n\n")
+      end
+
+      def model_header(unit, meta)
+        parts = ["# #{unit['identifier']} (model)"]
+        file_info = ["**File:** `#{unit['file_path']}`"]
+        file_info << "**LOC:** #{meta['loc']}" if meta['loc']
+        file_info << "**Table:** #{meta['table_name']}" if meta['table_name']
+        column_count = meta['column_count'] || (meta['columns'] || []).size
+        file_info << "(#{column_count} columns)" if column_count&.positive?
+        parts << file_info.join(' | ')
+        parts.join("\n")
+      end
+
+      def model_associations(meta)
+        assocs = meta['associations'] || []
+        return nil if assocs.empty?
+
+        grouped = assocs.group_by { |a| a['type'] }
+        lines = ["## Associations (#{assocs.size})"]
+
+        %w[belongs_to has_many has_one has_and_belongs_to_many].each do |type|
+          items = grouped[type]
+          next unless items&.any?
+
+          targets = items.map do |a|
+            name = a['target'] || a['name']
+            dep = a.dig('options', 'dependent')
+            dep ? "#{name} (#{dep})" : name
+          end
+          lines << "**#{type}:** #{targets.join(', ')}"
+        end
+
+        lines.join("\n")
+      end
+
+      def model_dependents(unit)
+        deps = unit['dependents'] || []
+        return nil if deps.empty?
+
+        grouped = deps.group_by { |d| d['type'] }
+        summary_parts = grouped.map { |type, items| "#{items.size} #{type}s" }
+
+        lines = ["## Dependents (#{deps.size} units)"]
+        lines << summary_parts.join(', ')
+
+        # Blast radius assessment
+        if deps.size > 50
+          lines << '**High blast radius** — changes here affect many parts of the codebase'
+        elsif deps.size > 20
+          lines << '**Moderate blast radius** — changes may ripple to dependent code'
+        end
+
+        lines.join("\n")
+      end
+
+      def model_entry_points(unit)
+        deps = unit['dependents'] || []
+        controllers = deps.select { |d| d['type'] == 'controller' }
+        graphql = deps.select { |d| d['type']&.start_with?('graphql') }
+        jobs = deps.select { |d| d['type'] == 'job' }
+
+        return nil if controllers.empty? && graphql.empty?
+
+        lines = ['## Entry Points']
+        lines << "**Controllers:** #{controllers.map { |c| c['identifier'] }.join(', ')}" if controllers.any?
+        lines << "**GraphQL:** #{graphql.map { |g| g['identifier'] }.join(', ')}" if graphql.any?
+        lines << "**Jobs:** #{jobs.map { |j| j['identifier'] }.join(', ')}" if jobs.any?
+
+        lines.join("\n")
+      end
+
+      def model_schema_highlights(meta)
+        parts = []
+
+        enums = meta['enums']
+        if enums.is_a?(Hash) && enums.any?
+          enum_strs = enums.map { |name, values| "#{name} (#{format_enum_values(values)})" }
+          parts << "**Enums:** #{enum_strs.join('; ')}"
+        end
+
+        scopes = meta['scopes']
+        parts << "**Scopes:** #{scopes.map { |s| s['name'] }.join(', ')}" if scopes.is_a?(Array) && scopes.any?
+
+        concerns = meta['inlined_concerns']
+        parts << "**Concerns:** #{concerns.join(', ')}" if concerns.is_a?(Array) && concerns.any?
+
+        callbacks = meta['callbacks']
+        if callbacks.is_a?(Array) && callbacks.any?
+          parts << "**Callbacks (#{callbacks.size}):** #{format_callbacks(callbacks)}"
+        end
+
+        return nil if parts.empty?
+
+        (['## Schema Highlights'] + parts).join("\n")
+      end
+
+      def model_side_effects(unit)
+        deps = unit['dependents'] || []
+        jobs = deps.select { |d| d['type'] == 'job' }
+        mailers = deps.select { |d| d['type'] == 'mailer' }
+
+        return nil if jobs.empty? && mailers.empty?
+
+        lines = ['## Side Effects']
+        lines << "**Jobs:** #{jobs.map { |j| j['identifier'] }.join(', ')}" if jobs.any?
+        lines << "**Mailers:** #{mailers.map { |m| m['identifier'] }.join(', ')}" if mailers.any?
+
+        lines.join("\n")
+      end
+
+      # ── Controller formatting ────────────────────────────────────────
+
+      def build_controller_body(unit)
+        meta = unit['metadata'] || {}
+        sections = []
+
+        sections << "# #{unit['identifier']} (controller)"
+        sections << "**File:** `#{unit['file_path']}`"
+
+        ancestors = meta['ancestors']
+        sections << "**Inherits:** #{ancestors[1..3]&.join(' → ')}" if ancestors.is_a?(Array) && ancestors.size > 1
+
+        sections << controller_routes(meta)
+        sections << controller_dependencies(unit)
+        sections << controller_dependents(unit)
+
+        sections.compact.join("\n\n")
+      end
+
+      def controller_routes(meta)
+        routes = meta['routes']
+        return nil unless routes.is_a?(Hash) && routes.any?
+
+        lines = ['## Routes']
+        routes.each do |action, route_list|
+          next unless route_list.is_a?(Array)
+
+          route_list.each do |route|
+            next unless route.is_a?(Hash)
+
+            lines << "- `#{route['verb']} #{route['path']}` (#{action})"
+          end
+        end
+
+        lines.size > 1 ? lines.first(20).join("\n") : nil
+      end
+
+      def controller_dependencies(unit)
+        deps = unit['dependencies'] || []
+        return nil if deps.empty?
+
+        models = deps.select { |d| d['type'] == 'model' }.map { |d| d['target'] }
+        return nil if models.empty?
+
+        "## Dependencies\n**Models:** #{models.join(', ')}"
+      end
+
+      def controller_dependents(unit)
+        deps = unit['dependents'] || []
+        views = deps.select { |d| d['type'] == 'view_template' }
+        return nil if views.empty?
+
+        "## Views\n#{views.map { |v| "- `#{v['identifier']}`" }.first(10).join("\n")}"
+      end
+
+      # ── GraphQL formatting ───────────────────────────────────────────
+
+      def build_graphql_body(unit)
+        sections = []
+
+        sections << "# #{unit['identifier']} (#{unit['type']})"
+        sections << "**File:** `#{unit['file_path']}`"
+
+        deps = unit['dependencies'] || []
+        models = deps.select { |d| d['type'] == 'model' }.map { |d| d['target'] }
+        sections << "**Models:** #{models.join(', ')}" if models.any?
+
+        dependents = unit['dependents'] || []
+        sections << "**Referenced by:** #{dependents.size} units" if dependents.any?
+
+        sections.compact.join("\n\n")
+      end
+
+      # ── Generic formatting (services, jobs, mailers, etc.) ──────────
+
+      def build_generic_body(unit)
+        meta = unit['metadata'] || {}
+        sections = []
+
+        sections << "# #{unit['identifier']} (#{unit['type']})"
+        sections << "**File:** `#{unit['file_path']}`"
+        sections << "**LOC:** #{meta['loc']}" if meta['loc']
+
+        deps = unit['dependencies'] || []
+        if deps.any?
+          by_type = deps.group_by { |d| d['type'] }
+          dep_parts = by_type.map { |type, items| "#{type}: #{items.map { |d| d['target'] }.join(', ')}" }
+          sections << "## Dependencies\n#{dep_parts.join("\n")}"
+        end
+
+        dependents = unit['dependents'] || []
+        if dependents.any?
+          grouped = dependents.group_by { |d| d['type'] }
+          summary = grouped.map { |type, items| "#{items.size} #{type}s" }
+          sections << "## Dependents (#{dependents.size})\n#{summary.join(', ')}"
+        end
+
+        sections.compact.join("\n\n")
+      end
+
+      # ── Helpers ──────────────────────────────────────────────────────
+
+      def format_enum_values(values)
+        case values
+        when Hash then values.keys.first(5).join(', ')
+        when Array then values.first(5).join(', ')
+        else values.to_s
+        end
+      end
+
+      def format_callbacks(callbacks)
+        callbacks.first(5).map do |cb|
+          "#{cb['type']}: #{cb['filter']}"
+        end.join(', ')
+      end
+    end
+  end
+end

data/lib/woods/unblocked/exporter.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'woods'
+require_relative 'client'
+require_relative 'rate_limiter'
+require_relative 'document_builder'
+
+module Woods
+  module Unblocked
+    # Orchestrates syncing Woods extraction data to an Unblocked collection.
+    #
+    # Reads extraction output from disk via IndexReader, converts units to
+    # condensed Markdown documents, and pushes via the Unblocked Documents API.
+    # All syncs are idempotent — documents are upserted by URI.
+    #
+    # @example
+    #   exporter = Exporter.new(index_dir: "tmp/woods")
+    #   stats = exporter.sync_all
+    #   # => { synced: 940, skipped: 5060, errors: [] }
+    #
+    class Exporter
+      MAX_ERRORS = 100
+
+      # Unit types to sync, in priority order.
+      # All units are synced for these types.
+      FULL_SYNC_TYPES = %w[
+        model controller service job mailer manager decorator concern serializer
+        graphql graphql_type graphql_mutation graphql_resolver graphql_query
+      ].freeze
+
+      # Unit types where only the most-connected units are synced.
+      # Each entry: [type, max_count]
+      PARTIAL_SYNC_TYPES = [
+        ['poro', 100],
+        ['lib', 50]
+      ].freeze
+
+      # @param index_dir [String] Path to extraction output directory
+      # @param config [Configuration] Woods configuration (default: global config)
+      # @param client [Client, nil] Unblocked API client (auto-created from config if nil)
+      # @param reader [Object, nil] IndexReader instance (auto-created if nil)
+      # @param output [IO] Progress output stream (default: $stdout)
+      # @raise [ConfigurationError] if required config is missing
+      def initialize(index_dir:, config: Woods.configuration, client: nil, reader: nil, output: $stdout)
+        @collection_id = config.unblocked_collection_id
+        raise ConfigurationError, 'unblocked_collection_id is required' unless @collection_id
+
+        repo_url = config.unblocked_repo_url
+        raise ConfigurationError, 'unblocked_repo_url is required' unless repo_url
+
+        api_token = config.unblocked_api_token
+        raise ConfigurationError, 'unblocked_api_token is required' unless api_token
+
+        budget = ENV.fetch('UNBLOCKED_DAILY_BUDGET', RateLimiter::DEFAULT_BUDGET.to_s).to_i
+        limiter = RateLimiter.new(daily_budget: budget)
+
+        @client = client || Client.new(api_token: api_token, rate_limiter: limiter)
+        @reader = reader || build_reader(index_dir)
+        @builder = DocumentBuilder.new(repo_url: repo_url)
+        @output = output
+      end
+
+      # Sync all configured unit types to the Unblocked collection.
+      #
+      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
+      def sync_all
+        synced = 0
+        skipped = 0
+        errors = []
+
+        FULL_SYNC_TYPES.each do |type|
+          result = sync_type(type)
+          synced += result[:synced]
+          skipped += result[:skipped]
+          errors.concat(result[:errors])
+        end
+
+        PARTIAL_SYNC_TYPES.each do |type, max_count|
+          result = sync_type_partial(type, max_count)
+          synced += result[:synced]
+          skipped += result[:skipped]
+          errors.concat(result[:errors])
+        end
+
+        { synced: synced, skipped: skipped, errors: cap_errors(errors) }
+      end
+
+      # Sync all units of a given type.
+      #
+      # @param type [String] Unit type (e.g. "model", "controller")
+      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
+      def sync_type(type)
+        units = @reader.list_units(type: type)
+        log "  #{type}: #{units.size} units"
+
+        sync_units(units)
+      end
+
+      # Sync the top N most-connected units of a type (by dependent count).
+      #
+      # @param type [String] Unit type
+      # @param max_count [Integer] Maximum units to sync
+      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
+      def sync_type_partial(type, max_count)
+        units = @reader.list_units(type: type)
+        return empty_stats if units.empty?
+
+        # Load full data to sort by dependent count
+        units_with_data = units.filter_map do |entry|
+          data = @reader.find_unit(entry['identifier'])
+          next unless data
+
+          dep_count = (data['dependents'] || []).size
+          { entry: entry, data: data, dep_count: dep_count }
+        end
+
+        top_units = units_with_data.sort_by { |u| -u[:dep_count] }.first(max_count)
+        skipped_count = [units.size - max_count, 0].max
+
+        log "  #{type}: #{top_units.size}/#{units.size} units (top by dependents)"
+
+        result = sync_unit_data(top_units.map { |u| [u[:entry], u[:data]] })
+        result[:skipped] += skipped_count
+        result
+      end
+
+      private
+
+      def sync_units(units)
+        synced = 0
+        skipped = 0
+        errors = []
+
+        units.each do |entry|
+          unit_data = @reader.find_unit(entry['identifier'])
+          unless unit_data
+            skipped += 1
+            next
+          end
+
+          push_document(unit_data)
+          synced += 1
+        rescue Woods::Error => e
+          errors << "#{entry['identifier']}: #{e.message}"
+          break if e.message.include?('daily budget exhausted')
+        rescue StandardError => e
+          errors << "#{entry['identifier']}: #{e.message}"
+        end
+
+        { synced: synced, skipped: skipped, errors: errors }
+      end
+
+      def sync_unit_data(entries_with_data)
+        synced = 0
+        skipped = 0
+        errors = []
+
+        entries_with_data.each do |entry, unit_data|
+          push_document(unit_data)
+          synced += 1
+        rescue Woods::Error => e
+          errors << "#{entry['identifier']}: #{e.message}"
+          break if e.message.include?('daily budget exhausted')
+        rescue StandardError => e
+          errors << "#{entry['identifier']}: #{e.message}"
+        end
+
+        { synced: synced, skipped: skipped, errors: errors }
+      end
+
+      def push_document(unit_data)
+        doc = @builder.build(unit_data)
+        @client.put_document(
+          collection_id: @collection_id,
+          title: doc[:title],
+          body: doc[:body],
+          uri: doc[:uri]
+        )
+      end
+
+      def build_reader(index_dir)
+        require_relative '../mcp/index_reader'
+        Woods::MCP::IndexReader.new(index_dir)
+      end
+
+      def empty_stats
+        { synced: 0, skipped: 0, errors: [] }
+      end
+
+      def cap_errors(errors)
+        return errors if errors.size <= MAX_ERRORS
+
+        errors.first(MAX_ERRORS) + ["... and #{errors.size - MAX_ERRORS} more errors"]
+      end
+
+      def log(message)
+        @output&.puts(message)
+      end
+    end
+  end
+end

data/lib/woods/unblocked/rate_limiter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Woods
+  module Unblocked
+    # Daily budget-based rate limiter for the Unblocked API (1000 calls/day).
+    #
+    # Unlike Notion's per-second throttling, Unblocked limits by daily call count.
+    # Tracks usage against a configurable budget, warns when approaching the limit,
+    # and raises when exhausted.
+    #
+    # @example
+    #   limiter = RateLimiter.new(daily_budget: 1000)
+    #   limiter.track { client.put_document(...) }  # => result
+    #   limiter.remaining                            # => 999
+    #
+    class RateLimiter
+      DEFAULT_BUDGET = 1000
+      WARN_THRESHOLD = 0.8 # Warn at 80% usage
+
+      # @param daily_budget [Integer] Maximum API calls per day
+      # @param warn_io [IO] Where to write warnings (default: $stderr)
+      def initialize(daily_budget: DEFAULT_BUDGET, warn_io: $stderr)
+        unless daily_budget.is_a?(Integer) && daily_budget.positive?
+          raise ArgumentError, 'daily_budget must be positive'
+        end
+
+        @daily_budget = daily_budget
+        @calls_today = 0
+        @warn_io = warn_io
+        @warned = false
+        @mutex = Mutex.new
+      end
+
+      # Execute a block, tracking the API call against the daily budget.
+      #
+      # @yield The API call to execute
+      # @return [Object] The block's return value
+      # @raise [Woods::Error] if daily budget is exhausted
+      def track
+        raise ArgumentError, 'block required' unless block_given?
+
+        @mutex.synchronize do
+          if @calls_today >= @daily_budget
+            raise Woods::Error,
+                  "Unblocked API daily budget exhausted (#{@daily_budget} calls). " \
+                  'Budget resets at midnight PST. Use UNBLOCKED_DAILY_BUDGET to adjust.'
+          end
+
+          @calls_today += 1
+          warn_if_approaching_limit
+        end
+
+        yield
+      end
+
+      # Number of API calls remaining in the daily budget.
+      #
+      # @return [Integer]
+      def remaining
+        @daily_budget - @calls_today
+      end
+
+      # Number of API calls used today.
+      #
+      # @return [Integer]
+      def used
+        @calls_today
+      end
+
+      # Reset the daily counter (for testing or manual reset).
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize do
+          @calls_today = 0
+          @warned = false
+        end
+      end
+
+      private
+
+      def warn_if_approaching_limit
+        return if @warned
+        return unless @calls_today >= (@daily_budget * WARN_THRESHOLD).to_i
+
+        @warned = true
+        @warn_io&.puts(
+          "WARNING: Unblocked API usage at #{@calls_today}/#{@daily_budget} " \
+          "(#{remaining} calls remaining)"
+        )
+      end
+    end
+  end
+end

data/lib/woods/util/host_guard.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Woods
+  module Util
+    # Shared host-header / URL-host canonicalization used by {MCP::OriginGuard}
+    # and the {Storage::VectorStore::Qdrant} URL validator.
+    #
+    # Both components need to reject numeric IPv4 notations that `URI` and
+    # `getaddrinfo` accept but `IPAddr` does not — hex (`0x7f000001`),
+    # bare integer (`2130706433`), octal (`017700000001` or
+    # `0177.0.0.1`), short-form (`127.1`), mixed-radix (`0x7f.0.0.1`).
+    # Keeping the logic in one place prevents drift between the two
+    # defenses (which previously had slightly different regex lists).
+    module HostGuard
+      # Non-canonical numeric IPv4 forms that legitimate clients never
+      # emit but `getaddrinfo` will happily resolve — rejecting the form
+      # is safer than trying to intuit the intended IPv4.
+      NUMERIC_HOST_BYPASS = Regexp.union(
+        /\A0x[0-9a-f]+\z/,           # hex: `0x7f000001`
+        /\A\d+\z/,                   # bare integer: `2130706433`
+        /\A0[0-7]+\z/,               # bare octal: `017700000001`
+        /\A\d+\.\d+\z/,              # short-form two-part: `127.1`
+        /\A\d+\.\d+\.\d+\z/          # short-form three-part: `127.0.1`
+      ).freeze
+
+      # Octets inside a four-part dotted form that tag the form as
+      # non-canonical: leading zero (octal interpretation), or `0x`
+      # prefix (hex interpretation).
+      SUSPICIOUS_OCTET = Regexp.union(
+        /\A0\d+\z/,                  # leading-zero octal: `0177`
+        /\A0x[0-9a-f]+\z/            # hex octet: `0x7f`
+      ).freeze
+
+      module_function
+
+      # Canonicalize a host string: downcase, strip port, strip the
+      # FQDN trailing dot, drop IPv6 brackets. Returns a plain host.
+      #
+      # @param host [String, nil]
+      # @return [String] canonical host, lowercase, without port/brackets.
+      def canonicalize(host)
+        host.to_s.downcase.sub(/:\d+\z/, '').sub(/\.\z/, '').delete('[]')
+      end
+
+      # Does this canonicalized host smuggle a private IP via a notation
+      # that `IPAddr.new` won't parse? Callers should reject any match
+      # rather than try to resolve it.
+      #
+      # @param canonical [String] Output of {.canonicalize}.
+      # @return [Boolean]
+      def suspicious_numeric_host?(canonical)
+        return true if canonical.match?(NUMERIC_HOST_BYPASS)
+
+        four_octet = canonical.match(/\A(\w+)\.(\w+)\.(\w+)\.(\w+)\z/)
+        return false unless four_octet
+
+        four_octet.captures.any? { |octet| octet.match?(SUSPICIOUS_OCTET) }
+      end
+    end
+  end
+end

data/lib/woods/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Woods
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
 end