milestoner 19.1.0 → 19.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a8bf5d3a4c7b698072a246f82b192a61e6284d5cb4596c1a23f884f83acc96d
-  data.tar.gz: ae0f82e2988be5295f10fb6c655d91763db92276950249738a6ee1c4ef7b7708
+  metadata.gz: 7d957f55958fe682de293955b8ae7d1762722654ab97323da41473e21a76c3b1
+  data.tar.gz: ed92635b6e20f6dbfb0ef8c43f11368bff7114aac753c8057753414e95e2e055
 SHA512:
-  metadata.gz: c92da6d4112e257e62868a046e4716954074051c38eba7b3fe3d06c7eae4ade9901f4f606ec6f849037b553eb95c1f000271d5030e894b613d0487991a9b5991
-  data.tar.gz: 913652d13c4e1a248e2f68becc4efe4eedd3c8af29d1563b660c284205f733a1719f14310552a69d281649d8ca05de5417797e60f18c63b65723670be91e33ac
+  metadata.gz: 7f78eb0132c2c5ea28e8d456bbd438cc0536785d085234cbc55fb431f712df51387bfa72102b127929cee70aba359b6bc507a97241498382f02be1a930334cd9
+  data.tar.gz: da79e4b9aa49da378d9e037799a85c63c66d5b9c743e1e0854157d9e525416eee21b4f24f65310b493984157ec2c61464c71e00d95c55c18575604ec8354c337

data/README.adoc

@@ -171,6 +171,7 @@ build:
   format: "stream"
   index: true
   layout: "page"
+  manifest: false
   max: 1
   output: "tmp/milestones"
   stylesheet: true
@@ -236,7 +237,8 @@ The above can be customized as follows:
 ** `basename`: Required. The build file basename. Default: `index`. Used to customize the built file name.
 ** `format`: Required. The build output format. Default: `stream`. Used to determine what format to build the release notes as. Multiple formats are supported.
 ** `index`: Required. Enables (or disables) building the versions index page for web format only. Default: true.
-** `layout`: Required. The {hanami_views_link} layout used when building release notes. Default: page. This can be disabled when using `false` or customized further -- via your own {xdg_link} configuration -- when providing your own templates and/or partials.
+** `layout`: Required. The {hanami_views_link} layout used when building release notes. Default: `page`. This can be disabled when using `false` or customized further -- via your own {xdg_link} configuration -- when providing your own templates and/or partials.
+** `manifest`: Required. The JSON manifest of milestones built. Handy for when you've built/cached previous milestones and want a quick way to check for differences (if any). Default: `false`.
 ** `max`: Required. The maximum number of {git_link} tags to build. Default: 1. By default, you are limited to building release notes for changes (commits) since the last tag but you can increase the maximum to build release notes for as many tags as you like.
 ** `output`: Required. The the directory for all generated output. Default: `tmp/milestones`. This can be a relative or absolute path and defaults to the current working directory. The path is automatically created if missing.
 ** `stylesheet`: Required. Enables (or disables) building the stylesheet for web format only. Default: true.
@@ -548,6 +550,97 @@ Milestone: patch
 
 Given the above, the resulting version would be: 2.0.0. This is because the highest milestone was a _major_ milestone.
 
