yard-yaml 0.1.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/yard/yaml/cli.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Yard
+  module Yaml
+    # CLI helpers to parse `.yardopts`/argv flags for yard-yaml.
+    #
+    # Phase 1: Only parses configuration flags and returns a Hash suitable for
+    # Yard::Yaml::Config#apply. It does not mutate global state.
+    module Cli
+      PREFIX = "--yard_yaml-"
+      NO_PREFIX = "--no-yard_yaml-"
+
+      class << self
+        # Parse argv for yard-yaml flags.
+        #
+        # Supported flags:
+        # - --yard_yaml-include <glob> (repeatable)
+        # - --yard_yaml-exclude <glob> (repeatable)
+        # - --yard_yaml-out_dir <dir>
+        # - --yard_yaml-index[=true|false] | --no-yard_yaml-index
+        # - --yard_yaml-front_matter[=true|false] | --no-yard_yaml-front_matter
+        # - --yard_yaml-strict[=true|false] | --no-yard_yaml-strict
+        # - --yard_yaml-allow_erb[=true|false] | --no-yard_yaml-allow_erb
+        # - --yard_yaml-toc <mode>
+        # - --yard_yaml-converter_options key:value[,key:value]
+        #
+        # @param argv [Array<String>]
+        # @return [Hash] normalized overrides
+        def parse(argv)
+          return {} if argv.nil? || argv.empty?
+
+          overrides = {}
+          i = 0
+          while i < argv.length
+            token = argv[i]
+
+            if token.start_with?(NO_PREFIX)
+              key = token.delete_prefix(NO_PREFIX).to_sym
+              apply_bool(overrides, key, false)
+              i += 1
+              next
+            end
+
+            unless token.start_with?(PREFIX)
+              i += 1
+              next
+            end
+
+            # handle --flag=value form
+            if token.include?("=")
+              flag, raw = token.split("=", 2)
+              key = flag.delete_prefix(PREFIX).to_sym
+              apply_kv(overrides, key, raw)
+              i += 1
+              next
+            end
+
+            key = token.delete_prefix(PREFIX).to_sym
+
+            case key
+            when :include, :exclude
+              value = argv[i + 1]
+              if value.nil? || value.start_with?("--")
+                warn_unknown("missing value for #{token}")
+                i += 1
+              else
+                arr = (overrides[key] ||= [])
+                arr << value.to_s
+                i += 2
+              end
+            when :out_dir, :toc
+              value = argv[i + 1]
+              if value.nil? || value.start_with?("--")
+                warn_unknown("missing value for #{token}")
+                i += 1
+              else
+                overrides[key] = value.to_s
+                i += 2
+              end
+            when :index, :front_matter, :strict, :allow_erb
+              # Bare presence means true
+              apply_bool(overrides, key, true)
+              i += 1
+            when :converter_options
+              value = argv[i + 1]
+              if value.nil? || value.start_with?("--")
+                warn_unknown("missing value for #{token}")
+                i += 1
+              else
+                overrides[:converter_options] = parse_converter_options(value)
+                i += 2
+              end
+            else
+              warn_unknown("unknown flag #{token}")
+              i += 1
+            end
+          end
+
+          overrides
+        end
+
+        private
+
+        def apply_kv(overrides, key, raw)
+          case key
+          when :include, :exclude
+            arr = (overrides[key] ||= [])
+            arr << raw.to_s
+          when :out_dir, :toc
+            overrides[key] = raw.to_s
+          when :index, :front_matter, :strict, :allow_erb
+            apply_bool(overrides, key, coerce_bool(raw))
+          when :converter_options
+            overrides[:converter_options] = parse_converter_options(raw)
+          else
+            warn_unknown("unknown flag --yard_yaml-#{key}")
+          end
+        end
+
+        def apply_bool(overrides, key, value)
+          overrides[key] = !!value
+        end
+
+        def coerce_bool(value)
+          case value.to_s.strip.downcase
+          when "", "true", "1", "yes", "y", "on" then true
+          when "false", "0", "no", "n", "off" then false
+          else
+            warn_unknown("invalid boolean '#{value}'")
+            false
+          end
+        end
+
+        def parse_converter_options(raw)
+          result = {}
+          raw.to_s.split(",").each do |pair|
+            k, v = pair.split(":", 2)
+            if k.nil? || v.nil?
+              warn_unknown("invalid converter option '#{pair}'")
+              next
+            end
+            result[k.to_s] = coerce_scalar(v)
+          end
+          result
+        end
+
+        def coerce_scalar(v)
+          s = v.to_s
+          low = s.strip.downcase
+          return true if %w[true yes y on 1].include?(low)
+          return false if %w[false no n off 0].include?(low)
+          begin
+            return Integer(s)
+          rescue
+            nil
+          end if s.match?(/\A[+-]?\d+\z/)
+          begin
+            return Float(s)
+          rescue
+            nil
+          end if s.match?(/\A[+-]?(?:\d+\.)?\d+\z/)
+          s
+        end
+
+        def warn_unknown(message)
+          # Delegate to unified helper to avoid NameError when a partial YARD stub exists.
+          if defined?(::Yard) && ::Yard.const_defined?(:Yaml)
+            ::Yard::Yaml.warn(message)
+          else
+            Kernel.warn("yard-yaml: #{message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/yaml/config.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Yard
+  module Yaml
+    # Configuration for the yard-yaml plugin.
+    #
+    # Phase 0: This is a data holder only; wiring into YARD will happen in later phases.
+    #
+    # Defaults are intentionally conservative and match the PRD/plan.
+    # Nothing here modifies YARD behavior when merely required.
+    class Config
+      # Default glob patterns to include during discovery.
+      DEFAULT_INCLUDE = [
+        "docs/**/*.y{a,}ml",
+        "*.y{a,}ml",
+        # CFF (Citation File Format) files are valid YAML; include them by default.
+        "docs/**/*.cff",
+        "*.cff",
+      ].freeze
+
+      # Default glob patterns to exclude during discovery.
+      DEFAULT_EXCLUDE = [
+        "**/_*.y{a,}ml",
+        "**/_*.cff",
+      ].freeze
+
+      # Directory (under YARD output) where converted pages will be written.
+      DEFAULT_OUT_DIR = "yaml"
+
+      # Whether to generate an index page for YAML documents.
+      DEFAULT_INDEX = true
+
+      # Table of contents generation strategy.
+      # "auto" defers to converter/page size; additional options may be added later.
+      DEFAULT_TOC = "auto"
+
+      # Options forwarded to yaml-converter.
+      DEFAULT_CONVERTER_OPTIONS = {}.freeze
+
+      # Whether to respect YAML front matter for title/nav order.
+      DEFAULT_FRONT_MATTER = true
+
+      # When true, errors are raised and should fail the build (later phases).
+      DEFAULT_STRICT = false
+
+      # Whether to allow ERB processing inside YAML (disabled by default for safety).
+      DEFAULT_ALLOW_ERB = false
+
+      attr_accessor :include,
+        :exclude,
+        :out_dir,
+        :index,
+        :toc,
+        :converter_options,
+        :front_matter,
+        :strict,
+        :allow_erb
+
+      # Create a new Config with defaults, optionally overridden via a hash.
+      #
+      # @param overrides [Hash] optional overrides for any attribute
+      def initialize(overrides = {})
+        @include = DEFAULT_INCLUDE.dup
+        @exclude = DEFAULT_EXCLUDE.dup
+        @out_dir = DEFAULT_OUT_DIR.dup
+        @index = DEFAULT_INDEX
+        @toc = DEFAULT_TOC.dup
+        @converter_options = DEFAULT_CONVERTER_OPTIONS.dup
+        @front_matter = DEFAULT_FRONT_MATTER
+        @strict = DEFAULT_STRICT
+        @allow_erb = DEFAULT_ALLOW_ERB
+
+        apply(overrides) unless overrides.nil? || overrides.empty?
+      end
+
+      # Apply a set of overrides to this config instance.
+      # Unknown keys are ignored in Phase 0 (later phases may warn).
+      #
+      # @param hash [Hash]
+      # @return [self]
+      def apply(hash)
+        hash.each do |key, value|
+          case key.to_sym
+          when :include then @include = Array(value).map(&:to_s)
+          when :exclude then @exclude = Array(value).map(&:to_s)
+          when :out_dir then @out_dir = value.to_s
+          when :index then @index = coerce_bool(value)
+          when :toc then @toc = value.to_s
+          when :converter_options then @converter_options = value || {}
+          when :front_matter then @front_matter = coerce_bool(value)
+          when :strict then @strict = coerce_bool(value)
+          when :allow_erb then @allow_erb = coerce_bool(value)
+          else
+            # Intentionally ignore unknown keys in Phase 0
+          end
+        end
+        self
+      end
+
+      private
+
+      # Coerce various truthy/falsey representations to a boolean.
+      # Accepts common string/number forms used in CLI and config files.
+      def coerce_bool(value)
+        case value
+        when true then true
+        when false, nil then false
+        when Integer
+          return true if value == 1
+          return false if value == 0
+          !!value
+        else
+          str = value.to_s.strip.downcase
+          return true if %w[true 1 yes y on].include?(str)
+          return false if %w[false 0 no n off].include?(str)
+          # Fallback to Ruby truthiness for anything else
+          !!value
+        end
+      end
+    end
+  end
+end

data/lib/yard/yaml/converter.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Yard
+  module Yaml
+    # Thin wrapper around the yaml-converter gem with safe defaults.
+    #
+    # Phase 2 scope:
+    # - Provide class methods to convert from a YAML string or a file path.
+    # - Apply safe defaults and respect config toggles (strict, allow_erb, front_matter).
+    # - Delegate conversion to an underlying backend (default: ::Yaml::Converter if available).
+    # - Return a normalized result Hash: { html:, title:, description:, meta: }.
+    #
+    # Note: We intentionally keep the contract minimal and stable. Tests stub the backend.
+    class Converter
+      class << self
+        # Assignable backend for dependency injection in tests.
+        # Expected to respond to `convert(yaml, options)` and return a Hash with :html, :title, :description, and :meta keys
+        attr_writer :backend
+
+        # Convert a YAML string into an HTML result.
+        #
+        # @param yaml [String]
+        # @param options [Hash] additional options passed to backend
+        # @param config [Yard::Yaml::Config] yard-yaml config (defaults to Yard::Yaml.config)
+        # @return [Hash] { html:, title:, description:, meta: }
+        def from_string(yaml, options = {}, config: Yard::Yaml.config)
+          run_convert(yaml.to_s, options, config)
+        end
+
+        # Convert a YAML file from disk.
+        #
+        # @param path [String]
+        # @param options [Hash]
+        # @param config [Yard::Yaml::Config]
+        # @return [Hash]
+        def from_file(path, options = {}, config: Yard::Yaml.config)
+          content = read_file(path)
+          return empty_result if content.nil?
+          run_convert(content, options.merge(source_path: path.to_s), config)
+        end
+
+        # Backend accessor with auto-discovery.
+        def backend
+          return @backend if defined?(@backend) && @backend
+          begin
+            require "yaml/converter"
+          rescue LoadError
+            # ignore; backend may be set by tests
+          end
+          @backend = if defined?(::Yaml) && ::Yaml.const_defined?(:Converter)
+            ::Yaml::Converter
+          end
+        end
+
+        private
+
+        def read_file(path)
+          File.read(path.to_s)
+        rescue Errno::ENOENT => e
+          handle_error(e, strict: Yard::Yaml.config.strict, context: "missing file: #{path}")
+          nil
+        end
+
+        def run_convert(yaml, options, config)
+          opts = build_options(options, config)
+          b = backend
+          unless b && b.respond_to?(:convert)
+            handle_error(Yard::Yaml::Error.new("yaml-converter backend not available"), strict: config.strict, context: "backend")
+            return empty_result
+          end
+
+          begin
+            normalize_result(b.convert(yaml, opts))
+          rescue StandardError => e
+            handle_error(e, strict: config.strict, context: opts[:source_path] || "string")
+            empty_result
+          end
+        end
+
+        def build_options(options, config)
+          safe = {
+            allow_erb: !!config.allow_erb,
+            front_matter: !!config.front_matter,
+          }
+          # Merge caller-supplied options and the config's converter_options map (caller wins)
+          safe.merge(config.converter_options || {}).merge(options || {})
+        end
+
+        def normalize_result(raw)
+          return empty_result if raw.nil?
+          {
+            html: raw[:html] || raw["html"] || "",
+            title: raw[:title] || raw["title"],
+            description: raw[:description] || raw["description"],
+            meta: raw[:meta] || raw["meta"] || {},
+          }
+        end
+
+        def empty_result
+          {html: "", title: nil, description: nil, meta: {}}
+        end
+
+        def handle_error(error, strict:, context: nil)
+          if strict
+            raise Yard::Yaml::Error, error.message
+          else
+            message = context ? "#{error.class}: #{error.message} (#{context})" : "#{error.class}: #{error.message}"
+            if defined?(::Yard) && ::Yard.const_defined?(:Yaml)
+              ::Yard::Yaml.__send__(:__warn, message)
+            else
+              Kernel.warn("yard-yaml: #{message}")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/yaml/discovery.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Yard
+  module Yaml
+    # Discovery helpers to find YAML files and collect converted pages.
+    #
+    # Phase 3 scope:
+    # - Discover files via include/exclude globs from config.
+    # - Convert files via Converter and return normalized page hashes.
+    # - Errors are handled by Converter according to config.strict.
+    module Discovery
+      class << self
+        # Find YAML files using include and exclude patterns.
+        # Patterns are evaluated relative to the current working directory.
+        #
+        # @param include_globs [Array<String>]
+        # @param exclude_globs [Array<String>]
+        # @return [Array<String>] sorted list of file paths
+        def find_files(include_globs, exclude_globs)
+          incs = Array(include_globs).compact
+          excs = Array(exclude_globs).compact
+
+          files = []
+          incs.each do |glob|
+            next if glob.nil? || glob.to_s.strip.empty?
+            Dir.glob(glob.to_s, File::FNM_CASEFOLD | File::FNM_EXTGLOB | File::FNM_PATHNAME).each do |path|
+              next unless File.file?(path)
+              files << path
+            end
+          end
+
+          files.uniq!
+
+          unless excs.empty?
+            files.select! do |path|
+              excs.none? { |pat| File.fnmatch?(pat.to_s, path, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_CASEFOLD) }
+            end
+          end
+
+          files.sort.map { |p| File.expand_path(p) }
+        end
+
+        # Collect pages by converting discovered files.
+        #
+        # @param config [Yard::Yaml::Config]
+        # @return [Array<Hash>] Array of page hashes: { path:, html:, title:, description:, meta: }
+        def collect(config = Yard::Yaml.config)
+          files = find_files(config.include, config.exclude)
+          results = []
+
+          files.each do |path|
+            converted = Yard::Yaml::Converter.from_file(path, {}, config: config)
+            results << {
+              path: path,
+              html: converted[:html],
+              title: converted[:title],
+              description: converted[:description],
+              meta: converted[:meta] || {},
+            }
+          rescue Yard::Yaml::Error
+            # In strict mode Converter will raise; re-raise to fail the build
+            raise
+          rescue StandardError => e
+            # Non-strict converter errors are already warned; skip file
+            warn_fallback("skipping #{path}: #{e.class}: #{e.message}")
+          end
+
+          # Deterministic ordering by nav_order (if present) then title then path.
+          # nav_order values sort numerically; missing/non-numeric values are treated as Infinity (i.e., after any numeric ones).
+          results.sort_by { |h| [nav_order_value(h[:meta]), h[:title].to_s.downcase, h[:path]] }
+        end
+
+        private
+
+        # Extract a numeric nav_order from meta. Returns Infinity when absent or non-numeric
+        # so those entries sort after any numeric ones.
+        def nav_order_value(meta)
+          return Float::INFINITY unless meta.is_a?(Hash)
+          val = meta[:nav_order] || meta["nav_order"]
+          case val
+          when Integer, Float
+            val
+          when String
+            s = val.strip
+            if s.match?(/\A[+-]?\d+\z/)
+              begin
+                Integer(s)
+              rescue
+                Float::INFINITY
+              end
+            elsif s.match?(/\A[+-]?(?:\d+\.)?\d+\z/)
+              begin
+                Float(s)
+              rescue
+                Float::INFINITY
+              end
+            else
+              Float::INFINITY
+            end
+          else
+            Float::INFINITY
+          end
+        rescue StandardError
+          Float::INFINITY
+        end
+
+        def warn_fallback(message)
+          if defined?(::Yard) && ::Yard.const_defined?(:Yaml)
+            ::Yard::Yaml.warn(message)
+          else
+            Kernel.warn("yard-yaml: #{message}")
+          end
+        end
+      end
+    end
+  end
+end