Module: Polyrun::SpecQuality::Report

Defined in:
lib/polyrun/spec_quality/report.rb

Overview

Human-readable spec quality report from merged JSON.

Constant Summary collapse

EXAMPLE_CSV_HEADERS = 
%w[example unique_lines line_churn max_line_churn shard_index].freeze

Class Method Summary collapse

Class Method Details

.analyze(merged, cfg = {}, plan_shards: nil) ⇒ Object

rubocop:disable Metrics/AbcSize -- merged example analysis



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/polyrun/spec_quality/report.rb', line 12

def analyze(merged, cfg = {}, plan_shards: nil)
  cfg = default_cfg(cfg)
  examples = merged["examples"] || {}
  hot_lines = merged["hot_lines"] || {}
  shard_summary = merged["shard_summary"] || Merge.shard_summary(examples)

  zero_hit = examples.select { |_loc, row| row["unique_lines"].to_i.zero? }
  churn = examples.select { |_loc, row| row["line_churn"].to_i >= cfg["min_line_churn"] }
    .sort_by { |_loc, row| -row["line_churn"].to_i }
  hot = hot_lines.select { |_line, h| h["example_count"].to_i >= cfg["hot_line_example_overlap"] }
    .sort_by { |_line, h| [-h["example_count"].to_i, -h["total_hits"].to_i] }

  outliers = build_outliers(examples, cfg)
  partition_hints = partition_hints_for(hot, examples, plan_shards) if plan_shards && !plan_shards.empty?

  {
    zero_hit: zero_hit,
    line_churn: churn,
    hot_lines: hot,
    outliers: outliers,
    shard_summary: shard_summary,
    partition_hints: partition_hints,
    config: cfg
  }
end

.build_outliers(examples, cfg) ⇒ Object

rubocop:disable Metrics/AbcSize -- outlier row filter



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/polyrun/spec_quality/report.rb', line 274

def build_outliers(examples, cfg)
  examples.filter_map do |loc, row|
    prof = row["profile"] || {}
    unique = row["unique_lines"].to_i
    wall = prof["wall"].to_f
    alloc = prof["gc_allocated"].to_i
    cpu = prof["cpu_user"].to_f + prof["cpu_system"].to_f
    sql = row["sql_count"].to_i
    factories = (row["factory_counts"] || {}).values.sum

    score = 0
    reasons = []
    if unique.zero?
      score += 10
      reasons << "zero_lines"
    end
    if wall > 1.0 && unique < 3
      score += 5
      reasons << "slow_low_coverage"
    end
    if alloc > 50_000 && wall > 0.5
      score += 3
      reasons << "high_alloc"
    end
    if cpu > 0.5 && unique < 3
      score += 3
      reasons << "high_cpu_low_coverage"
    end
    if sql >= cfg["min_query_count"]
      score += 4
      reasons << "high_sql_count"
    end
    if factories >= 10
      score += 2
      reasons << "many_factories"
    end
    next if score.zero?

    {location: loc, score: score, reasons: reasons, row: row}
  end.sort_by { |h| -h[:score] }
end

.default_cfg(cfg) ⇒ Object 



184
185
186
187
 
# File 'lib/polyrun/spec_quality/report.rb', line 184

def default_cfg(cfg)
  h = cfg.is_a?(Hash) ? cfg.transform_keys(&:to_s) : {}
  SpecQuality::Config::DEFAULTS.merge(h)
end

.emit_warnings!(merged, cfg = {}) ⇒ Object 



178
179
180
181
182
 
# File 'lib/polyrun/spec_quality/report.rb', line 178

def emit_warnings!(merged, cfg = {})
  analyze(merged, cfg).fetch(:line_churn, {}).each do |loc, row|
    Polyrun::Log.warn "polyrun spec-quality line_churn: #{loc} churn=#{row["line_churn"]}"
  end
end

.format_churn_section(churn_rows, top) ⇒ Object 



260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/polyrun/spec_quality/report.rb', line 260

def format_churn_section(churn_rows, top)
  lines = ["Per-example line churn (top #{[top, churn_rows.size].min}):"]
  if churn_rows.empty?
    lines << "  (none)"
    return lines
  end

  churn_rows.first(top).each do |loc, row|
    lines << format("  %s — churn=%d max_line=%d", loc, row["line_churn"], row["max_line_churn"])
  end
  lines
end

.format_csv(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil) ⇒ Object 



63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/polyrun/spec_quality/report.rb', line 63

def format_csv(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil)
  rows = merged.fetch("examples", {}).map do |location, row|
    [
      location,
      row["unique_lines"],
      row["line_churn"],
      row["max_line_churn"],
      row["polyrun_shard_index"]
    ]
  end.sort_by { |row| [-row[2].to_i, row[0].to_s] }
  rows = rows.first(top) if top
  Export::Csv.generate(EXAMPLE_CSV_HEADERS, rows)
end

.format_hot_lines_section(hot_lines, top) ⇒ Object 



