marcdouane 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ac5051e1dda30d1dd98035ba682431ac8e32788b4187772eea00e1306f5ca1d
+  data.tar.gz: 2b60396b0e783bf920602fd49c2d04e4288e2c9b35e1485f85e7a94a5653d046
+SHA512:
+  metadata.gz: e054ef7079b1bf87c8203d3db165a43c3b26ffa7fc7fd1301a346060b0b25e60b7868f82550972992291b16875a5ce22512784417f489f990a673aa49fb1f501
+  data.tar.gz: 3982749d76b7e586a67b6ed6a5b8ef13bcc3ecea6c0877166ac6fe00605979fd2904c5c069d9b1a0d16da9bbac9e98f186c2a21264038f7849648d78166d426e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Stéphane Maniaci
+
+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,109 @@
+# Marc d'Ouane
+
+a beautiful, epic Markdown linter
+
+![Logo](logo.jpeg)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add marcdouane
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install marcdouane
+```
+
+## Usage
+
+Checking a file with default rules:
+
+```sh
+marcdouane check some-file.md
+```
+
+For the complete tour just use
+
+```sh
+marcdouane
+marcdouane check --help
+```
+
+## Configuration
+
+Some rules have settings (see `lib/marcdouane/rules.rb` for
+now). These settings can be overriden with a YAML config file that
+resembles the Rubocop config:
+
+```yaml
+LineLength:
+  maximum_line_length: 90 # which is utter madness
+```
+
+## Development
+
+I'm doing it
+
+## Contributing
+
+A rule must inherit `Marcdouane::Rule`. It must answer to `check!` and
+raise a `Marcdouane::Error` with an `ERROR_MESSAGE` and a line
+number. Example:
+
+```ruby
+class CheckAnglois < Marcdouane::Rule
+  ERROR_MESSAGE = "Do not mention the English"
+
+  def check!
+    File
+      .read(file)
+      .lines
+      .each_with_index(line, index) do
+      raise Marcdouane:Error.new(ERROR_MESSAGE, index + 1) if line =~ /anglois/
+    end
+  end
+end
+```
+
+It is then expected to be tested throughout the Cucumber feature tests
+like such:
+
+```feature
+Feature: Built-in Markdown Rules
+  # [...]
+
+  Rule: Don't mention the English
+    Example: It fails when the English are mentioned
+      Given a file named "foo.md" with:
+        """
+        # Tout va bien
+        Pas d'anglois à l'horizon
+        """
+      When I run `marcdouane check "foo.md"`
+      Then it should fail with:
+        """
+        foo.md:2: Don't mention the English
+        """
+
+    Example: It passes when the English are not mentioned
+      Given a file named "foo.md" with:
+        """
+        # Tout va bien
+        Quelques voix dans la tête mais tranquille
+        """
+      When I run `marcdouane check "foo.md"`
+      Then it should pass
+
+```
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/freesteph/marcdouane.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/marcdouane

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "dry/cli"
+require "marcdouane"
+
+module Marcdouane
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      class Version < Dry::CLI::Command
+        desc "Print version"
+
+        def call(*)
+          puts Marcdouane::VERSION
+        end
+      end
+
+      class Check < Dry::CLI::Command
+        desc "Check the Markdown of one or more file"
+
+        option :verbose,
+               type: :boolean,
+               default: false,
+               desc: "Verbose output"
+
+        option :config,
+               type: :string,
+               required: false,
+               desc: "Configuration file"
+
+        argument :files,
+                 type: :array,
+                 required: true,
+                 desc: "Files to check against"
+
+        def call(files: [], **options)
+          if files.empty?
+            puts "No files provided."
+            return
+          end
+
+          exit_code = 0
+
+          files.each do |file|
+            if !File.exist?(file)
+              $stderr.puts "`#{file}' is missing, or not a valid file."
+              exit_code = 1
+            else
+              exit_code = Marcdouane::FileChecker.call(file, options)
+            end
+          end
+
+          exit(exit_code)
+        end
+      end
+
+
+      register "version", Version, aliases: ["v", "-v", "--version"]
+      register "check", Check
+    end
+  end
+end
+
+Dry::CLI.new(Marcdouane::CLI::Commands).call

