varar-core 0.5.0

data/lib/varar/core/drift.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'varar/core/hash'
+require 'varar/core/diagnostics'
+require 'varar/core/plan'
+require 'varar/core/canonical_json'
+
+module Varar
+  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 varar.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 varar.lock.json baseline
+    # recorded as an example that now matches no step. Pure, byte-identical to
+    # the TS port so varar.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 varar.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

data/lib/varar/core/execute.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'varar/core/span'
+require 'varar/core/deep_freeze'
+require 'varar/core/cell_diff'
+require 'varar/core/doc_string_diff'
+require 'varar/core/param_diff'
+require 'varar/core/failure_anchor'
+
+module Varar
+  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, replace 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'
+                # Full replacement: the returned Hash IS the next state (deep-frozen).
+                # There is no merge — a return with fewer keys shrinks the state.
+                # nil is a no-op; any other type is a contract violation.
+                unless returned.nil?
+                  unless returned.is_a?(Hash)
+                    raise ReturnShapeError,
+                          'a stimulus must return the complete next state, ' \
+                          'or nothing to leave it unchanged'
+                  end
+
+                  state = DeepFreeze.deep_freeze(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

data/lib/varar/core/failure_anchor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'varar/core/cell_diff'
+require 'varar/core/doc_string_diff'
+
+module Varar
+  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

data/lib/varar/core/hash.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Varar
+  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 varar.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

data/lib/varar/core/matcher.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'varar/core/span'
+
+module Varar
+  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

data/lib/varar/core/param_diff.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'varar/core/cell_diff'
+
+module Varar
+  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

data/lib/varar/core/parse.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'varar/core/scanner'
+require 'varar/core/structurer'
+
+module Varar
+  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