raindown 0.4.0 → 0.5.1

data/lib/raindown/projects.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'find'
+require_relative 'nodes'
+require_relative 'pages'
+
+module Raindown
+  # Raindown projects are folders with a .raindown folder, and their Markdown files are watched for changes.
+  # A file belongs to the project of the nearest .raindown folder above it, so projects can sit inside each other.
+  module Projects
+    # Folders of dependencies, builds and tooling, which aren't searched for projects or watched, nor are hidden folders.
+    IGNORED = %w[node_modules vendor tmp pkg build dist coverage].freeze
+
+    module_function
+
+    # The roots of the projects in a directory: the project the directory is in, if any, and every project below it.
+    def roots(directory)
+      directory = File.expand_path(directory)
+      roots = [root(directory)].compact
+
+      Find.find(directory) do |path|
+        next unless File.directory?(path)
+
+        Find.prune if path != directory && ignored?(File.basename(path))
+        roots << path if File.directory?(File.join(path, Nodes::FOLDER))
+      end
+
+      roots.uniq
+    end
+
+    # The root of the project a file or directory is in, or nil when it isn't in one.
+    def root(path)
+      path = File.expand_path(path)
+      folder = Nodes.find_folder(File.directory?(path) ? path : File.dirname(path))
+      folder && File.dirname(folder)
+    end
+
+    # The project's Markdown files, sorted. Ignored folders and the projects inside it are left out,
+    # since those projects have nodes of their own.
+    def files(root)
+      files = []
+
+      Find.find(root) do |path|
+        if File.directory?(path)
+          Find.prune if path != root && (ignored?(File.basename(path)) || File.directory?(File.join(path, Nodes::FOLDER)))
+        elsif markdown?(path, root:)
+          files << path
+        end
+      end
+
+      files.sort
+    end
+
+    # Whether a file is Markdown in its project, rather than in an ignored or hidden folder like node_modules.
+    def markdown?(path, root:)
+      return false unless Pages::EXTENSIONS.include?(File.extname(path).delete_prefix('.').downcase)
+
+      folders = File.dirname(File.expand_path(path)).delete_prefix(root).split('/').reject(&:empty?)
+      folders.none? { |folder| ignored?(folder) }
+    end
+
+    # Whether a file is one of a project's own nodes, which load when its watcher starts.
+    def node?(path, root:)
+      File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) && %w[.rb .rbx].include?(File.extname(path))
+    end
+
+    def ignored?(folder)
+      folder.start_with?('.') || IGNORED.include?(folder)
+    end
+  end
+end

