docyard 1.0.2 → 1.1.0

data/lib/docyard/doctor.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "doctor/config_checker"
+require_relative "doctor/sidebar_checker"
+require_relative "doctor/content_checker"
+require_relative "doctor/component_checker"
+require_relative "doctor/code_block_checker"
+require_relative "doctor/link_checker"
+require_relative "doctor/image_checker"
+require_relative "doctor/orphan_checker"
+require_relative "doctor/file_scanner"
+require_relative "doctor/config_fixer"
+require_relative "doctor/sidebar_fixer"
+require_relative "doctor/markdown_fixer"
+require_relative "doctor/reporter"
+
+module Docyard
+  class Doctor
+    attr_reader :config, :docs_path, :fix
+
+    def initialize(fix: false)
+      @fix = fix
+      @config = load_config_safely
+      @docs_path = config&.source || "docs"
+    end
+
+    def run
+      fix ? run_with_fix : run_check_only
+    end
+
+    private
+
+    def run_check_only
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      diagnostics, stats = collect_diagnostics
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+      reporter = Reporter.new(diagnostics, stats, duration: duration)
+      reporter.print
+      reporter.exit_code
+    end
+
+    def run_with_fix
+      config_fixer = ConfigFixer.new
+      sidebar_fixer = SidebarFixer.new(docs_path)
+      markdown_fixer = MarkdownFixer.new(docs_path)
+
+      run_config_fix_loop(config_fixer)
+      run_sidebar_fix(sidebar_fixer)
+      run_markdown_fix(markdown_fixer)
+
+      print_fix_results(config_fixer, sidebar_fixer, markdown_fixer)
+
+      diagnostics_after, _stats_after = collect_diagnostics
+      remaining_errors = diagnostics_after.count(&:error?)
+
+      print_remaining_issues(diagnostics_after) if remaining_errors.positive?
+      remaining_errors.positive? ? 1 : 0
+    end
+
+    def run_config_fix_loop(fixer)
+      max_iterations = 10
+      max_iterations.times do
+        reload_config
+        diagnostics, _stats = collect_diagnostics
+        config_diagnostics = diagnostics.select { |d| d.category == :CONFIG && d.fixable? }
+        break if config_diagnostics.empty?
+
+        count_before = fixer.fixed_count
+        fixer.fix(config_diagnostics)
+        break if fixer.fixed_count == count_before # no progress made
+      end
+    end
+
+    def run_sidebar_fix(fixer)
+      diagnostics, _stats = collect_diagnostics
+      sidebar_diagnostics = diagnostics.select { |d| d.category == :SIDEBAR && d.fixable? }
+      fixer.fix(sidebar_diagnostics)
+    end
+
+    def run_markdown_fix(fixer)
+      diagnostics, _stats = collect_diagnostics
+      component_diagnostics = diagnostics.select { |d| d.category == :COMPONENT && d.fixable? }
+      fixer.fix(component_diagnostics)
+    end
+
+    def reload_config
+      @config = load_config_safely
+    end
+
+    def print_fix_results(config_fixer, sidebar_fixer, markdown_fixer)
+      print_fix_header
+      fixers = [
+        [config_fixer, "docyard.yml"],
+        [sidebar_fixer, "_sidebar.yml"],
+        [markdown_fixer, "markdown files"]
+      ]
+      total_fixed = fixers.sum { |f, _| f.fixed_count }
+
+      total_fixed.positive? ? print_all_fixes(fixers, total_fixed) : print_no_fixes
+    end
+
+    def print_all_fixes(fixers, total_fixed)
+      fixers.each { |fixer, name| print_fixer_results(fixer, name) }
+      puts "  #{UI.success("Fixed #{total_fixed} issue(s) total")}"
+    end
+
+    def print_fixer_results(fixer, name)
+      return unless fixer.fixed_count.positive?
+
+      puts "  Fixed #{fixer.fixed_count} issue(s) in #{name}:"
+      print_fixed_issues(fixer) if fixer.respond_to?(:fixed_issues)
+      puts
+    end
+
+    def print_fixed_issues(fixer)
+      fixer.fixed_issues.each { |d| puts "    #{UI.dim(d.location)}: #{describe_fix(d)}" }
+    end
+
+    def print_no_fixes
+      puts "  #{UI.yellow('No issues were auto-fixed.')}"
+    end
+
+    def print_fix_header
+      puts
+      puts "  #{UI.bold('Docyard')} v#{VERSION}"
+      puts
+    end
+
+    def describe_fix(diagnostic)
+      case diagnostic.fix[:type]
+      when :rename then "renamed '#{diagnostic.fix[:from]}' to '#{diagnostic.fix[:to]}'"
+      when :replace then "changed to #{diagnostic.fix[:value].inspect}"
+      when :line_replace then "replaced '#{diagnostic.fix[:from]}' with '#{diagnostic.fix[:to]}'"
+      else "fixed"
+      end
+    end
+
+    def print_remaining_issues(diagnostics)
+      puts
+      puts "  Remaining issues:"
+      diagnostics.reject(&:fixable?).each { |d| puts "    #{d.location}: #{d.message}" }
+      puts
+    end
+
+    def load_config_safely
+      Config.load(Dir.pwd)
+    rescue ConfigError
+      nil
+    end
+
+    def collect_diagnostics
+      file_scanner = FileScanner.new(docs_path)
+      scanner_diagnostics = file_scanner.scan
+
+      diagnostics = [
+        collect_config_and_sidebar_diagnostics,
+        scanner_diagnostics,
+        config ? OrphanChecker.new(docs_path, config).check : []
+      ].flatten
+
+      stats = {
+        files: file_scanner.files_scanned,
+        links: file_scanner.links_checked,
+        images: file_scanner.images_checked
+      }
+
+      [diagnostics, stats]
+    end
+
+    def collect_config_and_sidebar_diagnostics
+      diagnostics = []
+      diagnostics.concat(ConfigChecker.new(config).check) if config
+      diagnostics.concat(SidebarChecker.new(docs_path).check)
+      diagnostics
+    end
+  end
+end