+==== Manifest
+
+When the manifest is enabled via the global/local {xdg_link} configuration or via the CLI, then a `manifest.json` file will be created for you in the root of your build output folder with contents similar to the following:
+
+[source,json]
+----
+{
+  "generator": {
+    "label": "Milestoner",
+    "version": "19.0.0"
+  },
+  "latest": "1.0.0",
+  "versions": [
+    "0.0.1",
+    "0.1.0",
+    "1.0.0"
+  ]
+}
+----
+
+The above breaks down as follows:
+
+* `generator`: Captures generator details at time of manifest creation.
+* `latest`: The most recent version built.
+* `versions`: The array of versions built based on max build settings.
+
+The manifest allows you to capture build details which can be useful when needing to compare differences between a previous and current build. For convience, you can use the `Milestoner::Tags::Manifest` class to manage manifests. Example:
+
+[source,ruby]
+----
+manifest = Milestoner::Tags::Manifest.new
+latest_path = Pathname "$HOME/Engineering/OSS/demo/tmp/milestones/latest.json"
+
+manifest.write generator: {label: "Milestoner", version: "19.0.0"},
+               latest: "0.0.1",
+               versions: %w[0.0.0 0.0.1]
+# $HOME/Engineering/OSS/demo/tmp/milestones/manifest.json
+
+manifest.write latest_path,
+               generator: {label: "Milestoner", version: "19.0.0"},
+               latest: "0.0.2",
+               versions: %w[0.0.0 0.0.1 0.0.2]
+# $HOME/Engineering/OSS/demo/tmp/milestones/latest.json
+
+manifest.read
+# {
+#   :generator => {
+#     :label => "Milestoner",
+#     :version => "19.0.0"
+#   },
+#   :latest => "0.0.1",
+#   :versions => [
+#     "0.0.0",
+#     "0.0.1"
+#   ]
+# }
+
+manifest.read latest_path
+# {
+#   :generator => {
+#     :label => "Milestoner",
+#     :version => "19.0.0"
+#   },
+#   :latest => "0.0.2",
+#   :versions => [
+#     "0.0.0",
+#     "0.0.1",
+#     "0.0.2"
+#   ]
+# }
+
+manifest.diff latest_path
+# {
+#   :latest => [
+#     "0.0.2",
+#     "0.0.1"
+#   ],
+#   :versions => [
+#     [
+#       "0.0.0",
+#       "0.0.1",
+#       "0.0.2"
+#     ],
+#     [
+#       "0.0.0",
+#       "0.0.1"
+#     ]
+#   ]
+# }
+----
+
 ==== Templates
 
 Template functionality is powered by {hanami_views_link} which means you can completely customize _all_ build formats, templates, partials, stylesheets, images, and much more.

data/lib/milestoner/builders/container.rb

@@ -10,6 +10,7 @@ module Milestoner
 
       register(:ascii_doc) { ASCIIDoc.new }
       register(:feed) { Feed.new }
+      register(:manifest) { Manifest.new }
       register(:markdown) { Markdown.new }
       register(:stream) { Stream.new }
       register(:web) { Web.new }

data/lib/milestoner/builders/manifest.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Milestoner
+  module Builders
+    # Builds JSON manifest.
+    class Manifest
+      include Dry::Monads[:result]
+      include Milestoner::Dependencies[:settings, :git, :logger]
+
+      def initialize(writer: Tags::Manifest.new, path_resolver: PathResolver, **)
+        super(**)
+        @writer = writer
+        @path_resolver = path_resolver
+      end
+
+      def call
+        return Success writer.build_path unless settings.build_manifest
+
+        git.tags.either -> tags { write tags }, -> message { failure message }
+      end
+
+      private
+
+      attr_reader :writer, :path_resolver
+
+      def write tags
+        path_resolver.call writer.build_path, logger: do
+          versions = tags.map(&:version)
+          writer.write latest: versions.last, versions:
+        end
+      end
+
+      def failure message
+        logger.error { message }
+        Failure message
+      end
+    end
+  end
+end

data/lib/milestoner/builders/path_resolver.rb

@@ -10,7 +10,7 @@ module Milestoner
 
     PathResolver = lambda do |path, logger:, &block|
       if path.exist?
-        logger.warn { "Skipped (exists): #{path}." }
+        logger.warn { "Path exists: #{path}. Skipped." }
       else
         path.make_ancestors
         block.call path if block

data/lib/milestoner/builders/site/indexer.rb

@@ -20,6 +20,7 @@ module Milestoner
           return Success() unless settings.build_index
 
           path_resolver.call settings.build_output.join("index.html"), logger: do |path|
+            settings.project_version = nil
             path.write view.call(tags:, layout: settings.build_layout)
           end
         end

data/lib/milestoner/builders/syndication/builder.rb

@@ -103,7 +103,7 @@ module Milestoner
 
           node.merge id: format(settings.syndication_id, id: version),
                      title: format(settings.syndication_entry_label, id: version),
-                     link: format(settings.syndication_entry_uri, id: version),
+                     link: format(settings.syndication_entry_uri, id: "#{version}/"),
                      rights: committed_at.strftime("%Y"),
                      published: committed_at,
                      updated: committed_at

