varar-core 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 840328108129bed1a48c4a3dc86fa1ca4d13937f0e313ccfa41fcaf0a98f89c3
-  data.tar.gz: 10d2916bda1d520f5521a99ddfd524305170b711fe476359746d83f5fa3f943b
+  metadata.gz: 8d857a484c127ac8dc313cff7dc855f7924e9b90dd9935b3575e880a4abc5e9c
+  data.tar.gz: becbdbfe8eda5afc06b7506b719fafd3868e1506cec1e484e461766b7b39225a
 SHA512:
-  metadata.gz: 579d8c9e3dbb19fb6b29165dd8ba075f9ec4d6cf75808648ffd0bbc49e9d5265c7864b784d5d79a29a1d66f530d4fc5b5b3739c434e60f4541e196421e5c402d
-  data.tar.gz: 42376d608744ce23fd97dc740c024d9432addf7b039a0ddcaa73eceab320c159ea06797e2729c13b4005d76c82a4fefde45af7cdebcaa8eacb1c5cf93a1499cf
+  metadata.gz: f1f17d5bf2fef77cc8c8dbb4d0991c72232b08d0fe139f0c60768016c86b2eeeca33e54b66a4098ba1ab5bf15cbb00aa91f0a3e48e9ceadc7c457c630085d62c
+  data.tar.gz: 05404cecafaeca822ede078824c9bfad5d959236ea7c23f00a8b44a9d0ffe4a002ff9363d7c52bc86649d2d3bfd6b353f68c67c1131ac0c867172beac0e0913f

data/lib/varar/core/ast.rb

@@ -40,7 +40,11 @@ module Varar
       def kind = 'thematic_break'
     end
 
-    Example = Data.define(:scope_stack, :span, :body)
+    # +preceded_by_delimiter+ is true when a heading or thematic break (`---`)
+    # sits between this candidate and the previous one (also true for the first
+    # candidate). The planner uses it to group adjacent matching candidates into
+    # one example. See ADR 0012.
+    Example = Data.define(:scope_stack, :span, :body, :preceded_by_delimiter)
 
     VarDoc = Data.define(:path, :source, :examples, :orphan_attachments)
   end

data/lib/varar/core/cell_diff.rb

@@ -5,7 +5,11 @@ module Varar
     # One checked column of one header-bound row: the cell text and its span.
     RowCheck = Data.define(:column, :value, :span)
 
-    # The verdict for one checked column after comparing against the table.
+    # The verdict for one comparison of one CELL — the atomic value a sensor
+    # checks against the document. A cell is a table cell, a header-bound row's
+    # cell, or a value captured from a paragraph by an expression parameter; all
+    # three land here. `column` labels the cell (a header cell's text, or `arg N`
+    # for an inline capture).
     # expected_value/actual_value/formatted are adapter-facing, never serialized.
     CellDiff = Data.define(:column, :span, :expected, :actual, :ok,
                            :expected_value, :actual_value, :formatted) do
@@ -18,7 +22,8 @@ module Varar
     # The step returned the wrong type/shape — an author mistake, not a value diff.
     class ReturnShapeError < StandardError; end
 
-    # Raised when a header-bound row's / a table's returned columns don't match.
+    # Raised when one or more compared CELLS differ — an inline capture, a table
+    # cell, or a header-bound row's cell.
     class CellMismatchError < StandardError
       attr_reader :cells
 

data/lib/varar/core/conformance.rb

@@ -93,7 +93,8 @@ module Varar
         {
           'scopeStack' => example.scope_stack,
           'span' => span_hash(example.span),
-          'body' => example.body.map { |b| block_hash(b) }
+          'body' => example.body.map { |b| block_hash(b) },
+          'precededByDelimiter' => example.preceded_by_delimiter
         }
       end
 
@@ -195,16 +196,6 @@ module Varar
               { 'column' => c.column, 'expected' => c.expected, 'actual' => c.actual, 'span' => span_hash(c.span) }
             end
           }
-        when DocStringMismatchError
-          {
-            'kind' => 'doc-string-mismatch', 'line' => line, 'anchor' => anchor,
-            'message' => error.message,
-            'diff' => {
-              'expected' => error.diff.expected,
-              'actual' => error.diff.actual,
-              'span' => span_hash(error.diff.span)
-            }
-          }
         when ReturnShapeError
           { 'kind' => 'return-shape', 'line' => line, 'anchor' => anchor, 'message' => error.message }
         when UnexpectedPassError

