Class: PlanMyStuff::Label

Inherits:
ApplicationRecord show all
Defined in:
lib/plan_my_stuff/label.rb

Overview

Wraps a GitHub label with a reference to its parent issue. Class methods provide the public API for add/remove operations.

Instance Attribute Summary

Attributes inherited from ApplicationRecord

#github_response

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from ApplicationRecord

#destroyed?, #initialize, #new_record?, #persisted?, read_field

Constructor Details

This class inherits a constructor from PlanMyStuff::ApplicationRecord

Class Method Details

.add!(issue:, labels:, user: nil) ⇒ Array<PlanMyStuff::Label>

Adds labels to a GitHub issue.

Parameters:

  • issue (PlanMyStuff::Issue) —

    parent issue

  • labels (Array<String>)
  • user (Object, nil) (defaults to: nil) —

    actor for the notification event

Returns:



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/plan_my_stuff/label.rb', line 21

def add!(issue:, labels:, user: nil)
  label_names = Array.wrap(labels)

  result = PlanMyStuff.client.rest(
    :add_labels_to_an_issue, issue.repo, issue.number, label_names,
  )

  PlanMyStuff::Cache.delete_issue(issue.repo, issue.number)

  PlanMyStuff::Notifications.instrument(
    'label.added', issue, user: user, labels: label_names,
  )

  result.map { |gh_label| build(gh_label, issue: issue) }
end

.ensure!(repo:, name:, color: 'fbca04', description: nil) ⇒ void

This method returns an undefined value.

Ensures a label exists on the given repo, creating it if missing. Idempotent: a 404 from label triggers creation; a 422 from add_label (concurrent-creation race) is treated as success.

Parameters:

  • repo (String, Symbol) —

    repo name or key

  • name (String) —

    label name

  • color (String) (defaults to: 'fbca04') —

    hex color without #

  • description (String, nil) (defaults to: nil) 


47
48
49
50
51
52
53
54
 
# File 'lib/plan_my_stuff/label.rb', line 47

def ensure!(repo:, name:, color: 'fbca04', description: nil)
  client = PlanMyStuff.client
  client.rest(:label, repo, name)
rescue PlanMyStuff::APIError => e
  raise unless e.status == 404

  create_label!(client, repo, name, color, description)
end

.exists?(repo:, name:) ⇒ Boolean

Returns whether a label exists in the repo.

Parameters:

  • repo (String, Symbol, PlanMyStuff::Repo) —

    repo name or key

  • name (String) —

    label name

Returns:

  • (Boolean)

Raises:



65
66
67
68
69
70
71
72
 
# File 'lib/plan_my_stuff/label.rb', line 65

def exists?(repo:, name:)
  PlanMyStuff.client.rest(:label, repo, name)
  true
rescue PlanMyStuff::APIError => e
  raise unless e.status == 404

  false
end

.remove!(issue:, labels:, user: nil) ⇒ Array<Array<PlanMyStuff::Label>>

Removes labels from a GitHub issue.

Parameters:

  • issue (PlanMyStuff::Issue) —

    parent issue

  • labels (Array<String>)
  • user (Object, nil) (defaults to: nil) —

    actor for the notification event

Returns:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/plan_my_stuff/label.rb', line 82

def remove!(issue:, labels:, user: nil)
  label_names = Array.wrap(labels)

  results = label_names.map do |label|
    result = PlanMyStuff.client.rest(:remove_label, issue.repo, issue.number, label)
    result.map { |gh_label| build(gh_label, issue: issue) }
  end

  PlanMyStuff::Cache.delete_issue(issue.repo, issue.number)

  PlanMyStuff::Notifications.instrument(
    'label.removed', issue, user: user, labels: label_names,
  )

  results
end

Instance Method Details

#as_json(options = {}) ⇒ Hash

Serializes the label to a JSON-safe hash, excluding the back-reference to the parent issue to prevent recursive serialization cycles.

Returns:

  • (Hash) 


141
142
143
144
 
# File 'lib/plan_my_stuff/label.rb', line 141

def as_json(options = {})
  merged_except = Array.wrap(options[:except]) + ['issue']
  super(options.merge(except: merged_except)).merge('issue_number' => issue&.number)
end

#issue ⇒ PlanMyStuff::Issue?

Returns:



10
 
# File 'lib/plan_my_stuff/label.rb', line 10

attribute :issue

#name ⇒ String?

Returns:

  • (String, nil) 


8
 
# File 'lib/plan_my_stuff/label.rb', line 8

attribute :name, :string