Class: Woods::MCP::Renderers::MarkdownRenderer

Inherits:
ToolResponseRenderer show all
Defined in:
lib/woods/mcp/renderers/markdown_renderer.rb

Overview

Renders MCP tool responses as pure Markdown. Headers, tables, code blocks, and bullet lists — no JSON structural markers.

Direct Known Subclasses

ClaudeRenderer

Constant Summary

Constants inherited from ToolResponseRenderer

ToolResponseRenderer::VALID_FORMATS

Instance Method Summary collapse

Methods inherited from ToolResponseRenderer

for, #render

Instance Method Details

#render_default(data) ⇒ String

Returns Markdown-formatted default output.

Parameters:

  • data (Object) —

    Any data

Returns:

  • (String) —

    Markdown-formatted default output



344
345
346
347
348
349
350
351
352
353
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 344

def render_default(data)
  case data
  when Hash
    render_hash_as_markdown(data)
  when Array
    render_array_as_markdown(data)
  else
    data.to_s
  end
end

#render_dependencies(data) ⇒ String

Returns Markdown dependency tree.

Parameters:

  • data (Hash) —

    Traversal result with :root, :nodes, :found

Returns:

  • (String) —

    Markdown dependency tree



82
83
84
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 82

def render_dependencies(data, **)
  render_traversal('Dependencies', data)
end

#render_dependents(data) ⇒ String

Returns Markdown dependents tree.

Parameters:

  • data (Hash) —

    Traversal result with :root, :nodes, :found

Returns:

  • (String) —

    Markdown dependents tree



88
89
90
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 88

def render_dependents(data, **)
  render_traversal('Dependents', data)
end

#render_domain_clusters(data) ⇒ String

Returns Markdown domain cluster overview.

Parameters:

  • data (Hash) —

    Domain cluster data with :clusters and :total

Returns:

  • (String) —

    Markdown domain cluster overview



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 199

def render_domain_clusters(data, **)
  clusters = fetch_key(data, :clusters) || []
  total = fetch_key(data, :total) || clusters.size
  lines = []
  lines << '## Domain Clusters'
  lines << ''
  lines << "#{total} domains detected."
  lines << ''

  clusters.each do |cluster|
    name = cluster[:name] || cluster['name']
    member_count = cluster[:member_count] || cluster['member_count'] || 0
    hub = cluster[:hub] || cluster['hub']
    lines << "### #{name} (#{member_count} units)"
    lines << ''
    lines << "**Hub:** #{hub}" if hub
    lines << ''

    # Type breakdown
    types = cluster[:types] || cluster['types']
    if types.is_a?(Hash) && types.any?
      type_parts = types.sort_by { |_, count| -count }.map { |type, count| "#{count} #{type}s" }
      lines << "**Types:** #{type_parts.join(', ')}"
    end

    # Entry points
    entry_points = cluster[:entry_points] || cluster['entry_points'] || []
    lines << "**Entry points:** #{entry_points.first(10).join(', ')}" if entry_points.any?

    # Members (show first 15)
    members = cluster[:members] || cluster['members'] || []
    if members.any?
      lines << ''
      lines << '**Members:**'
      members.first(15).each { |m| lines << "- #{m}" }
      lines << "- _... and #{members.size - 15} more_" if members.size > 15
    end

    # Boundary edges (show first 10)
    boundaries = cluster[:boundary_edges] || cluster['boundary_edges'] || []
    if boundaries.any?
      lines << ''
      lines << '**Boundary connections:**'
      boundaries.first(10).each do |edge|
        from = edge[:from] || edge['from']
        to = edge[:to] || edge['to']
        via = edge[:via] || edge['via']
        lines << "- #{from} → #{to} (#{via})"
      end
    end

    lines << ''
  end

  lines.join("\n").rstrip
end

#render_framework(data) ⇒ String

Returns Markdown framework results.

Parameters:

  • data (Hash) —

    Framework search results

Returns:

  • (String) —

    Markdown framework results



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 281

