actionagent 1.8.1 → 1.9.0

data/app/services/action_agent/project_install_pull_request.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to publish what a project's bootstrap wrote into its checkout as a
+  # pull request that installs the engine in the repository: the install
+  # pull request. Publishing goes through DraftPullRequestPublisher, from the
+  # project's live sandbox, and takes only the paths of #allowlist:
+  #
+  #   Gemfile, Gemfile.lock
+  #   config/initializers/action_agent.rb, config/routes.rb
+  #   config/active_agent.yml and app/agents/application_agent.rb, when the
+  #     bootstrap generated them (the repository locked no activeagent)
+  #   the migrations `action_agent:install` emits, by exact name after the
+  #     timestamp (ENGINE_MIGRATIONS and the numbered templates)
+  #   db/schema.rb or db/structure.sql
+  #   app/agent_tools/<model>_tools.rb for every model the App assistant was
+  #     ever given (Project#schema_tools_models), so that a file a boot
+  #     removed can be removed on the branch too
+  #   .activeagents/sandbox.yml and .activeagents/evals/<project>.yml
+  #   whatever a Claude Code boot fix changed to get the boot through
+  #     (ProjectBootFix.changed_paths_for)
+  #
+  # The last two are generated here rather than read from the checkout (see
+  # #generated_files): sandbox.yml holds the setup that booted the project
+  # and the names of its secrets, never their values, and the evaluation
+  # suite holds the project evaluation's enabled scenarios in the shape
+  # ActiveAgent::Evals::Suite.load reads. Anything else the sandbox changed,
+  # .github/ and any file holding one of the project's secrets is refused by
+  # the publisher.
+  #
+  # A publish takes every REQUIRED_PATHS file and engine migration the
+  # sandbox changed (#missing_required_paths): every boot of the branch
+  # installs nothing, so it boots only with all of them.
+  class ProjectInstallPullRequest
+    SANDBOX_CONFIG = ".activeagents/sandbox.yml"
+    STATIC_PATHS = [
+      "Gemfile", "Gemfile.lock", "config/initializers/action_agent.rb", "config/routes.rb", "db/schema.rb", "db/structure.sql",
+      SANDBOX_CONFIG
+    ].freeze
+    # What `active_agent:install` writes into a repository without the
+    # framework.
+    FRAMEWORK_PATHS = %w[config/active_agent.yml app/agents/application_agent.rb].freeze
+    # The migrations `action_agent:install` emits by name, beside its
+    # numbered templates (ActionAgent::InstallGenerator).
+    ENGINE_MIGRATIONS = %w[
+      create_active_agent_telemetry_traces add_agent_id_to_active_agent_telemetry_traces add_agent_releases
+      create_active_agent_dashboard_tables ensure_agent_release_columns create_active_agent_evaluation_scenarios
+      add_evaluation_report_identity add_provider_key_api_key create_active_agent_github_connections
+      create_active_agent_code_sessions add_code_session_runner
+    ].freeze
+    # What a boot of the branch, which installs nothing, needs to load the
+    # engine.
+    REQUIRED_PATHS = [
+      "Gemfile", "Gemfile.lock", "config/initializers/action_agent.rb", "config/routes.rb", "db/schema.rb", "db/structure.sql"
+    ].freeze
+    NUMBERED_MIGRATION = /\A\d{3}_(?<name>[a-z0-9_]+)\.rb\.erb\z/
+    NUMBERED_MIGRATIONS_PATH = File.expand_path("../../../lib/generators/action_agent/templates/migrations", __dir__)
+    DEFAULT_BRANCH = "activeagent/install-engine"
+    DEFAULT_SETUP = [ "bundle install", "bin/rails db:prepare" ].freeze
+
+    class << self
+      # The names of every migration `action_agent:install` emits.
+      def engine_migration_names
+        numbered = Dir.children(NUMBERED_MIGRATIONS_PATH).sort.filter_map { |file| NUMBERED_MIGRATION.match(file)&.[](:name) }
+        ENGINE_MIGRATIONS + numbered
+      rescue Errno::ENOENT
+        ENGINE_MIGRATIONS
+      end
+
+      # The publisher a queued +record+ is published with: the project's,
+      # with its generated files, when +record+ is a project's install pull
+      # request, and a plain one otherwise.
+      def publisher_for(record, user: nil)
+        project = record.sandbox_session&.project
+        if project && project.settings["install_pull_request_id"] == record.id
+          new(project, user: user).publisher(record.sandbox_session)
+        else
+          DraftPullRequestPublisher.new(record.sandbox_session, user: user)
+        end
+      end
+    end
+
+    attr_reader :project
+
+    def initialize(project, user: nil, orchestrator: SandboxOrchestrator.new)
+      @project = project
+      @user = user
+      @orchestrator = orchestrator
+    end
+
+    # The patterns DraftPullRequestPublisher#changes takes for the project.
+    #
+    # @return [Array<String, Regexp>]
+    def allowlist
+      paths = STATIC_PATHS.dup
+      paths.concat(FRAMEWORK_PATHS) if framework_generated?
+      paths.concat(project.schema_tools_models.map { |model| "#{SandboxBootSpec::SCHEMA_TOOLS_DIR}/#{model.underscore}_tools.rb" })
+      paths << evaluation_path
+      paths << engine_migration_pattern
+      paths.concat(ProjectBootFix.changed_paths_for(project).map { |path| exact_path(path) })
+      paths.uniq
+    end
+
+    # The REQUIRED_PATHS and engine migrations +publisher+'s sandbox changed
+    # that +paths+ leaves out.
+    #
+    # @return [Array<String>]
+    def missing_required_paths(publisher, paths)
+      chosen = paths.to_set
+      publisher.changed_paths.select do |path|
+        (REQUIRED_PATHS.include?(path) || engine_migration_pattern.match?(path)) && !chosen.include?(path)
+      end
+    end
+
+    # Where the project evaluation's suite is published.
+    def evaluation_path
+      ".activeagents/evals/#{project.name.parameterize.presence || "project-#{project.id}"}.yml"
+    end
+
+    # The publisher for +sandbox+ with the project's generated files.
+    def publisher(sandbox = project.current_sandbox_session)
+      DraftPullRequestPublisher.new(sandbox, user: @user, orchestrator: @orchestrator, generated_files: generated_files(sandbox))
+    end
+
+    # What the dashboard writes itself: sandbox.yml, and the evaluation
+    # suite when the project's evaluation has enabled scenarios.
+    #
+    # @return [Hash{String => String}]
+    def generated_files(sandbox = project.current_sandbox_session)
+      files = { SANDBOX_CONFIG => sandbox_config(sandbox) }
+      suite = evaluation_suite
+      files[evaluation_path] = suite if suite
+      files
+    end
+
+    # The project's sandbox.yml: the checkout's own, if it has one, with the
+    # setup that booted the project and the names of the project's secrets.
+    # The values the setup assistant set are not secrets, and stay with the
+    # project: a boot passes them as env.
+    def sandbox_config(sandbox)
+      data = base_sandbox_config(sandbox)
+      data["setup"] = setup_commands(sandbox)
+      names = Array(data["secrets"]).map(&:to_s) | project.secrets.ordered.reject(&:plain?).map(&:name)
+      data["secrets"] = names if names.any?
+
+      <<~YAML + data.to_yaml.delete_prefix("---\n")
+        # How an ActiveAgent checkout sandbox boots this app: the setup commands,
+        # and the names of the environment variables it needs. Their values are
+        # never written here: a sandbox is given them when it boots.
+      YAML
+    end
+
+    # The project evaluation's enabled scenarios as an evaluation suite
+    # (ActiveAgent::Evals::Suite), grouped as the dashboard groups them; nil
+    # when there are none.
+    def evaluation_suite
+      evaluation = project.evaluation
+      scenarios = evaluation ? evaluation.scenarios.enabled.ordered.to_a : []
+      return nil if scenarios.empty?
+
+      groups = scenarios.group_by { |scenario| scenario.group.presence || "default" }.map do |group, members|
+        { "key" => group, "name" => group, "scenarios" => members.map { |scenario| suite_entry(scenario) } }
+      end
+      document = {
+        "suite" => evaluation_path.delete_prefix(".activeagents/evals/").delete_suffix(".yml"),
+        "description" => "#{evaluation.name}: the scenarios #{project.repository}'s project evaluation replays",
+        "groups" => groups
+      }
+      document.to_yaml
+    end
+
+    private
+
+    # +path+ as a pattern File.fnmatch matches only itself.
+    def exact_path(path)
+      path.gsub(/[*?\[\]{}\\]/) { |char| "\\#{char}" }
+    end
+
+    def engine_migration_pattern
+      @engine_migration_pattern ||= begin
+        names = self.class.engine_migration_names.map { |name| Regexp.escape(name) }.join("|")
+        %r{\Adb/migrate/\d+_(?:#{names})\.rb\z}
+      end
+    end
+
+    # Whether the bootstrap wrote the framework's files: the repository's
+    # lock had no activeagent when the project picked it.
+    def framework_generated?
+      project.settings.dig("preflight", "activeagent").blank?
+    end
+
+    def suite_entry(scenario)
+      expect = {
+        "tools" => scenario.expected_tools.presence,
+        "contains" => scenario.expected_patterns.presence,
+        "not_contains" => scenario.forbidden_patterns.presence
+      }.compact
+      { "key" => scenario.key, "prompt" => scenario.prompt, "expect" => expect.presence, "notes" => scenario.notes.presence }.compact
+    end
+
+    def base_sandbox_config(sandbox)
+      content = sandbox && @orchestrator.read_file(sandbox, SANDBOX_CONFIG, base: true)
+      data = content ? YAML.safe_load(content.force_encoding(Encoding::UTF_8), aliases: false) : nil
+      data.is_a?(Hash) ? data : {}
+    rescue StandardError
+      {}
+    end
+
+    # The commands of the boot steps that succeeded, as the checkout's own
+    # sandbox.yml boot runs them: without the steps that installed the
+    # engine and wrote the schema tools, which the pull request carries.
+    def setup_commands(sandbox)
+      status = sandbox && @orchestrator.supports?(:boot_status) ? @orchestrator.boot_status(sandbox) : nil
+      succeeded = Array(status&.dig(:steps)).filter_map { |step| step[:name] if step[:status] == "succeeded" }.to_set
+      commands = project.boot_spec(sandbox).steps.filter_map do |step|
+        next if SandboxBootSpec::INSTALL_STEPS.include?(step["name"]) || SandboxBootSpec.schema_tools_step?(step["name"])
+
+        step["command"] if succeeded.include?(step["name"])
+      end
+      commands.presence || DEFAULT_SETUP.dup
+    rescue StandardError
+      DEFAULT_SETUP.dup
+    end
+  end
+end

data/app/services/action_agent/project_preflight.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to decide whether a repository can become a project before any
+  # sandbox exists, from files read through GitHub's contents API: its
+  # Gemfile.lock, .ruby-version, config/application.rb, config/database.yml
+  # and Gemfile. It applies the requirements a bootstrap boot's own preflight
+  # applies after checkout (LocalSandboxBackend), so a repository refused
+  # here would be refused there.
+  #
+  # Nothing of the repository runs: the lock is parsed with Bundler's parser,
+  # and the other files are only matched against.
+  #
+  # The files are read at the commit the ref names, and the report is kept in
+  # Rails.cache for that commit, so checking a repository again costs one
+  # GitHub call until it changes.
+  class ProjectPreflight
+    STATUSES = %w[supported bootstrap unsupported].freeze
+    CACHE_TTL = 1.day
+    SUMMARIES = {
+      "supported" => "Supported",
+      "bootstrap" => "Supported: installs the engine in the sandbox"
+    }.freeze
+    # Gems whose service a sandbox does not run, with the service's name.
+    SERVICE_GEMS = {
+      "redis" => "Redis",
+      "sidekiq" => "Redis (for Sidekiq)",
+      "resque" => "Redis (for Resque)",
+      "elasticsearch" => "Elasticsearch",
+      "elasticsearch-model" => "Elasticsearch",
+      "searchkick" => "Elasticsearch or OpenSearch (for Searchkick)",
+      "opensearch-ruby" => "OpenSearch"
+    }.freeze
+    ERB_TAG = /<%.*?%>/m
+
+    # @param client [GithubClient]
+    # @param repository [String] owner/name
+    # @param ref [String] the branch, tag or commit to read
+    # @return [Hash] see #call, with +ref+ as asked and +commit+, the SHA it
+    #   named. A ref naming no commit is unsupported, and nothing is read.
+    def self.call(client, repository:, ref:)
+      commit = client.commit_sha(repository, ref)
+      return no_commit(repository, ref) if commit.nil?
+
+      report = Rails.cache.fetch([ name, ActionAgent::VERSION, repository, commit ], expires_in: CACHE_TTL) do
+        new(client, repository: repository, ref: commit).call
+      end
+      report.deep_stringify_keys.merge("ref" => ref, "commit" => commit)
+    end
+
+    def self.no_commit(repository, ref)
+      reason = "#{repository} has no commit at #{ref.presence || "its default branch"}"
+      {
+        "status" => "unsupported", "summary" => reason, "reasons" => [ reason ], "warnings" => [], "engine" => false,
+        "ruby" => nil, "ruby_source" => nil, "railties" => nil, "activeagent" => nil, "actionagent" => nil,
+        "database_adapters" => [], "services" => [], "ref" => ref, "commit" => nil, "checked_at" => Time.current.iso8601
+      }
+    end
+
+    def initialize(client, repository:, ref:)
+      @client = client
+      @repository = repository
+      @ref = ref
+    end
+
+    # @return [Hash] with string keys:
+    #   status            one of STATUSES
+    #   summary           what the picker shows: SUMMARIES' text, or the
+    #                     first reason the repository is not supported
+    #   reasons           why it is not supported (empty otherwise)
+    #   warnings          services and databases the sandbox may lack
+    #   engine            whether the Gemfile.lock locks actionagent
+    #   ruby, ruby_source the Ruby it needs and where that was read
+    #   railties, activeagent, actionagent   the locked versions, or nil
+    #   database_adapters the adapters config/database.yml names
+    #   services          what SERVICE_GEMS found
+    #   ref, checked_at
+    def call
+      lock_text = read("Gemfile.lock")
+      facts = lock_text ? lock_facts(lock_text) : nil
+      ruby, ruby_source = ruby_requirement(facts)
+      railties = facts&.dig("gems", "railties")
+      reasons = refusals(lock_text, facts, ruby, ruby_source, railties)
+      adapters = database_adapters
+      services = required_services(facts)
+      engine = facts&.dig("gems", "actionagent").present?
+      status = if reasons.any? then "unsupported" elsif engine then "supported" else "bootstrap" end
+
+      {
+        "status" => status,
+        "summary" => reasons.first || SUMMARIES.fetch(status),
+        "reasons" => reasons,
+        "warnings" => warnings(adapters, services),
+        "engine" => engine,
+        "ruby" => ruby,
+        "ruby_source" => ruby_source,
+        "railties" => railties,
+        "activeagent" => facts&.dig("gems", "activeagent"),
+        "actionagent" => facts&.dig("gems", "actionagent"),
+        "database_adapters" => adapters,
+        "services" => services,
+        "ref" => @ref,
+        "checked_at" => Time.current.iso8601
+      }
+    end
+
+    private
+
+    def read(path)
+      @files ||= {}
+      return @files[path] if @files.key?(path)
+
+      @files[path] = @client.file(@repository, path, ref: @ref)
+    end
+
+    def refusals(lock_text, facts, ruby, ruby_source, railties)
+      return [ "#{@repository} has no Gemfile.lock at its root: a sandbox needs a bundled Rails app" ] if lock_text.nil?
+      return [ "#{@repository}'s Gemfile.lock could not be read" ] if facts.nil?
+
+      reasons = []
+      if ruby && below?(ruby, SandboxBootSpec::MINIMUM_RUBY)
+        reasons << "#{@repository} needs Ruby #{ruby} (#{ruby_source}); the engine needs Ruby #{SandboxBootSpec::MINIMUM_RUBY} or later"
+      end
+      if railties.nil?
+        reasons << "#{@repository}'s Gemfile.lock locks no railties: a sandbox needs a Rails app"
+      elsif below?(railties, SandboxBootSpec::MINIMUM_RAILTIES)
+        reasons << "#{@repository} locks railties #{railties}; the engine needs Rails #{SandboxBootSpec::MINIMUM_RAILTIES} or later"
+      end
+      if read("config/application.rb").nil?
+        reasons << "#{@repository} has no config/application.rb at its root: a sandbox needs the Rails app at the repository root"
+      end
+      reasons
+    end
+
+    # { "ruby" => "3.3.6" or nil, "gems" => { name => version } }, or nil
+    # when the lock does not parse.
+    def lock_facts(text)
+      parser = ::Bundler::LockfileParser.new(text)
+      gems = parser.specs.each_with_object({}) { |spec, all| all[spec.name] ||= spec.version.to_s }
+      { "ruby" => parser.ruby_version.to_s[/\d+\.\d+(?:\.\d+)?/], "gems" => gems }
+    rescue StandardError
+      nil
+    end
+
+    def ruby_requirement(facts)
+      return [ facts["ruby"], "Gemfile.lock" ] if facts&.dig("ruby")
+
+      version = read(".ruby-version").to_s.lines.first.to_s.strip.delete_prefix("ruby-")[/\A\d+\.\d+(?:\.\d+)?/]
+      version ? [ version, ".ruby-version" ] : [ nil, nil ]
+    end
+
+    def below?(version, minimum)
+      Gem::Version.correct?(version) && Gem::Version.new(version) < minimum
+    end
+
+    def database_adapters
+      text = read("config/database.yml").to_s.gsub(ERB_TAG, "")
+      text.scan(/^[ \t]*adapter:[ \t]*["']?([A-Za-z0-9_]+)/).flatten.uniq
+    end
+
+    def required_services(facts)
+      gemfile = read("Gemfile").to_s
+      named = gemfile.scan(/^\s*gem\s+["']([A-Za-z0-9_.-]+)["']/).flatten
+      locked = facts ? facts["gems"].keys : []
+      (named | locked).filter_map { |gem| SERVICE_GEMS[gem] }.uniq.sort
+    end
+
+    def warnings(adapters, services)
+      known = LocalSandboxDatabases::FILE_ADAPTERS + LocalSandboxDatabases::SERVER_ADAPTERS
+      unknown = adapters - known
+      notes = services.map { |service| "The app uses #{service}, which a sandbox does not run: features that need it may fail." }
+      if unknown.any?
+        notes << "config/database.yml names #{unknown.join(", ")}, which a local sandbox cannot give databases of its own."
+      end
+      notes
+    end
+  end
+end

data/app/services/action_agent/project_secret_discovery.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to find the environment variables a repository expects before its
+  # first boot, so the project's secrets form can ask for all of them at
+  # once. Deterministic and model-free: the same files at the same commit give
+  # the same names. Read through GitHub's contents API:
+  #
+  #   .env.example, .env.sample   every NAME= line
+  #   .activeagents/sandbox.yml   its `secrets:` key, a list of names or a
+  #                               mapping of names to descriptions
+  #   config/**, lib/**           ENV.fetch("NAME") and ENV["NAME"] call sites
+  #                               in Ruby, YAML and ERB files, at most
+  #                               MAX_SCANNED_FILES of them in path order
+  #
+  # Variables Rails or the sandbox sets (RUNTIME_VARIABLES, and the names a
+  # ProjectSecret may not take) are left out.
+  #
+  # Every file is read at the commit the ref names, and only when the
+  # commit's file listing has it. What was found is kept in Rails.cache for
+  # that commit, so discovering a repository again costs one GitHub call
+  # until it changes.
+  class ProjectSecretDiscovery
+    ENV_FILES = %w[.env.example .env.sample].freeze
+    CACHE_TTL = 1.day
+    SANDBOX_CONFIG = LocalSandboxBackend::Config::PATH
+    SCANNED = %r{\A(?:config|lib)/[^\0]+\.(?:rb|ya?ml|erb)\z}
+    MAX_SCANNED_FILES = 40
+    MAX_SCANNED_BYTES = 128 * 1024
+    # Where a variable was found, listed up to this many places.
+    MAX_SOURCES = 5
+    ENV_FILE_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/
+    NAME = "[A-Za-z_][A-Za-z0-9_]*"
+    # ENV.fetch("NAME") with no default and no block: the app cannot boot
+    # without it.
+    REQUIRED_FETCH = /ENV\.fetch\(\s*["'](#{NAME})["']\s*\)(?!\s*(?:\{|do\b))/
+    ANY_FETCH = /ENV\.fetch\(\s*["'](#{NAME})["']/
+    INDEX = /ENV\[\s*["'](#{NAME})["']\s*\]/
+    RUNTIME_VARIABLES = %w[
+      CI HOME HOSTNAME JOB_CONCURRENCY LANG PIDFILE PORT RACK_ENV RAILS_ENV RAILS_LOG_LEVEL RAILS_LOG_TO_STDOUT
+      RAILS_MAX_THREADS RAILS_MIN_THREADS RAILS_SERVE_STATIC_FILES SOLID_QUEUE_IN_PUMA TZ WEB_CONCURRENCY
+    ].freeze
+
+    # @param client [GithubClient]
+    # @param repository [String] owner/name
+    # @param ref [String] the branch, tag or commit to read
+    # @return [Hash] see #call, with +ref+ as asked and +commit+, the SHA it
+    #   named
+    # @raise [GithubClient::NotFound] when the ref names no commit
+    def self.call(client, repository:, ref:)
+      commit = client.commit_sha(repository, ref) or
+        raise GithubClient::NotFound, "#{repository} has no commit at #{ref.presence || "its default branch"}"
+
+      found = Rails.cache.fetch([ name, ActionAgent::VERSION, repository, commit ], expires_in: CACHE_TTL) do
+        new(client, repository: repository, ref: commit).call
+      end
+      found.deep_symbolize_keys.merge(ref: ref, commit: commit)
+    end
+
+    def initialize(client, repository:, ref:)
+      @client = client
+      @repository = repository
+      @ref = ref
+      @found = {}
+    end
+
+    # @return [Hash]
+    #   variables  [{ name:, required:, sources: [String] (at most
+    #              MAX_SOURCES), description:, organization_key: provider or
+    #              nil }], sorted by name
+    #   scanned    the paths read for ENV call sites
+    #   truncated  whether files were left unread (more than
+    #              MAX_SCANNED_FILES, or GitHub truncated the file listing)
+    def call
+      listing = @client.tree(@repository, ref: @ref)
+      listed = listing[:paths].to_set { |entry| entry[:path] }
+      # A truncated listing may leave out a file that is there.
+      present = ->(path) { listing[:truncated] || listed.include?(path) }
+      ENV_FILES.select(&present).each { |path| scan_env_file(path) }
+      scan_sandbox_config if present.call(SANDBOX_CONFIG)
+      candidates = listing[:paths].select { |entry| SCANNED.match?(entry[:path]) && entry[:size] <= MAX_SCANNED_BYTES }
+        .sort_by { |entry| entry[:path] }
+      scanned = candidates.first(MAX_SCANNED_FILES).map { |entry| entry[:path] }
+      scanned.each { |path| scan_source(path) }
+
+      {
+        variables: @found.values.sort_by { |variable| variable[:name] }.map do |variable|
+          variable.merge(sources: variable[:sources].uniq.first(MAX_SOURCES),
+            organization_key: ProjectSecret::ORGANIZATION_KEY_PROVIDERS[variable[:name]])
+        end,
+        scanned: scanned,
+        truncated: listing[:truncated] || candidates.size > MAX_SCANNED_FILES,
+        ref: @ref
+      }
+    end
+
+    private
+
+    def scan_env_file(path)
+      text = @client.file(@repository, path, ref: @ref) or return
+
+      text.each_line.with_index(1) do |line, number|
+        name = line[ENV_FILE_LINE, 1]
+        note(name, "#{path}:#{number}") if name
+      end
+    end
+
+    def scan_sandbox_config
+      text = @client.file(@repository, SANDBOX_CONFIG, ref: @ref) or return
+
+      data = YAML.safe_load(text, aliases: false)
+      entries = data.is_a?(Hash) ? data["secrets"] : nil
+      case entries
+      when Array then entries.each { |name| note(name.to_s, SANDBOX_CONFIG, required: true) }
+      when Hash then entries.each { |name, description| note(name.to_s, SANDBOX_CONFIG, required: true, description: description) }
+      end
+    rescue Psych::Exception
+      nil
+    end
+
+    def scan_source(path)
+      text = @client.file(@repository, path, ref: @ref) or return
+
+      required = text.scan(REQUIRED_FETCH).flatten.to_set
+      text.each_line.with_index(1) do |line, number|
+        (line.scan(ANY_FETCH) + line.scan(INDEX)).flatten.each do |name|
+          note(name, "#{path}:#{number}", required: required.include?(name))
+        end
+      end
+    end
+
+    def note(name, source, required: false, description: nil)
+      return unless SandboxBootSpec::ENV_NAME.match?(name)
+      return if RUNTIME_VARIABLES.include?(name) || ProjectSecret.refused_name?(name)
+
+      entry = @found[name] ||= { name: name, required: false, sources: [], description: nil }
+      entry[:required] ||= required
+      entry[:sources] << source
+      entry[:description] ||= description.to_s.truncate(200).presence if description.is_a?(String)
+    end
+  end
+end