boondoc 0.1.0

data/lib/boondoc/config.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Boondoc
+  # Options for one run, merged from defaults, `.yardopts`, `.boondoc.yml`, and the command line.
+  class Config
+    FILE = '.boondoc.yml'
+    DEFAULTS = {
+      sources: ['lib/**/*.rb'], exclude: [], output: 'docs', index: 'README.md',
+      readme: nil, files: [], assets: [], copy_linked_assets: false, title: nil,
+      private: false, protected: false, yard_macros: false,
+      strict: false, force: false, quiet: false, allow_outside_output: false, yardopts: true
+    }.freeze
+
+    # What each option accepts: a type name from {CHECKS} per key.
+    TYPES = {
+      sources: :list, exclude: :list, files: :list, assets: :list, copy_linked_assets: :boolean,
+      output: :string, index: :string, readme: :file_or_false, title: :optional_string,
+      private: :boolean, protected: :boolean, yard_macros: :boolean, strict: :boolean,
+      force: :boolean, quiet: :boolean, allow_outside_output: :boolean, yardopts: :boolean
+    }.freeze
+    # A test and a description for each type name in {TYPES}.
+    CHECKS = {
+      list: [->(value) { value.is_a?(String) || (value.is_a?(Array) && value.all?(String)) },
+             'a string or a list of strings'],
+      string: [->(value) { value.is_a?(String) }, 'a string'],
+      optional_string: [->(value) { value.nil? || value.is_a?(String) }, 'a string'],
+      file_or_false: [->(value) { value.nil? || value == false || value.is_a?(String) }, 'a file name or false'],
+      boolean: [->(value) { [true, false].include?(value) }, 'true or false']
+    }.freeze
+
+    attr_reader(*DEFAULTS.keys)
+    # @return [String] absolute path of the project being documented
+    attr_reader :root
+
+    # Builds a config from `.yardopts` and `.boondoc.yml` (if present) with `overrides` on top.
+    # Each option comes from the highest of those that sets it; lists are replaced, not merged.
+    # `.yardopts` is skipped when `yardopts` is false in the file or the overrides.
+    #
+    # @param overrides [Hash{Symbol => Object}] options that win over the file;
+    #   `:config` names an alternative config file
+    # @param root [String] project directory
+    # @return [Config]
+    # @raise [Error] when the config file is missing, has unknown keys, or tries
+    #   to set `allow_outside_output`, which only the caller may do
+    def self.load(overrides = {}, root: Dir.pwd)
+      overrides = overrides.transform_keys(&:to_sym)
+      path = File.expand_path(overrides[:config] || FILE, root)
+      raise Error, "config file not found: #{overrides[:config]}" if overrides[:config] && !File.file?(path)
+
+      settings = read_file(path).merge(overrides.except(:config).compact)
+      yardopts = Yardopts.read(root) unless settings[:yardopts] == false
+      new(root: root, from_yardopts: yardopts, **with_yardopts(settings, yardopts))
+    end
+
+    # @param settings [Hash{Symbol => Object}] options from the config file and the caller
+    # @param yardopts [Yardopts, nil]
+    # @return [Hash{Symbol => Object}] `settings` over what `.yardopts` sets
+    def self.with_yardopts(settings, yardopts)
+      yardopts ? yardopts.settings.merge(settings) : settings
+    end
+    private_class_method :with_yardopts
+
+    # @param path [String] the config file, which may not exist
+    # @return [Hash{Symbol => Object}]
+    # @raise [Error] when the file sets `allow_outside_output`
+    def self.read_file(path)
+      return {} unless File.file?(path)
+
+      settings = YAML.safe_load_file(path, symbolize_names: true) || {}
+      return settings unless settings.key?(:allow_outside_output)
+
+      raise Error, 'allow_outside_output cannot be set in a config file, because the project being ' \
+                   'documented is not trusted to choose it; pass --allow-outside-output on the command line'
+    end
+    private_class_method :read_file
+
+    # @param root [String] project directory
+    # @param from_yardopts [Yardopts, nil] the project's `.yardopts`, whose `--exclude`
+    #   patterns apply unless `exclude` is given and whose skipped options are reported
+    #   by {#yardopts_notes}; its other settings are expected in `options` already
+    # @param options [Hash{Symbol => Object}] any of the keys in {DEFAULTS}
+    # @raise [Error] on unknown options, or an option of the wrong type
+    def initialize(root: Dir.pwd, from_yardopts: nil, **options)
+      unknown = options.keys - DEFAULTS.keys
+      raise Error, "unknown option#{'s' if unknown.size > 1}: #{unknown.join(', ')}" if unknown.any?
+
+      @root = File.expand_path(root)
+      @yardopts_file = from_yardopts
+      @yardopts_exclude_patterns = options.key?(:exclude) ? [] : from_yardopts&.exclude || []
+      DEFAULTS.merge(options).each do |key, value|
+        check_type(key, value)
+        instance_variable_set(:"@#{key}", value)
+      end
+    end
+
+    # @return [String] absolute path of the output directory
+    # @raise [Error] when it is outside the project and `allow_outside_output`
+    #   is not set, or when it is reached through a symlink inside the project
+    def output_dir
+      @output_dir ||= begin
+        path = File.expand_path(output, root)
+        check_output_inside(path) unless allow_outside_output
+        link = Containment.symlink_between(path, root)
+        raise Error, "output directory #{path} goes through the symlink #{link}" if link
+
+        path
+      end
+    end
+
+    # @return [Array<String>] what the run ignores from `.yardopts`, such as its `--output-dir`
+    def yardopts_notes
+      @yardopts_file ? @yardopts_file.notes(output: output, root: root) : []
+    end
+
+    # @return [String] the documentation title; defaults to the project directory name
+    def title
+      @title || File.basename(root)
+    end
+
+    # @return [Array<String>] Ruby files to parse, relative to {#root}; files
+    #   that resolve outside the project are left out, see {#outside_sources}
+    def source_files
+      source_split.first
+    end
+
+    # @return [Array<String>] sources that resolve outside the project, through an
+    #   absolute path, `../`, or a symlink, and are therefore not parsed
+    def outside_sources
+      source_split.last
+    end
+
+    # @return [String, nil] the README to use as the index page, relative to {#root}
+    # @raise [Error] when an explicitly named README does not exist or is outside the project
+    def readme_file
+      return nil if readme == false
+      return inside_project('README.md') if readme.nil? && File.file?(File.join(root, 'README.md'))
+      return nil if readme.nil?
+      raise Error, "readme not found: #{readme}" unless File.file?(File.expand_path(readme, root))
+
+      inside_project(relative(readme))
+    end
+
+    # @return [Array<String>] extra files to stitch in, relative to {#root}
+    # @raise [Error] when a file is outside the project
+    def extra_files
+      (expand(files) - [readme_file]).each { |path| inside_project(path) }
+    end
+
+    private
+
+    def check_type(key, value)
+      test, description = CHECKS.fetch(TYPES.fetch(key))
+      return if test.call(value)
+
+      raise Error, "option `#{key}` must be #{description} (got #{value.inspect})"
+    end
+
+    def source_split
+      @source_split ||= (expand(sources, ruby: true) - expand(exclude, ruby: true))
+                        .reject { |path| excluded_by_yardopts?(path) }
+                        .partition { |path| Containment.inside?(File.expand_path(path, root), root) }
+    end
+
+    def excluded_by_yardopts?(path)
+      @yardopts_exclude_patterns.any? { |pattern| pattern.match?(path) }
+    rescue Regexp::TimeoutError
+      raise Error, "an --exclude pattern in .yardopts took too long to match #{path}"
+    end
+
+    def check_output_inside(path)
+      return if path == root || path.start_with?(File.join(root, ''))
+
+      raise Error, "output directory #{path} is outside the project (#{root}). A project must not choose where " \
+                   'boondoc writes. To write there anyway, pass --allow-outside-output; that is a security ' \
+                   'risk if you do not trust the project, and it is how docs are kept outside the repository.'
+    end
+
+    def expand(patterns, ruby: false)
+      Array(patterns).flat_map do |pattern|
+        pattern = File.join(pattern, '**', '*.rb') if ruby && File.directory?(File.expand_path(pattern, root))
+        paths = Dir.glob(pattern, base: root).select { |path| File.file?(File.expand_path(path, root)) }
+        paths.map { |path| relative(path) }
+      end.uniq.sort
+    end
+
+    # Paths under the root become relative to it, with `..` segments resolved.
+    def relative(path)
+      absolute = File.expand_path(path, root)
+      absolute.start_with?(File.join(root, '')) ? absolute.delete_prefix(File.join(root, '')) : path
+    end
+
+    # Files that are copied into the output must not come from elsewhere on the machine.
+    def inside_project(path)
+      return path if Containment.inside?(File.expand_path(path, root), root)
+
+      raise Error, "#{path} is outside the project (#{root})"
+    end
+  end
+end

