sleeping_king_studios-docs 0.2.0 → 0.3.0

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require 'cuprum/cli/files/generators'
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Helper command to populate the versions collection with past version data.
+  class BackfillVersions < Cuprum::Cli::Command # rubocop:disable Metrics/ClassLength
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    include Cuprum::Cli::Options::Quiet
+    include Cuprum::Cli::Options::Verbose
+
+    MAJOR_VERSION = /\A\d+\z/
+    private_constant :MAJOR_VERSION
+
+    MAJOR_MINOR_VERSION = /\A\d+\.\d+\z/
+    private_constant :MAJOR_MINOR_VERSION
+
+    MAJOR_MINOR_PATCH_VERSION = /\A\d+\.\d+\.\d+(\.)?/
+    private_constant :MAJOR_MINOR_PATCH_VERSION
+
+    NEXT_STEPS_MESSAGE = <<~OUTPUT
+      Next Steps
+
+        Update _config.yml:
+
+        - In %<docs_path>s/_config.yml, add `versions: { output: false }` to `collections`.
+        - In %<docs_path>s/_config.yml, remove `project_metadata.versions`.
+
+        Update _includes/pages/index-versions.md:
+
+        - In %<docs_path>s/_includes/pages/index-versions.md, replace the latest_version check with the following:
+
+        ```ruby
+        {%% assign latest_version = site.versions | sort: "sortable" | map: "version" | last %%}
+        ```
+
+        Update versions/index.md:
+
+        - In %<docs_path>s/versions/index.md, replace the versions loop with the following:
+
+        ```ruby
+        {%% assign versions = site.versions | sort: "sortable" | map: "version" | reverse %%}
+        {%% for version in versions %%}
+        - [Version {{ version }}]({{site.baseurl}}/versions/{{version}})
+        {%%- endfor %%}
+        ```
+    OUTPUT
+    private_constant :NEXT_STEPS_MESSAGE
+
+    full_name 'docs:jekyll:backfill_versions'
+
+    description 'Backfills the versions collection'
+
+    dependency :file_system
+    dependency :standard_io
+
+    option :docs_path, default: 'docs'
+
+    option :dry_run, type: :boolean, default: false
+
+    private
+
+    attr_reader :files
+
+    attr_reader :versions
+
+    def configured_versions
+      say "Checking _config.yml for existing versions...\n\n"
+
+      data = parse_config_file&.dig('project_metadata', 'versions')
+
+      return [] unless data.is_a?(Array)
+
+      say "  Found versions #{data.join(', ')}\n\n"
+
+      data.map(&:to_s)
+    end
+
+    def create_version(version) # rubocop:disable Metrics/MethodLength
+      result =
+        SleepingKingStudios::Docs::Jekyll::Generators::VersionGenerator
+        .new(
+          file_system:,
+          standard_io:,
+          docs_path:,
+          dry_run:     dry_run?,
+          quiet:       quiet?,
+          verbose:     verbose?,
+          version:
+        )
+        .call
+
+      files.concat(result.value) if result.success?
+    end
+
+    def create_versions_directory
+      dir_path = File.join(docs_path, '_versions')
+
+      file_system.create_directory(dir_path, recursive: true) unless dry_run?
+
+      say "Successfully generated versions collection at #{dir_path}.\n\n"
+    end
+
+    def display_message
+      say "\n" unless versions.empty? || verbose?
+
+      say format(NEXT_STEPS_MESSAGE, docs_path:)
+    end
+
+    def parse_config_file
+      raw = read_config_file
+
+      return unless raw
+
+      YAML.safe_load(raw)
+    rescue Psych::SyntaxError => exception
+      file_path = File.join(docs_path, '_config.yml')
+
+      warn \
+        "  Unable to parse config file at #{file_path} - #{exception.class}: " \
+        "#{exception.message}\n\n"
+    end
+
+    def process
+      @files    = []
+      @versions = []
+
+      versions.concat(configured_versions)
+      versions.concat(version_directories)
+
+      step { create_versions_directory }
+
+      versions.compact.uniq.each do |version|
+        step { create_version(version) }
+      end
+
+      display_message
+
+      files
+    end
+
+    def read_config_file
+      file_path = File.join(docs_path, '_config.yml')
+
+      file_system.read_file(file_path)
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      warn \
+        "  Unable to read config file - #{exception.class}: " \
+        "#{exception.message}\n\n"
+    end
+
+    def version_directories
+      say "Checking versions directory for existing versions...\n\n"
+
+      matching =
+        file_system
+        .each_file("#{docs_path}/versions/*")
+        .select { |file_name| file_system.directory?(file_name) }
+        .map { |file_name| File.basename(file_name) }
+        .select { |segment| version_string?(segment) }
+
+      say "  Found versions #{matching.join(', ')}\n\n" unless matching.empty?
+
+      matching
+    end
+
+    def version_string?(value)
+      MAJOR_VERSION.match?(value) ||
+        MAJOR_MINOR_VERSION.match?(value) ||
+        MAJOR_MINOR_PATCH_VERSION.match?(value)
+    end
+  end
+end

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