omoteura-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c9ec9195c34a9aa30eb4cb708dbf72cbaca5ee7b5f6f04a5e78df33c52ae428
+  data.tar.gz: 27841d7cd4cffc527a4270467d33d12e3629b0c85a260a5621d09ec630629811
+SHA512:
+  metadata.gz: 9565e3f5fdf46d9ceb06ff93b9de14c7bba26f40e385c401776725ecaadfdb67c1b7d7e5338096c684a36fb9f2165c06ace31b545bfef33139d6e24134d242bd
+  data.tar.gz: ea41624e44792a929c4429f6a8b4f640b5b6027bd7f28d203c8a2035419ca8c257321697e6eb3750d267e480360227b5681ee4ece9a6dc09197b2f71f14e642d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KAIBYAKU K.K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/exe/omoteura

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Checked before loading anything else, so an editor that finds the system
+# Ruby gets a message it can act on. Not warn, which prints nothing when
+# warnings are off.
+require_relative "../lib/omoteura/minimum_ruby"
+if (message = Omoteura.ruby_too_old_message)
+  $stderr.puts message # standard:disable Style/StderrPuts
+  exit 2
+end
+
+require "omoteura/cli"
+
+exit Omoteura::CLI.new.run(ARGV)

data/lib/omoteura/checker.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # Checks a whole project: every attached diagram must exist and parse,
+  # every omoteura: link in it must resolve, every magic comment must be
+  # valid, and every diagram under diagrams_dir must be attached to code.
+  class Checker
+    # file is relative to the project root. shape names the diagram element
+    # a link problem comes from, as its label or id.
+    Problem = Data.define(:file, :message, :shape)
+
+    Report = Data.define(:problems, :diagram_count, :link_count) do
+      def ok?
+        problems.empty?
+      end
+    end
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+      @project = Project.new(config)
+      @resolver = Resolver.new(config)
+      @link_resolver = LinkResolver.new(config)
+    end
+
+    def run
+      problems = []
+      attachments = @project.code_paths.filter_map do |code_path|
+        @resolver.resolve(code_path)
+      rescue MagicComment::Duplicate, Resolver::InvalidPath => e
+        problems << Problem.new(file: code_path, message: e.message.delete_prefix("#{code_path} "), shape: nil)
+        nil
+      end
+
+      link_count = 0
+      attachments.each do |attachment|
+        if attachment.missing?
+          problems << Problem.new(file: attachment.code_path, message: "attaches #{attachment.diagram_path}, which does not exist", shape: nil)
+          next
+        end
+
+        diagram = load_diagram(attachment.diagram_path, problems) or next
+        diagram.linked_elements.each do |element|
+          link_count += 1
+          result = @link_resolver.resolve(element.link, context_path: attachment.code_path)
+          next unless result.broken?
+
+          problems << Problem.new(file: attachment.diagram_path, message: result.error, shape: element.label || element.id)
+        end
+      end
+
+      problems.concat(unattached_diagrams(attachments))
+      diagram_paths = attachments.reject(&:missing?).map(&:diagram_path).uniq
+      Report.new(problems: problems, diagram_count: diagram_paths.size, link_count: link_count)
+    end
+
+    private
+
+    def load_diagram(diagram_path, problems)
+      Diagram.load(File.join(config.root, diagram_path))
+    rescue Diagram::NotADiagram, Diagram::ParseError => e
+      problems << Problem.new(file: diagram_path, message: e.message.delete_prefix("#{File.join(config.root, diagram_path)} "), shape: nil)
+      nil
+    end
+
+    def unattached_diagrams(attachments)
+      attached = attachments.map(&:diagram_path).to_set
+      diagram_dir = File.join(config.root, config.diagrams_dir)
+      return [] unless Dir.exist?(diagram_dir)
+
+      Dir.glob("**/*.{excalidraw,md}", base: diagram_dir).sort.filter_map do |relative|
+        path = File.join(config.diagrams_dir, relative)
+        next if attached.include?(path) || !Diagram.diagram_file?(File.join(config.root, path))
+
+        message = path.match?(/\.draft\.excalidraw(?:\.md)?\z/) ? "is a draft; copy what you need into the diagram, then delete it" : "is not attached to any code file"
+        Problem.new(file: path, message: message, shape: nil)
+      end
+    end
+  end
+end

