Module: Kettle::Jem::TemplatingReport

Defined in:
lib/kettle/jem.rb

Constant Summary collapse

REPORT_DIR = 
File.join("tmp", "kettle-jem").freeze
REPORT_PREFIX = 
"templating-report"
MERGE_GEM_NAMES = 
%w[
  ast-merge
  bash-merge
  dotenv-merge
  json-merge
  markdown-merge
  markly-merge
  prism-merge
  psych-merge
  rbs-merge
  toml-merge
].freeze

Class Method Summary collapse

Class Method Details

.build_entry(name, spec, workspace_root:) ⇒ Object 



2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
 
# File 'lib/kettle/jem.rb', line 2155

def build_entry(name, spec, workspace_root:)
  path = spec&.full_gem_path.to_s
  {
    name: name,
    version: spec&.version&.to_s,
    path: path.empty? ? nil : path,
    local_path: !path.empty? && local_path?(path, workspace_root: workspace_root),
    loaded: !spec.nil?
  }
end

.canonical_path(path) ⇒ Object 



2188
2189
2190
2191
2192
 
# File 'lib/kettle/jem.rb', line 2188

def canonical_path(path)
  File.realpath(path)
rescue
  File.expand_path(path)
end

.console_lines(snapshot: nil, project_root: nil) ⇒ Object 



2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
 
# File 'lib/kettle/jem.rb', line 2194

def console_lines(snapshot: nil, project_root: nil)
  snapshot ||= self.snapshot
  merge_gems = snapshot.fetch(:merge_gems, [])
  return [] if merge_gems.empty?

  lines = []
  kettle_jem = snapshot[:kettle_jem]
  header = "[kettle-jem] Templating merge environment"
  header += " (kettle-jem #{kettle_jem[:version]})" if kettle_jem&.dig(:version)
  lines << header
  workspace_root = snapshot[:workspace_root]
  lines << "  workspace root: #{Kettle::Jem.display_path(workspace_root)}" if workspace_root
  merge_gems.each do |entry|
    version = entry[:version] || "not loaded"
    path = entry[:path] ? " - #{Kettle::Jem.display_path(entry[:path])}" : ""
    lines << "  - #{entry[:name]} #{version} (#{source_label(entry)})#{path}"
  end
  local_workspace_warning_lines(snapshot: snapshot, project_root: project_root).each { |line| lines << "  #{line}" }
  lines
end

.default_workspace_root ⇒ Object 



2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
 
# File 'lib/kettle/jem.rb', line 2166

def default_workspace_root
  env_root = ENV["KETTLE_DEV_DEV"].to_s.strip
  return if env_root.casecmp("false").zero?

  repo_root = File.expand_path("../../..", __dir__)
  sibling_root = File.expand_path("..", repo_root)
  if env_root.empty? || env_root.casecmp("true").zero?
    return canonical_path(sibling_root) if File.directory?(File.join(sibling_root, "nomono"))

    return
  end
  canonical_path(env_root)
end

.local_path?(path, workspace_root: default_workspace_root) ⇒ Boolean

Returns:

  • (Boolean) 


2180
2181
2182
2183
2184
2185
2186
 
# File 'lib/kettle/jem.rb', line 2180

def local_path?(path, workspace_root: default_workspace_root)
  return false if workspace_root.to_s.strip.empty?

  expanded_path = canonical_path(path)
  expanded_root = canonical_path(workspace_root)
  expanded_path == expanded_root || expanded_path.start_with?("#{expanded_root}/")
end

.local_warning_section(warning) ⇒ Object 



2324
2325
2326
2327
2328
2329
2330
2331
2332
 
# File 'lib/kettle/jem.rb', line 2324

def local_warning_section(warning)
  <<~MARKDOWN.chomp
    ## Local Workspace Warning

    #{warning}

    Set `KETTLE_DEV_DEV=true` (or configure it in `.env.local`) to use sibling workspace gems instead of the installed release.
  MARKDOWN
end

.local_workspace_warning(snapshot:, project_root:) ⇒ Object 



2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
 
# File 'lib/kettle/jem.rb', line 2334

