hecks 3.5.0 → 3.7.0

data/lib/hecks/doors/mcp_door_scope.rb

@@ -27,7 +27,7 @@ module Hecks
       # names a host or a URL, a binary to run, a place to write, a port to open, a store to
       # switch to, or flips a command from a preview to a change of state.
       DENIED_ARGUMENTS = %w[
-        adapter artifact confirm expected from gem_only header health_path host no_wait npm_local
+        adapter artifact confirm expected from gem_only header health_path host live no_wait npm_local
         npm_only output path payload payload_file port rust_binary scheme stage_dir state_path stdio url
         write
       ].freeze
@@ -39,19 +39,19 @@ module Hecks
 
       # Argument names whose values are git refs: plain names only, so a value cannot read as an
       # option to git.
-      REF_ARGUMENTS = %w[ref].freeze
+      REF_ARGUMENTS = %w[commit ref].freeze
 
       # What a plain git ref looks like: no leading dash, no `..`, no spaces.
       PLAIN_REF = %r{\A[A-Za-z0-9][A-Za-z0-9._/~^@-]*\z}
 
       # Unrestricted when no HECKS_DOOR_* variable is set.
       def self.from_env(env = ENV)
-        problems = setting_problems(env)
+        problems = EnvProblems.setting_problems(env)
         raise ArgumentError, problems.join("\n") unless problems.empty?
         return new(allowed_domains: nil) unless env[TOOLS_VARIABLE]
 
-        commands = env[TOOLS_VARIABLE] == COMMANDS ? split_names(env[COMMANDS_VARIABLE]) : nil
-        new(allowed_domains: split_paths(env[DOMAINS_VARIABLE]), allowed_commands: commands)
+        commands = env[TOOLS_VARIABLE] == COMMANDS ? EnvProblems.split_names(env[COMMANDS_VARIABLE]) : nil
+        new(allowed_domains: EnvProblems.split_paths(env[DOMAINS_VARIABLE]), allowed_commands: commands)
       end
 
       # Refuses to stderr, not stdout, which carries the MCP protocol.
@@ -62,49 +62,6 @@ module Hecks
         exit(EXIT_STATUS)
       end
 
-      def self.setting_problems(env)
-        known = [TOOLS_VARIABLE, DOMAINS_VARIABLE, COMMANDS_VARIABLE]
-        problems = (env.keys.select { |name| name.start_with?(ENV_PREFIX) } - known).map do |name|
-          "environment #{name} is not accepted; the door takes only #{known.join(', ')}"
-        end
-        problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE], env[COMMANDS_VARIABLE])
-      end
-
-      def self.mode_problems(tools, domains, commands)
-        return stray_problems(domains, commands) if tools.nil?
-        unless MODES.include?(tools)
-          return ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the values are #{MODES.map(&:inspect).join(' and ')}"]
-        end
-
-        problems = []
-        if split_paths(domains.to_s).empty?
-          problems << "#{TOOLS_VARIABLE}=#{tools} needs #{DOMAINS_VARIABLE}, the domains this door may read"
-        end
-        problems + command_problems(tools, commands)
-      end
-
-      def self.stray_problems(domains, commands)
-        stray = { DOMAINS_VARIABLE => domains, COMMANDS_VARIABLE => commands }.compact.keys
-        return [] if stray.empty?
-
-        ["#{stray.join(' and ')} set without #{TOOLS_VARIABLE}=#{READERS} or #{TOOLS_VARIABLE}=#{COMMANDS}; " \
-         "they only narrow a restricted door"]
-      end
-
-      def self.command_problems(tools, commands)
-        if tools == COMMANDS && split_names(commands).empty?
-          ["#{TOOLS_VARIABLE}=#{COMMANDS} needs #{COMMANDS_VARIABLE}, the commands this door may dispatch"]
-        elsif tools == READERS && !commands.nil?
-          ["#{COMMANDS_VARIABLE} is set in reader mode; it only narrows a commands door"]
-        else
-          []
-        end
-      end
-
-      def self.split_paths(value) = value.to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
-
-      def self.split_names(value) = value.to_s.split(",").map(&:strip).reject(&:empty?).uniq
-
       # The named domains, resolved against Storehouse::BOOT_ROOT; nil when unrestricted.
       attr_reader :allowed_domains
 
@@ -136,7 +93,7 @@ module Hecks
       def refusal(name)
         { ok:    false,
           error: "#{name.inspect} is refused: this door runs in #{mode_label}, " \
-                 "which serves only #{served_tools.join(', ')}" }
+                 "which serves only #{served_tools.join(", ")}" }
       end
 
       # Checked before anything boots, so a path outside the allowed set never reaches Kernel.load.
