raindown 0.1.0 → 0.2.1

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative '../bare_directives'
+require_relative '../code_blocks'
+require_relative 'curl'
+
+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.
+  #   <{ endpoint: :x }>
+  #   ```sh
+  #   curl https://api.example.com
+  #   ```
+  #   ```json
+  #   { "id": 1 }
+  #   ```
+  #   <!-- raindown:fetched 2026-10-14 -->
+  #   <{ :endpoint }>
+  class EndpointRunner
+    DIRECTIVE = /\A {0,3}<\{\s*endpoint:(.*?)\}>[ \t]*$/
+    EXECUTE_ARGS = %w[:x :execute].freeze
+    # The date a response was fetched, on the line after it.
+    FETCHED = /\A {0,3}<!-- raindown:fetched [^\n]*? -->[ \t]*$/
+
+    def self.rewrite(content:, path: nil, bare: false, execute: false, **)
+      new(content:, bare: BareDirectives.enabled?(path:, bare:), execute:).rewrite
+    end
+
+    def initialize(content:, bare: false, execute: false)
+      @lines = content.lines
+      @bare = bare
+      @execute = execute
+    end
+
+    def rewrite
+      index = 0
+
+      while index < @lines.length
+        if (block = CodeBlocks.at(@lines, index))
+          index = block[:close]
+        elsif (args = directive_args(@lines[index]))
+          index = fill(index + 1, args)
+        end
+
+        index += 1
+      end
+
+      @lines.join
+    end
+
+    private
+
+    def directive_args(line)
+      line = BareDirectives.wrap(line) || line if @bare
+      line[DIRECTIVE, 1]&.split
+    end
+
+    # Returns the index of the last line it handled.
+    def fill(index, args)
+      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)
+
+      write_output(curl:, output:)
+    end
+
+    def execute?(args)
+      @execute || args.intersect?(EXECUTE_ARGS)
+    end
+
+    # Replaces the output block and the date it was fetched, or with no block, replaces nothing just after the curl block.
+    def write_output(curl:, output:)
+      block = [*output_block(*Curl.run(curl[:body])), fetched]
+      block.unshift("\n") unless output
+      start = output ? output[:open] : curl[:close] + 1
+
+      @lines[start, output ? replaced_length(output) : 0] = block
+      start + block.length - 1
+    rescue Curl::Error => e
+      warn "Endpoint failed: #{e.message}"
+      curl[:close]
+    end
+
+    # The output block, and the line after it when that's the date it was last fetched.
+    def replaced_length(output)
+      length = output[:close] - output[:open] + 1
+      @lines[output[:close] + 1]&.match?(FETCHED) ? length + 1 : length
+    end
+
+    def fetched
+      "<!-- raindown:fetched #{Date.today.iso8601} -->\n"
+    end
+
+    # The fence is longer than any run of backticks in the body, so the body can't close it.
+    def output_block(body, language)
+      fence = '`' * [3, (body.scan(/`+/).map(&:length).max || 0) + 1].max
+
+      ["#{fence}#{language}\n", *"#{body.chomp}\n".lines, "#{fence}\n"]
+    end
+  end
+end

data/lib/raindown/files.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+
+module Raindown
+  # The node behind files:, a list of links to the files the metadata has for its props, like files: folder: 'notes'.
+  # A project can change how files are listed with its own Files node in .raindown, like "class Files < Raindown::Files".
+  class Files < Node
+    def initialize(**tags)
+      @tags = tags
+    end
+
+    # Each file has its front matter, its path and its content.
+    def files(metadata: NoMetadata)
+      metadata.list(**@tags)
+    end
+
+    def replace(metadata: NoMetadata)
+      files(metadata:).map { |file| "- [#{file.title || file.path}](#{file.path})" }.join("\n")
+    end
+  end
+end

data/lib/raindown/fragments.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Raindown
+  # The HTML of components rendered while a document renders, kept out of its Markdown as placeholders
+  # so Commonmarker doesn't read it as Markdown, then filled in once the document is HTML.
+  module Fragments
+    PLACEHOLDER = /<!-- raindown:fragment (\d+) -->/
+
+    module_function
+
+    # Collects the fragments added while the block runs, like one document's render.
+    def collect
+      outer = Thread.current[:raindown_fragments]
+      Thread.current[:raindown_fragments] = []
+      yield
+    ensure
+      Thread.current[:raindown_fragments] = outer
+    end
+
+    def add(html)
+      list << html
+      "<!-- raindown:fragment #{list.length - 1} -->"
+    end
+
+    # Fills each placeholder, again and again, since a fragment can hold others, like a component in a slot.
+    def fill(html)
+      html = html.gsub(PLACEHOLDER) { list[::Regexp.last_match(1).to_i] } while html.match?(PLACEHOLDER)
+      html
+    end
+
+    def list
+      Thread.current[:raindown_fragments] ||= []
+    end
+  end
+end

data/lib/raindown/front_matter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'yaml'
+
+module Raindown
+  # YAML between two --- lines at the very start of a file.
+  module FrontMatter
+    PATTERN = /\A---[ \t]*\r?\n(.*?)^---[ \t]*(?:\r?\n|\z)/m
+
+    module_function
+
+    # Returns the metadata and the Markdown after it.
+    def parse(content)
+      match = content.match(PATTERN)
+      return [{}, content] if match.nil?
+
+      metadata = YAML.safe_load(match[1], permitted_classes: [Date, Time], symbolize_names: true)
+      [metadata.is_a?(Hash) ? metadata : {}, match.post_match]
+    end
+
+    # How many of the lines are front matter, so directives in its YAML are left alone.
+    def line_count(lines)
+      lines.join.match(PATTERN)&.then { |match| match[0].lines.length } || 0
+    end
+  end
+end

data/lib/raindown/heading_ids.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Raindown
+  # Commonmarker gives each heading a unique id within what it renders, but a document's components render
+  # on their own, so two can have a heading with the same id. Later ones get -1, -2 and so on, like Commonmarker.
+  module HeadingIds
+    HEADING = %r{<h([1-6]) id="([^"]*)"(.*?)</h\1>}m
+
+    module_function
+
+    def unique(html)
+      seen = Hash.new(0)
+
+      html.gsub(HEADING) do
+        level, id, rest = ::Regexp.last_match.captures
+        count = seen[id]
+        seen[id] += 1
+        next ::Regexp.last_match(0) if count.zero?
+
+        unique_id = "#{id}-#{count}"
+        "<h#{level} id=\"#{unique_id}\"#{rest.gsub("href=\"##{id}\"", "href=\"##{unique_id}\"")}</h#{level}>"
+      end
+    end
+  end
+end

data/lib/raindown/node.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Raindown
+  # The base class of Raindown's own nodes, like TOC and Files.
+  # A project's nodes are LowNodes, or subclasses of these.
+  class Node; end
+end

data/lib/raindown/node_blocks.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'code_blocks'
+require_relative 'directives'
+require_relative 'front_matter'
+require_relative 'nodes'
+
+module Raindown
+  # Finds node blocks in a file's lines: a node's directive and the Markdown it wrote below it.
+  # With delimiters the block ends with the node's end tag, and without them at the next blank line:
+  #   <{ Changelog: limit=3 }>          Changelog: limit=3
+  #                                     - **1.2.0** Bare directives
+  #   - **1.2.0** Bare directives
+  #
+  #   <{ :Changelog }>
+  # A self-closing <{ :Changelog }> or bare :Changelog that doesn't end a block renders the node without writing it.
+  # toc: and files: are Raindown's own nodes. A name only starts a block when it's a loaded node,
+  # so other text like "Note:" is left alone.
+  module NodeBlocks
+    class MissingEndTag < StandardError; end
+
+    NAME = "(?:#{Nodes::BUILT_INS.keys.join('|')}|[A-Z]\\w*(?:::[A-Z]\\w*)*)".freeze
+    OPEN = /\A( {0,3})<\{\s*(#{NAME}):(?:\s+(.*?))?\s*\}>[ \t]*$/
+    BARE_OPEN = /\A( {0,3})(#{NAME}):(?:[ \t]+(.*?))?[ \t]*$/
+    SELF_CLOSING = /\A( {0,3})<\{\s*:(#{NAME})(?:\s+(.*?))?\s*\}>[ \t]*$/
+    BARE_SELF_CLOSING = /\A( {0,3}):(#{NAME})(?:[ \t]+(.*?))?[ \t]*$/
+    # A prop is name=value or name: value, where the value is quoted text, a number, true, false
+    # or a front matter key like author.name.
+    PROP = /(\w+)(?:=|:[ \t]+)("[^"]*"|'[^']*'|\S+)/
+
+    module_function
+
+    # 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 = []
+      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]
+        end
+
+        index += 1
+      end
+
+      blocks
+    end
+
+    # Swaps each block for its node's HTML, through a placeholder, or for its Markdown when it has no HTML of its own.
+    # The directive and end tag become Directives markers, which also keep the node's output from joining
+    # the Markdown around it, like two lists becoming one.
+    def to_rendered(markdown, metadata: NoMetadata, bare: false)
+      lines = markdown.lines
+      find(lines, front_matter: FrontMatter.parse(markdown).first, bare:).reverse_each do |block|
+        lines[block[:open]..block[:last]] = rendered_lines(lines, block, markdown:, metadata:, bare:)
+      end
+      lines.join
+    end
+
+    def rendered_lines(lines, block, markdown:, metadata:, bare:)
+      node = block[:node]
+      output = if Nodes.html?(node) then ["#{Nodes.placeholder(node)}\n"]
+               else "#{Nodes.call(node, :replace, document: markdown, metadata:, bare:).to_s.chomp}\n".lines
+               end
+      output = [] if output == ["\n"]
+
+      [marker(lines[block[:open]]), *output, *(marker(lines[block[:close]]) if block[:close])]
+    end
+
+    def marker(line)
+      "#{Directives.marker(line)}\n"
+    end
+
+    def block_at(lines, index, front_matter:, bare:)
+      found, pattern = directive(lines[index], bare:)
+      return unless found && (klass = Nodes.node_class(found[2]))
+
+      node = Nodes.instance(klass, props(found[3].to_s, front_matter))
+      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 }
+      end
+    end
+
+    # The directive on the line and which kind it is, or nil.
+    def directive(line, bare:)
+      patterns = { open: OPEN, self_closing: SELF_CLOSING }
+      patterns.merge!(bare_open: BARE_OPEN, bare_self_closing: BARE_SELF_CLOSING) if bare
+
+      patterns.each do |pattern, regexp|
+        match = line.match(regexp)
+        return [match, pattern] if match
+      end
+
+      nil
+    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)
+      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: }
+    end
+
+    def end_tag(lines, open, name)
+      tag = /\A {0,3}<\{\s*:#{Regexp.escape(name)}\s*\}>[ \t]*$/
+      close = (open + 1...lines.length).find { |index| lines[index].match?(tag) }
+      raise MissingEndTag, "<{ #{name}: }> on line #{open + 1} needs <{ :#{name} }>" unless close
+
+      close
+    end
+
+    def props(text, front_matter)
+      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, front_matter)] }
+    end
+
+    def value(value, front_matter)
+      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 value.split('.').reduce(front_matter) { |data, key| data.is_a?(Hash) ? data[key.to_sym] : nil }
+      end
+    end
+  end
+end

data/lib/raindown/node_injector.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative '../raindown'
+require_relative 'bare_directives'
+require_relative 'front_matter'
+require_relative 'node_blocks'
+
+module Raindown
+  # Writes each node block's Markdown below its directive, replacing what it wrote before.
+  # Self-closing nodes only render, so they're left alone.
+  class NodeInjector
+    class BlankLine < StandardError; end
+
+    # Rewriter interface. Content without a node block is returned unchanged.
+    def self.rewrite(content:, path: nil, bare: false, metadata: NoMetadata, **)
+      new(content:, path:, bare:, metadata:).call
+    end
+
+    def initialize(content:, path: nil, bare: false, metadata: NoMetadata)
+      @content = content
+      @bare = BareDirectives.enabled?(path:, bare:)
+      @metadata = metadata
+    end
+
+    def call
+      lines = @content.lines
+      blocks = NodeBlocks.find(lines, front_matter: FrontMatter.parse(@content).first, bare: @bare)
+                         .reject { |block| block[:self_closing] }
+      return @content if blocks.empty?
+
+      blocks.reverse_each { |block| lines[block[:open]..block[:last]] = block_lines(lines, block) }
+      lines.join
+    end
+
+    private
+
+    def block_lines(lines, block)
+      markdown = Nodes.call(block[:node], :replace, document: @content, metadata: @metadata, bare: @bare).to_s.chomp
+      written = markdown.empty? ? [] : "#{markdown}\n".lines
+      return [line(lines[block[:open]]), *bare(written, block)] unless block[:close]
+
+      delimited(lines, block, written)
+    end
+
+    # The directive, what the node wrote and the end tag, each separated by a blank line.
+    def delimited(lines, block, written)
+      result = [line(lines[block[:open]])]
+      result.push("\n", *written) unless written.empty?
+      result.push("\n", line(lines[block[:close]]))
+    end
+
+    # A bare block ends at the next blank line, so what it writes can't have one.
+    def bare(written, block)
+      return written unless written.any? { |line| line.strip.empty? }
+
+      name = block[:node].class.name
+      raise BlankLine, "#{name} writes blank lines, so it needs <{ #{name}: }> and <{ :#{name} }> around it"
+    end
+
+    def line(line)
+      line.end_with?("\n") ? line : "#{line}\n"
+    end
+  end
+end

data/lib/raindown/nodes.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative 'files'
+require_relative 'node'
+require_relative 'toc'
+
+module Raindown
+  # Nodes are LowNodes that a node block writes into the Markdown and renders into the HTML.
+  # A project keeps them in a .raindown folder, which is loaded with Dirload.
+  # A node writes Markdown with #replace, and HTML with #render if it has one. Either can take the keywords
+  # document: (the Markdown being rendered), metadata: and bare:, and gets the ones it asks for.
+  module Nodes
+    FOLDER = '.raindown'
+    # Lowercase directives for Raindown's own nodes. A project's own TOC or Files node replaces Raindown's.
+    BUILT_INS = { 'toc' => 'TOC', 'files' => 'Files' }.freeze
+    # A placeholder for a node's HTML, which stays as it is through Commonmarker and Antlers.
+    PLACEHOLDER = /<!-- raindown:node (\d+) -->/
+
+    module_function
+
+    # Loads the .raindown folder beside the file or in the nearest directory above it, once per process.
+    def load(path)
+      folder = find_folder(File.dirname(File.expand_path(path)))
+      return if folder.nil? || loaded.include?(folder)
+
+      require 'lownode'
+      require 'dirload'
+      loaded << folder
+      dirload(folder)
+    end
+
+    def find_folder(directory)
+      loop do
+        folder = File.join(directory, FOLDER)
+        return folder if File.directory?(folder)
+
+        parent = File.dirname(directory)
+        return if parent == directory
+
+        directory = parent
+      end
+    end
+
+    def loaded
+      @loaded ||= []
+    end
+
+    # The node class a block names, when it's loaded.
+    def node_class(name)
+      return loaded_class(name) unless BUILT_INS.key?(name)
+
+      loaded_class(BUILT_INS[name]) || Raindown.const_get(BUILT_INS[name])
+    end
+
+    def loaded_class(name)
+      klass = Object.const_get(name)
+      klass if node?(klass)
+    rescue NameError
+      nil
+    end
+
+    # A LowNode, or one of Raindown's own nodes, that writes Markdown. In an app, LowNodes are also routes and pages,
+    # which don't have replace, so text like "Note:" only starts a block when the Note node writes something.
+    def node?(klass)
+      return false unless klass.is_a?(Class) && klass.method_defined?(:replace)
+
+      klass < Node || (defined?(::LowNode) && klass < ::LowNode) || false
+    end
+
+    # Calls a node's replace or render with the context keywords it takes.
+    def call(node, name, **context)
+      parameters = node.method(name).parameters
+      return node.public_send(name, **context) if parameters.any? { |type, _| type == :keyrest }
+
+      keys = parameters.filter_map { |type, key| key if %i[key keyreq].include?(type) }
+      node.public_send(name, **context.slice(*keys))
+    end
+
+    # One instance for each node and its props, kept for the whole process.
+    # So a node can keep what its Markdown and HTML share, like a date, and both stay the same between renders.
+    def instance(klass, props)
+      key = [klass, props]
+      instances[key] ||= begin
+        id = list.length
+        list << klass.new(**props)
+        id
+      end
+
+      list[instances[key]]
+    end
+
+    def placeholder(node)
+      "<!-- raindown:node #{list.index(node)} -->"
+    end
+
+    # Swaps each placeholder for its node's HTML.
+    def render_placeholders(html, **context)
+      html.gsub(PLACEHOLDER) { html(list[::Regexp.last_match(1).to_i], **context) }
+    end
+
+    def html(node, **context)
+      return node.render_template(props: {}).to_s if node.class.respond_to?(:template) && node.class.template
+
+      call(node, :render, **context).to_s
+    end
+
+    # Whether the node renders its own HTML rather than the HTML of its Markdown.
+    def html?(node)
+      node.respond_to?(:render) || (node.class.respond_to?(:template) && !node.class.template.nil?)
+    end
+
+    def instances
+      @instances ||= {}
+    end
+
+    def list
+      @list ||= []
+    end
+  end
+end

data/lib/raindown/page.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Raindown
+  # A file that Pages lists: its front matter and implicit metadata, like page.title, page.folder,
+  # page.order and page.path, and its content rendered to HTML when it's asked for.
+  class Page
+    attr_reader :file_path, :metadata
+
+    def initialize(file_path:, metadata:, render_options: {})
+      @file_path = file_path
+      @metadata = metadata
+      @render_options = render_options
+    end
+
+    # Rendered when asked for, so a file that lists itself doesn't render forever.
+    # The front matter is rendered with it, so its variables work, and a Raindown file's bare directives too.
+    def content
+      @content ||= begin
+        markdown = File.read(file_path)
+
+        if FrontMatter.parse(markdown).last.strip.empty? then ''
+        else Raindown.render(markdown:, bare: BareDirectives.file?(file_path), **@render_options)
+        end
+      end
+    end
+
+    def [](key)
+      key.to_sym == :content ? content : metadata[key.to_sym]
+    end
+
+    def respond_to_missing?(name, include_all = false)
+      metadata.key?(name) || super
+    end
+
+    # Unknown keys are nil, like front matter a file doesn't have.
+    def method_missing(name, *args)
+      return super unless args.empty? && !name.end_with?('=', '?', '!')
+
+      metadata[name]
+    end
+  end
+end