data/lib/docyard/editor_launcher.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Docyard
+  module EditorLauncher
+    EDITORS = {
+      vscode: {
+        patterns: ["code", "Code", "Visual Studio Code"],
+        command: ->(f, l) { ["code", "--goto", "#{f}:#{l}"] }
+      },
+      cursor: { patterns: %w[cursor Cursor], command: ->(f, l) { ["cursor", "--goto", "#{f}:#{l}"] } },
+      zed: { patterns: %w[zed Zed], command: ->(f, l) { ["zed", "#{f}:#{l}"] } },
+      webstorm: { patterns: %w[webstorm idea], command: ->(f, l) { ["webstorm", "--line", l.to_s, f] } },
+      rubymine: { patterns: %w[rubymine mine], command: ->(f, l) { ["rubymine", "--line", l.to_s, f] } },
+      vim: { patterns: %w[vim nvim], command: ->(f, l) { [detect_vim, "+#{l}", f] } },
+      emacs: { patterns: %w[emacs], command: ->(f, l) { ["emacs", "+#{l}", f] } }
+    }.freeze
+
+    class << self
+      def available?
+        !detect.nil?
+      end
+
+      def detect
+        detect_from_env || detect_from_process
+      end
+
+      def open(file, line = 1)
+        editor = detect
+        return false unless editor
+
+        command = EDITORS[editor][:command].call(file, line)
+        spawn(*command, %i[out err] => File::NULL)
+        true
+      rescue StandardError => e
+        Docyard.logger.warn("Failed to open editor: #{e.message}")
+        false
+      end
+
+      private
+
+      def detect_from_env
+        %i[VISUAL EDITOR].each do |var|
+          editor_cmd = ENV.fetch(var.to_s, nil)
+          next unless editor_cmd
+
+          EDITORS.each do |name, config|
+            return name if config[:patterns].any? { |p| editor_cmd.include?(p) }
+          end
+        end
+        nil
+      end
+
+      def detect_from_process
+        return detect_windows_apps if Gem.win_platform?
+        return nil unless command_exists?("pgrep")
+
+        EDITORS.each do |name, config|
+          config[:patterns].each do |pattern|
+            return name if process_running?(pattern)
+          end
+        end
+
+        detect_macos_apps
+      end
+
+      def process_running?(pattern)
+        system("pgrep", "-x", pattern, out: File::NULL, err: File::NULL)
+      end
+
+      def detect_macos_apps
+        return nil unless RUBY_PLATFORM.include?("darwin")
+
+        macos_apps = {
+          vscode: "Visual Studio Code",
+          cursor: "Cursor",
+          zed: "Zed"
+        }
+
+        macos_apps.each do |editor, app_name|
+          return editor if macos_app_running?(app_name)
+        end
+
+        nil
+      end
+
+      def macos_app_running?(app_name)
+        system("pgrep", "-f", app_name, out: File::NULL, err: File::NULL)
+      end
+
+      def detect_windows_apps
+        windows_apps = {
+          vscode: "Code.exe",
+          cursor: "Cursor.exe",
+          zed: "zed.exe",
+          webstorm: "webstorm64.exe",
+          rubymine: "rubymine64.exe"
+        }
+
+        windows_apps.each do |editor, exe|
+          return editor if windows_process_running?(exe)
+        end
+
+        nil
+      end
+
+      def windows_process_running?(exe)
+        system("tasklist /FI \"IMAGENAME eq #{exe}\" 2>NUL | find /I \"#{exe}\" >NUL")
+      end
+
+      def command_exists?(cmd)
+        system("which", cmd, out: File::NULL, err: File::NULL)
+      end
+
+      def detect_vim
+        command_exists?("nvim") ? "nvim" : "vim"
+      end
+    end
+  end
+end