@@ -146,7 +103,7 @@ module Hecks
 
         raise Runtime::TypeMismatch,
               "domain: #{domain.inspect} is refused: this door runs in #{mode_label} " \
-              "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
+              "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(", ")}"
       end
 
       # A commands door dispatches only the commands it was given. A requested name and each
@@ -165,7 +122,7 @@ module Hecks
         unless verbs.first && verbs.drop(1).include?(verbs.first)
           raise Runtime::TypeMismatch,
                 "command: #{command.to_s.inspect} is refused: this door runs in #{mode_label} " \
-                "and dispatches only #{COMMANDS_VARIABLE}: #{allowed_commands.join(', ')}"
+                "and dispatches only #{COMMANDS_VARIABLE}: #{allowed_commands.join(", ")}"
         end
 
         admit_arguments!(args)
@@ -194,12 +151,7 @@ module Hecks
       def admit_arguments!(args)
         return unless restricted?
 
-        each_argument(args) do |name, value|
-          refuse_argument!(name, "never passes it on: it names a host, a binary, an output or a change of state") if
-            DENIED_ARGUMENTS.include?(name)
-          admit_path!(name, value) if PATH_ARGUMENTS.include?(name)
-          admit_ref!(name, value) if REF_ARGUMENTS.include?(name)
-        end
+        ArgumentPolicy.admit!(args, mode_label)
       end
 
       # The one domain a restricted door serves, when it serves exactly one: a call may leave
@@ -220,138 +172,30 @@ module Hecks
         args.merge("domain" => default_domain)
       end
 
-      # The tool as `tools/list` shows it. A door that serves one domain makes `domain:` optional.
-      # On a commands door, `dispatch` also names the commands it serves as an enum, so a caller
-      # sees them as typed choices instead of finding out by being refused, and says what each
-      # takes and which role it declares.
+      # The tool as `tools/list` shows it; see `Presenter.present`.
       #
       # @param tool [Hash] a tool definition from `McpDoor::TOOLS`
       # @param guide [Array<String>, nil] one line per allowed command (`Storehouse.command_guide`)
       # @return [Hash] the definition, narrowed for this door
       def present(tool, guide = nil)
-        tool = domain_optional(tool) if default_domain
-        return tool unless commands_mode? && tool[:name] == "dispatch"
-
-        properties = tool[:inputSchema][:properties]
-        narrowed = properties.merge(command: with_enum(properties[:command]),
-                                    steps:   properties[:steps].merge(items: step_items(properties[:steps][:items])))
-        tool.merge(description: dispatch_description(tool[:description], guide),
-                   inputSchema: tool[:inputSchema].merge(properties: narrowed))
+        Presenter.present(self, tool, guide)
       end
 
       def notes
         return [] unless restricted?
 
-        commands_mode? ? commands_notes : reader_notes
+        commands_mode? ? Presenter.commands_notes(@allowed_domains, @allowed_commands) : Presenter.reader_notes(@allowed_domains)
       end
 
       private
 
