karst 0.1.0

data/lib/karst/access/population_approvals.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../value"
+
+module Karst
+  module Access
+    # The local, machine-scoped record of which discovered candidate
+    # populations a developer has explicitly allowed Karst to execute
+    # automatically (see Karst::Access::ApprovedPopulations for how an
+    # approval is turned back into something runnable, and
+    # Karst::Access::PopulationDiscovery for what can be discovered at all).
+    #
+    # Deliberately *data*, never code: an entry is a model name and a scope
+    # name, and nothing else. Karst never writes a lambda, a snippet, or any
+    # other executable Ruby into this file, and never evaluates its contents
+    # -- an entry is only ever compared, as a string, against what current
+    # source-based discovery independently confirms. That is what keeps this
+    # file from degrading into an arbitrary method allowlist: adding
+    # `{"model": "User", "scope": "destroy_all"}` by hand approves nothing,
+    # because discovery will not confirm it.
+    #
+    # Stored under the host application's `tmp/` (`tmp/karst/`) on purpose:
+    # Rails already treats `tmp/` as machine-local, disposable, and
+    # git-ignored, which is exactly the intended lifetime of a local
+    # development approval. Deleting the file resets every approval; nothing
+    # else in Karst is affected. Karst never edits the host application's
+    # initializer or any other committed file.
+    #
+    # Every read fails closed. A file that is unreadable, is not JSON, is not
+    # the expected document shape, carries an unknown schema version, or
+    # holds a single unusable entry approves *nothing at all* and reports an
+    # error for the panel to show -- rather than partially trusting a
+    # document Karst cannot fully account for.
+    # rubocop:disable Metrics/ModuleLength
+    module PopulationApprovals
+      SCHEMA_VERSION = 1
+
+      RELATIVE_PATH = File.join("tmp", "karst", "approved_populations.json")
+
+      # Both names are matched against exactly what PopulationDiscovery can
+      # produce -- a real constant path, and a scope name Ripper read from a
+      # literal symbol/string in `scope :name, -> { ... }`. Anything else is
+      # rejected before it can even be compared to a discovered candidate.
+      MODEL_NAME = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+      SCOPE_NAME = /\A[a-z_][A-Za-z0-9_]*\z/
+
+      # A bound on how much of this file Karst will consider at all, so a
+      # corrupted or maliciously grown document cannot turn every principal
+      # source resolution into an unbounded amount of source parsing.
+      MAX_ENTRIES = 500
+
+      Entry = Value.define(:model_name, :method_name) do
+        def matches?(model_name, method_name)
+          self.model_name == model_name.to_s && self.method_name == method_name.to_s
+        end
+
+        def display_label
+          "#{model_name}.#{method_name}"
+        end
+      end
+
+      # `entries` is always usable (possibly empty) and always sorted;
+      # `error` is a human-readable reason the stored document was rejected
+      # or could not be written, or nil.
+      Record = Value.define(:entries, :error) do
+        def approved?(model_name, method_name)
+          entries.any? { |entry| entry.matches?(model_name, method_name) }
+        end
+      end
+
+      class << self
+        def path
+          File.join(root, RELATIVE_PATH)
+        end
+
+        # The path as a developer should see it: relative to the application
+        # root, since that is where they will go looking for (or delete) it.
+        def display_path
+          RELATIVE_PATH
+        end
+
+        def load
+          document = JSON.parse(File.read(path))
+          parse(document)
+        rescue Errno::ENOENT
+          empty
+        rescue JSON::ParserError
+          failed("could not be read as JSON")
+        rescue StandardError => e
+          failed("could not be read (#{e.class})")
+        end
+
+        # Replaces the whole approval set with `entries`, atomically: callers
+        # always submit the complete list they intend to keep, so unapproving
+        # is simply approving a smaller set, and a partially written file can
+        # never be observed.
+        def replace(entries)
+          normalized = normalize(entries)
+          write(normalized)
+          Record.new(entries: normalized, error: nil)
+        rescue StandardError => e
+          Record.new(entries: normalized || [].freeze, error: "approvals could not be saved (#{e.class})")
+        end
+
+        private
+
+        def root
+          return Rails.root.to_s if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+          Dir.pwd
+        end
+
+        def parse(document)
+          reason = rejection(document)
+          return failed(reason) if reason
+
+          entries = document["approved"].map { |item| entry(item) }
+          return failed("holds an entry Karst does not recognize") if entries.include?(nil)
+
+          Record.new(entries: sort(entries.uniq).freeze, error: nil)
+        end
+
+        def rejection(document)
+          return "is not a Karst approval document" unless document.is_a?(Hash)
+          return "was written by an incompatible Karst version" unless document["version"] == SCHEMA_VERSION
+
+          approved = document["approved"]
+          return "is not a Karst approval document" unless approved.is_a?(Array)
+
+          "holds more than #{MAX_ENTRIES} entries" if approved.size > MAX_ENTRIES
+        end
+
+        def entry(item)
+          return nil unless item.is_a?(Hash)
+
+          model_name = item["model"]
+          method_name = item["scope"]
+          return nil unless model_name.is_a?(String) && method_name.is_a?(String)
+          return nil unless MODEL_NAME.match?(model_name) && SCOPE_NAME.match?(method_name)
+
+          Entry.new(model_name: model_name, method_name: method_name)
+        end
+
+        def normalize(entries)
+          usable = entries.filter_map do |item|
+            model_name = item.model_name.to_s
+            method_name = item.method_name.to_s
+            next unless MODEL_NAME.match?(model_name) && SCOPE_NAME.match?(method_name)
+
+            Entry.new(model_name: model_name, method_name: method_name)
+          end
+          sort(usable.uniq).first(MAX_ENTRIES).freeze
+        end
+
+        # One deterministic order everywhere -- the file, the panel, and the
+        # order Karst would try approved populations in -- so the same set of
+        # approvals always produces byte-identical storage and the same
+        # search behavior, regardless of checkbox submission order.
+        def sort(entries)
+          entries.sort_by { |item| [item.model_name, item.method_name] }
+        end
+
+        def write(entries)
+          target = path
+          FileUtils.mkdir_p(File.dirname(target))
+          temporary = "#{target}.#{Process.pid}.tmp"
+          File.write(temporary, "#{JSON.pretty_generate(document(entries))}\n")
+          File.rename(temporary, target)
+        ensure
+          FileUtils.rm_f(temporary) if temporary
+        end
+
+        def document(entries)
+          {
+            "version" => SCHEMA_VERSION,
+            "approved" => entries.map { |entry| { "model" => entry.model_name, "scope" => entry.method_name } }
+          }
+        end
+
+        def empty
+          Record.new(entries: [].freeze, error: nil)
+        end
+
+        def failed(reason)
+          Record.new(entries: [].freeze,
+                     error: "#{display_path} #{reason}; Karst approved no populations from it. " \
+                            "Delete the file and approve again.")
+        end
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/karst/access/population_config_snippet.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+
+module Karst
+  module Access
+    # Renders a developer's curated selection of
+    # Karst::Access::PopulationDiscovery::Candidate into a Ruby config
+    # snippet they can copy into their own Karst.configure block. Karst
+    # never writes to the host application's files on its own -- the
+    # developer stays in control of what actually gets committed (see
+    # README "Curation / persistence").
+    module PopulationConfigSnippet
+      # wired is the subset actually rendered into `code` (every selected
+      # candidate whose model matches a configured principal source).
+      # unwired is every selected candidate that is not wired into
+      # anything yet -- present so the UI can say so honestly instead of
+      # silently dropping a selection (see README "Principal vs artifact
+      # populations": this release only wires principal populations).
+      Result = Value.define(:code, :wired, :unwired)
+
+      class << self
+        def generate(candidates)
+          unique = candidates.uniq { |candidate| [candidate.model_name, candidate.method_name] }
+          wired, unwired = unique.partition(&:principal_source)
+          Result.new(code: render(wired), wired: wired, unwired: unwired)
+        end
+
+        private
+
+        def render(wired)
+          return "# Select at least one population above to generate a configuration snippet.\n" if wired.empty?
+
+          by_source = wired.group_by(&:principal_source)
+          by_source.size == 1 && by_source.keys.first == :default ? flat(by_source.fetch(:default)) : nested(by_source)
+        end
+
+        def flat(candidates)
+          "config.principal_populations = {\n#{entries(candidates, indent: 2)}\n}\n"
+        end
+
+        def nested(by_source)
+          sources = by_source.map do |source, group|
+            "  #{source_key(source)}: {\n    populations: {\n#{entries(group, indent: 6)}\n    }\n  }"
+          end.join(",\n")
+          "config.principal_sources = {\n#{sources}\n}\n"
+        end
+
+        # Sorted by model then method so the same selection always renders
+        # byte-identical output, regardless of checkbox submission order.
+        def entries(candidates, indent:)
+          pad = " " * indent
+          sorted = candidates.sort_by { |candidate| [candidate.model_name, candidate.method_name.to_s] }
+          sorted.map { |candidate| entry(candidate, pad) }.join(",\n")
+        end
+
+        def entry(candidate, pad)
+          "#{pad}#{candidate.method_name}: -> { #{candidate.model_name}.#{candidate.method_name} }"
+        end
+
+        def source_key(source)
+          source.to_s =~ /\A[a-zA-Z_][a-zA-Z0-9_]*\z/ ? source : source.inspect
+        end
+      end
+    end
+  end
+end

