liquid_xlsx 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 405eceeb12cbc1b76e2bb0fa1ef24f351f544551268799cffd3f1265fa3bda7f
-  data.tar.gz: 13f0be15c97eaf8f21c8e4b4b1c4a2665032f8a8b7fc0ae885a1c1a2fb2cb126
+  metadata.gz: 77859fcf54ec602752b61cb982570912a6da4acfe35da51bf159a6afa641e552
+  data.tar.gz: adf22d59468df31118460448d0e6f4c84b3f2a16facc4cb5ff849ef652202ecc
 SHA512:
-  metadata.gz: 1677f21ae1c65f95cf62fe1728cdeadef70e96a051ed33a1ed7acf57eb2b9067e00f3f4d1901caf20d9d23f37edbec601cef7115704404e75eaaca160d1d6405
-  data.tar.gz: 9eda27bf7211ffc329af17e9ddf9992dcda7e551ff9526d62afb8df870e56d88381cd369acf120704ede782e10ded1650c410e97d71ebbf5159bff46b311e630
+  metadata.gz: 7a6de15d7778d554d86582f64e641d9dd328ef743adc4dba868e06c936b39eaed6093fca1ca533ebb5745856304710013a11d61af41b80df3b40ed5a56e08109
+  data.tar.gz: 76e95b63732e91ef4202efc71d80b1f791d84108d1857c9eac9d74ea3f0695d65ef7591ff7c4dcf28cf92d89c3b96caca81089de997a4fcf4ada199346532f3d

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.3.0 (2026-08-14)
+
+### Added
+
+- `LiquidXlsx.validate(template:)` — check a template without rendering it and
+  without any data. Returns a `Validation::Result` listing every problem found
+  instead of raising on the first one.
+
+  This is deliberately not "render it and see what happens". The renderer parses
+  only the Liquid it actually executes, so a mistake inside an `{% if %}` branch
+  the current document does not take, or inside a loop over an empty collection,
+  stays invisible until some other document hits it. Rendering also stops at the
+  first failure and runs the template against live records — a heavy price for
+  the question "is the file I just uploaded any good?".
+
+  Issue codes: `:invalid_xlsx`, `:missing_worksheet`, `:template_syntax`,
+  `:liquid_syntax`, `:liquid_expression` (warning), `:unknown_filter`,
+  `:sheet_tag_disabled`, `:sheet_template_missing`,
+  `:merged_cell_crosses_block`, `:liquid_in_formula` (warning),
+  `:liquid_in_rich_text` (warning). Each carries the sheet, row and cell it came
+  from, plus a stable `code` a host application can map to its own wording.
+
+  Beyond issues, the result reports what the template *uses*: `roots` (the input
+  variables it expects, with loop variables and `{% assign %}` names excluded),
+  full `variables` paths, and `filters` — so a host application can check them
+  against its own data model without parsing Liquid itself.
+
+- Two silent losses are now reported, both of which used to produce a document
+  with tags left in it and no error anywhere:
+  - Liquid inside a formula is never evaluated (`:liquid_in_formula`).
+  - Liquid inside a rich-text inline string — text split into runs because part
+    of the cell is formatted differently — is not read (`:liquid_in_rich_text`).
+
+- Expressions Liquid silently misreads are reported as warnings
+  (`:liquid_expression`): `{{ invoice.total b c }}` and `{{ invoice..total }}`
+  print the total and quietly drop the rest. Liquid's default lax parser accepts
+  them, so nothing fails — which is exactly why they are worth pointing out.
+  Only fragments the renderer would actually reject are errors.
+
+- `Tags::SheetTag#template_name` / `#as_name` are now public, so the sheet a
+  `{% sheet %}` clones can be checked without rendering the tag.
+
 ## 0.2.2 (2026-08-14)
 
 ### Fixed

data/README.md

@@ -45,6 +45,8 @@ Object API: `LiquidXlsx::Template.new(path).render_to_file(data, out)`, or
 - `{% sheet %}` — generate whole worksheets from data
 - `{% image_tag %}` — embed PNG / JPEG / GIF
 - Errors report the sheet, row and cell they came from
+- `LiquidXlsx.validate` — check a template without data: every problem at once,
+  including the branches a trial render would never reach
 
 **Requirements:** Ruby >= 3.1. Works with both rubyzip 2.x and 3.x.
 