data/lib/omoteura/cli.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "omoteura/core"
+
+module Omoteura
+  # The omoteura command. #run returns the exit status: 0 when everything
+  # is fine, 1 when check finds problems or save refuses to write, 2 for
+  # usage or settings errors.
+  class CLI
+    USAGE = <<~TEXT
+      Usage: omoteura <command> [options]
+
+      Commands:
+        check     Report broken omoteura: links and diagrams not attached to code
+        inspect   Print what an editor needs about one code file, as JSON
+        diagram   Print what an editor needs to show one diagram, as JSON
+        coverage  Print which declarations and methods of one file its specs cover, as JSON
+        links     Print the places in one code file a shape can link to, as JSON
+        draft     Draft a diagram from code, as a starting point to draw on
+        save      Save a drawing an editor changed, read as JSON from stdin
+        version   Print the version
+
+      Run "omoteura <command> --help" for a command's options.
+    TEXT
+
+    def initialize(out: $stdout, err: $stderr, input: $stdin)
+      @out = out
+      @err = err
+      @input = input
+    end
+
+    def run(argv)
+      command, *args = argv
+      case command
+      when "check" then check(args)
+      when "inspect" then editor_report(args, "inspect FILE") { |config, results, file| Inspector.new(config, results: results).report(file) }
+      when "diagram" then editor_report(args, "diagram FILE") { |config, results, file| Inspector.new(config, results: results).diagram_report(file) }
+      when "coverage" then editor_report(args, "coverage FILE") { |config, results, file| CoverageReport.new(config, results: results).report(file) }
+      when "links"
+        editor_report(args, "links FILE") do |config, _results, file|
+          code_path = config.relative(file)
+          {version: Inspector::FORMAT_VERSION, code_path: code_path, candidates: LinkCandidates.new(config).for(code_path).map(&:to_h)}
+        end
+      when "draft" then draft(args)
+      when "save" then save(args)
+      when "version", "--version", "-v"
+        @out.puts VERSION
+        0
+      when "help", "--help", "-h"
+        @out.puts USAGE
+        0
+      when nil
+        @err.puts USAGE
+        2
+      else
+        @err.puts "omoteura: unknown command '#{command}'", "", USAGE
+        2
+      end
+    end
+
+    private
+
+    def check(args)
+      options = {root: Dir.pwd, format: "text"}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: omoteura check [options]"
+        o.on("--root DIR", "Project root (default: the current directory)") { |dir| options[:root] = dir }
+        o.on("--format FORMAT", %w[text github], "text, or github for GitHub Actions annotations (default: text)") { |f| options[:format] = f }
+        o.on("-h", "--help", "Show this help") do
+          @out.puts o
+          return 0
+        end
+      end
+      parser.parse!(args)
+
+      report = Checker.new(Config.load(options[:root])).run
+      report.problems.each { |problem| @out.puts format_problem(problem, options[:format]) }
+      @out.puts summary(report)
+      report.ok? ? 0 : 1
+    rescue OptionParser::ParseError, Config::Invalid => e
+      @err.puts "omoteura: #{e.message}"
+      2
+    end
+
+    # The commands editors run: one file in, one line of JSON out.
+    def editor_report(args, usage)
+      options = {root: Dir.pwd, results: TestResults::DEFAULT_PATH}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: omoteura #{usage} [options]"
+        o.on("--root DIR", "Project root (default: the current directory)") { |dir| options[:root] = dir }
+        o.on("--results PATH", "Test results, relative to the root (default: #{TestResults::DEFAULT_PATH})") { |path| options[:results] = path }
+        o.on("-h", "--help", "Show this help") do
+          @out.puts o
+          return 0
+        end
+      end
+      parser.parse!(args)
+      raise OptionParser::InvalidArgument, "expected exactly one FILE" unless args.size == 1
+
+      config = Config.load(options[:root])
+      file = File.expand_path(args.first)
+      raise OptionParser::InvalidArgument, "#{args.first} is not a file" unless File.file?(file)
+      raise OptionParser::InvalidArgument, "#{args.first} is outside #{config.root}" unless config.expand(file)
+
+      results = TestResults.load(File.expand_path(options[:results], config.root))
+      @out.puts JSON.generate(yield(config, results, file))
+      0
+    rescue OptionParser::ParseError, Config::Invalid, TestResults::Invalid => e
+      @err.puts "omoteura: #{e.message}"
+      2
+    end
+
+    def draft(args)
+      options = {root: Dir.pwd, only: Draft::CATEGORIES, out: nil, format: "json", dry_run: false, merge: false, json: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: omoteura draft FILE_OR_GLOB... [options]"
+        o.on("--root DIR", "Project root (default: the current directory)") { |dir| options[:root] = dir }
+        o.on("--out PATH", "Write here instead, relative to the root: a file or a directory") { |path| options[:out] = path }
+        o.on("--format FORMAT", %w[json md], "json for .excalidraw (default), or md for an Obsidian .excalidraw.md") { |f| options[:format] = f }
+        o.on("--only LIST", Array, "For code other than specs, draw only: #{Draft::CATEGORIES.join(", ")}") { |list| options[:only] = list }
+        o.on("--merge", "Add what the file's diagram has no shape for yet, to the right of it") { options[:merge] = true }
+        o.on("--dry-run", "Show what would be written without writing") { options[:dry_run] = true }
+        o.on("--json", "Print the results as one line of JSON, for editors") { options[:json] = true }
+        o.on("-h", "--help", "Show this help") do
+          @out.puts o
+          return 0
+        end
+      end
+      parser.parse!(args)
+      raise OptionParser::InvalidArgument, "expected at least one FILE" if args.empty?
+      unknown = options[:only] - Draft::CATEGORIES
+      raise OptionParser::InvalidArgument, "--only does not know #{unknown.join(", ")}" unless unknown.empty?
+
+      raise OptionParser::InvalidArgument, "--merge adds to the diagram in place, so it takes no --out" if options[:merge] && options[:out]
+
+      config = Config.load(options[:root])
+      paths = draft_paths(args, config)
+      format = (options[:format] == "md") ? :obsidian : :excalidraw
+      out_file = options[:out]&.match?(/\.excalidraw(?:\.md)?\z/)
+      if out_file && !options[:out].end_with?(Draft::EXTENSIONS.fetch(format))
+        raise OptionParser::InvalidArgument, "--out #{options[:out]} does not end in #{Draft::EXTENSIONS.fetch(format)}, as --format #{options[:format]} writes"
+      end
+      if out_file && paths.size > 1
+        raise OptionParser::InvalidArgument, "--out names one file, but #{paths.size} files match"
+      end
+
+      drafter = Draft.new(config, only: options[:only], out: options[:out], format: format)
+      results = paths.map do |path|
+        result = options[:merge] ? drafter.merge(path, dry_run: options[:dry_run]) : drafter.draft(path, dry_run: options[:dry_run])
+        @out.puts draft_line(result, options[:dry_run]) unless options[:json]
+        result
+      end
+      @out.puts JSON.generate(version: Inspector::FORMAT_VERSION, results: results.map { |r| r.to_h.merge(status: r.status.to_s) }) if options[:json]
+      0
+    rescue OptionParser::ParseError, Config::Invalid, Writer::Conflict, Diagram::ParseError, Diagram::NotADiagram, Resolver::InvalidPath, MagicComment::Duplicate => e
+      @err.puts "omoteura: #{e.message}"
+      2
+    end
+
+    # Prints one line of JSON: where the drawing went and the digest of
+    # what was written, or why nothing was.
+    def save(args)
+      options = {root: Dir.pwd, if_unchanged: nil}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: omoteura save FILE [options] < drawing.json"
+        o.on("--root DIR", "Project root (default: the current directory)") { |dir| options[:root] = dir }
+        o.on("--if-unchanged DIGEST", "Refuse to save unless the file's SHA-256 is still DIGEST") { |digest| options[:if_unchanged] = digest }
+        o.on("-h", "--help", "Show this help") do
+          @out.puts o
+          return 0
+        end
+      end
+      parser.parse!(args)
+      raise OptionParser::InvalidArgument, "expected exactly one FILE" unless args.size == 1
+
+      config = Config.load(options[:root])
+      begin
+        result = Writer.new(config).save(File.expand_path(args.first), JSON.parse(@input.read), if_unchanged: options[:if_unchanged])
+        @out.puts JSON.generate(version: Inspector::FORMAT_VERSION, diagram_path: result.diagram_path, digest: result.digest, error: nil, conflict: false)
+        0
+      rescue JSON::ParserError, Writer::Invalid, Writer::Conflict, Diagram::ParseError => e
+        error = e.is_a?(JSON::ParserError) ? "the drawing is not valid JSON" : e.message
+        @out.puts JSON.generate(version: Inspector::FORMAT_VERSION, diagram_path: nil, digest: nil, error: error, conflict: e.is_a?(Writer::Conflict))
+        1
+      end
+    rescue OptionParser::ParseError, Config::Invalid => e
+      @err.puts "omoteura: #{e.message}"
+      2
+    end
+
+    # Arguments are files or globs, relative to the root.
+    def draft_paths(args, config)
+      paths = args.flat_map do |arg|
+        matches = arg.match?(/[*?\[{]/) ? Dir.glob(arg, base: config.root).sort : [arg]
+        raise OptionParser::InvalidArgument, "#{arg} matches no files" if matches.empty?
+
+        matches.map do |path|
+          file = config.expand(path) or raise OptionParser::InvalidArgument, "#{path} is outside #{config.root}"
+          raise OptionParser::InvalidArgument, "#{path} is not a file" unless File.file?(file)
+
+          config.relative(file)
+        end
+      end
+      paths.uniq
+    end
+
+    def draft_line(result, dry_run)
+      shapes = "#{result.shape_count} #{(result.shape_count == 1) ? "shape" : "shapes"}"
+      verb = dry_run ? "would write" : "wrote"
+      case result.status
+      when :written then "#{verb} #{result.diagram_path} (#{shapes})"
+      when :draft
+        "#{verb} #{result.diagram_path} (#{shapes}) beside the diagram #{result.code_path} already has; copy what you need, then delete it"
+      when :exists then "skipped #{result.code_path}: #{result.diagram_path} already exists; delete it to draft again"
+      when :empty then "skipped #{result.code_path}: nothing to draw"
+      when :merged then "#{dry_run ? "would add" : "added"} #{shapes} to #{result.diagram_path}"
+      when :up_to_date then "skipped #{result.code_path}: #{result.diagram_path} already has a shape for everything"
+      when :no_diagram then "skipped #{result.code_path}: no diagram to merge into; draft without --merge"
+      end
+    end
+
+    def format_problem(problem, format)
+      message = problem.shape ? "#{problem.message} (shape \"#{problem.shape}\")" : problem.message
+      if format == "github"
+        "::error file=#{escape_property(problem.file)},title=omoteura check::#{escape_data(message)}"
+      else
+        "#{problem.file}: #{message}"
+      end
+    end
+
+    def summary(report)
+      checked = "Checked #{count(report.diagram_count, "diagram")} and #{count(report.link_count, "link")}"
+      report.ok? ? "#{checked}: no problems." : "#{checked}: #{count(report.problems.size, "problem")}."
+    end
+
+    def count(number, noun)
+      "#{number} #{noun}#{"s" unless number == 1}"
+    end
+
+    # Escaping rules for GitHub Actions workflow commands.
+    def escape_data(text)
+      text.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+    end
+
+    def escape_property(text)
+      escape_data(text).gsub(":", "%3A").gsub(",", "%2C")
+    end
+  end
+end

data/lib/omoteura/config.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "psych"
+
+module Omoteura
+  # Project settings from .omoteura.yml, overridden by .omoteura.local.yml.
+  class Config
+    class Invalid < Error; end
+
+    FILE_NAMES = %w[.omoteura.yml .omoteura.local.yml].freeze
+    DEFAULT_DIAGRAMS_DIR = "ura"
+
+    # coverage_panel is false to turn the editor's coverage panel off.
+    attr_reader :root, :diagrams_dir, :attach, :coverage_panel
+
+    def self.load(root)
+      root = File.expand_path(root)
+      settings = FILE_NAMES.each_with_object({}) do |name, merged|
+        path = File.join(root, name)
+        merge_settings(merged, read_settings(path)) if File.file?(path)
+      end
+      new(root: root, **settings)
+    end
+
+    def self.read_settings(path)
+      settings = Psych.safe_load_file(path) || {}
+      raise Invalid, "#{path} must be a mapping" unless settings.is_a?(Hash)
+
+      settings
+    rescue Psych::Exception => e
+      raise Invalid, "#{path} is not valid YAML: #{e.message}"
+    end
+
+    # The local file adds to and overrides individual attach entries
+    # rather than replacing the whole attach mapping.
+    def self.merge_settings(merged, settings)
+      merged[:diagrams_dir] = settings["diagrams_dir"] if settings.key?("diagrams_dir")
+      merged[:coverage_panel] = settings["coverage_panel"] if settings.key?("coverage_panel")
+      return unless settings.key?("attach")
+
+      attach = settings["attach"]
+      # A non-mapping value is passed through so #initialize reports it.
+      merged[:attach] = attach.is_a?(Hash) ? (merged[:attach] || {}).merge(attach) : attach
+    end
+    private_class_method :read_settings, :merge_settings
+
+    def initialize(root:, diagrams_dir: DEFAULT_DIAGRAMS_DIR, attach: {}, coverage_panel: true)
+      @root = File.expand_path(root)
+      @root_prefix = (@root + File::SEPARATOR).freeze
+      @diagrams_dir = validate_relative_path(diagrams_dir, "diagrams_dir")
+      @attach = validate_attach(attach).freeze
+      raise Invalid, "coverage_panel must be true or false, got #{coverage_panel.inspect}" unless [true, false].include?(coverage_panel)
+
+      @coverage_panel = coverage_panel
+    end
+
+    # Expands a path written relative to the project root. Returns nil when
+    # it points outside the root, so a repository cannot make Omoteura read
+    # arbitrary files on the machine.
+    def expand(relative_path)
+      path = File.expand_path(relative_path, root)
+      inside_root?(path) ? path : nil
+    end
+
+    # The path relative to the root, for paths that #expand accepted.
+    def relative(path)
+      Pathname(path).relative_path_from(Pathname(root)).to_s
+    end
+
+    private
+
+    def inside_root?(path)
+      return false unless path.start_with?(@root_prefix)
+      return true unless File.exist?(path)
+
+      File.realpath(path).start_with?(@real_root_prefix ||= (File.realpath(root) + File::SEPARATOR).freeze)
+    end
+
+    def validate_relative_path(value, key)
+      unless value.is_a?(String) && !value.empty? && !Pathname(value).absolute?
+        raise Invalid, "#{key} must be a relative path, got #{value.inspect}"
+      end
+
+      value
+    end
+
+    def validate_attach(value)
+      raise Invalid, "attach must be a mapping of code paths to diagram paths" unless value.is_a?(Hash)
+
+      value.to_h do |code_path, diagram_path|
+        [validate_relative_path(code_path, "attach key"), validate_relative_path(diagram_path, "attach[#{code_path}]")]
+      end
+    end
+  end
+end

data/lib/omoteura/core/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Omoteura
+  VERSION = "0.1.0"
+end

data/lib/omoteura/core.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "omoteura/core/version"
+
+module Omoteura
+  class Error < StandardError; end
+end
+
+require "omoteura/checker"
+require "omoteura/config"
+require "omoteura/coverage_report"
+require "omoteura/diagram"
+require "omoteura/draft"
+require "omoteura/inspector"
+require "omoteura/link_candidates"
+require "omoteura/link_resolver"
+require "omoteura/magic_comment"
+require "omoteura/minimum_ruby"
+require "omoteura/obsidian"
+require "omoteura/outline"
+require "omoteura/project"
+require "omoteura/resolver"
+require "omoteura/source_index"
+require "omoteura/test_results"
+require "omoteura/writer"

data/lib/omoteura/coverage_report.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # Which of a code file's declarations and public methods its specs cover,
+  # for the editor's coverage panel. Separate from diagrams: it works on any
+  # file and needs none.
+  #
+  # An item counts as covered by an example that names it, in the example's
+  # description or its code: "validates :email" by an example mentioning
+  # email, "def display_name" by one inside describe "#display_name". The
+  # descriptions RSpec generated in the last run, such as those of
+  # shoulda-matchers one-liners, count as well. A method also counts as
+  # covered when its body ran in the last run, if that run measured
+  # coverage.
+  class CoverageReport
+    FORMAT_VERSION = 1
+
+    def initialize(config, results: TestResults.new([]))
+      @config = config
+      @results = results
+    end
+
+    # code_path must be an existing file inside the project root.
+    def report(code_path)
+      file = @config.expand(code_path) or raise ArgumentError, "#{code_path} is outside the project"
+      relative = @config.relative(file)
+      data = {version: FORMAT_VERSION, code_path: relative, enabled: @config.coverage_panel, spec_paths: [], items: []}
+      return data unless @config.coverage_panel
+
+      specs = spec_paths(relative)
+      examples = specs.flat_map { |spec| examples_in(spec) }
+      items = Outline.new(SourceIndex.parse_file(file)).items
+      data.merge(spec_paths: specs, items: items.map { |item| item_data(item, examples, relative) })
+    end
+
+    private
+
+    ONE_LINER = /\A(?:it|specify|example|its)\b(?!\s*["'(])/
+    # label is what the panel shows; description is what names are looked for in.
+    Example = Data.define(:path, :line, :label, :description, :source, :status)
+    private_constant :ONE_LINER, :Example
+
+    # The specs for a file by RSpec's conventions: app/models/user.rb is
+    # tested in spec/models/user_spec.rb, lib/a/b.rb in spec/a/b_spec.rb or
+    # spec/lib/a/b_spec.rb.
+    def spec_paths(code_path)
+      base = code_path.delete_suffix(File.extname(code_path))
+      candidates =
+        if base.start_with?("app/") then ["spec/#{base.delete_prefix("app/")}_spec.rb"]
+        elsif base.start_with?("lib/") then ["spec/#{base.delete_prefix("lib/")}_spec.rb", "spec/#{base}_spec.rb"]
+        else ["spec/#{base}_spec.rb"]
+        end
+      candidates.select { |path| (full = @config.expand(path)) && File.file?(full) }
+    end
+
+    def examples_in(spec_path)
+      source = File.read(File.join(@config.root, spec_path), encoding: Encoding::UTF_8)
+      lines = source.lines
+      recorded = @results.examples.select { |e| e.file_path.delete_prefix("./") == spec_path }.to_h { |e| [e.line_number, e] }
+      index = SourceIndex.new(source)
+      described = index.spec_entries.reject(&:group)
+      # Examples without a description, such as it { is_expected.to ... },
+      # are statements only; their description comes from the last run.
+      lines_taken = described.to_h { |entry| [entry.start_line, true] }
+      undescribed = index.statement_entries.select { |e| e.name.match?(ONE_LINER) && !lines_taken[e.start_line] }
+      (described + undescribed).sort_by(&:start_line).map do |entry|
+        result = recorded[entry.start_line]
+        static = (entry.kind == :spec) ? entry.name : nil
+        description = [static, result&.full_description].compact.uniq.join("\n")
+        Example.new(path: spec_path, line: entry.start_line, label: static || result&.full_description || entry.name, description: description,
+          source: lines[(entry.start_line - 1)...entry.end_line].join, status: result&.status)
+      end
+    end
+
+    def item_data(item, examples, code_path)
+      entry = item.entry
+      patterns = names_of(item).map { |name| patterns_for(name) }
+      covering = examples.select { |example| patterns.any? { |words, code| example.description.match?(words) || example.source.match?(code) } }
+      executed = executed?(item, code_path)
+      {
+        kind: item.kind,
+        name: entry.name,
+        start_line: entry.start_line,
+        end_line: entry.end_line,
+        covered: !covering.empty? || executed == true,
+        executed: executed,
+        examples: covering.map { |e| {path: e.path, line: e.line, description: e.label, status: e.status} }
+      }
+    end
+
+    # Whether a method's body ran: its def line runs when the class loads,
+    # so only the lines after it tell. nil for declarations, which run when
+    # the class loads, and for methods on one line.
+    def executed?(item, code_path)
+      entry = item.entry
+      return nil unless item.kind == "methods" && entry.end_line - entry.start_line >= 2
+
+      @results.executed?(code_path, (entry.start_line + 1)...entry.end_line)
+    end
+
+    # What an example would call the item: the symbols a declaration names,
+    # such as email and name in "validates :email, :name, presence: true",
+    # or a method's name.
+    def names_of(item)
+      return [item.entry.name.delete_prefix("self.")] if item.kind == "methods"
+
+      call = item.entry.name.sub(/\A\S+\s*/, "")
+      symbols = call.scan(/(?<![\w:]):(\w+[?!]?)/).flatten
+      # enum role: { ... }, the older syntax, names its attribute as a key.
+      symbols = call.scan(/\A(\w+):/).flatten if symbols.empty?
+      symbols.reject { |name| name.length < 2 }
+    end
+
+    # The name as a word in an example's description, and in its code.
+    # Underscores may be spaces in a description: "display name" for
+    # display_name. Built once per name, not per example.
+    def patterns_for(name)
+      code = Regexp.escape(name)
+      [/(?<!\w)#{code.gsub("_", "[_ ]")}(?![\w?!])/i, /(?<!\w)#{code}(?![\w?!])/]
+    end
+  end
+end