data/lib/boondoc/containment.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Checks that a path stays inside a directory once symlinks are followed.
+  #
+  # The project being documented is not trusted to point Boondoc at files
+  # elsewhere on the machine, through `../`, absolute paths, or symlinks.
+  module Containment
+    module_function
+
+    # @param path [String] an existing file or directory
+    # @param directory [String]
+    # @return [Boolean] true when the real path of `path` is `directory` or inside it
+    def inside?(path, directory)
+      real = File.realpath(path)
+      base = File.realpath(directory)
+      real == base || real.start_with?(File.join(base, ''))
+    rescue SystemCallError
+      false
+    end
+
+    # Finds a symlink on the way from `directory` down to `path`.
+    #
+    # Only the names are looked at (`..` is resolved first), so this also works
+    # for a path that does not exist yet. `directory` itself is not checked.
+    #
+    # @param path [String] a path below `directory`, which need not exist
+    # @param directory [String]
+    # @return [String, nil] the first component that is a symlink, or nil when
+    #   there is none or `path` is not below `directory`
+    def symlink_between(path, directory)
+      base = File.join(File.expand_path(directory), '')
+      full = File.expand_path(path)
+      return nil unless full.start_with?(base)
+
+      parts = full.delete_prefix(base).split('/')
+      parts.each_index.map { |count| File.join(base, *parts.first(count + 1)) }.find { |step| File.symlink?(step) }
+    end
+  end
+end

