varar-core 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d857a484c127ac8dc313cff7dc855f7924e9b90dd9935b3575e880a4abc5e9c
-  data.tar.gz: becbdbfe8eda5afc06b7506b719fafd3868e1506cec1e484e461766b7b39225a
+  metadata.gz: 76ca7dbd630ae0e9925114d31967993e9a0f366a83844da58778afffaa1bf555
+  data.tar.gz: e37e4f44a2469a038ba6c733b6098249501c6c8bcdbc9e6db84a4d0219872bed
 SHA512:
-  metadata.gz: f1f17d5bf2fef77cc8c8dbb4d0991c72232b08d0fe139f0c60768016c86b2eeeca33e54b66a4098ba1ab5bf15cbb00aa91f0a3e48e9ceadc7c457c630085d62c
-  data.tar.gz: 05404cecafaeca822ede078824c9bfad5d959236ea7c23f00a8b44a9d0ffe4a002ff9363d7c52bc86649d2d3bfd6b353f68c67c1131ac0c867172beac0e0913f
+  metadata.gz: 5e9e258f4c033d489f529ddccb3d460afbae2c064ac58de82bed5f25b166ecc295d3c3537ad257d1a88b06784f8f21e3df26d808c5d36f521c66c3a147af9881
+  data.tar.gz: 9dc4d46d4052654752e5736b1703236e517e95412c193bd7851d1c37d6c2a88e4eea6f77c9aee7617272f769a796eb608d85111d243125b1209227ff95320454

data/lib/varar/core/ast.rb

@@ -46,6 +46,9 @@ module Varar
     # one example. See ADR 0012.
     Example = Data.define(:scope_stack, :span, :body, :preceded_by_delimiter)
 
-    VarDoc = Data.define(:path, :source, :examples, :orphan_attachments)
+    # +headings+ is every heading in the document in source order — the same
+    # Heading values the scanner produced. The planner uses it to tell whether
+    # a reference anchor names one section or several (ADR 0016).
+    Doc = Data.define(:path, :source, :examples, :orphan_attachments, :headings)
   end
 end

data/lib/varar/core/canonical_json.rb

@@ -4,39 +4,39 @@ require 'json'
 
 module Varar
   module Core
-    # JSON serializers byte-for-byte compatible with JS `JSON.stringify(v, null, 2)`:
+    # Writes varar.lock.json the way JS `JSON.stringify(v, null, 2)` does:
     # 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).
+    # {}/[], keys in insertion order.
     #
-    # 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).
+    # A committed, language-shared file, so the layout is hand-rolled rather
+    # than left to JSON.pretty_generate, which renders empty arrays/objects as
+    # "[\n\n]" — a Ruby run would otherwise churn the file against every other
+    # port's. Scalar encoding is delegated to the stdlib, which matches JS
+    # (escapes " \ control chars, keeps non-ASCII raw).
+    #
+    # Conformance goldens are NOT compared through here: a port has to agree
+    # with the goldens' CONTENT, and every spec parses them and compares deep
+    # equality.
     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"
+        "#{encode(value, '')}\n"
       end
 
-      def encode(value, indent, sort_keys:)
+      def encode(value, indent)
         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)}" }
+          items = value.keys.map { |key| "#{inner}#{key.to_s.to_json}: #{encode(value[key], inner)}" }
           "{\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)}" }
+          items = value.map { |element| "#{inner}#{encode(element, inner)}" }
           "[\n#{items.join(",\n")}\n#{indent}]"
         else
           value.to_json

data/lib/varar/core/conformance.rb

@@ -2,6 +2,7 @@
 
 require 'varar/core/ast'
 require 'varar/core/plan'
+require 'varar/core/reference'
 require 'varar/core/execute'
 require 'varar/core/failure_anchor'
 
@@ -98,12 +99,13 @@ module Varar
         }
       end
 
-      # Project a VarDoc to the wire dict for the var-doc artifact.
-      def to_var_doc_artifact(doc)
+      # Project a Doc to the wire dict for the var-doc artifact.
+      def to_doc_artifact(doc)
         {
           'path' => doc.path,
           'examples' => doc.examples.map { |ex| example_hash(ex) },
-          'orphanAttachments' => doc.orphan_attachments.map { |b| block_hash(b) }
+          'orphanAttachments' => doc.orphan_attachments.map { |b| block_hash(b) },
+          'headings' => doc.headings.map { |h| block_hash(h) }
         }
       end
 
@@ -137,7 +139,7 @@ module Varar
 
       # Project an ExecutionPlan to the wire dict for the plan artifact.
       def to_plan_artifact(plan)
-        source = plan.var_doc.source
+        source = plan.doc.source
         {
           'examples' => plan.examples.map { |ex| planned_example_hash(ex, source) },
           'diagnostics' => plan.diagnostics.map do |d|
@@ -158,20 +160,23 @@ module Varar
         result
       end
 
-      def planned_step_hash(step, source)
+      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|
+          'args' => step.param_texts.each_with_index.map do |value, i|
             {
-              'value' => Offsets.utf16_slice(source, s.start_offset, s.end_offset),
+              'value' => value,
               'parameterType' => i < step_names.length ? step_names[i] : nil
             }
           end
         }