def render_framework(data, **)
  keyword = fetch_key(data, :keyword)
  count = fetch_key(data, :result_count, 0)
  results = fetch_key(data, :results, [])

  lines = []
  lines << "## Framework: \"#{keyword}\""
  lines << ''
  lines << "#{count} result#{'s' unless count == 1} found."
  lines << ''

  results.each do |r|
    ident = fetch_key(r, :identifier)
    type = fetch_key(r, :type)
    file = fetch_key(r, :file_path)
    line = "- **#{ident}** (#{type})"
    line += " — `#{file}`" if file
    lines << line
  end

  lines.join("\n").rstrip
end

#render_graph_analysis(data) ⇒ String

Returns Markdown graph analysis.

Parameters:

  • data (Hash) —

    Graph analysis with section arrays and stats

Returns:

  • (String) —

    Markdown graph analysis



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 157

def render_graph_analysis(data, **)
  lines = []
  lines << '## Graph Analysis'
  lines << ''

  stats = fetch_key(data, :stats)
  if stats.is_a?(Hash)
    stats.each { |k, v| lines << "- **#{k}:** #{v}" }
    lines << ''
  end

  %w[orphans dead_ends hubs cycles bridges].each do |section|
    items = fetch_key(data, section)
    next unless items.is_a?(Array) && items.any?

    lines << "### #{section.tr('_', ' ').capitalize}"
    lines << ''
    items.each do |item|
      lines << if item.is_a?(Hash) && item.key?('score')
                 "- **#{item['identifier']}** (#{item['type']}) — score: #{item['score']}"
               elsif item.is_a?(Hash)
                 "- **#{item['identifier']}** (#{item['type']}) — #{item['dependent_count']} dependents"
               else
                 "- #{item}"
               end
    end

    total_key = "#{section}_total"
    if data[total_key]
      lines << ''
      lines << "_Showing #{items.size} of #{data[total_key]} (truncated)_"
    end
    lines << ''
  end

  lines.join("\n").rstrip
end

#render_lookup(data) ⇒ String

Returns Markdown-formatted unit.

Parameters:

  • data (Hash) —

    Unit data from IndexReader#find_unit

Returns:

  • (String) —

    Markdown-formatted unit



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 13

def render_lookup(data, **)
  return 'Unit not found' unless data.is_a?(Hash) && data['identifier']

  lines = []
  lines << "## #{data['identifier']} (#{data['type']})"
  lines << ''
  lines << "**File:** `#{data['file_path']}`" if data['file_path']
  lines << "**Namespace:** #{data['namespace']}" if data['namespace']
  lines << ''

  lines << render_metadata_section(data['metadata']) if data['metadata'].is_a?(Hash) && data['metadata'].any?

  if data['source_code']
    lines << '### Source'
    lines << ''
    lines << '```ruby'
    lines << data['source_code'].chomp
    lines << '```'
    lines << ''
  end

  if data['dependencies'].is_a?(Array) && data['dependencies'].any?
    lines << '### Dependencies'
    lines << ''
    data['dependencies'].each { |dep| lines << "- #{dep}" }
    lines << ''
  end

  if data['dependents'].is_a?(Array) && data['dependents'].any?
    lines << '### Dependents'
    lines << ''
    data['dependents'].each { |dep| lines << "- #{dep}" }
    lines << ''
  end

  lines.join("\n").rstrip
end

#render_pagerank(data) ⇒ String

Returns Markdown table of ranked nodes.

Parameters:

  • data (Hash) —

    PageRank data with :total_nodes and :results

Returns:

  • (String) —

    Markdown table of ranked nodes



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 260

def render_pagerank(data, **)
  lines = []
  lines << '## PageRank Scores'
  lines << ''
  lines << "Ranking #{fetch_key(data, :total_nodes)} nodes in the dependency graph."
  lines << ''
  lines << '| Rank | Identifier | Type | Score |'
  lines << '|------|-----------|------|-------|'

  results = fetch_key(data, :results, [])
  results.each_with_index do |r, i|
    lines << "| #{i + 1} | #{fetch_key(r, :identifier)} | #{fetch_key(r, :type)} | #{fetch_key(r, :score)} |"
  end

  lines.join("\n").rstrip
end

#render_recent_changes(data) ⇒ String

Returns Markdown table of recent changes.

Parameters:

  • data (Hash) —

    Recent changes with :result_count and :results

Returns:

  • (String) —

    Markdown table of recent changes



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 308