-      # Yields every argument name with its value, descending into nested objects and lists, so
-      # `{"file" => {"value" => "x"}}` is checked the way `{"file" => "x"}` is.
-      def each_argument(args, &visit)
-        case args
-        when Hash
-          args.each do |name, value|
-            visit.call(name.to_s, value)
-            each_argument(value, &visit)
-          end
-        when Array
-          args.each { |item| each_argument(item, &visit) }
-        end
-      end
-
-      # A value written as an object of one field (`{"value" => "x"}`) is that field's value.
-      def scalar(value)
-        return value unless value.is_a?(Hash)
-
-        value.fetch("value") { value.fetch(:value, value) }
-      end
-
-      def refuse_argument!(name, why)
-        raise Runtime::TypeMismatch, "argument: #{name.inspect} is refused: this door runs in #{mode_label} and #{why}"
-      end
-
-      def admit_path!(name, value)
-        Array(scalar(value)).flat_map { |item| item.to_s.split(",") }.reject(&:empty?).each do |path|
-          next if !path.include?(":") && inside_root?(path)
-
-          refuse_argument!(name, "passes a path only when it resolves inside #{Storehouse::BOOT_ROOT} " \
-                                 "and holds no colon: #{path.inspect}")
-        end
-      end
-
-      def admit_ref!(name, value)
-        ref = scalar(value).to_s
-        return if ref.match?(PLAIN_REF) && !ref.include?("..")
-
-        refuse_argument!(name, "passes only a plain git ref: #{ref.inspect}")
-      end
-
-      def inside_root?(path)
-        root = resolve_real(Storehouse::BOOT_ROOT)
-        resolved = resolve_real(File.expand_path(path, Storehouse::BOOT_ROOT))
-        resolved == root || resolved.start_with?("#{root}#{File::SEPARATOR}")
-      end
-
-      # The real path of `path`, symlinks followed: of the whole path when it exists, else of its
-      # deepest existing parent with the missing names put back, so a link above a file that does
-      # not exist yet still shows where the file would land.
-      def resolve_real(path)
-        missing = []
-        current = File.expand_path(path)
-        until File.exist?(current)
-          parent = File.dirname(current)
-          break if parent == current
-
-          missing.unshift(File.basename(current))
-          current = parent
-        end
-        File.join(File.realpath(current), *missing)
-      end
-
-      def domain_optional(tool)
-        schema = tool[:inputSchema]
-        return tool unless schema[:properties].key?(:domain)
-
-        note = "Optional: this door serves one domain, #{default_domain}, and uses it when you leave this out."
-        properties = schema[:properties].merge(domain: schema[:properties][:domain].merge(description: note))
-        tool.merge(inputSchema: schema.merge(properties: properties, required: schema[:required] - ["domain"]))
-      end
-
-      def dispatch_description(base, guide)
-        intro = "#{base} This door dispatches only the commands below, each with the role it declares: pass " \
-                "that role as `role`. A command that takes `run` takes a key you choose, and the call answers " \
-                "the record as it stands once its reactions have run; an argument marked * is required."
-        entries = Array(guide).empty? ? allowed_commands : guide
-        ([intro] + entries.map { |entry| "- #{entry}" }).join("\n")
-      end
-
-      def with_enum(property)
-        property.merge(enum: allowed_commands)
-      end
-
-      def step_items(items)
-        items.merge(properties: items[:properties].merge(command: with_enum(items[:properties][:command])))
-      end
-
       def mode_label
         commands_mode? ? "commands mode (#{TOOLS_VARIABLE}=#{COMMANDS})" : "reader mode (#{TOOLS_VARIABLE}=#{READERS})"
       end
-
-      def reader_notes
-        ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(', ')}; " \
-         "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
-         "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
-         "Reader mode limits reach and identifies no one; it is not authentication."]
-      end
-
-      def commands_notes
-        ["Commands mode (#{TOOLS_VARIABLE}=#{COMMANDS}): serves #{READER_TOOLS.join(', ')} and dispatch of only " \
-         "#{COMMANDS_VARIABLE}: #{@allowed_commands.join(', ')}; refuses behaviors and every other tool.",
-         "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
-         "Commands mode limits reach and identifies no one; role: stays self-asserted and it is not authentication."]
-      end
     end
   end
 end
+
+require_relative "mcp_door_scope/env_problems"
+require_relative "mcp_door_scope/argument_policy"
+require_relative "mcp_door_scope/presenter"

data/lib/hecks/doors/ruby_door/aggregate_door.rb

@@ -3,7 +3,7 @@ require_relative "../../bluebook/dsl/world_builder"
 require_relative "../../bluebook/dsl/domain_port_builder"
 require_relative "../../bluebook/dsl/const_shim"
 require_relative "../../bluebook/dsl/binding_proxy"
-require_relative "../../bluebook/hexagon"
+require_relative "../../bluebook/hecksagon"
 require_relative "../handle"
 require_relative "../../naming"
 

data/lib/hecks/doors/ruby_door/chapter.rb

@@ -20,11 +20,28 @@ module Hecks
         # @raise [NameError] if an aggregate's name is not a valid constant name
         def chapter_module(dispatcher, bluebook)
           chapter = Module.new
+          define_readers(chapter, bluebook)
+          define_projections(chapter, bluebook)
+
+          bluebook.aggregates.each do |aggregate|
+            chapter.const_set(aggregate.hecks_name, aggregate_module(dispatcher, bluebook.name, aggregate))
+          end
+
+          define_const_missing(chapter, bluebook)
+          chapter
+        end
+
+        private
+
+        # The chapter's vision and its aggregate names.
+        def define_readers(chapter, bluebook)
           chapter.define_singleton_method(:vision)     { bluebook.vision }
           chapter.define_singleton_method(:aggregates) { bluebook.aggregates.map(&:name).sort }