@@ -727,6 +729,72 @@ LiquidXlsx.render(template: "invoice.xlsx", output: "out.xlsx",
 на `Liquid::Environment` ничего не регистрируется — глобальная конфигурация
 Liquid в приложении остаётся нетронутой.
 
+## Проверка шаблона без рендера
+
+`LiquidXlsx.validate` разбирает шаблон и возвращает список всех найденных
+проблем. Данные не нужны, ничего не исполняется, на первой ошибке разбор не
+останавливается.
+
+```ruby
+result = LiquidXlsx.validate(
+  template: "invoice.xlsx",
+  known_filters: MyApp::Filters.public_instance_methods(false), # необязательно
+  dynamic_sheets: false                                          # как будете рендерить
+)
+
+result.valid?    # => false
+result.errors    # ошибки: документ не напечатается
+result.warnings  # предупреждения: напечатается, но не так, как задумано
+
+result.errors.first.code      # => :liquid_syntax
+result.errors.first.location  # => "Invoice!B12"
+```
+
+Почему это не «отрендерить и посмотреть»: рендер разбирает только тот Liquid,
+который реально исполняет. Опечатка в ветке `{% if %}`, которую этот документ не
+выбрал, или в теле цикла по пустой коллекции при пробном рендере не всплывёт — и
+дождётся другого документа. Плюс рендер выполняет шаблон на живых записях, что
+для проверки только что загруженного файла — лишнее.
+
+### Что находит
+
+| Код | Уровень | Что это |
+|---|---|---|
+| `:invalid_xlsx` | ошибка | файл не читается как книга `.xlsx` |
+| `:missing_worksheet` | ошибка | лист объявлен в `workbook.xml`, а его части в пакете нет |
+| `:template_syntax` | ошибка | непарные структурные теги, тег не на отдельной строке |
+| `:liquid_syntax` | ошибка | Liquid не разберёт фрагмент — рендер упадёт |
+| `:liquid_expression` | предупреждение | Liquid прочтёт выражение иначе, чем написано |
+| `:unknown_filter` | ошибка | фильтра не будет при рендере |
+| `:sheet_tag_disabled` | ошибка | `{% sheet %}` при `dynamic_sheets: false` |
+| `:sheet_template_missing` | ошибка | `{% sheet template: "X" %}`, а листа `X` нет |
+| `:merged_cell_crosses_block` | ошибка | объединение пересекает границу блока |
+| `:liquid_in_formula` | предупреждение | Liquid внутри формулы не вычисляется |
+| `:liquid_in_rich_text` | предупреждение | Liquid в ячейке с разным форматированием не читается |
+
+Разница между `:liquid_syntax` и `:liquid_expression` существенна.
+`{{ invoice.total b c }}` и `{{ invoice..total }}` Liquid принимает: печатает
+сумму, а лишнее молча выбрасывает. Документ выйдет, поэтому это предупреждение,
+а не ошибка — но в шаблоне написано не то, что имелось в виду.
+
+### Что шаблон использует
+
+```ruby
+result.roots      # => ["invoice", "customer"] — что шаблон ждёт на входе
+result.variables  # => [#<VariableUse root: "invoice", segments: ["items", "title"]>, ...]
+result.filters    # => ["money2", "date_words"]
+result.sheets     # => ["Invoice", "Приложение"]
+```
+
+`roots` — именно входные переменные: имена, которые шаблон заводит сам
+(`{% for item in ... %}`, `{% assign %}`, `{% capture %}`), из списка исключены.
+Так приложение может сверить шаблон со своей моделью данных, не разбирая Liquid
+самостоятельно.
+
+У пути есть признак `truncated?`: в `{{ items[i].title }}` за динамическим
+индексом проверять нечего, и об этом сказано явно — чтобы вызывающий код не
+объявил «нет такого поля» там, где поле определяется в рантайме.
+
 ## Обработка ошибок
 
 Все ошибки наследуются от `LiquidXlsx::Error < StandardError`. Там, где

data/lib/liquid_xlsx/renderer.rb

@@ -741,18 +741,10 @@ module LiquidXlsx
 
     private
 
+    # Shared with Validator: the renderer only sees blocks it executes, the
+    # validator sees all of them, and the two must judge a crossing the same way.
     def crosses_boundary?(merge_start, merge_end, block_start, block_end)
-      # Merge entirely above or below the block
-      return false if merge_end < block_start || merge_start > block_end
-
-      # Merge strictly inside the block body (between the tag rows)
-      return false if merge_start > block_start && merge_end < block_end
-
-      # Merge entirely on a single structural tag row (it is consumed with it)
-      return false if merge_start == merge_end && (merge_start == block_start || merge_start == block_end)
-
-      # Any other overlap = crossing (including merges that swallow a tag row)
-      true
+      Validation::BlockBoundary.crosses?(merge_start, merge_end, block_start, block_end)
     end
 
     def clone_merge(ref, start_offset, end_offset)

data/lib/liquid_xlsx/tags/sheet_tag.rb

@@ -12,6 +12,10 @@ module LiquidXlsx
     # - +data+: Liquid expression — object to pass as local variable
     # - +as+: (optional) quoted string — local variable name, defaults to "item"
     class SheetTag < Liquid::Tag
+      # Exposed for Validator: it has to know which sheet the tag clones, to
+      # check that the sheet exists, without rendering the tag.
+      attr_reader :template_name, :as_name
+
       SYNTAX = /\A\s*(.+)\s*\z/
       # Known argument keys. Values are split on the positions of these keys
       # (not on whitespace) so that a name/data value may itself contain

data/lib/liquid_xlsx/validation/block_boundary.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Validation
+    # Whether a merged range crosses the boundary of a structural block.
+    #
+    # A merge that starts outside a `{% for %}` and ends inside it cannot be
+    # cloned per iteration, so the renderer refuses such templates. The rule
+    # lives here because two callers need it and they must agree: the renderer
+    # (which only sees blocks it actually executes) and the validator (which
+    # sees every block in the AST, executed or not).
+    module BlockBoundary
+      module_function
+
+      def crosses?(merge_start, merge_end, block_start, block_end)
+        # Merge entirely above or below the block
+        return false if merge_end < block_start || merge_start > block_end
+
+        # Merge strictly inside the block body (between the tag rows)
+        return false if merge_start > block_start && merge_end < block_end
+
+        # Merge entirely on a single structural tag row (it is consumed with it)
+        return false if merge_start == merge_end && (merge_start == block_start || merge_start == block_end)
+
+        # Any other overlap = crossing (including merges that swallow a tag row)
+        true
+      end
+    end
+  end
+end

data/lib/liquid_xlsx/validation/issue.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Validation
+    # A single problem found in a template.
+    #
+    # `code` is a stable machine-readable symbol: host applications map it to
+    # their own localized text, so the English `message` here is a fallback for
+    # logs and specs, never the only thing a user can be shown.
+    Issue = Struct.new(:code, :severity, :sheet, :row, :cell, :message, :source,
+                       keyword_init: true) do
+      def error?
+        severity == :error
+      end
+
+      def warning?
+        severity == :warning
+      end
+
+      # Human-readable location: "Sheet1!B12", "Sheet1 row 12" or "Sheet1".
+      def location
+        return nil unless sheet
+
+        return "#{sheet}!#{cell}" if cell
+        return "#{sheet} row #{row}" if row
+
+        sheet
+      end
+
+      def to_h
+        { code: code, severity: severity, sheet: sheet, row: row, cell: cell,
+          message: message, source: source }
+      end
+    end
+  end
+end

data/lib/liquid_xlsx/validation/liquid_usage.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Validation
+    # Walks a parsed Liquid template and collects what it refers to: variable
+    # paths, filter names, and the names it binds itself.
+    #
+    # The point of doing this here rather than in the host application is that
+    # the host would have to parse every fragment a second time — and parse it
+    # with this gem's Liquid environment, or `{% sheet %}` and `{% image_tag %}`
+    # would come back as unknown tags. Handing back extracted usages keeps
+    # Liquid entirely on this side of the boundary.
+    class LiquidUsage
+      # Tags whose bodies Liquid exposes through an attachment rather than a
+      # nodelist ({% case %} branches).
+      def self.call(root)
+        collector = new
+        collector.walk(root)
+        collector
+      end
+
+      attr_reader :variables, :filters, :assigns, :locals
+
+      def initialize
+        @variables = []
+        @filters   = []
+        @assigns   = []
+        @locals    = []
+      end
+
+      def walk(node)
+        visit(node)
+        each_child(node) { |child| walk(child) }
+      end
+
+      private
+
+      def visit(node)
+        case node
+        when ::Liquid::Variable then visit_variable(node)
+        when ::Liquid::Assign   then visit_assign(node)
+        when ::Liquid::For      then visit_for(node)
+        when ::Liquid::TableRow then visit_for(node)
+        when ::Liquid::If       then visit_conditions(node.blocks)
+        when ::Liquid::Case     then visit_case(node)
+        when ::Liquid::Capture  then visit_capture(node)
+        end
+      end
+
+      def visit_variable(node)
+        collect_expression(node.name)
+        node.filters.each do |(name, *args)|
+          @filters << name.to_s
+          args.flatten.each { |arg| collect_expression(arg) }
+        end
+      end
+
+      def visit_assign(node)
+        @assigns << node.to.to_s
+        visit_variable(node.from) if node.from.is_a?(::Liquid::Variable)
+      end
+
+      # {% for item in list %} binds `item` (and `forloop`) for its body; the
+      # collection itself is an ordinary reference. `limit:`/`offset:` may be
+      # variables too.
+      def visit_for(node)
+        @locals << node.variable_name.to_s
+        @locals << "forloop"
+        collect_expression(node.collection_name)
+        collect_expression(node.limit)
+        collect_expression(node.from)
+      end
+
+      def visit_case(node)
+        collect_expression(node.left)
+        visit_conditions(node.blocks)
+      end
+
+      # Liquid does not expose the capture target, but a name captured and then
+      # used must not be reported as missing — read the ivar rather than let the
+      # host produce a false "unknown variable".
+      def visit_capture(node)
+        target = node.instance_variable_get(:@to)
+        @assigns << target.to_s if target
+      end
+
+      def visit_conditions(blocks)
+        Array(blocks).each do |condition|
+          next unless condition.respond_to?(:left)
+
+          collect_expression(condition.left)
+          collect_expression(condition.right)
+          visit_conditions([condition.child_condition]) if condition.child_condition
+        end
+      end
+
+      # Liquid's own children: BlockBody, nested tags, and the bodies {% case %}
+      # hangs off its conditions as attachments.
+      def each_child(node)
+        if node.respond_to?(:nodelist) && node.nodelist
+          node.nodelist.each { |child| yield child unless child.is_a?(::String) }
+        end
+
+        return unless node.is_a?(::Liquid::Case)
+
+        node.blocks.each do |condition|
+          attachment = condition.attachment
+          yield attachment if attachment
+        end
+      end
+
+      # A variable reference is a VariableLookup; literals and numbers are not
+      # references at all. Lookups that are themselves expressions (`items[i]`)
+      # end the path: what follows depends on a runtime value, so the caller is
+      # told the path is truncated instead of being handed a name to check.
+      def collect_expression(expression)
+        case expression
+        when ::Liquid::VariableLookup then collect_lookup(expression)
+        when ::Liquid::Variable       then visit_variable(expression)
+        when ::Liquid::RangeLookup
+          collect_expression(expression.instance_variable_get(:@start_obj))
+          collect_expression(expression.instance_variable_get(:@end_obj))
+        end
+      end
+
+      def collect_lookup(lookup)
+        root = lookup.name
+        # A lookup whose own name is an expression (`{{ [dynamic] }}`) has no
+        # static root to report.
+        return collect_expression(root) unless root.is_a?(::String)
+
+        segments  = []
+        truncated = false
+
+        Array(lookup.lookups).each do |segment|
+          unless segment.is_a?(::String)
+            collect_expression(segment)
+            truncated = true
+            break
+          end
+
+          segments << segment
+        end
+
+        @variables << VariableUse.new(root: root, segments: segments, truncated: truncated)
+      end
+    end
+  end
+end

data/lib/liquid_xlsx/validation/result.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Validation
+    # Outcome of validating a template: what is wrong with it, and what it uses.
+    #
+    # Validation never raises for a broken template — a broken template is the
+    # expected input here, and a caller wants the whole list, not the first
+    # failure. Only programming errors (a missing file handed to the validator,
+    # for instance) still raise.
+    class Result
+      attr_reader :issues, :usages, :sheets
+
+      def initialize(issues: [], usages: [], sheets: [])
+        @issues = issues
+        @usages = usages
+        @sheets = sheets
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def errors
+        issues.select(&:error?)
+      end
+
+      def warnings
+        issues.select(&:warning?)
+      end
+
+      def add(code:, severity: :error, sheet: nil, row: nil, cell: nil, message: nil, source: nil)
+        issues << Issue.new(code: code, severity: severity, sheet: sheet, row: row,
+                            cell: cell, message: message, source: source)
+        self
+      end
+
+      def add_usage(usage)
+        usages << usage
+        self
+      end
+
+      # Every variable reference in the workbook, deduplicated by path.
+      # Root names alone are rarely enough for a caller: `invoice.customer.name`
+      # and `invoice.customer.inn` are different questions to ask of a model.
+      def variables
+        usages.flat_map(&:variables).uniq(&:path)
+      end
+
+      # Root variable names the template expects to find in the data.
+      # Names bound by the template itself ({% for %}, {% assign %}) are not
+      # roots — they are excluded, otherwise every loop variable would look
+      # like a missing input.
+      def roots
+        bound = bound_names
+
+        variables.map(&:root).uniq.reject { |name| bound.include?(name) }
+      end
+
+      def filters
+        usages.flat_map(&:filters).uniq
+      end
+
+      # Names the template binds itself, in any sheet: loop variables, assigns,
+      # captures. Scope is deliberately ignored — a name bound anywhere counts
+      # as known everywhere. Tracking real scopes would let the validator report
+      # "unknown variable" for a name that is bound two rows above, and a false
+      # error costs more than a missed one here.
+      def bound_names
+        @bound_names ||= usages.flat_map { |usage| usage.assigns + usage.locals }.uniq
+      end
+
+      def to_h
+        { valid: valid?, issues: issues.map(&:to_h), sheets: sheets,
+          roots: roots, filters: filters,
+          variables: variables.map(&:path) }
+      end
+    end
+  end
+end

data/lib/liquid_xlsx/validation/usage.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Validation
+    # One variable reference found in a template fragment.
+    #
+    # `segments` is the lookup chain after the root: `invoice.items.first.name`
+    # becomes root "invoice" with segments ["items", "first", "name"].
+    #
+    # `truncated` marks a path the host application must not check past its last
+    # segment: a dynamic lookup (`items[idx].name`) hides what comes next, and
+    # reporting "no such field" for it would be a false alarm.
+    VariableUse = Struct.new(:root, :segments, :truncated, keyword_init: true) do
+      def path
+        ([root] + Array(segments)).join(".")
+      end
+
+      def truncated?
+        truncated ? true : false
+      end
+
+      def to_h
+        { root: root, segments: Array(segments), truncated: truncated?, path: path }
+      end
+    end
+
+    # Everything a single template fragment refers to.
+    #
+    # A fragment is one unit of Liquid the renderer will actually parse: a cell
+    # template, a structural `{% for %}` collection or an `{% if %}` condition.
+    # `kind` says which, so a host application can phrase its diagnostics in the
+    # user's terms ("cell B12" vs "the {% if %} in row 12").
+    # `kind` is one of :cell, :condition, :loop.
+    Usage = Struct.new(:sheet, :row, :cell, :kind, :source, :variables, :filters,
+                       :assigns, :locals, keyword_init: true) do
+      def variables
+        self[:variables] || []
+      end
+
+      def filters
+        self[:filters] || []
+      end
+
+      # Names bound by the fragment itself ({% assign %}, {% capture %}).
+      def assigns
+        self[:assigns] || []
+      end
+
+      # Names bound for the fragment's body ({% for item in ... %}, sheet `as:`).
+      def locals
+        self[:locals] || []
+      end
+
+      def to_h
+        { sheet: sheet, row: row, cell: cell, kind: kind, source: source,
+          variables: variables.map(&:to_h), filters: filters,
+          assigns: assigns, locals: locals }
+      end
+    end
+  end
+end

data/lib/liquid_xlsx/validator.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Checks a template without rendering it and without any data.
+  #
+  # Why this is not "render and see what happens": the renderer parses only the
+  # Liquid it actually executes (Renderer#cached_parse), so a typo inside an
+  # {% if %} branch that this document does not take, or inside a loop over an
+  # empty collection, stays invisible until the day some other document takes
+  # that branch. It also stops at the first failure, and rendering executes the
+  # template against live records — printing a document is a side effect nobody
+  # asked for when all they did was upload a file.
+  #
+  # So: parse everything, execute nothing, and report every problem found.
+  class Validator
+    LIQUID_MARKER = /\{\{|\{%/
+
+    # @param template_path [String] path to the .xlsx template
+    # @param dynamic_sheets [Boolean] whether the caller renders with
+    #   dynamic_sheets: true — {% sheet %} is an error when it does not
+    # @param known_filters [Array<String>, nil] filter names available at render
+    #   time; nil disables the unknown-filter check
+    def initialize(template_path, dynamic_sheets: false, known_filters: nil)
+      @template_path  = template_path
+      @dynamic_sheets = dynamic_sheets
+      @known_filters  = known_filters&.map(&:to_s)
+      @result         = Validation::Result.new
+    end
+
+    # @return [Validation::Result]
+    def call
+      package = open_package
+      return @result if package.nil?
+
+      sheet_names = safe_sheet_names(package)
+      @result.sheets.concat(sheet_names)
+
+      package.sheets.each { |sheet_info| validate_sheet(package, sheet_info) }
+
+      check_sheet_tags(sheet_names)
+      check_filters
+
+      @result
+    rescue Nokogiri::XML::SyntaxError => e
+      invalid_xlsx("Corrupt XML inside the workbook: #{e.message}")
+    end
+
+    private
+
+    attr_reader :result
+
+    def open_package
+      package = Package.new(@template_path)
+      package.read
+      package
+    rescue InvalidXlsxError => e
+      invalid_xlsx(e.message)
+      nil
+    rescue Zip::Error, Errno::ENOENT, Errno::EACCES, Errno::EISDIR => e
+      invalid_xlsx("#{e.class}: #{e.message}")
+      nil
+    end
+
+    def invalid_xlsx(message)
+      @result.add(code: :invalid_xlsx, message: "Not a readable .xlsx workbook. #{message}")
+      @result
+    end
+
+    # Sheet names are needed for {% sheet template: "X" %}; a workbook broken
+    # enough to fail here still gets its parts validated below.
+    def safe_sheet_names(package)
+      package.sheet_names
+    rescue StandardError
+      []
+    end
+
+    def validate_sheet(package, sheet_info)
+      name = sheet_info[:name]
+      xml  = worksheet_xml(package, sheet_info)
+      return if xml.nil?
+
+      worksheet = Worksheet.new(xml, name, SharedStrings.new(package.shared_strings_xml))
+      rows      = worksheet.parse_rows
+
+      check_formulas(name, rows)
+      check_rich_text(name, xml)
+
+      ast = parse_structure(name, rows)
+      # Structure did not parse: the cells are still worth checking, and a flat
+      # pass over them is exactly what the caller wants to see next to the
+      # structural error.
+      return validate_cells_flat(name, rows) if ast.nil?
+
+      validate_nodes(name, ast)
+      check_merges(name, worksheet, ast)
+    rescue Nokogiri::XML::SyntaxError => e
+      @result.add(code: :invalid_xlsx, sheet: name,
+                  message: "Corrupt XML in sheet '#{name}': #{e.message}")
+    end
+
+    # A workbook with no readable relationships part makes the lookup itself
+    # fail; for the caller that is the same problem as a missing sheet file, and
+    # the validator must not propagate it as a crash.
+    def worksheet_xml(package, sheet_info)
+      xml = begin
+        package.worksheet_xml(sheet_info[:r_id])
+      rescue StandardError
+        nil
+      end
+      return xml if xml
+
+      @result.add(code: :missing_worksheet, sheet: sheet_info[:name],
+                  message: "The workbook lists sheet '#{sheet_info[:name]}' " \
+                           "(#{sheet_info[:r_id]}) but the file for it is missing from the package.")
+      nil
+    end
+
+    # @return [Array<Nodes::Base>, nil] nil when the structure is broken
+    def parse_structure(name, rows)
+      TemplateParser.new(rows, name).parse
+    rescue TemplateSyntaxError => e
+      @result.add(code: :template_syntax, sheet: e.sheet || name, row: e.row, cell: e.cell,
+                  message: e.message.lines.first.to_s.strip, source: e.tag)
+      nil
+    end
+
+    # --- fragments ---------------------------------------------------------
+
+    def validate_nodes(sheet, nodes)
+      Array(nodes).each do |node|
+        case node
+        when Nodes::RowNode then validate_row(sheet, node.row_data)
+        when Nodes::ForNode then validate_for(sheet, node)
+        when Nodes::IfNode  then validate_if(sheet, node)
+        end
+      end
+    end
+
+    def validate_row(sheet, row)
+      row[:cells].each do |cell|
+        next unless cell[:template]
+
+        parse_fragment(sheet: sheet, row: row[:row_number], cell: "#{cell[:col]}#{row[:row_number]}",
+                       kind: :cell, source: cell[:template])
+      end
+    end
+
+    # The renderer looks the collection up by name (Renderer#resolve_for_collection),
+    # so validating `{{ name }}` sees exactly what it will see.
+    def validate_for(sheet, node)
+      usage = parse_fragment(sheet: sheet, row: node.for_row, kind: :loop,
+                             source: "{% for #{node.variable_name} in #{node.collection_name} %}",
+                             liquid: "{{ #{node.collection_name} }}")
+      if usage
+        usage.locals.push(node.variable_name.to_s, "forloop")
+        usage.locals.uniq!
+      end
+
+      validate_nodes(sheet, node.body)
+      validate_nodes(sheet, node.else_body)
+    end
+
+    # Conditions are wrapped exactly as Renderer#evaluate_condition wraps them:
+    # validating a different string than the one that gets executed would check
+    # the wrong thing.
+    def validate_if(sheet, node)
+      node.branches.each do |branch|
+        condition = branch[:condition]
+        if condition
+          parse_fragment(sheet: sheet, row: node.if_row, kind: :condition,
+                         source: "{% if #{condition} %}",
+                         liquid: "{% if #{condition} %}true{% endif %}")
+        end
+
+        validate_nodes(sheet, branch[:body])
+      end
+    end
+
+    # Cells of a sheet whose structure did not parse.
+    def validate_cells_flat(sheet, rows)
+      rows.each { |row| validate_row(sheet, row) }
+    end
+
+    # Fragments are parsed twice, in strict mode and in Liquid's default lax
+    # mode, because the two modes answer different questions.
+    #
+    # Lax mode is what the renderer uses, so a fragment it rejects will not
+    # print — that is an error. What lax mode accepts, it may still not read the
+    # way the author meant: `{{ invoice.total b c }}` and `{{ invoice..total }}`
+    # both render the total and quietly drop the rest. Strict mode is the only
+    # thing that notices, and the right word for it is a warning, not an error:
+    # the document does print, and calling it broken would be false.
+    #
+    # @return [Validation::Usage, nil] nil when the fragment does not parse
+    def parse_fragment(sheet:, kind:, source:, row: nil, cell: nil, liquid: nil)
+      text     = liquid || source
+      template = parse_liquid(text, :strict)
+      usage    = build_usage(template, sheet: sheet, row: row, cell: cell, kind: kind, source: source)
+      @result.add_usage(usage)
+      usage
+    rescue ::Liquid::SyntaxError => e
+      report_syntax_error(e, text: text, sheet: sheet, row: row, cell: cell, source: source)
+      nil
+    rescue TemplateSyntaxError, LiquidXlsx::Error => e
+      # Tag constructors of this gem validate their own arguments at parse time
+      # ({% sheet %} without `template:`, for instance).
+      @result.add(code: :liquid_syntax, sheet: sheet, row: row, cell: cell,
+                  message: e.message.lines.first.to_s.strip, source: source)
+      nil
+    end
+
+    def parse_liquid(text, error_mode)
+      ::Liquid::Template.parse(text, environment: LiquidXlsx.liquid_environment, error_mode: error_mode)
+    end
+
+    # Two different problems wear the same exception, and a user needs to tell
+    # them apart: a fragment the renderer will refuse outright (error), and a
+    # fragment it will accept while silently ignoring part of what was written
+    # (warning).
+    def report_syntax_error(error, text:, sheet:, row:, cell:, source:)
+      if parses_leniently?(text)
+        @result.add(code: :liquid_expression, severity: :warning, sheet: sheet, row: row, cell: cell,
+                    message: "Liquid does not read this expression the way it is written and will " \
+                             "ignore part of it: #{error.message}",
+                    source: source)
+      else
+        @result.add(code: :liquid_syntax, sheet: sheet, row: row, cell: cell,
+                    message: error.message, source: source)
+      end
+    end
+
+    def parses_leniently?(text)
+      parse_liquid(text, :lax)
+      true
+    rescue ::Liquid::SyntaxError, LiquidXlsx::Error
+      false
+    end
+
+    def build_usage(template, sheet:, row:, cell:, kind:, source:)
+      collected = Validation::LiquidUsage.call(template.root)
+      @sheet_tags = (@sheet_tags || []).concat(collect_sheet_tags(template.root, sheet, row, cell))
+
+      Validation::Usage.new(
+        sheet: sheet, row: row, cell: cell, kind: kind, source: source,
+        variables: collected.variables.uniq(&:path),
+        filters: collected.filters.uniq,
+        assigns: collected.assigns.uniq,
+        locals: collected.locals.uniq
+      )
+    end
+
+    # --- whole-workbook checks --------------------------------------------
+
+    def collect_sheet_tags(node, sheet, row, cell)
+      found = []
+      walk_liquid(node) do |child|
+        next unless child.is_a?(Tags::SheetTag)
+
+        found << { tag: child, sheet: sheet, row: row, cell: cell }
+      end
+      found
+    end
+
+    def walk_liquid(node, &block)
+      yield node
+      return unless node.respond_to?(:nodelist) && node.nodelist
+
+      node.nodelist.each do |child|
+        next if child.is_a?(::String)
+
+        walk_liquid(child, &block)
+      end
+    end
+
+    # {% sheet %} needs two things the fragment itself cannot know: the caller
+    # must render with dynamic_sheets, and the sheet named in `template:` must
+    # exist. Both fail at render time today, long after the template was saved.
+    def check_sheet_tags(sheet_names)
+      Array(@sheet_tags).each do |entry|
+        tag = entry[:tag]
+
+        unless @dynamic_sheets
+          @result.add(code: :sheet_tag_disabled, sheet: entry[:sheet], row: entry[:row], cell: entry[:cell],
+                      message: "{% sheet %} requires rendering with dynamic_sheets: true.")
+        end
+
+        template_name = tag.template_name
+        next if template_name.nil? || sheet_names.empty? || sheet_names.include?(template_name)
+
+        @result.add(code: :sheet_template_missing, sheet: entry[:sheet], row: entry[:row], cell: entry[:cell],
+                    message: "{% sheet %} refers to template sheet '#{template_name}', " \
+                             "which does not exist in this workbook.")
+      end
+    end
+
+    def check_filters
+      return if @known_filters.nil?
+
+      @result.usages.each do |usage|
+        usage.filters.each do |filter|
+          next if @known_filters.include?(filter)
+
+          @result.add(code: :unknown_filter, sheet: usage.sheet, row: usage.row, cell: usage.cell,
+                      message: "Unknown filter '#{filter}'.", source: usage.source)
+        end
+      end
+    end
+
+    # Liquid inside a formula is never evaluated: Worksheet#extract_cell_text
+    # keeps formula cells as formulas, so the tag travels into the output file
+    # untouched. Silent, and hard to spot in a large sheet.
+    def check_formulas(sheet, rows)
+      rows.each do |row|
+        row[:cells].each do |cell|
+          formula = cell[:formula]
+          next unless formula&.match?(LIQUID_MARKER)
+
+          @result.add(code: :liquid_in_formula, severity: :warning, sheet: sheet,
+                      row: row[:row_number], cell: "#{cell[:col]}#{row[:row_number]}",
+                      message: "Liquid inside a formula is not evaluated.",
+                      source: "=#{formula}")
+        end
+      end
+    end
+
+    # Rich-text inline strings: text split into runs (<is><r><t>) is not read by
+    # the renderer, so Liquid written there disappears from the output without
+    # any error. Editors produce runs as soon as part of a cell is formatted
+    # differently — a bold word inside the cell is enough.
+    def check_rich_text(sheet, xml)
+      doc = Nokogiri::XML(xml)
+      ns  = doc.root&.namespace
+      return unless ns
+
+      doc.xpath("//xmlns:c[@t='inlineStr']", "xmlns" => ns.href).each do |cell|
+        is_element = cell.at_xpath("xmlns:is")
+        next if is_element.nil? || is_element.at_xpath("xmlns:t")
+
+        text = is_element.xpath(".//xmlns:t").map(&:text).join
+        next unless text.match?(LIQUID_MARKER)
+
+        @result.add(code: :liquid_in_rich_text, severity: :warning, sheet: sheet,
+                    cell: cell["r"],
+                    message: "Liquid in a rich-text cell is not read. Retype the cell " \
+                             "so all of its text has the same formatting.",
+                    source: text)
+      end
+    end
+
+    def check_merges(sheet, worksheet, ast)
+      merges = worksheet.merge_cells
+      return if merges.empty?
+
+      blocks = collect_blocks(ast)
+      return if blocks.empty?
+
+      merges.each do |merge|
+        blocks.each do |block|
+          next unless Validation::BlockBoundary.crosses?(merge[:start_row], merge[:end_row],
+                                                         block[:start], block[:end])
+
+          @result.add(code: :merged_cell_crosses_block, sheet: sheet, row: block[:start],
+                      message: "Merged cell '#{merge[:ref]}' crosses the boundary of a " \
+                               "#{block[:type]} block (rows #{block[:start]}-#{block[:end]}).",
+                      source: merge[:ref])
+        end
+      end
+    end
+
+    def collect_blocks(nodes, blocks = [])
+      Array(nodes).each do |node|
+        case node
+        when Nodes::ForNode
+          blocks << { type: :for, start: node.for_row, end: node.endfor_row } if node.for_row && node.endfor_row
+          collect_blocks(node.body, blocks)
+          collect_blocks(node.else_body, blocks)
+        when Nodes::IfNode
+          blocks << { type: :if, start: node.if_row, end: node.endif_row } if node.if_row && node.endif_row
+          node.branches.each { |branch| collect_blocks(branch[:body], blocks) }
+        end
+      end
+
+      blocks
+    end
+  end
+end

data/lib/liquid_xlsx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LiquidXlsx
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/liquid_xlsx.rb

@@ -20,6 +20,12 @@ require_relative "liquid_xlsx/worksheet"
 require_relative "liquid_xlsx/renderer"
 require_relative "liquid_xlsx/workbook"
 require_relative "liquid_xlsx/template"
+require_relative "liquid_xlsx/validation/issue"
+require_relative "liquid_xlsx/validation/usage"
+require_relative "liquid_xlsx/validation/result"
+require_relative "liquid_xlsx/validation/block_boundary"
+require_relative "liquid_xlsx/validation/liquid_usage"
+require_relative "liquid_xlsx/validator"
 
 # LiquidXlsx is a Ruby gem for generating .xlsx files from Excel templates
 # with Liquid syntax. Edit templates in Excel, write Liquid in cells,
@@ -89,5 +95,38 @@ module LiquidXlsx
       # rubocop:enable Metrics/ParameterLists
       tpl.render_to_file(data, output)
     end
+
+    # Check a template without rendering it and without any data.
+    #
+    # Unlike a trial render, this parses every cell and every branch — including
+    # the ones a particular document would not take — collects all problems
+    # instead of stopping at the first, and executes nothing, so validating a
+    # template has no side effects on the application's records.
+    #
+    #   result = LiquidXlsx.validate(template: "invoice.xlsx",
+    #                                known_filters: MyFilters.public_instance_methods(false))
+    #   result.valid?   # => false
+    #   result.issues   # => [#<Issue code: :liquid_syntax, sheet: "Sheet1", cell: "B12", ...>]
+    #   result.roots    # => ["invoice", "customer"]  — what the template expects as input
+    #
+    # @param template [String] path to the .xlsx template
+    # @param dynamic_sheets [Boolean] pass true if you render with dynamic_sheets:
+    #   true; otherwise {% sheet %} in the template is reported as an error,
+    #   because that is what rendering it would do
+    # @param known_filters [Array<String, Symbol>, nil] filter names available at
+    #   render time (standard Liquid filters are included automatically); nil
+    #   disables the unknown-filter check
+    # @return [Validation::Result]
+    def validate(template:, dynamic_sheets: false, known_filters: nil)
+      Validator.new(template,
+                    dynamic_sheets: dynamic_sheets,
+                    known_filters: known_filters && (known_filters.map(&:to_s) + standard_filters))
+               .call
+    end
+
+    # Filters every Liquid template can use without the host registering anything.
+    def standard_filters
+      @standard_filters ||= ::Liquid::StandardFilters.public_instance_methods(false).map(&:to_s)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: liquid_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Ivan Khlipitkin
@@ -112,6 +112,12 @@ files:
 - lib/liquid_xlsx/template.rb
 - lib/liquid_xlsx/template_nodes.rb
 - lib/liquid_xlsx/template_parser.rb
+- lib/liquid_xlsx/validation/block_boundary.rb
+- lib/liquid_xlsx/validation/issue.rb
+- lib/liquid_xlsx/validation/liquid_usage.rb
+- lib/liquid_xlsx/validation/result.rb
+- lib/liquid_xlsx/validation/usage.rb
+- lib/liquid_xlsx/validator.rb
 - lib/liquid_xlsx/version.rb
 - lib/liquid_xlsx/workbook.rb
 - lib/liquid_xlsx/worksheet.rb