+        # Present only on a step a reference block spliced in from another oath
+        # (ADR 0016): the document its spans belong to.
+        result['docPath'] = step.doc_path if step.doc_path
         result['dataTable'] = block_hash(step.data_table) if step.data_table
         result['docString'] = doc_string_hash(step.doc_string) if step.doc_string
         result
@@ -206,8 +211,8 @@ module Varar
       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)
+      def run_conformance(doc, registry, create_context, parameter_types = [], workspace = nil)
+        execution = Plan.plan(doc, registry, workspace || Reference.empty_workspace)
         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)
@@ -244,7 +249,7 @@ module Varar
         end
 
         {
-          var_doc: to_var_doc_artifact(var_doc),
+          doc: to_doc_artifact(doc),
           registry: to_registry_artifact(registry, parameter_types),
           plan: to_plan_artifact(execution),
           trace: { 'examples' => trace_examples }

data/lib/varar/core/diagnostics.rb

@@ -3,8 +3,9 @@
 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.
+    # "ambiguous-match", "error-fence-without-step", "drift",
+    # "reference-not-found", "reference-empty", "reference-cycle",
+    # "ambiguous-anchor". 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)
@@ -43,6 +44,60 @@ module Varar
           span: span
         )
       end
+
+      # A reference block (ADR 0016) points at an oath the workspace does not
+      # hold. Never prose: a link-only block that resolves to nothing has no
+      # other reading, so it fails the run rather than degrading silently.
+      def reference_not_found(text, path, span)
+        Diagnostic.new(
+          severity: 'error',
+          code: 'reference-not-found',
+          message: %(Reference to "#{text}" points at "#{path}", which is not an oath in this ) +
+                   "workspace.\nCheck the path, and that the file is matched by the `docs` globs " \
+                   'in varar.config.json.',
+          span: span
+        )
+      end
+
+      # The referenced document exists but the section contributes no steps — a
+      # mistyped anchor, or a section that is pure prose.
+      def reference_empty(text, path, slug, span)
+        where = slug.empty? ? path : "#{path}##{slug}"
+        Diagnostic.new(
+          severity: 'error',
+          code: 'reference-empty',
+          message: %(Reference to "#{text}" resolves to "#{where}", which contributes no steps.\n) +
+                   'Check the heading the anchor names, and that its section contains a matching ' \
+                   'paragraph.',
+          span: span
+        )
+      end
+
+      # The anchor names more than one heading in the referenced document:
+      # GitHub would disambiguate with a numeric suffix, but a reference that
+      # could mean either section is an error, not a guess (ADR 0016).
+      def ambiguous_anchor(text, path, slug, heading_lines, span)
+        Diagnostic.new(
+          severity: 'error',
+          code: 'ambiguous-anchor',
+          message: "Reference to \"#{text}\" is ambiguous: \"#{path}\" has #{heading_lines.length} headings " \
+                   "with the anchor \"##{slug}\" (lines #{heading_lines.join(', ')}).\n" \
+                   'Rename the headings so each has an anchor of its own.',
+          span: span
+        )
+      end
+
+      # References may nest to any depth (depth is a style question, not a
+      # rule), so a chain that reaches a section already on it must be reported
+      # rather than recursed into.
+      def reference_cycle(chain, span)
+        Diagnostic.new(
+          severity: 'error',
+          code: 'reference-cycle',
+          message: "Reference cycle: #{chain.join(' → ')}.",
+          span: span
+        )
+      end
     end
   end
 end

data/lib/varar/core/drift.rb

@@ -10,14 +10,14 @@ 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)
+    # The committed baseline for one oath file.
+    OathBaseline = Data.define(:source_hash, :examples)
+    # The whole varar.lock.json: every oath keyed by its POSIX path.
+    LockFile = Data.define(:version, :oaths)
     # 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
+    # Oath 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.
     #
@@ -62,25 +62,25 @@ module Varar
       end
 
       # The current example-producing paragraphs, in document order.
-      def live_examples(var_doc, plan)
-        var_doc.examples.filter_map do |candidate|
+      def live_examples(doc, plan)
+        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))
+      def derive_oath_baseline(source, doc, plan)
+        OathBaseline.new(source_hash: Hash32.hash_source(source), examples: live_examples(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)
+      def detect_drift(baseline, doc, plan)
         return [] if baseline.nil?
 
-        candidates = var_doc.examples
+        candidates = doc.examples
         tokens = candidates.map { |c| tokenize(Plan.derive_example_name(c.body)) }
         live = candidates.map { |c| live?(c.span, plan) }
 
@@ -111,43 +111,76 @@ module Varar
         drifts.map { |d| Diagnostics.drift_detected(d.name, d.span) }
       end
 
-      # One spec's baseline reconciliation against a BaselineStore. In update
+      # One oath'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)
+      def reconcile_drift(store, oath_path, source, 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)
+        lock = text ? parse_lock_file(text) : nil
+        baseline = lock ? lock.oaths[oath_path] : nil
+        drifts = update ? [] : detect_drift(baseline, 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)))
+          oaths = lock ? lock.oaths.dup : {}
+          oaths[oath_path] = derive_oath_baseline(source, doc, plan)
+          store.write(stringify_lock_file(LockFile.new(version: 2, oaths: oaths)))
         end
         drifts
       end
 
