mdtoc 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f092d7c28f783773c0c48be2f48ec708b986cb2bc059a5312420a15dd7e57878
-  data.tar.gz: c1af35b25f4c5c9596c232572b158074574ba16b154c72de1ad84c22d189ec40
+  metadata.gz: 2c01cef42824ceeae479dc235cbe2c7565c2d6ef045074c8d55b34a821ee719d
+  data.tar.gz: c25c67f2bf841dd9e1e3bb6a632035693299e7a53367b5dd255ecfbc125adab2
 SHA512:
-  metadata.gz: 0f20e8dbf0ce1d8ccc67ede27cdb15c8a6253d01e35c44780194b8322ccd3281e8f5c9fb8a3d311fcd4f91236988e1379cb639315711f87549f6dbd4fed44402
-  data.tar.gz: fa16fbf938973290b2724a8d1215aca328260813592083f2ea7adf9a6503c1d981702594260ab38969de05b13e78477e60ad56e201f1b7e754aa9759666899f8
+  metadata.gz: 603bec1ab105a7438bb2d0c2e4fb0c7eead9c63b57bfe33ca9354b05458d435805ce614cd11549527749092f2cffdc1289691a177b3c86161bac714f877c3eb7
+  data.tar.gz: 6bb0b63c4217f899d2277ba35baf7966cd97219e88f111c7a842b535108c698ac0260c0cc1f2c7e24858c9464a9cac333ea1fa4a7244104b051ba3184ed326bd

data/bin/mdtoc

@@ -2,5 +2,5 @@
 # typed: true
 # frozen_string_literal: true
 
-require 'mdtoc'
+require "mdtoc"
 Mdtoc.main(ARGV)

data/lib/mdtoc/cli.rb

@@ -19,7 +19,7 @@ module Mdtoc
             exit
           end
           parser_.on('-o', '--output PATH', 'Update a table of contents in the file at PATH')
-          parser_.on('-a', '--[no-]append', 'Append to the --output file if a <!-- mdtoc --> tag isn\'t found')
+          parser_.on('-a', '--[no-]append', "Append to the --output file if a <!-- mdtoc --> tag isn't found")
           parser_.on('-c', '--[no-]create', 'Create the --output file if it does not exist')
         end
 

data/lib/mdtoc/markdown/fragment_generator.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module Mdtoc
+  module Markdown
+    module FragmentGenerator
+      extend T::Sig
+      extend T::Helpers
+
+      interface!
+
+      sig { abstract.params(label: String).returns(String) }
+      def generate(label); end
+
+      class GitHub
+        extend T::Sig
+        include FragmentGenerator
+
+        sig { void }
+        def initialize
+          @counts = T.let(Hash.new(0), T::Hash[String, Integer])
+        end
+
+        sig { override.params(label: String).returns(String) }
+        def generate(label)
+          # GitHub's fragment generation:
+          # 1. Downcase
+          # 2. Replace spaces with dashes
+          # 3. Remove non-alphanumeric characters (keeping dashes, dots and underscores)
+          # 4. Collapse multiple dashes
+          # 5. Remove leading/trailing dashes and dots (common in many implementations)
+          fragment = label.downcase.tr(' ', '-').gsub(/[^\w.-]/, '')
+          fragment = fragment.gsub(/-+/, '-')
+          fragment = fragment.gsub(/^[.-]+|[.-]+$/, '')
+
+          count = @counts[fragment]
+          @counts[fragment] += 1
+
+          if count.positive?
+            "#{fragment}-#{count}"
+          else
+            fragment
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mdtoc/markdown/header.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
+require_relative 'fragment_generator'
 
 module Mdtoc
   module Markdown
@@ -10,9 +11,8 @@ module Mdtoc
 
       sig { params(depth: Integer, label: String, url: String).void }
       def initialize(depth, label, url)
-        if depth < 0
-          raise ArgumentError, "Header depth must be >= 0, but was #{depth}"
-        end
+        raise ArgumentError, "Header depth must be >= 0, but was #{depth}" if depth.negative?
+
         @depth = depth
         @label = normalize_label(label)
         @url = url
@@ -33,15 +33,22 @@ module Mdtoc
 
       def normalize_label(label)
         label = label.strip.tr("\t\n\r", '') # Remove whitespace characters other than spaces.
-        label.gsub(/\[(.*)\]\(.*\)/, '\1') # Remove links
+        label.gsub(/\[(.*?)\]\(.*?\)/, '\1') # Remove links
       end
     end
 
     class HeaderWithFragment < Header
