woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/session_tracer/unit_resolver.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Woods
+  module SessionTracer
+    # A bare dependency name cannot choose between published extraction types.
+    class AmbiguousUnitError < StandardError
+      attr_reader :identifier, :types
+
+      def initialize(identifier, types)
+        @identifier = identifier
+        @types = types.sort.freeze
+        super("Ambiguous session unit #{identifier.inspect}: published types #{@types.join(', ')}. " \
+              'No session context was returned. Use depth: 0 for the timeline, or inspect each type with lookup.')
+      end
+    end
+
+    # Per-assembly resolver. The caller pins its complete lifetime to one generation.
+    # Summary entries may omit type in legacy indexes; the containing bucket and
+    # validated unit body establish the concrete type without reading unrelated bodies.
+    class UnitResolver
+      def initialize(reader)
+        @reader = reader
+        @resolved = {}
+      end
+
+      def find(identifier)
+        return @resolved[identifier] if @resolved.key?(identifier)
+
+        units = candidate_types.fetch(identifier, []).filter_map do |type|
+          @reader.find_unit(identifier, type: type)
+        end
+        raise AmbiguousUnitError.new(identifier, units.map { |unit| unit.fetch('type') }) if units.size > 1
+
+        @resolved[identifier] = units.first
+      end
+
+      private
+
+      def entries_for(dir)
+        path = @reader.payload_dir.join(dir, '_index.json')
+        raise IOError, "symlink unit index: #{dir}" if path.symlink?
+
+        entries = @reader.list_units(type: MCP::IndexReader::DIR_TO_TYPE.fetch(dir))
+        expected = @reader.manifest.dig('counts', dir)
+        if expected.is_a?(Integer) && expected != entries.size
+          raise IOError, "unit count mismatch in #{dir}: expected #{expected}, found #{entries.size}"
+        end
+
+        entries
+      end
+
+      def candidate_types
+        @candidate_types ||= MCP::IndexReader::UNIT_TYPES_BY_DIR.each_with_object({}) do |(dir, types), candidates|
+          entries_for(dir).each do |entry|
+            identifier = entry.fetch('identifier')
+            candidates[identifier] ||= []
+            candidates[identifier] |= types
+          end
+        end
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/consumer_errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Woods
+  module SourceInputs
+    # Error handlers can return the same nil/empty result as a successful
+    # negative match. Keep explicit evidence on the consumer instance instead
+    # of guessing from results or intercepting the application's logger.
+    module ConsumerErrors
+      FLAG = :@woods_source_consumer_failed
+
+      module_function
+
+      def record(consumer)
+        consumer.instance_variable_set(FLAG, true)
+      end
+
+      def failed?(consumer)
+        consumer && consumer.instance_variable_get(FLAG) == true
+      end
+
+      def log(consumer, ...)
+        record(consumer)
+        Rails.logger.error(...)
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/handoff.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'woods/source_inputs/manifest'
+
+module Woods
+  module SourceInputs
+    # Private one-process launch handoff. Its environment token names neither an
+    # existing index manifest nor a user-supplied proof of runtime freshness.
+    module Handoff
+      ENV_KEY = 'WOODS_SOURCE_CAPTURE'
+
+      module_function
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # Every independent handoff binding must match before a token is consumed.
+      def read(root:, output_dir:, operation:, rules:, key_id:)
+        token = ENV.fetch(ENV_KEY, nil)
+        return nil if token.nil? || token.empty?
+
+        descriptor = JSON.parse(token)
+        return nil unless descriptor.is_a?(Hash)
+
+        data = private_data(descriptor.fetch('path'))
+        return nil unless data.is_a?(Hash)
+
+        expected = { 'version' => 1, 'nonce' => descriptor.fetch('nonce'),
+                     'root' => File.expand_path(root.to_s), 'output' => File.expand_path(output_dir.to_s),
+                     'operation' => operation.to_s, 'rules' => rules, 'launcher_pid' => Process.ppid }
+        return nil unless expected.all? { |key, value| data[key] == value }
+        return nil unless valid_nonce?(data['nonce'])
+
+        snapshot = data.fetch('snapshot')
+        return nil unless valid_snapshot?(snapshot, expected, key_id)
+
+        ENV.delete(ENV_KEY)
+        snapshot
+      rescue JSON::ParserError, KeyError, TypeError, SystemCallError, IOError
+        nil
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def private_data(path)
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags) do |file|
+          stat = file.stat
+          return nil unless stat.file? && stat.uid == Process.uid && stat.mode.nobits?(0o077)
+          return nil if stat.size > Manifest::MAX_BYTES
+
+          JSON.parse(file.read(Manifest::MAX_BYTES + 1))
+        end
+      end
+
+      def valid_nonce?(value)
+        value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+      end
+
+      def valid_snapshot?(snapshot, expected, key_id)
+        return false unless matching_snapshot?(snapshot, expected, key_id)
+
+        files = snapshot['files']
+        paths = snapshot['scope_paths']
+        return false unless valid_tables?(files, paths)
+
+        expanded = paths.transform_values { |list| list.to_h { |path| [path, files.fetch(path)] } }
+        Manifest.build(snapshot: snapshot, scopes: expanded, boot_verified: true, generation: 1)
+        true
+      rescue Manifest::Invalid, KeyError, TypeError
+        false
+      end
+
+      def matching_snapshot?(snapshot, expected, key_id)
+        snapshot.is_a?(Hash) && snapshot['root'] == expected['root'] &&
+          snapshot['rules'] == expected['rules'] && snapshot['key_id'] == key_id
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def valid_tables?(files, paths)
+        files.is_a?(Hash) && paths.is_a?(Hash) &&
+          files.all? { |path, digest| path.is_a?(String) && valid_nonce?(digest) } &&
+          paths.values.all? { |list| list.is_a?(Array) && list.all? { |path| files.key?(path) } }
+      end
+
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def extra_roots
+        token = ENV.fetch(ENV_KEY, nil)
+        return [] if token.nil? || token.empty?
+
+        descriptor = JSON.parse(token)
+        return [] unless descriptor.is_a?(Hash)
+
+        roots = descriptor.fetch('extra_roots', [])
+        roots.is_a?(Array) ? roots : []
+      rescue JSON::ParserError, TypeError
+        []
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/launcher.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'tempfile'
+require 'base64'
+require 'securerandom'
+require 'woods/source_inputs/scanner'
+require 'woods/source_inputs/handoff'
+require 'woods/hooks/refresh'
+
+module Woods
+  module SourceInputs
+    # Captures before a fresh child evaluates Bundler, the Rakefile and Rails.
+    # The parent waits so all exit paths can remove the private handoff.
+    class Launcher # rubocop:disable Metrics/ClassLength -- parser and child lifetime form one CLI contract
+      OPERATIONS = %w[full incremental refresh].freeze
+
+      def self.run(argv, **options)
+        new(argv, **options).run
+      rescue OptionParser::ParseError, ArgumentError, PrivateKey::Unavailable, SystemCallError => e
+        warn "woods-extract: #{e.message}"
+        1
+      end
+
+      def initialize(argv, command: %w[bundle exec rake])
+        @arguments = argv.dup
+        @command = command
+        @original_directory = Dir.pwd
+        @root = @original_directory
+        @output = ENV.fetch('WOODS_OUTPUT', 'tmp/woods')
+        @extra_roots = []
+        parse!
+      end
+
+      def run # rubocop:disable Metrics/MethodLength -- handoff lifetime encloses the fresh child
+        return 0 if @help
+
+        operation, task = task_for_arguments
+        key = PrivateKey.new(output_dir: @output, create: true)
+        rules = Scopes.new(extra_roots: @extra_roots)
+        snapshot = Scanner.new(root: @root, output_dir: @output, key: key, scopes: rules).call
+        nonce = SecureRandom.hex(32)
+        Tempfile.create(['woods-source-capture-', '.json']) do |file|
+          file.binmode
+          file.chmod(0o600)
+          file.write(JSON.generate(version: 1, nonce: nonce, root: @root, output: @output,
+                                   operation: operation, rules: rules.fingerprint,
+                                   launcher_pid: Process.pid, snapshot: snapshot))
+          file.flush
+          file.fsync
+          descriptor = JSON.generate(path: file.path, nonce: nonce, extra_roots: @extra_roots)
+          environment = { Handoff::ENV_KEY => descriptor, 'WOODS_OUTPUT' => @output }
+          if ENV['BUNDLE_GEMFILE']
+            environment['BUNDLE_GEMFILE'] = File.expand_path(ENV.fetch('BUNDLE_GEMFILE'), @original_directory)
+          end
+          run_child(environment, task)
+        end
+      end
+
+      private
+
+      def parse!
+        parser.permute!(@arguments)
+        validate_arguments! unless @help
+      end
+
+      def parser
+        OptionParser.new do |options|
+          options.banner = 'Usage: woods-extract [options] full | incremental PATH... | refresh TYPE...'
+          options.on('--root PATH', 'Application root (default: current directory)') { |path| @root = path }
+          options.on('--output PATH', 'Index output (default: WOODS_OUTPUT or tmp/woods)') { |path| @output = path }
+          options.on('--source-root PATH', 'Additional application-relative runtime source root') do |path|
+            @extra_roots << path
+          end
+          options.on('-h', '--help', 'Show usage') do
+            puts options
+            @help = true
+          end
+        end
+      end
+
+      def validate_arguments!
+        @root = File.expand_path(@root)
+        raise ArgumentError, 'application root does not exist' unless File.directory?(@root)
+
+        @output = File.expand_path(@output, @root)
+        @operation = @arguments.shift
+        raise ArgumentError, 'choose full, incremental, or refresh' unless OPERATIONS.include?(@operation)
+        if @operation == 'full' && !@arguments.empty?
+          raise ArgumentError,
+                'full does not accept paths or extractor names'
+        end
+        if @operation != 'full' && @arguments.empty?
+          raise ArgumentError,
+                "#{@operation} requires paths or extractor names"
+        end
+
+        @extra_roots = Scopes.new(extra_roots: @extra_roots).extra_roots
+      end
+
+      def task_for_arguments
+        return ['full', 'woods:extract'] if @operation == 'full'
+        return refresh_task if @operation == 'refresh'
+
+        incremental_task
+      end
+
+      def incremental_task
+        paths = @arguments.map { |path| relative_path(path) }.uniq
+        action = InputRules.new
+        operation = paths.any? { |path| action.action(path) == :full } ? 'full' : 'incremental'
+        if paths.size > Hooks::Refresh::MAX_EVENTS
+          raise ArgumentError, 'too many incremental paths; split the input or run full'
+        end
+
+        batch = Base64.strict_encode64(JSON.generate(version: 1, output: @output,
+                                                     events: paths.map { |path| { path: path, operation: 'update' } }))
+        raise ArgumentError, 'incremental batch too large; split the input or run full' if batch.bytesize > 120_000
+
+        [operation, "woods:hook_refresh[#{batch}]"]
+      end
+
+      def refresh_task
+        names = @arguments.uniq
+        unless names.all? { |name| name.match?(/\A[a-z_]+\z/) && Extractor::EXTRACTORS.key?(name.to_sym) }
+          raise ArgumentError, 'refresh requires known extractor names'
+        end
+
+        ['refresh', "woods:refresh[#{names.join(',')}]"]
+      end
+
+      def relative_path(path)
+        absolute = File.expand_path(path, @root)
+        unless absolute.start_with?("#{@root}/") && !path.include?("\0")
+          raise ArgumentError, 'incremental paths must be inside the application root'
+        end
+
+        absolute.delete_prefix("#{@root}/")
+      end
+
+      def run_child(environment, task)
+        pid = Process.spawn(environment, *@command, task, chdir: @root, pgroup: true)
+        previous = %w[INT TERM].to_h do |signal|
+          [signal, Signal.trap(signal) do
+            Process.kill(signal, -pid)
+          rescue StandardError
+            nil
+          end]
+        end
+        _finished, status = Process.wait2(pid)
+        status.exitstatus || (128 + status.termsig)
+      ensure
+        previous&.each { |signal, handler| Signal.trap(signal, handler) }
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/manifest.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module SourceInputs
+    # Compact wire format: consumers refer to a shared identity table. Internal
+    # mutation uses expanded digests so table indices never leak across runs.
+    class Manifest
+      FILE_NAME = 'source_inputs.json'
+      VERSION = 1
+      MAX_BYTES = 16 * 1024 * 1024
+      class Invalid < StandardError; end
+
+      attr_reader :data
+
+      def self.parse(bytes)
+        raise Invalid, 'source_manifest_too_large' if bytes.bytesize > MAX_BYTES
+
+        new(JSON.parse(bytes))
+      rescue JSON::ParserError
+        raise Invalid, 'invalid_source_manifest'
+      end
+
+      def initialize(data)
+        @data = data
+        validate!
+      end
+
+      def expanded
+        identities = @data.fetch('identities')
+        @data.fetch('scopes').transform_values do |paths|
+          paths.transform_values { |index| identities.fetch(index) }
+        end
+      end
+
+      # Explicit wire fields keep incomplete coverage separate from boot provenance.
+      # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
+      def self.build(snapshot:, scopes:, boot_verified:, generation:, errors: [], unverified_scopes: [])
+        identities = scopes.values.flat_map(&:values).uniq.sort
+        indices = identities.each_with_index.to_h
+        new('version' => VERSION, 'generation' => generation, 'root' => snapshot.fetch('root'),
+            'key_id' => snapshot.fetch('key_id'), 'rules' => snapshot.fetch('rules'),
+            'extra_roots' => snapshot.fetch('extra_roots'), 'boot_verified' => boot_verified,
+            'complete' => snapshot.fetch('complete'), 'errors' => (snapshot.fetch('errors') + errors).uniq,
+            'unverified_scopes' => unverified_scopes.uniq.sort,
+            'identities' => identities, 'metrics' => snapshot.fetch('metrics'),
+            'scopes' => scopes.sort.to_h.transform_values do |paths|
+              paths.sort.to_h.transform_values { |digest| indices.fetch(digest) }
+            end)
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/ParameterLists
+
+      private
+
+      def validate!
+        raise Invalid, 'unsupported_source_manifest' unless supported_version?
+        raise Invalid, 'invalid_source_manifest_header' unless valid_header?
+
+        validate_tables!
+        return if @data['extra_roots'].all? { |path| valid_path?(path) }
+
+        raise Invalid, 'invalid_source_roots'
+      end
+
+      def validate_tables!
+        identities = @data['identities']
+        scopes = @data['scopes']
+        unless identities.is_a?(Array) && identities.all? { |digest| digest?(digest) } && scopes.is_a?(Hash)
+          raise Invalid, 'invalid_source_identity_table'
+        end
+
+        scopes.each { |scope, paths| validate_scope!(scope, paths, identities) }
+        raise Invalid, 'invalid_source_manifest_coverage' unless valid_coverage?
+      end
+
+      def validate_scope!(scope, paths, identities)
+        return if scope.is_a?(String) && paths.is_a?(Hash) &&
+                  paths.all? { |path, index| valid_entry?(path, index, identities) }
+
+        raise Invalid, 'invalid_source_scope'
+      end
+
+      def supported_version?
+        @data.is_a?(Hash) && @data['version'] == VERSION &&
+          @data['generation'].is_a?(Integer) && @data['generation'].positive?
+      end
+
+      def valid_header?
+        valid_root? && %w[key_id rules].all? { |key| digest?(@data[key]) } &&
+          %w[boot_verified complete].all? { |key| [true, false].include?(@data[key]) }
+      end
+
+      def valid_root?
+        root = @data['root']
+        root.is_a?(String) && root.start_with?('/') && !root.include?("\0")
+      end
+
+      def valid_coverage?
+        @data['errors'].is_a?(Array) && @data['errors'].all? { |error| valid_error?(error) } &&
+          %w[extra_roots unverified_scopes].all? { |key| @data[key].is_a?(Array) && @data[key].all?(String) }
+      end
+
+      def valid_error?(error)
+        error.is_a?(Hash) && error['reason'].is_a?(String) &&
+          (error['path'].nil? || error['path'].is_a?(String))
+      end
+
+      def valid_entry?(path, index, identities)
+        valid_path?(path) && index.is_a?(Integer) && index >= 0 && index < identities.size
+      end
+
+      def valid_path?(path)
+        path.is_a?(String) && !path.empty? && !path.start_with?('/') && !path.include?("\0") &&
+          path.split('/', -1).none? { |part| ['', '.', '..'].include?(part) }
+      end
+
+      def digest?(value)
+        value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/private_key.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'digest'
+require 'fileutils'
+
+module Woods
+  module SourceInputs
+    # Never copied into a published generation. Public identities are keyed even
+    # for ordinary source, so an unrecognized secret-bearing file stays protected.
+    class PrivateKey
+      FILE_NAME = '.source-inputs.key'
+      class Unavailable < StandardError; end
+
+      attr_reader :bytes, :identifier
+
+      def initialize(output_dir:, create: false)
+        path = File.join(output_dir.to_s, FILE_NAME)
+        create_key(path) if create
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags) do |file|
+          stat = file.stat
+          raise Unavailable, 'insecure_identity_key' unless private_regular?(stat)
+
+          @bytes = file.read(33)
+        end
+        raise Unavailable, 'invalid_identity_key' unless @bytes&.bytesize == 32
+
+        @identifier = Digest::SHA256.hexdigest(@bytes)
+      rescue SystemCallError, IOError
+        raise Unavailable, 'identity_key_unavailable'
+      end
+
+      private
+
+      def private_regular?(stat)
+        stat.file? && stat.uid == Process.uid && stat.mode.nobits?(0o077)
+      end
+
+      def create_key(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+          file.binmode
+          file.write(SecureRandom.random_bytes(32))
+          file.flush
+          file.fsync
+        end
+      rescue Errno::EEXIST
+        # Existing permissions/content are validated, never repaired implicitly.
+        nil
+      end
+    end
+  end
+end