mdl 0.0.1

data/lib/mdl.rb

@@ -0,0 +1,72 @@
+require 'mdl/cli'
+require 'mdl/config'
+require 'mdl/doc'
+require 'mdl/kramdown_parser'
+require 'mdl/ruleset'
+require 'mdl/style'
+require 'mdl/version'
+
+require 'kramdown'
+
+module MarkdownLint
+  def self.run
+    cli = MarkdownLint::CLI.new
+    cli.run
+    rules = RuleSet.load_default
+    style = Style.load(Config[:style], rules)
+    # Rule option filter
+    rules.select! {|r| Config[:rules].include?(r) } if Config[:rules]
+    # Tag option filter
+    rules.select! {|r, v| not (v.tags & Config[:tags]).empty? } if Config[:tags]
+
+    if Config[:list_rules]
+      puts "Enabled rules:"
+        rules.each do |id, rule|
+          if Config[:verbose]
+            puts "#{id} (#{rule.tags.join(', ')}) - #{rule.description}"
+          else
+            puts "#{id} - #{rule.description}"
+          end
+        end
+      exit 0
+    end
+
+    # Recurse into directories
+    cli.cli_arguments.each_with_index do |filename, i|
+      if Dir.exist?(filename)
+        pattern = "#{filename}/**/*.md" # This works for both Dir and ls-files
+        if Config[:git_recurse]
+          Dir.chdir(filename) do
+            cli.cli_arguments[i] = %x(git ls-files '*.md').split("\n")
+          end
+        else
+          cli.cli_arguments[i] = Dir["#{filename}/**/*.md"]
+        end
+      end
+    end
+    cli.cli_arguments.flatten!
+
+    status = 0
+    cli.cli_arguments.each do |filename|
+      puts "Checking #{filename}..." if Config[:verbose]
+      doc = Doc.new_from_file(filename)
+      filename = '(stdin)' if filename == "-"
+      if Config[:show_kramdown_warnings]
+        status = 2 if not doc.parsed.warnings.empty?
+        doc.parsed.warnings.each do |w|
+          puts "#{filename}: Kramdown Warning: #{w}"
+        end
+      end
+      rules.sort.each do |id, rule|
+        puts "Processing rule #{id}" if Config[:verbose]
+        error_lines = rule.check.call(doc)
+        next if error_lines.nil? or error_lines.empty?
+        status = 1
+        error_lines.each do |line|
+          puts "#{filename}:#{line}: #{id} #{rule.description}"
+        end
+      end
+    end
+    exit status
+  end
+end

data/lib/mdl/cli.rb

@@ -0,0 +1,89 @@
+require 'mixlib/cli'
+
+module MarkdownLint
+  class CLI
+    include Mixlib::CLI
+
+    banner "Usage: #{File.basename($0)} [options] [FILE.md|DIR ...]"
+
+    option :config_file,
+      :short => '-c',
+      :long => '--config FILE',
+      :description => 'The configuration file to use',
+      :default => '~/.mdlrc'
+
+    option :verbose,
+      :short => '-v',
+      :long => '--[no-]verbose',
+      :description => 'Increase verbosity',
+      :boolean => true
+
+    option :show_kramdown_warnings,
+      :short => '-w',
+      :long => '--[no-]warnings',
+      :description => 'Show kramdown warnings',
+      :boolean => true
+
+    option :tags,
+      :short => '-t',
+      :long => '--tags TAG1,TAG2',
+      :description => 'Only process rules with these tags',
+      :proc => Proc.new { |v| v.split(',').map { |t| t.to_sym } }
+
+    option :rules,
+      :short => '-r',
+      :long => '--rules RULE1,RULE2',
+      :description => 'Only process these rules',
+      :proc => Proc.new { |v| v.split(',') }
+
+    option :style,
+      :short => '-s',
+      :long => '--style STYLE',
+      :description => "Load the given style"
+
+    option :list_rules,
+      :short => '-l',
+      :long => '--list-rules',
+      :boolean => true,
+      :description => "Don't process any files, just list enabled rules"
+
+    option :git_recurse,
+      :short => '-g',
+      :long => '--git-recurse',
+      :boolean => true,
+      :description => "Only process files known to git when given a directory"
+
+    option :help,
+      :on => :tail,
+      :short => '-h',
+      :long => '--help',
+      :description => 'Show this message',
+      :boolean => true,
+      :show_options => true,
+      :exit => 0
+
+    option :version,
+      :on => :tail,
+      :short => "-V",
+      :long => "--version",
+      :description => "Show version",
+      :boolean => true,
+      :proc => Proc.new { puts MarkdownLint::VERSION },
+      :exit => 0
+
+    def run(argv=ARGV)
+      parse_options(argv)
+      # Load the config file if it's present
+      filename = File.expand_path(config[:config_file])
+      MarkdownLint::Config.from_file(filename) if File.exists?(filename)
+
+      # Put values in the config file
+      MarkdownLint::Config.merge!(config)
+
+      # Read from stdin if we didn't provide a filename
+      if cli_arguments.empty? and not config[:list_rules]
+        cli_arguments << "-"
+      end
+    end
+  end
+end