data/lib/boondoc/context.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Everything the renderers need to produce a page.
+  class Context
+    attr_reader :config, :registry, :reporter, :filter, :path_map, :assets, :stitcher, :linker
+
+    # @param config [Config]
+    # @param registry [Model::Registry]
+    # @param reporter [Reporter]
+    def initialize(config:, registry:, reporter:)
+      @config = config
+      @registry = registry
+      @reporter = reporter
+      @filter = Filter.new(config)
+      @path_map = PathMap.new(config, registry)
+      @assets = Assets.new(config)
+      @stitcher = Stitcher.new(config, assets: assets)
+      @linker = Linker.new(config: config, registry: registry, filter: filter, path_map: path_map,
+                           stitcher: stitcher, assets: assets, reporter: reporter)
+      @meths = {}
+      @aliases = {}
+    end
+
+    # The methods of a namespace in one scope, sorted once per run.
+    #
+    # Nothing changes the registry while pages are rendered, so the list can be
+    # kept for the lifetime of the context. Keeping it here rather than in the
+    # model matters because the parser changes `children` directly.
+    #
+    # @param namespace [Model::NamespaceObject]
+    # @param scope [Symbol] `:instance` or `:class`
+    # @return [Array<Model::MethodObject>] see {Model::NamespaceObject#meths}
+    def meths(namespace, scope)
+      @meths[[namespace, scope]] ||= namespace.meths(scope).freeze
+    end
+
+    # The aliases of the methods of a namespace, found without scanning every
+    # method for each one.
+    #
+    # @param namespace [Model::NamespaceObject]
+    # @param scope [Symbol] `:instance` or `:class`
+    # @return [Hash{String => Array<Model::MethodObject>}] aliases keyed by the name they alias
+    def aliases(namespace, scope)
+      @aliases[[namespace, scope]] ||= meths(namespace, scope).select(&:alias_for).group_by(&:alias_for).freeze
+    end
+  end
+end

data/lib/boondoc/core_constants.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Top-level classes and modules of Ruby core and the standard library. A
+  # fixed list, because what happens to be loaded in boondoc's own process
+  # (Thor, Rake, Boondoc itself) says nothing about the project being documented.
+  CORE_CONSTANTS = %w[
+    ArgumentError Array BasicObject Binding Class ClosedQueueError Comparable Complex ConditionVariable Data
+    Dir EOFError Encoding EncodingError Enumerable Enumerator Errno Exception FalseClass Fiber FiberError File
+    FileTest Float FloatDomainError FrozenError GC Hash IO IOError IndexError Integer Interrupt Kernel KeyError
+    LoadError LocalJumpError Marshal MatchData Math Method Module Mutex NameError NilClass NoMatchingPatternError
+    NoMatchingPatternKeyError NoMemoryError NoMethodError NotImplementedError Numeric Object ObjectSpace Pathname
+    Proc Process Queue Ractor Random Range RangeError Rational Refinement Regexp RegexpError Ruby RubyVM
+    RuntimeError ScriptError SecurityError Set Signal SignalException SizedQueue StandardError StopIteration String
+    Struct Symbol SyntaxError SystemCallError SystemExit SystemStackError Thread ThreadError ThreadGroup Time
+    TracePoint TrueClass TypeError UnboundMethod UncaughtThrowError Warning ZeroDivisionError
+    Base64 Benchmark BigDecimal CGI CSV Coverage DRb Date DateTime Delegator Digest ERB Etc Fcntl Fiddle FileUtils
+    Find Forwardable GetoptLong IPAddr IPSocket JSON Logger Monitor MonitorMixin Net Observable Open3 OpenSSL
+    OpenStruct OptionParser PP PStore Psych Racc Readline Reline Resolv Ripper SecureRandom Shellwords
+    SimpleDelegator Singleton Socket StringIO StringScanner Syslog TCPServer TCPSocket Tempfile Timeout Tmpdir
+    TSort UDPSocket UNIXServer UNIXSocket URI WeakRef YAML Zlib
+  ].freeze
+end

