Class: PlanMyStuff::Comment

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

Overview

Wraps a GitHub comment with parsed PMS metadata. Class methods provide the public API for CRUD operations.

Follows an ActiveRecord-style pattern:

  • ‘Comment.new(**attrs)` creates an unpersisted instance

  • ‘Comment.create!` / `Comment.list` return persisted instances

  • ‘comment.save!` / `comment.update!` / `comment.reload` for persistence

Instance Attribute Summary collapse

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

Instance Attribute Details

#waiting_on_reply ⇒ Boolean?

Returns transient flag used by the new-comment form to request waiting-on-user state when a support user posts. Not persisted.

Returns:

  • (Boolean, nil) —

    transient flag used by the new-comment form to request waiting-on-user state when a support user posts. Not persisted.



30
31
32
 
# File 'lib/plan_my_stuff/comment.rb', line 30

def waiting_on_reply
  @waiting_on_reply
end

Class Method Details

.create!(issue:, body:, user: nil, visibility: :public, custom_fields: {}, skip_responded: false, issue_body: false, waiting_on_reply: false, attachments: []) ⇒ PlanMyStuff::Comment

Creates a comment on a GitHub issue with PMS metadata and a visible header.

Parameters:

  • issue (PlanMyStuff::Issue) —

    parent issue

  • body (String)
  • user (Object, Integer) (defaults to: nil) —

    user object or user_id

  • visibility (Symbol) (defaults to: :public) —

    :public or :internal

  • custom_fields (Hash) (defaults to: {})
  • issue_body (Boolean) (defaults to: false) —

    whether this comment holds the issue body

  • waiting_on_reply (Boolean) (defaults to: false) —

    when true and the author is a support user, marks the issue as waiting on an end-user reply. Ignored for non-support authors.

  • attachments (Array) (defaults to: []) —

    files to upload to config.attachment_repo and record on the comment. Each entry may be an uploaded-file object responding to #path and #original_filename (e.g. Rails ActionDispatch::Http::UploadedFile), a String/Pathname path to a local file, or a pre-built PlanMyStuff::Attachment instance (passthrough, no re-upload).

Returns:

Raises:



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/plan_my_stuff/comment.rb', line 52

def create!(
  issue:,
  body:,
  user: nil,
  visibility: :public,
  custom_fields: {},
  skip_responded: false,
  issue_body: false,
  waiting_on_reply: false,
  attachments: []
)
  raise(PlanMyStuff::LockedIssueError, "Issue ##{issue.number} is locked") if issue.locked?

  resolved_user = PlanMyStuff::UserResolver.resolve(user)
  visibility = resolve_visibility(visibility, resolved_user)
  comment_metadata = PlanMyStuff::CommentMetadata.build(
    user: resolved_user,
    visibility: visibility.to_s,
    custom_fields: custom_fields,
    issue_body: issue_body,
  )
  comment_metadata.validate_custom_fields!
  comment_metadata.attachments = PlanMyStuff::AttachmentUploader.upload_all!(
    repo: issue.repo,
    issue_number: issue.number,
    files: attachments,
  )

  header = build_header(resolved_user)
  full_body = "#{header}\n\n#{body}"
  serialized_body = PlanMyStuff::MetadataParser.serialize!(comment_metadata.to_h, full_body)

  client = PlanMyStuff.client
  result = client.rest(:add_comment, issue.repo, issue.number, serialized_body)
  store_etag_to_cache(
    client,
    issue.repo,
    read_field(result, :id),
    result,
    cache_writer: :write_comment,
  )

  issue.mark_responded!(resolved_user) unless skip_responded

  comment = build(result, issue: issue)
  PlanMyStuff::Notifications.instrument('comment_created', comment, user: resolved_user)
  apply_waiting_state_transitions!(issue, resolved_user, waiting_on_reply, comment)
  comment
end

.find(id, issue:) ⇒ PlanMyStuff::Comment

Finds a single comment by ID, given its parent issue.

Parameters:

Returns:



130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/plan_my_stuff/comment.rb', line 130

def find(id, issue:)
  client = PlanMyStuff.client
  github_comment =
    fetch_with_etag_cache(
      client,
      issue.repo,
      id,
      rest_method: :issue_comment,
      cache_reader: :read_comment,
      cache_writer: :write_comment,
    )
  build(github_comment, issue: issue)
end

.list(issue:, pms_only: false) ⇒ Array<PlanMyStuff::Comment>

Lists comments on a GitHub issue, optionally filtering to PMS-only comments.

Parameters:

Returns:



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/plan_my_stuff/comment.rb', line 151

def list(issue:, pms_only: false)
  client = PlanMyStuff.client
  params = { issue_number: issue.number }

  cached = PlanMyStuff::Cache.read_list(:comment, issue.repo, params)
  request_options = cached ? { headers: { 'If-None-Match' => cached[:etag] } } : {}

  github_comments = client.rest(:issue_comments, issue.repo, issue.number, **request_options)

  comments =
    if cached && not_modified?(client)
      cached[:body].map { |gc| build(gc, issue: issue) }
    else
      store_list_etag_to_cache(client, :comment, issue.repo, params, github_comments)
      github_comments.map { |gc| build(gc, issue: issue) }
    end

  pms_only ? comments.select(&:pms_comment?) : comments
end

.update!(id:, repo:, body:) ⇒ Object

Updates an existing GitHub comment body.

Parameters:

  • id (Integer) —

    comment ID

  • repo (String) —

    repo path

  • body (String) —

    new serialized body

Returns:

  • (Object) —

    Octokit response



110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/plan_my_stuff/comment.rb', line 110

def update!(id:, repo:, body:)
  client = PlanMyStuff.client
  result = client.rest(:update_comment, repo, id, body)
  store_etag_to_cache(
    client,
    repo,
    id,
    result,
    cache_writer: :write_comment,
  )
  result
end

Instance Method Details

#as_json(options = {}) ⇒ Hash

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

Returns:

  • (Hash) 


331
332
333
334
 
# File 'lib/plan_my_stuff/comment.rb', line 331

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

#body ⇒ String?

Returns comment body without the metadata HTML comment.

Returns:

  • (String, nil) —

    comment body without the metadata HTML comment



18
 
# File 'lib/plan_my_stuff/comment.rb', line 18

attribute :body, :string

#body_without_header ⇒ String

Returns the comment body with the header stripped.

Returns:

  • (String) 


381
382
383
 
# File 'lib/plan_my_stuff/comment.rb', line 381

def body_without_header
  (body || '').sub(/\A###\s.+?:\s*\n\n/, '')
end

#created_at ⇒ Time?

Returns GitHub’s created_at timestamp; settable on unpersisted comments for use with Issue.import.

Returns:

  • (Time, nil) —

    GitHub’s created_at timestamp; settable on unpersisted comments for use with Issue.import



24
 
# File 'lib/plan_my_stuff/comment.rb', line 24

attribute :created_at

#header ⇒ String?

Extracts the ‘### Name at timestamp:` header line from the comment body.

