mdtoc 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae0f7d7fa8f96a2d68073f0fbc5a0b92f8ac8182b82fbd2a7bcabb074449d525
+  data.tar.gz: a0af9901b92c93dc3eea21ddae16fa349f7be653945f51e9867d2f69efc1073a
+SHA512:
+  metadata.gz: 350566fff5655c9ab17502f02992c23d04e23d844cd94a6c25788d9c745142135f3cc2a1d41e7b7cc6a691caf209edfb9f689816d2b3a1379a75f061a756fddc
+  data.tar.gz: 33af4aeb021e9b61bb111ab2c20904f1af90afb4bf5c62361fea8e08d3bb21fcde68a9dc45b1863035f321db4a23a367898b9648f270931394c76e3437562140

data/bin/mdtoc

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# typed: true
+# frozen_string_literal: true
+
+require 'mdtoc'
+Mdtoc.main(ARGV)

data/lib/mdtoc/cli.rb

@@ -0,0 +1,48 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'optparse'
+require 'sorbet-runtime'
+require 'tempfile'
+require_relative 'markdown'
+require_relative 'node'
+require_relative 'writer'
+
+module Mdtoc
+  module CLI
+    class Options < T::Struct
+      extend T::Sig
+
+      prop :append, T::Boolean, default: false
+      prop :create, T::Boolean, default: false
+      prop :output, T.nilable(String)
+      prop :paths, T::Array[String], default: []
+
+      def []=(key, val)
+        send("#{key}=", val)
+      end
+
+      sig { params(args: T::Array[String]).returns(Options) }
+      def self.for_args(args)
+        parser = OptionParser.new do |parser_|
+          parser_.banner = "Usage: #{parser_.program_name} [options] files or directories..."
+          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')
+        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')
+          exit(1)
+        end
+        options
+      end
+    end
+  end
+end

data/lib/mdtoc/markdown.rb

@@ -0,0 +1,78 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module Mdtoc
+  module Markdown
+    class Header
+      extend T::Sig
+
+      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
+        @depth = depth
+        @label = label.strip.gsub(/\s+/, ' ')
+        @url = url
+      end
+
+      sig { params(relative_to_depth: Integer).returns(T::Boolean) }
+      def top_level?(relative_to_depth)
+        @depth == relative_to_depth
+      end
+
+      sig { returns(String) }
+      def to_s
+        prefix = ' ' * 2 * @depth
+        "#{prefix}* [#{@label}](#{@url})"
+      end
+    end
+
+    class HeaderWithFragment < Header
+      sig { params(depth: Integer, label: String, url: String).void }
+      def initialize(depth, label, url)
+        url = "#{url}##{label.downcase.strip.gsub(/ /, '-').gsub(/[^\w\-_ ]/, '')}"
+        super
+      end
+    end
+
+    class Parser
+      extend T::Sig
+
+      sig { params(depth: Integer, url: String).void }
+      def initialize(depth, url)
+        @depth = depth
+        @url = url
+      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
+          end
+          next if skip || !line.start_with?('#')
+
+          header(line)
+        end
+      end
+
+      private
+
+      sig { params(line: String).returns(Header) }
+      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)
+      end
+    end
+  end
+end

data/lib/mdtoc/node.rb

@@ -0,0 +1,67 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'pathname'
+require 'sorbet-runtime'
+require_relative 'markdown'
+
+module Mdtoc
+  class Node
+    extend T::Helpers
+    extend T::Sig
+    abstract!
+
+    sig { params(path: String, depth: Integer).returns(Node) }
+    def self.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)
+    end
+
+    sig { params(path: String, depth: Integer).void }
+    def initialize(path, depth)
+      @path = path
+      @depth = depth
+    end
+
+    sig { returns(String) }
+    def label
+      File.basename(@path, File.extname(@path)).gsub(/_+/, ' ').gsub(/\s+/, ' ').capitalize
+    end
+
+    sig { abstract.returns(T::Array[Mdtoc::Markdown::Header]) }
+    def headers; end
+  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)
+        .map { |path| File.join(@path, path) }
+        .reject { |path| readme_path = path if File.basename(path).downcase == 'readme.md' }
+        .sort!
+        .map { |path| Node.for_path(path, @depth + 1).headers }
+        .flatten(1)
+      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.push(*child_headers)
+    end
+  end
+
+  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))
+      return headers if headers[0]&.top_level?(@depth)
+
+      headers.unshift(Mdtoc::Markdown::Header.new(@depth, label, @path))
+    end
+  end
+end

data/lib/mdtoc/version.rb

@@ -0,0 +1,6 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mdtoc
+  VERSION = '0.1.3'
+end

data/lib/mdtoc/writer.rb