-      def parse_var_lock(text)
+      # Drop every baseline whose oath path is not in +keep_paths+ — the entries
+      # left behind when an oath is deleted or moved. Pure counterpart of
+      # parse_lock_file / stringify_lock_file; the caller decides what "still
+      # exists" means.
+      def prune_lock_file(lock, keep_paths)
+        keep = keep_paths.to_a
+        LockFile.new(version: 2, oaths: lock.oaths.slice(*keep))
+      end
+
+      # The whole-lock counterpart of reconcile_drift, run ONCE per run rather
+      # than per oath: reconciliation cannot see paths that no longer exist, so
+      # without this the lock silently accumulates dead entries and stops being
+      # a faithful inventory of the oath set (#70).
+      #
+      # +keep_paths+ MUST be everything the +docs+ globs currently match — never
+      # the set the run happened to execute. Runs are routinely filtered, and
+      # pruning against a filtered set would delete live baselines.
+      #
+      # Removal is still not *gated*: a deleted oath is a different signal from
+      # drift and stays ungated (ADR 0002). This only stops preserving dead
+      # state, and only under +update+. Returns the paths removed (or, without
+      # +update+, the ones that would be).
+      def prune_baselines(store, keep_paths, update: false)
+        text = store.read
+        lock = text ? parse_lock_file(text) : nil
+        return [] unless lock
+
+        keep = keep_paths.to_a
+        stale = lock.oaths.keys.reject { |path| keep.include?(path) }
+        store.write(stringify_lock_file(prune_lock_file(lock, keep))) if update && !stale.empty?
+        stale
+      end
+
+      def parse_lock_file(text)
         parsed = JSON.parse(text)
-        return nil unless parsed.is_a?(::Hash) && parsed['version'] == 1
+        return nil unless parsed.is_a?(::Hash) && parsed['version'] == 2
 
-        specs_raw = parsed['specs']
-        return nil unless specs_raw.is_a?(::Hash)
+        oaths_raw = parsed['oaths']
+        return nil unless oaths_raw.is_a?(::Hash)
 
-        specs = {}
-        specs_raw.each do |path, value|
-          baseline = parse_spec_baseline(value)
+        oaths = {}
+        oaths_raw.each do |path, value|
+          baseline = parse_oath_baseline(value)
           return nil if baseline.nil?
 
-          specs[path] = baseline
+          oaths[path] = baseline
         end
-        VarLock.new(version: 1, specs: specs)
+        LockFile.new(version: 2, oaths: oaths)
       rescue JSON::ParserError, TypeError
         nil
       end
 
-      def parse_spec_baseline(value)
+      def parse_oath_baseline(value)
         return nil unless value.is_a?(::Hash)
 
         source_hash = value['sourceHash']
@@ -161,7 +194,7 @@ module Varar
 
           examples << parsed
         end
-        SpecBaseline.new(source_hash: source_hash, examples: examples)
+        OathBaseline.new(source_hash: source_hash, examples: examples)
       end
 
       def parse_baseline_example(value)
@@ -174,19 +207,19 @@ module Varar
         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;
+      # Serialize varar.lock.json deterministically: oath paths sorted, examples
+      # in document order, insertion-order keys otherwise (version, oaths;
       # 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] = {
+      def stringify_lock_file(lock)
+        oaths = {}
+        lock.oaths.keys.sort.each do |path|
+          baseline = lock.oaths[path]
+          oaths[path] = {
             'sourceHash' => baseline.source_hash,
             'examples' => baseline.examples.map { |e| { 'name' => e.name, 'line' => e.line } }
           }
         end
-        CanonicalJson.ordered_stringify({ 'version' => 1, 'specs' => specs })
+        CanonicalJson.ordered_stringify({ 'version' => 2, 'oaths' => oaths })
       end
     end
   end

data/lib/varar/core/execute.rb

@@ -42,17 +42,17 @@ module Varar
       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
+        oath_path = plan.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)
+          sink.call(ex.name, build_run(plan, ex, example_index, create_ctx, observer, oath_path), info)
         end
       end
 
-      def build_run(plan, ex, example_index, create_ctx, observer, var_path)
+      def build_run(plan, ex, example_index, create_ctx, observer, oath_path)
         lambda do
           state_by_file = {}
           last_return = nil
@@ -97,7 +97,7 @@ module Varar
                 raise ReturnShapeError, "unknown step kind: #{step.step_def.kind}"
               end
             rescue StandardError => e
-              augmented = augment_stack(e, step, var_path)
+              augmented = augment_stack(e, step, oath_path)
               observer&.call(observation(ex, example_index, i + 1, file, 'fail', augmented))
               thrown = augmented
               break
@@ -117,7 +117,7 @@ module Varar
             bad = CellDiffs.compare_row(last_return, ex.row_checks).reject(&:ok)
             if row_error || !bad.empty?
               last_step = ex.steps.last
-              augmented = augment_stack(row_error || CellMismatchError.new(bad), last_step, var_path)
+              augmented = augment_stack(row_error || CellMismatchError.new(bad), last_step, oath_path)
               observer&.call(observation(ex, example_index, ex.steps.length,
                                          last_step.step_def.expression_source_file, 'fail', augmented))
               thrown = augmented
@@ -129,7 +129,7 @@ module Varar
             if thrown.nil?
               error = UnexpectedPassError.new
               last = ex.steps.last
-              raise(last ? augment_stack(error, last, var_path) : error)
+              raise(last ? augment_stack(error, last, oath_path) : error)
             end
             raise thrown if ex.expected_error_message && !thrown.message.include?(ex.expected_error_message)
 
