varar-core 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c4b264453e49d1ef78d963222adc03b1a5451be6174115ce1f3d71f782557a7
+  data.tar.gz: bd3e11377f8cd5d7d4daaaf98e1f1e99d7219191d19c079c0a2db81bd17ebf9b
+SHA512:
+  metadata.gz: 40ede418f6ce40e216645671e9924781f087fd93e80c767f4bc19b04b89465d582c5c095a232130aac2ebb059d012936f2a8c4ca4a6ffc2bdbafaf6495ec8844
+  data.tar.gz: 66c49ff6cb8e61cda3ec6663b0000c9f189498ab02290c2a925fd9579aced637decfe18ec11fbda1ab55f03a1a4dd099206f391aa6085b1587cce989287b1b79

data/lib/varar/core/ast.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'varar/core/span'
+
+module Varar
+  module Core
+    # Maps a block-text offset to its source offset. Block text is the raw
+    # source minus BLOCK markers only (list bullets, blockquote `>` prefixes);
+    # inline markup is never stripped. A paragraph/list item has a single
+    # entry; a blockquote one entry per quoted line.
+    SegmentOffset = Data.define(:text_offset, :source_offset)
+
+    Heading = Data.define(:level, :text, :span) do
+      def kind = 'heading'
+    end
+
+    Paragraph = Data.define(:text, :span, :segment_map) do
+      def kind = 'paragraph'
+    end
+
+    ListItem = Data.define(:text, :span, :segment_map, :ordered, :marker_span) do
+      def kind = 'list_item'
+    end
+
+    Blockquote = Data.define(:text, :span, :segment_map) do
+      def kind = 'blockquote'
+    end
+
+    Row = Data.define(:cells, :cell_spans, :span)
+
+    Table = Data.define(:span, :header, :rows) do
+      def kind = 'table'
+    end
+
+    Fence = Data.define(:span, :info, :body, :body_span) do
+      def kind = 'fence'
+    end
+
+    ThematicBreak = Data.define(:span) do
+      def kind = 'thematic_break'
+    end
+
+    Example = Data.define(:scope_stack, :span, :body)
+
+    VarDoc = Data.define(:path, :source, :examples, :orphan_attachments)
+  end
+end

data/lib/varar/core/canonical_json.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Varar
+  module Core
+    # JSON serializers byte-for-byte compatible with JS `JSON.stringify(v, null, 2)`:
+    # 2-space indent, LF, trailing newline, non-ASCII raw, empty containers as
+    # {}/[]. `canonical_stringify` recursively sorts object keys (the goldens);
+    # `ordered_stringify` preserves insertion order (varar.lock.json).
+    #
+    # The container layout is hand-rolled because Ruby's JSON.pretty_generate
+    # renders empty arrays/objects as "[\n\n]". Scalar encoding is delegated to
+    # the stdlib, which matches JS (escapes " \ control chars, keeps non-ASCII raw).
+    module CanonicalJson
+      module_function
+
+      def canonical_stringify(value)
+        "#{encode(value, '', sort_keys: true)}\n"
+      end
+
+      def ordered_stringify(value)
+        "#{encode(value, '', sort_keys: false)}\n"
+      end
+
+      def encode(value, indent, sort_keys:)
+        case value
+        when Hash
+          return '{}' if value.empty?
+
+          keys = sort_keys ? value.keys.sort : value.keys
+          inner = "#{indent}  "
+          items = keys.map { |key| "#{inner}#{key.to_s.to_json}: #{encode(value[key], inner, sort_keys: sort_keys)}" }
+          "{\n#{items.join(",\n")}\n#{indent}}"
+        when Array
+          return '[]' if value.empty?
+
+          inner = "#{indent}  "
+          items = value.map { |element| "#{inner}#{encode(element, inner, sort_keys: sort_keys)}" }
+          "[\n#{items.join(",\n")}\n#{indent}]"
+        else
+          value.to_json
+        end
+      end
+    end
+  end
+end