-      sig { params(depth: Integer, label: String, url: String).void }
-      def initialize(depth, label, url)
-        super
-        @url += "##{@label.downcase.tr(' ', '-').gsub(/[^\w\-]/, '')}"
+      sig do
+        params(
+          depth: Integer,
+          label: String,
+          url: String,
+          generator: FragmentGenerator
+        ).void
+      end
+      def initialize(depth, label, url, generator:)
+        super(depth, label, url)
+        @url += "##{generator.generate(@label)}"
       end
     end
   end

data/lib/mdtoc/markdown/parser.rb

@@ -3,43 +3,102 @@
 
 require 'sorbet-runtime'
 require_relative 'header'
+require_relative 'fragment_generator'
 
 module Mdtoc
   module Markdown
     class Parser
       extend T::Sig
 
-      sig { params(depth: Integer, url: String).void }
-      def initialize(depth, url)
+      sig do
+        params(
+          depth: Integer,
+          url: String,
+          generator: FragmentGenerator
+        ).void
+      end
+      def initialize(depth, url, generator: FragmentGenerator::GitHub.new)
         @depth = depth
         @url = url
+        @generator = generator
+        @in_code_block = T.let(false, T::Boolean)
+        @in_html_comment = T.let(false, T::Boolean)
       end
 
       sig { params(lines: T::Enumerable[String]).returns(T::Array[Header]) }
       def headers(lines)
-        # TODO: Skip headers within multi-line comments.
-        # TODO: Handle --- and === style headers.
-        skip = T.let(false, T::Boolean)
-        lines.filter_map do |line|
-          # Skip code blocks.
-          if line.start_with?('```') && !T.must(line[3..]).strip.end_with?('```')
-            skip = !skip
+        @in_code_block = false
+        @in_html_comment = false
+
+        headers = T.let([], T::Array[Header])
+        prev_line = T.let(nil, T.nilable(String))
+
+        lines.each do |line|
+          stripped = line.strip
+
+          if skip_line?(line, stripped)
+            prev_line = line
+            next
+          end
+
+          if line.start_with?('#')
+            headers << header(line)
+          elsif (h = process_setext_header(stripped, prev_line))
+            headers << h
           end
-          next if skip || !line.start_with?('#')
 
-          header(line)
+          prev_line = line
         end
+
+        headers
       end
 
       private
 