+        end
 
-          # The chapter's usage document, projected from its IR on each call so it
-          # cannot go stale.
+        # The chapter's documents and projections, each projected from its IR on every call so
+        # none can go stale.
+        def define_projections(chapter, bluebook)
           chapter.define_singleton_method(:docs) do |**options|
             Projector.call(:docs, bluebook: bluebook, options: options)
           end
@@ -34,11 +51,15 @@ module Hecks
             Projector.call(:narrate, bluebook: bluebook, options: options)
           end
 
-          # Projects the chapter's IR through a target; `out:` writes the artifact and
-          # the remaining options go to the projector (`audience:` for OIDC).
-          #
-          #   Pizzas.project(Projections::OIDC)
-          #   Pizzas.project(Projections::Shape, out: "shape.json")
+          define_project(chapter, bluebook)
+        end
+
+        # Projects the chapter's IR through a target; `out:` writes the artifact and
+        # the remaining options go to the projector (`audience:` for OIDC).
+        #
+        #   Pizzas.project(Projections::OIDC)
+        #   Pizzas.project(Projections::Shape, out: "shape.json")
+        def define_project(chapter, bluebook)
           chapter.define_singleton_method(:project) do |target, out: nil, **options|
             key      = Projector.key_for(target)
             artifact = Projector.call(key, bluebook: bluebook, options: options)
@@ -46,14 +67,12 @@ module Hecks
 
             Projector.write(artifact, out, as: Projector.emits_for(key))
           end
+        end
 
-          bluebook.aggregates.each do |aggregate|
-            chapter.const_set(aggregate.hecks_name, aggregate_module(dispatcher, bluebook.name, aggregate))
-          end
-
-          # Inside a hecksagon a name is a declaration: with a collector open it becomes
-          # a `BindingProxy`. Otherwise a scoped reference from a bluebook mid-declaration
-          # goes to the `ConstShim` resolver, so it resolves whether or not a facade exists.
+        # Inside a hecksagon a name is a declaration: with a collector open it becomes
+        # a `BindingProxy`. Otherwise a scoped reference from a bluebook mid-declaration
+        # goes to the `ConstShim` resolver, so it resolves whether or not a facade exists.
+        def define_const_missing(chapter, bluebook)
           chapter.define_singleton_method(:const_missing) do |name|
             collector = Bluebook::DSL::HecksagonBuilder.collector
             return Bluebook::DSL::BindingProxy.new("#{bluebook.name}::#{name}", collector) if collector
@@ -63,8 +82,6 @@ module Hecks
 
             super(name)
           end
-
-          chapter
         end
       end
     end

data/lib/hecks/doors/ruby_door.rb

@@ -32,21 +32,24 @@ module Hecks
       # @raise [NameError] if a chapter or aggregate name is not a valid constant name
       def install(dispatcher)
         dispatcher.registry.bluebooks.each_value do |bluebook|
-          next if attached_chapter?(dispatcher.registry, bluebook)
+          install_chapter(dispatcher, bluebook) unless attached_chapter?(dispatcher.registry, bluebook)
+        end
+        dispatcher
+      end
 
-          chapter = chapter_module(dispatcher, bluebook)
-          Namespace.install(*placement(bluebook), chapter)
-          # A namespaced chapter keeps its aggregates inside its namespace: top-level
-          # shortcuts would bring back the collisions the namespace exists to avoid.
-          next if bluebook.namespace
+      # Installs one chapter's module, and the top-level shortcut of each of its aggregates.
+      def install_chapter(dispatcher, bluebook)
+        chapter = chapter_module(dispatcher, bluebook)
+        Namespace.install(*placement(bluebook), chapter)
+        # A namespaced chapter keeps its aggregates inside its namespace: top-level
+        # shortcuts would bring back the collisions the namespace exists to avoid.
+        return if bluebook.namespace
 
-          bluebook.aggregates.each do |aggregate|
-            next if aggregate.hecks_name == bluebook.name
+        bluebook.aggregates.each do |aggregate|
+          next if aggregate.hecks_name == bluebook.name
 
-            Namespace.install(Object, aggregate.hecks_name, chapter.const_get(aggregate.hecks_name, false))
-          end
+          Namespace.install(Object, aggregate.hecks_name, chapter.const_get(aggregate.hecks_name, false))
         end
-        dispatcher
       end
 
       # Whether `bluebook` is a gem chapter that a hecksagon attached rather than a domain's own.

data/lib/hecks/doors/usage_cache.rb

