woods 1.2.0 → 1.3.0

data/lib/woods/extractors/view_template_extractor.rb

@@ -1,16 +1,25 @@
 # frozen_string_literal: true
 
+require 'set'
+require_relative 'route_helper_resolver'
+require_relative 'view_engines/base'
+require_relative 'view_engines/erb'
+
 module Woods
   module Extractors
-    # ViewTemplateExtractor handles ERB view template extraction.
+    # ViewTemplateExtractor orchestrates view-template extraction across
+    # per-engine implementations under {ViewEngines}.
     #
-    # Scans `app/views/` for `.html.erb` and `.erb` files and produces
-    # one ExtractedUnit per template. Extracts render calls (partials),
-    # instance variables, and helper method usage. Links partials via
-    # dependencies and infers the owning controller from directory structure.
+    # For each configured view directory the orchestrator walks every
+    # extension any registered engine handles, finds the first engine
+    # whose {ViewEngines::Base#handles?} returns true for a given file,
+    # and delegates parsing, scanning, and partial-identifier resolution
+    # to that engine. The orchestrator itself owns filesystem walking,
+    # identifier construction, controller inference, route-helper edge
+    # resolution, and dependency assembly.
     #
-    # This is an ERB-only MVP — HAML, Slim, and layout inheritance
-    # are not yet supported.
+    # Engines are registered via {ENGINES}. Add a new engine by creating
+    # a {ViewEngines::Base} subclass and appending it to that list.
     #
     # @example
     #   extractor = ViewTemplateExtractor.new
@@ -18,67 +27,55 @@ module Woods
     #   index = units.find { |u| u.identifier == "users/index.html.erb" }
     #
     class ViewTemplateExtractor
-      # Directories to scan for view templates
+      include RouteHelperResolver
+
+      # Directories to scan for view templates.
       VIEW_DIRECTORIES = %w[
         app/views
       ].freeze
 
-      # Common Rails view helper methods to detect
-      COMMON_HELPERS = %w[
-        link_to
-        button_to
-        form_for
-        form_with
-        form_tag
-        image_tag
-        stylesheet_link_tag
-        javascript_include_tag
-        content_for
-        yield
-        render
-        redirect_to
-        truncate
-        pluralize
-        number_to_currency
-        number_to_percentage
-        number_with_delimiter
-        time_ago_in_words
-        distance_of_time_in_words
-        simple_format
-        sanitize
-        raw
-        safe_join
-        content_tag
-        tag
-        mail_to
-        url_for
-        asset_path
-        asset_url
-      ].freeze
+      # Registered view-template engines, in precedence order. The first
+      # engine whose {ViewEngines::Base#handles?} returns true for a file
+      # wins — place more specific engines before more general ones if
+      # overlap is ever introduced.
+      ENGINES = [ViewEngines::Erb].freeze
+
+      # Template engine names the extraction pipeline currently
+      # understands — aggregated from {ENGINES} so the list stays honest
+      # as engines are added or removed. Surfaced through the MCP
+      # `structure` tool.
+      #
+      # @return [Array<Symbol>]
+      def self.supported_template_engines
+        ENGINES.map { |klass| klass.new.name }.uniq.freeze
+      end
 
       def initialize
         @directories = VIEW_DIRECTORIES.map { |d| Rails.root.join(d) }
                                        .select(&:directory?)
+        @engines = self.class::ENGINES.map(&:new)
+        build_route_helper_map
       end
 
-      # Extract all ERB view templates
+      # Extract all view templates across the registered engines.
       #
       # @return [Array<ExtractedUnit>] List of view template units
       def extract_all
+        extensions = @engines.flat_map(&:extensions).uniq
         @directories.flat_map do |dir|
