omoteura-core 0.1.0

data/lib/omoteura/resolver.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Omoteura
+  # Decides which diagram is attached to a code file. In order of priority:
+  # the magic comment, the attach setting, then the path convention
+  # (<diagrams_dir>/<code path>.excalidraw.md or .excalidraw).
+  class Resolver
+    class InvalidPath < Error; end
+
+    # Paths are relative to the project root. An explicitly attached diagram
+    # that does not exist is still returned, marked missing, so callers can
+    # report it instead of silently falling back to the convention.
+    Attachment = Data.define(:code_path, :diagram_path, :source, :missing) do
+      def missing?
+        missing
+      end
+    end
+
+    CONVENTION_EXTENSIONS = %w[.excalidraw.md .excalidraw].freeze
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Returns an Attachment, or nil when the file has no diagram or lies
+    # outside the project root. The code file must exist.
+    def resolve(code_path)
+      code = config.expand(code_path) or return nil
+      relative = relative_to_root(code)
+
+      if (written = MagicComment.find(File.read(code, encoding: Encoding::UTF_8), path: relative))
+        explicit(relative, written, :magic_comment)
+      elsif (written = config.attach[relative])
+        explicit(relative, written, :config)
+      else
+        by_convention(relative)
+      end
+    end
+
+    private
+
+    # Obsidian URIs and wikilinks leave out the .md extension, so a path
+    # copied from Obsidian is accepted when only "<path>.md" exists.
+    def explicit(code_path, written, source)
+      path = config.expand(written) or
+        raise InvalidPath, "#{code_path} attaches #{written}, which is outside the project"
+
+      unless File.file?(path)
+        with_md = config.expand("#{written}.md")
+        path = with_md if with_md && File.file?(with_md)
+      end
+
+      Attachment.new(code_path: code_path, diagram_path: relative_to_root(path), source: source, missing: !File.file?(path))
+    end
+
+    def by_convention(code_path)
+      base = File.join(config.diagrams_dir, code_path.delete_suffix(File.extname(code_path)))
+      CONVENTION_EXTENSIONS.each do |extension|
+        path = config.expand(base + extension)
+        next unless path && File.file?(path)
+
+        return Attachment.new(code_path: code_path, diagram_path: relative_to_root(path), source: :convention, missing: false)
+      end
+      nil
+    end
+
+    def relative_to_root(path)
+      Pathname(path).relative_path_from(Pathname(config.root)).to_s
+    end
+  end
+end