@@ -8,8 +8,9 @@ module Hecks
     #
     # The help is a pure function of the domain's declarations and of the gem that projects them,
     # and reading those is most of what a launcher costs. The answer is kept in a file named for a
-    # digest of everything it depends on (the domain's declaration files, the gem's own library,
-    # the hecks and Ruby versions, the environment overlay, the command line and the program name),
+    # digest of everything it depends on (the domain's declaration files, the gem's judging code and
+    # doors, the hecks and Ruby versions, the environment overlay, the command line and the
+    # program name),
     # so any edit to one of them is simply a different entry: nothing is ever stale, only unused.
     # Only an answer that ended well is kept, and any trouble with the cache itself is ignored
     # and the help is worked out as if it did not exist.
@@ -33,22 +34,28 @@ module Hecks
       # @param runtime [#directory] what `Hecks.describe` answered; anything else bypasses the cache
       # @param argv [Array<String>] the command line
       # @param program [String] how the caller was invoked
+      # @param audience [String] who the help is for, since the same line reads differently to each
       # @yield works the answer out, loading the domain
       # @yieldreturn [Array(String, Integer), nil] the text and status; nil if it runs a command
       # @return [Array(String, Integer), nil] the block's answer, or the remembered one
-      def fetch(runtime, argv, program)
+      def fetch(runtime, argv, program, audience: "")
         directory = runtime.respond_to?(:directory) ? runtime.directory : nil
         return yield unless directory && enabled?
 
-        file = entry_path(directory, argv, program)
+        file = entry_path(directory, argv, program, audience)
         remembered = file && recall(file)
         return remembered if remembered
 
         answer = yield
-        remember(file, answer) if file && answer&.last&.zero?
+        remember(file, answer) if worth_keeping?(file, answer)
         answer
       end
 
+      # Whether an answer that ended well can be written to the entry's file.
+      def worth_keeping?(file, answer)
+        file && answer&.last&.zero?
+      end
+
       # @return [Boolean] whether the cache is on
       def enabled?
         off = ENV[DISABLE_VARIABLE].to_s
@@ -63,28 +70,37 @@ module Hecks
       # The file that holds the answer for this command line, named by what it depends on.
       #
       # @return [String, nil] nil when the digest cannot be taken
-      def entry_path(domain, argv, program)
+      def entry_path(domain, argv, program, audience = "")
         digest = Digest::SHA256.new
-        [Hecks::VERSION, RUBY_VERSION, ENV["HECKS_ENVIRONMENT"].to_s, program, argv.join("\0")].each do |part|
-          digest << part.to_s << "\0"
-        end
-        [domain, library].each { |root| fingerprint(root, digest) }
+        key_parts(program, audience, argv).each { |part| digest << part.to_s << "\0" }
+        fingerprint_code(domain, digest)
         File.join(directory, "usage-#{digest.hexdigest}.json")
       rescue SystemCallError
         nil
       end
 
-      # Feeds the digest every declaration file under `root`: its path, size and modification time.
+      # @return [Array<String>] what the answer depends on besides the files: the gem and Ruby
+      #   series, the environment overlay, the program and audience and the command line
+      def key_parts(program, audience, argv)
+        [Hecks::VERSION, Hecks::Bluebook::MetaValidator::VerdictCache.ruby_series,
+         ENV["HECKS_ENVIRONMENT"].to_s, program, audience, argv.join("\0")]
+      end
+
+      # Feeds the digest every declaration file under `root`: its path below `root` and its bytes,
+      # so a touch or a checkout elsewhere keeps the entry and an edit does not.
       def fingerprint(root, digest)
         Dir.glob(File.join(root, "**", DECLARATIONS)).each do |file|
-          stat = File.stat(file)
-          digest << file << ":" << stat.size.to_s << ":" << stat.mtime.to_f.to_s << "\0"
+          digest << file.delete_prefix(root) << "\0" << File.binread(file) << "\0"
         end
       end
 
-      # @return [String] the gem's own library directory, which the frameworks load from
-      def library
-        File.expand_path("..", __dir__)
+      # Feeds the digest what shapes a help text: the domain's declarations, the judging trees of
+      # the gem (the same set the verdict cache keys on) and the doors that render the text. An
+      # edit to the gem's projections, deploy or release code cannot change a help line.
+      def fingerprint_code(domain, digest)
+        fingerprint(domain, digest)
+        digest << Hecks::Bluebook::MetaValidator::VerdictCache.code_digest << "\0"
+        fingerprint(__dir__, digest)
       end
 
       # Reads the remembered answer and marks the entry as used, so a sweep keeps what is read.

