danger-toc 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d27e70d24b49b9cb6028e5f55a4315740babe9e9f51a73fe95d7c502e2c18b2
-  data.tar.gz: f58a7d7c22ae8f8746f9aa9318dbf461511149d5f3881bc9e927020723a80359
+  metadata.gz: 873eadcebb5c7ad1e01a9789251aaaf974f3852e6259d85cb95c4799c6d151b5
+  data.tar.gz: 4a852a1f1e5b173d136c47e022bd8037d7bdb40f0d09158460f8c53a0b39c1f1
 SHA512:
-  metadata.gz: cb815bca9f3cf08a3f6b2a474cdd9c15d8eb3b92c7478e595c86c62a510b52e55e1ef542a6121ca06fa4210239d6dfa4dcb50c26366e3e2adaffc639e6ef66e5
-  data.tar.gz: 36cb65b82c3ba399ef44a45c2f461f7b7cad09d857eadcb86265f7758370314637550ec1777db7a2c8ea8fa0a44e43d5ede2f4169600cd0bb31efe2531f27c16
+  metadata.gz: 1f163608c603f0e539a9e26ed82580b0ecfd22b120fc055e9376811645527147d2d0f243535898d123737307b0cdc5e2423c09c9fc533cb07d392c1f7fb12595
+  data.tar.gz: 1b5b1e067a7491ba736f62b4cada1226cb814bcbbe14c43774f6733e2a3c8c4d199b88125fdbfda4de1ee07aa6e4460439677411b53e5ce7e159774681534d51

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## Changelog
 
