Module: Yard::Timekeeper

Defined in:
lib/yard/timekeeper.rb,
lib/yard/timekeeper/version.rb

Defined Under Namespace

Modules: Version Classes: Error

Constant Summary collapse

RAKE_INTEGRATIONS = 
{}
RAKE_INTEGRATIONS_MUTEX = 
Mutex.new
TIMESTAMP_DIFF_LINE_RE = 
/\A[+-]\s{2}Generated on .+ by\s*\z/
GENERATOR_VERSION_DIFF_LINE_RE = 
/
  \A[+-]\s{2}
  \d+(?:\.\d+)+(?:[.\w-][.\w-]*)?
  \s\(ruby-[^)]+\)\.\s*
  \z
/x
DIFF_METADATA_PREFIXES = 
[
  "diff --git ",
  "index ",
  "--- ",
  "+++ ",
  "@@ "
].freeze
VERSION =

Traditional Constant Location

Version::VERSION

Class Method Summary collapse

Class Method Details

.__reset_rake_integrations__ ⇒ Object 



70
71
72
73
 
# File 'lib/yard/timekeeper.rb', line 70

def __reset_rake_integrations__
  RAKE_INTEGRATIONS_MUTEX.synchronize { RAKE_INTEGRATIONS.clear }
  nil
end

.balanced_footer_churn?(change_lines) ⇒ Boolean

Returns:

  • (Boolean) 


132
133
134
135
136
137
138
139
140
 
# File 'lib/yard/timekeeper.rb', line 132

def balanced_footer_churn?(change_lines)
  removed_lines = change_lines.select { |line| line.start_with?("-") }
  added_lines = change_lines.select { |line| line.start_with?("+") }

  removed_lines.size == added_lines.size &&
    removed_lines.size.between?(1, 2) &&
    removed_lines.map { |line| footer_churn_kind(line) }.sort ==
      added_lines.map { |line| footer_churn_kind(line) }.sort
end

.changed_docs_files(root) ⇒ Object 



88
89
90
91
92
93
94
95
 
# File 'lib/yard/timekeeper.rb', line 88

def changed_docs_files(root)
  stdout, status = Open3.capture2("git", "diff", "--name-only", "--relative", "--", "docs", chdir: root)
  return [] unless status.success?

  stdout.lines.map(&:strip).reject(&:empty?)
rescue Errno::ENOENT
  []
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
 
# File 'lib/yard/timekeeper.rb', line 75

def enabled?
  !ENV.fetch("YARD_TIMEKEEPER_DISABLE", "false").casecmp?("true")
end

.footer_churn_kind(line) ⇒ Object 



142
143
144
145
146
147
 
# File 'lib/yard/timekeeper.rb', line 142

def footer_churn_kind(line)
  return :timestamp if line.match?(TIMESTAMP_DIFF_LINE_RE)
  return :generator_version if line.match?(GENERATOR_VERSION_DIFF_LINE_RE)

  :unknown
end

.footer_churn_line?(line) ⇒ Boolean

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/yard/timekeeper.rb', line 128

def footer_churn_line?(line)
  line.match?(TIMESTAMP_DIFF_LINE_RE) || line.match?(GENERATOR_VERSION_DIFF_LINE_RE)
end

.git_diff(path, root) ⇒ Object 



97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/yard/timekeeper.rb', line 97

def git_diff(path, root)
  stdout, _status = Open3.capture2(
    "git",
    "diff",
    "--no-ext-diff",
    "--no-color",
    "--unified=0",
    "--",
    path,
    chdir: root
  )
  stdout
end

.git_root ⇒ Object 



79
80
81
82
83
84
85
86
 
# File 'lib/yard/timekeeper.rb', line 79

def git_root
  stdout, status = Open3.capture2("git", "rev-parse", "--show-toplevel", chdir: Dir.pwd)
  return unless status.success?

  stdout.strip
rescue Errno::ENOENT
  nil
end

.install_rake_tasks!(yard_task_name = :yard) ⇒ Object 



56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/yard/timekeeper.rb', line 56

def install_rake_tasks!(yard_task_name = :yard)
  return false unless defined?(::Rake::Task) && ::Rake::Task.task_defined?(yard_task_name)

  RAKE_INTEGRATIONS_MUTEX.synchronize do
    key = yard_task_name.to_s
    unless RAKE_INTEGRATIONS[key]
      ::Rake::Task[yard_task_name].enhance { ::Yard::Timekeeper.postprocess_html_docs }
      RAKE_INTEGRATIONS[key] = true
    end
  end

  true
end

.postprocess_html_docs ⇒ Object 



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/yard/timekeeper.rb', line 33

def postprocess_html_docs
  return unless enabled?

  docs_dir = File.join(Dir.pwd, "docs")
  return unless Dir.exist?(docs_dir)

  root = git_root
  return unless root

  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)
  end
rescue => e
  warn("Yard::Timekeeper.postprocess_html_docs failed: #{e.class}: #{e.message}")
end

.restore_file(path, root) ⇒ Object 



149
150
151
152
153
154
 
# File 'lib/yard/timekeeper.rb', line 149

def restore_file(path, root)
  _stdout, _stderr, status = Open3.capture3("git", "checkout", "--", path, chdir: root)
  status.success?
rescue Errno::ENOENT
  false
end

.run_at_exit ⇒ Object 



52
53
54
 
# File 'lib/yard/timekeeper.rb', line 52

def run_at_exit
  postprocess_html_docs
end

.timestamp_only_diff?(diff_text) ⇒ Boolean

Returns:

  • (Boolean) 


111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/yard/timekeeper.rb', line 111

def timestamp_only_diff?(diff_text)
  return false if diff_text.to_s.strip.empty?

  change_lines = []

  diff_text.each_line do |line|
    next if DIFF_METADATA_PREFIXES.any? { |prefix| line.start_with?(prefix) }
    next if line.strip.empty?

    return false unless footer_churn_line?(line)

    change_lines << line
  end

  balanced_footer_churn?(change_lines)
end