Class: Kettle::Dev::PreReleaseCLI

Inherits:
Object
  • Object
show all
Defined in:
lib/kettle/dev/pre_release_cli.rb,
sig/kettle/dev.rbs

Overview

PreReleaseCLI: run pre-release checks before invoking full release workflow. Checks:

1) Ensure GitHub Actions workflow actions are pinned to current SHAs.
2) Normalize Markdown image URLs using Addressable normalization.
3) Validate Markdown image links resolve via cached HTTP(S) HEAD/GET.

Usage: Kettle::Dev::PreReleaseCLI.new(check_num: 1).run

Defined Under Namespace

Modules: HTTP, Markdown Classes: ImageUrlCache

Constant Summary collapse

IMAGE_URL_CACHE_TTL_SECONDS =

Returns:

  • (Integer) 
7 * 24 * 60 * 60
DEFAULT_IMAGE_URL_SKIP_PATTERNS =

Returns:

  • (Array[String]) 
[
  "https://api.star-history.com/svg*"
].freeze
FAMILY_CONFIG_PATHS =

Returns:

  • (Array[String]) 
[".kettle-family.yml", ".structuredmerge/kettle-family.yml"].freeze

Instance Method Summary collapse

Constructor Details

#initialize(check_num: 1, event_recorder: nil) ⇒ PreReleaseCLI

Returns a new instance of PreReleaseCLI.

Parameters:

  • check_num (Integer) (defaults to: 1) —

    1-based index to resume from

  • check_num: (Integer) (defaults to: 1) 


275
276
277
278
279
280
281
282
 
# File 'lib/kettle/dev/pre_release_cli.rb', line 275

def initialize(check_num: 1, event_recorder: nil)
  @check_num = (check_num || 1).to_i
  @check_num = 1 if @check_num < 1
  @event_recorder = event_recorder
  @image_url_cache_path = configured_image_url_cache_path
  @refresh_image_url_cache = env_truthy?(ENV["KETTLE_IMAGE_URL_CACHE_REFRESH"])
  @image_url_skip_patterns = configured_image_url_skip_patterns
end

Instance Method Details

#check_github_actions_sha_pins! ⇒ void

This method returns an undefined value.

Check 1: Ensure GitHub Actions workflow action refs are current SHA pins.



313
314
315
316
317
318
319
 
# File 'lib/kettle/dev/pre_release_cli.rb', line 313

def check_github_actions_sha_pins!
  puts "[kettle-pre-release] Check 1: Validate GitHub Actions SHA pins"
  status = Kettle::Dev::GhaShaPinsCLI.new(["--root", Dir.pwd, "--check", "--upgrade", "major"]).run!
  return nil if status.zero?

  Kettle::Dev::ExitAdapter.abort("GitHub Actions SHA pin validation failed")
end

#check_markdown_images_http! ⇒ void

This method returns an undefined value.

Check 3: Validate Markdown image links by cached HTTP HEAD/GET.



380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/kettle/dev/pre_release_cli.rb', line 380

def check_markdown_images_http!
  puts "[kettle-pre-release] Check 3: Validate Markdown image links (cached HTTP HEAD, with GET fallback)"
  urls = Markdown.extract_image_urls_from_files
  puts "[kettle-pre-release] Found #{urls.size} unique image URL(s)."
  skipped = []
  cache = image_url_cache
  progress = CacheProgress.new(
    total: urls.size,
    cached_title: "Images cached",
    live_title: "Images live",
    skipped_title: "Images skipped",
    output: $stdout
  )
  failures = []
  begin
    urls.each do |url|
      if image_url_skipped?(url)
        skipped << url
        progress.skipped
        next
      end

      if cache && !@refresh_image_url_cache && cache.fresh_success?(url)
        progress.cached
        next
      end

      ok = HTTP.head_ok?(url)
      progress.live
      if ok
        cache&.write_success(url)
      else
        failures << url
      end
    end
  ensure
    progress.stop
  end
  puts "[kettle-pre-release] Image URL checks: #{progress.cached_count} cached, #{progress.live_count} live."
  puts "[kettle-pre-release] Skipped #{progress.skipped_count} image URL check(s)." if skipped.any?
  if failures.any?
    emit_pre_release_event(action: "image_links", status: "failed", urls: urls.size, cached: progress.cached_count, live: progress.live_count, skipped: progress.skipped_count, failures: failures.size)
    warn("[kettle-pre-release] #{failures.size} image URL(s) failed validation:")
    failures.each { |u| warn("  - #{u}") }
    Kettle::Dev::ExitAdapter.abort("Image link validation failed")
  else
    emit_pre_release_event(action: "image_links", status: "ok", urls: urls.size, cached: progress.cached_count, live: progress.live_count, skipped: progress.skipped_count, failures: 0)
    puts "[kettle-pre-release] All image links validated."
  end
  nil