data/lib/varar/core/doc_string_diff.rb

@@ -4,32 +4,30 @@ require 'varar/core/cell_diff'
 
 module Varar
   module Core
-    # A doc-string content difference: fence body span, expected, actual.
-    DocStringDiff = Data.define(:span, :expected, :actual)
-
-    # Raised when a doc-string step's returned string differs from the content.
-    class DocStringMismatchError < StandardError
-      attr_reader :diff
-
-      def initialize(diff)
-        @diff = diff
-        super("doc string: expected #{diff.expected.inspect} but was #{diff.actual.inspect}")
-      end
-    end
+    # The column label a doc-string cell carries in a CellDiff, so its mismatch
+    # message reads `doc string: expected … but was …`.
+    DOC_STRING_COLUMN = 'doc string'
 
     # Pure comparison of a doc-string step's return against the fence body.
     # Port of doc-string-diff.ts.
     module DocStringDiffs
       module_function
 
-      # nil → no check; equal string → nil (pass); unequal → DocStringDiff;
+      # A doc string is ONE CELL, compared whole, so a difference is an ordinary
+      # CellDiff and the executor raises the same CellMismatchError as any other
+      # cell. `expected`/`actual` are quoted: a doc string routinely differs only
+      # in whitespace, and bare text would render a missing trailing newline as
+      # no difference at all.
+      #
+      # nil → no check; equal string → nil (pass); unequal → CellDiff;
       # non-string → ReturnShapeError.
       def compare_doc_string(returned, content, span)
         return nil if returned.nil?
         raise ReturnShapeError, "expected a doc string (string), got #{returned.class}" unless returned.is_a?(String)
         return nil if returned == content
 
-        DocStringDiff.new(span: span, expected: content, actual: returned)
+        CellDiff.new(column: DOC_STRING_COLUMN, span: span, expected: content.inspect,
+                     actual: returned.inspect, ok: false)
       end
     end
   end

data/lib/varar/core/drift.rb

@@ -31,12 +31,20 @@ module Varar
 
       module_function
 
-      def within?(inner, outer)
-        inner.start_offset >= outer.start_offset && inner.end_offset <= outer.end_offset
+      # Do the two spans overlap at all (offset ranges intersect)? A candidate
+      # paragraph relates to its planned example either way round: a header-bound
+      # row sits inside its binding paragraph, while a merged example's span
+      # covers each candidate it absorbed (ADR 0012). Overlap catches both.
+      def overlaps?(span_a, span_b)
+        span_a.start_offset < span_b.end_offset && span_b.start_offset < span_a.end_offset
       end
 
+      # A candidate is "live" (still an example) if it overlaps at least one
+      # planned example. A now-prose paragraph — one whose step def was renamed
+      # or deleted — overlaps none (it became a delimiter, splitting any example
+      # it was part of), so drift catches it.
       def live?(candidate_span, plan)
-        plan.examples.any? { |pe| within?(pe.span, candidate_span) }
+        plan.examples.any? { |pe| overlaps?(pe.span, candidate_span) }
       end
 
       # Lower-cased word tokens (letters/digits) — the unit of similarity.

data/lib/varar/core/execute.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'varar/core/span'
-require 'varar/core/deep_freeze'
 require 'varar/core/cell_diff'
 require 'varar/core/doc_string_diff'
 require 'varar/core/param_diff'
@@ -61,7 +60,7 @@ module Varar
 
           ex.steps.each_with_index do |step, i|
             file = step.step_def.expression_source_file
-            state_by_file[file] = DeepFreeze.deep_freeze(create_ctx.call(file)) unless state_by_file.key?(file)
+            state_by_file[file] = create_ctx.call(file) unless state_by_file.key?(file)
             state = state_by_file[file]
 
             extra = []
@@ -76,9 +75,12 @@ module Varar
               last_return = returned
               case step.step_def.kind
               when 'stimulus'