@@ -0,0 +1,68 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mdtoc
+  module Writer
+    COMMENT_BEGIN = '<!-- mdtoc -->'
+    COMMENT_END = '<!-- mdtoc-end -->'
+
+    class << self
+      extend T::Sig
+
+      sig { params(toc: String, path: String, append: T::Boolean, create: T::Boolean).void }
+      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)
+        end
+      end
+
+      private
+
+      sig { params(toc: String, path: String, append: T::Boolean).returns(String) }
+      def content(toc, path, append)
+        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
+          # was specified due to the validation in self.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(
+            /#{Regexp.escape(COMMENT_BEGIN)}(.*#{Regexp.escape(COMMENT_END)})?/im, toc
+          )
+        elsif append
+          return "#{old_content}\n#{toc}\n"
+        end
+
+        warn("Could not update #{path}, because the target HTML tag \"#{COMMENT_BEGIN}\" was not found")
+        exit(1)
+      end
+
+      sig { params(path: String, create: T::Boolean).void }
+      def validate_path(path, create)
+        if path
+          if File.exist?(path)
+            unless File.file?(path)
+              warn("--output PATH \"#{path}\" is not a regular file")
+              exit
+            end
+          elsif !create
+            warn("--output PATH \"#{path}\" does not exist. Specify --create to create it.")
+            exit
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mdtoc.rb

@@ -0,0 +1,40 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'optparse'
+require 'tempfile'
+require_relative 'mdtoc/cli'
+require_relative 'mdtoc/markdown'
+require_relative 'mdtoc/node'
+require_relative 'mdtoc/writer'
+
+module Mdtoc
+  class << self
+    extend T::Sig
+
+    sig { params(args: T::Array[String]).void }
+    def main(args)
+      options = Mdtoc::CLI::Options.for_args(args)
+      toc = render_toc(options.paths)
+      unless options.output
+        puts toc
+        return
+      end
+
+      Mdtoc::Writer.write(toc, T.must(options.output), options.append, options.create)
+    end
+
+    private
+
+    sig { params(paths: T::Array[String]).returns(String) }
+    def render_toc(paths)
+      paths
+        .map { |path| Mdtoc::Node.for_path(path).headers }
+        .flatten(1)
+        .map(&:to_s)
+        .join("\n")
+    end
+  end
+end
+
+Mdtoc.main(ARGV) if __FILE__ == $PROGRAM_NAME

data/test/samples/README.md

@@ -0,0 +1,18 @@
+# Title
+intro text
+ # Ignore this non-title
+    # ignore this non title
+```
+ignore this multi-line code block
+```
+```ignore this inline block```
+<!-- ignore this comment -->
+## 2
+### 3
+
+## 2
+text
+
+#### 4
+text
+## 2

data/test/samples/a/c.md

@@ -0,0 +1,2 @@
+# c 1
+## c 2

data/test/samples/a/d/f.md

@@ -0,0 +1 @@
+## f 2

data/test/samples/a/e.md

@@ -0,0 +1 @@
+# e 1

data/test/samples/a/g/README.md

@@ -0,0 +1 @@
+# README 1 for g

data/test/samples/a/g/h.md

@@ -0,0 +1 @@
+# h 1

data/test/samples/a/readme.md

@@ -0,0 +1,4 @@
+# readme 1
+## readme 2
+### readme 3
+#### readme 4

data/test/test_markdown.rb

