omoteura-core 0.1.0

data/lib/omoteura/link_candidates.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # The places in a code file a shape can link to, each with a link that
+  # resolves to exactly that place: in a spec, every example group and
+  # example; in other code, every declaration and method. For an editor to
+  # offer when linking a shape, and for drafts.
+  class LinkCandidates
+    Candidate = Data.define(:link, :label, :kind, :line)
+
+    def initialize(config, link_resolver: LinkResolver.new(config))
+      @config = config
+      @link_resolver = link_resolver
+    end
+
+    # code_path is relative to the project root. Links leave the path out,
+    # so they are for a diagram attached to this file. Places no link can
+    # single out, such as two examples with one description, are left out.
+    def for(code_path)
+      index = SourceIndex.parse_file(File.join(@config.root, code_path))
+      candidates = index.spec_entries.empty? ? code(index, code_path) : specs(index, code_path)
+      candidates.sort_by(&:line)
+    end
+
+    private
+
+    def specs(index, code_path)
+      index.spec_entries.filter_map do |entry|
+        candidate(["omoteura:##{entry.name}"], entry, code_path, label: entry.name, kind: entry.group ? "group" : "example")
+      end
+    end
+
+    # Declarations link by the macro and its first argument, such as
+    # "validates :email", and failing that by their whole first line.
+    def code(index, code_path)
+      declarations = Outline.new(index).items(only: Outline::KINDS - ["methods"]).filter_map do |item|
+        entry = item.entry
+        prefix = entry.name[/\A\S+\s+[^,(\s]+/]
+        candidate(["omoteura:##{prefix}", "omoteura:##{entry.name}"].compact.uniq, entry, code_path,
+          label: entry.name.delete_suffix(","), kind: item.kind)
+      end
+      methods = index.method_entries.filter_map do |entry|
+        candidate(["omoteura:##{entry.name}"], entry, code_path, label: entry.name, kind: "methods")
+      end
+      declarations + methods
+    end
+
+    def candidate(links, entry, code_path, label:, kind:)
+      link = @link_resolver.exact_link(links, path: code_path, line: entry.start_line)
+      link && Candidate.new(link: link, label: label, kind: kind, line: entry.start_line)
+    end
+  end
+end

data/lib/omoteura/link_resolver.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # Turns an omoteura: link into a file and line range.
+  #
+  #   omoteura:#<fragment>         a place in the code file the diagram is attached to
+  #   omoteura:<path>#<fragment>   a place in another file
+  #   omoteura:<path>              a whole file
+  #
+  # A fragment is tried, in order, as a spec description (in full, or a
+  # trailing part of one), a method name, then the start of a statement.
+  # The first kind that matches decides: one match resolves the link, more
+  # than one makes it ambiguous, and none moves on to the next kind.
+  class LinkResolver
+    Target = Data.define(:path, :start_line, :end_line)
+
+    Result = Data.define(:link, :target, :error) do
+      def broken?
+        !error.nil?
+      end
+    end
+
+    IDENTIFIER_CHAR = /[[:alnum:]_?!]/
+    WORD_END_BYTES = [" ", "#", ".", ":"].map(&:ord).freeze
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+      @indexes = {}
+    end
+
+    # context_path is the code file the diagram is attached to, relative to
+    # the project root. It is needed only for links without a path.
+    def resolve(link, context_path: nil)
+      body = link.to_s.delete_prefix(Diagram::LINK_PREFIX)
+      path, fragment = body.split("#", 2)
+      path = path.to_s
+      fragment = fragment&.strip
+      return failure(link, "has an empty #fragment") if fragment == ""
+
+      path = context_path if path.empty?
+      return failure(link, "has no file and the diagram is not attached to one") if path.nil?
+
+      file = config.expand(path) or return failure(link, "points outside the project")
+      return failure(link, "points to #{path}, which does not exist") unless File.file?(file)
+
+      index = index_for(file)
+      return success(link, Target.new(path: path, start_line: 1, end_line: index.line_count)) if fragment.nil?
+
+      find(index, fragment, link, path)
+    end
+
+    # The first of links that resolves to exactly the code starting at line
+    # of path, or nil. Links without a path are read against path.
+    def exact_link(links, path:, line:)
+      links.find do |link|
+        target = resolve(link, context_path: path).target
+        target && target.path == path && target.start_line == line
+      end
+    end
+
+    private
+
+    # Each kind is only searched when the ones before it found nothing.
+    # filter_map rather than select: select sizes its result for the whole
+    # input even when nothing matches, about 9 KB per scan of a large file,
+    # while filter_map grows its result only for matches. (.standard.yml
+    # turns off the cop that prefers select here.)
+    def find(index, fragment, link, path)
+      candidates = spec_candidates(index.spec_entries, fragment)
+      candidates = index.method_entries.filter_map { |e| e if e.name == fragment } if candidates.empty?
+      candidates = index.statement_entries.filter_map { |e| e if statement_match?(e.name, fragment) } if candidates.empty?
+
+      case candidates.size
+      when 0 then failure(link, "matches nothing in #{path}")
+      when 1 then success(link, Target.new(path: path, start_line: candidates.first.start_line, end_line: candidates.first.end_line))
+      else
+        lines = candidates.map(&:start_line).join(", ")
+        failure(link, "matches #{candidates.size} places in #{path} (lines #{lines})")
+      end
+    end
+
+    # An exact description beats descriptions that only end with it.
+    def spec_candidates(entries, fragment)
+      exact = entries.filter_map { |e| e if e.name == fragment }
+      exact.empty? ? entries.filter_map { |e| e if spec_suffix_match?(e.name, fragment) } : exact
+    end
+
+    # A trailing part must start at a word boundary: "email 一意であること"
+    # matches "User validations email 一意であること" but "ail 一意であること"
+    # does not. In "User#display_name", both "#display_name" and
+    # "display_name" match, as "#", "." and "::" also end a word.
+    # Compares bytes so that checking thousands of entries allocates nothing.
+    def spec_suffix_match?(name, fragment)
+      return false unless name.bytesize > fragment.bytesize && name.end_with?(fragment)
+
+      fragment.start_with?("#", ".", "::") || WORD_END_BYTES.include?(name.getbyte(name.bytesize - fragment.bytesize - 1))
+    end
+
+    # "validates :email" matches "validates :email, presence: true" but not
+    # "validates :email_confirmation".
+    def statement_match?(first_line, fragment)
+      return false unless first_line.start_with?(fragment)
+
+      following = first_line.getbyte(fragment.bytesize)
+      return true if following.nil?
+      # Only a non-ASCII character needs the regexp; ASCII is checked by byte.
+      return !first_line[fragment.length].match?(IDENTIFIER_CHAR) if following >= 0x80
+
+      !(following == 95 || following == 33 || following == 63 || (48..57).cover?(following) ||
+        (65..90).cover?(following) || (97..122).cover?(following))
+    end
+
+    def index_for(file)
+      @indexes[file] ||= SourceIndex.parse_file(file)
+    end
+
+    def success(link, target)
+      Result.new(link: link, target: target, error: nil)
+    end
+
+    def failure(link, reason)
+      Result.new(link: link, target: nil, error: "#{link} #{reason}")
+    end
+  end
+end

data/lib/omoteura/lz_string.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # lz-string's compressToBase64 format, which the Obsidian Excalidraw
+  # plugin uses for ```compressed-json blocks.
+  # Port of https://github.com/pieroxy/lz-string (MIT).
+  module LZString
+    BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/="
+    # Value of each byte of the alphabet, indexed by byte; anything else reads as 0.
+    BASE64_BYTE_VALUES = Array.new(256, 0).tap { |table| BASE64_ALPHABET.each_byte.with_index { |b, i| table[b] = i } }.freeze
+    WHITESPACE = " \t\r\n\f\v"
+
+    module_function
+
+    # Compresses a UTF-8 string to the same output as lz-string's
+    # compressToBase64.
+    def compress_to_base64(input)
+      result = compress(input.encode(Encoding::UTF_16BE).unpack("n*"), 6)
+      result << "=" * ((4 - result.size % 4) % 4)
+    end
+
+    # Returns the decompressed UTF-8 string, or nil if the input is corrupt.
+    def decompress_from_base64(input)
+      input = input.delete(WHITESPACE)
+      return "" if input.empty?
+
+      values = input.bytes
+      values.map! { |b| BASE64_BYTE_VALUES[b] }
+      decompress(values, 32)
+    end
+
+    # Dictionary entries are UTF-16BE byte strings, because lz-string works on
+    # JavaScript's UTF-16 code units rather than on characters. They are never
+    # modified, so single code units are shared through the units cache.
+    def decompress(values, reset_value)
+      reader = BitReader.new(values, reset_value)
+      units = {}
+      dictionary = [nil, nil, nil]
+      enlarge_in = 4
+      num_bits = 3
+
+      c =
+        case reader.read(2)
+        when 0 then unit(units, reader.read(8))
+        when 1 then unit(units, reader.read(16))
+        else return ""
+        end
+      dictionary << c
+      w = c
+      result = c.dup
+
+      loop do
+        return nil if reader.exhausted?
+
+        code = reader.read(num_bits)
+        case code
+        when 0, 1
+          dictionary << unit(units, reader.read((code == 0) ? 8 : 16))
+          code = dictionary.size - 1
+          enlarge_in -= 1
+        when 2
+          return result.force_encoding(Encoding::UTF_16BE).encode(Encoding::UTF_8)
+        end
+
+        if enlarge_in == 0
+          enlarge_in = 2**num_bits
+          num_bits += 1
+        end
+
+        entry =
+          if dictionary[code]
+            dictionary[code]
+          elsif code == dictionary.size
+            w + first_unit(units, w)
+          else
+            return nil
+          end
+        result << entry
+        dictionary << (w + first_unit(units, entry))
+        enlarge_in -= 1
+        w = entry
+
+        if enlarge_in == 0
+          enlarge_in = 2**num_bits
+          num_bits += 1
+        end
+      end
+    rescue EncodingError
+      nil
+    end
+
+    # Phrases are dictionary codes rather than strings: a phrase extended by a
+    # code unit is looked up as (phrase << 16 | unit), so compressing
+    # allocates no string per phrase.
+    def compress(code_units, bits_per_char)
+      writer = BitWriter.new(bits_per_char)
+      singles = {}
+      phrases = {}
+      to_create = {}
+      dict_size = 3
+      enlarge_in = 2
+      num_bits = 2
+      w = nil
+      w_unit = nil
+
+      emit = lambda do
+        if w_unit && to_create.delete(w_unit)
+          if w_unit < 256
+            writer.write(0, num_bits)
+            writer.write(w_unit, 8)
+          else
+            writer.write(1, num_bits)
+            writer.write(w_unit, 16)
+          end
+          enlarge_in -= 1
+          if enlarge_in == 0
+            enlarge_in = 2**num_bits
+            num_bits += 1
+          end
+        else
+          writer.write(w, num_bits)
+        end
+        enlarge_in -= 1
+        if enlarge_in == 0
+          enlarge_in = 2**num_bits
+          num_bits += 1
+        end
+      end
+
+      code_units.each do |c|
+        unless singles.key?(c)
+          singles[c] = dict_size
+          dict_size += 1
+          to_create[c] = true
+        end
+
+        if w.nil?
+          w = singles[c]
+          w_unit = c
+        elsif (code = phrases[(w << 16) | c])
+          w = code
+          w_unit = nil
+        else
+          emit.call
+          phrases[(w << 16) | c] = dict_size
+          dict_size += 1
+          w = singles[c]
+          w_unit = c
+        end
+      end
+      emit.call if w
+      writer.write(2, num_bits)
+      writer.finish
+    end
+
+    def unit(units, code)
+      units[code] ||= [code].pack("n").freeze
+    end
+
+    # The first code unit of an entry, from the cache rather than byteslice,
+    # so that extending an entry allocates only the result.
+    def first_unit(units, entry)
+      unit(units, (entry.getbyte(0) << 8) | entry.getbyte(1))
+    end
+
+    class BitWriter
+      def initialize(bits_per_char)
+        @bits_per_char = bits_per_char
+        @val = 0
+        @position = 0
+        @out = +""
+      end
+
+      # Writes the low count bits of value, lowest first.
+      def write(value, count)
+        count.times do
+          @val = (@val << 1) | (value & 1)
+          if @position == @bits_per_char - 1
+            @out << BASE64_ALPHABET.getbyte(@val)
+            @val = 0
+            @position = 0
+          else
+            @position += 1
+          end
+          value >>= 1
+        end
+      end
+
+      def finish
+        loop do
+          @val <<= 1
+          if @position == @bits_per_char - 1
+            @out << BASE64_ALPHABET.getbyte(@val)
+            return @out
+          end
+          @position += 1
+        end
+      end
+    end
+
+    class BitReader
+      def initialize(values, reset_value)
+        @values = values
+        @reset_value = reset_value
+        @val = values.fetch(0, 0)
+        @position = reset_value
+        @index = 1
+      end
+
+      def exhausted?
+        @index > @values.size
+      end
+
+      def read(count)
+        bits = 0
+        count.times do |i|
+          bit = @val & @position
+          @position >>= 1
+          if @position == 0
+            @position = @reset_value
+            @val = @values.fetch(@index, 0)
+            @index += 1
+          end
+          bits |= 1 << i if bit > 0
+        end
+        bits
+      end
+    end
+  end
+end

data/lib/omoteura/magic_comment.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Omoteura
+  # Finds the "# omoteura: <path>" comment that attaches a diagram to a
+  # Ruby file. Only comments on their own line before the first statement
+  # or after the last one count; comments inside the code are ignored.
+  module MagicComment
+    class Duplicate < Error; end
+
+    PATTERN = /\A#[ \t]*omoteura:[ \t]*(\S(?:.*\S)?)[ \t]*\z/
+
+    module_function
+
+    # Returns the diagram path written in the magic comment, or nil.
+    def find(source, path: "source")
+      # Most files have no magic comment; skip parsing them.
+      return nil unless source.include?("omoteura:")
+
+      result = Prism.parse(source)
+      statements = result.value.statements.body
+      first_code = statements.first&.location&.start_offset
+      last_code = statements.last&.location&.end_offset
+
+      paths = result.comments.filter_map do |comment|
+        next if !comment.is_a?(Prism::InlineComment) || comment.trailing?
+
+        location = comment.location
+        outside_code = first_code.nil? || location.end_offset <= first_code || location.start_offset >= last_code
+        PATTERN.match(location.slice)&.[](1) if outside_code
+      end
+
+      raise Duplicate, "#{path} has #{paths.size} omoteura magic comments; keep only one" if paths.size > 1
+
+      paths.first
+    end
+  end
+end

data/lib/omoteura/minimum_ruby.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Loaded by the executable before anything else, so it must stay in syntax
+# that old Rubies can parse and must not depend on the rest of the gem.
+module Omoteura
+  MINIMUM_RUBY = "3.4"
+
+  # The message to stop with when version is older than MINIMUM_RUBY, or nil.
+  def self.ruby_too_old_message(version = RUBY_VERSION, ruby = RbConfig.ruby)
+    return nil unless Gem::Version.new(version) < Gem::Version.new(MINIMUM_RUBY)
+
+    "omoteura needs Ruby #{MINIMUM_RUBY} or later, but this is Ruby #{version} (#{ruby})."
+  end
+end

data/lib/omoteura/obsidian.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "omoteura/lz_string"
+
+module Omoteura
+  # Writes drawings as the Obsidian Excalidraw plugin saves them: a
+  # markdown note whose "# Excalidraw Data" part lists the text of each
+  # text element and the link of each linked element, followed by the
+  # scene itself in a ## Drawing block.
+  #
+  # The plugin reads ids back from those lists as exactly eight
+  # characters, so elements with other ids are left out of them. It still
+  # reads them from the scene, and gives text elements new ids.
+  module Obsidian
+    # What the plugin writes at the top of a new drawing.
+    HEADER = <<~MARKDOWN
+      ---
+
+      excalidraw-plugin: parsed
+      tags: [excalidraw]
+
+      ---
+      ==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'
+
+
+    MARKDOWN
+    ID_LENGTH = 8
+    CHUNK_SIZE = 256
+    # Where the plugin's part of the note starts; everything above is the
+    # user's. Older files have no "# Excalidraw Data" heading.
+    DATA_START = /^(%%\n+)?(?:# Excalidraw Data|##? Text Elements|##? Drawing)(?:\n|$)/
+    DRAWING_START = /^##? Drawing\n/
+    EMBEDDED_FILES = /^## Embedded Files\n.*/m
+
+    class << self
+      # A new note holding scene, a Hash with "elements", "appState" and
+      # "files" as Excalidraw saves them.
+      def render(scene, compress: true)
+        HEADER + data(scene, compress: compress, commented_out: false, embedded_files: "")
+      end
+
+      # source with its drawing replaced by scene. What the user wrote above
+      # the drawing, the Embedded Files list and whether the drawing is
+      # compressed stay as they were.
+      def rewrite(source, scene)
+        match = DATA_START.match(source) or raise Diagram::ParseError, "no Excalidraw data to replace"
+        commented_out = !match[1].nil?
+        rest = match.post_match
+        before_drawing = (drawing = DRAWING_START.match(rest)) ? drawing.pre_match : rest
+        before_drawing = before_drawing.delete_suffix("%%\n") unless commented_out
+
+        match.pre_match + data(
+          scene,
+          compress: source.include?("```compressed-json\n"),
+          commented_out: commented_out,
+          embedded_files: before_drawing[EMBEDDED_FILES] || ""
+        )
+      end
+
+      private
+
+      def data(scene, compress:, commented_out:, embedded_files:)
+        live = scene["elements"].select { |e| !e["isDeleted"] && e["id"].to_s.length == ID_LENGTH }
+        texts, others = live.partition { |e| e["type"] == "text" }
+        out = +(commented_out ? "%%\n" : "")
+        out << "# Excalidraw Data\n\n## Text Elements\n"
+        texts.each { |e| out << "#{e["rawText"] || e["originalText"] || e["text"]} ^#{e["id"]}\n\n" }
+        linked = others.select { |e| e["link"] } + texts.select { |e| e["link"] }
+        unless linked.empty?
+          out << "## Element Links\n"
+          linked.each { |e| out << "#{e["id"]}: #{e["link"]}\n\n" }
+        end
+        out << embedded_files
+        out << "%%\n" unless commented_out
+        out << drawing(scene, compress)
+      end
+
+      def drawing(scene, compress)
+        json = JSON.pretty_generate(scene, indent: "\t")
+        return "## Drawing\n```json\n#{json}\n```\n%%" unless compress
+
+        chunks = LZString.compress_to_base64(json).scan(/.{1,#{CHUNK_SIZE}}/o)
+        "## Drawing\n```compressed-json\n#{chunks.join("\n\n")}\n```\n%%"
+      end
+    end
+  end
+end

data/lib/omoteura/outline.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # What a code file declares, the way a reader of a Rails model groups it:
+  # validations, associations, callbacks, scopes and enums, then the public
+  # methods. Read from a SourceIndex, without loading Rails or the code.
+  class Outline
+    KINDS = %w[validations associations callbacks scopes enums methods].freeze
+    DECLARATIONS = {
+      "validations" => /\A(?:validates?|validates_\w+)\b/,
+      "associations" => /\A(?:has_many|has_one|belongs_to|has_and_belongs_to_many)\b/,
+      "callbacks" => /\A(?:before|after|around)_\w+\b/,
+      "scopes" => /\Ascope\b/,
+      "enums" => /\Aenum\b/
+    }.freeze
+
+    # entry is the SourceIndex entry the item was read from; its name is the
+    # statement's first line, or the method's name.
+    Item = Data.define(:kind, :entry)
+
+    def initialize(index)
+      @index = index
+    end
+
+    # Items of the given kinds, by kind in KINDS order, then by line.
+    def items(only: KINDS)
+      KINDS.flat_map do |kind|
+        next [] unless only.include?(kind)
+
+        entries = (kind == "methods") ? public_methods : @index.statement_entries.select { |e| e.name.match?(DECLARATIONS[kind]) }
+        entries.map { |entry| Item.new(kind: kind, entry: entry) }
+      end
+    end
+
+    private
+
+    # Methods after a bare private or protected in the same class, or
+    # defined with private def, are left out, and so is initialize, which
+    # Ruby makes private and callers reach through new.
+    def public_methods
+      statements = @index.statement_entries
+      classes = statements.select { |e| e.name.match?(/\A(?:class|module)\b/) }
+      hidden_from = statements.select { |e| %w[private protected].include?(e.name) }
+      hidden_names = statements.filter_map { |e| e.name[/\A(?:private|protected)\s+def\s+(?:self\.)?(\w+[?!=]?)/, 1] }
+      @index.method_entries.reject do |method|
+        owner = classes.select { |c| c.start_line < method.start_line && c.end_line >= method.end_line }.max_by(&:start_line)
+        method.name == "initialize" || hidden_names.include?(method.name.delete_prefix("self.")) ||
+          hidden_from.any? { |h| h.start_line < method.start_line && (!owner || (h.start_line > owner.start_line && h.end_line <= owner.end_line)) }
+      end
+    end
+  end
+end

data/lib/omoteura/project.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Omoteura
+  # The files of a project that can have a diagram attached.
+  class Project
+    # Ruby files under these top-level directories are not project code.
+    IGNORED_DIRS = %w[vendor tmp log node_modules coverage pkg].freeze
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    # The project's Ruby files, outside IGNORED_DIRS and the diagrams
+    # directory, and any other existing file named in the attach setting,
+    # relative to the root and sorted.
+    def code_paths
+      paths = ruby_files.to_set
+      paths.merge(config.attach.keys.select { |path| File.file?(File.join(config.root, path)) })
+      paths.sort
+    end
+
+    private
+
+    def ruby_files
+      Dir.glob("**/*.rb", base: config.root).reject do |path|
+        IGNORED_DIRS.include?(path.split("/", 2).first) || path.start_with?("#{config.diagrams_dir}/")
+      end
+    end
+  end
+end