raindown 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee322a9f4df788bddfb51b6d669a7a676574620ecd1ce30e69a5682d49b8c88e
-  data.tar.gz: 2bb5f698d9c5e90f0c44271e4b1529512dab858dcd07beb04061ac8690a81bff
+  metadata.gz: ae1eb87d8271ddcfcc3fb956311e11229421188a33f5bd7e0af70cffd2f49719
+  data.tar.gz: 380a98d835cfa9de899c5870828ba157e89aa0d3a4b8621a495f1a0ecd1e9bf6
 SHA512:
-  metadata.gz: e550608449c87c693edef3c249472a89c62618de92941b81e135250462bbc74a062b61b2e025ea8666ff571b5057a25b67a13ed6fb385f304e500448f09a3034
-  data.tar.gz: a60db4e479d593ea779e93c3c683401519599ac0bf1d07f6f1e2a280634eff26b5f46167f27d5ce24fcd08f54660cb4051ed21e0c422951247a8f3d2c53938a7
+  metadata.gz: b3e74f64840850c572446865664e5368915df5065f09e9483d530d58392acb13f0e20ce872b9f8ee1930154af82d4c3baf8bf6fbd7c370399315e3b7a3a3b480
+  data.tar.gz: '09a95ee90ef2568aff8c783ecee3b2ac06590f0a71f1bde6e14e99e7e8f5c6e05776ca6ff3c7dcce22fd55a56e456273ecb0de2475fceb0785a312a022cd48fa'

data/lib/raindown/actions.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+require_relative '../raindown'
+require_relative 'bare_directives'
+require_relative 'endpoint/endpoint_runner'
+require_relative 'rewriter'
+
+module Raindown
+  # What a tool can do to a file from its Document, like the terminal UI, without knowing how it's drawn.
+  # Each returns true when the file changed, and raises when it can't, for the tool to show.
+  module Actions
+    class NotAnEndpoint < StandardError; end
+
+    # Editors that open a file at a line with "path:line" rather than "+line path".
+    PATH_LINE_EDITORS = %w[hx helix subl zed].freeze
+    # Editors that need -g before "path:line", and --wait so the tool waits for the file to close.
+    GOTO_EDITORS = %w[code codium cursor windsurf].freeze
+
+    module_function
+
+    # Writes back the whole file, like saving it while it's watched.
+    def write_back(path)
+      Rewriter.update(path:, metadata: Pages.for(path))
+    end
+
+    # Runs one endpoint's request and writes its response, replacing any response it had.
+    def execute(path, directive)
+      raise NotAnEndpoint, "#{directive.name} on line #{directive.line} isn't an endpoint" unless directive.endpoint?
+
+      content = File.read(path, encoding: Encoding::UTF_8)
+      rewritten = EndpointRunner.new(content:, bare: BareDirectives.file?(path), only: directive.line - 1).rewrite
+      return false if rewritten == content
+
+      File.write(path, rewritten)
+      true
+    end
+
+    # The command that opens the file at a line in the person's editor, like ["vim", "+12", "notes.md"].
+    def edit_command(path, line:, editor: ENV['VISUAL'] || ENV['EDITOR'] || 'vi')
+      command = Shellwords.split(editor)
+      name = File.basename(command.first)
+
+      if GOTO_EDITORS.include?(name)
+        [*command, *('--wait' unless command.include?('--wait')), '-g', "#{path}:#{line}"]
+      elsif PATH_LINE_EDITORS.include?(name)
+        [*command, "#{path}:#{line}"]
+      else
+        [*command, "+#{line}", path]
+      end
+    end
+  end
+end

data/lib/raindown/cli.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require 'fileutils'
 require 'trees'
 require_relative '../raindown'
+require_relative '../version'
 require_relative 'rewriter'
+require_relative 'supervisor'
 require_relative 'watcher'
 
 module Raindown
@@ -10,22 +13,44 @@ module Raindown
     extend Trees
 
     USAGE = <<~TEXT
-      Usage: raindown FILE [options]
+      Usage: raindown [PATH] [options]
+             raindown FILE --html [OUTPUT]
+             raindown init [DIRECTORY]
+             raindown tui [PATH]
 