+      sig { params(line: String, stripped: String).returns(T::Boolean) }
+      def skip_line?(line, stripped)
+        html_comment?(stripped) || code_block?(line)
+      end
+
+      sig { params(stripped: String).returns(T::Boolean) }
+      def html_comment?(stripped)
+        if stripped.start_with?('<!--')
+          @in_html_comment = true unless stripped.end_with?('-->')
+          return true
+        elsif @in_html_comment && stripped.end_with?('-->')
+          @in_html_comment = false
+          return true
+        end
+        @in_html_comment
+      end
+
+      sig { params(line: String).returns(T::Boolean) }
+      def code_block?(line)
+        if line.start_with?('```') && !T.must(line[3..]).strip.end_with?('```')
+          @in_code_block = !@in_code_block
+          return true
+        end
+        @in_code_block
+      end
+
+      sig { params(stripped: String, prev_line: T.nilable(String)).returns(T.nilable(Header)) }
+      def process_setext_header(stripped, prev_line)
+        return nil unless prev_line && !prev_line.strip.empty?
+
+        if stripped.match?(/^=+$/)
+          HeaderWithFragment.new(@depth, prev_line.strip, @url, generator: @generator)
+        elsif stripped.match?(/^-+$/)
+          HeaderWithFragment.new(@depth + 1, prev_line.strip, @url, generator: @generator)
+        end
+      end
+
       sig { params(line: String).returns(HeaderWithFragment) }
       def header(line)
         m = T.must(line.strip.match(/^(#+)\s*(.*)$/))
         num_hashes = m[1]&.count('#') || 1
         depth = @depth + num_hashes - 1
         label = m[2] || ''
-        HeaderWithFragment.new(depth, label, @url)
+        HeaderWithFragment.new(depth, label, @url, generator: @generator)
       end
     end
   end

data/lib/mdtoc/node.rb

@@ -10,6 +10,7 @@ module Mdtoc
   class Node
     extend T::Helpers
     extend T::Sig
+
     abstract!
 
     class << self
@@ -18,10 +19,9 @@ module Mdtoc
       sig { params(path: String, depth: Integer).returns(Node) }
       def for_path(path, depth = 0)
         # Ensure that `path` is a relative path, so that all links are relative and therefore portable.
-        path = Pathname.new(path)
-        path = path.relative_path_from(Dir.pwd) if path.absolute?
-        path = path.to_s
-        File.directory?(path) ? DirNode.new(path, depth) : FileNode.new(path, depth)
+        pathname = Pathname.new(path)
+        pathname = pathname.relative_path_from(Dir.pwd) if pathname.absolute?
+        pathname.directory? ? DirNode.new(pathname, depth) : FileNode.new(pathname, depth)
       end
 
       sig { params(paths: T::Array[String]).returns(String) }
@@ -32,7 +32,7 @@ module Mdtoc
       end
     end
 
-    sig { params(path: String, depth: Integer).void }
+    sig { params(path: Pathname, depth: Integer).void }
     def initialize(path, depth)
       @path = path
       @depth = depth
@@ -43,22 +43,30 @@ module Mdtoc
 
     sig { returns(String) }
     def label
-      File.basename(@path, File.extname(@path)).gsub(/_+/, ' ').gsub(/\s+/, ' ').capitalize
+      @path.basename(@path.extname).to_s.gsub(/_+/, ' ').gsub(/\s+/, ' ').capitalize
     end
 
     class DirNode < Node
       sig { override.returns(T::Array[Mdtoc::Markdown::Header]) }
       def headers
-        readme_path = T.let(nil, T.nilable(String))
-        child_headers = Dir
-          .each_child(@path)
-          .reject { |path| readme_path = File.join(@path, path) if path.casecmp?('readme.md') }
-          .sort!
-          .flat_map { |path| Node.for_path(File.join(@path, path), @depth + 1).headers }
+        readme_path = T.let(nil, T.nilable(Pathname))
+        children = @path.children.reject do |child|
+          if child.basename.to_s.casecmp?('readme.md')
+            readme_path = child
+            true
+          else
+            false
+          end
+        end
+
+        child_headers = children.sort.flat_map do |child|
+          Node.for_path(child.to_s, @depth + 1).headers
+        end
+
         return child_headers unless readme_path
 
         # Include the headers from the README at the beginning.
-        readme_headers = FileNode.new(readme_path, @depth).headers
+        readme_headers = FileNode.new(T.must(readme_path), @depth).headers
         readme_headers + child_headers
       end
     end
@@ -66,11 +74,12 @@ module Mdtoc
     class FileNode < Node
       sig { override.returns(T::Array[Mdtoc::Markdown::Header]) }
       def headers
-        parser = Markdown::Parser.new(@depth, @path)
-        headers = parser.headers(File.foreach(@path))
+        path_s = @path.to_s
+        parser = Markdown::Parser.new(@depth, path_s)
+        headers = parser.headers(@path.each_line)
         return headers if headers[0]&.top_level?(@depth)
 
-        headers.unshift(Mdtoc::Markdown::Header.new(@depth, label, @path))
+        headers.unshift(Mdtoc::Markdown::Header.new(@depth, label, path_s))
       end
     end
   end

data/lib/mdtoc/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mdtoc
-  VERSION = '0.1.5'
+  VERSION = '0.3.0'
 end

data/lib/mdtoc/writer.rb

@@ -1,6 +1,9 @@
-# typed: strict
+# typed: true
 # frozen_string_literal: true
 
+require 'fileutils'
+require 'tempfile'
+
 module Mdtoc
   module Writer
     COMMENT_BEGIN = '<!-- mdtoc -->'
@@ -13,8 +16,15 @@ module Mdtoc
       def write(toc, path, append, create)
         validate_path(path, create)
         new_content = content(toc, path, append)
-        File.open(path, 'w') do |f|
-          f.write(new_content)
+
+        # Write to a temporary file and rename it to the target path to ensure atomic writing.
+        temp = Tempfile.new(File.basename(path), File.dirname(path))
+        begin
+          temp.write(new_content)
+          temp.close
+          FileUtils.mv(temp.path, path)
+        ensure
+          temp.close!
         end
       end
 
@@ -25,17 +35,12 @@ module Mdtoc
         toc = "#{COMMENT_BEGIN}\n#{toc}\n#{COMMENT_END}"
 
         begin
-          f = File.open(path)
-        rescue
-          # If File.open failed because the file didn't exist, then we know that --create
+          old_content = File.read(path)
+        rescue StandardError
+          # If File.read failed because the file didn't exist, then we know that --create
           # was specified due to the validation in validate_path.
           return "#{toc}\n"
         end
-        begin
-          old_content = T.must(f.read)
-        ensure
-          f.close
-        end
 
         if Regexp.new(Regexp.escape(COMMENT_BEGIN), Regexp::IGNORECASE).match?(old_content)
           return old_content.gsub(

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mdtoc
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.3.0
 platform: ruby
 authors:
 - andornaut
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-06 00:00:00.000000000 Z
+date: 2026-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.25'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.25'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -58,56 +58,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.86'
+        version: '1.50'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.86'
-- !ruby/object:Gem::Dependency
-  name: rubocop-shopify
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.4
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.4
+        version: '1.50'
 - !ruby/object:Gem::Dependency
   name: rubocop-sorbet
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.10.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: unparser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.9
+        version: 0.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.9
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -133,13 +119,13 @@ description: |
 
   * [Ruby](https://www.ruby-lang.org/en/) (see [.ruby-version](./.ruby-version))
 
-  ```
-  $ gem install mdtoc
+  ```bash
+  gem install mdtoc
   ```
 
   ## Usage
 
-  ```
+  ```bash
   $ mdtoc --help
   Usage: mdtoc [options] files or directories...
       -h, --help                       Show this message
@@ -149,12 +135,15 @@ description: |
   ```
 
   1. Add a `<!-- mdtoc -->` tag to a Markdown file.
+
+    ```bash
+    echo '<!-- mdtoc -->' >> README.md
     ```
-    $ echo '<!-- mdtoc -->` >> README.md
-    ```
+
   2. Run `mdtoc` and specify input files or directories (eg. the "test/samples" directory) and an output file (eg. "README.md").
-    ```
-    $ mdtoc -aco README.md test/samples
+
+    ```bash
+    mdtoc -aco README.md test/samples
     ```
 
   ## Example Rakefile
@@ -162,29 +151,33 @@ description: |
   Create a `Rakefile` with the contents below, then run
   [`rake`](https://github.com/ruby/rake) to:
 
-  * `git pull`
+  * `git pullgem push pkg/mdtoc-0.2.0.gem`
   * `git add` any *.md files
   * Run `mdtoc` to update the generated table of contents in the ./README.md file
   * Git commit and push any changes
 
-  ```
+  ```ruby
   task default: %w[mdtoc]
 
   desc 'Update Markdown table of contents and push changes to the git repository'
-  task :mdtoc do |t|
-    command = <<~END
+  task :mdtoc do
+    command = <<~CMD
       set -e
-      git pull
       if [ -n "$(git diff --name-only --diff-filter=U)" ]; then
         echo 'Error: conflicts exist' >&2
         exit 1
       fi
       mdtoc --append --create --output README.md docs/
       git add *.md **/*.md
-      git commit -m 'Update TOC'
+      git commit -qm 'Update TOC' || true
+      git pull
       git push
-    END
-    %x|#{command}|
+    CMD
+    sh command, verbose: false do |ok, status|
+      unless ok
+        fail "Failed with status: #{status.exitstatus}"
+      end
+    end
   end
   ```
 
@@ -192,38 +185,42 @@ description: |
 
   ## Development
 
-  ### Installation
+  ### Setup
 
   Requirements:
 
   * [Bundler](https://bundler.io/)
+  * [chruby](https://github.com/postmodern/chruby) (recommended)
 
-  ```
-  # Install dependencies
-  $ bundle
+  ```bash
+  # Setup development environment
+  bin/setup
   ```
 
-  ### Usage
+  ### Tasks
 
-  ```
+  ```bash
   # List rake tasks
   $ rake -T
-  rake build                 # Build mdtoc-0.0.2.gem into the pkg directory
-  rake default               # Run the build, rubocop:auto_correct, sorbet and test tasks
-  rake install               # Build and install mdtoc-0.0.2.gem into system gems
-  rake install:local         # Build and install mdtoc-0.0.2.gem into system gems without...
-  rake release[remote]       # Create tag v0.0.2 and build and push mdtoc-0.0.2.gem to ru...
-  rake rubocop               # Run RuboCop
-  rake rubocop:auto_correct  # Auto-correct RuboCop offenses
-  rake sorbet                # Run the Sorbet type checker
-  rake test                  # Run tests
-
+  rake build                    # Build gem into the pkg directory
+  rake default                  # Run the build, rubocop, sorbet and test tasks
+  rake install                  # Build and install gem into system gems
+  rake rubocop                  # Run RuboCop
+  rake sorbet                   # Run the Sorbet type checker
+  rake test                     # Run tests
+  ```
   # Run mdtoc with test inputs
   $ ruby -Ilib bin/mdtoc test/samples
 
   # Run mdtoc with test inputs, and write to a newly created output file
   $ f=$(mktemp) && ruby -Ilib bin/mdtoc -aco ${f} test/samples ; cat ${f}
   ```
+
+  ### Publishing
+
+  ```bash
+  rake release
+  ```
 email:
 executables:
 - mdtoc
@@ -233,6 +230,7 @@ files:
 - bin/mdtoc
 - lib/mdtoc.rb
 - lib/mdtoc/cli.rb
+- lib/mdtoc/markdown/fragment_generator.rb
 - lib/mdtoc/markdown/header.rb
 - lib/mdtoc/markdown/parser.rb
 - lib/mdtoc/node.rb
@@ -241,7 +239,8 @@ files:
 homepage: https://github.com/andornaut/mdtoc
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -257,7 +256,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Read Markdown files and output a table of contents