246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/polyrun/spec_quality/report.rb', line 246

def format_hot_lines_section(hot_lines, top)
  lines = ["Hot lines (shared across examples):"]
  if hot_lines.empty?
    lines << "  (none)"
    return lines
  end

  hot_lines.first(top).each do |line, h|
    lines << format("  %s — %d examples, %d cumulative hits", line, h["example_count"], h["total_hits"])
  end
  lines << "  …" if hot_lines.size > top
  lines
end

.format_markdown(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil) ⇒ Object 



77
78
79
80
81
 
# File 'lib/polyrun/spec_quality/report.rb', line 77

def format_markdown(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil)
  analysis = analyze(merged, cfg, plan_shards: plan_shards)
  sections = markdown_sections(analysis, top).compact
  Export::Markdown.document("Polyrun spec quality report", sections)
end

.format_outliers_section(outliers, top, profile) ⇒ Object

rubocop:disable Metrics/AbcSize -- outlier text formatting



318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/polyrun/spec_quality/report.rb', line 318

def format_outliers_section(outliers, top, profile)
  lines = ["Correlated outliers (slow / empty / heavy):"]
  if outliers.empty?
    lines << "  (none)"
    return lines
  end

  dims = profile ? profile.to_s.split(",").map(&:strip) : nil
  outliers.first(top).each do |o|
    row = o[:row]
    prof = row["profile"] || {}
    detail = o[:reasons].join(", ")
    if dims.nil? || dims.empty?
      lines << format("  %s — score=%d (%s)", o[:location], o[:score], detail)
    else
      prof_bits = dims.filter_map do |d|
        case d
        when "wall" then "wall=#{format("%.2f", prof["wall"])}" if prof["wall"]
        when "cpu" then "cpu=#{format("%.2f", prof["cpu_user"].to_f + prof["cpu_system"].to_f)}"
        when "mem" then "alloc=#{prof["gc_allocated"]}" if prof["gc_allocated"]
        when "io"
          r = prof["io_read_bytes"]
          w = prof["io_write_bytes"]
          "io=#{r}/#{w}" if r || w
        end
      end
      lines << format("  %s — score=%d (%s) %s", o[:location], o[:score], detail, prof_bits.join(" "))
    end
  end
  lines << "  …" if outliers.size > top
  lines
end

.format_partition_hints_section(hints, top) ⇒ Object 



208
209
210
211
212
213
214
215
216
217
 
# File 'lib/polyrun/spec_quality/report.rb', line 208

def format_partition_hints_section(hints, top)
  return [] if hints.nil? || hints.empty?

  lines = ["Partition hints (hot lines × shard):"]
  hints.first(top).each do |h|
    lines << format("  %s — shard %s (%d examples)", h[:line], h[:shard], h[:example_count])
  end
  lines << "  …" if hints.size > top
  lines
end

.format_report(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil) ⇒ Object

rubocop:enable Metrics/AbcSize



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/polyrun/spec_quality/report.rb', line 39

def format_report(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil)
  analysis = analyze(merged, cfg, plan_shards: plan_shards)
  lines = ["Polyrun spec quality report", ""]

  lines.concat(format_shard_summary_section(analysis[:shard_summary]))
  lines << ""
  lines.concat(format_zero_hit_section(analysis[:zero_hit], top))
  lines << ""
  lines.concat(format_hot_lines_section(analysis[:hot_lines], top))
  lines << ""
  lines.concat(format_churn_section(analysis[:line_churn], top))
  hints_section = format_partition_hints_section(analysis[:partition_hints], top)
  unless hints_section.empty?
    lines << ""
    lines.concat(hints_section)
  end
  lines << ""
  lines.concat(format_outliers_section(analysis[:outliers], top, profile))

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

.format_shard_summary_section(shard_summary) ⇒ Object 



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/polyrun/spec_quality/report.rb', line 189

def format_shard_summary_section(shard_summary)
  lines = ["Shard attribution:"]
  if shard_summary.nil? || shard_summary.empty?
    lines << "  (none)"
    return lines
  end

  shard_summary.sort_by { |k, _| k.to_s }.each do |shard, stats|
    lines << format(
      "  shard %s — examples=%d zero_hit=%d line_churn=%d",
      shard,
      stats["examples"],
      stats["zero_hit"],
      stats["line_churn"]
    )
  end
  lines
end

.format_zero_hit_section(zero_hit, top) ⇒ Object 



234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/polyrun/spec_quality/report.rb', line 234

def format_zero_hit_section(zero_hit, top)
  lines = ["Zero production lines (#{zero_hit.size} examples):"]
  if zero_hit.empty?
    lines << "  (none)"
    return lines
  end

  zero_hit.keys.sort.first(top).each { |loc| lines << "  #{loc}" }
  lines << "  …" if zero_hit.size > top
  lines
end

.gate_violations(merged, cfg = {}) ⇒ Object 



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/polyrun/spec_quality/report.rb', line 151

