omoteura-core 0.1.0

data/lib/omoteura/diagram.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "psych"
+require "omoteura/lz_string"
+
+module Omoteura
+  # An Excalidraw drawing read from disk, either a plain .excalidraw file or
+  # an Obsidian Excalidraw plugin markdown file.
+  class Diagram
+    class NotADiagram < Error; end
+
+    class ParseError < Error; end
+
+    LINK_PREFIX = "omoteura:"
+
+    Element = Data.define(:id, :type, :link, :label) do
+      def omoteura_link?
+        link&.start_with?(LINK_PREFIX) || false
+      end
+    end
+
+    FRONTMATTER = /\A---[ \t]*\r?\n(.*?)^---[ \t]*$/m
+    DRAWING_BLOCK = /^\#\#[ \t]+Drawing[ \t]*\r?\n+```(json|compressed-json)[ \t]*\r?\n(.*?)^```/m
+    ELEMENT_LINKS = /^\#\# Element Links\r?\n(.*?)(?=^\#\# Embedded Files|^\#\#? Drawing|\z)/m
+    # The plugin's ids are eight characters.
+    ELEMENT_LINK = /^(.{8}):[ \t]*(.*?)\r?$/
+
+    class << self
+      def load(path)
+        path = path.to_s
+        source = File.read(path, encoding: Encoding::UTF_8)
+        format = detect_format(path, source)
+        raise NotADiagram, "#{path} is not an Excalidraw drawing" unless format
+
+        new(path: path, format: format, data: parse_data(format, source, path), digest: Digest::SHA256.hexdigest(source))
+      end
+
+      def diagram_file?(path)
+        path = path.to_s
+        return false unless File.file?(path)
+
+        !detect_format(path, File.read(path, encoding: Encoding::UTF_8)).nil?
+      end
+
+      private
+
+      # Mirrors the Obsidian plugin: a .md file is a drawing when its
+      # frontmatter has the excalidraw-plugin key, whatever its name.
+      def detect_format(path, source)
+        case File.extname(path)
+        when ".excalidraw" then :excalidraw
+        when ".md" then :obsidian if obsidian_drawing?(source)
+        end
+      end
+
+      def obsidian_drawing?(source)
+        match = FRONTMATTER.match(source) or return false
+        frontmatter = Psych.safe_load(match[1])
+        frontmatter.is_a?(Hash) && frontmatter.key?("excalidraw-plugin")
+      rescue Psych::Exception
+        false
+      end
+
+      def parse_data(format, source, path)
+        json =
+          if format == :excalidraw
+            source
+          else
+            drawing_json(source, path)
+          end
+        data = JSON.parse(json)
+        raise ParseError, "#{path} has no elements list" unless data.is_a?(Hash) && data["elements"].is_a?(Array)
+
+        apply_element_links(source, data["elements"]) if format == :obsidian
+        data
+      rescue JSON::ParserError => e
+        raise ParseError, "#{path} has invalid drawing JSON: #{e.message}"
+      end
+
+      def drawing_json(source, path)
+        match = DRAWING_BLOCK.match(source) or raise ParseError, "#{path} has no ## Drawing block"
+        return match[2] if match[1] == "json"
+
+        LZString.decompress_from_base64(match[2]) or
+          raise ParseError, "#{path} has a corrupt compressed-json block"
+      end
+
+      # As in the plugin, a link listed under Element Links wins over the
+      # one in the drawing, so a link edited in the markdown counts before
+      # Obsidian has saved the drawing again.
+      def apply_element_links(source, elements)
+        section = ELEMENT_LINKS.match(source) or return
+        links = section[1].scan(ELEMENT_LINK).to_h
+        elements.each { |e| e["link"] = links[e["id"]] if e.is_a?(Hash) && links.key?(e["id"]) }
+      end
+    end
+
+    # data is the whole drawing as read, for writing it back; digest is the
+    # SHA-256 of the file as read, for noticing later changes.
+    attr_reader :path, :format, :elements, :digest, :data
+
+    def initialize(path:, format:, data:, digest: nil)
+      @path = path
+      @format = format
+      @data = data
+      @digest = digest
+      @elements = build_elements(data["elements"])
+    end
+
+    # The drawing as Excalidraw itself reads it, for showing it in an editor.
+    def scene
+      {"elements" => @data["elements"], "appState" => @data["appState"] || {}, "files" => @data["files"] || {}}
+    end
+
+    def linked_elements
+      elements.select(&:omoteura_link?)
+    end
+
+    private
+
+    def build_elements(raw_elements)
+      live = raw_elements.select { |e| e.is_a?(Hash) && !e["isDeleted"] }
+      labels = live.each_with_object({}) do |e, acc|
+        acc[e["containerId"]] = text_of(e) if e["type"] == "text" && e["containerId"]
+      end
+
+      live.map do |e|
+        label = (e["type"] == "text") ? text_of(e) : labels[e["id"]]
+        Element.new(id: e["id"], type: e["type"], link: e["link"], label: label)
+      end
+    end
+
+    def text_of(element)
+      element["originalText"] || element["text"]
+    end
+  end
+end