data/lib/boondoc/docstring_parser.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Turns the text of a documentation comment into a {Model::Docstring}.
+  #
+  # A line starting with `@name` begins a tag; indented lines that follow belong
+  # to it. Everything else is the markdown body.
+  class DocstringParser
+    TAG_LINE = /\A@(?<directive>!)?(?<name>[a-z_][\w.]*)(?:\s+(?<rest>.*))?\z/i
+    NAMED = %w[param yieldparam attr attr_reader attr_writer].freeze
+    FENCE = /\A\s*(?:```|~~~)/
+
+    # @param text [String] comment text with the leading `#` already removed
+    # @return [Model::Docstring]
+    def self.parse(text)
+      new.parse(text)
+    end
+
+    # @param text [String]
+    # @return [Model::Docstring]
+    def parse(text)
+      @body = []
+      @tags = []
+      @directives = []
+      @current = nil
+      @fenced = false
+      text.to_s.each_line(chomp: true) { |line| consume(line) }
+      finish_tag
+      Model::Docstring.new(@body.join("\n").strip, @tags, @directives)
+    end
+
+    private
+
+    def consume(line)
+      match = TAG_LINE.match(line) unless @fenced
+      return start_tag(match) if match
+      return @current[:lines] << line if @current && continuation?(line)
+
+      finish_tag
+      @fenced = !@fenced if FENCE.match?(line)
+      @body << line
+    end
+
+    def start_tag(match)
+      finish_tag
+      @current = { name: match[:name], directive: !match[:directive].nil?, lines: [match[:rest].to_s] }
+    end
+
+    def continuation?(line)
+      line.strip.empty? || line.start_with?(' ', "\t")
+    end
+
+    def finish_tag
+      return unless @current
+
+      current = @current
+      @current = nil
+      return @directives << current[:name] if current[:directive]
+
+      first, *rest = current[:lines]
+      @tags << build(current[:name], first.strip, dedent(rest))
+    end
+
+    def build(name, first, rest)
+      case name
+      when 'example'  then Model::Tag.new(tag_name: name, name: first, text: rest)
+      when 'overload' then overload(first, rest)
+      when 'option'   then option(join(first, rest))
+      when 'see'      then see(join(first, rest))
+      when *NAMED     then named(name, join(first, rest))
+      else typed(name, join(first, rest))
+      end
+    end
+
+    def overload(signature, rest)
+      Model::Tag.new(tag_name: 'overload', signature: signature, docstring: self.class.parse(rest))
+    end
+
+    # `@param name [Types] text` or `@param [Types] name text`
+    def named(tag_name, text)
+      types, text = TypeParser.extract(text)
+      name, text = text.split(/\s+/, 2)
+      types, text = TypeParser.extract(text.to_s) unless types
+      Model::Tag.new(tag_name: tag_name, name: name, types: types, text: text.to_s.strip)
+    end
+
+    # `@return [Types] text`
+    def typed(tag_name, text)
+      types, text = TypeParser.extract(text)
+      Model::Tag.new(tag_name: tag_name, types: types, text: text.strip)
+    end
+
+    # `@option opts [Types] :key (default) text`
+    def option(text)
+      name, text = text.split(/\s+/, 2)
+      types, text = TypeParser.extract(text.to_s)
+      key, text = text.split(/\s+/, 2)
+      default = text.to_s[/\A\((.*?)\)\s*/, 1]
+      text = text.to_s.sub(/\A\(.*?\)\s*/, '') if default
+      Model::Tag.new(tag_name: 'option', name: name, types: types, key: key, default: default,
+                     text: text.to_s.strip)
+    end
+
+    # `@see reference text`
+    def see(text)
+      name, text = text.split(/\s+/, 2)
+      Model::Tag.new(tag_name: 'see', name: name, text: text.to_s.strip)
+    end
+
+    def join(first, rest)
+      [first, rest].reject(&:empty?).join("\n")
+    end
+
+    def dedent(lines)
+      indent = lines.reject { |line| line.strip.empty? }.map { |line| line[/\A[ \t]*/].size }.min || 0
+      lines.map { |line| line[indent..] || '' }.join("\n").strip
+    end
+  end
+end

data/lib/boondoc/filter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Boondoc
+  # Decides which objects appear in the output.
+  class Filter
+    # @param config [Config]
+    def initialize(config)
+      @config = config
+    end
+
+    # An object is visible when it and every enclosing namespace pass the
+    # visibility options (`--private`, `--protected`).
+    #
+    # @param object [Model::CodeObject]
+    # @return [Boolean]
+    def visible?(object)
+      return true if object.root?
+
+      allowed?(object) && visible?(object.namespace)
+    end
+
+    private
+
+    def allowed?(object)
+      return false if object.private_api? && !@config.private
+
+      case object.visibility
+      when :private   then @config.private
+      when :protected then @config.private || @config.protected
+      else true
+      end
+    end
+  end
+end

data/lib/boondoc/frontend/comments.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Boondoc
+  module Frontend
+    # Finds the comment block that documents a given line of a parsed file.
+    class Comments
+      IGNORED = /\A#(?:!|\s*(?:rubocop:|frozen_string_literal:|encoding:|typed:|:nodoc:))/
+      DIRECTIVE = /^\s*@!\w/
+
+      # @param result [::Prism::ParseResult]
+      def initialize(result)
+        @blocks = {}
+        @trailing = {}
+        group(result.comments.grep(::Prism::InlineComment))
+      end
+
+      # @param line [Integer] the line a definition starts on
+      # @return [String, nil] the text of the comment block ending on the line above
+      def docstring_for(line)
+        @blocks[line - 1]
+      end
+
+      # @param line [Integer]
+      # @return [Boolean] true when the line carries a trailing `# :nodoc:`
+      def nodoc?(line)
+        @trailing[line].to_s.include?(':nodoc:')
+      end
+
+      # @return [Array<Integer>] last lines of comment blocks that contain YARD directives
+      def directive_lines
+        @blocks.select { |_, text| DIRECTIVE.match?(text) }.keys
+      end
+
+      private
+
+      def group(comments)
+        run = []
+        comments.each do |comment|
+          next @trailing[comment.location.start_line] = comment.location.slice if comment.trailing?
+
+          flush(run) unless adjacent?(run.last, comment)
+          run << comment
+        end
+        flush(run)
+      end
+
+      def adjacent?(previous, comment)
+        previous.nil? || (previous.location.start_line + 1 == comment.location.start_line &&
+          previous.location.start_column == comment.location.start_column)
+      end
+
+      def flush(run)
+        return if run.empty?
+
+        text = clean(run.map { |comment| comment.location.slice })
+        @blocks[run.last.location.start_line] = text unless text.strip.empty?
+        run.clear
+      end
+
+      def clean(lines)
+        lines = lines.grep_v(IGNORED).map { |line| line.delete_prefix('#').rstrip }
+        indent = lines.reject(&:empty?).map { |line| line[/\A */].size }.min || 0
+        lines.map { |line| line[indent..] || '' }.join("\n")
+      end
+    end
+  end
+end

data/lib/boondoc/frontend/prism_parser.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Boondoc
+  module Frontend
+    # Parses Ruby files with Prism and fills a {Model::Registry}.
+    class PrismParser
+      # @param registry [Model::Registry]
+      # @param reporter [Reporter]
+      def initialize(registry, reporter)
+        @registry = registry
+        @reporter = reporter
+      end
+
+      # @param path [String] file to parse
+      # @param label [String] the path to record on objects (usually relative to the project)
+      # @return [void]
+      def parse_file(path, label: path)
+        parse(File.read(path), label)
+      end
+
+      # @param source [String] Ruby source
+      # @param label [String] file name to record on objects
+      # @return [void]
+      def parse(source, label = '(source)')
+        result = ::Prism.parse(source)
+        return syntax_error(label, result) if result.failure?
+
+        comments = Comments.new(result)
+        result.value.accept(Visitor.new(@registry, label, comments))
+        comments.directive_lines.each { |line| @registry.directive_sites << "#{label}:#{line}" }
+      end
+
+      private
+
+      def syntax_error(label, result)
+        @reporter.warn("#{label}: skipped, syntax error: #{result.errors.first.message}")
+      end
+    end
+  end
+end