def gate_violations(merged, cfg = {})
  cfg = default_cfg(cfg)
  analysis = analyze(merged, cfg)
  violations = []

  max_zero = cfg["max_zero_hit_examples"]
  if max_zero && analysis[:zero_hit].size > max_zero.to_i
    violations << "zero_hit_examples=#{analysis[:zero_hit].size} max=#{max_zero}"
  end

  min_unique = cfg["minimum_unique_lines_per_example"]
  if min_unique
    bad = analysis[:zero_hit].keys
    if bad.size.positive?
      violations << "examples_below_minimum_unique_lines=#{bad.size} minimum=#{min_unique}"
    end
  end

  max_hot = cfg["max_hot_line_overlap"]
  if max_hot
    over = analysis[:hot_lines].count { |_k, h| h["example_count"].to_i > max_hot.to_i }
    violations << "hot_line_overlap_count=#{over} max=#{max_hot}" if over.positive?
  end

  violations
end

.markdown_churn_section(churn_rows, top) ⇒ Object 



125
126
127
128
129
130
131
132
133
134
 
# File 'lib/polyrun/spec_quality/report.rb', line 125

def markdown_churn_section(churn_rows, top)
  rows = churn_rows.first(top).map do |location, row|
    [location, row["line_churn"], row["max_line_churn"]]
  end
  {
    heading: "Per-example line churn",
    headers: %w[example line_churn max_line_churn],
    rows: rows.empty? ? [["(none)", 0, 0]] : rows
  }
end

.markdown_hot_lines_section(hot_lines, top) ⇒ Object 



114
115
116
117
118
119
120
121
122
123
 
# File 'lib/polyrun/spec_quality/report.rb', line 114

def markdown_hot_lines_section(hot_lines, top)
  hot_rows = hot_lines.first(top).map do |line, stats|
    [line, stats["example_count"], stats["total_hits"]]
  end
  {
    heading: "Hot lines",
    headers: %w[line example_count total_hits],
    rows: hot_rows.empty? ? [["(none)", 0, 0]] : hot_rows
  }
end

.markdown_sections(analysis, top) ⇒ Object 



83
84
85
86
87
88
89
90
 
# File 'lib/polyrun/spec_quality/report.rb', line 83

def markdown_sections(analysis, top)
  [
    markdown_shard_section(analysis[:shard_summary]),
    markdown_zero_hit_section(analysis[:zero_hit], top),
    markdown_hot_lines_section(analysis[:hot_lines], top),
    markdown_churn_section(analysis[:line_churn], top)
  ]
end

.markdown_shard_section(shard_summary) ⇒ Object 



92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/polyrun/spec_quality/report.rb', line 92

def markdown_shard_section(shard_summary)
  shard_rows = (shard_summary || {}).sort_by { |shard, _| shard.to_s }.map do |shard, stats|
    [shard, stats["examples"], stats["zero_hit"], stats["line_churn"]]
  end
  return if shard_rows.empty?

  {
    heading: "Shard attribution",
    headers: %w[shard examples zero_hit line_churn],
    rows: shard_rows
  }
end

.markdown_zero_hit_section(zero_hit, top) ⇒ Object 



105
106
107
108
109
110
111
112
 
# File 'lib/polyrun/spec_quality/report.rb', line 105

def markdown_zero_hit_section(zero_hit, top)
  zero_rows = zero_hit.keys.sort.first(top).zip
  {
    heading: "Zero production lines",
    headers: %w[example],
    rows: zero_rows.empty? ? [["(none)"]] : zero_rows
  }
end

.partition_hints_for(hot_lines, examples, plan_shards) ⇒ Object 



219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/polyrun/spec_quality/report.rb', line 219

def partition_hints_for(hot_lines, examples, plan_shards)
  hot_lines.filter_map do |line, h|
    example_locs = h["examples"] || []
    shard_counts = Hash.new(0)
    example_locs.each do |loc|
      s = PlanLoader.shard_for_example(loc, plan_shards) || examples.dig(loc, "polyrun_shard_index")&.to_s
      shard_counts[s] += 1 if s
    end
    next if shard_counts.empty?

    shard, count = shard_counts.max_by { |_s, n| n }
    {line: line, shard: shard, example_count: count, total_hits: h["total_hits"]}
  end.sort_by { |h| [-h[:example_count], -h[:total_hits]] }
end

.render(merged, format: "text", **kwargs) ⇒ Object 



136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/polyrun/spec_quality/report.rb', line 136

def render(merged, format: "text", **kwargs)
  case format.to_s.downcase
  when "text", "console", "txt"
    format_report(merged, **kwargs)
  when "json"
    JSON.pretty_generate(analyze(merged, kwargs[:cfg] || {}, plan_shards: kwargs[:plan_shards]))
  when "csv"
    format_csv(merged, **kwargs)
  when "markdown", "md"
    format_markdown(merged, **kwargs)
  else
    raise Polyrun::Error, "report-spec-quality: unknown format #{format.inspect} (use text, json, csv, or markdown)"
  end
end