oselvar-var-core 0.3.2

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'oselvar/var/core/hash'
+require 'oselvar/var/core/diagnostics'
+require 'oselvar/var/core/plan'
+require 'oselvar/var/core/canonical_json'
+
+module Oselvar
+  module Var
+    module Core
+      # One example-producing paragraph, as recorded in the baseline.
+      BaselineExample = Data.define(:name, :line)
+      # The committed baseline for one spec file.
+      SpecBaseline = Data.define(:source_hash, :examples)
+      # The whole var.lock.json: every spec keyed by its POSIX path.
+      VarLock = Data.define(:version, :specs)
+      # A paragraph the baseline says was an example and now matches no step.
+      Drift = Data.define(:name, :line, :span)
+
+      # Spec drift detection: a paragraph the committed var.lock.json baseline
+      # recorded as an example that now matches no step. Pure, byte-identical to
+      # the TS port so var.lock.json is shared across languages. Port of drift.ts.
+      #
+      # BaselineStore is a duck-typed port: #read -> String|nil, #write(contents).
+      module Drifts
+        # A paragraph may be moved anywhere and reworded up to ~half its words
+        # and still be recognized; edit it past this and it reads as remove+add,
+        # not drift. Ported byte-identically.
+        SIMILARITY_THRESHOLD = 0.5
+        TOKEN_RE = /[[:alnum:]]+/
+
+        module_function
+
+        def within?(inner, outer)
+          inner.start_offset >= outer.start_offset && inner.end_offset <= outer.end_offset
+        end
+
+        def live?(candidate_span, plan)
+          plan.examples.any? { |pe| within?(pe.span, candidate_span) }
+        end
+
+        # Lower-cased word tokens (letters/digits) — the unit of similarity.
+        def tokenize(text)
+          text.downcase.scan(TOKEN_RE).to_set
+        end
+
+        # Jaccard overlap |A∩B| / |A∪B|. 1 identical, 0 disjoint; two empty = 1.
+        def similarity(set_a, set_b)
+          return 1.0 if set_a.empty? && set_b.empty?
+
+          intersection = (set_a & set_b).size
+          union = set_a.size + set_b.size - intersection
+          union.zero? ? 0.0 : intersection.to_f / union
+        end
+
+        # The current example-producing paragraphs, in document order.
+        def live_examples(var_doc, plan)
+          var_doc.examples.filter_map do |candidate|
+            next unless live?(candidate.span, plan)
+
+            BaselineExample.new(name: Plan.derive_example_name(candidate.body), line: candidate.span.start_line)
+          end
+        end
+
+        def derive_spec_baseline(source, var_doc, plan)
+          SpecBaseline.new(source_hash: Hash32.hash_source(source), examples: live_examples(var_doc, plan))
+        end
+
+        # Paragraphs the baseline recorded as examples that now match zero steps.
+        # Each re-identified by the most word-similar current paragraph at/above
+        # the threshold (exact name scores 1; ties break toward the nearest line).
+        def detect_drift(baseline, var_doc, plan)
+          return [] if baseline.nil?
+
+          candidates = var_doc.examples
+          tokens = candidates.map { |c| tokenize(Plan.derive_example_name(c.body)) }
+          live = candidates.map { |c| live?(c.span, plan) }
+
+          baseline.examples.filter_map do |b|
+            b_tokens = tokenize(b.name)
+            best_idx = -1
+            best_score = 0.0
+            candidates.each_with_index do |candidate, i|
+              score = similarity(b_tokens, tokens[i])
+              next if score < SIMILARITY_THRESHOLD
+
+              line = candidate.span.start_line
+              best_line = best_idx >= 0 ? candidates[best_idx].span.start_line : 0
+              next unless best_idx.negative? || score > best_score ||
+                          (score == best_score && (line - b.line).abs < (best_line - b.line).abs)
+
+              best_idx = i
+              best_score = score
+            end
+            next if best_idx.negative?
+            next if live[best_idx]
+
+            Drift.new(name: b.name, line: candidates[best_idx].span.start_line, span: candidates[best_idx].span)
+          end
+        end
+
+        def drift_diagnostics(drifts)
+          drifts.map { |d| Diagnostics.drift_detected(d.name, d.span) }
+        end
+
+        # One spec's baseline reconciliation against a BaselineStore. In update
+        # mode, accept all drift (re-record, report nothing); otherwise detect
+        # drift and rewrite the baseline only on a clean run, so an unacknowledged
+        # drift keeps its old entry (and stays red).
+        def reconcile_drift(store, spec_path, source, var_doc, plan, update: false)
+          text = store.read
+          lock = text ? parse_var_lock(text) : nil
+          baseline = lock ? lock.specs[spec_path] : nil
+          drifts = update ? [] : detect_drift(baseline, var_doc, plan)
+          if update || drifts.empty?
+            specs = lock ? lock.specs.dup : {}
+            specs[spec_path] = derive_spec_baseline(source, var_doc, plan)
+            store.write(stringify_var_lock(VarLock.new(version: 1, specs: specs)))
+          end
+          drifts
+        end
+
+        def parse_var_lock(text)
+          parsed = JSON.parse(text)
+          return nil unless parsed.is_a?(::Hash) && parsed['version'] == 1
+
+          specs_raw = parsed['specs']
+          return nil unless specs_raw.is_a?(::Hash)
+
+          specs = {}
+          specs_raw.each do |path, value|
+            baseline = parse_spec_baseline(value)
+            return nil if baseline.nil?
+
+            specs[path] = baseline
+          end
+          VarLock.new(version: 1, specs: specs)
+        rescue JSON::ParserError, TypeError
+          nil
+        end
+
+        def parse_spec_baseline(value)
+          return nil unless value.is_a?(::Hash)
+
+          source_hash = value['sourceHash']
+          examples_raw = value['examples']
+          return nil unless source_hash.is_a?(String) && examples_raw.is_a?(Array)
+
+          examples = []
+          examples_raw.each do |item|
+            parsed = parse_baseline_example(item)
+            return nil if parsed.nil?
+
+            examples << parsed
+          end
+          SpecBaseline.new(source_hash: source_hash, examples: examples)
+        end
+
+        def parse_baseline_example(value)
+          return nil unless value.is_a?(::Hash)
+
+          name = value['name']
+          line = value['line']
+          return nil unless name.is_a?(String) && line.is_a?(Integer)
+
+          BaselineExample.new(name: name, line: line)
+        end
+
+        # Serialize var.lock.json deterministically: spec paths sorted, examples
+        # in document order, insertion-order keys otherwise (version, specs;
+        # sourceHash, examples; name, line) — NOT canonical JSON's key sort.
+        def stringify_var_lock(lock)
+          specs = {}
+          lock.specs.keys.sort.each do |path|
+            baseline = lock.specs[path]
+            specs[path] = {
+              'sourceHash' => baseline.source_hash,
+              'examples' => baseline.examples.map { |e| { 'name' => e.name, 'line' => e.line } }
+            }
+          end
+          CanonicalJson.ordered_stringify({ 'version' => 1, 'specs' => specs })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/span'
+require 'oselvar/var/core/deep_freeze'
+require 'oselvar/var/core/cell_diff'
+require 'oselvar/var/core/doc_string_diff'
+require 'oselvar/var/core/param_diff'
+require 'oselvar/var/core/failure_anchor'
+
+module Oselvar
+  module Var
+    module Core
+      # Raised when an expected-to-fail example passes unexpectedly.
+      class UnexpectedPassError < StandardError
+        def initialize(message = 'expected the example to fail, but it passed')
+          super
+        end
+      end
+
+      # Per-step outcome emitted to the optional observer.
+      StepObservation = Data.define(:example_name, :example_index, :ordinal, :step_file, :outcome, :error) do
+        def initialize(example_name:, example_index:, ordinal:, step_file:, outcome:, error: nil)
+          super
+        end
+      end
+
+      # A named, runnable example returned by collect_examples.
+      QueuedExample = Data.define(:name, :run)
+
+      # Execute an ExecutionPlan: route stimulus/sensor returns, merge immutable
+      # state, compare sensor returns via the diff helpers, invert expected
+      # failures. Handlers are user callbacks (sync). Port of execute.ts.
+      module Execute
+        module_function
+
+        # Collect all examples into an ordered Array of QueuedExamples.
+        def collect_examples(plan, create_context:, observer: nil, reporter: nil)
+          queue = []
+          sink = ->(name, run, _info) { queue << QueuedExample.new(name: name, run: run) }
+          execute_plan(plan, sink: sink, create_context: create_context, observer: observer, reporter: reporter)
+          queue
+        end
+
+        def execute_plan(plan, sink:, create_context:, observer: nil, reporter: nil)
+          plan.diagnostics.each { |d| reporter.call(d) } if reporter
+          create_ctx = create_context || ->(_file) { {} }
+          var_path = plan.var_doc.path
+
+          plan.examples.each_with_index do |ex, example_index|
+            seen_lines = {}
+            ex.steps.each { |s| seen_lines[s.match_span.start_line] = true }
+            info = { lines: seen_lines.keys }
+            sink.call(ex.name, build_run(plan, ex, example_index, create_ctx, observer, var_path), info)
+          end
+        end
+
+        def build_run(plan, ex, example_index, create_ctx, observer, var_path)
+          lambda do
+            state_by_file = {}
+            last_return = nil
+            thrown = nil
+
+            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 = state_by_file[file]
+
+              extra = []
+              if step.data_table
+                extra << ([step.data_table.header.cells] + step.data_table.rows.map(&:cells))
+              elsif step.doc_string
+                extra << step.doc_string.content
+              end
+
+              begin
+                returned = step.step_def.handler.call(state, *step.args, *extra)
+                last_return = returned
+                case step.step_def.kind
+                when 'stimulus'
+                  unless returned.nil?
+                    unless returned.is_a?(Hash)
+                      raise ReturnShapeError,
+                            'a stimulus must return a partial state object or nothing'
+                    end
+
+                    state = DeepFreeze.deep_freeze(state.merge(returned))
+                    state_by_file[file] = state
+                  end
+                when 'sensor'
+                  compare_sensor_return(plan, ex, step, returned, extra) if ex.row_checks.nil? && !returned.nil?
+                else
+                  raise ReturnShapeError, "unknown step kind: #{step.step_def.kind}"
+                end
+              rescue StandardError => e
+                augmented = augment_stack(e, step, var_path)
+                observer&.call(observation(ex, example_index, i + 1, file, 'fail', augmented))
+                thrown = augmented
+                break
+              end
+
+              observer&.call(observation(ex, example_index, i + 1, file, 'pass'))
+            end
+
+            # Header-bound row checks (after all steps).
+            if thrown.nil? && ex.row_checks && !ex.row_checks.empty?
+              bad = CellDiffs.compare_row(last_return, ex.row_checks).reject(&:ok)
+              unless bad.empty?
+                last_step = ex.steps.last
+                augmented = augment_stack(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
+              end
+            end
+
+            # Expected-failure inversion.
+            if ex.expected_outcome == 'fail'
+              if thrown.nil?
+                error = UnexpectedPassError.new
+                last = ex.steps.last
+                raise(last ? augment_stack(error, last, var_path) : error)
+              end
+              raise thrown if ex.expected_error_message && !thrown.message.include?(ex.expected_error_message)
+
+              return # satisfied expected-failure → pass
+            end
+
+            raise thrown if thrown
+          end
+        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.
+        def compare_sensor_return(plan, _ex, step, returned, extra)
+          slot_count = step.args.length + extra.length
+          if slot_count.zero?
+            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 slot_count == 1
+            slots = [returned]
+          else
+            unless returned.is_a?(Array)
+              raise ReturnShapeError,
+                    "a sensor with #{slot_count} parameters must return a list of " \
+                    "#{slot_count} values, got #{returned.class}"
+            end
+            unless returned.length == slot_count
+              raise ReturnShapeError,
+                    "sensor return must have #{slot_count} element(s), got #{returned.length}"
+            end
+
+            slots = returned
+          end
+
+          inline_returned = slots[0...step.args.length]
+          source_texts = step.param_spans.map do |s|
+            Offsets.utf16_slice(plan.var_doc.source, s.start_offset, s.end_offset)
+          end
+          param_diffs = ParamDiff.compare_params(inline_returned, step.args, step.param_spans, source_texts,
+                                                 step.formats).reject(&:ok)
+          raise CellMismatchError, param_diffs unless param_diffs.empty?
+
+          if step.data_table
+            bad = CellDiffs.compare_table(slots[step.args.length], step.data_table).reject(&:ok)
+            raise CellMismatchError, bad unless bad.empty?
+          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?
+          end
+        end
+
+        def observation(ex, example_index, ordinal, file, outcome, error = nil)
+          StepObservation.new(example_name: ex.name, example_index: example_index, ordinal: ordinal,
+                              step_file: file, outcome: outcome, error: error)
+        end
+
+        # In TS this injects a synthetic `at <text> (path:line:col)` frame for
+        # editor navigation; the conformance trace derives the anchor separately
+        # via failure_anchor, so here it is a no-op that returns the error.
+        def augment_stack(error, _step, _var_path)
+          error
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/cell_diff'
+require 'oselvar/var/core/doc_string_diff'
+
+module Oselvar
+  module Var
+    module Core
+      # Where a failure points in the .md source: a mismatch anchors at its first
+      # failing span (cell / doc-string body), anything else at the fallback (the
+      # step's match span). The single source of truth for failure locations,
+      # pinned as failure.anchor in the conformance trace. Port of failure-anchor.ts.
+      module FailureAnchor
+        module_function
+
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Oselvar
+  module Var
+    module Core
+      # FNV-1a (32-bit) change-detector over UTF-16 code units. Not a security
+      # hash: tiny and byte-identical to the TS/Python/JVM ports so var.lock.json
+      # fingerprints match everywhere. The "fnv1a:" prefix namespaces the algorithm.
+      # Port of hash.ts.
+      module Hash32
+        FNV_OFFSET = 0x811c9dc5
+        FNV_PRIME = 0x01000193
+        MASK = 0xffffffff
+
+        module_function
+
+        def hash_source(source)
+          h = FNV_OFFSET
+          data = source.encode('UTF-16LE').bytes
+          (0...data.length).step(2) do |i|
+            unit = data[i] | (data[i + 1] << 8)
+            h = ((h ^ unit) * FNV_PRIME) & MASK
+          end
+          format('fnv1a:%08x', h)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/span'
+
+module Oselvar
+  module Var
+    module Core
+      # UTF-16 start/end of one captured parameter within a sentence.
+      ParamSpan = Data.define(:start, :end)
+      # One successful expression match inside a sentence. Offsets are UTF-16.
+      Hit = Data.define(:expression, :step_def, :match_start, :match_end, :args, :param_spans, :formats) do
+        def initialize(expression:, step_def:, match_start:, match_end:, args:, param_spans:, formats: [])
+          super
+        end
+      end
+      # Two or more hits starting at the same position with equal length.
+      AmbiguityCollision = Data.define(:match_start, :match_end, :candidates)
+      # Tagged result of resolve_hits: kind "ok" (steps) or "ambiguous" (collisions).
+      ResolvedSteps = Data.define(:kind, :steps, :collisions) do
+        def initialize(kind:, steps: [], collisions: [])
+          super
+        end
+      end
+
+      # Cucumber-expression matching. Port of matcher.ts. cucumber-expressions'
+      # regexps are anchored (^...$) and its group offsets are code-point based,
+      # so we strip anchors for substring search and convert offsets to UTF-16.
+      module Matcher
+        module_function
+
+        # A compiled, un-anchored pattern from the step's CucumberExpression.
+        def unanchored_pattern(step)
+          regexp = step.compiled.instance_variable_get(:@tree_regexp).regexp
+          source = regexp.source
+          source = source[1..] if source.start_with?('^')
+          source = source[0...-1] if source.end_with?('$')
+          Regexp.new(source, regexp.options)
+        end
+
+        # Every expression match found anywhere in +sentence+.
+        def find_hits(sentence, registry)
+          hits = []
+          registry.steps.each do |step|
+            pattern = unanchored_pattern(step)
+            pos = 0
+            while pos <= sentence.length
+              m = pattern.match(sentence, pos)
+              break if m.nil?
+
+              matched_text = m[0]
+              arguments = step.compiled.match(matched_text) || []
+              args = arguments.map { |arg| arg.value(nil) }
+              formats = arguments.map { |arg| registry.formats[arg.parameter_type.name] }
+
+              # group.start/.end are code-point offsets within matched_text; add
+              # m.begin(0) for the sentence-absolute code-point index, then to UTF-16.
+              param_spans = arguments.filter_map do |arg|
+                g = arg.group
+                next unless g.start.is_a?(Integer) && g.end.is_a?(Integer)
+
+                ParamSpan.new(
+                  start: Offsets.to_utf16_offset(sentence, m.begin(0) + g.start),
+                  end: Offsets.to_utf16_offset(sentence, m.begin(0) + g.end)
+                )
+              end
+
+              hits << Hit.new(
+                expression: step.expression,
+                step_def: step,
+                match_start: Offsets.to_utf16_offset(sentence, m.begin(0)),
+                match_end: Offsets.to_utf16_offset(sentence, m.end(0)),
+                args: args,
+                param_spans: param_spans,
+                formats: formats
+              )
+
+              pos = matched_text.empty? ? m.begin(0) + 1 : m.end(0)
+            end
+          end
+          hits
+        end
+
+        # Select the best non-overlapping hits, or report ambiguities.
+        def resolve_hits(hits)
+          return ResolvedSteps.new(kind: 'ok') if hits.empty?
+
+          # Stable sort by (match_start asc, length desc); the original index
+          # breaks ties so equal-key order follows registration order (Ruby's
+          # sort_by is not stable, Python's sorted is).
+          sorted = hits.each_with_index.sort_by do |h, i|
+            [h.match_start, -(h.match_end - h.match_start), i]
+          end.map(&:first)
+
+          collisions = []
+          i = 0
+          while i < sorted.length
+            here = sorted[i]
+            here_len = here.match_end - here.match_start
+            tied = [here]
+            j = i + 1
+            while j < sorted.length
+              candidate = sorted[j]
+              if candidate.match_start == here.match_start &&
+                 candidate.match_end - candidate.match_start == here_len
+                tied << candidate
+                j += 1
+              else
+                break
+              end
+            end
+            if tied.length > 1
+              collisions << AmbiguityCollision.new(
+                match_start: here.match_start, match_end: here.match_end, candidates: tied
+              )
+            end
+            i = j
+          end
+
+          return ResolvedSteps.new(kind: 'ambiguous', collisions: collisions) unless collisions.empty?
+
+          steps = []
+          cursor = -1
+          sorted.each do |hit|
+            next if hit.match_start < cursor
+
+            steps << hit
+            cursor = hit.match_end
+          end
+          ResolvedSteps.new(kind: 'ok', steps: steps)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/cell_diff'
+
+module Oselvar
+  module Var
+    module Core
+      # Compare a sensor's returned inline actuals against captured document
+      # values. Port of param-diff.ts.
+      module ParamDiff
+        module_function
+
+        # Render one side of a parameter diff as [text, via_format]. The
+        # parameter type's format wins (document notation), else the shared
+        # string/primitive/inspect chain; a raising formatter falls through.
+        def render_param_value(value, format)
+          if format
+            begin
+              return [format.call(value), true]
+            rescue StandardError
+              # fall through to the native rendering
+            end
+          end
+          [CellDiffs.render_cell_value(value), false]
+        end
+
+        # Compare returned actuals against expected document values. Arrays align
+        # 1:1; structural equality (==) compares by value across references.
+        def compare_params(returned, expected, param_spans, source_texts, formats = nil)
+          expected.each_index.map do |i|
+            ok = returned[i] == expected[i]
+            format = formats && i < formats.length ? formats[i] : nil
+            actual_text, via_format = render_param_value(returned[i], format)
+            expected_text = if i < source_texts.length
+                              source_texts[i]
+                            else
+                              render_param_value(expected[i], format)[0]
+                            end
+            CellDiff.new(
+              column: "arg #{i + 1}",
+              span: param_spans[i],
+              expected: expected_text,
+              actual: actual_text,
+              ok: ok,
+              expected_value: expected[i],
+              actual_value: returned[i],
+              formatted: via_format
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'oselvar/var/core/scanner'
+require 'oselvar/var/core/structurer'
+
+module Oselvar
+  module Var
+    module Core
+      # Parse +source+ into a VarDoc: scan blocks, then group into Examples.
+      # Port of parse.ts.
+      module Parse
+        module_function
+
+        def parse(path, source, plugins = [])
+          Structurer.structure(path, source, Scanner.scan(source, plugins))
+        end
+      end
+    end
+  end
+end