powertom 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,697 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "set"
4
+ require_relative "scanner"
5
+ require_relative "table_loop"
6
+ require_relative "grid_value"
7
+ require_relative "path_resolver"
8
+ require_relative "formatter"
9
+
10
+ module PowerTom
11
+ # 校验条目:level(:error 阻断渲染 / :warning 不阻断)、定位(页码/形状/标签)、原因
12
+ CheckEntry = Struct.new(:level, :slide_no, :shape, :label, :message, keyword_init: true)
13
+
14
+ # 校验结果与人话报告(§7):每条问题给出"第 X 页、形状 Y、标签 Z、期望的数据路径"。
15
+ class CheckResult
16
+ attr_reader :entries
17
+
18
+ def initialize(template_name, entries)
19
+ @template_name = template_name
20
+ @entries = entries
21
+ end
22
+
23
+ def errors = entries.select { |e| e.level == :error }
24
+
25
+ def warnings = entries.select { |e| e.level == :warning }
26
+
27
+ def ok? = errors.empty?
28
+
29
+ def exit_code = ok? ? 0 : 1
30
+
31
+ def report
32
+ lines = ["PowerTom 模板校验 — #{@template_name}"]
33
+ entries.each do |e|
34
+ head = head_of(e)
35
+ body = head.empty? ? e.message : "#{head} #{e.message}"
36
+ lines << format("[%-7s] %s", e.level, body)
37
+ end
38
+ lines << "-" * 48
39
+ summary = "#{errors.size} 个 error,#{warnings.size} 个 warning"
40
+ summary += "(error 阻断渲染,修正后再调用 PowerTom.render)" unless ok?
41
+ lines << summary
42
+ lines.join("\n")
43
+ end
44
+
45
+ alias to_s report
46
+
47
+ private
48
+
49
+ def head_of(entry)
50
+ head = []
51
+ head << "第 #{entry.slide_no} 页" if entry.slide_no
52
+ head << "形状'#{entry.shape}'" if entry.shape
53
+ head << "{{#{entry.label}}}" if entry.label
54
+ head.join(" ")
55
+ end
56
+ end
57
+
58
+ # 对账器(§7,差异化核心):模板标签 vs 样例数据结构。纯 Ruby,不碰 XML。
59
+ #
60
+ # 与 render 的区别:check 报告问题而不抛异常 —— 语法错误也作为 error 条目输出,
61
+ # CI 通过 exit code 判定。报告分级:
62
+ # error 引用不存在的字段、指令语法错 → 阻断渲染
63
+ # warning 未使用字段、占位文本疑似超长、空数组、备注残留标签 → 不阻断
64
+ module Validator
65
+ OVERFLOW_MIN_LENGTH = 20 # 绑定后文本达到该长度才考虑溢出预警
66
+ OVERFLOW_RATIO = 2.0 # 且超过占位标签长度的 2 倍
67
+
68
+ module_function
69
+
70
+ # contexts: [{slide_no:, shape:, run_texts:}](Adapter 采集)
71
+ # tables: [{slide_no:, shape:, run_texts:, in_table:}](表格单元格段落)
72
+ # table_structures: [{slide_no:, shape:, rows:, merged_rows:}](表格结构,校验行循环)
73
+ # notes: [{slide_no:, text:}]
74
+ # pictures: [{slide_no:, shape:, field:}](powertom:image 占位)
75
+ # data: Hash 或 nil(nil → 跳过字段对账,只做语法与结构检查)
76
+ def check(contexts:, notes:, data:, pictures: [], tables: [], table_structures: [],
77
+ template_name: "template.pptx")
78
+ entries = []
79
+ used_roots = Set.new
80
+
81
+ # 1. 备注指令:逐页解析,语法错收集为 error;合法指令做结构对账
82
+ directives = {}
83
+ notes.each do |note|
84
+ directive = begin
85
+ Scanner.directive_for(note)
86
+ rescue TemplateSyntaxError => e
87
+ entries << error_entry(note[:slide_no], "(备注)", nil, strip_location(e.message))
88
+ nil
89
+ end
90
+ next unless directive
91
+ directives[note[:slide_no]] = directive
92
+ used_roots << root_of(directive[:path])
93
+ end
94
+
95
+ # 2. 正文标签:逐段校验语法;合法标签按页归组
96
+ labels_by_page = Hash.new { |h, k| h[k] = [] }
97
+ labels_by_table_row = Hash.new { |h, k| h[k] = [] }
98
+ contexts.each do |ctx|
99
+ labels = begin
100
+ Scanner.scan([ctx])
101
+ rescue TemplateSyntaxError => e
102
+ entries << error_entry(ctx[:slide_no], ctx[:shape], nil, strip_location(e.message))
103
+ next
104
+ end
105
+ labels.each { |l| labels_by_page[ctx[:slide_no]] << l }
106
+ end
107
+
108
+ # 2.2 表格单元格标签(行循环标签在这里出现)
109
+ tables.each do |ctx|
110
+ labels = begin
111
+ Scanner.scan([ctx])
112
+ rescue TemplateSyntaxError => e
113
+ entries << error_entry(ctx[:slide_no], ctx[:shape], nil, strip_location(e.message))
114
+ next
115
+ end
116
+ labels.each do |l|
117
+ labels_by_page[ctx[:slide_no]] << l
118
+ if ctx[:table_shape]
119
+ labels_by_table_row[[ctx[:slide_no], ctx[:table_shape], ctx[:row_index]]] << l
120
+ end
121
+ end
122
+ end
123
+
124
+ # 2.3 表格循环结构:#rows/#grid/#cols 标记位置、层级、作用域、合并单元格
125
+ table_plans = {}
126
+ failed_tables = Set.new
127
+ table_structures.each do |table|
128
+ plan = TableLoop.plan(table[:rows], merged_rows: table[:merged_rows],
129
+ columns: table[:columns])
130
+ table_plans[[table[:slide_no], table[:shape]]] = plan if plan
131
+ rescue TemplateSyntaxError => e
132
+ failed_tables << [table[:slide_no], table[:shape]]
133
+ entries << error_entry(table[:slide_no], table[:shape], nil, e.message)
134
+ end
135
+ block_row_stacks = {}
136
+ table_plans.each do |key, plan|
137
+ block_row_stacks[key] = TableLoop.build_row_stacks(plan[:blocks]) if plan[:kind] == :blocks
138
+ end
139
+
140
+ # 2.5 formatter 注册对账(§3.4):不依赖样例数据
141
+ labels_by_page.each_value do |labels|
142
+ labels.each do |l|
143
+ next unless l[:spec]
144
+ name = l[:spec].split(".").first
145
+ next if Formatter.registered?(name)
146
+ entries << error_entry(l[:context][:slide_no], l[:context][:shape], l[:path],
147
+ "未注册的 formatter '#{name}'" \
148
+ "(可用:#{Formatter.registered_names.join(', ')})")
149
+ end
150
+ end
151
+
152
+ # 3. 字段对账与溢出预警(需要样例数据)
153
+ if data.nil?
154
+ entries << CheckEntry.new(level: :warning, slide_no: nil, shape: nil, label: nil,
155
+ message: "未提供样例数据(DATA),已跳过字段对账与溢出检查")
156
+ else
157
+ directives.each do |slide_no, directive|
158
+ reconcile_directive(directive, slide_no, data, entries)
159
+ end
160
+ labels_by_page.each_value do |labels|
161
+ labels.each do |l|
162
+ ctx = l[:context]
163
+ next if ctx[:table_shape] && failed_tables.include?([ctx[:slide_no], ctx[:table_shape]])
164
+ next if block_row_stacks.dig([ctx[:slide_no], ctx[:table_shape]], ctx[:row_index])
165
+
166
+ grid = grid_plan_for(table_plans, ctx)
167
+ if grid && grid_variable_path?(l[:path])
168
+ reconcile_grid_label(l, grid, data, entries)
169
+ elsif l[:path].include?("[]")
170
+ reconcile_row_label(l, data, entries)
171
+ else
172
+ reconcile_label(l, directives[l[:context][:slide_no]], data, entries)
173
+ end
174
+ end
175
+ end
176
+ reconcile_block_tables(table_plans, labels_by_table_row, data, entries)
177
+ pictures.each do |pctx|
178
+ reconcile_picture(pctx, directives[pctx[:slide_no]], data, entries)
179
+ end
180
+ labels_by_page.each_value do |labels|
181
+ labels.each do |l|
182
+ next if l[:path].include?("[]")
183
+ next if block_row_stacks.dig([l[:context][:slide_no], l[:context][:table_shape]],
184
+ l[:context][:row_index])
185
+ next if grid_plan_for(table_plans, l[:context]) && grid_variable_path?(l[:path])
186
+
187
+ overflow_check(l, directives[l[:context][:slide_no]], data, entries)
188
+ end
189
+ end
190
+ # 未使用字段:#each 页的标签根是数据项字段,不计;指令路径根计入;
191
+ # 图片字段同样计入(image 字段通常是顶层键)
192
+ pictures.each { |pctx| used_roots << root_of(pctx[:field]) }
193
+ labels_by_page.each_value do |labels|
194
+ labels.each do |l|
195
+ directive = directives[l[:context][:slide_no]]
196
+ next if directive && directive[:kind] == :each
197
+ if block_row_stacks.dig([l[:context][:slide_no], l[:context][:table_shape]],
198
+ l[:context][:row_index])
199
+ used_roots << root_of(l[:path]) unless grid_variable_path?(l[:path])
200
+ next
201
+ end
202
+ next if grid_plan_for(table_plans, l[:context]) && grid_variable_path?(l[:path])
203
+
204
+ used_roots << root_of(l[:path])
205
+ end
206
+ end
207
+ table_plans.each_value do |plan|
208
+ case plan[:kind]
209
+ when :grid
210
+ used_roots << root_of(plan[:grid][:rows_path])
211
+ used_roots << root_of(plan[:grid][:cols_path])
212
+ when :blocks
213
+ each_block(plan[:blocks]) do |block|
214
+ used_roots << root_of(block[:path])
215
+ block[:ifs].each { |node| used_roots << root_of(node[:path]) }
216
+ end
217
+ used_roots << root_of(plan[:cols][:path]) if plan[:cols]
218
+ end
219
+ end
220
+ unused = data.keys.map(&:to_s) - used_roots.to_a
221
+ unused.each do |key|
222
+ entries << CheckEntry.new(level: :warning, slide_no: nil, shape: nil, label: nil,
223
+ message: "数据字段 '#{key}' 未被模板使用")
224
+ end
225
+ end
226
+
227
+ # 4. 备注残留的普通文本标签(§3.3:v0 不渲染备注)
228
+ notes.each do |note|
229
+ Scanner.scan_notes(note[:text], note[:slide_no]).each do |found|
230
+ next if found[:tag] =~ /\{\{\s*#/
231
+ entries << CheckEntry.new(level: :warning, slide_no: note[:slide_no], shape: "(备注)",
232
+ label: nil, message: "备注含标签 #{found[:tag]},v0 不渲染备注,已忽略")
233
+ end
234
+ end
235
+
236
+ CheckResult.new(template_name, entries)
237
+ end
238
+
239
+ # ---- 内部 ----
240
+
241
+ # 指令结构对账:#each 要数组(空数组 → 删组预警);#if 假值 → 删页预警
242
+ def reconcile_directive(directive, slide_no, data, entries)
243
+ path = directive[:path]
244
+ value = begin
245
+ PathResolver.resolve(data, path)
246
+ rescue MissingDataError => e
247
+ entries << error_entry(slide_no, "(备注)", path, e.message)
248
+ return
249
+ end
250
+ if directive[:kind] == :each
251
+ unless value.is_a?(Array)
252
+ entries << error_entry(slide_no, "(备注)", path, "取到 #{value.class},必须为数组")
253
+ return
254
+ end
255
+ if value.empty?
256
+ entries << CheckEntry.new(level: :warning, slide_no: slide_no, shape: "(备注)", label: path,
257
+ message: "数组 '#{path}' 为空(0 项):渲染时该组页面将被整组删除")
258
+ end
259
+ elsif value.nil? || value == false
260
+ entries << CheckEntry.new(level: :warning, slide_no: slide_no, shape: "(备注)", label: path,
261
+ message: "条件 #{path} 为假:渲染时该页将被删除")
262
+ end
263
+ end
264
+
265
+ # 标签对账:普通页对根数据;#each 页对数组的每一项(缺哪项报哪项)
266
+ def reconcile_label(label, directive, data, entries)
267
+ path = label[:path]
268
+ ctx = label[:context]
269
+ if directive && directive[:kind] == :each
270
+ items = begin
271
+ PathResolver.resolve(data, directive[:path])
272
+ rescue MissingDataError
273
+ return # 指令级 error 已单独报告
274
+ end
275
+ return unless items.is_a?(Array)
276
+ items.each_with_index do |item, k|
277
+ begin
278
+ PathResolver.resolve(item, path)
279
+ rescue MissingDataError => e
280
+ entries << error_entry(
281
+ ctx[:slide_no], ctx[:shape], path,
282
+ "数组 '#{directive[:path]}' 第 #{k + 1} 项:#{e.message}" \
283
+ "(期望:#{directive[:path]}[#{k}].#{path})"
284
+ )
285
+ end
286
+ end
287
+ else
288
+ begin
289
+ PathResolver.resolve(data, path)
290
+ rescue MissingDataError => e
291
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path, e.message)
292
+ end
293
+ end
294
+ end
295
+
296
+ # 溢出预警(§7):autofit 关闭时文字溢出不裁,绑定值显著长于占位标签时提醒
297
+ def overflow_check(label, directive, data, entries)
298
+ ctx = label[:context]
299
+ # 多项循环的标签取首项检查,避免同类警告刷屏
300
+ source = directive && directive[:kind] == :each ? begin
301
+ PathResolver.resolve(data, directive[:path])[0]
302
+ rescue MissingDataError
303
+ nil
304
+ end : data
305
+ return unless source
306
+
307
+ value = begin
308
+ PathResolver.resolve(source, label[:path])
309
+ rescue MissingDataError
310
+ return
311
+ end
312
+ return unless value.is_a?(String) || value.is_a?(Numeric)
313
+
314
+ rendered = value.to_s.length
315
+ placeholder = label[:path].length + 4 # "{{x}}" 形态的占位长度
316
+ return unless rendered >= OVERFLOW_MIN_LENGTH && rendered >= placeholder * OVERFLOW_RATIO
317
+
318
+ entries << CheckEntry.new(
319
+ level: :warning, slide_no: ctx[:slide_no], shape: ctx[:shape], label: label[:path],
320
+ message: "绑定后 #{rendered} 字,是占位标签(#{placeholder} 字)的 " \
321
+ "#{(rendered.to_f / placeholder).round(1)} 倍,文字可能溢出" \
322
+ "(autofit 关闭时不裁剪,建议精简文案或加长占位标签)"
323
+ )
324
+ end
325
+
326
+ # 图片字段对账(§5.3):与文本标签同一套 #each/普通 语义;额外检查
327
+ # 值必须是 String 且文件真实存在(设计师漏传图是最常见的交付事故)
328
+ def reconcile_picture(pctx, directive, data, entries)
329
+ path = pctx[:field]
330
+ ctx = { slide_no: pctx[:slide_no], shape: pctx[:shape] }
331
+ if directive && directive[:kind] == :each
332
+ items = begin
333
+ PathResolver.resolve(data, directive[:path])
334
+ rescue MissingDataError
335
+ return # 指令级 error 已单独报告
336
+ end
337
+ return unless items.is_a?(Array)
338
+ items.each_with_index do |item, k|
339
+ value = begin
340
+ PathResolver.resolve(item, path)
341
+ rescue MissingDataError => e
342
+ entries << error_entry(
343
+ ctx[:slide_no], ctx[:shape], path,
344
+ "数组 '#{directive[:path]}' 第 #{k + 1} 项:#{e.message}" \
345
+ "(期望:#{directive[:path]}[#{k}].#{path})"
346
+ )
347
+ next
348
+ end
349
+ check_image_value(value, ctx, path, entries, k)
350
+ end
351
+ else
352
+ value = begin
353
+ PathResolver.resolve(data, path)
354
+ rescue MissingDataError => e
355
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path, e.message)
356
+ return
357
+ end
358
+ check_image_value(value, ctx, path, entries)
359
+ end
360
+ end
361
+
362
+ def check_image_value(value, ctx, path, entries, item_index = nil)
363
+ return if value.nil?
364
+ where = item_index ? "第 #{item_index + 1} 项:" : ""
365
+ unless value.is_a?(String) && !value.empty?
366
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
367
+ "#{where}图片字段需要 String 文件路径,得到 #{value.class}")
368
+ return
369
+ end
370
+ return if File.file?(value)
371
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
372
+ "#{where}图片文件不存在:#{value}")
373
+ end
374
+
375
+ # #grid 变量对账:col.* 对每个列项,row.* 对每个行项,cell 对行列交叉
376
+ def reconcile_grid_label(label, plan, data, entries)
377
+ path = label[:path]
378
+ ctx = label[:context]
379
+ grid = plan[:grid]
380
+ rows = resolve_grid_array(grid[:rows_path], ctx, data, entries)
381
+ cols = resolve_grid_array(grid[:cols_path], ctx, data, entries)
382
+ return if rows.nil? || cols.nil?
383
+
384
+ if path == "cell"
385
+ reconcile_grid_cells(ctx, rows, cols, grid[:value_path], entries)
386
+ elsif path.start_with?("row.")
387
+ reconcile_grid_items(path, "row", grid[:rows_path], rows, ctx, entries)
388
+ elsif path.start_with?("col.")
389
+ reconcile_grid_items(path, "col", grid[:cols_path], cols, ctx, entries)
390
+ end
391
+ end
392
+
393
+ def resolve_grid_array(path, ctx, data, entries)
394
+ value = begin
395
+ PathResolver.resolve(data, path)
396
+ rescue MissingDataError => e
397
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path, e.message)
398
+ return nil
399
+ end
400
+
401
+ unless value.is_a?(Array)
402
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
403
+ "取到 #{value.class},循环需要数组")
404
+ return nil
405
+ end
406
+ if value.empty?
407
+ entries << CheckEntry.new(level: :warning, slide_no: ctx[:slide_no], shape: ctx[:shape],
408
+ label: path,
409
+ message: "数组 '#{path}' 为空:渲染时该方向的单元格会被移除")
410
+ end
411
+ value
412
+ end
413
+
414
+ # {{row.字段}} / {{col.字段}}:逐项对账,指出第几项与期望路径
415
+ def reconcile_grid_items(path, prefix, array_path, items, ctx, entries)
416
+ remainder = path.delete_prefix(prefix).delete_prefix(".")
417
+ items.each_with_index do |item, k|
418
+ PathResolver.resolve(item, remainder)
419
+ rescue MissingDataError => e
420
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
421
+ "数组 '#{array_path}' 第 #{k + 1} 项:#{e.message}" \
422
+ "(期望:#{array_path}[#{k}].#{remainder})")
423
+ end
424
+ end
425
+
426
+ # {{cell}}:逐个行列交叉检查取值(有 value: 时先下钻到嵌套 Hash)
427
+ def reconcile_grid_cells(ctx, rows, cols, value_path, entries)
428
+ rows.each_with_index do |row, r|
429
+ cols.each_with_index do |col, c|
430
+ GridValue.cell_value(row, col, value_path)
431
+ rescue MissingDataError => e
432
+ entries << error_entry(ctx[:slide_no], ctx[:shape], "cell",
433
+ "第 #{r + 1} 行 × 第 #{c + 1} 列:#{e.message}")
434
+ end
435
+ end
436
+ end
437
+
438
+ def grid_plan_for(plans, context)
439
+ return nil unless context[:table_shape]
440
+
441
+ plan = plans[[context[:slide_no], context[:table_shape]]]
442
+ plan && plan[:kind] == :grid ? plan : nil
443
+ end
444
+
445
+ def grid_variable_path?(path)
446
+ path == "cell" || path == "row" || path.start_with?("row.") ||
447
+ path == "col" || path.start_with?("col.")
448
+ end
449
+
450
+ # ---- v0.2.0:行区块 + 列带对账 ----
451
+
452
+ def reconcile_block_tables(plans, labels_by_row, data, entries)
453
+ plans.each do |(slide_no, shape), plan|
454
+ next unless plan[:kind] == :blocks
455
+
456
+ ctx = { slide_no: slide_no, shape: shape }
457
+ cols = plan[:cols] ? (resolve_grid_array(plan[:cols][:path], ctx, data, entries) || []) : []
458
+ reconcile_blocks(plan[:blocks], {}, nil, cols, plan[:cols], labels_by_row, ctx, data, entries)
459
+ end
460
+ end
461
+
462
+ # 与渲染同一套行计划:按区块逐项展开,再对每一行模板里的标签对账
463
+ def reconcile_blocks(blocks, parent_scope, parent_item, cols, band,
464
+ labels_by_row, ctx, data, entries)
465
+ blocks.each do |block|
466
+ items = block_array(block, parent_item, ctx, data, entries)
467
+ next if items.nil?
468
+ if items.empty?
469
+ entries << CheckEntry.new(level: :warning, slide_no: ctx[:slide_no], shape: ctx[:shape],
470
+ label: block[:path],
471
+ message: "数组 '#{block[:path]}' 为空:渲染时该行区块会被移除")
472
+ next
473
+ end
474
+
475
+ items.each_with_index do |item, index|
476
+ scope = parent_scope.merge(block[:prefix] => item)
477
+ where = "区块 #{block[:path]} 第 #{index + 1} 项"
478
+ row = block[:open] + 1
479
+ while row < block[:close]
480
+ if_node = block[:ifs].find { |n| n[:open] == row }
481
+ if if_node
482
+ if block_condition_true?(if_node[:path], item, scope, ctx, data, entries, where)
483
+ (if_node[:open] + 1...if_node[:close]).each do |r|
484
+ labels_by_row[[ctx[:slide_no], ctx[:shape], r]].each do |label|
485
+ reconcile_block_label(label, scope, item, cols, band, where, data, entries)
486
+ end
487
+ end
488
+ end
489
+ row = if_node[:close] + 1
490
+ next
491
+ end
492
+
493
+ child = block[:children].find { |c| c[:open] == row }
494
+ if child
495
+ reconcile_blocks([child], scope, item, cols, band, labels_by_row, ctx, data, entries)
496
+ row = child[:close] + 1
497
+ else
498
+ labels_by_row[[ctx[:slide_no], ctx[:shape], row]].each do |label|
499
+ reconcile_block_label(label, scope, item, cols, band, where, data, entries)
500
+ end
501
+ row += 1
502
+ end
503
+ end
504
+ end
505
+ end
506
+ end
507
+
508
+ def block_array(block, parent_item, ctx, data, entries)
509
+ value = if parent_item
510
+ PathResolver.resolve(parent_item, block[:relative])
511
+ else
512
+ PathResolver.resolve(data, block[:path])
513
+ end
514
+ unless value.is_a?(Array)
515
+ entries << error_entry(ctx[:slide_no], ctx[:shape], block[:path],
516
+ "取到 #{value.class},行区块需要数组")
517
+ return nil
518
+ end
519
+ value
520
+ rescue MissingDataError => e
521
+ message = parent_item ? "父项缺少 '#{block[:relative]}'(#{e.message})" : e.message
522
+ entries << error_entry(ctx[:slide_no], ctx[:shape], block[:path], message)
523
+ nil
524
+ end
525
+
526
+ # #if 条件求值:含 [] 走作用域栈;否则先看当前记录,再看整页数据
527
+ def block_condition_true?(path, item, scope, ctx, data, entries, where)
528
+ value = if path.include?("[]")
529
+ prefix = scope.keys.select { |key| path == key || path.start_with?("#{key}.") }
530
+ .max_by(&:length)
531
+ if prefix.nil?
532
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
533
+ "#{where}:条件路径不在行区块作用域内")
534
+ return false
535
+ end
536
+ remainder = path.delete_prefix(prefix).delete_prefix(".")
537
+ remainder.empty? ? scope[prefix] : PathResolver.resolve(scope[prefix], remainder)
538
+ else
539
+ begin
540
+ PathResolver.resolve(item, path)
541
+ rescue MissingDataError
542
+ PathResolver.resolve(data, path)
543
+ end
544
+ end
545
+ !(value.nil? || value == false)
546
+ rescue MissingDataError => e
547
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
548
+ "#{where}:条件求值失败:#{e.message}")
549
+ false
550
+ end
551
+
552
+ def reconcile_block_label(label, scope, row_item, cols, band, where, data, entries)
553
+ path = label[:path]
554
+ ctx = label[:context]
555
+ if path == "cell"
556
+ reconcile_block_cells(ctx, row_item, cols, band, where, entries)
557
+ elsif path.start_with?("row.")
558
+ reconcile_row_item_path(ctx, path, row_item, where, entries)
559
+ elsif path.start_with?("col.")
560
+ reconcile_col_item_path(ctx, path, cols, where, entries)
561
+ elsif path.include?("[]")
562
+ reconcile_block_scope_path(label, scope, where, entries)
563
+ else
564
+ reconcile_page_path(ctx, path, data, entries)
565
+ end
566
+ end
567
+
568
+ def reconcile_row_item_path(ctx, path, row_item, where, entries)
569
+ remainder = path.delete_prefix("row.")
570
+ PathResolver.resolve(row_item, remainder)
571
+ rescue MissingDataError => e
572
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path, "#{where}:#{e.message}")
573
+ end
574
+
575
+ def reconcile_col_item_path(ctx, path, cols, where, entries)
576
+ remainder = path.delete_prefix("col.")
577
+ cols.each_with_index do |col, index|
578
+ PathResolver.resolve(col, remainder)
579
+ rescue MissingDataError => e
580
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
581
+ "#{where},第 #{index + 1} 列:#{e.message}")
582
+ end
583
+ end
584
+
585
+ def reconcile_page_path(ctx, path, data, entries)
586
+ PathResolver.resolve(data, path)
587
+ rescue MissingDataError => e
588
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path, e.message)
589
+ end
590
+
591
+ def reconcile_block_cells(ctx, row_item, cols, band, where, entries)
592
+ width = band[:width]
593
+ cols.each_with_index do |col, col_index|
594
+ width.times do |template_index|
595
+ value_path = GridValue.band_value_path(band[:value_paths], template_index)
596
+ GridValue.cell_value(row_item, col, value_path)
597
+ rescue MissingDataError => e
598
+ entries << error_entry(ctx[:slide_no], ctx[:shape], "cell",
599
+ "#{where},#{cell_where(col_index, template_index, width)}:" \
600
+ "#{e.message}")
601
+ end
602
+ end
603
+ end
604
+
605
+ def cell_where(col_index, template_index, width)
606
+ return "第 #{col_index + 1} 列" if width == 1
607
+
608
+ "第 #{col_index + 1} 个列项的第 #{template_index + 1} 个模板列"
609
+ end
610
+
611
+ # 完整路径:按作用域栈里最长的匹配前缀取值
612
+ def reconcile_block_scope_path(label, scope, where, entries)
613
+ path = label[:path]
614
+ ctx = label[:context]
615
+ prefix = scope.keys.select { |key| path == key || path.start_with?("#{key}.") }
616
+ .max_by(&:length)
617
+ if prefix.nil?
618
+ entries << error_entry(ctx[:slide_no], ctx[:shape], path,
619
+ "#{where}:路径不在行区块作用域内")
620
+ return
621
+ end
622
+ remainder = path.delete_prefix(prefix).delete_prefix(".")
623
+ return if remainder.empty?
624
+
625
+ PathResolver.resolve(scope[prefix], remainder)
626
+ rescue MissingDataError => e
627
+ entries << error_entry(ctx[:slide_no], ctx[:shape], label[:path], "#{where}:#{e.message}")
628
+ end
629
+
630
+ def each_block(blocks, &block)
631
+ blocks.each do |item|
632
+ block.call(item)
633
+ each_block(item[:children], &block)
634
+ end
635
+ end
636
+
637
+ # 表格行循环标签:{{数组[].字段}} / {{父[].子[].字段}} 逐级对账;
638
+ # 空数组提醒行会被移除,缺字段指出第几项与期望的具体路径
639
+ def reconcile_row_label(label, data, entries)
640
+ path = label[:path]
641
+ ctx = label[:context]
642
+ reconcile_loop_level(path, data, "", "", ctx, entries, path)
643
+ end
644
+
645
+ # path: 剩余路径;data: 当前层数据;concrete: 已展开的具体路径前缀;
646
+ # where: 错误消息前缀(如 "数组 'classes' 第 1 项:")
647
+ def reconcile_loop_level(path, data, concrete, where, ctx, entries, original)
648
+ return PathResolver.resolve(data, path) unless path.include?("[]")
649
+
650
+ root, rest = path.split("[]", 2)
651
+ rest = rest.to_s.sub(/\A\./, "")
652
+
653
+ array = begin
654
+ PathResolver.resolve(data, root)
655
+ rescue MissingDataError => e
656
+ entries << error_entry(ctx[:slide_no], ctx[:shape], original, "#{where}#{e.message}")
657
+ return
658
+ end
659
+
660
+ unless array.is_a?(Array)
661
+ entries << error_entry(ctx[:slide_no], ctx[:shape], original,
662
+ "#{where}取到 #{array.class},行循环需要数组")
663
+ return
664
+ end
665
+ if array.empty?
666
+ entries << CheckEntry.new(level: :warning, slide_no: ctx[:slide_no], shape: ctx[:shape],
667
+ label: original,
668
+ message: "#{where}数组 '#{root}' 为空:渲染时表格循环行会被移除")
669
+ return
670
+ end
671
+ return if rest.empty?
672
+
673
+ array.each_with_index do |item, k|
674
+ reconcile_loop_level(
675
+ rest, item, "#{concrete}#{root}[#{k}].",
676
+ "#{where}数组 '#{root}' 第 #{k + 1} 项:", ctx, entries, original
677
+ )
678
+ end
679
+ rescue MissingDataError => e
680
+ entries << error_entry(ctx[:slide_no], ctx[:shape], original,
681
+ "#{where}#{e.message}(期望:#{concrete}#{path})")
682
+ end
683
+
684
+ def error_entry(slide_no, shape, label, message)
685
+ CheckEntry.new(level: :error, slide_no: slide_no, shape: shape, label: label, message: message)
686
+ end
687
+
688
+ def root_of(path)
689
+ path.split(".").first[/\A[A-Za-z0-9_]+/] || path
690
+ end
691
+
692
+ # Scanner 的错误消息自带页码/形状前缀,条目里已有定位字段,剥掉避免重复
693
+ def strip_location(message)
694
+ message.sub(/\A第 \d+ 页 形状'[^']*':/, "").sub(/\A第 \d+ 页备注:?/, "").sub(/\A第 \d+ 页:?/, "")
695
+ end
696
+ end
697
+ end