data/lib/karst/access/population_discovery.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "ripper"
+require_relative "../value"
+
+module Karst
+  module Access
+    # Finds zero-argument Rails scope declarations by parsing model source.
+    # Ripper is part of Ruby's standard library (including Ruby 2.7), so this
+    # does not raise Karst's minimum Ruby version or add a parser dependency.
+    # Discovery never calls a scope or any other model method.
+    class PopulationDiscovery
+      FRAMEWORK_NAMESPACES = %w[ActiveRecord ActiveStorage ActionText ActionMailbox].freeze
+
+      Candidate = Value.define(:model_name, :method_name, :principal_source)
+
+      ModelGroup = Value.define(:model_name, :candidate_names, :principal_source) do
+        def candidates
+          candidate_names.map do |method_name|
+            Candidate.new(model_name: model_name, method_name: method_name, principal_source: principal_source)
+          end
+        end
+      end
+
+      Result = Value.define(:model_groups, :load_warning) do
+        def candidates
+          model_groups.flat_map(&:candidates)
+        end
+      end
+
+      def call
+        Result.new(model_groups: model_groups, load_warning: @load_warning)
+      end
+
+      # Confirms one exact model/scope pair against the model's *current*
+      # source, executing nothing. Deliberately takes the class the caller
+      # already holds (always an already-configured principal source's own
+      # model, see Karst::Access::ApprovedPopulations) rather than a name to
+      # look up: a stored approval can therefore never cause Karst to
+      # constantize, autoload, or reach a class the application had not
+      # already pointed it at, and this check stays a single file parse
+      # instead of a full application eager load.
+      #
+      # Fails closed by construction: it answers "would discovery list this
+      # candidate right now," so a scope that was deleted, renamed, given
+      # parameters, or replaced by an ordinary class method stops being
+      # confirmed as soon as the source changes.
+      def confirms?(klass:, method_name:)
+        name = method_name.to_sym
+        klass.respond_to?(name) && scope_names(klass).include?(name)
+      end
+
+      private
+
+      def model_groups
+        candidate_models.filter_map do |klass|
+          names = scope_names(klass)
+          next if names.empty?
+
+          ModelGroup.new(model_name: klass.name, candidate_names: names,
+                         principal_source: principal_source_for(klass))
+        end.sort_by(&:model_name)
+      end
+
+      def eager_load_application!
+        return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+        Rails.application.eager_load!
+      rescue StandardError => e
+        @load_warning = "The application could not be fully loaded (#{e.class}: #{e.message}); " \
+                        "discovery may be missing some models."
+      end
+
+      def candidate_models
+        @candidate_models ||= begin
+          eager_load_application!
+          if defined?(ActiveRecord::Base)
+            ActiveRecord::Base.descendants.select { |klass| application_model?(klass) }.uniq
+          else
+            []
+          end
+        end
+      end
+
+      def application_model?(klass)
+        klass.name && !klass.abstract_class? && !framework_model?(klass)
+      end
+
+      def framework_model?(klass)
+        FRAMEWORK_NAMESPACES.any? { |namespace| klass.name == namespace || klass.name.start_with?("#{namespace}::") }
+      end
+
+      # Memoized per instance so one discovery pass parses each model's
+      # source file exactly once, whether it is reached by #call or by a
+      # sequence of #confirms? checks over the same class.
+      def scope_names(klass)
+        @scope_names ||= {}
+        @scope_names.fetch(klass) { @scope_names[klass] = parse_scope_names(klass) }
+      end
+
+      def parse_scope_names(klass)
+        file, = Object.const_source_location(klass.name)
+        return [] unless file && File.file?(file)
+
+        SourceScopes.new(File.read(file), klass.name).call
+      rescue StandardError
+        []
+      end
+
+      def principal_source_for(klass)
+        principal_source_klasses.each { |name, source_klass| return name if source_klass == klass }
+        nil
+      end
+
+      # Memoized around the configuration read as well as the result:
+      # resolving the effective principal sources now also resolves locally
+      # approved populations (see Karst::Access::ApprovedPopulations), so
+      # re-reading it once per model group would re-read the approval file
+      # and re-parse model source once per model group too.
+      def principal_source_klasses
+        @principal_source_klasses ||= begin
+          sources = Karst.config.principal_sources || {}
+          sources.each_with_object({}) do |(name, source), memo|
+            klass = source.record_klass
+            memo[name] = klass if klass
+          end
+        end
+      end
+
+      # A deliberately small Ripper AST reader. It recognizes only literal
+      # names and the two callable forms accepted here: -> {} and lambda {}.
+      # rubocop:disable Metrics/ClassLength
+      class SourceScopes
+        def initialize(source, model_name)
+          @tree = Ripper.sexp(source)
+          @model_name = model_name
+        end
+
+        def call
+          return [] unless @tree
+
+          find_classes(@tree, []).uniq.sort
+        end
+
+        private
+
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def find_classes(node, namespace)
+          return [] unless node.is_a?(Array)
+
+          case node[0]
+          when :module
+            name = constant_name(node[1])
+            find_classes(node[2], qualify(namespace, name))
+          when :class
+            name = constant_name(node[1])
+            full_name = qualify(namespace, name)
+            direct = full_name.join("::") == @model_name ? scopes_in_body(node[3]) : []
+            direct + find_classes(node[3], full_name)
+          else
+            node.flat_map { |child| find_classes(child, namespace) }
+          end
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+        def qualify(namespace, name)
+          return namespace unless name
+          return name.split("::") if name.include?("::")
+
+          namespace + [name]
+        end
+
+        def constant_name(node)
+          return unless node.is_a?(Array)
+          return node[1] if node[0] == :@const
+          return constant_name(node[1]) if %i[const_ref top_const_ref].include?(node[0])
+
+          [constant_name(node[1]), constant_name(node[2])].compact.join("::") if node[0] == :const_path_ref
+        end
+
+        def scopes_in_body(body)
+          statements = body && body[0] == :bodystmt ? body[1] : []
+          Array(statements).filter_map { |statement| scope_name(statement) }
+        end
+
+        def scope_name(node)
+          arguments = scope_arguments(node)
+          return unless arguments && arguments.length >= 2
+          return unless zero_argument_callable?(arguments[1])
+
+          literal_name(arguments[0])
+        end
+
+        def scope_arguments(node)
+          return unless node.is_a?(Array)
+
+          return unless scope_call?(node)
+
+          argument_list(node[2])
+        end
+
+        def scope_call?(node)
+          (node[0] == :command && identifier(node[1]) == "scope") ||
+            (node[0] == :method_add_arg && fcall_name(node[1]) == "scope")
+        end
+
+        def argument_list(node)
+          node = node[1] if node && node[0] == :arg_paren
+          node && node[0] == :args_add_block ? node[1] : nil
+        end
+
+        def fcall_name(node)
+          node = node[1] if node && node[0] == :method_add_arg
+          identifier(node[1]) if node && node[0] == :fcall
+        end
+
+        def identifier(node)
+          node[1] if node && %i[@ident @op].include?(node[0])
+        end
+
+        def literal_name(node)
+          return unless node
+
+          case node[0]
+          when :symbol_literal then simple_symbol(node)
+          when :dyna_symbol, :string_literal then static_string(node[1])&.to_sym
+          end
+        end
+
+        def simple_symbol(node)
+          token = node.dig(1, 1)
+          token[1].to_sym if token && token[0].to_s.start_with?("@")
+        end
+
+        def static_string(node)
+          return unless node && node[0] == :string_content
+
+          tokens = node.drop(1)
+          return unless tokens.all? { |token| token[0] == :@tstring_content }
+
+          tokens.map { |token| token[1] }.join
+        end
+
+        def zero_argument_callable?(node)
+          if node && node[0] == :lambda
+            empty_params?(node[1])
+          elsif lambda_block?(node)
+            block = node[2]
+            empty_params?(block[1])
+          else
+            false
+          end
+        end
+
+        def lambda_block?(node)
+          node && node[0] == :method_add_block && fcall_name(node[1]) == "lambda" &&
+            %i[brace_block do_block].include?(node[2]&.first)
+        end
+
+        def empty_params?(node)
+          return true if node.nil?
+
+          node = node[1] if node[0] == :paren
+          node && node[0] == :params && node.drop(1).all?(&:nil?)
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+      private_constant :SourceScopes
+    end
+  end
+end