data/lib/docyard/errors.rb

@@ -7,54 +7,5 @@ module Docyard
 
   class SidebarConfigError < Error; end
 
-  class FileNotFoundError < Error
-    attr_reader :path
-
-    def initialize(path)
-      @path = path
-      super("File not found: #{path}")
-    end
-  end
-
-  class InvalidPathError < Error; end
-
-  class MarkdownParseError < Error
-    attr_reader :file_path, :original_error
-
-    def initialize(file_path, original_error)
-      @file_path = file_path
-      @original_error = original_error
-      super("Failed to parse markdown file #{file_path}: #{original_error.message}")
-    end
-  end
-
-  class TemplateRenderError < Error
-    attr_reader :template_path, :original_error
-
-    def initialize(template_path, original_error)
-      @template_path = template_path
-      @original_error = original_error
-      super("Failed to render template #{template_path}: #{original_error.message}")
-    end
-  end
-
-  class ReloadCheckError < Error
-    attr_reader :original_error
-
-    def initialize(original_error)
-      @original_error = original_error
-      super("Reload check failed: #{original_error.message}")
-    end
-  end
-
-  class AssetNotFoundError < Error
-    attr_reader :asset_path
-
-    def initialize(asset_path)
-      @asset_path = asset_path
-      super("Asset not found: #{asset_path}")
-    end
-  end
-
   class BuildError < Error; end
 end

data/lib/docyard/initializer.rb

@@ -47,21 +47,23 @@ module Docyard
     end
 
     def user_confirms_overwrite?
-      print "\nOverwrite existing files? [y/N] "
+      puts
+      print "  Overwrite existing files? [y/N] "
       response = $stdin.gets&.strip&.downcase
       %w[y yes].include?(response)
     end
 
     def print_existing_files_warning
-      puts ""
-      puts "\e[33mWarning:\e[0m Existing files found:"
-      puts "  - #{docs_path}/" if File.exist?(docs_path)
-      puts "  - #{config_path}" if File.exist?(config_path)
+      puts
+      puts "  #{UI.yellow('Warning:')} Existing files found:"
+      puts "    #{docs_path}/" if File.exist?(docs_path)
+      puts "    #{config_path}" if File.exist?(config_path)
     end
 
     def print_abort_message
-      puts ""
-      puts "Aborted. Use \e[1m--force\e[0m to overwrite existing files."
+      puts
+      puts "  #{UI.yellow('Aborted.')} Use --force to overwrite existing files."
+      puts
     end
 
     def create_project_directory
@@ -103,48 +105,39 @@ module Docyard
     end
 
     def print_success
-      puts ""
-      puts "\e[32m#{success_icon} Docyard project initialized successfully!\e[0m"
-      puts ""
+      puts
+      puts "  #{UI.bold('Docyard')} v#{VERSION}"
+      puts
+      puts "  #{UI.success('Project initialized')}"
+      puts
       print_created_structure
       print_next_steps
     end
 
-    def success_icon
-      "\u2714"
-    end
-
-    def print_created_structure
-      puts "Created:"
-      puts ""
+    def print_created_structure # rubocop:disable Metrics/AbcSize
+      puts "  #{UI.bold('Created:')}"
       if project_name
-        puts "  \e[1m#{project_name}/\e[0m"
-        puts "  \u251C\u2500\u2500 docyard.yml"
-        puts "  \u2514\u2500\u2500 docs/"
+        puts UI.dim("    #{project_name}/")
+        puts UI.dim("      docyard.yml")
+        puts UI.dim("      docs/")
       else