@@ -177,7 +177,7 @@ module Varar
 
         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)
+          Offsets.utf16_slice(plan.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)
@@ -199,9 +199,16 @@ module Varar
       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)
+      # editor navigation. Ruby has no writable stack text to splice into, so
+      # it records the anchor structurally instead — the failing step's span
+      # (or the first mismatched cell's), which Failures.to_failure reads back
+      # so a renderer underlines the step and not its whole line.
+      def augment_stack(error, step, _var_path)
+        FailureAnchor.attach_anchor(error, FailureAnchor.failure_anchor(error, step.match_span))
+        # A step spliced in by a reference block has spans in the document it
+        # was WRITTEN in, so the payload must name that file — otherwise a
+        # renderer points at the running oath's line N, some other sentence.
+        FailureAnchor.attach_doc_path(error, step.doc_path) if step.doc_path
         error
       end
     end

data/lib/varar/core/failure.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'varar/core/cell_diff'
+require 'varar/core/failure_anchor'
+require 'varar/core/result'
+
+module Varar
+  module Core
+    # Converts a caught step error into the structured ExampleFailure payload —
+    # port of failure.ts / failure.py / Failure.java / failure.rs. Shared by
+    # every producer so failures are byte-identical across ports.
+    #
+    # Where TS scrapes an injected `<path>:line:col` stack frame for the failing
+    # line, Ruby reads it off the anchor the executor attached (the Rust port
+    # does the same): a Ruby backtrace has no synthetic frame to scrape, and the
+    # anchor already carries the line the frame would have named.
+    module Failures
+      module_function
+
+      # A caught step error → the ExampleResult.failure payload.
+      #
+      # `fallback_line` is used when the error carries no anchor, i.e. it never
+      # passed through a step.
+      def to_failure(error, _oath_path, fallback_line)
+        anchor = FailureAnchor.attached_anchor(error)
+
+        ExampleFailure.new(
+          line: anchor ? anchor.start_line : fallback_line,
+          message: error.message,
+          stack: render_stack(error),
+          cells: failing_cells(error),
+          anchor: anchor && AnchorRange.new(from: anchor.start_offset, to: anchor.end_offset),
+          doc_path: FailureAnchor.attached_doc_path(error)
+        )
+      end
+
+      # Every mismatched cell — table, header-bound row, inline capture or doc
+      # string. nil (not an empty array) when the error is not a mismatch, so
+      # the key stays absent in the serialized payload.
+      def failing_cells(error)
+        return nil unless error.is_a?(CellMismatchError)
+
+        failing = error.cells.reject(&:ok).map do |c|
+          CellFailure.new(from: c.span.start_offset, to: c.span.end_offset, actual: c.actual)
+        end
+        failing.empty? ? nil : failing
+      end
+
+      # Display-only: the message plus Ruby's own backtrace. Runtime-shaped by
+      # design (ADR 0014) — no consumer parses it.
+      def render_stack(error)
+        ([error.message] + Array(error.backtrace)).join("\n")
+      end
+    end
+  end
+end

data/lib/varar/core/failure_anchor.rb

@@ -12,6 +12,14 @@ module Varar
     module FailureAnchor
       module_function
 
+      # The anchor travels with the raised error, from the executor (which knows
+      # the step) to Failures.to_failure (which only sees the error) — the same
+      # job TS does with a global symbol on the Error. An instance variable on
+      # the exception, so it never shows up in `inspect` output the way an
+      # extra attribute would.
+      ANCHOR_IVAR = :@varar_failure_anchor
+      DOC_PATH_IVAR = :@varar_failure_doc_path
+
       def failure_anchor(error, fallback)
         case error
         when CellMismatchError
@@ -21,6 +29,35 @@ module Varar
           fallback
         end
       end
+
+      # Record on the error itself where the failure points.
+      def attach_anchor(error, anchor)
+        error.instance_variable_set(ANCHOR_IVAR, anchor) if error.respond_to?(:instance_variable_set)
+      end
+
+      # The anchor the executor attached, or nil if there is none — then a
+      # renderer only has the failing line to go on.
+      def attached_anchor(error)
+        return nil unless error.respond_to?(:instance_variable_get)
+
+        error.instance_variable_get(ANCHOR_IVAR)
+      end
+
+      # The document the anchor's offsets belong to, for a step a reference
+      # block spliced in from another oath (ADR 0016). Travels the same way and
+      # for the same reason as the anchor: the executor knows the step, and
+      # whoever builds the failure payload sees only the error.
+      def attach_doc_path(error, doc_path)
+        return unless error.respond_to?(:instance_variable_set)
+
+        error.instance_variable_set(DOC_PATH_IVAR, doc_path)
+      end
+
+      def attached_doc_path(error)
+        return nil unless error.respond_to?(:instance_variable_get)
+
+        error.instance_variable_get(DOC_PATH_IVAR)
+      end
     end
   end
 end

data/lib/varar/core/parse.rb

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

data/lib/varar/core/plan.rb

@@ -5,16 +5,22 @@ require 'varar/core/ast'
 require 'varar/core/cell_diff'
 require 'varar/core/diagnostics'
 require 'varar/core/matcher'
+require 'varar/core/reference'
 require 'varar/core/sentences'
 
 module Varar
   module Core
     DocString = Data.define(:content, :content_type, :span)
 
