varar-core 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e14558a60af014ad7a1e7edfea61644a415408c5da1e384d6c34d4f191a2743
-  data.tar.gz: f91c617e21f8affcd745676fffba8be6b1ab484ec9c2c4e17b7173d6d07e1733
+  metadata.gz: 76ca7dbd630ae0e9925114d31967993e9a0f366a83844da58778afffaa1bf555
+  data.tar.gz: e37e4f44a2469a038ba6c733b6098249501c6c8bcdbc9e6db84a4d0219872bed
 SHA512:
-  metadata.gz: 4a89ff743d9d00027565cad5933ad28f2bc05af437a773feeac38f9c7c640ee25d548af761852343259afed64654205360e5e2983df9fbd82bc14a1167746013
-  data.tar.gz: 66c9b893012bd279f337db321fbae0262802bf579f627a7d7e0db37ff4183b3ec3112c413af5614481521d61543ca2e634b966d54260032615cf0c97057fd89f
+  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)
 
-    Doc = 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/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'
 
@@ -103,7 +104,8 @@ module Varar
         {
           '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
 
@@ -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(doc, registry, create_context, parameter_types = [])
-        execution = Plan.plan(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)

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/execute.rb

@@ -205,6 +205,10 @@ module Varar
       # 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

@@ -29,7 +29,8 @@ module Varar
           message: error.message,
           stack: render_stack(error),
           cells: failing_cells(error),
-          anchor: anchor && AnchorRange.new(from: anchor.start_offset, to: anchor.end_offset)
+          anchor: anchor && AnchorRange.new(from: anchor.start_offset, to: anchor.end_offset),
+          doc_path: FailureAnchor.attached_doc_path(error)
         )
       end
 

data/lib/varar/core/failure_anchor.rb

@@ -18,6 +18,7 @@ module Varar
       # 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
@@ -41,6 +42,22 @@ module Varar
 
         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/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
@@ -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(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 = doc.examples.map { |ex| plan_candidate(ex, 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
@@ -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
@@ -92,12 +142,74 @@ module Varar
         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
@@ -125,6 +237,17 @@ module Varar
       # Plan a single candidate paragraph (plus attached tables/fences) in
       # isolation. Emits ambiguity / error-fence diagnostics into +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 = {}
 
@@ -161,6 +284,7 @@ module Varar
               text: Offsets.utf16_slice(block.text, hit.match_start, hit.match_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
@@ -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/result.rb

@@ -21,8 +21,11 @@ module Varar
     # 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.
-    ExampleFailure = Data.define(:line, :message, :stack, :cells, :anchor) do
-      def initialize(line:, message:, stack:, cells: nil, anchor: nil)
+    # `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
@@ -39,7 +42,15 @@ module Varar
     # 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.
-    OathResults = Data.define(:version, :oath_path, :source_hash, :examples)
+    # 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.
     #
@@ -51,12 +62,16 @@ module Varar
       module_function
 
       def to_wire(results)
-        {
+        out = {
           'version' => results.version,
           'oathPath' => results.oath_path,
-          'sourceHash' => results.source_hash,
-          'examples' => results.examples.map { |e| example_to_wire(e) }
+          '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)
@@ -71,6 +86,7 @@ module Varar
           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

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
 
@@ -70,7 +72,8 @@ module Varar
           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.8.0'
+    VERSION = '0.8.1'
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: varar-core
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Aslak Hellesøy
@@ -47,6 +47,7 @@ files:
 - 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