data/lib/marcdouane/file_checker.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "debug"
+require "yaml"
+
+require_relative "rules"
+
+module Marcdouane
+  class FileChecker
+    class << self
+      def call(file, options)
+        verbose = options.fetch(:verbose)
+
+        parse_config!(options[:config])
+
+        puts "Checking `#{file}'..." if verbose
+
+        exit_code = 0
+
+        rules.each do |rule|
+          rule.new(file, options).check!
+        rescue Marcdouane::Error => e
+          $stderr.puts("#{file}:#{e.line_number}: #{e.message}")
+
+          exit_code = 1
+        end
+
+        puts "Done." if verbose
+
+        exit_code
+      end
+
+      def parse_config!(path)
+        return if path.nil?
+
+        config = YAML.load_file(path)
+
+        config.each do |klass, hash|
+          hash.each do |key, value|
+            rule_class = "Marcdouane::Rules::#{klass}"
+
+            const_get(rule_class).class_eval do
+              self.config[key.to_sym] = value
+            end
+          end
+        end
+      end
+
+      def rules
+        Marcdouane::Rules::Rule.subclasses
+      end
+    end
+  end
+end

data/lib/marcdouane/rules/consistent_header_style.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Marcdouane
+  module Rules
+    class ConsistentHeaderStyle < Rule
+      ERROR_MESSAGE = "Use a unique, consistent header style"
+
+      def check!
+        reference_style, style = nil
+
+        source = @markdown.source.lines.dup
+
+        @markdown.on(:heading) do |header|
+          line_number = line_number_from_byte_range(header.byte_range)
+
+          raw_line = source[line_number]
+
+          if raw_line.start_with?("#")
+            style = :normal
+          else
+            style = :underline
+          end
+
+          reference_style ||= style
+
+          if reference_style != style
+            error!(line_number)
+          end
+        end
+
+        @markdown.walk
+      end
+    end
+  end
+end

data/lib/marcdouane/rules/ensure_headers_cascade.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Marcdouane
+  module Rules
+    # Ensure that every child header is always a direct descendant of
+    # the previous header (i.e its level increments by 1).
+    class EnsureHeadersCascade < Rule
+      ERROR_MESSAGE = "Header levels should increment one at a time"
+
+      def check!
+        previous_level = nil
+
+        @markdown.on(:heading) do |header|
+          previous_level ||= header.level
+
+          if header.level > previous_level && header.level != previous_level + 1
+            error!(line_number_from_byte_range(header.byte_range))
+          else
+            previous_level = header.level
+          end
+        end
+
+        @markdown.walk
+      end
+    end
+  end
+end