data/lib/raindown/supervisor.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative 'project_worker'
+require_relative 'projects'
+
+module Raindown
+  # Watches every Raindown project in a directory, like ~/dev, and writes back to each Markdown file as it's saved.
+  #
+  # Each project's nodes load in a process of its own, forked once the shared code has loaded, so starting a project
+  # costs almost nothing and two projects can have nodes of the same name. One listener watches the directory and sends
+  # each changed file to its project's process. Without fork, as on Windows, the projects share this process.
+  class Supervisor
+    # Watching skips these folders as they hold dependencies and builds, which Projects ignores too.
+    IGNORE = %r{(?:\A|/)(?:#{Projects::IGNORED.join('|')})/}
+
+    attr_reader :directory, :workers
+
+    def initialize(directory:, bare: false, execute: false)
+      @directory = File.expand_path(directory)
+      @bare = bare
+      @execute = execute
+      @workers = {}
+    end
+
+    def start
+      require 'listen'
+      $stdout.sync = true
+      preload
+
+      Projects.roots(directory).each { worker(it) }
+      puts "Watching #{workers.size} #{workers.size == 1 ? 'project' : 'projects'} in #{directory} for changes..."
+
+      trap_interrupt
+      listener.start
+      sleep
+    ensure
+      stop
+    end
+
+    # Sends each changed file to its project, starting a worker for a new project, or restarting one when its nodes change.
+    def handle(paths)
+      paths.each do |path|
+        root = Projects.root(path) || next
+
+        if Projects.node?(path, root:)
+          restart(root)
+        elsif Projects.markdown?(path, root:)
+          worker(root).update(path)
+        end
+      end
+    end
+
+    def stop
+      workers.each_value(&:stop)
+      workers.clear
+    end
+
+    private
+
+    def listener
+      Listen.to(directory, ignore: IGNORE) { |modified, added, _removed| handle(modified + added) }
+    end
+
+    def worker(root)
+      workers[root] ||= begin
+        worker = ProjectWorker.new(root:, name: name(root), bare: @bare, execute: @execute)
+        fork? ? ForkedWorker.new(worker).tap(&:start) : worker.tap(&:start)
+      end
+    end
+
+    # Without fork the projects share this process, where nodes can't be unloaded.
+    def restart(root)
+      return warn("[#{name(root)}] Restart raindown to load the node changes") unless fork?
+
+      worker = workers.delete(root) || return
+      worker.stop
+      puts "[#{worker.name}] Reloading nodes"
+      worker(root)
+    end
+
+    # A project in the directory is named by its path from there, and the project the directory is in by its folder.
+    def name(root)
+      return File.basename(root) unless root.start_with?(File.join(directory, ''))
+
+      root.delete_prefix(File.join(directory, ''))
+    end
+
+    # Loaded before forking, so every project's process shares them instead of loading its own.
+    def preload
+      return unless fork?
+
+      require 'lownode'
+      require 'dirload'
+    end
+
+    def fork?
+      Process.respond_to?(:fork)
+    end
+
+    # Ctrl+C reaches every process in the terminal, so the workers stop with the watcher.
+    def trap_interrupt
+      trap('INT') { exit }
+    end
+  end
+
+  # A project's worker in a forked process, which reads the files to update from a pipe until the pipe closes.
+  # The process ends with exit! as it's forked mid-call, so exit would run the watcher's ensure and stop its siblings.
+  class ForkedWorker
+    def initialize(worker)
+      @worker = worker
+    end
+
+    def name
+      @worker.name
+    end
+
+    def start
+      @writer&.close
+      reader, @writer = IO.pipe
+      @pid = fork do
+        @writer.close
+        trap('INT') { exit!(0) }
+        @worker.start
+        while (path = reader.gets)
+          @worker.update(path.chomp)
+        end
+        exit!(0)
+      end
+      reader.close
+    end
+
+    # A worker that stopped, such as from a crash, starts again for the next file.
+    def update(path, restarted: false)
+      start unless alive?
+      @writer.puts(path)
+      @writer.flush
+    rescue Errno::EPIPE
+      raise if restarted
+
+      start
+      update(path, restarted: true)
+    end
+
+    def stop
+      @writer&.close
+      Process.kill('TERM', @pid) if alive?
+      Process.wait(@pid)
+    rescue Errno::ECHILD, Errno::ESRCH
+      nil
+    end
+
+    private
+
+    def alive?
+      @pid && Process.waitpid(@pid, Process::WNOHANG).nil?
+    rescue Errno::ECHILD
+      false
+    end
+  end
+end

data/lib/raindown/tui/commands.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../actions'
+
+module Raindown
+  module TUI
+    # What a Navigator does to the open file: run an endpoint, open the editor, write back and read it again.
+    # Each sets the status, so the Screen shows how it went, and returns what the Screen should do next, if anything.
+    module Commands
+      private
+
+      def execute
+        directive = selected(:outline)&.target if @focus == :outline
+        return error('Select an endpoint to run') unless directive.is_a?(Document::Directive) && directive.endpoint?
+
+        [:wait, "Running the endpoint on line #{directive.line}...", -> { run_endpoint(directive) }]
+      end
+
+      def run_endpoint(directive)
+        changed = Actions.execute(path, directive)
+        @outline.read
+        info(changed ? "Ran the endpoint on line #{directive.line}" : 'The response is the same')
+      rescue StandardError => e
+        error(e.message)
+      end
+
+      # In the files pane, the selected file opens at its top, and in the outline, the open file at the selected line.
+      def edit
+        row = selected
+        show(row.target) if @focus == :files && row&.kind == :file
+        return error('Open a file to edit') unless path
+
+        line = @focus == :outline && row ? row.line : 1
+        [:run, Actions.edit_command(path, line:)]
+      end
+
+      def write_back
+        return error('Open a file to write back') unless path
+
+        changed = Actions.write_back(path)
+        @outline.read
+        info(changed ? "Updated #{relative(path)}" : "#{relative(path)} is up to date")
+      rescue StandardError => e
+        error(e.message)
+      end
+
+      def reload
+        @files.load
+        @outline&.read if path && File.exist?(path)
+        info('Reloaded')
+      end
+
+      # Reads the file again when it's changed, like when it's saved in an editor or a watcher writes back to it.
+      def refresh
+        @outline.read if @outline&.changed?
+        nil
+      end
+
+      def info(message)
+        @status = [:info, message]
+        nil
+      end
+
+      def error(message)
+        @status = [:error, message]
+        nil
+      end
+    end
+  end
+end

data/lib/raindown/tui/file_tree.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../projects'
+require_relative 'row'
+
+module Raindown
+  module TUI
+    # The files pane: a project's Markdown files as a tree, with folders before files, where folders fold.
+    class FileTree
+      attr_reader :root
+
+      def initialize(root:)
+        @root = root
+        @folded = Set.new
+        load
+      end
+
+      def load
+        @files = Projects.files(root)
+      end
+
+      def rows
+        tree = {}
+        @files.each { |path| relative(path).split('/').reduce(tree) { |node, part| node[part] ||= {} } }
+        tree_rows(tree, '', 0)
+      end
+
+      def toggle(folder)
+        @folded.delete?(folder) || @folded.add(folder)
+      end
+
+      def relative(path)
+        path.delete_prefix(File.join(root, ''))
+      end
+
+      private
+
+      def tree_rows(tree, prefix, depth)
+        folders, files = tree.partition { |_name, children| children.any? }
+
+        folders.sort.flat_map { |name, children| folder_rows(name, children, prefix, depth) } +
+          files.sort.map { |name, _| Row.new(text: name, depth:, kind: :file, target: File.join(root, prefix, name)) }
+      end
+
+      # A folder, and the tree inside it unless it's folded.
+      def folder_rows(name, children, prefix, depth)
+        folder = File.join(root, prefix, name)
+        folded = @folded.include?(folder)
+        row = Row.new(text: "#{folded ? '▸' : '▾'} #{name}/", depth:, kind: :folder, target: folder)
+
+        [row, *(tree_rows(children, File.join(prefix, name), depth + 1) unless folded)]
+      end
+    end
+  end
+end

data/lib/raindown/tui/input.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'curses'
+require 'unicode/display_width'
+
+module Raindown
+  module TUI
+    # Turns curses' keys and clicks into a Navigator's events.
+    module Input
+      KEYS = {
+        Curses::KEY_UP => :up, 'k' => :up, Curses::KEY_DOWN => :down, 'j' => :down,
+        Curses::KEY_LEFT => :left, 'h' => :left, Curses::KEY_RIGHT => :right, 'l' => :right,
+        "\t" => :tab, Curses::KEY_BTAB => :tab, "\r" => :enter, "\n" => :enter, Curses::KEY_ENTER => :enter,
+        ' ' => :toggle, 'x' => :execute, 'e' => :edit, 'w' => :write_back, 'r' => :reload, 'q' => :quit
+      }.freeze
+
+      module_function
+
+      # A key from getch, which is a string for a printable character and otherwise a number.
+      def key_event(key)
+        key = key.chr if key.is_a?(Integer) && key < 256
+        KEYS[key]
+      end
+
+      # A scroll of the wheel moves the cursor, and a click sends the event of what's under it.
+      def mouse_event(event, zones)
+        wheel.find { |button, _| event.bstate.anybits?(button) }&.last || click(zones, column: event.x, row: event.y)
+      end
+
+      # Older ncurses has no fifth button, which is the wheel scrolling down.
+      def wheel
+        { Curses::BUTTON4_PRESSED => :up }.tap do |buttons|
+          buttons[Curses::BUTTON5_PRESSED] = :down if Curses.const_defined?(:BUTTON5_PRESSED)
+        end
+      end
+
+      # Where each of a Layout's segments with an event is on the screen, as [row, columns, event].
+      def zones(lines)
+        lines.each_with_index.flat_map do |segments, row|
+          column = 0
+          segments.filter_map do |segment|
+            width = Unicode::DisplayWidth.of(segment.text)
+            zone = [row, column...(column + width), segment.event] if segment.event
+            column += width
+            zone
+          end
+        end
+      end
+
+      def click(zones, column:, row:)
+        zones.find { |zone_row, columns, _event| zone_row == row && columns.cover?(column) }&.last
+      end
+    end
+  end
+end

data/lib/raindown/tui/layout.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'unicode/display_width'
+
+module Raindown
+  module TUI
+    # The screen as lines of styled segments, worked out from a Navigator with no terminal, so the Screen only paints them.
+    # A title, the files pane beside the outline, a status line and a bar of buttons:
+    #    raindown  docs  guides/setup.md
+    #    ▾ guides/       │ # Setup
+    #      setup.md      │   toc: [+3]
+    #    README.md       │   ## Install
+    #    Opened guides/setup.md
+    #    Tab Pane  Enter Open  x Run  e Edit  w Write back  r Reload  q Quit
+    # Each line is exactly the width, in display columns. A segment with an event is clicked to send it.
+    class Layout
+      Segment = Data.define(:text, :style, :event)
+
+      BUTTONS = [['Tab', 'Pane', :tab], ['Enter', 'Open', :enter], ['x', 'Run', :execute], ['e', 'Edit', :edit],
+                 ['w', 'Write back', :write_back], ['r', 'Reload', :reload], ['q', 'Quit', :quit]].freeze
+      FILES_WIDTH = (16..32)
+      INDENT = '  '
+      # The title, status and button lines.
+      CHROME_HEIGHT = 3
+
+      attr_reader :navigator, :width, :height
+
+      def initialize(navigator, width:, height:)
+        @navigator = navigator
+        @width = width
+        @height = height
+      end
+
+      def lines
+        return [status].first(height) if height < CHROME_HEIGHT + 1
+
+        [title, *panes, status, button_bar]
+      end
+
+      def files_width
+        (width / 3).clamp(FILES_WIDTH.begin, [FILES_WIDTH.end, width / 2].min)
+      end
+
+      private
+
+      def title
+        path = navigator.path ? navigator.relative(navigator.path) : 'No Markdown files'
+        [segment(" raindown  #{File.basename(navigator.root)}  #{path}", :title)]
+      end
+
+      def panes
+        pane_height = height - CHROME_HEIGHT
+        files = navigator.visible(:files, pane_height)
+        outline = navigator.visible(:outline, pane_height)
+
+        Array.new(pane_height) do |index|
+          [*cell(:files, *files, index, files_width), Segment.new(text: '│', style: :border, event: nil),
+           *cell(:outline, *outline, index, width - files_width - 1)]
+        end
+      end
+
+      # A pane's row as its text, then its buttons, or blank below its last row.
+      def cell(pane, rows, offset, index, cell_width)
+        row = rows[index]
+        return [segment('', :blank, width: cell_width)] unless row
+
+        index += offset
+        selected = navigator.cursor(pane) == index
+        buttons = row_buttons(row, pane:, index:, selected:, cell_width:)
+        text_width = cell_width - display_width(buttons.map(&:text).join)
+        text = " #{INDENT * row.depth}#{row.text}"
+
+        [segment(text, row_style(pane, row, selected), width: text_width, event: [:select, pane, index]), *buttons]
+      end
+
+      # The row's buttons, right of its text, unless they'd take more than half the pane.
+      def row_buttons(row, pane:, index:, selected:, cell_width:)
+        buttons = row.buttons.map do |label, event|
+          Segment.new(text: " #{label}", style: selected ? :selected_button : :button, event: [:press, pane, index, event])
+        end
+        display_width(buttons.map(&:text).join) > cell_width / 2 ? [] : buttons
+      end
+
+      def row_style(pane, row, selected)
+        return row.kind unless selected
+
+        navigator.focus == pane ? :selected : :cursor
+      end
+
+      def status
+        kind, message = navigator.status
+        [segment(" #{message}", kind)]
+      end
+
+      # As many buttons as fit, each clicked by its key or its label.
+      def button_bar
+        segments = []
+        used = 0
+
+        BUTTONS.each do |key, label, event|
+          pair = [Segment.new(text: " #{key} ", style: :key, event:), Segment.new(text: "#{label} ", style: :bar, event:)]
+          pair_width = display_width(pair.map(&:text).join)
+          break if used + pair_width > width
+
+          segments.concat(pair)
+          used += pair_width
+        end
+
+        [*segments, segment('', :bar, width: width - used)]
+      end
+
+      # Text cut or padded to the width, with a cut shown by an ellipsis.
+      def segment(text, style, width: self.width, event: nil)
+        Segment.new(text: fit(printable(text), width), style:, event:)
+      end
+
+      def fit(text, width)
+        return '' if width <= 0
+        return text + (' ' * (width - display_width(text))) if display_width(text) <= width
+
+        cut = +''
+        cut_width = 0
+        text.each_char do |char|
+          break if cut_width + display_width(char) > width - 1
+
+          cut << char
+          cut_width += display_width(char)
+        end
+        "#{cut}…#{' ' * (width - 1 - cut_width)}"
+      end
+
+      # Tabs and control characters, like in a directive's output, would move the terminal's cursor.
+      def printable(text)
+        text.gsub("\t", INDENT).gsub(/[[:cntrl:]]/, '')
+      end
+
+      def display_width(text)
+        Unicode::DisplayWidth.of(text)
+      end
+    end
+  end
+end

data/lib/raindown/tui/navigator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative 'file_tree'
+require_relative 'commands'
+require_relative 'outline'
+require_relative 'pane'
+
+module Raindown
+  module TUI
+    # What the terminal UI shows and does, in plain Ruby, with no terminal: a FileTree of the project's Markdown files,
+    # beside the open file's Outline. The Screen draws it and sends it events, like :down or
+    # [:press, :outline, 3, :execute], and handle returns what the Screen should do next:
+    #   nil                     draw again
+    #   :quit                   stop
+    #   [:run, command]         leave the screen to run a command, like the editor, then call ran
+    #   [:wait, message, task]  show the message while the task runs, like an endpoint's request
+    class Navigator
+      include Commands
+
+      # Keys of the events that move the cursor or the focus, and those that act on what's selected.
+      MOVES = { up: -1, down: 1 }.freeze
+      PANES = { tab: nil, left: :files, right: :outline }.freeze
+      ACTIONS = { execute: :execute, edit: :edit, write_back: :write_back, reload: :reload, tick: :refresh }.freeze
+
+      attr_reader :focus, :status
+
+      def initialize(root:, path: nil)
+        @files = FileTree.new(root:)
+        @focus = :files
+        @panes = { files: Pane.new { @files.rows }, outline: Pane.new { @outline ? @outline.rows : [] } }
+        @status = [:info, 'Tab switches panes, Enter opens and folds, q quits']
+        first = @files.rows.find { it.kind == :file }&.target
+        show(path || first) if path || first
+      end
+
+      def handle(event)
+        name, *args = event
+        return :quit if name == :quit
+        return move(MOVES[name]) if MOVES.key?(name)
+        return switch(PANES[name] || other_pane) if PANES.key?(name)
+        return select(*args) if name == :select
+        return press(*args) if name == :press
+        return activate(name) if %i[enter toggle].include?(name)
+
+        send(ACTIONS[name]) if ACTIONS.key?(name)
+      end
+
+      # After the editor closes, the file is written back, like a save while it's watched, and read again.
+      def ran
+        write_back
+      end
+
+      def root = @files.root
+      def path = @outline&.path
+      def relative(path) = @files.relative(path)
+
+      def rows(pane) = @panes[pane].rows
+      def cursor(pane) = @panes[pane].cursor
+      def visible(pane, height) = @panes[pane].visible(height)
+
+      private
+
+      def show(path)
+        @outline = Outline.new(File.expand_path(path))
+        @panes[:outline].reset
+      end
+
+      def other_pane
+        @focus == :files ? :outline : :files
+      end
+
+      def move(by)
+        @panes[@focus].move(by)
+        nil
+      end
+
+      def switch(pane)
+        @focus = pane
+        nil
+      end
+
+      def select(pane, index)
+        @focus = pane
+        @panes[pane].cursor = index
+        nil
+      end
+
+      def press(pane, index, event)
+        select(pane, index)
+        handle(event)
+      end
+
+      def selected(pane = @focus)
+        @panes[pane].selected
+      end
+
+      # Enter opens what's selected, or folds it, and Space only folds.
+      # A line of output, or a directive without any, opens in the editor.
+      def activate(name)
+        row = selected
+        return edit if name == :enter && editable?(row)
+
+        case row&.kind
+        when :folder then @files.toggle(row.target)
+        when :file then open_file(row.target) if name == :enter
+        when :heading then @outline.fold(row.target)
+        when :directive then @outline.expand(row.target) if row.target.output
+        end
+        nil
+      end
+
+      def editable?(row)
+        row&.kind == :output || (row&.kind == :directive && !row.target.output)
+      end
+
+      def open_file(path)
+        show(path)
+        @focus = :outline
+        info("Opened #{relative(path)}")
+      end
+    end
+  end
+end