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/
DIFF_METADATA_PREFIXES = 
[
  "diff --git ",
  "index ",
  "--- ",
  "+++ ",
  "@@ ",
].freeze
VERSION =

Traditional Constant Location

Version::VERSION

Class Method Summary collapse

Class Method Details

.__reset_rake_integrations__ ⇒ Object 



64
65
66
67
 
# File 'lib/yard/timekeeper.rb', line 64

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

.changed_docs_files(root) ⇒ Object 



82
83
84
85
86
87
88
89
 
# File 'lib/yard/timekeeper.rb', line 82

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) 


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

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

.git_diff(path, root) ⇒ Object 



91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/yard/timekeeper.rb', line 91

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 



73
74
75
76
77
78
79
80
 
# File 'lib/yard/timekeeper.rb', line 73

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 



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/yard/timekeeper.rb', line 50

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 



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/yard/timekeeper.rb', line 27

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

.restore_file(path, root) ⇒ Object 



124
125
126
127
128
129
 
# File 'lib/yard/timekeeper.rb', line 124

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 



46
47
48
 
# File 'lib/yard/timekeeper.rb', line 46

def run_at_exit
  postprocess_html_docs
end

.timestamp_only_diff?(diff_text) ⇒ Boolean

Returns:

  • (Boolean) 


105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/yard/timekeeper.rb', line 105

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 line.match?(TIMESTAMP_DIFF_LINE_RE)

    change_lines << line
  end

  change_lines.size == 2 &&
    change_lines.one? { |line| line.start_with?("-") } &&
    change_lines.one? { |line| line.start_with?("+") }
end