-        puts "  \e[1mdocyard.yml\e[0m"
-        puts "  \e[1mdocs/\e[0m"
+        puts UI.dim("    docyard.yml")
+        puts UI.dim("    docs/")
       end
-      puts "      \u251C\u2500\u2500 _sidebar.yml"
-      puts "      \u251C\u2500\u2500 index.md"
-      puts "      \u251C\u2500\u2500 getting-started.md"
-      puts "      \u251C\u2500\u2500 components.md"
-      puts "      \u2514\u2500\u2500 public/"
-      puts ""
+      puts UI.dim("        _sidebar.yml")
+      puts UI.dim("        index.md")
+      puts UI.dim("        getting-started.md")
+      puts UI.dim("        components.md")
+      puts UI.dim("        public/")
+      puts
     end
 
     def print_next_steps
-      puts "Next steps:"
-      puts ""
-      if project_name
-        puts "  \e[1mcd #{project_name}\e[0m"
-        puts ""
-      end
-      puts "  Start the development server:"
-      puts "  \e[1m$ docyard serve\e[0m"
-      puts ""
-      puts "  Then open \e[4mhttp://localhost:4200\e[0m in your browser"
-      puts ""
+      puts "  #{UI.bold('Next steps:')}"
+      puts "    cd #{project_name}" if project_name
+      puts "    docyard serve"
+      puts "    Open #{UI.cyan('http://localhost:4200')}"
+      puts
     end
   end
 end

data/lib/docyard/navigation/sidebar/local_config_loader.rb

@@ -7,10 +7,11 @@ module Docyard
     class LocalConfigLoader
       SIDEBAR_CONFIG_FILE = "_sidebar.yml"
 
-      attr_reader :docs_path
+      attr_reader :docs_path, :key_errors
 
-      def initialize(docs_path)
+      def initialize(docs_path, validate: true)
         @docs_path = docs_path
+        @validate = validate
         @key_errors = []
       end
 
@@ -56,18 +57,18 @@ module Docyard
       def validate_items(items, path_prefix: "")
         return unless items.is_a?(Array)
 
-        items.each_with_index do |item, idx|
-          validate_item(item, "#{path_prefix}[#{idx}]")
+        items.each do |item|
+          validate_item(item, path_prefix)
         end
       end
 
-      def validate_item(item, context)
+      def validate_item(item, path_prefix)
         return unless item.is_a?(Hash)
 
         if external_link?(item)
-          validate_external_link(item, context)
+          validate_external_link(item, path_prefix)
         else
-          validate_sidebar_item(item, context)
+          validate_sidebar_item(item, path_prefix)
         end
       end
 
@@ -75,39 +76,61 @@ module Docyard
         item.key?("link") || item.key?(:link)
       end
 
-      def validate_external_link(item, context)
-        errors = Config::KeyValidator.validate(item, Config::Schema::SIDEBAR_EXTERNAL_LINK, context: context)
+      def validate_external_link(item, path_prefix)
+        link_text = item["text"] || item[:text] || item["link"] || item[:link]
+        context = build_context(path_prefix, link_text)
+        errors = Config::Schema.validate_keys(item, Config::Schema::SIDEBAR_EXTERNAL_LINK_KEYS, context: context)
         @key_errors.concat(errors)
       end
 
-      def validate_sidebar_item(item, context)
+      def validate_sidebar_item(item, path_prefix)
         slug, options = extract_slug_and_options(item)
+
+        if slug.nil?
+          @key_errors << build_invalid_format_error(item, path_prefix)
+          return
+        end
+
         return unless options.is_a?(Hash)
 
-        errors = Config::KeyValidator.validate(options, Config::Schema::SIDEBAR_ITEM, context: context)
+        context = build_context(path_prefix, slug)
+        errors = Config::Schema.validate_keys(options, Config::Schema::SIDEBAR_ITEM_KEYS, context: context)
         @key_errors.concat(errors)
-        validate_nested_items(options, slug, context)
+        validate_nested_items(options, context)
+      end
+
+      def build_invalid_format_error(item, path_prefix)
+        item_desc = item.keys.first&.to_s || "item"
+        context = build_context(path_prefix, item_desc)
+        {
+          context: context,
+          message: "invalid format, expected slug-based key (e.g., 'page-name:' or '- page-name')"
+        }
       end
 
       def extract_slug_and_options(item)
