doc_health 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc458994be6f5809ab84f50071a9bbe9996bf7ef5976681d84df0d9670c08ade
+  data.tar.gz: 0f367d8e57de1f2f759be7dffe973308ee0aaf9bdfc09c585fda33ddb57212de
+SHA512:
+  metadata.gz: 3d9df3626c0c98ac8351b1cdbfe93bd9aebf39de2d37065686456dbb8955b7dd8273174a24eaf07a51aa5f2bb0fd27fe5e603426df13aa91f8c4104978f16411
+  data.tar.gz: ba46718bf0a723badcbf2cde716aa19cc5cc61cee6c91c15f9290ed029f143202794b72e71659ee9d078b10c0e45a5e0873033f359b8f293a0086ab5e99eebc3

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20

data/README.md

@@ -0,0 +1,68 @@
+# DocHealth
+
+DocHealth is a Ruby gem that scans a given path for Markdown (`.md`) files and retrieves the last updated date and author. It provides a terminal readout or exports the results to a CSV file, helping you monitor the health of your documentation.
+
+## Installation
+
+Install the gem and add it to your application's Gemfile by executing:
+
+```bash
+bundle add doc_health
+```
+
+If bundler is not being used to manage dependencies, install the gem manually:
+
+```bash
+gem install doc_health
+```
+
+## Usage
+
+To scan a directory for Markdown files and display the last modified date and author, run:
+
+```bash
+doc-health --path /path/to/docs
+```
+
+To output the results to a CSV file:
+
+```bash
+doc-health --path /path/to/docs --csv
+```
+
+## Development
+
+After cloning the repository, install dependencies:
+
+```bash
+bin/setup
+```
+
+Run the tests:
+
+```bash
+rake test
+```
+
+Use `bin/console` for an interactive prompt to experiment with the code.
+
+To install this gem locally:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version:
+1. Update the version number in `lib/doc_health/version.rb`.
+2. Run:
+
+```bash
+bundle exec rake release
+```
+
+This will create a git tag, push commits and the tag, and publish the gem to [RubyGems](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/YOUR_USERNAME/doc_health](https://github.com/YOUR_USERNAME/doc_health).
+

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]
+
+task :build_and_install do
+  system "gem build doc_health.gemspec"
+  system "gem install doc_health-0.1.0.gem"
+end

data/exe/doc-health

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "doc_health"
+
+DocHealth.health_report

data/lib/doc_health/cli.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module DocHealth
+  class CLI
+    def self.options
+      options = {}
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: doc-health [options]"
+
+        opts.on("-h", "--help", "Show this help message") do
+          exit
+        end
+
+        opts.on("-p PATH", "--path=PATH", "Specify the documentation path") do |path|
+          options[:path] = path
+        end
+
+        opts.on("-csv", "--csv", "Generate CSV report") do
+          options[:csv] = true
+        end
+      end.parse!
+
+      options
+    end
+  end
+end

data/lib/doc_health/git.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "git"
+
+module DocHealth
+  class Git
+    attr_reader :path
+
+    def initialize(path)
+      @git = ::Git.open(path)
+      @path = path
+    end
+
+    def file_commit_author
+      Dir.glob("#{path}**/*.md").map do |file|
+        est_time = last_commit_date(file)
+        author = last_commit_author(file)
+        [file, est_time, author]
+      end
+    end
+
+    def last_commit_date(file)
+      # handle new files not in the git history
+      gitlog = @git.log(1).object(file).first
+      return "N/A" unless gitlog
+
+      gitlog.date.getlocal("-05:00").strftime("%Y-%m-%d %I:%M %p")
+    end
+
+    def last_commit_author(file)
+      gitlog = @git.log(1).object(file).first
+      return "N/A" unless gitlog
+
+      @git.log(1).object(file).first.author.name
+    end
+  end
+end

data/lib/doc_health/report.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "terminal-table"
+require "csv"
+require_relative "git"
+
+module DocHealth
+  class Report
+    attr_reader :path
+
+    def initialize(options)
+      @path = options[:path] || Dir.pwd
+      @generate_csv = options[:csv] || false
+    end
+
+    def generate
+      unless File.directory?(path)
+        puts "The path is invalid."
+        return
+      end
+
+      rows = Git.new(path).file_commit_author
+
+      if @generate_csv
+        generate_csv(rows)
+        puts "📋 CSV generated"
+        return
+      end
+
+      print_table(["File", "Last Commit (EST)"], rows)
+    end
+
+    def print_table(headers, rows)
+      table = Terminal::Table.new headings: headers, rows: rows
+      puts table
+    end
+
+    def generate_csv(rows)
+      CSV.open("doc_health_report.csv", "wb") do |csv|
+        csv << ["File", "Last Commit (EST)"]
+        rows.each { |row| csv << row }
+      end
+    end
+  end
+end

data/lib/doc_health/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DocHealth
+  VERSION = "0.1.0" unless defined?(VERSION)
+end

data/lib/doc_health.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "doc_health/version"
+require_relative "doc_health/cli"
+require_relative "doc_health/report"
+
+module DocHealth
+  class Error < StandardError; end
+
+  def self.health_report
+    options = DocHealth::CLI.options
+    Report.new(options).generate
+  end
+end

data/sig/doc_health.rbs

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

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: doc_health
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Greg Dodd
+bindir: exe
+cert_chain: []
+date: 2025-02-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  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'
+- !ruby/object:Gem::Dependency
+  name: git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Returns a report on the health of your markdown documentation. The generated
+  report is a CSV.
+email:
+- greg.dodd@shopify.com
+executables:
+- doc-health
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- README.md
+- Rakefile
+- exe/doc-health
+- lib/doc_health.rb
+- lib/doc_health/cli.rb
+- lib/doc_health/git.rb
+- lib/doc_health/report.rb
+- lib/doc_health/version.rb
+- sig/doc_health.rbs
+homepage: https://github.com/gregdodd/doc-health.git
+licenses: []
+metadata:
+  homepage_uri: https://github.com/gregdodd/doc-health.git
+  source_code_uri: https://github.com/gregdodd/doc-health.git
+  changelog_uri: https://github.com/gregdodd/doc-health/blob/main/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Returns a report on the health of your markdown documentation.
+test_files: []