-    PlannedStep = Data.define(:text, :match_span, :param_spans, :step_def, :args, :formats, :data_table,
-                              :doc_string) do
-      def initialize(text:, match_span:, param_spans:, step_def:, args:, formats: [], data_table: nil,
-                     doc_string: nil)
+    # param_texts: the notation each parameter matched, sliced at plan time from
+    # the document the step was WRITTEN in — consumers must use it rather than
+    # slicing the running oath's source, because a step a reference block
+    # spliced in (ADR 0016) has spans in a different document.
+    # doc_path: set only on such a spliced step — the document its spans belong to.
+    PlannedStep = Data.define(:text, :match_span, :param_spans, :param_texts, :step_def, :args, :formats,
+                              :data_table, :doc_string, :doc_path) do
+      def initialize(text:, match_span:, param_spans:, step_def:, args:, param_texts: [], formats: [],
+                     data_table: nil, doc_string: nil, doc_path: nil)
         super
       end
     end
@@ -29,9 +35,9 @@ module Varar
       end
     end
 
-    ExecutionPlan = Data.define(:var_doc, :examples, :diagnostics)
+    ExecutionPlan = Data.define(:doc, :examples, :diagnostics)
 
-    # Produce an ExecutionPlan from a VarDoc + Registry: match step expressions
+    # Produce an ExecutionPlan from a Doc + Registry: match step expressions
     # against every text block, attach trailing tables/fences, detect
     # header-bound tables, and collect diagnostics. Port of plan.ts.
     module Plan
@@ -42,21 +48,40 @@ module Varar
       # header-bound table (standalone rows) or a step-bearing candidate the
       # grouping pass may merge into an open example.
       HeaderBoundUnit = Data.define(:rows)
+      # A reference block: its whole text is a link to an oath section, whose
+      # steps are spliced in here (ADR 0016). Never prose, so it does not close
+      # the open example. Its span and scope stack are the referring
+      # document's: the example it opens lives here, not in the section.
+      ReferenceUnit = Data.define(:reference, :preceded_by_delimiter, :span, :scope_stack)
       StepsUnit = Data.define(:matched, :preceded_by_delimiter, :name, :scope_stack, :span, :steps,
                               :expected_outcome, :expected_error_message)
 
       # An open, merging example being built up across adjacent matching
       # candidates in Phase 2.
+      # name_from_reference: true while the name came from a spliced
+      # (referenced) paragraph and is waiting to be replaced by the example's
+      # own first matching paragraph.
       MergedExample = Struct.new(:name, :scope_stack, :start_offset, :end_offset, :steps,
-                                 :expected_outcome, :expected_error_message)
+                                 :expected_outcome, :expected_error_message, :name_from_reference)
 
       module_function
 
-      def plan(var_doc, registry)
+      def plan(doc, registry, workspace)
         diagnostics = []
 
+        # A section another oath references stops being a standalone example:
+        # it runs where it is referenced, not here (ADR 0016).
+        whole_file = Reference.section_key(doc.path, '')
+        consumed = lambda do |ex|
+          workspace.referenced.include?(whole_file) ||
+            ex.scope_stack.any? do |h|
+              workspace.referenced.include?(Reference.section_key(doc.path, Reference.slugify(h)))
+            end
+        end
+
         # Phase 1: plan each candidate paragraph independently into a "unit".
-        units = var_doc.examples.map { |ex| plan_candidate(ex, var_doc, registry, diagnostics) }
+        units = doc.examples.reject { |ex| consumed.call(ex) }
+                   .map { |ex| plan_candidate(ex, doc, registry, diagnostics) }
 
         # Phase 2: group adjacent candidates into examples. A matching candidate
         # continues the open example when no delimiter (heading / `---`) precedes
@@ -66,7 +91,7 @@ module Varar
         examples = []
         open = nil
         flush = lambda do
-          examples << finish_merged(open, var_doc.source) if open
+          examples << finish_merged(open, doc.source) if open
           open = nil
         end
         units.each do |unit|
@@ -75,6 +100,31 @@ module Varar
             examples.concat(unit.rows)
             next
           end
+          if unit.is_a?(ReferenceUnit)
+            # Splice the referenced section's steps in at this position. Only
+            # the reference block itself is subject to the delimiter rule;
+            # everything it splices in belongs to the same sequence, so a
+            # section of several paragraphs stays one example.
+            resolve_reference(unit, doc, registry, workspace, diagnostics, []).each_with_index do |spliced, i|
+              if open && (i.positive? || !unit.preceded_by_delimiter)
+                merge_into(open, spliced, from_reference: true)
+              else
+                flush.call
+                open = start_merged(spliced)
+                # An example that OPENS with a reference is named by its own
+                # first matching paragraph, not by the section it pulls in, and
+                # it sits under THIS document's headings, not the section's.
+                open.name_from_reference = true
+                open.scope_stack = unit.scope_stack
+                open.start_offset = unit.span.start_offset
+              end
+              # A spliced unit's span is in the referenced document; the
+              # example's span is in this one. It ends at the reference block
+              # until a later paragraph of the example's own extends it.
+              open.end_offset = unit.span.end_offset
+            end
+            next
+          end
           unless unit.matched
             # Prose paragraph — a delimiter. Drop it and end the open example.
             flush.call