data/lib/hecks/doors.rb

@@ -24,10 +24,8 @@ module Hecks
 
       if container.const_defined?(name, false)
         current = container.const_get(name)
-        unless GENERATED[[container, name]].equal?(current)
-          warn "[hecks] #{name} is already defined — leaving it alone"
-          return current
-        end
+        return leave_alone(name, current) unless GENERATED[[container, name]].equal?(current)
+
         container.send(:remove_const, name)
       end
 
@@ -35,6 +33,14 @@ module Hecks
       GENERATED[[container, name]] = value
       value
     end
+
+    # @param name [String] the constant name
+    # @param current [Object] the constant user code or the stdlib owns
+    # @return [Object] `current`, after warning that it was left in place
+    def leave_alone(name, current)
+      warn "[hecks] #{name} is already defined — leaving it alone"
+      current
+    end
   end
 end
 

data/lib/hecks/embryonaut_bluebook/manifest.rb

@@ -84,15 +84,23 @@ module Hecks
       end
 
       def judge(name, dir, lock, problems)
+        judge_fields(name, lock, problems)
+        judge_release(name, lock, problems)
+        judge_digest(name, dir, lock, problems)
+      end
+
+      def judge_fields(name, lock, problems)
         FIELDS.each { |field| problems << "#{name}: bluebook.lock has no #{field}" if blank?(lock[field.to_sym]) }
         problems << "#{name}: bluebook.lock names package #{lock.package}" if lock.package && lock.package != name
         problems << "#{name}: bluebook.lock has no shape" if Array(lock.shape).empty?
-        judge_release(name, lock, problems)
+      end
+
+      def judge_digest(name, dir, lock, problems)
         actual = Lock.digest_of(File.join(dir, "bluebook"))
         return if actual == lock.digest
 
-        problems << "#{name}: vendored files hash to #{(actual || 'nothing')[0, 12]}, but bluebook.lock says " \
-                    "#{(lock.digest || '?')[0, 12]} (edited by hand, or re-vendored without its lock?)"
+        problems << "#{name}: vendored files hash to #{(actual || "nothing")[0, 12]}, but bluebook.lock says " \
+                    "#{(lock.digest || "?")[0, 12]} (edited by hand, or re-vendored without its lock?)"
       end
 
       # The tag of a release is `<package>-v<version>`; a lock saying otherwise was edited.

data/lib/hecks/embryonaut_bluebook/registry/changelog.rb

@@ -0,0 +1,26 @@
+module Hecks
+  module EmbryonautBluebook
+    class Registry
+      # A package's `CHANGELOG.md`: whether a version has an entry, and what it says. Included in
+      # `Registry`.
+      module Changelog
+        private
+
+        def changelog_entry?(package, version)
+          file = File.join(@root, package, "CHANGELOG.md")
+          File.file?(file) && File.read(file).match?(/^## #{Regexp.escape(version)}( |$)/)
+        end
+
+        # The lines under a version's heading, up to the next heading, without trailing blank lines.
+        def changelog_section(package, version)
+          on = false
+          lines = File.readlines(File.join(@root, package, "CHANGELOG.md"), chomp: true).select do |line|
+            on = line.match?(/^## #{Regexp.escape(version)}( |$)/) if line.start_with?("## ")
+            on && !line.start_with?("## ")
+          end
+          lines.join("\n").sub(/\n+\z/, "")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/registry/versions.rb

@@ -0,0 +1,27 @@
+module Hecks
+  module EmbryonautBluebook
+    class Registry
+      # A package's versions: the one its manifest says, the release tags it has, and which of two
+      # is newer. Included in `Registry`.
+      module Versions
+        private
+
+        def manifest_version(package)
+          file = File.join(@root, package, "bluebook.yml")
+          File.file?(file) ? File.read(file)[/^version: *(.*)$/, 1] : nil
+        end
+
+        def tags(package) = @source.tags("#{package}-v*")
+
+        def latest_version(package)
+          tags(package).map { |tag| tag.delete_prefix("#{package}-v") }.max_by { |version| order(version) }
+        end
+
+        # The greater of two versions, compared as `sort -V` does: runs of digits as numbers.
+        def newest(left, right) = [left, right].max_by { |version| order(version) }
+
+        def order(version) = version.scan(/\d+|\D+/).map { |part| part.match?(/\A\d/) ? [0, part.to_i, ""] : [1, 0, part] }
+      end
+    end
+  end
+end