data/lib/milestoner/cli/actions/build/manifest.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "sod"
+
+module Milestoner
+  module CLI
+    module Actions
+      module Build
+        # Handles build manifest.
+        class Manifest < Sod::Action
+          include Dependencies[:settings]
+
+          description "Enable/disable manifest."
+
+          on "--[no-]manifest"
+
+          default { Container[:settings].build_manifest }
+
+          def call(boolean) = settings.build_manifest = boolean
+        end
+      end
+    end
+  end
+end

data/lib/milestoner/cli/commands/build.rb

@@ -8,7 +8,7 @@ module Milestoner
       # Handles the building of different milestone formats.
       class Build < Sod::Command
         include Dependencies[:settings, :logger, :io]
-        include Builders::Dependencies[:ascii_doc, :feed, :markdown, :stream, :web]
+        include Builders::Dependencies[:ascii_doc, :feed, :manifest, :markdown, :stream, :web]
 
         handle "build"
 
@@ -19,6 +19,7 @@ module Milestoner
         on Actions::Build::Index
         on Actions::Build::Label
         on Actions::Build::Layout
+        on Actions::Build::Manifest
         on Actions::Build::Max
         on Actions::Build::Output
         on Actions::Build::Stylesheet
@@ -35,6 +36,8 @@ module Milestoner
           else
             logger.abort "Invalid build format: #{format}."
           end
+
+          manifest.call
         end
 
         private

data/lib/milestoner/configuration/contract.rb

@@ -14,6 +14,7 @@ module Milestoner
       required(:build_index).filled :bool
       required(:build_layout) { str? | bool? }
       required(:build_max).filled :integer
+      required(:build_manifest).filled :bool
       required(:build_output).filled Etcher::Types::Pathname
       required(:build_stylesheet).filled :bool
       required(:build_tail).filled :string

data/lib/milestoner/configuration/defaults.yml

@@ -5,6 +5,7 @@ build:
   format: "stream"
   index: true
   layout: "page"
+  manifest: false
   max: 1
   output: "tmp/milestones"
   stylesheet: true

data/lib/milestoner/configuration/model.rb

@@ -8,6 +8,7 @@ module Milestoner
                        :build_format,
                        :build_index,
                        :build_layout,
+                       :build_manifest,
                        :build_max,
                        :build_output,
                        :build_stylesheet,

data/lib/milestoner/durationer.rb

@@ -3,23 +3,30 @@
 require "refinements/array"
 require "refinements/string"
 
-# Computes duration (in seconds) into human readable days, hours, minutes, and seconds.
+# Computes duration (in seconds) into human readable years, days, hours, minutes, and seconds.
 module Milestoner
   using Refinements::Array
   using Refinements::String
 
-  DURATION_UNITS = {"second" => 60, "minute" => 60, "hour" => 24, "day" => 86_400}.freeze
+  DURATION_UNITS = {
+    "year" => 31_536_000,  # 60 * 60 * 25 * 365
+    "day" => 86_400,       # 60 * 60 * 25
+    "hour" => 3_600,       # 60 * 60
+    "minute" => 60,
+    "second" => 1
+  }.freeze
 
   Durationer = lambda do |seconds, units: DURATION_UNITS|
-    result = units.map do |unit, value|
-      next unless seconds.positive?
+    return "0 seconds" if seconds.negative? || seconds.zero?
 
-      seconds, number = seconds.divmod value
-      number = number.to_i
+    result = units.map do |unit, divisor|
+      count, seconds = seconds.divmod divisor
 