@@ -89,15 +139,77 @@ module Varar
         end
         flush.call
 
-        ExecutionPlan.new(var_doc: var_doc, examples: examples, diagnostics: diagnostics)
+        ExecutionPlan.new(doc: doc, examples: examples, diagnostics: diagnostics)
+      end
+
+      # Resolve one reference block into the step-bearing units of the section
+      # it names, recursively: a referenced section may itself contain
+      # reference blocks, to any depth (ADR 0016 leaves depth to the author's
+      # judgement). `chain` carries the sections currently being resolved so a
+      # repeat is reported as a cycle instead of recursing forever.
+      def resolve_reference(unit, from_doc, registry, workspace, diagnostics, chain)
+        ref = unit.reference
+        key = Reference.section_key(ref.path, ref.slug)
+        if chain.include?(key)
+          diagnostics << Diagnostics.reference_cycle(chain + [key], unit.span)
+          return []
+        end
+        # A same-file reference resolves against the document being planned,
+        # which is not necessarily in the workspace.
+        target = ref.path == from_doc.path ? from_doc : workspace.docs[ref.path]
+        if target.nil?
+          diagnostics << Diagnostics.reference_not_found(ref.text, ref.path, unit.span)
+          return []
+        end
+        # An anchor that names more than one heading could mean either section:
+        # report it rather than splicing both. A whole-file reference ('' slug)
+        # names no heading, so it is never ambiguous.
+        unless ref.slug.empty?
+          named = target.headings.select { |h| Reference.slugify(h.text) == ref.slug }
+          if named.length > 1
+            diagnostics << Diagnostics.ambiguous_anchor(ref.text, ref.path, ref.slug,
+                                                        named.map { |h| h.span.start_line }, unit.span)
+            return []
+          end
+        end
+        out = []
+        Reference.section_candidates(target, ref.slug).each do |candidate|
+          planned = plan_candidate(candidate, target, registry, diagnostics)
+          if planned.is_a?(ReferenceUnit)
+            out.concat(resolve_reference(planned, target, registry, workspace, diagnostics, chain + [key]))
+            next
+          end
+          # A header-bound table produces one example per row, which a spliced
+          # step list cannot express; an `error` fence declares an outcome for
+          # an example, not for a reusable fragment. Both are left out.
+          next unless planned.is_a?(StepsUnit) && planned.matched
+
+          out << tag_with_doc(planned, target.path, from_doc.path)
+        end
+        diagnostics << Diagnostics.reference_empty(ref.text, ref.path, ref.slug, unit.span) if out.empty?
+        out
+      end
+
+      # Carry the source document's identity on every spliced step, so a failure
+      # in a referenced section reports spans against the file they were written
+      # in rather than the file being run.
+      def tag_with_doc(unit, doc_path, host_path)
+        return unit if doc_path == host_path
+
+        unit.with(steps: unit.steps.map { |step| step.with(doc_path: doc_path) })
       end
 
       def start_merged(unit)
         MergedExample.new(unit.name, unit.scope_stack, unit.span.start_offset, unit.span.end_offset,
-                          unit.steps.dup, unit.expected_outcome, unit.expected_error_message)
+                          unit.steps.dup, unit.expected_outcome, unit.expected_error_message, false)
       end
 
-      def merge_into(open, unit)
+      def merge_into(open, unit, from_reference: false)
+        if open.name_from_reference && !from_reference
+          open.name = unit.name
+          open.scope_stack = unit.scope_stack
+          open.name_from_reference = false
+        end
         open.end_offset = unit.span.end_offset
         open.steps.concat(unit.steps)
         # Any error fence in a merged part marks the whole example
@@ -124,7 +236,18 @@ module Varar
 
       # Plan a single candidate paragraph (plus attached tables/fences) in
       # isolation. Emits ambiguity / error-fence diagnostics into +diagnostics+.
-      def plan_candidate(ex, var_doc, registry, diagnostics)
+      def plan_candidate(ex, doc, registry, diagnostics)
+        # A block whose whole text is a link to an oath section is a reference,
+        # not content: never matched against step definitions, never prose.
+        primary = ex.body.first
+        if primary.respond_to?(:text)
+          ref = Reference.reference_of(primary.text, doc.path)
+          if ref
+            return ReferenceUnit.new(reference: ref, preceded_by_delimiter: ex.preceded_by_delimiter,
+                                     span: ex.span, scope_stack: ex.scope_stack)
+          end
+        end
+
         had_ambiguous = false
         steps_by_block = {}
 
@@ -135,7 +258,7 @@ module Varar
           result = plan_block(block.text, registry)
 
           result.ambiguities.each do |collision|