data/lib/varar/core/cell_diff.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Varar
+  module Core
+    # 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.
+    # expected_value/actual_value/formatted are adapter-facing, never serialized.
+    CellDiff = Data.define(:column, :span, :expected, :actual, :ok,
+                           :expected_value, :actual_value, :formatted) do
+      def initialize(column:, span:, expected:, actual:, ok:,
+                     expected_value: nil, actual_value: nil, formatted: false)
+        super
+      end
+    end
+
+    # 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.
+    class CellMismatchError < StandardError
+      attr_reader :cells
+
+      def initialize(cells)
+        @cells = cells
+        super(cells.map { |c| "#{c.column}: expected #{c.expected} but was #{c.actual}" }.join('; '))
+      end
+    end
+
+    # Pure comparison of row/table step returns against the authored cells.
+    # Port of cell-diff.ts.
+    module CellDiffs
+      module_function
+
+      # Display rules 2-4 of the mismatch-rendering chain (rule 1, the
+      # parameter type's `format`, is applied in param_diff). A string renders
+      # as-is, other primitives via to_s, anything else via inspect. The
+      # inspect fallback is port-native and deliberately outside conformance.
+      def render_cell_value(value)
+        return value if value.is_a?(String)
+        return value.to_s if value.nil? || value == true || value == false ||
+                             value.is_a?(Integer) || value.is_a?(Float)
+
+        value.inspect
+      end
+
+      # Compare a row step's returned Hash against the row's cells. Only columns
+      # present on +returned+ are checked; a non-Hash return checks nothing.
+      def compare_row(returned, checks)
+        return [] unless returned.is_a?(Hash)
+
+        checks.filter_map do |check|
+          next unless returned.key?(check.column)
+
+          actual = render_cell_value(returned[check.column])
+          CellDiff.new(column: check.column, span: check.span, expected: check.value,
+                       actual: actual, ok: actual == check.value)
+        end
+      end
+
+      # Compare a whole-table step's returned table against the input table.
+      # +returned+: nil (no checks), Array of Arrays (positional), or Array of
+      # Hashes (keyed by header). Cells compare as exact strings.
+      def compare_table(returned, input_table)
+        return [] if returned.nil?
+        raise ReturnShapeError, "expected a table (array of rows), got #{returned.class}" unless returned.is_a?(Array)
+
+        columns = input_table.header.cells
+        data_rows = input_table.rows
+        if returned.length != data_rows.length
+          raise ReturnShapeError, "expected #{data_rows.length} row(s), got #{returned.length}"
+        end
+
+        all_arrays = returned.all?(Array)
+        all_records = returned.all?(Hash)
+        raise ReturnShapeError, 'table rows must be all arrays or all objects' if !all_arrays && !all_records
+
+        diffs = []
+        data_rows.each_with_index do |row, i|
+          ret = returned[i]
+          if all_arrays && ret.length != columns.length
+            raise ReturnShapeError, "row #{i}: expected #{columns.length} column(s), got #{ret.length}"
+          end
+
+          columns.each_with_index do |column, j|
+            if all_arrays
+              actual_value = ret[j]
+            else
+              raise ReturnShapeError, "row #{i}: missing column \"#{column}\"" unless ret.key?(column)
+
+              actual_value = ret[column]
+            end
+            expected = j < row.cells.length ? row.cells[j] : ''
+            actual = render_cell_value(actual_value)
+            span = j < row.cell_spans.length ? row.cell_spans[j] : row.span
+            diffs << CellDiff.new(column: column, span: span, expected: expected, actual: actual,
+                                  ok: actual == expected)
+          end
+        end
+        diffs
+      end
+    end
+  end
+end

