yard-timekeeper 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 567e37f7fc86a762f9e0d35feaec883057dea29b3725c25273088a8021a4a5c2
-  data.tar.gz: 1066f8b83d942b4d4a86a814da7853afb69c95241f395f550cc261afd717b442
+  metadata.gz: e09988dc7f2aa7fbd159d09194aad1c6c8b0fd7108d2a2ed36c28a904783bcea
+  data.tar.gz: bf3b8b0ddf8b4306a88ba82c676411677ecd142326c6e3678145c0b9e5d45514
 SHA512:
-  metadata.gz: cb0c37e4573fd0081eb500931e03d1467f70e2ed56ae7a7ab76c7a30bac4ba37a8ae1b560164f54e51c59c64b361c911e0879cbf4561fae886a1f0a8149831cc
-  data.tar.gz: 9098901c7ce474e6dc43e8655147ff4b8feca71ffaddbbdad4cff48ee78aeff33e5bcbb64e86b35484a6f970a62d18856e0cf260e76ee7cb8fda587f98afd1e9
+  metadata.gz: e6b6fc80c60947b4ae41e30cbba483e07739294eb04814e2423e0ec704d29f76e3e8b8d3ce3460baf09859c6d0553568bcdb3a404db047a0b4d1a8f202a73958
+  data.tar.gz: 12f546cff001d872c891914ef9c76a6da879ed8b1d6a57441d9c79cfcc9291c0ebacf9b73f97746638f253f1d5c23e6b3b791f04f2db9fe8801e368b4ad5fb4e

data/CHANGELOG.md

@@ -30,6 +30,19 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.2.4] - 2026-07-18
+
+- TAG: [v0.2.4][0.2.4t]
+- COVERAGE: 95.20% -- 119/125 lines in 3 files
+- BRANCH COVERAGE: 86.54% -- 45/52 branches in 3 files
+- 15.62% documented
+
+### Fixed
+
+- Restored generated YARD title/header metadata from git when rebuilding docs
+  with a newer YARD version, including when the file also has real content
+  changes that should be preserved.
+
 ## [0.2.3] - 2026-07-02
 
 - TAG: [v0.2.3][0.2.3t]
@@ -119,7 +132,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.3...v0.2.4
+[0.2.4t]: https://github.com/galtzo-floss/yard-timekeeper/releases/tag/v0.2.4
 [0.2.3]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.2...v0.2.3
 [0.2.3t]: https://github.com/galtzo-floss/yard-timekeeper/releases/tag/v0.2.3
 [0.2.2]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.1...v0.2.2

data/README.md

@@ -540,7 +540,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.084-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.125-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/galtzo-floss/yard-timekeeper/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/yard/timekeeper/version.rb

@@ -3,7 +3,7 @@
 module Yard
   module Timekeeper
     module Version
-      VERSION = "0.2.3"
+      VERSION = "0.2.4"
     end
     VERSION = Version::VERSION # Traditional Constant Location
   end

data/lib/yard/timekeeper.rb

@@ -14,13 +14,22 @@ module Yard
     RAKE_INTEGRATIONS = {}
     RAKE_INTEGRATIONS_MUTEX = Mutex.new
 
+    TITLE_GENERATOR_DIFF_LINE_RE = /\A[+-].*Documentation by YARD \d+(?:\.\d+)+(?:[.\w-][.\w-]*)?\s*\z/
     TIMESTAMP_DIFF_LINE_RE = /\A[+-]\s{2}Generated on .+ by\s*\z/
-    GENERATOR_VERSION_DIFF_LINE_RE = /
+    FOOTER_GENERATOR_VERSION_DIFF_LINE_RE = /
       \A[+-]\s{2}
       \d+(?:\.\d+)+(?:[.\w-][.\w-]*)?
       \s\(ruby-[^)]+\)\.\s*
       \z
     /x