-      Renders FILE to HTML, then re-renders it every time it is saved.
+      Watches PATH and writes back to its Markdown files as they're saved, like their tables of contents and tables.
+      PATH is a file, or a directory (default: current directory) whose projects with a .raindown folder are watched.
+
+      Commands:
+        init [DIRECTORY]    Create a .raindown folder for the project's config and nodes (default: current directory)
+        tui [PATH]          Browse a project's files and outlines in the terminal, fold directives, run endpoints
+                            and open the editor at a line
 
       Options:
-        -o, --output PATH   Write output to PATH instead of FILE.html beside FILE
-        --once              Render once without watching, printing to stdout unless -o is given
-        --stdin             Render Markdown from stdin once, without formatting FILE, which only needs
-                            its extension (to allow bare directives) and can be unsaved
+        --html [OUTPUT]     Render FILE to HTML once, writing to OUTPUT or else printing to stdout
+        --stdin             Render Markdown from stdin to HTML once, without formatting FILE, which only needs
+                            its extension (to allow bare directives) and can be unsaved. Add --html OUTPUT to write a file
         --bare              Allow bare directives like :toc in Markdown files
         -x, --execute       Run endpoint curl snippets that have no output yet
         -h, --help          Show this message
+        -v, --version       Show the version
+
+      Set RAINDOWN_DEBUG=1 to show where an error happened.
     TEXT
 
-    OPTIONS = { output: ['-o :output', '--output :output'], bare: ['--bare'], execute: ['-x', '--execute'],
-                once: ['--once'], stdin: ['--stdin'] }.freeze
+    CONFIG = <<~YAML
+      # Raindown project settings. See https://raindown.dev/docs/config
+      #
+      # Show directives as HTML comments rather than in bold:
+      # hide_directives: true
+      #
+      # Leave code blocks unhighlighted, so the browser can highlight them instead:
+      # highlight_code: false
+    YAML
+
+    # "--html OUTPUT" is matched as "--html-to OUTPUT" (see run), so a flag after a bare --html isn't read as the OUTPUT.
+    OPTIONS = { html_to: ['--html-to :output'], html: ['--html'], bare: ['--bare'], execute: ['-x', '--execute'],
+                stdin: ['--stdin'] }.freeze
 
     # Trees matches tokens in order, so there's a line for every order and spelling of the options.
     OPTION_LINES = (0..OPTIONS.size).flat_map { |count| OPTIONS.keys.permutation(count).to_a }.flat_map do |names|
@@ -35,26 +60,82 @@ module Raindown
     OPTION_LINES.each do |names, flags|
       # Endpoints run while formatting, which --stdin skips.
       next if names.include?(:stdin) && names.include?(:execute)
+      next if names.include?(:html) && names.include?(:html_to)
 
       command = if names.include?(:stdin) then :render_stdin
-                elsif names.include?(:once) then :render
+                elsif names.intersect?(%i[html html_to]) then :render
                 else :watch
                 end
       options = { bare: names.include?(:bare), execute: names.include?(:execute) }
       pattern = [':path', *flags].join(' ')
 
-      if names.include?(:output)
+      if names.include?(:html_to)
         line(pattern) { |path, output| execute { send(command, path, output, **options) } }
       else
         line(pattern) { |path| execute { send(command, path, **options) } }
       end
     end
 
-    # The :path line would match a help flag as the file, so help is checked first.
     def self.run(argv)
-      abort(USAGE) if argv.empty? || argv.intersect?(%w[-h --help])
+      return if command(argv)
+
+      # Without a path, like "raindown" or "raindown -x", the current directory is watched.
+      argv = ['.', *argv] if argv.empty? || argv.first.start_with?('-')
+      argv = html_output(argv)
 
       super || abort("Unknown arguments: #{argv.join(' ')}\n\n#{USAGE}")
