Module: RailsAiBridge::Serializers::ManagedRegion

Defined in:
lib/rails_ai_bridge/serializers/managed_region.rb

Overview

Delimits the gem-owned portion of a generated provider file so hand-authored content around it survives regeneration.

A managed file looks like:

House rules the team wrote by hand.

…generated context…

Only the first region is treated as managed; everything else in the file belongs to the user and is never rewritten. An unterminated BEGIN marker (a truncated or hand-edited file) is treated as running to end of file, so the next run heals it rather than nesting a second block inside the first.

Constant Summary collapse

BEGIN_MARKER = 
'<!-- BEGIN rails-ai-bridge: generated. Edits inside this block are overwritten on `rails ai:bridge`. -->'
END_MARKER = 
'<!-- END rails-ai-bridge -->'
BEGIN_PATTERN =

Tolerant of marker-text drift (older gem versions worded the notice differently) and of trailing whitespace, so a region written by any version is still recognised.

/^<!-- BEGIN rails-ai-bridge:[^\n]*-->[^\S\n]*\n/
END_PATTERN = 
/^<!-- END rails-ai-bridge -->[^\S\n]*(?:\n|\z)/
REGION_PATTERN = 
/#{BEGIN_PATTERN}(.*?)(?:#{END_PATTERN}|\z)/m

Class Method Summary collapse

Class Method Details

.extract(content) ⇒ String?

Extracts the generated payload from a managed file.

Parameters:

  • content (String, nil) —

    file content to inspect

Returns:

  • (String, nil) —

    payload without markers, or nil when unmarked



51
52
53
54
55
 
# File 'lib/rails_ai_bridge/serializers/managed_region.rb', line 51

def extract(content)
  return nil unless content

  content[REGION_PATTERN, 1]&.chomp
end

.generated_payload(content) ⇒ String?

Returns the gem-owned portion of a file: the managed region when one is present, otherwise the whole file. Lets callers that only care about the generated payload (freshness metadata, staleness checks) stay agnostic about whether managed regions are enabled.

Parameters:

  • content (String, nil) —

    file content to inspect

Returns:

  • (String, nil) 


64
65
66
 
# File 'lib/rails_ai_bridge/serializers/managed_region.rb', line 64

def generated_payload(content)
  extract(content) || content
end

.markers?(content) ⇒ Boolean

Returns true when a managed region is present.

Parameters:

  • content (String, nil) —

    file content to inspect

Returns:

  • (Boolean) —

    true when a managed region is present



41
42
43
44
45
 
# File 'lib/rails_ai_bridge/serializers/managed_region.rb', line 41

def markers?(content)
  return false unless content

  REGION_PATTERN.match?(content)
end

.merge(existing, payload) ⇒ String

Combines existing file content with a freshly generated payload.

  • no existing content → the marked block alone
  • existing content with markers → only the region is replaced
  • existing content without markers → the block is appended, preserving the file

Parameters:

  • existing (String, nil) —

    current file content

  • payload (String) —

    generated content

Returns:

  • (String) —

    content to write



77
78
79
80
81
82
83
84
 
# File 'lib/rails_ai_bridge/serializers/managed_region.rb', line 77

def merge(existing, payload)
  block = wrap(payload)
  return block if existing.nil? || existing.strip.empty?
  # Block form: a String replacement would interpret backslash escapes in the payload.
  return existing.sub(REGION_PATTERN) { block } if markers?(existing)

  "#{existing.rstrip}\n\n#{block}"
end

.wrap(payload) ⇒ String

Wraps generated content in the managed-region markers.

Parameters:

  • payload (String) —

    generated content

Returns:

  • (String) —

    marked block, newline-terminated



35
36
37
 
# File 'lib/rails_ai_bridge/serializers/managed_region.rb', line 35

def wrap(payload)
  "#{BEGIN_MARKER}\n#{payload.to_s.chomp}\n#{END_MARKER}\n"
end