git-lint 2.4.0 → 3.0.0

data/README.adoc

@@ -12,9 +12,6 @@ image::https://badge.fury.io/rb/git-lint.svg[Gem Version]
 image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
 [link=https://circleci.com/gh/bkuhlmann/git-lint]
 image::https://circleci.com/gh/bkuhlmann/git-lint.svg?style=svg[Circle CI Status]
-
-[link=https://travis-ci.org/bkuhlmann/git-lint]
-image::https://travis-ci.org/bkuhlmann/git-lint.svg?branch=main[Travis CI Status]
 [link=https://app.netlify.com/sites/git-lint/deploys]
 image::https://api.netlify.com/api/v1/badges/7e23b422-3412-4e7f-b654-65c0417a0b1f/deploy-status[Netlify CI Status]
 
@@ -35,11 +32,6 @@ toc::[]
 * Provides Git Hook support for local use.
 * Provides Continuous Integration (CI) support.
 
-== Screencasts
-
-[link=https://www.alchemists.io/screencasts/git_lint]
-image::https://www.alchemists.io/images/screencasts/git_lint/cover.svg[Screencast,600,240,role=focal_point]
-
 == Requirements
 
 . link:https://www.ruby-lang.org[Ruby]
@@ -53,6 +45,23 @@ To install, run:
 gem install git-lint
 ----
 
+== Upgrade
+
+If upgrading from 2.0.0 to 3.0.0, you'll need to make the following changes:
+
+* The YAML configuration requires a top-level `:analyzers:` key for which all analyzer
+  configurations should be listed under. See the _Configuration_ section below for more details.
+* The `--config` command requires either an `edit` or `view` argument now.
+* The `--analyze` command can accept a `--sha` option for passing in the hash of the SHA you want to
+  analyze. If using this as a post commit Git Hook, you'll need to update your Bash script
+  accordingly.
+* The _Commit Body Line Length_ analyzer configuration has replaced `length` with `maximum` as the
+  key for defining maximum line length.
+* The _Commit Body Issue Tracker Link_ analyzer has been replaced with the _Commit Body Tracker
+  Shorthand_ analyzer. See documentation below for details.
+* The _Commit Subject Length_ analyzer has replaced `length` with `maximum` as the key for defining
+  maximum subject length.
+
 == Usage
 
 === Command Line Interface (CLI)
@@ -60,11 +69,15 @@ gem install git-lint
 From the command line, type: `git-lint --help`
 
 ....
-git-lint --hook                # Add Git Hook support.
-git-lint -a, [--analyze]       # Analyze feature branch for issues.
-git-lint -c, [--config]        # Manage gem configuration.
-git-lint -h, [--help=COMMAND]  # Show this message or get help for a command.
-git-lint -v, [--version]       # Show gem version.
+USAGE:
+  -a, --analyze [options]                  Analyze current branch commits.
+  -c, --config ACTION                      Manage gem configuration. Actions: edit or view.
+  -h, --help                               Show this message.
+      --hook PATH                          Hook for analyzing unsaved commits.
+  -v, --version                            Show gem version.
+
+ANALYZE OPTIONS:
+      --sha HASH                           Analyze specific commit SHA.
 ....
 
 To check if your Git commit history is clean, run: `git-lint --analyze`. It will exit with a failure
@@ -143,124 +156,124 @@ variables. The default configuration is:
 
 [source,yaml]
 ----
-:commit_author_capitalization:
-  :enabled: true
-  :severity: :error
-:commit_author_email:
-  :enabled: true
-  :severity: :error
-:commit_author_name:
-  :enabled: true
-  :severity: :error
-  :minimum: 2
-:commit_body_bullet:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "\\*"
-    - "•"
-:commit_body_bullet_capitalization:
-  :enabled: true
-  :severity: :error
-  :includes: "\\-"
-:commit_body_bullet_delimiter:
-  :enabled: true
-  :severity: :error
-  :includes: "\\-"
-:commit_body_issue_tracker_link:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "(f|F)ix(es|ed)?\\s\\#\\d+"
-    - "(c|C)lose(s|d)?\\s\\#\\d+"
-    - "(r|R)esolve(s|d)?\\s\\#\\d+"
-    - "github\\.com\\/.+\\/issues\\/\\d+"
-:commit_body_leading_line:
-  :enabled: false
-  :severity: :warn
-:commit_body_line_length:
-  :enabled: true
-  :severity: :error
-  :length: 72
-:commit_body_paragraph_capitalization:
-  :enabled: true
-  :severity: :error
-:commit_body_phrase:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "absolutely"
-    - "actually"
-    - "all intents and purposes"
-    - "along the lines"
-    - "at this moment in time"
-    - "basically"
-    - "each and every one"
-    - "everyone knows"
-    - "fact of the matter"
-    - "furthermore"
-    - "however"
-    - "in due course"
-    - "in the end"
-    - "last but not least"
-    - "matter of fact"
-    - "obviously"
-    - "of course"
-    - "really"
-    - "simply"
-    - "things being equal"
-    - "would like to"
-    - "/\\beasy\\b/"
-    - "/\\bjust\\b/"
-    - "/\\bquite\\b/"
-    - "/as\\sfar\\sas\\s.+\\sconcerned/"
-    - "/of\\sthe\\s(fact|opinion)\\sthat/"
-:commit_body_presence:
-  :enabled: false
-  :severity: :warn
-  :minimum: 1
-:commit_body_single_bullet:
-  :enabled: true
-  :severity: :error
-  :includes: "\\-"
-:commit_subject_length:
-  :enabled: true
-  :severity: :error
-  :length: 72
-:commit_subject_prefix:
-  :enabled: true
-  :severity: :error
-  :includes:
-    - Fixed
-    - Added
-    - Updated
-    - Removed
-    - Refactored
-:commit_subject_suffix:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "\\."
-    - "\\?"
-    - "\\!"
-:commit_trailer_collaborator_capitalization:
-  :enabled: true
-  :severity: :error
-:commit_trailer_collaborator_duplication:
-  :enabled: true
-  :severity: :error
-:commit_trailer_collaborator_email:
-  :enabled: true
-  :severity: :error
-:commit_trailer_collaborator_key:
-  :enabled: true
-  :severity: :error
-  :includes:
-    - "Co-Authored-By"
-:commit_trailer_collaborator_name:
-  :enabled: true
-  :severity: :error
-  :minimum: 2
+:analyzers:
+  :commit_author_capitalization:
+    :enabled: true
+    :severity: :error
+  :commit_author_email:
+    :enabled: true
+    :severity: :error
+  :commit_author_name:
+    :enabled: true
+    :severity: :error
+    :minimum: 2
+  :commit_body_bullet:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "\\*"
+      - "•"
+  :commit_body_bullet_capitalization:
+    :enabled: true
+    :severity: :error
+    :includes: "\\-"
+  :commit_body_bullet_delimiter:
+    :enabled: true
+    :severity: :error
+    :includes: "\\-"
+  :commit_body_tracker_shorthand:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "(f|F)ix(es|ed)?\\s\\#\\d+"
+      - "(c|C)lose(s|d)?\\s\\#\\d+"
+      - "(r|R)esolve(s|d)?\\s\\#\\d+"
+  :commit_body_leading_line:
+    :enabled: false
+    :severity: :warn
+  :commit_body_line_length:
+    :enabled: true
+    :severity: :error
+    :maximum: 72
+  :commit_body_paragraph_capitalization:
+    :enabled: true
+    :severity: :error
+  :commit_body_phrase:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "absolutely"
+      - "actually"
+      - "all intents and purposes"
+      - "along the lines"
+      - "at this moment in time"
+      - "basically"
+      - "each and every one"
+      - "everyone knows"
+      - "fact of the matter"
+      - "furthermore"
+      - "however"
+      - "in due course"
+      - "in the end"
+      - "last but not least"
+      - "matter of fact"
+      - "obviously"
+      - "of course"
+      - "really"
+      - "simply"
+      - "things being equal"
+      - "would like to"
+      - "\\beasy\\b"
+      - "\\bjust\\b"
+      - "\\bquite\\b"
+      - "as\\sfar\\sas\\s.+\\sconcerned"
+      - "of\\sthe\\s(fact|opinion)\\sthat"
+  :commit_body_presence:
+    :enabled: false
+    :severity: :warn
+    :minimum: 1
+  :commit_body_single_bullet:
+    :enabled: true
+    :severity: :error
+    :includes: "\\-"
+  :commit_subject_length:
+    :enabled: true
+    :severity: :error
+    :maximum: 72
+  :commit_subject_prefix:
+    :enabled: true
+    :severity: :error
+    :includes:
+      - Fixed
+      - Added
+      - Updated
+      - Removed
+      - Refactored
+  :commit_subject_suffix:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "\\."
+      - "\\?"
+      - "\\!"
+  :commit_trailer_collaborator_capitalization:
+    :enabled: true
+    :severity: :error
+  :commit_trailer_collaborator_duplication:
+    :enabled: true
+    :severity: :error
+  :commit_trailer_collaborator_email:
+    :enabled: true
+    :severity: :error
+  :commit_trailer_collaborator_key:
+    :enabled: true
+    :severity: :error
+    :includes:
+      - "Co-Authored-By"
+  :commit_trailer_collaborator_name:
+    :enabled: true
+    :severity: :error
+    :minimum: 2
 ----
 
 Feel free to take this default configuration, modify, and save as your own custom
@@ -316,18 +329,15 @@ any of the scripts within the `.git/hooks` directory of the repository.
 
 ==== Commit Message
 
-The _commit-msg_ hook, which is the best way to use this gem as a Git Hook, is provided as a
-`--hook` option. Run `git-lint --help --hook` for usage:
+The _commit-msg_ hook -- which is the best way to use this gem as a Git Hook -- is provided as a
+`--hook` option. Usage:
 
-    Usage:
-      git-lint --hook
-
-    Options:
-      [--commit-message=PATH]  # Check commit message.
-
-    Add Git Hook support.
+[source,bash]
+----
+git-lint --hook PATH
+----
 
-As shown above, the `--commit-message` option accepts a file path (i.e. `.git/COMMIT_EDITMSG`) which
+As shown above, the `--hook` command accepts a file path (i.e. `.git/COMMIT_EDITMSG`) which
 is provided to you by Git within the `.git/hooks/commit-msg` script. Here is a working example of
 what that script might look like:
 
@@ -345,27 +355,22 @@ if ! command -v git-lint > /dev/null; then
    exit 1
 fi
 
-git-lint --hook --commit-message "${BASH_ARGV[0]}"
+git-lint --hook "${BASH_ARGV[0]}"
 ----
 
 Whenever you attempt to add a commit, Git Lint will check your commit for issues prior to saving it.
 
 ==== Post Commit
 
-The _post-commit_ hook is possible via the `--analyze --commits` option. Usage:
-
-....
-Usage:
-  git-lint -a, [--analyze]
-
-Options:
-  -c, [--commits=one two three]  # Analyze specific commit SHA(s).
+The _post-commit_ hook is possible via the `--analyze` command. Usage:
 
-Analyze feature branch for issues.
-....
+[source,bash]
+----
+git-lint --analyze --shas SHA
+----
 
-The _post-commit_ hook can be used multiple ways but, if you want it to check each commit after it
-has been made, here is a working example which can be used as a `.git/hooks/post-commit` script:
+The _post-commit_ hook can be used multiple ways but, generally, you'll want to check the last
+commit made. Here is a working example which can be used as a `.git/hooks/post-commit` script:
 
 [source,bash]
 ----
@@ -381,7 +386,7 @@ if ! command -v git-lint > /dev/null; then
    exit 1
 fi
 
-git-lint --analyze --commits $(git log --pretty=format:%H -1)
+git-lint --analyze --shas $(git log --pretty=format:%H -1)
 ----
 
 Whenever a commit has been saved, this script will run Git Lint to check for issues.
@@ -435,11 +440,6 @@ The above will ensure Git Lint runs as an additional check on each Pull Request.
 Detection and configuration happens automatically by checking the `NETLIFY` environment variable. No
 additional setup required!
 
-==== link:https://travis-ci.org[Travis CI]
-
-Detection and configuration happens automatically by checking the `TRAVIS` environment variable. No
-additional setup required!
-
 == Analyzers
 
 The following details the various analyzers provided by this gem to ensure a high standard of
@@ -558,38 +558,6 @@ Ensures commit body bullets are delimited by a space. Example:
 - An example bullet.
 ....
 
-=== Commit Body Issue Tracker Link
-
-[options="header"]
-|===
-| Enabled | Severity | Defaults
-| true    | error    | excludes: (see configuration)
-|===
-
-Ensures commit body doesn't contain a link to an issue tracker. The exclude list defaults to GitHub
-Issue links but can be customized for any issue tracker.
-
-There are several reasons for excluding issue tracker links from commit bodies:
-
-. Not all issue trackers preserve issues (meaning they can be deleted). This makes make reading
-  historic commits much harder to understand why the change was made when the link no longer works.
-. When not connected to the internet or working on a laggy connection, it's hard to understand why
-  a commit was made when all you have is a link to an issue with no other supporting context.
-. During the course of a repository's life, issue trackers can be replaced (rare but it does
-  happen). If the old issue tracker service is no longer paid for, none of the links within the
-  commit will be of any relevance.
-. An issue might span several commits in order to resolve it. Including a link in each commit is
-  tedious and can create noise within the issue's history which is distracting.
-
-Instead of linking to issues, take the time to write a short summary as to _why_ the commit was
-made. Doing this will make it easier to understand _why_ the commit was made, keeps the commit self-
-contained, and makes learning about/debugging the commit faster.
-
-Issue tracker links are best used at the code review level due to an issue usually spanning multiple
-commits in order to complete the work. When reading a code review, this is a great opportunity to
-link to an issue in order to provide a high level overview and reason why the code review was
-initiated in the first place.
-
 === Commit Body Leading Line
 
 [options="header"]
@@ -626,13 +594,12 @@ ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, orn
 [options="header"]
 |===
 | Enabled | Severity | Defaults
-| true    | error    | length: 72
+| true    | error    | maximum: 72
 |===
 
-Ensures each line of the commit body is no longer than 72 characters in length for consistent
-readability and word-wrap prevention on smaller screen sizes. For further details, read Tim Pope's
-original link:http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[article] on the
-subject.
+Ensures each line of the commit body doesn't force you to scroll horizontally to read the message.
+This allows commit messages to remain readable and is especially handy when commit messages are read
+via the command line or email clients.
 
 === Commit Body Paragraph Capitalization
 
@@ -712,12 +679,37 @@ Pellentque morbi-trist sentus et netus et malesuada fames ac turpis egestas. Ves
 quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu_libero sit amet quam.
 ....
 
+=== Commit Body Tracker Shorthand
+
+[options="header"]
+|===
+| Enabled | Severity | Defaults
+| true    | error    | excludes: (see configuration)
+|===
+
+Ensures commit body doesn't use issue tracker shorthand. The exclude list defaults to GitHub Issues
+but can be customized for any issue tracker.
+
+There are several reasons for excluding issue tracker links from commit bodies:
+
+. Not all issue trackers preserve issues (meaning they can be deleted). This makes make reading
+  historic commits harder to understand why the change was made when the reference no longer works.
+. When disconnected from the internet or working on a laggy connection, it's hard to understand why
+  a commit was made when all you have is a shorthand issue reference with no supporting context.
+. During the course of a repository's life, issue trackers can be replaced (rare but does happen).
+  If the old issue tracker service is no longer in use, none of the commit body shorthand will
+  be of any relevance.
+
+Instead of using tracker shorthand syntax, take the time to write a short summary as to _why_ the
+commit was made. Doing this will make it easier to understand _why_ the commit was made, keeps the
+commit self-contained, and makes learning about/debugging the commit faster.
+
 === Commit Subject Length
 
 [options="header"]
 |===
 | Enabled | Severity | Defaults
-| true    | error    | length: 72
+| true    | error    | maximum: 72
 |===
 
 Ensures the commit subject length is no more than 72 characters in length. This default is more
@@ -906,9 +898,9 @@ worth considering:
   Submodules can accomplish.
 * Avoid using link:https://git-lfs.github.com[Git LFS] for tracking binary artifacts/resources.
   These files are not meant for version control and lead to large repositories that are time
-  consuming to clone/deploy. Use storage managers, like link:https://aws.amazon.com/s3[Amazon S3] or
-  link:https://lakefs.io[LakeFS] for example, that are better suited for binary assets that don't
-  change often.
+  consuming to clone/deploy. Use storage managers like link:https://git-annex.branchable.com[Git
+  Annex], link:https://aws.amazon.com/s3[Amazon S3], or link:https://lakefs.io[LakeFS] which are
+  better suited for binary assets that don't change often.
 
 === Security
 
@@ -1030,14 +1022,20 @@ participating in this project you agree to abide by its terms.
 
 Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details.
 
+== Community
+
+Feel free to link:https://www.alchemists.io/community[join the commmunity] for discussions related
+to this project and much more.
+
 == License
 
 Read link:LICENSE.adoc[LICENSE] for details.
 
-== History
+== Changes
 
 Read link:CHANGES.adoc[CHANGES] for details.
 
 == Credits
 
-Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
+* Built with link:https://www.alchemists.io/projects/gemsmith[Gemsmith].
+* Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

data/{bin → exe}/git-lint

@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 require "git/lint"
-require "git/lint/cli"
-require "git/lint/identity"
 
 Process.setproctitle Git::Lint::Identity::VERSION_LABEL
-Git::Lint::CLI.start
+Git::Lint::CLI::Shell.new.call ARGV

data/lib/git/lint/analyzer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Git
+  module Lint
+    # Runs all analyzers.
+    class Analyzer
+      ANALYZERS = [
+        Analyzers::CommitAuthorCapitalization,
+        Analyzers::CommitAuthorEmail,
+        Analyzers::CommitAuthorName,
+        Analyzers::CommitBodyBullet,
+        Analyzers::CommitBodyBulletCapitalization,
+        Analyzers::CommitBodyBulletDelimiter,
+        Analyzers::CommitBodyLeadingLine,
+        Analyzers::CommitBodyLineLength,
+        Analyzers::CommitBodyParagraphCapitalization,
+        Analyzers::CommitBodyPhrase,
+        Analyzers::CommitBodyPresence,
+        Analyzers::CommitBodySingleBullet,
+        Analyzers::CommitBodyTrackerShorthand,
+        Analyzers::CommitSubjectLength,
+        Analyzers::CommitSubjectPrefix,
+        Analyzers::CommitSubjectSuffix,
+        Analyzers::CommitTrailerCollaboratorCapitalization,
+        Analyzers::CommitTrailerCollaboratorDuplication,
+        Analyzers::CommitTrailerCollaboratorEmail,
+        Analyzers::CommitTrailerCollaboratorKey,
+        Analyzers::CommitTrailerCollaboratorName
+      ].freeze
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize analyzers: ANALYZERS,
+                     collector: Collector.new,
+                     reporter: Reporters::Branch,
+                     container: Container
+        @analyzers = analyzers
+        @collector = collector
+        @reporter = reporter
+        @container = container
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def call commits: Commits::Loader.new.call
+        process commits
+        a_reporter = reporter.new(collector:)
+        block_given? ? yield(collector, a_reporter) : [collector, a_reporter]
+      end
+
+      private
+
+      attr_reader :analyzers, :collector, :reporter, :container
+
+      def process commits
+        collector.clear
+        commits.map { |commit| analyze commit }
+      end
+
+      def analyze commit
+        settings.map { |setting| load_analyzer commit, setting.id }
+                .select(&:enabled?)
+                .map { |analyzer| collector.add analyzer }
+      end
+
+      def load_analyzer commit, id
+        analyzers.find { |analyzer| analyzer.id == id }
+                 .then do |analyzer|
+                   fail Errors::Base, "Invalid analyzer detected: #{id}." unless analyzer
+
+                   analyzer.new commit
+                 end
+      end
+
+      def settings = container[:configuration].analyzers
+    end
+  end
+end

data/lib/git/lint/analyzers/abstract.rb

@@ -12,36 +12,24 @@ module Git
         LEVELS = %i[warn error].freeze
         ISSUE_LINE_OFFSET = 2
 
-        def self.inherited klass
-          super
-          @descendants ||= []
-          @descendants << klass unless klass.to_s.start_with? "#<Class" # Ignore anonymous classes.
-        end
-
         def self.id = to_s.delete_prefix("Git::Lint::Analyzers").snakecase.to_sym
 
         def self.label = to_s.delete_prefix("Git::Lint::Analyzers").titleize
 
-        def self.defaults
-          fail NotImplementedError, "The `.#{__method__}` method must be implemented."
-        end
-
-        def self.descendants = @descendants || []
-
         def self.build_issue_line(index, line) = {number: index + ISSUE_LINE_OFFSET, content: line}
 
         attr_reader :commit
 
-        def initialize commit:, settings: self.class.defaults
+        def initialize commit, container: Container
           @commit = commit
-          @settings = settings
+          @container = container
           @filter_list = load_filter_list
         end
 
-        def enabled? = settings.fetch(:enabled)
+        def enabled? = settings.enabled
 
         def severity
-          settings.fetch(:severity).tap do |level|
+          settings.severity.tap do |level|
             fail Errors::Severity, level unless LEVELS.include? level
           end
         end
@@ -62,9 +50,9 @@ module Git
 
         protected
 
-        attr_reader :settings, :filter_list
+        attr_reader :container, :filter_list
 
-        def load_filter_list = Kit::FilterList.new(settings[:list])
+        def load_filter_list = []
 
         def affected_commit_body_lines
           commit.body_lines.each.with_object([]).with_index do |(line, lines), index|
@@ -85,6 +73,8 @@ module Git
         def invalid_line? _line
           fail NotImplementedError, "The `.#{__method__}` method must be implemented."
         end
+
+        def settings = container[:configuration].find_setting(self.class.id)
       end
     end
   end