+    rescue StandardError => e
+      report(e, path: argv.first)
+    end
+
+    # The :path line would match help, version, init and tui as the file, so they're checked first.
+    # Returns true when argv was one of them.
+    def self.command(argv)
+      abort(USAGE) if argv.intersect?(%w[-h --help])
+
+      if argv.intersect?(%w[-v --version]) then puts(VERSION)
+      elsif argv.first == 'init' && argv.size <= 2 then init(argv[1])
+      elsif argv.first == 'tui' && argv.size <= 2 then tui(argv[1] || '.')
+      else return false
+      end
+
+      true
+    end
+
+    # Shows an error in a file as one line, rather than a backtrace, unless RAINDOWN_DEBUG is set.
+    def self.report(error, path:)
+      raise error if ENV['RAINDOWN_DEBUG']
+
+      abort("raindown: #{path}: #{error.message}")
+    end
+
+    # "--html out.html" names an OUTPUT, while "--html --bare" doesn't, as OUTPUT never starts with "-".
+    def self.html_output(argv)
+      index = argv.index('--html') || (return argv)
+      output = argv[index + 1]
+      return argv if output.nil? || output.start_with?('-')
+
+      [*argv[0...index], '--html-to', *argv[(index + 1)..]]
+    end
+
+    # Creates the .raindown folder that marks a project's root and holds its config.yml and nodes.
+    def self.init(directory = nil)
+      folder = File.join(directory || Dir.pwd, Nodes::FOLDER)
+      config = File.join(folder, Config::FILE)
+      return puts("#{config} already exists") if File.exist?(config)
+
+      FileUtils.mkdir_p(folder)
+      File.write(config, CONFIG)
+      puts "Created #{config}"
+      puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/nodes'
+    end
+
+    # The terminal UI loads curses, so it's only required when it starts.
+    def self.tui(path)
+      abort("File not found: #{path}") unless File.exist?(path)
+
+      require_relative 'tui'
+      TUI.start(path)
     end
 
     class << self
@@ -62,6 +143,7 @@ module Raindown
 
       def render(path, output = nil, bare: false, execute: false)
         ensure_exists(path)
+        abort('--html renders a file, not a directory') if File.directory?(path)
         Nodes.load(path)
 
         metadata = Pages.for(path)
@@ -75,11 +157,13 @@ module Raindown
                                       **Config.render_options(path)))
       end
 
-      def watch(path, output = nil, bare: false, execute: false)
+      # Watching only writes back to the files, while --html and --stdin render HTML.
+      def watch(path, bare: false, execute: false)
         ensure_exists(path)
-        Nodes.load(path)
+        return Supervisor.new(directory: path, bare:, execute:).start if File.directory?(path)
 
-        Watcher.new(path:, output:, bare:, execute:).start
+        Nodes.load(path)
+        Watcher.new(path:, bare:, execute:).start
       end
 
       def write(output, html)

data/lib/raindown/directives.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'erb'
+require 'cgi/escape'
 
 module Raindown
   # Content directives, like a node's directive and end tag or an endpoint's, are kept in the HTML:
@@ -22,7 +22,7 @@ module Raindown
     def render(html, hide: false)
       html.gsub(MARKER) do
         text = ::Regexp.last_match(1)
-        hide ? "<!-- #{text} -->" : "<p><strong>#{ERB::Util.html_escape(text)}</strong></p>"
+        hide ? "<!-- #{text} -->" : "<p><strong>#{CGI.escapeHTML(text.to_s)}</strong></p>"
       end
     end
   end