-          erb_files = Dir[dir.join('**/*.html.erb')] + Dir[dir.join('**/*.erb')]
-          erb_files.uniq.filter_map do |file|
-            extract_view_template_file(file)
-          end
+          files = extensions.flat_map { |ext| Dir[dir.join("**/*#{ext}")] }
+          files.uniq.filter_map { |file| extract_view_template_file(file) }
         end
       end
 
-      # Extract a single view template file
+      # Extract a single view template file.
       #
-      # @param file_path [String] Path to the ERB template file
-      # @return [ExtractedUnit, nil] The extracted unit or nil if not ERB
+      # @param file_path [String] Path to the template file
+      # @return [ExtractedUnit, nil] The extracted unit, or nil if no
+      #   registered engine handles the file
       def extract_view_template_file(file_path)
-        return nil unless file_path.end_with?('.erb')
+        engine = engine_for(file_path)
+        return nil unless engine
 
         source = File.read(file_path)
         identifier = build_identifier(file_path)
@@ -92,8 +89,9 @@ module Woods
 
         unit.namespace = namespace
         unit.source_code = source
-        unit.metadata = build_metadata(source, file_path)
-        unit.dependencies = build_dependencies(source, file_path, identifier)
+        partials = engine.scan_partials(source)
+        unit.metadata = build_metadata(engine, source, file_path, partials)
+        unit.dependencies = build_dependencies(engine, source, file_path, identifier, partials)
 
         unit
       rescue StandardError => e
@@ -103,6 +101,14 @@ module Woods
 
       private
 
+      # Find the registered engine that handles the given file, if any.
+      #
+      # @param file_path [String]
+      # @return [ViewEngines::Base, nil]
+      def engine_for(file_path)
+        @engines.find { |e| e.handles?(file_path) }
+      end
+
       # Build a readable identifier from the file path.
       #
       # @param file_path [String] Absolute path to the template
@@ -124,16 +130,18 @@ module Woods
 
       # Build metadata hash for the template.
       #
+      # @param engine [ViewEngines::Base] Engine that matched this file
       # @param source [String] Template source code
       # @param file_path [String] Path to the template
+      # @param partials [Array<String>] Pre-extracted partial names
       # @return [Hash]
-      def build_metadata(source, file_path)
+      def build_metadata(engine, source, file_path, partials)
         {
-          template_engine: 'erb',
+          template_engine: engine.name.to_s,
           is_partial: partial?(file_path),
-          partials_rendered: extract_rendered_partials(source),
-          instance_variables: extract_instance_variables(source),
-          helpers_called: extract_helpers(source),
+          partials_rendered: partials,
+          instance_variables: engine.scan_instance_variables(source),
+          helpers_called: engine.scan_helpers(source),
           loc: source.lines.count { |l| l.strip.length.positive? }
         }
       end
@@ -146,98 +154,51 @@ module Woods
         File.basename(file_path).start_with?('_')
       end
 