data/lib/mdl/config.rb

@@ -0,0 +1,9 @@
+require 'mixlib/config'
+
+module MarkdownLint
+  module Config
+    extend Mixlib::Config
+
+    default :style, "default"
+  end
+end

data/lib/mdl/doc.rb

@@ -0,0 +1,252 @@
+require 'kramdown'
+require 'mdl/kramdown_parser'
+
+module MarkdownLint
+  ##
+  # Representation of the markdown document passed to rule checks
+
+  class Doc
+    ##
+    # A list of raw markdown source lines. Note that the list is 0-indexed,
+    # while line numbers in the parsed source are 1-indexed, so you need to
+    # subtract 1 from a line number to get the correct line. The element_line*
+    # methods take care of this for you.
+
+    attr_reader :lines
+
+    ##
+    # A Kramdown::Document object containing the parsed markdown document.
+
+    attr_reader :parsed
+
+    ##
+    # A list of top level Kramdown::Element objects from the parsed document.
+
+    attr_reader :elements
+
+    ##
+    # Create a new document given a string containing the markdown source
+
+    def initialize(text)
+      # Workaround for the following two issues:
+      #   https://github.com/mivok/markdownlint/issues/52
+      #   https://github.com/gettalong/kramdown/issues/158
+      # Unfortunately this forces all input text back into ascii, which may
+      # be problematic for any rules that make use of non-ascii characters, so
+      # we should remove this if it no longer becomes necessary to do so.
+      text.encode!("ASCII", invalid: :replace, undef: :replace, replace: '')
+
+      @lines = text.split("\n")
+      @parsed = Kramdown::Document.new(text, :input => 'MarkdownLint')
+      @elements = @parsed.root.children
+      add_levels(@elements)
+    end
+
+    ##
+    # Alternate 'constructor' passing in a filename
+
+    def self.new_from_file(filename)
+      if filename == "-"
+        self.new(STDIN.read)
+      else
+        self.new(File.read(filename))
+      end
+    end
+
+    ##
+    # Find all elements of a given type, returning their options hash. The
+    # options hash has most of the useful data about an element and often you
+    # can just use this in your rules.
+    #
+    #   # Returns [ { :location => 1, :element_level => 2 }, ... ]
+    #   elements = find_type(:li)
+    #
+    # If +nested+ is set to false, this returns only top level elements of a
+    # given type.
+
+    def find_type(type, nested=true)
+      find_type_elements(type, nested).map { |e| e.options }
+    end
+
+    ##
+    # Find all elements of a given type, returning a list of the element
+    # objects themselves.
+    #
+    # Instead of a single type, a list of types can be provided instead to
+    # find all types.
+    #
+    # If +nested+ is set to false, this returns only top level elements of a
+    # given type.
+
+    def find_type_elements(type, nested=true, elements=@elements)
+      results = []
+      if type.class == Symbol
+        type = [type]
+      end
+      elements.each do |e|
+        results.push(e) if type.include?(e.type)
+        if nested and not e.children.empty?
+          results.concat(find_type_elements(type, nested, e.children))
+        end
+      end
+      results
+    end
+
+    ##
+    # Returns the line number a given element is located on in the source
+    # file. You can pass in either an element object or an options hash here.
+
+    def element_linenumber(element)
+      element = element.options if element.is_a?(Kramdown::Element)
+      element[:location]
+    end
+
+    ##
+    # Returns the actual source line for a given element. You can pass in an
+    # element object or an options hash here. This is useful if you need to
+    # examine the source line directly for your rule to make use of
+    # information that isn't present in the parsed document.
+
+    def element_line(element)
+      @lines[element_linenumber(element) - 1]
+    end
+
+    ##
+    # Returns a list of line numbers for all elements passed in. You can pass
+    # in a list of element objects or a list of options hashes here.
+
+    def element_linenumbers(elements)
+      elements.map { |e| element_linenumber(e) }
+    end
+
+    ##
+    # Returns the actual source lines for a list of elements. You can pass in
+    # a list of elements objects or a list of options hashes here.
+
+    def element_lines(elements)
+      elements.map { |e| element_line(e) }
+    end
+
+    ##
+    # Returns the header 'style' - :atx (hashes at the beginning), :atx_closed
+    # (atx header style, but with hashes at the end of the line also), :setext
+    # (underlined). You can pass in the element object or an options hash
+    # here.
+
+    def header_style(header)
+      if header.type != :header
+        raise "header_style called with non-header element"
+      end
+      line = element_line(header)
+      if line.start_with?("#")
+        if line.strip.end_with?("#")
+          :atx_closed
+        else
+          :atx
+        end
+      else
+        :setext
+      end
+    end
+
+    ##
+    # Returns the list style for a list: :asterisk, :plus, :dash, :ordered or
+    # :ordered_paren depending on which symbol is used to denote the list
+    # item. You can pass in either the element itself or an options hash here.
+
+    def list_style(item)
+      if item.type != :li
+        raise "list_style called with non-list element"
+      end
+      line = element_line(item).strip
+      if line.start_with?("*")
+        :asterisk
+      elsif line.start_with?("+")
+        :plus
+      elsif line.start_with?("-")
+        :dash
+      elsif line.match("[0-9]+\.")
+        :ordered
+      elsif line.match("[0-9]+\)")
+        :ordered_paren
+      else
+        :unknown
+      end
+    end
+
+    ##
+    # Returns how much a given line is indented. Hard tabs are treated as an
+    # indent of 8 spaces. You need to pass in the raw string here.
+
+    def indent_for(line)
+      return line.match(/^\s*/)[0].gsub("\t", " " * 8).length
+    end
+
+    ##
+    # Returns line numbers for lines that match the given regular expression
+
+    def matching_lines(re)
+      @lines.each_with_index.select{|text, linenum| re.match(text)}.map{
+        |i| i[1]+1}
+    end
+
+    ##
+    # Returns line numbers for lines that match the given regular expression.
+    # Only considers text inside of 'text' elements (i.e. regular markdown
+    # text and not code/links or other elements).
+    def matching_text_element_lines(re)
+      matches = []
+      find_type_elements(:text).each do |e|
+        first_line = e.options[:location]
+        lines = e.value.split("\n")
+        lines.each_with_index do |l, i|
+          matches << first_line + i if re.match(l)
+        end
+      end
+      matches
+    end
+
+    ##
+    # Extracts the text from an element whose children consist of text
+    # elements and other things
+
+    def extract_text(element, prefix="")
+      quotes = {
+        :rdquo => '"',
+        :ldquo => '"',
+        :lsquo => "'",
+        :rsquo => "'"
+      }
+      # If anything goes amiss here, e.g. unknown type, then nil will be
+      # returned and we'll just not catch that part of the text, which seems
+      # like a sensible failure mode.
+      lines = element.children.map { |e|
+        if e.type == :text
+          e.value
+        elsif [:strong, :em, :p].include?(e.type)
+          extract_text(e, prefix).join("\n")
+        elsif e.type == :smart_quote
+          quotes[e.value]
+        end
+      }.join.split("\n")
+      # Text blocks have whitespace stripped, so we need to add it back in at
+      # the beginning. Because this might be in something like a blockquote,
+      # we optionally strip off a prefix given to the function.
+      lines[0] = element_line(element).sub(prefix, "")
+      lines
+    end
+
+    private
+
+    ##
+    # Adds a 'level' option to all elements to show how nested they are
+
+    def add_levels(elements, level=1)
+      elements.each do |e|
+        e.options[:element_level] = level
+        add_levels(e.children, level+1)
+      end
+    end
+
+  end
+end

data/lib/mdl/kramdown_parser.rb

@@ -0,0 +1,29 @@
+# Modified version of the kramdown parser to add in features/changes
+# appropriate for markdownlint, but which don't make sense to try to put
+# upstream.
+require 'kramdown/parser/gfm'
+
+module Kramdown
+  module Parser
+    class MarkdownLint < Kramdown::Parser::Kramdown
+
+      def initialize(source, options)
+        super
+        i = @block_parsers.index(:codeblock_fenced)
+        @block_parsers.delete(:codeblock_fenced)
+        @block_parsers.insert(i, :codeblock_fenced_gfm)
+      end
+
+      # Add location information to text elements
+      def add_text(text, tree = @tree, type = @text_type)
+        super
+        if tree.children.last
+          tree.children.last.options[:location] = @src.current_line_number
+        end
+      end
+
+      # Regular kramdown parser, but with GFM style fenced code blocks
+      FENCED_CODEBLOCK_MATCH = Kramdown::Parser::GFM::FENCED_CODEBLOCK_MATCH
+    end
+  end
+end