-            span = lift_span(var_doc.source, block, collision.match_start, collision.match_end)
+            span = lift_span(doc.source, block, collision.match_start, collision.match_end)
             cp_start = Offsets.cp_index_for_utf16(block.text, collision.match_start)
             cp_end = Offsets.cp_index_for_utf16(block.text, collision.match_end)
             diagnostics << Diagnostics.ambiguous_match(
@@ -159,8 +282,9 @@ module Varar
           steps_by_block[idx] = result.steps.map do |hit|
             PlannedStep.new(
               text: Offsets.utf16_slice(block.text, hit.match_start, hit.match_end),
-              match_span: lift_span(var_doc.source, block, hit.match_start, hit.match_end),
-              param_spans: hit.param_spans.map { |p| lift_span(var_doc.source, block, p.start, p.end) },
+              match_span: lift_span(doc.source, block, hit.match_start, hit.match_end),
+              param_spans: hit.param_spans.map { |p| lift_span(doc.source, block, p.start, p.end) },
+              param_texts: hit.param_spans.map { |p| Offsets.utf16_slice(block.text, p.start, p.end) },
               step_def: hit.step_def,
               args: hit.args,
               formats: hit.formats
@@ -169,7 +293,7 @@ module Varar
         end
 
         # Header-bound table detection.
-        bound = had_ambiguous ? nil : detect_header_bound(ex, steps_by_block, var_doc.source)
+        bound = had_ambiguous ? nil : detect_header_bound(ex, steps_by_block, doc.source)
         if bound
           table, binding_step, header_spans = bound
           header_binding = HeaderBinding.new(
@@ -182,14 +306,7 @@ module Varar
             table.header.cells.each_with_index do |cell_name, i|
               row_object[cell_name] = i < row.cells.length ? row.cells[i] : ''
             end
-            row_step = PlannedStep.new(
-              text: binding_step.text,
-              match_span: row.span,
-              param_spans: binding_step.param_spans,
-              step_def: binding_step.step_def,
-              args: binding_step.args + [row_object],
-              formats: binding_step.formats
-            )
+            row_step = binding_step.with(match_span: row.span, args: binding_step.args + [row_object])
             row_checks = table.header.cells.each_with_index.map do |cell_name, i|
               RowCheck.new(
                 column: cell_name,
@@ -236,11 +353,7 @@ module Varar
           block_steps.each_with_index do |step, s_idx|
             if s_idx == block_steps.length - 1 && attach
               data_table, doc_string = attach
-              final_steps << PlannedStep.new(
-                text: step.text, match_span: step.match_span, param_spans: step.param_spans,
-                step_def: step.step_def, args: step.args, formats: step.formats,
-                data_table: data_table, doc_string: doc_string
-              )
+              final_steps << step.with(data_table: data_table, doc_string: doc_string)
             else
               final_steps << step
             end

data/lib/varar/core/reference.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'varar/core/ast'
+
+module Varar
+  module Core
+    # Reuse is a link (ADR 0016). A candidate block whose entire content is a
+    # single Markdown link to an oath section is a REFERENCE BLOCK: it splices
+    # that section's steps in at its own position instead of being prose.
+    #
+    # Everything here is pure text and path arithmetic — no filesystem. The
+    # shell reads the documents; `references` tells it which ones to read, and
+    # `build_workspace` turns the collection into what `plan` needs.
+    module Reference
+      # The referenced oath's path (resolved against the referring doc's own
+      # path), the GFM slug of the heading, and the link's visible text.
+      Ref = Data.define(:path, :slug, :text)
+
+      # What `plan` needs to resolve references: every oath by path, plus which
+      # sections a reference block consumes somewhere in the project. A section
+      # that is referenced stops being a standalone example, so this is
+      # whole-project knowledge — see ADR 0016 on why each runner builds it at
+      # its once-per-run discovery pass.
+      Workspace = Data.define(:docs, :referenced)
+
+      # A candidate is a reference block iff its whole text is one Markdown link
+      # whose target is oath-shaped. Anything else — a link with surrounding
+      # words, a link to https://…, to a .rb file, to a mailto: — is ordinary
+      # content, so existing documents keep their meaning.
+      LINK_ONLY = /\A\[([^\]]*)\]\(\s*([^\s)]+)\s*\)\z/
+      PROTOCOL = /\A[a-z][a-z0-9+.-]*:/i
+
+      module_function
+
+      def reference_of(text, from_path)
+        m = LINK_ONLY.match(text.strip)
+        return nil if m.nil?
+
+        link_text = m[1]
+        target = m[2]
+        return Ref.new(path: from_path, slug: normalize_slug(target[1..]), text: link_text) if target.start_with?('#')
+
+        hash_at = target.index('#')
+        file_part = hash_at.nil? ? target : target[0...hash_at]
+        fragment = hash_at.nil? ? '' : target[(hash_at + 1)..]
+        # Only a relative Markdown path is a reference. A protocol (https:,
+        # mailto:) or any other extension is left alone — remote references are
+        # deliberately out of scope (ADR 0016).
+        return nil unless file_part.end_with?('.md')
+        return nil if PROTOCOL.match?(file_part) || file_part.start_with?('/')
+
+        Ref.new(path: join_posix(dirname_posix(from_path), file_part), slug: normalize_slug(fragment),
+                text: link_text)
+      end
+
+      # GitHub's heading anchors: inline markup dropped, lowercased, spaces to
+      # hyphens, everything else that isn't a word character or hyphen removed.
+      # The same function produces the slug of a heading and normalizes the slug
+      # written in a link, so the two meet in the middle.
+      def slugify(heading_text)
+        stripped = heading_text.gsub(/`([^`]*)`/, '\1')
+                               .gsub(/\*\*([^*]*)\*\*/, '\1')
+                               .gsub(/\*([^*]*)\*/, '\1')
+                               .gsub(/_([^_]*)_/, '\1')
+        normalize_slug(stripped)
+      end
+
+      # One hyphen per space, not per run of them: GitHub leaves the gap where
+      # it dropped punctuation, so "Fees, VAT & rounding" slugs with a double
+      # hyphen.
+      def normalize_slug(str)
+        str.strip.downcase.gsub(/[^[[:word:]] -]/, '').tr(' ', '-')
+      end
+
+      def dirname_posix(path)
+        i = path.rindex('/')
+        i.nil? ? '' : path[0...i]
+      end
+
+      # POSIX path arithmetic on oath paths (always '/'-separated, relative to
+      # the workspace root). The core may not touch the filesystem. A link that
+      # climbs above the root keeps its leading `../`, as the oath-path
+      # convention does for an oath outside the root.
+      def join_posix(dir, rel)
+        segments = dir.empty? ? [] : dir.split('/')
+        rel.split('/').each do |segment|
+          next if segment.empty? || segment == '.'
+
+          if segment != '..'
+            segments << segment
+          elsif !segments.empty? && segments.last != '..'
+            segments.pop
+          else
+            segments << '..'
+          end
+        end
+        segments.join('/')
+      end
+
+      # Every reference block in a document, in document order. The shell uses
+      # this to walk the closure of documents it must read before planning.
+      def references(doc)
+        doc.examples.filter_map do |ex|
+          primary = ex.body.first
+          next nil unless primary.respond_to?(:text)
+
+          reference_of(primary.text, doc.path)
+        end
+      end
+
+      def section_key(path, slug)
+        "#{path}##{slug}"
+      end
+
+      # The workspace with no references at all: what a caller planning a single
+      # document in isolation passes.
+      def empty_workspace
+        Workspace.new(docs: {}, referenced: Set.new)
+      end
+
+      def build_workspace(docs)
+        by_path = docs.to_h { |doc| [doc.path, doc] }
+        referenced = Set.new
+        docs.each do |doc|
+          references(doc).each { |ref| referenced << section_key(ref.path, ref.slug) }
+        end
+        Workspace.new(docs: by_path, referenced: referenced)
+      end
+
+      # The candidates that make up a section: those whose heading chain
+      # contains the slug. A whole-file reference ('' slug) is every candidate.
+      # Section membership follows the document outline exactly — a heading's
+      # section runs until the next heading of the same or higher level, which
+      # is precisely the range over which it stays on the scope stack.
+      def section_candidates(doc, slug)
+        return doc.examples if slug.empty?
+
+        doc.examples.select { |ex| ex.scope_stack.any? { |h| slugify(h) == slug } }
+      end
+    end
+  end
+end

data/lib/varar/core/registry.rb

@@ -39,7 +39,7 @@ module Varar
       end
 
       # Seed Varar's own built-in parameter types (beyond cucumber-expressions'
-      # int/float/string/word). Shared by every port so specs match
+      # int/float/string/word). Shared by every port so oaths match
       # identically. Built-ins are NOT tracked as custom parameter types, so
       # they never appear in the conformance registry.json projection.
       def seed_builtins(registry)

data/lib/varar/core/result.rb

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

data/lib/varar/core/structurer.rb

@@ -17,6 +17,7 @@ module Varar
       def structure(path, source, blocks)
         examples = []
         orphan_attachments = []
+        headings = []
         scope_stack = [] # [[level, text], ...]
         last_example_idx = -1
         attachment_open = false
@@ -32,6 +33,7 @@ module Varar
             # Pop deeper-or-equal-level entries before pushing the new heading.
             scope_stack.pop while !scope_stack.empty? && scope_stack.last[0] >= block.level
             scope_stack << [block.level, block.text]
+            headings << block
             attachment_open = false
             delimiter_pending = true
 
@@ -66,11 +68,12 @@ module Varar
           end
         end
 
-        VarDoc.new(
+        Doc.new(
           path: path,
           source: source,
           examples: examples,
-          orphan_attachments: orphan_attachments
+          orphan_attachments: orphan_attachments,
+          headings: headings
         )
       end
     end

data/lib/varar/core.rb

@@ -4,7 +4,7 @@ module Varar
   # The pure functional core: parse, match, plan, execute, diffs, drift, and
   # the conformance projections. No filesystem, network, globals, or time.
   module Core
-    VERSION = '0.7.0'
+    VERSION = '0.8.1'
   end
 end
 
@@ -24,6 +24,8 @@ require 'varar/core/plan'
 require 'varar/core/doc_string_diff'
 require 'varar/core/param_diff'
 require 'varar/core/failure_anchor'
+require 'varar/core/result'
+require 'varar/core/failure'
 require 'varar/core/execute'
 require 'varar/core/hash'
 require 'varar/core/drift'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: varar-core
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Aslak Hellesøy
@@ -40,13 +40,16 @@ files:
 - lib/varar/core/doc_string_diff.rb
 - lib/varar/core/drift.rb
 - lib/varar/core/execute.rb
+- lib/varar/core/failure.rb
 - lib/varar/core/failure_anchor.rb
 - lib/varar/core/hash.rb
 - lib/varar/core/matcher.rb
 - lib/varar/core/param_diff.rb
 - lib/varar/core/parse.rb
 - lib/varar/core/plan.rb
+- lib/varar/core/reference.rb
 - lib/varar/core/registry.rb
+- lib/varar/core/result.rb
 - lib/varar/core/scanner.rb
 - lib/varar/core/sentences.rb
 - lib/varar/core/span.rb