data/lib/karst/access/population_preview.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+require_relative "candidate_population"
+
+module Karst
+  module Access
+    # The explicit, bounded "does this discovered candidate actually work"
+    # step -- deliberately separate from Karst::Access::PopulationDiscovery,
+    # which never executes anything. Only ever resolves a model/method pair
+    # that a given Karst::Access::PopulationDiscovery::Result itself already
+    # discovered; a submitted name that is not on that list is rejected
+    # without calling anything, so this can never become a general "call any
+    # class method by name" endpoint. Every resolution is bounded to
+    # PREVIEW_LIMIT rows via Karst::Access::CandidatePopulation.resolve --
+    # never a COUNT, never full materialization.
+    class PopulationPreview
+      PREVIEW_LIMIT = 3
+
+      Result = Value.define(:model_name, :method_name, :resolved, :records, :error)
+
+      def self.call(model_name:, method_name:, discovery_result:)
+        new(model_name: model_name, method_name: method_name, discovery_result: discovery_result).call
+      end
+
+      def initialize(model_name:, method_name:, discovery_result:)
+        @model_name = model_name.to_s
+        @method_name = method_name.to_s
+        @discovery_result = discovery_result
+      end
+
+      def call
+        return unresolved("this is not a discovered candidate") unless known_candidate?
+
+        klass = model_class
+        return unresolved("the model could not be resolved") unless klass
+
+        resolve(klass)
+      end
+
+      private
+
+      def known_candidate?
+        @discovery_result.candidates.any? do |candidate|
+          candidate.model_name == @model_name && candidate.method_name.to_s == @method_name
+        end
+      end
+
+      def model_class
+        return nil unless defined?(ActiveRecord::Base)
+
+        ActiveRecord::Base.descendants.find { |klass| klass.name == @model_name }
+      end
+
+      def resolve(klass)
+        method_name = @method_name
+        return missing_scope unless scope_exists?(klass, method_name)
+
+        population = CandidatePopulation.resolve(
+          name: method_name.to_sym, callable: -> { klass.public_send(method_name) },
+          source_klass: klass, limit: PREVIEW_LIMIT
+        )
+        return unresolved("did not resolve to a usable ActiveRecord::Relation for #{@model_name}") unless population
+
+        Result.new(model_name: @model_name, method_name: @method_name, resolved: true, records: population.records,
+                   error: nil)
+      end
+
+      def scope_exists?(klass, method_name)
+        klass.respond_to?(method_name)
+      end
+
+      def missing_scope
+        unresolved("the discovered scope no longer exists on #{@model_name}")
+      end
+
+      def unresolved(error)
+        Result.new(model_name: @model_name, method_name: @method_name, resolved: false, records: [].freeze,
+                   error: error)
+      end
+    end
+  end
+end