@@ -0,0 +1,127 @@
+# typed: false
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "mdtoc/markdown"
+
+class TestHeader < Minitest::Test
+  def test_fragment_normalization
+    sample = [
+      'Spaces 1 space',
+      'Spaces  2 spaces',
+      "Spaces\t1 tab",
+      "Spaces\t\t2 tabs",
+      '    Spaces leading and trailing    ',
+      'Numbers 1234567890',
+      'Symbols -=~!@#$%^&',
+      'Symbols *()_+',
+      'Symbols <>?:"{}|[]\;\',./',
+    ]
+    expecteds = [
+      '/a#spaces-1-space',
+      '/a#spaces--2-spaces',
+      '/a#spaces1-tab',
+      '/a#spaces2-tabs',
+      '/a#spaces-leading-and-trailing',
+      '/a#numbers-1234567890',
+      '/a#symbols--',
+      '/a#symbols-_',
+      '/a#symbols-',
+    ]
+    actuals = sample.map do |label|
+      Mdtoc::Markdown::HeaderWithFragment.new(1, label, '/a').instance_variable_get(:@url)
+    end
+
+    expecteds.zip(actuals).each { |expected, actual| assert_equal(expected, actual) }
+  end
+
+  def test_invalid_depth
+    assert_raises(ArgumentError) do
+      Mdtoc::Markdown::Header.new(-1, 'a', '/a')
+    end
+  end
+
+  def test_label_normalization
+    sample = [
+      '  strip  ',
+      "squeeze    internal \t spaces",
+      'Don\'t change "#1?|!@#$%^&*()+ 2--',
+    ]
+    expecteds = [
+      'strip',
+      "squeeze internal spaces",
+      'Don\'t change "#1?|!@#$%^&*()+ 2--',
+    ]
+    actuals = sample.map { |label| Mdtoc::Markdown::Header.new(0, label, '/a').instance_variable_get(:@label) }
+
+    expecteds.zip(actuals).each { |expected, actual| assert_equal(expected, actual) }
+  end
+
+  def test_to_s_prefix
+    str = Mdtoc::Markdown::Header.new(3, 'a', '/a').to_s
+
+    assert_equal('      * [a](/a)', str)
+  end
+
+  def test_to_s_with_fragment
+    str = Mdtoc::Markdown::HeaderWithFragment.new(0, 'a', '/a').to_s
+
+    assert_equal('* [a](/a#a)', str)
+  end
+
+  def test_to_s_without_fragment
+    str = Mdtoc::Markdown::Header.new(0, 'a', '/a').to_s
+
+    assert_equal('* [a](/a)', str)
+  end
+end
+
+class TestParser < Minitest::Test
+  def test_skips_multiline_code_blocks
+    parser = Mdtoc::Markdown::Parser.new(0, '/')
+    sample = <<~END
+      # title
+      ```
+      code
+      # code
+      ```
+    END
+
+    headers = parser.headers(sample.each_line)
+
+    assert_equal(1, headers.size)
+    assert_equal('title', headers[0].instance_variable_get(:@label))
+  end
+
+  def test_skips_inline_code_blocks
+    parser = Mdtoc::Markdown::Parser.new(0, '/')
+    sample = <<~END
+      ```code #```
+      # Title
+      ```# code```
+      ```code```#
+    END
+
+    headers = parser.headers(sample.each_line)
+
+    assert_equal(1, headers.size)
+    assert_equal(headers[0].instance_variable_get(:@label), 'Title')
+  end
+
+  def test_depth
+    parser = Mdtoc::Markdown::Parser.new(10, '/')
+    sample = <<~END
+      # 1
+      ## 2
+      ### 3
+      #### 4
+    END
+
+    headers = parser.headers(sample.each_line)
+
+    assert_equal(4, headers.size)
+    (0..3).each do |i|
+      assert_equal(10 + i, headers[i].instance_variable_get(:@depth))
+    end
+  end
+end

data/test/test_node.rb

@@ -0,0 +1,50 @@
+# typed: false
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "mdtoc/node"
+
+class TestNode < Minitest::Test
+  SAMPLE_DIR = File.join(File.dirname(__FILE__), 'samples')
+
+  def test_dir
+    expected = <<~END
+      * [readme 1](test/samples/a/readme.md#readme-1)
+        * [readme 2](test/samples/a/readme.md#readme-2)
+          * [readme 3](test/samples/a/readme.md#readme-3)
+            * [readme 4](test/samples/a/readme.md#readme-4)
+        * [c 1](test/samples/a/c.md#c-1)
+          * [c 2](test/samples/a/c.md#c-2)
+          * [F](test/samples/a/d/f.md)
+            * [f 2](test/samples/a/d/f.md#f-2)
+        * [e 1](test/samples/a/e.md#e-1)
+        * [README 1 for g](test/samples/a/g/README.md#readme-1-for-g)
+          * [h 1](test/samples/a/g/h.md#h-1)
+    END
+    node = Mdtoc::Node.for_path(sample_path('a'))
+    actual = node.headers.join("\n") + "\n"
+
+    assert_equal(expected, actual)
+  end
+
+  def test_file
+    expected = <<~END
+      * [Title](test/samples/README.md#title)
+        * [2](test/samples/README.md#2)
+          * [3](test/samples/README.md#3)
+        * [2](test/samples/README.md#2)
+            * [4](test/samples/README.md#4)
+        * [2](test/samples/README.md#2)
+    END
+    node = Mdtoc::Node.for_path(sample_path('README.md'))
+    actual = node.headers.join("\n") + "\n"
+
+    assert_equal(expected, actual)
+  end
+
+  private
+
+  def sample_path(path)
+    File.join('test/samples', path)
+  end
+end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification
+name: mdtoc
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- andornaut
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.86'
+  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
+- !ruby/object:Gem::Dependency
+  name: rubocop-sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: unparser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.9
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+executables:
+- mdtoc
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/mdtoc
+- lib/mdtoc.rb
+- lib/mdtoc/cli.rb
+- lib/mdtoc/markdown.rb
+- lib/mdtoc/node.rb
+- lib/mdtoc/version.rb
+- lib/mdtoc/writer.rb
+- test/samples/README.md
+- test/samples/a/c.md
+- test/samples/a/d/f.md
+- test/samples/a/e.md
+- test/samples/a/g/README.md
+- test/samples/a/g/h.md
+- test/samples/a/readme.md
+- test/test_markdown.rb
+- test/test_node.rb
+homepage: https://github.com/andornaut/mdtoc
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Read Markdown files and output a table of contents
+test_files: []