homebrew_automation 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97e03de71e29414ed00f37914b8964e91421465de75ffd1cd39c85a4ceb274da
-  data.tar.gz: da6cf8c8bd4e2ad86ccd2f0242c0407ef2955b74e5fc70c8b0fbf39e1fa6ffe9
+  metadata.gz: bdaeff9e52d6b0ddeefead7ebced2d97dcde3ae8e6535648c5758ad218b8d42b
+  data.tar.gz: bdf140bc9b706c81ee09344bcb6c36bd8d7679f84fb0757db01fb7df78b0a019
 SHA512:
-  metadata.gz: 6ee552dac8c240c7585073046f2c6c1385bbd65802146aa55bd1e6bd074b9d122d8e018b2135ca13ee053df4f3bd113b52f687906bd08858748bdf0f03f1d83d
-  data.tar.gz: 6dd74ac44f8d465976426baf3f201ca5786d15e9f9c557610e19297d870764eef511390cfcbeeb1e7d5a5b5eb7ccba2b0d242668129e21c3bf765ec513030e38
+  metadata.gz: 77b8a3c5fbf0bf8488ebd6a39b2d493beb99b1ac2d2a6bfc64336cdacac2ae352dac3cd30ce62130c2de0bd898f8f9b9dcffce97bb69f6017f7110b2db5374cb
+  data.tar.gz: bb9add2b195407088552da55a35df30a0170fec173c437d97ef15db3cdb1237a4fb4b31b1d37f37edfaa9d124abe13beadab0ac6639048f0fdad4fffff9cb1f8

data/lib/homebrew_automation.rb

@@ -1,5 +1,5 @@
 
-# Helps you manipulate Homebrew Formula files, Bottles etc.
+# Help you manipulate Homebrew Formula files, Bottles etc.
 module HomebrewAutomation
 end
 

data/lib/homebrew_automation/bintray.rb

@@ -6,8 +6,14 @@ require 'rest-client'
 
 module HomebrewAutomation
 
+  # A bare-bones Bintray API client that implements only the methods needed for
+  # Homebrew things.
   class Bintray
 
+    # @param username [String] Bintray username; for me this was not my email address
+    # @param api_key [String] Bearer-token-like key; generated in the Bintray web UI
+    # @param http [RestClient.Class] The +RestClient+ class itself
+    # @param base_url [String] Include the +https://+; exclude the trailing slash.
     def initialize(
         username,
         api_key,
@@ -20,10 +26,15 @@ module HomebrewAutomation
       @http = http  # allow injecting mocks for testing
     end
 
-    # POST /packages/:subject/:repo/:package/versions
+    # <tt>POST /packages/:subject/:repo/:package/versions</tt>
     #
     # Redundant: Bintray seems to create nonexistant versions for you if you
     # just try to upload files into it.
+    #
+    # @param repo_name [String]
+    # @param package_name [String]
+    # @param version_name [String]
+    # @return [RestClient::Response]
     def create_version(repo_name, package_name, version_name)
       safe_repo = URI.escape(repo_name)
       safe_pkg = URI.escape(package_name)
@@ -34,11 +45,18 @@ module HomebrewAutomation
       )
     end
 
-    # PUT /content/:subject/:repo/:package/:version/:file_path[?publish=0/1][?override=0/1][?explode=0/1]
+    # <tt>PUT /content/:subject/:repo/:package/:version/:file_path[?publish=0/1][?override=0/1][?explode=0/1]</tt>
     #
     # Bintray seems to expect the byte sequence of the file to be written straight out into the
-    # HTTP request body, optionally via `Transfer-Encoding: chunked`. So we pass the `content` String
+    # HTTP request body, optionally via <tt>Transfer-Encoding: chunked</tt>. So we pass the +content+ String
     # straight through to RestClient