data/lib/raindown/document.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'commonmarker'
+
+require_relative 'bare_directives'
+require_relative 'code_blocks'
+require_relative 'endpoint/endpoint_runner'
+require_relative 'front_matter'
+require_relative 'node_blocks'
+
+module Raindown
+  # A Markdown file's structure, read from its source so each part has the line it's on, for tools like an editor.
+  # Headings that a directive writes back below it are in the source too, while ones a node only renders as HTML aren't.
+  # Lines count from 1, from the top of the file.
+  class Document
+    Heading = Data.define(:level, :text, :line)
+
+    # A content directive: a node, like toc: or a project's Changelog:, or an endpoint.
+    # It spans line to end_line, its end tag, or the last line of a bare block.
+    # Output is the lines Raindown writes back, like a node's Markdown or an endpoint's response, and is nil
+    # when nothing's written yet. A self-closing directive like <{ :toc }> only renders, so it never writes.
+    Directive = Data.define(:name, :args, :line, :end_line, :output, :writes) do
+      def endpoint? = name == 'endpoint'
+    end
+
+    # Inline nodes whose text a reader sees, like code spans, as opposed to inline HTML tags.
+    TEXT_NODES = %i[text code].freeze
+    BREAK_NODES = %i[softbreak linebreak].freeze
+    ENDPOINT_END_TAG = /\A {0,3}<\{\s*:endpoint\s*\}>[ \t]*$/
+
+    def self.parse(markdown, bare: false)
+      new(markdown:, bare:)
+    end
+
+    # Raindown files read bare directives. A project's own nodes are only directives once they're loaded,
+    # like with Nodes.load(path), the same as when the file renders.
+    def self.read(path)
+      new(markdown: File.read(path, encoding: Encoding::UTF_8), bare: BareDirectives.file?(path))
+    end
+
+    def initialize(markdown:, bare: false)
+      @markdown = markdown
+      @lines = markdown.lines
+      @bare = bare
+    end
+
+    # The headings in the order they appear, with their source text, like "Notes for {name}" before it's rendered.
+    def headings
+      @headings ||= nodes(:heading).map do |node|
+        Heading.new(level: node.header_level, text: text(node), line: node.source_position[:start_line])
+      end
+    end
+
+    # The content directives in the order they appear. Template directives like if: and for: aren't here,
+    # since they only change what renders, and write nothing back.
+    def directives
+      @directives ||= (node_directives + endpoint_directives).sort_by(&:line)
+    end
+
+    # The headings and directives together, in the order they appear.
+    def outline
+      (headings + directives).sort_by(&:line)
+    end
+
+    private
+
+    def root
+      @root ||= Commonmarker.parse(@markdown, options: MARKDOWN_OPTIONS)
+    end
+
+    def nodes(type)
+      [].tap { |nodes| root.walk { |node| nodes << node if node.type == type } }
+    end
+
+    def text(heading)
+      parts = []
+      heading.walk do |node|
+        parts << node.string_content if TEXT_NODES.include?(node.type)
+        parts << ' ' if BREAK_NODES.include?(node.type)
+      end
+      parts.join.strip
+    end
+
+    def node_directives
+      NodeBlocks.spans(@lines, bare: @bare).map do |span|
+        output = trimmed(span[:open] + 1, span[:close] ? span[:close] - 1 : span[:last])
+        directive(span[:name], span[:args], span[:open]..span[:last], output:, writes: !span[:self_closing])
+      end
+    end
+
+    def endpoint_directives
+      directives = []
+      index = FrontMatter.line_count(@lines)
+
+      while index < @lines.length
+        if (code = CodeBlocks.at(@lines, index))
+          index = code[:close]
+        elsif (args = endpoint_args(@lines[index]))
+          directives << endpoint(index, args)
+          index = directives.last.end_line - 1
+        end
+
+        index += 1
+      end
+
+      directives
+    end
+
+    def endpoint_args(line)
+      line = BareDirectives.wrap(line) || line if @bare
+      line[EndpointRunner::DIRECTIVE, 1]&.strip
+    end
+
+    # The response and the date it was fetched are the output, while the curl snippet above them is the author's.
+    def endpoint(open, args)
+      curl, response = CodeBlocks.endpoint(@lines, open + 1)
+      output = response && (response[:open]..(fetched?(response[:close] + 1) ? response[:close] + 1 : response[:close]))
+      last = output&.end || curl&.fetch(:close) || open
+      # A bare endpoint, which isn't delimited, ends after its blocks.
+      last = end_tag(after: last) || last if @lines[open].match?(EndpointRunner::DIRECTIVE)
+
+      directive('endpoint', args, open..last, output:, writes: true)
+    end
+
+    def fetched?(index)
+      @lines[index]&.match?(EndpointRunner::FETCHED)
+    end
+
+    # The end tag after the endpoint's blocks, with only blank lines between.
+    def end_tag(after:)
+      index = CodeBlocks.skip_blank_lines(@lines, after + 1)
+      index if @lines[index]&.match?(ENDPOINT_END_TAG)
+    end
+
+    # Lines from first to last with the blank lines around them left out, or nil when there are none.
+    def trimmed(first, last)
+      first += 1 while first <= last && @lines[first].strip.empty?
+      last -= 1 while last >= first && @lines[last].strip.empty?
+      first..last if first <= last
+    end
+
+    # From a range of indexes to line numbers.
+    def directive(name, args, span, output:, writes:)
+      output = (output.begin + 1)..(output.end + 1) if output
+      Directive.new(name:, args:, line: span.begin + 1, end_line: span.end + 1, output:, writes:)
+    end
+  end
+end

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -9,6 +9,7 @@ module Raindown
   # Runs the curl block under an endpoint directive and writes the response in the code block below it,
   # followed by the date it was fetched.
   # Only runs when that block is missing or empty, and the directive has :x/:execute or --execute is passed.
