varar-core 0.6.1 → 0.8.0

data/lib/varar/core/failure_anchor.rb

@@ -12,17 +12,35 @@ module Varar
     module FailureAnchor
       module_function
 
+      # The anchor travels with the raised error, from the executor (which knows
+      # the step) to Failures.to_failure (which only sees the error) — the same
+      # job TS does with a global symbol on the Error. An instance variable on
+      # the exception, so it never shows up in `inspect` output the way an
+      # extra attribute would.
+      ANCHOR_IVAR = :@varar_failure_anchor
+
       def failure_anchor(error, fallback)
         case error
         when CellMismatchError
           failing = error.cells.find { |c| !c.ok }
           failing ? failing.span : fallback
-        when DocStringMismatchError
-          error.diff.span
         else
           fallback
         end
       end
+
+      # Record on the error itself where the failure points.
+      def attach_anchor(error, anchor)
+        error.instance_variable_set(ANCHOR_IVAR, anchor) if error.respond_to?(:instance_variable_set)
+      end
+
+      # The anchor the executor attached, or nil if there is none — then a
+      # renderer only has the failing line to go on.
+      def attached_anchor(error)
+        return nil unless error.respond_to?(:instance_variable_get)
+
+        error.instance_variable_get(ANCHOR_IVAR)
+      end
     end
   end
 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/parse.rb

@@ -5,7 +5,7 @@ require 'varar/core/structurer'
 
 module Varar
   module Core
-    # Parse +source+ into a VarDoc: scan blocks, then group into Examples.
+    # Parse +source+ into a Doc: scan blocks, then group into Examples.
     # Port of parse.ts.
     module Parse
       module_function

data/lib/varar/core/plan.rb

@@ -29,169 +29,246 @@ module Varar
       end
     end
 
-    ExecutionPlan = Data.define(:var_doc, :examples, :diagnostics)
+    ExecutionPlan = Data.define(:doc, :examples, :diagnostics)
 
-    # Produce an ExecutionPlan from a VarDoc + Registry: match step expressions
+    # Produce an ExecutionPlan from a Doc + Registry: match step expressions
     # against every text block, attach trailing tables/fences, detect
     # header-bound tables, and collect diagnostics. Port of plan.ts.
     module Plan
       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 = []
+      def plan(doc, registry)
         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 = doc.examples.map { |ex| plan_candidate(ex, doc, registry, diagnostics) }
+
+        # 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, 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(doc: 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
 
-            next unless !had_ambiguous && !result.steps.empty?
+      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, 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(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(doc.source, block, hit.match_start, hit.match_end),
+              param_spans: hit.param_spans.map { |p| lift_span(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, 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?
+        runnable_steps = had_ambiguous ? [] : final_steps
 
-          next if final_steps.empty? && !had_ambiguous
+        diagnostics << Diagnostics.error_fence_without_step(error_fence.span) if error_fence && runnable_steps.empty?
 
-          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
-
-          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 oaths 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/result.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Varar
+  module Core
+    # Run-result records — port of result.ts / result.rb's siblings in every
+    # other port. The persisted .varar/<oath_path>.json file is a serialized
+    # OathResults, read by the language server to place run diagnostics in the
+    # editor (ADR 0014).
+
+    # One mismatched CELL as a source-offset range plus the runtime value.
+    # `from`/`to` are absolute UTF-16 source offsets; `to` is exclusive.
+    CellFailure = Data.define(:from, :to, :actual)
+
+    # Where a failure points in the source: an offset range, `to` exclusive.
+    # The failing step's match span, or the first mismatched cell's span (the
+    # failure_anchor rule) — what lets a renderer underline the step that
+    # failed rather than the whole line it sits on.
+    AnchorRange = Data.define(:from, :to)
+
+    # The failure payload of a failed ExampleResult. `cells` and `anchor` are
+    # nil when they do not apply, and serialize as absent (not null), so a
+    # reader that predates them still parses the file. `stack` is deliberately
+    # runtime-shaped — no consumer parses it.
+    ExampleFailure = Data.define(:line, :message, :stack, :cells, :anchor) do
+      def initialize(line:, message:, stack:, cells: nil, anchor: nil)
+        super
+      end
+    end
+
+    # The run result for one BDD example. `lines` are the 1-based source lines
+    # of its steps (the editor's line-wash anchors).
+    ExampleResult = Data.define(:name, :status, :lines, :failure) do
+      def initialize(name:, status:, lines:, failure: nil)
+        super
+      end
+    end
+
+    # The persisted run result for one oath file. `oath_path` uses POSIX
+    # separators and is relative to the workspace root; `source_hash` is
+    # Hashing.hash_source over the oath as it was run, so a reader can tell
+    # whether the offsets still apply to the buffer in front of it.
+    OathResults = Data.define(:version, :oath_path, :source_hash, :examples)
+
+    # Projection of OathResults onto the JSON shape of .varar/<oath_path>.json.
+    #
+    # The wire format is the TypeScript one (ADR 0014): camelCase names,
+    # declaration order, and the optional members absent rather than null so a
+    # reader that predates them still parses the file. Pure — writing the file
+    # is the shell's job.
+    module Results
+      module_function
+
+      def to_wire(results)
+        {
+          'version' => results.version,
+          'oathPath' => results.oath_path,
+          'sourceHash' => results.source_hash,
+          'examples' => results.examples.map { |e| example_to_wire(e) }
+        }
+      end
+
+      def example_to_wire(example)
+        out = { 'name' => example.name, 'status' => example.status, 'lines' => example.lines.to_a }
+        out['failure'] = failure_to_wire(example.failure) if example.failure
+        out
+      end
+
+      def failure_to_wire(failure)
+        out = { 'line' => failure.line, 'message' => failure.message, 'stack' => failure.stack }
+        if failure.cells && !failure.cells.empty?
+          out['cells'] = failure.cells.map { |c| { 'from' => c.from, 'to' => c.to, 'actual' => c.actual } }
+        end
+        out['anchor'] = { 'from' => failure.anchor.from, 'to' => failure.anchor.to } if failure.anchor
+        out
+      end
+    end
+  end
+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,10 +62,11 @@ module Varar
 
           when 'thematic_break'
             attachment_open = false
+            delimiter_pending = true
           end
         end
 
-        VarDoc.new(
+        Doc.new(
           path: path,
           source: source,
           examples: examples,