boondoc 0.1.0

data/lib/boondoc/links.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Finds the paths in markdown links, images and HTML attributes so they can be rewritten.
+  #
+  # Each path is passed on together with whether it is embedded in the page, as an image, video,
+  # audio, `<source>` or `srcset`, or only linked to. Code blocks and code spans are left alone.
+  module Links
+    # Targets that are not paths in the project: URLs, anchors, absolute paths, and `{references}`.
+    EXTERNAL = %r{\A(?:[a-z][a-z0-9+.-]*:|[#/\{])}i
+    INLINE = /(?<lead>\]\(\s*<?)(?<target>[^)\s>]+)/ # [text](target) and ![alt](target)
+    DEFINITION = /^(?<lead> {0,3}\[(?<label>[^\]]+)\]:\s+<?)(?<target>[^\s>]+)/ # [label]: target
+    ATTRIBUTE = /(?<lead>\b(?<name>src|href|poster|data)=["'])(?<target>[^"']+)/ # <img src="target">
+    SRCSET = /(?<lead>\bsrcset=["'])(?<value>[^"']+)/ # <source srcset="a.png 1x, b.png 2x">
+    SRCSET_ENTRY = /(?<url>[^\s,]+)(?<descriptor>\s+\d[\d.]*[wx])?/
+    IMAGE_REFERENCE = /!\[(?<alt>[^\]]*)\]\[(?<label>[^\]]*)\]/
+    EMBEDDING_ATTRIBUTES = %w[src poster data].freeze
+    IMAGE_OPENING = /!\[(?:[^\[\]]|\[[^\[\]]*\])*\z/ # an image whose alt text is still open
+
+    module_function
+
+    # @param content [String] markdown
+    # @yieldparam target [String] a path as written, with any fragment or query still attached
+    # @yieldparam embedded [Boolean] whether the page embeds the file rather than linking to it
+    # @yieldreturn [String] the path to write in its place
+    # @return [String] the content with every path replaced by the block's result
+    def rewrite(content, &)
+      labels = embedded_labels(content)
+      Markdown.map_prose(content) { |prose| rewrite_prose(prose, labels, &) }
+    end
+
+    # @api private
+    def rewrite_prose(prose, labels, &)
+      prose = rewrite_links(prose, labels, &)
+      prose = prose.gsub(ATTRIBUTE) do
+        replace(Regexp.last_match, EMBEDDING_ATTRIBUTES.include?(Regexp.last_match[:name]), &)
+      end
+      prose.gsub(SRCSET) { "#{Regexp.last_match[:lead]}#{rewrite_srcset(Regexp.last_match[:value], &)}" }
+    end
+
+    # @api private
+    def rewrite_links(prose, labels, &)
+      inline = prose.gsub(INLINE) { replace(Regexp.last_match, embedded_inline?(prose, Regexp.last_match), &) }
+      inline.gsub(DEFINITION) { replace(Regexp.last_match, labels.include?(Regexp.last_match[:label].downcase), &) }
+    end
+
+    # @api private
+    def replace(match, embedded)
+      return match[0] if EXTERNAL.match?(match[:target])
+
+      "#{match[:lead]}#{yield(match[:target], embedded)}"
+    end
+
+    # @api private
+    def rewrite_srcset(value)
+      value.gsub(SRCSET_ENTRY) do
+        url = Regexp.last_match[:url]
+        "#{EXTERNAL.match?(url) ? url : yield(url, true)}#{Regexp.last_match[:descriptor]}"
+      end
+    end
+
+    # The labels that an `![alt][label]` image refers to.
+    #
+    # @api private
+    def embedded_labels(content)
+      content.scan(IMAGE_REFERENCE).map { |alt, label| (label.empty? ? alt : label).downcase }
+    end
+
+    # Whether the link at `match` is the text of an image, `![...](...)`, rather than a plain link.
+    # The text before it, on the same line, must open an image and close only nested brackets.
+    #
+    # @api private
+    def embedded_inline?(text, match)
+      line = (text.rindex("\n", match.begin(:lead)) || -1) + 1
+      IMAGE_OPENING.match?(text[line...match.begin(:lead)])
+    end
+  end
+end

data/lib/boondoc/markdown.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Just enough markdown awareness to leave code alone while rewriting prose.
+  module Markdown
+    FENCE = /\A {0,3}(`{3,}|~{3,})/
+    INDENTED = /\A(?: {4}|\t)\s*\S/
+    LIST_ITEM = /\A\s*(?:[-*+]|\d+[.)])\s/
+    INLINE_CODE = /(?<!`)(`+)(?!`)(?:(?!\n\s*\n).)+?(?<!`)\1(?!`)/m
+
+    module_function
+
+    # Rewrites the prose of a markdown document, skipping fenced code blocks,
+    # indented code blocks and inline code spans.
+    #
+    # @param text [String]
+    # @yieldparam prose [String] a run of text outside any code
+    # @yieldreturn [String] its replacement
+    # @return [String]
+    def map_prose(text, &)
+      state = { fence: nil, indented: false, blank: true, list: false }
+      output = +''
+      prose = +''
+      text.each_line do |line|
+        next prose << line unless code_line?(line, state)
+
+        output << map_inline(prose, &) << line
+        prose = +''
+      end
+      output << map_inline(prose, &)
+    end
+
+    # @param text [String] a single table cell
+    # @return [String] the text on one line with pipes escaped
+    def table_cell(text)
+      text.gsub(/\s*\n\s*/, ' ').gsub('|', '\\|').strip
+    end
+
+    # @api private
+    def code_line?(line, state)
+      return fence_line?(line, state) if state[:fence] || FENCE.match?(line)
+
+      blank = line.strip.empty?
+      code = !blank && INDENTED.match?(line) && indented_code_allowed?(state)
+      state[:indented] = code || (blank && state[:indented])
+      state[:list] = in_list?(line, blank, state)
+      state[:blank] = blank
+      code
+    end
+
+    # An indented line is code when it continues a code block, or starts one
+    # after a blank line outside a list (where indentation means nesting).
+    #
+    # @api private
+    def indented_code_allowed?(state)
+      state[:indented] || (state[:blank] && !state[:list])
+    end
+
+    # @api private
+    def in_list?(line, blank, state)
+      LIST_ITEM.match?(line) || (state[:list] && (blank || line.start_with?(' ', "\t")))
+    end
+
+    # @api private
+    def fence_line?(line, state)
+      if state[:fence]
+        closing = /\A {0,3}#{Regexp.escape(state[:fence][0])}{#{state[:fence].size},}\s*\z/
+        state[:fence] = nil if closing.match?(line)
+      else
+        state[:fence] = FENCE.match(line)[1]
+      end
+      state[:blank] = false
+      true
+    end
+
+    # @api private
+    def map_inline(prose)
+      return prose if prose.empty?
+
+      output = +''
+      position = 0
+      prose.scan(INLINE_CODE) do
+        match = Regexp.last_match
+        output << yield(prose[position...match.begin(0)]) << match[0]
+        position = match.end(0)
+      end
+      output << yield(prose[position..])
+    end
+  end
+end

data/lib/boondoc/model/code_object.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Boondoc
+  module Model
+    # Base class for everything that can be documented.
+    class CodeObject
+      # @return [String] the unqualified name
+      attr_reader :name
+      # @return [NamespaceObject, nil] the enclosing namespace (nil only for the root)
+      attr_reader :namespace
+      # @return [Docstring]
+      attr_accessor :docstring
+      # @return [Symbol] `:public`, `:protected`, or `:private`
+      attr_accessor :visibility
+      # @return [Array<Array(String, Integer)>] `[file, line]` pairs where the object is defined
+      attr_reader :files
+
+      # @param name [String]
+      # @param namespace [NamespaceObject, nil]
+      def initialize(name, namespace)
+        @name = name
+        @namespace = namespace
+        @docstring = Docstring.new
+        @visibility = :public
+        @files = []
+      end
+
+      # @return [String] the fully qualified path, such as `Foo::Bar#baz`
+      def path
+        namespace.nil? || namespace.root? ? name : "#{namespace.path}::#{name}"
+      end
+
+      # @return [Boolean]
+      def root?
+        false
+      end
+
+      # Records a definition site, ignoring duplicates.
+      #
+      # @param file [String]
+      # @param line [Integer]
+      # @return [void]
+      def add_file(file, line)
+        files << [file, line] unless files.any? { |existing, _| existing == file }
+      end
+
+      # @return [Boolean] true when tagged `@private` or `@api private`
+      def private_api?
+        docstring.tag?('private') || docstring.tags_named('api').any? { |tag| tag.text.strip == 'private' }
+      end
+    end
+
+    # A class, a module, or the top-level namespace.
+    class NamespaceObject < CodeObject
+      # @return [Symbol] `:class`, `:module`, or `:root`
+      attr_accessor :kind
+      # @return [String, nil] the superclass as written in source
+      attr_accessor :superclass
+      # @return [Hash{Symbol => Array<String>}] mixin names keyed by `:include`, `:extend`, `:prepend`
+      attr_reader :mixins
+      # @return [Array<CodeObject>] everything defined directly inside this namespace
+      attr_reader :children
+
+      # @param name [String]
+      # @param namespace [NamespaceObject, nil]
+      # @param kind [Symbol]
+      def initialize(name, namespace, kind: :module)
+        super(name, namespace)
+        @kind = kind
+        @mixins = { include: [], extend: [], prepend: [] }
+        @children = []
+      end
+
+      # @return [String] empty for the root
+      def path
+        root? ? '' : super
+      end
+
+      # @return [Boolean]
+      def root?
+        kind == :root
+      end
+
+      # @return [Array<NamespaceObject>] nested classes and modules, sorted by name
+      def namespaces
+        children.grep(NamespaceObject).sort_by(&:name)
+      end
+
+      # @return [Array<ConstantObject>] constants, sorted by name
+      def constants
+        children.grep(ConstantObject).sort_by(&:name)
+      end
+
+      # @param scope [Symbol] `:instance` or `:class`
+      # @return [Array<MethodObject>] methods in that scope, `initialize` first, then by name
+      def meths(scope)
+        children.grep(MethodObject).select { |meth| meth.scope == scope }
+                .sort_by { |meth| [meth.name == 'initialize' ? 0 : 1, meth.name] }
+      end
+    end
+
+    # A method or attribute.
+    class MethodObject < CodeObject
+      # @return [Symbol] `:instance` or `:class`
+      attr_reader :scope
+      # @return [String, nil] the parameter list as written, without parentheses
+      attr_accessor :parameters
+      # @return [Symbol, nil] `:reader` or `:writer` when defined by `attr_*`
+      attr_reader :attribute
+      # @return [String, nil] name of the method this one aliases
+      attr_reader :alias_for
+
+      # @param name [String]
+      # @param namespace [NamespaceObject]
+      # @param scope [Symbol]
+      # @param parameters [String, nil]
+      # @param attribute [Symbol, nil]
+      # @param alias_for [String, nil]
+      def initialize(name, namespace, scope: :instance, parameters: nil, attribute: nil, alias_for: nil)
+        super(name, namespace)
+        @scope = scope
+        @parameters = parameters
+        @attribute = attribute
+        @alias_for = alias_for
+      end
+
+      # @param namespace [NamespaceObject]
+      # @param scope [Symbol] `:instance` or `:class`
+      # @param name [String]
+      # @return [String] the path a method with that name and scope would have
+      def self.path_for(namespace, scope, name)
+        "#{namespace.path}#{scope == :class ? '.' : '#'}#{name}"
+      end
+
+      # @return [String] `#` for instance methods, `.` for class methods
+      def separator
+        scope == :class ? '.' : '#'
+      end
+
+      # @return [String]
+      def path
+        self.class.path_for(namespace, scope, name)
+      end
+
+      # @return [String] the name with its separator, such as `#each`
+      def display_name
+        "#{separator}#{name}"
+      end
+    end
+
+    # A constant that is not a class or module.
+    class ConstantObject < CodeObject
+      # @return [String] the source of the assigned value
+      attr_reader :value
+
+      # @param name [String]
+      # @param namespace [NamespaceObject]
+      # @param value [String]
+      def initialize(name, namespace, value: '')
+        super(name, namespace)
+        @value = value
+      end
+    end
+  end
+end

data/lib/boondoc/model/docstring.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Boondoc
+  module Model
+    # One `@tag` from a docstring.
+    #
+    # Which fields are set depends on the tag: `@param` uses `name`, `types` and
+    # `text`; `@example` uses `name` as its title; `@option` adds `key` and
+    # `default`; `@overload` carries a `signature` and a nested `docstring`.
+    Tag = Struct.new(:tag_name, :name, :types, :text, :key, :default, :signature, :docstring,
+                     keyword_init: true) do
+      def initialize(**)
+        super
+        self.text ||= ''
+      end
+    end
+
+    # A parsed documentation comment: free markdown text plus tags.
+    class Docstring
+      # @return [String] the markdown body, without tags
+      attr_reader :text
+      # @return [Array<Tag>]
+      attr_reader :tags
+      # @return [Array<String>] names of YARD directives (`@!macro`, ...) found in the comment
+      attr_reader :directives
+
+      # @param text [String]
+      # @param tags [Array<Tag>]
+      # @param directives [Array<String>]
+      def initialize(text = '', tags = [], directives = [])
+        @text = text
+        @tags = tags
+        @directives = directives
+      end
+
+      # @param name [String] tag name without the `@`
+      # @return [Array<Tag>]
+      def tags_named(name)
+        tags.select { |tag| tag.tag_name == name }
+      end
+
+      # @param name [String]
+      # @return [Tag, nil] the first tag with that name
+      def tag(name)
+        tags.find { |tag| tag.tag_name == name }
+      end
+
+      # @param name [String]
+      # @return [Boolean]
+      def tag?(name)
+        !tag(name).nil?
+      end
+
+      # @return [Boolean] true when there is neither text nor tags
+      def empty?
+        text.strip.empty? && tags.empty?
+      end
+
+      # @return [String] the first sentence of the first paragraph, on one line;
+      #   falls back to the `@return` description when there is no body
+      def summary
+        paragraph = text.strip.split(/\n\s*\n/).first.to_s.gsub(/\s*\n\s*/, ' ')
+        return paragraph[/\A.*?[.!?](?=\s|\z)/] || paragraph unless paragraph.empty?
+
+        returned = tag('return')&.text.to_s.lines.first.to_s.strip
+        returned.empty? ? '' : "Returns #{returned}"
+      end
+    end
+  end
+end

data/lib/boondoc/model/registry.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Boondoc
+  module Model
+    # Every documented object, keyed by path, with YARD-style reference lookup.
+    class Registry
+      include Enumerable
+
+      REFERENCE = /\A(?<const>(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*)?(?:(?<sep>#|\.|::)(?<meth>[^A-Z:].*))?\z/
+
+      # @return [NamespaceObject] the top-level namespace
+      attr_reader :root
+      # @return [Array<String>] `file:line` locations of comments that use YARD directives
+      attr_reader :directive_sites
+
+      def initialize
+        @root = NamespaceObject.new('', nil, kind: :root)
+        @objects = { '' => @root }
+        @directive_sites = []
+      end
+
+      # @return [Array<String>] the files that contain YARD directives, in the order they were parsed
+      def directive_files
+        @directive_sites.map { |site| site.rpartition(':').first }.uniq
+      end
+
+      # @param path [String]
+      # @return [CodeObject, nil]
+      def [](path)
+        @objects[path]
+      end
+
+      # Adds an object, replacing any existing object at the same path.
+      #
+      # @param object [CodeObject]
+      # @return [CodeObject] the object
+      def register(object)
+        delete(@objects[object.path])
+        @objects[object.path] = object
+        object.namespace.children << object
+        object
+      end
+
+      # @param object [CodeObject, nil]
+      # @return [void]
+      def delete(object)
+        return unless object
+
+        @objects.delete(object.path)
+        object.namespace&.children&.delete(object)
+      end
+
+      # @yieldparam object [CodeObject]
+      def each(&)
+        @objects.values.each(&)
+      end
+
+      # Resolves a reference such as `Foo::Bar`, `Foo#bar`, `#bar`, or `bar` as
+      # seen from `context`, searching enclosing namespaces and ancestors.
+      #
+      # @param context [CodeObject] where the reference was written
+      # @param reference [String]
+      # @return [CodeObject, nil]
+      def resolve(context, reference)
+        reference = reference.to_s.strip
+        match = REFERENCE.match(reference) || /\A(?<const>)(?<sep>)(?<meth>\S+)\z/.match(reference)
+        return nil if reference.empty? || match.nil?
+
+        start = context.is_a?(NamespaceObject) ? context : context.namespace
+        resolve_parts(start, match[:const].to_s, match[:sep].to_s, match[:meth])
+      end
+
+      # @param namespace [NamespaceObject]
+      # @return [Array<NamespaceObject>] the namespace followed by its documented
+      #   mixins and superclasses, nearest first
+      def ancestors(namespace)
+        seen = [namespace]
+        seen.each do |current|
+          mixins = (current.mixins[:prepend] + current.mixins[:include]).map { |name| resolve_constant(current, name) }
+          [*mixins, superclass(current)].each do |found|
+            seen << found if found.is_a?(NamespaceObject) && !seen.include?(found)
+          end
+        end
+        seen
+      end
+
+      # Like Ruby, looks the superclass up from the scope around the class, and
+      # never finds the class itself, so `class Error < Error` inside a module
+      # refers to an outer `Error`.
+      #
+      # @param namespace [NamespaceObject]
+      # @return [NamespaceObject, nil] the documented superclass
+      def superclass(namespace)
+        return nil unless namespace.superclass && namespace.namespace
+
+        found = resolve_constant(namespace.namespace, namespace.superclass, except: namespace)
+        found if found.is_a?(NamespaceObject)
+      end
+
+      private
+
+      def resolve_parts(start, const, sep, meth)
+        return resolve_constant(start, const) if meth.nil?
+        return find_method(resolve_constant(start, const), sep, meth) unless const.empty?
+
+        lexical(start).each do |scope|
+          found = find_method(scope, sep, meth)
+          return found if found
+        end
+        nil
+      end
+
+      def resolve_constant(start, const, except: nil)
+        constant_candidates(start, const).each do |path|
+          found = self[path]
+          return found if found && !found.equal?(except)
+        end
+        nil
+      end
+
+      def constant_candidates(start, const)
+        return [const.delete_prefix('::')] if const.start_with?('::')
+
+        lexical(start).map { |scope| scope.root? ? const : "#{scope.path}::#{const}" }
+      end
+
+      def find_method(namespace, sep, meth)
+        return nil unless namespace.is_a?(NamespaceObject)
+
+        separators = { '' => %w[# .], '#' => ['#'] }.fetch(sep, ['.'])
+        ancestors(namespace).each do |ancestor|
+          separators.each do |separator|
+            found = self["#{ancestor.path}#{separator}#{meth}"]
+            return found if found
+          end
+        end
+        nil
+      end
+
+      def lexical(namespace)
+        scopes = []
+        while namespace
+          scopes << namespace
+          namespace = namespace.namespace
+        end
+        scopes
+      end
+    end
+  end
+end

data/lib/boondoc/path_map.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Boondoc
+  # Maps objects to output files and anchors, and computes relative links.
+  class PathMap
+    TOP_LEVEL = 'top-level.md'
+
+    # @param config [Config]
+    # @param registry [Model::Registry] consulted for classes and modules whose
+    #   names differ only by case
+    def initialize(config, registry)
+      @config = config
+      @registry = registry
+      @relative = {}
+    end
+
+    # @param object [Model::CodeObject]
+    # @return [String] output file, relative to the output directory. Classes and
+    #   modules whose names differ only by case get their kind appended, such as
+    #   `CLI.class.md` and `Cli.module.md`, so that the files stay apart on
+    #   case-insensitive filesystems.
+    def file_for(object)
+      namespace = object.is_a?(Model::NamespaceObject) ? object : object.namespace
+      namespace.root? ? TOP_LEVEL : (@files ||= {}.compare_by_identity)[namespace] ||= "#{directory(namespace)}.md"
+    end
+
+    # @param object [Model::CodeObject]
+    # @return [String, nil] the anchor inside its file; nil for namespaces
+    def anchor_for(object)
+      case object
+      when Model::MethodObject then "method-#{object.scope == :class ? 'c' : 'i'}-#{escape(object.name)}"
+      when Model::ConstantObject then "constant-#{escape(object.name)}"
+      end
+    end
+
+    # @param object [Model::CodeObject]
+    # @param from [String] the output file the link is written in
+    # @return [String] a relative link to the object
+    def href(object, from:)
+      anchor = anchor_for(object)
+      file = file_for(object)
+      return "##{anchor}" if anchor && file == from
+
+      [relative(file, from), anchor].compact.join('#')
+    end
+
+    # @param file [String] output file to link to
+    # @param from [String] output file the link is written in
+    # @return [String] frozen; each distinct link is worked out once, because
+    #   the same few targets are linked many times in a run
+    def relative(file, from)
+      @relative[[file, from]] ||= encode(Pathname.new(file).relative_path_from(Pathname.new(from).dirname).to_s).freeze
+    end
+
+    # @param source [String] a path relative to the project root
+    # @param from [String] output file the link is written in
+    # @return [String] a relative link from the output file to a project file
+    def source_href(source, from:)
+      target = Pathname.new(File.expand_path(source, @config.root))
+      origin = Pathname.new(File.expand_path(from, @config.output_dir)).dirname
+      encode(target.relative_path_from(origin).to_s)
+    end
+
+    private
+
+    def directory(namespace)
+      parts = []
+      while namespace && !namespace.root?
+        parts.unshift(segments[namespace])
+        namespace = namespace.namespace
+      end
+      parts.join('/')
+    end
+
+    # The file or directory name of every class and module, worked out once
+    # because nothing changes the registry while pages are rendered.
+    def segments
+      @segments ||= {}.compare_by_identity.tap { |names| name_children(@registry.root, names) }
+    end
+
+    def name_children(parent, names)
+      parent.namespaces.group_by { |child| child.name.downcase }.each_value do |group|
+        group.each { |child| names[child] = child.name } if group.one?
+        disambiguate(group, names) if group.size > 1
+      end
+      parent.namespaces.each { |child| name_children(child, names) }
+    end
+
+    # Appends the kind, and a number when two of the same kind still collide.
+    def disambiguate(group, names)
+      seen = Hash.new(0)
+      group.each do |child|
+        count = (seen[child.kind] += 1)
+        names[child] = ["#{child.name}.#{child.kind}", (count if count > 1)].compact.join('-')
+      end
+    end
+
+    def escape(name)
+      name.gsub(/[^A-Za-z0-9_]/) { |char| format('-%02X', char.ord) }
+    end
+
+    def encode(path)
+      path.gsub(' ', '%20')
+    end
+  end
+end