-                # Full replacement: the returned Hash IS the next state (deep-frozen).
-                # There is no merge — a return with fewer keys shrinks the state.
-                # nil is a no-op; any other type is a contract violation.
+                # Full replacement: the returned Hash IS the next state. There is
+                # no merge — a return with fewer keys shrinks the state. nil is a
+                # no-op; any other type is a contract violation.
+                #
+                # The state is the author's own value, handed back untouched: we
+                # do not freeze it. Whether it is immutable is the author's call.
                 unless returned.nil?
                   unless returned.is_a?(Hash)
                     raise ReturnShapeError,
@@ -86,11 +88,11 @@ module Varar
                           'or nothing to leave it unchanged'
                   end
 
-                  state = DeepFreeze.deep_freeze(returned)
+                  state = returned
                   state_by_file[file] = state
                 end
               when 'sensor'
-                compare_sensor_return(plan, ex, step, returned, extra) if ex.row_checks.nil? && !returned.nil?
+                compare_sensor_return(plan, ex, step, returned, extra) if ex.row_checks.nil?
               else
                 raise ReturnShapeError, "unknown step kind: #{step.step_def.kind}"
               end
@@ -106,10 +108,16 @@ module Varar
 
           # Header-bound row checks (after all steps).
           if thrown.nil? && ex.row_checks && !ex.row_checks.empty?
+            # Like a slotted sensor, a header-bound row step must answer the row
+            # it is bound to: no return means nothing was compared.
+            row_error = if last_return.nil?
+                          ReturnShapeError.new('a header-bound row step must return a row object ' \
+                                               'with one value per bound cell, got nothing')
+                        end
             bad = CellDiffs.compare_row(last_return, ex.row_checks).reject(&:ok)
-            unless bad.empty?
+            if row_error || !bad.empty?
               last_step = ex.steps.last
-              augmented = augment_stack(CellMismatchError.new(bad), last_step, var_path)
+              augmented = augment_stack(row_error || CellMismatchError.new(bad), last_step, var_path)
               observer&.call(observation(ex, example_index, ex.steps.length,
                                          last_step.step_def.expression_source_file, 'fail', augmented))
               thrown = augmented
@@ -133,20 +141,30 @@ module Varar
       end
 
       # Sensor slot contract: zero slots + a return is a mistake; one slot IS
-      # the return; two+ is a positional array. Raises the appropriate diff error.
+      # the return; two+ is a positional array. With one or more slots the
+      # return is REQUIRED — returning nothing used to skip the comparison
+      # silently, so a typo turned an assertion into a no-op. Raises the
+      # appropriate diff error.
       def compare_sensor_return(plan, _ex, step, returned, extra)
         slot_count = step.args.length + extra.length
         if slot_count.zero?
+          return if returned.nil?
+
           raise ReturnShapeError, 'this sensor has no parameters, data table or doc string — ' \
                                   'nothing to compare a return value against (raise to fail, return nothing to pass)'
         end
 
+        if returned.nil?
+          raise ReturnShapeError,
+                "a sensor with #{slot_count} slot(s) must return one value per slot, got nothing"
+        end
+
         if slot_count == 1
           slots = [returned]
         else
           unless returned.is_a?(Array)
             raise ReturnShapeError,
-                  "a sensor with #{slot_count} parameters must return a list of " \
+                  "a sensor with #{slot_count} slots must return a list of " \
                   "#{slot_count} values, got #{returned.class}"
           end
           unless returned.length == slot_count
@@ -171,7 +189,7 @@ module Varar
         elsif step.doc_string
           diff = DocStringDiffs.compare_doc_string(slots[step.args.length], step.doc_string.content,
                                                    step.doc_string.span)
-          raise DocStringMismatchError, diff unless diff.nil?
+          raise CellMismatchError, [diff] unless diff.nil?
         end
       end
 

data/lib/varar/core/failure_anchor.rb

@@ -17,8 +17,6 @@ module Varar
         when CellMismatchError
           failing = error.cells.find { |c| !c.ok }
           failing ? failing.span : fallback
-        when DocStringMismatchError
-          error.diff.span
         else
           fallback
         end

data/lib/varar/core/param_diff.rb