+### 0.3.0 (2026-10-20)
+
+* [#21](https://github.com/dblock/danger-toc/pull/21): Support every global TOC setting as a per-check keyword override without changing defaults; snapshot configuration and report every failing file - [@dblock](https://github.com/dblock).
+* [#20](https://github.com/dblock/danger-toc/pull/20): Configure bullets, indentation, maximum heading depth, and input parsers; exclude document titles from missing TOCs and support opt-in diff reports - [@dblock](https://github.com/dblock).
+* [#19](https://github.com/dblock/danger-toc/pull/19): Require Ruby 3.1, test through Ruby 4.0, declare the GFM parser dependency, and update pinned Danger workflows and contributor and release instructions - [@dblock](https://github.com/dblock).
+* [#18](https://github.com/dblock/danger-toc/pull/18): Migrate to danger-pr-comment workflow - [@dblock](https://github.com/dblock).
+* [#18](https://github.com/dblock/danger-toc/pull/18): Migrate from Travis CI to GitHub Actions - [@dblock](https://github.com/dblock).
+* [#18](https://github.com/dblock/danger-toc/pull/18): Upgrade rubocop to 1.82.0 - [@dblock](https://github.com/dblock).
+
 ### 0.2.0 (2019/07/28)
 
 * [#16](https://github.com/dblock/danger-toc/pull/16): Deprecate `check` in favor of `check!` - [@dblock](https://github.com/dblock).

data/README.md

@@ -1,17 +1,25 @@
 # danger-toc
 
-A plugin for [danger.systems](http://danger.systems) that makes sure your project’s `README.md` has a TOC.
+A plugin for [danger.systems](https://danger.systems) that makes sure your project's `README.md` has a TOC. Requires Ruby 3.1 or newer.
 
 [![Gem Version](https://badge.fury.io/rb/danger-toc.svg)](https://badge.fury.io/rb/danger-toc)
-[![Build Status](https://travis-ci.org/dblock/danger-toc.svg?branch=master)](https://travis-ci.org/dblock/danger-toc)
+[![CI](https://github.com/dblock/danger-toc/actions/workflows/ci.yml/badge.svg)](https://github.com/dblock/danger-toc/actions/workflows/ci.yml)
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
-  - [toc.files](#tocfiles)
-  - [toc.header](#tocheader)
   - [toc.check!](#toccheck)
+  - [Options](#options)
+    - [files](#files)
+    - [header](#header)
+    - [parser](#parser)
+    - [format](#format)
+    - [bullet](#bullet)
+    - [indent](#indent)
+    - [max_depth](#max_depth)
+    - [report](#report)
+  - [Global Defaults](#global-defaults)
 - [Contributing](#contributing)
 - [Copyright](#copyright)
 
@@ -20,36 +28,114 @@ A plugin for [danger.systems](http://danger.systems) that makes sure your projec
 Add `danger-toc` to your Gemfile.
 
 ```
-gem 'danger-toc', '~> 0.1'
+gem 'danger-toc'
 ```
 
-Add `toc.check` to your Dangerfile. Make a pull request and see this plugin in action.
+Add `toc.check!` to your Dangerfile. Make a pull request and see this plugin in action.
 
 <img src='images/toc-missing.png'>
 
 ## Usage
 
-Methods and settings from this plugin are available in your `Dangerfile` under the `toc` namespace.
+Methods from this plugin are available in your `Dangerfile` under the `toc` namespace. Every option can be set globally or passed to a check. Per-check options override global defaults without changing them.
 
-### toc.files
+### toc.check!
 
-List of files to ensure TOC in, default is `README.md`.
+Check README.md with default options, or pass options for a particular set of files:
 
 ```ruby
-config.files = [ 'README.md', 'DEV.md' ]
+toc.check!
+toc.check!(files: ['README.md', 'DEV.md'], header: 'Contents')
 ```
 
-### toc.header
+The method returns whether all checked TOCs are correct and reports every failing file. Use `toc.toc_changes?(files: ['README.md'])` to detect modified or added files before running a check.
 
-The Table of Contents header, without `#`, default is `Table of Contents`.
+### Options
 
 ```ruby
-config.header = 'Custom Table of Contents'
+toc.check!(files: ['README.md'], max_depth: 3)
+toc.check!(files: ['docs/guide.md'], parser: 'Kramdown', format: :kramdown, bullet: '*', indent: 4)
 ```
 
-### toc.check!
+#### files
+
+File paths to check. Default: `['README.md']`.
+
+```ruby
+toc.check!(files: ['README.md', 'DEV.md'])
+```
+
+#### header
+
+TOC heading text, without `#`. Default: `'Table of Contents'`.
+
+```ruby
+toc.check!(header: 'Contents')
+```
+
+When a TOC is missing, a leading `# Title` is excluded if every subsequent heading is nested below it. A lone heading or multiple top-level sections are retained. When a TOC exists, headings before it are excluded.
+
+#### parser
+
+Kramdown input parser name. Default: `'GFM'`. GFM and Kramdown input are available out of the box; install and require additional Kramdown parsers before selecting them.
+
+```ruby
+toc.check!(parser: 'Kramdown')
+```
+
+#### format
+
+Anchor ID format: `:github` (default) or `:kramdown`. This is independent of the input parser.
+
+```ruby
+toc.check!(parser: 'Kramdown', format: :kramdown)
+```
+
+#### bullet
+
+List marker: `'-'` (default), `'*'`, or `'+'`.
+
+```ruby
+toc.check!(bullet: '*')
+```
+
+#### indent
+
+Non-negative number of spaces per nesting level. Default: `2`.
+
+```ruby
+toc.check!(indent: 4)
+```
+
+#### max_depth
+
+Maximum absolute Markdown heading level (1–6). Default: `nil`, including all levels. For example, `2` includes `#` and `##` headings but not `###`.
+
+```ruby
+toc.check!(max_depth: 2)
+```
+
+#### report
+
+Report style: `:full` (default) shows the complete expected TOC. Use `:diff` to show mismatched entries with two surrounding entries of context. Removed lines are prefixed with `-`, additions with `+`. Missing TOCs always show the full suggestion.
+
+```ruby
+toc.check!(report: :diff)
+```
+
+### Global Defaults
+
+Set shared defaults on `toc`, then override individual settings for a particular check:
+
+```ruby
+toc.files = ['README.md', 'DEV.md']
+toc.header = 'Contents'
+toc.check!
+toc.check!(files: ['docs/guide.md'], header: 'Guide Contents', parser: 'Kramdown')
+toc.check! # still checks README.md and DEV.md using the Contents header
+```
 
-Run all checks.
+The same global/per-check choice applies to every option in the table, including `report`, `format`, and `max_depth`. Global settings are shared across plugin instances; each check captures its own immutable configuration snapshot.
 
 ## Contributing
 

data/lib/toc/config.rb

@@ -1,56 +1,81 @@
 module Danger
   module Toc
-    module Config
-      extend self
+    class Config
+      DEFAULTS = {
+        files: ['README.md'].freeze,
+        header: 'Table of Contents',
+        format: :github,
+        parser: 'GFM',
+        bullet: '-',
+        indent: 2,
+        max_depth: nil,
+        report: :full
+      }.freeze
 
-      ATTRIBUTES = %i[
-        files
-        header
-      ].freeze
+      ATTRIBUTES = DEFAULTS.keys.freeze
+      DELEGATORS = (ATTRIBUTES + ATTRIBUTES.map { |name| :"#{name}=" }).freeze
 
-      ACCESSORS = ATTRIBUTES.map { |name| "#{name}=".to_sym }
+      VALIDATORS = {
+        files: ->(value) { value.is_a?(Array) && value.all? { |file| file.is_a?(String) && !file.strip.empty? } },
+        header: ->(value) { value.is_a?(String) && !value.strip.empty? },
+        parser: ->(value) { value.is_a?(String) && !value.strip.empty? },
+        format: ->(value) { %i[github kramdown].include?(value) },
+        bullet: ->(value) { %w[- * +].include?(value) },
+        indent: ->(value) { value.is_a?(Integer) && value >= 0 },
+        max_depth: ->(value) { value.nil? || (value.is_a?(Integer) && (1..6).cover?(value)) },
+        report: ->(value) { %i[full diff].include?(value) }
+      }.freeze
 
-      DELEGATORS = ATTRIBUTES + ACCESSORS
+      attr_reader(*ATTRIBUTES)
 
-      attr_accessor(*Config::ATTRIBUTES)
-      attr_writer :format
-
-      # Files to process
-      def files=(value)
-        @files = value
+      ATTRIBUTES.each do |name|
+        define_method("#{name}=") do |value|
+          validate_option!(name, value)
+          instance_variable_set("@#{name}", snapshot(value))
+        end
       end
 
-      # Table of Contents Header
-      def header=(value)
-        @header = value
+      def initialize(**options)
+        unknown = options.keys - ATTRIBUTES
+        raise ArgumentError, "Unknown TOC options: #{unknown.join(', ')}" unless unknown.empty?
+
+        DEFAULTS.merge(options).each { |name, value| public_send("#{name}=", value) }
       end
 
-      def format
-        @format ||= default_format
+      def with(**options)
+        self.class.new(**to_h, **options).freeze
       end
 
-      def default_format
-        :github
+      def to_h
+        ATTRIBUTES.to_h { |name| [name, public_send(name)] }
       end
 
       def reset
-        self.files = ['README.md']
-        self.header = 'Table of Contents'
-        self.format = default_format
+        DEFAULTS.each { |name, value| public_send("#{name}=", value) }
       end
 
-      reset
-    end
+      private
 
-    class << self
-      def configure
-        warn '[DEPRECATION] `configure` is deprecated. Please directly configure the Danger plugin via `toc.xyz=` instead.'
-        block_given? ? yield(Config) : Config
+      def validate_option!(name, value)
+        raise ArgumentError, "Invalid TOC #{name}: #{value.inspect}" unless VALIDATORS.fetch(name).call(value)
       end
 
-      def config
-        Config
+      def snapshot(value)
+        case value
+        when Array then value.map { |item| snapshot(item) }.freeze
+        when String then value.dup.freeze
+        else value
+        end
       end
     end
+
+    def self.config
+      @config ||= Config.new
+    end
+
+    def self.configure
+      warn '[DEPRECATION] `configure` is deprecated. Please directly configure the Danger plugin via `toc.xyz=` instead.'
+      block_given? ? yield(config) : config
+    end
   end
 end

data/lib/toc/constructors/kramdown_constructor.rb

@@ -6,6 +6,7 @@ module Danger
       class KramdownConstructor < Kramdown::Converter::Toc
         def flatten(el)
           return [] unless el.type == :toc
+
           result = []
           if el.value
             result << {
@@ -14,20 +15,18 @@ module Danger
               depth: el.value.options[:level]
             }
           end
-          if el.children
-            el.children.each do |child|
-              result.concat(flatten(child))
-            end
+          el.children&.each do |child|
+            result.concat(flatten(child))
           end
           result
         end
 
         def convert(el)
-          toc = flatten(super(el))
+          toc = flatten(super)
           has_toc = false
           headers = []
           toc.each do |line|
-            if !has_toc && line[:text] == Danger::Toc.config.header
+            if !has_toc && line[:text] == (@options[:toc_header] || 'Table of Contents')
               headers = [] # drop any headers prior to TOC
               has_toc = true
             else

data/lib/toc/constructors.rb

@@ -7,10 +7,6 @@ module Danger
       def self.get(name)
         const_get "#{name.to_s.camelize}Constructor"
       end
-
-      def self.current
-        get Danger::Toc.config.format
-      end
     end
   end
 end

data/lib/toc/extractor.rb

@@ -8,10 +8,11 @@ module Danger
         @toc_start = nil
         @toc_end = nil
         @in_toc = false
+        @toc_header = options.fetch(:toc_header, 'Table of Contents')
       end
 
       def convert(el)
-        if el.type == :header && el.options[:raw_text] == Danger::Toc.config.header
+        if el.type == :header && el.options[:raw_text] == @toc_header
           @in_toc = true
           @toc_start = el.options[:location]
         elsif el.type == :header

data/lib/toc/gem_version.rb

@@ -1,3 +1,3 @@
 module Toc
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/toc/markdown_file.rb

@@ -1,24 +1,25 @@
 require 'active_support/core_ext/string/inflections'
+require 'kramdown-parser-gfm'
+require 'diff/lcs'
 
 require_relative 'extractor'
 require_relative 'constructors'
+require_relative 'config'
 
 module Danger
   module Toc
     class MarkdownFile
-      attr_reader :filename
-      attr_reader :exists
-      attr_reader :toc
-      attr_reader :headers
+      attr_reader :filename, :exists, :toc, :headers, :config
 
-      def initialize(filename = 'README.md')
+      def initialize(filename = 'README.md', config: Danger::Toc.config.with)
+        @config = config
         @filename = filename
         @exists = File.exist?(filename)
-        if @exists
-          parse!
-          reduce!
-          validate!
-        end
+        return unless @exists
+
+        parse!
+        reduce!
+        validate!
       end
 
       def exists?
@@ -40,27 +41,66 @@ module Danger
       def toc_from_headers
         headers.map do |header|
           [
-            ' ' * header[:depth] * 2,
-            "- [#{header[:text]}]",
+            ' ' * header[:depth] * config.indent,
+            "#{config.bullet} [#{header[:text]}]",
             "(##{header[:id]})"
           ].compact.join
         end
       end
 
+      def toc_diff
+        changes = Diff::LCS.sdiff(toc || [], toc_from_headers)
+        lines = []
+        previous = nil
+        diff_context(changes).each do |index|
+          lines << '...' if previous && index > previous + 1
+          lines.concat(diff_lines(changes[index]))
+          previous = index
+        end
+        lines.join("\n")
+      end
+
       private
 
+      def diff_context(changes)
+        changes.each_index.reject { |index| changes[index].action == '=' }.flat_map do |index|
+          (([index - 2, 0].max)..([index + 2, changes.length - 1].min)).to_a
+        end.uniq.sort
+      end
+
+      def diff_lines(change)
+        case change.action
+        when '!' then ["-#{change.old_element}", "+#{change.new_element}"]
+        when '-' then ["-#{change.old_element}"]
+        when '+' then ["+#{change.new_element}"]
+        else [" #{change.old_element}"]
+        end
+      end
+
       # Parse markdown file for TOC.
       def parse!
         md = File.read(filename)
-        doc = Kramdown::Document.new(md, input: 'GFM')
+        doc = Kramdown::Document.new(md, input: config.parser)
+
+        extract_toc!(md, doc)
+        construct_headers!(doc)
+      end
 
-        # extract toc
-        toc_start, toc_end = Danger::Toc::Extractor.convert(doc.root).first
+      def extract_toc!(markdown, doc)
+        toc_start, toc_end = Danger::Toc::Extractor.convert(doc.root, toc_header: config.header).first
+        toc_end ||= markdown.lines.length + 1 if toc_start
         @has_toc = toc_start && toc_end
-        @toc = md.split("\n")[toc_start, toc_end - toc_start - 1].reject(&:empty?) if @has_toc
+        @toc = markdown.split("\n")[toc_start, toc_end - toc_start - 1].reject(&:empty?) if @has_toc
+      end
 
-        # construct toc
-        @headers = Danger::Toc::Constructors.current.convert(doc.root).first
+      def construct_headers!(doc)
+        @headers = Danger::Toc::Constructors.get(config.format).convert(doc.root, toc_header: config.header).first
+        headers.shift if !@has_toc && document_title?
+        headers.select! { |header| header[:depth] <= config.max_depth } if config.max_depth
+      end
+
+      def document_title?
+        headers.length > 1 && headers.first[:depth] == 1 && headers.drop(1).all? { |header| header[:depth] > 1 }
       end
 
       def reduce!
@@ -68,10 +108,10 @@ module Danger
         headers.each do |header|
           min_depth = header[:depth] unless min_depth && min_depth < header[:depth]
         end
-        if min_depth
-          headers.each do |header|
-            header[:depth] -= min_depth
-          end
+        return unless min_depth
+
+        headers.each do |header|
+          header[:depth] -= min_depth
         end
       end
 

data/lib/toc/plugin.rb

@@ -7,8 +7,7 @@ module Danger
   #
   # @example Customize files and remind the requester to update TOCs when necessary.
   #
-  #          toc.files = ['README.md']
-  #          toc.is_toc_correct?
+  #          toc.check!(files: ['README.md'], max_depth: 3)
   #
   # @see  dblock/danger-toc
   # @tags toc
@@ -16,54 +15,75 @@ module Danger
   class DangerToc < Plugin
     extend Forwardable
 
-    def_delegators Danger::Toc.config, *Danger::Toc::Config::DELEGATORS
+    def_delegators 'Danger::Toc.config', *Danger::Toc::Config::DELEGATORS
 
     # Run all checks.
-    # @return [void]
-    def check!
-      is_toc_correct?
+    # @param options [Hash] Per-check files, header, parser, format, bullet, indent, max_depth, and report settings.
+    # @return [boolean] Whether all files have correct TOCs.
+    def check!(**options)
+      config = Danger::Toc.config.with(**options)
+      config.files.map { |filename| check_file(filename, config) }.all?
     end
 
     # Run all checks.
-    # @return [void]
-    def check
+    # @return [boolean]
+    def check(**options)
       warn '[DEPRECATION] `check` is deprecated. Please use `check!` instead.'
-      check!
+      check!(**options)
     end
 
     # Has the README file been modified?
     # @return [boolean]
-    def toc_changes?
-      (git.modified_files & files).any? || (git.added_files & files).any?
+    def toc_changes?(**options)
+      files = Danger::Toc.config.with(**options).files
+      git.modified_files.intersect?(files) || git.added_files.intersect?(files)
     end
 
     # Is the TOC format correct?
     # @return [boolean]
-    def is_toc_correct?
-      files.all? do |filename|
-        toc_file = Danger::Toc::MarkdownFile.new(filename)
-        if !toc_file.exists?
-          messaging.fail("The #{filename} file does not exist.", sticky: false)
-          false
-        elsif toc_file.good?
-          true
-        else
-          markdown <<-MARKDOWN
-Here's the expected TOC for #{filename}:
+    def is_toc_correct?(**options)
+      check!(**options)
+    end
 
-```markdown
-# #{Danger::Toc.config.header}
+    private
 
-#{toc_file.toc_from_headers.join("\n")}
-```
-          MARKDOWN
-          if toc_file.has_toc?
-            messaging.fail("The TOC found in #{filename} doesn't match the sections of the file.", sticky: false)
-          else
-            messaging.fail("The #{filename} file is missing a TOC.", sticky: false)
-          end
-          false
+    def check_file(filename, config)
+      toc_file = Danger::Toc::MarkdownFile.new(filename, config: config)
+      if !toc_file.exists?
+        messaging.fail("The #{filename} file does not exist.", sticky: false)
+        false
+      elsif toc_file.good?
+        true
+      else
+        report_toc(toc_file)
+        if toc_file.has_toc?
+          messaging.fail("The TOC found in #{filename} doesn't match the sections of the file.", sticky: false)
+        else
+          messaging.fail("The #{filename} file is missing a TOC.", sticky: false)
         end
+        false
+      end
+    end
+
+    def report_toc(toc_file)
+      if toc_file.config.report == :diff && toc_file.has_toc?
+        markdown <<~MARKDOWN
+          Here's the TOC diff for #{toc_file.filename} (- current, + expected):
+
+          ```diff
+          #{toc_file.toc_diff}
+          ```
+        MARKDOWN
+      else
+        markdown <<~MARKDOWN
+          Here's the expected TOC for #{toc_file.filename}:
+
+          ```markdown
+          # #{toc_file.config.header}
+
+          #{toc_file.toc_from_headers.join("\n")}
+          ```
+        MARKDOWN
       end
     end
   end