+    #
+    # @param repo_name [String]
+    # @param package_name [String]
+    # @param version_name [String]
+    # @param filename [String] The filename within one Bintray repository, e.g. +hack-assembler-0.1.1.17.high_sierra.bottle.tar.gz+
+    # @param content [String] The bytes for the file, e.g. from a +File.read+
+    # @return [RestClient::Response]
     def upload_file(repo_name, package_name, version_name, filename, content, publish: 1)
       safe_repo = URI.escape(repo_name)
       safe_pkg = URI.escape(package_name)
@@ -52,7 +70,14 @@ module HomebrewAutomation
       )
     end
 
-    # GET /packages/:subject/:repo/:package/versions/:version/files[?include_unpublished=0/1]
+    # <tt>GET /packages/:subject/:repo/:package/versions/:version/files[?include_unpublished=0/1]</tt>
+    #
+    # Useful when seeing what bottles have already been built.
+    #
+    # @param repo_name [String]
+    # @param package_name [String]
+    # @param version_name [String]
+    # @return [RestClient::Response]
     def get_all_files_in_version(repo_name, package_name, version_name)
       safe_repo = URI.escape(repo_name)
       safe_pkg = URI.escape(package_name)
@@ -62,21 +87,32 @@ module HomebrewAutomation
         auth_headers)
     end
 
+    # Bintray username, URI-escaped.
+    #
+    # @return [String]
     def safe_username
       URI.escape(@username)
     end
 
-    # Expand relative path
+    # Resolve a relative path into a URL using the current base_url
+    #
+    # @param slash_subpath [String]
+    # @return [String]
     def rel(slash_subpath)
       @base_url + slash_subpath
     end
 
+    # @return [Hash]
     def api_headers
       { "Content-Type" => "application/json" }.update auth_headers
     end
 
+    # Implement HTTP Basich Auth, as per RFC 7617.
+    #
+    # Let's not bring in a library just for these two lines.
+    #
+    # @return [Hash]
     def auth_headers
-      # As per RFC 7617
       cred = Base64.strict_encode64("#{@username}:#{@api_key}")
       { Authorization: "Basic #{cred}" }
     end

data/lib/homebrew_automation/bottle.rb

@@ -2,8 +2,14 @@
 
 module HomebrewAutomation
 
+  # A representation of a binary build of a Homebrew package
   class Bottle
 