data/lib/varar/core/conformance.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'varar/core/ast'
+require 'varar/core/plan'
+require 'varar/core/execute'
+require 'varar/core/failure_anchor'
+
+module Varar
+  module Core
+    # Projections from the internal pipeline values to the camelCase wire
+    # dicts compared against golden/*.json. Port of conformance.ts. (var-doc
+    # stage; registry/plan/trace projections are added in later stages.)
+    module Conformance
+      module_function
+
+      def span_hash(span)
+        {
+          'startOffset' => span.start_offset,
+          'endOffset' => span.end_offset,
+          'startLine' => span.start_line,
+          'startCol' => span.start_col,
+          'endLine' => span.end_line,
+          'endCol' => span.end_col
+        }
+      end
+
+      def segment_hash(segment_offset)
+        {
+          'textOffset' => segment_offset.text_offset,
+          'sourceOffset' => segment_offset.source_offset
+        }
+      end
+
+      def row_hash(row)
+        {
+          'cells' => row.cells,
+          'cellSpans' => row.cell_spans.map { |cs| span_hash(cs) },
+          'span' => span_hash(row.span)
+        }
+      end
+
+      def block_hash(block)
+        case block.kind
+        when 'paragraph', 'blockquote'
+          {
+            'kind' => block.kind,
+            'text' => block.text,
+            'span' => span_hash(block.span),
+            'segmentMap' => block.segment_map.map { |so| segment_hash(so) }
+          }
+        when 'heading'
+          {
+            'kind' => block.kind,
+            'level' => block.level,
+            'text' => block.text,
+            'span' => span_hash(block.span)
+          }
+        when 'list_item'
+          {
+            'kind' => block.kind,
+            'text' => block.text,
+            'span' => span_hash(block.span),
+            'segmentMap' => block.segment_map.map { |so| segment_hash(so) },
+            'ordered' => block.ordered,
+            'markerSpan' => span_hash(block.marker_span)
+          }
+        when 'table'
+          {
+            'kind' => block.kind,
+            'span' => span_hash(block.span),
+            'header' => row_hash(block.header),
+            'rows' => block.rows.map { |r| row_hash(r) }
+          }
+        when 'fence'
+          {
+            'kind' => block.kind,
+            'span' => span_hash(block.span),
+            'info' => block.info,
+            'body' => block.body,
+            'bodySpan' => span_hash(block.body_span)
+          }
+        when 'thematic_break'
+          {
+            'kind' => block.kind,
+            'span' => span_hash(block.span)
+          }
+        else
+          raise "Unknown block kind: #{block.kind}"
+        end
+      end
+
+      def example_hash(example)
+        {
+          'scopeStack' => example.scope_stack,
+          'span' => span_hash(example.span),
+          'body' => example.body.map { |b| block_hash(b) }
+        }
+      end
+
+      # Project a VarDoc to the wire dict for the var-doc artifact.
+      def to_var_doc_artifact(doc)
+        {
+          'path' => doc.path,
+          'examples' => doc.examples.map { |ex| example_hash(ex) },
+          'orphanAttachments' => doc.orphan_attachments.map { |b| block_hash(b) }
+        }
+      end
+
+      # Parameter-type names in source order from a compiled CucumberExpression.
+      # The Ruby gem populates @parameter_types in source order during
+      # construction (it has no public reader), mirroring the TS AST walk.
+      def parameter_type_names(compiled)
+        compiled.instance_variable_get(:@parameter_types).map(&:name)
+      end
+
+      # Project a Registry to the wire dict for the registry artifact.
+      # +parameter_types+ is the custom-type list ({"name","regexp"}).
+      def to_registry_artifact(registry, parameter_types = [])
+        {
+          'steps' => registry.steps.map do |s|
+            { 'expression' => s.expression, 'parameterTypeNames' => parameter_type_names(s.compiled) }
+          end,
+          'parameterTypes' => parameter_types.map do |p|
+            { 'name' => p['name'], 'regexp' => p['regexp'] }
+          end
+        }
+      end
+
+      def doc_string_hash(doc_string)
+        {
+          'content' => doc_string.content,
+          'contentType' => doc_string.content_type,
+          'span' => span_hash(doc_string.span)
+        }
+      end
+
+      # Project an ExecutionPlan to the wire dict for the plan artifact.
+      def to_plan_artifact(plan)
+        source = plan.var_doc.source
+        {
+          'examples' => plan.examples.map { |ex| planned_example_hash(ex, source) },
+          'diagnostics' => plan.diagnostics.map do |d|
+            { 'code' => d.code, 'severity' => d.severity, 'span' => span_hash(d.span) }
+          end
+        }
+      end
+
+      def planned_example_hash(example, source)
+        result = {
+          'name' => example.name,
+          'scopeStack' => example.scope_stack,
+          'span' => span_hash(example.span),
+          'expectedOutcome' => example.expected_outcome || 'pass'
+        }
+        result['expectedErrorMessage'] = example.expected_error_message if example.expected_error_message
+        result['steps'] = example.steps.map { |s| planned_step_hash(s, source) }
+        result
+      end
+
+      def planned_step_hash(step, source)
+        step_names = parameter_type_names(step.step_def.compiled)
+        result = {
+          'text' => step.text,
+          'matchSpan' => span_hash(step.match_span),
+          'paramSpans' => step.param_spans.map { |s| span_hash(s) },
+          'matchedExpression' => step.step_def.expression,
+          'args' => step.param_spans.each_with_index.map do |s, i|
+            {
+              'value' => Offsets.utf16_slice(source, s.start_offset, s.end_offset),
+              'parameterType' => i < step_names.length ? step_names[i] : nil
+            }
+          end
+        }
+        result['dataTable'] = block_hash(step.data_table) if step.data_table
+        result['docString'] = doc_string_hash(step.doc_string) if step.doc_string
+        result
+      end
+
+      # Return the file stem: "path/to/foo.steps.rb" -> "foo.steps".
+      def file_stem(path)
+        File.basename(path, '.*')
+      end
+
+      # Project an execution error to a FailureArtifact dict. line and anchor
+      # are deterministic source positions (never scraped from a backtrace).
+      def to_failure_artifact(error, match_span)
+        line = match_span.start_line
+        anchor = span_hash(FailureAnchor.failure_anchor(error, match_span))
+        case error
+        when CellMismatchError
+          {
+            'kind' => 'cell-mismatch', 'line' => line, 'anchor' => anchor,
+            'message' => error.message,
+            'cells' => error.cells.reject(&:ok).map do |c|
+              { '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
+          { 'kind' => 'unexpected-pass', 'line' => line, 'anchor' => anchor, 'message' => error.message }
+        else
+          { 'kind' => 'thrown', 'line' => line, 'anchor' => anchor }
+        end
+      end
+
+      # Run all examples and return the four-artifact bundle. Port of runConformance.
+      def run_conformance(var_doc, registry, create_context, parameter_types = [])
+        execution = Plan.plan(var_doc, registry)
+        observed = Hash.new { |h, k| h[k] = [] }
+        observer = ->(o) { observed[o.example_index] << o }
+        queue = Execute.collect_examples(execution, create_context: create_context, observer: observer)
+
+        trace_examples = queue.each_with_index.map do |queued, k|
+          outcome = 'pass'
+          begin
+            queued.run.call
+          rescue StandardError
+            outcome = 'fail'
+          end
+
+          planned = execution.examples[k]
+          obs_list = observed[k]
+          steps = planned.steps.each_with_index.map do |step, i|
+            ordinal = i + 1
+            matches = obs_list.select { |x| x.ordinal == ordinal }
+            observation = matches.find { |m| m.outcome == 'fail' } || matches.last
+            step_outcome = observation ? observation.outcome : 'skipped'
+            step_dict = {
+              'exampleName' => queued.name,
+              'ordinal' => ordinal,
+              'stepText' => step.text,
+              'matchedExpression' => step.step_def.expression,
+              'contextKey' => { 'exampleName' => queued.name,
+                                'stepFile' => file_stem(step.step_def.expression_source_file) },
+              'outcome' => step_outcome
+            }
+            step_dict['failure'] = to_failure_artifact(observation&.error, step.match_span) if step_outcome == 'fail'
+            step_dict
+          end
+
+          { 'name' => queued.name, 'outcome' => outcome, 'steps' => steps }
+        end
+
+        {
+          var_doc: to_var_doc_artifact(var_doc),
+          registry: to_registry_artifact(registry, parameter_types),
+          plan: to_plan_artifact(execution),
+          trace: { 'examples' => trace_examples }
+        }
+      end
+    end
+  end
+end

data/lib/varar/core/deep_freeze.rb

@@ -0,0 +1,25 @@
+# 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

data/lib/varar/core/diagnostics.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Varar
+  module Core
+    # A planning/run diagnostic on the shared rail. code is one of
+    # "ambiguous-match", "error-fence-without-step", "drift". Port of
+    # diagnostics.ts.
+    Diagnostic = Data.define(:code, :severity, :message, :span)
+    Candidate = Data.define(:expression, :source_file, :source_line)
+    AmbiguousInput = Data.define(:text, :span, :candidates)
+
+    module Diagnostics
+      module_function
+
+      def ambiguous_match(input)
+        lines = input.candidates.map do |c|
+          "  '#{c.expression}'    at #{c.source_file}:#{c.source_line}"
+        end.join("\n")
+        Diagnostic.new(
+          severity: 'error',
+          code: 'ambiguous-match',
+          message: "Ambiguous step: \"#{input.text}\"\nMatched by:\n#{lines}",
+          span: input.span
+        )
+      end
+
+      def drift_detected(name, span)
+        Diagnostic.new(
+          severity: 'error',
+          code: 'drift',
+          message: "This paragraph was an example and no longer matches any step (drift): \"#{name}\".\n" \
+                   'Fix the step so it matches again, or accept it as prose (run in update mode).',
+          span: span
+        )
+      end
+
+      def error_fence_without_step(span)
+        Diagnostic.new(
+          severity: 'error',
+          code: 'error-fence-without-step',
+          message: 'This `error` fence marks the example as expected-to-fail, ' \
+                   'but the example has no step to run.',
+          span: span
+        )
+      end
+    end
+  end
+end

data/lib/varar/core/doc_string_diff.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+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
+
+    # 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;
+      # 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)
+      end
+    end
+  end
+end