mdlint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1f620c8c00a85c39a41cc1f81a4708ead9496071dd6cf984cd64eb7749bf646f
+  data.tar.gz: 76c8f42560a6b98b8007b05911825017d34cc09dad59ee0545f2a87b863bfd01
+SHA512:
+  metadata.gz: 202ea22fc2617cce04c03a0785ee64dfd64e62e306de58a6cf50257668b0992b2de1fa953cbe8d7374db4de0aeb99940c8dd98e936b34b47022316058a34f8cd
+  data.tar.gz: b987544c415e6bfa021d7472080284c07a9f179b1ad46dddcc53944faa4e14a3f3a27db7202f72d8208deac05a95234a8f9b1eab5b3d40907cbd98aa0210eee0

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 - 2025-01-23
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,181 @@
+<h1 align="center">mdlint</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg" alt="Ruby Version"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"><a href="https://github.com/ydah/mdlint/actions/workflows/main.yml"><img src="https://github.com/ydah/mdlint/actions/workflows/main.yml/badge.svg?branch=main" alt="CI"></a><a href="https://badge.fury.io/rb/mdlint"><img src="https://badge.fury.io/rb/mdlint.svg" alt="Gem Version"></a>
+</p>
+
+<p align="center">
+  A pure Ruby Markdown linter and formatter with zero external dependencies
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#lint-rules">Lint Rules</a> •
+  <a href="#formatting-style">Formatting</a>
+</p>
+
+## Features
+
+- Pure Ruby, no C/Rust extensions or external dependencies
+- Linting with configurable rules and clear violations
+- Auto-formatting that follows mdformat conventions
+- CLI for CI-friendly workflows and local formatting
+- Simple YAML configuration file
+
+## Quickstart
+
+```bash
+gem install mdlint
+
+# format in place
+mdlint README.md docs/
+
+# check-only (CI)
+mdlint --check README.md
+
+# show diffs
+mdlint --diff README.md
+```
+
+## Installation
+
+With Bundler:
+
+```bash
+bundle add mdlint
+```
+
+Without Bundler:
+
+```bash
+gem install mdlint
+```
+
+## Usage
+
+Command line:
+
+```bash
+mdlint README.md docs/
+mdlint --check README.md
+mdlint --diff README.md
+```
+
+Options:
+
+```
+Usage: mdlint [options] [paths...]
+
+Options:
+    -c, --check              Check if files are formatted, exit with error if not
+    -d, --diff               Show diff of changes
+    -q, --quiet              Suppress output
+    -e, --exclude PATTERN    Exclude files matching pattern
+    -w, --wrap MODE          Paragraph wrapping: keep (default), no, or INTEGER
+        --number             Use consecutive numbering for ordered lists
+        --end-of-line MODE   End of line: lf (default), crlf, keep
+    -v, --version            Show version
+    -h, --help               Show help
+```
+
+Ruby API:
+
+```ruby
+require "mdlint"
+
+formatted = Mdlint.format("# Hello World")
+Mdlint.format_file("README.md")
+
+tokens = Mdlint.parse("# Hello World")
+
+violations = Mdlint.lint("# Heading\n\n\n\nParagraph")
+violations.each { |v| puts v }
+
+violations = Mdlint.lint_file("README.md")
+```
+
+## Configuration
+
+Create a `.mdlint.yml` file in your project root:
+
+```yaml
+# Check mode (don't modify files)
+check: false
+
+# Quiet mode (suppress output)
+quiet: false
+
+# Exclude patterns
+exclude:
+  - "vendor/**/*.md"
+  - "node_modules/**/*.md"
+```
+
+## Lint Rules
+
+Key rules:
+
+- Heading levels should increment by one
+- Heading style should be consistent (ATX)
+- No trailing spaces
+- No multiple consecutive blank lines
+- First line should be a top-level heading
+
+## Formatting Style
+
+| Element | Style |
+|---------|-------|
+| Headings | ATX style only (`#`) |
+| Bullet lists | Hyphen (`-`), alternating for nested |
+| Ordered lists | All items use `1.` (minimizes diffs) |
+| Code blocks | Fenced style (`` ``` ``) |
+| Horizontal rules | 70 underscores |
+| Hard breaks | Backslash (`\`) |
+| Line endings | LF (configurable) |
+| Reference links | Converted to inline links |
+
+## Supported Markdown Elements
+
+Block elements:
+
+- ATX headings (`# Heading`)
+- Setext headings (converted to ATX)
+- Paragraphs
+- Bullet lists (`-`, `*`, `+`)
+- Ordered lists (`1.`, `2.`)
+- Blockquotes (`>`)
+- Fenced code blocks (`` ``` ``)
+- Indented code blocks (converted to fenced)
+- Horizontal rules (`---`, `***`, `___`)
+- HTML blocks
+- Reference definitions
+
+Inline elements:
+
+- Bold (`**text**`, `__text__`)
+- Italic (`*text*`, `_text_`)
+- Inline code (`` `code` ``)
+- Links (`[text](url)`)
+- Reference links (`[text][ref]`)
+- Images (`![alt](src)`)
+- Autolinks (`<https://example.com>`)
+- Hard breaks (backslash + newline)
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/mdlint.
+
+## License
+
+MIT License. See `LICENSE.txt` for details.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/mdlint

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mdlint"
+require "mdlint/cli"
+
+exit Mdlint::CLI.new(ARGV).run || 0

data/lib/mdlint/cli.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "pathname"
+require_relative "config"
+
+module Mdlint
+  class CLI
+    def initialize(argv)
+      @argv = argv.dup
+      @cli_options = { exclude: [] }
+    end
+
+    def run
+      parse_options
+      load_config
+      paths = @argv
+
+      if paths.empty?
+        process_stdin
+      else
+        process_paths(paths)
+      end
+    end
+
+    private
+
+    def load_config
+      config = Config.new
+      config.load
+      @options = config.merge(@cli_options)
+    end
+
+    def parse_options
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: mdlint [options] [paths...]"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("-c", "--check", "Check if files are formatted, exit with error if not") do
+          @cli_options[:check] = true
+        end
+
+        opts.on("-d", "--diff", "Show diff of changes") do
+          @cli_options[:diff] = true
+        end
+
+        opts.on("-q", "--quiet", "Suppress output") do
+          @cli_options[:quiet] = true
+        end
+
+        opts.on("-e", "--exclude PATTERN", "Exclude files matching pattern") do |pattern|
+          @cli_options[:exclude] << pattern
+        end
+
+        opts.on("-w", "--wrap MODE", "Paragraph wrapping mode: keep (default), no, or INTEGER") do |mode|
+          @cli_options[:wrap] = parse_wrap_mode(mode)
+        end
+
+        opts.on("--number", "Use consecutive numbering for ordered lists") do
+          @cli_options[:number] = true
+        end
+
+        opts.on("--end-of-line MODE", "End of line: lf (default), crlf, keep") do |mode|
+          @cli_options[:end_of_line] = mode.downcase.to_sym
+        end
+
+        opts.on("-v", "--version", "Show version") do
+          puts "mdlint #{Mdlint::VERSION}"
+          exit 0
+        end
+
+        opts.on("-h", "--help", "Show this help") do
+          puts opts
+          exit 0
+        end
+      end
+
+      parser.parse!(@argv)
+    end
+
+    def process_stdin
+      input = $stdin.read
+      output = Mdlint.format(input, format_options)
+
+      if @options[:check]
+        exit(input == output ? 0 : 1)
+      elsif @options[:diff]
+        show_diff("stdin", input, output)
+        exit(input == output ? 0 : 1)
+      else
+        print output
+        0
+      end
+    end
+
+    def process_paths(paths)
+      files = collect_files(paths)
+      changed_files = []
+
+      files.each do |file|
+        result = process_file(file)
+        changed_files << file if result
+      end
+
+      if @options[:check]
+        exit(changed_files.empty? ? 0 : 1)
+      end
+
+      unless @options[:quiet]
+        if changed_files.any?
+          puts "#{changed_files.length} file(s) reformatted" unless @options[:diff]
+        else
+          puts "All files are formatted correctly" unless @options[:diff]
+        end
+      end
+
+      changed_files.empty? ? 0 : 1
+    end
+
+    def collect_files(paths)
+      files = []
+
+      paths.each do |path|
+        if File.directory?(path)
+          Dir.glob(File.join(path, "**", "*.md")).each do |file|
+            files << file unless excluded?(file)
+          end
+        elsif File.file?(path)
+          files << path unless excluded?(path)
+        else
+          warn "Warning: #{path} does not exist"
+        end
+      end
+
+      files.sort
+    end
+
+    def excluded?(file)
+      @options[:exclude].any? do |pattern|
+        File.fnmatch?(pattern, file, File::FNM_PATHNAME)
+      end
+    end
+
+    def process_file(file)
+      original = File.read(file)
+      formatted = Mdlint.format(original, format_options)
+      changed = original != formatted
+
+      if changed
+        if @options[:diff]
+          show_diff(file, original, formatted)
+        elsif !@options[:check]
+          File.write(file, formatted)
+          puts "Reformatted: #{file}" unless @options[:quiet]
+        elsif !@options[:quiet]
+          puts "Would reformat: #{file}"
+        end
+      end
+
+      changed
+    end
+
+    def show_diff(filename, original, formatted)
+      require "tempfile"
+
+      Tempfile.create("mdlint-original") do |orig_file|
+        Tempfile.create("mdlint-formatted") do |fmt_file|
+          orig_file.write(original)
+          orig_file.flush
+          fmt_file.write(formatted)
+          fmt_file.flush
+
+          diff_output = `diff -u "#{orig_file.path}" "#{fmt_file.path}" 2>&1`
+          unless diff_output.empty?
+            diff_output = diff_output.gsub(orig_file.path, "#{filename} (original)")
+                                     .gsub(fmt_file.path, "#{filename} (formatted)")
+            puts diff_output
+          end
+        end
+      end
+    end
+
+    def parse_wrap_mode(mode)
+      case mode.downcase
+      when "keep"
+        :keep
+      when "no"
+        :no
+      else
+        Integer(mode)
+      end
+    rescue ArgumentError
+      warn "Invalid wrap mode: #{mode}. Using 'keep'."
+      :keep
+    end
+
+    def format_options
+      {
+        wrap: @options[:wrap] || :keep,
+        number: @options[:number] || false,
+        end_of_line: @options[:end_of_line] || :lf
+      }
+    end
+  end
+end

data/lib/mdlint/config.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Mdlint
+  class Config
+    CONFIG_FILES = %w[
+      .mdlint.yml
+      .mdlint.yaml
+      mdlint.yml
+      mdlint.yaml
+    ].freeze
+
+    DEFAULT_OPTIONS = {
+      check: false,
+      diff: false,
+      quiet: false,
+      exclude: []
+    }.freeze
+
+    attr_reader :options
+
+    def initialize(base_path = Dir.pwd)
+      @base_path = base_path
+      @options = DEFAULT_OPTIONS.dup
+    end
+
+    def load
+      config_file = find_config_file
+      return @options unless config_file
+
+      file_options = load_config_file(config_file)
+      merge_options(file_options)
+      @options
+    end
+
+    def merge(cli_options)
+      cli_options.each do |key, value|
+        case key
+        when :exclude
+          @options[:exclude] = (@options[:exclude] + value).uniq
+        else
+          @options[key] = value unless value.nil?
+        end
+      end
+      @options
+    end
+
+    private
+
+    def find_config_file
+      current = @base_path
+
+      loop do
+        CONFIG_FILES.each do |name|
+          path = File.join(current, name)
+          return path if File.exist?(path)
+        end
+
+        parent = File.dirname(current)
+        break if parent == current
+
+        current = parent
+      end
+
+      nil
+    end
+
+    def load_config_file(path)
+      content = File.read(path)
+      parsed = YAML.safe_load(content, symbolize_names: true) || {}
+      normalize_options(parsed)
+    rescue Psych::SyntaxError => e
+      warn "Warning: Invalid YAML in #{path}: #{e.message}"
+      {}
+    end
+
+    def normalize_options(parsed)
+      options = {}
+
+      options[:check] = parsed[:check] if parsed.key?(:check)
+      options[:diff] = parsed[:diff] if parsed.key?(:diff)
+      options[:quiet] = parsed[:quiet] if parsed.key?(:quiet)
+
+      if parsed[:exclude]
+        options[:exclude] = Array(parsed[:exclude])
+      end
+
+      options
+    end
+
+    def merge_options(file_options)
+      file_options.each do |key, value|
+        case key
+        when :exclude
+          @options[:exclude] = (@options[:exclude] + value).uniq
+        else
+          @options[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/mdlint/linter/rule.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Mdlint
+  module Linter
+    class Rule
+      class << self
+        attr_accessor :rule_id, :description
+
+        def inherited(subclass)
+          super
+          RuleRegistry.register(subclass)
+        end
+      end
+
+      attr_reader :violations
+
+      def initialize
+        @violations = []
+      end
+
+      def check(_tokens, _source)
+        raise NotImplementedError, "Subclasses must implement #check"
+      end
+
+      def fix(_tokens, _source)
+        raise NotImplementedError, "Subclasses must implement #fix"
+      end
+
+      protected
+
+      def add_violation(message:, line:, column: nil, fixable: false)
+        @violations << Violation.new(
+          rule_id: self.class.rule_id,
+          message: message,
+          line: line,
+          column: column,
+          fixable: fixable
+        )
+      end
+    end
+
+    class RuleRegistry
+      @rules = []
+
+      class << self
+        attr_reader :rules
+
+        def register(rule_class)
+          @rules << rule_class
+        end
+
+        def all
+          @rules
+        end
+
+        def find(rule_id)
+          @rules.find { |r| r.rule_id == rule_id }
+        end
+
+        def clear
+          @rules = []
+        end
+      end
+    end
+  end
+end

data/lib/mdlint/linter/rule_engine.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Mdlint
+  module Linter
+    class RuleEngine
+      attr_reader :violations
+
+      def initialize(options = {})
+        @options = options
+        @enabled_rules = options[:rules] || RuleRegistry.all.map(&:rule_id)
+        @disabled_rules = options[:disable] || []
+        @violations = []
+      end
+
+      def check(tokens, source)
+        @violations = []
+
+        active_rules.each do |rule_class|
+          rule = rule_class.new
+          rule.check(tokens, source)
+          @violations.concat(rule.violations)
+        end
+
+        @violations.sort_by(&:line)
+      end
+
+      def fix(tokens, source)
+        result = source
+
+        active_rules.each do |rule_class|
+          rule = rule_class.new
+          result = rule.fix(tokens, result)
+        end
+
+        result
+      end
+
+      private
+
+      def active_rules
+        RuleRegistry.all.select do |rule_class|
+          @enabled_rules.include?(rule_class.rule_id) &&
+            !@disabled_rules.include?(rule_class.rule_id)
+        end
+      end
+    end
+  end
+end

data/lib/mdlint/linter/rules/first_line_heading.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mdlint
+  module Linter
+    module Rules
+      class FirstLineHeading < Rule
+        self.rule_id = "MD041"
+        self.description = "First line in file should be a top-level heading"
+
+        def check(tokens, _source)
+          first_content_token = tokens.find do |t|
+            %i[heading_open paragraph_open bullet_list_open ordered_list_open
+               blockquote_open fence code_block hr html_block].include?(t.type)
+          end
+
+          return @violations unless first_content_token
+
+          if first_content_token.type != :heading_open
+            add_violation(
+              message: "First line should be a top-level heading",
+              line: (first_content_token.map&.first || 0) + 1,
+              fixable: false
+            )
+          elsif first_content_token.tag != "h1"
+            add_violation(
+              message: "First heading should be h1",
+              line: (first_content_token.map&.first || 0) + 1,
+              fixable: false
+            )
+          end
+
+          @violations
+        end
+
+        def fix(tokens, _source)
+          tokens
+        end
+      end
+    end
+  end
+end