data/lib/omoteura/draft/scene_builder.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Omoteura
+  class Draft
+    # Builds Excalidraw elements laid out in columns: a title, then for each
+    # column a heading and a stack of boxes, each box labelled and linked.
+    # Element ids and seeds derive from the file and the box, so drafting
+    # the same code twice gives the same drawing.
+    class SceneBuilder
+      Box = Data.define(:label, :link)
+      Heading = Data.define(:text, :link)
+      Column = Data.define(:heading, :items)
+
+      INK = "#1e1e1e"
+      FONT_EXCALIFONT = 5
+      BOX_FONT_SIZE = 16
+      HEADING_FONT_SIZE = 20
+      TITLE_FONT_SIZE = 28
+      LINE_HEIGHT = 1.25
+      COLUMN_WIDTH = 280
+      COLUMN_GAP = 60
+      BOX_GAP = 16
+      BOX_PADDING = 14
+      MAX_LABEL_WIDTH = COLUMN_WIDTH - 2 * BOX_PADDING
+      # A word with its trailing space, or one Japanese or Chinese character.
+      WRAP_TOKENS = /[\p{Han}\p{Hiragana}\p{Katakana}ー、。]|[^\p{Han}\p{Hiragana}\p{Katakana}ー、。\s]+\s*|\s+/
+
+      # salt varies the ids, for adding to a drawing that has these already.
+      def initialize(code_path, updated: (Time.now.to_f * 1000).to_i, salt: nil)
+        @code_path = code_path
+        @updated = updated
+        @salt = salt
+        @elements = []
+      end
+
+      # columns are Columns whose items are Boxes, or Headings for a nested
+      # group, in reading order.
+      # origin is where the title's top left corner goes.
+      def build(title, columns, origin: [0, 0])
+        left, top_edge = origin
+        add_text("title", title, x: left, y: top_edge, size: TITLE_FONT_SIZE)
+        top = top_edge + TITLE_FONT_SIZE * LINE_HEIGHT + 32
+        columns.each_with_index do |column, index|
+          x = left + index * (COLUMN_WIDTH + COLUMN_GAP)
+          y = top
+          if column.heading
+            add_text("column #{index}", column.heading.text, x: x, y: y, size: HEADING_FONT_SIZE, link: column.heading.link)
+            y += HEADING_FONT_SIZE * LINE_HEIGHT + BOX_GAP
+          end
+          column.items.each_with_index do |item, row|
+            y += item.is_a?(Heading) ? place_heading(item, index, row, x, y) : place_box(item, index, row, x, y)
+          end
+        end
+        @elements
+      end
+
+      private
+
+      def place_heading(heading, column, row, x, y)
+        add_text("heading #{column}/#{row}", heading.text, x: x, y: y + 8, size: BOX_FONT_SIZE, link: heading.link)
+        8 + BOX_FONT_SIZE * LINE_HEIGHT + BOX_GAP / 2
+      end
+
+      def place_box(box, column, row, x, y)
+        key = "box #{column}/#{row}"
+        lines = wrap(box.label, MAX_LABEL_WIDTH, BOX_FONT_SIZE)
+        text_height = lines.size * BOX_FONT_SIZE * LINE_HEIGHT
+        height = (text_height + 2 * BOX_PADDING).round
+        box_id = id_for(key)
+        label_id = id_for("#{key} label")
+
+        @elements << base(key, type: "rectangle", x: x, y: y, width: COLUMN_WIDTH, height: height).merge(
+          "roundness" => {"type" => 3},
+          "boundElements" => [{"type" => "text", "id" => label_id}],
+          "link" => box.link
+        )
+        text = lines.join("\n")
+        width = lines.map { |line| text_width(line, BOX_FONT_SIZE) }.max
+        @elements << base("#{key} label", type: "text", x: x + (COLUMN_WIDTH - width) / 2.0, y: y + BOX_PADDING,
+          width: width, height: text_height).merge(text_fields(text, BOX_FONT_SIZE, container: box_id))
+        height + BOX_GAP
+      end
+
+      def add_text(key, text, x:, y:, size:, link: nil)
+        width = text.lines.map { |line| text_width(line.chomp, size) }.max
+        @elements << base(key, type: "text", x: x, y: y, width: width, height: size * LINE_HEIGHT)
+          .merge(text_fields(text, size, container: nil))
+          .merge("link" => link)
+      end
+
+      def text_fields(text, size, container:)
+        {
+          "text" => text,
+          "originalText" => text,
+          "fontSize" => size,
+          "fontFamily" => FONT_EXCALIFONT,
+          "textAlign" => container ? "center" : "left",
+          "verticalAlign" => container ? "middle" : "top",
+          "containerId" => container,
+          "autoResize" => true,
+          "lineHeight" => LINE_HEIGHT
+        }
+      end
+
+      def base(key, type:, x:, y:, width:, height:)
+        {
+          "id" => id_for(key),
+          "type" => type,
+          "x" => x,
+          "y" => y,
+          "width" => width,
+          "height" => height,
+          "angle" => 0,
+          "strokeColor" => INK,
+          "backgroundColor" => "transparent",
+          "fillStyle" => "solid",
+          "strokeWidth" => 2,
+          "strokeStyle" => "solid",
+          "roughness" => 1,
+          "opacity" => 100,
+          "groupIds" => [],
+          "frameId" => nil,
+          "index" => nil,
+          "roundness" => nil,
+          "seed" => seed_for(key),
+          "version" => 1,
+          "versionNonce" => seed_for("#{key} nonce"),
+          "isDeleted" => false,
+          "boundElements" => nil,
+          "updated" => @updated,
+          "link" => nil,
+          "locked" => false
+        }
+      end
+
+      # Eight characters, as the Obsidian Excalidraw plugin expects.
+      def id_for(key)
+        digest(key)[0, 8]
+      end
+
+      def seed_for(key)
+        digest(key)[0, 8].to_i(16) % 2**31
+      end
+
+      def digest(key)
+        Digest::SHA256.hexdigest(@salt ? "#{@code_path}\0#{@salt}\0#{key}" : "#{@code_path}\0#{key}")
+      end
+
+      # An estimate, since the real width depends on the font: Excalidraw
+      # measures text again when the drawing opens.
+      def text_width(text, size)
+        text.each_char.sum { |char| char.ascii_only? ? size * 0.55 : size * 1.0 }.ceil
+      end
+
+      # Breaks between words, or between characters in Japanese and Chinese
+      # text, which has no spaces; a word wider than a line is split.
+      def wrap(text, max_width, size)
+        lines = [+""]
+        text.scan(WRAP_TOKENS).each do |token|
+          if lines.last != "" && text_width(lines.last + token.rstrip, size) > max_width
+            lines.last.rstrip!
+            lines << +""
+            token = token.lstrip
+          end
+          token.each_char do |char|
+            lines << +"" if lines.last != "" && text_width(lines.last + char, size) > max_width
+            lines.last << char
+          end
+        end
+        lines.each(&:rstrip!)
+      end
+    end
+  end
+end

