codeinventory-github 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 14db941ce2b924355eaffb6c538731d1da65990b
-  data.tar.gz: 51069e1abc8f558d31839501a933c9ce3850928a
+  metadata.gz: 19dae8a55610afeed89a5575c736660b2a21345f
+  data.tar.gz: 29bba4eaaf69703b92a7d013e8b54de7907f9980
 SHA512:
-  metadata.gz: b490bf919711a73cf0c4a3c6c7f014efe96f6c6628a158138e5dd8e3e55ee6a17e0e114afb1e67ba16bae604bda35c488606c0cfe146c5ebfec59a13f4fa4cc4
-  data.tar.gz: 043d08d40d9d9eed3a5382bc5ae354f10541a25231a3b72dd8f0e799659215c3e5f988a654434c2edeb55a9d179a09dae2cad83d25861c32624800cd9ef3bfa8
+  metadata.gz: cc84d36b7e0b11382a27a6543ba801823ae22de8484f0946604e4ce95f4deafffdccc8f53b50eac3672e8d5a1e8ebcb5a13200b76dc0351a7f1d9aba3cc20ce9
+  data.tar.gz: 6c7dabbc11ec19c81c6394f2ea2d7d37163180f4164c8b9871364e5b11aff04344b58cc871cc57e16cb4e1006d6a0ee3c11ee1904faba93f9f8d5364c19a14ed

data/README.md

@@ -2,7 +2,11 @@
 
 *_This is an experimental gem that is currently in an alpha stage. The features and interface are unstable and may change at any time._*
 
