mdtoc 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67fab334c40c8a785d1ac0bcca6234a1fc048ad479ed7fb4df093f0eb14c2116
-  data.tar.gz: c80647e458fd2ceaa60189688d0c7a831ad023a20cb471fcc37d512e382db627
+  metadata.gz: 2c01cef42824ceeae479dc235cbe2c7565c2d6ef045074c8d55b34a821ee719d
+  data.tar.gz: c25c67f2bf841dd9e1e3bb6a632035693299e7a53367b5dd255ecfbc125adab2
 SHA512:
-  metadata.gz: 2e6e9abb89b30d7abed179b42b00a8d871ab7b5ea6b96a4607ea5284bed3a1e1b2bb3355e0258d84498b78c8dba1463ab170f46e9c4c7963f4931b2efa910483
-  data.tar.gz: a3c414d2472f1f2ad976bc02eca284c9b4f522ee21624ad30534d33563242cb2ac04457cf33a4bc1998f2af232f4aa803c2051ee066f910444d6f881c7b69396
+  metadata.gz: 603bec1ab105a7438bb2d0c2e4fb0c7eead9c63b57bfe33ca9354b05458d435805ce614cd11549527749092f2cffdc1289691a177b3c86161bac714f877c3eb7
+  data.tar.gz: 6bb0b63c4217f899d2277ba35baf7966cd97219e88f111c7a842b535108c698ac0260c0cc1f2c7e24858c9464a9cac333ea1fa4a7244104b051ba3184ed326bd

data/lib/mdtoc/cli.rb

@@ -1,9 +1,9 @@
 # typed: strict
 # frozen_string_literal: true
 
-require "optparse"
-require "sorbet-runtime"
-require "tempfile"
+require 'optparse'
+require 'sorbet-runtime'
+require 'tempfile'
 
 module Mdtoc
   module CLI
@@ -14,19 +14,19 @@ module Mdtoc
       def parse(args)
         parser = OptionParser.new do |parser_|
           parser_.banner = "Usage: #{parser_.program_name} [options] files or directories..."
-          parser_.on("-h", "--help", "Show this message") do
+          parser_.on('-h', '--help', 'Show this message') do
             puts parser_
             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("-c", "--[no-]create", "Create the --output file if it does not exist")
+          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('-c', '--[no-]create', 'Create the --output file if it does not exist')
         end
 
         options = Options.new
         options.paths = parser.parse(args, into: options)
         if options.paths.empty?
-          warn("Specify at least one file or directory to read")
+          warn('Specify at least one file or directory to read')
           exit(1)
         end
         options

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

@@ -1,7 +1,8 @@
 # typed: true
 # frozen_string_literal: true
 
-require "sorbet-runtime"
+require 'sorbet-runtime'
+require_relative 'fragment_generator'
 
 module Mdtoc
   module Markdown
@@ -10,9 +11,7 @@ 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)
@@ -21,7 +20,7 @@ module Mdtoc
 
       sig { returns(String) }
       def to_s
-        prefix = " " * 2 * @depth
+        prefix = ' ' * 2 * @depth
         "#{prefix}* [#{@label}](#{@url})"
       end
 
@@ -33,16 +32,23 @@ module Mdtoc
       private
 
       def normalize_label(label)
-        label = label.strip.tr("\t\n\r", "") # Remove whitespace characters other than spaces.
-        label.gsub(/\[(.*)\]\(.*\)/, '\1') # Remove links
+        label = label.strip.tr("\t\n\r", '') # Remove whitespace characters other than spaces.
+        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

@@ -1,45 +1,104 @@
 # typed: strict
 # frozen_string_literal: true
 
-require "sorbet-runtime"
-require_relative "header"
+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
+        num_hashes = m[1]&.count('#') || 1
         depth = @depth + num_hashes - 1
-        label = m[2] || ""
-        HeaderWithFragment.new(depth, label, @url)
+        label = m[2] || ''
+        HeaderWithFragment.new(depth, label, @url, generator: @generator)
       end
     end
   end

data/lib/mdtoc/node.rb

@@ -1,15 +1,16 @@
 # typed: strict
 # frozen_string_literal: true
 
-require "pathname"
-require "sorbet-runtime"
-require_relative "markdown/header"
-require_relative "markdown/parser"
+require 'pathname'
+require 'sorbet-runtime'
+require_relative 'markdown/header'
+require_relative 'markdown/parser'
 
 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.2.0"
+  VERSION = '0.3.0'
 end

data/lib/mdtoc/writer.rb

@@ -1,10 +1,13 @@
-# typed: strict
+# typed: true
 # frozen_string_literal: true
 
+require 'fileutils'
+require 'tempfile'
+
 module Mdtoc
   module Writer
-    COMMENT_BEGIN = "<!-- mdtoc -->"
-    COMMENT_END = "<!-- mdtoc-end -->"
+    COMMENT_BEGIN = '<!-- mdtoc -->'
+    COMMENT_END = '<!-- mdtoc-end -->'
 
     class << self
       extend T::Sig
@@ -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(

data/lib/mdtoc.rb

@@ -1,11 +1,11 @@
 # typed: strict
 # frozen_string_literal: true
 
-require "optparse"
-require "tempfile"
-require_relative "mdtoc/cli"
-require_relative "mdtoc/node"
-require_relative "mdtoc/writer"
+require 'optparse'
+require 'tempfile'
+require_relative 'mdtoc/cli'
+require_relative 'mdtoc/node'
+require_relative 'mdtoc/writer'
 
 module Mdtoc
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mdtoc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - andornaut
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-29 00:00:00.000000000 Z
+date: 2026-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -66,20 +66,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.50'
-- !ruby/object:Gem::Dependency
-  name: rubocop-shopify
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.0.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.0.0
 - !ruby/object:Gem::Dependency
   name: rubocop-sorbet
   requirement: !ruby/object:Gem::Requirement
@@ -165,7 +151,7 @@ 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
@@ -204,10 +190,11 @@ description: |
   Requirements:
 
   * [Bundler](https://bundler.io/)
+  * [chruby](https://github.com/postmodern/chruby) (recommended)
 
   ```bash
-  # Install dependencies
-  bundle
+  # Setup development environment
+  bin/setup
   ```
 
   ### Tasks
@@ -215,23 +202,25 @@ description: |
   ```bash
   # List rake tasks
   $ rake -T
-  rake build                    # Build mdtoc-0.1.5.gem into the pkg directory
-  rake default                  # Run the build, rubocop:autocorrect_all, sorbet and test tasks
-  rake install                  # Build and install mdtoc-0.1.5.gem into system gems
-  rake install:local            # Build and install mdtoc-0.1.5.gem into system gems without network access
-  rake release[remote]          # Create tag v0.1.5 and build and push mdtoc-0.1.5.gem to rubygems.org
+  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 rubocop:autocorrect      # Autocorrect RuboCop offenses (only when it's safe)
-  rake rubocop:autocorrect_all  # Autocorrect RuboCop offenses (safe and unsafe)
   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
@@ -241,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
@@ -249,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:
@@ -265,7 +256,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Read Markdown files and output a table of contents