def render_recent_changes(data, **)
  count = fetch_key(data, :result_count, 0)
  results = fetch_key(data, :results, [])

  lines = []
  lines << '## Recent Changes'
  lines << ''
  lines << "#{count} recently modified unit#{'s' unless count == 1}."
  lines << ''
  lines << '| Identifier | Type | Last Modified | Author |'
  lines << '|-----------|------|---------------|--------|'

  results.each do |r|
    ident = fetch_key(r, :identifier)
    type = fetch_key(r, :type)
    modified = fetch_key(r, :last_modified) || '-'
    author = fetch_key(r, :author) || '-'
    lines << "| #{ident} | #{type} | #{modified} | #{author} |"
  end

  lines.join("\n").rstrip
end

#render_search(data) ⇒ String

Returns Markdown search results.

Parameters:

  • data (Hash) —

    Search results with :query, :result_count, :results

Returns:

  • (String) —

    Markdown search results



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 55

def render_search(data, **)
  query = fetch_key(data, :query)
  count = fetch_key(data, :result_count, 0)
  results = fetch_key(data, :results, [])

  lines = []
  lines << "## Search: \"#{query}\""
  lines << ''
  lines << "#{count} result#{'s' unless count == 1} found."
  lines << ''

  results.each do |r|
    ident = fetch_key(r, :identifier)
    type = fetch_key(r, :type)
    match = fetch_key(r, :match_field)
    line = "- **#{ident}** (#{type})"
    line += " — matched in #{match}" if match
    lines << line
  end

  lines.join("\n").rstrip
end

#render_structure(data) ⇒ String

Returns Markdown structure overview.

Parameters:

  • data (Hash) —

    Structure data with :manifest and optional :summary

Returns:

  • (String) —

    Markdown structure overview



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 96

def render_structure(data, **)
  manifest = fetch_key(data, :manifest, {})
  lines = []
  lines << '## Codebase Structure'
  lines << ''

  %w[rails_version ruby_version git_branch git_sha extracted_at].each do |key|
    lines << "- **#{key.tr('_', ' ').capitalize}:** #{manifest[key]}" if manifest[key]
  end
  lines << "- **Total units indexed:** #{manifest['total_units']}" if manifest['total_units']
  template_engines = fetch_key(data, :template_engines)
  if template_engines.is_a?(Array) && template_engines.any?
    lines << "- **Supported template engines:** #{template_engines.join(', ')}"
  end
  lines << ''

  counts = manifest['counts']
  if counts.is_a?(Hash) && counts.any?
    lines << '| Type | Count |'
    lines << '|------|-------|'
    counts.sort_by { |_k, v| -v }.each do |type, count|
      lines << "| #{type} | #{count} |"
    end
    lines << ''
  end

  summary = fetch_key(data, :summary)
  if summary
    lines << '### Summary'
    lines << ''
    lines << summary
    lines << ''
  end

  lines << structure_denominators_glossary
  lines.join("\n").rstrip
end

#render_trace_flow(data) ⇒ String

Returns Markdown flow document with a step-by-step operations table.

Parameters:

  • data (Hash) —

    Serialized FlowDocument

Returns:

  • (String) —

    Markdown flow document with a step-by-step operations table



335
336
337
338
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 335

def render_trace_flow(data, **)
  require_relative '../../flow_document'
  Woods::FlowDocument.from_h(data).to_markdown
end

#structure_denominators_glossary ⇒ Object

Canonical glossary of the three index denominators that differ across Woods’ tools. Surfaced once in the structure tool so readers don’t have to cross-reference other tools’ outputs to understand why the numbers disagree. Resolves #105.



138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/woods/mcp/renderers/markdown_renderer.rb', line 138

def structure_denominators_glossary
  <<~GLOSSARY
    ### Denominators

    - **units_indexed** (manifest.json, `structure` tool) — total
      ExtractedUnits written by the extractor. Canonical count.
    - **graph_nodes** (`pagerank`, `dependencies`, `dependents`) —
      units present in the dependency graph. Excludes orphans
      that have no incoming or outgoing edges.
    - **searchable_entries** (`codebase_retrieve`) — retriever-store
      entries, including per-chunk rows for units long enough to
      be chunked. Always ≥ units_indexed.
  GLOSSARY
end