+    # @param tap_url [String] Something suitable for +git clone+, e.g. +git@github.com:easoncxz/homebrew-tap.git+ or +/some/path/to/my-git-repo+
+    # @param formula_name [String] As known by Homebrew
+    # @param os_name [String] As known by Homebrew, e.g. +el_capitan+
+    # @param filename [String] ???
+    # @param content [String] ???
     def initialize(
         tap_url,
         formula_name,
@@ -19,6 +25,9 @@ module HomebrewAutomation
     end
 
     # Takes ages to run, just like if done manually
+    #
+    # @raise [StandardError]
+    # @return [nil]
     def build
       die unless system 'brew', 'tap', local_tap_name, @tap_url
       die unless system 'brew', 'install', '--verbose', '--build-bottle', @formula_name
@@ -26,6 +35,7 @@ module HomebrewAutomation
     end
 
     # Read and analyse metadata JSON file
+    # @return [Array<(String, String)>] {#minus_minus} and {#filename}
     def locate_tarball
       json_filename = Dir['*.bottle.json'].first
       unless json_filename
@@ -41,19 +51,29 @@ module HomebrewAutomation
       @minus_minus, @filename = focus['local_filename'], focus['filename']
     end
 
+    # The +brew bottle+ original output filename
+    #
+    # See https://github.com/Homebrew/brew/pull/4612 for details.
+    #
+    # @return [String]
     def minus_minus
       @minus_minus || locate_tarball.first
     end
 
+    # Filename of a Bottle tarball suitable for writing into a Formula file
+    #
+    # @return [String]
     def filename
       @filename || locate_tarball.last
     end
 
+    # @return [String] {#content}
     def load_tarball_from_disk
       File.rename minus_minus, filename
       @content = File.read filename
     end
 
+    # @return [String] bytes of the tarball of this Bottle
     def content
       @content || load_tarball_from_disk
     end

data/lib/homebrew_automation/bottle_gatherer.rb

@@ -4,43 +4,41 @@ require_relative './formula.rb'
 
 module HomebrewAutomation
 
-  # Some functions for figuring out, from files on Bintray, what values to use in bottle DSL.
+  # See what Bottles have already been built and uploaded to Bintray
   class BottleGatherer
 
-    # @param json [Hash]  List of files from Bintray
+    # @param json [Array<Hash>] JSON from a +RestClient::Response+ containing the list of files from Bintray
     def initialize(json)
       @json = json
       @bottles = nil
     end
 
-    # () -> Hash String String
+    # The bottles gathered.
     #
-    # Returns a hash with keys being OS names (in Homebrew-form) and values being SHA256 checksums
+    # @return [Hash<String, String>] with keys being OS names (in Homebrew-form) and values being SHA256 checksums
     def bottles
       return @bottles if @bottles
       pairs = @json.map do |f|
-        os = parse_for_os(f['name'])
+        os = _parse_for_os(f['name'])
         checksum = f['sha256']
         [os, checksum]
       end
       @bottles = Hash[pairs]
     end
 
-    # Formula -> Formula
-    #
     # Put all bottles gathered here into the given formula, then return the result
+    #
+    # @param formula [HomebrewAutomation::Formula]
+    # @return [HomebrewAutomation::Formula]
     def put_bottles_into(formula)
       bottles.reduce(formula) do |formula, (os, checksum)|
         formula.put_bottle(os, checksum)
       end
     end
 
-    #private
-
-    # String -> String
-    #
-    # filename -> OS name
-    def parse_for_os(bottle_filename)
+    # @param bottle_filename [String] filename
+    # @return [String] OS name
+    def _parse_for_os(bottle_filename)
       File.extname(
         File.basename(bottle_filename, '.bottle.tar.gz')).
       sub(/^\./, '')

data/lib/homebrew_automation/formula.rb

@@ -7,16 +7,19 @@ Parser::Builders::Default.emit_procarg0 = true
 
 module HomebrewAutomation
 
-  # An internal representation of some Formula.rb Ruby source file, containing
-  # the definition of a Homebrew Bottle. See Homebrew docs for concepts:
-  # https://docs.brew.sh/Bottles.html
+  # An in-memory, programmable representation of some Formula.rb Ruby source
+  # file, containing the definition of a Homebrew Bottle. See Homebrew docs for
+  # concepts: https://docs.brew.sh/Bottles.html
   #
-  # Instance methods produce new instances where applicable, leaving all
+  # Instance methods produce new instances where sensible, leaving all
   # instances free from mutation.
+  #
+  # {#==} and {#hash} delegates to the underlying +Parser::AST::Node+.
   class Formula
 
-    # A constructor method that parses the string form of a Homebrew Formula
-    # source file into an internal representation
+    # Parse the string form of a Homebrew Formula source file into a {Formula}.
+    #
+    # {#to_s} is the inverse of this method.
     #
     # @return [Formula]
     def self.parse_string s
@@ -34,15 +37,17 @@ module HomebrewAutomation
     # Produce Homebrew Formula source code as a string, suitable for saving as
     # a Ruby source file.
     #
+    # This is the inverse of {.parse_string}.
+    #
     # @return [String]
     def to_s
       Unparser.unparse @ast
     end
 
-    # Update a field in the Formula
+    # Update a top-level field in the Formula
     #
-    # @param field [String] Name of the Formula field, e.g. `url`
-    # @param value [String] Value of the Formula field, e.g. `https://github.com/easoncxz/homebrew-automation`
+    # @param field [String] Name of the Formula field, e.g. +url+
+    # @param value [String] Value of the Formula field, e.g. +https://github.com/easoncxz/homebrew-automation+
     # @return [Formula] a new instance of Formula with the changes applied
     def update_field field, value
       Formula.new update(
@@ -59,6 +64,7 @@ module HomebrewAutomation
     #
     # @param url [String] URL of source tarball
     # @param sha256 [String] SHA256 sum of source tarball
+    # @return [Formula]
     def put_sdist url, sha256
       update_field("url", url).
       update_field("sha256", sha256)
@@ -76,10 +82,20 @@ module HomebrewAutomation
         put_bottle_version(os, sha256))
     end
 
+    # Both formulae are +==+, as per +Parser::AST::Node#==+.
+    #
+    # In practice, I think this means both formulae are equivalent in terms of
+    # Ruby semantics.
+    #
+    # @param o [Object] Expecting a {Formula}, really.
+    # @return [Boolean]
     def == o
       self.class == o.class && @ast == o.ast
     end
 
+    # Hash of the +Parser::AST::Node+
+    #
+    # @return [Integer]
     def hash
       @ast.hash
     end

data/lib/homebrew_automation/mac-os.rb

@@ -1,12 +1,15 @@
 
 module HomebrewAutomation
 
+  # Inspect version of the macOS we're running on
   class MacOS
 
-    # () -> String
+    # Identify the version of the macOS this is run on
     #
-    # Returns a representation of the macOS version name in a format recognised by Homebrew,
-    # in particular the Formula/Bottle DSL.
+    # Return a macOS version name in a convention recognised by Homebrew, in
+    # particular by the Formula/Bottle DSL.
+    #
+    # @return [String]
     def self.identify_version
       version = `sw_vers -productVersion`
       mac_to_homebrew.
@@ -15,6 +18,9 @@ module HomebrewAutomation
         first
     end
 
+    # Lookup table of numeric version patterns to Homebrew-recognised strings
+    #
+    # @return [Hash<Regexp, String>]
     def self.mac_to_homebrew
       {
         /^10.10/ => 'yosemite',

data/lib/homebrew_automation/source_dist.rb

@@ -1,35 +1,52 @@
 
-require 'http'
+require 'rest-client'
 
 module HomebrewAutomation
 
   # A representation of a source distribution tarball file
   class SourceDist
 
-    # @param tag [String] a Git tag, e.g. "v0.1.1.14"
+    # Assign args to attributes {#user}, {#repo}, {#tag}
     def initialize user, repo, tag
       @user = user
       @repo = repo
       @tag = tag
     end
 
-    attr_reader :user, :repo, :tag
+    # Github username, as appears in Github URLs
+    #
+    # @return [String]
+    attr_reader :user
+
+    # Github repo name, as appears in Github URLs
+    #
+    # @return [String]
+    attr_reader :repo
 
-    # Calculate and return the file's checksum. Lazy and memoized.
+    # Git tag name, as usable in +git+ commands
+    #
+    # @return [String]
+    attr_reader :tag
+
+    # Calculate and return the file's checksum.
+    #
+    # Lazy and memoized. Download the file if we haven't already.
     #
     # @return [String] hex-encoded string representation of the checksum
     def sha256
       @sha256 ||= Digest::SHA256.hexdigest contents
     end
 
-    # Fetch the file contents over HTTP. Lazy and memoized.
+    # Download and return the file contents.
+    #
+    # Lazy and memoized.
     #
-    # @param fake [String] fake file contents (for testing)
+    # @param fake [String] inject fake file contents (for testing)
     # @return [String] contents of the file
     def contents fake: nil
       @contents = @contents || fake ||
         begin
-          resp = HTTP.follow.get url
+          resp = RestClient.get url
           case resp.code
           when 200
             resp.body.to_s
@@ -40,7 +57,7 @@ module HomebrewAutomation
         end
     end
 
-    # Pure
+    # The URL to the source tarball Github generates for tagged commits
     #
     # @return [String]
     def url

data/lib/homebrew_automation/tap.rb

@@ -3,34 +3,65 @@ require_relative "formula.rb"
 
 module HomebrewAutomation
 
+  # A representation of a Github repo that acts as a Homebrew Tap.
   class Tap
 
-    # Get a token from: https://github.com/settings/tokens
+    # Assign params to attributes.
     #
-    # @param keep_submodule [Boolean] When done, don't delete the tap Git repo
+    # See {#user}, {#repo}, {#token}.
+    #
+    # @param keep_submodule [Boolean] Avoid deleting the cloned tap Git repo
+    #   directory when possible
     def initialize(user, repo, token, keep_submodule: false)
       @repo = repo
       @url = "https://#{token}@github.com/#{user}/#{repo}.git"
       @keep_submodule = keep_submodule
     end
 
-    attr_reader :user, :repo, :token
+    # Github username, as appears in Github URLs
+    #
+    # @return [String]
+    attr_reader :user
 
-    # forall a. Block (() -> a) -> a
+    # Github repo name, as appears in Github URLs
+    #
+    # @return [String]
+    attr_reader :repo
+
+    # Github OAuth token
+    #
+    # Get a token for yourself here: https://github.com/settings/tokens
     #
-    # Do something in a fresh clone, then clean-up.
+    # @return [String]
+    attr_reader :token
+
+    # +pushd+ into a fresh clone, call the block, then clean-up.
+    #
+    # Haskell-y type: +forall a. &Block (() -> a) -> a+
+    #
+    # @yield [String] Basename of the Tap repo directory we've just chdir'd into
+    # @return Whatever the block returns
     def with_git_clone(&block)
       begin
-        git_clone
+        _git_clone
         Dir.chdir @repo, &block
       ensure
-        remove_git_submodule unless @keep_submodule
+        _remove_git_submodule unless @keep_submodule
       end
     end
 
-    # (String, Block (Formula -> Formula)) -> nil
+    # Overwrite the specified Formula file, in-place, on-disk
+    #
+    # Haskell-y type: <tt>(String, &Block (Formula -> Formula)) -> nil</tt>
     #
-    # Overwrite the given formula
+    # If no block is passed, then this tries to find the formula file, but then
+    # does nothing.
+    #
+    # @param formula [String] Part of the name to the file within the +Formula+
+    #     directory inside the Tap repo's directory, excluding the +.rb+ suffix.
+    # @yield [Formula]
+    # @return [Formula] as returned from the block,
+    #     assuming it obediantly returns a {Formula}.
     def on_formula(formula, &block)
       name = "#{formula}.rb"
       block ||= ->(n) { n }
@@ -47,6 +78,13 @@ module HomebrewAutomation
       end
     end
 
+    # Set Git user's name and email
+    #
+    # Reads environment variables:
+    # - TRAVIS_GIT_USER_NAME
+    # - TRAVIS_GIT_USER_EMAIL
+    #
+    # If either env var is not set, do nothing.
     def git_config
       name = ENV['TRAVIS_GIT_USER_NAME']
       email = ENV['TRAVIS_GIT_USER_EMAIL']
@@ -56,26 +94,33 @@ module HomebrewAutomation
       end
     end
 
+    # Just +git commit -am "$msg"+
+    #
+    # @param msg [String] Git commit message
+    # @raise [StandardError]
     def git_commit_am(msg)
       die unless system "git", "commit", "-am", msg
     end
 
+    # Just +git push+
+    #
+    # @raise [StandardError]
     def git_push
       die unless system "git", "push"
     end
 
-
-    #private
-
-
-    def git_clone
+    # @raise [StandardError]
+    def _git_clone
       die unless system "git", "clone", @url
     end
 
-    def remove_git_submodule
+    # @raise [StandardError]
+    def _remove_git_submodule
       die unless system "rm", "-rf", @repo
     end
 
+    private
+
     def die
       raise StandardError.new
     end

data/lib/homebrew_automation/version.rb

@@ -1,4 +1,7 @@
 
 module HomebrewAutomation
-  VERSION = '0.0.8'
+
+  # Yep.
+  VERSION = '0.0.9'
+
 end

data/lib/homebrew_automation/workflow.rb

@@ -4,13 +4,18 @@ require_relative './bottle_gatherer.rb'
 
 module HomebrewAutomation
 
-  # Imperative glue code
+  # Imperative glue code.
   #
-  # Probably each method suits to become a CLI command.
+  # Each method in this class probably makes sense to be exposed as a CLI command.
   class Workflow
 
-    # @param tap [HomebrewAutomation::Tap]
-    # @param bintray [HomebrewAutomation::Bintray]
+    # Assign params to attributes.
+    #
+    # See {#tap} and {#bintray}.
+    #
+    # @param tap [Tap]
+    # @param bintray [Bintray]
+    # @param bintray_bottle_repo [String] Really should be somehow a part of the +bintray+ param
     def initialize(
         tap,
         bintray,
@@ -20,7 +25,26 @@ module HomebrewAutomation
       @bintray_bottle_repo = bintray_bottle_repo
     end
 
-    # Build a bottle from the given source tarball reference
+    # The Tap holding the Formulae for which we might want to build or publish bottles.
+    #
+    # @return [Tap]
+    attr_reader :tap
+
+    # An API client
+    #
+    # @return [Bintray]
+    attr_reader :bintray
+
+    # Build and upload a bottle.
+    #
+    # The Formula source comes from +source_dist+, and the Bottle tarball that
+    # is built goes to {#bintray}.
+    #
+    # +source_dist+ not only specifies the source tarball, but it also implies:
+    # - the formula name, as appears in the {#tap}, via {SourceDist#repo};
+    # - the Bintray package version, as to be uploaded, via {SourceDist#tag}, with any leading +v+ stripped off.
+    #
+    # The optional params overwrite the above implication.
     #
     # @param source_dist [HomebrewAutomation::SourceDist] Source tarball
     # @param formula_name [String] Formula name as appears in the Tap, which should be the same as the Bintray "Package" name
@@ -55,11 +79,15 @@ module HomebrewAutomation
       end
     end
 
-    # Look around on Bintray to see what bottles we've previously built, then
-    # push new commits into the Tap repository to register the new bottles.
+    # Gather and publish bottles.
+    #
+    # Look around on Bintray to see what Bottles we've already built and
+    # uploaded (as such "gathering" the bottles), then push new commits into
+    # the {#tap} repository to make an existing Formula aware of the Bottles
+    # we're gathered (as such "publishing" the bottles).
     #
-    # @param formula_name [String]
-    # @param version_name [String] Bintray "Version" name, not a Git tag
+    # @param formula_name [String] Both the Formula name in the Tap repo, and the Package name in the Bintray repo.
+    # @param version_name [String] Bintray "Version" name; not a Git tag.
     # @return [Formula]
     def gather_and_publish_bottles(formula_name, version_name)
       @tap.with_git_clone do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: homebrew_automation
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - easoncxz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-08 00:00:00.000000000 Z
+date: 2019-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -53,33 +53,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.6'
 - !ruby/object:Gem::Dependency
-  name: thor
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.20'
-  type: :runtime
+        version: '0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.20'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: http
+  name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '0.20'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: parser
   requirement: !ruby/object:Gem::Requirement
@@ -143,7 +143,8 @@ files:
 homepage: https://github.com/easoncxz/homebrew-automation
 licenses:
 - GPL-3.0
-metadata: {}
+metadata:
+  yard.run: yri
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -159,8 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Build bottles and update Formulae