data/lib/marcdouane/rules/line_length.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "uri"
+
+URI_REGEXP = URI::RFC2396_PARSER.make_regexp
+
+module Marcdouane
+  module Rules
+    # Ensure the line-length does not go over the default (80)
+    # character limit. Link references are not accounted for.
+    class LineLength < Rule
+      ERROR_MESSAGE = "Line-length is over %s characters"
+
+      setting :maximum_line_length, default: 80, reader: true
+
+      def check!
+        @markdown.source.lines.each_with_index do |line, index|
+          if line.match?(/^\[.*\]: #{URI_REGEXP}$/)
+            next
+          elsif line.length > self.class.maximum_line_length
+            error!(
+              index,
+              ERROR_MESSAGE % self.class.maximum_line_length
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/marcdouane/rules/no_consecutive_blank_lines.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Marcdouane
+  module Rules
+    # Ensure there are no consecutive blank lines
+    class NoConsecutiveBlankLines < Rule
+      ERROR_MESSAGE = "Consecutive blank lines"
+
+      def check!
+        @markdown
+          .source
+          .lines
+          .each_cons(2)
+          .each_with_index do |pair, index|
+          if pair.map(&:strip).all?(&:empty?)
+            error!(index + 2)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/marcdouane/rules/rule.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "inkmark"
+
+module Marcdouane
+  module Rules
+    # Rule is the base class to regroup all rules. It is initialized
+    # with a file path and some options forwarded from the CLI
+    # invocation.
+    #
+    # Subclasses must implement `check!` and provide an
+    # ERROR_MESSAGE when the check fails.
+    class Rule
+      extend Dry::Configurable
+
+      attr_reader :file, :options, :markdown
+
+      def initialize(file, options)
+        @file = file
+        @options = options
+        @markdown = Inkmark.new(
+          File.read(file),
+          options: {
+            frontmatter: true
+          }
+        )
+      end
+
+      def line_number_from_byte_range(range)
+        File.binread(file, range.first).count("\n")
+      end
+
+      def identifier
+        self.class.to_s.split("::").last
+      end
+
+      # Produces an error that will be collected and output by the
+      # CLI. It must be called with the 0-indexed line-number, and an
+      # optional `message` override instead of the class's
+      # ERROR_MESSAGE.
+      def error!(machine_line_number, message = nil)
+        msg = message || self.class.const_get("ERROR_MESSAGE")
+
+        raise Marcdouane::Error.new(
+          "[#{identifier}] #{msg}",
+          machine_line_number + 1
+        )
+      end
+    end
+  end
+end

data/lib/marcdouane/rules/start_with_top_level_header.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Marcdouane
+  module Rules
+    # Ensure the first line, frontmatter or not, is a top-level
+    # header.
+    class StartWithTopLevelHeader < Rule
+      ERROR_MESSAGE = "The file should start with a top-level header"
+
+      def check!
+        sections = @markdown.chunks_by_heading
+
+        if sections.empty? || sections.first[:level] != 1
+          error!(0)
+        end
+      end
+    end
+  end
+end

data/lib/marcdouane/rules.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "rules/rule"
+
+require_relative "rules/ensure_headers_cascade"
+require_relative "rules/line_length"
+require_relative "rules/no_consecutive_blank_lines"
+require_relative "rules/start_with_top_level_header"
+require_relative "rules/consistent_header_style"

data/lib/marcdouane/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Marcdouane
+  VERSION = "0.1.0"
+end

data/lib/marcdouane.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "marcdouane/version"
+require_relative "marcdouane/file_checker"
+
+module Marcdouane
+  class Error < StandardError
+    attr_reader :msg, :line_number
+
+    def initialize(msg, line_number)
+      @msg = msg
+      @line_number = line_number
+
+      super(@msg)
+    end
+  end
+end

data/sig/marcdouane.rbs

@@ -0,0 +1,4 @@
+module Marcdouane
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: marcdouane
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stéphane Maniaci
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: inkmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: Marcdouane lints Markdown files and can be easily extended to fit your
+  needs.
+email:
+- stephane.maniaci@gmail.com
+executables:
+- marcdouane
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/marcdouane
+- lib/marcdouane.rb
+- lib/marcdouane/file_checker.rb
+- lib/marcdouane/rules.rb
+- lib/marcdouane/rules/consistent_header_style.rb
+- lib/marcdouane/rules/ensure_headers_cascade.rb
+- lib/marcdouane/rules/line_length.rb
+- lib/marcdouane/rules/no_consecutive_blank_lines.rb
+- lib/marcdouane/rules/rule.rb
+- lib/marcdouane/rules/start_with_top_level_header.rb
+- lib/marcdouane/version.rb
+- logo.jpeg
+- sig/marcdouane.rbs
+homepage: https://github.com/freesteph/marcdouane
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/freesteph/marcdouane
+  source_code_uri: https://github.com/freesteph/marcdouane
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Marcdouane is a pretty Markdown linter
+test_files: []