+  # Or with only: and a directive's line index, runs just that endpoint, replacing any response it has.
   #   <{ endpoint: :x }>
   #   ```sh
   #   curl https://api.example.com
@@ -28,10 +29,11 @@ module Raindown
       new(content:, bare: BareDirectives.enabled?(path:, bare:), execute:).rewrite
     end
 
-    def initialize(content:, bare: false, execute: false)
+    def initialize(content:, bare: false, execute: false, only: nil)
       @lines = content.lines
       @bare = bare
       @execute = execute
+      @only = only
     end
 
     def rewrite
@@ -41,7 +43,7 @@ module Raindown
         if (block = CodeBlocks.at(@lines, index))
           index = block[:close]
         elsif (args = directive_args(@lines[index]))
-          index = fill(index + 1, args)
+          index = fill(index + 1, args, directive: index)
         end
 
         index += 1
@@ -58,15 +60,20 @@ module Raindown
     end
 
     # Returns the index of the last line it handled.
-    def fill(index, args)
+    def fill(index, args, directive:)
       curl, output = CodeBlocks.endpoint(@lines, index)
       return index - 1 unless curl&.dig(:body)&.lstrip&.start_with?('curl')
-
-      return curl[:close] if (output && !output[:body].strip.empty?) || !execute?(args)
+      return curl[:close] unless run?(args, output, directive)
 
       write_output(curl:, output:)
     end
 
+    def run?(args, output, directive)
+      return directive == @only if @only
+
+      (output.nil? || output[:body].strip.empty?) && execute?(args)
+    end
+
     def execute?(args)
       @execute || args.intersect?(EXECUTE_ARGS)
     end
@@ -80,6 +87,9 @@ module Raindown
       @lines[start, output ? replaced_length(output) : 0] = block
       start + block.length - 1
     rescue Curl::Error => e
+      # The one endpoint that was asked for fails for the caller to show, like in the terminal UI.
+      raise if @only
+
       warn "Endpoint failed: #{e.message}"
       curl[:close]
     end

data/lib/raindown/node_blocks.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'lowkey'
+
 require_relative 'code_blocks'
 require_relative 'directives'
 require_relative 'front_matter'
@@ -36,21 +38,31 @@ module Raindown
     # Each block outside code and front matter as { open:, close:, last:, node: }, where close is nil for a bare block.
     # A self-closing node is a block of one line with self_closing: true.
     def find(lines, front_matter: {}, bare: false)
-      blocks = []
+      variables = Variables.new(front_matter)
+
+      spans(lines, bare:).map do |span|
+        span.except(:name, :class, :args).merge(node: Nodes.instance(span[:class], *args(span[:args], variables)))
+      end
+    end
+
+    # Each block like find's, with the node's name, class and props text in place of the node,
+    # so a block can be found without making its node, like for a document's outline.
+    def spans(lines, bare: false)
+      spans = []
       index = FrontMatter.line_count(lines)
 
       while index < lines.length
         if (code = CodeBlocks.at(lines, index))
           index = code[:close]
-        elsif (block = block_at(lines, index, front_matter:, bare:))
-          blocks << block
-          index = block[:last]
+        elsif (span = span_at(lines, index, bare:))
+          spans << span
+          index = span[:last]
         end
 
         index += 1
       end
 