-      # Extract partial names from render calls.
-      #
-      # Matches:
-      # - render partial: 'foo/bar'
-      # - render 'foo/bar'
-      # - render :foo
-      #
-      # @param source [String] Template source code
-      # @return [Array<String>] Partial names
-      def extract_rendered_partials(source)
-        partials = Set.new
-
-        # render partial: 'path/to/partial'
-        source.scan(/render\s+partial:\s*['"]([^'"]+)['"]/).each do |match|
-          partials << match[0]
-        end
-
-        # render 'path/to/partial' (string without keyword)
-        source.scan(/render\s+['"]([^'"]+)['"]/).each do |match|
-          partials << match[0]
-        end
-
-        # render :symbol
-        source.scan(/render\s+:(\w+)/).each do |match|
-          partials << match[0]
-        end
-
-        partials.to_a
-      end
-
-      # Extract instance variables used in the template.
-      #
-      # @param source [String] Template source code
-      # @return [Array<String>] Instance variable names
-      def extract_instance_variables(source)
-        source.scan(/@[a-zA-Z_]\w*/).uniq.sort
-      end
-
-      # Extract common Rails helper calls from the template.
-      #
-      # @param source [String] Template source code
-      # @return [Array<String>] Helper method names
-      def extract_helpers(source)
-        found = Set.new
-        COMMON_HELPERS.each do |helper|
-          found << helper if source.match?(/\b#{Regexp.escape(helper)}\b/)
-        end
-        found.to_a.sort
-      end
-
       # Build dependencies for the template.
       #
+      # @param engine [ViewEngines::Base] Engine that matched this file
       # @param source [String] Template source code
       # @param file_path [String] Path to the template
       # @param identifier [String] Template identifier
+      # @param partials [Array<String>] Pre-extracted partial names
       # @return [Array<Hash>]
-      def build_dependencies(source, file_path, identifier)
+      def build_dependencies(engine, source, file_path, identifier, partials)
         deps = []
 
-        # Rendered partials
-        extract_rendered_partials(source).each do |partial_name|
-          partial_identifier = resolve_partial_identifier(partial_name, identifier)
+        partials.each do |partial_name|
+          partial_identifier = engine.resolve_partial_identifier(partial_name, identifier)
           deps << { type: :view_template, target: partial_identifier, via: :render }
         end
 
-        # Inferred controller
         controller = infer_controller(file_path)
         deps << { type: :controller, target: controller, via: :view_render } if controller
 
-        deps
+        deps.concat(resolve_navigation_candidates(engine, source))
+
+        deps.uniq { |d| [d[:type], d[:target], d[:via]] }
       end
 
-      # Resolve a partial name to its file identifier.
+      # Ask the engine for route-helper candidates and resolve each to a
+      # controller target via {RouteHelperResolver}. Gated by
+      # +Woods.configuration.extract_navigation_edges+ so the config
+      # toggle still applies.
       #
-      # Given a render call like `render 'comments/comment'`, resolves to
-      # `comments/_comment.html.erb`.
-      #
-      # @param partial_name [String] The partial name from the render call
-      # @param current_identifier [String] The current template's identifier
-      # @return [String] Resolved partial identifier
-      def resolve_partial_identifier(partial_name, current_identifier)
-        if partial_name.include?('/')
-          dir = File.dirname(partial_name)
-          base = File.basename(partial_name)
-          "#{dir}/_#{base}.html.erb"
-        else
-          dir = File.dirname(current_identifier)
-          if dir == '.'
-            "_#{partial_name}.html.erb"
-          else
-            "#{dir}/_#{partial_name}.html.erb"
-          end
+      # @param engine [ViewEngines::Base]
+      # @param source [String]
+      # @return [Array<Hash>]
+      def resolve_navigation_candidates(engine, source)
+        return [] unless Woods.configuration&.extract_navigation_edges
+
+        seen = Set.new
+        engine.scan_navigation_candidates(source).filter_map do |cand|
+          resolved = resolve_route_helper(cand[:helper])
+          next unless resolved
+
+          key = [resolved[:controller], cand[:via]]
+          next if seen.include?(key)
+
+          seen.add(key)
+          { type: :controller, target: resolved[:controller], via: cand[:via] }
         end
       end
 
@@ -248,8 +209,6 @@ module Woods
       def infer_controller(file_path)
         namespace = extract_view_namespace(file_path)
         return nil unless namespace
-
-        # Skip layout-only directories
         return nil if namespace == 'layouts'
 
         parts = namespace.split('/')

data/lib/woods/flow_assembler.rb

@@ -253,7 +253,11 @@ module Woods
 
       filenames.each do |filename|
         Dir[File.join(@extracted_dir, '*', filename)].each do |path|
-          return JSON.parse(File.read(path), symbolize_names: true)
+          # Force UTF-8: the extractor writes the routes-comment header in
+          # source_code using Unicode box-drawing characters; reading under
+          # the platform default (US-ASCII on some CIs) raises
+          # InvalidByteSequenceError before JSON parsing.
+          return JSON.parse(File.read(path, encoding: 'UTF-8'), symbolize_names: true)
         rescue JSON::ParserError
           next
         end
@@ -263,28 +267,32 @@ module Woods
     end
 
     # Extract route information from controller metadata.
+    #
+    # Handles two on-disk shapes:
+    # - Hash keyed by action (what ControllerExtractor writes):
+    #     { "create" => [{ verb:, path:, ... }, ...] }
+    # - Array of route hashes (older / test fixture shape):
+    #     [{ action:, verb:, path: }, ...]
     def extract_route(entry_point)
       unit_id, method_name = parse_identifier(entry_point)
       unit_data = load_unit(unit_id)
       return nil unless unit_data
 
       metadata = unit_data[:metadata] || {}
-      routes = metadata[:routes]
-      return nil unless routes.is_a?(Array)
-
-      # Find route matching the method name
-      route = if method_name
-                routes.find { |r| r[:action]&.to_s == method_name }
-              else
-                routes.first
-              end
-
+      route = resolve_route_entry(metadata[:routes], method_name)
       return nil unless route
 
-      {
-        verb: route[:verb],
-        path: route[:path]
-      }
+      { verb: route[:verb], path: route[:path] }
+    end
+
+    def resolve_route_entry(routes, method_name)
+      case routes
+      when Hash
+        action_routes = method_name ? routes[method_name.to_s] || routes[method_name.to_sym] : routes.values.first
+        Array(action_routes).first
+      when Array
+        method_name ? routes.find { |r| r[:action]&.to_s == method_name } : routes.first
+      end
     end
   end
 end

data/lib/woods/flow_precomputer.rb

@@ -83,7 +83,7 @@ module Woods
       filename = "#{controller_id.gsub('::', '__')}_#{action}.json"
       flow_path = File.join(@flows_dir, filename)
 
-      File.write(flow_path, JSON.pretty_generate(flow.to_h))
+      File.write(flow_path, canonical_json(flow.to_h))
 
       flow_path
     rescue StandardError => e
@@ -96,7 +96,26 @@ module Woods
     # @param flow_map [Hash{String => String}]
     def write_flow_index(flow_map)
       index_path = File.join(@flows_dir, 'flow_index.json')
-      File.write(index_path, JSON.pretty_generate(flow_map))
+      File.write(index_path, canonical_json(flow_map))
+    end
+
+    # Emit deterministic pretty JSON — keys recursively sorted so two runs
+    # over identical input produce byte-identical output. Without this,
+    # diff-based tooling (snapshot review, flow-change detection) flags
+    # spurious churn from incidental key-order differences in `flow.to_h`.
+    #
+    # @param value [Hash, Array, Object]
+    # @return [String]
+    def canonical_json(value)
+      JSON.pretty_generate(sort_keys_deep(value))
+    end
+
+    def sort_keys_deep(value)
+      case value
+      when Hash  then value.keys.sort_by(&:to_s).to_h { |k| [k, sort_keys_deep(value[k])] }
+      when Array then value.map { |v| sort_keys_deep(v) }
+      else value
+      end
     end
   end
 end

data/lib/woods/graph_analyzer.rb

@@ -307,11 +307,10 @@ module Woods
         # Find which other cluster this one connects to most
         target = find_merge_target(cluster, clusters, name)
 
-        if target
-          clusters[target][:members].concat(cluster[:members])
-          cluster[:members].each { |id| clusters[target][:member_set].add(id) }
-        end
+        break unless target
 
+        clusters[target][:members].concat(cluster[:members])
+        cluster[:members].each { |id| clusters[target][:member_set].add(id) }
         clusters.delete(name)
       end
     end

data/lib/woods/index_artifact.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'json'
+require 'fileutils'
+require 'tempfile'
+
+module Woods
+  # Whole Value for the on-disk artifact layout under +output_dir+.
+  #
+  # Centralises all path derivation and atomic write operations so that no
+  # caller ever assembles paths by hand. The +dumps/latest+ pointer file
+  # provides cross-artifact atomicity: consumers always read the pointer
+  # first; the pointer is flipped last, after the dump directory is fully
+  # fsynced.
+  #
+  # @example Basic usage
+  #   artifact = Woods::IndexArtifact.new(output_dir)
+  #   return if artifact.fresh?
+  #   config = artifact.read_config
+  #   dump_dir = artifact.latest_dump_path
+  #
+  class IndexArtifact
+    # @param output_dir [String, Pathname] path to the extraction output directory
+    def initialize(output_dir)
+      @root = Pathname.new(output_dir.to_s)
+    end
+
+    # The extraction output directory root.
+    #
+    # @return [Pathname]
+    def output_dir
+      @root
+    end
+
+    # Path to the resolved config snapshot written by the embed run.
+    #
+    # @return [Pathname]
+    def config_path
+      @root.join('woods.json')
+    end
+
+    # Root of the per-run dump directories.
+    #
+    # @return [Pathname]
+    def dumps_root
+      @root.join('dumps')
+    end
+
+    # Path to the +dumps/latest+ pointer file (may not exist yet).
+    #
+    # @return [Pathname]
+    def latest_pointer_path
+      dumps_root.join('latest')
+    end
+
+    # Returns true when the artifact has never been populated — +woods.json+
+    # is absent AND the +dumps/latest+ pointer does not exist.
+    #
+    # Once either file is present the artifact is considered non-fresh; the
+    # Bootstrapper uses this to decide whether to raise {Woods::MCP::MissingArtifact}
+    # or proceed with loading.
+    #
+    # @return [Boolean]
+    def fresh?
+      !config_path.exist? && !latest_pointer_path.exist?
+    end
+
+    # Path to the latest complete dump directory, or +nil+.
+    #
+    # Returns +nil+ if the pointer file does not exist, if the pointer content
+    # is blank, or if the directory it names no longer exists (stale pointer).
+    #
+    # @return [Pathname, nil]
+    def latest_dump_path
+      return nil unless latest_pointer_path.exist?
+
+      dirname = latest_pointer_path.read.strip
+      return nil if dirname.empty?
+
+      dir = dumps_root.join(dirname)
+      dir.exist? ? dir : nil
+    end
+
+    # Reads and parses +woods.json+, returning the raw hash.
+    #
+    # Returns +nil+ when the file does not exist. Schema-version validation
+    # is the caller's responsibility (typically {Woods::ResolvedConfig.from_hash}).
+    #
+    # @return [Hash, nil]
+    def read_config
+      return nil unless config_path.exist?
+
+      JSON.parse(config_path.read)
+    end
+
+    # Creates a new timestamped dump directory and returns its path.
+    #
+    # The directory is created immediately so callers can begin writing into
+    # it. +dumps_root+ is created on demand. Directory names use dashes in
+    # place of colons for filesystem compatibility (+%H-%M-%SZ+ not
+    # +%H:%M:%SZ+).
+    #
+    # @param now [Time] timestamp to use for the directory name (default: UTC now)
+    # @return [Pathname]
+    # @raise [Errno::EEXIST] if the target directory already exists
+    def new_dump_dir(now: Time.now.utc)
+      dirname = now.strftime('%Y-%m-%dT%H-%M-%SZ')
+      dir = dumps_root.join(dirname)
+      FileUtils.mkdir_p(dumps_root)
+      Dir.mkdir(dir.to_s)
+      dir
+    end
+
+    # Atomically flips the +latest+ pointer to the given dump directory.
+    #
+    # Uses a temp file + +File.rename+ so a crash mid-flip leaves the previous
+    # pointer intact. +dump_dir+ must exist and resolve to a path inside
+    # +dumps_root+.
+    #
+    # @param dump_dir [Pathname, String] completed dump directory to promote
+    # @return [void]
+    # @raise [ArgumentError] if +dump_dir+ does not exist or is outside +dumps_root+
+    def promote(dump_dir)
+      target = Pathname.new(dump_dir.to_s)
+      root_real = dumps_root.expand_path.to_s
+      target_real = target.exist? ? target.realpath.to_s : ''
+      # Resolve symlinks on both sides before comparing (handles macOS /tmp → /private/var)
+      root_resolved = Pathname.new(root_real).exist? ? Pathname.new(root_real).realpath.to_s : root_real
+      unless target.exist? && target_real.start_with?(root_resolved)
+        raise ArgumentError,
+              'dump_dir must exist inside dumps_root. ' \
+              "Got: #{dump_dir.inspect}, dumps_root: #{dumps_root}"
+      end
+
+      atomic_write(latest_pointer_path, target.basename.to_s)
+    end
+
+    # Atomically writes a resolved config hash as +woods.json+.
+    #
+    # Accepts either a +ResolvedConfig+ (responds to +#to_snapshot_json+) or
+    # a plain +Hash+. When +#to_snapshot_json+ returns a +Hash+, it is
+    # serialized to JSON automatically — callers need not pre-serialize.
+    #
+    # @param resolved_config_hash [#to_snapshot_json, Hash]
+    # @return [void]
+    def write_config(resolved_config_hash)
+      raw = if resolved_config_hash.respond_to?(:to_snapshot_json)
+              resolved_config_hash.to_snapshot_json
+            else
+              resolved_config_hash
+            end
+      json = raw.is_a?(String) ? raw : JSON.pretty_generate(raw)
+      atomic_write(config_path, json)
+    end
+
+    private
+
+    def atomic_write(path, content)
+      FileUtils.mkdir_p(path.dirname)
+      tmp = Tempfile.new('.woods-', path.dirname.to_s)
+      tmp.write(content)
+      tmp.flush
+      tmp.fsync
+      tmp.close
+      File.rename(tmp.path, path.to_s)
+    rescue StandardError
+      tmp&.close
+      tmp&.unlink
+      raise
+    end
+  end
+end

data/lib/woods/mcp/bearer_auth.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rack/utils'
+
+module Woods
+  module MCP
+    # Rack middleware that rejects requests lacking a matching bearer token.
+    #
+    # Uses Rack::Utils.secure_compare for constant-time comparison to avoid
+    # leaking token bytes via response-time side channels.
+    class BearerAuth
+      UNAUTHORIZED_BODY = { jsonrpc: '2.0', error: { code: -32_001, message: 'Unauthorized' }, id: nil }.to_json.freeze
+
+      # Bearer tokens shorter than this are rejected at construction time.
+      # Matches OWASP "session ID entropy" guidance (>= 128 bits ≈ 32 hex chars).
+      MIN_TOKEN_LENGTH = 32
+
+      def initialize(app, token:)
+        raise ArgumentError, 'token must be a non-empty string' if token.nil? || token.empty?
+        if token.to_s.length < MIN_TOKEN_LENGTH
+          raise ArgumentError,
+                "bearer token must be at least #{MIN_TOKEN_LENGTH} characters " \
+                "(got #{token.to_s.length}); generate with `SecureRandom.hex(32)`"
+        end
+
+        @app = app
+        @token = token.to_s
+      end
+
+      def call(env)
+        header = env['HTTP_AUTHORIZATION'].to_s
+        presented = header.start_with?('Bearer ') ? header.sub(/\ABearer /, '') : nil
+
+        if presented && Rack::Utils.secure_compare(@token, presented)
+          @app.call(env)
+        else
+          [401,
+           { 'content-type' => 'application/json', 'www-authenticate' => 'Bearer realm="woods-mcp-http"' },
+           [UNAUTHORIZED_BODY]]
+        end
+      end
+    end
+  end
+end