Module: RailsAiBridge::FreshnessHeader

Defined in:
lib/rails_ai_bridge/freshness_header.rb

Overview

Utility module to embed and extract freshness metadata from generated bridge files.

Constant Summary collapse

HEADER_PATTERN = 
/\A<!-- Generated at: ([^|]+) \| Source fingerprint: ([a-f0-9]{12})(?: \| rails-ai-bridge: v([^ ]+))? -->/i

Class Method Summary collapse

Class Method Details

.embed(content, timestamp, fingerprint) ⇒ String

Embeds the freshness header at the top of the content (Markdown formats).

Parameters:

  • content (String)
  • timestamp (String) —

    ISO 8601 UTC timestamp

  • fingerprint (String) —

    12-char SHA256 hex fingerprint

Returns:

  • (String) —

    content prefixed with freshness header



55
56
57
58
 
# File 'lib/rails_ai_bridge/freshness_header.rb', line 55

def embed(content, timestamp, fingerprint)
  header = "<!-- Generated at: #{timestamp} | Source fingerprint: #{fingerprint} | rails-ai-bridge: v#{RailsAiBridge::VERSION} -->\n"
  header + content
end

.embed_for(fmt, content, timestamp, fingerprint) ⇒ String

Embeds the freshness header appropriate for the given format. For JSON, merges a _meta key; for Markdown, prepends an HTML comment.

Parameters:

  • fmt (Symbol) —

    format key (e.g. :json, :claude)

  • content (String) —

    raw serialized content

  • timestamp (String) —

    ISO 8601 UTC timestamp

  • fingerprint (String) —

    12-char SHA256 hex fingerprint

Returns:

  • (String) —

    content with embedded freshness metadata



19
20
21
22
23
 
# File 'lib/rails_ai_bridge/freshness_header.rb', line 19

def embed_for(fmt, content, timestamp, fingerprint)
  return embed_json(content, timestamp, fingerprint) if fmt == :json

  embed(content, timestamp, fingerprint)
end

.extract_fingerprint(content) ⇒ String?

Extracts the fingerprint from the markdown freshness header.

Parameters:

  • content (String)

Returns:

  • (String, nil) —

    fingerprint if found, nil otherwise



64
65
66
67
 
# File 'lib/rails_ai_bridge/freshness_header.rb', line 64

def extract_fingerprint(content)
  match = content.match(HEADER_PATTERN)
  match ? match[2] : nil
end

.extract_fingerprint_for(fmt, content) ⇒ String?

Extracts the fingerprint from content, dispatching on format. Handles both JSON (_meta key) and Markdown (HTML comment header) formats.

Parameters:

  • fmt (Symbol) —

    format key (e.g. :json, :claude)

  • content (String) —

    file content to inspect

Returns:

  • (String, nil) —

    fingerprint if found, nil otherwise



43
44
45
46
47
 
# File 'lib/rails_ai_bridge/freshness_header.rb', line 43

def extract_fingerprint_for(fmt, content)
  return extract_json_fingerprint(content) if fmt == :json

  extract_fingerprint(content)
end

.extract_metadata_for(fmt, content) ⇒ Array(String, String), Array(nil, nil)

Extracts [fingerprint, timestamp] tuple from content, dispatching on format.

Parameters:

  • fmt (Symbol) —

    format key (e.g. :json, :claude)

  • content (String, nil) —

    file content to inspect

Returns:

  • (Array(String, String), Array(nil, nil)) 


30
31
32
33
34
35
 
# File 'lib/rails_ai_bridge/freshness_header.rb', line 30

def extract_metadata_for(fmt, content)
  return [nil, nil] unless content
  return extract_json_metadata(content) if fmt == :json

  [extract_fingerprint(content), extract_timestamp(content)]
end

.extract_timestamp(content) ⇒ String?

Extracts the timestamp from the markdown freshness header.

Parameters:

  • content (String)

Returns:

  • (String, nil) —

    timestamp if found, nil otherwise



73
74
75
76
 
# File 'lib/rails_ai_bridge/freshness_header.rb', line 73

def extract_timestamp(content)
  match = content.match(HEADER_PATTERN)
  match ? match[1] : nil
end

.extract_version(content) ⇒ String?

Extracts the gem version from the markdown freshness header.

Parameters:

  • content (String)

Returns:

  • (String, nil) —

    gem version if found, nil otherwise



82
83
84
85
 
# File 'lib/rails_ai_bridge/freshness_header.rb', line 82

def extract_version(content)
  match = content.match(HEADER_PATTERN)
  match ? match[3] : nil
end