+    TITLE_GENERATOR_LINE_RE = /Documentation by YARD \d+(?:\.\d+)+(?:[.\w-][.\w-]*)?/
+    TIMESTAMP_LINE_RE = /\A\s{2}Generated on .+ by\s*\z/
+    FOOTER_GENERATOR_VERSION_LINE_RE = /
+      \A\s{2}
+      \d+(?:\.\d+)+(?:[.\w-][.\w-]*)?
+      \s\(ruby-[^)]+\)\.\s*
+      \z
+    /x
     DIFF_METADATA_PREFIXES = [
       "diff --git ",
       "index ",
@@ -41,9 +50,12 @@ module Yard
 
         changed_docs_files(root).each do |relative_path|
           next unless relative_path.end_with?(".html")
-          next unless timestamp_only_diff?(git_diff(relative_path, root))
-
-          restore_file(relative_path, root)
+          diff = git_diff(relative_path, root)
+          if timestamp_only_diff?(diff)
+            restore_file(relative_path, root)
+          else
+            normalize_generated_metadata(relative_path, root)
+          end
         end
       rescue => e
         warn("Yard::Timekeeper.postprocess_html_docs failed: #{e.class}: #{e.message}")
@@ -126,7 +138,9 @@ module Yard
       end
 
       def footer_churn_line?(line)
-        line.match?(TIMESTAMP_DIFF_LINE_RE) || line.match?(GENERATOR_VERSION_DIFF_LINE_RE)
+        line.match?(TITLE_GENERATOR_DIFF_LINE_RE) ||
+          line.match?(TIMESTAMP_DIFF_LINE_RE) ||
+          line.match?(FOOTER_GENERATOR_VERSION_DIFF_LINE_RE)
       end
 
       def balanced_footer_churn?(change_lines)
@@ -140,12 +154,67 @@ module Yard
       end
 
       def footer_churn_kind(line)
+        return :title_generator if line.match?(TITLE_GENERATOR_DIFF_LINE_RE)
         return :timestamp if line.match?(TIMESTAMP_DIFF_LINE_RE)
-        return :generator_version if line.match?(GENERATOR_VERSION_DIFF_LINE_RE)
+        return :footer_generator_version if line.match?(FOOTER_GENERATOR_VERSION_DIFF_LINE_RE)
 
         :unknown
       end
 
+      def normalize_generated_metadata(path, root)
+        original = tracked_file_content(path, root)
+        return false unless original
+
+        absolute_path = File.join(root, path)
+        return false unless File.file?(absolute_path)
+
+        replacement_lines = generated_metadata_lines(original)
+        return false if replacement_lines.empty?
+
+        current = File.read(absolute_path)
+        changed = false
+        normalized_lines = current.lines.map do |line|
+          kind = generated_metadata_kind(line)
+          replacement = replacement_lines[kind]
+          if replacement && line != replacement
+            changed = true
+            replacement
+          else
+            line
+          end
+        end
+
+        return false unless changed
+
+        File.write(absolute_path, normalized_lines.join)
+        true
+      end
+
+      def tracked_file_content(path, root)
+        stdout, status = Open3.capture2("git", "show", "HEAD:#{path}", chdir: root)
+        return unless status.success?
+
+        stdout
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def generated_metadata_lines(content)
+        content.lines.each_with_object({}) do |line, replacements|
+          kind = generated_metadata_kind(line)
+          replacements[kind] ||= line if kind
+        end
+      end
+
+      def generated_metadata_kind(line)
+        stripped_line = line.strip
+        return :title_generator if stripped_line.match?(TITLE_GENERATOR_LINE_RE)
+        return :timestamp if line.match?(TIMESTAMP_LINE_RE)
+        return :footer_generator_version if line.match?(FOOTER_GENERATOR_VERSION_LINE_RE)
+
+        nil
+      end
+
       def restore_file(path, root)
         _stdout, _stderr, status = Open3.capture3("git", "checkout", "--", path, chdir: root)
         status.success?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-timekeeper
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Peter H. Boling
@@ -279,10 +279,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://yard-timekeeper.galtzo.com
-  source_code_uri: https://github.com/galtzo-floss/yard-timekeeper/tree/v0.2.3
-  changelog_uri: https://github.com/galtzo-floss/yard-timekeeper/blob/v0.2.3/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/yard-timekeeper/tree/v0.2.4
+  changelog_uri: https://github.com/galtzo-floss/yard-timekeeper/blob/v0.2.4/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/yard-timekeeper/issues
-  documentation_uri: https://www.rubydoc.info/gems/yard-timekeeper/0.2.3
+  documentation_uri: https://www.rubydoc.info/gems/yard-timekeeper/0.2.4
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/galtzo-floss/yard-timekeeper/wiki
   news_uri: https://www.railsbling.com/tags/yard-timekeeper
@@ -312,7 +312,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: "\U0001F570️ Preserve tracked YARD docs when only the generated timestamp
   changed."