def local_workspace_warning(snapshot:, project_root:)
  return if project_root.to_s.strip.empty?

  kettle_jem = snapshot[:kettle_jem]
  return unless kettle_jem&.fetch(:loaded, false)
  return if kettle_jem[:local_path]

  workspace_root = sibling_workspace_root(project_root)
  return unless workspace_root

  local_checkout = File.join(workspace_root, "kettle-jem")
  return unless File.directory?(local_checkout)

  loaded_path = canonical_path(kettle_jem[:path].to_s)
  checkout_path = canonical_path(local_checkout)
  return if loaded_path == checkout_path

  env_value = ENV.fetch("KETTLE_DEV_DEV", "<unset>")
  "Detected sibling workspace checkout at `#{Kettle::Jem.display_path(local_checkout)}`, but this run is using installed `kettle-jem` " \
    "(KETTLE_DEV_DEV=#{env_value.inspect})."
end

.local_workspace_warning_lines(snapshot:, project_root:) ⇒ Object 



2314
2315
2316
2317
2318
2319
2320
2321
2322
 
# File 'lib/kettle/jem.rb', line 2314

def local_workspace_warning_lines(snapshot:, project_root:)
  warning = local_workspace_warning(snapshot: snapshot, project_root: project_root)
  return [] unless warning

  [
    "WARNING: #{warning}",
    "Hint: set KETTLE_DEV_DEV=true (or configure it in .env.local) to use sibling workspace gems."
  ]
end

.markdown_section(snapshot: nil) ⇒ Object 



2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
 
# File 'lib/kettle/jem.rb', line 2215

def markdown_section(snapshot: nil)
  snapshot ||= self.snapshot
  merge_gems = snapshot.fetch(:merge_gems, [])
  return "" if merge_gems.empty?

  lines = ["## Merge Gem Environment", ""]
  workspace_root = snapshot[:workspace_root]
  if workspace_root
    lines << "**Workspace root**: `#{Kettle::Jem.display_path(workspace_root)}`"
    lines << ""
  end
  lines << "| Gem | Version | Source | Path |"
  lines << "|-----|---------|--------|------|"
  merge_gems.each do |entry|
    version = entry[:version] || "_not loaded_"
    path = entry[:path] ? "`#{Kettle::Jem.display_path(entry[:path])}`" : ""
    lines << "| #{entry[:name]} | #{version} | #{source_label(entry)} | #{path} |"
  end
  lines << ""
  lines.join("\n")
end

.render_markdown(project_root:, output_dir: nil, snapshot: nil, run_started_at: Time.now, finished_at: nil, status: nil, warnings: [], error: nil, template_diff: nil, template_commit_sha: nil) ⇒ Object 



2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
 
# File 'lib/kettle/jem.rb', line 2237

def render_markdown(project_root:, output_dir: nil, snapshot: nil, run_started_at: Time.now, finished_at: nil,
  status: nil, warnings: [], error: nil, template_diff: nil, template_commit_sha: nil)
  snapshot ||= self.snapshot
  lines = ["# kettle-jem Templating Run Report", ""]
  lines << "**Started**: #{run_started_at.iso8601}"
  lines << "**Finished**: #{finished_at.iso8601}" if finished_at
  lines << "**Status**: `#{status}`" if status
  lines << "**Project root**: `#{Kettle::Jem.display_path(project_root)}`"
  lines << "**Output dir**: `#{Kettle::Jem.display_path(output_dir)}`" if output_dir
  if (kettle_jem = snapshot[:kettle_jem])
    path = kettle_jem[:path] ? " `#{Kettle::Jem.display_path(kettle_jem[:path])}`" : ""
    lines << "**kettle-jem**: #{kettle_jem[:version] || "unknown"} (#{source_label(kettle_jem)})#{path}"
  end
  if (warning = local_workspace_warning(snapshot: snapshot, project_root: project_root))
    lines << ""
    lines << local_warning_section(warning)
  end
  lines << "**Template commit**: `#{template_commit_sha}`" if template_commit_sha
  lines << ""
  lines << template_diff_section(template_diff) if template_diff
  section = markdown_section(snapshot: snapshot)
  lines << section unless section.empty?
  unique_warnings = Array(warnings).map(&:to_s).reject { |warning| warning.strip.empty? }.uniq
  if unique_warnings.any?
    lines << "## Warnings"
    lines << ""
    unique_warnings.each { |warning| lines << "- #{warning}" }
    lines << ""
  end
  if error
    lines << "## Error"
    lines << ""
    lines << "```text"
    lines << "#{error.class}: #{error.message}"
    Array(error.backtrace).first(10).each { |line| lines << line }
    lines << "```"
    lines << ""
  end
  lines.join("\n")