@@ -36,7 +36,7 @@ module Varar
                             render_param_value(expected[i], format)[0]
                           end
           CellDiff.new(
-            column: "arg #{i + 1}",
+            column: "cell #{i + 1}",
             span: param_spans[i],
             expected: expected_text,
             actual: actual_text,

data/lib/varar/core/plan.rb

@@ -38,160 +38,237 @@ module Varar
       BlockPlan = Data.define(:steps, :ambiguities)
       Ambiguity = Data.define(:match_start, :match_end, :candidates)
 
+      # A candidate paragraph, planned in isolation (Phase 1). Either a
+      # header-bound table (standalone rows) or a step-bearing candidate the
+      # grouping pass may merge into an open example.
+      HeaderBoundUnit = Data.define(:rows)
+      StepsUnit = Data.define(:matched, :preceded_by_delimiter, :name, :scope_stack, :span, :steps,
+                              :expected_outcome, :expected_error_message)
+
+      # An open, merging example being built up across adjacent matching
+      # candidates in Phase 2.
+      MergedExample = Struct.new(:name, :scope_stack, :start_offset, :end_offset, :steps,
+                                 :expected_outcome, :expected_error_message)
+
       module_function
 
       def plan(var_doc, registry)
-        examples = []
         diagnostics = []
 
-        var_doc.examples.each do |ex|
-          had_ambiguous = false
-          steps_by_block = {}
-
-          # Pass 1: plan each text-bearing block.
-          ex.body.each_with_index do |block, idx|
-            next unless %w[paragraph list_item blockquote].include?(block.kind)
-
-            result = plan_block(block.text, registry)
-
-            result.ambiguities.each do |collision|
-              span = lift_span(var_doc.source, block, collision.match_start, collision.match_end)
-              cp_start = Offsets.cp_index_for_utf16(block.text, collision.match_start)
-              cp_end = Offsets.cp_index_for_utf16(block.text, collision.match_end)
-              diagnostics << Diagnostics.ambiguous_match(
-                AmbiguousInput.new(
-                  text: block.text[cp_start...cp_end],
-                  span: span,
-                  candidates: collision.candidates.map do |c|
-                    Candidate.new(
-                      expression: c.expression,
-                      source_file: c.step_def.expression_source_file,
-                      source_line: c.step_def.expression_source_line
-                    )
-                  end
-                )
-              )
-              had_ambiguous = true
-            end
+        # Phase 1: plan each candidate paragraph independently into a "unit".
+        units = var_doc.examples.map { |ex| plan_candidate(ex, var_doc, registry, diagnostics) }
 
-            next unless !had_ambiguous && !result.steps.empty?
+        # Phase 2: group adjacent candidates into examples. A matching candidate
+        # continues the open example when no delimiter (heading / `---`) precedes
+        # it; otherwise it starts a new one. A non-matching candidate (prose) is
+        # a delimiter: it closes the open example and is dropped. A header-bound
+        # table candidate is standalone — one example per row. See ADR 0012.
+        examples = []
+        open = nil
+        flush = lambda do
+          examples << finish_merged(open, var_doc.source) if open
+          open = nil
+        end
+        units.each do |unit|
+          if unit.is_a?(HeaderBoundUnit)
+            flush.call
+            examples.concat(unit.rows)
+            next
+          end
+          unless unit.matched
+            # Prose paragraph — a delimiter. Drop it and end the open example.
+            flush.call
+            next
+          end
+          if open && !unit.preceded_by_delimiter
+            merge_into(open, unit)
+          else
+            flush.call
+            open = start_merged(unit)
+          end
+        end
+        flush.call
+
+        ExecutionPlan.new(var_doc: var_doc, examples: examples, diagnostics: diagnostics)
+      end
+
+      def start_merged(unit)
+        MergedExample.new(unit.name, unit.scope_stack, unit.span.start_offset, unit.span.end_offset,
+                          unit.steps.dup, unit.expected_outcome, unit.expected_error_message)
+      end
+
+      def merge_into(open, unit)
+        open.end_offset = unit.span.end_offset
+        open.steps.concat(unit.steps)
+        # Any error fence in a merged part marks the whole example
+        # expected-to-fail; keep the first message we see.
+        return unless unit.expected_outcome == 'fail'
+
+        open.expected_outcome = 'fail'
+        return unless open.expected_error_message.nil? && !unit.expected_error_message.nil?
+
+        open.expected_error_message = unit.expected_error_message
+      end
+
+      def finish_merged(open, source)
+        span = Offsets.span_from_offsets(source, open.start_offset, open.end_offset)
+        PlannedExample.new(
+          name: open.name,
+          scope_stack: open.scope_stack,
+          span: span,
+          steps: open.steps,
+          expected_outcome: open.expected_outcome,
+          expected_error_message: open.expected_error_message
+        )
+      end
 
-            steps_by_block[idx] = result.steps.map do |hit|
-              PlannedStep.new(
-                text: Offsets.utf16_slice(block.text, hit.match_start, hit.match_end),
-                match_span: lift_span(var_doc.source, block, hit.match_start, hit.match_end),
-                param_spans: hit.param_spans.map { |p| lift_span(var_doc.source, block, p.start, p.end) },
-                step_def: hit.step_def,
-                args: hit.args,
-                formats: hit.formats
+      # Plan a single candidate paragraph (plus attached tables/fences) in
+      # isolation. Emits ambiguity / error-fence diagnostics into +diagnostics+.
+      def plan_candidate(ex, var_doc, registry, diagnostics)
+        had_ambiguous = false
+        steps_by_block = {}
+
+        # Pass 1: plan each text-bearing block.
+        ex.body.each_with_index do |block, idx|
+          next unless %w[paragraph list_item blockquote].include?(block.kind)
+
+          result = plan_block(block.text, registry)
+
+          result.ambiguities.each do |collision|
+            span = lift_span(var_doc.source, block, collision.match_start, collision.match_end)
+            cp_start = Offsets.cp_index_for_utf16(block.text, collision.match_start)
+            cp_end = Offsets.cp_index_for_utf16(block.text, collision.match_end)
+            diagnostics << Diagnostics.ambiguous_match(
+              AmbiguousInput.new(
+                text: block.text[cp_start...cp_end],
+                span: span,
+                candidates: collision.candidates.map do |c|
+                  Candidate.new(
+                    expression: c.expression,
+                    source_file: c.step_def.expression_source_file,
+                    source_line: c.step_def.expression_source_line
+                  )
+                end
               )
-            end
+            )
+            had_ambiguous = true
           end
 
-          # Header-bound table detection.
-          bound = had_ambiguous ? nil : detect_header_bound(ex, steps_by_block, var_doc.source)
-          if bound
-            table, binding_step, header_spans = bound
-            header_binding = HeaderBinding.new(
-              match_span: binding_step.match_span,
-              param_spans: header_spans,
-              step_def: binding_step.step_def
+          next unless !had_ambiguous && !result.steps.empty?
+
+          steps_by_block[idx] = result.steps.map do |hit|
+            PlannedStep.new(
+              text: Offsets.utf16_slice(block.text, hit.match_start, hit.match_end),
+              match_span: lift_span(var_doc.source, block, hit.match_start, hit.match_end),
+              param_spans: hit.param_spans.map { |p| lift_span(var_doc.source, block, p.start, p.end) },
+              step_def: hit.step_def,
+              args: hit.args,
+              formats: hit.formats
             )
-            table.rows.each do |row|
-              row_object = {}
-              table.header.cells.each_with_index do |cell_name, i|
-                row_object[cell_name] = i < row.cells.length ? row.cells[i] : ''
-              end
-              row_step = PlannedStep.new(
-                text: binding_step.text,
-                match_span: row.span,
-                param_spans: binding_step.param_spans,
-                step_def: binding_step.step_def,
-                args: binding_step.args + [row_object],
-                formats: binding_step.formats
-              )
-              row_checks = table.header.cells.each_with_index.map do |cell_name, i|
-                RowCheck.new(
-                  column: cell_name,
-                  value: i < row.cells.length ? row.cells[i] : '',
-                  span: i < row.cell_spans.length ? row.cell_spans[i] : row.span
-                )
-              end
-              examples << PlannedExample.new(
-                name: row.cells.join(' / '),
-                scope_stack: ex.scope_stack + [binding_step.text],
-                span: row.span,
-                steps: [row_step],
-                header_binding: header_binding,
-                row_checks: row_checks
+          end
+        end
+
+        # Header-bound table detection.
+        bound = had_ambiguous ? nil : detect_header_bound(ex, steps_by_block, var_doc.source)
+        if bound
+          table, binding_step, header_spans = bound
+          header_binding = HeaderBinding.new(
+            match_span: binding_step.match_span,
+            param_spans: header_spans,
+            step_def: binding_step.step_def
+          )
+          rows = table.rows.map do |row|
+            row_object = {}
+            table.header.cells.each_with_index do |cell_name, i|
+              row_object[cell_name] = i < row.cells.length ? row.cells[i] : ''
+            end
+            row_step = PlannedStep.new(
+              text: binding_step.text,
+              match_span: row.span,
+              param_spans: binding_step.param_spans,
+              step_def: binding_step.step_def,
+              args: binding_step.args + [row_object],
+              formats: binding_step.formats
+            )
+            row_checks = table.header.cells.each_with_index.map do |cell_name, i|
+              RowCheck.new(
+                column: cell_name,
+                value: i < row.cells.length ? row.cells[i] : '',
+                span: i < row.cell_spans.length ? row.cell_spans[i] : row.span
               )
             end
-            next
+            PlannedExample.new(
+              name: row.cells.join(' / '),
+              scope_stack: ex.scope_stack + [binding_step.text],
+              span: row.span,
+              steps: [row_step],
+              header_binding: header_binding,
+              row_checks: row_checks
+            )
           end
+          return HeaderBoundUnit.new(rows: rows)
+        end
 
-          # Error fence detection.
-          error_fence = ex.body.find { |b| b.kind == 'fence' && b.info == 'error' }
-
-          # Pass 2: attach trailing table / fence to the last step of a block.
-          attachments = {}
-          (1...ex.body.length).each do |idx|
-            here = ex.body[idx]
-            if here.kind == 'table' && steps_by_block.key?(idx - 1)
-              _prev_data, prev_doc = attachments[idx - 1] || [nil, nil]
-              attachments[idx - 1] = [here, prev_doc]
-            elsif here.kind == 'fence' && here.info != 'error' && steps_by_block.key?(idx - 1)
-              prev_data, = attachments[idx - 1] || [nil, nil]
-              attachments[idx - 1] = [
-                prev_data,
-                DocString.new(content: here.body, content_type: here.info, span: here.body_span)
-              ]
-            end
+        # Error fence detection.
+        error_fence = ex.body.find { |b| b.kind == 'fence' && b.info == 'error' }
+
+        # Pass 2: attach trailing table / fence to the last step of a block.
+        attachments = {}
+        (1...ex.body.length).each do |idx|
+          here = ex.body[idx]
+          if here.kind == 'table' && steps_by_block.key?(idx - 1)
+            _prev_data, prev_doc = attachments[idx - 1] || [nil, nil]
+            attachments[idx - 1] = [here, prev_doc]
+          elsif here.kind == 'fence' && here.info != 'error' && steps_by_block.key?(idx - 1)
+            prev_data, = attachments[idx - 1] || [nil, nil]
+            attachments[idx - 1] = [
+              prev_data,
+              DocString.new(content: here.body, content_type: here.info, span: here.body_span)
+            ]
           end
+        end
 
-          # Pass 3: rebuild the final step list, applying attachments.
-          final_steps = []
-          (0...ex.body.length).each do |idx|
-            block_steps = steps_by_block[idx] || []
-            attach = attachments[idx]
-            block_steps.each_with_index do |step, s_idx|
-              if s_idx == block_steps.length - 1 && attach
-                data_table, doc_string = attach
-                final_steps << PlannedStep.new(
-                  text: step.text, match_span: step.match_span, param_spans: step.param_spans,
-                  step_def: step.step_def, args: step.args, formats: step.formats,
-                  data_table: data_table, doc_string: doc_string
-                )
-              else
-                final_steps << step
-              end
+        # Pass 3: rebuild the final step list, applying attachments.
+        final_steps = []
+        (0...ex.body.length).each do |idx|
+          block_steps = steps_by_block[idx] || []
+          attach = attachments[idx]
+          block_steps.each_with_index do |step, s_idx|
+            if s_idx == block_steps.length - 1 && attach
+              data_table, doc_string = attach
+              final_steps << PlannedStep.new(
+                text: step.text, match_span: step.match_span, param_spans: step.param_spans,
+                step_def: step.step_def, args: step.args, formats: step.formats,
+                data_table: data_table, doc_string: doc_string
+              )
+            else
+              final_steps << step
             end
           end
+        end
 
-          runnable_steps = had_ambiguous ? [] : final_steps
-
-          diagnostics << Diagnostics.error_fence_without_step(error_fence.span) if error_fence && runnable_steps.empty?
-
-          next if final_steps.empty? && !had_ambiguous
+        runnable_steps = had_ambiguous ? [] : final_steps
 
-          expected_outcome = nil
-          expected_error_message = nil
-          if error_fence
-            expected_outcome = 'fail'
-            msg = error_fence.body.strip
-            expected_error_message = msg unless msg.empty?
-          end
+        diagnostics << Diagnostics.error_fence_without_step(error_fence.span) if error_fence && runnable_steps.empty?
 
-          examples << PlannedExample.new(
-            name: derive_example_name(ex.body),
-            scope_stack: ex.scope_stack,
-            span: ex.span,
-            steps: runnable_steps,
-            expected_outcome: expected_outcome,
-            expected_error_message: expected_error_message
-          )
+        expected_outcome = nil
+        expected_error_message = nil
+        if error_fence
+          expected_outcome = 'fail'
+          msg = error_fence.body.strip
+          expected_error_message = msg unless msg.empty?
         end
 
-        ExecutionPlan.new(var_doc: var_doc, examples: examples, diagnostics: diagnostics)
+        StepsUnit.new(
+          matched: !runnable_steps.empty?,
+          preceded_by_delimiter: ex.preceded_by_delimiter,
+          name: derive_example_name(ex.body),
+          scope_stack: ex.scope_stack,
+          span: ex.span,
+          steps: runnable_steps,
+          expected_outcome: expected_outcome,
+          expected_error_message: expected_error_message
+        )
       end
 
       def plan_block(text, registry)

data/lib/varar/core/registry.rb

@@ -20,11 +20,39 @@ module Varar
     module Registries
       module_function
 
+      # Markdown emphasis, as a built-in {emph} parameter type. Matches the
+      # uniform emphasis notations (bold-italic, bold, italic; `*` and `_`
+      # delimiters), ordered longest-delimiter-first so `**x**` isn't
+      # half-eaten by the `*` branch. Each branch captures the inner text in
+      # its own group, so only the outermost delimiter pair is stripped
+      # (`**_x_**` -> `_x_`). Byte-identical to the TS port's EMPH_REGEXP.
+      EMPH_REGEXP = '\*\*\*([^*]+)\*\*\*|___([^_]+)___|\*\*([^*]+)\*\*|__([^_]+)__|\*([^*]+)\*|_([^_]+)_'
+
       def create_registry
-        Registry.new(
-          steps: [],
-          parameter_types: Cucumber::CucumberExpressions::ParameterTypeRegistry.new,
-          formats: {}
+        seed_builtins(
+          Registry.new(
+            steps: [],
+            parameter_types: Cucumber::CucumberExpressions::ParameterTypeRegistry.new,
+            formats: {}
+          )
+        )
+      end
+
+      # Seed Varar's own built-in parameter types (beyond cucumber-expressions'
+      # int/float/string/word). Shared by every port so specs match
+      # identically. Built-ins are NOT tracked as custom parameter types, so
+      # they never appear in the conformance registry.json projection.
+      def seed_builtins(registry)
+        define_parameter_type(
+          registry,
+          name: 'emph',
+          regexp: EMPH_REGEXP,
+          # Exactly one alternation branch matches, so exactly one group is set.
+          parse: ->(*groups) { groups.find { |g| !g.nil? } || '' },
+          # Emphasis is distinctive notation; don't auto-suggest it in snippets.
+          use_for_snippets: false,
+          # Mismatch display renders the value back in single-asterisk emphasis.
+          format: ->(value) { "*#{value}*" }
         )
       end
 

data/lib/varar/core/structurer.rb

@@ -5,8 +5,12 @@ require 'varar/core/ast'
 
 module Varar
   module Core
-    # Group scanned blocks into Examples, tracking heading scope and orphan
-    # attachments. Port of structurer.ts.
+    # Group scanned blocks into candidate Examples, tracking heading scope and
+    # orphan attachments. This is pure syntax — it does NOT decide where one
+    # example ends and the next begins. Each candidate records
+    # +preceded_by_delimiter+ (a heading or `---` sits before it) and the planner
+    # groups adjacent matching candidates into examples. Port of structurer.ts.
+    # See ADR 0012.
     module Structurer
       module_function
 
@@ -16,6 +20,11 @@ module Varar
         scope_stack = [] # [[level, text], ...]
         last_example_idx = -1
         attachment_open = false
+        # A heading or thematic break seen since the previous candidate — the
+        # next candidate is then delimiter-preceded. Starts true so the first
+        # candidate in the file counts as delimiter-preceded (nothing to merge
+        # into).
+        delimiter_pending = true
 
         blocks.each do |block|
           case block.kind
@@ -24,35 +33,18 @@ module Varar
             scope_stack.pop while !scope_stack.empty? && scope_stack.last[0] >= block.level
             scope_stack << [block.level, block.text]
             attachment_open = false
+            delimiter_pending = true
 
           when 'paragraph', 'list_item', 'blockquote'
-            # Merge a block into the previous example when that example's last
-            # block is an attachment (table/fence) with no blank line between.
-            if attachment_open && last_example_idx >= 0
-              prev = examples[last_example_idx]
-              prev_last = prev.body.last
-              last_is_attachment = !prev_last.nil? && %w[table fence].include?(prev_last.kind)
-              if last_is_attachment
-                between = Offsets.utf16_slice(source, prev.span.end_offset, block.span.start_offset)
-                unless between.match?(/\n\s*\n/)
-                  new_span = Offsets.span_from_offsets(source, prev.span.start_offset, block.span.end_offset)
-                  examples[last_example_idx] = Example.new(
-                    scope_stack: prev.scope_stack,
-                    span: new_span,
-                    body: prev.body + [block]
-                  )
-                  next
-                end
-              end
-            end
-
             examples << Example.new(
               scope_stack: scope_stack.map { |(_, text)| text },
               span: block.span,
-              body: [block]
+              body: [block],
+              preceded_by_delimiter: delimiter_pending
             )
             last_example_idx = examples.length - 1
             attachment_open = true
+            delimiter_pending = false
 
           when 'table', 'fence'
             if attachment_open && last_example_idx >= 0
@@ -61,7 +53,8 @@ module Varar
               examples[last_example_idx] = Example.new(
                 scope_stack: prev.scope_stack,
                 span: new_span,
-                body: prev.body + [block]
+                body: prev.body + [block],
+                preceded_by_delimiter: prev.preceded_by_delimiter
               )
             else
               orphan_attachments << block
@@ -69,6 +62,7 @@ module Varar
 
           when 'thematic_break'
             attachment_open = false
+            delimiter_pending = true
           end
         end
 

data/lib/varar/core.rb

@@ -4,7 +4,7 @@ module Varar
   # The pure functional core: parse, match, plan, execute, diffs, drift, and
   # the conformance projections. No filesystem, network, globals, or time.
   module Core
-    VERSION = '0.6.1'
+    VERSION = '0.7.0'
   end
 end
 
@@ -21,7 +21,6 @@ require 'varar/core/diagnostics'
 require 'varar/core/cell_diff'
 require 'varar/core/matcher'
 require 'varar/core/plan'
-require 'varar/core/deep_freeze'
 require 'varar/core/doc_string_diff'
 require 'varar/core/param_diff'
 require 'varar/core/failure_anchor'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: varar-core
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Aslak Hellesøy
@@ -24,7 +24,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 20.0.0
 description: The pure functional pipeline (parse, match, plan, execute, drift) behind
-  Vár.
+  Varar.
 email:
 - aslak@oselvar.com
 executables: []
@@ -36,7 +36,6 @@ files:
 - lib/varar/core/canonical_json.rb
 - lib/varar/core/cell_diff.rb
 - lib/varar/core/conformance.rb
-- lib/varar/core/deep_freeze.rb
 - lib/varar/core/diagnostics.rb
 - lib/varar/core/doc_string_diff.rb
 - lib/varar/core/drift.rb

data/lib/varar/core/deep_freeze.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Varar
-  module Core
-    # Recursively freeze plain Hash/Array so handler code mutating state raises
-    # FrozenError. Other objects (class instances, primitives, nil) pass
-    # through. Assumes acyclic input. Port of deep-freeze.ts.
-    module DeepFreeze
-      module_function
-
-      def deep_freeze(value)
-        case value
-        when Hash
-          value.each_value { |v| deep_freeze(v) }
-          value.freeze
-        when Array
-          value.each { |v| deep_freeze(v) }
-          value.freeze
-        else
-          value
-        end
-      end
-    end
-  end
-end