sleeping_king_studios-docs 0.2.1 → 0.3.0

data/lib/sleeping_king_studios/docs/jekyll/commands/check.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Checks whether the current documentation is up to date.
+  class Check < SleepingKingStudios::Docs::Jekyll::Commands::Reference # rubocop:disable Metrics/ClassLength
+    full_name 'docs:jekyll:check'
+
+    description 'Checks whether the current documentation is up to date'
+
+    option :inspect_changes,
+      aliases: %i[inspect],
+      type:    :boolean,
+      default: false
+
+    private
+
+    attr_reader :changed_files
+
+    attr_reader :extra_files
+
+    attr_reader :missing_files
+
+    attr_reader :registry
+
+    def build_command
+      @build_command ||= SleepingKingStudios::Docs::Yard::Build.new
+    end
+
+    def collection_path_for(data)
+      data_type = data_type_for(data)
+
+      data_collections[data_type]
+    end
+
+    def compare_files(actual:, expected:)
+      # Skip the full analysis if all files are matching.
+      return if actual == expected
+
+      missing  = find_missing_files(actual:, expected:)
+      extra    = find_extra_files(actual:, expected:)
+      matching = expected.except(*missing).reject { |_, value| value == true }
+      changed  = find_changed_files(actual:, matching:)
+
+      @missing_files.concat(missing)
+      @extra_files.concat(extra)
+      @changed_files.concat(changed)
+    end
+
+    def data_collections
+      @data_collections ||= Hash.new do |hsh, data_type|
+        hsh[data_type] = tools.string_tools.pluralize(data_type)
+      end
+    end
+
+    def data_file_for(data)
+      "#{data_path_for(data)}/#{data.data_path}.yml"
+    end
+
+    def data_path_for(data)
+      collection_path = collection_path_for(data)
+
+      if version
+        File.join(docs_path, "_#{collection_path}", "version--#{version}")
+      else
+        File.join(docs_path, "_#{collection_path}")
+      end
+    end
+
+    def data_type_for(data)
+      data
+        .class
+        .name
+        .split('::')
+        .last
+        .sub(/Object\z/, '')
+        .then { |str| tools.string_tools.underscore(str) }
+        .then { |str| str == 'root' ? 'namespace' : str }
+    end
+
+    def file_not_found_error(**)
+      SleepingKingStudios::Docs::Errors::FileError.new(**)
+    end
+
+    def find_changed_files(actual:, matching:)
+      return [] if matching.empty?
+
+      matching
+        .reject { |key, value| value == actual[key] }
+        .keys
+    end
+
+    def find_data_files
+      [
+        *each_data_file(class_data_directory),
+        *each_data_file(constant_data_directory),
+        *each_data_file(method_data_directory),
+        *each_data_file(module_data_directory),
+        *each_data_file(namespace_data_directory)
+      ]
+        .to_h { |file_path| [file_path, step { read_checksum(file_path) }] }
+    end
+
+    def find_expected_files
+      expected_data      = {}
+      expected_reference = {}
+
+      registry.each do |native|
+        data = step { build_command.call(native) }
+
+        next unless data.public?
+
+        expected_data[data_file_for(data)] = data.checksum
+
+        next unless reference?(data)
+
+        expected_reference[reference_file_for(data)] = true
+      end
+
+      [expected_data, expected_reference]
+    end
+
+    def find_extra_files(actual:, expected:)
+      actual.each_key.reject { |key| expected.key?(key) }
+    end
+
+    def find_missing_files(actual:, expected:)
+      expected.each_key.reject { |key| actual.key?(key) }
+    end
+
+    def find_native_object_for(file_path)
+      registry.each do |native|
+        data = step { build_command.call(native) }
+
+        next unless data.public?
+
+        next unless file_path == data_file_for(data)
+
+        return data
+      end
+
+      # :nocov:
+      nil
+      # :nocov:
+    end
+
+    def find_reference_files
+      each_reference_file.to_h { |file_path| [file_path, true] }
+    end
+
+    def generate_inspect_contents_for(object, mock_fs:)
+      SleepingKingStudios::Docs::Jekyll::Generators::DataGenerator
+        .new(object:, file_system: mock_fs, standard_io:, quiet: true)
+        .call
+    end
+
+    def indent(contents)
+      contents
+        .each_line
+        .map do |line|
+          next "\n" if line == "\n"
+
+          "  #{line}"
+        end
+        .join
+    end
+
+    def inspect_changed_files # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      return unless inspect_changes? && !changed_files.empty?
+
+      say "\n"
+      say '-' * 80
+      say "\n"
+
+      mock_fs = Cuprum::Cli::Dependencies::FileSystem::Mock.new
+
+      changed_files.each do |file_path|
+        data   = find_native_object_for(file_path)
+        result = generate_inspect_contents_for(data, mock_fs:)
+
+        next unless result.success?
+
+        say "Changed file #{file_path}:\n\n"
+
+        contents = mock_fs.read(file_path)
+
+        say indent(contents)
+        say "\n"
+      end
+    end
+
+    def outdated_documentation_error
+      SleepingKingStudios::Docs::Errors::OutdatedDocumentation.new(
+        docs_path:,
+        version:,
+        changed_files:,
+        extra_files:,
+        missing_files:
+      )
+    end
+
+    def parse_registry # rubocop:disable Metrics/MethodLength
+      @registry = step do
+        SleepingKingStudios::Docs::Yard::Parse.new.call
+      end
+
+      SleepingKingStudios::Docs::Yard::Registry
+        .provider
+        .set(:registry, registry)
+
+      registry
+    rescue Plumbum::Errors::ImmutableError => exception
+      message = "#{exception.class}: #{exception.message}"
+      error   = SleepingKingStudios::Docs::Errors::RegistryError.new(message:)
+
+      failure(error)
+    end
+
+    def process # rubocop:disable Metrics/MethodLength
+      say "Checking documentation for #{version_string}..."
+      say "\n", verbose: true
+
+      @missing_files  = []
+      @extra_files    = []
+      @changed_files  = []
+      data_files      = step { find_data_files }
+      reference_files = step { find_reference_files }
+
+      step { parse_registry }
+
+      expected_data_files, expected_reference_files = step do
+        find_expected_files
+      end
+
+      compare_files(actual: data_files,      expected: expected_data_files)
+      compare_files(actual: reference_files, expected: expected_reference_files)
+
+      report_results
+    end
+
+    def read_checksum(file_path) # rubocop:disable Metrics/MethodLength
+      raw  = file_system.read(file_path)
+      yaml = YAML.safe_load(raw)
+
+      yaml.fetch('checksum') do
+        warn_missing_checksum(file_path)
+
+        nil
+      end
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      failure(file_not_found_error(message: exception.message, path: file_path))
+    rescue Psych::SyntaxError => exception
+      message =
+        "unable to parse file - error occurred on line #{exception.line}, " \
+        "column #{exception.column}"
+
+      failure(file_not_found_error(message:, path: file_path))
+    end
+
+    def reference?(data)
+      data.is_a?(SleepingKingStudios::Docs::Data::ModuleObject)
+    end
+
+    def reference_file_for(data)
+      "#{reference_path}/#{data.data_path}.md"
+    end
+
+    def reference_path
+      @reference_path ||=
+        if version
+          File.join(docs_path, 'versions', version, 'reference')
+        else
+          File.join(docs_path, 'reference')
+        end
+    end
+
+    def report_changed_files
+      return if changed_files.empty?
+
+      say 'Changed files:', verbose: true
+      say "\n", verbose: true
+
+      changed_files.each do |file_path|
+        say "  - Changed file #{file_path}"
+      end
+
+      say "\n", verbose: true
+    end
+
+    def report_extra_files
+      return if extra_files.empty?
+
+      say 'Extra files:', verbose: true
+      say "\n", verbose: true
+
+      extra_files.each do |file_path|
+        say "  - Extra file #{file_path}"
+      end
+
+      say "\n", verbose: true
+    end
+
+    def report_missing_files
+      return if missing_files.empty?
+
+      say 'Missing files:', verbose: true
+      say "\n", verbose: true
+
+      missing_files.each do |file_path|
+        say "  - Missing file #{file_path}"
+      end
+
+      say "\n", verbose: true
+    end
+
+    def report_results
+      if changed_files.empty? && missing_files.empty? && extra_files.empty?
+        say 'Success!'
+
+        return []
+      end
+
+      report_missing_files
+      report_extra_files
+      report_changed_files
+
+      say 'Failure!'
+
+      inspect_changed_files
+
+      failure(outdated_documentation_error)
+    end
+
+    def version_string
+      version ? "version #{version}" : 'current version'
+    end
+
+    def warn_missing_checksum(file_path)
+      message = "Warning: file #{file_path} does not have a valid checksum\n"
+
+      standard_io.write_error(message)
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll/commands/clobber.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Clears out the existing reference documentation.
+  class Clobber < SleepingKingStudios::Docs::Jekyll::Commands::Reference
+    full_name 'docs:jekyll:clobber'
+
+    description \
+      'Removes any existing reference documentation for the current version'
+
+    private
+
+    attr_reader :errors
+
+    def aggregate_errors
+      result = yield
+
+      errors << result.error if result.failure?
+
+      result
+    end
+
+    def process
+      @errors = []
+
+      remove_reference_files
+
+      remove_data_files(class_data_directory,     as: 'class')
+      remove_data_files(constant_data_directory,  as: 'constant')
+      remove_data_files(method_data_directory,    as: 'method')
+      remove_data_files(module_data_directory,    as: 'module')
+      remove_data_files(namespace_data_directory, as: 'namespace')
+
+      report_errors
+    end
+
+    def remove_data_files(directory, as:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      data_count = each_data_file(directory).count
+
+      say "Removing #{data_count} #{as} objects from #{directory}..."
+      say("\n", verbose: true) unless data_count.zero?
+
+      each_data_file(directory) do |path|
+        aggregate_errors { delete_file(path) }
+      end
+
+      each_data_directory(directory) do |path|
+        aggregate_errors { delete_directory(path, recursive: true) }
+      end
+
+      if version && file_system.directory?(directory)
+        aggregate_errors { delete_directory(directory) }
+      end
+
+      say("\n", verbose: true)
+    end
+
+    def remove_reference_files
+      reference_count = each_reference_file.count
+
+      say "Removing #{reference_count} files from #{reference_directory}..."
+      say("\n", verbose: true) unless reference_count.zero?
+
+      each_reference_file do |path|
+        aggregate_errors { delete_file(path) }
+      end
+
+      each_reference_directory do |path|
+        aggregate_errors { delete_directory(path, recursive: true) }
+      end
+
+      say("\n", verbose: true)
+    end
+
+    def report_errors # rubocop:disable Metrics/MethodLength
+      if errors.empty?
+        say 'Success!'
+
+        return
+      end
+
+      warn 'Failures:'
+      warn "\n"
+
+      errors.each do |error|
+        warn "  - Unable to remove #{error.path} - #{error.message}"
+      end
+
+      warn "\n"
+
+      message = 'unable to remove documentation files'
+      error   = Cuprum::Errors::MultipleErrors.new(errors:, message:)
+
+      failure(error)
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll/commands/document_version.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Generates pinned documentation for the specified project version.
+  #
+  # - Adds the version to the _versions collection.
+  # - Generates reference documentation for the version.
+  # - Copies all static documentation files to the respective versions/*
+  #   subdirectory.
+  class DocumentVersion < Cuprum::Cli::Command # rubocop:disable Metrics/ClassLength
+    dependency :file_system
+    dependency :standard_io
+
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    include Cuprum::Cli::Options::Quiet
+    include Cuprum::Cli::Options::Verbose
+
+    argument :version, type: :string, required: true
+
+    option :docs_path, default: 'docs'
+
+    option :dry_run,   type: :boolean, default: false
+
+    full_name 'docs:jekyll:document_version'
+
+    description 'Generates pinned documentation for the specified version'
+
+    private
+
+    def copy_static_file(original_path)
+      relative_path = original_path.sub(%r{#{docs_path}/}, '')
+      updated_path  = File.join(docs_path, 'versions', version, relative_path)
+
+      contents       = file_system.read_file(original_path)
+      metadata, text = step { extract_front_matter(contents) }
+      metadata       = update_metadata(metadata:, relative_path:)
+      contents       = generate_contents(metadata:, text:)
+
+      files = step { write_static_file(contents:, updated_path:) }
+
+      @files.concat(files)
+    end
+
+    def copy_static_files
+      say "\nCopying static documentation..."
+      say("\n", verbose: true)
+
+      find_static_docs.each { |file_path| copy_static_file(file_path) }
+    end
+
+    def default_breadcrumbs_for(relative_path)
+      *dir_path, _ = relative_path.split(File::SEPARATOR)
+
+      return [] if dir_path.empty?
+
+      dir_path
+        .each
+        .map do |segment, index|
+          name = tools.string_tools.camelize(segment.tr('-_', ''))
+          path = "#{File::SEPARATOR}#{File.join(dir_path[0..index])}"
+
+          { 'name' => name, 'path' => path }
+        end
+    end
+
+    def exclude_static_file?(file_path)
+      return false if file_path == "#{docs_path}/reference/index.md"
+
+      file_path.start_with?("#{docs_path}/_includes/") ||
+        file_path.start_with?("#{docs_path}/reference") ||
+        file_path.start_with?("#{docs_path}/versions")
+    end
+
+    def extract_front_matter(contents)
+      return [{}, contents] unless contents.start_with?("---\n")
+
+      match = /^---\n$/.match(contents[4..])
+
+      return [{}, contents] unless match
+
+      text = match.post_match
+      yaml = YAML.safe_load(match.pre_match) || {}
+
+      [yaml, text]
+    end
+
+    def generate_contents(metadata:, text:)
+      "#{YAML.safe_dump(metadata)}---\n#{text}"
+    end
+
+    def generate_reference_files # rubocop:disable Metrics/MethodLength
+      say "\nGenerating data and reference files:"
+      say("\n", verbose: true)
+
+      files = step do
+        SleepingKingStudios::Docs::Jekyll::Commands::Generate
+          .new(file_system:, standard_io:)
+          .call(
+            docs_path:,
+            dry_run:   dry_run?,
+            quiet:     quiet?,
+            verbose:   verbose?,
+            version:
+          )
+      end
+
+      @files.concat(files)
+    end
+
+    def generate_version # rubocop:disable Metrics/MethodLength
+      say "\nGenerating version file:"
+      say("\n", verbose: true)
+
+      files = step do
+        SleepingKingStudios::Docs::Jekyll::Generators::VersionGenerator
+          .new(
+            file_system:,
+            standard_io:,
+            docs_path:,
+            dry_run:     dry_run?,
+            quiet:       quiet?,
+            verbose:     verbose?,
+            version:
+          )
+          .call
+      end
+
+      @files.concat(files)
+    end
+
+    def find_static_docs
+      file_system
+        .each_file("#{docs_path}/**/*.md")
+        .reject { |file_path| exclude_static_file?(file_path) }
+        .to_a
+    end
+
+    def process
+      say "Generating pinned documentation for version #{version}"
+
+      @files = []
+
+      step { generate_reference_files }
+
+      step { generate_version }
+
+      step { copy_static_files }
+
+      say "\nSuccess!"
+
+      @files
+    end
+
+    def top_level_breadcrumb?(obj)
+      obj.is_a?(Hash) && obj['path'] == File::SEPARATOR
+    end
+
+    def version_breadcrumbs # rubocop:disable Metrics/MethodLength
+      @version_breadcrumbs ||= [
+        {
+          'name' => 'Documentation',
+          'path' => File::SEPARATOR
+        },
+        {
+          'name' => 'Versions',
+          'path' => "#{File::SEPARATOR}versions"
+        },
+        {
+          'name' => "Version #{version}",
+          'path' => "#{File::SEPARATOR}#{File.join('versions', version)}"
+        }
+      ]
+    end
+
+    def update_breadcrumbs(breadcrumbs:, relative_path:)
+      prefix      = "#{File::SEPARATOR}#{File.join('versions', version)}"
+      breadcrumbs = breadcrumbs[1..] if top_level_breadcrumb?(breadcrumbs.first)
+      breadcrumbs = breadcrumbs.map do |hsh|
+        hsh.merge('path' => File.join(prefix, hsh['path']))
+      end
+
+      if breadcrumbs.empty? && relative_path == 'index.md'
+        return version_breadcrumbs[...-1]
+      end
+
+      version_breadcrumbs + breadcrumbs
+    end
+
+    def update_metadata(metadata:, relative_path:)
+      breadcrumbs = update_breadcrumbs(
+        breadcrumbs:   metadata.fetch(
+          'breadcrumbs',
+          default_breadcrumbs_for(relative_path)
+        ),
+        relative_path:
+      )
+
+      metadata.merge('breadcrumbs' => breadcrumbs, 'version' => version)
+    end
+
+    def write_static_file(contents:, updated_path:) # rubocop:disable Metrics/MethodLength
+      Cuprum::Cli::Files::Generators::BasicGenerator
+        .new(
+          file_system:,
+          standard_io:,
+          contents:,
+          dry_run:     dry_run?,
+          file_path:   updated_path,
+          quiet:       quiet?,
+          verbose:     verbose?
+        )
+        .call
+    end
+  end
+end