github_members 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f27c99dd181831eb919dead2f515dbdfe8677732df33a529681f3218523fd045
+  data.tar.gz: 2a8315bd3492878505168b9d6bb1b77f58e5aa50cd7780eece32d48c8fd0e45c
+SHA512:
+  metadata.gz: ad928b3fad1ff61336a0c435e113ab534538465144c38f0bd056898018d2ee29b98d52cd63f75191610af477e548cbb197894d159a2f3f0c422f07086ec4a736
+  data.tar.gz: 90a313c90fa74106671683b6143e84c7189bee49b1262df2ba88062a4b3a7ee6ebb119df07a2255675adb53bdbe2f3e60c15748c7c4a0f0e118ec73d63a195c3

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1
+
+Initial release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Masafumi Koba
+
+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,72 @@
+# GitHub Members
+
+Manage GitHub members who belong to an organization.
+
+## Installation
+
+Add this line to your `Gemfile`:
+
+```ruby
+gem 'github_members', require: false
+```
+
+## Usage
+
+Run `bundle exec github_members --help`:
+
+<!-- HELP:BEGIN -->
+
+```
+Usage: github_members [options] <org>
+    -g, --github-token GITHUB_TOKEN  A GitHub access token. The `GITHUB_TOKEN` environment variable
+                                     is also available.
+    -m, --markdown-file [FILE]       A Markdown file path. Default: `members.md`
+    -y, --yaml-file [FILE]           A YAML file path. Default: `members.yml`
+    -f, --fields [FIELDS]            A comma-separated list of a member additional fields
+    -h, --help                       Show help
+    -v, --version                    Show version
+
+Examples:
+    # By default
+    github_members <org>
+
+    # Set a token
+    GITHUB_TOKEN=*** github_members <org>
+    github_members <org> -g ***
+
+    # Specify files
+    github_members <org> -m README.md -y company_members.yml
+
+    # Add fields
+    github_members <org> -f slack,note
+```
+
+<!-- HELP:END -->
+
+### Prepare GitHub access token
+
+By default, only public members of a specified organization is fetched.
+Perhaps, you may need to [generate an access token](https://github.com/settings/tokens/new?scopes=read:org&description=github_members) to fetch all members.
+
+### Generate YAML file including members
+
+Fetched organization members are saved in a YAML file. You can add any attributes for a member.
+
+### Insert members table into Markdown file
+
+Prepare the begin/end tags in your Markdown file like this:
+
+```markdown
+<!-- GITHUB_MEMBERS:BEGIN -->
+<!-- GITHUB_MEMBERS:END -->
+```
+
+When running `github_members`, a table of a specified organization members is inserted into the markdown file:
+
+```markdown
+<!-- GITHUB_MEMBERS:BEGIN -->
+
+{inserted_table}
+
+<!-- GITHUB_MEMBERS:END -->
+```

data/exe/github_members

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/github_members"
+
+exit GithubMembers::CLI.new(ARGV).run

data/lib/github_members/cli.rb

@@ -0,0 +1,85 @@
+module GithubMembers
+  class CLI
+    EXIT_SUCCESS = 0
+    EXIT_FAILURE = 1
+
+    attr_reader :argv
+    attr_reader :options
+
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def run
+      begin
+        @options = Options.new(argv)
+      rescue Options::ParseError => e
+        warn e.message
+        return EXIT_FAILURE
+      end
+
+      case
+       when options.help_shown
+         puts options.help
+         return EXIT_SUCCESS
+      when options.version
+        puts options.version
+        return EXIT_SUCCESS
+      when options.github_org.nil?
+        warn "Error: Organization is missing"
+        warn ""
+        warn options.help
+        return EXIT_FAILURE
+      end
+
+      members = read_members
+
+      Client.new(options).fetch_members(options.github_org).each do |new_member|
+        github = new_member.fetch(:github)
+        fullname = new_member.fetch(:fullname)
+        avatar = new_member.fetch(:avatar)
+
+        if members.key?(github)
+          members[github].tap do |m|
+            m.fullname = fullname
+            m.avatar = avatar
+            m.updated = true
+          end
+        else
+          members[github] = member_class.new(
+            github: github,
+            fullname: fullname,
+            avatar: avatar,
+            updated: true
+          )
+        end
+      end
+
+      members.delete_if { |_, m| !m.updated }
+
+      write_members(members.values)
+
+      MarkdownWriter.new.write(members: members.values, file: options.markdown_file)
+
+      EXIT_SUCCESS
+    end
+
+    private def member_class
+      @member_class ||= Member.new.define_class(*options.fields)
+    end
+
+    private def read_members
+      file = options.yaml_file
+      return {} unless file.exist?
+
+      YAML.safe_load(File.read(file)).each_with_object({}) do |member, hash|
+        m = member_class.new(**member, updated: false)
+        hash[m.github] = m
+      end
+    end
+
+    private def write_members(members)
+      options.yaml_file.write(members.map(&:to_h).to_yaml)
+    end
+  end
+end

data/lib/github_members/client.rb

@@ -0,0 +1,31 @@
+require "octokit"
+
+module GithubMembers
+  class Client
+    attr_reader :options
+
+    def initialize(options)
+      @options = options
+
+      Octokit.configure do |c|
+        token = options.github_token
+        c.access_token = token unless token.empty?
+        c.auto_paginate = true
+        c.per_page = 100
+      end
+    end
+
+    def fetch_members(org)
+      Octokit.organization_members(org).map do |gh_member|
+        gh_user = Octokit.user(gh_member.login)
+        fullname = gh_user.name.then { |name| name.to_s.empty? ? "" : name }
+
+        {
+          github: gh_member.login,
+          fullname: fullname,
+          avatar: gh_member.avatar_url
+        }
+      end
+    end
+  end
+end

data/lib/github_members/defaults.rb

@@ -0,0 +1,6 @@
+module GithubMembers
+  module Defaults
+    MARKDOWN_FILE = "members.md"
+    YAML_FILE = "members.yml"
+  end
+end

data/lib/github_members/errors.rb

@@ -0,0 +1,3 @@
+module GithubMembers
+  class Error < StandardError; end
+end

data/lib/github_members/markdown_writer.rb

@@ -0,0 +1,73 @@
+require "markdown-tables"
+
+module GithubMembers
+  class MarkdownWriter
+    TAG_BEGIN = "<!-- GITHUB_MEMBERS:BEGIN -->"
+    TAG_END = "<!-- GITHUB_MEMBERS:END -->"
+
+    def write(members:, file:)
+      unless file.exist?
+        file.write(<<~MARKDOWN)
+          # Members
+
+          #{TAG_BEGIN}
+          #{TAG_END}
+        MARKDOWN
+      end
+
+      table = render_table(members)
+      write_file(table, members.size, file)
+    end
+
+    private def render_table(members)
+      return "" if members.empty?
+
+      fields = members.first.additional_fields
+      labels = ["", "GitHub", "Fullname"]
+      align = ["c", "l", "l"]
+
+      fields.each do |field|
+        labels << field.capitalize
+        align << "l"
+      end
+
+      data = members.map do |member|
+        # NOTE: GitHub's default avatar doesn't support `&s=<size>`, so this uses the `<img>` tag.
+        avatar_url = URI(member.avatar).tap { |u| u.query = "s=64" }.to_s
+        avatar = %(<img src="#{avatar_url}" alt="@#{member.github}" width="32" height="32">)
+        github = "[@#{member.github}](#{member.github_url})"
+        fullname = member.fullname.to_s.then { |v| v.empty? ? "-" : v }
+
+        [avatar, github, fullname].tap do |d|
+          fields.each do |field|
+            d << member[field].to_s.then { |v| v.empty? ? "-" : v }
+          end
+        end
+      end
+
+      MarkdownTables.make_table(labels, data, is_rows: true, align: align)
+    end
+
+    private def write_file(table, member_count, file)
+      content = file.read
+
+      unless content.include?(TAG_BEGIN)
+        raise MissingTagInMarkdown, "#{file} must include `#{TAG_BEGIN}`"
+      end
+
+      unless content.include?(TAG_END)
+        raise MissingTagInMarkdown, "#{file} must include `#{TAG_END}`"
+      end
+
+      content.sub!(/#{TAG_BEGIN}.+#{TAG_END}/mo, <<~MARKDOWN.strip)
+        #{TAG_BEGIN}
+        **#{member_count}** member#{member_count == 1 ? "" : "s"}
+
+        #{table}
+        #{TAG_END}
+      MARKDOWN
+
+      file.write(content)
+    end
+  end
+end

data/lib/github_members/member.rb

@@ -0,0 +1,21 @@
+module GithubMembers
+  class Member
+    DEFAULT_FIELDS = [:github, :fullname, :avatar, :updated].freeze
+
+    def define_class(*fields)
+      Struct.new(*DEFAULT_FIELDS, *fields, keyword_init: true) do
+        def github_url
+          "https://github.com/#{github}"
+        end
+
+        def additional_fields
+          members - DEFAULT_FIELDS
+        end
+
+        def to_h
+          super.to_h.transform_keys(&:to_s).reject { |k, _| k == "updated" }
+        end
+      end
+    end
+  end
+end

data/lib/github_members/options.rb

@@ -0,0 +1,79 @@
+require "optparse"
+
+module GithubMembers
+  class Options
+    class ParseError < Error; end
+
+    attr_accessor :github_org
+    attr_accessor :github_token
+    attr_accessor :markdown_file
+    attr_accessor :yaml_file
+    attr_accessor :fields
+    attr_accessor :help
+    attr_accessor :help_shown
+    attr_accessor :version
+
+    def initialize(argv)
+      self.github_token = ENV["GITHUB_TOKEN"].to_s
+
+      args = parser.parse!(argv)
+      self.help = parser.help + help_examples
+      self.github_org = args.first
+      self.markdown_file = Pathname(markdown_file || Defaults::MARKDOWN_FILE)
+      self.yaml_file = Pathname(yaml_file || Defaults::YAML_FILE)
+    rescue OptionParser::ParseError => e
+      raise ParseError, e.message
+    end
+
+    private def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: github_members [options] <org>"
+
+        opts.on("-g", "--github-token GITHUB_TOKEN",
+          "A GitHub access token. The `GITHUB_TOKEN` environment variable",
+          "is also available.") do |v|
+          self.github_token = v
+        end
+
+        opts.on("-m", "--markdown-file [FILE]", "A Markdown file path. Default: `#{Defaults::MARKDOWN_FILE}`") do |v|
+          self.markdown_file = v
+        end
+
+        opts.on("-y", "--yaml-file [FILE]", "A YAML file path. Default: `#{Defaults::YAML_FILE}`") do |v|
+          self.yaml_file = v
+        end
+
+        opts.on("-f", "--fields [FIELDS]", Array, "A comma-separated list of a member additional fields") do |v|
+          self.fields = v
+        end
+
+        opts.on_tail("-h", "--help", "Show help") do
+          self.help_shown = true
+        end
+
+        opts.on_tail("-v", "--version", "Show version") do
+          self.version = VERSION
+        end
+      end
+    end
+
+    private def help_examples
+      <<~HELP
+
+        Examples:
+            # By default
+            github_members <org>
+
+            # Set a token
+            GITHUB_TOKEN=*** github_members <org>
+            github_members <org> -g ***
+
+            # Specify files
+            github_members <org> -m README.md -y company_members.yml
+
+            # Add fields
+            github_members <org> -f slack,note
+      HELP
+    end
+  end
+end

data/lib/github_members/version.rb

@@ -0,0 +1,3 @@
+module GithubMembers
+  VERSION = "0.0.1"
+end

data/lib/github_members.rb

@@ -0,0 +1,17 @@
+require "json"
+require "pathname"
+require "yaml"
+
+require_relative "github_members/errors"
+
+require_relative "github_members/client"
+require_relative "github_members/defaults"
+require_relative "github_members/markdown_writer"
+require_relative "github_members/member"
+require_relative "github_members/options"
+require_relative "github_members/version"
+
+require_relative "github_members/cli"
+
+module GithubMembers
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: github_members
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Masafumi Koba
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: markdown-tables
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: octokit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.21'
+description: 
+email:
+- ybiquitous@gmail.com
+executables:
+- github_members
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/github_members
+- lib/github_members.rb
+- lib/github_members/cli.rb
+- lib/github_members/client.rb
+- lib/github_members/defaults.rb
+- lib/github_members/errors.rb
+- lib/github_members/markdown_writer.rb
+- lib/github_members/member.rb
+- lib/github_members/options.rb
+- lib/github_members/version.rb
+homepage: https://github.com/ybiquitous/github_members
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ybiquitous/github_members
+  source_code_uri: https://github.com/ybiquitous/github_members
+  changelog_uri: https://github.com/ybiquitous/github_members/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key: 
+specification_version: 4
+summary: Manage GitHub members who belong to an organization.
+test_files: []