zard-doc 0.0.1 → 0.0.2

data/lib/zard/doc/build_renderer.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Zard
+  module Doc
+    class BuildRenderer
+      attr_reader :diagnostics, :links
+
+      def initialize(scope_documents:, scope_files:, scopes:, layout:, include_undocumented: false)
+        @diagnostics = []
+        @links = {}
+        @scopes = scopes
+        @renderers = scope_documents.keys.sort.to_h do |name|
+          [name, ScopeRenderer.new(name, scope_documents.fetch(name), scope_files.fetch(name), scopes.fetch(name), layout, self, include_undocumented: include_undocumented)]
+        end
+      end
+
+      def render
+        pages = {}
+        add_page(pages, "index.md", "# API documentation\n\n" + @renderers.map { |name, renderer| "- [#{renderer.label(name)}](#{renderer.url(renderer.index_path)})" }.join("\n") + "\n")
+        @renderers.each_value do |renderer|
+          renderer.pages.each { |path, text| add_page(pages, path, text) }
+        end
+        pages
+      end
+
+      def dependencies(name)
+        @scopes.fetch(name).fetch(:references, []).uniq.filter_map { |dependency| @renderers[dependency] }
+      end
+
+      def export_declarations
+        @renderers.transform_values(&:export_declarations)
+      end
+
+      def record_link(from, path, anchor)
+        targets = (@links[from] ||= [])
+        target = {"path" => path, "anchor" => anchor}
+        targets << target unless targets.include?(target)
+      end
+
+      def warn_ambiguity(reference, origin, candidates)
+        locations = candidates.map { |renderer, declaration| "#{renderer.name}:#{declaration.span.path}:#{declaration.span.start_line}" }
+        message = "warning: ambiguous reference #{reference.inspect} at #{origin.span.path}:#{origin.span.start_line}; candidates: #{locations.join(", ")}"
+        @diagnostics << message unless @diagnostics.include?(message)
+      end
+
+      def warn_relationship(kind, expression, origin)
+        message = "warning: unresolved #{kind} documentation relationship #{expression.inspect} at #{origin.span.path}:#{origin.span.start_line}"
+        @diagnostics << message unless @diagnostics.include?(message)
+      end
+
+      private
+
+      def add_page(pages, path, text)
+        raise BuildError, "output collision: #{path}" if pages.key?(path) || pages.keys.any? { |other| other.start_with?("#{path}/") || path.start_with?("#{other}/") }
+
+        pages[path] = text
+      end
+
+      class ScopeRenderer < Renderer
+        attr_reader :name, :index_path
+
+        def initialize(name, documents, files, config, layout, build, include_undocumented: false)
+          @name = name
+          @build = build
+          @layout = layout
+          @destination = config.fetch(:destination)
+          @include_undocumented = include_undocumented
+          @index_path = join_path("index.md")
+          @declarations = documents.sort_by(&:path).flat_map(&:declarations)
+          @container_names = @declarations.select { |declaration| %i[class module constant].include?(declaration.kind) }.map { |declaration| qualified_name(declaration) }
+          @targets = Hash.new { |hash, key| hash[key] = [] }
+          @declarations.each { |declaration| reference_names(declaration).each { |reference| @targets[reference] << declaration } }
+          @paths = {}
+          @anchors = {}
+          @text = {}
+          @descriptions = {}
+          @page_owners = {}
+          identities = @declarations.group_by { |declaration| anchor_identity(declaration) }
+          ordinals = Hash.new(0)
+          @declarations.each do |declaration|
+            identity_key = anchor_identity(declaration)
+            source = files.fetch(File.expand_path(declaration.span.path))
+            ordinals[[identity_key, source]] += 1
+            next unless renderable?(declaration)
+
+            owner = namespace_page(declaration)
+            relative = (layout == "file") ? files.fetch(File.expand_path(declaration.span.path)) : "#{owner.gsub("::", "/")}.md"
+            path = join_path(relative)
+            identity = (layout == "file") ? File.expand_path(declaration.span.path) : owner
+            raise BuildError, "output collision: #{path}" if path == @index_path || (@page_owners.key?(path) && @page_owners[path] != identity)
+
+            @page_owners[path] = identity
+            @paths[declaration] = path
+            key = identity_key
+            key += "\0#{source}\0#{ordinals[[identity_key, source]]}" if identities.fetch(identity_key).length > 1
+            @anchors[declaration] = "zard-#{key.bytes.map { |byte| "%02x" % byte }.join}"
+          end
+        end
+
+        def pages
+          @paths.each_key do |declaration|
+            text = declaration.documentation.select { |tag| tag.name == :text }.map(&:description).join("\n")
+            @text[declaration] = render_prose(text, declaration)
+            @descriptions[declaration] = declaration.documentation.to_h do |tag|
+              description = case tag.name
+              when :example, :raw, :text then tag.description
+              when :see then render_reference(tag.description, declaration)
+              else render_prose(tag.description, declaration)
+              end
+              [tag, description]
+            end
+          end
+          result = @paths.keys.group_by { |declaration| @paths.fetch(declaration) }.sort.to_h do |path, declarations|
+            sections = declarations.map do |declaration|
+              "#{render_declaration(declaration)}\n\nSource: #{label("#{declaration.span.path}:#{declaration.span.start_line}")}."
+            end
+            [path, "#{sections.join("\n\n")}\n"]
+          end
+          navigation = result.keys.map { |path| "- [#{label(Pathname.new(path).relative_path_from(Pathname.new(File.dirname(index_path))).to_s)}](#{relative_url(index_path, path)})" }
+          result[index_path] = "# #{label(name)}\n\n#{navigation.join("\n")}\n"
+          result
+        end
+
+        def lookup(candidates, path, containers: false)
+          path = path.delete_prefix("::")
+          candidates.each do |candidate|
+            targets = @targets[candidate].uniq
+            unless targets.empty?
+              if (@layout == "namespace" || containers) && targets.map(&:kind).uniq.one? && targets.all? { |target| %i[class module].include?(target.kind) }
+                published = targets.find { |target| renderable?(target) }
+                return [:found, [published]] if published
+              end
+              return [:found, targets]
+            end
+            if path.start_with?("#", ".") && @container_names.include?(candidate.split(/[.#]/, 2).first)
+              return [:shadowed, []]
+            end
+            first_constant = path.split(/::|[.#]/).first.to_s
+            local_constant = "#{candidate.delete_suffix(path)}#{first_constant}"
+            return [:shadowed, []] if !first_constant.empty? && @container_names.include?(local_constant)
+          end
+          [:missing, []]
+        end
+
+        def destination(declaration)
+          [@paths.fetch(declaration), @anchors.fetch(declaration)]
+        end
+
+        def export_declarations
+          @paths.map do |declaration, path|
+            descriptions = @descriptions.fetch(declaration).to_h do |tag, description|
+              [tag, (tag.name == :text) ? render_prose(tag.description, declaration) : description]
+            end
+            {declaration: declaration, page: path, anchor: @anchors.fetch(declaration),
+             display_name: reference_names(declaration).first || display_name(declaration),
+             references: reference_names(declaration), descriptions: descriptions, relationships: relationship_entries(declaration)}
+          end
+        end
+
+        def relationship_targets(declaration)
+          @targets.fetch(qualified_name(declaration)).select { |item| %i[class module].include?(item.kind) && published?(item) }.map do |item|
+            path, anchor = destination(item)
+            {scope: name, declaration_id: "#{name}:#{anchor}", path: path, anchor: anchor}
+          end
+        end
+
+        def published?(declaration)
+          renderable?(declaration)
+        end
+
+        def label(value)
+          escape_label(value)
+        end
+
+        def url(path)
+          path.bytes.map { |byte| byte.chr.match?(/[A-Za-z0-9\-._~\/]/) ? byte.chr : "%%%02X" % byte }.join
+        end
+
+        private
+
+        def renderable?(declaration)
+          declaration.visibility == :public && (@include_undocumented || super)
+        end
+
+        def join_path(path)
+          Pathname.new(File.join(@destination, path)).cleanpath.to_s
+        end
+
+        def anchor_identity(declaration)
+          reference = reference_names(declaration).first
+          [declaration.kind, reference || display_name(declaration), declaration.refinement].join("\0")
+        end
+
+        def namespace_page(declaration)
+          return qualified_name(declaration) if %i[class module].include?(declaration.kind)
+
+          if declaration.kind.to_s.start_with?("singleton_") && !declaration.refinement
+            owner = reference_owner(declaration)
+            return owner.delete_prefix("::") if owner&.match?(/\A(?:::)?[[:upper:]\p{Lt}][[:word:]]*(?:::[[:upper:]\p{Lt}][[:word:]]*)*\z/)
+          end
+
+          declaration.namespace || "_top-level"
+        end
+
+        def relative_url(from, to)
+          url(Pathname.new(to).relative_path_from(Pathname.new(File.dirname(from))).to_s)
+        end
+
+        def resolve_scoped(reference, declaration, outer: false, containers: false)
+          return if !reference || declaration.refinement
+
+          path = reference.sub(/\A((?:::)?[[:upper:]\p{Lt}][[:word:]]*(?:::[[:upper:]\p{Lt}][[:word:]]*)*)?(?:\?\.|\.#)/) { "#{$1}." }
+          candidates = if path.start_with?("::")
+            [path.delete_prefix("::")]
+          elsif path.start_with?("#", ".")
+            owner = declaration.kind.to_s.start_with?("singleton_") ? reference_owner(declaration) : declaration.namespace
+            owner = qualified_name(declaration) if %i[class module].include?(declaration.kind)
+            ["#{owner&.delete_prefix("::")}#{path}"]
+          else
+            namespace = (!outer && %i[class module].include?(declaration.kind)) ? qualified_name(declaration) : declaration.namespace
+            lexical_candidates(path, namespace)
+          end
+          status, targets = lookup(candidates, path, containers: containers)
+          matches = targets.map { |target| [self, target] }
+          if status == :missing
+            matches = @build.dependencies(name).flat_map do |renderer|
+              _, dependency_targets = renderer.lookup(candidates, path, containers: containers)
+              dependency_targets.map { |target| [renderer, target] }
+            end
+          end
+          if matches.length > 1
+            @build.warn_ambiguity(reference, declaration, matches)
+            return
+          end
+          match = matches.first
+          return unless match
+
+          match if match.first.published?(match.last)
+        end
+
+        def relationship_entries(declaration)
+          return [] unless %i[class module].include?(declaration.kind) && !declaration.refinement
+
+          entries = []
+          entries << [:superclass, declaration.superclass, declaration.superclass_span] if declaration.superclass
+          entries << [:container_builder, declaration.container_builder, declaration.container_builder_span] if declaration.container_builder
+          entries.concat(declaration.mixins.map { |mixin| [mixin.kind, mixin.target, mixin.span] })
+          entries.map do |kind, expression, span|
+            constant = expression.match?(/\A(?:::)?[[:upper:]\p{Lt}][[:word:]]*(?:::[[:upper:]\p{Lt}][[:word:]]*)*\z/)
+            match = resolve_scoped(expression, declaration, outer: kind == :superclass, containers: true) if constant && kind != :container_builder
+            expected_kind = (kind == :superclass) ? :class : :module
+            match = nil if match && match.last.kind != expected_kind
+            targets = match ? match.first.relationship_targets(match.last) : []
+            targets.each { |target| @build.record_link(@paths.fetch(declaration), target.fetch(:path), target.fetch(:anchor)) }
+            status = if !targets.empty?
+              :resolved
+            elsif constant && kind != :container_builder
+              :unresolved
+            else
+              :expression
+            end
+            @build.warn_relationship(kind, expression, declaration) unless status == :resolved
+            {kind: kind, expression: expression, span: span, status: status, targets: targets}
+          end
+        end
+
+        def link_destination(match, declaration)
+          path, anchor = match.first.destination(match.last)
+          @build.record_link(@paths.fetch(declaration), path, anchor)
+          "#{relative_url(@paths.fetch(declaration), path)}##{anchor}"
+        end
+
+        def render_prose(description, declaration)
+          ReferenceMarkup.rewrite(description) do |scheme, reference, label|
+            yield if block_given?
+            match = resolve_scoped(reference, declaration)
+            next unless match
+            next if (scheme == "c") != %i[class module].include?(match.last.kind)
+
+            title = label || reference
+            unless label && ReferenceMarkup.code_label?(label)
+              title = title.gsub(/\\([\\\[\]])/, '\1') if label
+              title = escape_label(title)
+            end
+            "[#{title}](#{link_destination(match, declaration)})"
+          end
+        end
+
+        def render_reference(description, declaration)
+          explicit = false
+          prose = render_prose(description, declaration) { explicit = true }
+          return prose if explicit
+
+          reference, label = description.strip.split(/\s+/, 2)
+          return description unless reference
+          return super if reference.match?(/\A(?:https?:\/\/|mailto:)/)
+
+          match = resolve_scoped(reference, declaration)
+          match ? "[#{escape_label(label || reference)}](#{link_destination(match, declaration)})" : description
+        end
+      end
+    end
+  end
+end

data/lib/zard/doc/cli.rb

@@ -2,6 +2,7 @@
 
 require "optparse"
 require "zard/doc"
+require "zard/doc/build"
 
 module Zard
   module Doc
@@ -28,8 +29,12 @@ module Zard
           lint_command
         when "render"
           render_command
+        when "format"
+          format_command
+        when "build"
+          build_command
         else
-          usage_error("Expected the lint or render command.")
+          usage_error("Expected the lint, render, format, or build command.")
         end
       rescue OptionParser::ParseError => error
         usage_error(error.message)
@@ -37,6 +42,56 @@ module Zard
 
       private
 
+      def build_command
+        config = nil
+        layout = nil
+        format = "markdown"
+        scopes = []
+        lens_root = nil
+        rigor_command = nil
+        lens_workers = 4
+        lens_config = nil
+        OptionParser.new do |parser|
+          parser.on("--config FILE", "Read the documentation build configuration") { |value| config = value }
+          parser.on("--layout LAYOUT", %w[namespace file], "Override page organization") { |value| layout = value }
+          parser.on("--format FORMAT", %w[markdown json], "Write Markdown pages or export JSON to stdout") { |value| format = value }
+          parser.on("--scope NAME", "Build a scope and its documentation dependencies (repeatable)") { |value| scopes << value }
+          parser.on("--lens-root DIR", "Enrich JSON using experimental Rigor lens (requires zard-rigor)") { |value| lens_root = value }
+          parser.on("--rigor-command FILE", "Supported Rigor executable (default: rigor)") { |value| rigor_command = value }
+          parser.on("--lens-workers N", Integer, "Lens workers (default: 4)") { |value| lens_workers = value }
+          parser.on("--lens-config FILE", "Rigor configuration, relative to lens root") { |value| lens_config = value }
+        end.parse!(@argv)
+        return usage_error("Pass --config FILE without positional arguments.") unless config && @argv.empty?
+
+        return usage_error("--lens-root requires --format json.") if lens_root && format != "json"
+        return usage_error("--rigor-command requires --lens-root.") if rigor_command && !lens_root
+        return usage_error("--lens-config requires --lens-root.") if lens_config && !lens_root
+        return usage_error("--lens-workers must be non-negative.") if lens_workers.negative?
+
+        enricher = lens_enricher(lens_root, rigor_command || "rigor", lens_workers, lens_config) if lens_root
+        builder = Build.new(config, layout: layout, scopes: scopes, format: format, stdout: @stdout, enricher: enricher)
+        builder.run
+      rescue BuildError => error
+        @stderr.puts error.message
+        error.status
+      ensure
+        builder&.diagnostics&.each { |diagnostic| @stderr.puts diagnostic }
+      end
+
+      def lens_enricher(root, command, workers, config)
+        require "zard/rigor"
+        adapter = Zard::Rigor::Lens.new(root: root, command: command, workers: workers, config: config)
+        lambda do |data, base:|
+          adapter.enrich(data, base: base)
+        rescue Zard::Rigor::Error => error
+          raise BuildError, error.message
+        end
+      rescue LoadError => error
+        raise BuildError, "Install the optional zard-rigor gem to use --lens-root: #{error.message}"
+      rescue SystemCallError => error
+        raise BuildError, "Invalid lens project root: #{error.message}"
+      end
+
       def lint_command
         lint_option_parser.parse!(@argv)
         return usage_error("Pass at least one Ruby source file.") if @argv.empty?
@@ -72,6 +127,46 @@ module Zard
         end.uniq.sort
       end
 
+      def format_command
+        check = false
+        write = false
+        OptionParser.new do |parser|
+          parser.on("--check", "Check whether formatting would change source") { check = true }
+          parser.on("--write", "Write formatted source to files") { write = true }
+        end.parse!(@argv)
+        return usage_error("Choose either --check or --write.") if check && write
+        return usage_error("Pass at least one Ruby source file.") if @argv.empty?
+
+        paths = source_paths(@argv)
+        return usage_error("No Ruby source files were found.") if paths.empty?
+        return usage_error("Standard input cannot be used with --write.") if write && paths.include?("-")
+        return usage_error("Pass one input for stdout, or use --check or --write.") if !check && !write && paths.length != 1
+
+        results = paths.map do |path|
+          source = read_source(path)
+          return 2 unless source
+
+          [path, Zard.format(source, path: path)]
+        end
+        results.each do |_, result|
+          result.diagnostics.each { |diagnostic| @stderr.puts format_diagnostic(diagnostic) }
+        end
+        return 1 if results.any? { |_, result| result.diagnostics.any? { |diagnostic| diagnostic.severity == :error } }
+        return (results.any? { |_, result| result.changed? }) ? 1 : 0 if check
+
+        if write
+          results.each do |path, result|
+            File.binwrite(path, result.source) if result.changed?
+          rescue SystemCallError => error
+            @stderr.puts "#{path}: #{error.message}"
+            return 2
+          end
+        else
+          @stdout.print results.first[1].source
+        end
+        0
+      end
+
       def lint(paths)
         failed = false
         input_error = false
@@ -106,7 +201,7 @@ module Zard
         diagnostics.each { |diagnostic| @stderr.puts format_diagnostic(diagnostic) }
         return 1 if diagnostics.any? { |diagnostic| diagnostic.severity == :error }
 
-        markdown = documents.map { |document| Zard::Doc.render(document) }.reject(&:empty?).join("\n")
+        markdown = Renderer.render_documents(documents)
         @stdout.print markdown
         0
       end
@@ -145,6 +240,9 @@ module Zard
           Usage:
             zard-doc lint [--fail-on error|warning] PATH...
             zard-doc render PATH...
+            zard-doc format [--check | --write] PATH...
+            zard-doc build --config FILE [--scope NAME ...] [--layout namespace|file] [--format markdown|json]
+              [--lens-root DIR [--rigor-command FILE] [--lens-workers N] [--lens-config FILE]]
         USAGE
       end
     end