data/lib/omoteura/source_index.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Omoteura
+  # The places in a Ruby file that an omoteura: link can point at, found by
+  # parsing the file with Prism without loading or running it.
+  class SourceIndex
+    # kind is :spec (an example group or example), :method or :statement.
+    # For :spec, name is the full description as RSpec builds it, and group
+    # tells example groups from examples; for :statement, name is the first
+    # line of the statement.
+    # Every entry is built with all five members: a default would need an
+    # initialize override that allocates on each of thousands of entries.
+    Entry = Data.define(:kind, :name, :start_line, :end_line, :group)
+
+    attr_reader :entries, :line_count, :spec_entries, :method_entries, :statement_entries
+
+    def self.parse_file(path)
+      new(File.read(path, encoding: Encoding::UTF_8))
+    end
+
+    def initialize(source)
+      visitor = Visitor.new(source)
+      Prism.parse(source).value.accept(visitor)
+      @entries = visitor.entries.freeze
+      # Grouped once here; link resolution reads these for every link.
+      by_kind = @entries.group_by(&:kind)
+      @spec_entries = by_kind.fetch(:spec, []).freeze
+      @method_entries = by_kind.fetch(:method, []).freeze
+      @statement_entries = by_kind.fetch(:statement, []).freeze
+      @line_count = source.count("\n") + ((source.empty? || source.end_with?("\n")) ? 0 : 1)
+    end
+
+    class Visitor < Prism::Visitor
+      EXAMPLE_GROUPS = %i[describe context feature example_group xdescribe xcontext xfeature fdescribe fcontext ffeature].freeze
+      EXAMPLES = %i[it specify example scenario xit xspecify xexample xscenario fit fspecify fexample fscenario].freeze
+
+      Group = Data.define(:description, :module)
+
+      attr_reader :entries
+
+      def initialize(source)
+        super()
+        @source = source
+        @entries = []
+        # Enclosing example groups. A nil description means a parent could
+        # not be read statically, so nothing below it has a known one.
+        @groups = []
+      end
+
+      def visit_statements_node(node)
+        node.body.each { |statement| add(:statement, first_line(statement), statement) }
+        super
+      end
+
+      def visit_def_node(node)
+        name = node.receiver.is_a?(Prism::SelfNode) ? "self.#{node.name}" : node.name.name
+        add(:method, name, node)
+        super
+      end
+
+      def visit_call_node(node)
+        return super unless spec_call?(node)
+
+        part, is_module = description_of(node)
+        description = full_description(part)
+        add(:spec, description, node, group: EXAMPLE_GROUPS.include?(node.name)) if description
+
+        if EXAMPLE_GROUPS.include?(node.name)
+          @groups.push(Group.new(description: description, module: is_module))
+          super
+          @groups.pop
+        else
+          super
+        end
+      end
+
+      private
+
+      # Cuts the statement's first line out of the source by byte offsets.
+      # Slicing the whole statement would copy most of the file for every
+      # class or describe block, and again for each level of nesting.
+      def first_line(node)
+        start = node.location.start_offset
+        stop = @source.byteindex("\n", start) || @source.bytesize
+        line = @source.byteslice(start, stop - start)
+        line.rstrip!
+        line
+      end
+
+      def add(kind, name, node, group: false)
+        location = node.location
+        @entries << Entry.new(kind: kind, name: name, start_line: location.start_line, end_line: location.end_line, group: group)
+      end
+
+      def spec_call?(node)
+        return false unless EXAMPLE_GROUPS.include?(node.name) || EXAMPLES.include?(node.name)
+
+        receiver = node.receiver
+        receiver.nil? || (receiver.is_a?(Prism::ConstantReadNode) && receiver.name == :RSpec)
+      end
+
+      # RSpec takes the first argument as the description, plus a second
+      # one when it is a string; later symbols and hashes are metadata.
+      def description_of(node)
+        first, second = node.arguments&.arguments
+        part, is_module = literal(first)
+        part = "#{part} #{second.unescaped}" if part && second.is_a?(Prism::StringNode)
+        [part, is_module]
+      end
+
+      def literal(node)
+        case node
+        when Prism::StringNode, Prism::SymbolNode then [node.unescaped, false]
+        when Prism::ConstantReadNode, Prism::ConstantPathNode then [node.slice, true]
+        else [nil, false]
+        end
+      end
+
+      # Mirrors RSpec's description building: parts are joined with a space,
+      # except that "#method", ".method" and "::Const" attach directly to a
+      # parent described by a module, as in "User#display_name".
+      def full_description(part)
+        return nil if part.nil?
+
+        parent = @groups.last
+        return part if parent.nil?
+        return nil if parent.description.nil?
+
+        separator = (parent.module && part.match?(/\A(?:#|::|\.)/)) ? "" : " "
+        "#{parent.description}#{separator}#{part}"
+      end
+    end
+  end
+end

data/lib/omoteura/test_results.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Omoteura
+  # Test results written by Omoteura::RSpec::Formatter.
+  class TestResults
+    class Invalid < Error; end
+
+    DEFAULT_PATH = "tmp/omoteura/results.json"
+    SUPPORTED_VERSION = 1
+
+    Example = Data.define(:file_path, :line_number, :full_description, :status, :message)
+
+    # Combined status of the examples behind one shape: any failure fails
+    # the shape, then any pending example makes it pending.
+    Summary = Data.define(:status, :examples) do
+      def self.of(examples)
+        statuses = examples.map(&:status)
+        status =
+          if statuses.include?("failed") then "failed"
+          elsif statuses.include?("pending") then "pending"
+          else "passed"
+          end
+        new(status: status, examples: examples)
+      end
+    end
+
+    attr_reader :examples
+
+    # Returns empty results when the file does not exist yet, so diagrams
+    # still work before the first test run.
+    def self.load(path)
+      return new([]) unless File.file?(path)
+
+      data = JSON.parse(File.read(path, encoding: Encoding::UTF_8))
+      unless data.is_a?(Hash) && data["version"] == SUPPORTED_VERSION && data["examples"].is_a?(Array)
+        raise Invalid, "#{path} is not an Omoteura results file of version #{SUPPORTED_VERSION}"
+      end
+
+      examples = data["examples"].map do |e|
+        Example.new(file_path: e["file_path"], line_number: e["line_number"], full_description: e["full_description"],
+          status: e["status"], message: e["message"])
+      end
+      executed = data["executed_lines"]
+      new(examples, executed_lines: executed.is_a?(Hash) ? executed : nil)
+    rescue JSON::ParserError => e
+      raise Invalid, "#{path} is not valid JSON: #{e.message}"
+    end
+
+    # executed_lines maps files to the line numbers that ran during the
+    # tests, when the run measured coverage; nil when it did not.
+    def initialize(examples, executed_lines: nil)
+      @examples = examples
+      @executed_lines = executed_lines&.transform_values { |lines| lines.to_h { |line| [line, true] } }
+    end
+
+    # Whether code between the lines ran, or nil when nothing says: the run
+    # did not measure coverage, or did not load the file.
+    def executed?(path, lines)
+      executed = @executed_lines&.[](path) or return nil
+      lines.any? { |line| executed[line] }
+    end
+
+    # Summarizes the examples defined within the lines of a link target,
+    # or returns nil when no recorded example is there.
+    def summary_for(target)
+      matching = examples.select do |e|
+        e.file_path == target.path && (target.start_line..target.end_line).cover?(e.line_number)
+      end
+      matching.empty? ? nil : Summary.of(matching)
+    end
+  end
+end

data/lib/omoteura/writer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+
+module Omoteura
+  # Saves a drawing an editor changed, in the format of the file it goes
+  # to: a .excalidraw file as JSON, an Obsidian note through
+  # Obsidian.rewrite so the rest of the note stays as it was.
+  #
+  # The file is replaced in one step, so a failed save leaves it whole.
+  # Given the digest of the file as the editor read it, a save that would
+  # overwrite someone else's change is refused instead.
+  class Writer
+    class Conflict < Error; end
+
+    class Invalid < Error; end
+
+    Result = Data.define(:diagram_path, :digest)
+
+    NEW_FILE_EXTENSIONS = [".excalidraw", ".excalidraw.md"].freeze
+
+    def self.digest(content)
+      Digest::SHA256.hexdigest(content)
+    end
+
+    def initialize(config)
+      @config = config
+    end
+
+    # data is the drawing as Excalidraw saves it: a Hash with "elements",
+    # and usually "type", "version", "source", "appState" and "files".
+    def save(diagram_path, data, if_unchanged: nil)
+      file = @config.expand(diagram_path) or raise Invalid, "#{diagram_path} is outside #{@config.root}"
+      raise Invalid, "the drawing has no elements list" unless data.is_a?(Hash) && data["elements"].is_a?(Array)
+
+      file = File.realpath(file) if File.symlink?(file)
+      existing = File.exist?(file) ? File.binread(file) : nil
+      if if_unchanged && (existing.nil? || self.class.digest(existing) != if_unchanged)
+        raise Conflict, "#{@config.relative(file)} changed since it was read"
+      end
+
+      content = render(file, data, existing)
+      replace(file, content)
+      Result.new(diagram_path: @config.relative(file), digest: self.class.digest(content))
+    end
+
+    private
+
+    def render(file, data, existing)
+      if existing
+        raise Invalid, "#{@config.relative(file)} is not an Excalidraw drawing" unless Diagram.diagram_file?(file)
+      elsif NEW_FILE_EXTENSIONS.none? { |ext| file.end_with?(ext) }
+        raise Invalid, "a new drawing must end in #{NEW_FILE_EXTENSIONS.join(" or ")}"
+      end
+
+      return JSON.pretty_generate(data) + "\n" if file.end_with?(".excalidraw")
+
+      existing ? Obsidian.rewrite(existing.force_encoding(Encoding::UTF_8), keep_raw_text(file, data)) : Obsidian.render(data)
+    end
+
+    # The plugin keeps the markdown behind a text element, such as a
+    # [[wiki link]], in rawText, and lists it in the note. Excalidraw does
+    # not know it, so it is carried over from the saved drawing while the
+    # text is unchanged, and dropped once the text was edited.
+    def keep_raw_text(file, data)
+      before = Diagram.load(file).scene["elements"].to_h { |e| [e["id"], e] }
+      elements = data["elements"].map do |element|
+        next element unless element.is_a?(Hash) && element["type"] == "text"
+
+        old = before[element["id"]]
+        raw = old["rawText"] if old && old["originalText"] == element["originalText"]
+        raw ? element.merge("rawText" => raw) : element.except("rawText")
+      end
+      data.merge("elements" => elements)
+    end
+
+    def replace(file, content)
+      FileUtils.mkdir_p(File.dirname(file))
+      temp = File.join(File.dirname(file), ".#{File.basename(file)}.#{Process.pid}.omoteura")
+      File.binwrite(temp, content)
+      File.chmod(File.stat(file).mode, temp) if File.exist?(file)
+      File.rename(temp, file)
+    ensure
+      File.delete(temp) if temp && File.exist?(temp)
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: omoteura-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- KAIBYAKU K.K
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables:
+- omoteura
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- exe/omoteura
+- lib/omoteura/checker.rb
+- lib/omoteura/cli.rb
+- lib/omoteura/config.rb
+- lib/omoteura/core.rb
+- lib/omoteura/core/version.rb
+- lib/omoteura/coverage_report.rb
+- lib/omoteura/diagram.rb
+- lib/omoteura/draft.rb
+- lib/omoteura/draft/scene_builder.rb
+- lib/omoteura/inspector.rb
+- lib/omoteura/link_candidates.rb
+- lib/omoteura/link_resolver.rb
+- lib/omoteura/lz_string.rb
+- lib/omoteura/magic_comment.rb
+- lib/omoteura/minimum_ruby.rb
+- lib/omoteura/obsidian.rb
+- lib/omoteura/outline.rb
+- lib/omoteura/project.rb
+- lib/omoteura/resolver.rb
+- lib/omoteura/source_index.rb
+- lib/omoteura/test_results.rb
+- lib/omoteura/writer.rb
+homepage: https://github.com/kaibyaku-jp/omoteura
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kaibyaku-jp/omoteura
+  changelog_uri: https://github.com/kaibyaku-jp/omoteura/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Diagram file I/O, omoteura: link resolution and CLI for Omoteura'
+test_files: []