Returns:

  • (String, nil) 


372
373
374
375
 
# File 'lib/plan_my_stuff/comment.rb', line 372

def header
  match = (body || '').match(/\A(###\s.+?:\s*)\n/)
  match&.captures&.first&.strip
end

#html_url ⇒ String?

GitHub web URL for this comment, for escape-hatch “View on GitHub” links.

Returns:

  • (String, nil) 


322
323
324
 
# File 'lib/plan_my_stuff/comment.rb', line 322

def html_url
  safe_read_field(github_response, :html_url)
end

#id ⇒ Integer?

Returns GitHub comment ID.

Returns:

  • (Integer, nil) —

    GitHub comment ID



12
 
# File 'lib/plan_my_stuff/comment.rb', line 12

attribute :id, :big_integer

#issue ⇒ PlanMyStuff::Issue?

Returns parent issue.

Returns:



20
 
# File 'lib/plan_my_stuff/comment.rb', line 20

attribute :issue

#metadata ⇒ PlanMyStuff::CommentMetadata

Returns parsed metadata (empty when no PMS metadata present).

Returns:



16
 
# File 'lib/plan_my_stuff/comment.rb', line 16

attribute :metadata, default: -> { PlanMyStuff::CommentMetadata.new }

#pms_comment? ⇒ Boolean

Returns:

  • (Boolean) 


337
338
339
 
# File 'lib/plan_my_stuff/comment.rb', line 337

def pms_comment?
  metadata.schema_version.present?
end

#raw_body ⇒ String?

Returns full body as stored on GitHub.

Returns:

  • (String, nil) —

    full body as stored on GitHub



14
 
# File 'lib/plan_my_stuff/comment.rb', line 14

attribute :raw_body, :string

#reload ⇒ self

Re-fetches this comment from GitHub and updates all local attributes.

Returns:

  • (self) 


312
313
314
315
316
 
# File 'lib/plan_my_stuff/comment.rb', line 312

def reload
  fresh = self.class.find(id, issue: issue)
  hydrate_from_comment(fresh)
  self
end

#save!(user: nil) ⇒ self

Persists the comment. Creates if new, updates if persisted.

Returns:

  • (self) 


256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/plan_my_stuff/comment.rb', line 256

def save!(user: nil)
  if new_record?
    created = self.class.create!(
      issue: issue,
      body: body,
      user: user || metadata.created_by,
      visibility: visibility || :public,
      custom_fields: metadata.custom_fields.to_h,
      issue_body: metadata.issue_body,
      waiting_on_reply: waiting_on_reply,
      attachments: metadata.attachments,
    )
    hydrate_from_comment(created)
  else
    update_attrs = { user: user, body: body }
    update_attrs[:visibility] = visibility if visibility_changed?
    update!(**update_attrs)
  end

  self
end

#update!(user: nil, **attrs) ⇒ self

Updates this comment on GitHub. Raises StaleObjectError if the remote has been modified since this instance was loaded.

Parameters:

  • attrs (Hash) —

    attributes to update (body:, visibility:)

Returns:

  • (self) 


285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/plan_my_stuff/comment.rb', line 285

def update!(user: nil, **attrs)
  raise_if_stale!

  captured_changes = capture_update_changes(attrs)

  new_body = attrs[:body] || body
  new_body = preserve_header(new_body) if attrs.key?(:body)
  meta_hash = metadata.to_h

  if attrs.key?(:visibility)
    resolved_user = PlanMyStuff::UserResolver.resolve(user)
    new_visibility = self.class.__send__(:resolve_visibility, attrs[:visibility], resolved_user).to_s
    meta_hash[:visibility] = new_visibility
  end

  serialized = PlanMyStuff::MetadataParser.serialize!(meta_hash, new_body)
  self.class.update!(id: id, repo: issue.repo, body: serialized)

  reload
  PlanMyStuff::Notifications.instrument('comment_updated', self, user: user, changes: captured_changes)
  self
end

#updated_at ⇒ Time?

Returns GitHub’s updated_at timestamp.

Returns:

  • (Time, nil) —

    GitHub’s updated_at timestamp



22
 
# File 'lib/plan_my_stuff/comment.rb', line 22

attribute :updated_at

#visibility ⇒ Symbol?

Returns the comment visibility as a symbol. Uses the locally set value if present, otherwise falls back to metadata.

Returns:

  • (Symbol, nil) —

    :public or :internal



26
 
# File 'lib/plan_my_stuff/comment.rb', line 26

attribute :visibility

#visible_to?(user) ⇒ Boolean

Checks if the comment is visible to the given user. Public PMS comments: visible to everyone the parent issue is visible to. Internal PMS comments: visible only to support users. Non-PMS comments: visible only to support users.

Parameters:

  • user (Object, Integer) —

    user object or user_id

Returns:

  • (Boolean) 


358
359
360
361
362
363
364
365
366
 
# File 'lib/plan_my_stuff/comment.rb', line 358

def visible_to?(user)
  resolved = PlanMyStuff::UserResolver.resolve(user)

  if pms_comment?
    issue.visible_to?(resolved) && (visibility != :internal || PlanMyStuff::UserResolver.support?(resolved))
  else
    PlanMyStuff::UserResolver.support?(resolved)
  end
end