oselvar-var-core 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c98c97c8b2591024987fbb163ba752459045e7fd3b51cb711567909bff8d70bc
+  data.tar.gz: 012bb71e5e6974d00b37df2b3ab2c380c4446d9301bd887b7871ae262847b803
+SHA512:
+  metadata.gz: 8b0b30035ea20fb0a36214099c3c18455024dea9fc8c999a072cdbfed6b16cb14313a5aa3b45cc7c87b979fbc28971698f29aa0e211335f64bd0fe5c51341bf5
+  data.tar.gz: 7bf02659040e7c302225da45c0385f86e12f591212e373eb70ce4d6aa2ab63d4962a4288252d668b817096836b5e696a56896cdb77e042abe7fb42c51d5f36d5

data/lib/oselvar/var/core/ast.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/span'
+
+module Oselvar
+  module Var
+    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
+end

data/lib/oselvar/var/core/canonical_json.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Oselvar
+  module Var
+    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 (var.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
+end

data/lib/oselvar/var/core/cell_diff.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Oselvar
+  module Var
+    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
+end

data/lib/oselvar/var/core/conformance.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/ast'
+require 'oselvar/var/core/plan'
+require 'oselvar/var/core/execute'
+require 'oselvar/var/core/failure_anchor'
+
+module Oselvar
+  module Var
+    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,
+              '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,
+              'diff' => {
+                'expected' => error.diff.expected,
+                'actual' => error.diff.actual,
+                'span' => span_hash(error.diff.span)
+              }
+            }
+          when ReturnShapeError
+            { 'kind' => 'return-shape', 'line' => line, 'anchor' => anchor }
+          when UnexpectedPassError
+            { 'kind' => 'unexpected-pass', 'line' => line, 'anchor' => anchor }
+          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
+end

data/lib/oselvar/var/core/deep_freeze.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Oselvar
+  module Var
+    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
+end

data/lib/oselvar/var/core/diagnostics.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Oselvar
+  module Var
+    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
+end

data/lib/oselvar/var/core/doc_string_diff.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/cell_diff'
+
+module Oselvar
+  module Var
+    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
+end