end

.report_path(project_root:, output_dir: nil, run_started_at: Time.now, pid: Process.pid) ⇒ Object 



2278
2279
2280
2281
2282
 
# File 'lib/kettle/jem.rb', line 2278

def report_path(project_root:, output_dir: nil, run_started_at: Time.now, pid: Process.pid)
  target_root = output_dir || project_root
  timestamp = run_started_at.utc.strftime("%Y%m%d-%H%M%S-%6N")
  File.join(target_root, REPORT_DIR, "#{REPORT_PREFIX}-#{timestamp}-#{pid}.md")
end

.sibling_workspace_root(project_root) ⇒ Object 



2356
2357
2358
2359
2360
2361
 
# File 'lib/kettle/jem.rb', line 2356

def sibling_workspace_root(project_root)
  candidate = canonical_path(File.expand_path("..", project_root))
  return unless File.directory?(File.join(candidate, "nomono"))

  candidate
end

.snapshot(loaded_specs: Gem.loaded_specs, workspace_root: default_workspace_root) ⇒ Object 



2147
2148
2149
2150
2151
2152
2153
 
# File 'lib/kettle/jem.rb', line 2147

def snapshot(loaded_specs: Gem.loaded_specs, workspace_root: default_workspace_root)
  {
    kettle_jem: build_entry("kettle-jem", loaded_specs["kettle-jem"], workspace_root: workspace_root),
    workspace_root: workspace_root,
    merge_gems: MERGE_GEM_NAMES.map { |name| build_entry(name, loaded_specs[name], workspace_root: workspace_root) }
  }
end

.source_label(entry) ⇒ Object 



2307
2308
2309
2310
2311
2312
 
# File 'lib/kettle/jem.rb', line 2307

def source_label(entry)
  return "not loaded" unless entry[:loaded]
  return "local path" if entry[:local_path]

  "installed gem"
end

.template_diff_section(diff) ⇒ Object 



2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
 
# File 'lib/kettle/jem.rb', line 2363

def template_diff_section(diff)
  lines = ["## Template File Changes", ""]
  if Kettle::Jem::TemplateChecksums.diff_count(diff).zero?
    lines << "_No template files changed since last run._"
    lines << ""
    return lines.join("\n")
  end
  lines << Kettle::Jem::TemplateChecksums.summary(diff)
  lines << ""
  {added: "Added", changed: "Changed", removed: "Removed"}.each do |key, label|
    next unless diff.fetch(key, []).any?

    lines << "### #{label} (#{diff.fetch(key).size})"
    lines << ""
    diff.fetch(key).each { |path| lines << "- `#{path}`" }
    lines << ""
  end
  lines.join("\n")
end

.write(project_root:, output_dir: nil, snapshot: nil, report_path: nil, run_started_at: Time.now, finished_at: nil, status: nil, warnings: [], error: nil, template_diff: nil, template_commit_sha: nil) ⇒ Object 



2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
 
# File 'lib/kettle/jem.rb', line 2284

def write(project_root:, output_dir: nil, snapshot: nil, report_path: nil, run_started_at: Time.now,
  finished_at: nil, status: nil, warnings: [], error: nil, template_diff: nil, template_commit_sha: nil)
  snapshot ||= self.snapshot
  report_path ||= self.report_path(project_root: project_root, output_dir: output_dir, run_started_at: run_started_at)
  FileUtils.mkdir_p(File.dirname(report_path))
  File.write(
    report_path,
    render_markdown(
      project_root: project_root,
      output_dir: output_dir,
      snapshot: snapshot,
      run_started_at: run_started_at,
      finished_at: finished_at,
      status: status,
      warnings: warnings,
      error: error,
      template_diff: template_diff,
      template_commit_sha: template_commit_sha
    )
  )
  report_path
end