-      %(#{number} #{unit.pluralize "s", number}) if number.nonzero?
+      next if count.zero?
+
+      %(#{count} #{unit.pluralize "s", count})
     end
 
-    result.compact.reverse.to_sentence
+    result.compact.to_sentence
   end
 end

data/lib/milestoner/tags/manifest.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "core"
+require "json"
+require "refinements/hash"
+require "refinements/pathname"
+
+module Milestoner
+  module Tags
+    # Manages build manifest.
+    class Manifest
+      include Dependencies[:settings, :git]
+
+      using Refinements::Hash
+      using Refinements::Pathname
+
+      def initialize(name: "manifest.json", **)
+        super(**)
+        @name = name
+      end
+
+      def build_path = settings.build_output.join name
+
+      def diff path = build_path
+        git.tags.value_or(Core::EMPTY_ARRAY).then do |tags|
+          return Core::EMPTY_HASH if tags.empty?
+
+          content_for(tags).diff read(path)
+        end
+      end
+
+      def read(path = build_path) = JSON(path.read, {symbolize_names: true})
+
+      def write(path = build_path, **)
+        path.make_ancestors.write JSON.pretty_generate(generator.deep_merge(**))
+      end
+
+      private
+
+      attr_reader :name
+
+      # :reek:FeatureEnvy
+      def content_for tags
+        generator.merge latest: tags.last.version, versions: tags.map(&:version)
+      end
+
+      def generator
+        {generator: {label: settings.generator_label, version: settings.generator_version.to_s}}
+      end
+    end
+  end
+end

data/lib/milestoner/templates/layouts/page.html.erb

@@ -2,7 +2,7 @@
 
 <html lang="en">
   <head>
-    <title><%= project_title %></title>
+    <title><%= page_title %></title>
 
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
@@ -30,8 +30,8 @@
           href="<%= stylesheet_uri %>.css"
           type="text/css">
 
-    <script src="https://unpkg.com/alpinejs@3.14.3"
-            integrity="sha384-iZD2X8o1Zdq0HR5H/7oa8W30WS4No+zWCKUPD7fHRay9I1Gf+C4F8sVmw7zec1wW"
+    <script src="https://unpkg.com/alpinejs@3.14.8"
+            integrity="sha384-X9kJyAubVxnP0hcA+AMMs21U445qsnqhnUF8EBlEpP3a42Kh/JwWjlv2ZcvGfphb"
             crossorigin="anonymous"
             defer>
     </script>

data/lib/milestoner/templates/milestones/index.adoc.erb

@@ -9,5 +9,5 @@ All versions adhere to the link:https://alchemists.io/articles/strict_semantic_v
 === History
 
 <% tags.each do |tag| %>
-* link:<%= tag.version %>[<%= tag.version %>] (<%= tag.committed_date %>)
+* link:/<%= tag.version %>/[<%= tag.version %>] (<%= tag.committed_date %>)
 <% end %>

data/lib/milestoner/templates/milestones/index.html.erb

@@ -14,9 +14,9 @@
   <ul class="list">
     <% tags.each do |tag| %>
       <li class="item">
-        <a href="<%= tag.version %>"
+        <a href="/<%= tag.version %>/"
            class="version"
-           hx-get="<%= tag.version %>"
+           hx-get="/<%= tag.version %>/"
            hx-select=".milestone"
            hx-target=".milestones"
            hx-swap="outerHTML"

data/lib/milestoner/templates/milestones/index.md.erb

@@ -9,5 +9,5 @@ All versions adhere to the [Strict Semantic Versioning](https://alchemists.io/ar
 ## History
 
 <% tags.each do |tag| %>
-- [<%= tag.version %>](<%= tag.version %>) (<%= tag.committed_date %>)
+- [<%= tag.version %>](/<%= tag.version %>/) (<%= tag.committed_date %>)
 <% end %>

data/lib/milestoner/templates/milestones/show.adoc.erb

@@ -13,5 +13,5 @@
 *<%= tag.total_commits %>. <%= tag.total_files %>. <%= tag.total_deletions %>. <%= tag.total_insertions %>.* +
 *<%= tag.total_duration %>.*
 
-link:<%= past.version %>[Previous (<%= past.version %>)] | link:<%= future.version %>[Next (<%= future.version %>)]
+link:<%= past.version %>/[Previous (<%= past.version %>)] | link:<%= future.version %>/[Next (<%= future.version %>)]
 <% end %>

data/lib/milestoner/templates/milestones/show.html.erb

@@ -72,10 +72,10 @@
 
     <ul class="actions">
       <li>
-        <a href="/<%= past.version %>"
+        <a href="/<%= past.version %>/"
            class="action"
            data-direction="previous"
-           hx-get="/<%= past.version %>"
+           hx-get="/<%= past.version %>/"
            hx-select=".milestone"
            hx-trigger="click, keyup[key=='ArrowLeft'] from:body"
            hx-target=".milestone"
@@ -101,10 +101,10 @@
       </li>
 
       <li>
-        <a href="/<%= future.version %>"
+        <a href="/<%= future.version %>/"
            class="action"
            data-direction="next"
-           hx-get="/<%= future.version %>"
+           hx-get="/<%= future.version %>/"
            hx-select=".milestone"
            hx-trigger="click, keyup[key=='ArrowRight'] from:body"
            hx-target=".milestone"

data/lib/milestoner/templates/milestones/show.md.erb

@@ -12,5 +12,5 @@
 **<%= tag.total_commits %>. <%= tag.total_files %>. <%= tag.total_deletions %>. <%= tag.total_insertions %>.**
 **<%= tag.total_duration %>.**
 
-[Previous (<%= past.version %>)](<%= past.version %>) | [Next (<%= future.version %>)](<%= future.version %>)
+[Previous (<%= past.version %>)](<%= past.version %>/) | [Next (<%= future.version %>)](<%= future.version %>/)
 <% end %>

data/lib/milestoner/templates/public/page.css.erb

@@ -621,6 +621,7 @@
       }
 
       .owner {
+        align-items: center;
         display: flex;
         gap: 0.5rem;
         justify-content: center;
@@ -646,6 +647,7 @@
 
     .summary {
       align-items: center;
+      border-radius: 0.5rem;
       display: grid;
       gap: 0 1rem;
       grid-template: 1fr / auto 5fr 1fr 1fr 1fr 1fr 1fr;
@@ -832,6 +834,7 @@
         }
 
         .line {
+          align-items: center;
           align-self: start;
           display: flex;
           gap: 0.5rem;

data/lib/milestoner/views/context.rb

@@ -3,6 +3,7 @@
 require "core"
 require "forwardable"
 require "hanami/view"
+require "refinements/array"
 
 module Milestoner
   module Views
@@ -12,11 +13,15 @@ module Milestoner
 
       include Dependencies[:settings]
 
+      using Refinements::Array
+
       delegate %i[
         build_stylesheet
         generator_label
         generator_uri
         generator_version
+        organization_label
+        organization_uri
         project_author
         project_description
         project_label
@@ -29,6 +34,10 @@ module Milestoner
         stylesheet_uri
       ] => :settings
 
+      def page_title delimiter: " | "
+        [project_title, organization_label].compress.join delimiter
+      end
+
       def project_slug
         [project_name, project_version].compact.join("_").tr ".", Core::EMPTY_STRING
       end

data/milestoner.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "milestoner"
-  spec.version = "19.1.0"
+  spec.version = "19.2.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/milestoner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: milestoner
 version: !ruby/object:Gem::Version
-  version: 19.1.0
+  version: 19.2.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -34,7 +34,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2025-01-25 00:00:00.000000000 Z
+date: 2025-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -379,6 +379,7 @@ files:
 - lib/milestoner/builders/container.rb
 - lib/milestoner/builders/dependencies.rb
 - lib/milestoner/builders/feed.rb
+- lib/milestoner/builders/manifest.rb
 - lib/milestoner/builders/markdown.rb
 - lib/milestoner/builders/md/container.rb
 - lib/milestoner/builders/md/dependencies.rb
@@ -401,6 +402,7 @@ files:
 - lib/milestoner/cli/actions/build/index.rb
 - lib/milestoner/cli/actions/build/label.rb
 - lib/milestoner/cli/actions/build/layout.rb
+- lib/milestoner/cli/actions/build/manifest.rb
 - lib/milestoner/cli/actions/build/max.rb
 - lib/milestoner/cli/actions/build/output.rb
 - lib/milestoner/cli/actions/build/stylesheet.rb
@@ -464,6 +466,7 @@ files:
 - lib/milestoner/tags/builder.rb
 - lib/milestoner/tags/creator.rb
 - lib/milestoner/tags/enricher.rb
+- lib/milestoner/tags/manifest.rb
 - lib/milestoner/tags/publisher.rb
 - lib/milestoner/tags/pusher.rb
 - lib/milestoner/templates/layouts/page.adoc.erb