end

#check_markdown_uri_normalization! ⇒ void

This method returns an undefined value.

Check 2: Normalize Markdown image URLs Compares URLs to Addressable-normalized form and rewrites Markdown when needed.



324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/kettle/dev/pre_release_cli.rb', line 324

def check_markdown_uri_normalization!
  puts "[kettle-pre-release] Check 2: Normalize Markdown image URLs"
  files = Markdown.project_markdown_files
  changed = []
  total_candidates = 0

  files.each do |file|
    begin
      original = File.read(file)
    rescue => e
      warn("[kettle-pre-release] Could not read #{Kettle::Dev.display_path(file)}: #{e.class}: #{e.message}")
      next
    end

    text = original.dup
    urls = Markdown.extract_image_urls_from_text(text)
    next if urls.empty?

    total_candidates += urls.size
    updated = text.dup
    modified = false

    urls.each do |url_str|
      normalized = normalized_markdown_image_url(url_str)
      next if normalized == url_str

      # Replace exact occurrences of the URL in the markdown content
      updated.gsub!(url_str, normalized)
      modified = true
      puts "  -> #{Kettle::Dev.display_path(file)}: normalized #{url_str} -> #{normalized}"
    end

    if modified && updated != original
      begin
        File.write(file, updated)
        changed << file
      rescue => e
        warn("[kettle-pre-release] Could not write #{Kettle::Dev.display_path(file)}: #{e.class}: #{e.message}")
      end
    end
  end

  puts "[kettle-pre-release] Normalization candidates: #{total_candidates}. Files changed: #{changed.uniq.size}."
  emit_pre_release_event(action: "markdown_urls", status: "ok", candidates: total_candidates, changed_files: changed.uniq.size)
  nil
end

#normalized_markdown_image_url(url_str) ⇒ Object 



371
372
373
374
375
376
 
# File 'lib/kettle/dev/pre_release_cli.rb', line 371

def normalized_markdown_image_url(url_str)
  addr = Addressable::URI.parse(url_str)
  normalized = addr.normalize
  normalized.query = addr.query if addr.query && normalized.query != addr.query
  normalized.to_s
end

#run ⇒ void

This method returns an undefined value.

Execute configured checks starting from @check_num.

Raises:

  • (ArgumentError) 


286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/kettle/dev/pre_release_cli.rb', line 286

def run
  checks = []
  checks << method(:check_github_actions_sha_pins!)
  checks << method(:check_markdown_uri_normalization!)
  checks << method(:check_markdown_images_http!)

  start = @check_num
  raise ArgumentError, "check_num must be >= 1" if start < 1

  begin_idx = start - 1
  checks[begin_idx..-1].each_with_index do |check, i|
    idx = begin_idx + i + 1
    puts "[kettle-pre-release] Running check ##{idx} of #{checks.size}"
    emit_pre_release_event(action: "check", status: "started", check: check_name(check), index: idx, total: checks.size)
    begin
      check.call
      emit_pre_release_event(action: "check", status: "ok", check: check_name(check), index: idx, total: checks.size)
    rescue => error
      emit_pre_release_event(action: "check", status: "failed", check: check_name(check), index: idx, total: checks.size, reason: "#{error.class}: #{error.message}")
      raise
    end
  end
  nil
end