-        first_key = item.keys.first
-        if first_key.is_a?(String) && !external_link?(item)
-          [first_key, item[first_key]]
-        else
-          [nil, item]
-        end
+        return [nil, item] if item.keys.size != 1
+
+        slug = item.keys.first
+        slug.is_a?(String) ? [slug, item[slug]] : [nil, item]
+      end
+
+      def build_context(prefix, name)
+        return name.to_s if prefix.empty?
+
+        "#{prefix}.#{name}"
       end
 
-      def validate_nested_items(options, slug, context)
+      def validate_nested_items(options, context)
         nested = options["items"] || options[:items]
         return unless nested
 
-        nested_context = slug ? "#{context}.#{slug}" : context
-        validate_items(nested, path_prefix: nested_context)
+        validate_items(nested, path_prefix: context)
       end
 
       def report_key_errors
         return if @key_errors.empty?
+        return unless @validate
 
         messages = @key_errors.map { |e| "#{e[:context]}: #{e[:message]}" }
         raise ConfigError, "Error in #{config_file_path}:\n#{messages.join("\n")}"

data/lib/docyard/rendering/icon_helpers.rb

@@ -2,15 +2,13 @@
 
 module Docyard
   module IconHelpers
-    VALID_WEIGHTS = %w[regular bold fill light thin duotone].freeze
-
     def icon(name, weight = "regular")
       name = name.to_s
       return name if name.strip.start_with?("<svg")
 
       name = name.tr("_", "-")
       weight = weight.to_s
-      weight = "regular" unless VALID_WEIGHTS.include?(weight)
+      weight = "regular" unless Icons::VALID_WEIGHTS.include?(weight)
       weight_class = weight == "regular" ? "ph" : "ph-#{weight}"
       %(<i class="#{weight_class} ph-#{name}" aria-hidden="true"></i>)
     end

data/lib/docyard/search/build_indexer.rb

@@ -18,39 +18,26 @@ module Docyard
       end
 
       def index
-        return 0 unless search_enabled?
-
-        log "Generating search index..."
-
-        unless pagefind_available?
-          warn_pagefind_missing
-          return 0
-        end
+        return [0, nil] unless search_enabled?
+        return [0, nil] unless pagefind_available?
 
         run_pagefind
       end
 
       private
 
-      def warn_pagefind_missing
-        log_warning "[!] Search index skipped: Pagefind not found"
-        log_warning "    Install with: npm install -g pagefind"
-        log_warning "    Or run: npx pagefind --site #{output_dir}"
-      end
-
       def run_pagefind
         args = build_pagefind_args(output_dir)
-        log "Running: npx #{args.join(' ')}" if verbose
 
         stdout, stderr, status = Open3.capture3(PAGEFIND_COMMAND, *args)
 
         if status.success?
-          page_count = extract_page_count(stdout)
-          log "[+] Generated search index (#{page_count} pages indexed)"
-          page_count
+          count = extract_page_count(stdout)
+          details = verbose ? collect_index_details : nil
+          [count, details]
         else
-          log_warning "[!] Search indexing failed: #{stderr}"
-          0
+          Docyard.logger.warn("Search indexing failed: #{stderr}") if verbose
+          [0, nil]
         end
       end
 
@@ -62,12 +49,40 @@ module Docyard
         end
       end
 
-      def log(message)
-        Docyard.logger.info(message)
+      def collect_index_details
+        indexed, excluded = classify_pages
+        format_index_details(indexed, excluded)
+      end
+
+      def classify_pages
+        indexed = []
+        excluded = []
+
+        Dir.glob(File.join(output_dir, "**", "index.html")).each do |file|
+          path = extract_page_path(file)
+          classify_page(File.read(file), path, indexed, excluded)
+        end
+
+        [indexed, excluded]
+      end
+
+      def extract_page_path(file)
+        path = file.delete_prefix("#{output_dir}/").delete_suffix("/index.html")
+        path.empty? ? "/" : path
+      end
+
+      def classify_page(content, path, indexed, excluded)
+        if content.include?("data-pagefind-body")
+          indexed << path
+        elsif content.include?("data-pagefind-ignore")
+          excluded << path
+        end
       end
 
-      def log_warning(message)
-        Docyard.logger.warn(message)
+      def format_index_details(indexed, excluded)
+        details = indexed.sort
+        excluded.sort.each { |path| details << "(excluded: #{path})" } if excluded.any?
+        details
       end
     end
   end