-      blocks
+      spans
     end
 
     # Swaps each block for its node's HTML, through a placeholder, or for its Markdown when it has no HTML of its own.
@@ -78,15 +90,15 @@ module Raindown
       "#{Directives.marker(line)}\n"
     end
 
-    def block_at(lines, index, front_matter:, bare:)
+    def span_at(lines, index, bare:)
       found, pattern = directive(lines[index], bare:)
       return unless found && (klass = Nodes.node_class(found[2]))
 
-      node = Nodes.instance(klass, *args(found[3].to_s, Variables.new(front_matter)))
+      span = { name: found[2], class: klass, args: found[3].to_s }
       case pattern
-      when :open then end_tag(lines, index, found[2]).then { |close| { open: index, close:, last: close, node: } }
-      when :bare_open then bare_block(lines, index, node)
-      else { open: index, close: nil, last: index, node:, self_closing: true }
+      when :open then end_tag(lines, index, found[2]).then { |close| { open: index, close:, last: close, **span } }
+      when :bare_open then { **bare_block(lines, index), **span }
+      else { open: index, close: nil, last: index, self_closing: true, **span }
       end
     end
 
@@ -104,11 +116,11 @@ module Raindown
     end
 
     # A bare block holds the lines straight below it, up to the next blank line, with fenced code kept whole.
-    def bare_block(lines, open, node)
+    def bare_block(lines, open)
       last = open
       last = CodeBlocks.at(lines, last + 1)&.fetch(:close) || (last + 1) while lines[last + 1] && !lines[last + 1].strip.empty?
 
-      { open:, close: nil, last:, node: }
+      { open:, close: nil, last: }
     end
 
     def end_tag(lines, open, name)
@@ -131,13 +143,12 @@ module Raindown
       text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, variables)] }
     end
 
+    # A value, like 'text', 3, true, nil or :draft, or else a variable, like author.name.
     def value(value, variables)
-      case value
-      when /\A(["']).*\1\z/ then value[1..-2]
-      when /\A-?\d+\z/ then value.to_i
-      when /\A-?\d+\.\d+\z/ then value.to_f
-      when 'true', 'false' then value == 'true'
-      else Variables.value(variables, value)
+      Lowkey::ValueParser.parse(value) do
+        next value[1..-2] if value.match?(/\A(["']).*\1\z/)
+
+        Variables.value(variables, value)
       end
     end
   end

data/lib/raindown/project_worker.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative '../raindown'
+require_relative 'rewriter'
+
+module Raindown
+  # Writes back to one project's Markdown files as they're saved, like its TOCs, tables and endpoint responses,
+  # with the project's own nodes. Each line it shows starts with the project's name.
+  class ProjectWorker
+    attr_reader :root, :name
+
+    def initialize(root:, name: File.basename(root), bare: false, execute: false)
+      @root = root
+      @name = name
+      @bare = bare
+      @execute = execute
+    end
+
+    # Loads the project's nodes from its .raindown folder.
+    def start
+      Nodes.load(File.join(root, Nodes::FOLDER))
+    rescue StandardError, ScriptError => e
+      raise if ENV['RAINDOWN_DEBUG']
+
+      warn "[#{name}] raindown: #{Nodes::FOLDER}: #{e.message}"
+    end
+
+    # Writing back saves the file again, and that save changes nothing, so it ends there.
+    def update(path)
+      changed = Rewriter.update(path:, bare: @bare, execute: @execute, metadata: Pages.for(path))
+      puts "[#{name}] Updated #{relative(path)}" if changed
+    rescue StandardError => e
+      raise if ENV['RAINDOWN_DEBUG']
+
+      # An error in the file is shown rather than stopping the watcher, so it can be fixed and saved again.
+      warn "[#{name}] raindown: #{relative(path)}: #{e.message}"
+    end
+
+    # Workers in this process have nothing to stop, unlike a ForkedWorker's process.
+    def stop; end
+
+    private
+
+    def relative(path)
+      File.expand_path(path).delete_prefix(File.join(root, ''))
+    end
+  end
+end