data/lib/omoteura/draft.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "omoteura/draft/scene_builder"
+require "omoteura/outline"
+
+module Omoteura
+  # Drafts a diagram from a code file: for a spec, a column per example
+  # group with a box per example; for other code, a column per kind of
+  # declaration and one for public methods. Every box links to its code,
+  # and a link is added only when it resolves to exactly that code.
+  #
+  # A draft is a starting point for a hand-drawn diagram. It never
+  # replaces one: when the file already has a diagram, the draft goes
+  # beside it as <name>.draft.excalidraw, or .draft.excalidraw.md when
+  # drafting for Obsidian.
+  class Draft
+    CATEGORIES = Outline::KINDS
+    FORMAT_SOURCE = "https://github.com/kaibyaku-jp/omoteura"
+    EXTENSIONS = {excalidraw: ".excalidraw", obsidian: ".excalidraw.md"}.freeze
+
+    # status is :written, :draft (written beside an existing diagram),
+    # :exists (a previous draft is in the way) or :empty (nothing to draw);
+    # for #merge, :merged, :up_to_date (nothing missing) or :no_diagram.
+    Result = Data.define(:code_path, :diagram_path, :shape_count, :status)
+
+    # format is :excalidraw for a .excalidraw file or :obsidian for an
+    # Obsidian Excalidraw plugin note.
+    def initialize(config, only: CATEGORIES, out: nil, format: :excalidraw)
+      @config = config
+      @only = only
+      @out = out
+      @format = format
+      @extension = EXTENSIONS.fetch(format)
+      @resolver = Resolver.new(config)
+      @link_resolver = LinkResolver.new(config)
+      @drawn = nil
+    end
+
+    # code_path is relative to the project root. Nothing is written when
+    # dry_run is true.
+    def draft(code_path, dry_run: false)
+      index = SourceIndex.parse_file(File.join(@config.root, code_path))
+      columns = index.spec_entries.empty? ? code_columns(index, code_path) : spec_columns(index, code_path)
+      boxes = columns.sum { |column| column.items.count { |item| item.is_a?(SceneBuilder::Box) } }
+      return Result.new(code_path: code_path, diagram_path: nil, shape_count: 0, status: :empty) if boxes.zero?
+
+      diagram_path, status = destination(code_path)
+      return Result.new(code_path: code_path, diagram_path: diagram_path, shape_count: boxes, status: :exists) if status == :exists
+
+      write(diagram_path, SceneBuilder.new(code_path).build(code_path, columns)) unless dry_run
+      Result.new(code_path: code_path, diagram_path: diagram_path, shape_count: boxes, status: status)
+    end
+
+    # Adds to the file's diagram what it has no shape for yet, in columns to
+    # the right of everything drawn. Nothing drawn is moved or removed. A
+    # shape counts as drawn when its link points at the same code, or its
+    # label is the same.
+    def merge(code_path, dry_run: false)
+      attachment = @resolver.resolve(code_path)
+      if attachment.nil? || attachment.missing?
+        return Result.new(code_path: code_path, diagram_path: attachment&.diagram_path, shape_count: 0, status: :no_diagram)
+      end
+
+      file = @config.expand(attachment.diagram_path)
+      diagram = Diagram.load(file)
+      existing = diagram.data["elements"].select { |e| e.is_a?(Hash) && !e["isDeleted"] }
+      @drawn = drawn_in(diagram, code_path)
+      index = SourceIndex.parse_file(File.join(@config.root, code_path))
+      columns = prune(index.spec_entries.empty? ? code_columns(index, code_path) : spec_columns(index, code_path))
+      boxes = columns.sum { |column| column.items.count { |item| item.is_a?(SceneBuilder::Box) } }
+      return Result.new(code_path: code_path, diagram_path: attachment.diagram_path, shape_count: 0, status: :up_to_date) if boxes.zero?
+
+      unless dry_run
+        added = merged_elements(code_path, columns, existing, diagram.data["elements"])
+        data = diagram.data.merge("elements" => diagram.data["elements"] + added)
+        Writer.new(@config).save(file, data, if_unchanged: diagram.digest)
+      end
+      Result.new(code_path: code_path, diagram_path: attachment.diagram_path, shape_count: boxes, status: :merged)
+    ensure
+      @drawn = nil
+    end
+
+    private
+
+    MERGE_TITLE = "Not drawn yet"
+
+    # The lines of this file the diagram's shapes link to, and their labels.
+    def drawn_in(diagram, code_path)
+      lines = diagram.linked_elements.filter_map do |element|
+        target = @link_resolver.resolve(element.link, context_path: code_path).target
+        target.start_line if target && target.path == code_path
+      end
+      labels = diagram.elements.filter_map { |element| element.label&.tr("\n", " ")&.squeeze(" ") }
+      {lines: lines.to_h { |line| [line, true] }, labels: labels.to_h { |label| [label, true] }}
+    end
+
+    def drawn?(entry, label)
+      @drawn && (@drawn[:lines][entry.start_line] || @drawn[:labels][label]) || false
+    end
+
+    # Without the boxes taken out for being drawn, headings left with no
+    # box under them go, and so do columns left with none.
+    def prune(columns)
+      columns.filter_map do |column|
+        items = column.items.each_with_index.select do |item, i|
+          item.is_a?(SceneBuilder::Box) || column.items[(i + 1)..].take_while { |next_item| !next_item.is_a?(SceneBuilder::Heading) }.any?
+        end.map(&:first)
+        column.with(items: items) if items.any? { |item| item.is_a?(SceneBuilder::Box) }
+      end
+    end
+
+    # The new elements, under a title to the right of everything drawn, with
+    # ids that no existing element has.
+    def merged_elements(code_path, columns, existing, all)
+      right = existing.map { |e| e["x"].to_f + e["width"].to_f }.max || 0
+      top = existing.map { |e| e["y"].to_f }.min || 0
+      taken = all.filter_map { |e| e["id"] if e.is_a?(Hash) }.to_h { |id| [id, true] }
+      (1..).each do |attempt|
+        elements = SceneBuilder.new(code_path, salt: "merge #{attempt}")
+          .build(MERGE_TITLE, columns, origin: [(right + SceneBuilder::COLUMN_GAP * 2).round, top.round])
+        return elements if elements.none? { |e| taken[e["id"]] }
+      end
+    end
+
+    def spec_columns(index, code_path)
+      entries = index.spec_entries.sort_by(&:start_line)
+      parents = parents_of(entries)
+      roots = entries.reject { |entry| parents[entry] }
+      # A single top-level group, the usual RSpec.describe, gives its
+      # children a column each; otherwise each top-level group is a column.
+      tops = (roots.size == 1 && roots.first.group) ? entries.select { |e| parents[e] == roots.first } : roots
+      loose = tops.reject(&:group)
+      loose_boxes = loose.filter_map { |e| spec_box(e, parents, code_path) }
+      columns = loose_boxes.empty? ? [] : [SceneBuilder::Column.new(heading: nil, items: loose_boxes)]
+      columns + tops.select(&:group).map do |group|
+        items = entries.select { |e| descendant?(e, group, parents) }.filter_map do |entry|
+          entry.group ? SceneBuilder::Heading.new(text: own_label(entry, parents), link: spec_link(entry, code_path)) : spec_box(entry, parents, code_path)
+        end
+        SceneBuilder::Column.new(heading: SceneBuilder::Heading.new(text: own_label(group, parents), link: spec_link(group, code_path)), items: items)
+      end
+    end
+
+    # nil when the diagram being merged into already has it.
+    def spec_box(entry, parents, code_path)
+      label = own_label(entry, parents)
+      return nil if drawn?(entry, label)
+
+      SceneBuilder::Box.new(label: label, link: spec_link(entry, code_path))
+    end
+
+    def spec_link(entry, code_path)
+      verified_link(["omoteura:##{entry.name}"], entry, code_path)
+    end
+
+    # Entries are sorted by start line and RSpec blocks nest, so each
+    # entry's parent is the nearest open entry that still contains it.
+    def parents_of(entries)
+      open = []
+      entries.to_h do |entry|
+        open.pop while open.any? && open.last.end_line < entry.start_line
+        parent = open.last
+        open.push(entry)
+        [entry, parent]
+      end
+    end
+
+    def descendant?(entry, ancestor, parents)
+      parent = parents[entry]
+      parent = parents[parent] while parent && parent != ancestor
+      !parent.nil?
+    end
+
+    # The description the entry adds to its parent's: "keeps emails
+    # unique" for "User validations keeps emails unique".
+    def own_label(entry, parents)
+      parent = parents[entry]
+      return entry.name unless parent && entry.name.start_with?(parent.name)
+
+      entry.name.delete_prefix(parent.name).delete_prefix(" ")
+    end
+
+    def code_columns(index, code_path)
+      Outline.new(index).items(only: @only).chunk_while { |a, b| a.kind == b.kind }.map do |items|
+        kind = items.first.kind
+        boxes = items.filter_map do |item|
+          entry = item.entry
+          label = (kind == "methods") ? entry.name : entry.name.delete_suffix(",")
+          next if drawn?(entry, label)
+
+          if kind == "methods"
+            SceneBuilder::Box.new(label: entry.name, link: verified_link(["omoteura:##{entry.name}"], entry, code_path))
+          else
+            prefix = entry.name[/\A\S+\s+[^,(\s]+/]
+            SceneBuilder::Box.new(label: entry.name.delete_suffix(","), link: verified_link(["omoteura:##{prefix}", "omoteura:##{entry.name}"].uniq, entry, code_path))
+          end
+        end
+        SceneBuilder::Column.new(heading: SceneBuilder::Heading.new(text: kind.capitalize, link: nil), items: boxes) unless boxes.empty?
+      end.compact
+    end
+
+    # The first candidate that resolves to exactly this entry, or nil.
+    def verified_link(candidates, entry, code_path)
+      @link_resolver.exact_link(candidates, path: code_path, line: entry.start_line)
+    end
+
+    # The draft takes the conventional place, unless the file already has
+    # a diagram, by any means, or a file is there. --out, relative to the
+    # root, names a file or a directory instead. Nothing is ever replaced.
+    def destination(code_path)
+      if @out
+        path = @out.end_with?(@extension) ? @out : File.join(@out, File.basename(base_name(code_path)) + @extension)
+        return [path, File.exist?(File.expand_path(path, @config.root)) ? :exists : :written]
+      end
+
+      base = File.join(@config.diagrams_dir, base_name(code_path))
+      attachment = @resolver.resolve(code_path)
+      taken = attachment || EXTENSIONS.each_value.any? { |ext| File.exist?(File.join(@config.root, base + ext)) }
+      return [base + @extension, :written] unless taken
+
+      path = base + ".draft" + @extension
+      [path, File.exist?(File.join(@config.root, path)) ? :exists : :draft]
+    end
+
+    def base_name(code_path)
+      code_path.delete_suffix(File.extname(code_path))
+    end
+
+    def write(diagram_path, elements)
+      full = File.expand_path(diagram_path, @config.root)
+      FileUtils.mkdir_p(File.dirname(full))
+      scene = {
+        "type" => "excalidraw",
+        "version" => 2,
+        "source" => FORMAT_SOURCE,
+        "elements" => elements,
+        "appState" => {"viewBackgroundColor" => "#ffffff", "gridSize" => nil},
+        "files" => {}
+      }
+      File.write(full, (@format == :obsidian) ? Obsidian.render(scene) : JSON.pretty_generate(scene) + "\n")
+    end
+  end
+end

data/lib/omoteura/inspector.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # Everything an editor needs about one code file or one diagram, as plain
+  # data: the attached diagram or the code it is attached to, where each
+  # linked shape points and how the tests behind it did. Broken links and
+  # unreadable diagrams are reported in the data rather than raised, so the
+  # editor can show them.
+  class Inspector
+    FORMAT_VERSION = 1
+
+    def initialize(config, results: TestResults.new([]))
+      @config = config
+      @results = results
+      @resolver = Resolver.new(config)
+      @link_resolver = LinkResolver.new(config)
+    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, new_diagram_path: new_diagram_path(relative),
+              attachment: nil, shapes: [], error: nil}
+
+      attachment = @resolver.resolve(relative) or return data
+      data[:attachment] = {diagram_path: attachment.diagram_path, source: attachment.source.to_s, missing: attachment.missing?}
+      return data if attachment.missing?
+
+      diagram = Diagram.load(@config.expand(attachment.diagram_path))
+      data[:shapes] = diagram.linked_elements.map { |element| shape(element, relative) }
+      data
+    rescue MagicComment::Duplicate, Resolver::InvalidPath, Diagram::NotADiagram, Diagram::ParseError => e
+      data.merge(error: e.message.delete_prefix("#{@config.root}/"))
+    end
+
+    # diagram_path must be an existing file inside the project root. A shared
+    # diagram can be attached to several files; links without a path are
+    # resolved against the first of them.
+    def diagram_report(diagram_path)
+      file = @config.expand(diagram_path) or raise ArgumentError, "#{diagram_path} is outside the project"
+      relative = @config.relative(file)
+      attached_to = code_attached_to(relative)
+      data = {version: FORMAT_VERSION, diagram_path: relative, attached_to: attached_to, digest: nil, scene: nil, shapes: [], error: nil}
+
+      diagram = Diagram.load(file)
+      data[:digest] = diagram.digest
+      data[:scene] = diagram.scene
+      data[:shapes] = diagram.linked_elements.map { |element| shape(element, attached_to.first) }
+      data
+    rescue Diagram::NotADiagram, Diagram::ParseError => e
+      data.merge(error: e.message.delete_prefix("#{@config.root}/"))
+    end
+
+    private
+
+    def code_attached_to(diagram_path)
+      Project.new(@config).code_paths.select do |code_path|
+        attachment = @resolver.resolve(code_path)
+        attachment && !attachment.missing? && attachment.diagram_path == diagram_path
+      rescue MagicComment::Duplicate, Resolver::InvalidPath
+        false
+      end
+    end
+
+    # Where a new plain Excalidraw diagram for the file belongs by the path
+    # convention, so an editor can offer to create one.
+    def new_diagram_path(code_path)
+      File.join(@config.diagrams_dir, code_path.delete_suffix(File.extname(code_path)) + ".excalidraw")
+    end
+
+    def shape(element, context_path)
+      result = @link_resolver.resolve(element.link, context_path: context_path)
+      target = result.target
+      summary = target && @results.summary_for(target)
+      {
+        id: element.id,
+        label: element.label,
+        link: element.link,
+        target: target&.to_h,
+        error: result.error,
+        test: summary && {
+          status: summary.status,
+          examples: summary.examples.map { |e| e.to_h.slice(:line_number, :full_description, :status, :message) }
+        }
+      }
+    end
+  end
+end