-The `codeinventory-github` gem is a [CodeInventory](https://github.com/GSA/codeinventory) plugin. This plugin allows CodeInventory to gather metadata from `.codeinventory.yml` or `.codeinventory.json` files in GitHub repositories.
+The `codeinventory-github` gem is a [CodeInventory](https://github.com/GSA/codeinventory) plugin. This plugin allows CodeInventory to gather metadata from GitHub repositories. It builds a list of projects based on a combination of:
+
+* `.codeinventory.yml` and `.codeinventory.json` files in GitHub repositories
+* GitHub metadata
+* Manually specified overrides
 
 ## Installation
 
@@ -26,15 +30,21 @@ Basically:
 
 ```ruby
 require "codeinventory"
-require "codeinventory-github"
+require "codeinventory/github"
 
 github_source = CodeInventory::GitHub.new(access_token: "GITHUB_ACCESS_TOKEN", org: "github_org_name")
 
 inventory = CodeInventory::Inventory.new(github_source)
-inventory.projects # Returns an array of all projects in the GitHub org that have metadata
+inventory.projects # Returns an array of projects in the GitHub org
 ```
 
-When using `CodeInventory::GitHub`, provide a [GitHub access token](https://developer.github.com/v3/oauth/) and the GitHub organization name (e.g., "[GSA](https://github.com/GSA/)"). Each repository within the organization that needs to be included in the project listing should have a `.codeinventory.yml` or `.codeinventory.json` file in the repository's root directory.
+When using `CodeInventory::GitHub`, provide a [GitHub access token](https://developer.github.com/v3/oauth/) and the GitHub organization name (e.g., "[GSA](https://github.com/GSA/)").
+
+The `codeinventory-github` plugin will then automatically harvest your project metadata from GitHub metadata.
+
+### Using inventory files
+
+If you want more fine-grained control over project metadata beyond what is in the GitHub metadata, you can optionally include a `.codeinventory.yml` or `.codeinventory.json` file in the root directories of your GitHub project repositories. For each repository that has such a file, `codeinventory-github` will automatically use the metadata from it.
 
 #### YAML Format (.codeinventory.yml)
 
@@ -68,6 +78,33 @@ contact:
 }
 ```
 
+### Using overrides
+
+You can override any of the inventory fields by passing an override hash.
+
+```ruby
+overrides = {
+  tags: ["my-tag-1", "my-tag-2"],
+  contact: {
+    email: "me@example.com"
+  }
+}
+github_source = CodeInventory::GitHub.new(access_token: "GITHUB_ACCESS_TOKEN", org: "github_org_name", overrides: overrides)
+```
+
+In this example, `codeinventory-github` will set the tags on all your projects to `my-tag-1` and `my-tag-2` also use the contact email you specified on all projects.
+
+### Excluding repositories
+
+You can exclude any repository from scanning.
+
+```ruby
+exclusions = ["not-a-real-product", "DontScanMe"]
+github_source = CodeInventory::GitHub.new(access_token: "GITHUB_ACCESS_TOKEN", org: "github_org_name", exclude: exclusions)
+```
+
+In this example, `codeinventory-github` will ignore the repositories named `not-a-real-product` or `DontScanMe`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/codeinventory/github.rb

@@ -4,41 +4,150 @@ require "base64"
 
 module CodeInventory
   class GitHub
-    VERSION = "0.1.0"
-    attr_accessor :org
+    VERSION = "0.1.1"
+    attr_accessor :org, :overrides, :exclude
 
-    def initialize(access_token:, org:)
+    def initialize(access_token:, org:, overrides: {}, exclude: [])
       Octokit.auto_paginate = true
       @access_token = access_token
       @org = org
+      @overrides = overrides
+      @exclude = exclude
     end
 
     def projects
       repos = client.organization_repositories(@org)
+      repos.delete_if { |repo| exclude.include? repo[:name] }
       projects = []
       repos.each do |repo|
-        begin
-          contents_metadata = client.contents(repo[:full_name], path: ".codeinventory.yml")
-          type = :yaml
-          raw_content = Base64.decode64(contents_metadata[:content])
-        rescue Octokit::NotFound
-          begin
-            contents_metadata = client.contents(repo[:full_name], path: ".codeinventory.json")
-            type = :json
-            raw_content = Base64.decode64(contents_metadata[:content])
-          rescue Octokit::NotFound
-            # Ignore repositories that don't have a CodeInventory metadata file
-          end
-        end
-        if type == :yaml
-          projects << YAML.load(raw_content).to_hash
-        elsif type == :json
-          projects << JSON.parse(raw_content)
-        end
+        inventory_file_metadata = inventory_file(repo)
+        repo_metadata = {}
+        repo_metadata["name"] = name(repo, inventory_file_metadata)
+        repo_metadata["description"] = description(repo, inventory_file_metadata)
+        repo_metadata["license"] = license(repo, inventory_file_metadata)
+        repo_metadata["openSourceProject"] = open_source_project(repo, inventory_file_metadata)
+        repo_metadata["governmentWideReuseProject"] = government_wide_reuse_project(repo, inventory_file_metadata)
+        repo_metadata["tags"] = tags(repo, inventory_file_metadata)
+        repo_metadata["contact"] = { "email" => contact_email(repo, inventory_file_metadata) }
+        repo_metadata["repository"] = repository(repo, inventory_file_metadata)
+        projects << repo_metadata
       end
       projects
     end
 
+    # Checks if the repo has an inventory file. If so, loads its metadata.
+    def inventory_file(repo)
+      filenames = [ ".codeinventory.yml", "codeinventory.yml", ".codeinventory.json", "codeinventory.json"]
+      repo_contents = client.contents(repo[:full_name], path: "/")
+      inventory_file = repo_contents.select { |file| filenames.include? file[:name] }.first
+      unless inventory_file.nil?
+        file_content = client.contents(repo[:full_name], path: inventory_file[:path])
+        raw_content = Base64.decode64(file_content[:content])
+        if inventory_file[:name].end_with? ".yml"
+          metadata = YAML.load(raw_content).to_hash
+        elsif inventory_file[:name].end_with? ".json"
+          metadata = JSON.parse(raw_content)
+        end
+      end
+      metadata || {}
+    end
+
+    # Provides a value for the name field.
+    # Order of precedence:
+    # 1. CodeInventory metadata file
+    # 2. GitHub repository name
+    def name(repo, inventory_file_metadata)
+      return inventory_file_metadata["name"] if inventory_file_metadata["name"]
+      repo[:name]
+    end
+
+    # Provides a value for the description field.
+    # Order of precedence:
+    # 1. List of overrides
+    # 2. CodeInventory metadata file
+    # 3. GitHub repository description
+    # 4. GitHub repository name
+    def description(repo, inventory_file_metadata)
+      return @overrides[:description] if @overrides[:description]
+      return inventory_file_metadata["description"] if inventory_file_metadata["description"]
+      return repo[:description] if repo[:description]
+      repo[:name]
+    end
+
+    # Provides a value for the license field.
+    # Order of precedence:
+    # 1. List of overrides
+    # 2. CodeInventory metadata file
+    # 3. LICENSE.md or LICENSE file in the repository
+    # 4. nil
+    def license(repo, inventory_file_metadata)
+      return @overrides[:license] if @overrides[:license]
+      return inventory_file_metadata["license"] if inventory_file_metadata["license"]
+      # Need to set header to quiet warning about using a GitHub preview feature
+      headers = { accept: "application/vnd.github.drax-preview+json" }
+      begin
+        license_meta = client.repository_license_contents(repo[:full_name], headers)
+        license = license_meta[:html_url]
+      rescue Octokit::NotFound ; end
+      license
+    end
+
+    # Provides a value for the openSourceProject field.
+    # Order of precedence:
+    # 1. List of overrides
+    # 2. CodeInventory metadata file
+    # 3. GitHub repository public/private status (public=1; private=0)
+    def open_source_project(repo, inventory_file_metadata)
+      return @overrides[:openSourceProject] if @overrides[:openSourceProject]
+      return inventory_file_metadata["openSourceProject"] if inventory_file_metadata["openSourceProject"]
+      repo[:private] ? 0 : 1
+    end
+
+    # Provides a value for the governmentWideReuseProject field.
+    # Order of precedence:
+    # 1. List of overrides
+    # 2. CodeInventory metadata file
+    # 3. 1 (assume government-wide reuse)
+    def government_wide_reuse_project(repo, inventory_file_metadata)
+      return @overrides[:governmentWideReuseProject] if @overrides[:governmentWideReuseProject]
+      return inventory_file_metadata["governmentWideReuseProject"] if inventory_file_metadata["governmentWideReuseProject"]
+      1
+    end
+
+    # Provides a value for the tags field.
+    # Order of precedence:
+    # 1. List of overrides
+    # 2. CodeInventory metadata file
+    # 3. A single tag consisting of the org name.
+    def tags(repo, inventory_file_metadata)
+      return @overrides[:tags] if @overrides[:tags]
+      return inventory_file_metadata["tags"] if inventory_file_metadata["tags"]
+      [repo[:owner][:login]]
+    end
+
+    # Provides a value for the contact.email field.
+    # Order of precedence:
+    # 1. List of overrides
+    # 2. CodeInventory metadata file
+    # 3. GitHub organization email
+    def contact_email(repo, inventory_file_metadata)
+      return @overrides[:contact][:email] if @overrides.dig(:contact, :email)
+      return inventory_file_metadata["contact"]["email"] if inventory_file_metadata.dig("contact", "email")
+      org = client.organization(@org)
+      org[:email]
+    end
+
+    # Provies a value for the repository field.
+    # Order of precedence:
+    # 1. List of overrides
+    # 2. CodeInventory metadata file
+    # 3. GitHub repository URL
+    def repository(repo, inventory_file_metadata)
+      return @overrides[:repository] if @overrides[:repository]
+      return inventory_file_metadata["repository"] if inventory_file_metadata["repository"]
+      repo[:html_url]
+    end
+
     def client
       @client ||= Octokit::Client.new(access_token: @access_token)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: codeinventory-github
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jeff Fredrickson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-06 00:00:00.000000000 Z
+date: 2016-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler